perf(renderer): accelerate capture and prototype native renderer

.github/workflows/ci.yml

@@ -146,7 +146,34 @@
       - run: bun install --frozen-lockfile
       - run: bun run --filter @hyperframes/core test:hyperframe-runtime-ci
 
+  native-renderer:
+    name: "Test: native renderer"
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install FFmpeg
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+      - run: bun install --frozen-lockfile
+      - run: cargo test --manifest-path packages/native-renderer/Cargo.toml -- --test-threads=1
+      - run: bun test packages/cli/src/utils/nativeBackend.test.ts packages/native-renderer/src/scene/extract.test.ts packages/native-renderer/src/scene/support.test.ts packages/native-renderer/src/timeline/bake.test.ts
+      - name: Native renderer comparison shard
+        run: |
+          bun packages/native-renderer/scripts/compare-regression-fixtures.ts \
+            --fixtures gsap-letters-render-compat \
+            --max-duration 0.25 \
+            --artifacts /tmp/native-renderer-comparison-ci
+
   smoke-global-install:
     name: "Smoke: global install"
     needs: [changes, build]
     if: needs.changes.outputs.code == 'true'

.github/workflows/native-renderer.yml

@@ -0,0 +1,65 @@
+name: Native Renderer
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths:
+      - "packages/native-renderer/**"
+      - ".github/workflows/native-renderer.yml"
+  push:
+    branches: [main]
+    paths:
+      - "packages/native-renderer/**"
+
+concurrency:
+  group: native-renderer-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Tests (Linux x86_64, CPU raster)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Cargo + Skia
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            packages/native-renderer/target
+          key: native-${{ runner.os }}-${{ hashFiles('packages/native-renderer/Cargo.lock') }}
+          restore-keys: native-${{ runner.os }}-
+
+      - name: Install system deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            clang libclang-dev pkg-config \
+            libfontconfig1-dev libfreetype6-dev \
+            ninja-build python3 \
+            ffmpeg fonts-liberation fonts-dejavu-core fontconfig
+          sudo fc-cache -fv
+
+      - name: Build (CPU raster, no GPU)
+        working-directory: packages/native-renderer
+        run: cargo build --release --no-default-features --tests
+
+      - name: Run tests
+        working-directory: packages/native-renderer
+        run: cargo test --release --no-default-features -- --test-threads=1
+
+      - name: Benchmark
+        working-directory: packages/native-renderer
+        run: |
+          cargo bench --no-default-features 2>&1 | tee /tmp/bench.txt
+          echo "## Native Renderer Benchmark" >> $GITHUB_STEP_SUMMARY
+          echo "Linux x86_64, CPU raster, no GPU" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          grep -E 'time:|^[a-z].*time:' /tmp/bench.txt >> $GITHUB_STEP_SUMMARY || echo "No benchmark output" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY

packages/cli/src/cli.ts

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
 
+// Polyfill esbuild's __name helper before any import can reference it.
+if (typeof (globalThis as Record<string, unknown>).__name !== "function") {
+  (globalThis as Record<string, unknown>).__name = <T>(fn: T, _n: string): T => fn;
+}
+
 // ── Fast-path exits ─────────────────────────────────────────────────────────
 // Check --version before importing anything heavy. This makes
 // `hyperframes --version` near-instant (~10ms vs ~80ms).

packages/cli/src/commands/doctor.ts

@@ -10,6 +10,7 @@ import { findFFmpeg, getFFmpegInstallHint } from "../browser/ffmpeg.js";
 import { VERSION } from "../version.js";
 import { getUpdateMeta } from "../utils/updateCheck.js";
 import { getSystemMeta, getShmSizeMb, getFreeDiskMb, bytesToMb } from "../telemetry/system.js";
+import { findNativeRendererRoot } from "../utils/nativeRender.js";
 
 interface Check {
   name: string;
@@ -181,6 +182,30 @@ function checkEnvironment(): CheckResult {
   return { ok: true, detail: parts.join(" \u00B7 ") };
 }
 
+function checkNativeRenderer(): CheckResult {
+  const root = findNativeRendererRoot();
+  if (!root) {
+    return {
+      ok: true,
+      detail: "Not bundled in this installation; --backend auto will use Chrome fallback",
+    };
+  }
+
+  try {
+    const cargo = execSync("cargo --version", { encoding: "utf-8", timeout: 5000 }).trim();
+    return {
+      ok: true,
+      detail: `${root} \u00B7 ${cargo} \u00B7 auto gates native by support detection; zero-copy is not proven yet`,
+    };
+  } catch {
+    return {
+      ok: false,
+      detail: `${root} \u00B7 cargo not found`,
+      hint: "Install Rust from https://rustup.rs/ to use --backend native from source; --backend auto falls back to Chrome when native is unavailable or unsupported.",
+    };
+  }
+}
+
 export default defineCommand({
   meta: { name: "doctor", description: "Check system dependencies and environment" },
   args: {},
@@ -207,6 +232,7 @@ export default defineCommand({
       { name: "FFmpeg", run: checkFFmpeg },
       { name: "FFprobe", run: checkFFprobe },
       { name: "Chrome", run: checkChrome },
+      { name: "Native renderer", run: checkNativeRenderer },
       { name: "Docker", run: checkDocker },
       { name: "Docker running", run: checkDockerRunning },
     );

packages/cli/src/commands/render.ts

@@ -26,6 +26,17 @@ import { bytesToMb } from "../telemetry/system.js";
 import { VERSION } from "../version.js";
 import { isDevMode } from "../utils/env.js";
 import { buildDockerRunArgs } from "../utils/dockerRunArgs.js";
+import {
+  parseRenderBackend,
+  resolveRenderBackend,
+  type RenderBackend,
+} from "../utils/nativeBackend.js";
+import {
+  formatUnsupportedNativeFeatures,
+  isNativeRendererAvailable,
+  renderNativeProject,
+  type NativeRenderResult,
+} from "../utils/nativeRender.js";
 import type { RenderJob } from "@hyperframes/producer";
 
 const VALID_FPS = new Set([24, 30, 60]);
@@ -73,6 +84,11 @@ export default defineCommand({
       description: "Output format: mp4, webm, mov (MOV/WebM render with transparency)",
       default: "mp4",
     },
+    backend: {
+      type: "string",
+      description: "Render backend: chrome, native, or auto",
+      default: "chrome",
+    },
     workers: {
       type: "string",
       alias: "w",
@@ -147,6 +163,14 @@ export default defineCommand({
     }
     const format = formatRaw as "mp4" | "webm" | "mov";
 
+    // ── Validate backend ────────────────────────────────────────────────
+    const backendRaw = args.backend ?? "chrome";
+    const backend = parseRenderBackend(backendRaw);
+    if (!backend) {
+      errorBox("Invalid backend", `Got "${backendRaw}". Must be chrome, native, or auto.`);
+      process.exit(1);
+    }
+
     // ── Validate workers ──────────────────────────────────────────────────
     let workers: number | undefined;
     if (args.workers != null && args.workers !== "auto") {
@@ -215,6 +239,22 @@ export default defineCommand({
       process.exit(1);
     }
 
+    const backendDecision = resolveRenderBackend({
+      requested: backend,
+      docker: useDocker,
+      format,
+      hdr: args.hdr ?? false,
+      nativeRuntimeAvailable: isNativeRendererAvailable(),
+    });
+    if (backendDecision.kind === "unavailable") {
+      errorBox(
+        "Native renderer unavailable",
+        backendDecision.reasons.map((reason) => `- ${reason}`).join("\n"),
+        "Use --backend chrome, or --backend auto to fall back automatically.",
+      );
+      process.exit(1);
+    }
+
     // ── Print render plan ─────────────────────────────────────────────────
     const workerCount = workers ?? defaultWorkerCount();
     if (!quiet) {
@@ -229,7 +269,22 @@ export default defineCommand({
           c.accent(project.name) +
           c.dim(" \u2192 " + outputPath),
       );
-      console.log(c.dim("   " + fps + "fps \u00B7 " + quality + " \u00B7 " + workerLabel));
+      const backendLabel = formatBackendLabel(backendDecision.requested, backendDecision.kind);
+      console.log(
+        c.dim(
+          "   " +
+            fps +
+            "fps \u00B7 " +
+            quality +
+            " \u00B7 " +
+            workerLabel +
+            " \u00B7 backend " +
+            backendLabel,
+        ),
+      );
+      if (backendDecision.requested === "auto" && backendDecision.reasons.length > 0) {
+        console.log(c.dim("   Native fallback: " + backendDecision.reasons.join("; ")));
+      }
       console.log("");
     }
 
@@ -302,31 +357,80 @@ export default defineCommand({
     }
 
     // ── Render ────────────────────────────────────────────────────────────
+    const renderOptions: RenderOptions = {
+      fps,
+      quality,
+      format,
+      workers: workerCount,
+      gpu: useGpu,
+      hdr: args.hdr ?? false,
+      crf,
+      videoBitrate,
+      quiet,
+      browserPath,
+    };
+
     if (useDocker) {
-      await renderDocker(project.dir, outputPath, {
+      await renderDocker(project.dir, outputPath, renderOptions);
+    } else if (backendDecision.kind === "native") {
+      const nativeStart = Date.now();
+      const nativeResult = await renderNativeProject(project.dir, outputPath, {
         fps,
         quality,
-        format,
-        workers: workerCount,
-        gpu: useGpu,
-        hdr: args.hdr ?? false,
-        crf,
-        videoBitrate,
+        browserPath,
         quiet,
-      });
+      }).catch((error: unknown) =>
+        handleRenderError(
+          error,
+          renderOptions,
+          nativeStart,
+          false,
+          "Use --backend chrome to render through the Chrome pipeline",
+        ),
+      );
+
+      if (nativeResult.kind === "rendered") {
+        trackNativeRenderMetrics(nativeResult, renderOptions);
+        printRenderComplete(outputPath, nativeResult.elapsedMs, quiet);
+        return;
+      }
+
+      if (nativeResult.kind === "unsupported") {
+        const reasons = formatUnsupportedNativeFeatures(nativeResult.support.reasons);
+        if (backendDecision.requested === "auto") {
+          if (!quiet) {
+            console.log(c.dim("   Native fallback:\n" + reasons));
+            console.log("");
+          }
+          await renderLocal(project.dir, outputPath, renderOptions);
+          return;
+        }
+
+        errorBox(
+          "Native renderer fallback required",
+          reasons,
+          "Use --backend auto or --backend chrome for this composition.",
+        );
+        process.exit(1);
+      }
+
+      if (backendDecision.requested === "auto") {
+        if (!quiet) {
+          console.log(c.dim("   Native fallback: " + nativeResult.reasons.join("; ")));
+          console.log("");
+        }
+        await renderLocal(project.dir, outputPath, renderOptions);
+        return;
+      }
+
+      errorBox(
+        "Native renderer unavailable",
+        nativeResult.reasons.map((reason) => `- ${reason}`).join("\n"),
+        "Use --backend chrome, or install the native renderer toolchain.",
+      );
+      process.exit(1);
     } else {
-      await renderLocal(project.dir, outputPath, {
-        fps,
-        quality,
-        format,
-        workers: workerCount,
-        gpu: useGpu,
-        hdr: args.hdr ?? false,
-        crf,
-        videoBitrate,
-        quiet,
-        browserPath,
-      });
+      await renderLocal(project.dir, outputPath, renderOptions);
     }
   },
 });
@@ -344,6 +448,10 @@ interface RenderOptions {
   browserPath?: string;
 }
 
+function formatBackendLabel(requested: RenderBackend, selected: "chrome" | "native"): string {
+  return requested === "auto" ? `auto \u2192 ${selected}` : selected;
+}
+
 const DOCKER_IMAGE_PREFIX = "hyperframes-renderer";
 
 function dockerImageTag(version: string): string {
@@ -578,6 +686,33 @@ function handleRenderError(
   process.exit(1);
 }
 
+function trackNativeRenderMetrics(
+  result: Extract<NativeRenderResult, { kind: "rendered" }>,
+  options: RenderOptions,
+): void {
+  const compositionDurationMs = Math.round(result.duration * 1000);
+  const speedRatio =
+    compositionDurationMs > 0 && result.elapsedMs > 0
+      ? Math.round((compositionDurationMs / result.elapsedMs) * 100) / 100
+      : undefined;
+
+  trackRenderComplete({
+    durationMs: result.elapsedMs,
+    fps: options.fps,
+    quality: options.quality,
+    workers: options.workers,
+    docker: false,
+    gpu: true,
+    compositionDurationMs,
+    compositionWidth: result.width,
+    compositionHeight: result.height,
+    totalFrames: result.totalFrames,
+    speedRatio,
+    captureAvgMs: result.renderer.avgPaintMs,
+    ...getMemorySnapshot(),
+  });
+}
+
 /**
  * Extract rich metrics from the completed render job and send to telemetry.
  * speed_ratio = composition_duration / render_time — higher is better, >1 means faster than realtime.