Skip to main content

Lenses

Every artifact in WonderForge has the same underlying data structure, but that does not mean every artifact should look the same. A conversation should look like a chat interface. A diagram should be a visual canvas. Lenses are the mechanism that makes this possible: pluggable view components that provide customized experiences tailored to specific artifact types.

What is a lens?​

A lens is a view component that targets a specific artifact type (or all types) and provides a specialized user experience. Lenses are themselves artifacts -- registered with the platform just like any other entity, queryable and manageable through the standard API.

Four lens kinds​

  • Detail -- Read-only display of an artifact. A detail lens for a conversation shows the message thread; for a diagram, the visual graph.
  • Edit -- A form or editor for modifying an artifact. Receives current data and emits save events back to the host.
  • Create -- A creation wizard for scaffolding a new artifact with a guided experience appropriate to the type.
  • App -- A full-page application with its own route and sidebar entry. Forge Studio -- the visual artifact graph designer -- is an example.

How the platform decides which lens to show​

When you open an artifact, the platform queries available lenses from the API, filters by the artifact's type (API group and kind), and sorts by priority (lower numbers appear first). Type-specific lenses use low priorities (100-500) for leftmost tabs; universal lenses use high priorities (700-900) for secondary tabs. One lens per type can be marked default to open automatically.

Lenses can target a specific type or use wildcards (*/* for all types). Because availability is determined by API query, adding a new lens requires no frontend rebuild -- register the artifact, and it appears on the next page load.

Universal lenses​

Three lenses are always available for every artifact type:

  • YAML view -- Raw artifact data for inspection, debugging, or quick edits.
  • Events view -- Change history as a timeline, recording every create, update, and metadata change.
  • Relationships view -- All flux connections to and from the artifact.

Custom lenses add type-specific experiences on top of this baseline -- they never replace it.

The web component model​

Each lens is an independent JavaScript bundle loaded at runtime as a web component. This means lenses are framework-independent (React, Svelte, vanilla JS -- anything that produces a web component), isolated from the host application, and hostable anywhere.

The Lens SDK provides a base class and utilities that handle the boilerplate: receiving artifact data, emitting events (navigate, save, create, toast), and communicating with the platform API through the API proxy. A lens developer focuses on the experience; the SDK handles the plumbing.

When to build a lens​

The universal YAML editor and events view are sufficient for many types, especially simpler ones managed primarily by agents. Consider a custom lens when the artifact type has a natural visual representation, needs a specialized editing experience, benefits from real-time interaction, or warrants an entire application.

For how to get a lens into the platform, see Installing Lenses. For how lenses communicate securely with the API, see the API Proxy page.