Skip to content

ADR 0001: Adopt a Private Anuva Bento Downstream

  • Status: Accepted
  • Date: 2026-07-24
  • Change ID: 2026-07-24-anuva-bento-integration
  • Source Linear issue: ANU-8

Context

Anuva needs structured slide authoring, semantic AI edits, reusable templates, three coordinated presentation surfaces, and deterministic playback shared by Web and Unity. The current Anuva path generates Reveal-compatible markup and does not provide one durable structured document or renderer contract.

Bento provides a plain JSON bento/slides model, reusable layouts, stable element identities, one shared renderer, offline-capable artifacts, and an MIT-licensed codebase. Its public product is a self-contained editor/viewer file and includes optional update and collaboration systems that Anuva must not enable in production.

Shoonya-specific editor, player, templates, contracts, and integrations must remain private. A normal public fork does not meet that requirement. The integration also introduces enough long-lived cross-repository behavior to require an explicit ownership and upstream-maintenance decision.

Decision

Create Shoonya-Game-Technologies/anuva-bento as an independent private downstream of https://github.com/nyblnet/bento.git.

  • Seed it from a recorded upstream release tag and commit while preserving Git ancestry, license, copyright, and third-party notices.
  • Use origin for the private Anuva repository and upstream for the public Bento source.
  • Protect main; deliver Anuva changes through reviewed PRs.
  • Merge selected tagged upstream releases through short-lived sync/bento-vX.Y.Z branches. Never auto-merge or mirror-push after downstream work exists.
  • Keep upstream-compatible core changes narrow and place Anuva contracts, adapters, editor/player entries, templates, and packaging behind explicit downstream boundaries.
  • Disable or omit public update and collaboration behavior in Anuva production editor/player builds.
  • Publish exact-version private contract and runtime artifacts for CMS and Unity.
  • Make Product Main the owner of product invariants and compatibility policy; make anuva-bento the owner of executable schemas, validators, editor/player builds, templates, and release artifacts.
  • Treat full adoption as conditional on a Product Main-approved feasibility spike.

The planning baseline observed on 2026-07-24 is Bento Slides v1.0.7. Bootstrap must independently record and verify the exact selected tag and commit rather than assuming that observation remains current.

Alternatives considered

Continue direct Reveal-oriented Anuva generation

Rejected because it keeps authoring coupled to generated markup and does not provide structured semantic editing, content-preserving templates, or one shared versioned Web/Unity renderer.

Consume public Bento directly without a downstream

Rejected because Anuva requires private product-specific contracts, host adapters, templates, editor/player variants, offline controls, and a reviewed release cadence.

Create a public GitHub fork

Rejected because Shoonya's Anuva-specific modifications must remain private.

Copy Bento source without preserving ancestry

Rejected because it makes upstream provenance, review, license tracking, and repeatable release synchronization harder.

Build a new slide editor and renderer from scratch

Deferred because it duplicates a substantial structured editor/rendering base before testing whether Bento can satisfy Anuva's deterministic and maintenance requirements. It remains a fallback if the spike fails.

Consequences

Positive

  • Anuva gains a structured document model and reusable renderer foundation.
  • Web and Unity can pin one runtime implementation and compatibility contract.
  • Private Anuva behavior stays within Shoonya's organization.
  • Preserved ancestry and tagged sync branches make upstream review auditable.
  • The feasibility gate limits sunk cost before a broad cross-repository cutover.

Costs and risks

  • Shoonya becomes responsible for downstream maintenance, security review, releases, notices, and conflict resolution.
  • Three concurrent Vuplex players and deterministic external timing may require non-trivial Bento changes.
  • A new repository expands Linear, CLI, docs-preview, publishing, and ownership configuration.
  • Upstream internal changes may create recurring merge conflicts.
  • CMS, Unity, and Python must coordinate exact contract/runtime/package versions.

Repository impact

  • Product Main registers the repository, extends the allowlisted harness, owns this ADR and product contracts, and coordinates staged Linear work.
  • anuva-bento owns downstream source, contract/editor/player/template artifacts, upstream sync, release, security, license, and implementation documentation.
  • CMS consumes the artifacts for persistence, AI authoring, compilation, Web preview, and packaging.
  • Unity consumes the player/package for deterministic three-surface playback.
  • Python validates and stages the immutable package and preserves failure semantics.

Compatibility and migration

The initial downstream preserves the selected upstream ancestry. Anuva artifact versions use an explicit downstream version and record their upstream base. Consumers pin exact compatible versions.

The product migration is a clean development cutover from Anuva's direct Reveal-oriented contracts to the accepted Bento contract. Bento may continue to use Reveal.js internally; that is not an Anuva integration contract.

Verification

  • Confirm private visibility, ancestry, selected tag/SHA, remotes, protected branch, ownership, and required notices.
  • Build and test the unmodified selected upstream baseline.
  • Rehearse one tagged upstream sync without mirror-overwriting downstream refs.
  • Prove the spike's Web/Vuplex parity, three-player performance, deterministic seek, transparency, assets, offline network behavior, and template preservation criteria.
  • Verify exact-version artifacts and consumer rejection of unsupported versions.
  • Record an explicit Product Main go/no-go decision before production work.

Follow-up Linear issues and PRs

The approved issue split and dependencies are maintained in ANU-8 Implementation Issues.