@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/domain/src/builder/builder-document.d.ts

@@ -0,0 +1,95 @@
+export type StepKeyword = "Given" | "When" | "Then" | "And" | "But" | "*";
+export declare const STEP_KEYWORDS: readonly StepKeyword[];
+/** A table as a feature file writes it: the header row, then the data rows (cells as text). */
+export type BlockTable = readonly (readonly string[])[];
+interface BlockBase {
+    /** The keyword the step is written with, when it differs from the one the builder would choose (kept from a loaded file). */
+    readonly keyword?: StepKeyword;
+    /** Pause here when the builder runs the scenario (saved as a `# checkpoint` comment after the block). */
+    readonly checkpoint?: boolean;
+}
+/** One registered atomic sentence: an action, an assertion, an identity or a navigation block. */
+export interface SentenceBlock extends BlockBase {
+    readonly kind: "sentence";
+    /** The registered pattern, e.g. `{actor} publishes the note {string}`. */
+    readonly pattern: string;
+    /** One text per parameter, as written (a string without its quotes; an output reference such as `$Ada.note`). */
+    readonly values: readonly string[];
+    /** The DataTable a sentence ending in ":" takes. */
+    readonly table?: BlockTable;
+}
+/**
+ * The generic Repeat ×N container. Saved as the action's declared plural when its body is one block that has one
+ * (`Ada publishes 3 notes`), else as N copies of its body between `# repeat N times` and `# end repeat`.
+ */
+export interface RepeatBlock extends BlockBase {
+    readonly kind: "repeat";
+    readonly count: number;
+    /** Atomic blocks without their own keyword, checkpoint or nesting. */
+    readonly body: readonly SentenceBlock[];
+}
+/**
+ * A "Run together" group, saved as `these steps run together:` with one row per block, or with `form: "inline"` as
+ * one step, `<block> and <block> … at the same time` (the form a loaded file used is kept). A group with a block that
+ * has its own table is saved with a doc string (backlog 113): each block on a line, its table under it; `form:
+ * "doc-string"` keeps that form for a group without one (a loaded file's).
+ */
+export interface TogetherBlock extends BlockBase {
+    readonly kind: "together";
+    readonly body: readonly SentenceBlock[];
+    readonly form?: "inline" | "doc-string";
+}
+/** A step the builder cannot express (a custom step, a step group, an unknown sentence); kept and saved as written. */
+export interface TextBlock extends BlockBase {
+    readonly kind: "text";
+    readonly keyword: StepKeyword;
+    readonly text: string;
+    readonly table?: BlockTable;
+    /** Its doc string, as written (backlog 113: a run-together group whose parts the builder cannot place). */
+    readonly docString?: string;
+    /** Why the builder shows it as text. */
+    readonly reason: string;
+}
+export type BuilderBlock = SentenceBlock | RepeatBlock | TogetherBlock | TextBlock;
+export interface BuilderScenario {
+    readonly name: string;
+    readonly tags: readonly string[];
+    /** Free text under the scenario line. */
+    readonly description: readonly string[];
+    readonly blocks: readonly BuilderBlock[];
+}
+export interface BuilderFeature {
+    readonly name: string;
+    readonly tags: readonly string[];
+    /** Free text under the Feature line. */
+    readonly description: readonly string[];
+    readonly scenarios: readonly BuilderScenario[];
+}
+/** Where a loaded file had something the builder cannot keep; saving over that file is refused. */
+export interface NotRepresentable {
+    /** 1-based line in the file. */
+    readonly line: number;
+    readonly text: string;
+    readonly reason: string;
+    /** `step`: kept as a text block (saving keeps it); `structure`: not kept (Background, outline, rule, doc string, comment). */
+    readonly scope: "step" | "structure";
+}
+export interface LoadedFeature {
+    readonly feature: BuilderFeature;
+    readonly notRepresentable: readonly NotRepresentable[];
+    /** True when saving the loaded document writes back everything the file said (no `structure` item). */
+    readonly lossless: boolean;
+    /** The feature's Background, read only: its steps as blocks (the builder does not save it, so such a file is not overwritten). */
+    readonly background?: {
+        readonly line: number;
+        readonly name: string;
+        readonly blocks: readonly BuilderBlock[];
+    };
+}
+/** Given (setup), When (doing), Then (checking). */
+export type StepClass = "given" | "when" | "then";
+/** The keyword the builder writes for a block of this class after a block of `previous`. */
+export declare function autoKeyword(kind: StepClass, previous: StepClass | undefined): StepKeyword;
+/** The class a written keyword puts a step in (`And`, `But` and `*` continue the previous one). */
+export declare function keywordClass(keyword: StepKeyword, previous: StepClass | undefined): StepClass;
+export {};

package/core/domain/src/builder/builder-document.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const STEP_KEYWORDS = ["Given", "When", "Then", "And", "But", "*"];
+const CLASS_KEYWORD = { given: "Given", when: "When", then: "Then" };
+export function autoKeyword(kind, previous) {
+    return kind === previous ? "And" : CLASS_KEYWORD[kind];
+}
+export function keywordClass(keyword, previous) {
+    if (keyword === "Given")
+        return "given";
+    if (keyword === "When")
+        return "when";
+    if (keyword === "Then")
+        return "then";
+    return previous ?? "given";
+}

package/core/domain/src/builder/builder-edit.d.ts

@@ -0,0 +1,70 @@
+import type { BlockTable, BuilderScenario, SentenceBlock } from "./builder-document.js";
+import type { BuilderPalette, PaletteBlock } from "./builder-palette.js";
+export type BuilderEdit = {
+    readonly op: "add";
+    readonly pattern: string;
+    readonly at?: number;
+    readonly values?: readonly string[];
+    readonly table?: BlockTable;
+} | {
+    readonly op: "move";
+    readonly from: number;
+    readonly to: number;
+} | {
+    readonly op: "remove";
+    readonly at: number;
+} | {
+    readonly op: "repeat";
+    readonly from: number;
+    readonly to: number;
+    readonly count: number;
+}
+/** `form: "inline"`: the group saves as one `… and … at the same time` step. */
+ | {
+    readonly op: "together";
+    readonly from: number;
+    readonly to: number;
+    readonly form?: "inline";
+} | {
+    readonly op: "ungroup";
+    readonly at: number;
+} | {
+    readonly op: "count";
+    readonly at: number;
+    readonly count: number;
+} | {
+    readonly op: "values";
+    readonly at: number;
+    readonly inner?: number;
+    readonly values: readonly string[];
+} | {
+    readonly op: "table";
+    readonly at: number;
+    readonly inner?: number;
+    readonly table: BlockTable;
+} | {
+    readonly op: "checkpoint";
+    readonly at: number;
+    readonly on: boolean;
+} | {
+    readonly op: "actors";
+    readonly names: readonly string[];
+} | {
+    readonly op: "rename";
+    readonly name: string;
+};
+/** The names a new actor gets, in order: the first one the scenario does not use yet. */
+export declare const ACTOR_ROSTER: readonly string[];
+/** The first roster name not in `taken`, then Actor1, Actor2, … */
+export declare function nextActorName(taken: readonly string[]): string;
+/**
+ * A new block of the palette with default values: the first actor in scope, a field's default or first option. The
+ * parameter or column that introduces actors gets a new name instead (`cast`: every actor the scenario has).
+ */
+export declare function newBlock(palette: BuilderPalette, pattern: string, actors?: readonly string[], cast?: readonly string[]): SentenceBlock;
+/**
+ * A table with the shape's columns (optional ones left out; the first optional one when every column is optional, so
+ * a table is never written without columns) and one row of defaults; an introducing column gets a new name.
+ */
+export declare function defaultTable(about: PaletteBlock, actors: readonly string[], cast?: readonly string[]): string[][];
+export declare function applyEdit(scenario: BuilderScenario, edit: BuilderEdit, palette: BuilderPalette): BuilderScenario;

package/core/domain/src/builder/builder-edit.js

@@ -0,0 +1,190 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { MAX_REPEAT } from "../sentences/sentence-book.js";
+import { BuilderError } from "./builder-error.js";
+import { checkScenario, togetherProblems } from "./builder-check.js";
+const ACTOR = /^[A-Za-z][A-Za-z0-9_-]*$/;
+export const ACTOR_ROSTER = ["Ada", "Grace", "Alan", "Barbara", "Edsger", "Frances", "Donald", "Margaret", "Dennis", "Radia", "Ken", "Katherine"];
+export function nextActorName(taken) {
+    const free = ACTOR_ROSTER.find((name) => !taken.includes(name));
+    if (free)
+        return free;
+    for (let index = 1;; index++)
+        if (!taken.includes(`Actor${index}`))
+            return `Actor${index}`;
+}
+export function newBlock(palette, pattern, actors = [], cast = actors) {
+    const about = palette.block(pattern);
+    if (!about)
+        throw new BuilderError(`"${pattern}" is not a block of this lab`);
+    const values = about.fields.map((field) => {
+        if (about.introduces?.parameter === field.index)
+            return nextActorName(cast);
+        if (field.default !== undefined)
+            return String(field.default);
+        if (field.options?.length)
+            return field.options[0];
+        if (field.kind === "actor")
+            return actors[0] ?? "Ada";
+        if (field.kind === "int" || field.kind === "count")
+            return String(field.min ?? 1);
+        if (field.kind === "route")
+            return "/";
+        return "";
+    });
+    return { kind: "sentence", pattern, values, ...(about.table ? { table: defaultTable(about, actors, cast) } : {}) };
+}
+export function defaultTable(about, actors, cast = actors) {
+    const required = about.table.columns.filter((column) => !column.optional);
+    const columns = required.length ? required : about.table.columns.slice(0, 1);
+    const row = columns.map((column) => column.name === about.introduces?.column ? nextActorName(cast) : column.values?.length ? column.values[0] : column.kind === "actor" ? (actors[0] ?? "Ada") : column.kind === "integer" ? "0" : column.kind === "boolean" ? "false" : "");
+    return [columns.map((column) => column.name), row];
+}
+export function applyEdit(scenario, edit, palette) {
+    const blocks = [...scenario.blocks];
+    const at = (index) => {
+        if (!Number.isInteger(index) || index < 0 || index >= blocks.length)
+            throw new BuilderError(`There is no block ${index + 1}`);
+        return blocks[index];
+    };
+    const range = (from, to) => {
+        at(from);
+        at(to);
+        if (to < from)
+            throw new BuilderError("The range ends before it starts");
+        const picked = blocks.slice(from, to + 1);
+        if (picked.some((block) => block.kind !== "sentence"))
+            throw new BuilderError("Only atomic blocks can go inside a Repeat or a Run together group");
+        return picked.map(({ keyword: _keyword, checkpoint: _checkpoint, ...rest }) => rest);
+    };
+    switch (edit.op) {
+        case "add": {
+            const index = edit.at ?? blocks.length;
+            if (!Number.isInteger(index) || index < 0 || index > blocks.length)
+                throw new BuilderError(`Cannot add a block at ${index + 1}`);
+            const scope = checkScenario(scenario, palette);
+            const block = newBlock(palette, edit.pattern, scope.scopes[index]?.actors.length ? scope.scopes[index].actors : scope.actors, scope.actors);
+            blocks.splice(index, 0, { ...block, ...(edit.values ? { values: [...edit.values] } : {}), ...(edit.table ? { table: edit.table } : {}) });
+            break;
+        }
+        case "move": {
+            const block = at(edit.from);
+            if (!Number.isInteger(edit.to) || edit.to < 0 || edit.to >= blocks.length)
+                throw new BuilderError(`Cannot move a block to ${edit.to + 1}`);
+            blocks.splice(edit.from, 1);
+            blocks.splice(edit.to, 0, block);
+            break;
+        }
+        case "remove":
+            at(edit.at);
+            blocks.splice(edit.at, 1);
+            break;
+        case "repeat": {
+            if (!Number.isSafeInteger(edit.count) || edit.count < 1 || edit.count > MAX_REPEAT)
+                throw new BuilderError(`A repeat count must be between 1 and ${MAX_REPEAT}`);
+            const body = range(edit.from, edit.to);
+            blocks.splice(edit.from, body.length, { kind: "repeat", count: edit.count, body });
+            break;
+        }
+        case "together": {
+            if (edit.form !== undefined && edit.form !== "inline")
+                throw new BuilderError(`Unknown Run together form ${String(edit.form)}`);
+            if (!(edit.form === "inline" ? palette.atTheSameTime : palette.together))
+                throw new BuilderError("This lab registers no run-together sentence");
+            const body = range(edit.from, edit.to);
+            if (body.length < 2)
+                throw new BuilderError("Run together needs at least two blocks");
+            const group = { kind: "together", body, ...(edit.form === "inline" ? { form: "inline" } : {}) };
+            const [problem] = togetherProblems(group, palette);
+            if (problem)
+                throw new BuilderError(problem.message, problem.inner);
+            blocks.splice(edit.from, body.length, group);
+            break;
+        }
+        case "ungroup": {
+            const block = at(edit.at);
+            if (block.kind !== "repeat" && block.kind !== "together")
+                throw new BuilderError("Only a Repeat or a Run together group can be ungrouped");
+            blocks.splice(edit.at, 1, ...block.body);
+            break;
+        }
+        case "count": {
+            const block = at(edit.at);
+            if (block.kind !== "repeat")
+                throw new BuilderError("Only a Repeat has a count");
+            if (!Number.isSafeInteger(edit.count) || edit.count < 1 || edit.count > MAX_REPEAT)
+                throw new BuilderError(`A repeat count must be between 1 and ${MAX_REPEAT}`);
+            blocks[edit.at] = { ...block, count: edit.count };
+            break;
+        }
+        case "values":
+        case "table": {
+            const block = at(edit.at);
+            const change = (atom) => {
+                if (edit.op === "values") {
+                    const about = palette.block(atom.pattern);
+                    if (!Array.isArray(edit.values) || edit.values.length !== (about?.fields.length ?? atom.values.length) || edit.values.some((value) => typeof value !== "string"))
+                        throw new BuilderError(`"${atom.pattern}" takes ${about?.fields.length ?? atom.values.length} value(s)`);
+                    return { ...atom, values: [...edit.values] };
+                }
+                if (!palette.block(atom.pattern)?.table)
+                    throw new BuilderError(`"${atom.pattern}" takes no table`);
+                if (!Array.isArray(edit.table) || edit.table.some((row) => !Array.isArray(row) || row.some((cell) => typeof cell !== "string")))
+                    throw new BuilderError("A table is rows of text cells");
+                return { ...atom, table: edit.table.map((row) => [...row]) };
+            };
+            if (block.kind === "sentence" && edit.inner === undefined)
+                blocks[edit.at] = change(block);
+            else if ((block.kind === "repeat" || block.kind === "together") && edit.inner !== undefined) {
+                const body = [...block.body];
+                if (!body[edit.inner])
+                    throw new BuilderError(`Block ${edit.at + 1} has no inner block ${edit.inner + 1}`);
+                body[edit.inner] = change(body[edit.inner]);
+                blocks[edit.at] = { ...block, body };
+            }
+            else
+                throw new BuilderError(block.kind === "text" ? "A text block is kept as written; edit it in the file" : "Name the inner block to change");
+            break;
+        }
+        case "checkpoint": {
+            const block = at(edit.at);
+            const { checkpoint: _old, ...rest } = block;
+            blocks[edit.at] = (edit.on ? { ...rest, checkpoint: true } : rest);
+            break;
+        }
+        case "actors": {
+            const names = [...edit.names];
+            const bad = names.find((name) => typeof name !== "string" || !ACTOR.test(name));
+            if (bad !== undefined || !names.length)
+                throw new BuilderError(`Actor names are letters, digits, "_" or "-", starting with a letter${bad !== undefined ? ` (not "${bad}")` : ""}`);
+            if (new Set(names).size !== names.length)
+                throw new BuilderError("An actor is named twice");
+            const cast = checkScenario(scenario, palette).actors;
+            const again = names.filter((name) => cast.includes(name));
+            if (again.length)
+                throw new BuilderError(`${again.join(", ")} ${again.length === 1 ? "is" : "are"} already in the cast`);
+            const exists = palette.book.entries.find((entry) => entry.kind === "identity" && entry.introduces?.column !== undefined);
+            const column = exists?.introduces?.column;
+            const where = exists ? blocks.findIndex((block) => block.kind === "sentence" && block.pattern === exists.pattern.text && !!block.table?.[0]?.includes(column)) : -1;
+            const found = where >= 0 ? blocks[where] : undefined;
+            if (found?.table) {
+                const header = found.table[0];
+                const rows = names.map((name) => header.map((cell, index) => (cell === column ? name : found.table[1]?.[index] ?? "")));
+                blocks[where] = { ...found, table: [...found.table, ...rows] };
+            }
+            else if (exists) {
+                blocks.unshift({ kind: "sentence", pattern: exists.pattern.text, values: [], table: [[exists.introduces.column], ...names.map((name) => [name])] });
+            }
+            else
+                throw new BuilderError("This lab registers no sentence that introduces several actors");
+            break;
+        }
+        case "rename":
+            if (typeof edit.name !== "string" || !edit.name.trim() || /[\r\n]/.test(edit.name))
+                throw new BuilderError("A scenario name is one non-empty line");
+            return { ...scenario, name: edit.name };
+        default:
+            throw new BuilderError(`Unknown edit ${String(edit.op)}`);
+    }
+    return { ...scenario, blocks };
+}

package/core/domain/src/builder/builder-error.d.ts

@@ -0,0 +1,8 @@
+export declare class BuilderError extends Error {
+    /** The body block of a Repeat or Run together group it concerns. */
+    readonly inner?: number | undefined;
+    readonly name = "BuilderError";
+    constructor(message: string, 
+    /** The body block of a Repeat or Run together group it concerns. */
+    inner?: number | undefined);
+}

package/core/domain/src/builder/builder-error.js

@@ -0,0 +1,11 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export class BuilderError extends Error {
+    inner;
+    name = "BuilderError";
+    constructor(message, 
+    inner) {
+        super(message);
+        this.inner = inner;
+    }
+}

package/core/domain/src/builder/builder-palette.d.ts

@@ -0,0 +1,101 @@
+import type { ParameterKind } from "../sentences/sentence-pattern.js";
+import type { OutputKind } from "../sentences/output-reference.js";
+import type { SentenceBook, SentenceEntry } from "../sentences/sentence-book.js";
+import type { TableColumn, TableShape } from "../sentences/table-shape.js";
+import type { StepClass } from "./builder-document.js";
+/** What the lab says about one parameter of a sentence (from the action input it maps to). */
+export interface ParameterHint {
+    readonly label?: string;
+    /** The values it may take (a choice input, the lab's apps, its routes). */
+    readonly options?: readonly string[];
+    readonly min?: number;
+    readonly max?: number;
+    readonly default?: string | number;
+}
+/** What the lab says about the block behind a sentence (the application builds it from the registry). */
+export interface BlockInfo {
+    readonly title?: string;
+    /** The integration id, or `lab` for the framework's generic sentences. */
+    readonly group?: string;
+    readonly via?: string;
+    /** The app a UI block drives. */
+    readonly app?: string;
+    /** Resources the scheduler serializes (the action's declared resources). */
+    readonly resources?: readonly string[];
+    readonly mutates?: boolean;
+    /** `false`: exploration never picks it. */
+    readonly explore?: false;
+    /** False when the block cannot run in the environment the palette was built for. */
+    readonly available?: boolean;
+    readonly reason?: string;
+    /** One hint per parameter, by position. */
+    readonly parameters?: readonly (ParameterHint | undefined)[];
+}
+export type AtomicKind = "action" | "assertion" | "identity" | "navigation" | "time" | "condition";
+/** A generated input for one parameter. */
+export interface BlockField {
+    /** Position among the sentence's parameters. */
+    readonly index: number;
+    readonly kind: ParameterKind;
+    readonly label: string;
+    readonly options?: readonly string[];
+    readonly min?: number;
+    readonly max?: number;
+    readonly default?: string | number;
+    /** An `{int}` or `{string}` may name an earlier step's output instead (`$Ada.note`). */
+    readonly references: boolean;
+}
+export interface PaletteBlock {
+    readonly pattern: string;
+    readonly owner: string;
+    readonly kind: AtomicKind;
+    /** Given, When or Then: which keyword the builder writes it with. */
+    readonly class: StepClass;
+    readonly group: string;
+    readonly title: string;
+    readonly via?: string;
+    readonly app?: string;
+    readonly resources: readonly string[];
+    readonly mutates: boolean;
+    /** `false`: model-based exploration never picks it (a negative control, for example). */
+    readonly explore?: false;
+    readonly available: boolean;
+    readonly reason?: string;
+    readonly fields: readonly BlockField[];
+    /** The generated table editor: typed columns (choices, integers, booleans, actors) and how many rows. */
+    readonly table?: {
+        readonly columns: readonly TableColumn[];
+        readonly rows: "one" | "many";
+    };
+    /** The declared plural a Repeat ×N of this block saves as. */
+    readonly plural?: string;
+    /** Outputs later blocks may reference. */
+    readonly outputs?: Readonly<Record<string, OutputKind>>;
+    /** An identity block: the parameter or the table column that names the actors it introduces (new names, not a choice of existing ones). */
+    readonly introduces?: {
+        readonly parameter?: number;
+        readonly column?: string;
+    };
+}
+export declare class BuilderPalette {
+    readonly book: SentenceBook;
+    readonly blocks: readonly PaletteBlock[];
+    /** The sentence a "Run together" group saves as, when the lab registers one. */
+    readonly together: string | undefined;
+    /** The inline run-together sentence (`{steps} at the same time`) a group with `form: "inline"` saves as. */
+    readonly atTheSameTime: string | undefined;
+    private readonly byPattern;
+    private constructor();
+    /** Every atomic sentence of the book as a block; `info` adds what the lab knows (titles, resources, options, availability). */
+    static from(book: SentenceBook, info?: (entry: SentenceEntry) => BlockInfo | undefined): BuilderPalette;
+    block(pattern: string): PaletteBlock | undefined;
+    /** The table shape a block's sentence takes. */
+    shape(pattern: string): TableShape | undefined;
+    /** Given for identities, When for actions, advancing time and opening an app, Then for assertions and navigation checks. */
+    private static classOf;
+    /** The palette as the panel receives it (plain JSON). */
+    toJSON(): {
+        blocks: readonly PaletteBlock[];
+        together?: string;
+    };
+}

package/core/domain/src/builder/builder-palette.js

@@ -0,0 +1,90 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const LABELS = {
+    actor: "Actor",
+    string: "Text",
+    int: "Number",
+    count: "Count",
+    word: "Word",
+    app: "App",
+    route: "Route",
+    steps: "Steps",
+};
+export class BuilderPalette {
+    book;
+    blocks;
+    together;
+    atTheSameTime;
+    byPattern;
+    constructor(book, blocks, 
+    together, 
+    atTheSameTime = undefined) {
+        this.book = book;
+        this.blocks = blocks;
+        this.together = together;
+        this.atTheSameTime = atTheSameTime;
+        this.byPattern = new Map(blocks.map((block) => [block.pattern, block]));
+    }
+    static from(book, info = () => undefined) {
+        const blocks = [];
+        for (const entry of book.entries) {
+            if (entry.kind !== "action" && entry.kind !== "assertion" && entry.kind !== "identity" && entry.kind !== "navigation" && entry.kind !== "time" && entry.kind !== "condition")
+                continue;
+            const about = info(entry) ?? {};
+            const plural = book.entries.find((item) => item.kind === "repeatable" && item.repeats?.text === entry.pattern.text);
+            blocks.push({
+                pattern: entry.pattern.text,
+                owner: entry.owner,
+                kind: entry.kind,
+                class: BuilderPalette.classOf(entry),
+                group: about.group ?? (entry.owner.includes(".") ? entry.owner.slice(0, entry.owner.indexOf(".")) : entry.owner),
+                title: about.title ?? entry.pattern.text,
+                ...(about.via ? { via: about.via } : {}),
+                ...(about.app ? { app: about.app } : {}),
+                resources: [...(about.resources ?? [])],
+                mutates: about.mutates ?? (entry.kind === "action" || entry.kind === "time" || entry.kind === "condition"),
+                ...(about.explore === false ? { explore: false } : {}),
+                available: about.available ?? true,
+                ...(about.reason ? { reason: about.reason } : {}),
+                fields: entry.pattern.parameters.map((kind, index) => {
+                    const hint = about.parameters?.[index];
+                    return {
+                        index,
+                        kind,
+                        label: hint?.label ?? LABELS[kind],
+                        ...(hint?.options ? { options: [...hint.options] } : {}),
+                        ...(hint?.min !== undefined ? { min: hint.min } : {}),
+                        ...(hint?.max !== undefined ? { max: hint.max } : {}),
+                        ...(hint?.default !== undefined ? { default: hint.default } : {}),
+                        references: kind === "int" || kind === "string",
+                    };
+                }),
+                ...(entry.table ? { table: { columns: entry.table.columns, rows: entry.table.rows } } : {}),
+                ...(plural ? { plural: plural.pattern.text } : {}),
+                ...(entry.outputs ? { outputs: { ...entry.outputs } } : {}),
+                ...(entry.introduces ? { introduces: { ...entry.introduces } } : {}),
+            });
+        }
+        const together = book.entries.find((entry) => entry.kind === "together" && entry.table)?.pattern.text;
+        const atTheSameTime = book.entries.find((entry) => entry.kind === "together" && !entry.table)?.pattern.text;
+        return new BuilderPalette(book, blocks, together, atTheSameTime);
+    }
+    block(pattern) {
+        return this.byPattern.get(pattern);
+    }
+    shape(pattern) {
+        return this.book.entries.find((entry) => entry.pattern.text === pattern)?.table;
+    }
+    static classOf(entry) {
+        if (entry.kind === "identity")
+            return "given";
+        if (entry.kind === "assertion")
+            return "then";
+        if (entry.kind === "navigation")
+            return entry.pattern.parameters.includes("route") ? "when" : "then";
+        return "when";
+    }
+    toJSON() {
+        return { blocks: this.blocks, ...(this.together ? { together: this.together } : {}) };
+    }
+}

package/core/domain/src/builder/feature-reader.d.ts

@@ -0,0 +1,4 @@
+import { type LoadedFeature } from "./builder-document.js";
+import type { BuilderPalette } from "./builder-palette.js";
+/** Load a feature file's text into blocks; the palette decides what is a block. */
+export declare function readFeature(text: string, palette: BuilderPalette): LoadedFeature;