Anuva Bento Integration

Document status

Status: Ideation reference
Last updated: 2026-07-24
Intended use: source material for Product Main change intake and repository-scoped Linear implementation issues
Approval state: not yet an approved Change Brief, ADR, repository handoff, or implementation authorization

This document consolidates the requirements, recommendations, constraints, and candidate work breakdown identified while exploring Bento as the next Anuva slide platform. It is intentionally detailed so that future Linear issues can be scoped without relying on Codex conversation history.

Executive recommendation

Adopt a private Anuva downstream of Bento as the structured slide-authoring and playback foundation for Anuva.

The target product is not merely a customized copy of the Bento Editor. It is an Anuva slide platform with:

An AI Assistant-powered Bento Editor embedded in the Anuva Web App.
Opinionated, versioned Anuva template families.
Three coordinated but independently editable presentation surfaces: Main Screen, Companion Screen, and Emphasis Projection.
A shared, versioned Anuva Bento Player used by both Web scene preview and Unity Vuplex WebViews.
A structured multi-surface presentation contract and one authoritative playback timeline.
A controlled downstream release process for receiving upstream Bento updates without losing Anuva modifications.

The existing Reveal-specific Anuva contracts, markup generation, validation, Web preview assumptions, and Unity Reveal assets should be removed as part of a clean development-phase cutover. Existing presentation data is disposable, so no legacy data migration or dual-format compatibility layer is required.

Important terminology

Term	Meaning
Bento	The public `nyblnet/bento` upstream project.
Anuva Bento	Shoonya's private downstream source and Anuva-specific platform built from Bento.
Bento document	A structured `bento/slides` JSON document containing slides, elements, layouts, theme data, assets, and presentation behavior.
Anuva Bento presentation	A composite Anuva contract containing the three surface-specific Bento documents and their shared timeline.
Surface	One Unity presentation output: Main Screen, Companion Screen, or Emphasis Projection.
Surface item	A slide or transient event associated with a surface and scene.
Template family	One visual identity with shared tokens and surface-specific layout packs.
Player	The read-only Anuva Bento browser runtime embedded in Web preview or a Unity Vuplex WebView.
Editor	The modified Bento authoring runtime embedded in the Anuva Web App.
Upstream	`https://github.com/nyblnet/bento.git`.
Downstream	The proposed private `Shoonya-Game-Technologies/anuva-bento` repository.

Product motivation

The current CMS slide path produces Reveal-compatible HTML markup. This creates several limitations:

Slide content and design are coupled inside generated HTML.
Editing requires manipulating rendered markup rather than structured presentation data.
Templates cannot be changed reliably while retaining semantic content.
AI generation must reason about low-level HTML rather than slide intent, content roles, layout constraints, and reusable visual systems.
Web preview and Unity playback do not yet share one clear, versioned renderer contract.
The CMS currently models one Reveal surface while Unity experimentation has established three distinct screen surfaces.

Bento provides a stronger base because the document is structured data. Its current model includes:

A deck-wide theme.
Slide-shaped reusable layouts.
Semantic element roles such as title, subtitle, body, and kicker.
Layout placeholders.
Layout reapplication that matches content first by element identity and then by semantic role.
Preservation of populated text and user-created extra elements when layouts change.
Stable element identities used for morph continuity.
A shared renderer for editor canvas, thumbnails, and presentation mode.

The desired Anuva outcome is that users work with content, communication intent, templates, and AI-assisted transformations instead of manually adjusting every low-level slide property.

Clarification: replacement of the current Reveal slide system

Bento currently uses Reveal.js internally for presentation navigation. Adopting Bento therefore replaces Anuva's direct Reveal-specific slide model, generated Reveal HTML, and custom Reveal player integration, but does not automatically remove Reveal.js from Bento's internal dependency tree.

This is acceptable for the proposed direction. The product goal is to replace Anuva's raw Reveal authoring and integration surface with Bento's structured model and renderer. Removing Reveal.js from inside Bento would be a separate downstream or upstream engineering decision and is not required for initial adoption.

Goals

Replace generated Reveal slide markup with structured Anuva Bento documents.
Embed a modified Bento Editor in the Anuva Web App.
Launch slide editing from the existing Scene Editor while retaining full-deck context.
Provide an AI Assistant that edits slides through validated, high-level operations.
Support versioned Anuva template families that change visual identity while preserving semantic slide content.
Represent Main Screen, Companion Screen, and Emphasis Projection as first-class independently editable surfaces.
Use the same renderer and player version for Web preview and Unity output.
Give Unity authoritative control over scene selection, surface items, fragments, events, and presentation time.
Keep all production playback offline and deterministic.
Preserve the ability to receive and review upstream Bento changes.
Keep Anuva modifications private under the Shoonya GitHub organization.
Establish contracts that are explicit enough for independent repository implementation and cross-repository acceptance review.

Non-goals

Migrating existing Reveal presentation data.
Maintaining simultaneous Reveal and Bento production formats after cutover.
Preserving the current development database.
Publishing Shoonya's Anuva-specific Bento modifications publicly.
Automatically merging or deploying upstream Bento releases.
Allowing a production player to self-update from bento.page.
Adopting Bento's public collaboration relay as part of the initial Anuva integration.
Replacing Payload, Mastra, the Python render orchestrator, Unity, Vuplex, or the existing video capture stack.
Finalizing the detailed visual design of the Web slide editor in this ideation document.
Treating every scene as exactly one slide on every surface.
Making all three surfaces show content at all times.

Existing Anuva evidence

CMS

The current anuvax-cms implementation and documentation use Reveal-specific concepts including:

screen.reveal.revealSlideMarkup.
RevealSceneModel.
Reveal slide planning and <section> markup generation.
Fragment-count and section-wrapper validation.
Reveal-specific prompt and workflow terminology.

Relevant implementation paths include:

anuvax-cms/src/lib/presentation-config/schema.ts
anuvax-cms/src/mastra/schemas/slide.schema.ts
anuvax-cms/src/mastra/tools/compiler/index.ts
anuvax-cms/src/mastra/tools/presentation/index.ts
anuvax-cms/src/mastra/tools/validation/index.ts
anuvax-cms/src/lib/anuva/contracts-v1.ts
anuvax-cms/src/lib/anuva/deterministic-tools.ts
anuvax-cms/src/lib/anuva/orchestration-service.ts

The CMS package itself does not currently depend directly on Reveal.js. It generates Reveal-compatible data that is consumed elsewhere. The change is therefore a product contract and renderer migration, not a simple dependency replacement.

Unity

Unity experimentation already contains artifacts for three virtual screen surfaces:

Surface	Existing role
Main Screen	Primary presentation content and multi-slide scene sequences.
Companion Screen	Supporting context and independently sequenced content.
Emphasis Projection	Transient emphasis events, commonly with transparent or projection-specific presentation.

Relevant Unity paths include:

anuva-unity-video-creator/docs/core/VirtualScreensAndMedia.md
anuva-unity-video-creator/Assets/Anuva/Scripts/VirtualScreens/Scripts/AnuvaScreenBridgeHost.cs
anuva-unity-video-creator/Assets/Anuva/Scripts/VirtualScreens/Scripts/AnuvaVirtualScreensPlaybackController.cs
anuva-unity-video-creator/Assets/Anuva/Scripts/VirtualScreens/Editor/AnuvaScreenHtmlBuilder.cs
anuva-unity-video-creator/Assets/Anuva/Scripts/VirtualScreens/Scripts/AnuvaScreenTemplateRegistry.cs
anuva-unity-video-creator/Assets/StreamingAssets/PresentationConfig.json

The Unity experiment already demonstrates several useful domain concepts:

A surfaces object with Main, Companion, and Emphasis content.
Slide sequences for Main and Companion.
Event sequences for Emphasis.
A presentation-wide playback order.
Word/relative/absolute timing concepts.
Three bridge hosts mapped to three Vuplex WebViews.
Show, hide, slide, fragment, and reset commands.

These concepts should be promoted into Product Main and CMS-owned durable contracts. The existing editor-only regex HTML builder and Unity-local duplicate configuration classes should not become the production contract.

Private downstream repository

Repository choice

Create:

Shoonya-Game-Technologies/anuva-bento

with private visibility.

A GitHub fork of a public repository cannot be private. The Anuva repository must therefore be an independent private downstream that preserves Bento's Git history but is not part of GitHub's public fork network.

The repository can be seeded through GitHub Importer. A one-time bare or mirror copy is an acceptable fallback. Mirror pushes must not be used after Anuva changes exist because they are designed to overwrite downstream refs to match the source.

Remotes

Every working clone should use:

origin    git@github.com:Shoonya-Game-Technologies/anuva-bento.git
upstream  https://github.com/nyblnet/bento.git

origin is the private Anuva delivery repository. upstream is read-only in normal operation.

Branch policy

main: reviewed Anuva Bento trunk and default branch.
sync/bento-vX.Y.Z: one short-lived branch per upstream release merge.
feature/...: Anuva-specific changes.
fix/...: Anuva-specific fixes.

Protect main, require pull requests, and avoid squashing upstream history. Preserving ancestry reduces repeated conflict resolution during later merges.

Licensing

Bento is MIT-licensed. Anuva may modify it, keep the modifications private, and use it commercially. The downstream and every distributed runtime must retain:

Bento's MIT license.
Relevant copyright notices.
Bundled third-party license notices.

Anuva build changes must not strip the notices that Bento intentionally embeds in its self-contained files.

Downstream code structure

Keep the upstream modification surface narrow. Prefer adding Anuva adapters, contracts, build entries, and packaging around shared Bento internals rather than scattering Shoonya-specific behavior through every upstream file.

A candidate organization is:

anuva-bento/
  slides/                         # Upstream Bento application source
  anuva/
    contract/                     # Anuva extensions and validation
    editor-host/                  # CMS persistence and host bridge
    player/                       # Read-only player entry
    templates/                    # Anuva template families
    build/                        # Artifact packaging
  docs/
    anuva/                        # Downstream decisions and integration docs

The exact directory layout can change during the repository bootstrap spike, but the following boundaries should remain explicit:

Upstream-compatible core.
Anuva contract extensions.
Editor host integration.
Player host integration.
Template assets.
Release and update metadata.

Required downstream artifacts

Anuva Bento Contract package

Publish a private scoped npm package, for example:

@shoonya-game-technologies/anuva-bento-contract

It should contain:

Bento document types required by consumers.
Anuva composite presentation types.
Anuva surface and timeline types.
Runtime schemas and validation.
Template family schemas.
Document and template transformation helpers that do not require a browser.
Supported format and runtime version metadata.
Stable error types for CMS and Unity handoff validation.

The package must avoid editor DOM dependencies so it can be consumed by server-side CMS compilation and tests.

Anuva Bento Editor

The editor build should contain:

Bento's editor and shared renderer.
Anuva surface navigation.
Anuva template picker and template application commands.
AI Assistant host integration.
CMS load, save, autosave, revision, and conflict adapters.
Anuva media-library adapters.
Host messaging with explicit origin and schema validation.
Editor-only diagnostics.

It should not rely on Bento's local-file save loop as the primary persistence mechanism inside Anuva.

Anuva Bento Player

The player build should contain:

The shared Bento renderer and presentation behavior.
No editor chrome.
No local file saving.
No upstream collaboration client.
No upstream update check.
No unexpected network access.
A versioned control API.
A deterministic externally controlled time mode.
Surface-specific initialization and transparent-background support.
Ready, asset-loaded, state-changed, animation-complete, and error events.

Distribution

The private contract package should be published through GitHub Packages or another approved private registry. anuvax-cms should pin an exact version and commit its lockfile.

The player may be distributed as:

A versioned package containing static runtime assets.
A GitHub release artifact.
Both, if CMS bundling and Unity packaging benefit from different delivery mechanisms.

Web and Unity must record and use the same runtime version for a given presentation/render package.

Composite presentation model

Anuva should persist one composite presentation containing three Bento documents rather than one Bento document per scene.

interface AnuvaBentoPresentation {
  format: 'anuva/bento-presentation'
  version: 1
  runtimeVersion: string

  presentationId: string
  revision: number

  template: {
    familyId: string
    version: number
  }

  surfaces: {
    main: AnuvaBentoSurface
    companion: AnuvaBentoSurface
    emphasis: AnuvaBentoSurface
  }

  timeline: SurfaceTimelineAction[]
}

interface AnuvaBentoSurface {
  surface: 'main' | 'companion' | 'emphasis'
  document: AnuvaBentoDoc
  viewport: {
    width: number
    height: number
    transparent: boolean
    safeArea?: {
      x: number
      y: number
      width: number
      height: number
    }
  }
}

The surface documents are independent because they may have:

Different dimensions or safe areas.
Different backgrounds and transparency requirements.
Different slide counts.
Different persistence behavior across scenes.
Different layout catalogs.
Different visual-density rules.

They are grouped into one composite presentation because they share:

Product identity.
Template family.
Narrative.
Scenes.
Timing authority.
Cross-surface coordination.
Release/runtime version.

Anuva document metadata

Use Bento documents as the canonical editable slide representation. Add explicit Anuva metadata rather than maintaining a second equal slide document that must be synchronized after every user and AI edit.

interface AnuvaBentoDoc extends BentoDoc {
  anuva: {
    presentationId: string
    surface: 'main' | 'companion' | 'emphasis'
    templateFamilyId: string
    templateFamilyVersion: number
    revision: number
  }
}

Each surface item should include semantic lineage:

interface AnuvaSlideMetadata {
  sceneId: string
  surfaceItemId: string
  slideIntent: string
  layoutKey: string
  templateFamilyId: string
  templateFamilyVersion: number
}

Important elements may include content bindings:

interface AnuvaElementMetadata {
  contentKey:
    | 'headline'
    | 'subtitle'
    | 'body'
    | 'metric'
    | 'visual'
    | 'caption'
    | 'source'
  generatedBy?: 'workflow' | 'assistant' | 'user'
}

These bindings make AI edits and template reapplication more reliable than depending only on element positions.

Scene-to-surface mapping

Do not enforce one scene to one slide. A scene maps to zero or more surface items on each surface.

Examples:

A scene may contain two sequential Main slides, one persistent Companion slide, and one short Emphasis event.
The Companion surface may intentionally hold content from the previous scene.
Emphasis may be empty for most scenes.
A surface may explicitly clear at a scene boundary.
Multiple surface changes may occur at different narrative beats within one scene.

The mapping should therefore identify:

sceneId.
surface.
surfaceItemId.
Item kind: persistent slide or transient event.
Start and end timing.
Hold/replace/clear behavior.
Fragment or state cues.

IDs must be stable and globally unambiguous within a presentation. A readable convention such as scene-03/main/2 may be used, but consumers must treat IDs as opaque values rather than parsing business meaning from them.

Surface responsibilities

Main Screen

Primary communication surface.
Supports dense explanatory layouts relative to the other surfaces.
Can advance through multiple slides during a scene.
Hosts diagrams, comparisons, timelines, processes, charts, and primary messaging.
Commonly persists until a replacement slide is activated.

Companion Screen

Supporting context rather than a duplicate of Main.
Hosts definitions, supporting metrics, examples, references, navigation context, or reinforcing visuals.
May hold one surface item across multiple Main Screen changes or scenes.
Should avoid demanding simultaneous detailed reading when Main is dense.

Emphasis Projection

Transient, sparse, and commonly transparent.
Product-facing concept is an Emphasis Event even if internally represented by a Bento slide/state.
Hosts a short phrase, number, icon, alert, visual flourish, or callout.
Requires explicit show and hide behavior.
Must not become mandatory for every scene.
Should support projection-specific safe areas, transparency, and visual constraints.

Authoritative surface timeline

The three documents must not run unrelated clocks. Persist one authoritative presentation timeline:

interface SurfaceTimelineAction {
  id: string
  sceneId: string
  surface: 'main' | 'companion' | 'emphasis'
  targetId: string
  action:
    | 'activate'
    | 'show'
    | 'hide'
    | 'showFragment'
    | 'hideFragment'
    | 'seek'
    | 'clear'
  at: {
    wordIndex?: number
    relativeSeconds?: number
    absoluteSeconds: number
  }
}

Authoring may begin with word-index or relative narrative anchors. Compilation must resolve them to authoritative absolute times after word timings and scene durations are available.

The timeline is responsible for cross-surface ordering. Bento documents remain responsible for visual content and renderer behavior.

Player runtime model

Three logical players

Unity should run three long-lived player instances:

Main player.
Companion player.
Emphasis player.

Each instance owns one Vuplex WebView and receives one surface document.

One shared runtime

All three instances should load the same versioned player implementation, for example:

anuva-bento-player.html?surface=main
anuva-bento-player.html?surface=companion
anuva-bento-player.html?surface=emphasis

Do not maintain three different player codebases. A render package may generate three self-contained HTML outputs for operational convenience, but they must be derived from the same runtime version and surface documents.

Load lifecycle

Load each player once per presentation rather than once per scene. Reloading a WebView per scene risks:

Flicker.
Asset reload delays.
Lost playback state.
Memory churn.
Timing variance.
Harder diagnostics.

Scene transitions should call the player control API.

Required player API

A candidate API is:

window.AnuvaBentoPlayer = {
  getApiVersion(),
  getRuntimeVersion(),
  loadDocument(document),
  activateScene(sceneId),
  activateItem(surfaceItemId),
  showFragment(fragmentId),
  hideFragment(fragmentId),
  showEvent(eventId),
  hideEvent(eventId),
  seek(absoluteSeconds),
  play(),
  pause(),
  reset(),
  resize(width, height),
  getState(),
  waitUntilReady()
}

Commands must be safe to repeat where practical. The bridge must reject unsupported API versions, malformed documents, unknown IDs, and commands issued before readiness with explicit errors rather than silent failure.

Required events

ready
documentLoaded
assetsReady
surfaceItemChanged
fragmentChanged
animationComplete
stateChanged
error

Web preview and Unity must use the same public API instead of reaching into Bento or Reveal internals.

Deterministic time

Unity's capture clock must be authoritative during video rendering. The player must support explicit seek/tick behavior instead of relying only on browser wall-clock timers.

The Unity spike must verify:

Frame-accurate animation seeking.
Behavior after backward and forward seeks.
Font and asset readiness before capture.
Pause/resume.
Transition completion.
Emphasis event show/hide.
Fragment state after a non-linear seek.
Consistent output between Web preview and Unity capture.

Unity integration

Replace the experimental bridge with a versioned Anuva Bento bridge while retaining the useful three-host and global-schedule concepts.

Unity responsibilities should be:

Load the render-job package and validate contract/runtime compatibility.
Initialize three Vuplex player instances.
Load the three surface documents.
Wait for all required surfaces and assets to report ready.
Drive the authoritative presentation clock.
Dispatch timeline commands.
Map player output to the correct Unity surface/RenderTexture.
Apply projection transparency and surface geometry.
Surface player errors in render diagnostics.
Stop or fail a render when required player state cannot be established.

Unity should not:

Recompile Bento documents.
Parse CMS JSON with regular expressions.
Own the template registry.
Generate presentation HTML from renderer markup.
Guess missing scene mappings.
Reach directly into Reveal APIs.
Download runtime updates during rendering.

Vuplex performance spike

Three Chromium-backed WebViews may have material GPU, CPU, and memory cost. The Unity issue must measure:

Startup latency.
Idle and active memory.
CPU/GPU load with one versus three players.
RenderTexture resolution cost.
Simultaneous animation cost.
Asset and font loading.
Transparent Emphasis rendering.
Stability during the full video capture path.

Three player instances remain the preferred initial architecture because each Unity surface requires independent output. If performance is unacceptable, an alternative rendering topology must be evaluated explicitly rather than hidden behind contract changes.

Web editor integration

Entry point

The existing Scene Editor should expose an Edit slides action.

Opening it should:

Load the full composite Anuva Bento presentation.
Focus the selected scene.
Select the last-used or default surface.
Show the surface items associated with that scene.
Preserve access to neighboring scenes and the full deck.

Full-deck context is required because:

Morphs depend on adjacent slides and stable element identities.
Template consistency is presentation-wide.
Companion content may persist across scenes.
The AI Assistant must avoid cross-scene and cross-surface repetition.

Surface selection

The first UI may use tabs:

[ Main Screen ] [ Companion Screen ] [ Emphasis Projection ]

The underlying contract must expose surface selection without depending on tabs so that later interfaces can introduce a composite three-surface view.

Composite preview

The model must support a future view that displays all three surfaces simultaneously. This is important for judging:

Competing visual attention.
Repeated content.
Surface timing.
Template cohesion.
Emphasis placement.

The detailed UI can be designed separately, but the editor bridge and persisted model must not prevent this view.

Hosting

An iframe is a reasonable initial isolation boundary for the modified editor. The host/editor protocol must include:

Explicit schema and protocol version.
Allowed message origins.
Runtime and document version negotiation.
Load/save acknowledgements.
Dirty state.
Revision ID.
Active scene and surface.
Selection changes.
Template commands.
AI command requests and results.
Structured errors.

Do not expose arbitrary script execution across the iframe boundary.

Persistence

Replace Bento's primary local-file save behavior with CMS persistence:

Load through authenticated CMS APIs.
Autosave document changes.
Use revision numbers or optimistic concurrency.
Detect stale edits rather than silently overwriting.
Maintain undo/redo inside the editor.
Record save failures visibly.
Keep media credentials out of persisted documents.

Version history and collaboration are separate product decisions. They should not be inferred from Bento's upstream collaboration feature during the initial integration.

Template system

Template family

An Anuva template family represents one coordinated visual identity:

interface AnuvaTemplateFamily {
  id: string
  version: number
  name: string
  description?: string
  thumbnailUrl: string

  sharedTokens: {
    colors: Record<string, string>
    fonts: Record<string, string>
    spacing: Record<string, number>
  }

  surfaces: {
    main: SurfaceTemplatePack
    companion: SurfaceTemplatePack
    emphasis: SurfaceTemplatePack
  }
}

Shared tokens create visual cohesion. Surface packs provide appropriate dimensions, safe areas, and layouts.

Surface-specific layout examples

Main:

Title.
Section divider.
Key message.
Text with image.
Two-column comparison.
Metric grid.
Timeline.
Process.
Chart.
Closing/CTA.

Companion:

Definition card.
Supporting statistic.
Source/reference.
Related examples.
Context/navigation.
Secondary visual.

Emphasis:

Key number.
Keyword.
Short quote.
Icon callout.
Alert.
Projection flourish.

Template operations

The product should distinguish:

Change theme: update shared colors, fonts, charts, and tokens without rearranging content.
Change layout: reflow one surface item into another compatible layout.
Change template family: remap all three surface decks into a new coordinated family.
Customize item: allow user changes after template application.

Applying a new family should:

Snapshot the previous state for undo.
Map each item by surface, semantic intent, and layout role.
Preserve semantic content and links.
Preserve user-created extras unless the user chooses a content-only reset.
Report items with no safe layout match.
Preview before committing where practical.

Template lineage and overrides

Persist:

Template family ID and version.
Surface layout key.
Semantic content bindings.
User override information where required.

This allows later template updates to distinguish template-owned properties from user-customized properties. The exact override representation requires an ADR or implementation spike; it must not rely on a silent destructive rewrite.

AI Assistant

Product role

The assistant should let users author and revise slides through communication goals rather than manual low-level editing.

Example requests:

"Make the Main Screen less text-heavy."
"Move this statistic to the Emphasis Projection."
"Keep the Companion Screen unchanged for this scene."
"Use the Companion Screen for the supporting examples."
"Apply the Technology Dark template to all screens."
"Make the three surfaces feel more coordinated."
"Turn this explanation into a process diagram."
"Shorten the slide without changing the narration."
"Remove unnecessary emphasis events."

Structured tools

The model should call high-level validated operations rather than returning raw HTML or an unrestricted document replacement. Candidate tools include:

rewriteSurfaceItem
shortenSurfaceItem
changeSlideIntent
applyLayout
applyTemplateFamily
replaceVisual
createChart
moveContentBetweenSurfaces
addEmphasisEvent
removeEmphasisEvent
holdSurfaceAcrossScene
clearSurfaceAtScene
regenerateSceneSurfaces
restylePresentation
validateSurfaceCoordination

Deterministic code should apply, validate, and record the changes.

Assistant context

Provide only the context required for the requested operation:

Current surface item.
Neighboring item summaries.
Scene narration and timing anchors.
Deck outline.
Other active surfaces for the scene.
Available template layouts and constraints.
Relevant media references.

The assistant must inspect all three surfaces before operations that could cause duplication or competing attention.

Safety and editability

Do not allow generated arbitrary JavaScript.
Keep text within Bento's supported sanitized representation.
Validate every change against the contract.
Preserve undo/redo.
Present clear before/after changes.
Detect revision conflicts between AI changes, autosave, and user edits.
Record whether content was created by workflow, assistant, or user where this provenance helps later transformations.

Narrative analysis and screen choreography

Required conceptual change

The current slide analysis is insufficient because it plans one Reveal-oriented slide stream. The new workflow must first decide how the story uses three surfaces.

Introduce a multi-surface screen choreography phase before template selection and Bento compilation.

Analysis responsibilities

For each scene, decide:

Primary communication objective.
Main Screen role.
Companion Screen role.
Whether Emphasis is justified.
Whether each surface replaces, continues, holds, or clears prior content.
How many surface items are required.
Which narrative beats activate changes.
Which surface owns audience attention at each beat.
How the scene continues or resets visual ideas from neighboring scenes.
How to avoid repeated headlines and redundant content.

Candidate semantic output

interface MultiSurfaceScenePlan {
  sceneId: string
  communicationIntent: string

  main: PlannedSurfaceTrack
  companion: PlannedSurfaceTrack
  emphasis: PlannedEmphasisTrack

  coordination: {
    attentionFocus: 'main' | 'companion' | 'emphasis'
    avoidDuplication: string[]
    visualRhythm: string
  }
}

interface PlannedSurfaceTrack {
  strategy: 'replace' | 'continue' | 'hold' | 'clear'
  items: PlannedSurfaceItem[]
}

interface PlannedEmphasisTrack {
  strategy: 'events' | 'none'
  items: PlannedEmphasisEvent[]
}

This output is semantic and template-neutral. A later deterministic or constrained AI-assisted step selects layouts and builds Bento documents.

Choreography rules

Main and Companion must have distinct roles.
Do not repeat one headline across all surfaces.
Emphasis is optional and should be sparse.
At most one surface should normally demand dense reading at a time.
A surface may intentionally retain content across scene boundaries.
A surface may explicitly be blank.
Three simultaneous changes require an intentional reason.
Authoring timing should use narrative beats or word anchors before absolute audio timing exists.
Camera and directing decisions may use the attention-focus output.

Revised presentation compilation

The proposed pipeline is:

Product input and sources
  -> narrative generation
  -> deck-level narrative analysis
  -> multi-surface choreography plan
  -> template/layout selection
  -> compile Main Bento document
  -> compile Companion Bento document
  -> compile Emphasis Bento document
  -> validate individual surface documents
  -> generate or resolve audio and word timing
  -> compile authoritative surface timeline
  -> validate cross-surface coordination and timing
  -> persist PresentationConfig v2
  -> build render-job package

Individual document validation

Supported Bento format and version.
Non-empty valid document.
Stable unique IDs.
Known scene mappings.
Valid template and layout references.
Valid semantic bindings.
Supported element and animation types.
Resolvable media and fonts.
Surface viewport and transparency compliance.

Cross-surface validation

No unknown scene or surface item IDs.
No invalid or overlapping Emphasis intervals.
No event extending outside its permitted scene or presentation interval.
Required show events have corresponding hide/clear behavior.
Held content has an explicit valid predecessor.
No unsupported layout for a target surface.
No unresolved timeline anchor.
No unintentional dense content on multiple surfaces simultaneously.
No unintentional duplicate messaging.
Runtime version is supported by all consumers.

PresentationConfig v2

Use a new contract version even though the database will be recreated. The version coordinates CMS, Python, and Unity behavior and communicates that the contract is intentionally incompatible with v1.

A candidate shape is:

interface PresentationConfigV2 {
  contractVersion: 'v2'
  presentationId: string

  slidePresentation: AnuvaBentoPresentation

  scenes: Array<{
    sceneId: string
    index: number
    timing: SceneTiming
    voiceover: SceneVoiceover
    screen: {
      mainItemIds: string[]
      companionItemIds: string[]
      emphasisEventIds: string[]
    }
    directing?: SceneDirecting
  }>

  studio: StudioConfiguration
  audio?: PresentationAudio
  render?: PresentationRenderSettings
}

The detailed placement of the timeline and surface mappings should be finalized in Product Main planning. Requirements are:

No repeated full Bento document per scene.
One authoritative timeline.
Explicit runtime/document versions.
Explicit scene-to-surface-item references.
Python can package and pass the contract without reconstructing documents.
Unity can validate and execute it without regex parsing.

CMS cutover

The CMS implementation should remove:

screen.reveal.
revealSlideMarkup.
RevealSceneModel.
Reveal <section> builders.
Reveal section-wrapper validators.
Reveal fragment naming where it leaks into product contracts.
Reveal-specific prompts and documentation.
Legacy database fields and generated Payload types.

Replace them with:

Composite Anuva Bento presentation persistence.
Surface-specific document revisions.
Multi-surface choreography output.
Template-aware Bento compilation.
Surface timeline compilation.
Bento validation.
Editor load/save endpoints.
Player preview endpoints or assets.
AI Assistant tools.

Because the current data is disposable:

Change schemas and migrations cleanly.
Recreate the development database.
Regenerate Payload types.
Seed representative three-surface presentation fixtures.
Do not add fallback parsing for old Reveal data.

Code rollback remains possible through Git and pinned package versions even without persisted data compatibility.

Python server impact

The expected Python role is narrow unless render-job packaging requires more:

Accept and validate the v2 render-job envelope.
Preserve the three surface documents and authoritative timeline.
Stage the exact player runtime version and surface assets required by Unity.
Avoid transforming Bento content.
Report contract/runtime incompatibility before invoking Unity.
Preserve checksums or version metadata needed for deterministic handoff.

The planning phase must confirm whether these behaviors belong in CMS package assembly or Python orchestration. If Python is a transparent transport, its Linear issue can remain small but must still verify compatibility.

Asset strategy

Bento supports embedded assets, while Anuva already has managed media storage. The implementation plan must choose when assets are:

Referenced through authenticated or signed URLs.
Copied into a render-job package.
Embedded into a Bento document.
Cached by Web preview.
Loaded from Unity StreamingAssets or a job-local directory.

Requirements:

Preview and Unity render must resolve the same content.
Expiring URLs must not fail during long-running or retried rendering.
Documents must not contain private credentials.
CORS and local-file access must be verified for Vuplex.
The player must not begin capture before required fonts and assets are ready.
Large media should not make routine CMS document revisions unnecessarily expensive.
Render packages should record checksums or immutable asset identities where deterministic reproduction requires them.

Security and network behavior

Disable Bento's upstream self-update channel in Anuva editor and player production modes.
Disable or omit upstream live-collaboration networking initially.
Do not contact bento.page or an external relay during preview/render.
Pin and verify the player runtime version.
Validate iframe message origins and schemas.
Sanitize all text and SVG/HTML-compatible fields.
Do not allow AI output to inject scripts.
Do not embed CMS access tokens in Bento documents or Unity artifacts.
Retain all required open-source notices.
Apply a Content Security Policy appropriate to the final asset strategy.

If Anuva later needs collaborative editing or a downstream update channel, that requires a separate security and product decision.

Upstream synchronization

Update policy

Prefer tagged upstream releases over arbitrary main commits.
Never auto-merge upstream updates.
Never update production documents directly from Bento's public release manifest.
Review dependencies, network behavior, file-format changes, license notices, and build changes for every update.

Recommended procedure

git fetch upstream --tags

git switch main
git pull --ff-only origin main

git switch -c sync/bento-v1.0.8
git rev-parse v1.0.8
git merge --no-ff v1.0.8

Then:

Record upstream tag and commit SHA.
Resolve conflicts without discarding Anuva adapters.
Run upstream typecheck/build and CRDT tests where applicable.
Run Anuva contract, editor, player, template, and packaging verification.
Review new network endpoints and dependencies.
Review license and third-party notice changes.
Verify Anuva editor and offline player behavior.
Bump the downstream version, for example 1.0.8-anuva.1.
Update the downstream changelog and upstream-base record.
Push the sync branch and open a PR into protected main.
Publish downstream artifacts only after PR approval and successful checks.
Update CMS and Unity through explicit exact-version dependency PRs.

Versioning

A candidate convention is:

1.0.8-anuva.1: first Anuva downstream release based on Bento 1.0.8.
1.0.8-anuva.2: second Anuva-only release on the same upstream base.
1.0.9-anuva.1: first downstream release after merging upstream 1.0.9.

Consumers must pin exact downstream versions.

Candidate repository workstreams

These are issue candidates, not final issue boundaries. Product planning should merge or split them based on dependencies and implementation risk.

1. Product Main: approve Anuva Bento architecture

Scope:

Convert this ideation into an approved Change Brief.
Decide repository creation and ownership.
Approve composite three-surface model.
Approve contract/versioning boundaries.
Create a product ADR for Bento adoption and private downstream maintenance.
Create repository-scoped implementation issues.

Dependencies:

Product decision to proceed with the technical spike.

Acceptance:

Approved product outcome and non-goals.
Approved repository impact.
Explicit spike go/no-go criteria.
Approved issue dependency order.

Documentation:

Product Main Change Brief, Repository Impact, ADR, Implementation Issues, and progress records.

2. New `anuva-bento`: private downstream bootstrap

Scope:

Create/import the private repository.
Preserve upstream Git history.
Configure origin and upstream.
Establish branch protection and ownership.
Retain license and third-party notices.
Document upstream synchronization.
Prove the unmodified upstream build.

Dependencies:

Product Main approval.
Shoonya organization permission to create a private repository.

Acceptance:

Private repository exists under the correct organization.
Upstream tag and SHA are recorded.
Upstream Bento builds and tests pass.
An update rehearsal demonstrates a non-destructive sync branch and PR.

Documentation:

Downstream README, architecture, release, and upstream-update documentation.
Product Main repository registry update.

3. `anuva-bento`: contract, editor, and player technical spike

Scope:

Define the composite presentation and surface schemas.
Extract or expose reusable renderer/model boundaries.
Build one editor host and one read-only player entry.
Implement a minimal versioned host/player API.
Demonstrate one document in Web and Vuplex.
Disable upstream update and collaboration networking.

Dependencies:

Downstream bootstrap.

Acceptance:

Same sample document renders in editor, Web player, and one Unity WebView.
Player works offline.
API reports readiness and structured errors.
Runtime/document versions are queryable.
Spike documents source changes required to maintain the downstream.

Documentation:

Downstream architecture and integration notes.
Spike results synchronized to Product Main.

4. `anuva-bento`: template-family and three-surface support

Scope:

Define template-family schema.
Define Main, Companion, and Emphasis packs.
Add Anuva metadata and semantic content bindings.
Implement theme, layout, and family application.
Support independent surface documents.
Provide representative templates and fixtures.

Dependencies:

Contract/editor/player spike.

Acceptance:

One family styles all three surfaces coherently.
User can edit each surface independently.
Switching families preserves semantic content.
Unmatched layouts produce explicit warnings.
Undo restores the pre-template state.

Documentation:

Template authoring guide.
Schema/versioning guide.
Example family documentation.

5. `anuvax-cms`: PresentationConfig v2 and multi-surface compilation

Scope:

Replace Reveal contracts.
Add multi-surface choreography schemas.
Update narrative analysis.
Compile three Bento documents.
Resolve one authoritative timeline.
Persist composite presentations.
Recreate development database and fixtures.
Build render-job packages.

Dependencies:

Stable Anuva Bento contract package.
Product Main contract approval.

Acceptance:

No Reveal markup remains in the active generation path.
Representative narratives produce complementary Main, Companion, and Emphasis outputs.
Surface and cross-surface validation passes.
Absolute timing resolves from authoritative narration timing.
Fresh database and seed path produce valid v2 presentations.

Documentation:

CMS PresentationConfig, workflow, agents/tools, persistence, and render-job documentation.
Implementation plan/log/report.

6. `anuvax-cms`: embedded editor, preview, and AI Assistant

Scope:

Launch editor from Scene Editor.
Load full presentation and focus a scene/surface.
Add surface navigation.
Implement authenticated load/save/autosave and revision conflict behavior.
Embed the same player for scene preview.
Add structured AI Assistant tools.
Integrate templates and media.

Dependencies:

Anuva Bento editor/player artifacts.
CMS v2 persistence.

Acceptance:

User can edit all three surfaces for a scene.
Changes persist and preview without regenerating raw HTML.
Template application affects the intended surface scope.
AI operations are validated, undoable, and surface-aware.
Web preview and saved document use the same player/runtime version.

Documentation:

User workflow.
Editor host protocol.
AI tool contracts.
Failure and recovery behavior.

7. `anuva-unity-video-creator`: three-player Vuplex integration

Scope:

Replace generated Reveal/regex HTML path.
Initialize three long-lived Anuva Bento players.
Load surface documents from the render package.
Drive the authoritative timeline.
Add deterministic seek/tick support.
Map outputs to Main, Companion, and Emphasis surfaces.
Remove direct Reveal bridge assumptions.
Measure three-WebView performance.

Dependencies:

Player artifact and API.
PresentationConfig v2 fixture.
Render package layout.

Acceptance:

Three surfaces render simultaneously from one composite presentation.
Scene seek restores the correct state on all surfaces.
Emphasis show/hide and transparency work.
Required assets are ready before capture.
Player failure stops or clearly fails the render.
Performance measurements meet approved thresholds or produce a reviewed alternative.

Documentation:

Virtual screen runtime.
Player bridge.
Render timing and capture behavior.
Performance evidence.
Implementation plan/log/report.

8. `anuva-python-server`: v2 render-package compatibility

Scope:

Accept or transport PresentationConfig v2.
Stage player runtime, documents, assets, and timeline.
Validate versions and checksums before Unity invocation.
Preserve structured errors.

Dependencies:

Final render-package contract.
CMS v2 fixture.
Unity expected package layout.

Acceptance:

Complete package reaches Unity without content transformation.
Unsupported versions fail before rendering.
Retries retain deterministic artifact identities.

Documentation:

Render orchestration and package contract.
Implementation plan/log/report if code changes are required.

9. Cross-repository acceptance and clean cutover

Scope:

Exercise generation, editing, template switching, Web preview, packaging, Unity playback, and video capture.
Remove remaining active Reveal-specific code and assets.
Recreate development database.
Complete Product Main review.

Dependencies:

All implementation workstreams.

Acceptance:

End-to-end representative presentation succeeds.
Web and Unity surfaces match within approved rendering tolerances.
All three surfaces follow one timeline.
No production path calls upstream Bento update/collaboration services.
Exact downstream runtime/package versions are recorded.
Active docs contain no obsolete Reveal workflow guidance.

Documentation:

Repository completion reports.
Product Main Completion Review.
Release impact and remaining follow-ups.

Suggested delivery sequence

flowchart TD
    Plan["Product Main approval and ADR"]
    Bootstrap["Private downstream bootstrap"]
    Spike["Contract/editor/player/Vuplex spike"]
    Decision{"Spike accepted?"}
    Core["Anuva Bento core + templates"]
    CmsContract["CMS v2 + choreography + compilation"]
    CmsEditor["CMS editor + AI + preview"]
    Unity["Unity three-player integration"]
    Python["Python package compatibility"]
    E2E["Cross-repository acceptance and cutover"]

    Plan --> Bootstrap --> Spike --> Decision
    Decision -->|Yes| Core
    Decision -->|No| Plan
    Core --> CmsContract
    Core --> Unity
    CmsContract --> CmsEditor
    CmsContract --> Python
    Unity --> E2E
    CmsEditor --> E2E
    Python --> E2E

Do not commit the complete product to Bento before the Vuplex and downstream maintenance spike passes.

Spike go/no-go criteria

Proceed to full implementation only if:

Bento can be built reproducibly from the private downstream.
Anuva modifications can remain concentrated behind maintainable boundaries.
A player can run without upstream update or collaboration network access.
One representative document renders consistently in Web and Vuplex.
Three concurrent Vuplex players fit approved memory and performance limits.
External time control can produce deterministic state after arbitrary seek.
Transparent Emphasis output works.
Fonts, images, SVG, charts, and supported media load reliably in both hosts.
A template family can reapply layouts without losing semantic content.
Upstream merge rehearsal is understandable and does not require rewriting the downstream.

Stop or revisit the design if:

Three WebViews are operationally infeasible.
Bento's renderer cannot be controlled deterministically.
Maintaining editor/player build boundaries requires pervasive recurring upstream conflicts.
The document model cannot preserve content safely across template changes.
Required player behavior depends on public Bento services.

Product acceptance criteria

[ ] A private Shoonya-Game-Technologies/anuva-bento repository preserves upstream history and has a documented update process.
[ ] Bento and third-party notices remain in downstream source and distributed artifacts.
[ ] The active Anuva contract contains three surface documents and one authoritative timeline.
[ ] Main, Companion, and Emphasis can contain independent surface items and scene mappings.
[ ] Main and Companion support persistent slide sequences; Emphasis supports transient show/hide events.
[ ] One versioned player implementation runs in Web preview and three Unity Vuplex instances.
[ ] Unity can load, seek, reset, and execute the surface timeline deterministically.
[ ] The editor opens from Scene Editor and can focus any scene and surface.
[ ] Users can edit surface content independently.
[ ] One template family applies coordinated surface-specific layouts.
[ ] Template changes preserve semantic content and report unsafe mappings.
[ ] The AI Assistant uses validated operations rather than unrestricted raw HTML or JavaScript generation.
[ ] Narrative analysis produces complementary multi-surface choreography.
[ ] Compilation produces valid Bento documents and resolves authoritative timing.
[ ] PresentationConfig v2 is the only active presentation contract after clean database recreation.
[ ] CMS, Python, and Unity reject unsupported runtime or document versions.
[ ] Production preview/render does not contact upstream Bento update or collaboration services.
[ ] Web preview and captured Unity output use the same recorded player version and resolve the same assets.
[ ] Active Reveal-specific contracts, generators, validators, player bridges, and documentation are removed.

Open decisions for formal planning

Contract ownership

Does Product Main own the normative Anuva Bento presentation schema, with the package implementing it?
Which subset of Bento types should be exposed to CMS consumers?
Where is runtime compatibility declared and validated?

Persistence granularity

Store the composite presentation as one database object or surface-specific documents with one aggregate revision?
How are partial autosaves and revision conflicts handled?
Is version history required in the initial release?

Template overrides

How are template-owned properties distinguished from user overrides?
Does family reapplication preserve all user extras by default?
What is the user experience when no compatible target layout exists?

Asset packaging

Which assets remain URLs during Web editing?
Which are copied or embedded for Unity?
How are signed URLs and CORS handled?
What is the maximum supported document/package size?

Editor deployment

Package editor JavaScript into anuvax-cms or serve a versioned static editor artifact?
One editor iframe that switches surface documents or multiple retained iframe instances?
Which host owns keyboard shortcuts and focus?

Player packaging

One shared HTML shell plus three JSON documents, or three generated self-contained HTML files for Unity?
How are runtime assets checksummed and cached?
How does Unity report the exact loaded player version?

Timing and animation

Exact external-clock API.
Allowed animation/effect subset for deterministic video.
Behavior of autoplay media and charts during seek.
Whether hover/interactivity is disabled or translated in video mode.

AI Assistant

Which model and tool boundary is used?
Which edits require user confirmation?
How is context minimized without losing cross-surface coherence?
How are AI changes attributed and audited?

Multi-surface directing

Should screen attention focus feed camera-shot planning?
When should the director intentionally calm or hide other surfaces?
Are there product rules for maximum simultaneous motion?

Runtime performance

Approved memory, CPU/GPU, startup, and frame-time thresholds for three Vuplex players.
Target player and RenderTexture resolutions per surface.
Fallback if three independent WebViews exceed limits.

Anuva Bento Integration

Document status

Executive recommendation

Important terminology

Product motivation

Clarification: replacement of the current Reveal slide system

Goals

Non-goals

Existing Anuva evidence

CMS

Unity

Private downstream repository

Repository choice

Remotes

Branch policy

Licensing

Downstream code structure

Required downstream artifacts

Anuva Bento Contract package

Anuva Bento Editor

Anuva Bento Player

Distribution

Composite presentation model

Anuva document metadata

Scene-to-surface mapping

Surface responsibilities

Main Screen

Companion Screen

Emphasis Projection

Authoritative surface timeline

Player runtime model

Three logical players

One shared runtime

Load lifecycle

Required player API

Required events

Deterministic time

Unity integration

Vuplex performance spike

Web editor integration

Entry point

Surface selection

Composite preview

Hosting

Persistence

Template system

Template family

Surface-specific layout examples

Template operations

Template lineage and overrides

AI Assistant

Product role

Structured tools

Assistant context

Safety and editability

Narrative analysis and screen choreography

Required conceptual change

Analysis responsibilities

Candidate semantic output

Choreography rules

Revised presentation compilation

Individual document validation

Cross-surface validation

PresentationConfig v2

CMS cutover

Python server impact

Asset strategy

Security and network behavior

Upstream synchronization

Update policy

Recommended procedure

Versioning

Candidate repository workstreams

1. Product Main: approve Anuva Bento architecture

2. New anuva-bento: private downstream bootstrap

3. anuva-bento: contract, editor, and player technical spike

4. anuva-bento: template-family and three-surface support

5. anuvax-cms: PresentationConfig v2 and multi-surface compilation

6. anuvax-cms: embedded editor, preview, and AI Assistant

7. anuva-unity-video-creator: three-player Vuplex integration

2. New `anuva-bento`: private downstream bootstrap

3. `anuva-bento`: contract, editor, and player technical spike

4. `anuva-bento`: template-family and three-surface support

5. `anuvax-cms`: PresentationConfig v2 and multi-surface compilation

6. `anuvax-cms`: embedded editor, preview, and AI Assistant

7. `anuva-unity-video-creator`: three-player Vuplex integration

8. `anuva-python-server`: v2 render-package compatibility