# Hilo (hilo)

> An ink thread tied between two points that lays out, sags, and snaps into frayed ends with an optional vermilion notch.

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

## Install

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

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

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

## API

### `Hilo` (component)

SVG <g> of an ink thread: one exact cubic Bézier while laying or tied, two pinned pieces after a snap (cut square, each end splitting into two or three short tapered strands), an optional vermilion tint on the broken tips, and ink knots at the tied points. No arrows. Controlled and deterministic: every quantity comes from props, with no timer or randomness. Render inside an <svg> whose units match your anchors.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `Pt` | required | Where the thread is tied first ({ x, y } in the parent SVG's user units). The first piece always starts exactly here. |
| `to` | `Pt` | required | Where the thread is tied last ({ x, y }, same units). Once laid, the last piece always ends exactly here, snapped or not. |
| `bend` | `number` | none | Curvature; 0 is straight. With curve `arc`, a sideways bow as a fraction of the from→to distance (positive bows left of travel: upward for a left-to-right thread). With curve `s`, the length of the level handles as a fraction of the horizontal distance (0.5 is a soft S), clamped to 0–1: shorter handles would point back past the anchors and hook the thread around its own knots. |
| `curve` | `HiloCurve` | none | `arc` bows the thread sideways; `s` leaves `from` and arrives at `to` level, like a line of writing tied to a folder tab. |
| `draw` | `number` | none | Progress 0–1. Without snapAt it lays the thread from `from` to `to` by arc length. With snapAt, 0 → snapAt lays it and snapAt → 1 snaps it: the ends recoil apart, fray, and hang by `slack`. Clamped; NaN is 0. |
| `width` | `number` | none | Thread stroke width in user units (minimum 0.5); defaults to the shared outline, stroke.outline (3). Knots are 1.4× it in radius; frayed strands split the cut between them; the notch tints each broken tip at this width. A snapped end is cut square. The bench's Width runs from 1.5, so the thread never renders as a faint hairline. |
| `snapAt` | `number` | none | The draw value (0–1) at which the laid thread snaps. Omit for a thread that never snaps. 0 starts fully laid, so draw drives only the snap. |
| `breakAt` | `number` | none | Where the thread parts, as a fraction of its length from `from`; clamped to 0.05–0.95. The gap opens symmetrically around it: about a fifth of the length, at most 90 units (20 widths for a thick thread), moved inward just enough to leave each end a stub longer than its knot and strands. |
| `fray` | `number` | none | 0–1: how each broken end frays: two short tapered strands below 0.5, three from 0.5. Their bases tile the square cut (so the thread splits into them with no step and no round cap), and each runs straight on along the thread, turning at most 8° toward gravity, no longer than about 1.5 widths (never under 3 units): a frayed end, never claws, legs, or a fan. 0 is a clean, square cut. |
| `slack` | `number` | none | 0–1. Before a snap, how far the thread sags under gravity (the middle drops up to a quarter of the from→to distance). As the ends recoil that sag hands over to the ends: fully snapped, the route no longer sags and each end hangs from its own anchor, tangent there, its free tip dropping up to half its piece's length. With slack the bow of an arc relaxes as the ends recoil, so limp ends always droop downward, never arch up, whichever way the arc bowed. |
| `notch` | `boolean` | none | Marks the break in vermilion on the broken ends themselves: the last max(5, 3 × width) units of each piece, along its own curve and at the thread's width, and their strands. Never a free capsule floating in the gap, so the snapped thread reads as two broken ends, not a thread with a bead. The only accent the thread draws. |
| `knots` | `boolean` | none | Small ink dots at the tied points: `from` as soon as any thread is laid, `to` once it is fully laid. |

### `hiloGeometry` (function)

The geometry Hilo draws, for tests and composites (a hand pinching the thread, a label at the break).

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `Pt` | required | Where the thread is tied first ({ x, y } in the parent SVG's user units). The first piece always starts exactly here. |
| `to` | `Pt` | required | Where the thread is tied last ({ x, y }, same units). Once laid, the last piece always ends exactly here, snapped or not. |
| `bend` | `number` | `0` | Curvature; 0 is straight. With curve `arc`, a sideways bow as a fraction of the from→to distance (positive bows left of travel: upward for a left-to-right thread). With curve `s`, the length of the level handles as a fraction of the horizontal distance (0.5 is a soft S), clamped to 0–1: shorter handles would point back past the anchors and hook the thread around its own knots. |
| `curve` | `HiloCurve` | `"arc"` | `arc` bows the thread sideways; `s` leaves `from` and arrives at `to` level, like a line of writing tied to a folder tab. |
| `draw` | `number` | `1` | Progress 0–1. Without snapAt it lays the thread from `from` to `to` by arc length. With snapAt, 0 → snapAt lays it and snapAt → 1 snaps it: the ends recoil apart, fray, and hang by `slack`. Clamped; NaN is 0. |
| `width` | `number` | `stroke.outline` | Thread stroke width in user units (minimum 0.5); defaults to the shared outline, stroke.outline (3). Knots are 1.4× it in radius; frayed strands split the cut between them; the notch tints each broken tip at this width. A snapped end is cut square. The bench's Width runs from 1.5, so the thread never renders as a faint hairline. |
| `snapAt` | `number` | none | The draw value (0–1) at which the laid thread snaps. Omit for a thread that never snaps. 0 starts fully laid, so draw drives only the snap. |
| `breakAt` | `number` | `0.5` | Where the thread parts, as a fraction of its length from `from`; clamped to 0.05–0.95. The gap opens symmetrically around it: about a fifth of the length, at most 90 units (20 widths for a thick thread), moved inward just enough to leave each end a stub longer than its knot and strands. |
| `fray` | `number` | `0.6` | 0–1: how each broken end frays: two short tapered strands below 0.5, three from 0.5. Their bases tile the square cut (so the thread splits into them with no step and no round cap), and each runs straight on along the thread, turning at most 8° toward gravity, no longer than about 1.5 widths (never under 3 units): a frayed end, never claws, legs, or a fan. 0 is a clean, square cut. |
| `slack` | `number` | `0` | 0–1. Before a snap, how far the thread sags under gravity (the middle drops up to a quarter of the from→to distance). As the ends recoil that sag hands over to the ends: fully snapped, the route no longer sags and each end hangs from its own anchor, tangent there, its free tip dropping up to half its piece's length. With slack the bow of an arc relaxes as the ends recoil, so limp ends always droop downward, never arch up, whichever way the arc bowed. |
| `notch` | `boolean` | `false` | Marks the break in vermilion on the broken ends themselves: the last max(5, 3 × width) units of each piece, along its own curve and at the thread's width, and their strands. Never a free capsule floating in the gap, so the snapped thread reads as two broken ends, not a thread with a bead. The only accent the thread draws. |
| `knots` | `boolean` | `true` | Small ink dots at the tied points: `from` as soon as any thread is laid, `to` once it is fully laid. |

Returns: { base, length, lay, recoil, snapped, width, pieces, inked, strands, notch, knots, knotRadius }: base is the resting cubic [start, handle, handle, end]; lay and recoil are the two phases (0–1); pieces are the whole laid or snapped cubics (pieces[0][0] is always `from`, and when laid the last piece ends at `to`); inked are the pieces as drawn in ink, each broken end short of its tint; strands are tapered strand outlines [base corner, point, base corner]; notch is the list of vermilion tints (the exact ends of the pieces), empty without `notch`; knots are the tied points. A thread laid to within six widths of `to` counts as laid, so its far knot shows.

### `cubicPoint` (function)

A point on a cubic Bézier, for placing things along hiloGeometry's pieces.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `c` | `HiloCubic` | required | Cubic [start, handle, handle, end]. |
| `t` | `number` | required | Curve parameter 0–1 (not arc length). |

Returns: { x, y } in the cubic's units.

### `HiloProps` (type)

Props of Hilo and hiloGeometry.

### `HiloCurve` (type)

"arc" | "s": the curve family bend shapes.

### `HiloCubic` (type)

A cubic Bézier as four points: start, two handles, end.

## Stage

fluid: Spans its anchors: the box from `from` to `to`, plus the bow (bend × distance for `arc`), the sag (up to slack × a quarter of the distance below the chord), and after a snap the hanging ends (up to half of each piece below its anchor, replacing the sag). Knots add 1.4 × width around each anchor. Size the parent SVG for those extremes.

## Examples

### Tie a line of writing to a folder tab

```tsx
import { Hilo } from "@/jbm/ui/hilo"

declare const progress: number
// Draw it over the stage, in the same units as your sheet and drawer.
<svg viewBox="0 0 1920 1080" style={{ position: "absolute", inset: 0 }}>
  <Hilo from={{ x: 520, y: 402 }} to={{ x: 1340, y: 236 }} curve="s" bend={0.5} draw={progress} />
</svg>
```

### Snap into a vermilion gap

```tsx
import { Hilo } from "@/jbm/ui/hilo"

declare const progress: number
// draw 0 → 0.5 lays the thread; 0.5 → 1 snaps it.
<svg viewBox="0 0 500 200">
  <Hilo from={{ x: 40, y: 100 }} to={{ x: 460, y: 100 }} draw={progress} snapAt={0.5} breakAt={0.4} fray={0.6} notch />
</svg>
```

### Thread from a drawer's folder tab

```tsx
import { Hilo } from "@/jbm/ui/hilo"
import { Cajon, cajonLayout } from "@/jbm/motion/cajon" // install @jbm/cajon separately

const drawer = { x: 520, y: 10, open: 1, folders: [{ name: "Taylor 1911" }] }
const tab = cajonLayout(drawer).folders[0].anchor
<svg viewBox="0 -260 1000 700">
  <Cajon {...drawer} />
  <Hilo from={{ x: 60, y: 120 }} to={tab} curve="s" bend={0.5} slack={0.1} />
</svg>
```

## QA

- Drag Draw from 0 to 1 without a snap: the thread grows from `from` along one smooth curve, the `from` knot appears first, and the `to` knot only when it arrives.
- Turn on the snap and drag past 50%: at the snap the two pieces coincide with the tied thread (no jump), then recoil apart; `from` and `to` never move.
- Snapped at the bench defaults reads as broken at a glance: two slack ends apart, each a square cut splitting into short strands, the broken tips tinted vermilion along their own curve at the thread's width (no floating bar or bead in the gap). Fray 0 is a clean square cut; 1 gives three strands per end that tile the cut, straight on along the thread, never claws, legs, or a fan.
- Slack 0 keeps the snapped ends on the original line (the rompe look); 1 lets them hang limply as two ends, each from its own anchor, never one deep V. With Curve arc, Slack Limp, both halves droop (never arch up). The tints stay on the tips at every slack and are the only vermilion.
- Try Break point 5% and 95%, Bend at both ends of its range (−0.3 to 0.3 for arc, 0 to 1 for S), both curve families, Slack 1, and Width 1 and 6 at 8× zoom: nothing leaves the viewBox, no S hooks around its knots at any width, and both tints sit on the tips at every combination.
- Place the anchors on real objects (a Cajon tab from cajonLayout, a VideoPrint mark from videoPrintLayout) and check the knots land on them. In the bench's Thread to drawer scene, knots sit on each tab's left edge, more than a knot's radius clear of its name; a thread into a tab below the rim passes behind the side wall (the wall is drawn over its inside segment) and never across the wall's face or the drawer front; no two threads cross; closing the drawer hides each thread behind the front at its own spot. On a phone the scene uses a narrower stage, so tab names stay legible.

## Family

Paper & writing

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

Imported in examples:

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