Skip to content

Implementation Plan: ANU-11 - Build the Anuva Bento Contract and Deterministic Player

Scope

  • Replace the provisional ANU-10 envelope and protocol with a production, versioned, pure-data contract covering:
  • presentation identity and revision;
  • Main, Companion, and Emphasis surface documents governed by the same rules;
  • one authoritative absolute-time timeline;
  • semantic template and content-role metadata;
  • stable surface, slide, element, fragment, event, and asset identities;
  • external non-font assets and embedded font metadata;
  • compatibility declarations and required runtime capabilities; and
  • structured, stable validation and runtime errors.
  • Add a private, server-safe contract package with runtime schemas, TypeScript types, validators, compatibility evaluation, and pure transformations. The package must not import the Bento editor, browser globals, DOM types, renderer, player, update client, or collaboration code.
  • Promote the spike player into a production read-only build exposing the approved load, reset, seek, tick, show, hide, clear, and fragment commands plus readiness, state, animation, and error events.
  • Make deterministic replay and arbitrary seek authoritative for the explicitly supported animation, fragment, surface-visibility, and media-state subset. Reject unsupported behavior during validation or load with stable errors rather than silently falling back to wall-clock playback.
  • Build exact-version, checksummed, offline static player artifacts that retain required license and third-party notices and contain no editor-only, updater, collaboration, or public Bento service behavior.
  • Provide fixtures and package/artifact references suitable for CMS, Python, and Unity compatibility checks without implementing those consumers.
  • Maintain normative contract, schema, compatibility, player API, error, asset, packaging, security, licensing, and release documentation.

Product Main inputs and dependencies

  • Parent change: ANU-8, 2026-07-24-anuva-bento-integration.
  • Linear issue: ANU-11.
  • Completed dependency: ANU-10, including its proceed recommendation, isolated Anuva source boundary, Web-host deterministic clock evidence, transparent Emphasis proof, embedded-font/external-non-font asset policy, offline seam, and semantic template-reapplication findings.
  • Product Main approved proceeding after ANU-10.
  • Product invariants retained from ANU-10:
  • three independent surface documents and one authoritative timeline;
  • exact runtime compatibility and stable identities;
  • a host-owned authoritative playback clock;
  • asset readiness before capture;
  • externally referenced image, SVG, chart-data/snapshot, and media assets;
  • embedded font binaries;
  • optional per-surface transparency independent of surface kind; and
  • no production dependency on public Bento update or collaboration services.
  • Repository boundary: this issue owns Bento schemas, validators, compatibility metadata, pure transformations, player code, artifacts, fixtures, tests, and documentation. It does not implement CMS persistence or compilation, Python orchestration, Unity hosting/capture, or product-level issue sequencing.
  • Approved deferrals:
  • Unity/Vuplex embedding, transport, transparency, lifecycle, and capture integration testing is deferred.
  • Performance, frame-time, memory, CPU/GPU, startup-latency, and concurrent-player profiling is deferred.
  • Repository-local compatibility fixtures may model CMS, Python, and Unity consumer declarations, but must not be described as consumer integration evidence.
  • The Completion Report must mark the deferred areas as not run and must not infer a pass from Web-only or repository-local evidence.

Implementation approach

1. Freeze the ANU-10 production baseline

  • Record the branch base, downstream and upstream commits, Bento version, Node, npm, TypeScript, and Vite versions.
  • Before product changes, run npm ci, the upstream build, the documented Windows-equivalent single-file build, the 45,362-check convergence suite, focused ANU-10 tests, and the Anuva build.
  • Preserve the isolated slides/src/anuva/ boundary and the single existing hard-offline seam in slides/src/update.ts. Record every production source seam added or changed by ANU-11.

2. Create the server-safe contract package

  • Add a dedicated private package under packages/anuva-bento-contract/ with explicit package name and semantic version, ESM exports, declarations, runtime schemas, fixtures, and an artifact manifest.
  • Define pure JSON-domain types rather than importing slides/src/model.ts. Keep the package build free of DOM libraries and verify import in a Node process where window, document, and browser APIs are absent.
  • Export canonical identifiers and versions for the composite presentation, surface document, timeline, player protocol, error catalog, compatibility manifest, and artifact manifest.
  • Provide generated-or-checked parity between runtime schemas and TypeScript types. Unknown fields, unsafe values, incompatible versions, duplicate or unstable identities, dangling references, unordered events, unsafe URLs, executable content, embedded non-font payloads, and unsupported player features must fail deterministically.
  • Return structured validation issues containing stable code, JSON-style path, severity, and safe diagnostic context. Do not make downstream consumers parse human prose to determine failure type.

3. Finalize identity, compatibility, and transformation rules

  • Define non-empty, stable identities for presentations, revisions, surfaces, slides, elements, fragments, timeline events, templates, content bindings, and assets. Enforce uniqueness in the correct scope and reject dangling references.
  • Define compatibility metadata containing exact contract, protocol, player, artifact, and Bento-base versions plus declared required and optional capabilities.
  • Export a pure compatibility evaluator that returns supported or rejected with stable reason codes. Exercise representative CMS, Python, and Unity consumer declarations as repository-local fixtures.
  • Replace the spike's broad recursive chart-data stripping with schema-specific pure transformations. Prove that normalize, validate, materialize-plan, and dehydrate operations are deterministic, do not mutate their inputs, and do not introduce browser dependencies.
  • Preserve embedded fonts and externalize every non-font payload. Require asset identity, kind, media type, integrity metadata, and an allowed locator form; keep authentication material and executable content out of the contract.

4. Promote the deterministic read-only player

  • Make the player consume the contract package through a narrow adapter from contract DTOs to Bento renderer data. The package stays pure; fetching, rendering, and DOM behavior remain in the player.
  • Expose a versioned direct JavaScript API and equivalent same-origin structured message bridge for load, reset, absolute seek, monotonic external tick, show, hide, clear, and fragment.
  • Define request correlation, lifecycle states, command preconditions, idempotency expectations, event ordering, and stable errors. Reject malformed requests, wrong sources/origins, unsupported versions, invalid state transitions, regressing ticks, and commands issued before readiness.
  • Define reset and arbitrary seek as reconstruction from the loaded immutable presentation at absolute time. Define fragment through stable fragment identity and deterministic state rather than Reveal navigation side effects.
  • Emit versioned ready, assets-ready, state-changed, animation-complete, and error events with presentation, surface, request, runtime, and absolute-time context where applicable.
  • Gate usable readiness on schema validation, compatibility, embedded fonts, external assets, and renderability. Make load cancellation and asset failures leave the player in a defined recoverable state.
  • Disable or exclude editor entry points, editing state, autosave, update behavior, collaboration, speaker view, authoring shortcuts, and implicit wall-clock autoplay from the production player graph.

5. Define and prove the deterministic feature subset

  • Enumerate the supported transition, enter animation, fragment, surface visibility, chart, and media-seek behaviors in the normative compatibility data.
  • Derive all visual state from the immutable envelope plus absolute host time. Sequential ticks, reset plus direct seek, repeated seek, and navigation in different command orders must converge on the same normalized state and Web checkpoint fingerprint.
  • Reject morph, loop, ambient, count-up, unseekable media, or other browser/wall-clock-dependent features unless ANU-11 implements and verifies a deterministic rule for them.
  • Exercise Main, Companion, and Emphasis fixtures under the same validation and playback rules at boundary times, simultaneous events, fragment transitions, arbitrary backward seek, clear/show/hide sequences, and end-of-timeline behavior. Exercise optional transparency without making it an Emphasis requirement.
  • Use Web tests for player rendering and clock evidence. Do not claim Unity/Vuplex behavior or performance characteristics.

6. Secure asset loading and offline behavior

  • Resolve only contract-declared assets, require expected media type and integrity, deduplicate requests, and produce stable timeout, network, status, integrity, decode, font, and media-readiness errors.
  • Restrict host messages to the configured origin and parent source. Restrict requests to player-local files and exact declared assets; deny redirects or resolved URLs that escape the allowlist.
  • Capture requests during load, control, reset, arbitrary seek, and replay. Fail any attempt to contact public Bento update/collaboration services or undeclared hosts.
  • Verify that embedded fonts generate no network requests and that serialized fixtures contain no embedded image, SVG, chart dataset/snapshot, audio, or video payload.

7. Package exact-version artifacts

  • Add production contract-package and static-player build entries with one runtime version source and reproducible output naming.
  • Produce a package tarball inspection and a static player artifact directory containing only required runtime files, compatibility metadata, checksums, LICENSE, and THIRD_PARTY_NOTICES.md.
  • Generate a deterministic manifest containing contract, protocol, player, package, artifact, and Bento-base versions plus SHA-256 digests for distributed files. Rebuild and compare manifests to detect nondeterministic output.
  • Inspect dependency graphs and emitted assets to prove the server package has no DOM/editor dependency and the player has no editor, updater, collaboration, or unexpected network entry.
  • Do not publish a registry package, GitHub release, or canonical documentation in this issue. Record exact local artifact paths and digests for downstream handoff and later approved release work.

8. Document and hand off the production contract

  • Maintain ImplementationLog.md with decisions, source-change map, commands, versions, network behavior, skipped checks, and artifact identities.
  • Add normative pages for schemas and identities, compatibility negotiation, player commands/events/lifecycle, error codes, assets/readiness/security, packaging/versioning/checksums, license/notices, supported deterministic features, and consumer fixture usage.
  • Produce CompletionReport.md mapping every Linear acceptance criterion to exact test, Web, package, artifact, and documentation evidence.
  • Mark Unity/Vuplex and performance testing as explicitly deferred and not run. Preserve unresolved limitations and required downstream verification as named risks.
  • 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;
  • normative contract/schema and identity documentation;
  • compatibility and supported-feature documentation;
  • player API, lifecycle, command/event, and error documentation;
  • asset, readiness, network, and security documentation;
  • package, artifact, checksum, license, and release documentation; and
  • fixture and downstream-consumer handoff references.
  • Update repository architecture and security/licensing pages only where ANU-11 establishes a durable production rule.
  • 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; and
  • existing npm run build:anuva.
  • Contract package:
  • package-only typecheck/build and declaration generation;
  • runtime-schema/type parity;
  • valid, invalid, boundary, unknown-field, unsafe-content, and incompatible fixtures;
  • property/fuzz-style invariant checks for identities, references, ordering, versions, and pure transformations;
  • stable error code/path snapshots;
  • input non-mutation and repeatability; and
  • Node server import with DOM/browser globals unavailable.
  • Compatibility:
  • exact supported combinations;
  • old, future, malformed, missing-capability, and artifact-mismatch cases;
  • repository-local CMS, Python, and Unity consumer declarations; and
  • stable rejection reasons before player or asset use.
  • Player API and lifecycle:
  • every approved command and event;
  • request correlation and event ordering;
  • pre-load, loading, ready, reset, cleared, hidden, and failed states;
  • same-origin/source validation;
  • invalid command/version/time/state cases; and
  • recoverable repeated load/reset behavior.
  • Determinism:
  • sequential tick versus direct seek;
  • arbitrary backward and forward seek;
  • repeated reset/seek/tick command permutations;
  • stable fragment identity and state;
  • simultaneous and boundary-time events;
  • supported transitions and enter animations;
  • representative chart and seekable media state;
  • identical Main, Companion, and Emphasis document behavior plus optional per-surface transparency; and
  • normalized state plus fixed-time Web checkpoint comparison.
  • Assets and security:
  • embedded-font readiness with zero font requests;
  • external image, SVG, chart-data/snapshot, audio, video, and poster cases;
  • integrity, media-type, redirect, timeout, HTTP, decode, and missing-asset failures;
  • serialized-payload rejection;
  • exact request allowlist and public-service denial; and
  • no executable document content or authentication secrets.
  • Packaging:
  • exact semantic versions in package, protocol, runtime, compatibility, and artifact manifests;
  • package tarball contents and server-safe dependency inspection;
  • static player contents and editor/update/collaboration exclusion;
  • SHA-256 manifest verification and repeated-build comparison;
  • offline Web smoke from produced artifacts; and
  • LICENSE and THIRD_PARTY_NOTICES.md retention.
  • Documentation:
  • criterion-by-criterion ImplementationLog and CompletionReport evidence;
  • recursive index validation;
  • strict MkDocs build;
  • fresh live-preview validation; and
  • exact valid preview links.
  • Explicitly not run:
  • Unity/Vuplex integration, transport, transparency, lifecycle, or capture testing; and
  • performance, profiling, startup-latency, memory, CPU/GPU, frame-time, or concurrent-player testing.

Non-goals and rollback

  • No CMS persistence, PresentationConfig compilation, authoring workflow, or package ingestion implementation.
  • No Python staging, retry, orchestration, upload, or service integration.
  • No Unity/Vuplex host lifecycle, virtual-screen mapping, message transport, capture, or production integration.
  • No performance targets, profiling, benchmark acceptance, or capacity claims.
  • No public Bento update/collaboration dependency, executable document content, embedded non-font payload, or secret-bearing asset locator.
  • No broad rewrite of the upstream editor, renderer, presenter, 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-11 package, production-player additions, generated build entries, fixtures, tests, normative docs, and narrow adapter seams from the feature branch. The ANU-10 spike remains the last accepted baseline.

Approval

Approved by Girish on 2026-07-25 with one clarification: Emphasis is governed by the same surface-document rules as Main and Companion. Transparency remains an optional per-surface player capability and is not an Emphasis requirement.