@treeseed/sdk 0.12.44 → 0.12.46

package/dist/reconcile/providers/railway-iac.js

@@ -1,6 +1,7 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { runRailwayIac } from "railway/iac";
+import { assertApiRailwaySourcePolicy, isApiRailwaySourcePolicyService } from "../../operations/services/railway-source-policy.js";
 function js(value) {
   return JSON.stringify(value);
 }
@@ -97,7 +98,13 @@ function renderPostgresEnv() {
     ["RAILWAY_DEPLOYMENT_DRAINING_SECONDS", js("60")]
   ]);
 }
+function normalizeIacScope(input) {
+  if (input.scope === "prod" || input.scope === "staging") return input.scope;
+  const environmentName = String(input.environmentName ?? "").trim().toLowerCase();
+  return environmentName === "production" || environmentName === "prod" ? "prod" : environmentName === "staging" ? "staging" : "local";
+}
 function renderRailwayIacProject(input) {
+  const scope = normalizeIacScope(input);
   const region = input.region?.trim() || "us-east4-eqdc4a";
   const tempParent = resolve(input.tenantRoot, ".treeseed", "tmp");
   mkdirSync(tempParent, { recursive: true });
@@ -145,6 +152,7 @@ function renderRailwayIacProject(input) {
     }
   }
   input.services.forEach((service, index) => {
+    assertApiRailwaySourcePolicy(scope, service);
     const serviceVar = id("svc", index);
     const invalidVariables = validateGeneratedVariables(service);
     if (invalidVariables.length > 0) {
@@ -232,7 +240,15 @@ function validateRailwayIacChangeSet(changeSet, desiredNames) {
   const created = new Set((changeSet?.changes ?? []).filter((change) => change.kind === "resource.create").map((change) => changeName(change)));
   for (const change of changeSet?.changes ?? []) {
     const name = changeName(change);
-    const sourceMode = desiredNames.serviceSourceModes?.[name] ?? desiredNames.serviceSourceModes?.[name.replace(/^(service|database)\./u, "")] ?? null;
+    const serviceName = name.replace(/^(service|database)\./u, "");
+    const sourceMode = desiredNames.serviceSourceModes?.[name] ?? desiredNames.serviceSourceModes?.[serviceName] ?? null;
+    const sourceRef = desiredNames.serviceSourceRefs?.[name] ?? desiredNames.serviceSourceRefs?.[serviceName] ?? null;
+    const sourceChanged = change.kind === "resource.update" && isRailwaySourceChange(change);
+    const imageSourceChange = sourceChanged && isRailwayImageSourceChange(change);
+    const gitSourceChange = sourceChanged && isRailwayGitSourceChange(change);
+    const desiredGitSource = sourceMode === "git" && typeof sourceRef === "string" && sourceRef.startsWith("github:");
+    const desiredImageSource = sourceMode === "image" && typeof sourceRef === "string" && sourceRef.startsWith("image:");
+    const apiPolicyService = isApiRailwaySourcePolicyService({ serviceName });
     if (change.kind === "resource.delete") {
       destructiveChanges.push(change.summary);
       blockedReasons.push(`Railway IaC plan would delete resource ${name || change.summary}; hosting reconciliation only updates or creates resources. Use the explicit destroy workflow for deletions.`);
@@ -240,12 +256,24 @@ function validateRailwayIacChangeSet(changeSet, desiredNames) {
         blockedReasons.push(`Railway IaC plan would delete desired resource ${name}.`);
       }
     }
-    if (desiredNames.scope === "staging" && change.kind === "resource.update" && isRailwayImageSourceChange(change) && (!sourceMode || sourceMode === "image")) {
+    if (desiredNames.scope === "staging" && sourceChanged && apiPolicyService && sourceMode === "git" && !gitSourceChange && !desiredGitSource) {
+      blockedReasons.push(`Railway IaC plan would change staging API resource ${name} source without confirming a GitHub source.`);
+    }
+    if (desiredNames.scope === "staging" && sourceChanged && imageSourceChange && !(apiPolicyService && sourceMode === "git" && (gitSourceChange || desiredGitSource))) {
       blockedReasons.push(`Railway IaC plan would switch staging resource ${name} to an image source.`);
     }
-    if (desiredNames.scope === "prod" && change.kind === "resource.update" && isRailwayGitSourceChange(change) && (!sourceMode || sourceMode === "git")) {
+    if (desiredNames.scope === "staging" && sourceChanged && (!sourceMode || sourceMode === "image")) {
+      blockedReasons.push(`Railway IaC plan would apply an image-backed desired source to staging resource ${name}.`);
+    }
+    if (desiredNames.scope === "prod" && sourceChanged && apiPolicyService && sourceMode === "image" && !imageSourceChange && !desiredImageSource) {
+      blockedReasons.push(`Railway IaC plan would change production API resource ${name} source without confirming an image source.`);
+    }
+    if (desiredNames.scope === "prod" && sourceChanged && gitSourceChange) {
       blockedReasons.push(`Railway IaC plan would switch production resource ${name} to a Git source.`);
     }
+    if (desiredNames.scope === "prod" && sourceChanged && (!sourceMode || sourceMode === "git")) {
+      blockedReasons.push(`Railway IaC plan would apply a Git-backed desired source to production resource ${name}.`);
+    }
   }
   return {
     ok: blockedReasons.length === 0,

package/dist/reconcile/providers/release-private.d.ts

@@ -11,6 +11,7 @@ export declare function runReleaseVerifyCommand(input: {
     status?: undefined;
     signal?: undefined;
     command?: undefined;
+    dependencies?: undefined;
     stdout?: undefined;
     stderr?: undefined;
 } | {
@@ -18,6 +19,15 @@ export declare function runReleaseVerifyCommand(input: {
     status: number | null;
     signal: NodeJS.Signals | null;
     command: import("../../index.js").TreeseedPackageCommand;
+    dependencies: {
+        status: "not-applicable";
+    } | {
+        status: "ready";
+    } | {
+        status: "restored";
+    } | {
+        status: "workspace-linked";
+    };
     stdout: string;
     stderr: string;
     skipped?: undefined;

package/dist/reconcile/providers/release-private.js

@@ -1,9 +1,43 @@
 import { spawn, spawnSync } from "node:child_process";
-import { mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { findTreeseedPackageAdapter } from "../../operations/services/package-adapters.js";
 import { checkedOutTemplateRepositories } from "../../operations/services/managed-repositories.js";
 import { runTreeseedGitText } from "../../operations/services/git-runner.js";
+import { ensureLocalWorkspaceLinks } from "../../operations/services/workspace-dependency-mode.js";
+function ensureReleaseVerifyDependencies(input) {
+  if (!existsSync(resolve(input.packageDir, "package.json")) || !existsSync(resolve(input.packageDir, "package-lock.json"))) {
+    return { status: "not-applicable" };
+  }
+  const env = { ...process.env, ...input.env ?? {} };
+  const inspection = spawnSync("npm", ["ls", "--depth=0", "--workspaces=false"], {
+    cwd: input.packageDir,
+    env,
+    encoding: "utf8"
+  });
+  if (inspection.status === 0) return { status: "ready" };
+  input.onProgress?.("Package dependencies are incomplete; restoring the standalone lockfile installation.");
+  const install = spawnSync("npm", [
+    "ci",
+    "--ignore-scripts",
+    "--workspaces=false",
+    "--no-audit",
+    "--no-fund"
+  ], {
+    cwd: input.packageDir,
+    env,
+    encoding: "utf8"
+  });
+  if (install.status !== 0) {
+    throw new Error([
+      "Standalone package dependency hydration failed before release verification.",
+      install.stderr,
+      install.stdout
+    ].filter(Boolean).join("\n").trim());
+  }
+  ensureLocalWorkspaceLinks(input.tenantRoot, { env: input.env });
+  return { status: "restored" };
+}
 async function runReleaseVerifyCommand(input) {
   const adapter = findTreeseedPackageAdapter(input.tenantRoot, input.packageId);
   if (!adapter) {
@@ -17,6 +51,15 @@ async function runReleaseVerifyCommand(input) {
       reason: `${input.packageId} has no release verify command.`
     };
   }
+  const dependencies = adapter.capabilities.localOnly ? (() => {
+    ensureLocalWorkspaceLinks(input.tenantRoot, { env: input.env });
+    return { status: "workspace-linked" };
+  })() : ensureReleaseVerifyDependencies({
+    tenantRoot: input.tenantRoot,
+    packageDir: adapter.dir,
+    env: input.env,
+    onProgress: input.onProgress
+  });
   const renderedCommand = [command.command, ...command.args].join(" ");
   input.onProgress?.(`Running ${input.packageId} release verification: ${renderedCommand}`);
   const started = Date.now();
@@ -53,6 +96,7 @@ async function runReleaseVerifyCommand(input) {
     status: result.status,
     signal: result.signal,
     command,
+    dependencies,
     stdout,
     stderr
   };

package/dist/scenes/builtin-plugins.js

@@ -15,6 +15,19 @@ function mailpitApiUrl(mailpitUrl, pathname) {
 function stringValue(value) {
   return typeof value === "string" ? value : "";
 }
+function shortRuntimeHash(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36).padStart(7, "0").slice(0, 10);
+}
+function sceneRuntimeValue(value, context) {
+  const runSlug = context.runId.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "").slice(0, 48);
+  const runShort = shortRuntimeHash(context.runId);
+  return value.replace(/\{\{\s*runId\s*\}\}/gu, context.runId).replace(/\{\{\s*runSlug\s*\}\}/gu, runSlug).replace(/\{\{\s*runShort\s*\}\}/gu, runShort);
+}
 function mailpitMessageId(value) {
   if (!value || typeof value !== "object") return "";
   const record = value;
@@ -57,6 +70,16 @@ function extractConfirmationUrl(body) {
   const relative = body.match(/(?:\/auth\/confirm-email\?[^"' <>\n]+|\/team-invites\/[^"' <>\n]+\/accept)/u)?.[0];
   return relative ?? null;
 }
+function resolveMailpitConfirmationUrl(confirmationUrl, context) {
+  try {
+    const parsed = new URL(confirmationUrl);
+    if (parsed.pathname === "/auth/confirm-email" || /^\/team-invites\/[^/]+\/accept$/u.test(parsed.pathname)) {
+      return context.resolveUrl(`${parsed.pathname}${parsed.search}${parsed.hash}`);
+    }
+  } catch {
+  }
+  return confirmationUrl.startsWith("/") ? context.resolveUrl(confirmationUrl) : confirmationUrl;
+}
 async function sleep(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -68,7 +91,11 @@ async function navigateScenePage(page, url) {
   let lastError = null;
   for (let attempt = 1; attempt <= 3; attempt += 1) {
     try {
-      await page.goto(url, { waitUntil: "domcontentloaded", timeout: 45e3 });
+      const response = await page.goto(url, { waitUntil: "domcontentloaded", timeout: 45e3 });
+      const status = response?.status();
+      if (typeof status === "number" && status >= 400) {
+        throw sceneErrorDiagnostic("scene.navigation_http_error", `Navigation to ${response?.url() ?? url} returned HTTP ${status}.`, "workflow.action.goto");
+      }
       return;
     } catch (error) {
       lastError = error;
@@ -76,7 +103,7 @@ async function navigateScenePage(page, url) {
       await sleep(500 * attempt);
     }
   }
-  throw lastError instanceof Error ? lastError : new Error(String(lastError ?? `Navigation failed for ${url}`));
+  throw lastError && typeof lastError === "object" && "code" in lastError ? lastError : lastError instanceof Error ? lastError : new Error(String(lastError ?? `Navigation failed for ${url}`));
 }
 async function assertionReport(kind, action, selector) {
   const startedAt = /* @__PURE__ */ new Date();
@@ -132,7 +159,7 @@ function createBuiltInTreeseedScenePlugins() {
             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);
+            await locator.fill(sceneRuntimeValue(action.fill.value, context));
             return { ok: true, diagnostics: [] };
           }
         },
@@ -208,7 +235,11 @@ function createBuiltInTreeseedScenePlugins() {
           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;
+            const raw = action.mailpitConfirmLatest;
+            const mailpitUrl = sceneRuntimeValue(raw.mailpitUrl, context);
+            const email = sceneRuntimeValue(raw.email, context);
+            const subjectIncludes = raw.subjectIncludes ? sceneRuntimeValue(raw.subjectIncludes, context) : void 0;
+            const { displayInboxSeconds, displayMessageSeconds } = raw;
             try {
               const listResponse = await fetch(mailpitApiUrl(mailpitUrl, "/api/v1/messages"));
               if (!listResponse.ok) {
@@ -233,7 +264,7 @@ function createBuiltInTreeseedScenePlugins() {
               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 resolvedUrl = resolveMailpitConfirmationUrl(confirmationUrl, context);
               const mailpitBase = mailpitUrl.endsWith("/") ? mailpitUrl : `${mailpitUrl}/`;
               if (displayInboxSeconds && displayInboxSeconds > 0) {
                 const search = new URL("search", mailpitBase);

package/dist/scenes/device-matrix.js

@@ -63,6 +63,8 @@ async function runTreeseedSceneDeviceMatrix(input) {
       scene: input.scene,
       environment: input.environment,
       device,
+      browser: input.browser,
+      authRole: input.authRole,
       record: input.record,
       artifactMode: input.artifactMode,
       mode: input.mode,

package/dist/scenes/environment.js

@@ -39,7 +39,7 @@ async function prepareTreeseedSceneEnvironment(input) {
       baseUrl = healthUrl(existing);
     } else {
       try {
-        const result = await startTreeseedManagedDev({ cwd: input.projectRoot, surfaces: "web,api,operations-runner", webRuntime: "local", env: input.env });
+        const result = await startTreeseedManagedDev({ cwd: input.projectRoot, surfaces: "web,api", webRuntime: "local", env: input.env });
         instances = result.instances;
         const web = result.instances.find((entry) => entry.surface === "web" || entry.id === "web");
         started = Boolean(web && running(web));

package/dist/scenes/runner.js

@@ -1,4 +1,4 @@
-import { copyFileSync, writeFileSync } from "node:fs";
+import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { sceneActionKind, sceneExpectationKinds } from "./schema.js";
 import { planTreeseedScene, validateTreeseedScene } from "./planner.js";
@@ -126,6 +126,7 @@ function planForInput(input, validation) {
   }
   const scene = validation.scene;
   const environment = input.environment ?? scene.target.environment;
+  const browser = input.browser ?? scene.target.browser;
   const workflowSteps = scene.workflow.map((step) => ({
     id: step.id,
     title: step.title,
@@ -145,7 +146,7 @@ function planForInput(input, validation) {
     title: scene.title,
     environment,
     baseUrl: scene.target.baseUrl,
-    browser: scene.target.browser,
+    browser,
     viewport: scene.target.viewport,
     workflowSteps,
     enabledActions: actionIds,
@@ -174,6 +175,20 @@ function planForInput(input, validation) {
 function canContinueAfterFailure(scene, step) {
   return scene.runtime.mode === "demo" || scene.runtime.mode === "training" || step.demoOnly === true || step.continueOnFailure === true || scene.runtime.failure.continueOnFailure === true;
 }
+function sceneWithRunOverrides(scene, input) {
+  if (!input.authRole) return scene;
+  return {
+    ...scene,
+    setup: {
+      ...scene.setup,
+      auth: {
+        ...scene.setup.auth ?? {},
+        required: input.authRole !== "anonymous",
+        role: scene.setup.auth?.role ?? input.authRole
+      }
+    }
+  };
+}
 async function runTreeseedScene(input) {
   const startedAt = now();
   const validation = validationForInput(input);
@@ -188,7 +203,8 @@ async function runTreeseedScene(input) {
       diagnostics: validation.diagnostics
     });
   }
-  const scene = validation.scene;
+  const scene = sceneWithRunOverrides(validation.scene, input);
+  const browser = input.browser ?? scene.target.browser;
   const deviceResolution = resolveTreeseedSceneDeviceProfile({ scene, device: input.device });
   if (!deviceResolution.profile && deviceResolution.diagnostics.some((entry) => entry.severity === "error")) {
     return reportFromBlock({
@@ -197,7 +213,7 @@ async function runTreeseedScene(input) {
       runId: input.runId ?? null,
       startedAt,
       environment: input.environment ?? scene.target.environment,
-      browser: scene.target.browser,
+      browser,
       diagnostics: deviceResolution.diagnostics
     });
   }
@@ -214,7 +230,7 @@ async function runTreeseedScene(input) {
       runId: input.runId ?? null,
       startedAt,
       environment: plan.environment,
-      browser: scene.target.browser,
+      browser,
       device,
       diagnostics: plan.diagnostics
     });
@@ -263,7 +279,7 @@ async function runTreeseedScene(input) {
       runId: paths.runId,
       startedAt,
       environment: plan.environment,
-      browser: scene.target.browser,
+      browser,
       device,
       diagnostics: [...plan.diagnostics, ...setupDiagnostics],
       artifacts,
@@ -289,7 +305,7 @@ async function runTreeseedScene(input) {
       runId: paths.runId,
       startedAt,
       environment: plan.environment,
-      browser: scene.target.browser,
+      browser,
       device,
       diagnostics: [...plan.diagnostics, ...setupDiagnostics, ...baseUrl.diagnostics],
       artifacts,
@@ -338,7 +354,7 @@ async function runTreeseedScene(input) {
   let sessionClosed = false;
   try {
     session = await adapter.launch({
-      browser: scene.target.browser,
+      browser,
       viewport: capture.viewport,
       videoSize: capture.videoSize,
       recordVideoDir: videoDir,
@@ -380,7 +396,7 @@ async function runTreeseedScene(input) {
       timeline.push("network", entry, currentStepId);
     });
     if (tracePath) await session.startTracing?.();
-    if (scene.setup.auth?.role && scene.setup.auth.role !== "anonymous") {
+    if (scene.setup.auth?.role && scene.setup.auth.role !== "anonymous" && scene.setup.auth.seedOnly !== true) {
       const signInDiagnostics = await signInTreeseedSceneVisualAuditRole({
         page: session.page,
         baseUrl: baseUrl.baseUrl,
@@ -446,6 +462,7 @@ async function runTreeseedScene(input) {
           projectRoot: input.projectRoot,
           scene,
           environment: plan.environment,
+          runId: paths.runId,
           session,
           baseUrl: baseUrl.baseUrl,
           timeline,
@@ -507,15 +524,10 @@ async function runTreeseedScene(input) {
           await session.page.screenshot({ path: viewportScreenshotPath, fullPage: false });
           artifacts.viewportScreenshotPaths?.push(viewportScreenshotPath);
           timeline.push("screenshot.viewport", { path: viewportScreenshotPath }, step.id);
-          if (screenshotPath && recordingVideo) {
-            copyFileSync(viewportScreenshotPath, screenshotPath);
-            artifacts.screenshotPaths.push(screenshotPath);
-            timeline.push("screenshot", { path: screenshotPath, captureKind: "viewport-copy" }, step.id);
-          }
         } catch {
         }
       }
-      if (screenshotPath && !recordingVideo) {
+      if (screenshotPath) {
         try {
           await session.page.screenshot({ path: screenshotPath, fullPage: true });
           artifacts.screenshotPaths.push(screenshotPath);
@@ -637,7 +649,7 @@ async function runTreeseedScene(input) {
     durationMs: duration(startedAt, finishedAt),
     environment: plan.environment,
     baseUrl: baseUrl.baseUrl,
-    browser: scene.target.browser,
+    browser,
     device,
     capture,
     workflowStatus,

package/dist/scenes/schema.js

@@ -6,7 +6,7 @@ import {
   TREESEED_SCENE_SCHEMA_VERSION
 } from "./types.js";
 const FILESYSTEM_SAFE_SCENE_ID = /^[a-z0-9][a-z0-9._-]*$/u;
-const TOP_LEVEL_FIELDS = /* @__PURE__ */ new Set(["schemaVersion", "id", "title", "description", "audience", "mode", "target", "devices", "setup", "artifacts", "workflow", "chapters", "overlays", "diagrams", "render", "runtime", "training", "visualAudit", "xScenario"]);
+const TOP_LEVEL_FIELDS = /* @__PURE__ */ new Set(["schemaVersion", "id", "title", "description", "audience", "journey", "mode", "target", "devices", "setup", "artifacts", "workflow", "chapters", "overlays", "diagrams", "render", "runtime", "training", "visualAudit", "xScenario"]);
 const FILESYSTEM_SAFE_CHECKPOINT_ID = /^[a-z0-9][a-z0-9._-]*$/u;
 const DIAGRAM_PLACEMENTS = ["overlay", "interstitial", "standalone"];
 const CAPTION_FORMATS = ["vtt", "srt"];
@@ -108,6 +108,34 @@ function stringArrayField(record, field, path, diagnostics) {
   });
   return strings;
 }
+function stateRefArray(record, field, path, diagnostics) {
+  const value = arrayField(record, field, path, diagnostics);
+  if (!value) return void 0;
+  const refs = [];
+  value.forEach((entry, index) => {
+    const entryPath = `${path}.${field}[${index}]`;
+    if (!isRecord(entry)) {
+      diagnostics.push(sceneErrorDiagnostic("scene.invalid_state_ref", `Expected ${field} entry to be an object.`, entryPath));
+      return;
+    }
+    refs.push({ key: requireString(entry, "key", entryPath, diagnostics), kind: requireString(entry, "kind", entryPath, diagnostics) });
+  });
+  return refs;
+}
+function parseJourney(record, diagnostics) {
+  const journey = objectField(record, "journey", "manifest", diagnostics);
+  if (!journey) return void 0;
+  const kind = optionalString(journey, "kind");
+  if (kind && !["service", "page", "visual-audit"].includes(kind)) diagnostics.push(sceneErrorDiagnostic("scene.invalid_journey_kind", `Unsupported journey kind: ${kind}.`, "journey.kind"));
+  return {
+    kind: kind === "page" || kind === "visual-audit" ? kind : "service",
+    proves: stringArrayField(journey, "proves", "journey", diagnostics),
+    minimumSteps: positiveNumberField(journey, "minimumSteps", void 0, "journey", diagnostics),
+    requiresInteractiveAction: booleanField(journey, "requiresInteractiveAction", false, "journey", diagnostics),
+    producesState: stateRefArray(journey, "producesState", "journey", diagnostics),
+    consumesState: stateRefArray(journey, "consumesState", "journey", diagnostics)
+  };
+}
 function enumArrayField(record, field, allowed, defaultValue, path, diagnostics) {
   const value = record[field];
   if (value === void 0) return defaultValue;
@@ -379,7 +407,7 @@ function parseSetup(value, targetEnvironment, diagnostics) {
   const dev = objectField(record, "dev", "setup", diagnostics);
   if (dev) setup.dev = { required: booleanField(dev, "required", false, "setup.dev", diagnostics), command: optionalString(dev, "command"), reuseExisting: booleanField(dev, "reuseExisting", true, "setup.dev", diagnostics) };
   const auth = objectField(record, "auth", "setup", diagnostics);
-  if (auth) setup.auth = { profile: optionalString(auth, "profile"), required: booleanField(auth, "required", false, "setup.auth", diagnostics), ...optionalString(auth, "role") ? { role: optionalString(auth, "role") } : {} };
+  if (auth) setup.auth = { profile: optionalString(auth, "profile"), required: booleanField(auth, "required", false, "setup.auth", diagnostics), seedOnly: booleanField(auth, "seedOnly", false, "setup.auth", diagnostics), ...optionalString(auth, "role") ? { role: optionalString(auth, "role") } : {} };
   const seed = objectField(record, "seed", "setup", diagnostics);
   if (seed) {
     const environments = (arrayField(seed, "environments", "setup.seed", diagnostics) ?? [targetEnvironment]).map((entry, index) => parseEnvironment(entry, `setup.seed.environments[${index}]`, diagnostics, targetEnvironment));
@@ -970,6 +998,7 @@ function parseTreeseedSceneManifest(value, diagnostics) {
     title,
     description: optionalString(value, "description"),
     audience: stringArrayField(value, "audience", "manifest", diagnostics),
+    journey: parseJourney(value, diagnostics),
     mode,
     target,
     devices,

package/dist/scenes/types.d.ts

@@ -99,6 +99,7 @@ export type TreeseedSceneSetup = {
         profile?: string;
         required: boolean;
         role?: TreeseedSceneVisualAuditRole;
+        seedOnly?: boolean;
     };
     seed?: {
         name?: string;
@@ -393,6 +394,20 @@ export type TreeseedSceneManifest = {
     title: string;
     description?: string;
     audience: string[];
+    journey?: {
+        kind: 'service' | 'page' | 'visual-audit';
+        proves?: string[];
+        minimumSteps?: number;
+        requiresInteractiveAction?: boolean;
+        producesState?: Array<{
+            key: string;
+            kind: string;
+        }>;
+        consumesState?: Array<{
+            key: string;
+            kind: string;
+        }>;
+    };
     mode: TreeseedSceneMode;
     target: TreeseedSceneTarget;
     devices: TreeseedSceneDeviceConfig;
@@ -469,6 +484,8 @@ export type TreeseedSceneRunOptions = {
     scene: string | TreeseedSceneManifest;
     environment?: TreeseedSceneEnvironment;
     device?: TreeseedSceneDeviceProfileId;
+    browser?: TreeseedSceneBrowser;
+    authRole?: TreeseedSceneVisualAuditRole;
     record?: boolean;
     artifactMode?: 'full' | 'screenshots';
     runId?: string;
@@ -491,6 +508,8 @@ export type TreeseedSceneDeviceMatrixOptions = {
     scene: string;
     environment?: TreeseedSceneEnvironment;
     devices?: TreeseedSceneDeviceProfileId[];
+    browser?: TreeseedSceneBrowser;
+    authRole?: TreeseedSceneVisualAuditRole;
     record?: boolean;
     artifactMode?: 'full' | 'screenshots';
     mode?: TreeseedSceneExecutionMode;
@@ -967,6 +986,7 @@ export type TreeseedSceneOperationWaitOptions = {
     projectRoot: string;
     scene: TreeseedSceneManifest;
     environment: TreeseedSceneEnvironment;
+    runId: string;
     baseUrl: string;
     spec: TreeseedSceneOperationWaitSpec;
     linkedOperationIds?: string[];
@@ -1812,9 +1832,12 @@ export type TreeseedSceneLocator = {
 };
 export type TreeseedScenePage = {
     goto(url: string, options?: {
-        waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+        waitUntil?: 'load' | 'domcontentLoaded' | 'domcontentloaded' | 'networkidle';
         timeout?: number;
-    }): Promise<void>;
+    }): Promise<{
+        status(): number;
+        url(): string;
+    } | null | undefined>;
     url(): string;
     locator(selector: string): TreeseedSceneLocator;
     getByTestId(testId: string): TreeseedSceneLocator;

package/dist/scenes/visual-audit-fixtures.js

@@ -52,10 +52,11 @@ function configuredValue(input, name) {
   }
 }
 function serviceHeaders(input) {
+  const localDevServiceSecret = input?.environment === "local" ? "treeseed-web-service-dev-secret" : null;
   return {
     "content-type": "application/json",
     "x-treeseed-service-id": configuredValue(input, "TREESEED_API_WEB_SERVICE_ID") ?? configuredValue(input, "TREESEED_WEB_SERVICE_ID") ?? "web",
-    "x-treeseed-service-secret": configuredValue(input, "TREESEED_API_WEB_SERVICE_SECRET") ?? configuredValue(input, "TREESEED_WEB_SERVICE_SECRET") ?? "treeseed-web-service-dev-secret"
+    "x-treeseed-service-secret": process.env.TREESEED_API_WEB_SERVICE_SECRET?.trim() ?? process.env.TREESEED_WEB_SERVICE_SECRET?.trim() ?? localDevServiceSecret ?? configuredValue(input, "TREESEED_API_WEB_SERVICE_SECRET") ?? configuredValue(input, "TREESEED_WEB_SERVICE_SECRET") ?? "treeseed-web-service-dev-secret"
   };
 }
 async function sleep(ms) {
@@ -123,12 +124,13 @@ async function seedVisualAuditFixtures(input) {
 async function ensureTreeseedSceneVisualAuditRoleFixtures(input) {
   const diagnostics = [];
   const roles = [...new Set(input.roles)].filter((role) => role !== "anonymous");
-  diagnostics.push(...await seedVisualAuditFixtures({
+  const seedDiagnostics = await seedVisualAuditFixtures({
     baseUrl: input.baseUrl,
     roles,
     projectRoot: input.projectRoot,
     environment: input.environment
-  }));
+  });
+  let roleSetupFailed = false;
   for (const role of roles) {
     const user = treeseedSceneVisualAuditUserForRole(role);
     if (!user) continue;
@@ -138,6 +140,7 @@ async function ensureTreeseedSceneVisualAuditRoleFixtures(input) {
       continue;
     } catch (error) {
       if (!isAuthFailure(error)) {
+        roleSetupFailed = true;
         diagnostics.push(sceneWarningDiagnostic(
           "scene.visual_audit_fixture_unavailable",
           `Visual audit fixture setup for ${role} failed against ${input.baseUrl}: ${error instanceof Error ? error.message : String(error ?? "local fixture API is unavailable")}. Authenticated screenshots require the local API and database to be healthy.`,
@@ -160,12 +163,14 @@ async function ensureTreeseedSceneVisualAuditRoleFixtures(input) {
       if (payload.confirmationToken) {
         await client.confirmWebEmail({ token: payload.confirmationToken });
       } else if (payload.confirmationRequired) {
+        roleSetupFailed = true;
         diagnostics.push(sceneWarningDiagnostic("scene.visual_audit_fixture_unavailable", `Visual audit fixture user ${user.email} requires email confirmation, but the local API did not return a confirmation token.`, "roles"));
       }
     } catch (error) {
       try {
         await client.webSignIn({ login: user.email, password: user.password });
       } catch {
+        roleSetupFailed = true;
         diagnostics.push(sceneWarningDiagnostic(
           "scene.visual_audit_fixture_unavailable",
           `Visual audit fixture setup for ${role} failed against ${input.baseUrl}: ${error instanceof Error ? error.message : String(error ?? "local fixture API is unavailable")}. Authenticated screenshots require the local API and database to be healthy.`,
@@ -174,6 +179,7 @@ async function ensureTreeseedSceneVisualAuditRoleFixtures(input) {
       }
     }
   }
+  if (roleSetupFailed) diagnostics.unshift(...seedDiagnostics);
   return diagnostics;
 }
 async function signInTreeseedSceneVisualAuditRole(input) {