# RebuildScreens (rebuild-screens)

> A phone screen assembled piece by piece, then rebuilt on each new screen that springs onto the pile; Stamp slams a loud word on top.

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

## Install

```sh
npx shadcn@latest add @jbm/rebuild-screens
```

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

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

## API

### `RebuildScreens` (component)

Fixed w × h box holding a pile of tilted PhoneFrames. The first screen is present from the start and its pieces (card, input, button, stacked in that order) pop in on their own cues. Each cue in `again` springs in another screen offset up and to the right, whose pieces rebuild in a quick stagger; the pile re-centres as screens arrive. An optional sticker stamps a word near the top left. The input piece's cursor blinks about 2.2 times per second.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | required | Box width in stage pixels; also caps the phone width at 50% of w. |
| `h` | `number` | required | Box height in stage pixels; the phone width is also capped at 47% of h (phone height is 1.82 × its width). |
| `pieces` | `ScreenPiece[]` | required | Pieces for the first screen: `kind` is button, input, or card and `at` is its entrance in seconds relative to the Sequence. One piece per kind; rendering order is always card, input, button. |
| `again` | `number[]` | `[]` | Seconds at which each extra screen arrives; every cue adds one screen whose pieces rebuild starting 0.12 s after it. |
| `sticker` | `{ text: string; at: number }` | none | Optional loud word: `text` and the `at` second it stamps in over the pile. |
| `rebuildStep` | `number` | `0.22` | Seconds between pieces when a new screen rebuilds them, in the order the pieces are listed in `pieces`. |
| `phoneScale` | `number` | `1` | Multiplies the default phone width; above 1 it is still limited so the whole pile fits in 90% of the box. Must be positive and finite or it throws. |

### `Stamp` (component)

Absolutely positioned Sticker that slams in from 1.7× to 1× scale on a bouncy spring (damping 9, stiffness 160) and fades in over the first half of the spring. Catalog reuses it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `at` | `number` | required | Stamp time in seconds relative to the enclosing Sequence. |
| `text` | `string` | required | The loud word or short phrase; it does not wrap. |
| `left` | `number` | required | Left offset in stage pixels inside the positioned parent. |
| `top` | `number` | required | Top offset in stage pixels inside the positioned parent. |
| `size` | `number` | required | Sticker font size in stage pixels; the sticker's padding and corner radius scale with it. |
| `rotate` | `number` | `-7` | Sticker tilt in degrees; negative tilts counter-clockwise. |

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 1680 | 720 |
| Vertical (1080×1920) | 936 | 1000 |

The component is exactly `w` × `h`; w and h are required, so these are the scene-spec `screens` defaults in flow layout: the usable width (1920 − 2 × 120, 1080 − 2 × 72) and h 720 landscape / 1000 vertical (override with the block's `h`). The phone is min(470, 0.5 w, 0.47 h) wide at phoneScale 1: 338 × 615 landscape, 468 × 852 vertical. Tilts and the arrival spring can reach slightly past the box.

## Examples

### Build, then rebuild twice

```tsx
import { RebuildScreens } from "@/jbm/motion/rebuild-screens"

<RebuildScreens w={936} h={1000}
  pieces={[{ kind: "button", at: 1 }, { kind: "input", at: 2.8 }, { kind: "card", at: 5.3 }]}
  again={[12.9, 14.5]} sticker={{ text: "¿otra vez?", at: 13 }} />
```

### Stamp a word on any scene

```tsx
import { Stamp } from "@/jbm/motion/rebuild-screens"

<div style={{ position: "relative", width: 936, height: 600 }}>
  <Stamp at={2} text="¡listo!" left={420} top={60} size={96} />
</div>
```

## QA

- Step to the start (empty first phone), mid-build (some pieces in), the moment each `again` screen arrives (spring from the upper right, pile re-centering), and the end (all screens rebuilt, sticker settled).
- Check the rotated phones and sticker stay inside the safe area in both orientations, especially with phoneScale above 1 or three or more screens.
- Rebuilt pieces stagger in `pieces` array order while pieces always stack card, input, button; confirm the rebuild order reads as intended. Duplicate kinds share a React key and are not supported.
- Confirm the input cursor blink is visible but not distracting at the final render scale.

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

```tsx
<RebuildScreens w={936} h={620} pieces={[{ kind: "button", at: 0.2 }, { kind: "input", at: 0.7 }, { kind: "card", at: 1.2 }]} again={[2.2, 3.2]} sticker={{ text: "¿otra vez?", at: 2.3 }} />
```

| Frame | Seconds | Shows | What to check |
| --- | --- | --- | --- |
| 0 | 0.00 | Begin |  |
| 63 | 2.10 | First screen built | Button, input, and card have popped into the first phone; no second screen yet. |
| 93 | 3.10 | Built again | The second screen has sprung in with its pieces rebuilt and the sticker stamped. |
| 131 | 4.37 | End |  |

## Docs

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

## Related

Installs:

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

Installed by:

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