Skip to content

Implementation Plan: ANU-10 - Prove Anuva Bento Editor, Player, and Vuplex Feasibility

Scope

  • Preserve the imported Bento v1.0.8 baseline and prove that it remains reproducible before and after the spike.
  • Create the smallest provisional Anuva adapter and build-entry boundary needed to exercise:
  • the existing structured Bento editor;
  • a read-only, externally controlled player;
  • a Web host with Main, Companion, and transparent Emphasis surfaces; and
  • a simulated Unity-style authoritative playback clock in Web tests.
  • Prototype a versioned three-surface envelope and versioned command/event protocol. These are feasibility artifacts, not the production contract.
  • Exercise representative documents containing semantic text roles, fonts, images, SVG, charts, transitions, state/fragment behavior, supported media, and transparent Emphasis content.
  • Prove external reset/seek/tick determinism, asset readiness, offline network behavior, template reapplication, and one upstream merge.
  • Keep image, SVG, chart-dataset/snapshot, and media payloads outside the Bento file. Embed every required font binary in the Bento file.
  • Produce criterion-by-criterion evidence and a proceed, revise, or stop recommendation for Product Main. Publish no production package.

Product Main inputs and dependencies

  • Parent change: ANU-8, 2026-07-24-anuva-bento-integration.
  • Linear issue: ANU-10.
  • Completed dependency: ANU-9, including the private downstream, v1.0.8 provenance, repository workflow, and upstream-sync policy.
  • Product invariants:
  • three independent surface documents and one authoritative timeline;
  • exact runtime compatibility and stable identities;
  • a host-owned authoritative playback clock, simulated in Web tests here and owned by Unity in the later production integration;
  • no public Bento update or collaboration dependency in production mode;
  • asset readiness before capture;
  • externally referenced image/SVG/chart/media assets and embedded fonts;
  • transparent transient Emphasis behavior; and
  • preserved licenses and third-party notices.
  • Repository boundary: this issue may build a Bento-owned player, bridge, fixtures, test host, and test artifacts. It must not implement CMS persistence, Python orchestration, or Unity production behavior.
  • Approval boundary: completing the spike supplies evidence only. ANU-11 and later production children must not start until Product Main records an explicit go decision.
  • Approved planning constraints for this revision:
  • Unity/Vuplex verification is deferred; Web tests are sufficient for ANU-10.
  • Performance testing and profiling are deferred.
  • The Completion Report must mark the original Vuplex and performance criteria as deferred by this approved plan, not as independently verified. Product Main decides whether the revised evidence is sufficient for go.

Implementation approach

1. Freeze the baseline and evidence method

  • Record the downstream and upstream commits plus runtime/tool versions.
  • Run npm ci, the normal upstream build, the Windows-equivalent single-file build, and the upstream sync/convergence test before changing product source.
  • Keep all Anuva-authored source behind a clearly named adapter directory, dedicated HTML/build entries, fixtures, and focused tests. Record a source-change map that distinguishes adapters from necessary upstream seam changes.

2. Prototype the composite envelope and fixtures

  • Define a provisional, pure-data version-1 envelope with presentation identity, contract/runtime version, Main/Companion/Emphasis descriptors, per-surface viewport/transparency data, representative Bento documents, a minimal ordered timeline, external asset identities/readiness expectations, and embedded-font metadata.
  • Validate required fields, supported versions, surface uniqueness, safe data, and document compatibility at the adapter boundary.
  • Create representative Main, Companion, and Emphasis fixtures. The Emphasis fixture uses a transparent background and sparse show/hide timing.
  • Keep the envelope separate from the upstream BentoDoc model except for the minimum typed adapter needed to load a surface document.
  • Store image, SVG, chart dataset/snapshot, and media payloads behind external asset references. Presentation semantics such as element geometry, labels, and chart configuration may remain structured document data. Store every font binary needed by a document inside that Bento file.

3. Add an isolated read-only player and host bridge

  • Add a dedicated player entry that reuses the upstream renderer/presenter but does not boot the editor, update UI, collaboration session, speaker view, or interactive self-update behavior.
  • Expose a provisional version-1 direct JavaScript API and equivalent structured host-message adapter. Requests carry protocol version and request identity; responses and events carry runtime version, surface identity, state, and structured error information.
  • Exercise initialize, load, reset, absolute seek, external tick, show, hide, clear, and diagnostics. Emit ready, assets-ready, state-changed, animation-complete, and structured error evidence.
  • Reject unknown versions, malformed commands, unsafe messages, and commands issued before the required readiness state. The test Web host validates the message origin rather than accepting arbitrary callers.

4. Prove deterministic time and asset behavior

  • Add the smallest clock seam needed to drive approved transition/animation behavior from absolute host time rather than wall-clock autoplay.
  • Implement a deterministic Web test clock that uses the same host-owned reset/seek/tick sequencing expected from the later Unity integration.
  • Define reset as restoration of a known loaded state. Define seek as rebuilding that state at an absolute timeline position, then allow tick to advance it monotonically from the host clock.
  • Run repeated reset/seek/tick sequences in different navigation orders and compare normalized player state plus captured frames at fixed checkpoints.
  • Inventory renderer features that remain wall-clock, browser-dependent, or unsafe to seek. Any unsupported animation/media behavior becomes an explicit production-contract restriction or a revise/stop finding.
  • Gate assets-ready on all embedded fonts and externally referenced image/SVG/chart/media assets being renderable, and verify that simulated capture does not start before that event.
  • Inspect serialized fixtures to reject embedded non-font data URIs or payload blobs, reject unresolved font references, and verify that fonts cause no network request.

5. Prove offline Web hosting

  • Make the Anuva player build offline-by-construction: it must not initialize update checks, online collaboration, or public-service clients. Retain local browser primitives only where they do not create network traffic.
  • Serve the player artifact to a Web three-surface harness driven entirely by the simulated host clock.
  • Capture browser requests while loading, controlling, and replaying the fixtures. Any request to Bento update or collaboration services fails the criterion. Expected requests are limited to the local player host and the explicitly configured external asset host.
  • Compare repeated Web checkpoints for dimensions, embedded fonts, external images/SVG/charts/media, state/fragment behavior, and transparency.
  • Do not run Unity, Vuplex, frame-time, memory, CPU/GPU, startup-latency, or concurrent-player profiling in this issue.

6. Exercise semantic template reapplication

  • Use the existing role/id-based layout machinery with a representative template-family fixture spanning the three surface types.
  • Verify that compatible title/body/kicker and linked content survive reapplication, user extras remain, and layout-owned empty placeholders are replaced safely.
  • Add an ambiguous or incompatible mapping case and require an explicit unsafe mapping result. The spike must not silently drop semantic content.

7. Rehearse upstream synchronization

  • Create a disposable rehearsal branch from the current downstream branch and merge the current recorded upstream ref without pushing or merging it to main.
  • Run the baseline plus focused spike checks on the rehearsal result, record conflicts by path and cause, and confirm the Anuva adapter/build entries survive.
  • Remove or retain the rehearsal branch according to the documented upstream sync procedure; never rewrite downstream or upstream refs.

8. Report and hand off the decision

  • Maintain ImplementationLog.md while running the spike.
  • Produce CompletionReport.md with the provisional envelope/API, exact build identity, source-change map, Web setup, simulated external-clock evidence, asset matrix, serialized-document inspection, network capture, deterministic replay evidence, template results, upstream rehearsal, limitations, and every Linear acceptance criterion.
  • Identify Unity/Vuplex verification and performance profiling as deliberately deferred to later work. Do not convert absence of those tests into a pass.
  • Recommend exactly one of:
  • proceed: every criterion retained in this revised plan passes and Product Main accepts the documented deferrals;
  • revise: the evidence supports a bounded design or topology change; or
  • stop: a core requirement is infeasible or would require pervasive downstream divergence.
  • After the Bento PR is reviewed and merged, synchronize the report and links to Product Main. Do not start a production issue during this handoff.

Documentation impact

  • Add this change index, ImplementationPlan.md, ImplementationLog.md, and CompletionReport.md.
  • Document the provisional envelope and external API as spike evidence, clearly marked non-normative.
  • Document the source-change map, build entries, Web host and simulated external clock, supported-feature and asset matrix, embedded-font/external-asset policy, offline-network observations, deterministic-time findings, template reapplication, deferred checks, upstream rehearsal, and go/no-go recommendation.
  • Preserve the existing repository architecture, provenance, security/license, and upstream-sync records; update them only if the spike proves a durable correction.
  • Return exact bento1.girishd.com preview URLs after every logical docs update.

Verification and acceptance checks

  • Baseline: clean commit/remotes, upstream ancestry, npm ci, normal build, Windows-equivalent single-file build, and sync/convergence checks.
  • Structure: typecheck/build, focused adapter tests, contract fixtures, dedicated player build, license/notices inspection, and source-change map.
  • Host/API: valid and invalid command/event cases, readiness ordering, origin/version validation, structured failures, Web host smoke, and exact runtime identity.
  • Determinism: repeated reset/seek/tick orderings, normalized state comparison, fixed-time frame comparisons, transparency, state/fragment behavior, and unsupported-effect inventory.
  • Assets/network: embedded-font readiness, external image/SVG/chart-dataset/media readiness, serialized-document payload checks, browser request capture, zero font requests, and zero requests to public Bento update or collaboration services.
  • Web clock simulation: host-driven initialization, reset, arbitrary seek, external tick, show/hide/clear, readiness ordering, and repeated three-surface checkpoint comparisons.
  • Templates: compatible semantic preservation plus explicit unsafe-mapping evidence.
  • Upstream: disposable merge rehearsal, conflict inventory, adapter preservation, and repeated baseline/focused checks.
  • Docs: recursive change indexes, strict MkDocs build, live-preview freshness, and valid links.

Non-goals and rollback

  • No production contract, published package, release artifact, public repository, or production service deployment.
  • No CMS persistence/editor integration, Python staging/orchestration, or Unity production integration.
  • No Unity/Vuplex verification and no performance testing or profiling.
  • No migration of existing Reveal-oriented development data and no removal of current production paths.
  • No adoption of Bento's update or collaboration services.
  • No broad rewrite of upstream editor, renderer, presenter, or model code.
  • No automatic Product Main go decision or start of ANU-11 through ANU-16.
  • Before merge, rollback is deletion of spike-only adapters, entries, fixtures, tests, and docs from the feature branch. After an accepted spike merge, the artifacts remain private, provisional evidence; production consumers still require the later approved contract issue.

Approval

Approved by Girish on 2026-07-24 after incorporating the Web-only clock verification, deferred performance work, external non-font asset policy, and embedded-font requirement.