Skip to content

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

Quiet render logs; approve skia-canvas install script in setup skill

okanasl56201a9744db
diff --git a/packages/renderer/src/dynamic-node-discovery.ts b/packages/renderer/src/dynamic-node-discovery.ts
index 3e6307a5..78d94c62 100644
--- a/packages/renderer/src/dynamic-node-discovery.ts
+++ b/packages/renderer/src/dynamic-node-discovery.ts
@@ -6,6 +6,7 @@ import {
type NodeRendererPlugin,
registerWebGPURenderer,
} from "@gitframes/node-sdk";
+import { rendererLogger } from "@gitframes/server-utils";
import { BUILTIN_NODE_RENDERERS } from "./generated/node-renderers.js";
import {
loadNodeManifests,
@@ -146,7 +147,7 @@ export async function discoverAndRegisterNodeRenderers(): Promise<void> {
return;
}
- console.log(
+ rendererLogger.debug(
`[HeadlessWebGPURenderer] Discovering node renderers in: ${nodesDir}`,
);
diff --git a/packages/webgpu-renderers/src/debug-log.ts b/packages/webgpu-renderers/src/debug-log.ts
new file mode 100644
index 00000000..b9b938fe
--- /dev/null
+++ b/packages/webgpu-renderers/src/debug-log.ts
@@ -0,0 +1,8 @@
+/** Debug output: shown only with LOG_LEVEL=debug or trace. */
+export const DEBUG_LOGS =
+ typeof process !== "undefined" &&
+ /^(debug|trace)$/i.test(process.env?.LOG_LEVEL ?? "");
+
+export function debugLog(...args: unknown[]): void {
+ if (DEBUG_LOGS) console.debug(...args);
+}
diff --git a/packages/webgpu-renderers/src/headless-font-loader.ts b/packages/webgpu-renderers/src/headless-font-loader.ts
index d1e40719..9cf09200 100644
--- a/packages/webgpu-renderers/src/headless-font-loader.ts
+++ b/packages/webgpu-renderers/src/headless-font-loader.ts
@@ -1,4 +1,5 @@
import { BASE_URL } from "@gitframes/client-utils";
+import { debugLog } from "./debug-log.js";
let tempDir: string | null = null;
const fontPathCache = new Map<string, string>();
@@ -96,8 +97,10 @@ export async function registerHeadlessFont(
try {
const fontPath = await getLocalFontPath(family, url);
fontPaths.set(family, fontPath);
- console.log(
- `[registerHeadlessFont] Headless font registered: "${family}" from URL: ${url} -> saved to local path: ${fontPath}`,
+ debugLog(
+ fontPath === url
+ ? `[registerHeadlessFont] Registered "${family}" from ${fontPath}`
+ : `[registerHeadlessFont] Registered "${family}" from ${url} (cached at ${fontPath})`,
);
try {
@@ -146,7 +149,7 @@ export async function getHeadlessFontData(
// because Node.js Buffer instances can share an internal global pool.
const uint8 = new Uint8Array(buf.length);
uint8.set(buf);
- console.log(
+ debugLog(
`[getHeadlessFontData] Read local font binary for "${family}" from: ${path} (${uint8.length} bytes)`,
);
fontDataCache.set(family, uint8);
diff --git a/packages/webgpu-renderers/src/headless/init.ts b/packages/webgpu-renderers/src/headless/init.ts
index 61d19981..d1aed145 100644
--- a/packages/webgpu-renderers/src/headless/init.ts
+++ b/packages/webgpu-renderers/src/headless/init.ts
@@ -1,3 +1,4 @@
+import { debugLog } from "../debug-log.js";
import { HeadlessDOMMatrix } from "./dom-matrix.js";
export async function initHeadlessWebGPU(): Promise<void> {
@@ -19,7 +20,7 @@ export async function initHeadlessWebGPU(): Promise<void> {
if (!(globalThis as any).navigator?.gpu) {
const gpu = create([]);
- console.log("WebGPU created", gpu);
+ debugLog("[webgpu] Created headless GPU");
if (!(globalThis as any).navigator) {
try {
(globalThis as any).navigator = { gpu };
diff --git a/packages/webgpu-renderers/src/nodes/lottie.ts b/packages/webgpu-renderers/src/nodes/lottie.ts
index a1c56756..34e693dc 100644
--- a/packages/webgpu-renderers/src/nodes/lottie.ts
+++ b/packages/webgpu-renderers/src/nodes/lottie.ts
@@ -18,6 +18,7 @@ function resolveUrl(url: string): string {
return url;
}
+import { debugLog } from "../debug-log.js";
import type { RenderContextValue } from "../render-context.js";
import { textureCache } from "../texture-cache.js";
import type { LottieNodeProps } from "./types.js";
@@ -104,7 +105,7 @@ async function registerLottieFont(family: string): Promise<void> {
const baseFamily = getBaseFontFamily(family);
let fontUrl = GetFontAssetUrl(baseFamily);
- console.log(
+ debugLog(
`[LottieRenderer] Registering font: "${family}" (base: "${baseFamily}") from URL: ${fontUrl}`,
);
diff --git a/packages/webgpu-renderers/src/slug/slug-font-cache.ts b/packages/webgpu-renderers/src/slug/slug-font-cache.ts
index 83a917f8..07cad9e5 100644
--- a/packages/webgpu-renderers/src/slug/slug-font-cache.ts
+++ b/packages/webgpu-renderers/src/slug/slug-font-cache.ts
@@ -1,13 +1,9 @@
import * as fontkit from "fontkit";
+import { debugLog } from "../debug-log.js";
import type { FontkitFont } from "./slug-generator.js";
import { SlugGenerator } from "./slug-generator.js";
import type { SlugFont } from "./slug-loader.js";
-/** Per-font load timings are debug output: shown only with LOG_LEVEL=debug or trace. */
-const VERBOSE_FONT_LOGS =
- typeof process !== "undefined" &&
- /^(debug|trace)$/i.test(process.env?.LOG_LEVEL ?? "");
-
export type FontLoadListener = (fontFamily: string) => void;
export function parseFontWeight(fontWeight?: string | number): number {
@@ -736,13 +732,12 @@ export class SlugFontCache {
const generated = generator.generate(device, font);
const generateTime = performance.now();
- if (VERBOSE_FONT_LOGS)
- console.log(
- `[SlugFontCache] Preloaded and parsed font "${fontFamily}":\n` +
- ` - fontkit parse: ${(parseTime - startTime).toFixed(2)}ms\n` +
- ` - slug generation: ${(generateTime - parseTime).toFixed(2)}ms\n` +
- ` - total: ${(generateTime - startTime).toFixed(2)}ms`,
- );
+ debugLog(
+ `[SlugFontCache] Preloaded and parsed font "${fontFamily}":\n` +
+ ` - fontkit parse: ${(parseTime - startTime).toFixed(2)}ms\n` +
+ ` - slug generation: ${(generateTime - parseTime).toFixed(2)}ms\n` +
+ ` - total: ${(generateTime - startTime).toFixed(2)}ms`,
+ );
generated.fontFamily = fontFamily;
SlugFontCache.cache.set(fontFamily, generated);
@@ -846,7 +841,7 @@ export class SlugFontCache {
document.fonts.add(loadedFace);
await document.fonts.ready;
- console.log(
+ debugLog(
"[SlugFontCache] Emoji font preloaded and registered via Cache API.",
);
diff --git a/packages/webgpu-renderers/src/slug/slug-loader.ts b/packages/webgpu-renderers/src/slug/slug-loader.ts
index 52b35a95..cbc7503c 100644
--- a/packages/webgpu-renderers/src/slug/slug-loader.ts
+++ b/packages/webgpu-renderers/src/slug/slug-loader.ts
@@ -1,3 +1,5 @@
+import { debugLog } from "../debug-log.js";
+
const SLUGGISH_HEADER_DATA = "SLUGGISH";
const TEXTURE_WIDTH = 4096;
@@ -158,7 +160,7 @@ export class SlugLoader {
);
const elapsed = performance.now() - startTime;
- console.log(
+ debugLog(
`[SlugLoader] Parsed slug binary (${codePoints.size} glyphs) in ${elapsed.toFixed(2)}ms`,
);
diff --git a/plugins/gitframes/skills/gitframes/SKILL.md b/plugins/gitframes/skills/gitframes/SKILL.md
index c3a58aad..a543494a 100644
--- a/plugins/gitframes/skills/gitframes/SKILL.md
+++ b/plugins/gitframes/skills/gitframes/SKILL.md
@@ -26,14 +26,42 @@ This skill takes a project from nothing to a verified first render. For anything
## 2. Install
-Use the package manager the project already uses (look for `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, or `package-lock.json`):
+Use the package manager the project already uses (look for `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, or `package-lock.json`).
+
+**Write `package.json` before installing.** npm 11, pnpm 10, and bun block dependency install scripts unless the project approves them, and gitframes needs exactly one: `skia-canvas` downloads its native binary in its install script. Without it, `import "gitframes"` fails with `Cannot find module '.../skia.node'`. The other packages that ship install scripts work without them, so deny them to keep installs quiet and skip downloads gitframes never uses.
+
+For a new project, create `package.json` with all three blocks. In an existing project, merge them into its `package.json`, keeping any entries it already has:
+
+```json
+{
+ "name": "my-film",
+ "private": true,
+ "type": "module",
+ "allowScripts": {
+ "skia-canvas": true,
+ "sharp": false,
+ "webgpu": false,
+ "onnxruntime-node": false,
+ "node-av": false
+ },
+ "pnpm": {
+ "onlyBuiltDependencies": ["skia-canvas"],
+ "ignoredBuiltDependencies": ["sharp", "webgpu", "onnxruntime-node", "node-av"]
+ },
+ "trustedDependencies": ["skia-canvas"]
+}
+```
+
+`allowScripts` is read by npm, `pnpm` by pnpm, and `trustedDependencies` by bun; each tool ignores the others' fields. Yarn runs install scripts by default and needs none of them. Then install:
```bash
npm install gitframes
npm install --save-dev tsx typescript @types/node
```
-For a new project, run `npm init -y` first and set `"type": "module"` in `package.json`. A minimal `tsconfig.json`:
+The install must finish without an `install-scripts` warning. If gitframes was installed before the approval was in place, add it and rerun the skipped script with `npm rebuild skia-canvas` (`pnpm rebuild skia-canvas`). Never approve every script wholesale (`npm install-scripts approve --all`).
+
+A minimal `tsconfig.json`:
```json
{