@w6w/ui 0.2.11 → 0.2.54

package/dist/data-stores/data-store-view.d.ts

@@ -0,0 +1,371 @@
+/**
+ * The pure, data-free vocabulary of a Data store (F-2, lifted from Studio's
+ * `lib/data-stores-view`, `data-cells`, `data-grid` and `data-store-errors`).
+ *
+ * One import point for every consumer (Studio, `@w6w/embed`, the components in
+ * this package): the wire types, the closed kind/scalar vocabularies, the
+ * cell text codec, the row-draft/write helpers and the error locator. Paths,
+ * query builders and cache keys deliberately stay in Studio.
+ *
+ * Pure and dependency-free on purpose: no React, no SDK, no `fetch`, only
+ * relative imports, so `node --test` loads it with nothing but type-stripping.
+ */
+/** Display label per store kind (shared by every list and picker). */
+export declare const DATA_STORE_KIND_LABEL: {
+    readonly kv: "Key-value";
+    readonly doc: "Document";
+    readonly table: "Table";
+};
+/**
+ * The three store shapes. `kv` holds one value per key, `doc` holds a JSON
+ * document per key, `table` holds rows whose columns are declared in the
+ * store's schema.
+ */
+export type DataStoreKind = "kv" | "doc" | "table";
+/**
+ * The server's scalar vocabulary (S-1). A value of this type is validated
+ * server-side and stored as the string the caller sent — never coerced.
+ */
+export type ScalarType = "string" | "number" | "integer" | "boolean" | "date" | "datetime";
+/** One declared table column (S-2). `default` is the column's JSON default, verbatim. */
+export interface TableColumn {
+    name: string;
+    type: ScalarType;
+    required: boolean;
+    default?: unknown;
+}
+/** A `kv` store's schema (S-2): one scalar type for every value. */
+export interface KvSchema {
+    valueType: ScalarType;
+}
+/** A `table` store's schema (S-2); `key` names the column whose cell is the row's key. */
+export interface TableSchema {
+    columns: TableColumn[];
+    key?: string;
+}
+/** A store as the wire carries it (S-3). Timestamps are ISO-8601 strings. */
+export interface DataStore {
+    id: string;
+    kind: DataStoreKind;
+    name: string;
+    description: string;
+    project: string;
+    schema: Record<string, unknown>;
+    entryCount: number;
+    sizeBytes: number;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One entry as the wire carries it (S-3). `expiresAt` is `null` when the entry never expires. */
+export interface Entry {
+    key: string;
+    value: unknown;
+    version: number;
+    sizeBytes: number;
+    expiresAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** `GET /data-stores` — one page of stores plus the cursor for the next one. */
+export interface DataStorePage {
+    items: DataStore[];
+    nextCursor?: string;
+}
+/** `GET /data-stores/:id/entries` — one page of entries (a table query never carries a cursor). */
+export interface EntryPage {
+    items: Entry[];
+    nextCursor?: string;
+}
+/** `POST /data-stores/:id/import` — how many CSV rows the host upserted/appended. */
+export interface ImportResult {
+    imported: number;
+}
+/** `POST /data-stores` body. `schema` is the S-2 shape for the chosen `kind`. */
+export interface DataStoreCreateInput {
+    kind: DataStoreKind;
+    name: string;
+    description?: string;
+    schema?: Record<string, unknown>;
+}
+/** `PATCH /data-stores/:id` body — every field optional, none of them the kind. */
+export interface DataStorePatch {
+    name?: string;
+    description?: string;
+    schema?: Record<string, unknown>;
+}
+/** The closed set of store kinds, in the order the create dialog offers them. */
+export declare const DATA_STORE_KINDS: readonly ["kv", "doc", "table"];
+/** The closed set of scalar cell types, in the order the columns editor offers them. */
+export declare const SCALAR_TYPES: readonly ["string", "number", "integer", "boolean", "date", "datetime"];
+/** R-7: a CSV upload is at most 5 MB (5 242 880 bytes). The client checks before sending. */
+export declare const CSV_MAX_BYTES = 5242880;
+/**
+ * A `kv` store's declared value type, defaulting to `"string"` — S-2's own
+ * default, and the only safe reading of a schema the client did not write
+ * (a store created before the field existed, or one whose schema is garbage).
+ */
+export declare function kvValueTypeOf(store: DataStore): ScalarType;
+/**
+ * A `table` store's schema, or `null` when the store is not a table or its
+ * schema has no column array. `null` — not an empty column list — so the grid
+ * can tell "not a table" from "a table with nothing declared".
+ */
+export declare function tableSchemaOf(store: DataStore): TableSchema | null;
+/**
+ * The filename to save an export under: the host's own `filename="…"` from the
+ * `Content-Disposition` header when it sent one, otherwise `<store name>.csv`.
+ * A header without that parameter (`attachment` alone, or `null` when a
+ * proxy stripped it) falls back rather than producing a nameless file.
+ */
+export declare function csvFilenameOf(contentDisposition: string | null, storeName: string): string;
+/** Why a cell's text could not become a value. */
+export type CellProblem = "required" | "not_a_number" | "not_an_integer" | "not_a_boolean" | "not_a_date" | "not_a_datetime";
+/** The one sentence rendered beside the offending cell, per problem. */
+export declare const CELL_PROBLEM_COPY: Record<CellProblem, string>;
+/**
+ * Turn the text an operator typed into the value the wire takes, for a column
+ * of `type`.
+ *
+ * `required` is applied to the EMPTY cell only (R-7): every other rule is the
+ * server's own, so a cell this returns `ok` for is a cell the server accepts.
+ * `string` is the one type that keeps the text as typed — trimming it would
+ * silently edit the operator's value.
+ */
+export declare function parseCell(type: ScalarType, text: string, required: boolean): {
+    ok: true;
+    value: string | number | boolean | undefined;
+} | {
+    ok: false;
+    problem: CellProblem;
+    message: string;
+};
+/**
+ * The text to put in a cell for an already-typed value.
+ *
+ * `undefined`/`null` render as the empty cell (never `"undefined"` or `"null"`);
+ * a string value for a string-ish column is shown as itself; a finite number
+ * and a boolean render as their JSON literals; anything else (an object cell,
+ * a `null` inside a document) falls back to its JSON text so the cell shows
+ * what the server holds rather than `[object Object]`.
+ */
+export declare function serializeCell(type: ScalarType, value: unknown): string;
+/**
+ * Is an already-typed JSON value of `type`? The same rules {@linkcode parseCell}
+ * applies to text, applied to a value that came back from the server — the grid
+ * uses it to mark a row the server would refuse before the operator presses
+ * Save. `required` plays no part here: an absent value is the caller's problem
+ * to decide about, not this predicate's.
+ */
+export declare function isCellValue(type: ScalarType, value: unknown): boolean;
+/** What is shown when the server said nothing a human can read. */
+export declare const DATA_STORE_ERROR_FALLBACK = "The request failed.";
+/** `rawRequest`'s `status: 0` — the request never reached the server. */
+export declare const DATA_STORE_NETWORK_ERROR = "Could not reach the server.";
+/** A failure, flattened into the fields the page needs and nothing else. */
+export interface DataStoreErrorLocator {
+    /** Always present: the server's own sentence, or one of the two copy constants above. */
+    message: string;
+    /** The host's machine-readable code (`invalid_value`, `invalid_cursor`, …). */
+    code?: string;
+    /** The HTTP status; `0` is the transport-failure convention. */
+    status?: number;
+    /** The request-body field the host blamed. */
+    field?: string;
+    /** The 0-based CSV data row the host blamed (header excluded). */
+    row?: number;
+    /** The table column the host blamed. */
+    column?: string;
+}
+/**
+ * Locate a thrown JSON-call failure: an `ApiError` (whose parsed body lives on
+ * `.raw`), a plain `Error`, or anything else at all.
+ *
+ * The message falls back in that order — the envelope's `message`, the error's
+ * own `message`, then {@linkcode DATA_STORE_ERROR_FALLBACK} — so an unfamiliar
+ * throw still produces a sentence rather than an empty panel.
+ */
+export declare function locateDataStoreError(e: unknown): DataStoreErrorLocator;
+/**
+ * Locate a CSV-call failure from P-RAW's `{status, text}` — the body is still
+ * unparsed text because that transport does not know the content type.
+ *
+ * `status: 0` means the request never produced a response, and gets the
+ * transport sentence rather than an attempt to parse an empty body. Otherwise
+ * the body is parsed iff it is JSON: an HTML error page from a proxy is
+ * `{status, message: fallback}`, not a crash.
+ */
+export declare function locateRawResponseError(res: {
+    status: number;
+    text: string;
+}): DataStoreErrorLocator;
+/** Where the message is rendered: under one table cell, under one form field, or over the whole form. */
+export declare function errorPlacement(loc: DataStoreErrorLocator): {
+    kind: "cell";
+    column: string;
+    row?: number;
+} | {
+    kind: "field";
+    field: string;
+} | {
+    kind: "form";
+};
+/**
+ * The operator's 1-based line number in the CSV they uploaded, from the host's
+ * 0-based data-row index: the header row is line 1, so data row 0 is line 2.
+ */
+export declare function csvLineOf(row: number): number;
+/**
+ * The draft id of a row that does not exist yet: a NUL-prefixed sentinel, which
+ * R-5 forbids a real key from ever being (no control characters in a key), so
+ * `id === NEW_ROW_ID` and "this row has no server-side key" are the same fact.
+ */
+export declare const NEW_ROW_ID = "\0new";
+/** Rendered beside a row whose `ifVersion` was stale — never as the server's sentence alone. */
+export declare const VERSION_CONFLICT_COPY = "Changed by someone else since you loaded it.";
+/** A `doc` store holds a JSON object or array; anything else is not a document. */
+export declare const DOC_VALUE_COPY = "Enter a JSON object or array.";
+/** R-7's client-side ceiling copy — the check runs before anything is sent. */
+export declare const CSV_TOO_LARGE_COPY = "The file is larger than 5 MB.";
+/**
+ * One row's editable state: the id it is saved under (`entry.key`, or
+ * {@linkcode NEW_ROW_ID}), the version the save guards with (`null` for a new
+ * row) and the cell TEXT per declared column (never a parsed value — the text
+ * is what the operator is editing, and re-serialising it on every keystroke
+ * would fight their cursor).
+ */
+export interface RowDraft {
+    id: string;
+    version: number | null;
+    cells: Record<string, string>;
+}
+/**
+ * An entry's value read as a table row: the object the server stored, or `{}`
+ * for anything that is not a plain object (a `null`, an array, a scalar from a
+ * column set that has since changed).
+ */
+export declare function rowValueOf(entry: Entry): Record<string, unknown>;
+/** The draft an entry starts as: its key, its version, and each declared column's text. */
+export declare function draftFromEntry(entry: Entry, columns: readonly TableColumn[]): RowDraft;
+/**
+ * The draft a brand-new row starts as: {@linkcode NEW_ROW_ID}, no version, and
+ * each column seeded from its declared `default` (absent default = empty cell).
+ */
+export declare function newRowDraft(columns: readonly TableColumn[]): RowDraft;
+/**
+ * Which declared columns the operator actually changed, in DECLARED order.
+ *
+ * Declared order (not object order) so the answer is stable across browsers and
+ * the row's Save button can decide "dirty" with one empty-array check. An
+ * untouched draft is `[]`.
+ */
+export declare function dirtyColumns(draft: RowDraft, base: RowDraft, columns: readonly TableColumn[]): string[];
+/**
+ * The row body a Save sends, or the per-cell refusals that stop it.
+ *
+ * Every DECLARED column is parsed through {@linkcode parseCell} with its own
+ * `required` flag: an absent value omits the key entirely (R-7's empty-cell
+ * rule, so the host's default applies), a `string` cell keeps its text verbatim
+ * and every other type is the JSON value the server expects — never the typed
+ * text. Failures are keyed by column name so the caller renders them under the
+ * offending cell.
+ */
+export declare function buildRowValue(draft: RowDraft, columns: readonly TableColumn[]): {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    errors: Record<string, string>;
+};
+/**
+ * The `ttlSeconds` a save must resend so it does not CLEAR an existing expiry
+ * (S-1: a PUT without `ttlSeconds` sets `expires_at = NULL`).
+ *
+ * `undefined` for an entry that never expires, for an unparseable timestamp and
+ * for one already in the past — in all three cases sending nothing is correct
+ * (and a non-positive TTL is not a TTL the host accepts). Rounded UP, so a save
+ * one millisecond before the deadline does not shorten the entry's life.
+ */
+export declare function remainingTtlSeconds(expiresAt: string | null, nowMs: number): number | undefined;
+/**
+ * Which request a draft implies: an INSERT (`POST entries`, no `ifVersion`) for
+ * a row that does not exist yet, otherwise a PUT under the row's key guarded by
+ * the version the operator loaded.
+ *
+ * `ttlSeconds` is present ONLY when the caller has one: it reaches the wire as
+ * a defining key, and an explicit `undefined` would be indistinguishable from
+ * "the caller measured nothing".
+ */
+export declare function rowWriteOf(draft: RowDraft, value: Record<string, unknown>, ttlSeconds: number | undefined): {
+    kind: "insert";
+    value: Record<string, unknown>;
+    ttlSeconds?: number;
+} | {
+    kind: "put";
+    key: string;
+    value: Record<string, unknown>;
+    ifVersion: number;
+    ttlSeconds?: number;
+};
+/**
+ * The cell errors a refusal places, or `null` when it belongs somewhere else
+ * (the form, a request-body field, a column this table does not declare).
+ *
+ * `null` is load-bearing: the grid renders `grid-error` exactly when this
+ * returns `null`, so "the message shows in one slot" is a property of the
+ * answer rather than of the caller's care.
+ */
+export declare function cellErrorsOf(loc: DataStoreErrorLocator, columns: readonly TableColumn[]): Record<string, string> | null;
+/**
+ * Is this failure the optimistic-concurrency refusal — and nothing else?
+ *
+ * `409` alone is not enough: `entry_exists` and `store_exists` share the status
+ * and neither is fixed by reloading, so both halves of the locator must agree.
+ */
+export declare function isVersionConflict(loc: DataStoreErrorLocator): boolean;
+/**
+ * A `doc` store's value from the editor's text: any JSON object or array.
+ *
+ * A scalar is refused rather than wrapped — the store's own `doc` shape is an
+ * object/array (S-2), and the host would refuse `42` anyway; failing here means
+ * the operator sees why without a round trip. `null` parses but is not a
+ * document, so it is refused with the same sentence.
+ */
+export declare function parseDocText(text: string): {
+    ok: true;
+    value: object;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * A `kv` store's value from the editor's text.
+ *
+ * `string` is the one type whose text IS the value, empty string included (an
+ * empty `string` entry is a real value, not an absent one), so it never passes
+ * through {@linkcode parseCell} — which reads an empty cell as absent. Every
+ * other type is parsed exactly as a table cell would be, `required` on, because
+ * a kv entry always has a value.
+ */
+export declare function kvValueOf(type: ScalarType, text: string): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * What a CSV import's `RawResponse` says to the operator.
+ *
+ * The host is the only parser (R-7): a `200` reports how many rows it took, and
+ * a refusal is located rather than interpreted — a `row` becomes the operator's
+ * own 1-based line (`csvLineOf`), the `column` is named when the host named one,
+ * and everything else is the host's sentence verbatim.
+ */
+export declare function csvImportMessage(res: {
+    status: number;
+    text: string;
+}): {
+    ok: boolean;
+    message: string;
+};

package/dist/eventbrite-trigger-selection.d.ts

@@ -0,0 +1,13 @@
+import { ActionDef } from './types.ts';
+export interface EventbriteTriggerChoices {
+    triggerKey: string;
+    options: {
+        value: string;
+        label: string;
+        triggerKey: string;
+    }[];
+    selected: string[];
+}
+/** Eventbrite's activity trigger registers several events on one webhook. Keep its
+ * event catalog in the app manifest; the editor only adapts the existing trigger keys. */
+export declare function eventbriteTriggerChoices(appId: string, triggers: ActionDef[] | null, triggerKey: string, values: Record<string, unknown>): EventbriteTriggerChoices | null;

package/dist/flow-connect.d.ts

@@ -1,5 +1,6 @@
 import { Edge } from '@xyflow/react';
-import { PortsLookup } from './flow-types.ts';
+import { LoopRefusalReason } from './flow-loop.ts';
+import { CanvasLane, PortsLookup } from './flow-types.ts';
 import { StepNode } from './flow-utils.ts';
 /**
  * Which lane a React Flow edge belongs to (core `rfcs/workflow.md` · `Edge.when`
@@ -8,7 +9,7 @@ import { StepNode } from './flow-utils.ts';
  * `data` at all. The single accessor: every consumer calls this rather than
  * re-deriving the fallback, so "absent means success" is decided once.
  */
-export declare function edgeLane(e: Edge): "success" | "error";
+export declare function edgeLane(e: Edge): CanvasLane;
 /**
  * A refused connection: the source's exit port is full **in this lane** and the cap
  * is finite. Drawing past a finite `out` cap is refused, never satisfied by evicting
@@ -18,14 +19,22 @@ export type OutCapRefusal = {
     refused: "out_cap";
     cap: number;
 };
+/**
+ * A refused connection that would break the v1 linear-body rule of a For each
+ * (see {@link loopRefusal}). Raised before the out-cap census and before any
+ * inbound eviction, always against the INPUT edges.
+ */
+export type LoopRefusal = {
+    refused: "loop";
+    reason: LoopRefusalReason;
+};
 /**
  * The hard rules for an edge `source → target` — the ones no amount of
  * replacement can satisfy: a real, *distinct* pair (no self-loops), no duplicate
  * edge, the target accepts an entry port (blocks connecting *into* a trigger,
  * which declares `in: 0`), and the source has an exit port. Port **capacity** is
- * deliberately NOT checked here: a full single-slot port is freed by replacement
- * (see `applyConnect`), so dragging a new wire from an already-connected node
- * re-points it rather than being rejected. Used as the live `isValidConnection`.
+ * deliberately NOT checked here: an input accepts any number of edges, and the exit
+ * cap is refused in `applyConnect`. Used as the live `isValidConnection`.
  *
  * The duplicate-pair check is **lane-blind by design**, and that is a v1 *editor*
  * limit, not a model limit: the model permits a success edge and an error edge
@@ -41,13 +50,13 @@ export type OutCapRefusal = {
  * Letting the drop through and refusing in `applyConnect` is what lets the reason
  * paint — see {@link connectConflict}.
  */
-export declare function canConnect(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], lookup?: PortsLookup): boolean;
+export declare function canConnect(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], lookup?: PortsLookup, route?: string): boolean;
 /**
  * Build the next edge set for a new `source → target` connection. **Additive at the
  * source**: a source under its `out` cap (or unbounded) keeps every existing edge and
  * gains one; at a finite cap the connection is **refused** (see {@link connectRefusal}),
- * never satisfied by evicting. The target's entry port is still single-slot-replacing:
- * the oldest inbound edge(s) are dropped to make room. Returns `null` when the
+ * never satisfied by evicting. The target's entry port accepts any number of
+ * inbound edges, so nothing is ever evicted there. Returns `null` when the
  * connection is disallowed by {@link canConnect}, refused at the out cap — **or when the minted id would
  * duplicate a surviving edge's id**, the same refusal {@link setEdgeWhen} performs
  * through the same {@link collidingEdgeId} test.
@@ -68,13 +77,10 @@ export declare function canConnect(source: string | null | undefined, target: st
  * `send → (error) → fallback` shape authorable at all. No `ports.out` bump is
  * needed, so every persisted definition and palette entry stays valid.
  *
- * The target's entry capacity stays **lane-blind**, and that asymmetry is the
- * point: a converging tail step receiving one success and one error edge is
- * governed by `ports.in` alone. Partitioning the target rule by lane too — the
- * plausible "symmetry" cleanup — would let a `ports.in: 1` node silently accept
- * two inbound edges.
+ * The target's entry has no capacity: any number of edges, from any number of
+ * sources (several triggers may feed one node), converge on it.
  */
-export declare function applyConnect(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: "success" | "error", lookup?: PortsLookup): Edge[] | null;
+export declare function applyConnect(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: CanvasLane, lookup?: PortsLookup, route?: string): Edge[] | null;
 /**
  * The id of the existing edge that drawing `source → target` would collide with, or
  * `null` when the connection is safe (or refused for an ordinary reason — a
@@ -85,13 +91,13 @@ export declare function applyConnect(source: string | null | undefined, target:
  * selects that edge and renders the message in the edge-lane panel (never a browser
  * dialog; see `.ai/conventions.md`).
  */
-export declare function connectConflict(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: "success" | "error", lookup?: PortsLookup): string | null;
+export declare function connectConflict(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: CanvasLane, lookup?: PortsLookup, route?: string): string | null;
 /**
  * The out-cap refusal for drawing `source → target`, or `null` when the source has
  * room (or is unbounded). The editor renders `cap` in an inline message on the same
  * channel as {@link connectConflict}; {@link applyConnect} returns `null` for it.
  */
-export declare function connectRefusal(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: "success" | "error", lookup?: PortsLookup): OutCapRefusal | null;
+export declare function connectRefusal(source: string | null | undefined, target: string | null | undefined, nodes: StepNode[], edges: Edge[], when?: CanvasLane, lookup?: PortsLookup, route?: string): OutCapRefusal | LoopRefusal | null;
 /**
  * Re-lane one edge. Updates its `data.when`, its visuals and its id, and frees
  * nothing: when the destination lane is at a finite out cap the switch is refused

package/dist/flow-delete.d.ts

@@ -0,0 +1,16 @@
+import { Edge } from '@xyflow/react';
+import { FlowCanvas } from './canvas-types.ts';
+import { StepNode } from './flow-utils.ts';
+export interface FlowDeleteSelection {
+    nodeIds: string[];
+    edgeIds: string[];
+}
+/** Capture the full selection, independently of the first item shown in the side panel. */
+export declare function selectedFlowElements(nodes: StepNode[], edges: Edge[]): FlowDeleteSelection;
+/** Apply the entire confirmed selection before the editor emits one change/history entry. */
+export declare function deleteFlowSelection(selection: FlowDeleteSelection, nodes: StepNode[], edges: Edge[], canvas: FlowCanvas): {
+    nodes: StepNode[];
+    edges: Edge[];
+    canvas: FlowCanvas;
+};
+export declare function flowDeleteMessage(selection: FlowDeleteSelection, nodes: StepNode[], edges: Edge[]): string;

package/dist/flow-history.d.ts

@@ -0,0 +1,75 @@
+import { Edge } from '@xyflow/react';
+import { FlowCanvas } from './canvas-types.ts';
+import { FlowStep, FlowWorkflow } from './flow-types.ts';
+import { StepNode } from './flow-utils.ts';
+/** Only authored graph data. Tests, samples, run paint, selection and viewport never enter history. */
+export interface FlowEditSnapshot {
+    nodes: FlowStep[];
+    edges: NonNullable<FlowWorkflow["edges"]>;
+    connections: NonNullable<FlowWorkflow["connections"]>;
+    canvas: FlowCanvas;
+    /** Keep the live layout even when saving positions is switched off. */
+    positions: Record<string, {
+        x: number;
+        y: number;
+    }>;
+}
+export declare function captureFlowEdit(base: FlowWorkflow, nodes: StepNode[], edges: Edge[], connections: FlowEditSnapshot["connections"], canvas: FlowCanvas): FlowEditSnapshot;
+export declare function restoreFlowEdit(base: FlowWorkflow, snapshot: FlowEditSnapshot): {
+    nodes: {
+        position: {
+            x: number;
+            y: number;
+        };
+        id: string;
+        data: import('./flow-utils.ts').StepNodeData;
+        sourcePosition?: import('@xyflow/react').Position;
+        targetPosition?: import('@xyflow/react').Position;
+        hidden?: boolean;
+        selected?: boolean;
+        dragging?: boolean;
+        draggable?: boolean;
+        selectable?: boolean;
+        connectable?: boolean;
+        deletable?: boolean;
+        dragHandle?: string;
+        width?: number;
+        height?: number;
+        initialWidth?: number;
+        initialHeight?: number;
+        parentId?: string;
+        zIndex?: number;
+        extent?: "parent" | import('@xyflow/react').CoordinateExtent | null;
+        expandParent?: boolean;
+        ariaLabel?: string;
+        origin?: import('@xyflow/react').NodeOrigin;
+        handles?: import('@xyflow/react').NodeHandle[];
+        measured?: {
+            width?: number;
+            height?: number;
+        };
+        type?: string | undefined;
+        style?: import('react').CSSProperties;
+        className?: string;
+        resizing?: boolean;
+        focusable?: boolean;
+        ariaRole?: import('react').AriaRole;
+        domAttributes?: Omit<import('react').HTMLAttributes<HTMLDivElement>, "id" | "style" | "className" | "draggable" | "role" | "aria-label" | "defaultValue" | "dangerouslySetInnerHTML" | keyof import('react').DOMAttributes<HTMLDivElement>>;
+    }[];
+    edges: Edge[];
+};
+/** Bounded, editor-session history. One text-field focus session is one undoable edit. */
+export declare class FlowEditHistory {
+    private past;
+    private future;
+    private present;
+    private group;
+    private readonly limit;
+    constructor(initial: FlowEditSnapshot, limit?: number);
+    reset(initial: FlowEditSnapshot): void;
+    record(snapshot: FlowEditSnapshot, group?: object): void;
+    undo(): FlowEditSnapshot | undefined;
+    redo(): FlowEditSnapshot | undefined;
+}
+/** Leave native text undo and CodeMirror's own history alone. */
+export declare function isFlowTextTarget(target: EventTarget | null): boolean;

package/dist/flow-layout.d.ts

@@ -0,0 +1,13 @@
+import { Edge } from '@xyflow/react';
+import { FlowCanvas } from './canvas-types.ts';
+import { StepNode } from './flow-utils.ts';
+/**
+ * Arrange paths and their section frames together. Membership is authored data:
+ * fit each frame to its members, never infer new membership from moved geometry.
+ * A section spanning non-members is moved with its members below the obstruction.
+ * Notes and empty sections retain their authored geometry.
+ */
+export declare function relayoutFlow(nodes: StepNode[], edges: Edge[], canvas: FlowCanvas): {
+    nodes: StepNode[];
+    canvas: FlowCanvas;
+};

package/dist/flow-loop-colors.d.ts

@@ -0,0 +1,39 @@
+import { Edge } from '@xyflow/react';
+import { CSSProperties } from 'react';
+import { StepNode } from './flow-utils.ts';
+/** How many `--w6w-loop-N` tokens `_tokens.scss` defines. */
+export declare const LOOP_TONES = 6;
+/**
+ * Tone index (1-based) per For each id. Ids are visited in sorted order so the result
+ * does not depend on node order; each takes its hashed tone, or the next free one.
+ */
+export declare function assignLoopTones(foreachIds: Iterable<string>): Map<string, number>;
+/** The CSS colour for a tone index. */
+export declare function loopToneVar(tone: number): string;
+/** The loops enclosing `id`, outermost first, following each For each's own `loopOf`. */
+export declare function enclosingLoops(id: string, loopOfById: ReadonlyMap<string, string | undefined>): string[];
+/**
+ * Paint each-lane edges with the colour of the loop they belong to: the For each itself
+ * for its Each item link, else the loop the edge's source step runs in. Sets the
+ * `--w6w-loop-color` custom property the `.w6w-edge-each` rule reads, so run-state
+ * classes still compose over it. Same array when nothing needs painting.
+ */
+export declare function paintLoopEdges(edges: Edge[], tones: ReadonlyMap<string, number>, loopOfById: ReadonlyMap<string, string | undefined>): Edge[];
+/**
+ * The colour custom property a card's root carries: a For each's own tone, read by its
+ * Each item port. A loop-body step gets none — it looks exactly like a step outside a
+ * loop; its dots are what mark it.
+ */
+export declare function loopCardStyle(id: string, tones: ReadonlyMap<string, number>): CSSProperties | undefined;
+/** What the canvas paints loops from: each For each's tone, and each step's own loop. */
+export type LoopPaint = {
+    tones: ReadonlyMap<string, number>;
+    loopOf: ReadonlyMap<string, string | undefined>;
+};
+/**
+ * A string that changes only when a loop's membership does — the memo key for
+ * {@link loopPaint}, so dragging a node does not hand every card a new context value.
+ */
+export declare function loopPaintKey(nodes: readonly StepNode[]): string;
+/** Rebuild the {@link LoopPaint} a {@link loopPaintKey} describes. */
+export declare function loopPaint(key: string): LoopPaint;