@hyperframes/aws-lambda 0.6.20

package/dist/index.js

@@ -0,0 +1,951 @@
+// src/handler.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, mkdtempSync, readFileSync, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join as join2 } from "node:path";
+import { S3Client } from "@aws-sdk/client-s3";
+import {
+  assemble,
+  plan,
+  renderChunk
+} from "@hyperframes/producer/distributed";
+
+// src/chromium.ts
+import { existsSync } from "node:fs";
+function resolveChromeSource() {
+  const raw = process.env.HYPERFRAMES_LAMBDA_CHROME_SOURCE?.toLowerCase();
+  if (raw === "chrome-headless-shell" || raw === "shell") return "chrome-headless-shell";
+  return "sparticuz";
+}
+async function resolveChromeExecutablePath() {
+  const source = resolveChromeSource();
+  if (source === "sparticuz") {
+    const mod = await loadSparticuzChromium();
+    return mod.executablePath();
+  }
+  const explicit = process.env.HYPERFRAMES_LAMBDA_CHROME_PATH;
+  if (!explicit) {
+    throw new Error(
+      "[chromium] HYPERFRAMES_LAMBDA_CHROME_SOURCE=chrome-headless-shell requires HYPERFRAMES_LAMBDA_CHROME_PATH to be set to the absolute path of the bundled binary."
+    );
+  }
+  if (!existsSync(explicit)) {
+    throw new Error(
+      `[chromium] HYPERFRAMES_LAMBDA_CHROME_PATH=${JSON.stringify(explicit)} does not exist`
+    );
+  }
+  return explicit;
+}
+async function resolveChromeArgs() {
+  if (resolveChromeSource() !== "sparticuz") return [];
+  const mod = await loadSparticuzChromium();
+  return mod.args;
+}
+var cachedSparticuz = null;
+async function loadSparticuzChromium() {
+  if (cachedSparticuz) return cachedSparticuz;
+  const mod = await import("@sparticuz/chromium");
+  const resolved = "default" in mod ? mod.default : mod;
+  cachedSparticuz = resolved;
+  return resolved;
+}
+
+// src/formatExtension.ts
+function formatExtension(format) {
+  switch (format) {
+    case "mp4":
+      return ".mp4";
+    case "mov":
+      return ".mov";
+    case "png-sequence":
+      return "";
+    default: {
+      const _exhaustive = format;
+      throw new Error(`[formatExtension] unsupported format: ${_exhaustive}`);
+    }
+  }
+}
+
+// src/s3Transport.ts
+import {
+  createReadStream,
+  createWriteStream,
+  existsSync as existsSync2,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  statSync
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { GetObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
+import * as tar from "tar";
+function parseS3Uri(uri) {
+  if (!uri.startsWith("s3://")) {
+    throw new Error(`[s3Transport] expected s3:// URI, got: ${JSON.stringify(uri)}`);
+  }
+  const rest = uri.slice("s3://".length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) {
+    throw new Error(`[s3Transport] missing key in s3 URI: ${JSON.stringify(uri)}`);
+  }
+  const bucket = rest.slice(0, slash);
+  const key = rest.slice(slash + 1);
+  if (!bucket || !key) {
+    throw new Error(`[s3Transport] empty bucket or key in s3 URI: ${JSON.stringify(uri)}`);
+  }
+  return { bucket, key };
+}
+function formatS3Uri(loc) {
+  return `s3://${loc.bucket}/${loc.key}`;
+}
+async function downloadS3ObjectToFile(client, uri, destPath) {
+  const { bucket, key } = parseS3Uri(uri);
+  const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+  const body = response.Body;
+  if (!body) {
+    throw new Error(`[s3Transport] s3 GetObject returned empty body for ${uri}`);
+  }
+  mkdirSync(dirname(destPath), { recursive: true });
+  await pipeline(body, createWriteStream(destPath));
+}
+async function uploadFileToS3(client, localPath, uri, contentType) {
+  if (!existsSync2(localPath)) {
+    throw new Error(`[s3Transport] upload source missing: ${localPath}`);
+  }
+  const { bucket, key } = parseS3Uri(uri);
+  const size = statSync(localPath).size;
+  await client.send(
+    new PutObjectCommand({
+      Bucket: bucket,
+      Key: key,
+      Body: createReadStream(localPath),
+      ContentType: contentType,
+      ContentLength: size
+    })
+  );
+}
+async function tarDirectory(sourceDir, destTarball) {
+  if (!existsSync2(sourceDir) || !statSync(sourceDir).isDirectory()) {
+    throw new Error(`[s3Transport] tar source must be an existing directory: ${sourceDir}`);
+  }
+  mkdirSync(dirname(destTarball), { recursive: true });
+  await tar.create({ gzip: true, file: destTarball, cwd: sourceDir }, ["."]);
+}
+async function untarDirectory(tarballPath, destDir) {
+  if (!existsSync2(tarballPath)) {
+    throw new Error(`[s3Transport] tarball missing: ${tarballPath}`);
+  }
+  if (existsSync2(destDir)) {
+    rmSync(destDir, { recursive: true, force: true });
+  }
+  mkdirSync(destDir, { recursive: true });
+  await tar.extract({ file: tarballPath, cwd: destDir });
+}
+
+// src/handler.ts
+var cachedS3Client = null;
+function getS3Client() {
+  if (cachedS3Client) return cachedS3Client;
+  cachedS3Client = new S3Client({});
+  return cachedS3Client;
+}
+async function handler(event, deps) {
+  const unwrapped = unwrapEvent(event);
+  primeRuntimeEnv();
+  logEvent({ event: "handler_start", action: unwrapped.Action, input: summarizeEvent(unwrapped) });
+  try {
+    switch (unwrapped.Action) {
+      case "plan":
+        return await handlePlan(unwrapped, deps);
+      case "renderChunk":
+        return await handleRenderChunk(unwrapped, deps);
+      case "assemble":
+        return await handleAssemble(unwrapped, deps);
+      default: {
+        const _exhaustive = unwrapped;
+        throw new Error(
+          `[handler] unknown Action: ${JSON.stringify(
+            _exhaustive.Action
+          )}. Expected one of "plan", "renderChunk", "assemble".`
+        );
+      }
+    }
+  } catch (err) {
+    logEvent({
+      event: "handler_error",
+      action: unwrapped.Action,
+      message: err instanceof Error ? err.message : String(err),
+      name: err instanceof Error ? err.name : void 0
+    });
+    throw err;
+  }
+}
+var MAX_ENVELOPE_DEPTH = 4;
+function unwrapEvent(event) {
+  let cursor = event;
+  for (let i = 0; i < MAX_ENVELOPE_DEPTH; i++) {
+    if (cursor && typeof cursor === "object") {
+      const obj = cursor;
+      if (typeof obj.Action === "string" && isLambdaAction(obj.Action)) {
+        return cursor;
+      }
+      if ("Payload" in obj) {
+        cursor = obj.Payload;
+        continue;
+      }
+      if ("Input" in obj) {
+        cursor = obj.Input;
+        continue;
+      }
+    }
+    break;
+  }
+  throw new Error(
+    `[handler] event has no recognised Action; unwrapped ${MAX_ENVELOPE_DEPTH} levels of Payload/Input without finding one.`
+  );
+}
+function isLambdaAction(value) {
+  return value === "plan" || value === "renderChunk" || value === "assemble";
+}
+function logEvent(payload) {
+  console.log(JSON.stringify(payload));
+}
+function summarizeEvent(event) {
+  switch (event.Action) {
+    case "plan":
+      return {
+        projectS3Uri: event.ProjectS3Uri,
+        planOutputS3Prefix: event.PlanOutputS3Prefix,
+        format: event.Config.format,
+        fps: event.Config.fps
+      };
+    case "renderChunk":
+      return {
+        planS3Uri: event.PlanS3Uri,
+        chunkIndex: event.ChunkIndex,
+        format: event.Format
+      };
+    case "assemble":
+      return {
+        planS3Uri: event.PlanS3Uri,
+        chunkCount: event.ChunkS3Uris.length,
+        hasAudio: event.AudioS3Uri !== null,
+        outputS3Uri: event.OutputS3Uri,
+        format: event.Format
+      };
+  }
+}
+var runtimeEnvPrimed = false;
+function primeRuntimeEnv() {
+  if (runtimeEnvPrimed) return;
+  runtimeEnvPrimed = true;
+  const taskRoot = process.env.LAMBDA_TASK_ROOT ?? "/var/task";
+  const bin = join2(taskRoot, "bin");
+  if (existsSync3(bin)) {
+    process.env.PATH = `${bin}:${process.env.PATH ?? ""}`;
+  }
+}
+async function handlePlan(event, deps) {
+  const started = Date.now();
+  const s3 = deps?.s3 ?? getS3Client();
+  const primitive = deps?.primitives?.plan ?? plan;
+  const work = mkdtempSync(join2(deps?.tmpRoot ?? tmpdir(), "hf-lambda-plan-"));
+  const projectArchive = join2(work, "project.tar.gz");
+  const projectDir = join2(work, "project");
+  const planDir = join2(work, "plan");
+  try {
+    await downloadS3ObjectToFile(s3, event.ProjectS3Uri, projectArchive);
+    await untarDirectory(projectArchive, projectDir);
+    const config = {
+      ...event.Config
+    };
+    const result = await primitive(projectDir, config, planDir);
+    const planTar = join2(work, "plan.tar.gz");
+    await tarDirectory(planDir, planTar);
+    const planTarUri = `${trimTrailingSlash(event.PlanOutputS3Prefix)}/plan.tar.gz`;
+    const audioPath = join2(planDir, "audio.aac");
+    const hasAudio = existsSync3(audioPath) && statSync2(audioPath).size > 0;
+    const audioUri = hasAudio ? `${trimTrailingSlash(event.PlanOutputS3Prefix)}/audio.aac` : null;
+    await Promise.all([
+      uploadFileToS3(s3, planTar, planTarUri, "application/gzip"),
+      hasAudio && audioUri ? uploadFileToS3(s3, audioPath, audioUri, "audio/aac") : null
+    ]);
+    return {
+      Action: "plan",
+      PlanS3Uri: planTarUri,
+      PlanHash: result.planHash,
+      ChunkCount: result.chunkCount,
+      TotalFrames: result.totalFrames,
+      Fps: result.fps,
+      Width: result.width,
+      Height: result.height,
+      Format: result.format,
+      HasAudio: audioUri !== null,
+      AudioS3Uri: audioUri,
+      FfmpegVersion: result.ffmpegVersion,
+      ProducerVersion: result.producerVersion,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function handleRenderChunk(event, deps) {
+  const started = Date.now();
+  const s3 = deps?.s3 ?? getS3Client();
+  const primitive = deps?.primitives?.renderChunk ?? renderChunk;
+  if (!deps?.skipChromeResolution && !process.env.PRODUCER_HEADLESS_SHELL_PATH) {
+    const chromePath = await resolveChromeExecutablePath();
+    process.env.PRODUCER_HEADLESS_SHELL_PATH = chromePath;
+  }
+  const work = mkdtempSync(join2(deps?.tmpRoot ?? tmpdir(), "hf-lambda-chunk-"));
+  const planTar = join2(work, "plan.tar.gz");
+  const planDir = join2(work, "plan");
+  try {
+    await downloadS3ObjectToFile(s3, event.PlanS3Uri, planTar);
+    await untarDirectory(planTar, planDir);
+    verifyPlanHash(planDir, event.PlanHash);
+    const chunkOutputBase = join2(
+      work,
+      event.Format === "png-sequence" ? `chunk-${pad(event.ChunkIndex)}` : `chunk-${pad(event.ChunkIndex)}${formatExtension(event.Format)}`
+    );
+    const result = await primitive(planDir, event.ChunkIndex, chunkOutputBase);
+    const chunkUri = await uploadChunkOutput(
+      s3,
+      result,
+      event.ChunkOutputS3Prefix,
+      event.ChunkIndex
+    );
+    return {
+      Action: "renderChunk",
+      ChunkS3Uri: chunkUri,
+      ChunkIndex: event.ChunkIndex,
+      Sha256: result.sha256,
+      FramesEncoded: result.framesEncoded,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function uploadChunkOutput(s3, result, prefix, chunkIndex) {
+  const trimmed = trimTrailingSlash(prefix);
+  if (result.outputKind === "file") {
+    const ext = result.outputPath.slice(result.outputPath.lastIndexOf("."));
+    const uri2 = `${trimmed}/chunks/${pad(chunkIndex)}${ext}`;
+    await uploadFileToS3(s3, result.outputPath, uri2);
+    return uri2;
+  }
+  const tarball = `${result.outputPath}.tar.gz`;
+  await tarDirectory(result.outputPath, tarball);
+  const uri = `${trimmed}/chunks/${pad(chunkIndex)}.tar.gz`;
+  await uploadFileToS3(s3, tarball, uri, "application/gzip");
+  return uri;
+}
+async function handleAssemble(event, deps) {
+  const started = Date.now();
+  const s3 = deps?.s3 ?? getS3Client();
+  const primitive = deps?.primitives?.assemble ?? assemble;
+  const work = mkdtempSync(join2(deps?.tmpRoot ?? tmpdir(), "hf-lambda-assemble-"));
+  const planTar = join2(work, "plan.tar.gz");
+  const planDir = join2(work, "plan");
+  try {
+    await downloadS3ObjectToFile(s3, event.PlanS3Uri, planTar);
+    await untarDirectory(planTar, planDir);
+    const chunkPaths = await downloadChunkObjects(s3, event.ChunkS3Uris, work, event.Format);
+    let audioPath = null;
+    if (event.AudioS3Uri) {
+      audioPath = join2(planDir, "audio.aac");
+      await downloadS3ObjectToFile(s3, event.AudioS3Uri, audioPath);
+    }
+    const finalOutput = event.Format === "png-sequence" ? join2(work, "output-frames") : join2(work, `output${formatExtension(event.Format)}`);
+    const result = await primitive(planDir, chunkPaths, audioPath, finalOutput);
+    if (event.Format === "png-sequence") {
+      const tarball = `${finalOutput}.tar.gz`;
+      await tarDirectory(finalOutput, tarball);
+      await uploadFileToS3(s3, tarball, event.OutputS3Uri, "application/gzip");
+    } else {
+      await uploadFileToS3(s3, finalOutput, event.OutputS3Uri);
+    }
+    return {
+      Action: "assemble",
+      OutputS3Uri: event.OutputS3Uri,
+      FramesEncoded: result.framesEncoded,
+      FileSize: result.fileSize,
+      DurationMs: Date.now() - started
+    };
+  } finally {
+    cleanupDir(work);
+  }
+}
+async function downloadChunkObjects(s3, uris, workDir, format) {
+  const chunksDir = join2(workDir, "chunks");
+  mkdirSync2(chunksDir, { recursive: true });
+  const local = new Array(uris.length);
+  await Promise.all(
+    uris.map(async (uri, i) => {
+      if (!uri) {
+        throw new Error(`[handler] chunk URI at index ${i} is empty`);
+      }
+      const { key } = parseS3Uri(uri);
+      const localPath = join2(chunksDir, basename(key));
+      await downloadS3ObjectToFile(s3, uri, localPath);
+      if (format === "png-sequence") {
+        const dirPath = join2(chunksDir, `frames-${pad(i)}`);
+        await untarDirectory(localPath, dirPath);
+        local[i] = dirPath;
+      } else {
+        local[i] = localPath;
+      }
+    })
+  );
+  return local;
+}
+function pad(n) {
+  return n.toString().padStart(4, "0");
+}
+function trimTrailingSlash(prefix) {
+  return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+}
+function cleanupDir(dir) {
+  try {
+    rmSync2(dir, { recursive: true, force: true });
+  } catch {
+  }
+}
+function verifyPlanHash(planDir, expected) {
+  const planJsonPath = join2(planDir, "plan.json");
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(planJsonPath, "utf-8"));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const error = new Error(`PLAN_HASH_MISMATCH: failed to read ${planJsonPath}: ${msg}`);
+    error.name = "PLAN_HASH_MISMATCH";
+    throw error;
+  }
+  const actual = parsed.planHash;
+  if (typeof actual !== "string" || actual !== expected) {
+    const error = new Error(
+      `PLAN_HASH_MISMATCH: event PlanHash=${expected} did not match plan.json planHash=${String(actual)}`
+    );
+    error.name = "PLAN_HASH_MISMATCH";
+    throw error;
+  }
+}
+
+// src/sdk/deploySite.ts
+import { mkdtempSync as mkdtempSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, rmSync as rmSync3, statSync as statSync3 } from "node:fs";
+import { createHash } from "node:crypto";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join3, relative } from "node:path";
+import { HeadObjectCommand, S3Client as S3Client2 } from "@aws-sdk/client-s3";
+import { PLAN_PROJECT_DIR_SKIP_SEGMENTS } from "@hyperframes/producer/distributed";
+async function deploySite(opts) {
+  if (!statSync3(opts.projectDir).isDirectory()) {
+    throw new Error(`[deploySite] projectDir is not a directory: ${opts.projectDir}`);
+  }
+  const siteId = opts.siteId ?? hashProjectDir(opts.projectDir);
+  const key = `sites/${siteId}/project.tar.gz`;
+  const projectS3Uri = formatS3Uri({ bucket: opts.bucketName, key });
+  const s3 = opts.s3 ?? new S3Client2({ region: opts.region });
+  const existing = await headObject(s3, opts.bucketName, key);
+  if (existing) {
+    return {
+      siteId,
+      bucketName: opts.bucketName,
+      projectS3Uri,
+      bytes: existing.bytes,
+      uploadedAt: existing.lastModified,
+      uploaded: false
+    };
+  }
+  const workdir = mkdtempSync2(join3(tmpdir2(), "hf-deploy-site-"));
+  try {
+    const tarball = join3(workdir, "project.tar.gz");
+    await tarDirectory(opts.projectDir, tarball);
+    const size = statSync3(tarball).size;
+    await uploadFileToS3(s3, tarball, projectS3Uri, "application/gzip");
+    return {
+      siteId,
+      bucketName: opts.bucketName,
+      projectS3Uri,
+      bytes: size,
+      uploadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      uploaded: true
+    };
+  } finally {
+    rmSync3(workdir, { recursive: true, force: true });
+  }
+}
+function hashProjectDir(projectDir) {
+  const hash = createHash("sha256");
+  const files = [];
+  function walk(dir, isRoot) {
+    for (const entry of readdirSync2(dir, { withFileTypes: true }).sort(
+      (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+    )) {
+      if (isRoot && PLAN_PROJECT_DIR_SKIP_SEGMENTS.has(entry.name)) continue;
+      const full = join3(dir, entry.name);
+      if (entry.isDirectory()) walk(full, false);
+      else if (entry.isFile()) files.push(full);
+    }
+  }
+  walk(projectDir, true);
+  for (const file of files) {
+    const rel = relative(projectDir, file).replaceAll("\\", "/");
+    hash.update(rel);
+    hash.update("\0");
+    hash.update(readFileSync2(file));
+  }
+  return hash.digest("hex").slice(0, 16);
+}
+async function headObject(s3, bucket, key) {
+  try {
+    const res = await s3.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
+    return {
+      bytes: typeof res.ContentLength === "number" ? res.ContentLength : 0,
+      lastModified: res.LastModified instanceof Date ? res.LastModified.toISOString() : (/* @__PURE__ */ new Date()).toISOString()
+    };
+  } catch (err) {
+    const status = err.$metadata?.httpStatusCode;
+    if (status === 404) return null;
+    const name = err.name;
+    if (name === "NotFound" || name === "NoSuchKey") return null;
+    throw err;
+  }
+}
+
+// src/sdk/renderToLambda.ts
+import { randomUUID } from "node:crypto";
+import { SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
+
+// src/sdk/validateConfig.ts
+var InvalidConfigError = class extends Error {
+  name = "InvalidConfigError";
+  /** Dotted JSON-pointer-ish path to the offending field, e.g. `config.fps`. */
+  field;
+  constructor(field, message) {
+    super(`[validateConfig] ${field}: ${message}`);
+    this.field = field;
+  }
+};
+var ALLOWED_FPS = [24, 30, 60];
+var ALLOWED_FORMATS = ["mp4", "mov", "png-sequence"];
+var ALLOWED_CODECS = ["h264", "h265"];
+var ALLOWED_QUALITIES = ["draft", "standard", "high"];
+var ALLOWED_RUNTIME_CAPS = ["lambda", "temporal", "cloud-run-job", "k8s-job", "none"];
+var ALLOWED_HDR_MODES = ["auto", "force-sdr"];
+var MAX_DIMENSION = 7680;
+var MIN_DIMENSION = 16;
+var MAX_CHUNK_SIZE = 3600;
+var MAX_PARALLEL_CHUNKS_CEILING = 256;
+function validateDistributedRenderConfig(config) {
+  if (config === null || typeof config !== "object") {
+    throw new InvalidConfigError("config", "must be an object");
+  }
+  if (!ALLOWED_FPS.includes(config.fps)) {
+    throw new InvalidConfigError(
+      "config.fps",
+      `must be one of ${ALLOWED_FPS.join(", ")}; got ${String(config.fps)}`
+    );
+  }
+  validateIntDimension("config.width", config.width);
+  validateIntDimension("config.height", config.height);
+  if (!ALLOWED_FORMATS.includes(config.format)) {
+    throw new InvalidConfigError(
+      "config.format",
+      `must be one of ${ALLOWED_FORMATS.join(", ")}; got ${String(config.format)}`
+    );
+  }
+  if (config.codec !== void 0) {
+    if (config.format !== "mp4") {
+      throw new InvalidConfigError(
+        "config.codec",
+        `is only valid with format="mp4"; got format=${String(config.format)}`
+      );
+    }
+    if (!ALLOWED_CODECS.includes(config.codec)) {
+      throw new InvalidConfigError(
+        "config.codec",
+        `must be one of ${ALLOWED_CODECS.join(", ")}; got ${String(config.codec)}`
+      );
+    }
+  }
+  if (config.quality !== void 0 && !ALLOWED_QUALITIES.includes(config.quality)) {
+    throw new InvalidConfigError(
+      "config.quality",
+      `must be one of ${ALLOWED_QUALITIES.join(", ")}; got ${String(config.quality)}`
+    );
+  }
+  if (config.crf !== void 0 && config.bitrate !== void 0) {
+    throw new InvalidConfigError("config.crf", "is mutually exclusive with config.bitrate");
+  }
+  if (config.crf !== void 0 && (!Number.isInteger(config.crf) || config.crf < 0 || config.crf > 51)) {
+    throw new InvalidConfigError("config.crf", `must be an integer in [0, 51]; got ${config.crf}`);
+  }
+  if (config.bitrate !== void 0 && !/^\d+(\.\d+)?[kKmM]?$/.test(config.bitrate)) {
+    throw new InvalidConfigError(
+      "config.bitrate",
+      `must look like "10M" or "5000k"; got ${JSON.stringify(config.bitrate)}`
+    );
+  }
+  if (config.chunkSize !== void 0) {
+    if (!Number.isInteger(config.chunkSize) || config.chunkSize < 1) {
+      throw new InvalidConfigError(
+        "config.chunkSize",
+        `must be a positive integer; got ${config.chunkSize}`
+      );
+    }
+    if (config.chunkSize > MAX_CHUNK_SIZE) {
+      throw new InvalidConfigError(
+        "config.chunkSize",
+        // Lambda 15-min cap leaves no useful headroom past ~3600 frames
+        // at 4 fps capture-equivalent throughput; rejecting up front
+        // avoids a 14-minute Plan-state retry storm.
+        `must be \u2264 ${MAX_CHUNK_SIZE} (Lambda 15-min cap); got ${config.chunkSize}`
+      );
+    }
+  }
+  if (config.maxParallelChunks !== void 0) {
+    if (!Number.isInteger(config.maxParallelChunks) || config.maxParallelChunks < 1) {
+      throw new InvalidConfigError(
+        "config.maxParallelChunks",
+        `must be a positive integer; got ${config.maxParallelChunks}`
+      );
+    }
+    if (config.maxParallelChunks > MAX_PARALLEL_CHUNKS_CEILING) {
+      throw new InvalidConfigError(
+        "config.maxParallelChunks",
+        `must be \u2264 ${MAX_PARALLEL_CHUNKS_CEILING}; got ${config.maxParallelChunks}`
+      );
+    }
+  }
+  if (config.runtimeCap !== void 0 && !ALLOWED_RUNTIME_CAPS.includes(config.runtimeCap)) {
+    throw new InvalidConfigError(
+      "config.runtimeCap",
+      `must be one of ${ALLOWED_RUNTIME_CAPS.join(", ")}; got ${String(config.runtimeCap)}`
+    );
+  }
+  if (config.hdrMode !== void 0 && !ALLOWED_HDR_MODES.includes(config.hdrMode)) {
+    throw new InvalidConfigError(
+      "config.hdrMode",
+      `distributed mode supports only ${ALLOWED_HDR_MODES.join(", ")}; got ${String(config.hdrMode)}`
+    );
+  }
+  return config;
+}
+function validateIntDimension(field, value) {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new InvalidConfigError(field, `must be an integer; got ${String(value)}`);
+  }
+  if (value < MIN_DIMENSION || value > MAX_DIMENSION) {
+    throw new InvalidConfigError(
+      field,
+      `must be in [${MIN_DIMENSION}, ${MAX_DIMENSION}]; got ${value}`
+    );
+  }
+  if (value % 2 !== 0) {
+    throw new InvalidConfigError(field, `must be even (yuv420p constraint); got ${value}`);
+  }
+}
+
+// src/sdk/renderToLambda.ts
+async function renderToLambda(opts) {
+  validateDistributedRenderConfig(opts.config);
+  if (!opts.bucketName) {
+    throw new Error("[renderToLambda] bucketName is required");
+  }
+  if (!opts.stateMachineArn) {
+    throw new Error("[renderToLambda] stateMachineArn is required");
+  }
+  if (!opts.siteHandle && !opts.projectDir) {
+    throw new Error("[renderToLambda] either siteHandle or projectDir must be supplied");
+  }
+  const executionName = opts.executionName ?? `hf-render-${randomUUID()}`;
+  const ext = formatExtension(opts.config.format);
+  const outputKey = opts.outputKey ?? `renders/${executionName}/output${ext}`;
+  const planOutputS3Prefix = formatS3Uri({
+    bucket: opts.bucketName,
+    key: `renders/${executionName}/`
+  });
+  const outputS3Uri = formatS3Uri({ bucket: opts.bucketName, key: outputKey });
+  const site = opts.siteHandle ?? await deploySite({
+    projectDir: opts.projectDir,
+    bucketName: opts.bucketName,
+    region: opts.region,
+    s3: opts.s3
+  });
+  const input = {
+    ProjectS3Uri: site.projectS3Uri,
+    PlanOutputS3Prefix: planOutputS3Prefix,
+    OutputS3Uri: outputS3Uri,
+    Config: opts.config
+  };
+  const sfn = opts.sfn ?? new SFNClient({ region: opts.region });
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const response = await sfn.send(
+    new StartExecutionCommand({
+      stateMachineArn: opts.stateMachineArn,
+      name: executionName,
+      input: JSON.stringify(input)
+    })
+  );
+  if (!response.executionArn) {
+    throw new Error("[renderToLambda] StartExecution returned no executionArn");
+  }
+  return {
+    renderId: executionName,
+    executionArn: response.executionArn,
+    bucketName: opts.bucketName,
+    stateMachineArn: opts.stateMachineArn,
+    outputS3Uri,
+    projectS3Uri: site.projectS3Uri,
+    startedAt
+  };
+}
+
+// src/sdk/getRenderProgress.ts
+import {
+  DescribeExecutionCommand,
+  GetExecutionHistoryCommand,
+  SFNClient as SFNClient2
+} from "@aws-sdk/client-sfn";
+
+// src/sdk/costAccounting.ts
+var LAMBDA_USD_PER_GB_SECOND = 166667e-10;
+var SFN_USD_PER_TRANSITION = 25e-6;
+function computeRenderCost(lambdaInvocations, stateTransitions) {
+  let lambdaUsd = 0;
+  let anyEstimated = false;
+  for (const inv of lambdaInvocations) {
+    const gbSeconds = inv.memorySizeMb / 1024 * (inv.billedDurationMs / 1e3);
+    lambdaUsd += gbSeconds * LAMBDA_USD_PER_GB_SECOND;
+    if (inv.estimated) anyEstimated = true;
+  }
+  const stepFunctionsUsd = stateTransitions * SFN_USD_PER_TRANSITION;
+  const accruedSoFarUsd = roundUsd(lambdaUsd + stepFunctionsUsd);
+  return {
+    accruedSoFarUsd,
+    displayCost: formatUsd(accruedSoFarUsd),
+    breakdown: {
+      lambdaUsd: roundUsd(lambdaUsd),
+      stepFunctionsUsd: roundUsd(stepFunctionsUsd),
+      s3Estimate: "not-included",
+      estimated: anyEstimated
+    }
+  };
+}
+function roundUsd(usd) {
+  return Math.round(usd * 1e4) / 1e4;
+}
+function formatUsd(usd) {
+  return `$${usd.toFixed(4)}`;
+}
+
+// src/sdk/getRenderProgress.ts
+var DEFAULT_MEMORY_MB = 10240;
+async function getRenderProgress(opts) {
+  if (!opts.executionArn) {
+    throw new Error("[getRenderProgress] executionArn is required");
+  }
+  const sfn = opts.sfn ?? new SFNClient2({ region: opts.region });
+  const memoryMb = opts.defaultMemorySizeMb ?? DEFAULT_MEMORY_MB;
+  const describe = await sfn.send(
+    new DescribeExecutionCommand({ executionArn: opts.executionArn })
+  );
+  const status = describe.status ?? "RUNNING";
+  const startedAt = describe.startDate?.toISOString() ?? (/* @__PURE__ */ new Date(0)).toISOString();
+  const endedAt = describe.stopDate?.toISOString() ?? null;
+  const history = await loadFullHistory(sfn, opts.executionArn);
+  const summary = summarizeHistory(history, memoryMb);
+  const costs = computeRenderCost(summary.lambdaInvocations, summary.stateTransitions);
+  const overallProgress = computeOverallProgress({
+    status,
+    totalFrames: summary.totalFrames,
+    framesRendered: summary.framesRendered,
+    assembleComplete: summary.assembleComplete
+  });
+  return {
+    status,
+    overallProgress,
+    framesRendered: summary.framesRendered,
+    totalFrames: summary.totalFrames,
+    lambdasInvoked: summary.lambdasInvoked,
+    costs,
+    outputFile: summary.outputFile,
+    errors: summary.errors,
+    fatalErrorEncountered: isTerminalFailure(status),
+    startedAt,
+    endedAt
+  };
+}
+async function loadFullHistory(sfn, executionArn) {
+  const events = [];
+  let nextToken;
+  for (let page = 0; page < 50; page++) {
+    const res = await sfn.send(
+      new GetExecutionHistoryCommand({
+        executionArn,
+        maxResults: 1e3,
+        nextToken,
+        reverseOrder: false
+      })
+    );
+    if (res.events) events.push(...res.events);
+    nextToken = res.nextToken;
+    if (!nextToken) break;
+  }
+  return events;
+}
+function summarizeHistory(events, memoryMb) {
+  let framesRendered = 0;
+  let totalFrames = null;
+  let lambdasInvoked = 0;
+  let assembleComplete = false;
+  let outputFile = null;
+  let stateTransitions = 0;
+  const errors = [];
+  const lambdaInvocations = [];
+  let currentLambdaState = null;
+  for (const ev of events) {
+    switch (ev.type) {
+      case "TaskStateEntered":
+      case "MapStateEntered":
+      case "PassStateEntered":
+      case "ChoiceStateEntered":
+      case "SucceedStateEntered":
+      case "FailStateEntered":
+      case "WaitStateEntered":
+      case "ParallelStateEntered":
+        stateTransitions++;
+        currentLambdaState = ev.stateEnteredEventDetails?.name ?? currentLambdaState;
+        break;
+      case "LambdaFunctionScheduled":
+        lambdasInvoked++;
+        break;
+      case "LambdaFunctionSucceeded": {
+        const payload = parseJson(ev.lambdaFunctionSucceededEventDetails?.output);
+        const billedDurationMs = inferBilledMs(payload);
+        lambdaInvocations.push({
+          billedDurationMs,
+          memorySizeMb: memoryMb,
+          estimated: billedDurationMs === 0
+        });
+        if (payload && typeof payload === "object") {
+          const obj = payload;
+          if (typeof obj.TotalFrames === "number") totalFrames = obj.TotalFrames;
+          if (typeof obj.FramesEncoded === "number") {
+            if (currentLambdaState === "RenderChunk") {
+              framesRendered += obj.FramesEncoded;
+            }
+          }
+        }
+        break;
+      }
+      case "TaskStateExited":
+      case "MapStateExited":
+        if (ev.stateExitedEventDetails?.name === "Assemble") {
+          assembleComplete = true;
+          const exitPayload = parseJson(ev.stateExitedEventDetails?.output);
+          if (exitPayload && typeof exitPayload === "object") {
+            const obj = exitPayload;
+            const out = obj.Output;
+            const outputS3Uri = typeof out?.OutputS3Uri === "string" ? out.OutputS3Uri : null;
+            const bytes = typeof out?.FileSize === "number" ? out.FileSize : null;
+            outputFile = outputS3Uri ? { s3Uri: outputS3Uri, bytes } : outputFile;
+          }
+        }
+        break;
+      case "LambdaFunctionFailed":
+        errors.push({
+          state: currentLambdaState ?? "<unknown>",
+          error: ev.lambdaFunctionFailedEventDetails?.error ?? "UNKNOWN",
+          cause: ev.lambdaFunctionFailedEventDetails?.cause ?? ""
+        });
+        break;
+      case "ExecutionFailed":
+        errors.push({
+          state: "<execution>",
+          error: ev.executionFailedEventDetails?.error ?? "UNKNOWN",
+          cause: ev.executionFailedEventDetails?.cause ?? ""
+        });
+        break;
+      case "ExecutionAborted":
+        errors.push({
+          state: "<execution>",
+          error: ev.executionAbortedEventDetails?.error ?? "ABORTED",
+          cause: ev.executionAbortedEventDetails?.cause ?? ""
+        });
+        break;
+      case "ExecutionTimedOut":
+        errors.push({
+          state: "<execution>",
+          error: "TIMEOUT",
+          cause: ev.executionTimedOutEventDetails?.cause ?? ""
+        });
+        break;
+      default:
+        break;
+    }
+  }
+  return {
+    lambdaInvocations,
+    stateTransitions,
+    framesRendered,
+    totalFrames,
+    lambdasInvoked,
+    assembleComplete,
+    outputFile,
+    errors
+  };
+}
+function parseJson(s) {
+  if (!s) return null;
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+function inferBilledMs(payload) {
+  if (!payload || typeof payload !== "object") return 0;
+  const obj = payload;
+  if (typeof obj.DurationMs === "number") return obj.DurationMs;
+  return 0;
+}
+function computeOverallProgress({
+  status,
+  totalFrames,
+  framesRendered,
+  assembleComplete
+}) {
+  if (status === "SUCCEEDED") return 1;
+  if (assembleComplete) return 1;
+  if (totalFrames === null) return 0;
+  const chunkProgress = Math.min(1, framesRendered / totalFrames);
+  return 0.1 + 0.8 * chunkProgress;
+}
+function isTerminalFailure(status) {
+  return status === "FAILED" || status === "TIMED_OUT" || status === "ABORTED";
+}
+export {
+  InvalidConfigError,
+  computeRenderCost,
+  deploySite,
+  downloadS3ObjectToFile,
+  formatS3Uri,
+  getRenderProgress,
+  handler,
+  parseS3Uri,
+  renderToLambda,
+  resolveChromeArgs,
+  resolveChromeExecutablePath,
+  resolveChromeSource,
+  tarDirectory,
+  untarDirectory,
+  unwrapEvent,
+  uploadFileToS3,
+  validateDistributedRenderConfig
+};
+//# sourceMappingURL=index.js.map