Skip to content

Implementation Plan: ANU-12 - Build the Anuva Bento Editor and Template Families

Scope

  • Replace the ANU-10 representative editor entry and provisional layout wrapper with a production Anuva editor build that edits Main, Companion, and Emphasis through one editor instance while preserving the complete presentation context.
  • Add a versioned, same-origin editor-host protocol for validated load, save, revision, dirty-state, operation, result, and error messages. The host remains authoritative for persistence and accepted revisions.
  • Extend the server-safe Anuva contract with closed, runtime-validated schemas and TypeScript types for:
  • versioned template families;
  • coordinated per-surface layout packs;
  • dimensions, transparency, safe areas, theme tokens, and semantic slots;
  • semantic content bindings and explicitly user-owned extras;
  • editor compatibility and revision metadata; and
  • an allowlisted catalog of auditable, surface-aware AI operations.
  • Implement atomic theme, layout, and family application that preserves compatible semantic content and user extras, reports unsafe or ambiguous mappings before mutation, and participates in undo/redo as one command.
  • Implement editor media adapters for embedded fonts and externally bound image, SVG, chart-data/snapshot, audio, video, and poster assets without introducing embedded non-font payloads.
  • Provide representative coordinated family and layout fixtures for Main, Companion, and Emphasis, including differing dimensions, optional transparency, and safe areas.
  • Produce an exact-version production editor build that shares the ANU-11 renderer version source and excludes public Bento update and collaboration behavior.
  • Maintain normative editor-host, template-family, semantic-binding, AI-operation, media-adapter, undo/failure, security, versioning, and example-family documentation.

Product Main inputs and dependencies

  • Parent change: ANU-8, 2026-07-24-anuva-bento-integration.
  • Product Main source: docs/changes/2026-07-24-anuva-bento-integration/index.md.
  • Linear issue: ANU-12.
  • Completed blocker: ANU-11, which supplies:
  • contract, protocol, player, artifact, and Bento-base version authority;
  • runtime schemas, stable validation issues, compatibility evaluation, and pure transformations in @anuva/bento-contract;
  • identical document rules for Main, Companion, and Emphasis;
  • optional per-surface transparency;
  • stable presentation, revision, surface, slide, element, fragment, template, event, and asset identities;
  • embedded-font and external-non-font asset policy;
  • an offline deterministic player and exact-version artifact manifest; and
  • a renderer adapter boundary that the editor must remain compatible with.
  • Retained ANU-10 feasibility evidence:
  • the upstream structured editor can load an Anuva surface through an isolated entry;
  • materialize/dehydrate adapters can keep external non-font payloads out of serialized documents; and
  • semantic role mapping can preserve compatible content and report ambiguous mappings as unsafe.
  • Repository boundary: this issue owns editor contracts, validators, adapters, UI entry points, template-family schemas and fixtures, transformations, build artifacts, tests, and documentation. It does not own CMS persistence, PresentationConfig compilation, AI model invocation or orchestration, asset storage/upload, Web-host product UX, Python orchestration, or Unity hosting and capture.
  • The production editor may request and return complete validated DTOs, but it must not write an external datastore, assign an authoritative accepted revision, or silently resolve a revision conflict.

Implementation approach

1. Freeze the ANU-11 baseline and editor seams

  • Record the branch base, downstream and upstream commits, Bento version, Node, npm, TypeScript, Vite, contract, player, and renderer versions.
  • Before product changes, run npm ci, the upstream build, the documented Windows-equivalent single-file build, the 45,362-check convergence suite, ANU-11 contract/player tests, the Anuva build, and player packaging checks.
  • Inventory the current editor API, store history, document replacement, autosave, update, collaboration, file-save, asset, renderer, and layout seams. Prefer additions under slides/src/anuva/ and narrowly documented upstream adapters over a broad editor/model rewrite.
  • Replace provisional ANU-10 labels and fixtures only after their production equivalents pass. Preserve ANU-11 player behavior and artifact compatibility.

2. Define the editor, template-family, and operation contracts

  • Extend the server-safe contract package with closed schemas and pure JSON types for an editor protocol and template-family catalog. Keep Node import free of DOM, editor, renderer, network, and browser dependencies.
  • Define template-family identity and semantic version, supported contract and renderer versions, shared theme tokens, coordinated Main/Companion/Emphasis layout packs, per-layout viewport, transparency, safe-area insets, semantic slots, layout-owned elements, and explicit constraints.
  • Define semantic slots with stable identity, role, content kind, cardinality, compatibility constraints, and surface ownership. Distinguish layout-owned placeholders from semantic content and user extras so transformations can preserve, warn, or reject deterministically.
  • Define a closed AI-operation union covering only validated editor actions needed by this issue: semantic text updates, external media/chart binding updates, approved layout or family application, and approved slide creation, removal, or ordering. Every operation carries stable operation/request ID, target surface and stable target IDs, expected revision, actor/audit context, and typed payload.
  • Prohibit executable source, callbacks, expressions, arbitrary selectors, unrestricted JSON Patch, arbitrary property paths, inline event handlers, unsafe HTML, credential-bearing locators, and embedded non-font payloads.
  • Return stable issue and result codes with JSON-style paths and safe diagnostic context. Validate structural shape, cross-references, surface ownership, version compatibility, operation preconditions, content kind, safe area, viewport, and asset rules before editor mutation.

3. Build the revision-aware editor-host bridge

  • Add a production protocol such as anuva/bento-editor with an exact semantic version, request correlation, configured origin, parent-window source checks, compatibility declaration, and closed message validation.
  • Support host-to-editor load/reload, accepted-revision, rejected-save, operation, and diagnostics requests plus editor-to-host ready, save-request, revision/dirty-state, operation-result, and structured error events.
  • Treat the loaded revision as the immutable save base. Include the expected base revision in save and mutating-operation requests; reject stale or mismatched revisions with stable conflict results and no partial mutation.
  • Keep the host authoritative for accepted revision changes. A save request returns a validated, dehydrated presentation plus its base revision; only an explicit host acknowledgement advances the editor's accepted revision.
  • Define idempotency, duplicate request handling, event ordering, load supersession, cancellation, recovery after invalid messages, and safe reload behavior. Never infer success from message delivery alone.
  • Route production save behavior through this bridge. Do not create a second persistence authority through file handles, IndexedDB autosave, public collaboration, update services, or editor-owned remote requests.

4. Edit three surfaces in one presentation context

  • Keep one authoritative in-memory presentation session containing all three independent surface documents, timeline, assets, template metadata, compatibility, and revision state.
  • Add keyboard-accessible Main, Companion, and Emphasis navigation around one Bento editor/store instance. Before switching, dehydrate and validate the active surface; then materialize and load the selected surface without discarding unsaved changes on either inactive surface.
  • Preserve stable selection where valid, focus, dirty state, undo state, presentation identity, timeline references, asset bindings, and template context across switches. Never copy one surface document over another.
  • Enforce each surface's viewport, optional transparency, and safe-area overlay while editing. Surface kind does not imply dimensions or transparency.
  • Surface validation and save errors with their owning surface and stable path so the author can navigate directly to the failing content.

5. Implement semantic content and template-family application

  • Replace the provisional assessLayoutReapplication wrapper with pure, contract-owned plan/apply transformations that never mutate their inputs.
  • Build a deterministic mapping plan from stable slot identity and compatible semantic role/content kind. The plan classifies every source item and target slot as preserved, moved, created, empty, retained-extra, warned, or rejected.
  • Preserve compatible semantic content and explicitly user-owned extras. Remove only layout-owned placeholders or layout-owned decoration covered by the approved transformation. Never silently drop, concatenate, or duplicate semantic content to force a mapping.
  • Treat missing targets, cardinality loss, incompatible content kinds, duplicate/ambiguous slots, cross-surface references, invalid dimensions, and unsafe-area violations as explicit warnings or hard rejection according to documented rules.
  • Apply a layout to one surface, or a family/theme to all coordinated surfaces, from the reviewed mapping plan. Revalidate the complete presentation and asset bindings before committing the result.
  • Make family, theme, and layout application one atomic command across all affected surfaces. A failed surface rolls back the entire command; undo and redo restore the full presentation context, not only the currently visible Bento document.

6. Add coordinated example families and media adapters

  • Add versioned representative families with multiple layouts for each surface. Exercise landscape and non-matching companion/emphasis viewports, optional transparency on more than one surface kind, safe-area constraints, shared theme tokens, semantic text roles, user extras, images, SVG, charts, audio, video, and posters.
  • Validate that a family is coherent without requiring all surfaces to share dimensions, background behavior, element count, or slide count.
  • Adapt external assets into editor-safe runtime values for preview and editing, then dehydrate exact asset bindings before validation and save. Preserve embedded font binaries and reject embedded non-font data, inline SVG, undeclared assets, redirects, media-type mismatch, and digest mismatch.
  • Define deterministic replacement and removal behavior for every supported asset slot. Preserve asset identity where content is unchanged and clean up only bindings made unreachable by the committed atomic command.
  • Keep asset authentication, upload, storage, URL signing, and lifecycle management outside this repository.

7. Execute validated, auditable AI-operation primitives

  • Reuse the same command, validation, mapping, and undo paths for host-supplied AI operations and interactive editor actions; do not maintain a privileged AI mutation path.
  • Validate the whole operation batch against protocol, contract, revision, stable identities, surface ownership, semantic types, asset policy, and renderer capabilities before mutation.
  • Execute a batch atomically with deterministic ordered results. On any failed precondition or unsafe mapping, return stable per-operation diagnostics and leave the presentation unchanged.
  • Emit an audit result containing operation ID, actor/audit context, expected and resulting local revision state, target surface/identities, result code, and warnings without storing prompts, secrets, binary payloads, or sensitive response bodies.
  • Prove that malformed, unknown, future-version, script-bearing, arbitrary-patch, stale-revision, cross-surface, and incompatible operations cannot reach the Bento store.

8. Produce the secure production editor build

  • Add explicit production editor build and packaging entries with one shared renderer/version source used by the player. Fail the build or compatibility check when editor and player renderer versions diverge.
  • Define hard production mode before loading editor modules. Exclude or disable public Bento update, collaboration, speaker/presenter, self-update, file-persistence, and public-service entry behavior that conflicts with the host-owned editor boundary.
  • Inspect the emitted dependency graph and artifact contents. Verify no public update/collaboration endpoint, credential, source map containing secrets, or unintended persistence client is present.
  • Produce exact-version local artifacts and compatibility/checksum metadata with retained LICENSE and THIRD_PARTY_NOTICES.md. Do not publish a registry package, GitHub release, production deployment, or canonical documentation.

9. Document and hand off the editor boundary

  • Maintain ImplementationLog.md with decisions, source-change map, commands, tool versions, network behavior, renderer parity, skipped checks, fixtures, and artifact identities.
  • Add normative pages for the editor-host protocol; template-family authoring and versioning; semantic content bindings; the AI-operation catalog; media adapters; atomic undo/redo and failure behavior; editor security and packaging; and the example families.
  • Update repository architecture, presentation contract, compatibility, assets, errors, packaging, and security pages where ANU-12 establishes a durable rule.
  • Produce CompletionReport.md mapping every Linear acceptance criterion to exact contract, unit, integration, browser, accessibility, network, build, package, and documentation evidence.
  • Create a linked draft PR through the guarded Anuva CLI. Do not merge, mark Done, publish artifacts, or call preview documentation canonical.

Documentation impact

  • This planning step adds only this change index, this ImplementationPlan, and the navigation/index entries required to preview them.
  • After explicit plan approval, add and maintain:
  • this change's ImplementationLog.md and CompletionReport.md;
  • an editor documentation section covering host protocol, lifecycle, revisions, save behavior, and stable errors;
  • template-family schema, authoring, coordinated layout, safe-area, and versioning guidance;
  • semantic binding and preservation rules;
  • the closed AI-operation catalog and audit-result schema;
  • external-media materialization/dehydration rules;
  • atomic command, undo/redo, rollback, and failure behavior;
  • production editor security, network, renderer parity, packaging, and compatibility guidance; and
  • example-family documentation and fixtures.
  • Update existing contract and repository pages only for durable rules established by ANU-12.
  • Keep recursive index.md coverage and return exact bento1.girishd.com preview URLs after every logical documentation update.

Verification and acceptance checks

  • Baseline and regression:
  • clean base identity and remotes;
  • npm ci;
  • upstream npm run build;
  • documented Windows-equivalent single-file build;
  • node ..\scripts\test-sync.ts;
  • existing npm run test:anuva;
  • existing contract and player builds; and
  • existing player package/checksum verification.
  • Contract and schema:
  • server-safe package typecheck, build, declarations, and Node import without DOM/browser globals;
  • schema/type parity for editor protocol, template families, semantic slots, layout packs, revisions, operations, results, and audit context;
  • valid, invalid, boundary, unknown-field, future-version, cross-reference, unsafe-content, and incompatible fixtures;
  • stable issue code/path snapshots; and
  • deterministic pure transformations, repeatability, and input non-mutation.
  • Editor host and revision behavior:
  • exact origin and parent-source enforcement;
  • malformed, unsupported-version, wrong-runtime, duplicate, and unsolicited messages;
  • ready/load/reload/save/accepted/rejected/conflict/dirty/error ordering;
  • request correlation, idempotency, cancellation, load supersession, and recovery;
  • stale revision rejection with no partial mutation; and
  • proof that the editor does not persist to CMS or assign an accepted revision.
  • Three-surface editing:
  • repeated Main/Companion/Emphasis switching in one editor instance;
  • independent content, dimensions, safe areas, and transparency;
  • unsaved edit retention across switches;
  • stable presentation/timeline/asset/template context;
  • focus, selection, keyboard surface navigation, and accessible state labels;
  • surface-specific validation navigation; and
  • save/reload round-trip equality after materialize/dehydrate cycles.
  • Templates and semantic preservation:
  • layout, theme, and whole-family application;
  • coordinated application across all three surfaces;
  • compatible semantic text, media, chart, and user-extra preservation;
  • layout-owned placeholder cleanup;
  • missing, duplicate, ambiguous, incompatible, cardinality-loss, cross-surface, dimension, and safe-area cases;
  • dry-run plan equality with committed results;
  • atomic failure rollback; and
  • full-presentation undo and redo as one step.
  • Media adapters:
  • embedded-font round trip with no font request;
  • external image, SVG, chart-data/snapshot, audio, video, and poster edit and save cases;
  • replacement, removal, deduplication, binding cleanup, and stable identity;
  • integrity, media-type, redirect, timeout, HTTP, decode, and missing-asset failures; and
  • rejection of embedded non-font payloads, inline SVG, unsafe locators, and credential-bearing data.
  • AI operations:
  • every allowed operation and batch form;
  • deterministic order, typed results, audit context, and atomic undo;
  • surface and stable-target enforcement;
  • expected revision and operation preconditions;
  • malformed, unknown, future-version, cross-surface, unsafe-mapping, and incompatible operations; and
  • explicit rejection of scripts, callbacks, arbitrary selectors, arbitrary JSON Patch/property paths, unsafe HTML, and binary or secret payloads.
  • Production build and security:
  • editor and player renderer/version parity;
  • production editor build and exact-version artifact manifest;
  • dependency/output inspection for editor/update/collaboration separation;
  • denied public Bento update/collaboration requests;
  • exact local/runtime/declared-asset request allowlist;
  • host-origin and source denial in browser tests;
  • no alternate editor persistence authority; and
  • retained license and third-party notices.
  • Browser and accessibility:
  • production artifact smoke in the Web host;
  • three-surface edit, template apply, media edit, save, conflict, undo, redo, reload, and recovery scenarios;
  • keyboard-only navigation and commands;
  • focus visibility and restoration;
  • names, roles, states, live errors, and warnings; and
  • no uncaught errors or unexpected network requests.
  • Documentation:
  • criterion-by-criterion ImplementationLog and CompletionReport evidence;
  • recursive index validation;
  • strict MkDocs build;
  • fresh live-preview validation; and
  • exact valid preview links.

Non-goals and rollback

  • No CMS persistence, database writes, PresentationConfig compilation, authoring-workflow ownership, asset upload/storage, URL signing, or authentication implementation.
  • No AI model call, prompt construction, provider integration, content planning, moderation workflow, job orchestration, or unrestricted generated-code execution.
  • No Python staging, retry, orchestration, upload, or service integration.
  • No Unity/Vuplex host lifecycle, virtual-screen mapping, transport, timing, capture, or production integration.
  • No product Web-host shell beyond the repository-local editor bridge and test harness.
  • No broad rewrite of the upstream editor, renderer, store, save system, or document model and no unrelated upstream synchronization.
  • No registry publication, GitHub release, production deployment, canonical docs publication, PR merge, or Linear completion.
  • Before merge, rollback is removal of the ANU-12 editor build, bridge, template-family/operation contract additions, adapters, example families, fixtures, tests, artifacts, and normative docs from the feature branch. ANU-11 remains the accepted contract/player baseline.

Approval

Approved by Girish on 2026-07-26. Girish separately approved implementation start on 2026-07-26.