Skip to content

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.md
index 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.md
index 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 `framef
Framefields 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.
+
---
## Documentation
diff --git a/packages/components/SPEC.md b/packages/components/SPEC.md
index 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 a
note 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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>\` copies
one 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.ts
index 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.ts
index 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.md
index 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 anything
npx 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`).