Code-first video & image, rendered natively on WebGPU.
feat(cli): init asks nothing, adds .env.example; README covers init
okanasl52d5632855a9
diff --git a/.changeset/components-polish-fonts-init.md b/.changeset/components-polish-fonts-init.mdindex 893f4609..3f07e82b 100644--- a/.changeset/components-polish-fonts-init.md+++ b/.changeset/components-polish-fonts-init.md@@ -4,8 +4,9 @@Start projects with `framefields init`, install fonts with components, and polish the component toolkit.-- `npx framefields init [dir]` writes a working project: `package.json` (ES module, scripts, dependencies, `packageManager`, and install-script approvals that let only skia-canvas run its script), `tsconfig.json`, `src/theme.ts` / `film.ts` / `render.ts`, `assets/`, an LFS `.gitattributes`, `.gitignore` and `README.md`. It also installs Inter and JetBrains Mono and runs `git init`. It never overwrites: in an existing project, files only gain what they lack. Options: `--pm`, `--install`, `--emoji`, `--no-fonts`, `--no-git`, `--name`.+- `npx framefields init [dir]` writes a working project: `package.json` (ES module, scripts, dependencies, `packageManager`, and install-script approvals that let only skia-canvas run its script), `tsconfig.json`, `src/theme.ts` / `film.ts` / `render.ts`, `assets/`, an LFS `.gitattributes`, `.gitignore` and `README.md`. It also installs Inter and JetBrains Mono and runs `git init`. It never overwrites: in an existing project, files only gain what they lack. Options: `--pm`, `--install`, `--emoji`, `--no-fonts`, `--no-git`, `--name`. It asks no questions, so it runs unattended in CI. The AI gateway key is optional: `init` writes `.env.example`, git-ignores `.env`, and the generated `render.ts` loads `.env` when it exists.- Fonts come with the components that need them. `framefields add chat-thread` / `captions` installs Noto Color Emoji, and `terminal` / `code-block` install JetBrains Mono. Each font is pinned by size and SHA-256, saved with its OFL license, recorded in `framefields.json` and registered in a generated `fonts.ts` (`await registerFonts()`). `framefields fonts add <emoji|sans|mono>` and `fonts list` install fonts directly, and `--no-fonts` skips them. The package itself ships no fonts.- `comp.lint()` reports `missing_emoji_font` when text has emoji but no emoji font is registered, and the render warning now names the fix. `FontManager.hasEmojiFont()` is new.- Toolkit: `withDefaults({ fps, canvas, theme, seed })` and `after(node, gap)` (also on the root), a `canvas` base prop, prop typos answered with "did you mean", `partNames` on every node, a `blur` option on motion presets, and shared keyframe, color, layout and surface helpers.- Themes gain `mode`, font weights, elevation, springs, `color.shadow` and `syntax`. LowerThird, Toasts, Callout, CardStack and ChatThread surfaces get depth (shadow, lit top edge, sheen), and sliding surfaces get motion blur. ChatThread reactions are emoji text drawn from the color emoji font.+- Fix: fonts registered from a `file://` URL whose path has spaces (or a Windows drive letter) are found again. The browser preview failed to load them.diff --git a/README.md b/README.mdindex 147922e0..ab5e30c8 100644--- a/README.md+++ b/README.md@@ -82,6 +82,15 @@ Every frame is rendered by framefields directly from TypeScript in [`examples/`]pnpm add framefields```+Starting a new film? `framefields init` sets up the whole project: `package.json`, TypeScript, a `film.ts` to edit and a `render.ts` to render it, `assets/` with Git LFS, and the Inter and JetBrains Mono fonts:++```bash+pnpm dlx framefields init my-film --install # or: npx framefields init my-film --install+cd my-film && pnpm frames -- 0 30 60 # first frames in output/+```++Run it inside an existing project to add framefields there; it only fills in what's missing and never overwrites your files. It asks nothing, so it works in CI and on remote servers too.+> **Requirements:** Node.js ≥ 22. Native GPU acceleration via WebGPU / Dawn (macOS Metal, Linux Vulkan, Windows D3D12). Machines without a dedicated GPU can render on the CPU via Mesa lavapipe on Linux or WARP on Windows (~10–12× slower than GPU; suitable for headless CI and test frames).---@@ -186,6 +195,8 @@ Installed components import only `framefields` and the shared toolkit in `framefFramefields provides built-in access to the [**AI Gateway**](https://framefields.dev/models), allowing agents and developers to generate cinematic video, images, music, and voiceovers directly from code using hundreds of hosted models. Explore the full model catalog in the [**AI Gateway**](https://framefields.dev/models) or read the integration guide in the [**documentation**](https://framefields.dev/docs/guides/ai/).+The gateway is optional. To use it, create a key at [**framefields.dev/dashboard**](https://framefields.dev/dashboard) and set `FRAMEFIELDS_API_KEY`. In a project made with `framefields init`, copy `.env.example` to `.env` and put the key there; `render.ts` loads it.+---## Documentationdiff --git a/packages/components/SPEC.md b/packages/components/SPEC.mdindex d4f72b15..37520a28 100644--- a/packages/components/SPEC.md+++ b/packages/components/SPEC.md@@ -2059,6 +2059,17 @@ the project layout the setup skill describes, so a project starts the same way e- **Git:** `git init` when the folder isn't in a repository (`--no-git` skips it), and anote to run `git lfs install`, or to install Git LFS when `git lfs` is missing.`--install` runs the package manager's install, and prints the next steps either way.+- **No questions.** `init` never prompts, so CI and remote servers run it unattended.+ The AI gateway key is optional: `init` writes `.env.example` (`FRAMEFIELDS_API_KEY=`,+ with the dashboard link), git-ignores `.env`, and `render.ts` loads `.env` when it exists+ (`process.loadEnvFile`; Node's `--env-file-if-exists` prints a note when the file is+ missing, which is noise in CI). The last line of the output names the gateway and+ `framefields.dev/dashboard`.+- **Fonts from `file://` URLs with spaces.** `FontManager` decoded a `file://` source by+ taking its pathname, which stays percent-encoded (`My%20Film`). Node renders found the+ file anyway through the `cwd/assets/fonts` fallback, but the browser preview has none, so+ fonts failed there. It now decodes the path (and drops the leading slash before a Windows+ drive letter). `font-sources.test.ts` covers it.- **Tests:** `init.test.ts` covers a new project, a merge into an existing one (twice:the second run changes nothing), CommonJS, emoji / no-git / install with bun, failures,and the package-manager detection. It also checks that every TypeScript template parses.diff --git a/packages/framefields/src/cli.ts b/packages/framefields/src/cli.tsindex 729533ad..17024b9c 100644--- a/packages/framefields/src/cli.ts+++ b/packages/framefields/src/cli.ts@@ -28,6 +28,7 @@ import {shownPath,} from "./cli/init.js";import { openRegistry } from "./cli/registry.js";+import { AI_DASHBOARD } from "./cli/templates.js";const HELP = `Usage: framefields <command> [options]@@ -306,6 +307,9 @@ function logInit(report: InitReport, cwd: string, log: (s: string) => void) {log("\nThen edit src/film.ts, and run `npx framefields list` for ready-made components.",);+ log(+ `\nOptional: to generate images, video, music, voice and 3D with the framefields AI gateway, get a key at ${AI_DASHBOARD} and put it in .env as FRAMEFIELDS_API_KEY (see .env.example).`,+ );}/** Installed components import `framefields`; say so if the project lacks it. */diff --git a/packages/framefields/src/cli/init.test.ts b/packages/framefields/src/cli/init.test.tsindex 2936c575..a798f829 100644--- a/packages/framefields/src/cli/init.test.ts+++ b/packages/framefields/src/cli/init.test.ts@@ -135,6 +135,10 @@ describe("framefields init", () => {expect(existsSync(join(cwd, root("assets/footage/.gitkeep")))).toBe(true);expect(read(root(".gitattributes"))).toContain(GITATTRIBUTES[0]);expect(read(root(".gitignore"))).toContain("output/");+ // The AI gateway key is optional: an example file, never a prompt.+ expect(read(root(".env.example"))).toMatch(/^FRAMEFIELDS_API_KEY=$/m);+ expect(read(root(".gitignore"))).toContain(".env\n");+ expect(read(root("src/render.ts"))).toContain("process.loadEnvFile(ENV)");expect(read(root("README.md"))).toContain("pnpm frames -- 0 30 60");// The themes' fonts, recorded and registered where theme.ts imports them.expect(report.fonts.map((f) => [f.role, f.path, f.status])).toEqual([@@ -190,7 +194,7 @@ describe("framefields init", () => {expect(pkg.pnpm.onlyBuiltDependencies).toEqual(["esbuild", "skia-canvas"]);expect(read("src/film.ts")).toBe("// mine\n");expect(read(".gitignore")).toBe(- "dist/\noutput/\nnode_modules/\nscratch/\n.DS_Store\n",+ "dist/\noutput/\nnode_modules/\nscratch/\n.DS_Store\n.env\n",);expect(report.merged).toEqual(["package.json", ".gitignore"]);expect(report.unchanged).toContain("src/film.ts");diff --git a/packages/framefields/src/cli/init.ts b/packages/framefields/src/cli/init.tsindex 3918d73f..da94111a 100644--- a/packages/framefields/src/cli/init.ts+++ b/packages/framefields/src/cli/init.ts@@ -23,6 +23,7 @@ import {writeFontsModule,} from "./fonts.js";import {+ ENV_EXAMPLE,FILM_TS,GITATTRIBUTES,GITIGNORE,@@ -171,6 +172,7 @@ export async function init(options: InitOptions): Promise<InitReport> {["src/film.ts", FILM_TS],["src/render.ts", RENDER_TS],["assets/footage/.gitkeep", ""],+ [".env.example", ENV_EXAMPLE],["README.md", readme(report.name, report.runScript)],];for (const [path, content] of files) {diff --git a/packages/framefields/src/cli/templates.ts b/packages/framefields/src/cli/templates.tsindex b145ef73..78d86e15 100644--- a/packages/framefields/src/cli/templates.ts+++ b/packages/framefields/src/cli/templates.ts@@ -77,7 +77,24 @@ export const TSCONFIG = `${JSON.stringify()}\n`;/** Lines `init` makes sure `.gitignore` has. */-export const GITIGNORE = ["node_modules/", "output/", "scratch/", ".DS_Store"];+export const GITIGNORE = [+ "node_modules/",+ "output/",+ "scratch/",+ ".DS_Store",+ ".env",+];++/** Where the AI gateway's keys come from. */+export const AI_DASHBOARD = "https://framefields.dev/dashboard";++/** Optional settings; `render.ts` loads `.env` when there is one. Commit this, not `.env`. */+export const ENV_EXAMPLE = `# Copy to .env (git-ignored). Everything here is optional.++# framefields AI gateway: generate images, video, music, voice and 3D from code.+# Create a key at ${AI_DASHBOARD}+FRAMEFIELDS_API_KEY=+`;/** Media, LUTs and fonts go to Git LFS; renders stay out of Git. */export const GITATTRIBUTES = [@@ -159,11 +176,16 @@ export async function buildFilm(): Promise<Composition> {}`;-export const RENDER_TS = `import fs from "node:fs/promises";+export const RENDER_TS = `import { existsSync } from "node:fs";+import fs from "node:fs/promises";import path from "node:path";import { HeadlessMediaRenderer, startPreview } from "framefields";import { buildFilm } from "./film.js";+// 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@@ -231,6 +253,8 @@ ${run("render")} # output/output.mp4\`src/render.ts\` renders it.- \`npx framefields list\` shows ready-made components; \`npx framefields add <name>\` copiesone into \`src/components/\`.+- Optional: the AI gateway generates images, video, music, voice and 3D from code. Copy+ \`.env.example\` to \`.env\` and set \`FRAMEFIELDS_API_KEY\` (keys at ${AI_DASHBOARD}).- Footage, audio and fonts live in \`assets/\` and are tracked with Git LFS(\`git lfs install\` once per machine, \`git lfs pull\` after cloning).`;diff --git a/packages/framefields/src/font-sources.test.ts b/packages/framefields/src/font-sources.test.tsindex 6ae6b4c6..f6723b2d 100644--- a/packages/framefields/src/font-sources.test.ts+++ b/packages/framefields/src/font-sources.test.ts@@ -126,3 +126,21 @@ describe.skipIf(!hasInter)(});},);++describe.skipIf(!hasInter)("file URLs", () => {+ it("registers a font from a file:// URL whose path has spaces", async () => {+ const { mkdtempSync, cpSync } = await import("node:fs");+ const { tmpdir } = await import("node:os");+ const { pathToFileURL } = await import("node:url");+ const dir = path.join(mkdtempSync(path.join(tmpdir(), "ff-")), "My Film");+ const file = path.join(dir, "Spaced Name.ttf");+ cpSync(INTER, file, { recursive: true });+ const url = pathToFileURL(file).href;+ expect(url).toContain("My%20Film");+ // Run from elsewhere so no cwd fallback can find it by name.+ const cwd = vi.spyOn(process, "cwd").mockReturnValue(tmpdir());+ await FontManager.register({ family: "Spaced", source: url });+ cwd.mockRestore();+ expect(FontManager.has("Spaced")).toBe(true);+ });+});diff --git a/packages/framefields/src/fonts/manager.ts b/packages/framefields/src/fonts/manager.tsindex 2a82d215..6cb801c8 100644--- a/packages/framefields/src/fonts/manager.ts+++ b/packages/framefields/src/fonts/manager.ts@@ -102,7 +102,12 @@ async function resolveSourceBuffer(if (cleanPath.startsWith("file://")) {try {- cleanPath = new URL(cleanPath).pathname;+ // A URL path is percent-encoded ("My%20Film"); files aren't. On+ // Windows "/C:/…" loses its leading slash.+ cleanPath = decodeURIComponent(new URL(cleanPath).pathname).replace(+ /^\/([A-Za-z]:)/,+ "$1",+ );} catch {cleanPath = cleanPath.replace(/^file:\/\//, "");}diff --git a/plugins/framefields/skills/framefields/SKILL.md b/plugins/framefields/skills/framefields/SKILL.mdindex 4fab7b81..dabf5066 100644--- a/plugins/framefields/skills/framefields/SKILL.md+++ b/plugins/framefields/skills/framefields/SKILL.md@@ -36,7 +36,7 @@ This skill takes a project from nothing to a verified first render. For anythingnpx framefields init my-film --install # a new project; or `init` inside an existing one```-In an existing project it never overwrites: existing files are left alone, and `package.json`, `.gitignore` and `.gitattributes` only gain what they lack (a `"type": "commonjs"` package is refused). Options: `--pm npm|pnpm|yarn|bun` (default: the one running it), `--emoji` (also the color emoji font), `--no-fonts`, `--no-git`, `--name`. Then go to section 4. The rest of this section and section 3 describe what it writes, for doing it by hand or merging into an unusual setup.+In an existing project it never overwrites: existing files are left alone, and `package.json`, `.gitignore` and `.gitattributes` only gain what they lack (a `"type": "commonjs"` package is refused). Options: `--pm npm|pnpm|yarn|bun` (default: the one running it), `--emoji` (also the color emoji font), `--no-fonts`, `--no-git`, `--name`. It asks no questions, so it runs unattended in CI. The AI gateway key is optional: `init` writes `.env.example` and git-ignores `.env`, and `render.ts` loads `.env` when it exists; the user sets `FRAMEFIELDS_API_KEY` there themselves (never write a key for them). Then go to section 4. The rest of this section and section 3 describe what it writes, for doing it by hand or merging into an unusual setup.Use the package manager the project already uses (look for `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, or `package-lock.json`).