@graphrefly/graphrefly 0.24.0 → 0.26.0

package/dist/patterns/reactive-layout/index.cjs

@@ -27,14 +27,20 @@ __export(reactive_layout_exports, {
   PrecomputedAdapter: () => PrecomputedAdapter,
   SvgBoundsAdapter: () => SvgBoundsAdapter,
   analyzeAndMeasure: () => analyzeAndMeasure,
+  carveTextLineSlots: () => carveTextLineSlots,
+  circleIntervalForBand: () => circleIntervalForBand,
   computeBlockFlow: () => computeBlockFlow,
   computeCharPositions: () => computeCharPositions,
+  computeFlowLines: () => computeFlowLines,
   computeLineBreaks: () => computeLineBreaks,
   computeTotalHeight: () => computeTotalHeight,
+  layoutNextLine: () => layoutNextLine,
   measureBlock: () => measureBlock,
   measureBlocks: () => measureBlocks,
   reactiveBlockLayout: () => reactiveBlockLayout,
-  reactiveLayout: () => reactiveLayout
+  reactiveFlowLayout: () => reactiveFlowLayout,
+  reactiveLayout: () => reactiveLayout,
+  rectIntervalForBand: () => rectIntervalForBand
 });
 module.exports = __toCommonJS(reactive_layout_exports);
 
@@ -232,7 +238,7 @@ var CanvasMeasureAdapter = class {
       this.currentFont = font;
     }
     let width = ctx.measureText(text).width;
-    if (this.emojiCorrection !== 1 && /\p{Emoji_Presentation}/u.test(text)) {
+    if (this.emojiCorrection !== 1 && new RegExp("\\p{Emoji_Presentation}", "u").test(text)) {
       width *= this.emojiCorrection;
     }
     return { width };
@@ -1159,6 +1165,12 @@ var NodeImpl = class _NodeImpl {
   _autoError;
   _pausable;
   _guard;
+  /**
+   * @internal Additional guards stacked at runtime via {@link NodeImpl._pushGuard}
+   * (e.g. by `policyEnforcer({ mode: "enforce" })`, roadmap §9.2). Effective
+   * write/signal/observe checks AND the original `_guard` with every entry here.
+   */
+  _extraGuards;
   _hashFn;
   _versioning;
   /**
@@ -1332,18 +1344,61 @@ var NodeImpl = class _NodeImpl {
       if (this._inspectorHooks?.size === 0) this._inspectorHooks = void 0;
     };
   }
+  /**
+   * @internal Push an additional guard onto this node. Effective enforcement
+   * is the AND of `_guard` and every guard pushed via this hook — any one
+   * rejecting throws {@link GuardDenied}. Returns a disposer that removes
+   * the pushed guard. Multiple guards may be stacked simultaneously.
+   *
+   * Used by `policyEnforcer({ mode: "enforce" })` (roadmap §9.2) to overlay
+   * runtime constraint enforcement onto an existing graph without rebuilding
+   * its nodes. Pre-1.0 internal API; not part of the public surface.
+   *
+   * **Identity semantics:** guards are tracked in a `Set`, so pushing the
+   * same `NodeGuard` reference twice is a single registration. Wrap each
+   * push in a unique closure if independent stacking is needed.
+   *
+   * **Iteration order:** insertion-ordered (`Set` semantics). Determinism
+   * follows from single-threaded JS execution; nested re-entry from inside
+   * a guard body (push/pop while iterating) is undefined-but-survivable.
+   */
+  _pushGuard(guard) {
+    if (this._extraGuards == null) this._extraGuards = /* @__PURE__ */ new Set();
+    this._extraGuards.add(guard);
+    return () => {
+      this._extraGuards?.delete(guard);
+      if (this._extraGuards?.size === 0) this._extraGuards = void 0;
+    };
+  }
   allowsObserve(actor) {
-    if (this._guard == null) return true;
-    return this._guard(normalizeActor(actor), "observe");
+    if (this._guard == null && this._extraGuards == null) return true;
+    const a = normalizeActor(actor);
+    if (this._guard != null && !this._guard(a, "observe")) return false;
+    if (this._extraGuards != null) {
+      for (const eg of this._extraGuards) {
+        if (!eg(a, "observe")) return false;
+      }
+    }
+    return true;
   }
   // --- Guard helper ---
   _checkGuard(options) {
-    if (options?.internal || this._guard == null) return;
+    if (options?.internal) return;
+    const hasGuard = this._guard != null || this._extraGuards != null;
+    const hasActor = options?.actor != null;
+    if (!hasGuard && !hasActor) return;
     const actor = normalizeActor(options?.actor);
     const action = options?.delivery === "signal" ? "signal" : "write";
-    if (!this._guard(actor, action)) {
+    if (this._guard != null && !this._guard(actor, action)) {
       throw new GuardDenied({ actor, action, nodeName: this.name });
     }
+    if (this._extraGuards != null) {
+      for (const eg of this._extraGuards) {
+        if (!eg(actor, action)) {
+          throw new GuardDenied({ actor, action, nodeName: this.name });
+        }
+      }
+    }
     this._lastMutation = { actor, timestamp_ns: wallClockNs() };
   }
   // --- Public transport ---
@@ -2275,6 +2330,10 @@ function sentinelGuard(batchData, ctx, allowPartial) {
 function state(initial, opts) {
   return node([], { ...opts, initial });
 }
+function producer(fn, opts) {
+  const wrapped = (_data, actions, ctx) => fn(actions, ctx) ?? void 0;
+  return node(wrapped, { describeKind: "producer", ...opts });
+}
 function derived(deps, fn, opts) {
   const allowPartial = opts?.partial ?? false;
   const wrapped = (batchData, actions, ctx) => {
@@ -2477,6 +2536,200 @@ var RingBuffer = class {
   }
 };
 
+// src/graph/explain.ts
+function explainPath(described, from, to, opts = {}) {
+  const fromExists = from in described.nodes;
+  const toExists = to in described.nodes;
+  if (!fromExists) return makeFailure(from, to, "no-such-from");
+  if (!toExists) return makeFailure(from, to, "no-such-to");
+  const maxDepth = opts.maxDepth;
+  if (maxDepth != null && (!Number.isInteger(maxDepth) || maxDepth < 0)) {
+    throw new Error(`explainPath: maxDepth must be an integer >= 0`);
+  }
+  if (from === to) {
+    if (opts.findCycle === true) {
+      const cycle = findShortestCycle(described, from, opts);
+      if (cycle != null) return cycle;
+    }
+    const step = buildStep(from, described.nodes[from], 0, opts);
+    return makeSuccess(from, to, [step]);
+  }
+  if (maxDepth === 0) return makeFailure(from, to, "no-path");
+  const result = bfsShortestPath(described, from, to, maxDepth);
+  if (!result.found) {
+    return makeFailure(from, to, result.truncated ? "max-depth-exceeded" : "no-path");
+  }
+  return makeSuccess(from, to, materializeSteps(described, result.pathOrder, opts));
+}
+function bfsShortestPath(described, from, to, maxDepth) {
+  const pred = /* @__PURE__ */ new Map();
+  const queue = [{ path: to, depth: 0 }];
+  const visited = /* @__PURE__ */ new Set([to]);
+  let head = 0;
+  let truncated = false;
+  while (head < queue.length) {
+    const cur = queue[head++];
+    if (cur.path === from) break;
+    if (maxDepth != null && cur.depth >= maxDepth) {
+      const node3 = described.nodes[cur.path];
+      if (node3?.deps && node3.deps.length > 0) truncated = true;
+      continue;
+    }
+    const node2 = described.nodes[cur.path];
+    if (node2 == null) continue;
+    const deps = node2.deps ?? [];
+    const slots = /* @__PURE__ */ new Map();
+    for (let i = 0; i < deps.length; i++) {
+      const dep = deps[i];
+      if (!dep) continue;
+      let arr = slots.get(dep);
+      if (arr == null) {
+        arr = [];
+        slots.set(dep, arr);
+      }
+      arr.push(i);
+    }
+    for (const [dep, indices] of slots) {
+      if (visited.has(dep)) continue;
+      visited.add(dep);
+      pred.set(dep, { from: cur.path, depIndices: indices });
+      queue.push({ path: dep, depth: cur.depth + 1 });
+    }
+  }
+  if (!pred.has(from)) {
+    return { found: false, pathOrder: [], truncated };
+  }
+  const pathOrder = [{ path: from }];
+  let cursor = from;
+  while (cursor !== to) {
+    const p = pred.get(cursor);
+    if (p == null) return { found: false, pathOrder: [], truncated: false };
+    pathOrder[pathOrder.length - 1].depIndices = p.depIndices;
+    pathOrder.push({ path: p.from });
+    cursor = p.from;
+  }
+  return { found: true, pathOrder, truncated: false };
+}
+function findShortestCycle(described, start, opts) {
+  const startNode = described.nodes[start];
+  if (startNode == null) return null;
+  const startDeps = startNode.deps ?? [];
+  const selfSlots = [];
+  for (let i = 0; i < startDeps.length; i++) if (startDeps[i] === start) selfSlots.push(i);
+  if (selfSlots.length > 0) {
+    const step0 = buildStep(start, startNode, 0, opts);
+    step0.dep_index = selfSlots[0];
+    const step1 = buildStep(start, startNode, 1, opts);
+    return makeSuccess(start, start, [step0, step1]);
+  }
+  let best = null;
+  for (let i = 0; i < startDeps.length; i++) {
+    const dep = startDeps[i];
+    if (!dep || dep === start) continue;
+    const sub = bfsShortestPath(described, dep, start, opts.maxDepth);
+    if (!sub.found) continue;
+    if (best == null || sub.pathOrder.length < best.pathOrder.length) {
+      best = sub;
+      best = {
+        found: true,
+        pathOrder: [{ path: start, depIndices: [i] }, ...sub.pathOrder],
+        truncated: false
+      };
+    }
+  }
+  if (best == null) return null;
+  return makeSuccess(start, start, materializeSteps(described, best.pathOrder, opts));
+}
+function materializeSteps(described, pathOrder, opts) {
+  return pathOrder.map((entry, i) => {
+    const node2 = described.nodes[entry.path];
+    const step = buildStep(entry.path, node2, i, opts);
+    if (entry.depIndices != null && entry.depIndices.length > 0) {
+      step.dep_index = entry.depIndices[0];
+      if (entry.depIndices.length > 1) step.dep_indices = [...entry.depIndices];
+    }
+    return step;
+  });
+}
+function buildStep(path, node2, hop, opts) {
+  const step = {
+    path,
+    type: node2.type,
+    hop
+  };
+  if (node2.status !== void 0) step.status = node2.status;
+  if ("value" in node2) step.value = node2.value;
+  if (node2.v != null) step.v = node2.v;
+  const annotation = opts.annotations?.get(path) ?? node2.reason;
+  if (annotation != null) step.reason = annotation;
+  const lastMutation = opts.lastMutations?.get(path) ?? node2.lastMutation;
+  if (lastMutation != null) step.lastMutation = lastMutation;
+  return step;
+}
+function makeSuccess(from, to, steps) {
+  return finalize(from, to, true, "ok", steps);
+}
+function makeFailure(from, to, reason) {
+  return finalize(from, to, false, reason, []);
+}
+function finalize(from, to, found, reason, steps) {
+  const text = renderChain(from, to, found, reason, steps);
+  return {
+    from,
+    to,
+    found,
+    reason,
+    steps,
+    text,
+    toJSON() {
+      return { from, to, found, reason, steps };
+    }
+  };
+}
+function renderChain(from, to, found, reason, steps) {
+  if (!found) {
+    switch (reason) {
+      case "no-such-from":
+        return `explainPath: no node named "${from}"`;
+      case "no-such-to":
+        return `explainPath: no node named "${to}"`;
+      case "max-depth-exceeded":
+        return `explainPath: no path from "${from}" to "${to}" within maxDepth`;
+      default:
+        return `explainPath: no path from "${from}" to "${to}"`;
+    }
+  }
+  const lines = [`Causal path: ${from} \u2192 ${to} (${steps.length} step(s))`];
+  for (const step of steps) {
+    const arrow = step.hop === 0 ? "\xB7" : "\u2193";
+    const head = `  ${arrow} ${step.path} (${step.type}${step.status ? `/${step.status}` : ""})`;
+    lines.push(head);
+    if ("value" in step) {
+      lines.push(`      value: ${formatValue(step.value)}`);
+    }
+    if (step.reason != null) {
+      lines.push(`      reason: ${step.reason}`);
+    }
+    if (step.lastMutation != null) {
+      const a = step.lastMutation.actor;
+      lines.push(`      actor: ${a.type}${a.id ? `:${a.id}` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatValue(v) {
+  if (v === void 0) return "<sentinel>";
+  if (v === null) return "null";
+  if (typeof v === "string") return JSON.stringify(v);
+  if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+  try {
+    const s = JSON.stringify(v);
+    return s.length > 80 ? `${s.slice(0, 77)}...` : s;
+  } catch {
+    return String(v);
+  }
+}
+
 // src/extra/utils/sizeof.ts
 var OVERHEAD = {
   object: 56,
@@ -3110,6 +3363,20 @@ var Graph = class _Graph {
   _parent = void 0;
   _storageDisposers = /* @__PURE__ */ new Set();
   _disposers = /* @__PURE__ */ new Set();
+  /**
+   * @internal Lazy `TopologyEvent` producer. Created on first `.topology`
+   * access. Zero cost until something subscribes — producer fn only runs when
+   * the first sink attaches, registering one handler into
+   * {@link Graph._topologyEmitters}.
+   */
+  _topology;
+  /**
+   * @internal Active emit handlers for the topology producer. Each entry is
+   * the closure registered by the producer fn on activation; cleared on
+   * deactivation. `_emitTopology` broadcasts through every entry (there is at
+   * most one per activation cycle of the producer).
+   */
+  _topologyEmitters = /* @__PURE__ */ new Set();
   /**
    * @param name - Non-empty graph id (must not contain `::` and must not
    *   equal the reserved meta segment `__meta__`).
@@ -3149,6 +3416,55 @@ var Graph = class _Graph {
     return out;
   }
   // ——————————————————————————————————————————————————————————————
+  //  Topology companion (structural-change event stream)
+  // ——————————————————————————————————————————————————————————————
+  /**
+   * Reactive stream of structural changes to this graph's own registry
+   * (add / mount / remove). Value mutations live on `observe()`; this
+   * companion only fires when the topology shape changes.
+   *
+   * Lazy: the underlying node is created on first access and activates when
+   * something subscribes. No emission replay — late subscribers do not
+   * receive historical events and should snapshot via {@link Graph.describe}
+   * before listening for incremental changes. Events that fire while the
+   * producer has zero subscribers are dropped (no retention).
+   *
+   * Own-graph only: a parent's `topology` does NOT emit for structural
+   * changes inside a mounted child. Transitive consumers subscribe to each
+   * child's topology separately (recurse through `topology`'s own "added"
+   * events with `nodeKind: "mount"` to discover new children).
+   *
+   * See {@link TopologyEvent} for payload shape.
+   *
+   * @category observability
+   */
+  get topology() {
+    if (this._topology == null) {
+      this._topology = producer(
+        (actions) => {
+          const handler = (event) => {
+            actions.emit(event);
+          };
+          this._topologyEmitters.add(handler);
+          return () => {
+            this._topologyEmitters.delete(handler);
+          };
+        },
+        { name: `${this.name}_topology` }
+      );
+    }
+    return this._topology;
+  }
+  /**
+   * @internal Fire a {@link TopologyEvent} to every active subscriber of
+   * `this.topology`. No-op when the topology node has never been accessed or
+   * currently has no sinks — zero cost for graphs nobody observes.
+   */
+  _emitTopology(event) {
+    if (this._topology == null || this._topologyEmitters.size === 0) return;
+    for (const h of this._topologyEmitters) h(event);
+  }
+  // ——————————————————————————————————————————————————————————————
   //  Node registry
   // ——————————————————————————————————————————————————————————————
   /**
@@ -3178,6 +3494,7 @@ var Graph = class _Graph {
     }
     this._nodes.set(name, node2);
     this._nodeToName.set(node2, name);
+    this._emitTopology({ kind: "added", name, nodeKind: "node" });
     return node2;
   }
   /**
@@ -3218,22 +3535,23 @@ var Graph = class _Graph {
     assertRegisterableName(name, this.name, "remove");
     const child = this._mounts.get(name);
     if (child) {
-      const audit = { kind: "mount", nodes: [], mounts: [] };
+      const audit2 = { kind: "mount", nodes: [], mounts: [] };
       const targets = [];
       child._collectObserveTargets("", targets);
       for (const [p, n] of targets) {
         if (!p.includes(`${PATH_SEP}${GRAPH_META_SEGMENT}${PATH_SEP}`)) {
-          audit.nodes.push(p);
+          audit2.nodes.push(p);
         }
         void n;
       }
-      audit.nodes.sort();
-      audit.mounts.push(name);
-      audit.mounts.push(...child._collectSubgraphs(`${name}${PATH_SEP}`));
+      audit2.nodes.sort();
+      audit2.mounts.push(name);
+      audit2.mounts.push(...child._collectSubgraphs(`${name}${PATH_SEP}`));
       this._mounts.delete(name);
       child._parent = void 0;
       teardownMountedGraph(child);
-      return audit;
+      this._emitTopology({ kind: "removed", name, nodeKind: "mount", audit: audit2 });
+      return audit2;
     }
     const node2 = this._nodes.get(name);
     if (!node2) {
@@ -3242,7 +3560,9 @@ var Graph = class _Graph {
     this._nodes.delete(name);
     this._nodeToName.delete(node2);
     node2.down([[TEARDOWN]], { internal: true });
-    return { kind: "node", nodes: [name], mounts: [] };
+    const audit = { kind: "node", nodes: [name], mounts: [] };
+    this._emitTopology({ kind: "removed", name, nodeKind: "node", audit });
+    return audit;
   }
   /**
    * Bulk remove — invokes {@link Graph.remove} for every local name matching
@@ -3471,6 +3791,7 @@ var Graph = class _Graph {
     }
     this._mounts.set(name, child);
     child._parent = this;
+    this._emitTopology({ kind: "added", name, nodeKind: "mount" });
     return child;
   }
   /**
@@ -3761,6 +4082,33 @@ var Graph = class _Graph {
     }
     return reachable(this.describe(), from, direction, opts);
   }
+  /**
+   * Causal walkback: shortest dep-chain from `from` to `to`, enriched with
+   * each node's value, status, last-mutation actor, and reasoning annotation
+   * from {@link Graph.trace}. Wraps {@link explainPath} (roadmap §9.2).
+   *
+   * @param from - Upstream node (the cause).
+   * @param to - Downstream node (the effect).
+   * @param opts - Optional `maxDepth` and `findCycle`. When `findCycle:true`
+   *   and `from === to`, returns the shortest cycle through other nodes
+   *   (useful for diagnosing feedback loops, COMPOSITION-GUIDE §7).
+   *   Annotations and lastMutations are collected automatically from the
+   *   live graph.
+   */
+  explain(from, to, opts) {
+    const described = this.describe({ detail: "full" });
+    const annotations = new Map(this._annotations);
+    const lastMutations = /* @__PURE__ */ new Map();
+    for (const [path, n] of Object.entries(described.nodes)) {
+      if (n.lastMutation != null) lastMutations.set(path, n.lastMutation);
+    }
+    return explainPath(described, from, to, {
+      ...opts?.maxDepth != null ? { maxDepth: opts.maxDepth } : {},
+      ...opts?.findCycle === true ? { findCycle: true } : {},
+      annotations,
+      lastMutations
+    });
+  }
   /**
    * @internal Collect all qualified paths in this graph tree matching a
    * glob pattern. Used by scoped autoCheckpoint subscription.
@@ -4439,7 +4787,7 @@ var Graph = class _Graph {
         return;
       }
       const nextSeq = s.seq + 1;
-      const timestamp_ns = monotonicNs();
+      const timestamp_ns = wallClockNs();
       const isFirst = s.lastSnapshot == null;
       const shouldCompact = isFirst || nextSeq % s.compactEvery === 0;
       const record = shouldCompact ? {
@@ -4958,7 +5306,7 @@ function analyzeAndMeasure(text, font, adapter, cache, stats) {
   const normalized = normalizeWhitespace(text);
   if (normalized.length === 0) return [];
   const pieces = segmentText(normalized);
-  const graphemeSegmenter = new Intl.Segmenter(void 0, {
+  const graphemeSegmenter2 = new Intl.Segmenter(void 0, {
     granularity: "grapheme"
   });
   const rawTexts = [];
@@ -5002,7 +5350,8 @@ function analyzeAndMeasure(text, font, adapter, cache, stats) {
     let w = fontCache.get(seg);
     if (w === void 0) {
       if (stats) stats.misses += 1;
-      w = adapter.measureSegment(seg, font).width;
+      const raw = adapter.measureSegment(seg, font).width;
+      w = Number.isFinite(raw) && raw >= 0 ? raw : 0;
       fontCache.set(seg, w);
     } else if (stats) {
       stats.hits += 1;
@@ -5024,7 +5373,7 @@ function analyzeAndMeasure(text, font, adapter, cache, stats) {
     }
     if (isCJK(t)) {
       let unitText = "";
-      for (const gs of graphemeSegmenter.segment(t)) {
+      for (const gs of graphemeSegmenter2.segment(t)) {
         const grapheme = gs.segment;
         if (unitText.length > 0 && kinsokuStart.has(grapheme)) {
           unitText += grapheme;
@@ -5056,7 +5405,7 @@ function analyzeAndMeasure(text, font, adapter, cache, stats) {
     let graphemeWidths = null;
     if (mergedWordLike[i] && t.length > 1) {
       const gWidths = [];
-      for (const gs of graphemeSegmenter.segment(t)) {
+      for (const gs of graphemeSegmenter2.segment(t)) {
         gWidths.push(measureCached(gs.segment));
       }
       if (gWidths.length > 1) {
@@ -5096,10 +5445,10 @@ function computeLineBreaks(segments, maxWidth, adapter, font, cache) {
       const seg = segments[i];
       if (seg.kind === "soft-hyphen" || seg.kind === "hard-break") continue;
       if (i === lineStartSeg && lineStartGrapheme > 0 && seg.graphemeWidths) {
-        const graphemeSegmenter = new Intl.Segmenter(void 0, {
+        const graphemeSegmenter2 = new Intl.Segmenter(void 0, {
           granularity: "grapheme"
         });
-        const graphemes = [...graphemeSegmenter.segment(seg.text)].map((g) => g.segment);
+        const graphemes = [...graphemeSegmenter2.segment(seg.text)].map((g) => g.segment);
         text += graphemes.slice(lineStartGrapheme).join("");
       } else {
         text += seg.text;
@@ -5107,10 +5456,10 @@ function computeLineBreaks(segments, maxWidth, adapter, font, cache) {
     }
     if (endGrapheme > 0 && endSeg < segments.length) {
       const seg = segments[endSeg];
-      const graphemeSegmenter = new Intl.Segmenter(void 0, {
+      const graphemeSegmenter2 = new Intl.Segmenter(void 0, {
         granularity: "grapheme"
       });
-      const graphemes = [...graphemeSegmenter.segment(seg.text)].map((g) => g.segment);
+      const graphemes = [...graphemeSegmenter2.segment(seg.text)].map((g) => g.segment);
       const startG = lineStartSeg === endSeg ? lineStartGrapheme : 0;
       text += graphemes.slice(startG, endGrapheme).join("");
     }
@@ -5130,7 +5479,7 @@ function computeLineBreaks(segments, maxWidth, adapter, font, cache) {
     pendingBreakSeg = -1;
     pendingBreakWidth = 0;
   }
-  function canBreakAfter(kind) {
+  function canBreakAfter2(kind) {
     return kind === "space" || kind === "zero-width-break" || kind === "soft-hyphen";
   }
   function startLine(segIdx, graphemeIdx, width) {
@@ -5175,7 +5524,7 @@ function computeLineBreaks(segments, maxWidth, adapter, font, cache) {
       } else {
         startLine(i, 0, w);
       }
-      if (canBreakAfter(seg.kind)) {
+      if (canBreakAfter2(seg.kind)) {
         pendingBreakSeg = i + 1;
         pendingBreakWidth = seg.kind === "space" ? lineW - w : lineW;
       }
@@ -5183,7 +5532,7 @@ function computeLineBreaks(segments, maxWidth, adapter, font, cache) {
     }
     const newW = lineW + w;
     if (newW > maxWidth + 5e-3) {
-      if (canBreakAfter(seg.kind)) {
+      if (canBreakAfter2(seg.kind)) {
         lineW += w;
         lineEndSeg = i + 1;
         lineEndGrapheme = 0;
@@ -5207,7 +5556,7 @@ function computeLineBreaks(segments, maxWidth, adapter, font, cache) {
     lineW = newW;
     lineEndSeg = i + 1;
     lineEndGrapheme = 0;
-    if (canBreakAfter(seg.kind)) {
+    if (canBreakAfter2(seg.kind)) {
       pendingBreakSeg = i + 1;
       pendingBreakWidth = seg.kind === "space" ? lineW - w : lineW;
     }
@@ -5238,9 +5587,289 @@ function computeLineBreaks(segments, maxWidth, adapter, font, cache) {
     }
   }
 }
+function canBreakAfter(kind) {
+  return kind === "space" || kind === "zero-width-break" || kind === "soft-hyphen";
+}
+var _graphemeSegmenter = null;
+function graphemeSegmenter() {
+  if (_graphemeSegmenter === null) {
+    _graphemeSegmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+  }
+  return _graphemeSegmenter;
+}
+function sliceSegmentText(seg, startG, endG) {
+  if (startG === 0 && endG < 0) return seg.text;
+  const graphemes = [...graphemeSegmenter().segment(seg.text)].map((g) => g.segment);
+  const stop = endG < 0 ? graphemes.length : endG;
+  return graphemes.slice(startG, stop).join("");
+}
+function buildLineText(segments, startSeg, startG, endSeg, endG, appendHyphen) {
+  let text = "";
+  for (let i = startSeg; i < endSeg; i++) {
+    const seg = segments[i];
+    if (seg.kind === "soft-hyphen" || seg.kind === "hard-break") continue;
+    if (i === startSeg && startG > 0) {
+      text += sliceSegmentText(seg, startG, -1);
+    } else {
+      text += seg.text;
+    }
+  }
+  if (endG > 0 && endSeg < segments.length) {
+    const seg = segments[endSeg];
+    const from = startSeg === endSeg ? startG : 0;
+    text += sliceSegmentText(seg, from, endG);
+  }
+  if (appendHyphen) text += "-";
+  return text;
+}
+function resolveHyphenWidth(ctx) {
+  if (!ctx || !ctx.adapter || !ctx.font) return 0;
+  const cache = ctx.cache;
+  if (cache) {
+    let fc = cache.get(ctx.font);
+    if (!fc) {
+      fc = /* @__PURE__ */ new Map();
+      cache.set(ctx.font, fc);
+    }
+    let hw = fc.get("-");
+    if (hw === void 0) {
+      hw = ctx.adapter.measureSegment("-", ctx.font).width;
+      fc.set("-", hw);
+    }
+    return hw;
+  }
+  return ctx.adapter.measureSegment("-", ctx.font).width;
+}
+function layoutNextLine(segments, cursor, slotWidth, ctx) {
+  let i = cursor.segmentIndex;
+  const initialG = cursor.graphemeIndex;
+  if (i >= segments.length) return null;
+  if (initialG === 0) {
+    while (i < segments.length) {
+      const seg = segments[i];
+      if (seg.kind === "hard-break") {
+        return {
+          text: "",
+          width: 0,
+          start: { segmentIndex: cursor.segmentIndex, graphemeIndex: 0 },
+          end: { segmentIndex: i + 1, graphemeIndex: 0 }
+        };
+      }
+      if (seg.kind === "space" || seg.kind === "zero-width-break" || seg.kind === "soft-hyphen") {
+        i += 1;
+        continue;
+      }
+      break;
+    }
+    if (i >= segments.length) return null;
+  }
+  const hyphenWidth = resolveHyphenWidth(ctx);
+  const startSeg = i;
+  const startG = i === cursor.segmentIndex ? initialG : 0;
+  let lineW = 0;
+  let lineEndSeg = startSeg;
+  let lineEndG = 0;
+  let hasContent = false;
+  let pendingBreakSeg = -1;
+  let pendingBreakG = 0;
+  let pendingBreakWidth = 0;
+  let pendingBreakSoftHyphen = false;
+  const recordPending = (sIdx, gIdx, widthAtBreak, kind) => {
+    pendingBreakSeg = sIdx;
+    pendingBreakG = gIdx;
+    pendingBreakWidth = widthAtBreak;
+    pendingBreakSoftHyphen = kind === "soft-hyphen";
+  };
+  const consumeBreakable = (segIdx, gStart, gWidths) => {
+    for (let g = gStart; g < gWidths.length; g++) {
+      const gw = gWidths[g];
+      if (!hasContent) {
+        lineW = gw;
+        lineEndSeg = segIdx;
+        lineEndG = g + 1;
+        hasContent = true;
+        continue;
+      }
+      if (lineW + gw > slotWidth + 5e-3) {
+        return true;
+      }
+      lineW += gw;
+      lineEndSeg = segIdx;
+      lineEndG = g + 1;
+    }
+    if (lineEndSeg === segIdx && lineEndG === gWidths.length) {
+      lineEndSeg = segIdx + 1;
+      lineEndG = 0;
+    }
+    return false;
+  };
+  if (startG > 0 && startSeg < segments.length) {
+    const seg = segments[startSeg];
+    if (seg.graphemeWidths) {
+      const overflowed = consumeBreakable(startSeg, startG, seg.graphemeWidths);
+      if (overflowed) {
+        const text2 = buildLineText(segments, startSeg, startG, lineEndSeg, lineEndG, false);
+        return {
+          text: text2,
+          width: lineW,
+          start: { segmentIndex: startSeg, graphemeIndex: startG },
+          end: { segmentIndex: lineEndSeg, graphemeIndex: lineEndG }
+        };
+      }
+      i = lineEndSeg;
+    } else {
+    }
+  }
+  for (; i < segments.length; ) {
+    const seg = segments[i];
+    if (seg.kind === "hard-break") {
+      if (hasContent) {
+        const endsAtSoftHyphen2 = lineEndSeg > 0 && segments[lineEndSeg - 1]?.kind === "soft-hyphen";
+        const text2 = buildLineText(
+          segments,
+          startSeg,
+          startG,
+          lineEndSeg,
+          lineEndG,
+          endsAtSoftHyphen2
+        );
+        return {
+          text: text2,
+          width: lineW + (endsAtSoftHyphen2 ? hyphenWidth : 0),
+          start: { segmentIndex: startSeg, graphemeIndex: startG },
+          end: { segmentIndex: lineEndSeg, graphemeIndex: lineEndG }
+        };
+      }
+      return {
+        text: "",
+        width: 0,
+        start: { segmentIndex: startSeg, graphemeIndex: startG },
+        end: { segmentIndex: i + 1, graphemeIndex: 0 }
+      };
+    }
+    const w = seg.width;
+    if (!hasContent) {
+      if (w > slotWidth && seg.graphemeWidths) {
+        const overflowed = consumeBreakable(i, 0, seg.graphemeWidths);
+        if (overflowed) {
+          const text2 = buildLineText(segments, startSeg, startG, lineEndSeg, lineEndG, false);
+          return {
+            text: text2,
+            width: lineW,
+            start: { segmentIndex: startSeg, graphemeIndex: startG },
+            end: { segmentIndex: lineEndSeg, graphemeIndex: lineEndG }
+          };
+        }
+        i = lineEndSeg;
+        continue;
+      }
+      lineW = w;
+      lineEndSeg = i + 1;
+      lineEndG = 0;
+      hasContent = true;
+      if (canBreakAfter(seg.kind)) {
+        recordPending(i + 1, 0, seg.kind === "space" ? lineW - w : lineW, seg.kind);
+      }
+      i += 1;
+      continue;
+    }
+    const newW = lineW + w;
+    if (newW > slotWidth + 5e-3) {
+      if (canBreakAfter(seg.kind)) {
+        lineEndSeg = i + 1;
+        lineEndG = 0;
+        const endsAtSoftHyphen2 = seg.kind === "soft-hyphen";
+        const finalWidth = seg.kind === "space" ? lineW : lineW + (endsAtSoftHyphen2 ? hyphenWidth : 0);
+        const text3 = buildLineText(
+          segments,
+          startSeg,
+          startG,
+          lineEndSeg,
+          lineEndG,
+          endsAtSoftHyphen2
+        );
+        return {
+          text: text3,
+          width: finalWidth,
+          start: { segmentIndex: startSeg, graphemeIndex: startG },
+          end: { segmentIndex: lineEndSeg, graphemeIndex: lineEndG }
+        };
+      }
+      if (pendingBreakSeg >= 0) {
+        const text3 = buildLineText(
+          segments,
+          startSeg,
+          startG,
+          pendingBreakSeg,
+          pendingBreakG,
+          pendingBreakSoftHyphen
+        );
+        return {
+          text: text3,
+          width: pendingBreakWidth + (pendingBreakSoftHyphen ? hyphenWidth : 0),
+          start: { segmentIndex: startSeg, graphemeIndex: startG },
+          end: { segmentIndex: pendingBreakSeg, graphemeIndex: pendingBreakG }
+        };
+      }
+      if (w > slotWidth && seg.graphemeWidths) {
+        const text3 = buildLineText(segments, startSeg, startG, lineEndSeg, lineEndG, false);
+        return {
+          text: text3,
+          width: lineW,
+          start: { segmentIndex: startSeg, graphemeIndex: startG },
+          end: { segmentIndex: lineEndSeg, graphemeIndex: lineEndG }
+        };
+      }
+      const text2 = buildLineText(segments, startSeg, startG, lineEndSeg, lineEndG, false);
+      return {
+        text: text2,
+        width: lineW,
+        start: { segmentIndex: startSeg, graphemeIndex: startG },
+        end: { segmentIndex: lineEndSeg, graphemeIndex: lineEndG }
+      };
+    }
+    lineW = newW;
+    lineEndSeg = i + 1;
+    lineEndG = 0;
+    if (canBreakAfter(seg.kind)) {
+      recordPending(i + 1, 0, seg.kind === "space" ? lineW - w : lineW, seg.kind);
+    }
+    i += 1;
+  }
+  if (!hasContent) return null;
+  const endsAtSoftHyphen = lineEndSeg > 0 && segments[lineEndSeg - 1]?.kind === "soft-hyphen";
+  const text = buildLineText(segments, startSeg, startG, lineEndSeg, lineEndG, endsAtSoftHyphen);
+  return {
+    text,
+    width: lineW + (endsAtSoftHyphen ? hyphenWidth : 0),
+    start: { segmentIndex: startSeg, graphemeIndex: startG },
+    end: { segmentIndex: lineEndSeg, graphemeIndex: lineEndG }
+  };
+}
+function carveTextLineSlots(base, blocked, minSlotWidth = 0) {
+  let slots = [base];
+  for (let bi = 0; bi < blocked.length; bi++) {
+    const block = blocked[bi];
+    const next = [];
+    for (let si = 0; si < slots.length; si++) {
+      const slot = slots[si];
+      if (block.right <= slot.left || block.left >= slot.right) {
+        next.push(slot);
+        continue;
+      }
+      if (block.left > slot.left) next.push({ left: slot.left, right: block.left });
+      if (block.right < slot.right) next.push({ left: block.right, right: slot.right });
+    }
+    slots = next;
+  }
+  if (minSlotWidth > 0) {
+    return slots.filter((s) => s.right - s.left >= minSlotWidth);
+  }
+  return slots;
+}
 function computeCharPositions(lineBreaks, segments, lineHeight) {
   const positions = [];
-  const graphemeSegmenter = new Intl.Segmenter(void 0, {
+  const graphemeSegmenter2 = new Intl.Segmenter(void 0, {
     granularity: "grapheme"
   });
   for (let lineIdx = 0; lineIdx < lineBreaks.lines.length; lineIdx++) {
@@ -5253,7 +5882,7 @@ function computeCharPositions(lineBreaks, segments, lineHeight) {
         if (si >= line.endSegment && line.endGrapheme === 0) break;
         continue;
       }
-      const graphemes = [...graphemeSegmenter.segment(seg.text)].map((g) => g.segment);
+      const graphemes = [...graphemeSegmenter2.segment(seg.text)].map((g) => g.segment);
       if (graphemes.length === 0) continue;
       const startG = si === line.startSegment ? line.startGrapheme : 0;
       let endG;
@@ -5609,6 +6238,185 @@ function reactiveBlockLayout(opts) {
     totalHeight: totalHeightNode
   };
 }
+
+// src/patterns/reactive-layout/reactive-flow-layout.ts
+function circleIntervalForBand(o, bandTop, bandBottom) {
+  const hPad = o.hPad ?? 0;
+  const vPad = o.vPad ?? 0;
+  const top = bandTop - vPad;
+  const bottom = bandBottom + vPad;
+  if (top >= o.cy + o.r || bottom <= o.cy - o.r) return null;
+  const minDy = o.cy >= top && o.cy <= bottom ? 0 : o.cy < top ? top - o.cy : o.cy - bottom;
+  if (minDy >= o.r) return null;
+  const maxDx = Math.sqrt(o.r * o.r - minDy * minDy);
+  return { left: o.cx - maxDx - hPad, right: o.cx + maxDx + hPad };
+}
+function rectIntervalForBand(o, bandTop, bandBottom) {
+  const hPad = o.hPad ?? 0;
+  const vPad = o.vPad ?? 0;
+  if (bandBottom <= o.y - vPad) return null;
+  if (bandTop >= o.y + o.h + vPad) return null;
+  return { left: o.x - hPad, right: o.x + o.w + hPad };
+}
+function obstacleIntervalForBand(o, bandTop, bandBottom) {
+  return o.kind === "circle" ? circleIntervalForBand(o, bandTop, bandBottom) : rectIntervalForBand(o, bandTop, bandBottom);
+}
+function computeFlowLines(segments, container, columns, obstacles, lineHeight, minSlotWidth) {
+  const lines = [];
+  let cursor = { segmentIndex: 0, graphemeIndex: 0 };
+  if (segments.length === 0 || columns.count <= 0 || lineHeight <= 0) {
+    return { lines, cursor };
+  }
+  const padX = container.paddingX ?? 0;
+  const padY = container.paddingY ?? 0;
+  const availWidth = Math.max(0, container.width - padX * 2);
+  const availHeight = Math.max(0, container.height - padY * 2);
+  const gapTotal = columns.gap * Math.max(0, columns.count - 1);
+  const colWidth = Math.max(0, (availWidth - gapTotal) / columns.count);
+  if (colWidth <= 0) return { lines, cursor };
+  outerCol: for (let col = 0; col < columns.count; col++) {
+    const colLeft = padX + col * (colWidth + columns.gap);
+    const colRight = colLeft + colWidth;
+    let bandTop = padY;
+    while (bandTop + lineHeight <= padY + availHeight) {
+      const bandBottom = bandTop + lineHeight;
+      const blocked = [];
+      for (let oi = 0; oi < obstacles.length; oi++) {
+        const iv = obstacleIntervalForBand(obstacles[oi], bandTop, bandBottom);
+        if (iv !== null) blocked.push(iv);
+      }
+      const slots = carveTextLineSlots({ left: colLeft, right: colRight }, blocked, minSlotWidth);
+      if (slots.length === 0) {
+        bandTop += lineHeight;
+        continue;
+      }
+      let hardBreakThisBand = false;
+      for (let si = 0; si < slots.length; si++) {
+        const slot = slots[si];
+        const slotW = slot.right - slot.left;
+        const line = layoutNextLine(segments, cursor, slotW);
+        if (line === null) {
+          return { lines, cursor };
+        }
+        if (line.text.length === 0 && line.width === 0) {
+          cursor = line.end;
+          hardBreakThisBand = true;
+          break;
+        }
+        lines.push({
+          x: slot.left,
+          y: bandTop,
+          width: line.width,
+          slotWidth: slotW,
+          text: line.text,
+          columnIndex: col,
+          flushToRight: slot.right < colRight - 0.5
+        });
+        cursor = line.end;
+      }
+      bandTop += lineHeight;
+      if (hardBreakThisBand) continue;
+      if (cursor.segmentIndex >= segments.length) break outerCol;
+    }
+    if (cursor.segmentIndex >= segments.length) break;
+  }
+  return { lines, cursor };
+}
+function reactiveFlowLayout(opts) {
+  const { adapter, name = "reactive-flow-layout", minSlotWidth = 20 } = opts;
+  const g = new Graph(name);
+  const measureCache = /* @__PURE__ */ new Map();
+  const textNode = state(opts.text ?? "", { name: "text" });
+  const fontNode = state(opts.font ?? "16px sans-serif", { name: "font" });
+  const lineHeightNode = state(opts.lineHeight ?? 20, { name: "line-height" });
+  const containerNode = state(
+    opts.container ?? { width: 800, height: 600, paddingX: 0, paddingY: 0 },
+    { name: "container" }
+  );
+  const columnsNode = state(opts.columns ?? { count: 1, gap: 0 }, {
+    name: "columns"
+  });
+  const obstaclesNode = state(opts.obstacles ?? [], { name: "obstacles" });
+  const segmentsNode = node(
+    [textNode, fontNode],
+    (data, actions, ctx) => {
+      const b0 = data[0];
+      const textVal = b0 != null && b0.length > 0 ? b0.at(-1) : ctx.prevData[0];
+      const b1 = data[1];
+      const fontVal = b1 != null && b1.length > 0 ? b1.at(-1) : ctx.prevData[1];
+      const result = analyzeAndMeasure(textVal, fontVal, adapter, measureCache);
+      actions.emit(result);
+      return () => {
+        measureCache.clear();
+        adapter.clearCache?.();
+      };
+    },
+    { name: "segments", describeKind: "derived" }
+  );
+  const flowLinesNode = derived(
+    [segmentsNode, containerNode, columnsNode, obstaclesNode, lineHeightNode],
+    ([segs, cont, cols, obs, lh]) => {
+      const segments = segs;
+      const t0 = monotonicNs();
+      const { lines: result, cursor } = computeFlowLines(
+        segments,
+        cont,
+        cols,
+        obs,
+        lh,
+        minSlotWidth
+      );
+      const elapsed = monotonicNs() - t0;
+      const overflow = Math.max(0, segments.length - cursor.segmentIndex);
+      const meta = flowLinesNode.meta;
+      if (meta) {
+        emitToMeta(meta["line-count"], result.length);
+        emitToMeta(meta["layout-time-ns"], elapsed);
+        emitToMeta(meta["overflow-segments"], overflow);
+      }
+      return result;
+    },
+    {
+      name: "flow-lines",
+      meta: {
+        "line-count": 0,
+        "layout-time-ns": 0,
+        "overflow-segments": 0
+      },
+      equals: (a, b) => {
+        const la = a;
+        const lb = b;
+        if (la.length !== lb.length) return false;
+        for (let i = 0; i < la.length; i++) {
+          const pa = la[i];
+          const pb = lb[i];
+          if (pa.x !== pb.x || pa.y !== pb.y || pa.width !== pb.width || pa.slotWidth !== pb.slotWidth || pa.text !== pb.text || pa.columnIndex !== pb.columnIndex || pa.flushToRight !== pb.flushToRight)
+            return false;
+        }
+        return true;
+      }
+    }
+  );
+  g.add("text", textNode);
+  g.add("font", fontNode);
+  g.add("line-height", lineHeightNode);
+  g.add("container", containerNode);
+  g.add("columns", columnsNode);
+  g.add("obstacles", obstaclesNode);
+  g.add("segments", segmentsNode);
+  g.add("flow-lines", flowLinesNode);
+  return {
+    graph: g,
+    setText: (t) => g.set("text", t),
+    setFont: (f) => g.set("font", f),
+    setLineHeight: (lh) => g.set("line-height", lh),
+    setContainer: (c) => g.set("container", c),
+    setColumns: (c) => g.set("columns", c),
+    setObstacles: (o) => g.set("obstacles", o),
+    segments: segmentsNode,
+    flowLines: flowLinesNode
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CanvasMeasureAdapter,
@@ -5618,13 +6426,19 @@ function reactiveBlockLayout(opts) {
   PrecomputedAdapter,
   SvgBoundsAdapter,
   analyzeAndMeasure,
+  carveTextLineSlots,
+  circleIntervalForBand,
   computeBlockFlow,
   computeCharPositions,
+  computeFlowLines,
   computeLineBreaks,
   computeTotalHeight,
+  layoutNextLine,
   measureBlock,
   measureBlocks,
   reactiveBlockLayout,
-  reactiveLayout
+  reactiveFlowLayout,
+  reactiveLayout,
+  rectIntervalForBand
 });
 //# sourceMappingURL=index.cjs.map