bireactive 0.2.4 → 0.3.0

package/dist/propagators/graph.js

@@ -0,0 +1,543 @@
+// graph.ts — graph layout on the interval atoms.
+//
+// The headline is `rank`: layer assignment is longest-path, and
+// longest-path IS interval narrowing. For every edge u→v we assert
+// `order(layer(u), layer(v), 1)` (v sits at least one layer below u);
+// the solver narrows each layer cell's lower bound to the length of the
+// longest path reaching it. A merge node — many edges into one cell —
+// is fan-in narrowing, the thing a lens can't express.
+//
+// Everything after ranking (crossing reduction, coordinate assignment)
+// is the standard Sugiyama machinery: barycenter sweeps to order each
+// layer, then pool-adjacent-violators to place nodes as close to their
+// neighbours' barycenter as non-overlap allows. Those are heuristics,
+// not lattice operations, and are written as plain functions.
+//
+// Layouts share one engine: `layered` (4 directions), `tree`
+// (parents centred over children), `radial` (layers as rings), and
+// `lanes` (git-style column packing).
+import { intervalCell } from "./lattice.js";
+import { order } from "./numeric.js";
+import { solve } from "./solver.js";
+const DEFAULT_SIZE = { w: 46, h: 34 };
+// ── ranking: longest-path via interval narrowing ────────────────────
+/** Assign each node an integer layer so every edge increases layer by
+ *  ≥1. Cycles are broken (back edges reversed for ranking only). The
+ *  value is the longest path from a source — computed as the lower
+ *  bound the `order` atoms narrow each layer cell to. */
+export function rank(g) {
+    const acyclic = breakCycles(g);
+    const cell = new Map();
+    const hi = Math.max(1, g.nodes.length);
+    for (const n of g.nodes)
+        cell.set(n, intervalCell(0, hi));
+    const props = [];
+    for (const [u, v] of acyclic)
+        props.push(...order(cell.get(u), cell.get(v), 1));
+    const s = solve(...props);
+    const layer = new Map();
+    for (const n of g.nodes)
+        layer.set(n, Math.round(cell.get(n).value[0]));
+    s.dispose();
+    return layer;
+}
+/** Strongly-connected components (Tarjan), each a list of mutually
+ *  reachable nodes, in reverse-topological order of the condensation.
+ *  Singletons are size-1 components; a self-loop still reports size 1.
+ *  The cyclic cores of a graph are exactly the components of size > 1. */
+export function scc(g) {
+    const adj = new Map();
+    for (const n of g.nodes)
+        adj.set(n, []);
+    for (const [u, v] of g.edges)
+        adj.get(u)?.push(v);
+    let idx = 0;
+    const index = new Map();
+    const low = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const out = [];
+    const connect = (v) => {
+        index.set(v, idx);
+        low.set(v, idx);
+        idx++;
+        stack.push(v);
+        onStack.add(v);
+        for (const w of adj.get(v)) {
+            if (!index.has(w)) {
+                connect(w);
+                low.set(v, Math.min(low.get(v), low.get(w)));
+            }
+            else if (onStack.has(w)) {
+                low.set(v, Math.min(low.get(v), index.get(w)));
+            }
+        }
+        if (low.get(v) === index.get(v)) {
+            const comp = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                comp.push(w);
+            } while (w !== v);
+            out.push(comp);
+        }
+    };
+    for (const n of g.nodes)
+        if (!index.has(n))
+            connect(n);
+    return out;
+}
+/** Reverse edges that close a cycle (DFS back edges), returning an
+ *  acyclic edge list. Order of `g.edges` is otherwise preserved. */
+function breakCycles(g) {
+    const adj = new Map();
+    for (const n of g.nodes)
+        adj.set(n, []);
+    for (const [u, v] of g.edges)
+        adj.get(u)?.push(v);
+    const WHITE = 0;
+    const GREY = 1;
+    const BLACK = 2;
+    const color = new Map(g.nodes.map(n => [n, WHITE]));
+    const back = new Set();
+    const key = (u, v) => `${g.nodes.indexOf(u)}->${g.nodes.indexOf(v)}`;
+    const visit = (u) => {
+        color.set(u, GREY);
+        for (const v of adj.get(u) ?? []) {
+            const c = color.get(v);
+            if (c === GREY)
+                back.add(key(u, v)); // edge into the active stack
+            else if (c === WHITE)
+                visit(v);
+        }
+        color.set(u, BLACK);
+    };
+    for (const n of g.nodes)
+        if (color.get(n) === WHITE)
+            visit(n);
+    return g.edges.map(([u, v]) => (back.has(key(u, v)) ? [v, u] : [u, v]));
+}
+// ── crossing reduction ──────────────────────────────────────────────
+/** Group nodes by layer, ordered to reduce edge crossings via
+ *  barycenter sweeps. Returns the per-layer node arrays. */
+function ordered(g, layer, sweeps) {
+    const numLayers = Math.max(0, ...[...layer.values()].map(l => l + 1));
+    const layers = Array.from({ length: numLayers }, () => []);
+    for (const n of g.nodes)
+        layers[layer.get(n)].push(n);
+    const down = new Map(); // node → neighbours in layer below
+    const up = new Map(); // node → neighbours in layer above
+    for (const n of g.nodes) {
+        down.set(n, []);
+        up.set(n, []);
+    }
+    for (const [u, v] of g.edges) {
+        const lu = layer.get(u);
+        const lv = layer.get(v);
+        if (lu === lv)
+            continue;
+        const [hiNode, loNode] = lu < lv ? [u, v] : [v, u];
+        down.get(hiNode).push(loNode);
+        up.get(loNode).push(hiNode);
+    }
+    const indexIn = (arr) => new Map(arr.map((n, i) => [n, i]));
+    const sweep = (from, to, step, side) => {
+        for (let l = from; l !== to; l += step) {
+            const ref = indexIn(layers[l - step]);
+            const bary = (n) => {
+                const nb = side.get(n);
+                if (nb.length === 0)
+                    return Number.POSITIVE_INFINITY; // keep relative order
+                let acc = 0;
+                for (const m of nb)
+                    acc += ref.get(m);
+                return acc / nb.length;
+            };
+            const b = new Map(layers[l].map(n => [n, bary(n)]));
+            // Stable sort; nodes with no neighbours (Infinity) hold position.
+            layers[l].sort((p, q) => {
+                const bp = b.get(p);
+                const bq = b.get(q);
+                if (!Number.isFinite(bp) || !Number.isFinite(bq))
+                    return 0;
+                return bp - bq;
+            });
+        }
+    };
+    for (let s = 0; s < sweeps; s++) {
+        if (numLayers > 1)
+            sweep(1, numLayers, 1, up); // top→bottom by parents
+        if (numLayers > 1)
+            sweep(numLayers - 2, -1, -1, down); // bottom→top by children
+    }
+    return layers;
+}
+/** Count edge crossings given per-layer orderings (for tests / quality). */
+export function crossings(g, layer, layers) {
+    const pos = new Map();
+    for (const arr of layers)
+        arr.forEach((n, i) => pos.set(n, i));
+    let total = 0;
+    const byLayerPair = new Map();
+    for (const [u, v] of g.edges) {
+        const lu = layer.get(u);
+        const lv = layer.get(v);
+        if (Math.abs(lu - lv) !== 1)
+            continue;
+        const top = lu < lv ? lu : lv;
+        const [a, b] = lu < lv ? [u, v] : [v, u];
+        const list = byLayerPair.get(top) ?? byLayerPair.set(top, []).get(top);
+        list.push([pos.get(a), pos.get(b)]);
+    }
+    for (const list of byLayerPair.values()) {
+        for (let i = 0; i < list.length; i++) {
+            for (let j = i + 1; j < list.length; j++) {
+                const [a1, b1] = list[i];
+                const [a2, b2] = list[j];
+                if ((a1 < a2 && b1 > b2) || (a1 > a2 && b1 < b2))
+                    total++;
+            }
+        }
+    }
+    return total;
+}
+// ── coordinate assignment ───────────────────────────────────────────
+/** Pool-adjacent-violators: the non-decreasing sequence closest (least
+ *  squares) to `y`. The kernel of minimum-displacement, ordered,
+ *  non-overlapping placement. */
+function isotonic(y) {
+    const blocks = [];
+    for (const yi of y) {
+        let b = { sum: yi, count: 1 };
+        while (blocks.length > 0 &&
+            blocks[blocks.length - 1].sum / blocks[blocks.length - 1].count > b.sum / b.count) {
+            const prev = blocks.pop();
+            b = { sum: prev.sum + b.sum, count: prev.count + b.count };
+        }
+        blocks.push(b);
+    }
+    const out = [];
+    for (const b of blocks) {
+        const avg = b.sum / b.count;
+        for (let k = 0; k < b.count; k++)
+            out.push(avg);
+    }
+    return out;
+}
+/** Place ordered nodes at centres as close to `desired` as possible
+ *  subject to `gap` edge-to-edge separation. */
+function placeRow(sizes, desired, gap) {
+    const n = sizes.length;
+    if (n === 0)
+        return [];
+    const cumSep = new Array(n);
+    cumSep[0] = 0;
+    for (let i = 1; i < n; i++)
+        cumSep[i] = cumSep[i - 1] + sizes[i - 1] / 2 + gap + sizes[i] / 2;
+    const q = desired.map((d, i) => d - cumSep[i]);
+    const qhat = isotonic(q);
+    return qhat.map((v, i) => v + cumSep[i]);
+}
+/** Full layered layout → top-left placement per node. */
+export function layered(g, opts = {}) {
+    const dir = opts.direction ?? "TB";
+    const layerGap = opts.layerGap ?? 90;
+    const nodeGap = opts.nodeGap ?? 28;
+    const sizeOf = opts.sizeOf ?? (() => DEFAULT_SIZE);
+    const sweeps = opts.sweeps ?? 6;
+    const align = opts.align ?? "both";
+    const layer = rank(g);
+    const layers = ordered(g, layer, sweeps);
+    const horizontal = dir === "LR" || dir === "RL";
+    // Cross-axis size of a node (the extent we pack along within a layer).
+    const cross = (n) => (horizontal ? sizeOf(n).h : sizeOf(n).w);
+    // Neighbour sets for barycenter, per `align`. `hi` is the upper
+    // (smaller-layer) endpoint, `lo` the lower. "down" centres a node on
+    // its lower neighbours (parents over children); "up" the reverse.
+    const nbrs = new Map();
+    for (const n of g.nodes)
+        nbrs.set(n, []);
+    for (const [u, v] of g.edges) {
+        const lu = layer.get(u);
+        const lv = layer.get(v);
+        if (lu === lv)
+            continue;
+        const hiNode = lu < lv ? u : v;
+        const loNode = lu < lv ? v : u;
+        if (align !== "up")
+            nbrs.get(hiNode).push(loNode); // hi centred on its lo neighbours
+        if (align !== "down")
+            nbrs.get(loNode).push(hiNode); // lo centred on its hi neighbours
+    }
+    // Initial centres: pack each layer from 0.
+    const center = new Map();
+    for (const arr of layers) {
+        let c = 0;
+        for (let i = 0; i < arr.length; i++) {
+            const half = cross(arr[i]) / 2;
+            c += half;
+            center.set(arr[i], c);
+            c += half + nodeGap;
+        }
+    }
+    // Refinement: pull toward neighbour barycenter, re-resolve overlaps.
+    const refine = (order) => {
+        for (const li of order) {
+            const arr = layers[li];
+            if (arr.length === 0)
+                continue;
+            const desired = arr.map(n => {
+                const nb = nbrs.get(n).filter(m => layer.get(m) !== li);
+                if (nb.length === 0)
+                    return center.get(n);
+                let acc = 0;
+                for (const m of nb)
+                    acc += center.get(m);
+                return acc / nb.length;
+            });
+            const placed = placeRow(arr.map(cross), desired, nodeGap);
+            arr.forEach((n, i) => center.set(n, placed[i]));
+        }
+    };
+    const numLayers = layers.length;
+    const downOrder = Array.from({ length: numLayers }, (_, i) => i);
+    const upOrder = [...downOrder].reverse();
+    for (let s = 0; s < sweeps; s++) {
+        refine(downOrder);
+        refine(upOrder);
+    }
+    // Layer-axis coordinate (centre of each layer).
+    const layerCenter = (l) => l * layerGap;
+    // Assemble placements in (layerAxis, crossAxis) then orient.
+    const maxLayer = numLayers - 1;
+    const out = new Map();
+    for (const n of g.nodes) {
+        const { w, h } = sizeOf(n);
+        const l = layer.get(n);
+        const cc = center.get(n); // cross-axis centre
+        let lc = layerCenter(l); // layer-axis centre
+        if (dir === "BT" || dir === "RL")
+            lc = layerCenter(maxLayer) - lc;
+        const cx = horizontal ? lc : cc;
+        const cy = horizontal ? cc : lc;
+        out.set(n, { x: cx - w / 2, y: cy - h / 2, w, h });
+    }
+    return normalize(out, 0);
+}
+/** Tree layout: parents centred over their children. A `layered` with
+ *  downward barycenter and tighter defaults. */
+export function tree(g, opts = {}) {
+    return layered(g, { align: "down", sweeps: 8, layerGap: 80, ...opts });
+}
+/** Radial layout: layers become concentric rings, cross-axis position
+ *  becomes angle. Reads a `layered` (TB) result and re-maps to polar. */
+export function radial(g, opts = {}) {
+    const flat = layered(g, { ...opts, direction: "TB", align: "down" });
+    const layer = rank(g);
+    const ringGap = opts.layerGap ?? 80;
+    // Cross-axis span per ring → map to [0, 2π) (or a fan for the root ring).
+    let minX = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    for (const p of flat.values()) {
+        minX = Math.min(minX, p.x + p.w / 2);
+        maxX = Math.max(maxX, p.x + p.w / 2);
+    }
+    const span = Math.max(1, maxX - minX);
+    const out = new Map();
+    for (const n of g.nodes) {
+        const p = flat.get(n);
+        const cxFlat = p.x + p.w / 2;
+        const l = layer.get(n);
+        const radius = l * ringGap;
+        const theta = l === 0 ? 0 : ((cxFlat - minX) / span) * Math.PI * 1.8 - Math.PI * 0.9;
+        const cx = Math.sin(theta) * radius;
+        const cy = -Math.cos(theta) * radius;
+        out.set(n, { x: cx - p.w / 2, y: cy - p.h / 2, w: p.w, h: p.h });
+    }
+    return normalize(out, 0);
+}
+// ── recurrent (cyclic) layout ───────────────────────────────────────
+/** A traversal order of an SCC's members that follows edges where it
+ *  can — a greedy walk. For a simple cycle this is the cycle order, so
+ *  laying the members out in this order around a circle traces the loop. */
+function ringOrder(members, adj) {
+    const set = new Set(members);
+    const seen = new Set();
+    const out = [];
+    let cur = members[0];
+    while (out.length < members.length && cur !== undefined) {
+        out.push(cur);
+        seen.add(cur);
+        const here = cur;
+        const next = (adj.get(here) ?? []).find(w => set.has(w) && !seen.has(w));
+        cur = next ?? members.find(m => !seen.has(m));
+    }
+    return out;
+}
+/** Recurrent-hierarchy layout: decompose into strongly-connected
+ *  components, lay the condensation (a DAG of SCCs) out hierarchically,
+ *  and draw every cyclic component as a ring centred on its condensation
+ *  slot. The cycle closes by going around the circle — no backward edge.
+ *  Singleton components are placed as ordinary nodes. */
+export function recurrent(g, opts = {}) {
+    const sizeOf = opts.sizeOf ?? (() => DEFAULT_SIZE);
+    const ringGap = 16;
+    const comps = scc(g);
+    const compOf = new Map();
+    comps.forEach((c, i) => c.forEach(n => compOf.set(n, i)));
+    const adj = new Map();
+    for (const n of g.nodes)
+        adj.set(n, []);
+    for (const [u, v] of g.edges)
+        adj.get(u)?.push(v);
+    // Ring radius for a component: chord between adjacent members ≥ their
+    // widest extent plus a gap.
+    const radiusOf = (members) => {
+        if (members.length < 2)
+            return 0;
+        let widest = 0;
+        for (const n of members)
+            widest = Math.max(widest, sizeOf(n).w, sizeOf(n).h);
+        return (widest + ringGap) / (2 * Math.sin(Math.PI / members.length));
+    };
+    // Each SCC is a meta-node sized to its ring's bounding box.
+    const ringSize = (i) => {
+        const members = comps[i];
+        if (members.length < 2)
+            return sizeOf(members[0]);
+        const r = radiusOf(members);
+        let widest = 0;
+        for (const n of members)
+            widest = Math.max(widest, sizeOf(n).w, sizeOf(n).h);
+        return { w: 2 * r + widest, h: 2 * r + widest };
+    };
+    const metaEdges = new Set();
+    const edges = [];
+    for (const [u, v] of g.edges) {
+        const cu = compOf.get(u);
+        const cv = compOf.get(v);
+        const key = `${cu}->${cv}`;
+        if (cu !== cv && !metaEdges.has(key)) {
+            metaEdges.add(key);
+            edges.push([cu, cv]);
+        }
+    }
+    const horizontal = opts.direction === "LR" || opts.direction === "RL";
+    let maxAlong = 0;
+    for (let i = 0; i < comps.length; i++) {
+        const sz = ringSize(i);
+        maxAlong = Math.max(maxAlong, horizontal ? sz.w : sz.h);
+    }
+    const metaPlace = layered({ nodes: comps.map((_, i) => i), edges }, {
+        direction: opts.direction ?? "TB",
+        sizeOf: ringSize,
+        layerGap: maxAlong + (opts.layerGap ?? 60),
+        nodeGap: opts.nodeGap ?? 40,
+    });
+    const out = new Map();
+    for (let i = 0; i < comps.length; i++) {
+        const members = comps[i];
+        const slot = metaPlace.get(i);
+        const cx = slot.x + slot.w / 2;
+        const cy = slot.y + slot.h / 2;
+        if (members.length < 2) {
+            const { w, h } = sizeOf(members[0]);
+            out.set(members[0], { x: cx - w / 2, y: cy - h / 2, w, h });
+            continue;
+        }
+        const order = ringOrder(members, adj);
+        const r = radiusOf(members);
+        order.forEach((n, k) => {
+            const theta = -Math.PI / 2 + (k / order.length) * Math.PI * 2;
+            const { w, h } = sizeOf(n);
+            out.set(n, {
+                x: cx + Math.cos(theta) * r - w / 2,
+                y: cy + Math.sin(theta) * r - h / 2,
+                w,
+                h,
+            });
+        });
+    }
+    return normalize(out, 0);
+}
+/** Git-style lane packing: nodes flow top-to-bottom in topological
+ *  order (one row each), each assigned the first free column ("lane")
+ *  that no live edge occupies. Branch points open lanes, merges free
+ *  them. Expects a DAG whose `nodes` are in commit order (parents
+ *  before children). */
+export function lanes(g, opts = {}) {
+    const rowGap = opts.rowGap ?? 56;
+    const laneGap = opts.laneGap ?? 46;
+    const sizeOf = opts.sizeOf ?? (() => DEFAULT_SIZE);
+    const layer = rank(g);
+    const rowOf = new Map();
+    [...g.nodes]
+        .map((n, i) => [n, i])
+        .sort((a, b) => layer.get(a[0]) - layer.get(b[0]) || a[1] - b[1])
+        .forEach(([n], row) => rowOf.set(n, row));
+    const parentsOf = new Map(g.nodes.map(n => [n, []]));
+    const unplacedKids = new Map(g.nodes.map(n => [n, 0]));
+    for (const [u, v] of g.edges) {
+        parentsOf.get(v).push(u);
+        unplacedKids.set(u, unplacedKids.get(u) + 1);
+    }
+    // Greedy lane assignment in row order: continue a parent's lane where
+    // possible (the branch stays in its column), else take the first free
+    // lane. A lane frees once its owner's last child is placed.
+    const laneOf = new Map();
+    const owner = [];
+    for (const n of [...g.nodes].sort((a, b) => rowOf.get(a) - rowOf.get(b))) {
+        const parentLane = owner.findIndex(o => o !== null && parentsOf.get(n).includes(o));
+        let lane = parentLane;
+        if (lane === -1) {
+            lane = owner.findIndex(o => o === null);
+            if (lane === -1) {
+                lane = owner.length;
+                owner.push(null);
+            }
+        }
+        laneOf.set(n, lane);
+        for (const p of parentsOf.get(n)) {
+            unplacedKids.set(p, unplacedKids.get(p) - 1);
+            if (unplacedKids.get(p) === 0) {
+                const pl = owner.indexOf(p);
+                if (pl !== -1)
+                    owner[pl] = null;
+            }
+        }
+        owner[lane] = unplacedKids.get(n) > 0 ? n : null;
+    }
+    const out = new Map();
+    for (const n of g.nodes) {
+        const { w, h } = sizeOf(n);
+        const cx = laneOf.get(n) * laneGap;
+        const cy = rowOf.get(n) * rowGap;
+        out.set(n, { x: cx - w / 2, y: cy - h / 2, w, h });
+    }
+    return normalize(out, 0);
+}
+/** Shift placements so the bounding box starts at (pad, pad). */
+function normalize(p, pad) {
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    for (const b of p.values()) {
+        minX = Math.min(minX, b.x);
+        minY = Math.min(minY, b.y);
+    }
+    if (!Number.isFinite(minX))
+        return p;
+    for (const [n, b] of p)
+        p.set(n, { ...b, x: b.x - minX + pad, y: b.y - minY + pad });
+    return p;
+}
+/** Bounding size of a placement map. */
+export function extent(p) {
+    let w = 0;
+    let h = 0;
+    for (const b of p.values()) {
+        w = Math.max(w, b.x + b.w);
+        h = Math.max(h, b.y + b.h);
+    }
+    return { w, h };
+}

package/dist/propagators/index.d.ts

@@ -1,6 +1,8 @@
-export { Box, box } from "../core/values/box.js";
-export { attach, centerInside, follow, type GridOpts, grid, hstack, inset, lockSize, pinEdge, type Side, type StackItem, type StackOpts, vstack, } from "./layout.js";
-export { PropagatorDivergedError, Propagators, type PropagatorsOpts, propagate, propagators, } from "./network.js";
-export { type Propagator, propagator } from "./propagator.js";
-export { constrain, intervalAdd, intervalAdder, intervalEq, intervalSub, intervalSum, RANGE_TOP, type Range, type RangeCell, RangeContradiction, rangeCell, rangeEq, rangeIsContradiction, rangeIsExact, rangeMeet, rangeMerge, rangeWidth, snap, } from "./range.js";
-export { add, align, allDifferent, aspectRatio, between, centroid, constant, eq, keepDistance, mid, mul, onCircle, onLine, reflect, type SetCell, sub, sum, } from "./relations.js";
+export { Box, box } from "../core/index.js";
+export { allDifferent, restrict, same } from "./csp.js";
+export { col, type FlexOpts, type Item, row } from "./flex.js";
+export { crossings, type Direction, extent, type Graph, type LanesOpts, type LayeredOpts, lanes, layered, type Placement, radial, rank, recurrent, type Size, scc, tree, } from "./graph.js";
+export { type Interval, interval, intervalCell, isContradiction, isTop, type Lattice, type LatticeCell, latticeCell, latticeFor, merge, point, set, setCell, width, } from "./lattice.js";
+export { attach, centerInside, follow, type GridOpts, grid, inset, lockSize, pinEdge, type Side, } from "./layout.js";
+export { add, bound, equal, fix, order, total } from "./numeric.js";
+export { type Propagator, propagator, Solver, type SolverOpts, solve, solver } from "./solver.js";

package/dist/propagators/index.js

@@ -1,6 +1,15 @@
-export { Box, box } from "../core/values/box.js";
-export { attach, centerInside, follow, grid, hstack, inset, lockSize, pinEdge, vstack, } from "./layout.js";
-export { PropagatorDivergedError, Propagators, propagate, propagators, } from "./network.js";
-export { propagator } from "./propagator.js";
-export { constrain, intervalAdd, intervalAdder, intervalEq, intervalSub, intervalSum, RANGE_TOP, RangeContradiction, rangeCell, rangeEq, rangeIsContradiction, rangeIsExact, rangeMeet, rangeMerge, rangeWidth, snap, } from "./range.js";
-export { add, align, allDifferent, aspectRatio, between, centroid, constant, eq, keepDistance, mid, mul, onCircle, onLine, reflect, sub, sum, } from "./relations.js";
+// Propagators — the monotone, partial-information solver layer.
+//
+// Cells hold partial knowledge on a lattice; propagators only ever
+// narrow it (`merge`). Fixpoint iteration terminates by the structure
+// of the lattice, so there is no divergence panic and no fuel cap that
+// can lie. Two lattices cover the surface: intervals (layout, ranges,
+// graph layering) and finite sets (CSP, sudoku, type inference).
+export { Box, box } from "../core/index.js";
+export { allDifferent, restrict, same } from "./csp.js";
+export { col, row } from "./flex.js";
+export { crossings, extent, lanes, layered, radial, rank, recurrent, scc, tree, } from "./graph.js";
+export { interval, intervalCell, isContradiction, isTop, latticeCell, latticeFor, merge, point, set, setCell, width, } from "./lattice.js";
+export { attach, centerInside, follow, grid, inset, lockSize, pinEdge, } from "./layout.js";
+export { add, bound, equal, fix, order, total } from "./numeric.js";
+export { propagator, Solver, solve, solver } from "./solver.js";

package/dist/propagators/lattice.d.ts

@@ -0,0 +1,45 @@
+import { type Cell, type Writable } from "../core/index.js";
+/** A meet-semilattice with a greatest element and a contradiction test.
+ *  `meet` is the only way information enters a cell, so it must be
+ *  commutative, associative, idempotent, and ≤ both inputs. */
+export interface Lattice<T> {
+    /** No information — the identity for `meet`. */
+    readonly top: T;
+    /** Greatest lower bound: combine two pieces of partial knowledge. */
+    meet(a: T, b: T): T;
+    /** Value equality — drives change detection (and cell de-duping). */
+    equals(a: T, b: T): boolean;
+    /** Self-contradiction: the empty interval / empty candidate set. */
+    isBottom(a: T): boolean;
+}
+/** A `cell<T>` carrying a `Lattice<T>` so `merge` can narrow generically. */
+export type LatticeCell<T> = Writable<Cell<T>>;
+/** The lattice a cell was minted with, or `undefined` for a plain cell. */
+export declare function latticeFor<T>(c: Cell<T>): Lattice<T> | undefined;
+/** Mint a cell over `lat`, seeded at `top` (no information) by default. */
+export declare function latticeCell<T>(lat: Lattice<T>, init?: T): LatticeCell<T>;
+/** Narrow `c` by `info` (monotone meet). No-ops when nothing sharpens, so
+ *  it's safe to call in any order and any number of times. Returns true
+ *  iff the cell actually narrowed. */
+export declare function merge<T>(c: LatticeCell<T>, info: T): boolean;
+/** True when the cell's knowledge has collapsed to a contradiction. */
+export declare function isContradiction<T>(c: Cell<T>): boolean;
+/** True when the cell still holds no information (its lattice `top`). */
+export declare function isTop<T>(c: Cell<T>): boolean;
+/** An inclusive numeric interval `[lo, hi]`. `top` is `[-∞, ∞]`;
+ *  `lo > hi` is bottom (the empty interval). */
+export type Interval = readonly [number, number];
+export declare const interval: Lattice<Interval>;
+/** Interval cell, optionally seeded with bounds (defaults to `top`). */
+export declare function intervalCell(lo?: number, hi?: number): LatticeCell<Interval>;
+/** Width of an interval (`Infinity` if unbounded, negative if bottom). */
+export declare function width(i: Interval): number;
+/** A single value, or `undefined` when the interval isn't a point. */
+export declare function point(i: Interval): number | undefined;
+/** A finite candidate-set lattice over `universe`. `top` is the whole
+ *  universe (all candidates open); `meet` intersects; bottom is empty.
+ *  Height is `|universe|`, so narrowing always terminates. */
+export declare function set<E>(universe: Iterable<E>): Lattice<ReadonlySet<E>>;
+/** Candidate-set cell over `universe`, seeded with `init` (defaults to
+ *  the whole universe). */
+export declare function setCell<E>(universe: Iterable<E>, init?: Iterable<E>): LatticeCell<ReadonlySet<E>>;