Skip to content

Change Brief: Anuva Bento Integration

Identity

  • Change ID: 2026-07-24-anuva-bento-integration
  • Source Linear change issue: ANU-8
  • Priority: High
  • Owner: Product Main coordination with Anuva Bento, CMS, Unity, and Python delivery
  • Status: Product plan approved; planning PR delivery pending

User outcome

Anuva users create, revise, preview, and render structured slide content through one Anuva Bento system. The Web application provides an AI-assisted Bento editor and preview, while Unity uses the same versioned player for Main Screen, Companion Screen, and Emphasis Projection output.

Current behavior

  • CMS planning and compilation produce Reveal-compatible HTML-oriented slide data rather than a durable structured slide document.
  • Web editing and preview do not use the same versioned renderer contract as Unity playback.
  • Unity experimentation contains three virtual screen surfaces and useful timing concepts, but the production contract does not yet make those surfaces first-class coordinated outputs.
  • Template changes, semantic AI edits, and content-preserving layout changes are difficult because content and presentation are coupled in generated markup.
  • Product Main has no registered anuva-bento repository, Linear label, CLI allowlist entry, docs preview, or implementation workflow.

Target behavior

Structured authoring

  • CMS persists one versioned Anuva Bento presentation with independent Bento documents for Main, Companion, and Emphasis surfaces.
  • Each surface contains stable scene and item identities plus semantic content bindings used by templates and validated AI operations.
  • The user launches the embedded editor from the Scene Editor, can focus any scene and surface, and retains full-presentation context.
  • Save, autosave, revision conflict, undo, and failure behavior are explicit.

Shared playback

  • One versioned Anuva Bento player implementation renders Web preview and three long-lived Unity Vuplex instances.
  • Unity owns the authoritative playback clock and can load, reset, seek, tick, show, hide, clear, and advance fragments deterministically.
  • Main and Companion may persist across scene boundaries. Emphasis is a sparse, transient, transparency-capable event surface.
  • The player reports readiness, asset readiness, state changes, animation completion, version information, and structured failures.

Controlled downstream

  • Shoonya-Game-Technologies/anuva-bento is an independent private downstream of nyblnet/bento, preserving upstream ancestry without joining GitHub's public fork network.
  • origin is the private Anuva repository and upstream is the public Bento source.
  • Upstream releases are merged only through reviewed sync branches; production never self-updates from Bento's public service.
  • Bento's MIT license, copyright, and third-party notices remain present in source and distributed artifacts.

Known constraints

  • The source requirements and candidate breakdown are in AnuvaBento.md.
  • The new private repository does not exist or participate in the Anuva allowlisted workflow yet; Product Main must bootstrap that boundary first.
  • Product implementation must occur in the repository that owns it. Product Main may change only product records and the narrow Anuva development harness.
  • The current development database and existing Reveal presentation data are disposable; no legacy data migration or dual-write format is required.
  • Web and Unity must use the same recorded player/runtime version for an accepted presentation or render package.
  • Production preview and rendering must work without Bento update, collaboration, or other public-service network calls.
  • Full implementation is conditional on an accepted feasibility spike.

Non-goals

  • Preserving current Reveal presentation data or running Bento and Reveal as permanent parallel production formats.
  • Removing Reveal.js from Bento's own internal navigation implementation during initial adoption.
  • Adopting Bento's public collaboration relay or signed self-update channel.
  • Replacing Payload, Mastra, Python orchestration, Unity, Vuplex, the render queue, or video capture.
  • Publishing Shoonya's Anuva-specific Bento modifications.
  • Automatically merging upstream Bento releases.
  • Finalizing every editor visual-design detail during Product Main planning.
  • Requiring every scene to show content on all three surfaces.

Product acceptance criteria

  • [ ] A private Shoonya-Game-Technologies/anuva-bento repository preserves the selected upstream tag, commit, ancestry, license, and third-party notices.
  • [ ] Product Main, Linear, the Anuva CLI, docs preview/publisher mappings, and repository instructions recognize anuva-bento.
  • [ ] The feasibility spike satisfies every documented go criterion and records explicit Product Main approval before production work starts.
  • [ ] The canonical presentation contract contains three independent surface documents and one authoritative cross-surface timeline.
  • [ ] Main, Companion, and Emphasis support their approved persistence, sequencing, transparency, and safe-area behavior.
  • [ ] One exact-version player implementation runs in Web preview and three Unity Vuplex instances.
  • [ ] Unity can load, reset, seek, externally tick, and restore all surfaces deterministically after arbitrary scene navigation.
  • [ ] The CMS editor loads and saves the full presentation, focuses any scene/surface, handles revision conflicts, and provides preview through the shared player.
  • [ ] Template-family changes preserve compatible semantic content, clearly report unsafe mappings, and remain undoable.
  • [ ] AI Assistant changes use validated, surface-aware operations rather than unrestricted raw HTML or JavaScript generation.
  • [ ] CMS compilation produces complementary multi-surface content and resolves narrative timing into the authoritative timeline.
  • [ ] CMS, Python, and Unity validate compatible format, runtime, and package versions before preview or rendering.
  • [ ] Fonts, images, SVG, charts, and supported media resolve consistently in Web and packaged offline Unity playback.
  • [ ] Production preview and render make no Bento update or collaboration network calls and contain no embedded CMS credentials.
  • [ ] Active Reveal-specific Anuva contracts, generators, validators, bridges, assets, and workflow documentation are removed after accepted cutover.
  • [ ] A representative presentation completes generation, user editing, template switching, Web preview, packaging, three-surface Unity playback, capture, and final video delivery.

Canonical contracts

Ownership

  • Product Main owns the product-level presentation invariants, compatibility policy, repository boundaries, and acceptance criteria.
  • anuva-bento owns the executable document schemas, validators, transformations, editor build, player build, templates, and release artifacts.
  • CMS owns presentation persistence, revisions, AI authoring operations, PresentationConfig compilation, authoritative timeline generation, editor hosting, Web preview, and render-package assembly.
  • Unity owns three-player lifecycle, Vuplex hosting, deterministic playback, virtual-surface mapping, readiness, and capture behavior.
  • Python owns render-package staging, version/checksum validation, transport, Unity lifecycle orchestration, and structured failure propagation.

Presentation envelope

The production contract contains:

  • format and contract version;
  • exact player/runtime version;
  • presentation identity and aggregate revision;
  • template family identity and version;
  • Main, Companion, and Emphasis surface documents;
  • per-surface viewport, transparency, and safe-area data;
  • stable scene, surface-item, element, and semantic-content identities;
  • one authoritative ordered surface timeline; and
  • immutable or checksummed asset/package references required for deterministic preview and rendering.

The feasibility spike may refine field names, but it must not weaken these invariants without a reviewed Product Main plan revision.

Runtime compatibility

  • Consumers reject unsupported contract or player versions before use.
  • Web preview and Unity record the exact same player version for an accepted presentation.
  • Packages are immutable for one render attempt and do not depend on expiring credentials or public Bento services.
  • Runtime errors use stable structured categories and never degrade silently to partial capture.

Compatibility and migration

This is a clean development-phase cutover:

  1. Build and accept Bento contract/player foundations alongside the current path.
  2. Add PresentationConfig v2, new persistence, fixtures, and package generation.
  3. Add Web editor/preview and Unity/Python consumers.
  4. Run cross-repository acceptance with representative fixtures.
  5. Recreate development data and switch the active path.
  6. Remove direct Reveal-specific Anuva contracts and assets in the same accepted cutover; keep no indefinite compatibility layer.

Rollback before cutover means retaining the current development branch and database state. Rollback after a failed cutover test means recreating development data on the last accepted contract and runtime, not converting Bento documents back to Reveal markup.

Failure, cancellation, and recovery behavior

  • If repository import, history, license, or upstream-build verification fails, do not begin the spike.
  • If the spike fails a go criterion, keep ANU-8 In Progress while Product Main records whether to revise the design or cancel the change. Do not start production children automatically.
  • Unsupported contract/runtime/package versions fail before editor load, preview, Unity startup, or capture.
  • Missing assets, player readiness failures, or deterministic-seek failures stop the render with structured evidence; they never produce an apparently successful partial video.
  • CMS revision conflicts preserve both the persisted revision and the user's unsaved work until an explicit resolution.
  • Upstream synchronization failures remain isolated to a sync branch and cannot overwrite downstream refs or published artifacts.

Security and privacy

  • Disable or omit upstream update checks and collaboration networking in Anuva production modes.
  • Validate iframe origins, player messages, schemas, versions, and asset identities.
  • Sanitize text and SVG/HTML-compatible fields; documents and AI output cannot carry executable scripts.
  • Do not store CMS access tokens, signed credentials, or secrets in documents, player artifacts, render packages, Markdown, Linear, or PR evidence.
  • Keep the private downstream and its packages restricted to approved Shoonya organization access.
  • Retain all upstream and third-party notices in every distributed runtime.

Documentation impact

  • Product Main updates this change folder, ADR, product architecture, repository registry, capability map, Linear workflow labels, CLI configuration guidance, and final completion review.
  • anuva-bento documents bootstrap provenance, architecture, contracts, editor, player, templates, packaging, releases, upstream synchronization, security, and its implementation plan/log/report.
  • CMS documents PresentationConfig v2, persistence, generation, editor host, AI operations, preview, assets, render packaging, and implementation evidence.
  • Unity documents three-player lifecycle, bridge API, timing, virtual surfaces, readiness, assets, performance, and implementation evidence.
  • Python documents package validation/staging, version handling, lifecycle, failures, and implementation evidence.

Approval record

  • Plan reviewed by: Girish
  • Approved at: 2026-07-24 06:06 UTC
  • Approval notes: Approved as written, including the private downstream, staged repository bootstrap, feasibility spike and explicit go/no-go gate, three-surface aggregate, shared exact-version player, repository issue split, and clean development-phase Reveal cutover. Detailed persistence, packaging, external-clock, asset, and numeric performance choices remain governed by the approved spike and contract invariants.