@treeseed/sdk 0.10.28 → 0.12.4

package/dist/scenes/builtin-plugins.js

@@ -0,0 +1,447 @@
+import { resolveTreeseedSceneBaseUrl } from "./base-url.js";
+import { prepareTreeseedSceneEnvironment } from "./environment.js";
+import { resolveTreeseedSceneAuth } from "./auth.js";
+import { planOrApplyTreeseedSceneSeed } from "./seed.js";
+import { sceneErrorDiagnostic } from "./diagnostics.js";
+import { createBuiltInTreeseedSceneDiagramProvider } from "./diagram-providers.js";
+import { buildTreeseedSceneNarrationEntries } from "./training-transcript.js";
+function duration(start, end) {
+  return Math.max(0, end.getTime() - start.getTime());
+}
+function mailpitApiUrl(mailpitUrl, pathname) {
+  const url = new URL(pathname, mailpitUrl.endsWith("/") ? mailpitUrl : `${mailpitUrl}/`);
+  return url.toString();
+}
+function stringValue(value) {
+  return typeof value === "string" ? value : "";
+}
+function mailpitMessageId(value) {
+  if (!value || typeof value !== "object") return "";
+  const record = value;
+  return stringValue(record.ID) || stringValue(record.Id) || stringValue(record.id);
+}
+function mailpitMessageSubject(value) {
+  if (!value || typeof value !== "object") return "";
+  const record = value;
+  return stringValue(record.Subject) || stringValue(record.subject);
+}
+function mailpitMessageRecipients(value) {
+  if (!value || typeof value !== "object") return [];
+  const record = value;
+  const recipients = record.To ?? record.to ?? record.Recipients ?? record.recipients;
+  if (!Array.isArray(recipients)) return [];
+  return recipients.map((recipient) => {
+    if (typeof recipient === "string") return recipient;
+    if (!recipient || typeof recipient !== "object") return "";
+    const entry = recipient;
+    return stringValue(entry.Address) || stringValue(entry.address) || stringValue(entry.Email) || stringValue(entry.email);
+  }).filter(Boolean);
+}
+function mailpitMessages(value) {
+  if (!value || typeof value !== "object") return [];
+  const record = value;
+  const messages = record.messages ?? record.Messages;
+  return Array.isArray(messages) ? messages : [];
+}
+function mailpitMessageBody(value) {
+  if (!value || typeof value !== "object") return "";
+  const record = value;
+  const html = stringValue(record.HTML) || stringValue(record.Html) || stringValue(record.html);
+  const text = stringValue(record.Text) || stringValue(record.text);
+  return `${html}
+${text}`.replace(/&/gu, "&");
+}
+function extractConfirmationUrl(body) {
+  const absolute = body.match(/https?:\/\/[^"' <>\n]+(?:\/auth\/confirm-email\?[^"' <>\n]+|\/team-invites\/[^"' <>\n]+\/accept)/u)?.[0];
+  if (absolute) return absolute;
+  const relative = body.match(/(?:\/auth\/confirm-email\?[^"' <>\n]+|\/team-invites\/[^"' <>\n]+\/accept)/u)?.[0];
+  return relative ?? null;
+}
+async function assertionReport(kind, action, selector) {
+  const startedAt = /* @__PURE__ */ new Date();
+  try {
+    await action();
+    const finishedAt = /* @__PURE__ */ new Date();
+    return { kind, status: "passed", startedAt: startedAt.toISOString(), finishedAt: finishedAt.toISOString(), durationMs: duration(startedAt, finishedAt), ...selector ? { selector } : {} };
+  } catch (error) {
+    const finishedAt = /* @__PURE__ */ new Date();
+    const diagnostic = error && typeof error === "object" && "code" in error ? error : sceneErrorDiagnostic("scene.assertion_failed", error instanceof Error ? error.message : String(error ?? "Assertion failed."));
+    return { kind, status: "failed", startedAt: startedAt.toISOString(), finishedAt: finishedAt.toISOString(), durationMs: duration(startedAt, finishedAt), message: diagnostic.message, error: diagnostic, ...selector ? { selector } : {} };
+  }
+}
+function createBuiltInTreeseedScenePlugins() {
+  return [
+    {
+      id: "treeseed.scene.browser-actions",
+      version: "1.0.0",
+      phase: 4,
+      status: "available",
+      summary: "Browser actions for Playwright-backed scene execution.",
+      actions: {
+        goto: {
+          id: "goto",
+          phase: 2,
+          status: "available",
+          summary: "Navigate to a route or absolute URL.",
+          async run({ action, context }) {
+            if (!("goto" in action)) return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.invalid_action", "Expected goto action.", "workflow.action.goto")] };
+            await context.session.page.goto(context.resolveUrl(action.goto));
+            return { ok: true, diagnostics: [] };
+          }
+        },
+        click: {
+          id: "click",
+          phase: 2,
+          status: "available",
+          summary: "Click a semantic selector.",
+          async run({ action, context }) {
+            if (!("click" in action)) return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.invalid_action", "Expected click action.", "workflow.action.click")] };
+            const locator = context.resolveSelector(action.click);
+            await locator.waitFor({ state: "visible", timeout: 1e4 });
+            await locator.click();
+            return { ok: true, diagnostics: [] };
+          }
+        },
+        fill: {
+          id: "fill",
+          phase: 2,
+          status: "available",
+          summary: "Fill a semantic selector with a value.",
+          async run({ action, context }) {
+            if (!("fill" in action)) return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.invalid_action", "Expected fill action.", "workflow.action.fill")] };
+            const locator = context.resolveSelector(action.fill);
+            await locator.waitFor({ state: "visible", timeout: 1e4 });
+            await locator.fill(action.fill.value);
+            return { ok: true, diagnostics: [] };
+          }
+        },
+        select: {
+          id: "select",
+          phase: 2,
+          status: "available",
+          summary: "Select an option in a dropdown control.",
+          async run({ action, context }) {
+            if (!("select" in action)) return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.invalid_action", "Expected select action.", "workflow.action.select")] };
+            const locator = context.resolveSelector(action.select);
+            await locator.waitFor({ state: "visible", timeout: 1e4 });
+            if (!locator.selectOption) return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.unsupported_runtime_action", "The active browser adapter does not support select actions.", "workflow.action.select")] };
+            await locator.selectOption(action.select.value ?? { label: action.select.label ?? "" });
+            return { ok: true, diagnostics: [] };
+          }
+        },
+        keyboard: {
+          id: "keyboard",
+          phase: 2,
+          status: "available",
+          summary: "Send keyboard input.",
+          async run({ action, context }) {
+            if (!("keyboard" in action)) return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.invalid_action", "Expected keyboard action.", "workflow.action.keyboard")] };
+            await context.session.page.keyboard.press(action.keyboard);
+            return { ok: true, diagnostics: [] };
+          }
+        },
+        apiRequest: {
+          id: "apiRequest",
+          phase: 4,
+          status: "deferred",
+          summary: "API request actions are reserved for the plugin-contract extension point.",
+          async run() {
+            return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.unsupported_runtime_action", 'Action "apiRequest" is deferred until an API action plugin is available.', "workflow.action.apiRequest")] };
+          }
+        },
+        pause: {
+          id: "pause",
+          phase: 5,
+          status: "available",
+          summary: "Pause execution for live demos and long workflow orchestration.",
+          async run({ action, step, context }) {
+            if (!("pause" in action)) return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.invalid_action", "Expected pause action.", `workflow.${step.id}.action.pause`)] };
+            context.timeline.push("pause.waiting", { mode: action.pause.mode, prompt: action.pause.prompt ?? null }, step.id);
+            context.progress?.push("pause.waiting", { mode: action.pause.mode, prompt: action.pause.prompt ?? null }, { stepId: step.id });
+            if (action.pause.mode === "timed") {
+              await context.sleep((action.pause.durationSeconds ?? 0) * 1e3);
+              context.timeline.push("pause.resumed", { mode: "timed" }, step.id);
+              context.progress?.push("pause.resumed", { mode: "timed" }, { stepId: step.id });
+              return { ok: true, diagnostics: [] };
+            }
+            if (!context.interactive || !context.pauseController) {
+              return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.manual_pause_requires_tty", "Manual pause steps require an interactive terminal.", `workflow.${step.id}.action.pause`)] };
+            }
+            const result = await context.pauseController({
+              sceneId: context.scene.id,
+              stepId: step.id,
+              title: step.title,
+              prompt: action.pause.prompt
+            });
+            if (result.ok) {
+              context.timeline.push("pause.resumed", { mode: "manual" }, step.id);
+              context.progress?.push("pause.resumed", { mode: "manual" }, { stepId: step.id });
+            }
+            return result;
+          }
+        },
+        mailpitConfirmLatest: {
+          id: "mailpitConfirmLatest",
+          phase: 11,
+          status: "available",
+          summary: "Confirm the latest local Mailpit email by navigating the browser to its confirmation link.",
+          async run({ action, step, context }) {
+            if (!("mailpitConfirmLatest" in action)) return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.invalid_action", "Expected mailpitConfirmLatest action.", `workflow.${step.id}.action.mailpitConfirmLatest`)] };
+            const { mailpitUrl, email, subjectIncludes, displayInboxSeconds, displayMessageSeconds } = action.mailpitConfirmLatest;
+            try {
+              const listResponse = await fetch(mailpitApiUrl(mailpitUrl, "/api/v1/messages"));
+              if (!listResponse.ok) {
+                return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.mailpit_unavailable", `Mailpit message list returned HTTP ${listResponse.status}.`, `workflow.${step.id}.action.mailpitConfirmLatest`)] };
+              }
+              const list = await listResponse.json();
+              const target = mailpitMessages(list).find((message2) => {
+                const recipients = mailpitMessageRecipients(message2);
+                const subject = mailpitMessageSubject(message2);
+                return recipients.some((recipient) => recipient.toLowerCase() === email.toLowerCase()) && (!subjectIncludes || subject.toLowerCase().includes(subjectIncludes.toLowerCase()));
+              });
+              const id = mailpitMessageId(target);
+              if (!id) {
+                return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.mailpit_message_not_found", `No Mailpit message found for ${email}.`, `workflow.${step.id}.action.mailpitConfirmLatest.email`)] };
+              }
+              const messageResponse = await fetch(mailpitApiUrl(mailpitUrl, `/api/v1/message/${encodeURIComponent(id)}`));
+              if (!messageResponse.ok) {
+                return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.mailpit_unavailable", `Mailpit message ${id} returned HTTP ${messageResponse.status}.`, `workflow.${step.id}.action.mailpitConfirmLatest`)] };
+              }
+              const message = await messageResponse.json();
+              const confirmationUrl = extractConfirmationUrl(mailpitMessageBody(message));
+              if (!confirmationUrl) {
+                return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.mailpit_confirm_link_not_found", `No confirmation link was found in Mailpit message ${id}.`, `workflow.${step.id}.action.mailpitConfirmLatest`)] };
+              }
+              const resolvedUrl = confirmationUrl.startsWith("/") ? context.resolveUrl(confirmationUrl) : confirmationUrl;
+              const mailpitBase = mailpitUrl.endsWith("/") ? mailpitUrl : `${mailpitUrl}/`;
+              if (displayInboxSeconds && displayInboxSeconds > 0) {
+                const search = new URL("search", mailpitBase);
+                search.searchParams.set("query", `to:${email}`);
+                context.timeline.push("mailpit.inbox.open", { messageId: id, email, url: search.toString() }, step.id);
+                context.progress?.push("mailpit.inbox.open", { messageId: id, email }, { stepId: step.id });
+                await context.session.page.goto(search.toString());
+                await context.sleep(displayInboxSeconds * 1e3);
+              }
+              if (displayMessageSeconds && displayMessageSeconds > 0) {
+                const view = new URL(`view/${encodeURIComponent(id)}`, mailpitBase);
+                context.timeline.push("mailpit.message.open", { messageId: id, email, url: view.toString() }, step.id);
+                context.progress?.push("mailpit.message.open", { messageId: id, email }, { stepId: step.id });
+                await context.session.page.goto(view.toString());
+                await context.sleep(displayMessageSeconds * 1e3);
+              }
+              context.timeline.push("mailpit.confirm.open", { messageId: id, email, url: resolvedUrl }, step.id);
+              await context.session.page.goto(resolvedUrl);
+              return { ok: true, diagnostics: [] };
+            } catch (error) {
+              return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.mailpit_unavailable", error instanceof Error ? error.message : String(error ?? "Mailpit confirmation failed."), `workflow.${step.id}.action.mailpitConfirmLatest`)] };
+            }
+          }
+        }
+      }
+    },
+    {
+      id: "treeseed.scene.operation-actions",
+      version: "1.0.0",
+      phase: 4,
+      status: "available",
+      summary: "Operation wait actions for backend workflow proof.",
+      actions: {
+        waitForOperation: {
+          id: "waitForOperation",
+          phase: 3,
+          status: "available",
+          summary: "Wait for a linked or explicit Treeseed platform operation.",
+          async run({ action, step, context }) {
+            if (!("waitForOperation" in action)) return { ok: false, diagnostics: [sceneErrorDiagnostic("scene.invalid_action", "Expected waitForOperation action.", `workflow.${step.id}.action.waitForOperation`)] };
+            context.timeline.push("operation.poll.start", { spec: action.waitForOperation }, step.id);
+            const report = await context.operationWaiter({
+              projectRoot: context.projectRoot,
+              scene: context.scene,
+              environment: context.environment,
+              baseUrl: context.baseUrl,
+              spec: action.waitForOperation,
+              linkedOperationIds: context.linkedOperationIds,
+              onUpdate: async (update) => {
+                context.timeline.push("operation.poll.tick", { operationId: update.operationId, status: update.finalStatus }, step.id);
+              }
+            });
+            context.timeline.push("operation.poll.end", { ok: report.ok, operationId: report.operationId, status: report.finalStatus }, step.id);
+            context.operationReports.push(report);
+            if (report.operationId && !context.linkedOperationIds.includes(report.operationId)) context.linkedOperationIds.push(report.operationId);
+            return { ok: report.ok, operationReport: report, diagnostics: report.diagnostics };
+          }
+        }
+      }
+    },
+    {
+      id: "treeseed.scene.browser-assertions",
+      version: "1.0.0",
+      phase: 4,
+      status: "available",
+      summary: "Browser assertions for Playwright-backed scene execution.",
+      assertions: {
+        visible: {
+          id: "visible",
+          phase: 2,
+          status: "available",
+          summary: "Expect selectors to be visible.",
+          async run({ value, step, context }) {
+            const selectors = Array.isArray(value) ? value : [];
+            const results = [];
+            for (const selector of selectors) {
+              results.push(await assertionReport("visible", async () => {
+                const locator = context.resolveSelector(selector);
+                await locator.waitFor({ state: "visible", timeout: 1e4 });
+                if (!await locator.isVisible()) throw sceneErrorDiagnostic("scene.selector_not_found", "Expected selector to be visible.", `workflow.${step.id}.expect.visible`);
+              }, selector));
+            }
+            return results.find((result) => result.status === "failed") ?? results[0] ?? await assertionReport("visible", async () => void 0);
+          }
+        },
+        text: {
+          id: "text",
+          phase: 2,
+          status: "available",
+          summary: "Expect text to appear.",
+          async run({ value, step, context }) {
+            const text = String(value ?? "");
+            const selector = { text };
+            return assertionReport("text", async () => {
+              const textLocator = context.session.page.getByText(text);
+              const locator = textLocator.first ? textLocator.first() : textLocator;
+              await locator.waitFor({ state: "visible", timeout: 1e4 });
+              if (!await locator.isVisible()) throw sceneErrorDiagnostic("scene.text_not_found", `Expected text to be visible: ${text}.`, `workflow.${step.id}.expect.text`);
+            }, selector);
+          }
+        },
+        urlIncludes: {
+          id: "urlIncludes",
+          phase: 2,
+          status: "available",
+          summary: "Expect the URL to include a fragment.",
+          async run({ value, step, context }) {
+            const expected = String(value ?? "");
+            return assertionReport("urlIncludes", async () => {
+              const timeoutMs = 1e4;
+              const deadline = Date.now() + timeoutMs;
+              let current = context.session.page.url();
+              while (!current.includes(expected) && Date.now() < deadline) {
+                await context.sleep(250);
+                current = context.session.page.url();
+              }
+              if (!current.includes(expected)) {
+                throw sceneErrorDiagnostic("scene.url_mismatch", `Expected URL to include "${expected}", got "${current}".`, `workflow.${step.id}.expect.urlIncludes`);
+              }
+            });
+          }
+        }
+      }
+    },
+    {
+      id: "treeseed.scene.operation-assertions",
+      version: "1.0.0",
+      phase: 4,
+      status: "available",
+      summary: "Operation assertions for backend workflow proof.",
+      assertions: {
+        operation: {
+          id: "operation",
+          phase: 3,
+          status: "available",
+          summary: "Expect a Treeseed platform operation to reach an accepted status.",
+          async run({ value, step, context }) {
+            return assertionReport("operation", async () => {
+              context.timeline.push("operation.poll.start", { spec: value }, step.id);
+              const report = await context.operationWaiter({
+                projectRoot: context.projectRoot,
+                scene: context.scene,
+                environment: context.environment,
+                baseUrl: context.baseUrl,
+                spec: value,
+                linkedOperationIds: context.linkedOperationIds,
+                onUpdate: async (update) => {
+                  context.timeline.push("operation.poll.tick", { operationId: update.operationId, status: update.finalStatus }, step.id);
+                }
+              });
+              context.timeline.push("operation.poll.end", { ok: report.ok, operationId: report.operationId, status: report.finalStatus }, step.id);
+              context.operationReports.push(report);
+              if (report.operationId && !context.linkedOperationIds.includes(report.operationId)) context.linkedOperationIds.push(report.operationId);
+              if (!report.ok) throw report.diagnostics[0] ?? sceneErrorDiagnostic("scene.operation_failed", "Operation assertion failed.", `workflow.${step.id}.expect.operation`);
+            });
+          }
+        }
+      }
+    },
+    {
+      id: "treeseed.scene.environment",
+      version: "1.0.0",
+      phase: 4,
+      status: "available",
+      summary: "Treeseed environment preparation, auth, seed, and base URL integration.",
+      environment: {
+        prepare: prepareTreeseedSceneEnvironment,
+        resolveAuth: resolveTreeseedSceneAuth,
+        prepareSeed: planOrApplyTreeseedSceneSeed,
+        resolveBaseUrl: resolveTreeseedSceneBaseUrl
+      }
+    },
+    {
+      id: "treeseed.scene.capture.playwright",
+      version: "1.0.0",
+      phase: 4,
+      status: "available",
+      summary: "Built-in Playwright capture providers exposed through the plugin registry.",
+      captures: Object.fromEntries(["playwright-trace", "playwright-video", "playwright-screenshots", "playwright-console", "playwright-network", "operation-id-detection"].map((id) => [id, { id, phase: 4, status: "available", summary: `Built-in capture provider: ${id}.` }]))
+    },
+    {
+      id: "treeseed.scene.artifacts.default",
+      version: "1.0.0",
+      phase: 4,
+      status: "available",
+      summary: "Default scene artifact writers exposed through the plugin registry.",
+      artifacts: Object.fromEntries(["json-run", "json-timeline", "json-plan", "json-normalized-scene", "markdown-report", "setup-json", "managed-dev-logs"].map((id) => [id, { id, phase: 4, status: "available", summary: `Built-in artifact writer: ${id}.` }]))
+    },
+    {
+      id: "treeseed.scene.renderer.remotion",
+      version: "1.0.0",
+      phase: 6,
+      status: "available",
+      summary: "Render scene timelines and browser artifacts through Remotion.",
+      renderers: {
+        remotion: { id: "remotion", phase: 6, status: "available", summary: "Render demo, training, chapter, and failure-review videos from scene run artifacts." }
+      }
+    },
+    {
+      id: "treeseed.scene.diagrams.remotion",
+      version: "1.0.0",
+      phase: 7,
+      status: "available",
+      summary: "Built-in typed Remotion diagram providers for scene videos.",
+      diagrams: {
+        "treeseed-remotion-diagrams": createBuiltInTreeseedSceneDiagramProvider()
+      }
+    },
+    {
+      id: "treeseed.scene.training.deterministic",
+      version: "1.0.0",
+      phase: 8,
+      status: "available",
+      summary: "Deterministic captions, transcripts, narration scripts, glossary, and chapter clip manifests.",
+      narration: {
+        "deterministic-narration": {
+          id: "deterministic-narration",
+          phase: 8,
+          status: "available",
+          summary: "Generate deterministic scene narration scripts from transcript entries.",
+          generate({ scene, run, transcript, style }) {
+            return buildTreeseedSceneNarrationEntries({ scene, run, transcript, style });
+          }
+        }
+      },
+      artifacts: Object.fromEntries(["training-json", "training-markdown", "training-captions", "training-chapter-clips"].map((id) => [id, { id, phase: 8, status: "available", summary: `Built-in training artifact writer: ${id}.` }]))
+    }
+  ];
+}
+export {
+  createBuiltInTreeseedScenePlugins
+};

package/dist/scenes/checkpoints.d.ts

@@ -0,0 +1,14 @@
+import type { TreeseedSceneArtifactPathPlan, TreeseedSceneCheckpoint } from './types.js';
+export declare function createTreeseedSceneCheckpoint(input: {
+    paths: TreeseedSceneArtifactPathPlan;
+    sceneId: string;
+    runId: string;
+    stepId: string;
+    chapterId: string;
+    segmentId: string;
+    completedStepIds: string[];
+    nextStepId: string | null;
+    checkpointId?: string;
+    resumable: boolean;
+}): TreeseedSceneCheckpoint;
+export declare function writeTreeseedSceneCheckpoint(checkpoint: TreeseedSceneCheckpoint): void;

package/dist/scenes/checkpoints.js

@@ -0,0 +1,33 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+function createTreeseedSceneCheckpoint(input) {
+  const id = input.checkpointId ?? input.stepId;
+  const checkpointPath = join(input.paths.checkpointsRoot, `${id}.json`);
+  return {
+    id,
+    sceneId: input.sceneId,
+    runId: input.runId,
+    stepId: input.stepId,
+    chapterId: input.chapterId,
+    segmentId: input.segmentId,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    resumable: input.resumable,
+    completedStepIds: [...input.completedStepIds],
+    nextStepId: input.nextStepId,
+    artifactPaths: {
+      checkpointPath,
+      runRoot: input.paths.runRoot,
+      timelinePath: input.paths.timelinePath,
+      reportPath: input.paths.markdownReportPath
+    }
+  };
+}
+function writeTreeseedSceneCheckpoint(checkpoint) {
+  mkdirSync(dirname(checkpoint.artifactPaths.checkpointPath), { recursive: true });
+  writeFileSync(checkpoint.artifactPaths.checkpointPath, `${JSON.stringify(checkpoint, null, 2)}
+`, "utf8");
+}
+export {
+  createTreeseedSceneCheckpoint,
+  writeTreeseedSceneCheckpoint
+};

package/dist/scenes/device-matrix.d.ts

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

package/dist/scenes/device-matrix.js

@@ -0,0 +1,97 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { listTreeseedSceneDeviceProfiles, resolveTreeseedSceneDeviceProfile } from "./devices.js";
+import { validateTreeseedScene } from "./planner.js";
+import { runTreeseedScene } from "./runner.js";
+function splitDiagnostics(diagnostics, severity) {
+  return diagnostics.filter((entry) => entry.severity === severity);
+}
+function timestampId(value) {
+  return value ?? (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/gu, "").replace(/\.\d{3}Z$/u, "Z");
+}
+async function runTreeseedSceneDeviceMatrix(input) {
+  const validation = validateTreeseedScene({ projectRoot: input.projectRoot, scene: input.scene });
+  if (!validation.ok || !validation.scene) {
+    return {
+      ok: false,
+      phase: 11,
+      sceneId: validation.scene?.id ?? null,
+      matrixId: null,
+      scenePath: validation.scenePath,
+      devices: input.devices ?? [],
+      runReports: [],
+      matrixRoot: null,
+      matrixPath: null,
+      diagnostics: validation.diagnostics,
+      warnings: splitDiagnostics(validation.diagnostics, "warning"),
+      blockers: splitDiagnostics(validation.diagnostics, "error")
+    };
+  }
+  const scene = validation.scene;
+  const requested = input.devices?.length ? input.devices : listTreeseedSceneDeviceProfiles(scene).map((profile) => profile.id);
+  const diagnostics = [];
+  const profiles = [];
+  for (const device of requested) {
+    const resolved = resolveTreeseedSceneDeviceProfile({ scene, device });
+    diagnostics.push(...resolved.diagnostics);
+    if (resolved.profile) profiles.push(resolved.profile.id);
+  }
+  if (diagnostics.some((entry) => entry.severity === "error")) {
+    return {
+      ok: false,
+      phase: 11,
+      sceneId: scene.id,
+      matrixId: null,
+      scenePath: validation.scenePath,
+      devices: requested,
+      runReports: [],
+      matrixRoot: null,
+      matrixPath: null,
+      diagnostics,
+      warnings: splitDiagnostics(diagnostics, "warning"),
+      blockers: splitDiagnostics(diagnostics, "error")
+    };
+  }
+  const matrixId = timestampId(input.timestamp).toLowerCase();
+  const matrixRoot = join(input.projectRoot, ".treeseed", "scenes", "matrix", scene.id, `${timestampId(input.timestamp)}-${matrixId}`);
+  const matrixPath = join(matrixRoot, "matrix.json");
+  mkdirSync(matrixRoot, { recursive: true });
+  const runReports = [];
+  for (const device of profiles) {
+    const runReport = await runTreeseedScene({
+      projectRoot: input.projectRoot,
+      scene: input.scene,
+      environment: input.environment,
+      device,
+      record: input.record,
+      mode: input.mode,
+      timestamp: input.timestamp,
+      runId: `${matrixId}-${device}`,
+      browserAdapter: input.browserAdapter
+    });
+    runReports.push(runReport);
+  }
+  const ok = runReports.every((report2) => report2.ok);
+  const runDiagnostics = runReports.flatMap((entry) => entry.diagnostics ?? []);
+  const allDiagnostics = [...diagnostics, ...runDiagnostics];
+  const report = {
+    ok,
+    phase: 11,
+    sceneId: scene.id,
+    matrixId,
+    scenePath: validation.scenePath,
+    devices: profiles,
+    runReports,
+    matrixRoot,
+    matrixPath,
+    diagnostics: allDiagnostics,
+    warnings: splitDiagnostics(allDiagnostics, "warning"),
+    blockers: splitDiagnostics(allDiagnostics, "error")
+  };
+  writeFileSync(matrixPath, `${JSON.stringify(report, null, 2)}
+`, "utf8");
+  return report;
+}
+export {
+  runTreeseedSceneDeviceMatrix
+};

package/dist/scenes/devices.d.ts

@@ -0,0 +1,11 @@
+import { defaultTreeseedSceneDeviceConfig } from './schema.js';
+import type { TreeseedSceneDeviceProfile, TreeseedSceneDiagnostic, TreeseedSceneManifest } from './types.js';
+export { defaultTreeseedSceneDeviceConfig };
+export declare function listTreeseedSceneDeviceProfiles(scene: TreeseedSceneManifest): TreeseedSceneDeviceProfile[];
+export declare function resolveTreeseedSceneDeviceProfile(input: {
+    scene: TreeseedSceneManifest;
+    device?: string;
+}): {
+    profile: TreeseedSceneDeviceProfile | null;
+    diagnostics: TreeseedSceneDiagnostic[];
+};

package/dist/scenes/devices.js

@@ -0,0 +1,22 @@
+import { sceneErrorDiagnostic } from "./diagnostics.js";
+import { defaultTreeseedSceneDeviceConfig } from "./schema.js";
+function listTreeseedSceneDeviceProfiles(scene) {
+  return scene.devices?.profiles?.length ? scene.devices.profiles : defaultTreeseedSceneDeviceConfig().profiles;
+}
+function resolveTreeseedSceneDeviceProfile(input) {
+  const profiles = listTreeseedSceneDeviceProfiles(input.scene);
+  const selected = input.device ?? input.scene.devices?.defaultProfile ?? "desktop";
+  const profile = profiles.find((entry) => entry.id === selected) ?? null;
+  if (!profile) {
+    return {
+      profile: null,
+      diagnostics: [sceneErrorDiagnostic("scene.device_unknown", `Unknown scene device profile: ${selected}.`, "device")]
+    };
+  }
+  return { profile, diagnostics: [] };
+}
+export {
+  defaultTreeseedSceneDeviceConfig,
+  listTreeseedSceneDeviceProfiles,
+  resolveTreeseedSceneDeviceProfile
+};

package/dist/scenes/diagnostics.d.ts

@@ -0,0 +1,5 @@
+import type { TreeseedSceneDiagnostic } from './types.js';
+export declare function sceneErrorDiagnostic(code: string, message: string, path?: string): TreeseedSceneDiagnostic;
+export declare function sceneWarningDiagnostic(code: string, message: string, path?: string): TreeseedSceneDiagnostic;
+export declare function hasTreeseedSceneErrors(diagnostics: TreeseedSceneDiagnostic[]): boolean;
+export declare function formatTreeseedSceneDiagnostics(diagnostics: TreeseedSceneDiagnostic[]): string[];

package/dist/scenes/diagnostics.js

@@ -0,0 +1,22 @@
+function sceneErrorDiagnostic(code, message, path) {
+  return { severity: "error", code, message, path };
+}
+function sceneWarningDiagnostic(code, message, path) {
+  return { severity: "warning", code, message, path };
+}
+function hasTreeseedSceneErrors(diagnostics) {
+  return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+}
+function formatTreeseedSceneDiagnostics(diagnostics) {
+  return diagnostics.map((diagnostic) => {
+    const prefix = diagnostic.severity === "error" ? "ERROR" : "WARN";
+    const location = diagnostic.path ? ` ${diagnostic.path}` : "";
+    return `${prefix} ${diagnostic.code}${location}: ${diagnostic.message}`;
+  });
+}
+export {
+  formatTreeseedSceneDiagnostics,
+  hasTreeseedSceneErrors,
+  sceneErrorDiagnostic,
+  sceneWarningDiagnostic
+};

package/dist/scenes/diagram-providers.d.ts

@@ -0,0 +1,2 @@
+import type { TreeseedSceneDiagramProvider } from './types.js';
+export declare function createBuiltInTreeseedSceneDiagramProvider(): TreeseedSceneDiagramProvider;