Skip to content

Change Brief: Bento readiness gate for ANU-14

Identity

  • Change ID: 2026-07-27-anu-17-bento-readiness-gate
  • Source Linear change issue: ANU-17
  • Priority: High
  • Owner: Product Main coordination with anuva-bento delivery
  • Status: Implementation delivered; completion review approved

User outcome

ANU-14 can deliver reliable editor autosave, open the exact scene and surface the user selected, and load the approved Signal/Paper templates through a reviewed Bento artifact instead of reaching into iframe internals or duplicating Bento-owned data in CMS.

Current behavior

  • The anuva/bento-editor 1.0.0 host protocol can emit a validated save-request after an editor-local Save action, but the host cannot request that same action for debounced autosave.
  • The protocol has no stable focus command. The editor session switches surfaces but reports the first slide as current rather than tracking the actual active slide.
  • The editor load command requires template families, but the packaged editor artifact does not expose a host-readable, checksummed Signal/Paper catalog.
  • ANU-14 is In Progress, but its approved implementation plan explicitly stops before CMS code changes until a reviewed Bento-owned artifact closes these gaps.

Target behavior

Host-triggered save

  • Protocol 1.1.0 adds a closed request-save command with payload { trigger: "manual" | "autosave" }.
  • The bridge routes the command through the existing validated save path used by the editor Save control. It does not simulate keyboard input or expose an iframe DOM escape hatch.
  • A successful request emits save-request with the host request ID, accepted baseRevision, requested trigger, and complete validated envelope.
  • Validation failure and duplicate request handling are deterministic and correlated to the host request ID.
  • Persistence and accepted-revision authority remain with the host.

Stable editor focus

  • Protocol 1.1.0 adds a closed focus command accepting { surface, slideId, sceneId? }.
  • Bento authoritatively validates that slideId belongs to the requested surface, switches surfaces when required, and navigates through the Bento store's supported API.
  • The session tracks and reports the real active slide for each surface.
  • Focus is idempotent and never changes document content, dirty state, accepted revision, undo history, or redo history.
  • Missing slides and cross-surface targets return stable structured errors. sceneId is optional opaque correlation data, not document identity.

Packaged template catalog

  • The editor package contains deterministic JSON for the exact Signal and Paper families generated from the same source used by the runtime.
  • The artifact manifest exposes a descriptor containing at least catalog path, format version, SHA-256, and family IDs.
  • Rebuilding the same source produces byte-identical catalog content and hash.
  • The host can verify and load the catalog without private runtime access, copied definitions, credentials, or a public-service request.

Compatibility and capability discovery

  • The editor protocol, editor artifact, and contract package advance together to 1.1.0.
  • The presentation contract, player protocol, renderer, and template-family object version remain unchanged unless their serialized shapes actually change.
  • Editor readiness and artifact metadata advertise explicit capabilities for host-requested save, stable-slide focus, and the packaged catalog.
  • Consumers reject unsupported protocol, capability, version, or checksum combinations before editor load.

Known constraints

  • Product implementation belongs in anuva-bento; Product Main will not modify Bento or CMS implementation code.
  • ANU-14 must not work around the gate with iframe DOM access, synthetic keystrokes, the private debug adapter, hand-copied template definitions, or a CMS-owned fork of the Bento contract.
  • sceneId -> slideId ownership remains in CMS. Adding scene identity to the presentation envelope is outside this change.
  • Existing hard-offline behavior, exact-origin/source message validation, server-safe contract imports, license/notices, and host persistence authority must be preserved.
  • The current renderer and player need no version bump when their behavior and serialized contracts are unchanged.

Non-goals

  • Implementing ANU-14 CMS persistence, autosave queues, conflict recovery, AI operations, media hosting, editor UI, or Web preview.
  • Changing the PresentationConfig envelope or authoritative timeline.
  • Adding a protocol command that lets the host perform arbitrary navigation, arbitrary mutation, DOM access, or raw script execution.
  • Moving template-family ownership into CMS or fetching catalogs from a public Bento service.
  • Redesigning Bento editor controls, templates, player behavior, or the renderer.
  • Reopening the approved ANU-8 downstream, ownership, or compatibility decision.

Product acceptance criteria

  • [ ] TypeScript types, runtime validation, and distributed JSON Schema define identical closed request-save and focus command shapes.
  • [ ] Manual and autosave requests reuse the existing validated save path and preserve host request ID, base revision, trigger, and complete envelope.
  • [ ] Malformed, duplicate, and validation-failing save requests return stable, correlated results without changing accepted revision state.
  • [ ] Focus succeeds for non-first slides on Main, Companion, and Emphasis, preserves each surface's last focus, and reports the real active slide.
  • [ ] Missing and cross-surface slide targets fail with stable structured errors.
  • [ ] Focus idempotency leaves content, dirty state, revision, undo, and redo unchanged.
  • [ ] A deterministic Signal/Paper JSON catalog is generated from the runtime source of truth and included in the editor artifact.
  • [ ] The artifact manifest declares catalog path, format version, SHA-256, and exact family IDs; a clean rebuild reproduces the catalog and hash.
  • [ ] The contract package and editor artifact are 1.1.0, expose the required capabilities, retain exact renderer compatibility, license, notices, and hard-offline behavior, and pass package inspection.
  • [ ] A real host/editor browser scenario proves request-save correlation, stable focus across all surfaces, catalog loading, and no public-service network request.
  • [ ] Bento publishes a CompletionReport containing the reviewed commit, artifact paths, versions, manifests, hashes, verification evidence, limitations, recovery guidance, and ANU-14 handoff.
  • [ ] Product Main completion review verifies the artifact against this gate before ANU-17 can become Done.

Migration and rollback

This is an additive pre-consumption protocol upgrade. No persisted presentation data migration is required.

  • Consumers that require the new capabilities must require protocol/editor/ contract 1.1.0 and fail closed against 1.0.0.
  • Existing 1.0.0 artifacts remain immutable evidence; they are not overwritten or silently treated as compatible.
  • If implementation or packaging verification fails, publish no 1.1.0 artifact and keep ANU-14 at its readiness gate.
  • Recovery is to correct the Bento branch, rebuild from the recorded source, and repeat contract, package, browser, offline, and hash verification.

Failure and cancellation behavior

  • Invalid messages, unsupported commands, missing targets, cross-surface targets, incompatible versions, or checksum mismatches fail with structured errors and no document mutation.
  • Save validation failure emits no apparently successful save proposal.
  • Catalog generation or manifest mismatch fails the package build.
  • Partial artifacts, unreviewed working-directory output, and unverifiable hashes cannot satisfy ANU-17.
  • If the scope expands into the presentation envelope, renderer/player behavior, or CMS implementation, return to Product Main planning for revision before continuing.

Security and privacy

  • Preserve exact origin and parent-window source checks for every host message.
  • Keep the command union closed and reject unknown fields and executable data.
  • Do not place credentials, signed URLs, user content, or private service endpoints in the template catalog or manifests.
  • Production artifacts remain hard-offline and retain required license and third-party notices.
  • Error details are structured and safe for host display; they do not expose document content or internal paths unnecessarily.

Documentation impact

  • Product Main adds this change folder, issue registry, repository impact, and progress record.
  • anuva-bento creates the implementation change folder and updates the editor-host protocol, template-family/catalog, packaging/manifest, compatibility/capabilities, structured-error, security, and verification documentation.
  • ANU-14's CMS plan and implementation log may record the final reviewed Bento commit, versions, paths, and hashes when CMS work resumes. No CMS code or durable contract change is part of this product-planning phase.

Approval record

  • Plan reviewed by: Girish
  • Approved at: 2026-07-27 15:06 UTC
  • Approval notes: Approved as written, including the single Bento child, protocol/editor/contract 1.1.0 boundary, host-save and stable-focus command shapes, packaged Signal/Paper catalog, unchanged presentation/player/renderer boundary, and prohibition on CMS workarounds.