# Paper and filing illustrations

These components adapt the Agent Skills and Opus 5.5 films in `chekos/design` into independently installable React primitives. All inputs are controlled: the caller supplies progress and owns playback, reduced-motion preferences, and scene timing. The gallery uses keyboard-operable sliders without autoplay.

## Paper coordinates

Install `@jbm/paper-tape`. `length` is the amount of paper fed out, in pixels; `window` bounds the visible run. `paperAt(length, at)` converts a position on the paper to its distance from the source. Writing, checkpoint markers, and arbitrary React attachments use that same coordinate system. Increase length to feed paper; do not animate the marks separately. Only visible marks are rendered, so a long process does not accumulate offscreen SVG nodes. The viewport clips attachments at its boundaries.

`@jbm/tape-marker`, `@jbm/paper-clip`, `@jbm/clipped-note`, and `@jbm/punched-tag` are separate objects. The note composes `Paper` and `PaperClip`; all paper surfaces reuse the shared paper shadow. Marker and attachment IDs must be unique within one tape.

## Ink and metadata

`@jbm/paper-line` accepts normalized `reveal`, `lift`, and `strike` controls, plus independent `dotted`, `accent`, and `mono` options. Reveal preserves complete graphemes and reserves the full text footprint. A visually hidden copy supplies the complete text to assistive technology. Use short lines for the single strike-through stroke.

`@jbm/stamp` takes arbitrary text and a normalized `press`. It represents an ink impression, not a validation result. `@jbm/frontmatter` provides semantic key/value rows, YAML delimiters, optional emphasis/dimming, and an explicit stacked layout for narrow compositions.

The gallery's Ticket example demonstrates a work order using the existing header and stub slots. Named sheets can likewise compose Paper and Frontmatter without adding another surface primitive.

## Folder contents and transport

`Folder` has three tones: `accent` (vermilion), `ink`, and `card` (plain cream with ink text). Accent and ink print their label on the front panel, as before; the card tone prints it on the tab by default (`labelOn` chooses either placement for any tone). A tab label is never truncated: the tab widens to fit it, up to the body width, then the label compresses. The tab belongs to the back panel, so once the folder opens and a sheet stands in front of it, the label prints on the front panel instead (never a fragment beside the sheet or painted over it). An optional `sublabel` prints on the front panel and moves with it as the folder opens; front-panel type is placed with the exported `frontType`, which follows the panel (`frontPlane`) but keeps the glyphs' proportions.

`Folder` accepts optional SVG children in its 260×220 space, between the back and front panels. Existing calls retain the original sheet. `@jbm/folder-contents` composes this slot with rigid nested folders and documents. `open`, per-entry `reveal`, per-entry `documentReveal`, and group `lift` are independent controls. Empty entries and an empty sheet label produce an empty folder. More entries tighten packing instead of changing the folder's size. Hidden geometry is complete and clipped at the container bottom.

`@jbm/folder-carry` exports `tableFolderGeometry`, `folderGrip`, and `carriedFolderGeometry`. A transport path should begin and end at the corresponding `folderGrip` points. A drawer can supply its own `x`, `y`, `w`, `h`, `tabX`, and `tabWidth`. Optional tab dimensions interpolate too, avoiding an endpoint shape change when carrying between scales. `fill` sets the carried folder's color (vermilion by default; pass `color.card` for a plain cream folder or `color.ink`). The name prints once, fully opaque, for the whole carry: on the tab for light fills (card and drawer shades, as the Doorways board files them) and on the front panel for vermilion and ink, where it stays clear of the pinch on the tab. `labelOn` overrides the place; the default colour is ink or card, whichever contrasts more with the fill (at least 4.5:1 on every palette fill).

Install `@jbm/mano` separately to add a hand. Its optional `anchor` is in the Hand artwork's 30×29 coordinate system; `{ x: 6, y: 10 }` places the pinch opening at `at`. Rotation occurs around that contact point. Omit `anchor` to preserve the existing placement behavior.

## Sheets under stress and torn sheets

`@jbm/paper` takes an optional `tension` (0–1) and `tab`. Tension is a quantity on the sheet, not a pose of the hands that pull it: each corner in `pull` sends two short, soft creases inward (the longer at most 14% of the sheet's shorter side). They start at the pulled corner itself and spread apart from there: no two meet. They lie under the writing, and result boxes and tables are filled with the stock, so a crease never shows through an input box and a stressed page never reads as crossed out. Past 0.6 a notch tears into the sheet at `seam` (a y in stage px) from `seamSide`: a short frayed wedge (about a seventh of the width), widest at the edge and narrowing into a crack, already clearly visible at 0.7. The tear cuts the sheet itself, writing included, so its mouth shows whatever lies underneath, with a thin band of the upper lip's shadow inside it; its lips are ink on cream stock and a cream hairline on vermilion or ink stock. The tab is a pestaña fixed behind the top edge in the sheet's own stock; `reveal` slides it out from behind the sheet, its label fades in whole once most of its capitals show, and it is Geist 800 at 32 stage px by default. With tension 0 and no tab, Paper renders its original markup unchanged. Hands stay separate: compose `Mano` at the pulled corners.

`@jbm/tear` cuts a `w` × `h` sheet at `seams` into strips. At progress 0 the strips tile the sheet exactly, with no visible seam; each strip then moves to its `pieces[i].to` offset and turn, optionally staggered. Its seam edges are frayed from the same seeded `frayEdge` that Paper's starting tear uses (fine, irregular grain on a slow wander with the odd fibre, never a regular zig-zag), so `Paper` at tension 1 and `Tear` with the same `seed`, `w`, and seam continue one edge. A strip parts from its neighbours before it drifts: `y` follows its progress and `x` and `rotate` follow its square, so the two torn edges of a seam separate as parallel copies instead of crossing. While a seam is still closed no shadow or line shows along it. The root stays `w` × `h`; reserve `tearBounds(props)`, the box every strip and its shadow stays inside at any progress. Writing is laid out once on the whole sheet (a node, or a render prop that receives each strip's `index`, `top`, and `bottom`) and clipped to each strip, so any register content tears along with the paper. Progress is not eased; ease it in the scene.

The gallery's Paper and Tear benches write a mixed `Register` on the sheet and tear it at `registerSeams`, so every strip carries whole bands. With other seam counts (up to four) the Tear bench cuts only clear rows of the page (a fray reach from every filled mark, 8px from every rule and box edge), so no torn edge cuts a table header or a bar into a black zig-zag, moves every strip but the last one up so no strip slides back into its neighbour, and sizes its stage from `tearBounds`. On ink stock the writing is card-coloured (`RegisterInk tone="ink"`).

## Thread and video print

`@jbm/hilo` is the ink thread from the Doorways film: an SVG `<g>` tied from `from` to `to` in the parent SVG's units. It has no arrowheads. `curve="s"` leaves and arrives level (a line of writing tied to a folder tab), with `bend` clamped to 0–1 so it never hooks around its own knots; `curve="arc"` bows sideways by `bend`. `draw` lays it by arc length. With `snapAt`, the same `draw` first lays the thread (0 → snapAt) and then snaps it (snapAt → 1): the thread parts at `breakAt`, the two ends recoil about a fifth of its length apart (never more than 90 units, or 20 widths for a thick thread), each end is cut square, and according to `fray` it splits into two or three short tapered strands that tile the cut and run straight on, at most about 1.5 widths long. `slack` sags a tied thread and lets snapped ends hang; a limp snapped arc loses its bow, so both ends droop. Both ends stay tied: the first piece always starts at `from`, and once laid the last piece ends at `to`, with the anchor tangents unchanged. `notch` tints the broken ends themselves: the last few units of each piece, along its curve at the thread's width, and their strands, so the snapped thread reads as two broken ends rather than a thread with a bead; it is the only accent the thread draws. `hiloGeometry` returns the exact cubics it draws.

`@jbm/video-print` composes `Paper` and `PunchedTag` unchanged. The 16:9 frame is a pale sketch (an opaque tint, the same with or without the sheet, an ink outline, head and shoulders), never a solid block. The ink scrub bar advances with `scrub` and leaves a tick at each mark it reaches. `link` hangs a mono URL tag over the bottom edge, meaning the page was opened (`opened` fades it in as it settles up into place from just below, never crossing the date line); a long URL ends in an ellipsis rather than passing the sheet's right edge. `videoPrintLayout(props, at)` returns the mark points on the rule, the tag hole, and `bounds` (the sheet plus the tag's overhang) in stage coordinates, so a Hilo can tie on as the tick appears.

The Hilo bench's *Thread to drawer* scene composes these pieces without new components: each `VideoPrint` mark (`videoPrintLayout`) and each prose `Register` source line (from its right end, a `registerLayout` cell's `lead`) ties to the left edge of a `Cajon` tab (`cajonLayout(...).folders`), more than a knot's radius clear of its name, all in one stage px space. The print sits above the page: its ticks tie to the three oldest tabs, which stand above the rim, and the source lines to the three newest; a thread into a tab below the rim passes behind the side wall, which is drawn over its inside segment, so no thread crosses the wall's face or the drawer front. On phones the scene switches to a narrower stage with a smaller print, page, and drawer, so tab names stay legible. Each set is nested so no two threads cross. A mark's thread ties on as the scrub passes it, laying out from the tick and leaving the rule downward in a shallow arc. The drawer front masks whatever passes behind it, so as the drawer closes each thread goes over the rim and disappears behind the front at its own spot.

## Verification

Run `node --test scripts/paper-tear.test.mjs` for Paper's unchanged default markup, crease counts, lengths, and layering, tear thresholds and notch size, the tab label, fray bounds and determinism, exact strip tiling, seam filtering, destinations, and the shared edge between Paper and Tear.

Run `node --test scripts/design-video-components.test.mjs scripts/thread-components.test.mjs` for isolated installation, paper-coordinate and bounded-rendering checks, grapheme behavior, carry/contact invariants, pinned thread ends, snap continuity, and scrub marks. `pnpm consumer:check` exercises the components through both source copying and real registry installation.

Inspect open/closed folders, extracted documents, zero/one/crowded contents, horizontal/vertical tape, and separate control combinations at desktop and mobile widths. Check caption playback too: emphasized words now move vertically without scaling into their neighbors.

Source references: Design's `2026-09-23-opus-5-5-explainer/src/scenes/objetos.tsx` and `2026-09-21-agent-skills-explainer-video/storyboard-anaquel/desk/`. The registry deliberately removes those films' localization and narration dependencies.
