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.ts

@@ -0,0 +1,134 @@
+/**
+ * `renderToLambda` — start a distributed render against an already-deployed
+ * SAM/CDK stack and return a handle the caller can poll with
+ * {@link getRenderProgress}.
+ *
+ * The function does *not* wait for the render to finish. Step Functions
+ * standard workflows can run for hours; blocking the caller's process on
+ * the SFN execution is the wrong default. The returned `RenderHandle`
+ * carries everything the progress / cost / download paths need.
+ *
+ * Wire order:
+ *   1. Validate config (typed throw before any AWS call).
+ *   2. `deploySite` if no `siteHandle` was provided.
+ *   3. `StartExecution` against the state machine with the same input
+ *      shape `examples/aws-lambda/scripts/smoke.sh` builds.
+ *   4. Return handle. The S3 `outputKey` is deterministic from the
+ *      execution name so the caller can predict the final object URL.
+ */
+
+import { randomUUID } from "node:crypto";
+import { SFNClient, StartExecutionCommand } from "@aws-sdk/client-sfn";
+import type { S3Client } from "@aws-sdk/client-s3";
+import type { SerializableDistributedRenderConfig } from "../events.js";
+import { formatExtension } from "../formatExtension.js";
+import { formatS3Uri } from "../s3Transport.js";
+import { deploySite, type SiteHandle } from "./deploySite.js";
+import { validateDistributedRenderConfig } from "./validateConfig.js";
+
+/** Options for {@link renderToLambda}. */
+export interface RenderToLambdaOptions {
+  /** Local project directory. Required when `siteHandle` is not supplied. */
+  projectDir?: string;
+  /** Re-use an existing `deploySite` upload (skips tar+S3 PUT). */
+  siteHandle?: SiteHandle;
+  /** Validated `SerializableDistributedRenderConfig` (no logger / abortSignal). */
+  config: SerializableDistributedRenderConfig;
+  /** S3 bucket from the SAM stack output (`RenderBucketName`). */
+  bucketName: string;
+  /** State machine ARN from the SAM stack output (`RenderStateMachineArn`). */
+  stateMachineArn: string;
+  /** AWS region; defaults to the SDK default chain. */
+  region?: string;
+  /**
+   * Final output S3 key. Defaults to `renders/<executionName>/output.<ext>`
+   * where `<ext>` is derived from `config.format`.
+   */
+  outputKey?: string;
+  /**
+   * Step Functions execution name. Defaults to `hf-render-<uuid>`.
+   * Used as `renderId` everywhere downstream (history queries, cost
+   * accounting, predictable S3 key prefix).
+   */
+  executionName?: string;
+  /** Test injection seam — production callers leave unset. */
+  sfn?: SFNClient;
+  /** Test injection seam — propagated to `deploySite` when applicable. */
+  s3?: S3Client;
+}
+
+/** Stable identifier + every URL/ARN the caller needs to follow the render. */
+export interface RenderHandle {
+  /** Same as the Step Functions execution name. */
+  renderId: string;
+  /** Full execution ARN; pass to {@link getRenderProgress}. */
+  executionArn: string;
+  bucketName: string;
+  stateMachineArn: string;
+  outputS3Uri: string;
+  projectS3Uri: string;
+  startedAt: string;
+}
+
+export async function renderToLambda(opts: RenderToLambdaOptions): Promise<RenderHandle> {
+  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 as string,
+      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 = 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,
+  };
+}