# CodeCard (code-card)

> Dark code card that types each line in place at a steady character rate, one line after another.

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

## Install

```sh
npx shadcn@latest add @jbm/code-card
```

Also installs @jbm/card, @jbm/tokens (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/code-card.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/motion/code-card.tsx` | `src/jbm/motion/code-card.tsx` | `@/jbm/motion/code-card` |
| `registry/jbm/motion/code-card-timing.js` | `src/jbm/motion/code-card-timing.js` | `@/jbm/motion/code-card-timing.js` |
| `registry/jbm/motion/code-card-timing.d.ts` | `src/jbm/motion/code-card-timing.d.ts` | `@/jbm/motion/code-card-timing` |

## API

### `CodeCard` (component)

Fixed-size dark Card with three window dots, an optional mono title, and mono code lines. Each line starts typing at its `at` cue or when the previous line finishes, whichever is later, at `charsPerSecond`; empty rows keep their line height so the layout never jumps.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `lines` | `CodeLine[]` | required | Code lines in order: `t` is the text (whitespace preserved, no wrapping), `at` is the earliest start in seconds relative to the enclosing Sequence, and optional `color` overrides the cream text color. |
| `w` | `number` | `900` | Card width in stage pixels. |
| `h` | `number` | `520` | Card height in stage pixels; content beyond it is clipped. |
| `size` | `number` | `24` | Code font size in stage pixels; lines are 1.55 × size tall. |
| `title` | `string` | none | Optional mono file name beside the window dots. |
| `charsPerSecond` | `number` | `32` | Typing rate in characters per second; must be positive and finite or the schedule throws. |

### `codeTypingSchedule` (function)

Builds the sequential typing schedule CodeCard uses, in frames. Use it in the host to budget scene duration: the last entry's `end` plus one terminal frame.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `lines` | `{ t: string; at: number }[]` | required | The same `{ t, at }` lines passed to CodeCard; `at` in seconds. |
| `fps` | `number` | required | Composition frames per second. |
| `charsPerSecond` | `number` | none | Typing rate; throws a RangeError unless positive and finite. |

Returns: One `{ characters, start, end }` per line: the line split into characters (code points) and its start and end frames.

### `typedCode` (function)

The visible prefix of one scheduled line at a given frame.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `line` | `CodeTypingLine` | required | One entry from codeTypingSchedule. |
| `frame` | `number` | required | Current frame relative to the enclosing Sequence. |
| `fps` | `number` | required | Composition frames per second. |
| `charsPerSecond` | `number` | none | Typing rate; must match the value used for the schedule. |

Returns: The typed text so far: empty before `start`, the full line from `end` on.

## Stage

Declared in stage pixels at the documented defaults.

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

The card is border-box with width `w` (900) and height `h` (520) at the defaults, regardless of content. Scene specs pass w = min(usable width, 1200) and h 480 in landscape, the usable width (936) and h 520 in vertical, and the available height in illustration layouts. Long lines do not wrap; they clip at the card edge.

## Examples

### Type a short file

```tsx
import { CodeCard } from "@/jbm/motion/code-card"

<CodeCard title="hello.ts" charsPerSecond={32} lines={[
  { t: "const idea = \"simple\"", at: 0.2 },
  { t: "render(idea)", at: 0.7, color: "#FF8A6A" },
]} />
```

### Budget the scene length

```tsx
import { codeTypingSchedule } from "@/jbm/motion/code-card-timing"

const fps = 30
const schedule = codeTypingSchedule(lines, fps, 32)
const durationInFrames = (schedule.at(-1)?.end ?? 0) + 1
```

## QA

- Step to the first frame (empty rows at full height), mid-typing (a partially typed line, earlier lines complete), and the last frame (every line complete).
- Give two lines overlapping `at` cues: the second waits for the first to finish instead of typing in parallel.
- Check the longest line and the line count fit inside `w` × `h` at the chosen `size`; overflow is clipped, not wrapped.
- Inspect the dark surface border and shadow at display scale (docs/surface-depth.md).

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

```tsx
<CodeCard w={620} h={280} title="hello.ts" lines={[{ t: "const idea = \"simple\";", at: 0.2 }, { t: "const story = explain(idea);", at: 0.7 }, { t: "render(story);", at: 1.2, color: "#FF8A6A" }]} />
```

| Frame | Seconds | Shows | What to check |
| --- | --- | --- | --- |
| 0 | 0.00 | Begin |  |
| 27 | 0.90 | First line typed | The first line is complete and the second has not started. |
| 54 | 1.80 | Second line typed | Two lines are complete; the vermilion third line is next. |
| 68 | 2.27 | End |  |

## Docs

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

## Related

Installs:

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