Code-first video & image, rendered natively on WebGPU.
feat(cli): render and preview by name, here or in the cloud
okanasl7edabea03e98
diff --git a/.changeset/local-render-preview.md b/.changeset/local-render-preview.mdnew file mode 100644index 00000000..357d2226--- /dev/null+++ b/.changeset/local-render-preview.md@@ -0,0 +1,5 @@+---+"framefields": minor+---++`framefields render <name>` renders a named render on this machine and `framefields preview <name>` plays it in the browser, reading the same `framefields.json` render as `--cloud`, so a render writes the same file wherever it runs. Both load the module with the project's own tsx and framefields. A local render first downloads pinned assets that are missing; the preview streams them from their bucket instead (redirecting the page to the remote's `publicUrl` or a signed URL, and mixing the soundtrack over HTTP), so an agent in a cloud sandbox previews footage without downloading it. `init`'s `render` and `preview` scripts now call the CLI.diff --git a/CLAUDE.md b/CLAUDE.mdindex b93594d4..590d6099 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -13,13 +13,13 @@ Code-first video engine on native WebGPU (Dawn) in Node, no browser. pnpm + turb- 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.ts` is the export surface. CLI in `src/cli/` (`init`, `add`, `list`, `fonts add|list`, `assets add|push|pull|status`, `check`, `renders`, `render --cloud`); `framefields.json` (`cli/config.ts`) holds the components folder, fonts, named `renders` that the CLI, `renderCloud` and the dashboard pick by name, and `storage` remotes plus sha256-pinned `assets`; `framefields/cloud` (`renderCloud`) is the GPU-free client for api.framefields.dev; `init` never prompts or overwrites, and its file templates are strings in `templates.ts` (a test parses them).+- `packages/framefields`: public SDK. `Composition`, `Layer.*`, `LayerAnimation`, `Signal`, effects (`src/effects/classes.ts`), `FontManager`, `renderFrameGrid`. `src/index.ts` is the export surface. CLI in `src/cli/` (`init`, `add`, `list`, `fonts add|list`, `assets add|push|pull|status`, `check`, `renders`, `render [--cloud]`, `preview`; local render and preview run `cli/local-worker.ts` with the project's own tsx and framefields); `framefields.json` (`cli/config.ts`) holds the components folder, fonts, named `renders` that the CLI, `renderCloud` and the dashboard pick by name, and `storage` remotes plus sha256-pinned `assets`; `framefields/cloud` (`renderCloud`) is the GPU-free client for api.framefields.dev; `init` never prompts or overwrites, and its file templates are strings in `templates.ts` (a test parses them).- `packages/components`: the component registry `framefields add` copies into user projects (shadcn-style). `defineComponent`/`bind` contract in `src/core/contract.ts`, shared helpers in `src/core/` (keys, color, layout, surface, theme). Components import only `framefields` and `../core`. Registry items declare font needs (e.g. emoji); CLI fonts are pinned by URL, size and SHA-256 in `cli/fonts.ts`. Prop docs in `components.json` are 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), private; `framefields` bundles it as a lazy chunk (`clip-vision.ts` imports it dynamically for `comp.vision(..., { sam2 | sam3 })`; `index.ts` re-exports types only) and exposes the trackers as `framefields/sam`. No weights ship; `packages/framefields/NOTICE.md` covers their licenses. Pins in `src/models/registry.ts`.-- `packages/storage`: content-addressed assets on any S3-compatible bucket (R2 first): manifest format, SigV4 client (aws4fetch), verified downloads. Shared by the CLI (`framefields/storage`) and the render worker, which fetches pinned assets after LFS.+- `packages/storage`: content-addressed assets on any S3-compatible bucket (R2 first): manifest format, SigV4 client (aws4fetch), verified downloads, and the locator the preview uses to redirect missing pinned files to their bucket. Shared by the CLI (`framefields/storage`), the preview and the render worker, which fetches pinned assets after LFS.- `packages/core`: shared types, `Effect` base, 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`). Only `node-compositor` has a `SKILL.md`; update it when Compositor behavior changes (guarded by `skillmd-check.test.ts`). Effect renderers declare `reach` and `maxPixelScale` (node-sdk) when they can: without `maxPixelScale` a scaled-up leaf using the effect stays at layout resolution.diff --git a/apps/renderer-service/src/git/assets.ts b/apps/renderer-service/src/git/assets.tsindex af6af8a5..46f02e57 100644--- a/apps/renderer-service/src/git/assets.ts+++ b/apps/renderer-service/src/git/assets.ts@@ -4,12 +4,10 @@ import path from "node:path";import {type AssetEntry,AssetError,- type AssetManifest,downloadVerified,hashFile,ManifestError,- parseAssets,- parseStorage,+ readProjectManifest,readUrl,type StorageConfig,} from "@framefields/storage";@@ -96,22 +94,11 @@ export async function fetchAssets(};}-async function readManifest(- workdir: string,-): Promise<{ storage?: StorageConfig; assets?: AssetManifest } | undefined> {- const file = path.join(workdir, "framefields.json");- if (!existsSync(file)) return undefined;+async function readManifest(workdir: string) {try {- const raw = JSON.parse(await fs.readFile(file, "utf8")) as {- storage?: unknown;- assets?: unknown;- };- if (raw.assets === undefined) return undefined;- const storage =- raw.storage === undefined ? undefined : parseStorage(raw.storage);- return { storage, assets: parseAssets(raw.assets, storage) };+ return await readProjectManifest(workdir);} catch (err) {- if (err instanceof ManifestError || err instanceof SyntaxError)+ if (err instanceof ManifestError)throw new RenderError("ASSET_MANIFEST_INVALID", err.message, {hint: "`npx framefields assets status` reads the same file locally.",});diff --git a/packages/framefields/src/cli.ts b/packages/framefields/src/cli.tsindex 4e96ec20..24c52dcc 100644--- a/packages/framefields/src/cli.ts+++ b/packages/framefields/src/cli.ts@@ -9,7 +9,9 @@* npx framefields fonts list the fonts you can install* npx framefields assets add|push|pull|status media on your own bucket* npx framefields renders the renders named in framefields.json+ * npx framefields render <name> render on this machine's GPU* npx framefields render <name> --cloud render on api.framefields.dev+ * npx framefields preview <name> play it in the browser*/import { readFileSync } from "node:fs";import { join, relative, resolve } from "node:path";@@ -35,6 +37,7 @@ import {type PackageManager,shownPath,} from "./cli/init.js";+import { runLocal } from "./cli/local.js";import { openRegistry } from "./cli/registry.js";import { AI_DASHBOARD } from "./cli/templates.js";@@ -67,13 +70,19 @@ Commands:assets pull Download missing assets, checked against their sha256.assets status Which assets are here, missing or changed.renders List the renders named in framefields.json.- render [name|entry] --cloud- Render on api.framefields.dev from the pushed commit of- this git repo, and download the video. Needs- FRAMEFIELDS_API_KEY. A render named in framefields.json+ render [name|entry]+ Render on this machine: a render named in framefields.json(its fields are the defaults; flags override them), or amodule (--export defaults to buildFilm). Without either,- the project's only named render.+ the project's only named render. Pinned assets missing+ here are downloaded first.+ render [name|entry] --cloud+ The same render on api.framefields.dev, from the pushed+ commit of this git repo, downloaded to the same file.+ Needs FRAMEFIELDS_API_KEY.+ preview [name|entry]+ Play it in the browser (localhost, WebGPU). Pinned assets+ that aren't here stream from their bucket.Options for check:--export <name> Composition or builder export (default buildFilm).@@ -83,6 +92,10 @@ Options for check:--warnings-as-errors Fail on lint warnings.--json Machine-readable check, component list, or font list result.+Options for render and preview:+ --export, --select, --codec, --quality and --output (render) override the+ named render's fields, locally and with --cloud.+Options for render --cloud:--workers <n|auto> 1 (default) renders on one GPU. auto measures the filmfirst and splits it across as many GPUs as stay@@ -133,6 +146,8 @@ Examples:npx framefields add mouse-pointer focus-zoomnpx framefields fonts add emojinpx framefields assets add assets/footage+ npx framefields preview film+ npx framefields render filmnpx framefields render film --cloud --plan`;@@ -202,10 +217,30 @@ async function main(argv: string[]): Promise<number> {overwrite: values.overwrite,json: values.json,});+ if (command === "preview" || (command === "render" && !values.cloud)) {+ if (names.length > 1) {+ process.stderr.write(+ `Usage: framefields ${command} [name|entry] [--export <name>]\n`,+ );+ return 2;+ }+ return runLocal(+ command === "preview" ? "preview" : "render",+ {+ entry: names[0],+ export: values.export,+ select: values.select,+ codec: values.codec,+ quality: values.quality,+ output: values.output,+ },+ log,+ );+ }if (command === "render") {- if (names.length > 1 || !values.cloud) {+ if (names.length > 1) {process.stderr.write(- "Usage: framefields render [name|entry] --cloud [--workers auto] [--plan]\nLocal renders run your project's render script (`npm run render`).\n",+ "Usage: framefields render [name|entry] --cloud [--workers auto] [--plan]\n",);return 2;}diff --git a/packages/framefields/src/cli/assets.test.ts b/packages/framefields/src/cli/assets.test.tsindex f88a61f4..72bca3e5 100644--- a/packages/framefields/src/cli/assets.test.ts+++ b/packages/framefields/src/cli/assets.test.ts@@ -64,7 +64,7 @@ function fakeR2() {return new Response(null, {headers: { "content-length": String(body.length) },});- return new Response(body);+ return new Response(new Uint8Array(body));};return { fetch: handler as typeof fetch, objects, log };}diff --git a/packages/framefields/src/cli/check.ts b/packages/framefields/src/cli/check.tsindex 84ac3f74..5e7c0a9f 100644--- a/packages/framefields/src/cli/check.ts+++ b/packages/framefields/src/cli/check.ts@@ -1,9 +1,8 @@import { spawn } from "node:child_process";-import { createRequire } from "node:module";import { resolve } from "node:path";-import { fileURLToPath, pathToFileURL } from "node:url";import { type CheckReport, failedCheck } from "./check-result.js";import { ownVersion } from "./init.js";+import { projectNodeArgs } from "./project-node.js";export interface CheckOptions {/** Module path, resolved from the project working directory. */@@ -30,28 +29,8 @@ export async function runCheck(options: CheckOptions): Promise<CheckReport> {throw new Error("--timeout must be a positive integer in milliseconds");const fail = (code: string, message: string) =>failedCheck(entry, exportName, sdkVersion, code, message);- const source = import.meta.url.endsWith(".ts");- const args = source ? ["--conditions=development"] : [];- // TypeScript belongs to the consumer project; it is already in init's scaffold.- if (source || /\.[cm]?tsx?$/.test(entry)) {- try {- const require = createRequire(resolve("package.json"));- args.push("--import", pathToFileURL(require.resolve("tsx")).href);- } catch {- return fail(- "missing_ts_loader",- "Install the project's tsx dev dependency to check a TypeScript entry.",- );- }- }- args.push(- fileURLToPath(- new URL(- source ? "./check-worker.ts" : "./cli/check-worker.mjs",- import.meta.url,- ),- ),- );+ const args = projectNodeArgs(entry, "check-worker");+ if ("error" in args) return fail("missing_ts_loader", args.error);return new Promise((done) => {const child = spawn(process.execPath, args, {stdio: ["ignore", "pipe", "pipe", "ipc"],diff --git a/packages/framefields/src/cli/cloud.ts b/packages/framefields/src/cli/cloud.tsindex d81b1767..5598498c 100644--- a/packages/framefields/src/cli/cloud.ts+++ b/packages/framefields/src/cli/cloud.ts@@ -13,7 +13,12 @@ import {type CloudRenderStatus,renderCloud,} from "../cloud/index.js";-import { CONFIG_FILE, findRender, readConfig } from "./config.js";+import {+ CONFIG_FILE,+ findRender,+ type RenderSpec,+ readConfig,+} from "./config.js";export interface CloudCliOptions {/** A render named in framefields.json, or a module path. Optional when framefields.json has one render. */@@ -59,13 +64,7 @@ export async function runCloudRender(}const spec = target.name ? findRender(cwd, target.name) : undefined;const codec = (o.codec ?? spec?.codec ?? "h264") as "h264" | "vp9";- const outputPath =- o.output ??- spec?.output ??- path.join(- "output",- `${target.name ?? path.basename(target.entry ?? "").replace(/\.[^.]+$/, "")}.${codec === "vp9" ? "webm" : "mp4"}`,- );+ const outputPath = renderOutput(target, spec, codec, o.output);// A plan of a one-worker render would only ever say "one worker".const planWorkers =o.plan && (workers ?? spec?.workers ?? 1) === 1 ? "auto" : workers;@@ -143,6 +142,22 @@ export function renderCommand(o: CloudCliOptions): string {].join(" ");}+/** What a render named `name` (or the module `entry`) produces, wherever it runs. */+export function renderOutput(+ target: { name?: string; entry?: string },+ spec: RenderSpec | undefined,+ codec: string,+ output?: string,+): string {+ const base =+ target.name ?? path.basename(target.entry ?? "").replace(/\.[^.]+$/, "");+ return (+ output ??+ spec?.output ??+ path.join("output", `${base}.${codec === "vp9" ? "webm" : "mp4"}`)+ );+}+/*** What `framefields render [arg]` renders: a render named in framefields.json,* or a module path; with no argument, the project's only named render.@@ -158,7 +173,7 @@ export function pickRender(return {error: names.length? `Name the render: ${names.join(", ")}. \`framefields renders\` lists them.`- : `Name a module, e.g. \`framefields render src/film.ts --cloud\`, or add "renders" to ${CONFIG_FILE}.`,+ : `Name a module, e.g. \`framefields render src/film.ts\`, or add "renders" to ${CONFIG_FILE}.`,};}if (renders[arg]) return { name: arg };diff --git a/packages/framefields/src/cli/local-worker.ts b/packages/framefields/src/cli/local-worker.tsnew file mode 100644index 00000000..3a7382c0--- /dev/null+++ b/packages/framefields/src/cli/local-worker.ts@@ -0,0 +1,76 @@+/**+ * Runs a render or a preview of the user's module in its own Node process+ * (with the project's TypeScript loader), for `framefields render` and+ * `framefields preview`. Its options arrive over IPC; it reports back over+ * IPC and exits, since GPU and encoder threads keep Node alive otherwise.+ *+ * It uses the project's own framefields, as the cloud worker does: a second+ * copy of the engine next to the one the film imports would not share its+ * decoders.+ */+import { pathToFileURL } from "node:url";+import type { startPreview } from "../preview/index.js";+import { pickComposition } from "./pick-composition.js";++export interface LocalJob {+ mode: "render" | "preview";+ /** Absolute module path. */+ entry: string;+ export: string;+ /** File URL of the project's framefields entry (for the preview). */+ engine: string;+ args?: unknown;+ select?: string;+ /** render: where the video goes. */+ outputPath?: string;+ codec?: string;+ quality?: string;+ /** preview: the page's title. */+ title?: string;+}++export type LocalResult =+ | { ok: true; filePath?: string }+ | { ok: false; message: string };++async function run(job: LocalJob): Promise<LocalResult> {+ if (job.mode === "preview") {+ // The project's framefields: known only at runtime.+ const engine = (await import(job.engine)) as {+ startPreview: typeof startPreview;+ };+ const session = await engine.startPreview(+ { entry: job.entry, export: job.export },+ { title: job.title },+ );+ process.stdout.write(`Preview at ${session.url}\n`);+ await session.closed;+ return { ok: true };+ }+ const mod: Record<string, unknown> = await import(+ pathToFileURL(job.entry).href+ );+ const comp = await pickComposition(mod, job);+ const result = await comp.renderVideo({+ outputPath: job.outputPath,+ ...(job.codec && { codec: job.codec }),+ ...(job.quality && { quality: job.quality }),+ });+ await result.cleanup?.();+ return { ok: true, filePath: result.filePath };+}++process.once("message", (job: LocalJob) => {+ process.channel?.ref();+ run(job).then(+ (result) => process.send?.(result, () => process.exit(0)),+ (error: unknown) =>+ process.send?.(+ {+ ok: false,+ message: error instanceof Error ? error.message : String(error),+ } satisfies LocalResult,+ () => process.exit(1),+ ),+ );+});diff --git a/packages/framefields/src/cli/local.ts b/packages/framefields/src/cli/local.tsnew file mode 100644index 00000000..1f31c282--- /dev/null+++ b/packages/framefields/src/cli/local.ts@@ -0,0 +1,144 @@+/**+ * `framefields render [name|entry]` and `framefields preview [name|entry]`+ * on this machine. They read the same named renders in framefields.json as+ * `--cloud`, so a render goes to the same file wherever it runs.+ *+ * A local render first downloads pinned assets that are missing here; a+ * preview doesn't need to: the page streams them from their bucket.+ */+import { spawn } from "node:child_process";+import { createRequire } from "node:module";+import path from "node:path";+import { pathToFileURL } from "node:url";+import { AssetsError, megabytes, pullAssets } from "./assets.js";+import { pickRender, renderOutput } from "./cloud.js";+import { findRender, readConfig } from "./config.js";+import type { LocalJob, LocalResult } from "./local-worker.js";+import { projectNodeArgs } from "./project-node.js";++export interface LocalCliOptions {+ /** A render named in framefields.json, or a module path. */+ entry?: string;+ export?: string;+ select?: string;+ codec?: string;+ quality?: string;+ output?: string;+ /** Project folder. Default `process.cwd()`. */+ cwd?: string;+}++export async function runLocal(+ mode: LocalJob["mode"],+ o: LocalCliOptions,+ log: (line: string) => void,+): Promise<number> {+ const cwd = o.cwd ?? process.cwd();+ const target = pickRender(o.entry, cwd);+ if ("error" in target) {+ log(target.error);+ return 2;+ }+ const spec = target.name ? findRender(cwd, target.name) : undefined;+ const entry = path.resolve(cwd, spec?.entry ?? (target.entry as string));+ const codec = o.codec ?? spec?.codec ?? "h264";+ if (codec !== "h264" && codec !== "vp9") {+ log(`--codec must be h264 or vp9, not "${codec}".`);+ return 2;+ }+ const engine = projectEngine(entry);+ if (!engine) {+ log("framefields isn't installed in this project: `npm i framefields`.");+ return 2;+ }+ const job: LocalJob = {+ mode,+ entry,+ engine,+ export: o.export ?? spec?.export ?? "buildFilm",+ args: spec?.args,+ select: o.select ?? spec?.select,+ codec,+ quality: o.quality ?? spec?.quality,+ outputPath: path.resolve(cwd, renderOutput(target, spec, codec, o.output)),+ title: spec?.title ?? target.name,+ };+ if (mode === "preview" && (job.args !== undefined || job.select))+ log(+ "The preview calls the export without args or select; it shows what the export returns by default.",+ );+ if (mode === "render" && !(await ensureAssets(cwd, log))) return 1;+ const result = await runWorker(job, cwd);+ if (!result.ok) {+ log(result.message);+ return 1;+ }+ if (result.filePath)+ log(`Rendered ${path.relative(cwd, result.filePath) || result.filePath}`);+ return 0;+}++/** The framefields the film imports, resolved from its module. */+function projectEngine(entry: string): string | undefined {+ try {+ return pathToFileURL(createRequire(entry).resolve("framefields")).href;+ } catch {+ return undefined;+ }+}++/** Downloads pinned assets missing here; false (after saying why) when it can't. */+async function ensureAssets(+ cwd: string,+ log: (line: string) => void,+): Promise<boolean> {+ const assets = readConfig(cwd).config.assets ?? {};+ if (Object.keys(assets).length === 0) return true;+ try {+ const { downloaded, changed } = await pullAssets({ cwd, log });+ if (downloaded.length) {+ const bytes = downloaded.reduce((n, p) => n + (assets[p]?.size ?? 0), 0);+ log(+ `Downloaded ${downloaded.length} pinned assets (${megabytes(bytes)}).`,+ );+ }+ if (changed.length)+ log(+ `Rendering local edits of pinned assets: ${changed.join(", ")}. \`framefields assets add\` pins them for the cloud.`,+ );+ return true;+ } catch (err) {+ if (!(err instanceof AssetsError)) throw err;+ log(err.message);+ return false;+ }+}++function runWorker(job: LocalJob, cwd: string): Promise<LocalResult> {+ const args = projectNodeArgs(job.entry, "local-worker");+ if ("error" in args)+ return Promise.resolve({ ok: false, message: args.error });+ return new Promise((done) => {+ const child = spawn(process.execPath, args, {+ cwd,+ stdio: ["inherit", "inherit", "inherit", "ipc"],+ });+ let result: LocalResult | undefined;+ child.on("message", (message: LocalResult) => {+ result = message;+ });+ child.on("error", (error) => done({ ok: false, message: error.message }));+ child.on("close", (code, signal) =>+ done(+ result ??+ (signal === "SIGINT" || code === 130+ ? { ok: false, message: "Stopped." }+ : {+ ok: false,+ message: `The ${job.mode} exited without a result (code ${code}, signal ${signal}).`,+ }),+ ),+ );+ child.send(job);+ });+}diff --git a/packages/framefields/src/cli/pick-composition.test.ts b/packages/framefields/src/cli/pick-composition.test.tsnew file mode 100644index 00000000..84d2b0fa--- /dev/null+++ b/packages/framefields/src/cli/pick-composition.test.ts@@ -0,0 +1,51 @@+import { describe, expect, it } from "vitest";+import { Composition } from "../index.js";+import { pickComposition } from "./pick-composition.js";++const comp = (width: number) =>+ new Composition({ width, height: 36, fps: 10, durationFrames: 10 });++describe("pickComposition", () => {+ it("takes a Composition, or calls a builder with the render's args", async () => {+ const film = comp(64);+ expect(+ await pickComposition({ buildFilm: film }, { export: "buildFilm" }),+ ).toBe(film);+ const built = await pickComposition(+ { build: (args: { width: number }) => comp(args.width) },+ { export: "build", args: { width: 128 } },+ );+ expect(built.toSpec().width).toBe(128);+ });++ it("picks one of several by select, as the cloud worker does", async () => {+ const a = comp(64);+ const b = comp(96);+ expect(+ await pickComposition(+ { cuts: () => ({ wide: a, tall: b }) },+ { export: "cuts", select: "tall" },+ ),+ ).toBe(b);+ expect(+ await pickComposition(+ { plan: { outputs: [{ name: "teaser", composition: a }] } },+ { export: "plan" },+ ),+ ).toBe(a);+ await expect(+ pickComposition({ cuts: { wide: a, tall: b } }, { export: "cuts" }),+ ).rejects.toThrow(+ 'returns several compositions (wide, tall): name one with "select"',+ );+ });++ it("names a missing or wrong export", async () => {+ await expect(+ pickComposition({ other: 1 }, { export: "buildFilm" }),+ ).rejects.toThrow('no export named "buildFilm". Exports: other');+ await expect(+ pickComposition({ buildFilm: 42 }, { export: "buildFilm" }),+ ).rejects.toThrow("must be a Composition");+ });+});diff --git a/packages/framefields/src/cli/pick-composition.ts b/packages/framefields/src/cli/pick-composition.tsnew file mode 100644index 00000000..40e6fd44--- /dev/null+++ b/packages/framefields/src/cli/pick-composition.ts@@ -0,0 +1,63 @@+import type { Composition } from "../index.js";++export interface PickOptions {+ export: string;+ args?: unknown;+ select?: string;+}++/**+ * The composition an export yields, read the way the cloud worker reads it:+ * a Composition, a function returning one (called with `args`), or several+ * by name (a record, or `{ outputs: [{ name, composition }] }`) picked with+ * `select`.+ */+export async function pickComposition(+ mod: Record<string, unknown>,+ job: PickOptions,+): Promise<Composition> {+ if (!(job.export in mod))+ throw new Error(+ `The module has no export named "${job.export}". Exports: ${Object.keys(mod).join(", ") || "none"}.`,+ );+ let value = mod[job.export];+ if (typeof value === "function" && !isComposition(value))+ value = await (value as (args: unknown) => unknown)(job.args);+ if (isComposition(value)) return value;+ const named = namedOutputs(value);+ if (!named)+ throw new Error(+ `Export "${job.export}" must be a Composition, a function returning one, or compositions by name.`,+ );+ const names = Object.keys(named);+ const pick = job.select ?? (names.length === 1 ? names[0] : undefined);+ if (!pick || !named[pick])+ throw new Error(+ `Export "${job.export}" returns several compositions (${names.join(", ")}): name one with "select".`,+ );+ return named[pick];+}++function namedOutputs(value: unknown): Record<string, Composition> | undefined {+ if (typeof value !== "object" || value === null) return undefined;+ const outputs = (value as { outputs?: unknown }).outputs;+ const entries = Array.isArray(outputs)+ ? outputs.map((o: { name?: string; composition?: unknown }, i) => [+ o?.name ?? `output-${i}`,+ o?.composition,+ ])+ : Object.entries(value);+ if (!entries.length || !entries.every(([, c]) => isComposition(c)))+ return undefined;+ return Object.fromEntries(entries) as Record<string, Composition>;+}++/** Duck-typed: the project may load its own copy of framefields. */+function isComposition(value: unknown): value is Composition {+ return (+ typeof value === "object" &&+ value !== null &&+ typeof (value as Composition).renderVideo === "function" &&+ typeof (value as Composition).toSpec === "function"+ );+}diff --git a/packages/framefields/src/cli/project-node.ts b/packages/framefields/src/cli/project-node.tsnew file mode 100644index 00000000..3b585ee6--- /dev/null+++ b/packages/framefields/src/cli/project-node.ts@@ -0,0 +1,37 @@+/**+ * Node arguments to run a CLI worker against the user's project: the+ * project's own tsx loader for a TypeScript entry (TypeScript belongs to the+ * consumer project; init's scaffold has it), and the worker script, from+ * source when the CLI runs from source.+ */+import { createRequire } from "node:module";+import { resolve } from "node:path";+import { fileURLToPath, pathToFileURL } from "node:url";++export function projectNodeArgs(+ entry: string,+ worker: "check-worker" | "local-worker",+): string[] | { error: string } {+ const source = import.meta.url.endsWith(".ts");+ const args = source ? ["--conditions=development"] : [];+ if (source || /\.[cm]?tsx?$/.test(entry)) {+ try {+ const require = createRequire(resolve("package.json"));+ args.push("--import", pathToFileURL(require.resolve("tsx")).href);+ } catch {+ return {+ error:+ "Install the project's tsx dev dependency to load a TypeScript entry.",+ };+ }+ }+ args.push(+ fileURLToPath(+ new URL(+ source ? `./${worker}.ts` : `./cli/${worker}.mjs`,+ import.meta.url,+ ),+ ),+ );+ return args;+}diff --git a/packages/framefields/src/cli/templates.ts b/packages/framefields/src/cli/templates.tsindex b453bd37..ed3ba684 100644--- a/packages/framefields/src/cli/templates.ts+++ b/packages/framefields/src/cli/templates.ts@@ -32,8 +32,8 @@ export const SCRIPTS: Record<string, string> = {"check:render": "tsc --noEmit -p . && framefields check film --render --json",frames: "tsx src/render.ts frames",grid: "tsx src/render.ts grid",- preview: "tsx src/render.ts preview",- render: "tsx src/render.ts",+ preview: "framefields preview film",+ render: "framefields render film","render:cloud": "framefields render film --cloud",};@@ -196,44 +196,30 @@ export async function buildFilm(): Promise<Composition> {export const RENDER_TS = `import { existsSync } from "node:fs";import fs from "node:fs/promises";import path from "node:path";-import { HeadlessMediaRenderer, frameCount, startPreview } from "framefields";+import { HeadlessMediaRenderer, frameCount } from "framefields";import { buildFilm } from "./film.js";+// Quick looks at the film: \`npm run frames -- 0 30 60\` and \`npm run grid\`.+// \`npm run render\` and \`npm run preview\` use the "film" render in+// framefields.json instead (\`framefields render film\`, \`framefields preview film\`).+// Optional settings such as FRAMEFIELDS_API_KEY (see .env.example).const ENV = path.resolve(import.meta.dirname, "../.env");if (existsSync(ENV)) process.loadEnvFile(ENV);const OUT = path.resolve(import.meta.dirname, "../output");// \`npm run frames -- 0 30\` needs the \`--\`; pnpm passes it through: drop it.-const [mode = "video", ...args] = process.argv+const [mode = "frames", ...args] = process.argv.slice(2).filter((a) => a !== "--");-if (mode === "preview") {- // The page runs film.ts itself and renders it with WebGPU in the browser.- const session = await startPreview({- entry: new URL("./film.ts", import.meta.url),- export: "buildFilm",- });- console.log(\`Preview at \${session.url}\`);- await session.closed; // until its tab closes or the next preview replaces it- process.exit(0);-}-const film = await buildFilm();await fs.mkdir(OUT, { recursive: true });-if (mode === "frames") {- const renderer = new HeadlessMediaRenderer();- for (const frame of (args.length ? args : ["0"]).map(Number)) {- const png = await film.renderFrame({ frame, renderer });- const file = path.join(OUT, \`f\${String(frame).padStart(4, "0")}.png\`);- await fs.writeFile(file, png);- console.log(\`Wrote \${path.relative(process.cwd(), file)}\`);- }-} else if (mode === "grid") {+if (mode === "grid") {+ const last = frameCount(film.durationMs ?? (await film.computeDuration()), film.fps) - 1;const png = await film.renderFrameGrid({- frames: args.length ? args.map(Number) : [...new Set([0, Math.floor((frameCount(film.durationMs ?? await film.computeDuration(), film.fps) - 1) / 2), frameCount(film.durationMs ?? await film.computeDuration(), film.fps) - 1])],+ frames: args.length ? args.map(Number) : [...new Set([0, Math.floor(last / 2), last])],columns: 4,cellWidth: 480,showLabels: true,@@ -241,12 +227,13 @@ if (mode === "frames") {await fs.writeFile(path.join(OUT, "grid.png"), png);console.log("Wrote output/grid.png");} else {- const result = await film.renderVideo({- outputPath: path.join(OUT, "output.mp4"),- quality: "high",- });- await result.cleanup?.();- console.log(\`Exported \${result.filePath}\`);+ const renderer = new HeadlessMediaRenderer();+ for (const frame of (args.length ? args : ["0"]).map(Number)) {+ const png = await film.renderFrame({ frame, renderer });+ const file = path.join(OUT, \`f\${String(frame).padStart(4, "0")}.png\`);+ await fs.writeFile(file, png);+ console.log(\`Wrote \${path.relative(process.cwd(), file)}\`);+ }}// Native GPU and encoder threads keep Node alive; always exit explicitly.@@ -263,7 +250,7 @@ ${run("typecheck")}${run("frames")} -- 0 30 60 # PNGs in output/${run("grid")} # a contact sheet of the motion${run("preview")} # play it in the browser-${run("render")} # output/output.mp4+${run("render")} # output/film.mp4${run("render:cloud")} # on cloud GPUs, from the pushed commit\`\`\`diff --git a/packages/framefields/src/preview/index.ts b/packages/framefields/src/preview/index.tsindex f976220d..a377e56b 100644--- a/packages/framefields/src/preview/index.ts+++ b/packages/framefields/src/preview/index.ts@@ -6,6 +6,8 @@ import type { AddressInfo } from "node:net";import path from "node:path";import { fileURLToPath, pathToFileURL } from "node:url";import type { VirtualMediaData } from "@framefields/core";+import { type AssetLocator, openAssetLocator } from "@framefields/storage";+import { inputStore } from "@framefields/webgpu-renderers";import { encodeStereoWav } from "../audio/index.js";import { HeadlessMediaRenderer } from "../renderer/index.js";import {@@ -191,6 +193,18 @@ export async function startPreview(// Changes run one at a time: each reads and rewrites notes.json.let noteQueue: Promise<unknown> = Promise.resolve();+ // Assets framefields.json pins but that aren't on disk (an agent's+ // sandbox, a fresh clone) stream from their bucket: the page is+ // redirected there, and the soundtrack mix reads them over HTTP.+ const assets = await openAssetLocator(path.dirname(entry)).catch(+ (err: unknown) => {+ say(`pinned assets are off: ${(err as Error).message}`);+ return undefined;+ },+ );+ if (assets) inputStore.setMissingMediaResolver((file) => assets.url(file));+ const unreadable = new Set<string>();+const target = await loadTarget(entry, exportName);const meta = await resolveMeta(target, title, session, notes?.dir ?? null);// The project's own code, bundled against the browser engine; the engine@@ -286,6 +300,7 @@ export async function startPreview(if (reason === "replaced") say("stopped: a newer preview took over");for (const client of sseClients) client.end();sseClients.clear();+ if (assets) inputStore.setMissingMediaResolver();server.close(() => {resolve();resolveClosed(reason);@@ -353,7 +368,7 @@ export async function startPreview(if (roots.some((r) => isInside(r, file))) {size = await fs.promises.stat(file).then((st) => (st.isFile() ? st.size : -1),- () => -1,+ () => assets?.entry(file)?.size ?? -1,);}sendJson(res, 200, { exists: size >= 0, size: Math.max(0, size) });@@ -492,6 +507,11 @@ export async function startPreview(await sendFile(req, res, file);return;}+ if (+ assets &&+ (await redirectToBucket(res, assets, file, unreadable, say))+ )+ return;}sendJson(res, 404, { error: "not found" });} catch (err) {@@ -691,6 +711,35 @@ const CONTENT_TYPES: Record<string, string> = {".txt": "text/plain; charset=utf-8",};+/**+ * Sends the page to the bucket for a pinned asset that isn't on disk. The+ * bucket must allow this page's origin (CORS): the engine reads media with+ * `fetch`. True when it answered.+ */+async function redirectToBucket(+ res: http.ServerResponse,+ assets: AssetLocator,+ file: string,+ unreadable: Set<string>,+ say: (line: string) => void,+): Promise<boolean> {+ if (!assets.entry(file)) return false;+ const url = await assets.url(file);+ if (url) {+ res.writeHead(302, { location: url, "cache-control": "no-store" });+ res.end();+ return true;+ }+ const rel = path.relative(assets.root, file);+ if (!unreadable.has(rel)) {+ unreadable.add(rel);+ say(+ `${rel} is pinned on a private remote and there are no keys here: set its FRAMEFIELDS_STORAGE_* keys, give the remote a publicUrl, or \`npx framefields assets pull\``,+ );+ }+ return false;+}+/** Serves a file, with byte ranges so video can seek without loading it whole. */async function sendFile(req: http.IncomingMessage,diff --git a/packages/framefields/src/preview/preview.test.ts b/packages/framefields/src/preview/preview.test.tsindex 25c160d2..ffe66b11 100644--- a/packages/framefields/src/preview/preview.test.ts+++ b/packages/framefields/src/preview/preview.test.ts@@ -168,6 +168,75 @@ describe("startPreview", () => {}});+ it("sends the page to the bucket for pinned assets that aren't on disk", async () => {+ const project = await fs.promises.mkdtemp(+ path.join(os.tmpdir(), "gf-project-"),+ );+ const sha = "ab".repeat(32);+ const raw = "cd".repeat(32);+ process.env.FRAMEFIELDS_STORAGE_RAW_ACCESS_KEY_ID = "id";+ process.env.FRAMEFIELDS_STORAGE_RAW_SECRET_ACCESS_KEY = "secret";+ try {+ const src = path.join(project, "src");+ await fs.promises.mkdir(src, { recursive: true });+ await fs.promises.writeFile(path.join(project, "package.json"), "{}");+ const endpoint = "https://acct.r2.cloudflarestorage.com";+ await fs.promises.writeFile(+ path.join(project, "framefields.json"),+ JSON.stringify({+ storage: {+ default: "media",+ remotes: {+ media: {+ endpoint,+ bucket: "films",+ publicUrl: "https://media.example.com",+ },+ raw: { endpoint, bucket: "raw" },+ },+ },+ assets: {+ "assets/intro.mp4": { sha256: sha, size: 1234 },+ "assets/raw.mov": { sha256: raw, size: 99, remote: "raw" },+ },+ }),+ );+ const comp = path.join(src, "comp.ts");+ await fs.promises.writeFile(+ comp,+ "export default function build() { return { fps: 10, durationMs: 1000, width: 64, height: 36 }; }",+ );+ const session = await start({ entry: comp }, { open: false, port: 0 });+ const get = (rel: string) =>+ fetch(`${session.url}@fs${path.join(project, rel)}`, {+ redirect: "manual",+ });+ const intro = await get("assets/intro.mp4");+ expect(intro.status).toBe(302);+ expect(intro.headers.get("location")).toBe(+ `https://media.example.com/sha256/ab/${sha}`,+ );+ const signed = new URL(+ (await get("assets/raw.mov")).headers.get("location") ?? "",+ );+ expect(signed.origin + signed.pathname).toBe(+ `${endpoint}/raw/sha256/cd/${raw}`,+ );+ expect(signed.searchParams.get("X-Amz-Signature")).toMatch(+ /^[0-9a-f]{64}$/,+ );+ expect((await get("assets/other.mp4")).status).toBe(404);+ const stat = await fetch(+ `${session.url}@framefields/stat?path=${encodeURIComponent(path.join(project, "assets/intro.mp4"))}`,+ ).then((r) => r.json());+ expect(stat).toEqual({ exists: true, size: 1234 });+ } finally {+ delete process.env.FRAMEFIELDS_STORAGE_RAW_ACCESS_KEY_ID;+ delete process.env.FRAMEFIELDS_STORAGE_RAW_SECRET_ACCESS_KEY;+ await fs.promises.rm(project, { recursive: true, force: true });+ }+ });+it("names a missing export", async () => {await expect(startPreview({ entry, export: "film" }, { open: false, port: 0 }),diff --git a/packages/framefields/tsdown.config.ts b/packages/framefields/tsdown.config.tsindex c1f0b272..cf27d889 100644--- a/packages/framefields/tsdown.config.ts+++ b/packages/framefields/tsdown.config.ts@@ -19,6 +19,7 @@ export default defineConfig({"src/storage/index.ts","src/cli.ts","src/cli/check-worker.ts",+ "src/cli/local-worker.ts",],format: ["esm"],clean: true,diff --git a/packages/storage/src/index.ts b/packages/storage/src/index.tsindex 202bc420..0637f56e 100644--- a/packages/storage/src/index.ts+++ b/packages/storage/src/index.ts@@ -17,6 +17,13 @@ export {hashFile,redactQuery,} from "./files.js";+export {+ type AssetLocator,+ findProjectDir,+ openAssetLocator,+ type ProjectManifest,+ readProjectManifest,+} from "./locate.js";export {type AssetEntry,type AssetManifest,diff --git a/packages/storage/src/locate.ts b/packages/storage/src/locate.tsnew file mode 100644index 00000000..581bfbad--- /dev/null+++ b/packages/storage/src/locate.ts@@ -0,0 +1,112 @@+/**+ * Finding a project's pinned assets from file paths: what a preview or an+ * engine asks for is an absolute path, and a pinned file that isn't on disk+ * is read from its bucket instead.+ */+import { existsSync } from "node:fs";+import { readFile } from "node:fs/promises";+import { dirname, join, relative, sep } from "node:path";+import { Bucket, credentialsFromEnv } from "./bucket.js";+import {+ type AssetEntry,+ type AssetManifest,+ ManifestError,+ parseAssets,+ parseStorage,+ pickRemote,+ readUrl,+ type StorageConfig,+} from "./manifest.js";++const FILE = "framefields.json";++export interface ProjectManifest {+ storage?: StorageConfig;+ assets: AssetManifest;+}++/** The nearest folder at or above `dir` holding a framefields.json. */+export function findProjectDir(dir: string): string | undefined {+ for (let at = dir; ; at = dirname(at)) {+ if (existsSync(join(at, FILE))) return at;+ if (dirname(at) === at) return undefined;+ }+}++/** The `storage` and `assets` of the project at `dir`; undefined without assets. */+export async function readProjectManifest(+ dir: string,+): Promise<ProjectManifest | undefined> {+ const file = join(dir, FILE);+ if (!existsSync(file)) return undefined;+ let raw: { storage?: unknown; assets?: unknown };+ try {+ raw = JSON.parse(await readFile(file, "utf8")) as typeof raw;+ } catch (err) {+ throw new ManifestError(+ `${FILE} is not valid JSON: ${(err as Error).message}`,+ );+ }+ if (raw.assets === undefined) return undefined;+ const storage =+ raw.storage === undefined ? undefined : parseStorage(raw.storage);+ return { storage, assets: parseAssets(raw.assets, storage) };+}++export interface AssetLocator {+ /** The project folder (where framefields.json is). */+ readonly root: string;+ /** The pinned entry for an absolute path, if the project pins it. */+ entry(file: string): AssetEntry | undefined;+ /**+ * A URL to read a pinned file from: its public domain or own URL, else+ * a GET signed with the remote's keys from the environment. Undefined+ * when the file isn't pinned, or is private and there are no keys.+ */+ url(file: string): Promise<string | undefined>;+}++/** Signatures last 6 h and are reused for 5, so long sessions keep working. */+const SIGNED_SEC = 6 * 3600;+const REUSE_MS = 5 * 3600 * 1000;++/**+ * Pinned-asset lookup for the project at or above `dir`, or undefined when+ * it pins none.+ */+export async function openAssetLocator(+ dir: string,+ options: {+ env?: Readonly<Record<string, string | undefined>>;+ fetch?: typeof fetch;+ } = {},+): Promise<AssetLocator | undefined> {+ const root = findProjectDir(dir);+ const manifest = root && (await readProjectManifest(root));+ if (!root || !manifest) return undefined;+ const signed = new Map<string, { url: string; at: number }>();+ const entry = (file: string) => {+ const rel = relative(root, file).split(sep).join("/");+ return rel.startsWith("../") ? undefined : manifest.assets[rel];+ };+ return {+ root,+ entry,+ async url(file) {+ const pinned = entry(file);+ if (!pinned) return undefined;+ const open = readUrl(pinned, manifest.storage);+ if (open) return open;+ const cached = signed.get(pinned.sha256);+ if (cached && Date.now() - cached.at < REUSE_MS) return cached.url;+ const { name, remote } = pickRemote(manifest.storage, pinned.remote);+ const keys = credentialsFromEnv(name, options.env);+ if (!keys) return undefined;+ const url = await new Bucket(remote, keys, {+ fetch: options.fetch,+ }).presign(pinned.sha256, SIGNED_SEC);+ signed.set(pinned.sha256, { url, at: Date.now() });+ return url;+ },+ };+}diff --git a/packages/webgpu-renderers/src/input-store.ts b/packages/webgpu-renderers/src/input-store.tsindex aa8a23d3..081840d8 100644--- a/packages/webgpu-renderers/src/input-store.ts+++ b/packages/webgpu-renderers/src/input-store.ts@@ -50,11 +50,29 @@ async function assertReadableFile(}}+/**+ * Where to read a local media file that isn't on disk: a URL for it (a+ * project's asset pinned on a bucket), or undefined.+ */+export type MissingMediaResolver = (+ filePath: string,+) => Promise<string | undefined>;+class InputStore {private store = new Map<string,{ promise: Promise<Input>; refCount: number }>();+ private resolveMissing?: MissingMediaResolver;++ /**+ * Reads local files that are missing from disk from the URL `resolver`+ * gives, with HTTP range requests, so a clip pinned on a bucket plays+ * without being downloaded. Unset with no argument.+ */+ setMissingMediaResolver(resolver?: MissingMediaResolver): void {+ this.resolveMissing = resolver;+ }async acquire(url: string): Promise<Input> {if (!url) throw new Error("Cannot acquire Input for empty URL");@@ -73,10 +91,7 @@ class InputStore {| InstanceType<typeof FilePathSource>| InstanceType<typeof UrlSource>;if (filePath !== null) {- // FilePathSource opens lazily; check now so a bad path fails- // with its name instead of deep inside the first decode.- await assertReadableFile(filePath, url);- source = new FilePathSource(filePath);+ source = await this.localSource(filePath, url);} else {source = new UrlSource(resolvedUrl);}@@ -114,6 +129,24 @@ class InputStore {}}+ private async localSource(+ filePath: string,+ url: string,+ ): Promise<+ InstanceType<typeof FilePathSource> | InstanceType<typeof UrlSource>+ > {+ try {+ // FilePathSource opens lazily; check now so a bad path fails+ // with its name instead of deep inside the first decode.+ await assertReadableFile(filePath, url);+ return new FilePathSource(filePath);+ } catch (err) {+ const remote = await this.resolveMissing?.(filePath);+ if (remote) return new UrlSource(remote);+ throw err;+ }+ }+release(url: string): void {if (!url) return;const resolvedUrl = resolveInputUrl(url, isNodeRuntime());diff --git a/plugins/framefields/skills/framefields-render/SKILL.md b/plugins/framefields/skills/framefields-render/SKILL.mdindex 4ce3327b..46a6cbe6 100644--- a/plugins/framefields/skills/framefields-render/SKILL.md+++ b/plugins/framefields/skills/framefields-render/SKILL.md@@ -354,12 +354,17 @@ CLI Usage:tsx src/render.ts frames 0 18 36 72# Live player for the user (run in the background; re-run after changes and the open tab reloads):-tsx src/render.ts preview+npx framefields preview film-# Render full master video:-tsx src/render.ts+# Render the full video on this machine, to the render's output in framefields.json:+npx framefields render film++# The same render on framefields cloud GPUs, to the same file:+npx framefields render film --cloud```+`framefields render <name>` and `framefields preview <name>` load the module with the project's own tsx and framefields, like the cloud worker, and call the export with the render's `args` (and `select`); the preview calls it without them. A local render downloads pinned assets that are missing first; the preview streams them from their bucket.+### Reading render progress`renderVideo` logs its own progress to stderr, one short `[framefields]` line per event. The log stays short however long the film is, about 15 lines for an export:diff --git a/plugins/framefields/skills/framefields/SKILL.md b/plugins/framefields/skills/framefields/SKILL.mdindex 6503656f..46098e2b 100644--- a/plugins/framefields/skills/framefields/SKILL.md+++ b/plugins/framefields/skills/framefields/SKILL.md@@ -170,33 +170,19 @@ export async function buildFilm(): Promise<Composition> {``````typescript-// src/render.ts+// src/render.ts: quick looks (frames, a contact sheet). Full renders and the preview use the CLI.import fs from "node:fs/promises";import path from "node:path";-import { HeadlessMediaRenderer, startPreview } from "framefields";+import { HeadlessMediaRenderer } from "framefields";import { buildFilm } from "./film.js";const OUT = path.resolve(import.meta.dirname, "../output");-const [mode = "video", ...args] = process.argv.slice(2);--if (mode === "preview") {- // The page runs film.ts itself and renders it with WebGPU in the browser.- const session = await startPreview({ entry: new URL("./film.ts", import.meta.url), export: "buildFilm" });- console.log(`Preview at ${session.url}`);- await session.closed; // until its tab closes or the next preview replaces it- process.exit(0);-}+const [mode = "frames", ...args] = process.argv.slice(2);const film = await buildFilm();await fs.mkdir(OUT, { recursive: true });-if (mode === "frames") {- const renderer = new HeadlessMediaRenderer();- for (const frame of args.map(Number)) {- const png = await film.renderFrame({ frame, renderer });- await fs.writeFile(path.join(OUT, `f${String(frame).padStart(4, "0")}.png`), png);- }-} else if (mode === "grid") {+if (mode === "grid") {const png = await film.renderFrameGrid({frames: args.length ? args.map(Number) : [0, 10, 20, 30, 45, 60, 75, 89],columns: 4,@@ -205,12 +191,11 @@ if (mode === "frames") {});await fs.writeFile(path.join(OUT, "grid.png"), png);} else {- const result = await film.renderVideo({- outputPath: path.join(OUT, "output.mp4"),- quality: "high",- });- await result.cleanup?.();- console.log(`Exported ${result.filePath}`);+ const renderer = new HeadlessMediaRenderer();+ for (const frame of (args.length ? args : ["0"]).map(Number)) {+ const png = await film.renderFrame({ frame, renderer });+ await fs.writeFile(path.join(OUT, `f${String(frame).padStart(4, "0")}.png`), png);+ }}// Native GPU and encoder threads keep Node alive; always exit explicitly.@@ -224,12 +209,14 @@ Add scripts to `package.json`:"typecheck": "tsc --noEmit -p .","frames": "tsx src/render.ts frames","grid": "tsx src/render.ts grid",- "preview": "tsx src/render.ts preview",- "render": "tsx src/render.ts",+ "preview": "framefields preview film",+ "render": "framefields render film","render:cloud": "framefields render film --cloud"}```+`framefields render film`, `framefields render film --cloud` and `framefields preview film` all read the `film` render below, so a render writes the same file wherever it runs: switching between this machine and the cloud is the `--cloud` flag, nothing else. Flags (`--export`, `--select`, `--codec`, `--quality`, `--output`) override the render's fields either way.+`framefields.json` names what the project renders; `film` is the scaffold's. Add an entry per cut (teaser, vertical edit) so the CLI, `framefields check` and the dashboard pick it by name:```json@@ -267,7 +254,11 @@ Footage, audio, Lottie files, LUTs and generated media are too big for plain git3. `npx framefields assets add assets/footage` hashes the files (a folder means every file in it), uploads what the bucket lacks, records them under `assets` and adds them to `.gitignore`. Commit `framefields.json` and `.gitignore`. Adding a changed file again records the new version.4. In a fresh clone or container, `npx framefields assets pull` downloads what's missing and checks every byte; it leaves files changed locally alone unless `--overwrite`. `assets status` lists each asset as `ok`, `missing` or `changed`; `assets push` re-uploads what the bucket lacks.-Code references assets by path as usual (`Layer.video("assets/footage/intro.mp4")`); nothing in the film changes. A missing pinned file makes `framefields check` say to run `assets pull`.+Code references assets by path as usual (`Layer.video("assets/footage/intro.mp4")`); nothing in the film changes. Where the files aren't on disk (a fresh clone, a cloud agent's sandbox):++- `framefields preview` streams them from the bucket: the page is redirected to the remote's `publicUrl` (or a URL signed with the remote's keys), so nothing is downloaded into the sandbox. The bucket needs a CORS rule allowing the preview's origin; see the assets guide (https://framefields.dev/docs/guides/assets/#preview-from-the-bucket).+- `framefields render` downloads the missing ones first (`assets pull`), then renders.+- `framefields check` says to run `assets pull`.**Or Git LFS**, when the project already uses it or there's no bucket. `npx framefields init` writes the LFS `.gitattributes`. In fresh clones LFS media are ~130-byte pointer files that decode as blank frames, so run `git lfs pull` first, and never add `*.mp4` to `.gitignore` for LFS-tracked footage. Every clone and every cloud render worker downloads LFS objects from the git host, which bills that bandwidth to the repo owner; a bucket with no egress fees avoids it.