@hyperframes/aws-lambda 0.6.20

package/README.md

@@ -0,0 +1,191 @@
+# @hyperframes/aws-lambda
+
+AWS Lambda adapter for HyperFrames distributed rendering. Ships three
+things together:
+
+1. The **Lambda handler** that wraps the OSS `plan` / `renderChunk` /
+   `assemble` primitives behind a single dispatch boundary Step Functions
+   can drive (`src/handler.ts`).
+2. A **client-side SDK** — `renderToLambda`, `getRenderProgress`,
+   `deploySite`, plus `validateDistributedRenderConfig` and
+   `computeRenderCost` (`src/sdk/`).
+3. An **`aws-cdk-lib` L2 construct** (`HyperframesRenderStack`) that
+   provisions the same topology as `examples/aws-lambda/template.yaml`
+   inside an adopter's own CDK app (`src/cdk/`).
+
+The handler ZIP and the SAM template still drive a maintainer-run real-AWS
+smoke flow; the SDK + CDK are the supported public surface for adopters.
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ Step Functions state machine                                     │
+│   Plan → Map(N) RenderChunk → Assemble                           │
+└──────────────────────────────────────────────────────────────────┘
+                              │ dispatches by event.Action
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ One Lambda function (this package's `dist/handler.zip`)          │
+│   handler.mjs                                                    │
+│     ├─ Action="plan"        → @hyperframes/producer/distributed  │
+│     ├─ Action="renderChunk" → @hyperframes/producer/distributed  │
+│     └─ Action="assemble"    → @hyperframes/producer/distributed  │
+│   bin/ffmpeg                — ffmpeg-static                      │
+│   node_modules/@sparticuz/chromium/ — Lambda-optimised Chromium  │
+└──────────────────────────────────────────────────────────────────┘
+                              │ pure functions over local paths
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│ S3 bucket — plan tarball + per-chunk outputs + final mp4         │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+The handler downloads inputs from S3 into `/tmp`, calls the OSS primitive,
+uploads outputs back to S3, and returns a small JSON result that fits
+inside Step Functions' history budget (under 200 bytes per chunk).
+
+## Chrome runtime
+
+The package supports two Chromium sources:
+
+| Source                          | Default | Size               | When to pick it                                                                                                       |
+| ------------------------------- | ------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `@sparticuz/chromium`           | yes     | ~70 MiB compressed | Lambda. Decompresses into `/tmp` at runtime; the rest of the ecosystem already uses it for headless-Chrome-in-Lambda. |
+| Bundled `chrome-headless-shell` | no      | ~140 MiB           | Fallback. Used if `@sparticuz/chromium` ever drops `HeadlessExperimental.beginFrame` support.                         |
+
+Pick the source at build time:
+
+```bash
+bun run --cwd packages/aws-lambda build:zip
+bun run --cwd packages/aws-lambda build:zip -- --source=chrome-headless-shell
+```
+
+The handler reads `HYPERFRAMES_LAMBDA_CHROME_SOURCE` at boot. The build
+script sets that env var via Lambda function configuration in
+`examples/aws-lambda/template.yaml`.
+
+## BeginFrame regression guard
+
+HyperFrames' renderer drives Chrome via the CDP
+`HeadlessExperimental.beginFrame` command — same path the K8s deploy uses.
+The Lambda adapter assumes that `@sparticuz/chromium`'s
+chrome-headless-shell build honours BeginFrame. To prove it (and re-prove
+it on every release), the package ships a Docker probe:
+
+```bash
+# Build the Lambda-like container and run the probe.
+bun run --cwd packages/aws-lambda probe:beginframe:docker
+```
+
+The probe boots `@sparticuz/chromium` inside
+`public.ecr.aws/lambda/nodejs:22` and asserts CDP `beginFrame` with
+`screenshot: true` returns a PNG buffer. Exit code 0 = green; non-zero =
+fall back to bundling chrome-headless-shell directly via `--source=chrome-headless-shell`.
+
+## Building the ZIP
+
+```bash
+bun install                                          # at the monorepo root
+bun run --cwd packages/aws-lambda build:zip          # → packages/aws-lambda/dist/handler.zip
+bun run --cwd packages/aws-lambda verify:zip-size    # CI gate
+```
+
+The build script bundles `src/handler.ts` via esbuild, stages
+`@sparticuz/chromium` and `puppeteer-core` under `node_modules/`, copies
+ffmpeg-static into `bin/`, and zips the result. The unzipped layout is
+designed to extract cleanly into Lambda's `/var/task/`.
+
+`verify:zip-size` enforces:
+
+- Unzipped ≤ 248 MiB (in-house budget; Lambda hard ceiling is 250 MiB unzipped — AWS docs label this "250 MB" but use binary mebibytes)
+- Zipped ≤ 150 MiB (in-house budget; Lambda has no hard zipped cap for S3-deployed functions)
+
+CI fails the PR if either is exceeded.
+
+## Running tests
+
+```bash
+bun run --cwd packages/aws-lambda test               # unit tests (no Chrome)
+bun run --cwd packages/aws-lambda probe:beginframe   # local probe (Linux only)
+```
+
+## Using the SDK
+
+After deploying the stack (via the SAM template, CDK construct below, or
+your own CFN of choice), drive renders from Node:
+
+```ts
+import { deploySite, getRenderProgress, renderToLambda } from "@hyperframes/aws-lambda";
+
+// One-time upload per project version.
+const site = await deploySite({
+  projectDir: "./my-composition",
+  bucketName: "hyperframes-render-bucket",
+});
+
+// Start a render. Returns immediately — does NOT poll.
+const handle = await renderToLambda({
+  siteHandle: site,
+  bucketName: site.bucketName,
+  stateMachineArn: "arn:aws:states:us-east-1:123:stateMachine:hyperframes-render",
+  config: {
+    fps: 30,
+    width: 1920,
+    height: 1080,
+    format: "mp4",
+    chunkSize: 240,
+    maxParallelChunks: 16,
+    runtimeCap: "lambda",
+  },
+});
+
+// Poll progress + cost on your own cadence.
+const progress = await getRenderProgress({ executionArn: handle.executionArn });
+console.log(progress.overallProgress, progress.costs.displayCost);
+if (progress.status === "SUCCEEDED" && progress.outputFile) {
+  console.log("Render landed at", progress.outputFile.s3Uri);
+}
+```
+
+`renderToLambda` validates the config client-side via
+`validateDistributedRenderConfig` and throws a typed `InvalidConfigError`
+before the Step Functions execution starts, so shape errors surface
+synchronously instead of as opaque `ExecutionFailed` results.
+
+`getRenderProgress` reports an approximate per-render cost
+(`accruedSoFarUsd` plus a formatted `displayCost`) derived from Lambda
+billed-duration × memory × the us-east-1 on-demand rate plus the Step
+Functions transition price. The math is documented in
+`src/sdk/costAccounting.ts`; numbers are best-effort and exclude S3
+transfer.
+
+## Using the CDK construct
+
+```ts
+import { App, Stack } from "aws-cdk-lib";
+import { HyperframesRenderStack } from "@hyperframes/aws-lambda/cdk";
+
+const app = new App();
+const stack = new Stack(app, "MyApp");
+const render = new HyperframesRenderStack(stack, "Render", {
+  // optional: reservedConcurrency: 8,
+  // optional: lambdaMemoryMb: 10240,
+  // optional: chromeSource: "sparticuz",
+});
+
+// Re-export so an adopter app can wire dashboards / SNS topics.
+new CfnOutput(stack, "RenderBucketName", { value: render.bucket.bucketName });
+new CfnOutput(stack, "StateMachineArn", { value: render.stateMachine.stateMachineArn });
+```
+
+`aws-cdk-lib` and `constructs` are **optional peer dependencies**: SDK-only
+consumers don't pull them at runtime. The construct itself imports from
+`@hyperframes/aws-lambda/cdk`.
+
+## What's still ahead
+
+- `hyperframes lambda` CLI (deploy / sites create / render / progress / destroy) — PR 6.5.
+- IAM bootstrap subcommand (`policies role | user | validate`) — PR 6.9.
+- Lambda-local regression harness (`--mode=lambda-local`) — PR 6.6.
+- Adopter-facing migration guide — PR 6.8.

package/dist/cdk/HyperframesRenderStack.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `HyperframesRenderStack` — aws-cdk-lib L2 construct that emits the same
+ * topology as `examples/aws-lambda/template.yaml`.
+ *
+ * Adopters who embed HyperFrames inside their own CDK app can extend this
+ * construct or compose alongside it; the construct exposes its `.bucket`,
+ * `.renderFunction`, and `.stateMachine` properties so additional
+ * resources (alarms, dashboards, SNS topics) can be wired without
+ * re-deriving the ARNs from a stack export.
+ *
+ * `aws-cdk-lib` and `constructs` are **peerDependencies**. The package
+ * still type-checks (and the snapshot test still runs) because they're
+ * also `devDependencies`, but adopters who only consume the SDK side of
+ * `@hyperframes/aws-lambda` don't pull the CDK tree at runtime.
+ *
+ * Drift from the SAM template is guarded by the snapshot test
+ * (`HyperframesRenderStack.snapshot.test.ts`), which diffs the synthed
+ * CloudFormation against the SAM-rendered CloudFormation modulo
+ * normalisation.
+ */
+import { RemovalPolicy } from "aws-cdk-lib";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import * as s3 from "aws-cdk-lib/aws-s3";
+import * as sfn from "aws-cdk-lib/aws-stepfunctions";
+import { Construct } from "constructs";
+/** Construction-time props for {@link HyperframesRenderStack}. */
+export interface HyperframesRenderStackProps {
+    /** Name prefix applied to function / state-machine / alarm names. Default `"hyperframes"`. */
+    projectName?: string;
+    /** Lambda memory in MB. Allowed: 2048..10240 in 1024 steps. Default 10240. */
+    lambdaMemoryMb?: 2048 | 3072 | 4096 | 5120 | 6144 | 7168 | 8192 | 9216 | 10240;
+    /** Per-invocation Lambda timeout. Default 900 (15 min, Lambda hard cap). */
+    lambdaTimeoutSec?: number;
+    /** Lambda reserved concurrency cap. `undefined` = unreserved (account default). */
+    reservedConcurrency?: number;
+    /** Which Chrome runtime was bundled into the handler ZIP. Default `"sparticuz"`. */
+    chromeSource?: "sparticuz" | "chrome-headless-shell";
+    /** Threshold for the runaway-invocations alarm. Default 1000 invocations/hour. */
+    chunkInvocationAlarmThreshold?: number;
+    /**
+     * Absolute path to the handler ZIP produced by
+     * `bun run --cwd packages/aws-lambda build:zip`. Defaults to the
+     * package-relative path the build script writes to. Adopters who
+     * deploy the published handler ZIP set this explicitly.
+     */
+    handlerZipPath?: string;
+    /** S3 bucket retention policy on stack delete. Default RETAIN. */
+    bucketRemovalPolicy?: RemovalPolicy;
+}
+export declare class HyperframesRenderStack extends Construct {
+    /** S3 bucket for plan tarballs, chunk outputs, and final renders. */
+    readonly bucket: s3.Bucket;
+    /** The single Lambda function dispatching plan / renderChunk / assemble. */
+    readonly renderFunction: lambda.Function;
+    /** The Step Functions state machine orchestrating the render. */
+    readonly stateMachine: sfn.StateMachine;
+    constructor(scope: Construct, id: string, props?: HyperframesRenderStackProps);
+    /**
+     * Build the state-machine chain. Kept in a single method so the SAM
+     * template and this construct can be diffed shape-for-shape during
+     * the snapshot test.
+     */
+    private buildStateMachineDefinition;
+}
+//# sourceMappingURL=HyperframesRenderStack.d.ts.map

package/dist/cdk/HyperframesRenderStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HyperframesRenderStack.d.ts","sourceRoot":"","sources":["../../src/cdk/HyperframesRenderStack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAY,aAAa,EAAQ,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,MAAM,MAAM,wBAAwB,CAAC;AAEjD,OAAO,KAAK,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,KAAK,GAAG,MAAM,+BAA+B,CAAC;AAErD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,kEAAkE;AAClE,MAAM,WAAW,2BAA2B;IAC1C,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;IAC/E,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,YAAY,CAAC,EAAE,WAAW,GAAG,uBAAuB,CAAC;IACrD,kFAAkF;IAClF,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,mBAAmB,CAAC,EAAE,aAAa,CAAC;CACrC;AAOD,qBAAa,sBAAuB,SAAQ,SAAS;IACnD,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,QAAQ,CAAC;IACzC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,YAAY,CAAC;gBAE5B,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,GAAE,2BAAgC;IAmHjF;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;CA2IpC"}

package/dist/cdk/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CDK subpath export — `@hyperframes/aws-lambda/cdk`.
+ *
+ * Pulled into its own subpath so SDK-only consumers don't import
+ * `aws-cdk-lib`. The construct itself depends on `aws-cdk-lib` and
+ * `constructs` as peer dependencies; adopters using CDK already have
+ * both installed.
+ */
+export { HyperframesRenderStack, type HyperframesRenderStackProps, } from "./HyperframesRenderStack.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cdk/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,2BAA2B,GACjC,MAAM,6BAA6B,CAAC"}

package/dist/cdk/index.js

@@ -0,0 +1,263 @@
+// src/cdk/HyperframesRenderStack.ts
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Duration, RemovalPolicy, Size } from "aws-cdk-lib";
+import * as cloudwatch from "aws-cdk-lib/aws-cloudwatch";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import * as logs from "aws-cdk-lib/aws-logs";
+import * as s3 from "aws-cdk-lib/aws-s3";
+import * as sfn from "aws-cdk-lib/aws-stepfunctions";
+import * as tasks from "aws-cdk-lib/aws-stepfunctions-tasks";
+import { Construct } from "constructs";
+var DEFAULT_MEMORY_MB = 10240;
+var DEFAULT_TIMEOUT_SEC = 900;
+var DEFAULT_CHROME_SOURCE = "sparticuz";
+var DEFAULT_ALARM_THRESHOLD = 1e3;
+var HyperframesRenderStack = class extends Construct {
+  /** S3 bucket for plan tarballs, chunk outputs, and final renders. */
+  bucket;
+  /** The single Lambda function dispatching plan / renderChunk / assemble. */
+  renderFunction;
+  /** The Step Functions state machine orchestrating the render. */
+  stateMachine;
+  constructor(scope, id, props = {}) {
+    super(scope, id);
+    const projectName = props.projectName ?? "hyperframes";
+    const memorySize = props.lambdaMemoryMb ?? DEFAULT_MEMORY_MB;
+    const timeoutSec = props.lambdaTimeoutSec ?? DEFAULT_TIMEOUT_SEC;
+    const chromeSource = props.chromeSource ?? DEFAULT_CHROME_SOURCE;
+    const alarmThreshold = props.chunkInvocationAlarmThreshold ?? DEFAULT_ALARM_THRESHOLD;
+    const handlerZipPath = props.handlerZipPath ?? defaultHandlerZipPath();
+    this.bucket = new s3.Bucket(this, "RenderBucket", {
+      removalPolicy: props.bucketRemovalPolicy ?? RemovalPolicy.RETAIN,
+      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+      // `Suspended` is the cheapest mode that still satisfies KMS / replication
+      // prerequisites callers can layer on later. Adopters who treat the final
+      // mp4 as user-keepable can switch to `Enabled`.
+      versioned: false,
+      lifecycleRules: [
+        {
+          id: "ExpireIntermediates",
+          enabled: true,
+          prefix: "renders/",
+          expiration: Duration.days(7)
+        }
+      ]
+    });
+    this.renderFunction = new lambda.Function(this, "RenderFunction", {
+      functionName: `${projectName}-render`,
+      runtime: lambda.Runtime.NODEJS_22_X,
+      handler: "handler.handler",
+      code: lambda.Code.fromAsset(handlerZipPath),
+      memorySize,
+      timeout: Duration.seconds(timeoutSec),
+      ephemeralStorageSize: Size.gibibytes(10),
+      architecture: lambda.Architecture.X86_64,
+      reservedConcurrentExecutions: props.reservedConcurrency,
+      tracing: lambda.Tracing.ACTIVE,
+      environment: {
+        NODE_OPTIONS: "--enable-source-maps",
+        TMPDIR: "/tmp",
+        HYPERFRAMES_LAMBDA_CHROME_SOURCE: chromeSource
+      }
+    });
+    this.bucket.grantReadWrite(this.renderFunction);
+    const stateMachineLogGroup = new logs.LogGroup(this, "RenderStateMachineLogGroup", {
+      logGroupName: `/aws/states/${projectName}-render`,
+      retention: logs.RetentionDays.ONE_MONTH,
+      removalPolicy: RemovalPolicy.DESTROY
+    });
+    const definition = this.buildStateMachineDefinition();
+    this.stateMachine = new sfn.StateMachine(this, "RenderStateMachine", {
+      stateMachineName: `${projectName}-render`,
+      stateMachineType: sfn.StateMachineType.STANDARD,
+      definitionBody: sfn.DefinitionBody.fromChainable(definition),
+      tracingEnabled: true,
+      timeout: Duration.hours(1),
+      logs: {
+        destination: stateMachineLogGroup,
+        level: sfn.LogLevel.ERROR,
+        includeExecutionData: false
+      }
+    });
+    this.renderFunction.grantInvoke(this.stateMachine);
+    new cloudwatch.Alarm(this, "RenderChunkInvocationAlarm", {
+      alarmName: `${projectName}-runaway-chunk-invocations`,
+      alarmDescription: "Fires if RenderChunk Lambda invocations exceed the configured threshold in a 1-hour window.",
+      metric: this.renderFunction.metricInvocations({
+        period: Duration.hours(1),
+        statistic: cloudwatch.Stats.SUM
+      }),
+      threshold: alarmThreshold,
+      evaluationPeriods: 1,
+      comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
+      treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING
+    });
+    new cloudwatch.Alarm(this, "RenderFunctionErrorsAlarm", {
+      alarmName: `${projectName}-render-function-errors`,
+      alarmDescription: "Fires if the render Lambda reports any errors in a 5-minute window.",
+      metric: this.renderFunction.metricErrors({
+        period: Duration.minutes(5),
+        statistic: cloudwatch.Stats.SUM
+      }),
+      threshold: 1,
+      evaluationPeriods: 1,
+      comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+      treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING
+    });
+    new cloudwatch.Alarm(this, "RenderStateMachineFailedAlarm", {
+      alarmName: `${projectName}-render-state-machine-failed`,
+      alarmDescription: "Fires when the render state machine reports a failed execution.",
+      metric: this.stateMachine.metricFailed({
+        period: Duration.minutes(5),
+        statistic: cloudwatch.Stats.SUM
+      }),
+      threshold: 1,
+      evaluationPeriods: 1,
+      comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+      treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING
+    });
+  }
+  /**
+   * Build the state-machine chain. Kept in a single method so the SAM
+   * template and this construct can be diffed shape-for-shape during
+   * the snapshot test.
+   */
+  buildStateMachineDefinition() {
+    const NON_RETRYABLE_PLAN = [
+      "FFMPEG_VERSION_MISMATCH",
+      "PLAN_HASH_MISMATCH",
+      "BROWSER_GPU_NOT_SOFTWARE",
+      "FONT_FETCH_FAILED",
+      "PLAN_TOO_LARGE",
+      "FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED"
+    ];
+    const NON_RETRYABLE_CHUNK = [
+      "FFMPEG_VERSION_MISMATCH",
+      "PLAN_HASH_MISMATCH",
+      "BROWSER_GPU_NOT_SOFTWARE"
+    ];
+    const NON_RETRYABLE_ASSEMBLE = [
+      "FFMPEG_VERSION_MISMATCH",
+      "PLAN_HASH_MISMATCH",
+      "FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED"
+    ];
+    const plan = new tasks.LambdaInvoke(this, "Plan", {
+      lambdaFunction: this.renderFunction,
+      payload: sfn.TaskInput.fromObject({
+        Action: "plan",
+        "ProjectS3Uri.$": "$.ProjectS3Uri",
+        "PlanOutputS3Prefix.$": "$.PlanOutputS3Prefix",
+        "Config.$": "$.Config"
+      }),
+      resultSelector: {
+        "PlanS3Uri.$": "$.Payload.PlanS3Uri",
+        "PlanHash.$": "$.Payload.PlanHash",
+        "ChunkCount.$": "$.Payload.ChunkCount",
+        "Format.$": "$.Payload.Format",
+        "HasAudio.$": "$.Payload.HasAudio",
+        "AudioS3Uri.$": "$.Payload.AudioS3Uri"
+      },
+      resultPath: "$.Plan"
+    });
+    plan.addRetry({
+      errors: NON_RETRYABLE_PLAN,
+      maxAttempts: 0
+    });
+    plan.addRetry({
+      errors: ["States.ALL"],
+      interval: Duration.seconds(2),
+      maxAttempts: 4,
+      backoffRate: 2,
+      maxDelay: Duration.seconds(60)
+    });
+    const buildChunkList = new sfn.Pass(this, "BuildChunkList", {
+      parameters: {
+        "ChunkIndexes.$": "States.ArrayRange(0, States.MathAdd($.Plan.ChunkCount, -1), 1)"
+      },
+      resultPath: "$.Iterator"
+    });
+    const planProducedZero = new sfn.Fail(this, "PlanProducedZeroChunks", {
+      error: "PLAN_TOO_LARGE",
+      cause: "Plan returned ChunkCount=0 \u2014 non-retryable producer-side invariant violation."
+    });
+    const renderChunkTask = new tasks.LambdaInvoke(this, "RenderChunk", {
+      lambdaFunction: this.renderFunction,
+      payload: sfn.TaskInput.fromObject({
+        Action: "renderChunk",
+        "ChunkIndex.$": "$.ChunkIndex",
+        "PlanS3Uri.$": "$.PlanS3Uri",
+        "PlanHash.$": "$.PlanHash",
+        "ChunkOutputS3Prefix.$": "$.ChunkOutputS3Prefix",
+        "Format.$": "$.Format"
+      }),
+      resultSelector: {
+        "ChunkS3Uri.$": "$.Payload.ChunkS3Uri",
+        "ChunkIndex.$": "$.Payload.ChunkIndex",
+        "Sha256.$": "$.Payload.Sha256"
+      }
+    });
+    renderChunkTask.addRetry({
+      errors: NON_RETRYABLE_CHUNK,
+      maxAttempts: 0
+    });
+    renderChunkTask.addRetry({
+      errors: ["States.ALL"],
+      interval: Duration.seconds(2),
+      maxAttempts: 4,
+      backoffRate: 2,
+      maxDelay: Duration.seconds(60)
+    });
+    const renderChunks = new sfn.Map(this, "RenderChunks", {
+      itemsPath: "$.Iterator.ChunkIndexes",
+      itemSelector: {
+        "ChunkIndex.$": "$$.Map.Item.Value",
+        "PlanS3Uri.$": "$.Plan.PlanS3Uri",
+        "PlanHash.$": "$.Plan.PlanHash",
+        "ChunkOutputS3Prefix.$": "$.PlanOutputS3Prefix",
+        "Format.$": "$.Plan.Format"
+      },
+      maxConcurrencyPath: "$.Plan.ChunkCount",
+      resultPath: "$.Chunks"
+    });
+    renderChunks.itemProcessor(renderChunkTask);
+    const assemble = new tasks.LambdaInvoke(this, "Assemble", {
+      lambdaFunction: this.renderFunction,
+      payload: sfn.TaskInput.fromObject({
+        Action: "assemble",
+        "PlanS3Uri.$": "$.Plan.PlanS3Uri",
+        "ChunkS3Uris.$": "$.Chunks[*].ChunkS3Uri",
+        "AudioS3Uri.$": "$.Plan.AudioS3Uri",
+        "OutputS3Uri.$": "$.OutputS3Uri",
+        "Format.$": "$.Plan.Format"
+      }),
+      resultSelector: {
+        "OutputS3Uri.$": "$.Payload.OutputS3Uri",
+        "FramesEncoded.$": "$.Payload.FramesEncoded",
+        "FileSize.$": "$.Payload.FileSize"
+      },
+      resultPath: "$.Output"
+    });
+    assemble.addRetry({
+      errors: NON_RETRYABLE_ASSEMBLE,
+      maxAttempts: 0
+    });
+    assemble.addRetry({
+      errors: ["States.ALL"],
+      interval: Duration.seconds(2),
+      maxAttempts: 4,
+      backoffRate: 2,
+      maxDelay: Duration.seconds(60)
+    });
+    const assertChunkCount = new sfn.Choice(this, "AssertChunkCount").when(sfn.Condition.numberGreaterThan("$.Plan.ChunkCount", 0), renderChunks.next(assemble)).otherwise(planProducedZero);
+    return plan.next(buildChunkList).next(assertChunkCount);
+  }
+};
+function defaultHandlerZipPath() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, "..", "..", "dist", "handler.zip");
+}
+export {
+  HyperframesRenderStack
+};
+//# sourceMappingURL=index.js.map

package/dist/cdk/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/cdk/HyperframesRenderStack.ts"],
+  "sourcesContent": ["/**\n * `HyperframesRenderStack` \u2014 aws-cdk-lib L2 construct that emits the same\n * topology as `examples/aws-lambda/template.yaml`.\n *\n * Adopters who embed HyperFrames inside their own CDK app can extend this\n * construct or compose alongside it; the construct exposes its `.bucket`,\n * `.renderFunction`, and `.stateMachine` properties so additional\n * resources (alarms, dashboards, SNS topics) can be wired without\n * re-deriving the ARNs from a stack export.\n *\n * `aws-cdk-lib` and `constructs` are **peerDependencies**. The package\n * still type-checks (and the snapshot test still runs) because they're\n * also `devDependencies`, but adopters who only consume the SDK side of\n * `@hyperframes/aws-lambda` don't pull the CDK tree at runtime.\n *\n * Drift from the SAM template is guarded by the snapshot test\n * (`HyperframesRenderStack.snapshot.test.ts`), which diffs the synthed\n * CloudFormation against the SAM-rendered CloudFormation modulo\n * normalisation.\n */\n\nimport { dirname, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { Duration, RemovalPolicy, Size } from \"aws-cdk-lib\";\nimport * as cloudwatch from \"aws-cdk-lib/aws-cloudwatch\";\nimport * as lambda from \"aws-cdk-lib/aws-lambda\";\nimport * as logs from \"aws-cdk-lib/aws-logs\";\nimport * as s3 from \"aws-cdk-lib/aws-s3\";\nimport * as sfn from \"aws-cdk-lib/aws-stepfunctions\";\nimport * as tasks from \"aws-cdk-lib/aws-stepfunctions-tasks\";\nimport { Construct } from \"constructs\";\n\n/** Construction-time props for {@link HyperframesRenderStack}. */\nexport interface HyperframesRenderStackProps {\n  /** Name prefix applied to function / state-machine / alarm names. Default `\"hyperframes\"`. */\n  projectName?: string;\n  /** Lambda memory in MB. Allowed: 2048..10240 in 1024 steps. Default 10240. */\n  lambdaMemoryMb?: 2048 | 3072 | 4096 | 5120 | 6144 | 7168 | 8192 | 9216 | 10240;\n  /** Per-invocation Lambda timeout. Default 900 (15 min, Lambda hard cap). */\n  lambdaTimeoutSec?: number;\n  /** Lambda reserved concurrency cap. `undefined` = unreserved (account default). */\n  reservedConcurrency?: number;\n  /** Which Chrome runtime was bundled into the handler ZIP. Default `\"sparticuz\"`. */\n  chromeSource?: \"sparticuz\" | \"chrome-headless-shell\";\n  /** Threshold for the runaway-invocations alarm. Default 1000 invocations/hour. */\n  chunkInvocationAlarmThreshold?: number;\n  /**\n   * Absolute path to the handler ZIP produced by\n   * `bun run --cwd packages/aws-lambda build:zip`. Defaults to the\n   * package-relative path the build script writes to. Adopters who\n   * deploy the published handler ZIP set this explicitly.\n   */\n  handlerZipPath?: string;\n  /** S3 bucket retention policy on stack delete. Default RETAIN. */\n  bucketRemovalPolicy?: RemovalPolicy;\n}\n\nconst DEFAULT_MEMORY_MB = 10240;\nconst DEFAULT_TIMEOUT_SEC = 900;\nconst DEFAULT_CHROME_SOURCE = \"sparticuz\";\nconst DEFAULT_ALARM_THRESHOLD = 1000;\n\nexport class HyperframesRenderStack extends Construct {\n  /** S3 bucket for plan tarballs, chunk outputs, and final renders. */\n  readonly bucket: s3.Bucket;\n  /** The single Lambda function dispatching plan / renderChunk / assemble. */\n  readonly renderFunction: lambda.Function;\n  /** The Step Functions state machine orchestrating the render. */\n  readonly stateMachine: sfn.StateMachine;\n\n  constructor(scope: Construct, id: string, props: HyperframesRenderStackProps = {}) {\n    super(scope, id);\n\n    const projectName = props.projectName ?? \"hyperframes\";\n    const memorySize = props.lambdaMemoryMb ?? DEFAULT_MEMORY_MB;\n    const timeoutSec = props.lambdaTimeoutSec ?? DEFAULT_TIMEOUT_SEC;\n    const chromeSource = props.chromeSource ?? DEFAULT_CHROME_SOURCE;\n    const alarmThreshold = props.chunkInvocationAlarmThreshold ?? DEFAULT_ALARM_THRESHOLD;\n    const handlerZipPath = props.handlerZipPath ?? defaultHandlerZipPath();\n\n    this.bucket = new s3.Bucket(this, \"RenderBucket\", {\n      removalPolicy: props.bucketRemovalPolicy ?? RemovalPolicy.RETAIN,\n      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,\n      // `Suspended` is the cheapest mode that still satisfies KMS / replication\n      // prerequisites callers can layer on later. Adopters who treat the final\n      // mp4 as user-keepable can switch to `Enabled`.\n      versioned: false,\n      lifecycleRules: [\n        {\n          id: \"ExpireIntermediates\",\n          enabled: true,\n          prefix: \"renders/\",\n          expiration: Duration.days(7),\n        },\n      ],\n    });\n\n    this.renderFunction = new lambda.Function(this, \"RenderFunction\", {\n      functionName: `${projectName}-render`,\n      runtime: lambda.Runtime.NODEJS_22_X,\n      handler: \"handler.handler\",\n      code: lambda.Code.fromAsset(handlerZipPath),\n      memorySize,\n      timeout: Duration.seconds(timeoutSec),\n      ephemeralStorageSize: Size.gibibytes(10),\n      architecture: lambda.Architecture.X86_64,\n      reservedConcurrentExecutions: props.reservedConcurrency,\n      tracing: lambda.Tracing.ACTIVE,\n      environment: {\n        NODE_OPTIONS: \"--enable-source-maps\",\n        TMPDIR: \"/tmp\",\n        HYPERFRAMES_LAMBDA_CHROME_SOURCE: chromeSource,\n      },\n    });\n\n    // Scoped S3 perms only \u2014 explicitly NOT `CloudWatchLogsFullAccess`,\n    // which would grant `logs:*` on `*` and overscope adopter accounts.\n    // SAM's AWSLambdaBasicExecutionRole equivalent is included by the\n    // default `new lambda.Function` execution role.\n    this.bucket.grantReadWrite(this.renderFunction);\n\n    const stateMachineLogGroup = new logs.LogGroup(this, \"RenderStateMachineLogGroup\", {\n      logGroupName: `/aws/states/${projectName}-render`,\n      retention: logs.RetentionDays.ONE_MONTH,\n      removalPolicy: RemovalPolicy.DESTROY,\n    });\n\n    const definition = this.buildStateMachineDefinition();\n\n    this.stateMachine = new sfn.StateMachine(this, \"RenderStateMachine\", {\n      stateMachineName: `${projectName}-render`,\n      stateMachineType: sfn.StateMachineType.STANDARD,\n      definitionBody: sfn.DefinitionBody.fromChainable(definition),\n      tracingEnabled: true,\n      timeout: Duration.hours(1),\n      logs: {\n        destination: stateMachineLogGroup,\n        level: sfn.LogLevel.ERROR,\n        includeExecutionData: false,\n      },\n    });\n\n    this.renderFunction.grantInvoke(this.stateMachine);\n\n    new cloudwatch.Alarm(this, \"RenderChunkInvocationAlarm\", {\n      alarmName: `${projectName}-runaway-chunk-invocations`,\n      alarmDescription:\n        \"Fires if RenderChunk Lambda invocations exceed the configured threshold in a 1-hour window.\",\n      metric: this.renderFunction.metricInvocations({\n        period: Duration.hours(1),\n        statistic: cloudwatch.Stats.SUM,\n      }),\n      threshold: alarmThreshold,\n      evaluationPeriods: 1,\n      comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,\n      treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,\n    });\n\n    new cloudwatch.Alarm(this, \"RenderFunctionErrorsAlarm\", {\n      alarmName: `${projectName}-render-function-errors`,\n      alarmDescription: \"Fires if the render Lambda reports any errors in a 5-minute window.\",\n      metric: this.renderFunction.metricErrors({\n        period: Duration.minutes(5),\n        statistic: cloudwatch.Stats.SUM,\n      }),\n      threshold: 1,\n      evaluationPeriods: 1,\n      comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,\n      treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,\n    });\n\n    new cloudwatch.Alarm(this, \"RenderStateMachineFailedAlarm\", {\n      alarmName: `${projectName}-render-state-machine-failed`,\n      alarmDescription: \"Fires when the render state machine reports a failed execution.\",\n      metric: this.stateMachine.metricFailed({\n        period: Duration.minutes(5),\n        statistic: cloudwatch.Stats.SUM,\n      }),\n      threshold: 1,\n      evaluationPeriods: 1,\n      comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,\n      treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,\n    });\n  }\n\n  /**\n   * Build the state-machine chain. Kept in a single method so the SAM\n   * template and this construct can be diffed shape-for-shape during\n   * the snapshot test.\n   */\n  private buildStateMachineDefinition(): sfn.IChainable {\n    const NON_RETRYABLE_PLAN = [\n      \"FFMPEG_VERSION_MISMATCH\",\n      \"PLAN_HASH_MISMATCH\",\n      \"BROWSER_GPU_NOT_SOFTWARE\",\n      \"FONT_FETCH_FAILED\",\n      \"PLAN_TOO_LARGE\",\n      \"FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED\",\n    ];\n    const NON_RETRYABLE_CHUNK = [\n      \"FFMPEG_VERSION_MISMATCH\",\n      \"PLAN_HASH_MISMATCH\",\n      \"BROWSER_GPU_NOT_SOFTWARE\",\n    ];\n    const NON_RETRYABLE_ASSEMBLE = [\n      \"FFMPEG_VERSION_MISMATCH\",\n      \"PLAN_HASH_MISMATCH\",\n      \"FORMAT_NOT_SUPPORTED_IN_DISTRIBUTED\",\n    ];\n\n    const plan = new tasks.LambdaInvoke(this, \"Plan\", {\n      lambdaFunction: this.renderFunction,\n      payload: sfn.TaskInput.fromObject({\n        Action: \"plan\",\n        \"ProjectS3Uri.$\": \"$.ProjectS3Uri\",\n        \"PlanOutputS3Prefix.$\": \"$.PlanOutputS3Prefix\",\n        \"Config.$\": \"$.Config\",\n      }),\n      resultSelector: {\n        \"PlanS3Uri.$\": \"$.Payload.PlanS3Uri\",\n        \"PlanHash.$\": \"$.Payload.PlanHash\",\n        \"ChunkCount.$\": \"$.Payload.ChunkCount\",\n        \"Format.$\": \"$.Payload.Format\",\n        \"HasAudio.$\": \"$.Payload.HasAudio\",\n        \"AudioS3Uri.$\": \"$.Payload.AudioS3Uri\",\n      },\n      resultPath: \"$.Plan\",\n    });\n    plan.addRetry({\n      errors: NON_RETRYABLE_PLAN,\n      maxAttempts: 0,\n    });\n    plan.addRetry({\n      errors: [\"States.ALL\"],\n      interval: Duration.seconds(2),\n      maxAttempts: 4,\n      backoffRate: 2,\n      maxDelay: Duration.seconds(60),\n    });\n\n    const buildChunkList = new sfn.Pass(this, \"BuildChunkList\", {\n      parameters: {\n        \"ChunkIndexes.$\": \"States.ArrayRange(0, States.MathAdd($.Plan.ChunkCount, -1), 1)\",\n      },\n      resultPath: \"$.Iterator\",\n    });\n\n    const planProducedZero = new sfn.Fail(this, \"PlanProducedZeroChunks\", {\n      error: \"PLAN_TOO_LARGE\",\n      cause: \"Plan returned ChunkCount=0 \u2014 non-retryable producer-side invariant violation.\",\n    });\n\n    const renderChunkTask = new tasks.LambdaInvoke(this, \"RenderChunk\", {\n      lambdaFunction: this.renderFunction,\n      payload: sfn.TaskInput.fromObject({\n        Action: \"renderChunk\",\n        \"ChunkIndex.$\": \"$.ChunkIndex\",\n        \"PlanS3Uri.$\": \"$.PlanS3Uri\",\n        \"PlanHash.$\": \"$.PlanHash\",\n        \"ChunkOutputS3Prefix.$\": \"$.ChunkOutputS3Prefix\",\n        \"Format.$\": \"$.Format\",\n      }),\n      resultSelector: {\n        \"ChunkS3Uri.$\": \"$.Payload.ChunkS3Uri\",\n        \"ChunkIndex.$\": \"$.Payload.ChunkIndex\",\n        \"Sha256.$\": \"$.Payload.Sha256\",\n      },\n    });\n    renderChunkTask.addRetry({\n      errors: NON_RETRYABLE_CHUNK,\n      maxAttempts: 0,\n    });\n    renderChunkTask.addRetry({\n      errors: [\"States.ALL\"],\n      interval: Duration.seconds(2),\n      maxAttempts: 4,\n      backoffRate: 2,\n      maxDelay: Duration.seconds(60),\n    });\n\n    const renderChunks = new sfn.Map(this, \"RenderChunks\", {\n      itemsPath: \"$.Iterator.ChunkIndexes\",\n      itemSelector: {\n        \"ChunkIndex.$\": \"$$.Map.Item.Value\",\n        \"PlanS3Uri.$\": \"$.Plan.PlanS3Uri\",\n        \"PlanHash.$\": \"$.Plan.PlanHash\",\n        \"ChunkOutputS3Prefix.$\": \"$.PlanOutputS3Prefix\",\n        \"Format.$\": \"$.Plan.Format\",\n      },\n      maxConcurrencyPath: \"$.Plan.ChunkCount\",\n      resultPath: \"$.Chunks\",\n    });\n    renderChunks.itemProcessor(renderChunkTask);\n\n    const assemble = new tasks.LambdaInvoke(this, \"Assemble\", {\n      lambdaFunction: this.renderFunction,\n      payload: sfn.TaskInput.fromObject({\n        Action: \"assemble\",\n        \"PlanS3Uri.$\": \"$.Plan.PlanS3Uri\",\n        \"ChunkS3Uris.$\": \"$.Chunks[*].ChunkS3Uri\",\n        \"AudioS3Uri.$\": \"$.Plan.AudioS3Uri\",\n        \"OutputS3Uri.$\": \"$.OutputS3Uri\",\n        \"Format.$\": \"$.Plan.Format\",\n      }),\n      resultSelector: {\n        \"OutputS3Uri.$\": \"$.Payload.OutputS3Uri\",\n        \"FramesEncoded.$\": \"$.Payload.FramesEncoded\",\n        \"FileSize.$\": \"$.Payload.FileSize\",\n      },\n      resultPath: \"$.Output\",\n    });\n    assemble.addRetry({\n      errors: NON_RETRYABLE_ASSEMBLE,\n      maxAttempts: 0,\n    });\n    assemble.addRetry({\n      errors: [\"States.ALL\"],\n      interval: Duration.seconds(2),\n      maxAttempts: 4,\n      backoffRate: 2,\n      maxDelay: Duration.seconds(60),\n    });\n\n    const assertChunkCount = new sfn.Choice(this, \"AssertChunkCount\")\n      .when(sfn.Condition.numberGreaterThan(\"$.Plan.ChunkCount\", 0), renderChunks.next(assemble))\n      .otherwise(planProducedZero);\n\n    return plan.next(buildChunkList).next(assertChunkCount);\n  }\n}\n\n/**\n * Default location of the handler ZIP relative to this source file. Two\n * parents up = `packages/aws-lambda/`; the build script writes the ZIP\n * to `packages/aws-lambda/dist/handler.zip`. The package is published with\n * `main: \"./src/index.ts\"`, so this path resolves correctly both in the\n * source tree (during `bun test` / local CDK synth) and in a consumer's\n * `node_modules/@hyperframes/aws-lambda/` install.\n */\nfunction defaultHandlerZipPath(): string {\n  const here = dirname(fileURLToPath(import.meta.url));\n  return resolve(here, \"..\", \"..\", \"dist\", \"handler.zip\");\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/chromium.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Lambda-runtime Chrome resolver.
+ *
+ * `renderChunk()` (the only primitive that needs a browser) launches Chrome
+ * via the engine's `BrowserManager`. In Lambda we can't ship the full
+ * Puppeteer-managed Chrome download — Puppeteer's Chrome binary is ~330 MB
+ * unzipped, well over Lambda's 250 MB ZIP-deploy ceiling.
+ *
+ * Two valid runtime sources:
+ *
+ *   1. `@sparticuz/chromium` (primary). Decompresses a Lambda-optimised
+ *      `chrome-headless-shell` build into `/tmp` at runtime. ~70 MB
+ *      compressed; the same binary the rest of the ecosystem uses for
+ *      headless-Chrome-in-Lambda. CDP-level BeginFrame works because the
+ *      command lives in the protocol, not the binary; the
+ *      `scripts/probe-beginframe.ts` regression guard pins this.
+ *
+ *   2. A bundled `chrome-headless-shell` binary (fallback). If
+ *      `@sparticuz/chromium`'s build ever drops `HeadlessExperimental`
+ *      support, we fall back to the same `chrome-headless-shell` build
+ *      the K8s deploy uses. The fallback raises the ZIP from ~70 MB
+ *      Chrome to ~140 MB Chrome — still well under 250 MB.
+ *
+ * The runtime path is selected by the `HYPERFRAMES_LAMBDA_CHROME_SOURCE`
+ * env var (set by `build-zip.ts`):
+ *
+ *   "sparticuz"          → use `@sparticuz/chromium.executablePath()`
+ *   "chrome-headless-shell" → use `process.env.HYPERFRAMES_LAMBDA_CHROME_PATH`
+ *
+ * Adapters that bundle this package can override
+ * `HYPERFRAMES_LAMBDA_CHROME_PATH` directly when running outside Lambda
+ * (e.g. the SAM-local RIE smoke).
+ */
+/** Discriminator for the two supported Chrome sources. */
+export type ChromeSource = "sparticuz" | "chrome-headless-shell";
+/**
+ * Read which Chrome source the bundled ZIP was built against. Defaults to
+ * `"sparticuz"` so a fresh build with no env override picks the primary
+ * path.
+ */
+export declare function resolveChromeSource(): ChromeSource;
+/**
+ * Resolve the absolute path to a Chrome binary suitable for BeginFrame.
+ *
+ * For `"sparticuz"`: dynamically import `@sparticuz/chromium` and call
+ * `chromium.executablePath()`. The module is dynamic so a build-zip that
+ * never reaches the import (because the fallback Chrome is bundled) can
+ * tree-shake it out.
+ *
+ * For `"chrome-headless-shell"`: read the path from
+ * `HYPERFRAMES_LAMBDA_CHROME_PATH`. Throws if absent or non-existent so a
+ * misconfigured deploy fails loudly at boot rather than at first frame.
+ */
+export declare function resolveChromeExecutablePath(): Promise<string>;
+/**
+ * Resolve the Chromium launch args for the selected source. For
+ * `@sparticuz/chromium` we forward `chromium.args` (Lambda-tuned defaults
+ * — single-process, no-sandbox, /tmp paths). For the shell fallback the
+ * engine's own arg builder owns it; we return an empty array so the
+ * engine's defaults apply.
+ */
+export declare function resolveChromeArgs(): Promise<string[]>;
+/**
+ * Dynamic import wrapper isolated so unit tests can stub the module without
+ * jest-style module mocking gymnastics. The narrow type here pins the
+ * subset of `@sparticuz/chromium`'s surface this package depends on; if
+ * the upstream module ever changes shape the type error here surfaces
+ * before runtime.
+ */
+interface SparticuzChromiumModule {
+    args: string[];
+    executablePath(): Promise<string>;
+}
+/** Test-only seam: replace the cached `@sparticuz/chromium` module. */
+export declare function _setSparticuzChromiumForTests(mod: SparticuzChromiumModule | null): void;
+export {};
+//# sourceMappingURL=chromium.d.ts.map