@graphrefly/graphrefly 0.27.0 → 0.29.0

package/dist/index-DDy8eeXS.d.ts

@@ -0,0 +1,321 @@
+import { a as Node } from './node-Dd6wHSib.js';
+import { G as Graph } from './graph-Qjg9gWHI.js';
+import { L as LLMAdapter } from './types-u64Ose53.js';
+
+/**
+ * LLM graph composition (roadmap §8.3).
+ *
+ * Declarative GraphSpec schema + compiler/decompiler for graph topology.
+ * The LLM designs graphs as JSON; compileSpec instantiates them; decompileGraph
+ * extracts them back. Templates support reusable subgraph patterns. Feedback
+ * edges express bounded cycles via §8.1 feedback().
+ *
+ * @module
+ */
+
+/** A single node declaration in a GraphSpec. */
+type GraphSpecNode = {
+    /** Node kind: state, producer, derived, effect, operator. */
+    type: "state" | "producer" | "derived" | "effect" | "operator";
+    /** Dependency node names (for derived/effect/operator). */
+    deps?: string[];
+    /** Named function from the catalog (for derived/effect/operator/producer). */
+    fn?: string;
+    /** Named source from the catalog (for producer). */
+    source?: string;
+    /** Freeform config passed to the catalog fn/source factory. */
+    config?: Record<string, unknown>;
+    /** Initial value (for state nodes). */
+    initial?: unknown;
+    /** Human/LLM-readable metadata. */
+    meta?: Record<string, unknown>;
+};
+/** Template instantiation node — expanded at compile time. */
+type GraphSpecTemplateRef = {
+    type: "template";
+    /** Name of the template to instantiate. */
+    template: string;
+    /** Parameter bindings: template param name → node name. */
+    bind: Record<string, string>;
+};
+/** A reusable subgraph pattern with parameter substitution. */
+type GraphSpecTemplate = {
+    /** Parameter names (prefixed with $ in node refs). */
+    params: string[];
+    /** Node declarations within the template. */
+    nodes: Record<string, GraphSpecNode>;
+    /** Which node's output is the template's output. */
+    output: string;
+};
+/** A feedback edge: bounded cycle from condition to reentry. */
+type GraphSpecFeedbackEdge = {
+    /** Node whose DATA triggers the feedback. */
+    from: string;
+    /** State node that receives the feedback value. */
+    to: string;
+    /** Max iterations before stopping (default: 10). */
+    maxIterations?: number;
+};
+/** Declarative graph topology for LLM composition (§8.3). */
+type GraphSpec = {
+    /** Graph name. */
+    name: string;
+    /** Node declarations (keyed by node name). */
+    nodes: Record<string, GraphSpecNode | GraphSpecTemplateRef>;
+    /** Reusable subgraph templates. */
+    templates?: Record<string, GraphSpecTemplate>;
+    /** Feedback edges (bounded cycles). */
+    feedback?: GraphSpecFeedbackEdge[];
+};
+/**
+ * Factory for creating a derived/effect/operator node from catalog.
+ * Receives resolved dep nodes and the config from the spec.
+ */
+type FnFactory = (deps: Node<unknown>[], config: Record<string, unknown>) => Node<unknown>;
+/**
+ * Factory for creating a producer node from catalog.
+ * Receives the config from the spec.
+ */
+type SourceFactory = (config: Record<string, unknown>) => Node<unknown>;
+/** Simple config field descriptor for LLM prompt generation and validation. */
+type ConfigFieldSchema = {
+    /** Human-readable type: "string", "number", "boolean", "string[]", etc. */
+    type: string;
+    /** Whether this field is required (default: true). */
+    required?: boolean;
+    /** Allowed values (enum constraint). */
+    enum?: readonly (string | number | boolean)[];
+    /** Human-readable description for LLM context. */
+    description?: string;
+    /** Default value if omitted. */
+    default?: unknown;
+};
+/**
+ * Rich catalog entry: bundles a runtime factory with LLM-facing metadata.
+ *
+ * The metadata is used to:
+ * 1. Auto-generate prompt text for {@link llmCompose} (replaces manual `catalogDescription`)
+ * 2. Validate LLM output in {@link validateSpec} (catch wrong fn names, invalid config)
+ * 3. Provide actionable error messages for {@link llmRefine} feedback loops
+ *
+ * Developers register ONE object; the library handles prompt generation and validation.
+ */
+type CatalogFnEntry = {
+    /** Runtime factory. */
+    factory: FnFactory;
+    /** One-line description for LLM prompt (what it does, not how). */
+    description: string;
+    /** Config field schemas. Keys are config field names. */
+    configSchema?: Record<string, ConfigFieldSchema>;
+    /** Example config objects (shown in prompt for complex fns). */
+    examples?: Record<string, unknown>[];
+    /** Category tags for grouping in prompt (e.g., "resilience", "reduction", "ai"). */
+    tags?: string[];
+};
+/** Rich catalog entry for producer sources. */
+type CatalogSourceEntry = {
+    /** Runtime factory. */
+    factory: SourceFactory;
+    /** One-line description for LLM prompt. */
+    description: string;
+    /** Config field schemas. */
+    configSchema?: Record<string, ConfigFieldSchema>;
+    /** Example config objects. */
+    examples?: Record<string, unknown>[];
+    /** Category tags. */
+    tags?: string[];
+};
+/**
+ * Fn/source lookup table passed to compileSpec and llmCompose.
+ *
+ * Accepts both bare factories (backward-compatible) and rich {@link CatalogFnEntry}
+ * / {@link CatalogSourceEntry} objects. When rich entries are provided, the library
+ * auto-generates LLM prompts and validates LLM output against the catalog.
+ */
+type GraphSpecCatalog = {
+    fns?: Record<string, FnFactory | CatalogFnEntry>;
+    sources?: Record<string, SourceFactory | CatalogSourceEntry>;
+};
+/** Type guard: is this a rich catalog fn entry (vs bare factory)? */
+declare function isRichFnEntry(entry: FnFactory | CatalogFnEntry): entry is CatalogFnEntry;
+/** Type guard: is this a rich catalog source entry (vs bare factory)? */
+declare function isRichSourceEntry(entry: SourceFactory | CatalogSourceEntry): entry is CatalogSourceEntry;
+/** Extract the runtime factory from a catalog entry (rich or bare). */
+declare function extractFnFactory(entry: FnFactory | CatalogFnEntry): FnFactory;
+/** Extract the runtime factory from a catalog source entry (rich or bare). */
+declare function extractSourceFactory(entry: SourceFactory | CatalogSourceEntry): SourceFactory;
+/**
+ * Auto-generate catalog prompt text from rich catalog entries.
+ *
+ * Groups fns by tag, formats each as `- name: description. Config: { ... }`.
+ * Falls back to listing names only for bare factories.
+ */
+declare function generateCatalogPrompt(catalog: GraphSpecCatalog): string;
+/**
+ * Validate a GraphSpec against a catalog.
+ *
+ * Checks that fn/source names reference actual catalog entries, and validates
+ * config fields against configSchema when rich entries are available.
+ * Returns additional errors beyond structural {@link validateSpec} checks.
+ */
+declare function validateSpecAgainstCatalog(spec: GraphSpec, catalog: GraphSpecCatalog): GraphSpecValidation;
+/** Validation result from {@link validateSpec}. */
+type GraphSpecValidation = {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Validate a GraphSpec JSON object.
+ *
+ * Checks structural validity: required fields, node types, dep references,
+ * template references, feedback edge targets, self-cycles, and bind completeness.
+ */
+declare function validateSpec(spec: unknown): GraphSpecValidation;
+/** Options for {@link compileSpec}. */
+type CompileSpecOptions = {
+    /** Fn/source catalog for resolving named factories. */
+    catalog?: GraphSpecCatalog;
+};
+/**
+ * Instantiate a Graph from a GraphSpec.
+ *
+ * Handles template expansion (mounted subgraphs), feedback wiring via §8.1
+ * feedback(), node factory lookup from the catalog, and topology validation.
+ *
+ * @param spec - Declarative graph topology.
+ * @param opts - Catalog and compile options.
+ * @returns A running Graph.
+ * @throws On validation failure, missing catalog entries, or unresolvable deps.
+ *
+ * @category patterns
+ */
+declare function compileSpec(spec: GraphSpec, opts?: CompileSpecOptions): Graph;
+/**
+ * Extract a GraphSpec from a running graph.
+ *
+ * Uses `describe({ detail: "standard" })` as a starting point, then enriches:
+ * - Feedback edges recovered from counter node meta (`feedbackFrom`/`feedbackTo`)
+ * - Template refs recovered from output node meta (`_templateName`/`_templateBind`)
+ * - Structural fingerprinting as fallback for 2+ identical mounted subgraphs
+ *
+ * @param graph - Running graph to decompile.
+ * @returns A GraphSpec representation.
+ *
+ * @category patterns
+ */
+declare function decompileGraph(graph: Graph): GraphSpec;
+/** A single change in a spec diff. */
+type SpecDiffEntry = {
+    type: "added" | "removed" | "changed";
+    path: string;
+    detail?: string;
+};
+/** Structural diff between two GraphSpecs. */
+type SpecDiffResult = {
+    entries: SpecDiffEntry[];
+    summary: string;
+};
+/**
+ * Compute a structural diff between two GraphSpecs.
+ *
+ * Template-aware: reports "changed template definition" vs "changed
+ * instantiation bindings." No runtime needed — pure JSON comparison.
+ *
+ * @param specA - The "before" spec.
+ * @param specB - The "after" spec.
+ * @returns Diff entries and a human-readable summary.
+ *
+ * @category patterns
+ */
+declare function specDiff(specA: GraphSpec, specB: GraphSpec): SpecDiffResult;
+/** Options for {@link llmCompose}. */
+type LLMComposeOptions = {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Extra instructions appended to the system prompt. */
+    systemPromptExtra?: string;
+    /**
+     * Available fn/source catalog names for the LLM to reference.
+     * When omitted and `catalog` contains rich {@link CatalogFnEntry} entries,
+     * the prompt is auto-generated via {@link generateCatalogPrompt}.
+     */
+    catalogDescription?: string;
+    /**
+     * Catalog for auto-prompt generation and catalog-aware validation.
+     * When rich entries are provided, the catalog prompt is auto-generated
+     * and LLM output is validated against fn/source names and config schemas.
+     */
+    catalog?: GraphSpecCatalog;
+    /**
+     * Max auto-refine attempts when the LLM output fails catalog validation.
+     * Each attempt feeds the validation errors back to the LLM via llmRefine.
+     * Default: 0 (no auto-refine). Set to 2-3 for production use.
+     */
+    maxAutoRefine?: number;
+};
+/**
+ * Ask an LLM to compose a GraphSpec from a natural-language problem description.
+ *
+ * The LLM generates a GraphSpec (with templates + feedback), validated before
+ * returning. The spec is for human review before compilation via compileSpec().
+ *
+ * @param problem - Natural language problem description.
+ * @param adapter - LLM adapter for the generation call.
+ * @param opts - Model options and catalog description.
+ * @returns A validated GraphSpec.
+ * @throws On invalid LLM output or validation failure.
+ *
+ * @category patterns
+ */
+declare function llmCompose(problem: string, adapter: LLMAdapter, opts?: LLMComposeOptions): Promise<GraphSpec>;
+/** Options for {@link llmRefine}. */
+type LLMRefineOptions = LLMComposeOptions;
+/**
+ * Ask an LLM to modify an existing GraphSpec based on feedback or changed requirements.
+ *
+ * @param currentSpec - The current GraphSpec to modify.
+ * @param feedback - Natural language feedback or changed requirements.
+ * @param adapter - LLM adapter for the generation call.
+ * @param opts - Model options.
+ * @returns A new GraphSpec incorporating the feedback.
+ * @throws On invalid LLM output or validation failure.
+ *
+ * @category patterns
+ */
+declare function llmRefine(currentSpec: GraphSpec, feedback: string, adapter: LLMAdapter, opts?: LLMRefineOptions): Promise<GraphSpec>;
+
+type index_CatalogFnEntry = CatalogFnEntry;
+type index_CatalogSourceEntry = CatalogSourceEntry;
+type index_CompileSpecOptions = CompileSpecOptions;
+type index_ConfigFieldSchema = ConfigFieldSchema;
+type index_FnFactory = FnFactory;
+type index_GraphSpec = GraphSpec;
+type index_GraphSpecCatalog = GraphSpecCatalog;
+type index_GraphSpecFeedbackEdge = GraphSpecFeedbackEdge;
+type index_GraphSpecNode = GraphSpecNode;
+type index_GraphSpecTemplate = GraphSpecTemplate;
+type index_GraphSpecTemplateRef = GraphSpecTemplateRef;
+type index_GraphSpecValidation = GraphSpecValidation;
+type index_LLMComposeOptions = LLMComposeOptions;
+type index_LLMRefineOptions = LLMRefineOptions;
+type index_SourceFactory = SourceFactory;
+type index_SpecDiffEntry = SpecDiffEntry;
+type index_SpecDiffResult = SpecDiffResult;
+declare const index_compileSpec: typeof compileSpec;
+declare const index_decompileGraph: typeof decompileGraph;
+declare const index_extractFnFactory: typeof extractFnFactory;
+declare const index_extractSourceFactory: typeof extractSourceFactory;
+declare const index_generateCatalogPrompt: typeof generateCatalogPrompt;
+declare const index_isRichFnEntry: typeof isRichFnEntry;
+declare const index_isRichSourceEntry: typeof isRichSourceEntry;
+declare const index_llmCompose: typeof llmCompose;
+declare const index_llmRefine: typeof llmRefine;
+declare const index_specDiff: typeof specDiff;
+declare const index_validateSpec: typeof validateSpec;
+declare const index_validateSpecAgainstCatalog: typeof validateSpecAgainstCatalog;
+declare namespace index {
+  export { type index_CatalogFnEntry as CatalogFnEntry, type index_CatalogSourceEntry as CatalogSourceEntry, type index_CompileSpecOptions as CompileSpecOptions, type index_ConfigFieldSchema as ConfigFieldSchema, type index_FnFactory as FnFactory, type index_GraphSpec as GraphSpec, type index_GraphSpecCatalog as GraphSpecCatalog, type index_GraphSpecFeedbackEdge as GraphSpecFeedbackEdge, type index_GraphSpecNode as GraphSpecNode, type index_GraphSpecTemplate as GraphSpecTemplate, type index_GraphSpecTemplateRef as GraphSpecTemplateRef, type index_GraphSpecValidation as GraphSpecValidation, type index_LLMComposeOptions as LLMComposeOptions, type index_LLMRefineOptions as LLMRefineOptions, type index_SourceFactory as SourceFactory, type index_SpecDiffEntry as SpecDiffEntry, type index_SpecDiffResult as SpecDiffResult, index_compileSpec as compileSpec, index_decompileGraph as decompileGraph, index_extractFnFactory as extractFnFactory, index_extractSourceFactory as extractSourceFactory, index_generateCatalogPrompt as generateCatalogPrompt, index_isRichFnEntry as isRichFnEntry, index_isRichSourceEntry as isRichSourceEntry, index_llmCompose as llmCompose, index_llmRefine as llmRefine, index_specDiff as specDiff, index_validateSpec as validateSpec, index_validateSpecAgainstCatalog as validateSpecAgainstCatalog };
+}
+
+export { type CatalogFnEntry as C, type FnFactory as F, type GraphSpec as G, type LLMComposeOptions as L, type SourceFactory as S, type CatalogSourceEntry as a, type ConfigFieldSchema as b, type GraphSpecCatalog as c, type GraphSpecFeedbackEdge as d, type GraphSpecNode as e, type GraphSpecTemplate as f, type GraphSpecTemplateRef as g, type GraphSpecValidation as h, index as i, type CompileSpecOptions as j, type LLMRefineOptions as k, type SpecDiffEntry as l, type SpecDiffResult as m, compileSpec as n, decompileGraph as o, extractFnFactory as p, extractSourceFactory as q, generateCatalogPrompt as r, isRichFnEntry as s, isRichSourceEntry as t, llmCompose as u, llmRefine as v, specDiff as w, validateSpec as x, validateSpecAgainstCatalog as y };

package/dist/index-DJ5oNBc8.d.ts

@@ -0,0 +1,143 @@
+import { a as Node, N as NodeOptions, c as NodeActions } from './node-Dd6wHSib.js';
+import { D as DerivedFn } from './sugar-CY-MCfZ9.js';
+import { G as Graph, a as GraphOptions } from './graph-Qjg9gWHI.js';
+
+/**
+ * Orchestration patterns (roadmap §4.1).
+ *
+ * Domain-layer helpers that build workflow shapes on top of core + extra primitives.
+ * Exported under the `patterns.orchestration` namespace to avoid collisions with
+ * Phase 2 operator names (for example `gate`, `forEach`).
+ */
+
+type StepRef = string | Node<unknown>;
+type OrchestrationMeta = {
+    orchestration?: true;
+    orchestration_type?: string;
+};
+type OrchestrationStepOptions = Omit<NodeOptions<unknown>, "describeKind" | "name" | "meta"> & {
+    deps?: ReadonlyArray<StepRef>;
+    meta?: Record<string, unknown> & OrchestrationMeta;
+};
+type BranchResult<T> = {
+    branch: "then" | "else";
+    value: T;
+};
+type SensorControls<T> = {
+    node: Node<T>;
+    push(value: T): void;
+    error(err: unknown): void;
+    complete(): void;
+};
+type LoopOptions = Omit<OrchestrationStepOptions, "deps"> & {
+    iterations?: number | StepRef;
+};
+type SubPipelineBuilder = (sub: Graph) => void;
+/**
+ * Creates an orchestration graph container.
+ */
+declare function pipeline(name: string, opts?: GraphOptions): Graph;
+/**
+ * Registers a workflow task node.
+ */
+declare function task<T>(graph: Graph, name: string, run: DerivedFn<T>, opts?: OrchestrationStepOptions): Node<T>;
+/**
+ * Emits tagged branch outcomes (`then` / `else`) for each source value.
+ */
+declare function branch<T>(graph: Graph, name: string, source: StepRef, predicate: (value: T) => boolean, opts?: Omit<OrchestrationStepOptions, "deps">): Node<BranchResult<T>>;
+type ApprovalOptions = Omit<OrchestrationStepOptions, "deps"> & {
+    isApproved?: (value: unknown) => boolean;
+};
+/**
+ * Human/LLM approval gate over a source value.
+ */
+declare function approval<T>(graph: Graph, name: string, source: StepRef, approver: StepRef, opts?: ApprovalOptions): Node<T>;
+interface GateOptions {
+    /** Maximum queue size. Oldest values are FIFO-dropped when exceeded. Default: Infinity. */
+    maxPending?: number;
+    /** Start in open mode (auto-approve). Default: false. */
+    startOpen?: boolean;
+    meta?: Record<string, unknown>;
+}
+/** Control surface returned by {@link gate}. */
+interface GateController<T> {
+    /** The output node registered in the graph (subscribe to receive approved values). */
+    node: Node<T>;
+    /** Reactive queue of values waiting for approval. */
+    pending: Node<T[]>;
+    /** Derived count of pending items. */
+    count: Node<number>;
+    /** Whether the gate is currently open (auto-approving). */
+    isOpen: Node<boolean>;
+    /** Approve and forward the next `count` pending values (default: 1). */
+    approve(count?: number): void;
+    /** Reject (discard) the next `count` pending values (default: 1). */
+    reject(count?: number): void;
+    /**
+     * Transform and forward `count` pending values (default: 1).
+     * `fn` receives `(value, index, pending)` — Array.map-style.
+     */
+    modify(fn: (value: T, index: number, pending: readonly T[]) => T, count?: number): void;
+    /** Flush all pending values and auto-approve future values. */
+    open(): void;
+    /** Re-enable manual gating (stop auto-approving). */
+    close(): void;
+}
+/**
+ * Human-in-the-loop gate: queues incoming values from `source` and lets an external
+ * controller {@link GateController.approve approve}, {@link GateController.reject reject},
+ * or {@link GateController.modify modify} them before forwarding downstream.
+ *
+ * Observable surfaces (`pending`, `count`, `isOpen`) are reactive nodes registered in
+ * the graph. The gate output node is also registered.
+ */
+declare function gate<T>(graph: Graph, name: string, source: StepRef, opts?: GateOptions): GateController<T>;
+/**
+ * Registers a join step that emits a tuple of latest dependency values.
+ */
+declare function join<T extends readonly unknown[]>(graph: Graph, name: string, deps: {
+    [K in keyof T]: StepRef;
+}, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
+/**
+ * Registers a loop step that applies `iterate` to each source value N times.
+ */
+declare function loop<T>(graph: Graph, name: string, source: StepRef, iterate: (value: T, iteration: number, actions: NodeActions) => T, opts?: LoopOptions): Node<T>;
+/**
+ * Mounts and returns a child workflow graph.
+ */
+declare function subPipeline(graph: Graph, name: string, childOrBuild?: Graph | SubPipelineBuilder, opts?: GraphOptions): Graph;
+/**
+ * Registers a producer-style sensor source and returns imperative controls.
+ */
+declare function sensor<T>(graph: Graph, name: string, initial?: T, opts?: Omit<NodeOptions<unknown>, "name" | "describeKind" | "meta"> & {
+    meta?: Record<string, unknown>;
+}): SensorControls<T>;
+/**
+ * Registers an error-recovery step for a source.
+ */
+declare function onFailure<T>(graph: Graph, name: string, source: StepRef, recover: (err: unknown, actions: NodeActions) => T, opts?: Omit<OrchestrationStepOptions, "deps">): Node<T>;
+
+type index_ApprovalOptions = ApprovalOptions;
+type index_BranchResult<T> = BranchResult<T>;
+type index_GateController<T> = GateController<T>;
+type index_GateOptions = GateOptions;
+type index_LoopOptions = LoopOptions;
+type index_OrchestrationStepOptions = OrchestrationStepOptions;
+type index_SensorControls<T> = SensorControls<T>;
+type index_StepRef = StepRef;
+type index_SubPipelineBuilder = SubPipelineBuilder;
+declare const index_approval: typeof approval;
+declare const index_branch: typeof branch;
+declare const index_gate: typeof gate;
+declare const index_join: typeof join;
+declare const index_loop: typeof loop;
+declare const index_onFailure: typeof onFailure;
+declare const index_pipeline: typeof pipeline;
+declare const index_sensor: typeof sensor;
+declare const index_subPipeline: typeof subPipeline;
+declare const index_task: typeof task;
+declare namespace index {
+  export { type index_ApprovalOptions as ApprovalOptions, type index_BranchResult as BranchResult, type index_GateController as GateController, type index_GateOptions as GateOptions, type index_LoopOptions as LoopOptions, type index_OrchestrationStepOptions as OrchestrationStepOptions, type index_SensorControls as SensorControls, type index_StepRef as StepRef, type index_SubPipelineBuilder as SubPipelineBuilder, index_approval as approval, index_branch as branch, index_gate as gate, index_join as join, index_loop as loop, index_onFailure as onFailure, index_pipeline as pipeline, index_sensor as sensor, index_subPipeline as subPipeline, index_task as task };
+}
+
+export { type ApprovalOptions as A, type BranchResult as B, type GateController as G, type LoopOptions as L, type OrchestrationStepOptions as O, type SensorControls as S, type GateOptions as a, type StepRef as b, type SubPipelineBuilder as c, approval as d, branch as e, subPipeline as f, gate as g, index as i, join as j, loop as l, onFailure as o, pipeline as p, sensor as s, task as t };

package/dist/{index-CI3DprxP.d.cts → index-DP0_O3ls.d.cts}

@@ -1,6 +1,6 @@
-import { M as MeasurementAdapter, P as PreparedSegment, L as LineBreaksResult, C as CharPosition, a as LayoutCursor, I as Interval, b as LayoutLine, c as LayoutNextLineContext, d as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from './reactive-layout-MQP--J3F.cjs';
-import { N as Node } from './node-BmerH3kS.cjs';
-import { a as Graph } from './graph-DNCrvZSn.cjs';
+import { M as MeasurementAdapter, P as PreparedSegment, L as LineBreaksResult, C as CharPosition, a as LayoutCursor, I as Interval, b as LayoutLine, c as LayoutNextLineContext, d as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from './reactive-layout-PiFwVaWS.cjs';
+import { a as Node } from './node-Dd6wHSib.cjs';
+import { G as Graph } from './graph-DgohqXK-.cjs';
 
 /**
  * MeasurementAdapter implementations (roadmap §7.1 — pluggable backends).
@@ -355,6 +355,17 @@ type ReactiveFlowLayoutOptions = {
     obstacles?: Obstacle[];
     /** Minimum slot width (px) below which a slot is discarded rather than squeezed. Default `20`. */
     minSlotWidth?: number;
+    /**
+     * Vertical gap (px) inserted after a hard-break segment (the spacing
+     * between paragraphs). When unset (or explicitly set to `null`), tracks
+     * the current `lineHeight` reactively — one line-height of visible
+     * paragraph gap, matching dense editorial layouts. Set to `0` for
+     * paragraph-preserving layout that reclaims the break line; set larger
+     * (e.g. `2 * lineHeight`) for looser manuscript settings. Reactive —
+     * update via `setParagraphSpacing(n)` or restore to track-lineHeight
+     * mode via `setParagraphSpacing(null)`.
+     */
+    paragraphSpacing?: number | null;
 };
 /** Result bundle from `reactiveFlowLayout`. */
 type ReactiveFlowLayoutBundle = {
@@ -365,6 +376,7 @@ type ReactiveFlowLayoutBundle = {
     setContainer: (c: FlowContainer) => void;
     setColumns: (c: FlowColumns) => void;
     setObstacles: (o: Obstacle[]) => void;
+    setParagraphSpacing: (ps: number | null) => void;
     segments: Node<PreparedSegment[]>;
     flowLines: Node<PositionedLine[]>;
 };
@@ -377,6 +389,17 @@ type FlowLinesResult = {
      *  container couldn't fit all text. */
     cursor: LayoutCursor;
 };
+/** Optional tuning knobs for {@link computeFlowLines}. */
+type ComputeFlowLinesOptions = {
+    /**
+     * Vertical gap (px) inserted after a hard-break segment (the spacing
+     * between paragraphs). Defaults to `lineHeight` — one line-height of
+     * visible paragraph gap, which matches dense editorial layouts. Set to
+     * `0` for paragraph-preserving layout that reclaims the break line;
+     * set larger (e.g. `2 * lineHeight`) for looser manuscript settings.
+     */
+    paragraphSpacing?: number;
+};
 /**
  * Lay out `segments` across N columns, wrapping each line around `obstacles`.
  * Pure function — no reactive wiring. Exported for testing and for consumers
@@ -385,7 +408,7 @@ type FlowLinesResult = {
  * `carveTextLineSlots` guarantees left-to-right-ordered, non-overlapping slots,
  * so this function does not sort them.
  */
-declare function computeFlowLines(segments: PreparedSegment[], container: FlowContainer, columns: FlowColumns, obstacles: Obstacle[], lineHeight: number, minSlotWidth: number): FlowLinesResult;
+declare function computeFlowLines(segments: PreparedSegment[], container: FlowContainer, columns: FlowColumns, obstacles: Obstacle[], lineHeight: number, minSlotWidth: number, opts?: ComputeFlowLinesOptions): FlowLinesResult;
 /**
  * Create a reactive flow-layout graph: N columns of text wrapping around
  * shape obstacles. Re-runs only the dependent derived nodes on any input
@@ -433,6 +456,7 @@ type index_CircleObstacle = CircleObstacle;
 type index_CliMeasureAdapter = CliMeasureAdapter;
 declare const index_CliMeasureAdapter: typeof CliMeasureAdapter;
 type index_CliMeasureAdapterOptions = CliMeasureAdapterOptions;
+type index_ComputeFlowLinesOptions = ComputeFlowLinesOptions;
 type index_ContentBlock = ContentBlock;
 type index_FlowColumns = FlowColumns;
 type index_FlowContainer = FlowContainer;
@@ -485,7 +509,7 @@ declare const index_reactiveFlowLayout: typeof reactiveFlowLayout;
 declare const index_reactiveLayout: typeof reactiveLayout;
 declare const index_rectIntervalForBand: typeof rectIntervalForBand;
 declare namespace index {
-  export { type index_BlockAdapters as BlockAdapters, index_CanvasMeasureAdapter as CanvasMeasureAdapter, type index_CanvasMeasureAdapterOptions as CanvasMeasureAdapterOptions, type index_CanvasModule as CanvasModule, index_CharPosition as CharPosition, type index_CircleObstacle as CircleObstacle, index_CliMeasureAdapter as CliMeasureAdapter, type index_CliMeasureAdapterOptions as CliMeasureAdapterOptions, type index_ContentBlock as ContentBlock, type index_FlowColumns as FlowColumns, type index_FlowContainer as FlowContainer, type index_FlowLinesResult as FlowLinesResult, type index_ImageMeasurer as ImageMeasurer, index_ImageSizeAdapter as ImageSizeAdapter, index_Interval as Interval, index_LayoutCursor as LayoutCursor, index_LayoutLine as LayoutLine, index_LayoutNextLineContext as LayoutNextLineContext, index_LayoutNextLineResult as LayoutNextLineResult, index_LineBreaksResult as LineBreaksResult, type index_MeasuredBlock as MeasuredBlock, index_MeasurementAdapter as MeasurementAdapter, index_NodeCanvasMeasureAdapter as NodeCanvasMeasureAdapter, type index_Obstacle as Obstacle, type index_PositionedBlock as PositionedBlock, type index_PositionedLine as PositionedLine, index_PrecomputedAdapter as PrecomputedAdapter, type index_PrecomputedAdapterOptions as PrecomputedAdapterOptions, index_PreparedSegment as PreparedSegment, type index_ReactiveBlockLayoutBundle as ReactiveBlockLayoutBundle, type index_ReactiveBlockLayoutOptions as ReactiveBlockLayoutOptions, type index_ReactiveFlowLayoutBundle as ReactiveFlowLayoutBundle, type index_ReactiveFlowLayoutOptions as ReactiveFlowLayoutOptions, index_ReactiveLayoutBundle as ReactiveLayoutBundle, index_ReactiveLayoutOptions as ReactiveLayoutOptions, type index_RectObstacle as RectObstacle, index_SegmentBreakKind as SegmentBreakKind, index_SegmentMeasureStats as SegmentMeasureStats, index_SvgBoundsAdapter as SvgBoundsAdapter, type index_SvgMeasurer as SvgMeasurer, index_analyzeAndMeasure as analyzeAndMeasure, index_carveTextLineSlots as carveTextLineSlots, index_circleIntervalForBand as circleIntervalForBand, index_computeBlockFlow as computeBlockFlow, index_computeCharPositions as computeCharPositions, index_computeFlowLines as computeFlowLines, index_computeLineBreaks as computeLineBreaks, index_computeTotalHeight as computeTotalHeight, index_layoutNextLine as layoutNextLine, index_measureBlock as measureBlock, index_measureBlocks as measureBlocks, index_reactiveBlockLayout as reactiveBlockLayout, index_reactiveFlowLayout as reactiveFlowLayout, index_reactiveLayout as reactiveLayout, index_rectIntervalForBand as rectIntervalForBand };
+  export { type index_BlockAdapters as BlockAdapters, index_CanvasMeasureAdapter as CanvasMeasureAdapter, type index_CanvasMeasureAdapterOptions as CanvasMeasureAdapterOptions, type index_CanvasModule as CanvasModule, index_CharPosition as CharPosition, type index_CircleObstacle as CircleObstacle, index_CliMeasureAdapter as CliMeasureAdapter, type index_CliMeasureAdapterOptions as CliMeasureAdapterOptions, type index_ComputeFlowLinesOptions as ComputeFlowLinesOptions, type index_ContentBlock as ContentBlock, type index_FlowColumns as FlowColumns, type index_FlowContainer as FlowContainer, type index_FlowLinesResult as FlowLinesResult, type index_ImageMeasurer as ImageMeasurer, index_ImageSizeAdapter as ImageSizeAdapter, index_Interval as Interval, index_LayoutCursor as LayoutCursor, index_LayoutLine as LayoutLine, index_LayoutNextLineContext as LayoutNextLineContext, index_LayoutNextLineResult as LayoutNextLineResult, index_LineBreaksResult as LineBreaksResult, type index_MeasuredBlock as MeasuredBlock, index_MeasurementAdapter as MeasurementAdapter, index_NodeCanvasMeasureAdapter as NodeCanvasMeasureAdapter, type index_Obstacle as Obstacle, type index_PositionedBlock as PositionedBlock, type index_PositionedLine as PositionedLine, index_PrecomputedAdapter as PrecomputedAdapter, type index_PrecomputedAdapterOptions as PrecomputedAdapterOptions, index_PreparedSegment as PreparedSegment, type index_ReactiveBlockLayoutBundle as ReactiveBlockLayoutBundle, type index_ReactiveBlockLayoutOptions as ReactiveBlockLayoutOptions, type index_ReactiveFlowLayoutBundle as ReactiveFlowLayoutBundle, type index_ReactiveFlowLayoutOptions as ReactiveFlowLayoutOptions, index_ReactiveLayoutBundle as ReactiveLayoutBundle, index_ReactiveLayoutOptions as ReactiveLayoutOptions, type index_RectObstacle as RectObstacle, index_SegmentBreakKind as SegmentBreakKind, index_SegmentMeasureStats as SegmentMeasureStats, index_SvgBoundsAdapter as SvgBoundsAdapter, type index_SvgMeasurer as SvgMeasurer, index_analyzeAndMeasure as analyzeAndMeasure, index_carveTextLineSlots as carveTextLineSlots, index_circleIntervalForBand as circleIntervalForBand, index_computeBlockFlow as computeBlockFlow, index_computeCharPositions as computeCharPositions, index_computeFlowLines as computeFlowLines, index_computeLineBreaks as computeLineBreaks, index_computeTotalHeight as computeTotalHeight, index_layoutNextLine as layoutNextLine, index_measureBlock as measureBlock, index_measureBlocks as measureBlocks, index_reactiveBlockLayout as reactiveBlockLayout, index_reactiveFlowLayout as reactiveFlowLayout, index_reactiveLayout as reactiveLayout, index_rectIntervalForBand as rectIntervalForBand };
 }
 
-export { rectIntervalForBand as A, type BlockAdapters as B, CanvasMeasureAdapter as C, type FlowColumns as F, type ImageMeasurer as I, type MeasuredBlock as M, NodeCanvasMeasureAdapter as N, type Obstacle as O, type PositionedBlock as P, type ReactiveBlockLayoutBundle as R, SvgBoundsAdapter as S, type CanvasMeasureAdapterOptions as a, type CanvasModule as b, type CircleObstacle as c, CliMeasureAdapter as d, type CliMeasureAdapterOptions as e, type ContentBlock as f, type FlowContainer as g, type FlowLinesResult as h, index as i, ImageSizeAdapter as j, type PositionedLine as k, PrecomputedAdapter as l, type PrecomputedAdapterOptions as m, type ReactiveBlockLayoutOptions as n, type ReactiveFlowLayoutBundle as o, type ReactiveFlowLayoutOptions as p, type RectObstacle as q, type SvgMeasurer as r, circleIntervalForBand as s, computeBlockFlow as t, computeFlowLines as u, computeTotalHeight as v, measureBlock as w, measureBlocks as x, reactiveBlockLayout as y, reactiveFlowLayout as z };
+export { reactiveFlowLayout as A, type BlockAdapters as B, CanvasMeasureAdapter as C, rectIntervalForBand as D, type FlowColumns as F, type ImageMeasurer as I, type MeasuredBlock as M, NodeCanvasMeasureAdapter as N, type Obstacle as O, type PositionedBlock as P, type ReactiveBlockLayoutBundle as R, SvgBoundsAdapter as S, type CanvasMeasureAdapterOptions as a, type CanvasModule as b, type CircleObstacle as c, CliMeasureAdapter as d, type CliMeasureAdapterOptions as e, type ComputeFlowLinesOptions as f, type ContentBlock as g, type FlowContainer as h, index as i, type FlowLinesResult as j, ImageSizeAdapter as k, type PositionedLine as l, PrecomputedAdapter as m, type PrecomputedAdapterOptions as n, type ReactiveBlockLayoutOptions as o, type ReactiveFlowLayoutBundle as p, type ReactiveFlowLayoutOptions as q, type RectObstacle as r, type SvgMeasurer as s, circleIntervalForBand as t, computeBlockFlow as u, computeFlowLines as v, computeTotalHeight as w, measureBlock as x, measureBlocks as y, reactiveBlockLayout as z };

package/dist/{demo-shell-Crid1WdR.d.cts → index-DX8xS-yB.d.cts}

@@ -1,5 +1,5 @@
-import { a as Graph } from './graph-DNCrvZSn.cjs';
-import { M as MeasurementAdapter } from './reactive-layout-MQP--J3F.cjs';
+import { G as Graph } from './graph-DgohqXK-.cjs';
+import { M as MeasurementAdapter } from './reactive-layout-PiFwVaWS.cjs';
 
 /**
  * Three-pane demo shell (roadmap §7.2).
@@ -86,17 +86,17 @@ type DemoShellHandle = {
  */
 declare function demoShell(opts?: DemoShellOptions): DemoShellHandle;
 
-type demoShell$1_DemoShellHandle = DemoShellHandle;
-type demoShell$1_DemoShellOptions = DemoShellOptions;
-type demoShell$1_FullscreenPane = FullscreenPane;
-type demoShell$1_GraphLabelSize = GraphLabelSize;
-type demoShell$1_HighlightCallbacks = HighlightCallbacks;
-type demoShell$1_HoverPaneType = HoverPaneType;
-type demoShell$1_HoverTarget = HoverTarget;
-type demoShell$1_NodeRegistry = NodeRegistry;
-declare const demoShell$1_demoShell: typeof demoShell;
-declare namespace demoShell$1 {
-  export { type demoShell$1_DemoShellHandle as DemoShellHandle, type demoShell$1_DemoShellOptions as DemoShellOptions, type demoShell$1_FullscreenPane as FullscreenPane, type demoShell$1_GraphLabelSize as GraphLabelSize, type demoShell$1_HighlightCallbacks as HighlightCallbacks, type demoShell$1_HoverPaneType as HoverPaneType, type demoShell$1_HoverTarget as HoverTarget, type demoShell$1_NodeRegistry as NodeRegistry, demoShell$1_demoShell as demoShell };
+type index_DemoShellHandle = DemoShellHandle;
+type index_DemoShellOptions = DemoShellOptions;
+type index_FullscreenPane = FullscreenPane;
+type index_GraphLabelSize = GraphLabelSize;
+type index_HighlightCallbacks = HighlightCallbacks;
+type index_HoverPaneType = HoverPaneType;
+type index_HoverTarget = HoverTarget;
+type index_NodeRegistry = NodeRegistry;
+declare const index_demoShell: typeof demoShell;
+declare namespace index {
+  export { type index_DemoShellHandle as DemoShellHandle, type index_DemoShellOptions as DemoShellOptions, type index_FullscreenPane as FullscreenPane, type index_GraphLabelSize as GraphLabelSize, type index_HighlightCallbacks as HighlightCallbacks, type index_HoverPaneType as HoverPaneType, type index_HoverTarget as HoverTarget, type index_NodeRegistry as NodeRegistry, index_demoShell as demoShell };
 }
 
-export { type DemoShellHandle as D, type FullscreenPane as F, type GraphLabelSize as G, type HighlightCallbacks as H, type NodeRegistry as N, type DemoShellOptions as a, type HoverPaneType as b, type HoverTarget as c, demoShell$1 as d, demoShell as e };
+export { type DemoShellHandle as D, type FullscreenPane as F, type GraphLabelSize as G, type HighlightCallbacks as H, type NodeRegistry as N, type DemoShellOptions as a, type HoverPaneType as b, type HoverTarget as c, demoShell as d, index as i };