Skip to content

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

feat(renderer-service): render with each project's own framefields

okanaslffd8993c85bb
diff --git a/.github/workflows/renderer-image.yml b/.github/workflows/renderer-image.yml
index c20952a7..c01eaacb 100644
--- a/.github/workflows/renderer-image.yml
+++ b/.github/workflows/renderer-image.yml
@@ -76,8 +76,8 @@ jobs:
load: ${{ matrix.variant == 'slim' }}
cache-from: type=gha,scope=renderer-${{ matrix.variant }}
cache-to: type=gha,mode=max,scope=renderer-${{ matrix.variant }}
- - name: Smoke test (no GPU; checks the image boots its config and tools)
+ - name: Smoke test (no GPU; checks tools, pinned host keys, and that no engine is baked in)
if: matrix.variant == 'slim'
run: |
tag=$(echo "${{ steps.meta.outputs.tags }}" | cut -d, -f1)
- docker run --rm --entrypoint bash "$tag" -c 'git --version && git lfs version && ffprobe -version | head -1 && test -s apps/renderer-service/deploy/known_hosts'
+ docker run --rm --entrypoint bash "$tag" -c 'git --version && git lfs version && ffprobe -version | head -1 && test -s /app/deploy/known_hosts && test ! -e /app/node_modules/framefields'
diff --git a/apps/renderer-service/Dockerfile b/apps/renderer-service/Dockerfile
index 8ac602c2..ee48a301 100644
--- a/apps/renderer-service/Dockerfile
+++ b/apps/renderer-service/Dockerfile
@@ -1,80 +1,61 @@
# framefields renderer worker (apps/renderer-service/PLAN.md §12).
#
+# The image contains the worker only, with no framefields engine. Each job
+# renders with the framefields version its own repo installs (package.json +
+# lockfile), so the runtime stage carries the system libraries that
+# framefields' native modules (WebGPU/Dawn, skia, sharp, webcodecs) need.
+#
# Build from the repo root:
# docker build -f apps/renderer-service/Dockerfile -t framefields-renderer .
# docker build -f apps/renderer-service/Dockerfile --build-arg VARIANT=full -t framefields-renderer:full .
#
# VARIANT=full adds a C/C++ toolchain for projects whose native dependencies
-# have no prebuilt binaries.
-
-ARG NODE_IMAGE=node:24-bookworm-slim
+# have no prebuilt binaries for linux-x64.
-# ─── Stage 0: base ────────────────────────────────────────────────────────────
-FROM ${NODE_IMAGE} AS base
-WORKDIR /app
-ENV NODE_ENV=production
-RUN apt-get update && apt-get install -y --no-install-recommends openssl \
- && rm -rf /var/lib/apt/lists/*
+# Debian 13 (trixie): prebuilt WebGPU/Dawn binaries in npm need glibc >= 2.38.
+ARG NODE_IMAGE=node:24-trixie-slim
-# ─── Stage 1: prune the monorepo to the service and its node packages ────────
-FROM base AS pruner
+# ─── Stage 1: prune the monorepo to the service ──────────────────────────────
+FROM ${NODE_IMAGE} AS pruner
+WORKDIR /repo
RUN npm install -g turbo@2
COPY turbo.json package.json pnpm-workspace.yaml pnpm-lock.yaml ./
COPY packages/ packages/
COPY apps/ apps/
COPY nodes/ nodes/
-RUN NODE_PACKAGES=$(node -e "const fs=require('fs');console.log(fs.readdirSync('nodes').filter(d=>fs.statSync('nodes/'+d).isDirectory()).map(d=>{try{return require('./nodes/'+d+'/package.json').name}catch{return null}}).filter(Boolean).join(' '))") && \
- turbo prune @framefields/renderer-service $NODE_PACKAGES --docker
-
-# ─── Stage 2: build ──────────────────────────────────────────────────────────
-FROM base AS builder
-RUN apt-get update && apt-get install -y --no-install-recommends \
- build-essential git ca-certificates pkg-config python3 \
- libxi-dev libglu1-mesa-dev libglew-dev libgl1-mesa-dev \
- libvulkan-dev libfontconfig1-dev \
- && ln -s /usr/bin/python3 /usr/bin/python \
- && rm -rf /var/lib/apt/lists/*
+RUN turbo prune @framefields/renderer-service --docker
-COPY --from=pruner /app/out/json/ .
-COPY --from=pruner /app/out/pnpm-lock.yaml ./pnpm-lock.yaml
-RUN corepack enable && \
- pnpm config set package-import-method copy && \
- pnpm install --frozen-lockfile
-
-COPY --from=pruner /app/out/full/ .
-ENV NODE_OPTIONS="--max-old-space-size=6144"
-# Everything pruned in: node packages are discovered at runtime, not imported.
-RUN pnpm exec turbo run build
-
-RUN pnpm install --prod --frozen-lockfile
-# Linux native bindings for webcodecs, then rebuild native modules for this arch.
-RUN pnpm --filter=@framefields/renderer add @napi-rs/webcodecs-linux-x64-gnu @napi-rs/webcodecs-linux-arm64-gnu
-RUN pnpm rebuild -r sharp skia-canvas webgpu gl @napi-rs/webcodecs mediabunny
-RUN find /app/node_modules -name "prebuild.mjs" -path "*/skia-canvas/*" -exec sh -c 'cd "$(dirname {})/.." && node lib/prebuild.mjs download --or-compile' \;
-RUN find /app/node_modules -name "skia.node" | grep -q skia.node || (echo "ERROR: skia.node missing!" && exit 1)
-
-# Pinned SSH host keys for github.com / gitlab.com / bitbucket.org (§6.5).
+# ─── Stage 2: build the service and a standalone copy of it ──────────────────
+FROM ${NODE_IMAGE} AS builder
+WORKDIR /repo
RUN apt-get update && apt-get install -y --no-install-recommends openssh-client \
- && apps/renderer-service/deploy/known-hosts.sh
-
-RUN find /app -type d \( -name ".turbo" -o -name ".cache" \) -exec rm -rf {} + 2>/dev/null || true && \
- find /app -name "*.tsbuildinfo" -delete 2>/dev/null || true && \
- rm -rf /root/.local /root/.cache /root/.npm /tmp/*
+ && rm -rf /var/lib/apt/lists/* && corepack enable
+COPY --from=pruner /repo/out/json/ .
+COPY --from=pruner /repo/out/pnpm-lock.yaml ./pnpm-lock.yaml
+# Scripts off: nothing here is built natively; workspace packages pulled in as
+# test-only devDependencies (framefields) are installed but never built.
+RUN pnpm install --frozen-lockfile --ignore-scripts
+COPY --from=pruner /repo/out/full/ .
+RUN pnpm --filter @framefields/renderer-service build \
+ && pnpm --filter @framefields/renderer-service deploy --prod --legacy /out \
+ # Pinned SSH host keys for github.com / gitlab.com / bitbucket.org (§6.5).
+ && /out/deploy/known-hosts.sh
# ─── Stage 3: runtime ────────────────────────────────────────────────────────
-FROM base AS runner
+FROM ${NODE_IMAGE} AS runner
ARG VARIANT=slim
-# Rendering (GL/Vulkan/fonts), ffmpeg/ffprobe (output checks), git + LFS +
-# ssh (checkouts), tini (PID 1: forwards signals, reaps git subprocesses),
-# python3 + runpod (serverless shim).
+# Rendering (Vulkan/GL/fonts/media libs for framefields' native modules),
+# ffmpeg/ffprobe (output checks), git + LFS + ssh (checkouts), tini (PID 1:
+# forwards signals, reaps git/install subprocesses), python3 + runpod (shim).
RUN apt-get update && apt-get install -y --no-install-recommends \
- libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
- libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 \
- libgbm1 libpango-1.0-0 libcairo2 libasound2 \
- libgl1-mesa-dri libglapi-mesa libegl1 libvulkan1 libfontconfig1 \
+ ca-certificates openssl \
+ libnss3 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 libdrm2 \
+ libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libxi6 \
+ libgbm1 libpango-1.0-0 libcairo2 libasound2t64 \
+ libgl1-mesa-dri libglapi-mesa libegl1 libvulkan1 mesa-vulkan-drivers libfontconfig1 \
ffmpeg xvfb xauth \
- git git-lfs openssh-client ca-certificates tini \
+ git git-lfs openssh-client tini \
python3 python3-pip \
&& if [ "$VARIANT" = "full" ]; then \
apt-get install -y --no-install-recommends build-essential python3-dev pkg-config; \
@@ -85,25 +66,26 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
RUN pip3 install --no-cache-dir "runpod>=1.7,<2" --break-system-packages
-ENV NVIDIA_VISIBLE_DEVICES=all \
+ENV NODE_ENV=production \
+ NVIDIA_VISIBLE_DEVICES=all \
NVIDIA_DRIVER_CAPABILITIES=graphics,utility,video,compute \
FF_WORK_DIR=/tmp/framefields \
- RENDERER_PORT=8082
+ RENDERER_PORT=8082 \
+ COREPACK_HOME=/var/cache/framefields/corepack
RUN groupadd --system --gid 1001 framefields && \
useradd --system --uid 1001 -m -g framefields framefields && \
mkdir -p /var/cache/framefields /tmp/framefields && \
- chown -R framefields:framefields /var/cache/framefields /tmp/framefields
+ chown -R framefields:framefields /var/cache/framefields /tmp/framefields && \
+ corepack enable
-ENV COREPACK_HOME=/var/cache/framefields/corepack
WORKDIR /app
-COPY --from=builder --chown=framefields:framefields /app .
-RUN corepack enable
+COPY --from=builder --chown=framefields:framefields /out .
USER framefields
EXPOSE 8082
-HEALTHCHECK --interval=30s --timeout=5s --start-period=120s --retries=3 \
+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
CMD node -e "fetch('http://127.0.0.1:'+(process.env.RENDERER_PORT||8082)+'/health').then(r=>process.exit(r.status===200?0:1),()=>process.exit(1))"
-ENTRYPOINT ["/usr/bin/tini", "-g", "--", "apps/renderer-service/docker/entrypoint.sh"]
+ENTRYPOINT ["/usr/bin/tini", "-g", "--", "/app/docker/entrypoint.sh"]
diff --git a/apps/renderer-service/PLAN.md b/apps/renderer-service/PLAN.md
index 82e89b3c..1f96e354 100644
--- a/apps/renderer-service/PLAN.md
+++ b/apps/renderer-service/PLAN.md
@@ -5,7 +5,7 @@ Status: **draft, decisions recorded**, 2026-10-14. Branch: `feat/renderer-self-d
### Decisions (2026-10-14)
1. **Rendering runs in the main service process** (revised 2026-10-14; this replaces the earlier child-process design). The repo's entry module is imported into the long-lived worker and rendered with the worker's warm GPU device. Section 8 covers what this costs and how each cost is handled.
-2. **Engine source: `bundled`.** This follows from decision 1, because one process can only hold one GPU stack. Imports of `framefields` and `@framefields/*` from repo code resolve to the worker's own copy. The project's lockfile version is still checked (section 7). The earlier `project` default, where each job used the framefields version in its lockfile, is dropped.
+2. **Engine source: the project's own `framefields`** (revised 2026-10-14; this replaces the earlier bundled engine). The image contains no engine. Each repo installs the framefields version it pins in `package.json` and its lockfile, and the worker renders with that install. One process can hold only one GPU stack, so a worker **binds** to the version its first job installs. Later jobs on the same version share that warm engine, even from other repos. A job needing another version fails with retryable `ENGINE_SWITCH`, and the worker recycles so the retry gets a fresh process (§7).
3. **Script mode is dropped.** A package script always runs as its own process, so it can't render in the main process. Its use cases (several outputs, contact sheets, parametrised variants) are covered by letting an export return several compositions or a render plan (section 4).
4. **The inline `virtualMedia` path is removed.** That covers the legacy input mapping, the v1 `/run` and `/status` routes, `cli.ts --job <json>`, `configureAssetUrls` and `BASE_URL`, and the `R2_*` env names. There are no callers left.
5. **Git hosts:** GitHub, GitLab, Bitbucket and self-hosted servers (GitLab self-managed, Gitea/Forgejo, plain git over HTTPS/SSH) are all in scope from the start (section 6.5).
@@ -156,7 +156,7 @@ Security-relevant settings (allowlists, credentials, limits, output buckets) can
"status": "COMPLETED",
"jobId": "…",
"source": { "repo": "https://github.com/acme/promo-videos.git", "ref": "main", "sha": "9f2c1e…", "workdir": "videos/launch" },
- "engine": { "framefields": "2.1.3", "source": "bundled", "projectDeclared": "^2.1.0" },
+ "engine": { "framefields": "2.1.3", "source": "project", "workerHooks": true, "projectDeclared": "^2.1.0" },
"outputs": [{ "key": "acme/9f2c1e4/….mp4", "url": "https://…", "bytes": 48213311, "sha256": "…", "contentType": "video/mp4", "durationMs": 12000, "frames": 720 }],
"qa": { /* VideoQaReport when requested */ },
"timings": { "resolveMs": 210, "fetchMs": 1830, "lfsMs": 9400, "installMs": 0, "loadMs": 900, "renderMs": 61000, "uploadMs": 3100 },
@@ -315,11 +315,15 @@ Rules that apply to every host:
- **Install scripts** are on by default, because the native GPU, skia and webcodecs modules need them. `FF_INSTALL_SCRIPTS=false` turns them off. The build toolchain is only present in the `-full` image (section 11).
- **Private registries:** `FF_NPMRC` (secret, file contents) is written to a temp `.npmrc` that is used only for the install.
- **Prepare steps (optional):** `install.prepare: ["fonts"]` in the repo file runs those package scripts after the install, under the same timeout. It is used for fetching fonts and similar setup.
-- **Engine alias (always on).** A `module.register` resolve hook, installed once at boot, maps every `framefields` and `@framefields/*` import from inside a workspace to the worker's own copy. This happens however the project declares the dependency (npm range or `workspace:*`). Repo code therefore shares the worker's single, already-initialised GPU stack, and a second copy of Dawn or skia never gets loaded.
-- **The project's own copy of framefields is installed but never loaded.** Leaving it out of the install would mean changing the overrides, which breaks the frozen-lockfile check, so the install runs as is and the alias wins at import time. The cost is mostly prebuild downloads, which the shared store absorbs after the first install.
-- **Skip the install** entirely when the project's only runtime dependencies are framefields packages, which is the common case. This is the fast path.
-- **Engine check:** compare the version range the project declares with the bundled version.
- - If the bundled version doesn't satisfy it, apply `FF_ENGINE_POLICY=warn|fail` (default `warn`, which adds `ENGINE_MISMATCH` to the warnings).
+- **The project must depend on framefields** (in the workdir's or the workspace root's `package.json`); otherwise the job fails with `ENGINE_NOT_FOUND`. There is no "skip the install" fast path, because the engine itself comes from the install. A warm workspace with an unchanged stamp skips the install instead.
+- **Engine binding** (`render/engine.ts`, `render/engine-alias.ts`):
+ - The first job resolves `framefields` from its workdir, imports it (ESM build), and calls `HeadlessMediaRenderer.initialize()`. That is the worker's engine for the rest of its life.
+ - A synchronous `module.registerHooks` resolve hook then maps every `framefields` / `@framefields/*` import from any workspace to the bound engine's package. Two repos on the same version share one GPU stack, even though each has its own `node_modules`.
+ - A job whose project installs a **different version** fails with `ENGINE_SWITCH` (retryable). The worker recycles, and RunPod or the caller's retry lands on a fresh worker that binds the new version. Workers that serve one project, or projects pinned to one version, never switch.
+ - The janitor never evicts the workspace the bound engine was loaded from.
+- **Dependencies stay cached by path** for the life of the process, and they are shared with the engine (one copy of `mediabunny` and similar). A new install in a workspace this process already loaded modules from can't take effect in-process. So after installing, the job fails with `ENGINE_SWITCH` and the worker recycles; the retry gets a fresh process, and the install is already done.
+- **Older engines without worker hooks.** Some framefields versions predate `resetRenderCaches`, `signal` and `onProgress` (2.1.3, the current release, among them). They still render, but stall detection is off, cancellation relies on the grace period, and the worker recycles after each job rather than risk stale path-keyed caches. The warning is `ENGINE_NO_WORKER_HOOKS`.
+- **npm runs as shipped with Node** unless the project pins `packageManager`. Corepack's unpinned npm can be a different major than the one that wrote the lockfile, which made `npm ci` fail on lockfile sync. pnpm and yarn always go through corepack.
- `engines.node` mismatches only produce a warning.
## 8. Render execution (in-process)
@@ -336,7 +340,7 @@ Rules that apply to every host:
- A missing module gives `ENTRY_NOT_FOUND`. A TS or syntax error gives `ENTRY_COMPILE_FAILED`, with the first frames of the error.
3. Read the export (`EXPORT_NOT_FOUND`). If it is a function, call it with `args`. A throw here gives `COMPOSITION_BUILD_FAILED`.
4. Normalise the result to a render plan (section 4). Anything that isn't a Composition, a record of compositions, or a plan gives `EXPORT_INVALID`.
-5. **Composition from a different engine instance.** If the result was built by some other copy of framefields (the alias was bypassed, for example by a bundled `dist/` inside the repo), `instanceof` fails. The worker then falls back to `toVirtualMedia()` and renders that with its own renderer, adding the warning `ENGINE_FOREIGN_INSTANCE`.
+5. **Composition from a different engine instance.** If the result was built by some other copy of framefields (the alias was bypassed, for example by a bundled `dist/` inside the repo), `instanceof` fails. The worker renders it anyway, through its own methods, with the bound engine's renderer, and adds the warning `ENGINE_FOREIGN_INSTANCE`.
### 8.2 Job sandbox
@@ -439,7 +443,8 @@ Every failure maps to a stable `code`. `retryable` is what RunPod or the caller
| lfs | `UNSUPPORTED_GIT_FILTER` | no | `git-crypt` and similar. |
| any | `DISK_FULL` | yes (other worker) | Raised by the preflight or by ENOSPC. |
| install | `LOCKFILE_MISSING` / `INSTALL_FAILED` / `INSTALL_TIMEOUT` | no / no / yes | The tail of the install log is attached. |
-| install | `ENGINE_INCOMPATIBLE` | no | Only with `FF_ENGINE_POLICY=fail`. |
+| install | `ENGINE_NOT_FOUND` | no | The project doesn't depend on, or didn't install, framefields. |
+| install / render | `ENGINE_SWITCH` | yes (fresh worker) | The project needs a different framefields version than the worker bound, or its dependencies changed after the worker loaded them. The worker recycles. |
| load | `ENTRY_NOT_FOUND` / `ENTRY_COMPILE_FAILED` / `EXPORT_NOT_FOUND` / `EXPORT_INVALID` / `EXPORT_SIDE_EFFECT` / `COMPOSITION_BUILD_FAILED` | no | The user's stack trace is attached and trimmed to the project's files. |
| render | `ASSET_NOT_FOUND` | no | A referenced file is missing. Often an LFS include that is too narrow, so the hint says so. |
| render | `RENDER_FAILED` / `RENDER_STALLED` / `RENDER_TIMEOUT` | no / yes / no | |
@@ -450,7 +455,7 @@ Every failure maps to a stable `code`. `retryable` is what RunPod or the caller
| upload | `UPLOAD_AUTH_FAILED` | no | Storage rejected the credentials or the bucket policy (`AccessDenied`, `InvalidAccessKeyId`, `SignatureDoesNotMatch`). |
| any | `CANCELLED` / `SHUTDOWN` | no / yes | `SHUTDOWN` means the worker was preempted or scaled down mid-job. |
-Warnings don't fail a job; they are listed in the result's `warnings`. They include `ENGINE_MISMATCH` (the declared framefields range isn't satisfied by the bundled engine, under `warn` policy), `ENGINE_FOREIGN_INSTANCE` (8.1), and `NODE_ENGINE_MISMATCH`.
+Warnings don't fail a job; they are listed in the result's `warnings`. They include `ENGINE_NO_WORKER_HOOKS` (an older framefields; the worker recycles after the job), `ENGINE_FOREIGN_INSTANCE` (8.1), `LFS_POINTERS_LEFT` and `NODE_ENGINE_MISMATCH`.
## 11. Configuration reference (env)
@@ -463,7 +468,7 @@ On boot the service validates **all** keys and fails with the complete list of p
| Mode | `FF_MODE` (`runpod-serverless` if `RUNPOD_POD_ID` is set, else `http`), `RENDERER_PORT` (8082), `RENDERER_API_KEY`, `FF_HTTP_INSECURE` (false), `LOG_LEVEL` (info), `LOG_FORMAT` (json) |
| Source | `FF_DEFAULT_REPO`, `FF_DEFAULT_REF` (`main`), `FF_REPO_ALLOWLIST` (comma globs), `FF_ALLOW_LOCAL_REPOS` (false), `FF_GIT_FETCH` (`mirror`\|`single`), `FF_LFS_CONCURRENCY` (8), `FF_LFS_DEFAULT_INCLUDE` |
| Git auth & hosts | `GIT_TOKEN`, `GIT_USERNAME`, `FF_GIT_CREDENTIALS` (`{host: token \| {username, token}}`), `FF_GIT_HOSTS` (`{host: github\|gitlab\|bitbucket\|gitea\|generic}`), `FF_GIT_CA_BUNDLE`, `GIT_SSH_KEY`, `GIT_SSH_KNOWN_HOSTS`, `FF_SSH_ACCEPT_NEW` (false), `FF_ALLOW_JOB_CREDENTIALS` (false) |
-| Install | `FF_INSTALL_SCRIPTS` (true), `FF_ALLOW_UNLOCKED_INSTALL` (false), `FF_NPMRC`, `FF_ENGINE_POLICY` (`warn`) |
+| Install | `FF_INSTALL_SCRIPTS` (true), `FF_ALLOW_UNLOCKED_INSTALL` (false), `FF_NPMRC` |
| Storage | `STORAGE_DRIVER` (`s3`\|`local`\|`none`), `STORAGE_ENDPOINT`, `STORAGE_REGION` (`auto`), `STORAGE_ACCESS_KEY_ID`, `STORAGE_SECRET_ACCESS_KEY`, `STORAGE_BUCKET`, `STORAGE_PUBLIC_BASE_URL`, `STORAGE_FORCE_PATH_STYLE` (MinIO), `FF_OUTPUT_BUCKETS`, `FF_OUTPUT_DIR`, `FF_INLINE_MAX_BYTES`, `FF_OUTPUT_MAX_BYTES`. The `R2_*` names are gone, with no aliases. |
| Paths & cache | `FF_CACHE_DIR`, `FF_WORK_DIR`, `FF_CACHE_MAX_GB` (50), `FF_WORK_MAX_GB` (40), `FRAMEFIELDS_MODELS_DIR` (`$FF_CACHE_DIR/models`), `FRAMEFIELDS_FONTS_DIR` |
| Limits | `FF_QUEUE_MAX` (8), `FF_JOB_TIMEOUT_MAX_SEC` (7200), `FF_TIMEOUT_{GIT,LFS,INSTALL,LOAD,RENDER}_SEC`, `FF_STALL_TIMEOUT_SEC` (300), `FF_KILL_GRACE_SEC` (20), `FF_JOB_TTL_SEC` (3600), `FF_JOB_HISTORY_MAX` (500) |
@@ -478,16 +483,15 @@ The service no longer uses `S3StorageService` from `@framefields/server-utils`,
**Image** (`apps/renderer-service/Dockerfile`, formerly `Dockerfile.renderer`; the build context is still the repo root):
-- **Runtime packages added:** `git`, `git-lfs`, `openssh-client`, `ca-certificates`, `tini` (PID 1, reaps git and install subprocesses), `jq`. Corepack is pre-warmed for pnpm, yarn and npm, and `tsx` ships in the service's prod dependencies (its `tsImport` API is used in-process).
-- **Two variants:**
- - `:<ver>` (slim) has no compiler. It relies on prebuilds and the bundled native modules.
- - `:<ver>-full` adds `build-essential` and `python3-dev`, for projects whose native dependencies need compiling.
-- The user is renamed from `gatewai` to `framefields`. The `HEALTHCHECK` hits `/health`.
-- **Entrypoint fixes:**
- - correct paths (`apps/renderer-service`);
- - `xvfb-run` is used only when `FF_XVFB=auto` and no headless Vulkan/EGL is available;
- - pre-boot checks: GPU visible (`nvidia-smi`, warn only), cache dirs writable, `git lfs install --skip-repo`.
-- **Published to** `ghcr.io/gatewai-dev/framefields-renderer` by a release workflow, tagged from the package version. Multi-arch is not needed because RunPod is amd64.
+- **Worker only, no engine.**
+ - `turbo prune` cuts the repo down to the service, then `pnpm install --ignore-scripts` and a `tsc` build of the service alone (`tsconfig.build.json`, without tests).
+ - `pnpm deploy --prod --legacy` produces a standalone `/app` holding the service's own dependencies (about 52 MB), with no `framefields` or `@framefields/*`.
+- **Base `node:24-trixie-slim`.** The `webgpu` package's prebuilt Dawn binary needs glibc ≥ 2.38. Bookworm (2.36) fails with ``GLIBC_2.38 not found`` once a project installs framefields from npm. Package names follow trixie's t64 rename (`libasound2t64`, …).
+- **Runtime packages:** the system libraries framefields' native modules need (Vulkan/GL including Mesa's software Vulkan driver, fonts, media), plus `ffmpeg`/`ffprobe`, `git`, `git-lfs` (3.6), `openssh-client`, `tini` (PID 1), and python3 with the `runpod` package. Corepack is enabled for projects' pnpm and yarn.
+- **Two variants:** `:<ver>` (slim, no compiler; projects rely on prebuilt binaries) and `:<ver>-full` (adds `build-essential` and `python3-dev`).
+- Runs as user `framefields`. The `HEALTHCHECK` hits `/health`.
+- **Entrypoint (`docker/entrypoint.sh`):** `http` | `runpod-serverless` | `cli`. `xvfb-run` is used only with `FF_XVFB=1`, and the GPU is logged at boot (`nvidia-smi`).
+- **Published to** `ghcr.io/gatewai-dev/framefields-renderer` by `.github/workflows/renderer-image.yml`.
**RunPod template:** `apps/renderer-service/deploy/runpod/`.
@@ -538,14 +542,12 @@ Each phase is its own PR-sized step with tests.
- CLI `--job-file` / `--job -` with `--result-file`. Exit codes: 0 completed, 1 failed, 2 bad invocation or job.
- Server and CLI share `worker/boot.ts`.
- Also done here: cache eviction (§6.4, `worker/janitor.ts`). It runs between jobs (at most every 5 min), and on demand when the LFS disk preflight finds too little space.
-8. **Image + template + compose + docs.** Written, but the image has **not been built yet** (no Docker daemon on the dev machine):
- - `apps/renderer-service/Dockerfile` (`VARIANT=slim|full`; tini, git, git-lfs, ssh, ffmpeg; user `framefields`; `HEALTHCHECK`) and `docker/entrypoint.sh` (`http` | `runpod-serverless` | `cli`).
- - Pinned SSH host keys: `deploy/known_hosts`, verified against `deploy/known_hosts.fingerprints` by `deploy/known-hosts.sh`, which the image build runs. The live keys were checked against the published fingerprints on 2026-10-14.
- - RunPod: `deploy/runpod/{serverless,pod}.template.json` and `create-template.sh` (GraphQL `saveTemplate`).
- - `deploy/docker-compose.yml` with MinIO (validated with `docker compose config`) and `deploy/env.example`.
- - `.github/workflows/renderer-image.yml`: tests, then builds both variants, a no-GPU smoke test, and a push to GHCR on `renderer-v*` tags.
- - `README.md` is the self-hosting guide. A page on the docs website is still to do; the site isn't in this repo.
- - Still to do: the first image build, a GPU smoke test on a RunPod pod and a serverless endpoint, and the nightly host smoke tests (6.5).
+8. **Image + template + compose + docs.** Built and run locally (arm64, Docker on macOS, without a GPU):
+ - **Inside the container:** a file:// repo pinned to the published `[email protected]` went through checkout, then `npm ci` from the registry (40 s cold), then engine binding with GPU init on Mesa's software Vulkan, then a VP9 render, verification and delivery. The output was a valid 2 s VP9/Opus file.
+ - **Findings fixed on the way:** glibc 2.38 (moved to trixie); EPIPE from the `exec` helper writing stdin that git never reads; corepack's npm differing from the lockfile's npm; install errors keeping only npm's usage text.
+ - **Engine issue found (not the worker):** on linux-arm64, `@napi-rs/webcodecs` picks the Rockchip `h264_rkmpp` encoder, which fails with "cannot be used for quantizer-based encoding". H.264 renders fail on ARM Linux; VP9 works. amd64/NVIDIA (RunPod) takes a different path, but this should be fixed in framefields.
+ - Pinned SSH host keys, the RunPod templates and `create-template.sh`, `docker-compose.yml` with MinIO, `env.example`, the release workflow, and the README guide as listed above.
+ - **Still to do:** an amd64 build (CI), a GPU smoke test on a RunPod pod and a serverless endpoint, the nightly host smoke tests (6.5), and a page on the docs website.
9. **(Later)**
- Chunked distributed rendering: split a frame range across N jobs and concat with a stream copy.
- Webhooks on completion (`output.webhook` with an HMAC signature).
diff --git a/apps/renderer-service/README.md b/apps/renderer-service/README.md
index 4569d349..829b337f 100644
--- a/apps/renderer-service/README.md
+++ b/apps/renderer-service/README.md
@@ -29,7 +29,8 @@ job ─▶ resolve ref → fetch (mirror cache) → checkout → git LFS pull
→ import your entry → render on the warm GPU → verify (ffprobe) → upload
```
-- **Your code runs inside the worker process.** Imports of `framefields` and `@framefields/*` resolve to the worker's own copy, so every job shares one initialised GPU device. Each job loads your modules fresh.
+- **Your repo picks the framefields version.** The worker image contains no engine. Each repo depends on `framefields` in its `package.json` (with a committed lockfile), and the worker renders with exactly that install.
+- **Your code runs inside the worker process.** The first job loads its project's framefields and initialises the GPU. Later jobs on the same version reuse that warm engine, even from other repos. A job that needs a different version fails with retryable `ENGINE_SWITCH`, and the worker restarts so the retry loads it. Keep a worker (or endpoint) per framefields version if your projects pin different ones.
- **Everything is pinned to one commit.** A branch is resolved once per job, and the result reports the SHA it rendered.
- **Caches survive between jobs:** git mirrors, LFS objects and package stores live on the cache volume, and checkouts and `node_modules` are reused. A warm job spends almost all its time rendering.
- **The worker protects itself.** It recycles after N jobs, high memory, GPU device loss, or code that won't stop. If it crashes, the job is still reported after the restart.
@@ -70,7 +71,7 @@ docker build -f apps/renderer-service/Dockerfile -t framefields-renderer .
docker build -f apps/renderer-service/Dockerfile --build-arg VARIANT=full -t framefields-renderer:full .
```
-The `full` variant adds a C/C++ toolchain, for projects whose native dependencies have no prebuilt binaries.
+The `full` variant adds a C/C++ toolchain, for projects whose native dependencies have no prebuilt binaries. The image is based on Debian trixie, because the prebuilt WebGPU (Dawn) binaries need glibc 2.38 or newer.
## RunPod
@@ -163,6 +164,8 @@ export const deliverables = () => ({
Don't render or call `process.exit()` at import time: the job fails with `EXPORT_SIDE_EFFECT`. Your repo files load as ES modules even without `"type": "module"`.
+Versions of `framefields` released before worker support (2.1.3 and older) still render. They report no progress, and the worker restarts after each of their jobs to keep caches correct. Newer versions keep the worker warm between jobs.
+
### Render kinds
`render.kind` is one of:
@@ -214,7 +217,6 @@ Everything is set by environment variables. The worker checks them all at startu
| `FF_CACHE_DIR`, `FF_CACHE_MAX_GB`, `FF_WORK_MAX_GB` | Cache location and size limits. Eviction runs automatically. |
| `FF_JOB_TIMEOUT_MAX_SEC`, `FF_STALL_TIMEOUT_SEC` | Time limits. |
| `FF_MAX_JOBS_PER_WORKER` | Recycle after N jobs (default 25). |
-| `FF_ENGINE_POLICY` | `warn` (default) or `fail` when a project asks for a framefields version the worker doesn't have. |
| `FF_NPMRC` | `.npmrc` contents, for private registries. |
## Errors
@@ -238,7 +240,9 @@ A failed job returns:
| `EXPORT_NOT_FOUND` / `EXPORT_INVALID` / `EXPORT_SIDE_EFFECT` | The entry doesn't export a builder the worker can use. |
| `ASSET_NOT_FOUND` | A file the composition references is missing; often an LFS include that's too narrow. |
| `RENDER_TIMEOUT` / `RENDER_STALLED` | The render took too long, or stopped making progress. |
-| `GPU_DEVICE_LOST` / `RENDER_OOM` | Retry. The worker replaces itself. |
+| `ENGINE_NOT_FOUND` | The project doesn't depend on `framefields`, so there is nothing to render with. |
+| `ENGINE_SWITCH` | Retry. The project needs another framefields version, or new dependencies; the worker restarts to load them. |
+| `GPU_DEVICE_LOST` / `RENDER_OOM` / `GPU_UNAVAILABLE` | Retry. The worker replaces itself. |
| `QA_FAILED` | `render.qa.failOn` matched. The outputs are still uploaded and listed. |
## Security
diff --git a/apps/renderer-service/docker/entrypoint.sh b/apps/renderer-service/docker/entrypoint.sh
index 660cafb6..a51a1c13 100755
--- a/apps/renderer-service/docker/entrypoint.sh
+++ b/apps/renderer-service/docker/entrypoint.sh
@@ -6,7 +6,7 @@
# cli: one job; pass the CLI's arguments, e.g. --job-file /jobs/job.json
set -euo pipefail
-SERVICE_DIR=apps/renderer-service
+SERVICE_DIR="$(cd "$(dirname "$0")/.." && pwd)"
MODE="${FF_MODE:-}"
if [ -z "$MODE" ]; then
if [ -n "${RUNPOD_POD_ID:-}" ]; then MODE=runpod-serverless; else MODE=http; fi
diff --git a/apps/renderer-service/package.json b/apps/renderer-service/package.json
index 294848e1..d6c46d7c 100644
--- a/apps/renderer-service/package.json
+++ b/apps/renderer-service/package.json
@@ -4,6 +4,12 @@
"version": "2.1.3",
"type": "module",
"types": "./dist/src/index.d.ts",
+ "files": [
+ "dist/src",
+ "runpod_worker.py",
+ "docker",
+ "deploy"
+ ],
"exports": {
".": {
"types": "./dist/src/index.d.ts",
@@ -13,7 +19,7 @@
"scripts": {
"dev": "tsx watch --tsconfig tsconfig.dev.json --conditions=development src/index.ts",
"typecheck": "tsc -b tsconfig.json",
- "build": "tsc -b tsconfig.json",
+ "build": "tsc -p tsconfig.build.json",
"start": "node dist/src/index.js",
"render": "node dist/src/cli.js",
"test": "vitest run"
@@ -21,21 +27,20 @@
"dependencies": {
"@aws-sdk/client-s3": "^3.1151.0",
"@aws-sdk/lib-storage": "^3.1151.0",
- "@framefields/core": "workspace:*",
- "@framefields/renderer": "workspace:*",
- "@framefields/server-utils": "workspace:*",
"@hono/node-server": "^1.19.11",
"dotenv": "^17.0.1",
- "framefields": "workspace:*",
"hono": "^4.13.7",
+ "pino": "^10.3.1",
"semver": "^7.8.5",
"tsx": "^4.21.0",
"zod": "^4.3.6"
},
"devDependencies": {
+ "@framefields/renderer": "workspace:*",
"@framefields/tsconfig": "workspace:*",
"@types/node": "^24.1.0",
"@types/semver": "^7.8.0",
+ "framefields": "workspace:*",
"typescript": "^5.8.3",
"vitest": "^4.1.5"
}
diff --git a/apps/renderer-service/src/cli.ts b/apps/renderer-service/src/cli.ts
index 3d4238b6..5a48f590 100644
--- a/apps/renderer-service/src/cli.ts
+++ b/apps/renderer-service/src/cli.ts
@@ -67,7 +67,7 @@ for (const signal of ["SIGINT", "SIGTERM"] as const) {
}
try {
- await worker.initGpu();
+ await worker.checkTools();
const record = worker.runner.submit(raw);
const done = await new Promise<JobRecord>((resolve) => {
const check = (r: JobRecord) => {
diff --git a/apps/renderer-service/src/config/schema.ts b/apps/renderer-service/src/config/schema.ts
index 67b2ed81..7fadb393 100644
--- a/apps/renderer-service/src/config/schema.ts
+++ b/apps/renderer-service/src/config/schema.ts
@@ -91,7 +91,6 @@ export const envSchema = z.object({
FF_INSTALL_SCRIPTS: bool(true),
FF_ALLOW_UNLOCKED_INSTALL: bool(false),
FF_NPMRC: z.string().optional(),
- FF_ENGINE_POLICY: z.enum(["warn", "fail"]).default("warn"),
// Storage
STORAGE_DRIVER: z.enum(["s3", "local", "none"]).optional(),
@@ -312,7 +311,6 @@ export function buildConfig(
scripts: e.FF_INSTALL_SCRIPTS,
allowUnlocked: e.FF_ALLOW_UNLOCKED_INSTALL,
npmrc: e.FF_NPMRC,
- enginePolicy: e.FF_ENGINE_POLICY,
},
storage: {
driver: storageDriver,
diff --git a/apps/renderer-service/src/engine.gpu.test.ts b/apps/renderer-service/src/engine.gpu.test.ts
index e3ffb4e9..fd4dc128 100644
--- a/apps/renderer-service/src/engine.gpu.test.ts
+++ b/apps/renderer-service/src/engine.gpu.test.ts
@@ -163,6 +163,7 @@ gpu("in-process render step (real Node loader)", () => {
expect(r.exits).toMatchObject({ ok: false, code: "EXPORT_SIDE_EFFECT" });
expect(r.cancel).toMatchObject({ ok: false, code: "CANCELLED" });
expect(r.after.ok).toBe(true);
+ expect(r.switch).toMatchObject({ ok: false, code: "ENGINE_SWITCH" });
for (const k of [
"video1",
"video2",
diff --git a/apps/renderer-service/src/errors.ts b/apps/renderer-service/src/errors.ts
index 4ad48c54..e008736f 100644
--- a/apps/renderer-service/src/errors.ts
+++ b/apps/renderer-service/src/errors.ts
@@ -54,7 +54,8 @@ const CODES = {
LOCKFILE_MISSING: { phase: "install", retryable: false },
INSTALL_FAILED: { phase: "install", retryable: false },
INSTALL_TIMEOUT: { phase: "install", retryable: true },
- ENGINE_INCOMPATIBLE: { phase: "install", retryable: false },
+ ENGINE_NOT_FOUND: { phase: "install", retryable: false },
+ ENGINE_SWITCH: { phase: "render", retryable: true },
ENTRY_NOT_FOUND: { phase: "load", retryable: false },
ENTRY_COMPILE_FAILED: { phase: "load", retryable: false },
diff --git a/apps/renderer-service/src/git/exec.ts b/apps/renderer-service/src/git/exec.ts
index 20bbac8c..321d746b 100644
--- a/apps/renderer-service/src/git/exec.ts
+++ b/apps/renderer-service/src/git/exec.ts
@@ -47,7 +47,9 @@ export function exec(
const child = spawn(file, args, {
cwd: options.cwd,
env: options.env ?? process.env,
- stdio: ["pipe", "pipe", "pipe"],
+ // No stdin unless we have input: a child that exits without reading
+ // it would otherwise raise EPIPE on our side.
+ stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
detached: process.platform !== "win32",
});
const max = options.maxStdoutBytes ?? 64 * 1024 * 1024;
@@ -56,10 +58,10 @@ export function exec(
let timedOut = false;
let aborted = false;
- child.stdout.setEncoding("utf8").on("data", (d: string) => {
+ child.stdout?.setEncoding("utf8").on("data", (d: string) => {
if (stdout.length < max) stdout += d;
});
- child.stderr.setEncoding("utf8").on("data", (d: string) => {
+ child.stderr?.setEncoding("utf8").on("data", (d: string) => {
stderr = (stderr + d).slice(-64 * 1024);
});
@@ -108,7 +110,12 @@ export function exec(
);
});
- child.stdin.end(options.input ?? "");
+ if (child.stdin) {
+ child.stdin.on("error", () => {
+ // EPIPE: the child exited before reading all input; its exit code says why.
+ });
+ child.stdin.end(options.input);
+ }
});
}
diff --git a/apps/renderer-service/src/http/app.ts b/apps/renderer-service/src/http/app.ts
index 0dd365c1..d7a43c11 100644
--- a/apps/renderer-service/src/http/app.ts
+++ b/apps/renderer-service/src/http/app.ts
@@ -1,5 +1,4 @@
import { createHash, timingSafeEqual } from "node:crypto";
-import { rendererLogger } from "@framefields/server-utils";
import { type Context, Hono, type MiddlewareHandler } from "hono";
import { HTTPException } from "hono/http-exception";
import { streamSSE } from "hono/streaming";
@@ -7,6 +6,7 @@ import type { RendererConfig } from "../config/index.js";
import { RenderError } from "../errors.js";
import type { JobRunner } from "../jobs/runner.js";
import { isTerminal, type JobRecord } from "../jobs/store.js";
+import { rendererLogger } from "../logger.js";
import { loggerMiddleware } from "../middlewares.js";
import { redact } from "../redact.js";
diff --git a/apps/renderer-service/src/index.ts b/apps/renderer-service/src/index.ts
index 8d74d4e5..bd842d52 100644
--- a/apps/renderer-service/src/index.ts
+++ b/apps/renderer-service/src/index.ts
@@ -1,8 +1,8 @@
import { Server as HttpServer } from "node:http";
-import { rendererLogger } from "@framefields/server-utils";
import { serve } from "@hono/node-server";
import { RenderError } from "./errors.js";
import { createApp } from "./http/app.js";
+import { rendererLogger } from "./logger.js";
import { bootWorker, exit } from "./worker/boot.js";
import { workerHealth } from "./worker/health.js";
@@ -67,8 +67,8 @@ if (server instanceof HttpServer) {
server.keepAliveTimeout = 65_000;
}
-worker.initGpu().catch(() => {
- // RunPod should replace a worker without a usable GPU; /health reports it otherwise.
+worker.checkTools().catch(() => {
+ // RunPod should replace a broken worker; /health reports it otherwise.
if (config.mode === "runpod-serverless") exit(1);
});
diff --git a/apps/renderer-service/src/install/installer.test.ts b/apps/renderer-service/src/install/installer.test.ts
index 3b806aba..980c5cef 100644
--- a/apps/renderer-service/src/install/installer.test.ts
+++ b/apps/renderer-service/src/install/installer.test.ts
@@ -7,14 +7,10 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { RenderError } from "../errors.js";
import { CommandError } from "../git/exec.js";
import type { CheckoutResult, StepContext } from "../jobs/pipeline.js";
+import { _resetEngineBinding, markDepsLoaded } from "../render/engine.js";
import { testConfig } from "../test-helpers.js";
-import {
- bundledEngineVersion,
- classifyInstallError,
- install,
- STAMP_FILE,
-} from "./installer.js";
-import { inspectProject, needsNoInstall } from "./project.js";
+import { classifyInstallError, install, STAMP_FILE } from "./installer.js";
+import { inspectProject } from "./project.js";
let tmp: string;
@@ -25,6 +21,7 @@ beforeAll(async () => {
});
afterAll(async () => {
await fs.rm(tmp, { recursive: true, force: true });
+ _resetEngineBinding();
});
async function project(name: string, files: Record<string, unknown>) {
@@ -109,77 +106,62 @@ describe("project inspection", () => {
});
expect(await codeOf(inspectProject(root, root))).toBe("INSTALL_FAILED");
});
-
- it("needs no install when only framefields and tooling are used", () => {
- expect(
- needsNoInstall({
- dependencies: {
- framefields: "^2.1.0",
- "@framefields/compositions": "workspace:*",
- },
- devDependencies: { typescript: "^5", tsx: "^4", "@types/node": "^24" },
- }),
- ).toBe(true);
- expect(
- needsNoInstall({ dependencies: { framefields: "^2", mediabunny: "^1" } }),
- ).toBe(false);
- });
});
describe("install step", () => {
- it("skips projects that only need framefields, warning on a version mismatch", async () => {
- const root = await project("plain", {
- "package.json": { name: "p", dependencies: { framefields: "^0.1.0" } },
- });
- const { ctx, warnings } = context();
- const result = await install(checkoutOf(root), ctx);
- expect(result).toMatchObject({ skipped: true, declaredEngine: "^0.1.0" });
- expect(warnings).toContain("ENGINE_MISMATCH");
- });
-
- it("fails on an engine mismatch when the policy says so", async () => {
- const root = await project("strict", {
- "package.json": { name: "p", dependencies: { framefields: "^0.1.0" } },
+ it("requires the project to depend on framefields", async () => {
+ const root = await project("no-engine", {
+ "package.json": { name: "p", dependencies: { "left-pad": "1.3.0" } },
});
- const { ctx } = context({ FF_ENGINE_POLICY: "fail" });
- expect(await codeOf(install(checkoutOf(root), ctx))).toBe(
- "ENGINE_INCOMPATIBLE",
+ expect(await codeOf(install(checkoutOf(root), context().ctx))).toBe(
+ "ENGINE_NOT_FOUND",
+ );
+ const empty = await project("no-package", { "readme.md": "hi" });
+ expect(await codeOf(install(checkoutOf(empty), context().ctx))).toBe(
+ "ENGINE_NOT_FOUND",
);
});
- it("accepts the bundled version and workspace ranges", async () => {
- const root = await project("ok", {
+ it("accepts framefields declared at the workspace root", async () => {
+ const root = await project("root-engine", {
"package.json": {
- name: "p",
- dependencies: { framefields: `^${bundledEngineVersion()}` },
- devDependencies: { "@framefields/x": "workspace:*" },
+ name: "root",
+ workspaces: ["videos/*"],
+ dependencies: { framefields: "^2.1.0" },
},
+ "videos/launch/package.json": { name: "launch" },
});
- const { ctx, warnings } = context();
- await install(checkoutOf(root), ctx);
- expect(warnings).toEqual([]);
+ // No lockfile, so it stops there, after the engine check passed.
+ expect(
+ await codeOf(
+ install(
+ checkoutOf(root, path.join(root, "videos/launch")),
+ context().ctx,
+ ),
+ ),
+ ).toBe("LOCKFILE_MISSING");
});
- it("requires a lockfile when dependencies must be installed", async () => {
+ it("requires a lockfile", async () => {
const root = await project("nolock", {
- "package.json": { name: "p", dependencies: { "left-pad": "1.3.0" } },
+ "package.json": { name: "p", dependencies: { framefields: "^2.1.0" } },
});
expect(await codeOf(install(checkoutOf(root), context().ctx))).toBe(
"LOCKFILE_MISSING",
);
});
- it("runs npm ci once, then reuses node_modules until the lockfile changes", async () => {
+ it("runs npm ci once, reuses it until the lockfile changes, and asks for a restart when loaded deps change", async () => {
const root = await project("npm-project", {
+ // A stand-in engine package, so npm ci works offline.
"package.json": {
name: "film",
version: "1.0.0",
- dependencies: { helper: "file:./helper" },
+ dependencies: { framefields: "file:./engine" },
},
- "helper/package.json": { name: "helper", version: "1.0.0" },
- "helper/index.js": "module.exports = 1;\n",
+ "engine/package.json": { name: "framefields", version: "9.9.9" },
+ "engine/index.js": "module.exports = 1;\n",
});
- // Generate a real lockfile offline (file: deps need no registry).
execFileSync(
"npm",
[
@@ -196,22 +178,37 @@ describe("install step", () => {
);
const first = await install(checkoutOf(root), context().ctx);
- expect(first.cache.install).toBe("miss");
- expect(existsSync(path.join(root, "node_modules/helper/index.js"))).toBe(
- true,
- );
+ expect(first).toMatchObject({
+ declaredEngine: "file:./engine",
+ cache: { install: "miss" },
+ });
+ expect(
+ existsSync(path.join(root, "node_modules/framefields/index.js")),
+ ).toBe(true);
expect(existsSync(path.join(root, STAMP_FILE))).toBe(true);
- const second = await install(checkoutOf(root), context().ctx);
- expect(second.cache.install).toBe("hit");
+ expect((await install(checkoutOf(root), context().ctx)).cache.install).toBe(
+ "hit",
+ );
const pkg = JSON.parse(
await fs.readFile(path.join(root, "package.json"), "utf8"),
);
pkg.description = "changed";
await fs.writeFile(path.join(root, "package.json"), JSON.stringify(pkg));
- const third = await install(checkoutOf(root), context().ctx);
- expect(third.cache.install).toBe("miss");
+ expect((await install(checkoutOf(root), context().ctx)).cache.install).toBe(
+ "miss",
+ );
+
+ // Once this process loaded modules from the workspace, new dependencies
+ // need a fresh worker: installed, then ENGINE_SWITCH (retryable).
+ markDepsLoaded(root);
+ pkg.description = "changed again";
+ await fs.writeFile(path.join(root, "package.json"), JSON.stringify(pkg));
+ expect(await codeOf(install(checkoutOf(root), context().ctx))).toBe(
+ "ENGINE_SWITCH",
+ );
+ expect(existsSync(path.join(root, STAMP_FILE))).toBe(true);
}, 120_000);
});
diff --git a/apps/renderer-service/src/install/installer.ts b/apps/renderer-service/src/install/installer.ts
index 3e8c8c5a..33bb0835 100644
--- a/apps/renderer-service/src/install/installer.ts
+++ b/apps/renderer-service/src/install/installer.ts
@@ -1,76 +1,60 @@
import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
-import { fileURLToPath } from "node:url";
import semver from "semver";
import type { RendererConfig } from "../config/index.js";
import { RenderError } from "../errors.js";
import { CommandError, exec } from "../git/exec.js";
import type { Pipeline, StepContext } from "../jobs/pipeline.js";
import { redact } from "../redact.js";
+import { depsLoadedFrom } from "../render/engine.js";
+import { workerHealth } from "../worker/health.js";
import {
declaredEngineRange,
inspectProject,
- needsNoInstall,
type ProjectInfo,
+ readPackageJson,
} from "./project.js";
export const STAMP_FILE = ".ff-install-stamp";
-let engineVersion: string | undefined;
-
-/** Version of the framefields copy this worker renders with. */
-export function bundledEngineVersion(): string {
- if (engineVersion) return engineVersion;
- // The package doesn't export ./package.json; walk up from its entry.
- let dir = path.dirname(fileURLToPath(import.meta.resolve("framefields")));
- for (;;) {
- const file = path.join(dir, "package.json");
- if (existsSync(file)) {
- const pkg = JSON.parse(readFileSync(file, "utf8")) as {
- name?: string;
- version: string;
- };
- if (pkg.name === "framefields") {
- engineVersion = pkg.version;
- return engineVersion;
- }
- }
- if (path.dirname(dir) === dir)
- throw new Error("framefields package.json not found");
- dir = path.dirname(dir);
- }
-}
-
/**
- * Pipeline step: installs the project's dependencies (PLAN.md §7). Skipped
- * when the project only needs framefields, or when the lockfile hasn't
- * changed since the last install in this workspace slot.
+ * Pipeline step: installs the project's dependencies, including the
+ * framefields version it renders with (PLAN.md §7). Skipped when the
+ * lockfile hasn't changed since the last install in this workspace slot.
*/
export const install: Pipeline["install"] = async (checkout, ctx) => {
const project = await inspectProject(checkout.root, checkout.workdir);
if (!project) {
- ctx.warn(
- "NO_PACKAGE_JSON",
- "The workdir has no package.json; rendering without installing dependencies.",
+ throw new RenderError(
+ "ENGINE_NOT_FOUND",
+ "The workdir has no package.json, so there's no framefields to render with.",
+ {
+ phase: "install",
+ hint: 'Point source.workdir at the package that depends on "framefields".',
+ },
);
- return { skipped: true, cache: { install: "skipped" } };
}
- const declaredEngine = declaredEngineRange(project.pkg);
- checkEngine(declaredEngine, ctx);
- checkNodeEngine(project, ctx);
-
- if (needsNoInstall(project.pkg)) {
- return {
- skipped: true,
- packageManager: project.manager,
- declaredEngine,
- cache: { install: "skipped" },
- };
+ const rootPkg = project.inWorkspace
+ ? await readPackageJson(project.installRoot)
+ : undefined;
+ const declaredEngine =
+ declaredEngineRange(project.pkg) ??
+ (rootPkg && declaredEngineRange(rootPkg));
+ if (!declaredEngine) {
+ throw new RenderError(
+ "ENGINE_NOT_FOUND",
+ "The project doesn't depend on framefields.",
+ {
+ phase: "install",
+ hint: 'Add "framefields" to the dependencies in package.json and commit the lockfile.',
+ },
+ );
}
+ checkNodeEngine(project, ctx);
if (!project.lockfile && !ctx.config.install.allowUnlocked) {
throw new RenderError(
@@ -102,6 +86,20 @@ export const install: Pipeline["install"] = async (checkout, ctx) => {
await fs.rm(stampPath, { force: true });
await runInstall(project, ctx, checkout.root);
await fs.writeFile(stampPath, stamp);
+
+ // This process holds the old dependencies in its module cache; only a
+ // fresh worker can load the new ones (engine-alias.ts).
+ if (depsLoadedFrom(checkout.root)) {
+ workerHealth.requestRecycle("project dependencies changed");
+ throw new RenderError(
+ "ENGINE_SWITCH",
+ "The project's dependencies changed since this worker loaded them.",
+ {
+ phase: "install",
+ hint: "Retry: the worker restarts and loads the new dependencies (already installed).",
+ },
+ );
+ }
return {
skipped: false,
packageManager: project.manager,
@@ -110,22 +108,6 @@ export const install: Pipeline["install"] = async (checkout, ctx) => {
};
};
-function checkEngine(declared: string | undefined, ctx: StepContext): void {
- if (!declared) return;
- const range = declared.replace(/^npm:framefields@/, "");
- if (!semver.validRange(range)) return; // workspace:*, file:, git URLs, tags
- const bundled = bundledEngineVersion();
- if (semver.satisfies(bundled, range, { includePrerelease: true })) return;
- const message = `The project asks for framefields ${range}; this worker renders with ${bundled}.`;
- if (ctx.config.install.enginePolicy === "fail") {
- throw new RenderError("ENGINE_INCOMPATIBLE", message, {
- phase: "install",
- hint: "Use a worker image whose framefields version matches, or update the project's dependency.",
- });
- }
- ctx.warn("ENGINE_MISMATCH", message);
-}
-
function checkNodeEngine(project: ProjectInfo, ctx: StepContext): void {
const range = project.pkg.engines?.node;
if (
@@ -258,7 +240,11 @@ async function runInstall(
}
const [pm, ...args] = installCommand(project, config);
- const useCorepack = await hasCorepack();
+ // npm ships with Node, so corepack only runs it when the project pins a
+ // version; an unpinned npm via corepack can be a different major than
+ // the one that wrote the lockfile. pnpm and yarn always go through it.
+ const useCorepack =
+ (pm !== "npm" || Boolean(project.managerSpec)) && (await hasCorepack());
const file = useCorepack ? "corepack" : pm;
const argv = useCorepack ? [pm, ...args] : args;
@@ -323,13 +309,29 @@ export function classifyInstallError(
});
}
const output = `${err.result.stderr}\n${err.result.stdout}`;
- const logTail = redact(
- output.trim().split("\n").slice(-40).join("\n"),
- ).replaceAll(repoRoot, "<repo>");
+ // Package managers put the cause first and usage/help text last: keep both ends.
+ const lines = output
+ .trim()
+ .split("\n")
+ .filter((l) => !/^npm error\s*$/.test(l));
+ const excerpt =
+ lines.length > 45
+ ? [...lines.slice(0, 15), "…", ...lines.slice(-30)]
+ : lines;
+ const logTail = redact(excerpt.join("\n")).replaceAll(repoRoot, "<repo>");
+ // The first line that names the problem, e.g. npm's "`npm ci` can only install…".
+ const cause =
+ lines.find(
+ (l) =>
+ /ERR_PNPM_|error (?!code\b)|YN\d{4}|ERR!/i.test(l) &&
+ l.replace(/^npm error\s*/, "").length > 12,
+ ) ??
+ lines.at(-1) ??
+ "unknown error";
const fail = (hint?: string, transient = false) =>
new RenderError(
"INSTALL_FAILED",
- err.message.replaceAll(repoRoot, "<repo>"),
+ `${err.command} failed: ${redact(cause).replaceAll(repoRoot, "<repo>")}`,
{
phase: "install",
hint,
diff --git a/apps/renderer-service/src/install/project.ts b/apps/renderer-service/src/install/project.ts
index 09157777..7058f609 100644
--- a/apps/renderer-service/src/install/project.ts
+++ b/apps/renderer-service/src/install/project.ts
@@ -127,43 +127,6 @@ export async function inspectProject(
};
}
-/** Packages the worker provides itself (resolved to its copy, PLAN.md §7). */
-export function isEnginePackage(name: string): boolean {
- return name === "framefields" || name.startsWith("@framefields/");
-}
-
-/** Build/typing tools that never load at render time. */
-const TOOLING = [
- /^typescript$/,
- /^tsx$/,
- /^ts-node$/,
- /^@types\//,
- /^vitest$/,
- /^@vitest\//,
- /^@biomejs\//,
- /^eslint/,
- /^@eslint\//,
- /^prettier/,
- /^tsdown$/,
- /^tsup$/,
- /^esbuild$/,
- /^lefthook$/,
- /^husky$/,
-];
-
-/**
- * True when the package needs nothing beyond what the worker provides: every
- * dependency is a framefields package and every dev dependency is tooling.
- */
-export function needsNoInstall(pkg: PackageJson): boolean {
- const deps = Object.keys(pkg.dependencies ?? {});
- const dev = Object.keys(pkg.devDependencies ?? {});
- return (
- deps.every(isEnginePackage) &&
- dev.every((d) => isEnginePackage(d) || TOOLING.some((re) => re.test(d)))
- );
-}
-
/** The range the package declares for `framefields`, if any. */
export function declaredEngineRange(pkg: PackageJson): string | undefined {
return pkg.dependencies?.framefields ?? pkg.devDependencies?.framefields;
diff --git a/apps/renderer-service/src/jobs/runner.ts b/apps/renderer-service/src/jobs/runner.ts
index be4040a2..e8285b4e 100644
--- a/apps/renderer-service/src/jobs/runner.ts
+++ b/apps/renderer-service/src/jobs/runner.ts
@@ -1,9 +1,9 @@
import { randomUUID } from "node:crypto";
import fs from "node:fs/promises";
import path from "node:path";
-import { loggerContext, rendererLogger } from "@framefields/server-utils";
import type { RendererConfig } from "../config/index.js";
import { type JobPhase, RenderError, toRenderError } from "../errors.js";
+import { loggerContext, rendererLogger } from "../logger.js";
import { redact, redactValue } from "../redact.js";
import type { CrashJournal } from "./journal.js";
import type { DeliveredFile, Pipeline, StepContext } from "./pipeline.js";
diff --git a/apps/renderer-service/src/logger.ts b/apps/renderer-service/src/logger.ts
new file mode 100644
index 00000000..7203ea49
--- /dev/null
+++ b/apps/renderer-service/src/logger.ts
@@ -0,0 +1,44 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { readFileSync } from "node:fs";
+import pino from "pino";
+
+/** The service's version, from src/ (tests, dev) or dist/src/ (build). */
+const version = (() => {
+ for (const rel of ["../package.json", "../../package.json"]) {
+ try {
+ const pkg = JSON.parse(
+ readFileSync(new URL(rel, import.meta.url), "utf8"),
+ ) as {
+ name?: string;
+ version?: string;
+ };
+ if (pkg.name === "@framefields/renderer-service" && pkg.version)
+ return pkg.version;
+ } catch {
+ // try the next location
+ }
+ }
+ return "unknown";
+})();
+
+/** Per-job / per-request fields merged into every log line. */
+export const loggerContext = new AsyncLocalStorage<Record<string, unknown>>();
+
+export const logger = pino({
+ level: process.env.LOG_LEVEL || "info",
+ timestamp: pino.stdTimeFunctions.isoTime,
+ base: { service: "framefields-renderer", version },
+ mixin: () => loggerContext.getStore() ?? {},
+ redact: {
+ paths: [
+ "req.headers.authorization",
+ "headers.authorization",
+ "token",
+ "password",
+ ],
+ remove: true,
+ },
+});
+
+export const apiLogger = logger.child({ component: "api" });
+export const rendererLogger = logger.child({ component: "renderer" });
diff --git a/apps/renderer-service/src/middlewares.ts b/apps/renderer-service/src/middlewares.ts
index a9c6dcee..8d9e54ad 100644
--- a/apps/renderer-service/src/middlewares.ts
+++ b/apps/renderer-service/src/middlewares.ts
@@ -1,29 +1,25 @@
-import { generateId } from "@framefields/core";
-import { apiLogger, loggerContext } from "@framefields/server-utils";
+import { randomUUID } from "node:crypto";
import type { Context, Next } from "hono";
+import { apiLogger, loggerContext } from "./logger.js";
-// 1. Request/Response Middleware
+/** Tags each request with an id (x-request-id) and logs client errors. */
export const loggerMiddleware = async (c: Context, next: Next) => {
- const requestId = c.req.header("x-request-id") || generateId();
- c.set("requestId", requestId);
+ const requestId = c.req.header("x-request-id") || randomUUID();
c.header("x-request-id", requestId);
-
- const { method, url } = c.req;
+ const { method, path } = c.req;
const start = Date.now();
- await loggerContext.run({ component: "api", requestId }, async () => {
+ await loggerContext.run({ requestId }, async () => {
await next();
-
const status = c.res.status;
- const duration = `${Date.now() - start}ms`;
-
- const logPayload = { method, url, status, duration, requestId };
-
- if (status < 400) {
- apiLogger.trace(logPayload, "✅ Request Success");
- } else if (status < 500) {
- apiLogger.warn(logPayload, "⚠️ Client Error");
- }
- // Note: 500+ errors are handled by app.onError in index.ts
+ const payload = {
+ method,
+ path,
+ status,
+ duration: `${Date.now() - start}ms`,
+ };
+ if (status < 400) apiLogger.trace(payload, "request");
+ else if (status < 500) apiLogger.warn(payload, "client error");
+ // 5xx are logged by app.onError.
});
};
diff --git a/apps/renderer-service/src/readiness.test.ts b/apps/renderer-service/src/readiness.test.ts
index 0d305a07..fdcdad78 100644
--- a/apps/renderer-service/src/readiness.test.ts
+++ b/apps/renderer-service/src/readiness.test.ts
@@ -2,48 +2,23 @@ import { describe, expect, it } from "vitest";
import { ReadinessTracker } from "./readiness.js";
describe("ReadinessTracker", () => {
- it("should initialize as not ready", () => {
+ it("is ready once tools are present, before any engine is bound", () => {
const tracker = new ReadinessTracker();
expect(tracker.isReady).toBe(false);
- expect(tracker.status).toEqual({
- ready: false,
- components: {
- gpu: false,
- renderer: false,
- },
- });
- });
-
- it("should transition to ready when all components are set to true", () => {
- const tracker = new ReadinessTracker();
-
- tracker.setGpuReady(true);
- expect(tracker.isReady).toBe(false);
-
- tracker.setRendererReady(true);
- expect(tracker.isReady).toBe(true);
-
+ tracker.setToolsReady(true);
expect(tracker.status).toEqual({
ready: true,
- components: {
- gpu: true,
- renderer: true,
- },
+ components: { tools: true, engine: null },
});
+ tracker.setEngine("2.1.3");
+ expect(tracker.status.components.engine).toBe("2.1.3");
});
- it("should include failure reason when set", () => {
+ it("reports failures and stops being ready", () => {
const tracker = new ReadinessTracker();
- tracker.setFailure("GPU initialization timed out");
-
+ tracker.setToolsReady(true);
+ tracker.setFailure("TOOL_MISSING: git-lfs");
expect(tracker.isReady).toBe(false);
- expect(tracker.status).toEqual({
- ready: false,
- components: {
- gpu: false,
- renderer: false,
- },
- error: "GPU initialization timed out",
- });
+ expect(tracker.status.error).toBe("TOOL_MISSING: git-lfs");
});
});
diff --git a/apps/renderer-service/src/readiness.ts b/apps/renderer-service/src/readiness.ts
index d98c0186..1901be99 100644
--- a/apps/renderer-service/src/readiness.ts
+++ b/apps/renderer-service/src/readiness.ts
@@ -1,29 +1,32 @@
+/**
+ * Worker readiness. The worker is ready once the tools it shells out to are
+ * present; the GPU is initialised by the first job, with that project's
+ * framefields (PLAN.md §7), so it is reported but not required.
+ */
export class ReadinessTracker {
- private _gpuReady = false;
- private _rendererReady = false;
+ private _toolsReady = false;
+ private _engine: string | null = null;
private _failureReason: string | null = null;
get isReady(): boolean {
- return this._gpuReady && this._rendererReady;
+ return this._toolsReady && !this._failureReason;
}
get status() {
return {
ready: this.isReady,
- components: {
- gpu: this._gpuReady,
- renderer: this._rendererReady,
- },
+ components: { tools: this._toolsReady, engine: this._engine },
...(this._failureReason && { error: this._failureReason }),
};
}
- setGpuReady(ready: boolean) {
- this._gpuReady = ready;
+ setToolsReady(ready: boolean) {
+ this._toolsReady = ready;
}
- setRendererReady(ready: boolean) {
- this._rendererReady = ready;
+ /** framefields version bound by the first job (GPU initialised). */
+ setEngine(version: string | null) {
+ this._engine = version;
}
setFailure(reason: string) {
diff --git a/apps/renderer-service/src/render/engine-alias.ts b/apps/renderer-service/src/render/engine-alias.ts
index a03d98a9..72c863f4 100644
--- a/apps/renderer-service/src/render/engine-alias.ts
+++ b/apps/renderer-service/src/render/engine-alias.ts
@@ -2,12 +2,12 @@ import { createRequire, registerHooks } from "node:module";
import path from "node:path";
import { pathToFileURL } from "node:url";
-/** Query parameter that scopes workspace ES modules to one job. */
+/** Query parameter that scopes workspace source modules to one job. */
export const JOB_PARAM = "ff-job";
let roots: string[] = [];
let rootDirs: string[] = [];
-let engineParent = "";
+let engineEntry: string | undefined;
let installed = false;
const isEngine = (s: string) =>
@@ -15,7 +15,8 @@ const isEngine = (s: string) =>
s.startsWith("framefields/") ||
s.startsWith("@framefields/");
const inWorkspace = (url: string) => roots.some((r) => url.startsWith(r));
-/** Source files that become ESM even in a package without "type": "module". */
+const isDependency = (url: string) => url.includes("/node_modules/");
+/** Project source files that load as ESM even without "type": "module". */
const FORCE_ESM = /\.(ts|tsx|js|jsx)$/;
function jobOf(url: string | undefined): string | undefined {
@@ -27,30 +28,36 @@ function jobOf(url: string | undefined): string | undefined {
}
}
+/** Routes framefields imports to the bound engine (see engine.ts). */
+export function setEngineEntry(url: string): void {
+ engineEntry = url;
+}
+
/**
- * Installs the engine alias once per process (PLAN.md §7): imports and
- * requires of `framefields` / `@framefields/*` made from inside a workspace
- * resolve as if made by the worker's own framefields (ESM build), so repo
- * code shares the worker's single, already-initialised GPU stack. Workspace
- * ES modules also inherit a per-job query, so a job never reuses modules
- * cached by a previous one. Uses synchronous in-thread hooks, which apply to
- * both `import` and `require()`.
+ * Installs the loader hooks once per process (PLAN.md §7, §8.1). Uses
+ * synchronous in-thread hooks, which apply to both `import` and `require()`.
+ *
+ * - Once an engine is bound, `framefields` / `@framefields/*` imported from
+ * any workspace resolve from the bound engine's package (always its ESM
+ * build), so every project on the same version shares one GPU stack.
+ * - Project source files (outside node_modules) inherit a per-job query, so
+ * a job never reuses source modules cached by a previous one, and load as
+ * ESM: in CommonJS mode tsx would transpile a second copy of the engine.
+ * - Dependencies in node_modules load as they are and stay cached by path,
+ * shared with the engine. A dependency change restarts the worker instead
+ * (installer.ts).
*/
export function installEngineAlias(workspaceRoots: string[]): void {
if (installed) return;
installed = true;
rootDirs = workspaceRoots.map((r) => path.resolve(r) + path.sep);
roots = rootDirs.map((r) => pathToFileURL(r).href);
- // framefields depends on every @framefields/* package, so resolving from
- // its entry finds them all.
- engineParent = import.meta.resolve("framefields");
registerHooks({
resolve(specifier, context, next) {
const parent = context.parentURL;
- if (isEngine(specifier) && parent && inWorkspace(parent)) {
+ if (engineEntry && isEngine(specifier) && parent && inWorkspace(parent)) {
try {
- // Always the ESM build, so require() and import share one instance.
const conditions = (context.conditions ?? []).map((c) =>
c === "require" ? "import" : c,
);
@@ -58,18 +65,21 @@ export function installEngineAlias(workspaceRoots: string[]): void {
return next(specifier, {
...context,
conditions,
- parentURL: engineParent,
+ parentURL: engineEntry,
});
} catch {
// Not part of the engine (e.g. a project-local @framefields/* package).
}
}
const result = next(specifier, context);
- if (!result.url.startsWith("file:") || !inWorkspace(result.url))
+ if (
+ !result.url.startsWith("file:") ||
+ !inWorkspace(result.url) ||
+ isDependency(result.url)
+ ) {
return result;
+ }
let { url, format } = result;
- // Repo code always runs as ESM. In CommonJS mode tsx would transpile
- // framefields' .mjs into a second, CJS copy of the engine.
if (format === "commonjs" && FORCE_ESM.test(new URL(url).pathname))
format = "module";
const job = jobOf(parent);
@@ -84,12 +94,17 @@ export function installEngineAlias(workspaceRoots: string[]): void {
}
/**
- * Drops CommonJS modules loaded from the workspaces (ES modules are scoped by
- * the job query instead). Called when a job ends.
+ * Drops CommonJS project sources loaded from the workspaces (ES modules are
+ * scoped by the job query instead). Called when a job ends.
*/
export function clearWorkspaceRequireCache(): void {
const cache = createRequire(import.meta.url).cache;
for (const key of Object.keys(cache)) {
- if (rootDirs.some((r) => key.startsWith(r))) delete cache[key];
+ if (
+ rootDirs.some((r) => key.startsWith(r)) &&
+ !key.includes(`${path.sep}node_modules${path.sep}`)
+ ) {
+ delete cache[key];
+ }
}
}
diff --git a/apps/renderer-service/src/render/engine.ts b/apps/renderer-service/src/render/engine.ts
new file mode 100644
index 00000000..7a915304
--- /dev/null
+++ b/apps/renderer-service/src/render/engine.ts
@@ -0,0 +1,175 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { RenderError } from "../errors.js";
+import { rendererLogger } from "../logger.js";
+import { workerHealth } from "../worker/health.js";
+import { setEngineEntry } from "./engine-alias.js";
+
+/** The parts of a project's `framefields` module the worker uses. */
+export interface EngineModule {
+ HeadlessMediaRenderer: {
+ new (): EngineRenderer;
+ initialize(): Promise<void>;
+ };
+ Composition?: abstract new (...args: never[]) => unknown;
+ Media?: abstract new (...args: never[]) => unknown;
+ FontManager?: { clear(): void };
+ /** Present in framefields versions built for long-lived workers. */
+ resetRenderCaches?: () => void;
+}
+
+export interface EngineRenderer {
+ renderLut(vm: never, frame?: number): Promise<string | Buffer>;
+}
+
+export interface BoundEngine {
+ version: string;
+ /** Real path of the framefields package directory. */
+ dir: string;
+ entryUrl: string;
+ /** Workspace slot the engine was loaded from (kept by the janitor). */
+ workspace: string;
+ mod: EngineModule;
+ /** Engine supports `signal`/`onProgress` and the per-job cache reset. */
+ workerHooks: boolean;
+}
+
+let bound: BoundEngine | undefined;
+/** Workspaces whose node_modules this process has loaded modules from. */
+const loadedDeps = new Set<string>();
+
+export function markDepsLoaded(workspace: string): void {
+ loadedDeps.add(workspace);
+}
+
+/**
+ * Dependencies stay cached by path for the life of the process, so a new
+ * install in a workspace this process already loaded from can't take effect
+ * without a restart.
+ */
+export function depsLoadedFrom(workspace: string): boolean {
+ return loadedDeps.has(workspace);
+}
+
+export function boundEngine(): BoundEngine | undefined {
+ return bound;
+}
+
+/** Finds the framefields the project installed, as seen from its workdir. */
+export function locateEngine(workdir: string): {
+ version: string;
+ dir: string;
+ entryUrl: string;
+} {
+ let entry: string;
+ try {
+ entry = createRequire(path.join(workdir, "package.json")).resolve(
+ "framefields",
+ );
+ } catch {
+ throw new RenderError(
+ "ENGINE_NOT_FOUND",
+ "The project does not have framefields installed.",
+ {
+ phase: "install",
+ hint: 'Add "framefields" to the package.json dependencies (and commit the lockfile).',
+ },
+ );
+ }
+ for (let dir = path.dirname(entry); ; dir = path.dirname(dir)) {
+ const file = path.join(dir, "package.json");
+ if (existsSync(file)) {
+ const pkg = JSON.parse(readFileSync(file, "utf8")) as {
+ name?: string;
+ version?: string;
+ };
+ if (pkg.name === "framefields" && pkg.version) {
+ return {
+ version: pkg.version,
+ dir: realpathSync(dir),
+ entryUrl: pathToFileURL(realpathSync(entry)).href,
+ };
+ }
+ }
+ if (path.dirname(dir) === dir) {
+ throw new RenderError(
+ "ENGINE_NOT_FOUND",
+ "Found framefields but not its package.json.",
+ { phase: "install" },
+ );
+ }
+ }
+}
+
+/**
+ * Returns the engine for this job (PLAN.md §7). The first job binds the
+ * worker to its project's framefields version: loaded once, GPU initialised
+ * once. Later jobs needing the same version share it, even from other repos.
+ * A different version can't share the process (one GPU stack per process):
+ * the job fails with retryable ENGINE_SWITCH and the worker recycles, so the
+ * retry lands on a fresh worker.
+ */
+export async function bindEngine(
+ workdir: string,
+ workspace: string,
+): Promise<BoundEngine> {
+ const found = locateEngine(workdir);
+ if (bound) {
+ if (bound.version === found.version) return bound;
+ workerHealth.requestRecycle(
+ `engine switch ${bound.version} → ${found.version}`,
+ );
+ throw new RenderError(
+ "ENGINE_SWITCH",
+ `This worker runs framefields ${bound.version}; the project needs ${found.version}.`,
+ {
+ phase: "render",
+ hint: "Retry: the worker restarts and loads the project's version.",
+ },
+ );
+ }
+
+ setEngineEntry(found.entryUrl);
+ const mod = (await import(/* @vite-ignore */ found.entryUrl)) as EngineModule;
+ if (typeof mod.HeadlessMediaRenderer?.initialize !== "function") {
+ throw new RenderError(
+ "ENGINE_NOT_FOUND",
+ `framefields ${found.version} has no HeadlessMediaRenderer.`,
+ {
+ phase: "render",
+ },
+ );
+ }
+ try {
+ await mod.HeadlessMediaRenderer.initialize();
+ } catch (err) {
+ workerHealth.requestRecycle("GPU initialisation failed");
+ throw new RenderError(
+ "GPU_UNAVAILABLE",
+ err instanceof Error ? err.message : String(err),
+ {
+ phase: "render",
+ cause: err,
+ },
+ );
+ }
+ bound = {
+ ...found,
+ workspace,
+ mod,
+ workerHooks: typeof mod.resetRenderCaches === "function",
+ };
+ rendererLogger.info(
+ { version: found.version, workerHooks: bound.workerHooks },
+ "Bound framefields engine and initialised the GPU",
+ );
+ return bound;
+}
+
+/** Test hook: forget the bound engine. */
+export function _resetEngineBinding(): void {
+ bound = undefined;
+ loadedDeps.clear();
+}
diff --git a/apps/renderer-service/src/render/render-step.ts b/apps/renderer-service/src/render/render-step.ts
index 0a2fe224..5507354a 100644
--- a/apps/renderer-service/src/render/render-step.ts
+++ b/apps/renderer-service/src/render/render-step.ts
@@ -1,12 +1,6 @@
import fs from "node:fs/promises";
import path from "node:path";
-import {
- HeadlessMediaRenderer,
- resetRenderCaches,
-} from "@framefields/renderer";
-import { Composition, FontManager, Media } from "framefields";
import { RenderError } from "../errors.js";
-import { bundledEngineVersion } from "../install/installer.js";
import type {
CheckoutResult,
Pipeline,
@@ -15,6 +9,7 @@ import type {
} from "../jobs/pipeline.js";
import type { JobInput, RenderSettings } from "../jobs/schema.js";
import { workerHealth } from "../worker/health.js";
+import { type BoundEngine, bindEngine, markDepsLoaded } from "./engine.js";
import { clearWorkspaceRequireCache } from "./engine-alias.js";
import { buildPlan, importEntry, type PlanOutput } from "./load.js";
import { openSandbox } from "./sandbox.js";
@@ -26,9 +21,24 @@ const PROGRESS_INTERVAL_MS = 500;
* output of its plan on the worker's warm GPU device (PLAN.md §8).
*/
export const render: Pipeline["render"] = async (checkout, input, ctx) => {
- // Path-keyed caches from the previous job may hold stale bytes (§8.2).
- resetRenderCaches();
- FontManager.clear();
+ // The project's own framefields, bound once per worker (§7).
+ const engine = await bindEngine(checkout.workdir, checkout.root);
+ markDepsLoaded(checkout.root);
+ if (engine.workerHooks) {
+ // Path-keyed caches from the previous job may hold stale bytes (§8.2).
+ engine.mod.resetRenderCaches?.();
+ engine.mod.FontManager?.clear();
+ } else {
+ // No cache reset, progress or abort in this version: render it, then
+ // start fresh rather than risk stale caches in the next job.
+ workerHealth.requestRecycle(
+ `framefields ${engine.version} lacks worker hooks`,
+ );
+ ctx.warn(
+ "ENGINE_NO_WORKER_HOOKS",
+ `framefields ${engine.version} predates worker support (progress, cancel, cache reset); the worker restarts after this job.`,
+ );
+ }
const outDir = path.join(ctx.jobDir, "out");
await fs.mkdir(outDir, { recursive: true });
@@ -58,19 +68,18 @@ export const render: Pipeline["render"] = async (checkout, input, ctx) => {
"load",
);
for (const output of plan) {
- if (
- !(
- output.target instanceof Composition ||
- output.target instanceof Media
- )
- ) {
+ const { Composition, Media } = engine.mod;
+ const known =
+ (Composition && output.target instanceof Composition) ||
+ (Media && output.target instanceof Media);
+ if (!known) {
warnings.push(output.name);
}
}
if (warnings.length) {
ctx.warn(
"ENGINE_FOREIGN_INSTANCE",
- `Outputs ${warnings.join(", ")} were built by another copy of framefields; rendering them with the worker's engine.`,
+ `Outputs ${warnings.join(", ")} were built by a different copy of framefields than the project's; rendering them with the project's engine.`,
);
}
for (const [index, output] of plan.entries()) {
@@ -84,6 +93,7 @@ export const render: Pipeline["render"] = async (checkout, input, ctx) => {
outDir,
ctx,
controller,
+ engine,
)),
);
}
@@ -98,7 +108,11 @@ export const render: Pipeline["render"] = async (checkout, input, ctx) => {
);
return {
files,
- engine: { framefields: bundledEngineVersion(), source: "bundled" },
+ engine: {
+ framefields: engine.version,
+ source: "project",
+ workerHooks: engine.workerHooks,
+ },
};
} catch (err) {
throw classifyRenderError(
@@ -142,10 +156,15 @@ async function renderOutput(
outDir: string,
ctx: StepContext,
controller: AbortController,
+ engine: BoundEngine,
): Promise<RenderedFile[]> {
const settings = { ...defaults, ...output.render } as RenderSettings;
- const renderer = new HeadlessMediaRenderer();
- const stall = stallWatch(ctx.config.limits.stallTimeoutSec, controller);
+ const renderer = new engine.mod.HeadlessMediaRenderer();
+ // Without progress events there is nothing to measure stalls by.
+ const stall = stallWatch(
+ engine.workerHooks ? ctx.config.limits.stallTimeoutSec : 0,
+ controller,
+ );
const base = path.join(outDir, `${index}-${output.name}`);
try {
diff --git a/apps/renderer-service/src/render/render.test.ts b/apps/renderer-service/src/render/render.test.ts
index 3b587a9e..1a8d7187 100644
--- a/apps/renderer-service/src/render/render.test.ts
+++ b/apps/renderer-service/src/render/render.test.ts
@@ -30,12 +30,23 @@ async function codeOf(promise: Promise<unknown>) {
}
}
+/** The framefields this package tests against, standing in for a project's install. */
+const ENGINE = path.resolve(
+ import.meta.dirname,
+ "../../node_modules/framefields",
+);
+
beforeAll(async () => {
ws = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "ff-ws-")));
+ // Workspace "a" installed framefields; workspace "b" (another repo on the
+ // same version) gets it through the bound engine.
await write(
- "package.json",
- '{ "name": "film", "type": "module", "dependencies": { "framefields": "^0.0.1" } }',
+ "a/package.json",
+ '{ "name": "film", "type": "module", "dependencies": { "framefields": "*" } }',
);
+ await fs.mkdir(path.join(ws, "a/node_modules"), { recursive: true });
+ await fs.symlink(ENGINE, path.join(ws, "a/node_modules/framefields"));
+ await write("b/package.json", '{ "name": "other", "type": "module" }');
});
afterAll(async () => {
await fs.rm(ws, { recursive: true, force: true });
@@ -47,20 +58,31 @@ const fake = () => ({
});
/** Runs the loader in a real Node process (see test/load-harness.ts). */
-function harness(entry: string, token: string, exportName?: string) {
+function harness(
+ workdir: string,
+ entry: string,
+ token: string,
+ exportName = "",
+ bindFrom = "",
+) {
const tsx = path.resolve(import.meta.dirname, "../../node_modules/.bin/tsx");
const script = path.resolve(
import.meta.dirname,
"../../test/load-harness.ts",
);
- const out = execFileSync(
- tsx,
- [script, ws, entry, token, ...(exportName ? [exportName] : [])],
- {
- encoding: "utf8",
- env: { ...process.env, NODE_ENV: "test" },
- },
- );
+ const args = [
+ script,
+ ws,
+ workdir,
+ entry,
+ token,
+ exportName,
+ ...(bindFrom ? [path.join(ws, bindFrom)] : []),
+ ];
+ const out = execFileSync(tsx, args, {
+ encoding: "utf8",
+ env: { ...process.env, NODE_ENV: "test" },
+ });
const line =
out
.trim()
@@ -70,29 +92,45 @@ function harness(entry: string, token: string, exportName?: string) {
return JSON.parse(line) as Record<string, unknown>;
}
+const FILM = `import { Composition } from "framefields";
+ const n: number = 1;
+ export const Ctor = Composition;
+ export const buildFilm = () => new Composition({ width: 64, height: 64, fps: 24, durationFrames: n });`;
+
describe("entry loading (real Node loader)", () => {
- it("gives repo code the worker's framefields, even with none installed", async () => {
- await write(
- "src/film.ts",
- `import { Composition } from "framefields";
- const n: number = 1;
- export const Ctor = Composition;
- export const buildFilm = () => new Composition({ width: 64, height: 64, fps: 24, durationFrames: n });`,
- );
- expect(harness("src/film.ts", "job-a", "buildFilm")).toMatchObject({
+ it("renders with the project's own framefields once it's bound", async () => {
+ await write("a/src/film.ts", FILM);
+ expect(
+ harness("a", "src/film.ts", "job-a", "buildFilm", "a"),
+ ).toMatchObject({
ok: true,
sameComposition: true,
- plan: [{ name: "main", isWorkerComposition: true }],
+ plan: [{ name: "main", isEngineComposition: true }],
+ });
+ }, 60_000);
+
+ it("shares the bound engine with another repo on the same version", async () => {
+ await write("b/src/film.ts", FILM);
+ expect(harness("b", "src/film.ts", "job-b2", "", "a")).toMatchObject({
+ ok: true,
+ sameComposition: true,
+ });
+ }, 60_000);
+
+ it("fails to load framefields when the project didn't install it and nothing is bound", async () => {
+ expect(harness("b", "src/film.ts", "job-b3")).toMatchObject({
+ ok: false,
+ code: "ENTRY_COMPILE_FAILED",
});
}, 60_000);
it('gives the same instance to a package without "type": "module"', async () => {
- await write("cjs/package.json", '{ "name": "legacy" }');
+ await write("a/cjs/package.json", '{ "name": "legacy" }');
await write(
- "cjs/film.ts",
+ "a/cjs/film.ts",
'import { Composition } from "framefields"; export const Ctor = Composition;',
);
- expect(harness("cjs/film.ts", "job-cjs")).toMatchObject({
+ expect(harness("a/cjs", "film.ts", "job-cjs", "", "a")).toMatchObject({
ok: true,
sameComposition: true,
});
@@ -100,13 +138,13 @@ describe("entry loading (real Node loader)", () => {
it("loads changed code at the same path under a new job token", async () => {
await write(
- "src/v.ts",
+ "a/src/v.ts",
'import { dep } from "./dep-v.js"; export const v = dep;',
);
- await write("src/dep-v.ts", "export const dep = 1;");
- expect(harness("src/v.ts", "job-b").v).toBe(1);
- await write("src/dep-v.ts", "export const dep = 2;");
- expect(harness("src/v.ts", "job-c").v).toBe(2);
+ await write("a/src/dep-v.ts", "export const dep = 1;");
+ expect(harness("a", "src/v.ts", "job-b").v).toBe(1);
+ await write("a/src/dep-v.ts", "export const dep = 2;");
+ expect(harness("a", "src/v.ts", "job-c").v).toBe(2);
}, 60_000);
it.each([
@@ -131,8 +169,8 @@ describe("entry loading (real Node loader)", () => {
])(
"classifies %s",
async (entry, source, code) => {
- if (source) await write(entry, source);
- expect(harness(entry, "job-d")).toMatchObject({ ok: false, code });
+ if (source) await write(path.join("a", entry), source);
+ expect(harness("a", entry, "job-d")).toMatchObject({ ok: false, code });
},
60_000,
);
diff --git a/apps/renderer-service/src/worker/boot.ts b/apps/renderer-service/src/worker/boot.ts
index 75ad579d..88865f70 100644
--- a/apps/renderer-service/src/worker/boot.ts
+++ b/apps/renderer-service/src/worker/boot.ts
@@ -1,8 +1,5 @@
import { mkdirSync, realpathSync } from "node:fs";
import path from "node:path";
-import { HeadlessMediaRenderer } from "@framefields/renderer";
-import "@framefields/renderer/offscreen-gl-polyfill";
-import { rendererLogger } from "@framefields/server-utils";
import {
describeConfig,
loadConfig,
@@ -11,14 +8,17 @@ import {
} from "../config/index.js";
import { RenderError } from "../errors.js";
import { checkout } from "../git/checkout.js";
+import { exec } from "../git/exec.js";
import { repoHash, workerId } from "../git/mirror.js";
import { install } from "../install/installer.js";
import { CrashJournal } from "../jobs/journal.js";
import type { Pipeline } from "../jobs/pipeline.js";
import { JobRunner } from "../jobs/runner.js";
+import { rendererLogger } from "../logger.js";
import { deliver, findExisting } from "../output/deliver.js";
import { ReadinessTracker } from "../readiness.js";
import { redact } from "../redact.js";
+import { boundEngine } from "../render/engine.js";
import { installEngineAlias } from "../render/engine-alias.js";
import { render } from "../render/render-step.js";
import { installProcessGuards, strayErrorCount } from "../render/sandbox.js";
@@ -38,8 +38,8 @@ export interface Worker {
isDraining(): boolean;
/** Stops taking jobs and waits for the current one. */
drain(reason: RenderError, abortActive: boolean): Promise<void>;
- /** Initialises the GPU; rejects when no usable device is found. */
- initGpu(): Promise<void>;
+ /** Checks git, git-lfs and ffprobe; rejects with TOOL_MISSING. */
+ checkTools(): Promise<void>;
stop(): void;
}
@@ -87,12 +87,26 @@ export function bootWorker(
deliver,
};
let baselineHandles = 0;
+ let boundVersion: string | undefined;
let draining = false;
const runner = new JobRunner(config, pipeline, {
journal,
- beforeJob: (job) => janitor.maybeRun([repoHash(job.repo)]),
+ beforeJob: (job) => {
+ // The bound engine is loaded from a workspace: never evict that one.
+ const engine = boundEngine();
+ const keep = [repoHash(job.repo)];
+ if (engine) keep.push(path.basename(path.dirname(engine.workspace)));
+ return janitor.maybeRun(keep);
+ },
afterJob: (completed) => {
+ const engine = boundEngine();
+ if (engine && boundVersion !== engine.version) {
+ // The engine's own timers and GPU handles aren't leaks.
+ boundVersion = engine.version;
+ readiness.setEngine(engine.version);
+ baselineHandles = process.getActiveResourcesInfo().length;
+ }
const reason = recycleReason(
currentStats(
completed,
@@ -137,23 +151,33 @@ export function bootWorker(
runner.queue.close(reason, abortActive);
await runner.queue.idle();
},
- async initGpu() {
- try {
- rendererLogger.info("Initializing renderer (GPU, node discovery)...");
- await HeadlessMediaRenderer.initialize();
- readiness.setRendererReady(true);
- readiness.setGpuReady(true);
- baselineHandles = process.getActiveResourcesInfo().length;
- rendererLogger.info("Renderer initialized.");
- } catch (error) {
- const message = error instanceof Error ? error.message : String(error);
- rendererLogger.fatal(
- { err: error },
- "❌ GPU / Renderer initialization failed",
+ async checkTools() {
+ const missing: string[] = [];
+ for (const [tool, args] of [
+ ["git", ["--version"]],
+ ["git", ["lfs", "version"]],
+ ["ffprobe", ["-version"]],
+ ] as const) {
+ await exec(tool, [...args], { timeoutMs: 10_000 }).catch(() =>
+ missing.push(
+ `${tool} ${args[0]}`
+ .replace(" --version", "")
+ .replace(" -version", ""),
+ ),
+ );
+ }
+ // ffprobe only sharpens output checks; git and git-lfs are required.
+ const required = missing.filter((m) => m.startsWith("git"));
+ if (missing.length) rendererLogger.warn({ missing }, "Tools missing");
+ if (required.length) {
+ readiness.setFailure(`TOOL_MISSING: ${required.join(", ")}`);
+ throw new RenderError(
+ "TOOL_MISSING",
+ `Missing: ${required.join(", ")}`,
);
- readiness.setFailure(`GPU_UNAVAILABLE: ${message}`);
- throw new RenderError("GPU_UNAVAILABLE", message, { cause: error });
}
+ readiness.setToolsReady(true);
+ baselineHandles = process.getActiveResourcesInfo().length;
},
stop: stopWatchdog,
};
diff --git a/apps/renderer-service/src/worker/janitor.ts b/apps/renderer-service/src/worker/janitor.ts
index c32facb9..b6eee8a2 100644
--- a/apps/renderer-service/src/worker/janitor.ts
+++ b/apps/renderer-service/src/worker/janitor.ts
@@ -1,8 +1,8 @@
import { existsSync } from "node:fs";
import fs from "node:fs/promises";
import path from "node:path";
-import { rendererLogger } from "@framefields/server-utils";
import type { RendererConfig } from "../config/index.js";
+import { rendererLogger } from "../logger.js";
/** Marker whose mtime records when a mirror or workspace was last used. */
export const LAST_USED = ".ff-last-used";
diff --git a/apps/renderer-service/test/load-harness.ts b/apps/renderer-service/test/load-harness.ts
index cd5e1b57..26c63702 100644
--- a/apps/renderer-service/test/load-harness.ts
+++ b/apps/renderer-service/test/load-harness.ts
@@ -1,37 +1,55 @@
/**
* Runs the entry loader in a real Node process (vitest's VM can't do native
* dynamic imports through loader hooks). Usage:
- * tsx test/load-harness.ts <workspace> <entry> <jobToken> [export]
- * Prints one JSON line describing the outcome.
+ * tsx test/load-harness.ts <workspacesRoot> <workdir> <entry> <jobToken> [export] [bindFrom]
+ * With bindFrom, the engine installed in that directory is bound first (as
+ * the first job on a worker would, minus GPU init). Prints one JSON line.
*/
-import * as worker from "framefields";
+import path from "node:path";
import { RenderError } from "../src/errors.js";
-import { installEngineAlias } from "../src/render/engine-alias.js";
+import { locateEngine } from "../src/render/engine.js";
+import {
+ installEngineAlias,
+ setEngineEntry,
+} from "../src/render/engine-alias.js";
import { buildPlan, importEntry } from "../src/render/load.js";
import { openSandbox } from "../src/render/sandbox.js";
-const [ws, entry, token, exportName] = process.argv.slice(2);
-installEngineAlias([ws]);
+const [root, workdir, entry, token, exportName, bindFrom] =
+ process.argv.slice(2);
+installEngineAlias([root]);
const report = (value: unknown) => {
process.stdout.write(`${JSON.stringify(value)}\n`);
};
-const sandbox = openSandbox({ cwd: ws, argv1: entry, env: {} });
+let engine: { Composition?: unknown } | undefined;
+if (bindFrom) {
+ const found = locateEngine(bindFrom);
+ setEngineEntry(found.entryUrl);
+ engine = (await import(found.entryUrl)) as { Composition?: unknown };
+}
+
+const dir = path.join(root, workdir);
+const sandbox = openSandbox({ cwd: dir, argv1: entry, env: {} });
try {
- const { mod, dispose } = await importEntry(ws, entry, token);
+ const { mod, dispose } = await importEntry(dir, entry, token);
const out: Record<string, unknown> = {
ok: true,
exports: Object.keys(mod).sort(),
v: mod.v,
sameComposition:
- mod.Ctor === undefined ? undefined : mod.Ctor === worker.Composition,
+ mod.Ctor === undefined || !engine
+ ? undefined
+ : mod.Ctor === engine.Composition,
};
if (exportName) {
const plan = await buildPlan(mod, exportName, undefined, undefined);
out.plan = plan.map((o) => ({
name: o.name,
- isWorkerComposition: o.target instanceof worker.Composition,
+ isEngineComposition: engine
+ ? o.target instanceof (engine.Composition as new () => unknown)
+ : undefined,
}));
}
await dispose();
diff --git a/apps/renderer-service/test/render-harness.ts b/apps/renderer-service/test/render-harness.ts
index b1da1af5..6b9df1e5 100644
--- a/apps/renderer-service/test/render-harness.ts
+++ b/apps/renderer-service/test/render-harness.ts
@@ -4,6 +4,7 @@
* tsx test/render-harness.ts <workDir>
* Prints one JSON line with each scenario's outcome. Needs a GPU.
*/
+import { writeSync } from "node:fs";
import fs from "node:fs/promises";
import path from "node:path";
import { Composition } from "framefields";
@@ -19,8 +20,36 @@ const workDir = path.resolve(process.argv[2]);
const ws = path.join(workDir, "ws", "repo", "0");
await fs.mkdir(path.join(ws, "src"), { recursive: true });
await fs.mkdir(path.join(ws, "assets"), { recursive: true });
+// The project's own framefields install (here: the one this package tests against).
+await fs.mkdir(path.join(ws, "node_modules"), { recursive: true });
+await fs.symlink(
+ path.resolve(import.meta.dirname, "../node_modules/framefields"),
+ path.join(ws, "node_modules/framefields"),
+);
+// Another repo pinned to a different framefields version.
+const other = path.join(workDir, "ws", "other", "0");
+await fs.mkdir(path.join(other, "node_modules/framefields"), {
+ recursive: true,
+});
+await fs.writeFile(
+ path.join(other, "package.json"),
+ '{ "name": "other", "type": "module" }',
+);
+await fs.writeFile(
+ path.join(other, "node_modules/framefields/package.json"),
+ '{ "name": "framefields", "version": "9.9.9", "type": "module", "exports": "./index.js" }',
+);
+await fs.writeFile(
+ path.join(other, "node_modules/framefields/index.js"),
+ "export {};",
+);
+await fs.writeFile(
+ path.join(other, "film.ts"),
+ "export const buildFilm = () => null;",
+);
installEngineAlias([await fs.realpath(path.join(workDir, "ws"))]);
-installProcessGuards(() => {});
+// Surface stray errors instead of swallowing them (the worker logs them).
+installProcessGuards((msg, err) => writeSync(2, `[harness] ${msg}: ${err}\n`));
const built = buildConfig(
{
@@ -43,6 +72,14 @@ const checkout: CheckoutResult = {
cache: {},
release: async () => {},
};
+const otherRoot = await fs.realpath(other);
+const otherCheckout: CheckoutResult = {
+ root: otherRoot,
+ workdir: otherRoot,
+ sha: "y",
+ cache: {},
+ release: async () => {},
+};
async function clip(color: string) {
const comp = new Composition({
@@ -62,6 +99,7 @@ async function job(
target: Record<string, unknown>,
render_: Record<string, unknown> = {},
abortAfterMs?: number,
+ on: CheckoutResult = checkout,
) {
const input = jobSchema.parse({
version: 2,
@@ -86,8 +124,12 @@ async function job(
abortAfterMs,
);
}
+ writeSync(
+ 2,
+ `[harness] ${new Date().toISOString().slice(11, 19)} ${name} start\n`,
+ );
try {
- const result = await render(checkout, input, ctx);
+ const result = await render(on, input, ctx);
const files = await Promise.all(
result.files.map(async (f) => ({
name: f.name,
@@ -96,8 +138,16 @@ async function job(
path: f.path,
})),
);
+ writeSync(
+ 2,
+ `[harness] ${new Date().toISOString().slice(11, 19)} ${name} ok\n`,
+ );
return { ok: true, files, warnings, cwdRestored: process.cwd() !== root };
} catch (err) {
+ writeSync(
+ 2,
+ `[harness] ${new Date().toISOString().slice(11, 19)} ${name} failed: ${err instanceof Error ? err.message : err}\n`,
+ );
return {
ok: false,
code: err instanceof RenderError ? err.code : String(err),
@@ -152,6 +202,14 @@ results.after = await job("after", {
entry: "src/film.ts",
export: "buildFilm",
});
+// Last: a repo pinned to another framefields version can't share this process.
+results.switch = await job(
+ "switch",
+ { entry: "film.ts", export: "buildFilm" },
+ {},
+ undefined,
+ otherCheckout,
+);
const bytes = async (r: unknown) => {
const f = (r as { files?: { path: string }[] }).files?.[0];
diff --git a/apps/renderer-service/tsconfig.build.json b/apps/renderer-service/tsconfig.build.json
new file mode 100644
index 00000000..b05b66ca
--- /dev/null
+++ b/apps/renderer-service/tsconfig.build.json
@@ -0,0 +1,10 @@
+{
+ "extends": "./tsconfig.json",
+ "compilerOptions": {
+ "composite": false,
+ "incremental": false,
+ "tsBuildInfoFile": null
+ },
+ "include": ["src/**/*"],
+ "exclude": ["src/**/*.test.ts", "src/test-helpers.ts"]
+}
diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.ts
index ea117cc4..5baf8cbf 100644
--- a/packages/framefields/src/index.ts
+++ b/packages/framefields/src/index.ts
@@ -2925,6 +2925,7 @@ export {
type RenderProgress,
renderFrameGrid,
renderSemaphore,
+ resetRenderCaches,
resolveSamplePoints,
type VideoQaOptions,
type VideoQaReport,
diff --git a/packages/framefields/src/renderer/index.ts b/packages/framefields/src/renderer/index.ts
index d811bbad..3b4b3b07 100644
--- a/packages/framefields/src/renderer/index.ts
+++ b/packages/framefields/src/renderer/index.ts
@@ -7,6 +7,7 @@ export {
type QaSegment,
type RenderProgress,
renderSemaphore,
+ resetRenderCaches,
type VideoQaOptions,
type VideoQaReport,
type VideoQaStats,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2d6e715d..adcb5b1b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -184,27 +184,18 @@ importers:
'@aws-sdk/lib-storage':
specifier: ^3.1151.0
version: 3.1151.0(@aws-sdk/[email protected])
- '@framefields/core':
- specifier: workspace:*
- version: link:../../packages/core
- '@framefields/renderer':
- specifier: workspace:*
- version: link:../../packages/renderer
- '@framefields/server-utils':
- specifier: workspace:*
- version: link:../../packages/server-utils
'@hono/node-server':
specifier: '>=2.0.5'
version: 2.0.12([email protected])
dotenv:
specifier: ^17.0.1
version: 17.3.1
- framefields:
- specifier: workspace:*
- version: link:../../packages/framefields
hono:
specifier: ^4.13.7
version: 4.13.13
+ pino:
+ specifier: ^10.3.1
+ version: 10.3.1
semver:
specifier: ^7.8.5
version: 7.8.5
@@ -215,6 +206,9 @@ importers:
specifier: ^4.3.6
version: 4.3.6
devDependencies:
+ '@framefields/renderer':
+ specifier: workspace:*
+ version: link:../../packages/renderer
'@framefields/tsconfig':
specifier: workspace:*
version: link:../../packages/tsconfig
@@ -224,6 +218,9 @@ importers:
'@types/semver':
specifier: ^7.8.0
version: 7.8.0
+ framefields:
+ specifier: workspace:*
+ version: link:../../packages/framefields
typescript:
specifier: ^5.8.3
version: 5.9.3