# SceneGeometry (scene-geometry)

> Shared points, bounds, arc-length path interpolation and travel tilt.

- Entry: component
- Category: Foundations
- Preview capabilities: none (still preview)
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/scene-geometry
- JSON: https://jbm-ui.bns.studio/catalog/scene-geometry.json
- Registry item: https://jbm-ui.bns.studio/r/scene-geometry.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/scene-geometry
```

## 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/scene-geometry.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/lib/geometry.ts` | `src/jbm/lib/geometry.ts` | `@/jbm/lib/geometry` |

## API

### `unit` (function)

Clamps a progress value to 0–1, treating non-finite input as 0.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | required | Any number, usually a progress value. |

Returns: The value clamped to 0–1, or 0 when it is NaN or infinite.

### `pointOn` (function)

Point at a fraction of a polyline's total length (arc-length, not per segment). Repeated points and a one-point path are valid; an empty path throws.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `readonly Pt[]` | required | Polyline points in the caller's coordinate space; at least one. |
| `progress` | `number` | required | 0–1 fraction of the total length; clamped with unit. |

Returns: A new { x, y } on the path; the last point at 1 or when the path has no length.

### `pathTilt` (function)

Restrained travel tilt from the direction of travel around a progress point (sampled ±0.01), measured against horizontal regardless of left/right direction.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `readonly Pt[]` | required | Polyline points, as for pointOn. |
| `progress` | `number` | required | 0–1 fraction of the total length. |

Returns: Degrees clamped to −18…18; positive when the path descends on screen (y grows).

### `Pt` (type)

A point { x, y } in scene (SVG user) units.

### `Box` (type)

A Pt plus w and h: the top-left corner and size of a rectangle.

## Stage

n/a: Geometry helpers only; nothing renders. The gallery draws an example path to illustrate the points.

## Examples

### Place and tilt an object along a path

```tsx
import { pointOn, pathTilt } from "@/jbm/lib/geometry"

const path = [{ x: 40, y: 170 }, { x: 220, y: 50 }, { x: 460, y: 130 }]
const at = pointOn(path, 0.5)
const angle = pathTilt(path, 0.5)
<g transform={`translate(${at.x} ${at.y}) rotate(${angle})`} />
```

## QA

- pointOn at 0, 0.5, and 1 returns the first point, the arc-length midpoint, and the last point; out-of-range progress clamps.
- A path with repeated points or a single point never returns NaN.
- pathTilt stays within ±18° on steep segments; objects moving right-to-left tilt the same way as left-to-right on the same slope.

## Related

Installed by: 18 items (see https://jbm-ui.bns.studio/catalog.json).

## 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
