# Register (register)

> Paper sheet of drawn writing whose shape says who reads it: steps, lists, tables, sourced prose, or a mixed page.

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

## Install

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

Also installs @jbm/tokens, @jbm/scene-geometry, @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/.

## Files

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

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

## API

### `Register` (component)

A Paper sheet (ink edge at the shared outline weight, house paper shadow) carrying one register of drawn writing: bars, boxes, and rules, never legible prose. `mono` is a prompt chevron, prompt bar, and outlined result box per step; `plain` short numbered lists in two columns; `grid` ruled tables with an ink header; `prose` a justified block with paragraph ends (every fifth line and the last, never two in a row and never the first line after a gap) and a block of source ticks; `mixed` stacks registers on one long page. Every quantity is a prop (no timer), so a slider or video frame drives it. Anchors, seams, and the gap are in the sheet's px from its outer top-left corner, the same space `children` draw in.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `RegisterKind` | required | Register: mono, plain, grid, prose, or mixed. |
| `n` | `number` | none | Steps (mono, 0–24, default 7), list groups (plain, 0–24, default 10), tables (grid, 0–12, default 7; one column up to 4, then two, then three), source ticks (prose, 0–16, default 8), or bands (mixed, 0–4 of mono, plain, grid, prose; default 4). 0 draws a blank sheet (prose keeps its lines). Rounded and clamped. More items tighten the packing; the sheet never grows. List numerals set at 12 × scale; source ticks sit 14 × scale apart. |
| `w` | `number` | required | Sheet width in stage px. |
| `h` | `number` | required | Sheet height in stage px. |
| `sources` | `number` | none | Prose only: source ticks, overriding n. In mixed, the prose band's ticks (default 3). |
| `bands` | `readonly RegisterBand[]` | none | Mixed only: the stacked registers, top to bottom, each `{ kind, n?, weight? }` (weight sets its share of the page before row pitches are capped; each band then sits at the height its writing actually uses, bands follow each other with even separators at least 2 × (frayReach() + 2) + 8 px tall so a Tear's fray or Paper's starting notch at a seam never reaches the writing, and any leftover height collects at the foot of the page; at most 8 bands). Overrides n. Give a mixed page about the board's proportions (460 × 1000): a squatter sheet compresses every band. |
| `gapAt` | `number` | none | Row index where a gap opens: mono steps, plain and grid rows of cells, prose lines then the spacer then source rows; for mixed, the band index (0 = above the first band, bands.length = below the last). Rows from here down move to make room; omit for no gap. |
| `gap` | `number` | none | Gap height in px when fully open. Defaults to a quarter of the writing height; clamped to 60% of it. Marks are sized for the open gap at every reflow value, so reflow moves writing without resizing it. |
| `reflow` | `number` | none | How open the gap is, 0–1 (default 1): run 1 → 0 on the sheet a slip leaves (it closes) and 0 → 1 on the sheet it lands on (it makes room). |
| `scale` | `number` | none | Mark scale: bar thickness, strokes, and spacing. Defaults to w / 360 (clamped 0.4–4), so a 360 px sheet draws 6 px prompt bars and 1.5 px outlines. |
| `pad` | `number` | none | Inset from the sheet edge to the writing in px (default 20 × scale). |
| `reveal` | `number` | none | Writing drawn so far, 0–1: cells ink in reading order, each one left to right; 0 is a blank sheet. The sheet itself is always there. |
| `tone` | `PaperTone` | none | The stock the writing sits on (Paper's tone, default paper): ink writing on paper; on ink or vermilion stock the writing is card-coloured and dim marks cream at 62%. Result boxes and tables are filled with the stock, so whatever lies under the writing (Paper's creases) never shows through them. |
| `accent` | `readonly number[]` | none | Cell indices (reading order, see registerLayout) whose lead mark is vermilion: the prompt bar, list heading, table header, prose line, or source tick. Everything else stays ink. |
| `rotate` | `number` | `0` | Sheet rotation in degrees (Paper's rotate). |
| `label` | `string` | none | Accessible name of the drawing; defaults to “Page of <kind> writing”. |
| `children` | `ReactNode` | none | Laid over the sheet in sheet px (a Slip at registerGap, a tab, a thread origin). |
| `style` | `CSSProperties` | none | Styles merged onto the Paper sheet, e.g. position. |

### `RegisterInk` (component)

The writing alone as an SVG <g> in sheet px, for SVG scenes, tear pieces, or any other surface. Takes the RegisterSpec props plus reveal and accent. Render inside an <svg>.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kind` | `RegisterKind` | required | Register: mono, plain, grid, prose, or mixed. |
| `n` | `number` | none | Steps (mono, 0–24, default 7), list groups (plain, 0–24, default 10), tables (grid, 0–12, default 7; one column up to 4, then two, then three), source ticks (prose, 0–16, default 8), or bands (mixed, 0–4 of mono, plain, grid, prose; default 4). 0 draws a blank sheet (prose keeps its lines). Rounded and clamped. More items tighten the packing; the sheet never grows. List numerals set at 12 × scale; source ticks sit 14 × scale apart. |
| `w` | `number` | required | Sheet width in stage px. |
| `h` | `number` | required | Sheet height in stage px. |
| `sources` | `number` | none | Prose only: source ticks, overriding n. In mixed, the prose band's ticks (default 3). |
| `bands` | `readonly RegisterBand[]` | none | Mixed only: the stacked registers, top to bottom, each `{ kind, n?, weight? }` (weight sets its share of the page before row pitches are capped; each band then sits at the height its writing actually uses, bands follow each other with even separators at least 2 × (frayReach() + 2) + 8 px tall so a Tear's fray or Paper's starting notch at a seam never reaches the writing, and any leftover height collects at the foot of the page; at most 8 bands). Overrides n. Give a mixed page about the board's proportions (460 × 1000): a squatter sheet compresses every band. |
| `gapAt` | `number` | none | Row index where a gap opens: mono steps, plain and grid rows of cells, prose lines then the spacer then source rows; for mixed, the band index (0 = above the first band, bands.length = below the last). Rows from here down move to make room; omit for no gap. |
| `gap` | `number` | none | Gap height in px when fully open. Defaults to a quarter of the writing height; clamped to 60% of it. Marks are sized for the open gap at every reflow value, so reflow moves writing without resizing it. |
| `reflow` | `number` | none | How open the gap is, 0–1 (default 1): run 1 → 0 on the sheet a slip leaves (it closes) and 0 → 1 on the sheet it lands on (it makes room). |
| `scale` | `number` | none | Mark scale: bar thickness, strokes, and spacing. Defaults to w / 360 (clamped 0.4–4), so a 360 px sheet draws 6 px prompt bars and 1.5 px outlines. |
| `pad` | `number` | none | Inset from the sheet edge to the writing in px (default 20 × scale). |
| `reveal` | `number` | `1` | Writing drawn so far, 0–1: cells ink in reading order, each one left to right; 0 is a blank sheet. The sheet itself is always there. |
| `tone` | `PaperTone` | `"paper"` | The stock the writing sits on (Paper's tone, default paper): ink writing on paper; on ink or vermilion stock the writing is card-coloured and dim marks cream at 62%. Result boxes and tables are filled with the stock, so whatever lies under the writing (Paper's creases) never shows through them. |
| `accent` | `readonly number[]` | `[]` | Cell indices (reading order, see registerLayout) whose lead mark is vermilion: the prompt bar, list heading, table header, prose line, or source tick. Everything else stays ink. |

### `registerLayout` (function)

Pure geometry for a register: every cell (reading order, band, row, kind, box, lead point, anchor, marks), row slots, band boxes, mixed seams, prose anchors, and the gap box, in sheet px. Register and RegisterInk draw exactly this, so hosts can attach threads and tears to the same points.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RegisterSpec` | required | RegisterSpec: kind, n, w, h, sources, bands, gapAt, gap, reflow, scale, pad. |

Returns: RegisterLayout { w, h, scale, cells, rows, bands, seams, anchors, gap }.

### `registerAnchors` (function)

Prose source tick centres (prose kind or the prose band of mixed), top to bottom, in sheet px: where threads leave the sheet.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RegisterSpec` | required | RegisterSpec. |

Returns: Pt[]; empty when there is no prose.

### `registerSeams` (function)

Mixed only: the y of each seam between bands, top to bottom, in sheet px, halfway through the space between bands. Tear lines follow them.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RegisterSpec` | required | RegisterSpec. |

Returns: number[] (bands − 1 values); empty for single registers.

### `registerGap` (function)

The gap's box in sheet px: full writing width, height gap × reflow. Place a slip at the fully open gap (reflow 1) so its resting place does not move while the gap animates.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` | `RegisterSpec` | required | RegisterSpec with gapAt. |

Returns: Box, or null without gapAt.

### `sheetRadius` (function)

The corner radius of a writing sheet: SHEET_RADIUS × its mark scale, never under 4 px. Register draws its Paper with it and Tear defaults to it, so a torn page keeps the corners of the sheet it was; pass it to a Paper that stands in for a page.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | required | Sheet width in stage px. |
| `scale` | `number` | none | The sheet's mark scale, when set; defaults to w / 360 clamped to 0.4–4, as Register's. |

Returns: Radius in stage px (6 on a 360 px sheet).

### `SHEET_RADIUS` (constant)

6: a writing sheet's corner radius per unit of mark scale (6 px on a 360 px sheet).

### `RegisterKind` (type)

"mono" | "plain" | "grid" | "prose" | "mixed".

### `RegisterBand` (type)

One band of a mixed page: `{ kind, n?, weight? }`.

### `RegisterSpec` (type)

The geometry props shared by Register, RegisterInk, and the layout helpers.

### `RegisterTone` (type)

"ink" | "dim" | "accent": the fill of a bar mark.

### `RegisterMark` (type)

One drawn mark: bar, outlined box, rule, chevron, or numeral, in sheet px.

### `RegisterCell` (type)

One unit of writing: index, band, row, kind, box, lead, optional anchor, marks.

### `RegisterLayout` (type)

registerLayout's result.

### `RegisterInkProps` (type)

RegisterSpec plus reveal and accent.

### `RegisterProps` (type)

RegisterInkProps plus rotate, label, children, style.

## Stage

Declared in stage pixels at the documented defaults.

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

Exactly w × h stage px (the gallery uses 300 × 380, and 300 × 700 for mixed, near the board's long-page proportions); n, reveal, gap, and reflow never change the box. Rotation and the paper shadow draw outside it. On a 1920 × 1080 stage the board's quadrant sheets are about 440 × 280 and the long mixed page about 460 × 1000.

## Examples

### Four readers, four registers

```tsx
import { Register } from "@/jbm/ui/register"

<div style={{ display: "flex", gap: 24 }}>
  <Register kind="mono" n={7} w={300} h={380} />
  <Register kind="plain" n={10} w={300} h={380} />
  <Register kind="grid" n={7} w={300} h={380} />
  <Register kind="prose" sources={8} w={300} h={380} />
</div>
```

### Long mixed page with seams and source anchors

```tsx
import { Register, registerSeams, registerAnchors } from "@/jbm/ui/register"

const page = { kind: "mixed", w: 380, h: 840 } as const
const seams = registerSeams(page) // three y positions: tear lines
const anchors = registerAnchors(page) // prose source ticks: thread origins

<Register {...page} reveal={0.6} />
```

### A destination making room

```tsx
import { Register, registerGap } from "@/jbm/ui/register"

const reflow = 0.5 // from a slider or frame
const sheet = { kind: "prose", n: 3, w: 250, h: 300, gapAt: 4, gap: 66 } as const
const landing = registerGap({ ...sheet, reflow: 1 }) // where the slip settles

<Register {...sheet} reflow={reflow} />
```

## QA

- Switch Kind through all five: each reads as one register at a glance (steps with result boxes, numbered lists, ruled tables, a justified block with source ticks, a stacked page) and no mark forms a legible word.
- Step Count from 0 to its maximum for every kind: 0 is a blank sheet (no steps, lists, tables, or bands; prose keeps its lines), marks pack tighter inside the same sheet, nothing crosses the pad or the sheet edge, and grid switches to two columns above 4 tables.
- Mixed: every band keeps readable proportions (list numerals at 12 × scale, tables with open rows, not squeezed), and the seams sit in the even gaps between bands.
- Drag Reveal 0 → 1: a blank sheet, then cells ink in reading order, each left to right; no mark appears early or pops.
- Turn on Gap and drag Reflow 1 → 0 → 1: rows below the gap slide while every mark keeps its size; at 0 the writing is evenly spaced again.
- Show seams, anchors, gap: seams sit between mixed bands, anchor rings sit on the source ticks without touching each other or the sheet edge, and the gap box is empty.
- Accent first mark: only that lead mark turns vermilion.
- Check 2× zoom: chevrons, result-box corners, and table rules are crisp and consistent; outlines never exceed the prompt bar's weight.

## Family

Paper & writing

## Docs

- [Writing registers guide](https://jbm-ui.bns.studio/docs/writing-registers.md)

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [SceneGeometry (scene-geometry)](https://jbm-ui.bns.studio/catalog/scene-geometry.md)
- [Paper (paper)](https://jbm-ui.bns.studio/catalog/paper.md)

Installed by:

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