@loadmap/layout 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Rojas
+
+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,6 @@
-# Temporary Holding Version
+# @loadmap/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.
+Views for [loadmap](https://jaim3r0jas.github.io/loadmap/) models (`defineView`, `node`, `cluster`, `pool`, `edge`) and
+their layout with ELK: boxes, orthogonal edges, labels sized for their widest text so the load never moves the
+diagram and no label covers another. `layout()` takes an ELK engine; by default it imports ELK on first use.
+`@loadmap/react` re-exports the view API and runs ELK in a Web Worker. MIT.

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+import { Dyn, Evaluation, LooseValues, Model } from "@loadmap/core";
+/** Width in px of `text` at `size` px. The browser passes a canvas measurer; Node uses the estimate below. */
+type TextMeasure = (text: string, size: number, weight?: number) => number;
+/** A sans-serif estimate, slightly generous so labels laid out with it never end up narrower than they render. */
+export declare const estimateText: TextMeasure;
+/** Text, or text computed from the model's context (e.g. a rate). */
+type Label = string | ((ctx: LooseValues) => string);
+/** A theme token (accent, alt, ok, warn, drop, muted) or any CSS colour. */
+type FlowColor = 'accent' | 'alt' | 'ok' | 'warn' | 'drop' | 'muted' | (string & {});
+interface NodeDef<S extends string = string> {
+  kind: 'node';
+  label: Label;
+  sub?: Label;
+  /** The stage this node shows: dots stop here, and it takes its component's state colour. */
+  stage?: S;
+  /** A component to colour by, for a node that is not a stage. */
+  component?: string;
+  shape: 'box' | 'cylinder';
+}
+/**
+ * A cluster of members (brokers) holding the partitions of one or several queue stages (topics): partition i of each
+ * on member i mod n.
+ */
+interface ClusterDef<S extends string = string> {
+  kind: 'cluster';
+  label: Label;
+  sub?: Label;
+  stage: S | readonly S[];
+  members: Dyn<number>;
+  memberLabel?: (i: number) => string;
+}
+/** A workers stage drawn as pods holding a grid of workers. */
+interface PoolDef<S extends string = string> {
+  kind: 'pool';
+  label: Label;
+  sub?: Label;
+  stage: S;
+  podLabel?: (i: number) => string;
+}
+type AnyNodeDef<S extends string = string> = NodeDef<S> | ClusterDef<S> | PoolDef<S>;
+interface EdgeDef<N extends string = string> {
+  from: N;
+  to: N;
+  label?: Label;
+  /** The edge is left out when this returns false. */
+  when?: (ctx: LooseValues) => unknown;
+}
+interface FlowView<N extends string = string> {
+  /** The node a flow's dots start from. */
+  from: N;
+  color: FlowColor;
+  label?: string;
+}
+interface ViewDef<F extends string, S extends string, N extends string> {
+  nodes: { [K in N]: AnyNodeDef<NoInfer<S>>; };
+  edges: readonly EdgeDef<NoInfer<N>>[];
+  flows: { [K in F]: FlowView<NoInfer<N>>; };
+}
+interface View<F extends string = string, S extends string = string, N extends string = string> {
+  model: Model<any, F, any, S>;
+  def: ViewDef<F, S, N>;
+}
+export declare function defineView<P, F extends string, C extends string, S extends string, const N extends string>(model: Model<P, F, C, S>, def: ViewDef<F, S, N>): View<F, S, N>;
+export declare function node<const S extends string = never>(o: {
+  label: Label;
+  sub?: Label;
+  stage?: S;
+  component?: string;
+  shape?: NodeDef['shape'];
+}): NodeDef<S>;
+export declare function cluster<const S extends string>(o: Omit<ClusterDef<S>, 'kind'>): ClusterDef<S>;
+export declare function pool<const S extends string>(o: Omit<PoolDef<S>, 'kind'>): PoolDef<S>;
+export declare function edge<const A extends string, const B extends string>(from: A, to: B, o?: {
+  label?: Label;
+  when?: EdgeDef['when'];
+}): EdgeDef<A | B>;
+type Direction = 'RIGHT' | 'DOWN';
+interface Box {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+/** Where a piece of text sits; the text itself comes from `labelsAt`, since it changes with the values. */
+interface TextSpot {
+  x: number;
+  y: number;
+  size: number;
+  weight: number;
+}
+interface Cell extends Box {
+  stage: string;
+  flow: string;
+  /** The partition's index within its flow. */
+  index: number;
+}
+interface SceneNode extends Box {
+  id: string;
+  kind: AnyNodeDef['kind'];
+  shape: 'box' | 'cylinder';
+  /** The stages this node shows: one, or several queues for a cluster that holds several topics. */
+  stages: string[];
+  component?: string;
+  title: TextSpot;
+  sub?: TextSpot;
+  /** Cluster members (brokers) and pods, with their own small labels. */
+  members: (Box & {
+    label: string;
+    spot: TextSpot;
+  })[];
+  /** Per member, the name of each flow above its partitions. */
+  groups: {
+    flow: string;
+    text: string;
+    spot: TextSpot;
+  }[];
+  cells: Cell[];
+  /** Workers, indexed pod × workers per pod + worker, the index the sim's fill uses. */
+  slots: (Box & {
+    index: number;
+  })[];
+}
+interface SceneEdge {
+  id: string;
+  from: string;
+  to: string;
+  points: [number, number][];
+  /** The box reserved for the label, wide enough for its widest text across the load range. */
+  label?: Box;
+}
+interface Scene {
+  /** Changes only when something that moves the layout changes; the load alone never does. */
+  key: string;
+  direction: Direction;
+  width: number;
+  height: number;
+  nodes: SceneNode[];
+  edges: SceneEdge[];
+  /** The node that shows each stage, and the node each flow starts from. */
+  stageNode: Readonly<Record<string, string>>;
+  flowFrom: Readonly<Record<string, string>>;
+}
+interface LayoutOptions {
+  direction?: Direction;
+  measure?: TextMeasure;
+  /** Where ELK runs. Default: on this thread, loaded on first use. */
+  elk?: ElkEngine;
+}
+/**
+ * Lays out an ELK graph: ELK on this thread, or in a worker. Every engine gives the same result for a graph. The graph
+ * is typed loosely here so that our typings never pull in elkjs's (which fail a strict check without skipLibCheck).
+ */
+interface ElkEngine {
+  layout(graph: ElkGraph): Promise<ElkGraph>;
+}
+/** An ELK JSON graph (elkjs's ElkNode). */
+type ElkGraph = {
+  id: string;
+} & Record<string, unknown>;
+/** ELK on this thread, imported on first use: it is about 1.6 MB, so it stays out of a page's first load. */
+export declare function localElk(): Promise<ElkEngine>;
+/** The current text of every label. Cheap: call it on every change of values; the layout stays put. */
+export declare function labelsAt(view: View, ev: Evaluation): {
+  nodes: Record<string, {
+    title: string;
+    sub?: string;
+  }>;
+  edges: Record<string, string>;
+};
+/**
+ * Lays the view out for the current values: grids inside clusters and pools are packed here; ELK places the boxes,
+ * routes the edges and places the edge labels so that none overlaps another or a node. Results are cached by the
+ * structure, so a call after a load change returns the same scene.
+ */
+export declare function layout(view: View, ev: Evaluation, o?: LayoutOptions): Promise<Scene>;
+/** The structure key for the current values: equal keys give equal scenes. */
+export declare function structureKey(view: View, ev: Evaluation, o?: LayoutOptions): string;
+type Point = [number, number];
+interface Collision {
+  a: string;
+  b: string;
+}
+/** Every edge label that overlaps another edge label or a node. An empty list is the layout's promise. */
+export declare function collisions(scene: Scene, slack?: number): Collision[];
+/** Where a dot sits at a place: a partition cell, a worker, or the middle of the stage's node. */
+export declare function anchor(scene: Scene, place: {
+  stage: string | null;
+  cell?: number;
+}, flow: string): Point;
+/** The path a dot takes between two places: along the edge between their nodes when there is one. */
+export declare function legPath(scene: Scene, from: {
+  stage: string | null;
+  cell?: number;
+}, to: {
+  stage: string | null;
+  cell?: number;
+}, flow: string): Point[];
+/** The point a share `t` (0–1) along a polyline, by length. */
+export declare function pointAt(points: readonly Point[], t: number): Point;
+export type { AnyNodeDef, Box, Cell, ClusterDef, Collision, Direction, EdgeDef, ElkEngine, ElkGraph, FlowColor, FlowView, Label, LayoutOptions, NodeDef, Point, PoolDef, Scene, SceneEdge, SceneNode, TextMeasure, TextSpot, View, ViewDef };

package/dist/index.js

@@ -0,0 +1,574 @@
+import { dyn } from "@loadmap/core";
+// src/geometry.ts
+const overlap = (p, q, slack) => p.x < q.x + q.w - slack && q.x < p.x + p.w - slack && p.y < q.y + q.h - slack && q.y < p.y + p.h - slack;
+/** Every edge label that overlaps another edge label or a node. An empty list is the layout's promise. */
+function collisions(scene, slack = .5) {
+	const labels = scene.edges.filter((e) => e.label).map((e) => ({
+		id: `label ${e.id} (${e.from}→${e.to})`,
+		box: e.label
+	}));
+	const out = [];
+	labels.forEach((l, i) => {
+		for (const m of labels.slice(i + 1)) if (overlap(l.box, m.box, slack)) out.push({
+			a: l.id,
+			b: m.id
+		});
+		for (const n of scene.nodes) if (overlap(l.box, n, slack)) out.push({
+			a: l.id,
+			b: `node ${n.id}`
+		});
+	});
+	scene.nodes.forEach((n, i) => {
+		for (const m of scene.nodes.slice(i + 1)) if (overlap(n, m, slack)) out.push({
+			a: `node ${n.id}`,
+			b: `node ${m.id}`
+		});
+	});
+	return out;
+}
+const centre = (b) => [b.x + b.w / 2, b.y + b.h / 2];
+/** Where a dot sits at a place: a partition cell, a worker, or the middle of the stage's node. */
+function anchor(scene, place, flow) {
+	const n = nodeOf(scene, place.stage, flow);
+	if (!n) return [0, 0];
+	if (place.cell != null) {
+		const cell = n.cells.find((c) => c.stage === place.stage && c.flow === flow && c.index === place.cell) ?? n.slots[place.cell];
+		if (cell) return centre(cell);
+	}
+	return centre(n);
+}
+/** The path a dot takes between two places: along the edge between their nodes when there is one. */
+function legPath(scene, from, to, flow) {
+	const a = anchor(scene, from, flow);
+	const b = anchor(scene, to, flow);
+	const na = nodeOf(scene, from.stage, flow);
+	const nb = nodeOf(scene, to.stage, flow);
+	const e = na && nb ? scene.edges.find((x) => x.from === na.id && x.to === nb.id) : void 0;
+	return e?.points.length ? [
+		a,
+		...e.points,
+		b
+	] : [a, b];
+}
+/** The point a share `t` (0–1) along a polyline, by length. */
+function pointAt(points, t) {
+	if (points.length < 2) return points[0] ?? [0, 0];
+	const lens = points.slice(1).map((p, i) => Math.hypot(p[0] - points[i][0], p[1] - points[i][1]));
+	let left = Math.min(1, Math.max(0, t)) * lens.reduce((s, l) => s + l, 0);
+	for (let i = 0; i < lens.length; i++) {
+		const l = lens[i];
+		if (left <= l || i === lens.length - 1) {
+			const k = l > 0 ? Math.min(1, left / l) : 1;
+			const p = points[i];
+			const q = points[i + 1];
+			return [p[0] + (q[0] - p[0]) * k, p[1] + (q[1] - p[1]) * k];
+		}
+		left -= l;
+	}
+	return points.at(-1);
+}
+function nodeOf(scene, stage, flow) {
+	const id = stage == null ? scene.flowFrom[flow] : scene.stageNode[stage];
+	return scene.nodes.find((n) => n.id === id);
+}
+// src/text.ts
+const NARROW = /* @__PURE__ */ new Set([..."ijlrtf.,:;|!'\"()[] "]);
+const WIDE = /* @__PURE__ */ new Set([..."mwMW@%"]);
+/** A sans-serif estimate, slightly generous so labels laid out with it never end up narrower than they render. */
+const estimateText = (text, size, weight = 400) => {
+	let em = 0;
+	for (const ch of text) if (NARROW.has(ch)) em += .32;
+	else if (WIDE.has(ch)) em += .86;
+	else if (ch >= "A" && ch <= "Z") em += .68;
+	else em += .57;
+	return Math.ceil(em * size * (weight >= 600 ? 1.06 : 1));
+};
+// src/layout.ts
+let local = null;
+/** ELK on this thread, imported on first use: it is about 1.6 MB, so it stays out of a page's first load. */
+function localElk() {
+	local ??= import("elkjs/lib/elk.bundled.js").then((m) => new m.default(), (err) => {
+		local = null;
+		throw err;
+	});
+	return local;
+}
+const T_TITLE = {
+	size: 13,
+	weight: 600
+};
+const T_SUB = {
+	size: 11,
+	weight: 400
+};
+const T_SMALL = {
+	size: 9,
+	weight: 400
+};
+const PAD = 8;
+const GAP = 6;
+const CELL = 9;
+const CELL_COLS = 6;
+const SLOT = 10;
+const SLOT_GAP = 3;
+const LABEL_H = 16;
+const scenes = /* @__PURE__ */ new WeakMap();
+const sampleCache = /* @__PURE__ */ new WeakMap();
+/** The current text of every label. Cheap: call it on every change of values; the layout stays put. */
+function labelsAt(view, ev) {
+	const ctx = ev.ctx;
+	const nodes = {};
+	for (const [id, n] of Object.entries(view.def.nodes)) nodes[id] = {
+		title: text(n.label, ctx),
+		sub: n.sub == null ? void 0 : text(n.sub, ctx)
+	};
+	const edges = {};
+	visibleEdges(view, ctx).forEach(({ e, id }) => {
+		if (e.label != null) edges[id] = text(e.label, ctx);
+	});
+	return {
+		nodes,
+		edges
+	};
+}
+/**
+* Lays the view out for the current values: grids inside clusters and pools are packed here; ELK places the boxes,
+* routes the edges and places the edge labels so that none overlaps another or a node. Results are cached by the
+* structure, so a call after a load change returns the same scene.
+*/
+function layout(view, ev, o = {}) {
+	const prep = prepare(view, ev, o.direction ?? "RIGHT", o.measure ?? estimateText);
+	const cache = scenes.get(view) ?? /* @__PURE__ */ new Map();
+	scenes.set(view, cache);
+	let hit = cache.get(prep.key);
+	if (!hit) {
+		hit = run(prep, o.elk).catch((err) => {
+			cache.delete(prep.key);
+			throw err;
+		});
+		if (cache.size > 32) cache.delete(cache.keys().next().value);
+		cache.set(prep.key, hit);
+	}
+	return hit;
+}
+/** The structure key for the current values: equal keys give equal scenes. */
+function structureKey(view, ev, o = {}) {
+	return prepare(view, ev, o.direction ?? "RIGHT", o.measure ?? estimateText).key;
+}
+function prepare(view, ev, direction, measure) {
+	const widest = labelWidths(view, ev, measure);
+	const stageNode = {};
+	const nodes = Object.entries(view.def.nodes).map(([id, def]) => {
+		const own = stagesOf(def);
+		for (const st of own) stageNode[st] = id;
+		const titleW = widest(def.label, T_TITLE.size, T_TITLE.weight);
+		const subW = widest(def.sub, T_SUB.size, T_SUB.weight);
+		const resolved = own.map((st) => ev.stages[st]);
+		const stage = resolved[0];
+		const queues = resolved.filter((r) => r.kind === "queue");
+		return {
+			id,
+			def,
+			inner: def.kind === "cluster" && queues.length ? clusterInner(def, queues, ev.ctx, direction, titleW, subW, measure, view) : def.kind === "pool" && stage?.kind === "workers" ? poolInner(def, stage, direction, titleW, subW) : boxInner(titleW, subW, def.sub != null, def.kind === "node" && def.shape === "cylinder" ? 8 : 0)
+		};
+	});
+	const edges = visibleEdges(view, ev.ctx).map(({ e, id }) => ({
+		id,
+		from: e.from,
+		to: e.to,
+		labelW: e.label == null ? void 0 : widest(e.label, T_SUB.size, T_SUB.weight) + 8
+	}));
+	const flowFrom = {};
+	for (const [f, fv] of Object.entries(view.def.flows)) flowFrom[f] = fv.from;
+	return {
+		key: JSON.stringify({
+			direction,
+			nodes: nodes.map((n) => [
+				n.id,
+				n.def.kind,
+				n.inner
+			]),
+			edges,
+			flowFrom
+		}),
+		direction,
+		nodes,
+		edges,
+		stageNode,
+		flowFrom
+	};
+}
+/**
+* Labels are sized for their widest text over every load the slider can reach, so moving the load never moves the
+* layout. Text width does not grow steadily with a number ("9.9k" is wider than "10k"), hence every step, not a few.
+*/
+function labelWidths(view, ev, measure) {
+	const { load: _, ...rest } = ev.values;
+	const key = JSON.stringify(rest);
+	const byView = sampleCache.get(measure) ?? /* @__PURE__ */ new WeakMap();
+	sampleCache.set(measure, byView);
+	const byValues = byView.get(view) ?? /* @__PURE__ */ new Map();
+	byView.set(view, byValues);
+	let sampled = byValues.get(key);
+	if (!sampled) {
+		const { min, max, step } = view.model.load;
+		const n = Math.floor((max - min) / step);
+		sampled = {
+			contexts: (n <= 400 ? [...Array.from({ length: n + 1 }, (_, i) => min + i * step), max] : Array.from({ length: 401 }, (_, i) => min + (max - min) * i / 400)).map((load) => view.model.evaluate({
+				...ev.values,
+				load
+			}).ctx),
+			widths: /* @__PURE__ */ new Map()
+		};
+		if (byValues.size > 32) byValues.delete(byValues.keys().next().value);
+		byValues.set(key, sampled);
+	}
+	const { contexts, widths } = sampled;
+	return (l, size, weight) => {
+		if (l == null) return 0;
+		if (typeof l === "string") return measure(l, size, weight);
+		const byFont = widths.get(l) ?? /* @__PURE__ */ new Map();
+		widths.set(l, byFont);
+		const font = `${size}/${weight}`;
+		let w = byFont.get(font);
+		if (w == null) {
+			w = Math.max(...contexts.map((ctx) => measure(text(l, ctx), size, weight)));
+			byFont.set(font, w);
+		}
+		return w;
+	};
+}
+async function run(prep, elk) {
+	const graph = {
+		id: "root",
+		layoutOptions: {
+			"elk.algorithm": "layered",
+			"elk.direction": prep.direction,
+			"elk.edgeRouting": "ORTHOGONAL",
+			"elk.padding": "[top=16,left=16,bottom=16,right=16]",
+			"elk.spacing.nodeNode": "28",
+			"elk.spacing.edgeNode": "16",
+			"elk.spacing.edgeEdge": "12",
+			"elk.spacing.edgeLabel": "4",
+			"elk.layered.spacing.nodeNodeBetweenLayers": "48",
+			"elk.layered.spacing.edgeNodeBetweenLayers": "16",
+			"elk.layered.nodePlacement.strategy": "BRANDES_KOEPF",
+			"elk.layered.nodePlacement.bk.fixedAlignment": "BALANCED",
+			"elk.layered.edgeLabels.sideSelection": "ALWAYS_UP"
+		},
+		children: prep.nodes.map((n) => ({
+			id: n.id,
+			width: n.inner.w,
+			height: n.inner.h
+		})),
+		edges: prep.edges.map((e) => ({
+			id: e.id,
+			sources: [e.from],
+			targets: [e.to],
+			labels: e.labelW ? [{
+				id: `${e.id}:label`,
+				text: e.id,
+				width: e.labelW,
+				height: LABEL_H,
+				layoutOptions: { "elk.edgeLabels.placement": "CENTER" }
+			}] : []
+		}))
+	};
+	const out = await (elk ?? await localElk()).layout(graph);
+	const placed = new Map((out.children ?? []).map((c) => [c.id, c]));
+	const nodes = prep.nodes.map(({ id, def, inner }) => {
+		const c = placed.get(id);
+		return offset({
+			id,
+			kind: def.kind,
+			shape: def.kind === "node" ? def.shape : "box",
+			stages: stagesOf(def),
+			component: def.kind === "node" ? def.component : void 0,
+			...inner,
+			x: 0,
+			y: 0
+		}, c.x ?? 0, c.y ?? 0);
+	});
+	const edges = (out.edges ?? []).map((e) => {
+		const p = prep.edges.find((x) => x.id === e.id);
+		const points = [];
+		for (const s of e.sections ?? []) {
+			points.push([s.startPoint.x, s.startPoint.y]);
+			for (const b of s.bendPoints ?? []) points.push([b.x, b.y]);
+			points.push([s.endPoint.x, s.endPoint.y]);
+		}
+		const l = e.labels?.[0];
+		return {
+			id: e.id,
+			from: p.from,
+			to: p.to,
+			points,
+			label: l ? {
+				x: l.x ?? 0,
+				y: l.y ?? 0,
+				w: l.width ?? 0,
+				h: l.height ?? 0
+			} : void 0
+		};
+	});
+	return {
+		key: prep.key,
+		direction: prep.direction,
+		width: Math.ceil(out.width ?? 0),
+		height: Math.ceil(out.height ?? 0),
+		nodes,
+		edges,
+		stageNode: prep.stageNode,
+		flowFrom: prep.flowFrom
+	};
+}
+/** A plain box; `top` makes room for a cylinder's lid. */
+function boxInner(titleW, subW, hasSub, top) {
+	const w = Math.max(110, titleW + 24, subW + 24);
+	return {
+		w,
+		h: (hasSub ? 48 : 36) + top,
+		title: {
+			x: w / 2,
+			y: (hasSub ? 20 : 23) + top,
+			...T_TITLE
+		},
+		sub: hasSub ? {
+			x: w / 2,
+			y: 36 + top,
+			...T_SUB
+		} : void 0,
+		members: [],
+		groups: [],
+		cells: [],
+		slots: []
+	};
+}
+function header(titleW, subW, hasSub) {
+	return {
+		h: hasSub ? 40 : 26,
+		minW: Math.max(titleW, subW) + 16
+	};
+}
+function clusterInner(def, stages, ctx, direction, titleW, subW, measure, view) {
+	const m = Math.max(1, dyn(def.members, ctx));
+	const hd = header(titleW, subW, def.sub != null);
+	const flowName = (f) => view.def.flows[f]?.label ?? f;
+	const flows = stages.flatMap((st) => {
+		const parts = Object.entries(st.partitions).filter(([, n]) => n > 0);
+		return parts.map(([f, n]) => ({
+			stage: st.id,
+			f,
+			n,
+			text: stages.length > 1 ? parts.length > 1 ? `${st.label} · ${flowName(f)}` : st.label : flowName(f)
+		}));
+	});
+	const memberW = Math.max(64, ...flows.map((g) => measure(g.text, T_SMALL.size)), measure("member 00", T_SMALL.size)) + 12;
+	const rowsOf = (n, k) => Math.ceil(Math.ceil((n - k) / m) / CELL_COLS);
+	const memberH = (k) => 14 + flows.reduce((h, g) => h + 12 + rowsOf(g.n, k) * 11, 0) + 4;
+	const mh = Math.max(...Array.from({ length: m }, (_, k) => memberH(k)));
+	const down = direction === "DOWN";
+	const innerW = down ? m * memberW + (m - 1) * GAP : memberW;
+	const w = Math.max(innerW + 16, hd.minW);
+	const h = hd.h + (down ? mh : m * mh + (m - 1) * GAP) + PAD;
+	const x0 = (w - innerW) / 2;
+	const members = [];
+	const groups = [];
+	const cells = [];
+	for (let k = 0; k < m; k++) {
+		const bx = down ? x0 + k * (memberW + GAP) : x0;
+		const by = down ? hd.h : hd.h + k * (mh + GAP);
+		members.push({
+			x: bx,
+			y: by,
+			w: memberW,
+			h: mh,
+			label: def.memberLabel?.(k) ?? `member ${k}`,
+			spot: {
+				x: bx + GAP,
+				y: by + 11,
+				...T_SMALL
+			}
+		});
+		let cy = by + 14;
+		for (const { stage, f, n, text } of flows) {
+			groups.push({
+				flow: f,
+				text,
+				spot: {
+					x: bx + GAP,
+					y: cy + 9,
+					...T_SMALL
+				}
+			});
+			cy += 12;
+			for (let i = k, j = 0; i < n; i += m, j++) cells.push({
+				stage,
+				flow: f,
+				index: i,
+				x: bx + GAP + j % CELL_COLS * 11,
+				y: cy + Math.floor(j / CELL_COLS) * 11,
+				w: CELL,
+				h: CELL
+			});
+			cy += rowsOf(n, k) * 11;
+		}
+	}
+	return {
+		w,
+		h,
+		title: {
+			x: w / 2,
+			y: 17,
+			...T_TITLE
+		},
+		sub: def.sub != null ? {
+			x: w / 2,
+			y: 32,
+			...T_SUB
+		} : void 0,
+		members,
+		groups,
+		cells,
+		slots: []
+	};
+}
+function poolInner(def, stage, direction, titleW, subW) {
+	const { pods, perPod } = stage;
+	const hd = header(titleW, subW, def.sub != null);
+	const cols = Math.min(perPod, 4);
+	const rows = Math.ceil(perPod / cols);
+	const podW = Math.max(cols * 13 - SLOT_GAP + 12, 44);
+	const podH = 14 + rows * 13 - SLOT_GAP + GAP;
+	const podCols = direction === "DOWN" ? Math.min(pods, 3) : Math.ceil(pods / 3);
+	const podRows = Math.ceil(pods / podCols);
+	const innerW = podCols * podW + (podCols - 1) * GAP;
+	const w = Math.max(innerW + 16, hd.minW);
+	const h = hd.h + podRows * podH + (podRows - 1) * GAP + PAD;
+	const x0 = (w - innerW) / 2;
+	const members = [];
+	const slots = [];
+	for (let p = 0; p < pods; p++) {
+		const bx = x0 + p % podCols * (podW + GAP);
+		const by = hd.h + Math.floor(p / podCols) * (podH + GAP);
+		members.push({
+			x: bx,
+			y: by,
+			w: podW,
+			h: podH,
+			label: def.podLabel?.(p) ?? `pod ${p}`,
+			spot: {
+				x: bx + GAP,
+				y: by + 11,
+				...T_SMALL
+			}
+		});
+		const gx = bx + (podW - (cols * 13 - SLOT_GAP)) / 2;
+		for (let t = 0; t < perPod; t++) slots.push({
+			index: p * perPod + t,
+			x: gx + t % cols * 13,
+			y: by + 14 + Math.floor(t / cols) * 13,
+			w: SLOT,
+			h: SLOT
+		});
+	}
+	return {
+		w,
+		h,
+		title: {
+			x: w / 2,
+			y: 17,
+			...T_TITLE
+		},
+		sub: def.sub != null ? {
+			x: w / 2,
+			y: 32,
+			...T_SUB
+		} : void 0,
+		members,
+		groups: [],
+		cells: [],
+		slots
+	};
+}
+function offset(n, dx, dy) {
+	const box = (b) => ({
+		...b,
+		x: b.x + dx,
+		y: b.y + dy
+	});
+	const spot = (s) => ({
+		...s,
+		x: s.x + dx,
+		y: s.y + dy
+	});
+	return {
+		...n,
+		x: dx,
+		y: dy,
+		title: spot(n.title),
+		sub: n.sub && spot(n.sub),
+		members: n.members.map((m) => ({
+			...box(m),
+			spot: spot(m.spot)
+		})),
+		groups: n.groups.map((g) => ({
+			...g,
+			spot: spot(g.spot)
+		})),
+		cells: n.cells.map(box),
+		slots: n.slots.map(box)
+	};
+}
+function stagesOf(def) {
+	const st = def.stage;
+	return st == null ? [] : typeof st === "string" ? [st] : [...st];
+}
+function visibleEdges(view, ctx) {
+	return view.def.edges.map((e, i) => ({
+		e,
+		id: `e${i}`
+	})).filter(({ e }) => e.when ? Boolean(e.when(ctx)) : true);
+}
+function text(l, ctx) {
+	return typeof l === "function" ? l(ctx) : l;
+}
+// src/view.ts
+function defineView(model, def) {
+	const nodes = def.nodes;
+	for (const e of def.edges) for (const end of [e.from, e.to]) if (!(end in nodes)) throw new Error(`loadmap: edge to unknown node "${end}"`);
+	for (const [f, fv] of Object.entries(def.flows)) if (!(fv.from in nodes)) throw new Error(`loadmap: flow "${f}" starts at unknown node "${fv.from}"`);
+	const shows = (n, s) => Array.isArray(n.stage) ? n.stage.includes(s) : n.stage === s;
+	for (const s of model.stageIds) if (!Object.values(nodes).some((n) => shows(n, s))) throw new Error(`loadmap: no node shows stage "${s}"`);
+	return {
+		model,
+		def
+	};
+}
+function node(o) {
+	return {
+		kind: "node",
+		shape: "box",
+		...o
+	};
+}
+function cluster(o) {
+	return {
+		kind: "cluster",
+		...o
+	};
+}
+function pool(o) {
+	return {
+		kind: "pool",
+		...o
+	};
+}
+function edge(from, to, o = {}) {
+	return {
+		from,
+		to,
+		...o
+	};
+}
+export { anchor, cluster, collisions, defineView, edge, estimateText, labelsAt, layout, legPath, localElk, node, pointAt, pool, structureKey };

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@loadmap/layout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Views for loadmap models and their ELK layout: nodes, clusters, pools, edges, labels that never collide.",
+  "keywords": [
+    "loadmap",
+    "layout",
+    "elk",
+    "diagram"
+  ],
+  "license": "MIT",
+  "author": "Jaime Rojas",
+  "homepage": "https://jaim3r0jas.github.io/loadmap/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaim3r0jas/loadmap.git",
+    "directory": "packages/layout"
+  },
+  "bugs": "https://github.com/jaim3r0jas/loadmap/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@loadmap/core": "0.1.0",
+    "elkjs": "^0.12.1"
+  },
+  "peerDependencies": {},
+  "scripts": {
+    "build": "tsdown"
+  }
 }