Skip to content

Editor-Host Protocol

Identity

Field Value
Protocol anuva/bento-editor
Protocol version 1.1.0
Editor version 1.1.0
Renderer version 1.0.8-anuva-renderer.1
Contract package @anuva/bento-contract 1.1.0

Every request has the exact protocol and version, a stable requestId, one allowlisted command, and a closed command-specific payload. Unknown fields and future versions fail before dispatch.

The distributed editor.schema.json defines closed request, response, and event variants. Its save triggers, focus payload, validation issues, operation results, and capability-bearing ready event match the public TypeScript contract.

Host requests

Command Purpose
load Replace the complete presentation and loaded template-family catalog.
apply-operations Validate and execute an atomic allowlisted operation batch.
save-accepted Record the host-assigned accepted revision after persistence.
save-rejected Keep the editor dirty after a host rejection or conflict.
diagnostics Return lifecycle, active surface, dirty state, accepted revision, versions, and loaded families.
request-save Ask the editor to produce a validated save DTO for trigger manual or autosave.
focus Focus an exact slide on Main, Companion, or Emphasis by stable identity.

load requires a production-valid presentation and at least one valid template family. A later load supersedes the in-memory authoring session and clears composite history and the request-ID ledger. The successful load request ID remains reserved so replay cannot repeat the load.

Every request variant is closed. request-save requires exactly {"trigger":"manual"} or {"trigger":"autosave"}. focus requires the owning surface, stable slideId, and optional sceneId; it does not accept a mutable array index.

Editor events

Event Purpose
ready Advertise exact editor, renderer, and capability versions.
dirty-changed Report the current accepted revision and dirty state.
save-request Return a validated, dehydrated presentation and its baseRevision.
operation-result Return stable per-operation codes, warnings, issues, and audit identity.
error Return a stable failure code and safe diagnostics.

A save-request event includes the initiating requestId and trigger. A host request-save receives one correlated response after the same validation and dehydration path completes. A save request does not mean persistence succeeded. Only save-accepted moves the accepted revision and clears dirty state. Validation failure emits a stable error and does not advance revision, clear dirty state, or authorize persistence.

The ready event advertises editor.host-request-save, editor.focus.stable, and templates.catalog.packaged. Hosts must require capabilities rather than infer support from version prose.

Stable focus and diagnostics

The editor remembers one active slide ID for each surface. Switching surfaces restores that surface's remembered slide, and diagnostics reports the real activeSlides map for Main, Companion, and Emphasis.

Focus validates that the slide exists and belongs to the named surface before calling the upstream Store navigation API. Unknown slides return SLIDE_NOT_FOUND; cross-surface identities return SLIDE_SURFACE_MISMATCH. Repeating an already-satisfied focus is successful and does not alter content, dirty state, accepted revision, or undo/redo history.

Revision authority

The loaded presentation revision is the immutable save base. Every mutating operation carries expectedRevision, and the editor rejects a stale value with REVISION_CONFLICT before mutation.

The editor never invents an accepted revision. It may hold dirty content while the envelope still contains the accepted base revision. The host persists that DTO and then sends save-accepted with the new stable revision. A rejection leaves the DTO and dirty state available for user review or reload.

Origin, source, and ordering

  • The bridge accepts only the configured exact origin.
  • The message source must be the editor's parent window.
  • Request IDs correlate responses and operation-result events.
  • Replayed IDs return DUPLICATE_REQUEST_ID and do not authorize mutation.
  • Invalid messages cannot reach the Bento store.
  • The top-level standalone editor is a repository demo; without a parent host, save requests are not durable.