# SceneFromSpec (scene-spec)

> Compiles a YAML-shaped scene spec into a Remotion scene for either orientation, with timed blocks, explicit layouts, orientation overrides, and configurable safe areas.

- Entry: component
- Category: Layout
- Preview capabilities: controls, replay, portrait, player
- Runtime: Remotion
- Needs Remotion: yes
- QA page: https://jbm-ui.bns.studio/c/scene-spec
- JSON: https://jbm-ui.bns.studio/catalog/scene-spec.json
- Registry item: https://jbm-ui.bns.studio/r/scene-spec.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/scene-spec
```

Also installs @jbm/tokens, @jbm/label, @jbm/big, @jbm/chip, @jbm/stat-card, @jbm/callout, @jbm/bullet-list, @jbm/scene, @jbm/pop, @jbm/code-card, @jbm/brand, @jbm/rebuild-screens, @jbm/catalog, @jbm/propagate, @jbm/shelf (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.
3. Install `remotion` and render inside a Remotion `<Composition>` or `<Player>`, not a plain React tree. Timing values are in seconds.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/scene-spec.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/motion/compile.tsx` | `src/jbm/motion/compile.tsx` | `@/jbm/motion/compile` |
| `registry/jbm/motion/spec.ts` | `src/jbm/motion/spec.ts` | `@/jbm/motion/spec` |

## API

### `SceneFromSpec` (component)

Renders one SceneSpec as a full-canvas Scene for one orientation. Blocks (big, stat-row, note, callout, bullets, chips, code, spacer, screens, catalog, propagate, shelf, twice, brand, overlay) stack inside the safe area with `gap` between them; `composition` and `variants[orientation]` choose the layout (flow, hero, headline-illustration, illustration), safe area, headline ratio, subject scale, and optional block overrides. Anchors resolve through `host.resolve`, text through `host.t`. It does not fit, shrink, or paginate content, and throws on invalid layouts, anchors, gaps, or insets. It does not validate the spec's shape (an unknown block type renders nothing): validate parsed YAML against the JSON Schema in `schemas` first. Every block, field, default, unit, and error is listed in the scene spec guide in `docs`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `SceneSpec` | required | One parsed scene (SceneSpec): required id and blocks; optional anchors (needed only when a block time names an anchor), title, starts, composition, variants, gap, and valign. The compiler takes plain objects; parse YAML in the host (the guide uses js-yaml 4 `load`) and validate against #/$defs/SceneSpec of the JSON Schema. |
| `showSafeArea` | `boolean` | `false` | Draws a dashed vermilion outline of the safe area for debugging; leave off for final renders. |
| `orientation` | `Orientation` | required | landscape (for a 1920 × 1080 composition) or vertical (1080 × 1920); picks stage geometry, block sizes, and variants. |
| `host` | `Host` | required | Injected services: `resolve(phrase)` returns seconds from scene start for an anchor's narration phrase; optional `t(string)` translates on-screen text. |

### `resolveAt` (function)

Resolves a block time: a number of seconds, an anchor name, or an anchor with a signed offset such as "explain+0.2".

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `at` | `At` | required | Seconds from scene start, or an anchor name with an optional +/- offset in seconds. |
| `spec` | `SceneSpec` | required | The scene whose `anchors` map names to narration phrases; its id appears in errors. |
| `host` | `Host` | required | Supplies `resolve(phrase)` in seconds. |

Returns: Seconds from scene start. Throws on malformed, unknown, or non-finite anchors.

### `sceneGeometry` (function)

Safe-area rectangle in canvas pixels for an orientation and safe-area preset or custom insets.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `Orientation` | required | landscape or vertical; selects stage[orientation]. |
| `safeArea` | `SafeArea` | `"legacy"` | legacy (default; portrait bottom 480), full (portrait 100/72/100/72, landscape 90/120/90/120), social (portrait 160/160/320/72), or explicit { top, right, bottom, left } insets. |

Returns: { left, top, width, height } in canvas pixels. Throws when insets are negative, non-finite, or leave no content area.

### `Host` (type)

Timing and translation services injected by the video project: `resolve(phrase)` and optional `t(s)`.

### `SceneSpec` (type)

One scene: required id and blocks; optional anchors, title, starts, composition, variants, gap, valign.

### `ScenesFile` (type)

The parsed YAML file: `{ scenes: SceneSpec[] }`.

### `Block` (type)

Any block body plus an optional `until` exit cue.

### `CompositionOptions` (type)

safeArea, layout, headlineRatio, subjectScale, gap, valign, and an optional full blocks override.

### `SafeArea` (type)

"legacy" | "full" | "social" | explicit pixel insets { top, right, bottom, left }. Social applies to vertical only; in landscape it falls back to full (90/120/90/120).

### `PerOrientation` (type)

`{ landscape, vertical }` pixel values, accepted wherever a size may differ per orientation (gap, spacer h, screens and propagate h).

### `StatItem` (type)

One stat-row card: at, label, value, optional sub and valueColor.

### `Exit` (type)

The optional `until` cue every block accepts: fade out and drift up over 0.4 s.

### `BlockBody` (type)

The block union without `until`, discriminated by `type`.

### `SceneLayout` (type)

"flow" | "hero" | "headline-illustration" | "illustration".

### `At` (type)

A time: anchor name (optionally with an offset) or seconds.

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 1920 | 1080 |
| Vertical (1080×1920) | 1080 | 1920 |

SceneFromSpec renders a Scene that fills its parent (position absolute, inset 0); use a 1920 × 1080 composition for landscape and 1080 × 1920 for vertical. Blocks lay out inside sceneGeometry(orientation, safeArea).

## Examples

### Compile a parsed scene

```tsx
import { SceneFromSpec } from "@/jbm/motion/compile"
import type { ScenesFile } from "@/jbm/motion/spec"

// Placeholders: a parsed, schema-validated scenes file, and seconds from scene start per phrase.
declare const scenes: ScenesFile
declare const timings: Record<string, number>

export const FirstScene = () => (
  <SceneFromSpec spec={scenes.scenes[0]} orientation="landscape"
    host={{ resolve: (phrase) => timings[phrase] }} />
)
// Every block and field: https://jbm-ui.bns.studio/docs/scene-spec.md
```

### Headline and illustration, tuned for portrait

```tsx
import type { SceneSpec } from "@/jbm/motion/spec"

const spec: SceneSpec = {
  id: "library",
  anchors: { build: "una biblioteca" },
  composition: { safeArea: "full", layout: "headline-illustration", subjectScale: 1.3 },
  variants: { vertical: { headlineRatio: 0.23, gap: 48 } },
  blocks: [
    { type: "big", at: 0, text: "Una biblioteca.\nMuchas posibilidades.", align: "center", size: 90 },
    { type: "screens", pieces: [{ kind: "card", at: "build" }, { kind: "button", at: "build+0.6" }], phoneScale: 1.5 },
  ],
}
```

### Parse, validate, and compile a YAML scenes file

```tsx
import { load } from "js-yaml"
import Ajv2020 from "ajv/dist/2020"
import { SceneFromSpec } from "@/jbm/motion/compile"
import type { ScenesFile } from "@/jbm/motion/spec"
import schema from "./scene-spec.schema.json" // curl -o scene-spec.schema.json https://jbm-ui.bns.studio/schemas/scene-spec.json

// Placeholders: the YAML source, seconds from scene start per phrase, and a translator.
declare const yamlText: string
declare const timings: Record<string, number>
declare const translate: (text: string) => string

const validate = new Ajv2020({ allErrors: true }).compile(schema)
const data: unknown = load(yamlText)
if (!validate(data)) throw new Error(JSON.stringify(validate.errors, null, 2))
const { scenes } = data as ScenesFile

export const FirstScene = () => (
  <SceneFromSpec spec={scenes[0]} orientation="vertical"
    host={{ resolve: (phrase) => timings[phrase], t: translate }} />
)
```

### Multi-scene vertical composition

```tsx
import { Composition, Series } from "remotion"
import { loadFont as loadGeist } from "@remotion/google-fonts/Geist"
import { loadFont as loadGeistMono } from "@remotion/google-fonts/GeistMono"
import { load } from "js-yaml"
import Ajv2020 from "ajv/dist/2020"
import { SceneFromSpec } from "@/jbm/motion/compile"
import type { ScenesFile } from "@/jbm/motion/spec"
import schema from "./scene-spec.schema.json" // curl -o scene-spec.schema.json https://jbm-ui.bns.studio/schemas/scene-spec.json

// npm install remotion @remotion/google-fonts js-yaml ajv (and @types/js-yaml).
// Token font stacks fall back to the family names "Geist" and "Geist Mono" these load.
loadGeist("normal", { weights: ["400", "500", "600", "700"], subsets: ["latin"] })
loadGeistMono("normal", { weights: ["400", "500"], subsets: ["latin"] })

const FPS = 30
const yamlText = `
scenes:
  - id: hook
    anchors: { reveal: "hecha de piezas" }
    blocks:
      - { type: big, at: 0, text: "Una biblioteca." }
      - { type: note, at: reveal, text: "Hecha de piezas." }
  - id: pieces
    composition: { safeArea: full, layout: illustration }
    anchors: { build: "una pieza" }
    blocks:
      - type: screens
        pieces:
          - { kind: card, at: build }
          - { kind: button, at: build+0.6 }
`

// No narration yet: a literal phrase → seconds (from its scene's start) table, and scene lengths.
const timings: Record<string, number> = { "hecha de piezas": 1.2, "una pieza": 0.8 }
const seconds: Record<string, number> = { hook: 4, pieces: 5 }
const resolve = (phrase: string) => {
  const at = timings[phrase]
  if (at === undefined) throw new Error(`No timing for "${phrase}"`)
  return at
}

const validate = new Ajv2020({ allErrors: true }).compile(schema)
const data: unknown = load(yamlText)
if (!validate(data)) throw new Error(JSON.stringify(validate.errors, null, 2))
const { scenes } = data as ScenesFile
const frames = (id: string) => Math.round(seconds[id] * FPS)

// One Series.Sequence per scene: each scene's times start at 0 inside its own sequence.
export const Explainer = () => (
  <Series>
    {scenes.map((spec) => (
      <Series.Sequence key={spec.id} durationInFrames={frames(spec.id)}>
        <SceneFromSpec spec={spec} orientation="vertical" host={{ resolve }} />
      </Series.Sequence>
    ))}
  </Series>
)

// Register in your Remotion root (registerRoot). Use 1920×1080 with orientation="landscape".
export const RemotionRoot = () => (
  <Composition
    id="explainer-vertical"
    component={Explainer}
    width={1080}
    height={1920}
    fps={FPS}
    durationInFrames={scenes.reduce((total, spec) => total + frames(spec.id), 0)}
  />
)
```

## QA

- Switch the preview through hero, headline-illustration, and illustration layouts and full/social safe areas; inspect beginning, middle, and end frames in both landscape and portrait.
- Turn guides on to see the safe area, then confirm showSafeArea is off in final renders.
- Nothing auto-fits: check tall content (code, stat rows, long headlines) for overflow or clipping at the safe-area edges, especially in portrait.
- Exercise error paths: unknown anchors, headline-illustration with other than two blocks or with a title, and invalid gap or insets must throw with the scene id or a clear message.

## Gallery preview cues

Cue times are seconds on the gallery preview's timeline, which renders the demo below; the Usage examples may use other timings. Map a cue to your own props by its place in the demo. The preview runs at 30 fps for 43 frames (0–42); see them side by side at https://jbm-ui.bns.studio/c/scene-spec?view=strip, or open one frame with ?frame=<frame>.

```tsx
<SceneFromSpec spec={{ id: "portrait-reference", composition: { safeArea: "full", layout: "headline-illustration", subjectScale: 1.3 }, blocks: [{ type: "big", at: 0, text: "Una biblioteca.\nMuchas posibilidades.", align: "center", size: 90 }, { type: "screens", phoneScale: 1.5, pieces: [{ kind: "card", at: 0.2 }, { kind: "input", at: 0.5 }, { kind: "button", at: 0.8 }] }], variants: { vertical: { headlineRatio: 0.23, gap: 48 } } }} orientation="landscape" />
```

| Frame | Seconds | Shows | What to check |
| --- | --- | --- | --- |
| 0 | 0.00 | Begin |  |
| 24 | 0.80 | Subject building | The headline is in and the screen's pieces are arriving (default layout; the hero layout ends before this cue and shows a Middle frame). |
| 42 | 1.40 | End |  |

## Docs

- [Scene spec guide](https://jbm-ui.bns.studio/docs/scene-spec.md)

## Schemas

- [Scene spec JSON Schema](https://jbm-ui.bns.studio/schemas/scene-spec.json)

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [Label (label)](https://jbm-ui.bns.studio/catalog/label.md)
- [Big (big)](https://jbm-ui.bns.studio/catalog/big.md)
- [Chip (chip)](https://jbm-ui.bns.studio/catalog/chip.md)
- [StatCard (stat-card)](https://jbm-ui.bns.studio/catalog/stat-card.md)
- [Callout (callout)](https://jbm-ui.bns.studio/catalog/callout.md)
- [BulletList (bullet-list)](https://jbm-ui.bns.studio/catalog/bullet-list.md)
- [Scene (scene)](https://jbm-ui.bns.studio/catalog/scene.md)
- [Pop (pop)](https://jbm-ui.bns.studio/catalog/pop.md)
- [CodeCard (code-card)](https://jbm-ui.bns.studio/catalog/code-card.md)
- [Brand (brand)](https://jbm-ui.bns.studio/catalog/brand.md)
- [RebuildScreens (rebuild-screens)](https://jbm-ui.bns.studio/catalog/rebuild-screens.md)
- [Catalog (catalog)](https://jbm-ui.bns.studio/catalog/catalog.md)
- [Propagate (propagate)](https://jbm-ui.bns.studio/catalog/propagate.md)
- [Shelf (shelf)](https://jbm-ui.bns.studio/catalog/shelf.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
