@opencraw/studio 0.0.3 → 0.0.5

package/dist/index.esm.js

@@ -7,6 +7,34 @@ import { BrowserClient, HttpClient, readRecipeSource, parseInputRecipe, parseOut
 import { writeFile } from 'node:fs/promises';
 import { existsSync, createReadStream } from 'node:fs';
 
+const sentencePartSchema = z.object({
+  kind: z.enum(['word', 'pill', 'code']),
+  text: z.string()
+});
+const outlineNodeBase = {
+  path: z.string(),
+  stepType: z.string(),
+  sentence: z.array(sentencePartSchema),
+  step: z.record(z.string(), z.unknown())
+};
+const outlineCardSchema = z.object({
+  ...outlineNodeBase,
+  kind: z.literal('card'),
+  custom: z.boolean()
+});
+const outlineBracketSchema = z.lazy(() => z.object({
+  ...outlineNodeBase,
+  kind: z.literal('bracket'),
+  stepType: z.enum(['forEach', 'paginate', 'if']),
+  children: z.array(outlineNodeSchema),
+  elseChildren: z.array(outlineNodeSchema).optional()
+}));
+const outlineNodeSchema = z.union([outlineCardSchema, outlineBracketSchema]);
+const outlineViewSchema = z.object({
+  recipe: z.record(z.string(), z.unknown()),
+  steps: z.array(outlineNodeSchema)
+});
+
 /** A budget for a sample run; never authored into a recipe, only asked for by the caller. */
 const sampleBudgetSchema = z.object({
   maxRecords: z.number().int().positive().optional(),
@@ -39,7 +67,22 @@ const fetchStartPageCommandSchema = z.object({
   type: z.literal('fetch-start-page'),
   recipeId: z.string().min(1)
 });
-const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema]);
+/**
+ * Writes a recipe file from an edited outline: the server converts it back
+ * to the recipe's JSON (`scope-outline`'s `outlineToRecipe`) and saves it
+ * exactly as `save-recipe` would. Kept as its own command, rather than
+ * asking the Steps tab to run the outline↔recipe mappers itself, so that
+ * conversion stays server-side code (it already is: `@opencraw/studio`'s
+ * root export also carries Node-only slices, so the UI never imports
+ * runtime code from it, only types — see `apps/studio-ui`'s `steps-outline`
+ * for where this is called from).
+ */
+const saveOutlineCommandSchema = z.object({
+  type: z.literal('save-outline'),
+  path: z.string().min(1),
+  outline: outlineViewSchema
+});
+const studioCommandSchema = z.discriminatedUnion('type', [openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema]);
 
 /** Why a sample run stopped before finishing on its own; mirrors `@opencraw/core`'s `RecipeReport.stoppedBy`. */
 const stoppedBySchema = z.enum(['sample-maxRecords', 'sample-maxPages', 'sample-maxMs']);
@@ -85,7 +128,9 @@ const recipeListingSchema = z.object({
   id: z.string().optional(),
   issues: z.array(recipeIssueSchema),
   /** The file's JSON, pretty-printed: the JSON tab's starting text (see `save-recipe` for how an edit is written back). */
-  text: z.string()
+  text: z.string(),
+  /** The Steps tab's view of this file's `steps`, from `@opencraw/studio`'s `scope-outline` slice. `input` recipes only; `undefined` for an `output` or `unknown` file, which has no steps to show. */
+  outline: outlineViewSchema.optional()
 });
 /** What `open-workspace` answers with: every recipe file directly inside the folder. */
 const workspaceViewSchema = z.object({
@@ -326,6 +371,261 @@ async function handleFetchStartPage(state, command) {
   };
 }
 
+/**
+ * The outline model: an `InputRecipe`'s `steps` (and only `steps`; the rest
+ * of the recipe passes through untouched, see `recipe-to-outline.mapper.ts`)
+ * read as a tree of cards and brackets instead of raw JSON.
+ *
+ * A **card** is one step that reads as a sentence (`sentence`, built by
+ * `card-sentence.mapper.ts`). A **bracket** is a container step (`forEach`,
+ * `paginate`, `if`) whose body is itself a list of cards/brackets: the
+ * indentation the plan doc describes is this nesting, not a separate layout
+ * concept. Both kinds carry `step`, the step's own raw JSON exactly as
+ * parsed (every key, in its original order): `outline-to-recipe.mapper.ts`
+ * rebuilds the recipe from it, substituting only the (possibly edited)
+ * `children`/`elseChildren` for whatever `steps`/`else` value `step` itself
+ * holds, so an edit to one field never disturbs another's position or a
+ * step type this outline cannot make sense of.
+ */
+/** The step types the outline renders as a bracket: their body is nested steps, not a single value. */
+const BRACKET_STEP_TYPES = ['forEach', 'paginate', 'if'];
+function isBracket(node) {
+  return node.kind === 'bracket';
+}
+function isBracketStepType(type) {
+  return BRACKET_STEP_TYPES.includes(type);
+}
+
+/** Step types the plan doc names as always going to a "custom" card: nothing here renders their meaning as a sentence. */
+const ALWAYS_CUSTOM = new Set(['evaluate', 'hook', 'captcha']);
+/**
+ * Turns one step's raw JSON into its sentence parts (word/pill/code), the
+ * way the plan doc's examples read: *Go to…*, *Read… from…*, *For each… in…
+ * → one record*, and so on. Never throws: a step type this cannot read
+ * becomes a short, honest fallback with `custom: true`, so the outline never
+ * drops a step for looking unfamiliar.
+ *
+ * @param step - A step's raw JSON (its `type` and whatever fields it has).
+ * @returns The sentence parts, and whether they are a real reading or a fallback.
+ */
+function cardSentence(step) {
+  const type = typeof step.type === 'string' ? step.type : undefined;
+  if (type === undefined || ALWAYS_CUSTOM.has(type)) return fallback(type);
+  const build = BUILDERS[type];
+  if (build === undefined) return fallback(type);
+  try {
+    return {
+      parts: build(step),
+      custom: false
+    };
+  } catch {
+    return fallback(type);
+  }
+}
+function fallback(type) {
+  return {
+    parts: [word(type ?? 'custom step')],
+    custom: true
+  };
+}
+function word(text) {
+  return {
+    kind: 'word',
+    text
+  };
+}
+function pill(text) {
+  return {
+    kind: 'pill',
+    text
+  };
+}
+function code(text) {
+  return {
+    kind: 'code',
+    text
+  };
+}
+/** A field that names an id: shown as a pill, `fallbackText` when it is absent. */
+function pillField(step, key, fallbackText) {
+  const value = step[key];
+  return pill(typeof value === 'string' && value.length > 0 ? value : fallbackText);
+}
+/** A field shown as a literal (a selector, a template, a value): stringified when it is not already a string. */
+function codeField(step, key, fallbackText = '') {
+  const value = step[key];
+  if (typeof value === 'string') return code(value);
+  if (value === undefined) return code(fallbackText);
+  return code(safeJson(value));
+}
+function safeJson(value) {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+/** `selector` or `target`, whichever the step gives (`step.contract.ts`'s `TargetFields`: exactly one is present). */
+function targetField(step) {
+  if (typeof step.target === 'string') return code(step.target);
+  return codeField(step, 'selector');
+}
+const BUILDERS = {
+  goto: step => [word('Go to'), codeField(step, 'url')],
+  click: step => [word('Click'), targetField(step)],
+  fill: step => [word('Fill'), targetField(step), word('with'), codeField(step, 'value')],
+  press: step => [word('Press'), codeField(step, 'key'), word('in'), targetField(step)],
+  select: step => [word('Choose'), selectChoice(step), word('in'), targetField(step)],
+  scroll: step => [word('Scroll to'), codeField(step, 'to')],
+  wait: step => [word('Wait for'), waitFor(step)],
+  screenshot: step => [word('Screenshot'), codeField(step, 'path')],
+  request: step => [word('Request'), code(`${typeof step.method === 'string' ? step.method : 'GET'} `), codeField(step, 'url')],
+  extract: step => [word('Read'), pillField(step, 'id', '(unnamed)'), word('from'), pillField(step, 'from', 'page'), word('←'), codeField(step, 'selector')],
+  set: step => [word('Set'), pillField(step, 'id', '(unnamed)'), word('to'), codeField(step, 'value')],
+  collect: step => [word('Collect'), codeField(step, 'value'), word('into'), pillField(step, 'into', '(unnamed)')],
+  forEach: step => forEachSentence(step),
+  paginate: step => paginateSentence(step),
+  if: step => [word('If'), codeField(step, 'test')],
+  emit: step => emitSentence(step)
+};
+function selectChoice(step) {
+  if (typeof step.value === 'string') return code(step.value);
+  if (typeof step.label === 'string') return code(step.label);
+  if (typeof step.index === 'number') return code(String(step.index));
+  if (Array.isArray(step.values)) return code(step.values.join(', '));
+  return code('');
+}
+function waitFor(step) {
+  if (typeof step.selector === 'string') return code(step.selector);
+  if (typeof step.ms === 'number') return code(`${step.ms}ms`);
+  if (typeof step.state === 'string') return code(step.state);
+  return code('');
+}
+function forEachSentence(step) {
+  const parts = [word('For each'), pillField(step, 'as', '(item)'), word('in'), typeof step.over === 'string' ? pill(step.over) : targetField(step)];
+  if (step.emit !== undefined) parts.push(word('→'), word('one record'));
+  return parts;
+}
+function paginateSentence(step) {
+  const parts = [word('For every page')];
+  const next = step.next;
+  if (next !== null && typeof next === 'object') {
+    const record = next;
+    if (typeof record.selector === 'string') parts.push(word('via'), code(record.selector));else if (typeof record.url === 'string') parts.push(word('via'), code(record.url));else if (typeof record.jsonpath === 'string') parts.push(word('via'), code(record.jsonpath));
+  }
+  if (typeof step.until === 'string') parts.push(word('until'), code(step.until));
+  return parts;
+}
+function emitSentence(step) {
+  if (typeof step.output === 'string') return [word('Emit'), word('to'), pill(step.output)];
+  return [word('Emit')];
+}
+
+/**
+ * Reads a recipe's `steps` as an outline. Works on whatever JSON parsed
+ * (not a validated `InputRecipe`): a recipe mid-edit in the JSON tab may be
+ * missing fields or have the wrong shape, and the outline still has to
+ * render something rather than crash the tab. Anything that is not a
+ * well-formed step becomes a custom card holding what was there; anything
+ * that is not an object at the top becomes an outline with no steps.
+ *
+ * @param content - The recipe's parsed JSON (the JSON tab's own `JSON.parse` of its text).
+ * @returns The outline: the untouched top-level record plus the step tree.
+ */
+function recipeToOutline(content) {
+  const recipe = isRecord(content) ? content : {};
+  const steps = Array.isArray(recipe.steps) ? recipe.steps : [];
+  return {
+    recipe,
+    steps: stepsToNodes(steps, 'steps')
+  };
+}
+function stepsToNodes(steps, pathPrefix) {
+  return steps.map((step, index) => stepToNode(step, `${pathPrefix}.${index}`));
+}
+function stepToNode(step, path) {
+  if (!isRecord(step)) {
+    return {
+      kind: 'card',
+      path,
+      stepType: 'unknown',
+      sentence: [{
+        kind: 'word',
+        text: 'custom step'
+      }],
+      step: {},
+      custom: true
+    };
+  }
+  const stepType = typeof step.type === 'string' ? step.type : 'unknown';
+  const {
+    parts,
+    custom
+  } = cardSentence(step);
+  if (!isBracketStepType(stepType)) return {
+    kind: 'card',
+    path,
+    stepType,
+    sentence: parts,
+    step,
+    custom
+  };
+  const children = Array.isArray(step.steps) ? stepsToNodes(step.steps, `${path}.steps`) : [];
+  const elseChildren = stepType === 'if' && Array.isArray(step.else) ? stepsToNodes(step.else, `${path}.else`) : undefined;
+  return {
+    kind: 'bracket',
+    path,
+    stepType,
+    sentence: parts,
+    step,
+    children,
+    ...(elseChildren !== undefined && {
+      elseChildren
+    })
+  };
+}
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Rebuilds a recipe from its outline: `recipe`'s keys, in their original
+ * order, with `steps` (when the recipe had one) replaced by the outline's
+ * (possibly edited) step tree. A card's own raw `step` is used as-is; a
+ * bracket's `step` supplies every field but `steps`/`else`, which come from
+ * `children`/`elseChildren` instead, put back at the position `step` itself
+ * held that key at (or appended, for a bracket a `+` menu just added, whose
+ * `step` never had one) — this, together with `recipe-to-outline.mapper.ts`
+ * always keeping the step's whole original object, is what makes
+ * `recipe → outline → recipe` preserve every key and its order.
+ *
+ * @param outline - An outline, from `recipe-to-outline.mapper.ts` or edited by the UI.
+ * @returns The recipe's plain JSON, ready for `save-recipe`.
+ */
+function outlineToRecipe(outline) {
+  if (!('steps' in outline.recipe) && outline.steps.length === 0) return {
+    ...outline.recipe
+  };
+  return {
+    ...outline.recipe,
+    steps: nodesToSteps(outline.steps)
+  };
+}
+function nodesToSteps(nodes) {
+  return nodes.map(node => nodeToStep(node));
+}
+function nodeToStep(node) {
+  if (!isBracket(node)) return node.step;
+  const keys = Object.keys(node.step);
+  const step = {};
+  for (const key of keys) {
+    if (key === 'steps') step.steps = nodesToSteps(node.children);else if (key === 'else' && node.stepType === 'if') step.else = nodesToSteps(node.elseChildren ?? []);else step[key] = node.step[key];
+  }
+  if (!keys.includes('steps')) step.steps = nodesToSteps(node.children);
+  if (node.stepType === 'if' && node.elseChildren !== undefined && !keys.includes('else')) step.else = nodesToSteps(node.elseChildren);
+  return step;
+}
+
 /**
  * Opens a recipe folder: every `.json`/`.jsonl` recipe directly inside it
  * (core's own directory reading, so relative `file:` URLs resolve the same
@@ -366,7 +666,10 @@ async function openWorkspace(folder) {
       kind,
       id,
       issues,
-      text: `${JSON.stringify(content, null, 2)}\n`
+      text: `${JSON.stringify(content, null, 2)}\n`,
+      // The Steps tab needs steps to render: an output/unknown file has none. recipeToOutline never
+      // throws, so this covers a file that fails validation too (its outline just has "custom" cards).
+      outline: kind === 'input' ? recipeToOutline(content) : undefined
     }))
   };
 }
@@ -559,6 +862,28 @@ async function handleStopRun(state, _command) {
   };
 }
 
+/**
+ * Handles `save-outline`: the Steps tab's edits, as the outline it holds
+ * locally, converted back to the recipe's JSON (`scope-outline`'s
+ * `outlineToRecipe`, so the conversion runs here rather than in the
+ * browser) and written the same way `save-recipe` writes the JSON tab's
+ * edits. Every connected client, including the sender, is told the
+ * workspace changed, so both tabs re-fetch it and stay in sync.
+ *
+ * @param state - The server state holding the connected sockets.
+ * @param command - The command: the file path and the edited outline.
+ * @returns `{ saved: true }` once the write has completed.
+ */
+async function handleSaveOutline(state, command) {
+  await saveRecipe(command.path, outlineToRecipe(command.outline));
+  broadcast(state, {
+    type: 'workspace-changed'
+  });
+  return {
+    saved: true
+  };
+}
+
 /**
  * Handles `save-recipe`: writes the file (see `recipe-workspace/save-recipe.use-case.ts`
  * for the pretty-printing and its round-trip guarantee), then tells every
@@ -826,6 +1151,10 @@ function dispatch(command, state) {
       {
         return handleFetchStartPage(state, command);
       }
+    case 'save-outline':
+      {
+        return handleSaveOutline(state, command);
+      }
   }
 }
 function respondJson(response, status, body) {
@@ -882,5 +1211,5 @@ async function main(argv) {
   process.on('SIGTERM', shutdown);
 }
 
-export { fetchStartPage, fetchStartPageCommandSchema, loadRecipePair, main, openWorkspace, openWorkspaceCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveRecipe, saveRecipeCommandSchema, startPageViewSchema, startStudioServer, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, traceLineEventSchema, workspaceChangedEventSchema, workspaceViewSchema };
+export { fetchStartPage, fetchStartPageCommandSchema, loadRecipePair, main, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, startPageViewSchema, startStudioServer, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, traceLineEventSchema, workspaceChangedEventSchema, workspaceViewSchema };
 //# sourceMappingURL=index.esm.js.map

package/dist/src/index.d.ts

@@ -5,6 +5,6 @@ export { openWorkspace, saveRecipe } from './recipe-workspace/index.js';
 export { runSample, loadRecipePair } from './sample-run/index.js';
 export type { RecipePair, SampleRunCallbacks, SampleRunHandle, SampleRunRecord, SampleRunResult, SampleStoppedBy } from './sample-run/index.js';
 export { fetchStartPage } from './page-snapshot/index.js';
-export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, studioCommandSchema, stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, } from './studio-api/index.js';
-export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, StudioCommand, StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, } from './studio-api/index.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, studioCommandSchema, stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, } from './studio-api/index.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, StudioCommand, StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, } from './studio-api/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/scope-outline/card-sentence.mapper.d.ts

@@ -0,0 +1,18 @@
+import type { SentencePart } from './outline.model.js';
+export interface StepSentence {
+    parts: SentencePart[];
+    /** `true` when this is a fallback (an unrecognised type, or one of `ALWAYS_CUSTOM`): the UI shows `step`'s raw JSON instead of trusting `parts` alone. */
+    custom: boolean;
+}
+/**
+ * Turns one step's raw JSON into its sentence parts (word/pill/code), the
+ * way the plan doc's examples read: *Go to…*, *Read… from…*, *For each… in…
+ * → one record*, and so on. Never throws: a step type this cannot read
+ * becomes a short, honest fallback with `custom: true`, so the outline never
+ * drops a step for looking unfamiliar.
+ *
+ * @param step - A step's raw JSON (its `type` and whatever fields it has).
+ * @returns The sentence parts, and whether they are a real reading or a fallback.
+ */
+export declare function cardSentence(step: Record<string, unknown>): StepSentence;
+//# sourceMappingURL=card-sentence.mapper.d.ts.map

package/dist/src/scope-outline/index.d.ts

@@ -0,0 +1,8 @@
+export { BRACKET_STEP_TYPES, isBracket, isBracketStepType } from './outline.model.js';
+export type { OutlineBracket, OutlineCard, OutlineNode, RecipeOutline, SentencePart, BracketStepType } from './outline.model.js';
+export { cardSentence } from './card-sentence.mapper.js';
+export type { StepSentence } from './card-sentence.mapper.js';
+export { recipeToOutline } from './recipe-to-outline.mapper.js';
+export { outlineToRecipe } from './outline-to-recipe.mapper.js';
+export { scopeAtPath } from './scope-at-path.algorithm.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/scope-outline/outline-to-recipe.mapper.d.ts

@@ -0,0 +1,17 @@
+import type { RecipeOutline } from './outline.model.js';
+/**
+ * Rebuilds a recipe from its outline: `recipe`'s keys, in their original
+ * order, with `steps` (when the recipe had one) replaced by the outline's
+ * (possibly edited) step tree. A card's own raw `step` is used as-is; a
+ * bracket's `step` supplies every field but `steps`/`else`, which come from
+ * `children`/`elseChildren` instead, put back at the position `step` itself
+ * held that key at (or appended, for a bracket a `+` menu just added, whose
+ * `step` never had one) — this, together with `recipe-to-outline.mapper.ts`
+ * always keeping the step's whole original object, is what makes
+ * `recipe → outline → recipe` preserve every key and its order.
+ *
+ * @param outline - An outline, from `recipe-to-outline.mapper.ts` or edited by the UI.
+ * @returns The recipe's plain JSON, ready for `save-recipe`.
+ */
+export declare function outlineToRecipe(outline: RecipeOutline): Record<string, unknown>;
+//# sourceMappingURL=outline-to-recipe.mapper.d.ts.map

package/dist/src/scope-outline/outline.model.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The outline model: an `InputRecipe`'s `steps` (and only `steps`; the rest
+ * of the recipe passes through untouched, see `recipe-to-outline.mapper.ts`)
+ * read as a tree of cards and brackets instead of raw JSON.
+ *
+ * A **card** is one step that reads as a sentence (`sentence`, built by
+ * `card-sentence.mapper.ts`). A **bracket** is a container step (`forEach`,
+ * `paginate`, `if`) whose body is itself a list of cards/brackets: the
+ * indentation the plan doc describes is this nesting, not a separate layout
+ * concept. Both kinds carry `step`, the step's own raw JSON exactly as
+ * parsed (every key, in its original order): `outline-to-recipe.mapper.ts`
+ * rebuilds the recipe from it, substituting only the (possibly edited)
+ * `children`/`elseChildren` for whatever `steps`/`else` value `step` itself
+ * holds, so an edit to one field never disturbs another's position or a
+ * step type this outline cannot make sense of.
+ */
+/** One piece of a card's sentence: plain wording, a bound id (a "pill"), or a literal (a selector, a template, a value) shown as code. */
+export interface SentencePart {
+    kind: 'word' | 'pill' | 'code';
+    text: string;
+}
+/** The step types the outline renders as a bracket: their body is nested steps, not a single value. */
+export declare const BRACKET_STEP_TYPES: readonly ["forEach", "paginate", "if"];
+export type BracketStepType = typeof BRACKET_STEP_TYPES[number];
+interface OutlineNodeBase {
+    /** The step's JSON path in the recipe, e.g. `steps.3.steps.1`. */
+    path: string;
+    /** The step's own `type`, or `'unknown'` when `step` has none. */
+    stepType: string;
+    sentence: SentencePart[];
+    /** The step's raw JSON, exactly as parsed: never dropped, always editable as JSON. */
+    step: Record<string, unknown>;
+}
+/** One step the outline could not, or chose not to, read as a bracket: a leaf card. */
+export interface OutlineCard extends OutlineNodeBase {
+    kind: 'card';
+    /** `true` when `card-sentence.mapper.ts` could not build a real sentence: the UI shows `step` as raw, editable JSON instead. */
+    custom: boolean;
+}
+/** A container step (`forEach`, `paginate`, `if`): its body nested one level in. */
+export interface OutlineBracket extends OutlineNodeBase {
+    kind: 'bracket';
+    stepType: BracketStepType;
+    children: OutlineNode[];
+    /** `if` only: the `else` branch, when the step has one. */
+    elseChildren?: OutlineNode[];
+}
+export type OutlineNode = OutlineCard | OutlineBracket;
+/** A recipe read as an outline: `recipe` is everything but the derived view of `steps`, kept so the mapper back can restore it untouched. */
+export interface RecipeOutline {
+    recipe: Record<string, unknown>;
+    steps: OutlineNode[];
+}
+export declare function isBracket(node: OutlineNode): node is OutlineBracket;
+export declare function isBracketStepType(type: string): type is BracketStepType;
+export {};
+//# sourceMappingURL=outline.model.d.ts.map

package/dist/src/scope-outline/recipe-to-outline.mapper.d.ts

@@ -0,0 +1,14 @@
+import type { RecipeOutline } from './outline.model.js';
+/**
+ * Reads a recipe's `steps` as an outline. Works on whatever JSON parsed
+ * (not a validated `InputRecipe`): a recipe mid-edit in the JSON tab may be
+ * missing fields or have the wrong shape, and the outline still has to
+ * render something rather than crash the tab. Anything that is not a
+ * well-formed step becomes a custom card holding what was there; anything
+ * that is not an object at the top becomes an outline with no steps.
+ *
+ * @param content - The recipe's parsed JSON (the JSON tab's own `JSON.parse` of its text).
+ * @returns The outline: the untouched top-level record plus the step tree.
+ */
+export declare function recipeToOutline(content: unknown): RecipeOutline;
+//# sourceMappingURL=recipe-to-outline.mapper.d.ts.map

package/dist/src/scope-outline/scope-at-path.algorithm.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The ids visible at a step path: the built-ins (`page`, `start`, `vars`),
+ * every id bound above it on the same path, and the `as`/`next.as` name of
+ * every loop it sits inside. This is core's own binding rule
+ * (`bindingsAt`, `recipe-loading/recipe-binding.validator.ts`): the walk
+ * that decides what a `{{ }}` template, `from` or `over` can name is the one
+ * `opencraw validate` already runs, not a copy of it.
+ *
+ * `content` is the recipe's raw parsed JSON, the same loosely-typed value
+ * `recipe-to-outline.mapper.ts` reads: a recipe mid-edit may not parse as a
+ * valid `InputRecipe` (a missing `mode`, a step with the wrong shape), and
+ * this never throws for that — it falls back to just the built-ins.
+ *
+ * @param content - The recipe's parsed JSON.
+ * @param path - A step's JSON path, e.g. `steps.3.steps.1`.
+ * @returns The ids in scope at that path, `page`/`start`/`vars` first.
+ */
+export declare function scopeAtPath(content: unknown, path: string): string[];
+//# sourceMappingURL=scope-at-path.algorithm.d.ts.map

package/dist/src/studio-api/command.contract.d.ts

@@ -35,6 +35,21 @@ export declare const fetchStartPageCommandSchema: z.ZodObject<{
     type: z.ZodLiteral<"fetch-start-page">;
     recipeId: z.ZodString;
 }, z.core.$strip>;
+/**
+ * Writes a recipe file from an edited outline: the server converts it back
+ * to the recipe's JSON (`scope-outline`'s `outlineToRecipe`) and saves it
+ * exactly as `save-recipe` would. Kept as its own command, rather than
+ * asking the Steps tab to run the outline↔recipe mappers itself, so that
+ * conversion stays server-side code (it already is: `@opencraw/studio`'s
+ * root export also carries Node-only slices, so the UI never imports
+ * runtime code from it, only types — see `apps/studio-ui`'s `steps-outline`
+ * for where this is called from).
+ */
+export declare const saveOutlineCommandSchema: z.ZodObject<{
+    type: z.ZodLiteral<"save-outline">;
+    path: z.ZodString;
+    outline: z.ZodType<import("./outline-view.contract").OutlineView, unknown, z.core.$ZodTypeInternals<import("./outline-view.contract").OutlineView, unknown>>;
+}, z.core.$strip>;
 export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"open-workspace">;
     folder: z.ZodString;
@@ -55,6 +70,10 @@ export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"fetch-start-page">;
     recipeId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"save-outline">;
+    path: z.ZodString;
+    outline: z.ZodType<import("./outline-view.contract").OutlineView, unknown, z.core.$ZodTypeInternals<import("./outline-view.contract").OutlineView, unknown>>;
 }, z.core.$strip>], "type">;
 export type SampleBudget = z.infer<typeof sampleBudgetSchema>;
 export type OpenWorkspaceCommand = z.infer<typeof openWorkspaceCommandSchema>;
@@ -62,6 +81,7 @@ export type RunSampleCommand = z.infer<typeof runSampleCommandSchema>;
 export type StopRunCommand = z.infer<typeof stopRunCommandSchema>;
 export type SaveRecipeCommand = z.infer<typeof saveRecipeCommandSchema>;
 export type FetchStartPageCommand = z.infer<typeof fetchStartPageCommandSchema>;
+export type SaveOutlineCommand = z.infer<typeof saveOutlineCommandSchema>;
 /** Every command the UI can send the server, over HTTP POST. */
 export type StudioCommand = z.infer<typeof studioCommandSchema>;
 //# sourceMappingURL=command.contract.d.ts.map

package/dist/src/studio-api/index.d.ts

@@ -1,5 +1,5 @@
-export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, studioCommandSchema } from './command.contract.js';
-export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, StudioCommand } from './command.contract.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, studioCommandSchema } from './command.contract.js';
+export type { SampleBudget, OpenWorkspaceCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, StudioCommand } from './command.contract.js';
 export { stoppedBySchema, traceLineEventSchema, recordEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema } from './event.contract.js';
 export type { StoppedBy, TraceLineEvent, RecordEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent } from './event.contract.js';
 export { recipeIssueSchema, recipeListingSchema, workspaceViewSchema } from './workspace-view.contract.js';
@@ -8,4 +8,6 @@ export { sampleRunRecordSchema, sampleRunViewSchema } from './sample-run-view.co
 export type { SampleRunRecord, SampleRunView } from './sample-run-view.contract.js';
 export { startPageViewSchema } from './start-page-view.contract.js';
 export type { StartPageView } from './start-page-view.contract.js';
+export { sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema } from './outline-view.contract.js';
+export type { SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView } from './outline-view.contract.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/studio-api/outline-view.contract.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+/** One piece of a card's sentence: plain wording, a bound id (a "pill"), or a literal shown as code. Mirrors `scope-outline/outline.model.ts`'s `SentencePart`: the wire shape for the UI. */
+export interface SentencePart {
+    kind: 'word' | 'pill' | 'code';
+    text: string;
+}
+interface OutlineNodeBase {
+    path: string;
+    stepType: string;
+    sentence: SentencePart[];
+    step: Record<string, unknown>;
+}
+/** A leaf step, read as a sentence (or, when `custom`, not read as one: the UI shows `step`'s raw JSON instead). */
+export interface OutlineCard extends OutlineNodeBase {
+    kind: 'card';
+    custom: boolean;
+}
+/** A container step (`forEach`, `paginate`, `if`), its body nested one level in. */
+export interface OutlineBracket extends OutlineNodeBase {
+    kind: 'bracket';
+    stepType: 'forEach' | 'paginate' | 'if';
+    children: OutlineNode[];
+    elseChildren?: OutlineNode[];
+}
+export type OutlineNode = OutlineCard | OutlineBracket;
+/** The outline the UI renders and edits: the recipe's other keys untouched, plus its steps as a tree. */
+export interface OutlineView {
+    recipe: Record<string, unknown>;
+    steps: OutlineNode[];
+}
+export declare const sentencePartSchema: z.ZodType<SentencePart>;
+export declare const outlineCardSchema: z.ZodType<OutlineCard>;
+export declare const outlineBracketSchema: z.ZodType<OutlineBracket>;
+export declare const outlineNodeSchema: z.ZodType<OutlineNode>;
+export declare const outlineViewSchema: z.ZodType<OutlineView>;
+export {};
+//# sourceMappingURL=outline-view.contract.d.ts.map