# PaperTape (paper-tape)

> Strip of paper fed out by length, with printed marks, checkpoint markers, and attachments on one coordinate system.

- Entry: component
- Category: UI Bits
- Preview capabilities: controls
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/paper-tape
- JSON: https://jbm-ui.bns.studio/catalog/paper-tape.json
- Registry item: https://jbm-ui.bns.studio/r/paper-tape.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/paper-tape
```

Also installs @jbm/tokens, @jbm/paper, @jbm/tape-marker (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/.

## Files

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

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/paper-tape.tsx` | `src/jbm/ui/paper-tape.tsx` | `@/jbm/ui/paper-tape` |

## API

### `PaperTape` (component)

A card strip with an ink edge and paper shadow that grows from the source as `length` increases. Paired ink dashes are printed every 72 paper px, and markers and attachments ride on the same paper coordinates, so feeding the tape moves them together. Only marks, markers, and attachments inside the visible window render; the viewport clips at its bounds.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` | required | Paper fed out so far, in stage px. Increase it to feed the tape; negative or non-finite values count as 0. |
| `window` | `number` | `400` | Visible run in stage px; also the component's width (horizontal) or height (vertical). |
| `thickness` | `number` | `48` | Strip thickness in stage px; minimum 16. |
| `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | `horizontal` feeds along x; `vertical` feeds along y and turns markers 90°. |
| `markers` | `{ id: string; at: number; label?: string }[]` | `[]` | Checkpoint TapeMarkers placed at paper coordinate `at` (0 = start of the paper). `id` must be unique within the tape; `label` shows above the marker. |
| `attachments` | `TapeAttachment[]` | `[]` | Arbitrary React content pinned at paper coordinate `at`, below the strip (horizontal) or beside it (vertical). IDs must be unique across markers and attachments. |
| `style` | `CSSProperties` | none | Inline styles merged last onto the outer viewport, e.g. width or overflow. |

### `paperAt` (function)

Converts a paper coordinate to its screen distance from the tape's origin; markers, attachments, and printed marks all use it.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` | required | Paper fed out so far, as passed to PaperTape. |
| `coordinate` | `number` | required | Position on the paper, measured from the start of the paper. |

Returns: Screen offset in stage px: length − coordinate (length clamped to ≥ 0). Values within the window are visible.

## Stage

Declared in stage pixels at the documented defaults.

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

Horizontal default: width = window (400), height = thickness + 150 (48 + 150); the strip sits 48px from the top to leave room for markers and labels. direction="vertical" gives width thickness + 180 (228) by height window (400). maxWidth is 100% of the container. Stage orientation does not change the box.

## Examples

### Tape with a checkpoint

```tsx
import { PaperTape, paperAt } from "@/jbm/ui/paper-tape"

<PaperTape length={700} window={320} markers={[{ id: "review", at: 520, label: "revisar" }]} />
// paperAt(700, 520) === 180: marks and attachments share this origin.
```

### Feed from a Remotion timeline

```tsx
import { PaperTape } from "@/jbm/ui/paper-tape"
import { useProgress } from "@/jbm/motion/hooks" // install @jbm/motion-hooks separately

// Render inside a Remotion <Composition> or <Player>: hooks run in the component body.
export function FeedingTape() {
  const feed = useProgress(0.2, 1000, 4)
  return <PaperTape length={feed} window={280} direction="vertical" markers={[{ id: "stop", at: 520 }]} />
}
```

## QA

- Drag Feed from 0 to 1: the strip grows from zero, printed dashes, the marker, and the note move together, and nothing appears before its coordinate is fed out.
- Toggle Vertical tape: markers rotate 90° and attachments sit beside the strip; check both directions at narrow widths.
- Toggle Checkpoint marker: the tape and note do not move.
- Try a very long length: only the visible dashes render and content past the window is clipped at the edge.

## Family

Tape, clips & marks

## Docs

- [Paper and filing illustrations guide](https://jbm-ui.bns.studio/docs/design-video-components.md)

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [Paper (paper)](https://jbm-ui.bns.studio/catalog/paper.md)
- [TapeMarker (tape-marker)](https://jbm-ui.bns.studio/catalog/tape-marker.md)

Imported in examples:

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