# Propagate (propagate)

> One source card fans ink lines out to a row of phone screens; bug, fix, and recolour cues travel down the lines to every screen.

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

## Install

```sh
npx shadcn@latest add @jbm/propagate
```

Also installs @jbm/tokens, @jbm/motion-hooks, @jbm/pop, @jbm/paper, @jbm/ui-bits (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/propagate.json, files[].content).

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

## API

### `Propagate` (component)

Remotion illustration of one source of truth. At `at` the sheet springs in, the curved lines draw over 0.9 s from at + 0.25, and the screens pop up one by one (0.08 s apart). Optional cue pairs then play: `bug` puts a cross badge on the source and every screen; `fix` → `fixed` flips the source badge to a check, sends vermilion pulses down the lines, and flips every screen's badge on arrival; `recolor` → `recolored` crossfades the source buttons to vermilion (badges fade out from recolor − 0.2), sends pulses, and recolours every screen on arrival. Absent cues never fire.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | required | Box width in stage pixels; the screens divide it into columns and the source card is 47% of it (at most 440). |
| `h` | `number` | required | Box height in stage pixels; screens fill the space below the source, capped at 1.6 × their width. |
| `at` | `number` | required | Seconds from the start of the sequence when the sheet enters and the lines start drawing. |
| `label` | `{ text: string; at: number }` | none | Optional sticker above the source: `text` and its entrance `at` in seconds. Reserves extra room above the source card. |
| `targets` | `number` | `6` | Number of screens; a positive integer (throws otherwise). Up to 6 sit in one row; more split into two rows. |
| `bug` | `number` | none | Seconds when the cross badges appear on the source and on every screen. |
| `fix` | `number` | none | Seconds when the source badge flips to a check and fix pulses leave the source. |
| `fixed` | `number` | none | Seconds when fix pulses arrive and every screen's badge flips to a check. Must be later than `fix`. |
| `recolor` | `number` | none | Seconds when the source buttons turn vermilion (0.35 s crossfade) and recolour pulses leave; badges fade out from 0.2 s before. |
| `recolored` | `number` | none | Seconds when recolour pulses arrive and every screen's buttons turn vermilion. Must be later than `recolor`. |

### `propagationProgress` (function)

Pulse position along the lines for one departure/arrival pair, eased in-out cubic and clamped. Used by Propagate; exported for tests and custom pulses.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `sec` | `number` | required | Current time in seconds (e.g. from useSec). |
| `from` | `number` | none | Departure cue in seconds; when either cue is missing the result is -1 (no pulse). |
| `to` | `number` | none | Arrival cue in seconds; must be finite and later than `from`, or it throws a RangeError. |

Returns: Progress from 0 (at the source) to 1 (arrived), or -1 when a cue is missing. Pulses render only strictly between 0 and 1.

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 1680 | 760 |
| Vertical (1080×1920) | 936 | 1040 |

The box is exactly w × h (both required). The numbers are what SceneFromSpec passes in a legacy flow layout: the safe-area width (1920 − 2 × 120, 1080 − 2 × 72) and the default block height { landscape: 760, vertical: 1040 }. In illustration layouts it gets the allocated height instead. Badges (−22px on the source, −14px on screens), screen tilt, and shadows can reach past the box.

## Examples

### Bug, fix, and recolour across six screens

```tsx
import { Propagate } from "@/jbm/motion/propagate"

<Propagate w={936} h={1040} at={0.9} targets={6}
  label={{ text: "una sola fuente de verdad", at: 4 }}
  bug={5.8} fix={6.6} fixed={7.7} recolor={10.5} recolored={11.7} />
// Render inside a Remotion <Composition> or <Player>.
```

### Recolour only, eight screens in two rows

```tsx
import { Propagate } from "@/jbm/motion/propagate"

<Propagate w={1680} h={760} at={0.2} targets={8}
  recolor={3} recolored={4.2} />
```

## QA

- Step through at, mid-line draw, and each cue: badges scale in on `bug`, pulses travel only between departure and arrival, and screens change exactly on `fixed` and `recolored`.
- Check the final frame: every screen shows vermilion buttons, badges have faded out after a recolour, and nothing is mid-flight.
- Try targets 1, 6, and 7+: one row up to 6, two rows beyond; confirm screens do not become too short when h is small (height is floored by the space left under the source).
- Without a label the source sits at the top of the box and its badge pokes 22px above it; leave room in the layout.
- Inspect landscape and vertical widths: the last screen's badge and tilt can cross the right edge by about 14px.

## 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 155 frames (0–154); see them side by side at https://jbm-ui.bns.studio/c/propagate?view=strip, or open one frame with ?frame=<frame>.

```tsx
<Propagate w={936} h={640} at={0.2} label={{ text: "una sola fuente de verdad", at: 0.9 }} targets={6} bug={1.6} fix={2.4} fixed={3.2} recolor={4} recolored={4.8} />
```

| Frame | Seconds | Shows | What to check |
| --- | --- | --- | --- |
| 0 | 0.00 | Empty stage |  |
| 69 | 2.30 | Bug appears | Cross badges sit on the source and on every screen; no pulse has left yet. |
| 84 | 2.80 | Fix travels | The source shows a check and vermilion pulses are mid-line; screens still show crosses. |
| 111 | 3.70 | Fix lands | Every screen shows a check and nothing is in flight, before the recolour starts. |
| 154 | 5.13 | End |  |

## Docs

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

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [MotionHooks (motion-hooks)](https://jbm-ui.bns.studio/catalog/motion-hooks.md)
- [Pop (pop)](https://jbm-ui.bns.studio/catalog/pop.md)
- [Paper (paper)](https://jbm-ui.bns.studio/catalog/paper.md)
- [UiBits (ui-bits)](https://jbm-ui.bns.studio/catalog/ui-bits.md)

Installed by:

- [SceneFromSpec (scene-spec)](https://jbm-ui.bns.studio/catalog/scene-spec.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
