Skip to content

Presentation Contract

Identity and version

An Anuva Bento presentation is a pure JSON object with:

  • format: anuva/bento-presentation;
  • contractVersion: 1.0.0;
  • stable presentationId and revision;
  • an exact compatibility manifest;
  • Main, Companion, and Emphasis surfaces;
  • one ordered absolute-time timeline;
  • external asset declarations;
  • semantic template metadata.

Stable identifiers use 1-128 ASCII letters, digits, ., _, :, or -, starting with a letter or digit. IDs are never derived from mutable display text. The validator rejects duplicate slide, element, fragment, event, template, or asset identities in their applicable scope and rejects dangling references.

Surface rules

main, companion, and emphasis are required and use identical validation and playback rules. A surface contains:

  • a stable surface ID and matching kind;
  • a positive viewport;
  • a Boolean transparent capability;
  • a read-only Bento document;
  • external asset bindings; and
  • stable fragment definitions.

Transparency is optional for every surface kind. Emphasis is not implicitly transparent, initially hidden, or otherwise structurally special.

Production documents must be read-only and must not contain collaboration metadata. Embedded document assets are limited to declared font binaries. Images, SVG, chart data or snapshots, audio, video, and posters use external bindings.

Timeline and fragments

Timeline events have a stable ID, non-negative atMs, target surface, and one action:

  • select a slide by ID;
  • show, hide, or clear the surface; or
  • set a stable fragment ID visible or hidden.

Events are ordered by absolute milliseconds. A deterministic state is rebuilt from the immutable presentation and all applicable events at or before the requested time. Slide changes reset that surface's fragments before subsequent fragment events are applied.

Fragments belong to a surface, identify one slide and one or more element IDs, and carry a unique non-negative order. The player command uses fragment identity, not Reveal navigation position.

Templates

Template metadata identifies a template, family, semantic version, and role-to-element bindings. Bindings reference stable element IDs. Rendering consumers may use this metadata for compatibility and diagnostics.

ANU-12 adds a separate versioned template-family schema for authoring, including coordinated surface layout packs, safe areas, theme tokens, semantic slots, and pure application rules. This repository owns schema validation and transformation semantics. CMS owns durable persistence, PresentationConfig compilation, and product workflow orchestration.

Runtime schema

The package exports server-safe TypeScript declarations for the presentation, surface, and minimum read-only Bento document structures plus runtime validation. The distribution also carries schemas/presentation.schema.json, which defines every contract-owned nested structure with closed properties and the minimum player-safe Bento document shape.

Runtime validation additionally enforces cross-reference, unique surface and document identity, fragment-to-slide membership, safe-content, deterministic-feature, asset-kind/media-type, and embedded-asset rules that exceed structural JSON Schema.