@tscomfy/layout 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the tscomfy authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @tscomfy/layout
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Automatic layout for tscomfy workflows written in the ComfyUI frontend's UI format: positions
+for `toUi`, in columns by dependency depth, left to right. Pure, with no runtime dependencies.
+
+```sh
+npm install @tscomfy/layout @tscomfy/core
+```
+
+```ts
+import { stringify, toUi } from "@tscomfy/core";
+import { layout } from "@tscomfy/layout";
+
+const { workflow: ui } = toUi(txt2img, { positions: layout(txt2img) });
+const file = stringify(ui); // opens in the ComfyUI frontend
+```
+
+Needs ES2024 (Node 24 or later, Bun 1.4 or later). See the [guides](https://github.com/TheeKia/tscomfy/tree/main/docs/guides), in particular
+[the UI format](https://github.com/TheeKia/tscomfy/tree/main/docs/guides/ui-format.md).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @module @tscomfy/layout
+ *
+ * Automatic layout for workflows exported to the ComfyUI frontend's UI format:
+ * positions for `toUi`. Pure and runtime-agnostic, like core.
+ */
+export { layered, type LayoutBox, type LayoutSpacing, type Position } from "./layered.ts";
+export { layout } from "./layout.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC1F,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @module @tscomfy/layout
+ *
+ * Automatic layout for workflows exported to the ComfyUI frontend's UI format:
+ * positions for `toUi`. Pure and runtime-agnostic, like core.
+ */
+export { layered } from "./layered.js";
+export { layout } from "./layout.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAqD,MAAM,cAAc,CAAC;AAC1F,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/layered.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A box to place: its size, and the boxes its inputs come from. Sizes and positions are in the
+ * same units, canvas units for `toUi` (the frontend's pixels at zoom 1).
+ */
+export interface LayoutBox {
+    /** Unique among the boxes laid out together. */
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+    /** Ids of the boxes linked into this one; unknown ids and cycles are ignored. */
+    readonly sources: readonly string[];
+}
+/** Gaps between boxes, in the units of their sizes. */
+export interface LayoutSpacing {
+    /** Between a column's widest box and the next column. */
+    readonly column: number;
+    /** Between one box and the next in a column. */
+    readonly row: number;
+}
+/** Where a box goes: its top-left corner. */
+export type Position = readonly [x: number, y: number];
+/**
+ * Positions for boxes that flow left to right: a box sits one column right of its rightmost
+ * source, boxes without sources in the first column; in each column boxes are ordered by the
+ * average row of their sources (ties by input order), and each column is as wide as its widest
+ * box. Boxes on a cycle go where the cycle is broken, in input order. The first column starts at
+ * x 0 and every column at y 0; `spacing` defaults to 80 between columns and 40 between rows.
+ *
+ * Throws a `TypeError` when two boxes share an id: their positions couldn't be told apart.
+ */
+export declare function layered(boxes: readonly LayoutBox[], spacing?: LayoutSpacing): ReadonlyMap<string, Position>;
+//# sourceMappingURL=layered.d.ts.map

package/dist/layered.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layered.d.ts","sourceRoot":"","sources":["../src/layered.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAKD,6CAA6C;AAC7C,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;AAEvD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,OAAO,GAAE,aAA+B,GACvC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CA4C/B"}

package/dist/layered.js

@@ -0,0 +1,97 @@
+// A layered layout (after Sugiyama et al., much simplified): columns by dependency depth, rows
+// in each column ordered by where their sources sit, then packed from the top. Deterministic,
+// and linear apart from one sort per column.
+/** The spacing unless one is given. */
+const DEFAULT_SPACING = { column: 80, row: 40 };
+/**
+ * Positions for boxes that flow left to right: a box sits one column right of its rightmost
+ * source, boxes without sources in the first column; in each column boxes are ordered by the
+ * average row of their sources (ties by input order), and each column is as wide as its widest
+ * box. Boxes on a cycle go where the cycle is broken, in input order. The first column starts at
+ * x 0 and every column at y 0; `spacing` defaults to 80 between columns and 40 between rows.
+ *
+ * Throws a `TypeError` when two boxes share an id: their positions couldn't be told apart.
+ */
+export function layered(boxes, spacing = DEFAULT_SPACING) {
+    const index = new Map();
+    for (const [position, box] of boxes.entries()) {
+        if (index.has(box.id)) {
+            throw new TypeError(`layered: two boxes have the id ${JSON.stringify(box.id)}`);
+        }
+        index.set(box.id, position);
+    }
+    const columns = depths(boxes, index);
+    const byColumn = new Map();
+    for (const box of boxes) {
+        const column = columns.get(box.id) ?? 0;
+        const list = byColumn.get(column);
+        if (list === undefined)
+            byColumn.set(column, [box]);
+        else
+            list.push(box);
+    }
+    const rows = new Map();
+    const positions = new Map();
+    let x = 0;
+    for (const column of [...byColumn.keys()].toSorted((a, b) => a - b)) {
+        const members = byColumn.get(column) ?? [];
+        const order = (box) => {
+            const placed = box.sources.flatMap((source) => {
+                const row = rows.get(source);
+                return row === undefined ? [] : [row];
+            });
+            return placed.length === 0
+                ? Number.POSITIVE_INFINITY
+                : placed.reduce((sum, row) => sum + row, 0) / placed.length;
+        };
+        const sorted = members
+            .map((box) => ({ box, key: order(box), at: index.get(box.id) ?? 0 }))
+            .toSorted((a, b) => (a.key === b.key ? a.at - b.at : a.key < b.key ? -1 : 1));
+        let y = 0;
+        let width = 0;
+        for (const [row, { box }] of sorted.entries()) {
+            rows.set(box.id, row);
+            positions.set(box.id, [x, y]);
+            y += box.height + spacing.row;
+            width = Math.max(width, box.width);
+        }
+        x += width + spacing.column;
+    }
+    return positions;
+}
+/** Each box's column: the longest path from a box without sources (iterative, cycle-safe). */
+function depths(boxes, index) {
+    const depth = new Map();
+    const state = new Map();
+    for (const start of boxes) {
+        if (state.has(start.id))
+            continue;
+        const stack = [{ box: start, next: 0 }];
+        state.set(start.id, "open");
+        while (stack.length > 0) {
+            const frame = stack.at(-1);
+            if (frame === undefined)
+                break;
+            const source = frame.box.sources[frame.next++];
+            if (source !== undefined) {
+                const at = index.get(source);
+                const box = at === undefined ? undefined : boxes[at];
+                // Unknown sources, and back edges of a cycle, don't count.
+                if (box !== undefined && !state.has(box.id)) {
+                    state.set(box.id, "open");
+                    stack.push({ box, next: 0 });
+                }
+                continue;
+            }
+            stack.pop();
+            state.set(frame.box.id, "done");
+            const sources = frame.box.sources.flatMap((id) => {
+                const value = state.get(id) === "done" ? depth.get(id) : undefined;
+                return value === undefined ? [] : [value];
+            });
+            depth.set(frame.box.id, sources.length === 0 ? 0 : Math.max(...sources) + 1);
+        }
+    }
+    return depth;
+}
+//# sourceMappingURL=layered.js.map

package/dist/layered.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layered.js","sourceRoot":"","sources":["../src/layered.ts"],"names":[],"mappings":"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"}

package/dist/layout.d.ts

@@ -0,0 +1,15 @@
+import { type NodeId, type Workflow } from "@tscomfy/core";
+import { type LayoutSpacing, type Position } from "./layered.ts";
+/**
+ * Positions for `toUi`: the workflow laid out left to right in columns by
+ * dependency depth (see {@link layered}), each node the size `toUi` writes for it. A node's
+ * sources are the nodes its inputs link to, inside lists, Autogrow slots and dynamic-combo
+ * options too. `spacing` is in canvas units and defaults to 80 between columns and 40 between
+ * rows.
+ *
+ * ```ts
+ * const { workflow: ui } = toUi(built, { positions: layout(built) });
+ * ```
+ */
+export declare function layout(workflow: Workflow, spacing?: LayoutSpacing): ReadonlyMap<NodeId, Position>;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,MAAM,EAEX,KAAK,QAAQ,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAW,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAOjG"}

package/dist/layout.js

@@ -0,0 +1,36 @@
+import { isOutputRef, uiNodeSizes, } from "@tscomfy/core";
+import { layered } from "./layered.js";
+/**
+ * Positions for `toUi`: the workflow laid out left to right in columns by
+ * dependency depth (see {@link layered}), each node the size `toUi` writes for it. A node's
+ * sources are the nodes its inputs link to, inside lists, Autogrow slots and dynamic-combo
+ * options too. `spacing` is in canvas units and defaults to 80 between columns and 40 between
+ * rows.
+ *
+ * ```ts
+ * const { workflow: ui } = toUi(built, { positions: layout(built) });
+ * ```
+ */
+export function layout(workflow, spacing) {
+    const sizes = uiNodeSizes(workflow);
+    const boxes = [...workflow.graph.nodes.values()].map((node) => {
+        const [width, height] = sizes.get(node.id) ?? [0, 0];
+        return { id: node.id, width, height, sources: sources(node.inputs) };
+    });
+    return layered(boxes, spacing);
+}
+/** The nodes a node's inputs link to. */
+function sources(inputs) {
+    const found = new Set();
+    const pending = Object.values(inputs);
+    for (let value = pending.pop(); value !== undefined; value = pending.pop()) {
+        if (isOutputRef(value))
+            found.add(value.node);
+        else if (Array.isArray(value))
+            pending.push(...value);
+        else if (typeof value === "object" && value !== null)
+            pending.push(...Object.values(value));
+    }
+    return [...found];
+}
+//# sourceMappingURL=layout.js.map

package/dist/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EAGX,WAAW,GAEZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAqC,MAAM,cAAc,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,MAAM,CAAC,QAAkB,EAAE,OAAuB;IAChE,MAAM,KAAK,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC5D,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrD,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IACvE,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACjC,CAAC;AAED,yCAAyC;AACzC,SAAS,OAAO,CAAC,MAA+C;IAC9D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,MAAM,OAAO,GAAiB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACpD,KAAK,IAAI,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,KAAK,SAAS,EAAE,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;QAC3E,IAAI,WAAW,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;aACzC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,GAAI,KAA+B,CAAC,CAAC;aAC5E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC"}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@tscomfy/layout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Automatic layout for tscomfy workflows written in the ComfyUI frontend's UI format.",
+  "keywords": [
+    "comfyui",
+    "graph",
+    "layout",
+    "typescript",
+    "workflow"
+  ],
+  "homepage": "https://github.com/TheeKia/tscomfy/tree/main/packages/layout#readme",
+  "bugs": "https://github.com/TheeKia/tscomfy/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheeKia/tscomfy.git",
+    "directory": "packages/layout"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@tscomfy/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@tscomfy/core": "0.1.0",
+    "@tscomfy/fixtures": "0.0.0"
+  },
+  "peerDependencies": {
+    "@tscomfy/core": "^0.1.0"
+  },
+  "engines": {
+    "bun": ">=1.4",
+    "node": ">=24"
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @module @tscomfy/layout
+ *
+ * Automatic layout for workflows exported to the ComfyUI frontend's UI format:
+ * positions for `toUi`. Pure and runtime-agnostic, like core.
+ */
+
+export { layered, type LayoutBox, type LayoutSpacing, type Position } from "./layered.ts";
+export { layout } from "./layout.ts";

package/src/layered.ts

@@ -0,0 +1,125 @@
+// A layered layout (after Sugiyama et al., much simplified): columns by dependency depth, rows
+// in each column ordered by where their sources sit, then packed from the top. Deterministic,
+// and linear apart from one sort per column.
+
+/**
+ * A box to place: its size, and the boxes its inputs come from. Sizes and positions are in the
+ * same units, canvas units for `toUi` (the frontend's pixels at zoom 1).
+ */
+export interface LayoutBox {
+  /** Unique among the boxes laid out together. */
+  readonly id: string;
+  readonly width: number;
+  readonly height: number;
+  /** Ids of the boxes linked into this one; unknown ids and cycles are ignored. */
+  readonly sources: readonly string[];
+}
+
+/** Gaps between boxes, in the units of their sizes. */
+export interface LayoutSpacing {
+  /** Between a column's widest box and the next column. */
+  readonly column: number;
+  /** Between one box and the next in a column. */
+  readonly row: number;
+}
+
+/** The spacing unless one is given. */
+const DEFAULT_SPACING: LayoutSpacing = { column: 80, row: 40 };
+
+/** Where a box goes: its top-left corner. */
+export type Position = readonly [x: number, y: number];
+
+/**
+ * Positions for boxes that flow left to right: a box sits one column right of its rightmost
+ * source, boxes without sources in the first column; in each column boxes are ordered by the
+ * average row of their sources (ties by input order), and each column is as wide as its widest
+ * box. Boxes on a cycle go where the cycle is broken, in input order. The first column starts at
+ * x 0 and every column at y 0; `spacing` defaults to 80 between columns and 40 between rows.
+ *
+ * Throws a `TypeError` when two boxes share an id: their positions couldn't be told apart.
+ */
+export function layered(
+  boxes: readonly LayoutBox[],
+  spacing: LayoutSpacing = DEFAULT_SPACING,
+): ReadonlyMap<string, Position> {
+  const index = new Map<string, number>();
+  for (const [position, box] of boxes.entries()) {
+    if (index.has(box.id)) {
+      throw new TypeError(`layered: two boxes have the id ${JSON.stringify(box.id)}`);
+    }
+    index.set(box.id, position);
+  }
+  const columns = depths(boxes, index);
+  const byColumn = new Map<number, LayoutBox[]>();
+  for (const box of boxes) {
+    const column = columns.get(box.id) ?? 0;
+    const list = byColumn.get(column);
+    if (list === undefined) byColumn.set(column, [box]);
+    else list.push(box);
+  }
+  const rows = new Map<string, number>();
+  const positions = new Map<string, Position>();
+  let x = 0;
+  for (const column of [...byColumn.keys()].toSorted((a, b) => a - b)) {
+    const members = byColumn.get(column) ?? [];
+    const order = (box: LayoutBox): number => {
+      const placed = box.sources.flatMap((source) => {
+        const row = rows.get(source);
+        return row === undefined ? [] : [row];
+      });
+      return placed.length === 0
+        ? Number.POSITIVE_INFINITY
+        : placed.reduce((sum, row) => sum + row, 0) / placed.length;
+    };
+    const sorted = members
+      .map((box) => ({ box, key: order(box), at: index.get(box.id) ?? 0 }))
+      .toSorted((a, b) => (a.key === b.key ? a.at - b.at : a.key < b.key ? -1 : 1));
+    let y = 0;
+    let width = 0;
+    for (const [row, { box }] of sorted.entries()) {
+      rows.set(box.id, row);
+      positions.set(box.id, [x, y]);
+      y += box.height + spacing.row;
+      width = Math.max(width, box.width);
+    }
+    x += width + spacing.column;
+  }
+  return positions;
+}
+
+/** Each box's column: the longest path from a box without sources (iterative, cycle-safe). */
+function depths(
+  boxes: readonly LayoutBox[],
+  index: ReadonlyMap<string, number>,
+): ReadonlyMap<string, number> {
+  const depth = new Map<string, number>();
+  const state = new Map<string, "open" | "done">();
+  for (const start of boxes) {
+    if (state.has(start.id)) continue;
+    const stack: { readonly box: LayoutBox; next: number }[] = [{ box: start, next: 0 }];
+    state.set(start.id, "open");
+    while (stack.length > 0) {
+      const frame = stack.at(-1);
+      if (frame === undefined) break;
+      const source = frame.box.sources[frame.next++];
+      if (source !== undefined) {
+        const at = index.get(source);
+        const box = at === undefined ? undefined : boxes[at];
+        // Unknown sources, and back edges of a cycle, don't count.
+        if (box !== undefined && !state.has(box.id)) {
+          state.set(box.id, "open");
+          stack.push({ box, next: 0 });
+        }
+        continue;
+      }
+      stack.pop();
+      state.set(frame.box.id, "done");
+      const sources = frame.box.sources.flatMap((id) => {
+        const value = state.get(id) === "done" ? depth.get(id) : undefined;
+        return value === undefined ? [] : [value];
+      });
+      depth.set(frame.box.id, sources.length === 0 ? 0 : Math.max(...sources) + 1);
+    }
+  }
+  return depth;
+}

package/src/layout.ts

@@ -0,0 +1,40 @@
+import {
+  isOutputRef,
+  type InputValue,
+  type NodeId,
+  uiNodeSizes,
+  type Workflow,
+} from "@tscomfy/core";
+import { layered, type LayoutSpacing, type Position } from "./layered.ts";
+
+/**
+ * Positions for `toUi`: the workflow laid out left to right in columns by
+ * dependency depth (see {@link layered}), each node the size `toUi` writes for it. A node's
+ * sources are the nodes its inputs link to, inside lists, Autogrow slots and dynamic-combo
+ * options too. `spacing` is in canvas units and defaults to 80 between columns and 40 between
+ * rows.
+ *
+ * ```ts
+ * const { workflow: ui } = toUi(built, { positions: layout(built) });
+ * ```
+ */
+export function layout(workflow: Workflow, spacing?: LayoutSpacing): ReadonlyMap<NodeId, Position> {
+  const sizes = uiNodeSizes(workflow);
+  const boxes = [...workflow.graph.nodes.values()].map((node) => {
+    const [width, height] = sizes.get(node.id) ?? [0, 0];
+    return { id: node.id, width, height, sources: sources(node.inputs) };
+  });
+  return layered(boxes, spacing);
+}
+
+/** The nodes a node's inputs link to. */
+function sources(inputs: { readonly [name: string]: InputValue }): string[] {
+  const found = new Set<string>();
+  const pending: InputValue[] = Object.values(inputs);
+  for (let value = pending.pop(); value !== undefined; value = pending.pop()) {
+    if (isOutputRef(value)) found.add(value.node);
+    else if (Array.isArray(value)) pending.push(...(value as readonly InputValue[]));
+    else if (typeof value === "object" && value !== null) pending.push(...Object.values(value));
+  }
+  return [...found];
+}