# Fieldnotes motion library — review-stage toolkit

Source-mapped editing recipes sharing a typed Remotion renderer. This package is
an extension of the approved fieldnotes benchmark, not a replacement. No entry
is a fidelity pass merely because it appears in the catalog or renders.

Start with `AGENT_GUIDE.md`; the project-local skill is in
`.agents/skills/fieldnotes-editing/SKILL.md`.

## Run

Requirements: Node 22.18+, FFmpeg/FFprobe, and a Chromium executable. Remotion and
React versions are pinned in `package-lock.json`. Set
`REMOTION_BROWSER_EXECUTABLE` when the browser is not discoverable on `PATH`.
The render process does not download external assets or a browser.
Its pinned renderer integration binds the local asset server to loopback. This
also avoids the sandbox's `uv_interface_addresses` failure seen with the bare
Remotion CLI. Use this package's `npm run render` command; the compatibility path
is covered by the real-Chromium smoke test and is version-specific.

```bash
npm ci
npm run typecheck
npm test
npm run catalog -- search --family camera --duration '1..6'
npm run catalog -- show RECIPE_ID
npm run render -- --recipe RECIPE_ID --variant default --out out/original.mp4
npm run render -- --recipe RECIPE_ID --variant adaptation --out out/adaptation.mp4
npm run verify -- out/original.mp4
```

Replace `RECIPE_ID` with a returned ID. Search is machine-readable and supports
intent, treatment, film, duration, input and neighbor filters. `show` loads one
full recipe. Copy its documented content object to your own JSON and pass
`--content my-content.json`; do not patch the component implementation. Output
files are never overwritten. Use a new output path for another revision.

Custom JSON must be inside the toolkit project. Keep it under `inputs/` and
preserve its relative location with the output and manifest when moving the
toolkit. `docs/PORTABILITY.md` describes relocation checks, symlink limits,
external-input migration and historical manifests.

For a parser or pipeline, use `npm --silent run catalog -- search QUERY` or
`npm --silent run catalog -- show RECIPE_ID`. `--silent` removes npm's launcher
banner; the CLI's stdout is then a single JSON document.

## Assemble an edit

The `EditInput` type in `src/types.ts` accepts a name, output fps rational,
`shots` containing complete `RenderInput` objects, and one explicit `joins`
decision between each adjacent pair. A shot contains the selected `recipe` JSON
and its substituted `content`, plus optional native-frame opening/closing holds.
Use the returned recipe objects; do not invent their source tracks.

```ts
import type {EditInput, RenderInput} from './src/types.ts';

export const makeEdit = (first: RenderInput, second: RenderInput): EditInput => ({
  name: 'Material study',
  fps: {numerator: 30, denominator: 1},
  shots: [first, second],
  joins: [{
    kind: 'cut',
    continuity: 'reset',
    reason: 'The title gives way to the established work surface.',
    equalSlots: [],
  }],
});
```

Serialize that object as `my-edit.json`, then:

```bash
npm run render -- --edit my-edit.json --out out/my-edit.mp4
npm run verify -- --edit my-edit.json --out out/my-edit.mp4
```

A `match` join requires compatible entry/exit field types and at least one pair
of equal content slots. This catches broken asset/text continuity, not all
perceptual discontinuities; inspect every join in the rendered edit. Durations
are converted in seconds, with cumulative boundaries rounded to the output
clock. A mixed-fps edit is a labeled adaptation, not a native source comparison.
All shot canvases must match; there is no implicit crop, stretch or scale-to-fit.

## Assets and evidence

Only original/permitted content belongs under `public/`. The licensed Geist font
is included with `public/fonts/OFL.txt`; it is not the identified source font.
Per-recipe declarations distinguish measurements, estimates, implementation
choices and unresolved source differences. Source films and research comparisons
are not bundled as editable production assets.

Read `ASSET_RIGHTS.md` for the separately credited NASA photographs, font license,
and the limits of the prototype's declaration-based permission check.

The output manifest binds selected code, recipe, content and asset hashes to the
MP4. It is a reproducibility record, not a cryptographic signature or visual
approval. Mechanical verification checks decoding, dimensions, frame count,
cadence, silence and those bindings. Fresh-context moving-source review and
independent content adaptation remain separate requirements.

The library is under review. Publication requires explicit approval and must
preserve the existing `openai-film-fieldnotes-100` Cloudflare Pages project. This
toolkit does not authorize the final all-hands presentation.

## Public draft download

Read `DOWNLOAD_TOOLKIT.md` for verified archive merging, dependency setup,
selected-asset limitations and licenses. Artifact history is intentionally
omitted locally; `public-guide/index.html` opens the published review.