@draftably/editor 0.4.0 → 0.6.0

package/dist/types/src/components/scene/EdgeView.d.ts

@@ -4,6 +4,8 @@ export interface EdgeViewProps {
     doc: Diagram;
     route: DrawnRoute;
     selected?: boolean;
+    /** In a sequence: the selected message answers this one, or this one answers it. */
+    paired?: boolean;
     interactive?: boolean;
     /** Its label is being edited in place, so the drawn label hides. */
     editing?: boolean;

package/dist/types/src/components/scene/Lifelines.d.ts

@@ -6,10 +6,11 @@ export declare function Lifelines(props: {
     rect: (id: string) => NodeLayout | undefined;
 }): import("solid-js").JSX.Element;
 /**
- * A sequence diagram's panel (`part="panel"`, under the groups) or its phase bands
- * (`part="phases"`, over the groups' column bands), as the SVG export draws them.
+ * A sequence diagram's panel (`part="panel"`, under the groups), its phase bands
+ * (`part="phases"`, over the groups' column bands) or its activation bars (`part="bars"`, over
+ * the lifelines), as the SVG export draws them.
  */
 export declare function SequenceBackdrop(props: {
     doc: Diagram;
-    part: 'panel' | 'phases';
+    part: 'panel' | 'phases' | 'bars';
 }): import("solid-js").JSX.Element;

package/dist/types/src/components/session-context.d.ts

@@ -213,6 +213,8 @@ export declare const useSessionIfAny: () => ({
             tail?: import("../model/markers").EndMarker;
             emphasis: boolean;
             dashed: boolean;
+            message?: import("../model/markers").MessageKind;
+            replyTo?: string;
             status?: import("../model/status").Status;
             spot?: import("../model/status").Spot;
         }[];
@@ -221,7 +223,7 @@ export declare const useSessionIfAny: () => ({
     routingReport: () => import("../engines/routing-engine").RoutingReport;
     blockedRouteIds: () => string[];
     sceneBounds: () => import("../model/types").Rect;
-    viewerFrame: () => {
+    viewerFrame: import("solid-js").Accessor<{
         x: number;
         y: number;
         w: number;
@@ -265,7 +267,7 @@ export declare const useSessionIfAny: () => ({
             h: number;
         };
         notes: import("../model/note").PlacedNote[];
-    };
+    }>;
 } & {
     states: () => import("../model/appearance").EmphasisState[];
     activeState: () => string | null;
@@ -274,6 +276,9 @@ export declare const useSessionIfAny: () => ({
     showState: (id: string | null) => void;
     stepState: (by: 1 | -1) => boolean;
     drawnDoc: () => import("../model/types").Diagram;
+    dark: import("solid-js").Accessor<boolean>;
+    setDark: import("solid-js").Setter<boolean>;
+    drawnAppearance: () => import("../model/appearance").DiagramAppearance;
 } & {
     tool: import("solid-js").Accessor<import("../state/session/editor").Tool>;
     setToolSignal: import("solid-js").Setter<import("../state/session/editor").Tool>;
@@ -400,6 +405,8 @@ export declare const useSessionIfAny: () => ({
     fitSelectedContainer: () => void;
     toggleCollapse: (id?: string | undefined) => void;
     reverseSelectedEdge: () => void;
+    insertEvent: (where: "before" | "after") => string | undefined;
+    moveEvent: (by: -1 | 1) => void;
     resetSelectedBends: () => void;
     setLayoutIntent: (role: import("../model/types").IntentRole, id: string | null, placement?: import("../model/types").IntentPlacement) => void;
     markSelectedAs: (role: import("../model/types").IntentRole) => void;

package/dist/types/src/dsl/compile.d.ts

@@ -49,6 +49,8 @@ export interface SceneEdge extends ModelEdge {
     plan?: Planned;
     /** A sequence message: the height of its row; it is drawn straight between lifelines there. */
     row?: number;
+    /** A message between distant lanes: the middle of the gap its label sits in. */
+    labelX?: number;
 }
 export interface Scene {
     model: Model;

package/dist/types/src/dsl/sequence-layout.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The arithmetic of a sequence diagram's layout, apart from the scene it is applied to: where a
+ * label that spans several lanes sits, where each lane stands, and how tall each phase is.
+ * `sequenced` in `compile.ts` measures the text and calls these.
+ */
+/** A lower bound on a lane's centre: at least `room` past the centre of lane `from`. */
+export type Hold = {
+    from: number;
+    room: number;
+};
+/**
+ * The gap a distant message's label sits in, so it crosses no lifeline between its two ends.
+ * `base` holds the lane centres that the headers alone give. The choice prefers a gap inside one
+ * band, so the label covers no band's border, then a gap that already has room, then the gap
+ * nearest the middle of the message, then the left one. Returns the left lane of the gap.
+ */
+export declare function labelSlot(base: number[], a: number, b: number, room: number, across: (lane: number) => boolean): number;
+/**
+ * Lane centres from left to right: each lane takes the header gap from its neighbour, or what
+ * holds it away from an earlier lane, if that is more.
+ */
+export declare function laneCentres(first: number, gaps: number[], holds: Hold[][]): number[];
+/** What one event draws round its row: how far above it and how far below. */
+export type EventInk = {
+    id: string;
+    /** The phase that lists the event, if one does. */
+    phase?: string;
+    /** Height of the label above the line; 0 with no label or for a self-message. */
+    label: number;
+    /** Ink above and below the row. */
+    above: number;
+    below: number;
+    /** A self-message or a local action: the row after it must clear its ink. */
+    tall: boolean;
+    /** How far the event runs on down its lifeline, which the next row starts from. */
+    drop: number;
+};
+export type RowRules = {
+    /** Least distance between two rows. */
+    row: number;
+    /** Room between a tall event's ink and the next event's ink. */
+    clear: number;
+    /** Room between a phase band's edge and the ink inside it. */
+    pad: number;
+    /** Room between two phase bands. */
+    gap: number;
+};
+/**
+ * Rows from top to bottom, starting under the headers at `top`. A phase is one block: its band
+ * starts `gap` under what came before, holds its events with `pad` round them, and is at least
+ * as tall as its title needs. Events outside every phase keep the plain row rule.
+ */
+export declare function eventRows(events: EventInk[], top: number, titleHeight: (phase: string) => number, rules: RowRules): {
+    rows: Map<string, number>;
+    bands: Map<string, {
+        y: number;
+        h: number;
+    }>;
+    end: number;
+};
+/** An event as activation bars read it: who sends to whom, its kind, and what it answers. */
+export type SequenceEvent = {
+    id: string;
+    source: string;
+    target: string;
+    message?: string;
+    replyTo?: string;
+};
+/**
+ * A stretch in which a participant is at work on a call: from the event at index `start` to
+ * the one at `end`, or a short stub when `end` is unset. `level` is 0, or more when the
+ * participant took the call while another of its bars was open.
+ */
+export type ActivationSpan = {
+    lane: string;
+    call: string;
+    start: number;
+    end?: number;
+    level: number;
+};
+/**
+ * The activation bars of a sequence, read from its calls and their replies. A bar opens where a
+ * participant receives a `call` from another and closes at the last reply that answers that
+ * call. A call with no reply closes at the participant's next message to another, and without
+ * one it is a stub. A call a participant sends to itself opens no bar.
+ */
+export declare function activationSpans(events: SequenceEvent[]): ActivationSpan[];

package/dist/types/src/dsl/source-edits.d.ts

@@ -8,6 +8,8 @@ export declare const statements: (doc: SourceDoc) => Statement[];
 export declare function statement(command: string, args: Word[], attrs?: Array<[string, Word]>): Statement;
 /** The `node` or `group` declaration of an object. */
 export declare const declaration: (doc: SourceDoc, id: string) => Statement | undefined;
+/** A statement that makes a connection: an `edge`, or a sequence's `action`. */
+export declare const isEdge: (s: Statement) => boolean;
 export declare const edgeStatement: (doc: SourceDoc, id: string) => Statement | undefined;
 export declare const layoutStatement: (doc: SourceDoc, scope: string) => Statement | undefined;
 export declare function getAttr(s: Statement, key: string): Word | undefined;

package/dist/types/src/dsl/syntax.d.ts

@@ -6,7 +6,7 @@
  * keeps every comment and unrelated statement.
  */
 import { type DiagramAppearance, type Shade } from '../model/appearance';
-import { type EndMarker } from '../model/markers';
+import { type EndMarker, type MessageKind } from '../model/markers';
 import type { Status } from '../model/status';
 import type { ColorKey, LayoutAlgorithmId, LayoutSettings, PortSide, RoutingSettings, ShapeKind } from '../model/types';
 export declare class DslError extends Error {
@@ -131,9 +131,13 @@ export interface ModelEdge {
     tail?: EndMarker;
     /** `constraint=false`: drawn and routed, but layout doesn't rank or order by it. */
     constraint?: false;
+    /** Sequence diagrams: `message=`, or `action` for an `action` line. */
+    message?: MessageKind;
+    /** `answers=`: the earlier message a reply answers. */
+    replyTo?: string;
     line: number;
 }
-/** A layout engine run cold over a scope's subtree; see `src/engines/layout-engine.js`. */
+/** A layout engine run cold over a scope's subtree; see `src/engines/layout-engine.ts`. */
 export interface EngineRecipe {
     algorithm: LayoutAlgorithmId;
     params: Partial<LayoutSettings>;
@@ -160,6 +164,8 @@ export interface ModelLayout {
     /** With `unit`: the width of one unit, and whether unit numbers run above the first row. */
     unitWidth?: number;
     ruler?: boolean;
+    /** `sequence` only: draw a bar on a participant's lifeline while it is at work on a call. */
+    activations?: true;
     /** `flow` only: whether a long run of ranks folds into bands. Engines take `fold` as a param. */
     fold: 'auto' | 'never';
     /** Root only: the image shape to aim for; compile tries direction and folding to get closest. */

package/dist/types/src/dsl/translate.d.ts

@@ -7,7 +7,7 @@
  * write snaps back when the source is reprojected, so nothing unsaved looks saved. Changes the
  * file cannot express are rejected outright.
  */
-import type { DiagramAppearance } from '../model/appearance';
+import { type DiagramAppearance } from '../model/appearance';
 import type { Diagram } from '../model/types';
 import { type Scene } from './compile';
 import { type SourceDoc } from './syntax';

package/dist/types/src/editor/internal.d.ts

@@ -207,6 +207,8 @@ export declare const sessions: WeakMap<object, {
             tail?: import("../model/markers").EndMarker;
             emphasis: boolean;
             dashed: boolean;
+            message?: import("../model/markers").MessageKind;
+            replyTo?: string;
             status?: import("../model/status").Status;
             spot?: import("../model/status").Spot;
         }[];
@@ -215,7 +217,7 @@ export declare const sessions: WeakMap<object, {
     routingReport: () => import("../engines/routing-engine").RoutingReport;
     blockedRouteIds: () => string[];
     sceneBounds: () => import("../model/types").Rect;
-    viewerFrame: () => {
+    viewerFrame: import("solid-js").Accessor<{
         x: number;
         y: number;
         w: number;
@@ -259,7 +261,7 @@ export declare const sessions: WeakMap<object, {
             h: number;
         };
         notes: import("../model/note").PlacedNote[];
-    };
+    }>;
 } & {
     states: () => import("../model/appearance").EmphasisState[];
     activeState: () => string | null;
@@ -268,6 +270,9 @@ export declare const sessions: WeakMap<object, {
     showState: (id: string | null) => void;
     stepState: (by: 1 | -1) => boolean;
     drawnDoc: () => import("../model/types").Diagram;
+    dark: import("solid-js").Accessor<boolean>;
+    setDark: import("solid-js").Setter<boolean>;
+    drawnAppearance: () => import("../model/appearance").DiagramAppearance;
 } & {
     tool: import("solid-js").Accessor<import("../state/session/editor").Tool>;
     setToolSignal: import("solid-js").Setter<import("../state/session/editor").Tool>;
@@ -394,6 +399,8 @@ export declare const sessions: WeakMap<object, {
     fitSelectedContainer: () => void;
     toggleCollapse: (id?: string | undefined) => void;
     reverseSelectedEdge: () => void;
+    insertEvent: (where: "before" | "after") => string | undefined;
+    moveEvent: (by: -1 | 1) => void;
     resetSelectedBends: () => void;
     setLayoutIntent: (role: import("../model/types").IntentRole, id: string | null, placement?: import("../model/types").IntentPlacement) => void;
     markSelectedAs: (role: import("../model/types").IntentRole) => void;

package/dist/types/src/editor/mount.d.ts

@@ -3,6 +3,7 @@ import { type Camera, type CameraReason, type FrameOptions, type MoveResult } fr
 import { type Geometry } from '../runtime/geometry';
 import { type Anchor, type DraftSlot } from '../runtime/anchors';
 import type { Diagnostic } from '../runtime/types';
+import type { EditorUpdate } from '../runtime/host';
 import '../styles/app.css';
 /** The options a host sets on `<draft-editor>`: every mount option but the text and `onChange`. */
 export type EditorOptions = Pick<SessionOptions, 'storageKey' | 'openLink' | 'confirm' | 'onInteract'> & {
@@ -21,12 +22,21 @@ export interface EditorEvents {
     anchors: {
         anchors: readonly Anchor[];
     };
-    /** Slot warnings: an unknown slot, or content larger than its node. */
+    /** A source that does not parse (`DRAFT_PARSE`), then slot warnings: an unknown slot, or content larger than its node. */
     diagnostics: {
         revision: number;
         diagnostics: readonly Diagnostic[];
         stale: boolean;
     };
+    /** Each update's result, from the first text on. */
+    update: EditorUpdateResult;
+    /** A link mark was pressed. `preventDefault()` stops the editor opening it. */
+    link: {
+        itemId: string;
+        href: string;
+        target: '_blank';
+        preventDefault(): void;
+    };
     camera: {
         camera: Camera;
         reason: CameraReason;
@@ -45,11 +55,8 @@ export interface EditorEvents {
         preventDefault(): void;
     };
 }
-/** An editor update's outcome. The editor draws in its own session, so it has no SVG value. */
-export type EditorUpdateResult = {
-    status: 'committed' | 'error' | 'destroyed';
-    revision: number;
-};
+/** An editor update's outcome: `EditorUpdate` in `@draftably/runtime/host`. */
+export type EditorUpdateResult = EditorUpdate;
 /** The editor's handle: the viewer's camera, plus editing. */
 export interface MountedEditor {
     /** Resolves once the first text is drawn. */

package/dist/types/src/engines/explorer-engine.d.ts

@@ -0,0 +1,63 @@
+import type { Diagram, LayoutAlgorithmId, LayoutIntent } from '../model/types.ts';
+import type { LayoutReport, LayoutScope } from './layout-engine.ts';
+import type { PriorRoute, RouteInput, RoutingResult } from './routing-engine.ts';
+export type ParamValue = string | number | boolean;
+export interface ParamDefinition {
+    name: string;
+    values: ParamValue[];
+    passOnly?: boolean;
+}
+export type ComparisonMode = 'layout' | 'routing';
+export type ComparisonRun = 'rebuild' | 'warm' | 'pass';
+export interface ComparisonConfig {
+    mode: ComparisonMode;
+    /** Engines, the suggested routing alternatives, or a grid of parameter values. */
+    kind: 'algorithms' | 'routes' | 'parameters';
+    algorithm: LayoutAlgorithmId;
+    algorithms: LayoutAlgorithmId[];
+    axisA: string;
+    valuesA: string;
+    axisB: string;
+    valuesB: string;
+    run: ComparisonRun;
+    maxIterations: number;
+    scope: LayoutScope;
+    autoPorts: boolean;
+    selected: string[];
+    containerId?: string;
+    fixedIds: string[];
+    intent: LayoutIntent;
+    viewport: {
+        w: number;
+        h: number;
+    };
+    priorRoutes: PriorRoute[];
+}
+export interface CandidateSpec {
+    key: string;
+    title: string;
+    subtitle: string;
+    patch: Record<string, ParamValue>;
+}
+export interface CandidateResult {
+    spec: CandidateSpec;
+    document: Diagram;
+    report: LayoutReport | null;
+    routing: RoutingResult;
+}
+declare function parseValues(key: string, text: string, mode?: ComparisonMode): ParamValue[];
+declare function effectiveParams(algorithm: LayoutAlgorithmId, run: ComparisonRun): Record<string, ParamDefinition>;
+declare function specs(config: ComparisonConfig): CandidateSpec[];
+/** The scene as the router sees it: collapsed groups stand in for their members. */
+declare function sceneInput(doc: Diagram): RouteInput;
+declare function candidate(baseline: Diagram, spec: CandidateSpec, config: ComparisonConfig): Promise<CandidateResult>;
+export declare const ExplorerLab: {
+    layoutParams: Record<string, ParamDefinition>;
+    routeParams: Record<string, ParamDefinition>;
+    parseValues: typeof parseValues;
+    effectiveParams: typeof effectiveParams;
+    specs: typeof specs;
+    sceneInput: typeof sceneInput;
+    candidate: typeof candidate;
+};
+export {};

package/dist/types/src/engines/layout/arrange.d.ts

@@ -0,0 +1,36 @@
+import type { DiagramEdge, Direction } from '../../model/types.ts';
+import type { Scene } from './scene.ts';
+import type { Centres, Item, LayoutIntent, Point, Rect, Topology } from './types.ts';
+/** A link with an end outside the solve, or between two of its items: `a` and `b` are the items that own its ends. */
+export interface BoundaryLink extends DiagramEdge {
+    a: string | null;
+    b: string | null;
+}
+/** What one solve of one container's children shares with its force, separation and packing steps. */
+export interface Batch {
+    parentId: string | null;
+    direction: Direction;
+    items: Item[];
+    byId: Map<string, Item>;
+    t: Topology;
+    localIntent: LayoutIntent;
+    boundaryLinks: BoundaryLink[];
+    /** Hop counts, for the stress solve only. */
+    distances: Map<string, Map<string, number>> | null;
+    target: Centres | null;
+    /** The inside of the parent's frame, or null at the top level. */
+    container: Rect | null;
+    availableAspect: number;
+    /** Each item's centre when the solve began. */
+    origin: Centres;
+    anchor: number;
+    baseCenter: Point;
+    pairGap(a: Item, b: Item): number;
+    /** Copies the document's positions back onto the items. */
+    sync(): void;
+}
+/**
+ * Solves the children of one container: builds the target for the chosen algorithm, runs the
+ * force ticks, and keeps the best state by collisions first and energy second.
+ */
+export declare function arrange(scene: Scene, activeIds: string[], parentId: string | null, direction: Direction): Promise<void>;

package/dist/types/src/engines/layout/compute.d.ts

@@ -0,0 +1,7 @@
+import type { Diagram } from '../../model/types.ts';
+import type { LayoutOptions, LayoutResult } from './types.ts';
+/**
+ * Lays out a copy of `input`. A pass moves boxes at most `maxMove` from where they are; a rebuild
+ * starts from a seed. Pins, fixed frames and the scope bound what may move.
+ */
+export declare function compute(input: Diagram, opts?: LayoutOptions): Promise<LayoutResult>;

package/dist/types/src/engines/layout/forces.d.ts

@@ -0,0 +1,8 @@
+import type { Batch } from './arrange.ts';
+import type { Scene } from './scene.ts';
+/** The force on each item for one tick, by ID; `degree` is the weight of the links behind it. */
+export declare function tickForces(scene: Scene, batch: Batch): Map<string, {
+    x: number;
+    y: number;
+    degree: number;
+}>;

package/dist/types/src/engines/layout/grid.d.ts

@@ -0,0 +1,10 @@
+import type { Centres, Item, Rect, Settings } from './types.ts';
+/** Items in ID order on a grid of even cells, near the wanted aspect. */
+export declare function seedGrid(items: Item[], s: Settings, aspect: number): Centres;
+/** The nearest free cell of a grid round the current centre, closest matches first. */
+export declare function gridTarget(items: Item[], s: Settings, aspect: number): Centres;
+/**
+ * Shifts a target onto the drawing: onto the container's corner, the mean of the fixed items, a
+ * fixed origin for a rebuild (`canonical`), or else the items' current centre.
+ */
+export declare function alignTarget(map: Centres, items: Item[], container: Rect | null, canonical?: boolean): Centres;

package/dist/types/src/engines/layout/intent.d.ts

@@ -0,0 +1,14 @@
+import type { IntentPlacement, IntentRole } from '../../model/types.ts';
+import type { Centres, Item, LayoutIntent } from './types.ts';
+export type Hint = {
+    id: string;
+    placement: IntentPlacement;
+};
+/** The hints of an intent with their roles, in the order the intent holds them. */
+export declare const hintsOf: (intent: LayoutIntent) => Array<[IntentRole, Hint]>;
+/** Where in the drawing's box each placement puts a shape, as fractions of its free width and height. */
+export declare const placements: Record<IntentPlacement, [number, number]>;
+/** A checked start and end hint. Throws on an unknown shape, an unknown placement, or one shape in both roles. */
+export declare function normalizeIntent(raw?: unknown, validIds?: Set<string> | null): LayoutIntent;
+/** The centre each hinted item should reach, inside the items' current box. */
+export declare function hintTargets(items: Item[], intent: LayoutIntent): Centres;

package/dist/types/src/engines/layout/layered.d.ts

@@ -0,0 +1,5 @@
+import type { Centres, Item, Settings, Topology } from './types.ts';
+/** Straight centre-to-centre crossings between a candidate placement's edges. */
+export declare function sketchCrossings(t: Topology, map: Centres): number;
+/** Ranks as columns (or rows), ordered by barycentre sweeps, folded into bands when that fits the aspect better. */
+export declare function layeredTarget(items: Item[], t: Topology, s: Settings, aspect: number): Centres;

package/dist/types/src/engines/layout/objective.d.ts

@@ -0,0 +1,6 @@
+import type { Centres, Item, Settings, Topology } from './types.ts';
+/**
+ * The energy a solve lowers: hint and target errors, link lengths by algorithm, overlap area and
+ * forward links that run backwards. `compoundEnergy` adds the cross-boundary links of a compound solve.
+ */
+export declare function objective(items: Item[], t: Topology, s: Settings, distances: Map<string, Map<string, number>> | null, target: Centres | null, compoundEnergy: (() => number) | null): number;

package/dist/types/src/engines/layout/packing.d.ts

@@ -0,0 +1,7 @@
+import type { Batch } from './arrange.ts';
+import type { Scene } from './scene.ts';
+/**
+ * After a rebuild that left overlaps inside a fixed frame: place the movable items one at a time
+ * at the free spot nearest their target, in up to four orders. Moves them only when one order fits.
+ */
+export declare function packIntoFrame(scene: Scene, batch: Batch, collisions: number): void;

package/dist/types/src/engines/layout/report.d.ts

@@ -0,0 +1,7 @@
+import type { Scene } from './scene.ts';
+import type { LayoutResult, LayoutScope } from './types.ts';
+/**
+ * Ends a run: holds each move to the pass limit and rounds it, rejects a pass that added
+ * overlaps, writes the settings back, and builds the report.
+ */
+export declare function finish(scene: Scene, scope: LayoutScope, started: number, authoredRootId: string): LayoutResult;

package/dist/types/src/engines/layout/scene.d.ts

@@ -0,0 +1,53 @@
+import type { DiagramGroup, DiagramNode, Direction, NodeLayout } from '../../model/types.ts';
+import type { Diagram, LayoutMetrics, LayoutOptions, Settings, SolverStop, TraceFrame } from './types.ts';
+/** A shape or group ID, or nothing for the top level. */
+export type ParentId = string | null | undefined;
+/** Counters and findings that every solve of one layout run adds to. */
+export interface Run {
+    batchCount: number;
+    totalIterations: number;
+    /** Which hierarchy sweep is running; odd sweeps of a compound layout go top down. */
+    hierarchyPhase: number;
+    stops: SolverStop[];
+    warnings: Set<string>;
+    /** Containers whose children a rebuild has already placed from a seed. */
+    seeded: Set<string | null>;
+}
+/**
+ * One layout run's view of the document: the hierarchy, what is fixed or hidden, and the only
+ * ways a solve may move or measure boxes. `doc` is the copy the run changes; `original` keeps the
+ * geometry it started from.
+ */
+export declare function createScene(input: Diagram, doc: Diagram, s: Settings, opts: LayoutOptions): {
+    doc: Diagram;
+    original: Record<string, NodeLayout>;
+    nodeIndex: Map<string, number>;
+    s: Settings;
+    opts: LayoutOptions;
+    run: Run;
+    aspect: number;
+    intent: Partial<Record<import("../../model/types.ts").IntentRole, {
+        id: string;
+        placement: import("../../model/types.ts").IntentPlacement;
+    }>>;
+    compound: boolean;
+    globalTopology: import("./types.ts").Topology<import("../../model/types.ts").DiagramEdge>;
+    groups: Map<string, DiagramGroup>;
+    entities: Map<string, DiagramNode | DiagramGroup>;
+    pos: Record<string, NodeLayout>;
+    child: (id: ParentId) => (DiagramNode | DiagramGroup)[];
+    parent: (id: string) => string | undefined;
+    inheritedDirection: (id: ParentId) => Direction;
+    descend: (id: string) => string[];
+    branch: (id: ParentId) => boolean;
+    fixed: (id: string) => boolean;
+    visible: (id: string) => boolean;
+    padded: (id: string) => NodeLayout;
+    move: (id: string, dx: number, dy: number) => void;
+    resizeAuto: (id: string) => void;
+    metrics: () => LayoutMetrics;
+    before: LayoutMetrics;
+    trace: TraceFrame[];
+    captureTrace: (phase: string, force?: boolean) => void;
+};
+export type Scene = ReturnType<typeof createScene>;

package/dist/types/src/engines/layout/seed.d.ts

@@ -0,0 +1,3 @@
+import type { Direction } from '../../model/types.ts';
+import type { Scene } from './scene.ts';
+export declare function seedHierarchy(scene: Scene, pid: string | null, direction: Direction): void;

package/dist/types/src/engines/layout/separation.d.ts

@@ -0,0 +1,17 @@
+import type { Batch } from './arrange.ts';
+import type { Scene } from './scene.ts';
+import type { Axis, Item } from './types.ts';
+/**
+ * The guarded moves of one solve: a move that keeps an item in its frame and inside the pass's
+ * movement limit, the room an item has along one axis, and the pairwise pass that pushes
+ * overlapping items apart.
+ */
+export declare function createSeparation(scene: Scene, batch: Batch): {
+    constrainedMove: (p: Item, dx: number, dy: number) => void;
+    axisCapacity: (p: Item, axis: Axis, sign: number) => number;
+    separate: (rounds?: number) => void;
+    collisions: () => {
+        n: number;
+        a: number;
+    };
+};

package/dist/types/src/engines/layout/settings.d.ts

@@ -0,0 +1,6 @@
+import type { LayoutSettings } from '../../model/types.ts';
+import type { LayoutAlgorithm } from './types.ts';
+export declare const ALGORITHMS: LayoutAlgorithm[];
+export declare const defaults: LayoutSettings;
+/** Checked settings: defaults under `values`, old names mapped, numbers held to their ranges. */
+export declare function settings(values?: object): LayoutSettings;

package/dist/types/src/engines/layout/topology.d.ts

@@ -0,0 +1,18 @@
+import type { LayoutIntent, Link, Settings, Topology } from './types.ts';
+/**
+ * The link structure of one solve: neighbours, feedback links, longest-path ranks and connected
+ * parts. Links stay as given; a feedback link is only left out of the ranks.
+ */
+export declare function topology<E extends Link>(items: Array<{
+    id: string;
+}>, edges: E[], intent?: LayoutIntent): Topology<E>;
+/** Hop counts between every pair of items that links join. */
+export declare function shortestPaths(t: Topology): Map<string, Map<string, number>>;
+export interface Forest {
+    roots: string[];
+    parent: Map<string, string>;
+    kids: Map<string, string[]>;
+    depth: Map<string, number>;
+}
+/** A breadth-first spanning forest: from the chosen root, then every source, then the rest. */
+export declare function forest(t: Topology, s: Settings): Forest;

package/dist/types/src/engines/layout/trees.d.ts

@@ -0,0 +1,8 @@
+import type { Centres, Item, Link, Settings, Topology } from './types.ts';
+/** A span-based tree: each subtree gets its own width and parents sit over their children. */
+export declare function treeTarget(items: Item[], t: Topology, s: Settings): Centres;
+/** Rings round each root by depth. No solve reaches it: see `Settings`. */
+export declare function radialTarget(items: Item[], t: Topology, s: Settings): Centres;
+export declare function bilateralTarget(items: Item[], t: Topology, s: Settings): Centres | null;
+/** Which way a forward link should run: 1, -1 on the far side of a centred start, 0 across it. */
+export declare function forwardSign(t: Topology, e: Link): number;