* fix(capture): never silently render a webgpu composition blank A composition declaring data-requires-webgpu only got the Chrome WebGPU flag when hardware GPU auto-detection succeeded. On a software-GPU host it launched without the flag and rendered blank with no error. compositionRequiresWebGpu (static declaration check) and assertWebGpuAdapterAvailable (live per-page adapter probe) now live once in packages/engine's browserManager, the shared choke point every launch site already goes through. All six launch sites (frame capture, the four CLI diagnostic commands, the studio thumbnail server, and the render pipeline's capture-options builder) route through those two functions; the old CLI-only static-heuristic guard is deleted, not kept alongside the new one. A software host that cannot obtain any WebGPU adapter now fails loudly naming the requirement instead of producing a blank frame. * fix(capture): thread requiresWebGpu through the distributed chunk-render path The distributed renderChunk() path built its CaptureOptions without requiresWebGpu, so it fell through to frameCapture's own fetch-based detection, whose failure path silently treats "requires webgpu" as "doesn't" if that fetch ever fails. Every other launch site (frame capture, all four CLI diagnostic commands, the studio thumbnail server, and the in-process render pipeline) already reads the value from HTML already in memory or on disk instead of relying on that fallback. Reads the compiled composition's index.html the same way probeStage already does and derives requiresWebGpu from it before building CaptureOptions. Adds a regression test that pins the exact path renderChunk() reads at render time, since the composition doesn't actually exercise WebGPU so an end-to-end render can't distinguish the two cases on this host. * test(producer): observe the real CaptureOptions renderChunk() builds The previous regression test called plan() and compositionRequiresWebGpu() directly, bypassing renderChunk() entirely, so it could not detect a regression to the wiring it was meant to protect (confirmed: it stayed green with the fix reverted). Exports the existing createCaptureSession dependency seam so a test can substitute a spy that delegates to the real implementation while capturing the CaptureOptions object renderChunk() actually constructs. Verified non-vacuous by reverting the fix and confirming the test fails. * fix(gcp-cloud-run): resolve puppeteer-core from a real file in the webgpu probe The image build's WebGPU adapter probe imported puppeteer-core from an inline `bun -e` eval string. The eval's synthetic /app/[eval] location can't resolve the workspace-hoisted dependency, so every build of this stage failed closed with "Cannot find package 'puppeteer-core'" before the probe itself ever ran. Moves the probe into a real script file next to probe-beginframe.ts, which already imports puppeteer-core dynamically the same way and resolves fine from its real workspace location. Verified locally against a cached chrome-headless-shell binary. * fix(engine): bound the webgpu adapter probe so a stuck driver can't hang the caller requestAdapter() has no native timeout. A broken software GPU driver that never settles it would hang assertWebGpuAdapterAvailable indefinitely, including inside the GCP image build's probe RUN step, producing an opaque build timeout instead of a clean probe failure. Races the in-page request against a bounded timeout so a stuck adapter reads as unavailable and fails the same way a genuinely absent one does. * test(cli): mock the engine's webgpu exports in the browser-fallback test * test(producer): run the typegpu adapter fixture only on hosts with a hardware WebGPU adapter The fixture declares data-requires-webgpu, so a software-only host now refuses it instead of silently rendering the shader blank. The old golden had no shader in it. Tag it webgpu, skip that tag in the CI image and the test scripts, and re-record the golden from a Metal render with the shader visible. * fix(engine): bound the composition fetch that decides the webgpu flag createCaptureSession fetched the served page with no timeout before launching the browser, so a hung server stalled a render forever and hung a fake-timer test. Give it a five second limit, and let that test say it has no WebGPU requirement the way the producer does. * fix(capture): refuse a software fallback WebGPU adapter instead of rendering on it swiftshader reports a WebGPU adapter but cannot render canvas WebGPU, so a data-requires-webgpu composition on a software-only host crashed on its first frame. Refuse fallback adapters with the same clear WebGPU-unavailable error. The GCP image probe now serves its page over http (file:// hides navigator.gpu) and reports a software-only host instead of failing the image build. * fix(engine): parse the composition root tag without a backtracking regex * fix(engine): keep quoted attribute values whole when reading the composition root tag
@hyperframes/gcp-cloud-run
Google Cloud Run + Cloud Workflows adapter for HyperFrames distributed
rendering. The OSS render primitives (plan → renderChunk × N →
assemble) are pure functions over local file paths; this package is the
deployment, orchestration, and storage glue that runs them on Google Cloud —
the GCP counterpart to @hyperframes/aws-lambda.
Two surfaces, one package:
- Server-side handler (
./server) — a Cloud Run HTTP service that dispatchesplan/renderChunk/assembleon the request body'sActionfield, bridging GCS ↔ the container's filesystem around each OSS primitive. This is what the bundledDockerfileruns. - Client-side SDK (
./sdk) —renderToCloudRun,getRenderProgress,deploySite,validateDistributedRenderConfig, andcomputeRenderCost. Call these from a Node process (CI, CLI, app backend) to drive a deployed stack without writing GCS / Workflows boilerplate.
The package is not a dependency of @hyperframes/producer; install it
separately.
Architecture
GCS bucket ←→ Cloud Run service (plan / renderChunk / assemble)
▲
│ OIDC-authenticated http.post, one per step
│
Cloud Workflows (Plan → parallel RenderChunk → Assemble)
- Plan downloads the project tarball and publishes either a legacy v1 planDir tarball or a v2 manifest plus content-addressed artifacts.
- RenderChunk runs in a parallel
forloop in the workflow, fanned out up to the plan's chunk count. Each invocation renders one chunk and uploads it. - Assemble downloads every chunk + audio, stitches the final deliverable, and uploads it.
Every step is a POST to the same Cloud Run URL with a different Action.
The workflow accumulates each step's small result body and returns
{ Plan, Chunks, Assemble } so getRenderProgress can read frame totals and
per-step durations on success.
Plan transport selection
Plan v2 is the default for new renders. When planProtocol is omitted,
renderToCloudRun sends an explicit PlanProtocol: "v2" so the SDK and
the deployed workflow agree:
await renderToCloudRun({
// ...project, bucket, workflow, service, and config...
});
V2 uses separate manifest and content-addressed artifact locators throughout the workflow. Unknown protocols and integrity failures fail closed; a render never mixes v1 and v2 artifacts.
The monolithic v1 transport remains available as deprecated compatibility by
passing planProtocol: "v1" explicitly.
Upgrade order
Redeploy the Cloud Run image and Cloud Workflows definition from the same new
package version before upgrading an application that calls
renderToCloudRun. Pause new renders and drain active workflow executions
during the infrastructure update. Older workflows can default omission to v1
or lack the v2 branch, while the new SDK sends explicit v2. If infrastructure
cannot be redeployed first, keep the previous SDK version or pass
planProtocol: "v1" explicitly until the Terraform/workflow redeploy is
complete.
Chrome runtime
Unlike the Lambda adapter — which fights a 250 MB ZIP ceiling and
decompresses @sparticuz/chromium into /tmp at runtime — Cloud Run runs a
container image. The Dockerfile installs the same pinned
chrome-headless-shell build and font set the production renderer uses, at a
fixed path, and exports HYPERFRAMES_CHROME_PATH. CDP-level BeginFrame
support is a binary/runtime capability, so the image build launches that
exact executable and requires an enable + warm-up + PNG-returning
HeadlessExperimental.beginFrame probe to pass. The end-to-end smoke also
requires every chunk to report effective CaptureMode: "beginframe", which
catches runtime fallback separately from build-time packaging. There is no
runtime decompression step and no packaging ceiling.
Deploying
The terraform/ module provisions everything: the GCS render bucket, the
Cloud Run service, the Cloud Workflows definition, two least-privilege
service accounts (the service reads/writes the bucket; the workflow invokes
the service), and a runaway-request alert.
# 1. Build + push the image (Cloud Build or local docker).
gcloud builds submit . \
--tag REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
# 2. Apply the module.
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform init
terraform -chdir=node_modules/@hyperframes/gcp-cloud-run/terraform apply \
-var project_id=PROJECT \
-var region=us-central1 \
-var image=REGION-docker.pkg.dev/PROJECT/REPO/hyperframes-render:TAG
Terraform outputs render_bucket_name, service_url, workflow_name, and
region — pass them straight into the SDK.
Using the SDK
import { renderToCloudRun, getRenderProgress } from "@hyperframes/gcp-cloud-run/sdk";
const handle = await renderToCloudRun({
projectDir: "./my-composition",
config: { fps: 30, width: 1920, height: 1080, format: "mp4" },
bucketName: "hyperframes-render-my-project", // from terraform output
projectId: "my-project",
location: "us-central1",
workflowId: "hyperframes-render",
serviceUrl: "https://hyperframes-render-abc.us-central1.run.app",
});
// Poll until done.
let progress = await getRenderProgress({ executionName: handle.executionName });
while (progress.status === "running") {
await new Promise((r) => setTimeout(r, 5000));
progress = await getRenderProgress({ executionName: handle.executionName });
}
console.log(progress.status, progress.outputFile, progress.costs.displayCost);
deploySite is called implicitly when you pass projectDir; call it
yourself to pre-upload once and reuse the siteHandle across many renders
(e.g. personalised template batches).
Running tests
bun test # unit tests over an in-memory GCS double — no network
bun run typecheck
The live end-to-end smoke (build image → terraform apply → render a fixture
through the workflow → PSNR-compare → destroy) lives at
examples/gcp-cloud-run/scripts/smoke.sh and needs a GCP project with
billing enabled.
What's still ahead
- Mid-flight per-chunk progress.
getRenderProgressreports coarserunningprogress and exact numbers on success. Reading the Cloud Workflows step-entries API would give per-chunk progress while the render is in flight; tracked as a follow-up. - Cloud Run Jobs / Firebase Functions variants. This first version targets Cloud Run services + Workflows (the closest analog to Lambda + Step Functions). The same handler runs unchanged under Cloud Run Jobs; only the orchestration trigger differs.