@treeseed/sdk 0.11.0 → 0.12.4

package/dist/scenes/render-report.js

@@ -0,0 +1,27 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { sceneWarningDiagnostic } from "./diagnostics.js";
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function writeTreeseedSceneRenderReport(input) {
+  if (input.report.inputPath && input.input) writeJson(input.report.inputPath, input.input);
+  if (input.report.compositionPath) writeJson(input.report.compositionPath, input.composition ?? {});
+  if (input.report.renderRoot) writeJson(join(input.report.renderRoot, "report.json"), input.report);
+}
+function appendTreeseedSceneRenderedVideo(input) {
+  try {
+    const run = JSON.parse(readFileSync(input.runPath, "utf8"));
+    const renderedVideoPaths = [.../* @__PURE__ */ new Set([...run.renderedVideoPaths ?? [], input.outputPath])];
+    writeJson(input.runPath, { ...run, renderedVideoPaths });
+    return [];
+  } catch (error) {
+    return [sceneWarningDiagnostic("scene.render_run_update_failed", `Rendered video was created but run.json could not be updated. ${error instanceof Error ? error.message : String(error ?? "")}`.trim(), "run.json")];
+  }
+}
+export {
+  appendTreeseedSceneRenderedVideo,
+  writeTreeseedSceneRenderReport
+};

package/dist/scenes/render.d.ts

@@ -0,0 +1,2 @@
+import type { TreeseedSceneRenderOptions, TreeseedSceneRenderReport } from './types.js';
+export declare function renderTreeseedScene(input: TreeseedSceneRenderOptions): Promise<TreeseedSceneRenderReport>;

package/dist/scenes/render.js

@@ -0,0 +1,218 @@
+import { mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { appendTreeseedSceneJsonl } from "./artifacts.js";
+import { sceneErrorDiagnostic, sceneWarningDiagnostic } from "./diagnostics.js";
+import { resolveTreeseedScenePlugins } from "./registry.js";
+import { createRemotionTreeseedSceneRendererAdapter, resolveTreeseedSceneRemotionEntryPoint } from "./remotion-adapter.js";
+import { listTreeseedSceneRemotionCompositions } from "./remotion-composition-registry.js";
+import { loadTreeseedSceneRenderInput } from "./remotion-input.js";
+import { stageTreeseedSceneRenderMediaAssets } from "./render-media-assets.js";
+import { appendTreeseedSceneRenderedVideo, writeTreeseedSceneRenderReport } from "./render-report.js";
+import { appendTreeseedSceneTrainingOutputPaths, writeTreeseedSceneTrainingOutputs } from "./training-report.js";
+function renderId(timestamp) {
+  return timestamp.toLowerCase().replace(/[^a-z0-9]/gu, "").slice(0, 12) || "render";
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function sourceArtifacts(runRoot, input) {
+  return {
+    runPath: runRoot ? join(runRoot, "run.json") : null,
+    timelinePath: runRoot ? join(runRoot, "timeline.json") : null,
+    normalizedScenePath: runRoot ? join(runRoot, "scene.normalized.json") : null,
+    planPath: runRoot ? join(runRoot, "scene.plan.json") : null,
+    videoPaths: input?.media.videoRefs?.map((entry) => entry.path) ?? input?.media.videos ?? [],
+    screenshotPaths: input?.media.screenshots.map((screenshot) => screenshot.path) ?? [],
+    segmentPaths: input?.segments.map((segment) => segment.segmentPath) ?? []
+  };
+}
+function progressWriter(input) {
+  return (type, data = {}) => {
+    const event = {
+      type,
+      sceneId: input.sceneId,
+      runId: input.runId,
+      renderId: input.renderId,
+      timestamp: nowIso(),
+      offsetMs: Math.max(0, Date.now() - input.startedAt.getTime()),
+      data
+    };
+    if (input.progressPath) appendTreeseedSceneJsonl(input.progressPath, event);
+    input.onProgress?.(event);
+    return event;
+  };
+}
+function report(input) {
+  const finishedAt = /* @__PURE__ */ new Date();
+  return {
+    ok: input.ok,
+    phase: 6,
+    renderer: input.renderer,
+    renderId: input.renderId,
+    sceneId: input.sceneId,
+    sourceRunId: input.sourceRunId,
+    scenePath: input.scenePath,
+    runRoot: input.runRoot,
+    device: input.device ?? null,
+    startedAt: input.startedAt.toISOString(),
+    finishedAt: finishedAt.toISOString(),
+    durationMs: Math.max(0, finishedAt.getTime() - input.startedAt.getTime()),
+    mode: input.mode,
+    composition: input.composition,
+    format: input.format,
+    outputPath: input.outputPath,
+    renderRoot: input.renderRoot,
+    inputPath: input.inputPath,
+    compositionPath: input.compositionPath,
+    progressPath: input.progressPath,
+    renderedVideoPaths: input.renderedVideoPaths,
+    trainingOutputPaths: input.trainingOutputPaths,
+    sourceArtifacts: input.sourceArtifacts,
+    diagnostics: input.diagnostics,
+    warnings: input.warnings,
+    blockers: input.blockers
+  };
+}
+function createDefaultRendererAdapter(renderer) {
+  if (renderer === "remotion") return createRemotionTreeseedSceneRendererAdapter();
+  return null;
+}
+function renderEntrypoint(renderer) {
+  return renderer === "remotion" ? resolveTreeseedSceneRemotionEntryPoint() : void 0;
+}
+function compositionDescription(renderer, compositionId) {
+  if (renderer !== "remotion" || !compositionId) return null;
+  return listTreeseedSceneRemotionCompositions().find((entry) => entry.id === compositionId) ?? null;
+}
+async function renderTreeseedScene(input) {
+  const startedAt = /* @__PURE__ */ new Date();
+  const timestamp = input.timestamp ?? startedAt.toISOString().replace(/[-:]/gu, "").replace(/\.\d{3}Z$/u, "Z");
+  const id = input.runId ?? renderId(timestamp);
+  const renderer = input.renderer ?? "remotion";
+  const format = input.format ?? "mp4";
+  const initialMode = input.mode ?? "demo";
+  if (format !== "mp4") {
+    const diagnostic = sceneErrorDiagnostic("scene.render_format_unsupported", `Unsupported scene render format: ${format}.`, "format");
+    return report({ ok: false, startedAt, renderId: id, scenePath: input.scene, runRoot: null, renderRoot: null, inputPath: null, compositionPath: null, progressPath: null, outputPath: null, mode: initialMode, composition: input.composition ?? null, format: "mp4", sourceRunId: null, sceneId: null, renderedVideoPaths: [], trainingOutputPaths: null, diagnostics: [diagnostic], warnings: [], blockers: [diagnostic], sourceArtifacts: sourceArtifacts(null, null), renderer });
+  }
+  const resolution = resolveTreeseedScenePlugins({ plugins: input.plugins });
+  const rendererDefinition = resolution.registry.renderers.get(renderer);
+  if (!rendererDefinition) {
+    const diagnostic = sceneErrorDiagnostic("scene.renderer_unknown", `Unknown scene renderer: ${renderer}.`, "renderer");
+    return report({ ok: false, startedAt, renderId: id, scenePath: input.scene, runRoot: null, renderRoot: null, inputPath: null, compositionPath: null, progressPath: null, outputPath: null, mode: initialMode, composition: input.composition ?? null, format, sourceRunId: null, sceneId: null, renderedVideoPaths: [], trainingOutputPaths: null, diagnostics: [diagnostic], warnings: [], blockers: [diagnostic], sourceArtifacts: sourceArtifacts(null, null), renderer });
+  }
+  if (rendererDefinition.status !== "available") {
+    const diagnostic = sceneErrorDiagnostic("scene.renderer_unavailable", `The scene renderer "${renderer}" is ${rendererDefinition.status} until Phase ${rendererDefinition.phase}.`, "renderer");
+    return report({ ok: false, startedAt, renderId: id, scenePath: input.scene, runRoot: null, renderRoot: null, inputPath: null, compositionPath: null, progressPath: null, outputPath: null, mode: initialMode, composition: input.composition ?? null, format, sourceRunId: null, sceneId: null, renderedVideoPaths: [], trainingOutputPaths: null, diagnostics: [diagnostic], warnings: [], blockers: [diagnostic], sourceArtifacts: sourceArtifacts(null, null), renderer });
+  }
+  const loaded = loadTreeseedSceneRenderInput({
+    projectRoot: input.projectRoot,
+    scene: input.scene,
+    from: input.from,
+    mode: input.mode,
+    composition: input.composition,
+    format,
+    chapterId: input.chapterId,
+    renderer,
+    device: input.device
+  });
+  const renderRoot = loaded.runRoot ? join(loaded.runRoot, "render", renderer) : null;
+  const inputPath = renderRoot ? join(renderRoot, "input.json") : null;
+  const compositionPath = renderRoot ? join(renderRoot, "composition.json") : null;
+  const progressPath = renderRoot ? join(renderRoot, "progress.jsonl") : null;
+  const outputPath = input.output ? resolve(input.projectRoot, input.output) : renderRoot ? join(renderRoot, "output.mp4") : null;
+  if (renderRoot) mkdirSync(renderRoot, { recursive: true });
+  const pushProgress = progressWriter({
+    sceneId: loaded.input?.scene.id ?? null,
+    runId: loaded.input?.run.runId ?? null,
+    renderId: id,
+    startedAt,
+    progressPath,
+    onProgress: input.onProgress
+  });
+  pushProgress("scene.render.started", { renderer, format });
+  if (!loaded.ok || !loaded.input || !outputPath) {
+    const failed = report({ ok: false, startedAt, renderId: id, scenePath: input.scene, runRoot: loaded.runRoot, renderRoot, inputPath, compositionPath, progressPath, outputPath, mode: loaded.input?.render.mode ?? initialMode, composition: loaded.input?.render.composition ?? input.composition ?? null, format, sourceRunId: loaded.input?.run.runId ?? null, sceneId: loaded.input?.scene.id ?? null, renderedVideoPaths: [], trainingOutputPaths: null, diagnostics: loaded.diagnostics, warnings: loaded.warnings, blockers: loaded.blockers, sourceArtifacts: sourceArtifacts(loaded.runRoot, loaded.input), renderer });
+    writeTreeseedSceneRenderReport({ report: failed, input: loaded.input, composition: null });
+    pushProgress("scene.render.finished", { ok: false });
+    return failed;
+  }
+  let renderInput = loaded.input;
+  const stagedMedia = renderRoot && renderer === "remotion" ? stageTreeseedSceneRenderMediaAssets({ renderRoot, renderInput }) : null;
+  if (stagedMedia) renderInput = stagedMedia.renderInput;
+  pushProgress("scene.render.input.loaded", { runRoot: loaded.runRoot, stagedVideos: renderInput.media.videoRefs?.filter((entry) => entry.staticPath).length ?? 0 });
+  const composition = compositionDescription(renderer, renderInput.render.composition);
+  const adapter = input.rendererAdapter ?? input.rendererAdapterFactory?.({ renderer }) ?? createDefaultRendererAdapter(renderer);
+  if (!adapter) {
+    const diagnostic = sceneErrorDiagnostic("scene.renderer_unavailable", `No adapter is available for scene renderer "${renderer}".`, "renderer");
+    const failed = report({ ok: false, startedAt, renderId: id, scenePath: input.scene, runRoot: loaded.runRoot, renderRoot, inputPath, compositionPath, progressPath, outputPath, mode: renderInput.render.mode, composition: renderInput.render.composition, format, sourceRunId: renderInput.run.runId, sceneId: renderInput.scene.id, renderedVideoPaths: [], trainingOutputPaths: null, diagnostics: [...loaded.diagnostics, ...stagedMedia?.warnings ?? [], diagnostic], warnings: [...loaded.warnings, ...stagedMedia?.warnings ?? []], blockers: [diagnostic], sourceArtifacts: sourceArtifacts(loaded.runRoot, renderInput), renderer });
+    writeTreeseedSceneRenderReport({ report: failed, input: renderInput, composition });
+    pushProgress("scene.render.finished", { ok: false });
+    return failed;
+  }
+  const adapterResult = await adapter.render({
+    entryPoint: renderEntrypoint(renderer),
+    compositionId: renderInput.render.composition,
+    inputProps: renderInput,
+    outputPath,
+    publicDir: stagedMedia?.publicDir,
+    codec: "h264",
+    onProgress(progress) {
+      const type = progress.type === "bundle.started" ? "scene.render.bundle.started" : progress.type === "bundle.finished" ? "scene.render.bundle.finished" : progress.type === "composition.selected" ? "scene.render.composition.selected" : progress.type === "media.started" ? "scene.render.media.started" : progress.type === "media.finished" ? "scene.render.media.finished" : "scene.render.media.progress";
+      pushProgress(type, progress);
+    }
+  });
+  const updateWarnings = adapterResult.ok && adapterResult.outputPath ? appendTreeseedSceneRenderedVideo({ runPath: join(loaded.runRoot, "run.json"), outputPath: adapterResult.outputPath }) : [];
+  let trainingOutputPaths = null;
+  let trainingWarnings = [];
+  if (adapterResult.ok && renderInput.render.mode === "training" && loaded.runRoot) {
+    try {
+      const outputs = {
+        schemaVersion: "treeseed.scene.training-output/v1",
+        sceneId: renderInput.scene.id,
+        runId: renderInput.run.runId,
+        generatedAt: nowIso(),
+        ...renderInput.training
+      };
+      trainingOutputPaths = writeTreeseedSceneTrainingOutputs({ runRoot: loaded.runRoot, scene: renderInput.scene, outputs });
+      trainingWarnings = appendTreeseedSceneTrainingOutputPaths({ runPath: join(loaded.runRoot, "run.json"), paths: trainingOutputPaths });
+    } catch (error) {
+      trainingWarnings = [sceneWarningDiagnostic("scene.training_write_failed", `Training outputs could not be written. ${error instanceof Error ? error.message : String(error ?? "")}`.trim(), "training")];
+    }
+  }
+  const warnings = [...loaded.warnings, ...stagedMedia?.warnings ?? [], ...updateWarnings, ...trainingWarnings.filter((entry) => entry.severity === "warning")];
+  const diagnostics = [...loaded.diagnostics, ...stagedMedia?.warnings ?? [], ...adapterResult.diagnostics, ...updateWarnings, ...trainingWarnings];
+  const blockers = adapterResult.ok ? loaded.blockers : adapterResult.diagnostics.filter((entry) => entry.severity === "error");
+  const renderedVideoPaths = adapterResult.ok && adapterResult.outputPath ? [adapterResult.outputPath] : [];
+  const finalReport = report({
+    ok: adapterResult.ok,
+    startedAt,
+    renderId: id,
+    scenePath: input.scene,
+    runRoot: loaded.runRoot,
+    device: renderInput.run.device ?? null,
+    renderRoot,
+    inputPath,
+    compositionPath,
+    progressPath,
+    outputPath: adapterResult.outputPath ?? outputPath,
+    mode: renderInput.render.mode,
+    composition: renderInput.render.composition,
+    format,
+    sourceRunId: renderInput.run.runId,
+    sceneId: renderInput.scene.id,
+    renderedVideoPaths,
+    trainingOutputPaths,
+    diagnostics,
+    warnings,
+    blockers,
+    sourceArtifacts: sourceArtifacts(loaded.runRoot, renderInput),
+    renderer
+  });
+  writeTreeseedSceneRenderReport({ report: finalReport, input: renderInput, composition: composition ?? null });
+  pushProgress("scene.render.finished", { ok: finalReport.ok, outputPath: finalReport.outputPath });
+  return finalReport;
+}
+export {
+  renderTreeseedScene
+};

package/dist/scenes/reporter.d.ts

@@ -0,0 +1,3 @@
+import type { TreeseedSceneRunReport } from './types.js';
+export declare function formatTreeseedSceneMarkdownReport(report: TreeseedSceneRunReport): string;
+export declare function writeTreeseedSceneMarkdownReport(report: TreeseedSceneRunReport): void;

package/dist/scenes/reporter.js

@@ -0,0 +1,101 @@
+import { writeFileSync } from "node:fs";
+import { formatTreeseedSceneDiagnostics } from "./diagnostics.js";
+function row(values) {
+  return `| ${values.map((value) => value.replace(/\|/gu, "\\|")).join(" | ")} |`;
+}
+function formatTreeseedSceneMarkdownReport(report) {
+  const lines = [
+    `# Treeseed Scene Run: ${report.sceneId ?? "(unknown)"}`,
+    "",
+    `- Status: ${report.workflowStatus}`,
+    `- Run: ${report.runId ?? "(none)"}`,
+    `- Environment: ${report.environment}`,
+    `- Base URL: ${report.baseUrl ?? "(unresolved)"}`,
+    `- Browser: ${report.browser ?? "(unknown)"}`,
+    `- Setup: ${report.setup ? setupSummary(report) : "(not run)"}`,
+    `- Started: ${report.startedAt}`,
+    `- Finished: ${report.finishedAt}`,
+    `- Duration: ${report.durationMs}ms`,
+    "",
+    "## Steps",
+    "",
+    row(["Step", "Title", "Action", "Status", "Screenshot"]),
+    row(["---", "---", "---", "---", "---"]),
+    ...report.steps.map((step) => row([
+      step.id,
+      step.title,
+      step.actionKind,
+      step.status,
+      step.screenshotPath ?? ""
+    ])),
+    ""
+  ];
+  if (report.failedStep) {
+    const failed = report.steps.find((step) => step.id === report.failedStep);
+    lines.push("## Failed Step", "", `- Step: ${report.failedStep}`);
+    if (failed?.error) lines.push(`- Error: ${failed.error.code}: ${failed.error.message}`);
+    if (failed?.screenshotPath) lines.push(`- Screenshot: ${failed.screenshotPath}`);
+    if (report.playwrightTracePath) lines.push(`- Trace: ${report.playwrightTracePath}`);
+    lines.push("");
+  }
+  if (report.setup) {
+    lines.push("## Setup", "");
+    lines.push(`- Environment readiness: ${report.setup.environment?.ok ? "passed" : "failed"}`);
+    lines.push(`- Local dev: ${report.setup.environment?.dev.requested ? report.setup.environment.dev.reused ? "reused" : report.setup.environment.dev.started ? "started" : "requested" : "not requested"}`);
+    lines.push(`- Auth: ${report.setup.auth?.required ? report.setup.auth.hasSession ? "resolved" : "missing" : "optional"}`);
+    lines.push(`- Seed: ${report.setup.seed?.mode ?? "none"}`);
+    lines.push("");
+  }
+  if (report.operations.length > 0) {
+    lines.push("## Operations", "");
+    for (const operation of report.operations) {
+      lines.push(`- ${operation.operationId ?? "(unresolved)"}: ${operation.finalStatus ?? "(unknown)"} (${operation.ok ? "passed" : "failed"})`);
+    }
+    lines.push("");
+  }
+  if (report.diagnostics.length > 0) {
+    lines.push("## Diagnostics", "", ...formatTreeseedSceneDiagnostics(report.diagnostics).map((line) => `- ${line}`), "");
+  }
+  lines.push("## Artifacts", "");
+  if (report.artifacts) {
+    lines.push(
+      `- Run JSON: ${report.artifacts.runPath}`,
+      `- Timeline: ${report.artifacts.timelinePath}`,
+      `- Trace: ${report.artifacts.playwrightTracePath ?? "(none)"}`,
+      `- Console: ${report.artifacts.consoleLogPath ?? "(none)"}`,
+      `- Network: ${report.artifacts.networkLogPath ?? "(none)"}`,
+      `- Dev logs: ${report.logs.dev ?? "(none)"}`,
+      `- API logs: ${report.logs.api ?? "(none)"}`,
+      `- Operations runner logs: ${report.logs.operationsRunner ?? "(none)"}`
+    );
+  } else {
+    lines.push("- No artifacts were written.");
+  }
+  lines.push("", "## Console And Network Errors", "");
+  const consoleErrors = report.steps.flatMap((step) => step.consoleErrors.map((entry) => `${step.id}: ${entry.message}`));
+  const networkErrors = report.steps.flatMap((step) => step.networkErrors.map((entry) => `${step.id}: ${entry.method ?? "GET"} ${entry.url ?? ""} ${entry.status ?? ""} ${entry.message}`.trim()));
+  if (consoleErrors.length === 0 && networkErrors.length === 0) {
+    lines.push("- None observed.");
+  } else {
+    lines.push(...consoleErrors.map((entry) => `- Console: ${entry}`), ...networkErrors.map((entry) => `- Network: ${entry}`));
+  }
+  return `${lines.join("\n")}
+`;
+}
+function setupSummary(report) {
+  const setup = report.setup;
+  if (!setup) return "not run";
+  const parts = [];
+  if (setup.environment?.dev.requested) parts.push(setup.environment.dev.reused ? "dev reused" : setup.environment.dev.started ? "dev started" : "dev requested");
+  if (setup.seed?.requested) parts.push(setup.seed.mode === "apply" ? "seed applied" : "seed planned");
+  if (setup.auth?.required) parts.push(setup.auth.hasSession ? "auth resolved" : "auth missing");
+  return parts.length > 0 ? parts.join(", ") : "checked";
+}
+function writeTreeseedSceneMarkdownReport(report) {
+  if (!report.artifacts) return;
+  writeFileSync(report.artifacts.markdownReportPath, formatTreeseedSceneMarkdownReport(report), "utf8");
+}
+export {
+  formatTreeseedSceneMarkdownReport,
+  writeTreeseedSceneMarkdownReport
+};

package/dist/scenes/resume.d.ts

@@ -0,0 +1,2 @@
+import type { TreeseedSceneResumeOptions, TreeseedSceneRunReport } from './types.js';
+export declare function resumeTreeseedScene(input: TreeseedSceneResumeOptions): Promise<TreeseedSceneRunReport>;

package/dist/scenes/resume.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { sceneErrorDiagnostic } from "./diagnostics.js";
+import { resolveTreeseedSceneRunRoot } from "./inspect.js";
+import { runTreeseedScene } from "./runner.js";
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function blocked(input, diagnostics) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    ok: false,
+    phase: 5,
+    sceneId: null,
+    runId: null,
+    scenePath: input.run,
+    startedAt: now,
+    finishedAt: now,
+    durationMs: 0,
+    environment: input.environment ?? "local",
+    baseUrl: null,
+    browser: null,
+    workflowStatus: "blocked",
+    steps: [],
+    failedStep: null,
+    assertions: [],
+    artifacts: null,
+    timelinePath: null,
+    playwrightTracePath: null,
+    videoPaths: [],
+    renderedVideoPaths: [],
+    logs: {},
+    setup: null,
+    operations: [],
+    chapters: [],
+    segments: [],
+    checkpoints: [],
+    resumedFrom: null,
+    progressPath: null,
+    warnings: diagnostics.filter((entry) => entry.severity === "warning"),
+    blockers: diagnostics.filter((entry) => entry.severity === "error"),
+    diagnostics
+  };
+}
+async function resumeTreeseedScene(input) {
+  input.onProgress?.({ type: "resume.started", sceneId: null, runId: null, timestamp: (/* @__PURE__ */ new Date()).toISOString(), offsetMs: 0, checkpointId: input.fromCheckpoint, data: { run: input.run } });
+  const resolved = resolveTreeseedSceneRunRoot(input.projectRoot, input.run);
+  if (!resolved.runRoot) return blocked(input, resolved.diagnostics);
+  const checkpointPath = join(resolved.runRoot, "checkpoints", `${input.fromCheckpoint}.json`);
+  if (!existsSync(checkpointPath)) return blocked(input, [sceneErrorDiagnostic("scene.checkpoint_not_found", `Checkpoint not found: ${input.fromCheckpoint}.`, "checkpoint")]);
+  const checkpoint = readJson(checkpointPath);
+  if (!checkpoint.resumable) return blocked(input, [sceneErrorDiagnostic("scene.checkpoint_not_resumable", `Checkpoint is not resumable: ${input.fromCheckpoint}.`, "checkpoint")]);
+  const scenePath = join(resolved.runRoot, "scene.normalized.json");
+  if (!existsSync(scenePath)) return blocked(input, [sceneErrorDiagnostic("scene.normalized_scene_not_found", `Normalized scene not found: ${scenePath}.`, "scene")]);
+  const scene = readJson(scenePath);
+  const nextIndex = checkpoint.nextStepId ? scene.workflow.findIndex((step) => step.id === checkpoint.nextStepId) : scene.workflow.length;
+  if (nextIndex < 0) return blocked(input, [sceneErrorDiagnostic("scene.resume_step_not_found", `Resume step not found: ${checkpoint.nextStepId}.`, "checkpoint.nextStepId")]);
+  const resumeScene = {
+    ...scene,
+    workflow: scene.workflow.slice(nextIndex)
+  };
+  const report = await runTreeseedScene({
+    ...input,
+    scene: resumeScene,
+    onProgress: (event) => {
+      input.onProgress?.(event);
+    }
+  });
+  report.resumedFrom = {
+    runRoot: resolved.runRoot,
+    checkpointId: checkpoint.id,
+    sourceRunId: checkpoint.runId
+  };
+  input.onProgress?.({ type: "resume.finished", sceneId: report.sceneId, runId: report.runId, timestamp: (/* @__PURE__ */ new Date()).toISOString(), offsetMs: 0, checkpointId: checkpoint.id, status: report.workflowStatus, data: { ok: report.ok } });
+  return report;
+}
+export {
+  resumeTreeseedScene
+};

package/dist/scenes/runner.d.ts

@@ -0,0 +1,2 @@
+import type { TreeseedSceneRunOptions, TreeseedSceneRunReport } from './types.js';
+export declare function runTreeseedScene(input: TreeseedSceneRunOptions): Promise<TreeseedSceneRunReport>;