Runtime API

The runtime is framework-agnostic and operates on the DOM. It renders one non-blocking clue surface at a time.

new ViewCueRuntime(options)

const runtime = new ViewCueRuntime({
  theme: "civic",
  motion: "calm",
})

Available themes are civic, paper, night, and contrast. Motion modes are calm, expressive, and reduced.

registerTarget(meta, resolver)

Registers a stable semantic target:

const unregister = runtime.registerTarget(
  {
    id: "checkout.total",
    label: "Order total",
    description: "The final amount before checkout",
    kind: "status",
  },
  () => document.querySelector("#checkout-total"),
)

The runtime rejects malformed IDs, missing metadata, disconnected elements, and sensitive targets.

observeDeclarativeTargets()

Scans [data-viewcue-target] elements and observes later DOM changes. The declarative metadata is:

• data-viewcue-target;
• data-viewcue-label;
• data-viewcue-description;
• data-viewcue-kind;
• data-viewcue-sensitive.

showClue(options)

Shows the core UI clue:

await runtime.showClue({
  targetId: "checkout.total",
  title: "Order total",
  message: "Review this amount before checkout.",
  ensureVisible: true,
})

It returns a bounded result with ok, action, and target IDs. It never invokes a domain action.

traceAction(trace)

Renders an application-owned activity clue. The phases are planned, executing, completed, and failed. This is optional and is useful when the host application wants to make a consequential tool’s activity visible.

instrumentTool(tool, options)

Returns a wrapper around a WebMCP tool. The wrapper emits the optional activity clue, calls the original execute(), returns its result unchanged, and marks thrown or explicitly classified failures as failed.

getVisibleContext()

Returns a bounded view of the current route/screen context, registered visible targets, and current clue. It does not expose raw DOM, cookies, local storage, or arbitrary page HTML.

clear(reason) and dispose()

clear() removes the current clue. dispose() clears the clue, disconnects observers, unregisters targets, and removes the overlay host.