Code-first video & image, rendered natively on WebGPU.
Framefields
Code-first video engine on native WebGPU (Dawn) in Node, no browser. pnpm + turbo monorepo, Node >=22, ESM, Biome (tabs, double quotes), tsdown builds, vitest tests. Rendering needs a GPU. Our aim is to improve the engine harness: no cheating or workarounds.
Working rules
- Be brave; we can change anything. Aim for engineering elegance, not just goal completion.
- Debug to the root cause. If a workaround is the only option, stop and ask.
- No
any. Named exports unless a default is required. Top-of-file imports (noawait importunless required). Pass the cyclomatic complexity lint. - pnpm only; never hand-edit
pnpm-lock.yaml. - Never run bare
tsc(it emits into source). Use the package script (tsdown, ortsc --noEmit -p .). - Render scripts end with
process.exit. - Plain console output, no colors. Don't use the user's name. Final answers concise.
- Keep this file current when structure or dev patterns change but do not bloat it.
Repo map
packages/framefields: public SDK.Composition,Layer.*,LayerAnimation,Signal, effects (src/effects/classes.ts),FontManager,renderFrameGrid.src/index.tsis the export surface. CLI insrc/cli/(init,add,list,fonts add|list,check,api);checkisolates builders in an IPC worker,--renderadds GPU smoke checks, andapireads the build-generated type catalog.initnever prompts or overwrites, and its file templates are strings intemplates.ts(a test parses them).packages/components: the component registryframefields addcopies into user projects (shadcn-style).defineComponent/bindcontract insrc/core/contract.ts, shared helpers insrc/core/(keys, color, layout, surface, theme). Components import onlyframefieldsand../core. Registry items declare font needs (e.g. emoji); CLI fonts are pinned by URL, size and SHA-256 incli/fonts.ts. Prop docs incomponents.jsonare generated (drift test). Tree-shake size budgets are tested.packages/compositions: Yoga layout (utils/layout/resolve-layout.ts), program schema (program/schema.ts), lint (program/lint.ts), animation/evaluator.packages/webgpu-renderers: WGSL shaders, 2D/3D pipelines, Slug text (src/slug/), audio DSP.packages/renderer: headless Node renderer (Dawn, WebCodecs/mediabunny).packages/vision-sam: SAM 2.1 Tiny/Small and SAM 3 trackers (Apache-2.0 code; SAM 3 weights need runtime SAM License acceptance), an optional peer offramefields.clip-vision.tsimports it only forcomp.vision(..., { sam2 | sam3 }); keep runtime imports of it out offramefields(types only). Pins insrc/models/registry.ts.packages/core: shared types,Effectbase, signals,emojiPresentation(the one UTS #51 rule used by layout, preload and lint).- Others:
renderers,media,node-sdk,server-utils,client-utils,tensor-webgpu,vision,tsconfig. nodes/node-*: one VFX/audio/layout node each (src/shared/,src/renderers/,src/index.ts). Onlynode-compositorhas aSKILL.md; update it when Compositor behavior changes (guarded byskillmd-check.test.ts).apps/renderer-service: HTTP render service (Docker, RunPod).examples/NN_*: reference films. Study19_framefields_film(structure),22_framefields_launch(lyric sync),28_physics_dancer(physics, vision, GPU particles) before writing one.plugins/framefields/skills/framefields{,-compose,-effects,-render,-vision,-cloud}: agent skills, symlinked from.agents/skillsand.Codex/skills.- Package
exportshave adevelopmentcondition pointing atsrc/; otherwisedist/, sopnpm buildafter changing a dependency. - Docs site is a separate repo:
/Users/okanaslankan/framefields-dev/docs(Astro Starlight).docs/labpins the publishedframefieldsversion and builds the component demos; deploy withpnpm run deploy.
Commands
- Build:
pnpm build, orpnpm --filter <name> build. - Test:
pnpm --filter <name> test(packages/renderer:test:vitest). Rootpnpm testis slow. - Lint:
pnpm exec biome check --write <files>(lefthook runs it on commit). - Example:
pnpm --filter @framefields/example-19-framefields-film assets|render|test|typecheck. - Component gallery:
pnpm --filter framefields gallery. - Skills: after engine API changes update the owning skill;
pnpm --filter framefields testfails on stale generated effects or catalog.effects-catalog.mdis generated bypnpm run sync:effects-catalog; never hand-edit. - Releases: changesets (
.changeset/).
Local-only files
Gitignored, never commit: assets/fonts, *.mp4/mp3/wav/png/jpg, *.onnx, scratch*/, examples/output/, .hermes/, .env* (never print secrets). Put probes and logs under scratch/ or output/.