feat(lambda): add TypeScript SDK and CDK construct (#909)

* feat(lambda): add TypeScript SDK and CDK construct

Adds the client-side surface on top of the Phase 6a Lambda handler so
adopters can drive a deployed stack from Node without writing AWS-SDK
boilerplate:

- renderToLambda(opts) starts a Step Functions execution and returns a
  handle. Does NOT poll.
- getRenderProgress({ executionArn }) returns a snapshot of progress,
  frames rendered, cost (Lambda GB-seconds + SFN transitions), errors,
  and the final output object once Assemble completes.
- deploySite({ projectDir, bucketName }) content-addresses the project
  tree, tar.gzs it, and uploads to S3 with a HeadObject short-circuit so
  re-renders of the same tree skip the tar+PUT.
- validateDistributedRenderConfig throws a typed InvalidConfigError
  before StartExecution, so shape errors surface synchronously.
- computeRenderCost is exposed for callers who want to format cost out
  of band.

Also ships HyperframesRenderStack, an aws-cdk-lib L2 construct that
emits the same topology as examples/aws-lambda/template.yaml. Lives on
the ./cdk subpath export so SDK-only consumers don't pull aws-cdk-lib
into their runtime graph (declared as an optional peer dependency).

Tests: 24 new unit tests across the SDK plus 9 CDK synth / contract /
snapshot tests. All 83 tests in packages/aws-lambda/src pass.

* refactor(lambda): /simplify pass on the SDK + CDK PR

Pulls shared logic out so the SDK doesn't re-invent things the handler
and the producer already have:

- `formatExtension` extracted to packages/aws-lambda/src/formatExtension.ts.
  handler.ts and renderToLambda.ts both used identical 12-line copies of
  this switch.
- `PLAN_PROJECT_DIR_SKIP_SEGMENTS` is now exported from
  @hyperframes/producer/distributed. deploySite consumes it instead of
  its own duplicate SKIP_TOP_LEVEL set; the two lists were trivially
  identical and would have drifted silently.
- `FakeS3` + `drainBody` factored out of the two SDK test files into
  src/sdk/__fixtures__/fakeS3.ts. Drops ~110 lines of test-file
  duplication and gives future SDK tests a one-line FakeS3 import.
- S3 URI building in deploySite and renderToLambda routes through the
  existing `formatS3Uri` helper instead of inline `s3://...`
  concatenation; matches the convention already in handler.ts.

Net -133 lines across the touched files. All 83 aws-lambda tests still
pass; all 60 producer distributed tests still pass.

* fix(lambda): bump CDK test timeouts for CI cold-start synth

The bun:test default 5s timeout tripped the first CDK snapshot test
in CI when the cold-start `Template.fromStack(stack)` synth took ~5-8s
on the slowest GitHub Actions runner. Locally on a warm shell the
synth measures <1s, so the failure didn't reproduce until PR #909 hit
CI.

Two changes:

  - Both CDK test files cache one synth in `beforeAll(..., 30000)` and
    reuse the result across every test that uses the default props.
    Each individual test now runs in microseconds (pure assertions
    against the already-synthed template), so the 5s timeout no longer
    applies on the hot path.

  - The two contract tests that exercise non-default props
    (reservedConcurrency, projectName) still synth fresh per-test; they
    get a per-test `it(..., 30000)` timeout.

No behavior changes.

* fix(lambda): address PR review on SDK + CDK construct

Three correctness + ergonomics fixes raised in Vai's review:

  - getRenderProgress over-counted SFN transitions by 3-5×. Step
    Functions Standard Workflows bill per state-entry, not per
    history event. Each Task produces ~5-7 history events
    (Scheduled / Started / Succeeded / TaskStateExited / …);
    counting `events.length` reported the runaway. Switch to
    counting `*StateEntered` events explicitly.

  - assembleComplete + outputFile detection was coupled to the
    Lambda payload's `Action` field. Move both signals onto the
    enclosing state name (`StateExited.name === "Assemble"`), which
    is the state-machine identity rather than the Lambda event
    contract. framesRendered increment moves to the same boundary
    (RenderChunk state).

  - SiteHandle now carries `bucketName` directly so README + CLI
    callers don't have to re-parse `projectS3Uri.split("/")[2]`.

Test updates: getRenderProgress tests wrap renderChunk/assemble
events in matching StateEntered + StateExited pairs so the new
state-name-driven dispatch is exercised end-to-end. SiteHandle
fixture in renderToLambda.test.ts gets the new bucketName field.

All 83 aws-lambda tests still pass.

packages/aws-lambda/src/sdk/renderToLambda.test.ts

@@ -0,0 +1,200 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { SFNClient } from "@aws-sdk/client-sfn";
+import type { SerializableDistributedRenderConfig } from "../events.js";
+import { asS3Client, FakeS3 } from "./__fixtures__/fakeS3.js";
+import type { SiteHandle } from "./deploySite.js";
+import { renderToLambda } from "./renderToLambda.js";
+import { InvalidConfigError } from "./validateConfig.js";
+
+interface CapturedStart {
+  stateMachineArn: string;
+  name: string;
+  input: unknown;
+}
+
+class FakeSFN {
+  starts: CapturedStart[] = [];
+  async send(command: unknown): Promise<unknown> {
+    const cmdName = (command as { constructor: { name: string } }).constructor.name;
+    if (cmdName === "StartExecutionCommand") {
+      const input = (command as { input: { stateMachineArn: string; name: string; input: string } })
+        .input;
+      this.starts.push({
+        stateMachineArn: input.stateMachineArn,
+        name: input.name,
+        input: JSON.parse(input.input),
+      });
+      return {
+        executionArn: `arn:aws:states:us-east-1:1234:execution:hf:${input.name}`,
+        startDate: new Date(),
+      };
+    }
+    throw new Error(`FakeSFN: unexpected command ${cmdName}`);
+  }
+}
+
+function asSFNClient(fake: { send(command: unknown): Promise<unknown> }): SFNClient {
+  return fake as unknown as SFNClient;
+}
+
+const baseConfig: SerializableDistributedRenderConfig = {
+  fps: 30,
+  width: 1280,
+  height: 720,
+  format: "mp4",
+};
+
+let projectDir: string;
+
+beforeEach(() => {
+  projectDir = mkdtempSync(join(tmpdir(), "hf-render-test-"));
+  writeFileSync(join(projectDir, "index.html"), "<html></html>");
+});
+
+afterEach(() => {
+  rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe("renderToLambda", () => {
+  it("returns a handle and starts a state-machine execution with the right input", async () => {
+    const sfn = new FakeSFN();
+    const s3 = new FakeS3();
+    const handle = await renderToLambda({
+      projectDir,
+      bucketName: "test-bucket",
+      stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
+      config: baseConfig,
+      executionName: "smoke-1",
+      sfn: asSFNClient(sfn),
+      s3: asS3Client(s3),
+    });
+
+    expect(handle.renderId).toBe("smoke-1");
+    expect(handle.executionArn).toContain("smoke-1");
+    expect(handle.bucketName).toBe("test-bucket");
+    expect(handle.outputS3Uri).toBe("s3://test-bucket/renders/smoke-1/output.mp4");
+    expect(handle.projectS3Uri).toMatch(
+      /^s3:\/\/test-bucket\/sites\/[0-9a-f]{16}\/project\.tar\.gz$/,
+    );
+
+    expect(sfn.starts).toHaveLength(1);
+    const start = sfn.starts[0]!;
+    expect(start.name).toBe("smoke-1");
+    expect(start.stateMachineArn).toBe("arn:aws:states:us-east-1:1234:stateMachine:hf");
+    expect(start.input).toEqual({
+      ProjectS3Uri: handle.projectS3Uri,
+      PlanOutputS3Prefix: "s3://test-bucket/renders/smoke-1/",
+      OutputS3Uri: "s3://test-bucket/renders/smoke-1/output.mp4",
+      Config: baseConfig,
+    });
+  });
+
+  it("derives the file extension from config.format", async () => {
+    const sfn = new FakeSFN();
+    const s3 = new FakeS3();
+    const handle = await renderToLambda({
+      projectDir,
+      bucketName: "test-bucket",
+      stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
+      config: { ...baseConfig, format: "mov" },
+      executionName: "smoke-mov",
+      sfn: asSFNClient(sfn),
+      s3: asS3Client(s3),
+    });
+    expect(handle.outputS3Uri).toBe("s3://test-bucket/renders/smoke-mov/output.mov");
+  });
+
+  it("reuses a supplied siteHandle (no deploy)", async () => {
+    const sfn = new FakeSFN();
+    const s3 = new FakeS3();
+    const prebuilt: SiteHandle = {
+      siteId: "prebaked",
+      bucketName: "test-bucket",
+      projectS3Uri: "s3://test-bucket/sites/prebaked/project.tar.gz",
+      bytes: 4096,
+      uploadedAt: "2026-05-16T00:00:00Z",
+      uploaded: true,
+    };
+    const handle = await renderToLambda({
+      siteHandle: prebuilt,
+      bucketName: "test-bucket",
+      stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
+      config: baseConfig,
+      executionName: "smoke-reuse",
+      sfn: asSFNClient(sfn),
+      s3: asS3Client(s3),
+    });
+    expect(handle.projectS3Uri).toBe(prebuilt.projectS3Uri);
+    // No HEAD/PUT means s3.existing stayed empty.
+    expect(s3.existing.size).toBe(0);
+  });
+
+  it("rejects invalid configs synchronously before any AWS call", async () => {
+    const sfn = new FakeSFN();
+    const s3 = new FakeS3();
+    try {
+      await renderToLambda({
+        projectDir,
+        bucketName: "test-bucket",
+        stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
+        config: { ...baseConfig, fps: 25 as 24 | 30 | 60 },
+        sfn: asSFNClient(sfn),
+        s3: asS3Client(s3),
+      });
+      throw new Error("expected throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(InvalidConfigError);
+    }
+    expect(sfn.starts).toHaveLength(0);
+  });
+
+  it("requires either siteHandle or projectDir", async () => {
+    const sfn = new FakeSFN();
+    const s3 = new FakeS3();
+    await expect(
+      renderToLambda({
+        bucketName: "test-bucket",
+        stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
+        config: baseConfig,
+        sfn: asSFNClient(sfn),
+        s3: asS3Client(s3),
+      }),
+    ).rejects.toThrow(/either siteHandle or projectDir/);
+  });
+
+  it("auto-generates an executionName when omitted", async () => {
+    const sfn = new FakeSFN();
+    const s3 = new FakeS3();
+    const handle = await renderToLambda({
+      projectDir,
+      bucketName: "test-bucket",
+      stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
+      config: baseConfig,
+      sfn: asSFNClient(sfn),
+      s3: asS3Client(s3),
+    });
+    expect(handle.renderId).toMatch(/^hf-render-[0-9a-f-]{36}$/);
+  });
+
+  it("propagates a missing executionArn as an error", async () => {
+    const sfn = {
+      async send(_cmd: unknown): Promise<unknown> {
+        return { executionArn: undefined };
+      },
+    };
+    const s3 = new FakeS3();
+    await expect(
+      renderToLambda({
+        projectDir,
+        bucketName: "test-bucket",
+        stateMachineArn: "arn:aws:states:us-east-1:1234:stateMachine:hf",
+        config: baseConfig,
+        sfn: asSFNClient(sfn),
+        s3: asS3Client(s3),
+      }),
+    ).rejects.toThrow(/no executionArn/);
+  });
+});