Skip to content

Code-first video & image, rendered natively on WebGPU.

Serve preview assets from the project root, not just the entry directory

okanasld7bda9e23cd7
diff --git a/.changeset/preview-asset-root.md b/.changeset/preview-asset-root.md
new file mode 100644
index 00000000..6043a093
--- /dev/null
+++ b/.changeset/preview-asset-root.md
@@ -0,0 +1,5 @@
+---
+"gitframes": patch
+---
+
+The preview now serves assets from the project that holds the entry (its nearest `.git`, else `package.json`), not just the entry's own directory. A project with no `.git`, where fonts and media live in a sibling `assets/` folder, previously failed to load them. `root` also accepts several paths now, for assets kept outside the project.
diff --git a/packages/gitframes/src/preview/index.ts b/packages/gitframes/src/preview/index.ts
index 7b80bdcb..96dd4c26 100644
--- a/packages/gitframes/src/preview/index.ts
+++ b/packages/gitframes/src/preview/index.ts
@@ -68,9 +68,11 @@ export interface PreviewOptions {
idleCloseMs?: number | false;
/**
* Files the page may load by absolute path (the composition's assets).
- * Defaults to the repository that holds the entry, or its directory.
+ * Defaults to the project that holds the entry: the nearest `.git`, else
+ * the nearest `package.json`, else the entry's directory. Pass one path or
+ * several to allow assets kept outside it.
*/
- root?: string;
+ root?: string | string[];
}
export interface PreviewSession {
@@ -120,12 +122,21 @@ export async function startPreview(
? fileURLToPath(source.entry)
: path.resolve(String(source.entry));
const exportName = source.export ?? "default";
- const root = path.resolve(options.root ?? repoRoot(path.dirname(entry)));
// Vision nodes load their cached models, and onnxruntime-web's files when
// the project has it installed.
const modelsDir = visionModelsDir();
const ort = onnxRuntimeWeb(path.dirname(entry));
- const roots = [root, modelsDir, ort.dir].filter((r): r is string => !!r);
+ const roots = [
+ ...(options.root === undefined
+ ? [repoRoot(path.dirname(entry))]
+ : Array.isArray(options.root)
+ ? options.root
+ : [options.root]),
+ modelsDir,
+ ort.dir,
+ ]
+ .filter((r): r is string => !!r)
+ .map((r) => path.resolve(r));
const sseClients = new Set<http.ServerResponse>();
const idleCloseMs = options.idleCloseMs ?? 5000;
let idleTimer: NodeJS.Timeout | undefined;
@@ -442,11 +453,17 @@ async function loadTarget(
) as PreviewTarget;
}
-/** The repository holding `dir` (nearest `.git`), else `dir` itself. */
+/**
+ * The project holding `dir`: the nearest `.git`, else the nearest
+ * `package.json`, else `dir` itself. A repo wins over a nested package, so a
+ * monorepo's shared assets stay reachable.
+ */
function repoRoot(dir: string): string {
+ let project: string | undefined;
for (let d = dir; ; d = path.dirname(d)) {
if (fs.existsSync(path.join(d, ".git"))) return d;
- if (path.dirname(d) === d) return dir;
+ if (!project && fs.existsSync(path.join(d, "package.json"))) project = d;
+ if (path.dirname(d) === d) return project ?? dir;
}
}
diff --git a/packages/gitframes/src/preview/preview.test.ts b/packages/gitframes/src/preview/preview.test.ts
index e8152fa8..d5bda87f 100644
--- a/packages/gitframes/src/preview/preview.test.ts
+++ b/packages/gitframes/src/preview/preview.test.ts
@@ -88,6 +88,66 @@ describe("startPreview", () => {
expect(await stat("/etc/hosts")).toEqual({ exists: false, size: 0 });
});
+ it("serves assets from the project root, not only the entry's directory", async () => {
+ const project = await fs.promises.mkdtemp(
+ path.join(os.tmpdir(), "gf-project-"),
+ );
+ try {
+ const src = path.join(project, "src");
+ const fonts = path.join(project, "assets", "fonts");
+ await fs.promises.mkdir(src, { recursive: true });
+ await fs.promises.mkdir(fonts, { recursive: true });
+ // A project with no .git: the root is the nearest package.json.
+ await fs.promises.writeFile(path.join(project, "package.json"), "{}");
+ 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 font = path.join(fonts, "Test.ttf");
+ await fs.promises.writeFile(font, "font-bytes");
+
+ const session = await start({ entry: comp }, { open: false, port: 0 });
+ const res = await fetch(`${session.url}${font.slice(1)}`);
+ expect(res.status).toBe(200);
+ expect(await res.text()).toBe("font-bytes");
+ } finally {
+ await fs.promises.rm(project, { recursive: true, force: true });
+ }
+ });
+
+ it("allows extra asset roots outside the project", async () => {
+ const project = await fs.promises.mkdtemp(
+ path.join(os.tmpdir(), "gf-project-"),
+ );
+ const shared = await fs.promises.mkdtemp(
+ path.join(os.tmpdir(), "gf-shared-"),
+ );
+ try {
+ const src = path.join(project, "src");
+ await fs.promises.mkdir(src, { recursive: true });
+ await fs.promises.writeFile(path.join(project, "package.json"), "{}");
+ 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 font = path.join(shared, "Shared.ttf");
+ await fs.promises.writeFile(font, "shared-bytes");
+
+ const session = await start(
+ { entry: comp },
+ { open: false, port: 0, root: [project, shared] },
+ );
+ const res = await fetch(`${session.url}${font.slice(1)}`);
+ expect(res.status).toBe(200);
+ expect(await res.text()).toBe("shared-bytes");
+ } finally {
+ await fs.promises.rm(project, { recursive: true, force: true });
+ await fs.promises.rm(shared, { recursive: true, force: true });
+ }
+ });
+
it("names a missing export", async () => {
await expect(
startPreview({ entry, export: "film" }, { open: false, port: 0 }),
diff --git a/plugins/gitframes/skills/gitframes-render/SKILL.md b/plugins/gitframes/skills/gitframes-render/SKILL.md
index 6deb67d8..95a375e6 100644
--- a/plugins/gitframes/skills/gitframes-render/SKILL.md
+++ b/plugins/gitframes/skills/gitframes-render/SKILL.md
@@ -125,7 +125,7 @@ console.log(`Preview at ${session.url}`);
await session.closed; // keep the process alive while the user watches
```
-- **The export is a function returning the `Composition`** (it may be async), or a `Composition` itself. The browser calls it, so build-time Node code in it must stay simple: `node:path`, `fileURLToPath(import.meta.url)` and synchronous `fs` reads (JSON, text) work through shims; writes are skipped. Assets referenced by absolute path load from the server, limited to the repository that holds the entry (`root` overrides it).
+- **The export is a function returning the `Composition`** (it may be async), or a `Composition` itself. The browser calls it, so build-time Node code in it must stay simple: `node:path`, `fileURLToPath(import.meta.url)` and synchronous `fs` reads (JSON, text) work through shims; writes are skipped. Assets referenced by absolute path load from the server, limited to the project that holds the entry (its nearest `.git` or `package.json`); pass `root` with one or more paths for assets kept outside it (e.g. a shared fonts folder).
- **Run it in the background.** The preview serves until it is stopped. Start the script as a background command with the longest timeout your harness allows, tell the user the URL, and ask for feedback in the chat. Feedback comes from the user, not from the page.
- **One tab for the whole loop.** The port is fixed per project directory. Running the preview again (after you've made changes) takes over from the one already running, and a tab left open reconnects and reloads into the new version by itself. Don't ask the user to reopen anything. When the user closes the tab, the preview stops by itself about 5 s later (a reload doesn't stop it). If the preview was stopped (tab closed, time limit, or you killed it), just start it again.
- **Show it where the user is.** `startPreview` only serves the page and returns the URL. If your app has a built-in browser (Claude Code's browser pane, Codex's), open the URL there. Otherwise give the user the link, or pass `open: true` to open their default browser (skipped when an open tab reconnects on its own). The page needs WebGPU (current Chrome, Edge or Safari).