@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/reactive-layout-fswlBUvX.d.cts

@@ -0,0 +1,195 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { Graph } from '@graphrefly/pure-ts/graph';
+
+/**
+ * Reactive text layout engine (roadmap §7.1 — Pretext parity).
+ *
+ * Pure-arithmetic text measurement and line breaking without DOM thrashing.
+ * Inspired by [Pretext](https://github.com/chenglou/pretext), rebuilt as a
+ * GraphReFly graph — inspectable via `describe()`, snapshotable, debuggable.
+ *
+ * Two-tier DX:
+ * - `reactiveLayout({ adapter, text?, font?, lineHeight?, maxWidth?, name? })` — convenience factory
+ * - `MeasurementAdapter` — pluggable backends (`measureSegment`; optional `clearCache`)
+ */
+
+/** Pluggable measurement backend. */
+interface MeasurementAdapter {
+    measureSegment(text: string, font: string): {
+        width: number;
+    };
+    /** Optional; adapters may omit for read-only / stateless measurement. */
+    clearCache?(): void;
+}
+/** Mutable counters for `analyzeAndMeasure` cache hit ratio (hits / (hits + misses)). */
+type SegmentMeasureStats = {
+    hits: number;
+    misses: number;
+};
+/** Break kind for each segment (ported from Pretext analysis.ts). */
+type SegmentBreakKind = "text" | "space" | "zero-width-break" | "soft-hyphen" | "hard-break";
+/** A measured text segment ready for line breaking. */
+type PreparedSegment = {
+    text: string;
+    width: number;
+    kind: SegmentBreakKind;
+    /** Grapheme widths for overflow-wrap: break-word (null if single grapheme). */
+    graphemeWidths: number[] | null;
+};
+/** A laid-out line with start/end cursors. */
+type LayoutLine = {
+    text: string;
+    width: number;
+    startSegment: number;
+    startGrapheme: number;
+    endSegment: number;
+    endGrapheme: number;
+};
+/** Per-character position for hit testing. */
+type CharPosition = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    line: number;
+};
+/** Full layout result from the line-breaks derived node. */
+type LineBreaksResult = {
+    lines: LayoutLine[];
+    lineCount: number;
+};
+/**
+ * A position within `PreparedSegment[]` — segment + grapheme offset.
+ * `graphemeIndex: 0` at segment boundaries.
+ *
+ * Used by {@link layoutNextLine} for cursor-based line walking; needed when
+ * lines have varying widths (multi-column flow, text wrapping around obstacles).
+ */
+type LayoutCursor = {
+    segmentIndex: number;
+    graphemeIndex: number;
+};
+/** A horizontal span `[left, right]` in pixels — used by flow-layout slot carving. */
+type Interval = {
+    left: number;
+    right: number;
+};
+/** Result of a single `layoutNextLine` call. */
+type LayoutNextLineResult = {
+    text: string;
+    width: number;
+    start: LayoutCursor;
+    end: LayoutCursor;
+};
+/** Optional context for `layoutNextLine` — enables soft-hyphen visible-hyphen rendering. */
+type LayoutNextLineContext = {
+    adapter?: MeasurementAdapter;
+    font?: string;
+    cache?: Map<string, Map<string, number>>;
+};
+/** Result of the reactive layout graph's describe-accessible state. */
+type ReactiveLayoutBundle = {
+    graph: Graph;
+    /** Set input text. */
+    setText: (text: string) => void;
+    /** Set CSS font string. */
+    setFont: (font: string) => void;
+    /** Set line height (px). */
+    setLineHeight: (lineHeight: number) => void;
+    /** Set max width constraint (px). */
+    setMaxWidth: (maxWidth: number) => void;
+    /** Segments node. */
+    segments: Node<PreparedSegment[]>;
+    /** Line breaks node. */
+    lineBreaks: Node<LineBreaksResult>;
+    /** Total height node. */
+    height: Node<number>;
+    /** Per-character positions node. */
+    charPositions: Node<CharPosition[]>;
+};
+/**
+ * Merge segmentation pieces: sticky punctuation, CJK per-grapheme splitting,
+ * and produce the final measured segment list.
+ */
+declare function analyzeAndMeasure(text: string, font: string, adapter: MeasurementAdapter, cache: Map<string, Map<string, number>>, stats?: SegmentMeasureStats): PreparedSegment[];
+/**
+ * Greedy line-breaking algorithm.
+ *
+ * Walks segments left to right, accumulating width. Breaks when a segment would
+ * overflow maxWidth. Supports:
+ * - Trailing space hang (spaces don't trigger breaks)
+ * - overflow-wrap: break-word via grapheme widths
+ * - Soft hyphens (break opportunity, adds visible hyphen width)
+ * - Hard breaks (forced newline)
+ */
+declare function computeLineBreaks(segments: PreparedSegment[], maxWidth: number, adapter: MeasurementAdapter, font: string, cache: Map<string, Map<string, number>>): LineBreaksResult;
+/**
+ * Lay out the next single line starting from `cursor`, fitting into `slotWidth`.
+ *
+ * Unlike `computeLineBreaks`, which consumes whole text with one `maxWidth`,
+ * this is the cursor-based primitive needed when successive lines have different
+ * widths (multi-column flow, text wrapping around shape obstacles, mixed
+ * column+pullquote layouts).
+ *
+ * Returns `null` when the cursor is past all segments (text exhausted).
+ * At a hard-break with no preceding content, returns an empty line and advances
+ * the cursor past the break so the caller can continue.
+ *
+ * ```ts
+ * let cursor: LayoutCursor = { segmentIndex: 0, graphemeIndex: 0 };
+ * while (true) {
+ *   const line = layoutNextLine(segments, cursor, availableWidth);
+ *   if (line === null) break;
+ *   render(line);
+ *   cursor = line.end;
+ * }
+ * ```
+ */
+declare function layoutNextLine(segments: PreparedSegment[], cursor: LayoutCursor, slotWidth: number, ctx?: LayoutNextLineContext): LayoutNextLineResult | null;
+/**
+ * Subtract blocked horizontal intervals from a base interval, producing
+ * remaining ordered, non-overlapping slots wide enough to fit text.
+ *
+ * Pure geometry — no text dependency. Used by flow-layout to turn obstacle
+ * intersections into per-line layout slots.
+ *
+ * ```ts
+ * carveTextLineSlots({left: 0, right: 600}, [{left: 200, right: 280}])
+ * // → [{left: 0, right: 200}, {left: 280, right: 600}]
+ * ```
+ */
+declare function carveTextLineSlots(base: Interval, blocked: Interval[], minSlotWidth?: number): Interval[];
+/** Compute per-character x,y positions from line breaks and segments. */
+declare function computeCharPositions(lineBreaks: LineBreaksResult, segments: PreparedSegment[], lineHeight: number): CharPosition[];
+type ReactiveLayoutOptions = {
+    /** Measurement backend (required). */
+    adapter: MeasurementAdapter;
+    /** Graph name (default: "reactive-layout"). */
+    name?: string;
+    /** Initial text. */
+    text?: string;
+    /** Initial CSS font string. */
+    font?: string;
+    /** Initial line height in px. */
+    lineHeight?: number;
+    /** Initial max width in px (clamped to ≥ 0). */
+    maxWidth?: number;
+};
+/**
+ * Create a reactive text layout graph.
+ *
+ * ```
+ * Graph("reactive-layout")
+ * ├── node([], { initial: "text" })
+ * ├── node([], { initial: "font" })
+ * ├── node([], { initial: "line-height" })
+ * ├── node([], { initial: "max-width" })
+ * ├── derived("segments")      — text + font → PreparedSegment[]
+ * ├── derived("line-breaks")   — segments + max-width → LineBreaksResult
+ * ├── derived("height")        — line-breaks → number
+ * └── derived("char-positions") — line-breaks + segments → CharPosition[]
+ * ```
+ */
+declare function reactiveLayout(opts: ReactiveLayoutOptions): ReactiveLayoutBundle;
+
+export { type CharPosition as C, type Interval as I, type LayoutCursor as L, type MeasurementAdapter as M, type PreparedSegment as P, type ReactiveLayoutBundle as R, type SegmentBreakKind as S, type LayoutLine as a, type LayoutNextLineContext as b, type LayoutNextLineResult as c, type LineBreaksResult as d, type ReactiveLayoutOptions as e, type SegmentMeasureStats as f, analyzeAndMeasure as g, carveTextLineSlots as h, computeCharPositions as i, computeLineBreaks as j, layoutNextLine as l, reactiveLayout as r };

package/dist/reactive-layout-fswlBUvX.d.ts

@@ -0,0 +1,195 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { Graph } from '@graphrefly/pure-ts/graph';
+
+/**
+ * Reactive text layout engine (roadmap §7.1 — Pretext parity).
+ *
+ * Pure-arithmetic text measurement and line breaking without DOM thrashing.
+ * Inspired by [Pretext](https://github.com/chenglou/pretext), rebuilt as a
+ * GraphReFly graph — inspectable via `describe()`, snapshotable, debuggable.
+ *
+ * Two-tier DX:
+ * - `reactiveLayout({ adapter, text?, font?, lineHeight?, maxWidth?, name? })` — convenience factory
+ * - `MeasurementAdapter` — pluggable backends (`measureSegment`; optional `clearCache`)
+ */
+
+/** Pluggable measurement backend. */
+interface MeasurementAdapter {
+    measureSegment(text: string, font: string): {
+        width: number;
+    };
+    /** Optional; adapters may omit for read-only / stateless measurement. */
+    clearCache?(): void;
+}
+/** Mutable counters for `analyzeAndMeasure` cache hit ratio (hits / (hits + misses)). */
+type SegmentMeasureStats = {
+    hits: number;
+    misses: number;
+};
+/** Break kind for each segment (ported from Pretext analysis.ts). */
+type SegmentBreakKind = "text" | "space" | "zero-width-break" | "soft-hyphen" | "hard-break";
+/** A measured text segment ready for line breaking. */
+type PreparedSegment = {
+    text: string;
+    width: number;
+    kind: SegmentBreakKind;
+    /** Grapheme widths for overflow-wrap: break-word (null if single grapheme). */
+    graphemeWidths: number[] | null;
+};
+/** A laid-out line with start/end cursors. */
+type LayoutLine = {
+    text: string;
+    width: number;
+    startSegment: number;
+    startGrapheme: number;
+    endSegment: number;
+    endGrapheme: number;
+};
+/** Per-character position for hit testing. */
+type CharPosition = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    line: number;
+};
+/** Full layout result from the line-breaks derived node. */
+type LineBreaksResult = {
+    lines: LayoutLine[];
+    lineCount: number;
+};
+/**
+ * A position within `PreparedSegment[]` — segment + grapheme offset.
+ * `graphemeIndex: 0` at segment boundaries.
+ *
+ * Used by {@link layoutNextLine} for cursor-based line walking; needed when
+ * lines have varying widths (multi-column flow, text wrapping around obstacles).
+ */
+type LayoutCursor = {
+    segmentIndex: number;
+    graphemeIndex: number;
+};
+/** A horizontal span `[left, right]` in pixels — used by flow-layout slot carving. */
+type Interval = {
+    left: number;
+    right: number;
+};
+/** Result of a single `layoutNextLine` call. */
+type LayoutNextLineResult = {
+    text: string;
+    width: number;
+    start: LayoutCursor;
+    end: LayoutCursor;
+};
+/** Optional context for `layoutNextLine` — enables soft-hyphen visible-hyphen rendering. */
+type LayoutNextLineContext = {
+    adapter?: MeasurementAdapter;
+    font?: string;
+    cache?: Map<string, Map<string, number>>;
+};
+/** Result of the reactive layout graph's describe-accessible state. */
+type ReactiveLayoutBundle = {
+    graph: Graph;
+    /** Set input text. */
+    setText: (text: string) => void;
+    /** Set CSS font string. */
+    setFont: (font: string) => void;
+    /** Set line height (px). */
+    setLineHeight: (lineHeight: number) => void;
+    /** Set max width constraint (px). */
+    setMaxWidth: (maxWidth: number) => void;
+    /** Segments node. */
+    segments: Node<PreparedSegment[]>;
+    /** Line breaks node. */
+    lineBreaks: Node<LineBreaksResult>;
+    /** Total height node. */
+    height: Node<number>;
+    /** Per-character positions node. */
+    charPositions: Node<CharPosition[]>;
+};
+/**
+ * Merge segmentation pieces: sticky punctuation, CJK per-grapheme splitting,
+ * and produce the final measured segment list.
+ */
+declare function analyzeAndMeasure(text: string, font: string, adapter: MeasurementAdapter, cache: Map<string, Map<string, number>>, stats?: SegmentMeasureStats): PreparedSegment[];
+/**
+ * Greedy line-breaking algorithm.
+ *
+ * Walks segments left to right, accumulating width. Breaks when a segment would
+ * overflow maxWidth. Supports:
+ * - Trailing space hang (spaces don't trigger breaks)
+ * - overflow-wrap: break-word via grapheme widths
+ * - Soft hyphens (break opportunity, adds visible hyphen width)
+ * - Hard breaks (forced newline)
+ */
+declare function computeLineBreaks(segments: PreparedSegment[], maxWidth: number, adapter: MeasurementAdapter, font: string, cache: Map<string, Map<string, number>>): LineBreaksResult;
+/**
+ * Lay out the next single line starting from `cursor`, fitting into `slotWidth`.
+ *
+ * Unlike `computeLineBreaks`, which consumes whole text with one `maxWidth`,
+ * this is the cursor-based primitive needed when successive lines have different
+ * widths (multi-column flow, text wrapping around shape obstacles, mixed
+ * column+pullquote layouts).
+ *
+ * Returns `null` when the cursor is past all segments (text exhausted).
+ * At a hard-break with no preceding content, returns an empty line and advances
+ * the cursor past the break so the caller can continue.
+ *
+ * ```ts
+ * let cursor: LayoutCursor = { segmentIndex: 0, graphemeIndex: 0 };
+ * while (true) {
+ *   const line = layoutNextLine(segments, cursor, availableWidth);
+ *   if (line === null) break;
+ *   render(line);
+ *   cursor = line.end;
+ * }
+ * ```
+ */
+declare function layoutNextLine(segments: PreparedSegment[], cursor: LayoutCursor, slotWidth: number, ctx?: LayoutNextLineContext): LayoutNextLineResult | null;
+/**
+ * Subtract blocked horizontal intervals from a base interval, producing
+ * remaining ordered, non-overlapping slots wide enough to fit text.
+ *
+ * Pure geometry — no text dependency. Used by flow-layout to turn obstacle
+ * intersections into per-line layout slots.
+ *
+ * ```ts
+ * carveTextLineSlots({left: 0, right: 600}, [{left: 200, right: 280}])
+ * // → [{left: 0, right: 200}, {left: 280, right: 600}]
+ * ```
+ */
+declare function carveTextLineSlots(base: Interval, blocked: Interval[], minSlotWidth?: number): Interval[];
+/** Compute per-character x,y positions from line breaks and segments. */
+declare function computeCharPositions(lineBreaks: LineBreaksResult, segments: PreparedSegment[], lineHeight: number): CharPosition[];
+type ReactiveLayoutOptions = {
+    /** Measurement backend (required). */
+    adapter: MeasurementAdapter;
+    /** Graph name (default: "reactive-layout"). */
+    name?: string;
+    /** Initial text. */
+    text?: string;
+    /** Initial CSS font string. */
+    font?: string;
+    /** Initial line height in px. */
+    lineHeight?: number;
+    /** Initial max width in px (clamped to ≥ 0). */
+    maxWidth?: number;
+};
+/**
+ * Create a reactive text layout graph.
+ *
+ * ```
+ * Graph("reactive-layout")
+ * ├── node([], { initial: "text" })
+ * ├── node([], { initial: "font" })
+ * ├── node([], { initial: "line-height" })
+ * ├── node([], { initial: "max-width" })
+ * ├── derived("segments")      — text + font → PreparedSegment[]
+ * ├── derived("line-breaks")   — segments + max-width → LineBreaksResult
+ * ├── derived("height")        — line-breaks → number
+ * └── derived("char-positions") — line-breaks + segments → CharPosition[]
+ * ```
+ */
+declare function reactiveLayout(opts: ReactiveLayoutOptions): ReactiveLayoutBundle;
+
+export { type CharPosition as C, type Interval as I, type LayoutCursor as L, type MeasurementAdapter as M, type PreparedSegment as P, type ReactiveLayoutBundle as R, type SegmentBreakKind as S, type LayoutLine as a, type LayoutNextLineContext as b, type LayoutNextLineResult as c, type LineBreaksResult as d, type ReactiveLayoutOptions as e, type SegmentMeasureStats as f, analyzeAndMeasure as g, carveTextLineSlots as h, computeCharPositions as i, computeLineBreaks as j, layoutNextLine as l, reactiveLayout as r };

package/dist/retry-BDbRZ_gx.d.ts

@@ -0,0 +1,125 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { N as NodeOrValue } from './_internal-B23BagFd.js';
+import { B as BackoffStrategy, a as BackoffPreset } from './backoff-Bnb9OoPh.js';
+import { S as StatusValue } from './status-U-rUI79b.js';
+
+/**
+ * Retry — re-attempt a node on terminal failure.
+ *
+ * Two modes selected by the type of `input`:
+ * - **Source mode** (`Node<T>`): resubscribes the same node after each ERROR.
+ *   Upstream must be `resubscribable: true` or retries are silent no-ops.
+ * - **Factory mode** (`() => Node<T>`): builds a fresh node per attempt.
+ *
+ * Shared with `circuitBreaker` / `rateLimiter`: `NodeOrValue<RetryOptions>`
+ * lets callers swap retry config reactively (re-validates on each attempt).
+ */
+
+/**
+ * Lifecycle-shaped state companion emitted by {@link retry} (DS-13.5.B,
+ * locked 2026-05-01). Tracks the retry state machine's current status,
+ * the attempt counter, and the last scheduled delay (null before the
+ * first retry).
+ *
+ * @category extra/resilience
+ */
+interface RetryState {
+    status: StatusValue;
+    attempt: number;
+    lastDelay_ns: number | null;
+}
+/**
+ * Bundle returned by {@link retry}: the retry-wrapped output node and its
+ * lifecycle state companion. Pre-1.0 break vs the prior `Node<T>` return.
+ *
+ * **Single-subscriber / pipeline-only contract (DS-13.5.B QA, N1, 2026-05-03).**
+ * The `retryState` companion is allocated once at factory time and shared
+ * across all subscribers to `node`. With one subscriber (the typical use
+ * case — wire `node` into your downstream chain, optionally observe
+ * `retryState` separately) the companion reflects a coherent timeline.
+ * With **two or more subscribers** to `node`, each subscriber re-runs the
+ * producer body and writes into the same `retryState`, including
+ * `publish("pending")` resets that can clobber an in-flight machine's
+ * `running`/`paused` state. Don't fan out `node` to multiple subscribers
+ * and rely on `retryState` accuracy unless you use
+ * {@link keepalive} / `share`-style consolidation.
+ *
+ * @category extra/resilience
+ */
+interface RetryBundle<T> {
+    node: Node<T>;
+    retryState: Node<RetryState>;
+}
+type RetryOptions = {
+    /**
+     * Max retry attempts after each terminal `ERROR` (not counting the first failure).
+     *
+     * **Required when `backoff` is set.** Pass `Infinity` to opt in to unbounded retries
+     * — the explicit value rules out the silent-infinite-budget footgun (a flaky provider
+     * + exponential backoff + omitted `count` would previously default to ~2.1B retries).
+     */
+    count?: number;
+    /** Delay between attempts; strategies use **nanoseconds**. */
+    backoff?: BackoffStrategy | BackoffPreset;
+    /**
+     * Caller-supplied metadata merged into the produced node's `meta` (Tier 5.2
+     * D8 widening). Use {@link domainMeta} to tag the layer for `describe()`
+     * grouping. The primitive's `factoryTag("retry", …)` always wins against
+     * caller keys.
+     */
+    meta?: Record<string, unknown>;
+};
+/** Factory-mode-only options. `initial` seeds the outer node's cache before the first attempt. */
+type RetryFactoryOptions<T> = RetryOptions & {
+    /** Initial cache value for the outer node before the factory runs the first time. */
+    initial?: T;
+};
+/**
+ * Retry operator — two modes selected by the type of `input`:
+ *
+ * **Source mode** (`input: Node<T>`): resubscribes to the same node after each terminal
+ * `ERROR`. The upstream should use `resubscribable: true` if it must emit again after `ERROR`.
+ *
+ * **Factory mode** (`input: () => Node<T>`): invokes the factory to build a fresh `Node<T>`
+ * on every connect / reconnect. Ideal for producers that capture per-attempt resources
+ * (sockets, clients, file handles) that become unusable after an error. Synchronous
+ * exceptions thrown by the factory are treated as terminal ERROR and run through the
+ * same retry pipeline as inner-node ERROR.
+ *
+ * @param input - Upstream node or factory that returns a fresh node per attempt.
+ * @param opts - `count` caps attempts (**required when `backoff` is set**; pass `Infinity` to opt in to unbounded); `backoff` supplies delay in **nanoseconds** (or a preset name); `initial` seeds the outer node cache (factory mode only).
+ * @returns Node that retries on error.
+ *
+ * @throws {RangeError} when `backoff` is provided without an explicit `count` (unbounded-retry footgun guard) or when `count < 0`.
+ *
+ * @remarks
+ * **Protocol:** Forwards unknown message tuples unchanged; handles `DIRTY`, `DATA`, `RESOLVED`, `COMPLETE`, `ERROR`.
+ *
+ * **Backoff floor:** every scheduled delay is floored at 1ms via `Math.max(1, delayNs / NS_PER_MS)` even when the strategy returns 0ns. This avoids 0-delay re-entrancy on the active stack frame on a tight ERROR loop. Strategies that return `null`/`undefined` stop retrying immediately and forward the original error.
+ *
+ * @example
+ * ```ts
+ * // Source mode — resubscribe the same node:
+ * import { ERROR, NS_PER_SEC, producer, retry, constant } from "@graphrefly/graphrefly-ts";
+ *
+ * const src = producer(
+ *   (a) => { a.down([[ERROR, new Error("x")]]); },
+ *   { resubscribable: true },
+ * );
+ * const out = retry(src, { count: 2, backoff: constant(0.25 * NS_PER_SEC) });
+ *
+ * // Factory mode — fresh node per attempt (e.g. reconnecting WebSocket):
+ * import { NS_PER_SEC, exponential, retry, fromWebSocket } from "@graphrefly/graphrefly-ts";
+ *
+ * const connected$ = retry(
+ *   () => fromWebSocket(new WebSocket("wss://example/stream")),
+ *   { count: 10, backoff: exponential({ baseNs: 1 * NS_PER_SEC }) },
+ * );
+ * ```
+ *
+ * @category extra
+ */
+declare function retry<T>(input: Node<T>, opts?: NodeOrValue<RetryOptions>): RetryBundle<T>;
+declare function retry<T>(input: () => Node<T>, opts?: NodeOrValue<RetryFactoryOptions<T>>): RetryBundle<T>;
+
+export { type RetryBundle as R, type RetryFactoryOptions as a, type RetryOptions as b, type RetryState as c, retry as r };

package/dist/retry-DWuhjvsA.d.cts

@@ -0,0 +1,125 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { N as NodeOrValue } from './_internal-B23BagFd.cjs';
+import { B as BackoffStrategy, a as BackoffPreset } from './backoff-Bnb9OoPh.cjs';
+import { S as StatusValue } from './status-U-rUI79b.cjs';
+
+/**
+ * Retry — re-attempt a node on terminal failure.
+ *
+ * Two modes selected by the type of `input`:
+ * - **Source mode** (`Node<T>`): resubscribes the same node after each ERROR.
+ *   Upstream must be `resubscribable: true` or retries are silent no-ops.
+ * - **Factory mode** (`() => Node<T>`): builds a fresh node per attempt.
+ *
+ * Shared with `circuitBreaker` / `rateLimiter`: `NodeOrValue<RetryOptions>`
+ * lets callers swap retry config reactively (re-validates on each attempt).
+ */
+
+/**
+ * Lifecycle-shaped state companion emitted by {@link retry} (DS-13.5.B,
+ * locked 2026-05-01). Tracks the retry state machine's current status,
+ * the attempt counter, and the last scheduled delay (null before the
+ * first retry).
+ *
+ * @category extra/resilience
+ */
+interface RetryState {
+    status: StatusValue;
+    attempt: number;
+    lastDelay_ns: number | null;
+}
+/**
+ * Bundle returned by {@link retry}: the retry-wrapped output node and its
+ * lifecycle state companion. Pre-1.0 break vs the prior `Node<T>` return.
+ *
+ * **Single-subscriber / pipeline-only contract (DS-13.5.B QA, N1, 2026-05-03).**
+ * The `retryState` companion is allocated once at factory time and shared
+ * across all subscribers to `node`. With one subscriber (the typical use
+ * case — wire `node` into your downstream chain, optionally observe
+ * `retryState` separately) the companion reflects a coherent timeline.
+ * With **two or more subscribers** to `node`, each subscriber re-runs the
+ * producer body and writes into the same `retryState`, including
+ * `publish("pending")` resets that can clobber an in-flight machine's
+ * `running`/`paused` state. Don't fan out `node` to multiple subscribers
+ * and rely on `retryState` accuracy unless you use
+ * {@link keepalive} / `share`-style consolidation.
+ *
+ * @category extra/resilience
+ */
+interface RetryBundle<T> {
+    node: Node<T>;
+    retryState: Node<RetryState>;
+}
+type RetryOptions = {
+    /**
+     * Max retry attempts after each terminal `ERROR` (not counting the first failure).
+     *
+     * **Required when `backoff` is set.** Pass `Infinity` to opt in to unbounded retries
+     * — the explicit value rules out the silent-infinite-budget footgun (a flaky provider
+     * + exponential backoff + omitted `count` would previously default to ~2.1B retries).
+     */
+    count?: number;
+    /** Delay between attempts; strategies use **nanoseconds**. */
+    backoff?: BackoffStrategy | BackoffPreset;
+    /**
+     * Caller-supplied metadata merged into the produced node's `meta` (Tier 5.2
+     * D8 widening). Use {@link domainMeta} to tag the layer for `describe()`
+     * grouping. The primitive's `factoryTag("retry", …)` always wins against
+     * caller keys.
+     */
+    meta?: Record<string, unknown>;
+};
+/** Factory-mode-only options. `initial` seeds the outer node's cache before the first attempt. */
+type RetryFactoryOptions<T> = RetryOptions & {
+    /** Initial cache value for the outer node before the factory runs the first time. */
+    initial?: T;
+};
+/**
+ * Retry operator — two modes selected by the type of `input`:
+ *
+ * **Source mode** (`input: Node<T>`): resubscribes to the same node after each terminal
+ * `ERROR`. The upstream should use `resubscribable: true` if it must emit again after `ERROR`.
+ *
+ * **Factory mode** (`input: () => Node<T>`): invokes the factory to build a fresh `Node<T>`
+ * on every connect / reconnect. Ideal for producers that capture per-attempt resources
+ * (sockets, clients, file handles) that become unusable after an error. Synchronous
+ * exceptions thrown by the factory are treated as terminal ERROR and run through the
+ * same retry pipeline as inner-node ERROR.
+ *
+ * @param input - Upstream node or factory that returns a fresh node per attempt.
+ * @param opts - `count` caps attempts (**required when `backoff` is set**; pass `Infinity` to opt in to unbounded); `backoff` supplies delay in **nanoseconds** (or a preset name); `initial` seeds the outer node cache (factory mode only).
+ * @returns Node that retries on error.
+ *
+ * @throws {RangeError} when `backoff` is provided without an explicit `count` (unbounded-retry footgun guard) or when `count < 0`.
+ *
+ * @remarks
+ * **Protocol:** Forwards unknown message tuples unchanged; handles `DIRTY`, `DATA`, `RESOLVED`, `COMPLETE`, `ERROR`.
+ *
+ * **Backoff floor:** every scheduled delay is floored at 1ms via `Math.max(1, delayNs / NS_PER_MS)` even when the strategy returns 0ns. This avoids 0-delay re-entrancy on the active stack frame on a tight ERROR loop. Strategies that return `null`/`undefined` stop retrying immediately and forward the original error.
+ *
+ * @example
+ * ```ts
+ * // Source mode — resubscribe the same node:
+ * import { ERROR, NS_PER_SEC, producer, retry, constant } from "@graphrefly/graphrefly-ts";
+ *
+ * const src = producer(
+ *   (a) => { a.down([[ERROR, new Error("x")]]); },
+ *   { resubscribable: true },
+ * );
+ * const out = retry(src, { count: 2, backoff: constant(0.25 * NS_PER_SEC) });
+ *
+ * // Factory mode — fresh node per attempt (e.g. reconnecting WebSocket):
+ * import { NS_PER_SEC, exponential, retry, fromWebSocket } from "@graphrefly/graphrefly-ts";
+ *
+ * const connected$ = retry(
+ *   () => fromWebSocket(new WebSocket("wss://example/stream")),
+ *   { count: 10, backoff: exponential({ baseNs: 1 * NS_PER_SEC }) },
+ * );
+ * ```
+ *
+ * @category extra
+ */
+declare function retry<T>(input: Node<T>, opts?: NodeOrValue<RetryOptions>): RetryBundle<T>;
+declare function retry<T>(input: () => Node<T>, opts?: NodeOrValue<RetryFactoryOptions<T>>): RetryBundle<T>;
+
+export { type RetryBundle as R, type RetryFactoryOptions as a, type RetryOptions as b, type RetryState as c, retry as r };