@neoloopy/cld-canvas 0.1.3 → 0.1.7

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 neoloopy
+Copyright (c) 2026 Abraham Kim
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,6 +5,10 @@ engine used by neoloopy surfaces, including the Obsidian plugin and web app.
 Pure TypeScript, ESM-only, with no runtime dependency on Obsidian, React, Vue,
 or a server.
 
+![An SIR epidemic causal-loop diagram open on the neoloopy canvas in Obsidian, with the link-editing toolbar visible](https://raw.githubusercontent.com/frozenabe/neoloopy-obsidian/main/screenshots/example-model.png)
+
+<sub>The canvas this package renders — an SIR epidemic model open in Obsidian with the link-editing toolbar.</sub>
+
 **This README is ordered easy → hard** — start at the top with the one-tag React
 drop-in and go only as deep as you need:
 
@@ -463,22 +467,45 @@ import { buildMermaid, render } from "@neoloopy/cld-canvas";
 
 ## 5. Analysis helpers
 
+![A project-dynamics model — effort, schedule pressure, rework, burnout — showing detected reinforcing and balancing loops alongside the insight panel](https://raw.githubusercontent.com/frozenabe/neoloopy-obsidian/main/screenshots/sample-model.png)
+
+<sub>The same loop detection these helpers expose, surfaced in a neoloopy surface — a project-dynamics model with its reinforcing and balancing loops and the insight panel.</sub>
+
 ```ts
-import { LoopGraph, endogeneity } from "@neoloopy/cld-canvas";
+import { LoopGraph, discoverCanvasLoops, endogeneity } from "@neoloopy/cld-canvas";
 
 const loopGraph = new LoopGraph(graph.nodes);
-const loops = loopGraph.detectLoops();
+const qualitative = loopGraph.detectLoops();
+const { loops, analysisError } = discoverCanvasLoops(graph.nodes, qualitative, {
+  manifest: graph.manifest,
+});
 const metrics = loopGraph.metrics();
 const summary = endogeneity(graph.nodes, loops);
 ```
 
+`discoverCanvasLoops` first enriches each declared qualitative loop whose whole
+authored route resolves to exact visible connectors or material pipe legs, even
+when quantitative analysis is unavailable or incomplete. It adds a synthesized
+quantitative loop only when its complete executable route resolves just as
+exactly.
+Material endpoints may be explicit or use the unique, direct, signed legacy
+flow-to-stock encoding already supported by SFD rendering. It preserves
+qualitative loop identity and deduplicates exact counterparts. Quantitative
+discovery failures surface as `analysisError` and add no partial quantitative
+badge. A declared qualitative loop whose exact canvas route cannot be resolved
+keeps its established CLD identity and badge but is excluded from SFD; that
+qualitative exclusion by itself does not set `analysisError`. SFD retains every
+exactly resolved qualitative loop; a quantitative-only SFD badge additionally
+requires at least one first-class material leg.
+
 ## What is exported
 
 The package exports the public modules from `src/index.ts`, including:
 
 - Engine: `NativeEngine`, `NeoloopyEngine`, `MemoryStorage`, `VaultStorage`
 - Domain types: `VariableFile`, `VaultLink`, `ModelManifest`, `GraphView`
-- Graph logic: `LoopGraph`, `DetectedLoop`, `LoopType`, `labelLoopsByKey`
+- Graph logic: `LoopGraph`, `DetectedLoop`, `LoopType`, `labelLoopsByKey`,
+  `discoverCanvasLoops`
 - Rendering: `paint`, `SceneCache`, `Camera`, `LIGHT`, `DARK`, geometry helpers
 - File codecs: `parseNote`, `serializeNote`, `manifestFromJson`
 - Exporters: `render`, `buildMermaid`, `loopNoteKey`

package/dist/engine/engine.d.ts

@@ -7,6 +7,7 @@
 import { DetectedLoop, ModelManifest, VarType, VariableFile, Viewport } from "./types";
 import { Rendered } from "./exporters";
 import { ParentAnchor } from "./subsystemLinks";
+import { ChildInterface } from "./publicInterface";
 /** Lightweight model descriptor for pickers/lists (no notes loaded). */
 export interface ModelRef {
     id: string;
@@ -33,6 +34,8 @@ export interface GraphView {
     /** loop.key -> "R1" / "B2" badge label. */
     labels: Map<string, string>;
     quant: boolean;
+    /** Non-null when quantitative canvas-loop discovery could not complete. */
+    analysisError?: string | null;
 }
 export interface NewVariable {
     label: string;
@@ -157,7 +160,17 @@ export interface NeoloopyEngine {
     setEquation(folder: string, id: string, patch: QuantPatch): Promise<VariableFile>;
     /** Cosmetic position change — never bumps rev/modified. */
     moveVariable(folder: string, id: string, x: number, y: number): Promise<void>;
+    /** Cosmetic SFD-view position change (`extra.sfd`) — never bumps rev/modified. */
+    moveVariableSfd(folder: string, id: string, x: number, y: number): Promise<void>;
+    /**
+     * If a model has no authored SFD coordinates, persist the deterministic SFD
+     * fallback positions into `extra.sfd` so the first manual SFD edit does not
+     * make the diagram jump back to CLD coordinates.
+     */
+    pinSfdLayout(folder: string): Promise<void>;
     removeVariable(folder: string, id: string): Promise<void>;
+    /** Validated SFD material topology write for a flow note (`extra.flow`). */
+    setFlowEndpoints(folder: string, flowId: string, from: string, to: string): Promise<void>;
     /**
      * Link (or clear, with `child=null`) a node's subsystem anchor — the same
      * `[[../<childDir>/System|<Child Name>]]` wikilink the app/CLI write, so the
@@ -176,10 +189,10 @@ export interface NeoloopyEngine {
     export(folder: string, format: ExportFormat): Promise<Rendered>;
     /**
      * Loop notes — one `Loops/<slug>.md` file per feedback loop, identity-anchored
-     * in frontmatter (the same files the Dart app/CLI write). Resolved into a map
-     * keyed by `<R|B>:<sorted unique variable names>` so both surfaces agree.
-     * `getLoopNotes` returns the body text per live loop; `setLoopNote` writes it
-     * into the identity-matched file (preserving title/valence/archetype).
+     * in frontmatter (the same files the Dart app/CLI write). Qualitative entries
+     * retain the established `<R|B>:<sorted unique variable names>` map key;
+     * quantitative-only entries use their exact directed `loop.key` so distinct
+     * routes cannot collide. `setLoopNote` accepts that one resolved key.
      */
     getLoopNotes(folder: string): Promise<Record<string, string>>;
     setLoopNote(folder: string, key: string, text: string): Promise<void>;
@@ -200,4 +213,13 @@ export interface NeoloopyEngine {
      * Each anchor names the parent model + the linking variable. Empty when none.
      */
     deriveParents(folder: string): Promise<ParentAnchor[]>;
+    /**
+     * The public interface of the child model linked from `varId`'s subsystem
+     * anchor: a display qualifier (the link alias, else the child model name) plus
+     * the labels of the child's public OUTPUTS and INPUTS. Null when the node has
+     * no subsystem link, or the child can't be resolved/loaded (fail closed —
+     * callers render a muted fallback). Read-only: the qualitative engine never
+     * edits the quant interface (publish/bind live in the app/CLI/MCP).
+     */
+    childInterface(folder: string, varId: string): Promise<ChildInterface | null>;
 }

package/dist/engine/exporters.d.ts

@@ -16,7 +16,7 @@ export interface ExportEdge {
     id?: string;
     source: string;
     target: string;
-    polarity?: number;
+    polarity?: number | "?";
     delay?: boolean;
     curvature?: number;
     dashed?: boolean;

package/dist/engine/exporters.js

@@ -26,7 +26,7 @@ export function buildMermaid(nodes, edges) {
         const t = key.get(String(e.target));
         if (!s || !t)
             continue;
-        const sym = (e.polarity ?? 1) >= 0 ? "+" : "−";
+        const sym = e.polarity === "?" ? "?" : (e.polarity ?? 1) >= 0 ? "+" : "−";
         const arrow = e.delay === true ? "-.->" : "-->";
         lines.push(`  ${s} ${arrow}|${sym}| ${t}`);
     }

package/dist/engine/loopGraph.d.ts

@@ -23,9 +23,9 @@ export interface VarMetrics {
     loopCount: number;
 }
 /**
- * Deterministic loop labels: reinforcing -> R1,R2,… and balancing -> B1,B2,…,
- * ordered within each type by case-insensitive sorted variable names. Returns a
- * map from `DetectedLoop.key` to its label.
+ * Deterministic loop labels: reinforcing -> R1,R2,… and balancing -> B1,B2,….
+ * Existing qualitative loops keep their historical ordering and numbering;
+ * quantitative-only loops follow them in the same deterministic name order.
  */
 export declare function labelLoopsByKey(loops: DetectedLoop[], name: (id: string) => string): Map<string, string>;
 export declare class LoopGraph {
@@ -37,7 +37,11 @@ export declare class LoopGraph {
     adjacency(reverse?: boolean): Map<string, TracedEdge[]>;
     /** Direct (loop-relevant) adjacency: source -> [target, polaritySign]. */
     private directAdjacency;
-    /** All simple directed cycles, R/B classified, deduped to one per node-set. */
+    /**
+     * All simple directed cycles, R/B classified, deduped by the legacy node
+     * set. When distinct directed routes collapse to that compatibility key, the
+     * retained CLD loop is marked ambiguous so SFD resolution can fail closed.
+     */
     detectLoops(): DetectedLoop[];
     /**
      * The Shortest Independent Loop Set (SILS): the minimum-weight basis of the

package/dist/engine/loopKey.d.ts

@@ -1,3 +1,4 @@
+import { DetectedLoop } from "./types";
 /**
  * The resolved-map key for a feedback loop: `<R|B>:<sorted unique member
  * labels>`. This is the key every UI consumer indexes loop notes by; it is NOT
@@ -9,6 +10,14 @@
  * its own copy.
  */
 export declare function loopKey(labels: string[], type: string): string;
+/**
+ * The one UI/engine lookup key for a detected loop note. Existing qualitative
+ * loops, including a qualitative counterpart enriched with a quantitative
+ * canvas path, retain the sorted-label key shared with earlier releases.
+ * Quantitative-only loops use exact directed id identity so different routes
+ * through the same displayed members remain independent.
+ */
+export declare function resolvedLoopNoteKey(loop: DetectedLoop, nameOf: (id: string) => string): string;
 /**
  * Human-readable, non-link echo for a loop note's `loop:` frontmatter field:
  * `<R|B> · <sorted unique labels joined by " | ">`. Same membership rule as

package/dist/engine/loopKey.js

@@ -1,3 +1,4 @@
+import { LoopType } from "./types";
 /**
  * The resolved-map key for a feedback loop: `<R|B>:<sorted unique member
  * labels>`. This is the key every UI consumer indexes loop notes by; it is NOT
@@ -13,6 +14,19 @@ export function loopKey(labels, type) {
     const uniq = [...new Set(labels.map((l) => String(l)))].sort();
     return `${letter}:${uniq.join("|")}`;
 }
+/**
+ * The one UI/engine lookup key for a detected loop note. Existing qualitative
+ * loops, including a qualitative counterpart enriched with a quantitative
+ * canvas path, retain the sorted-label key shared with earlier releases.
+ * Quantitative-only loops use exact directed id identity so different routes
+ * through the same displayed members remain independent.
+ */
+export function resolvedLoopNoteKey(loop, nameOf) {
+    if (loop.identityMode === "quantitative")
+        return loop.exactKey;
+    const type = loop.type === LoopType.reinforcing ? "R" : "B";
+    return loopKey(loop.nodeIds.map(nameOf), type);
+}
 /**
  * Human-readable, non-link echo for a loop note's `loop:` frontmatter field:
  * `<R|B> · <sorted unique labels joined by " | ">`. Same membership rule as

package/dist/engine/nativeEngine.d.ts

@@ -26,6 +26,7 @@ import { contentSignature } from "./specHash";
 import { Rendered } from "./exporters";
 import { VaultStorage } from "./storage";
 import { ParentAnchor } from "./subsystemLinks";
+import { ChildInterface } from "./publicInterface";
 export interface NativeEngineOptions {
     /** Vault-relative base folder for newly created models (may be ""). */
     modelsRoot: string;
@@ -84,13 +85,17 @@ export declare class NativeEngine implements NeoloopyEngine {
         name: string;
     } | null): Promise<void>;
     moveVariable(folder: string, id: string, x: number, y: number): Promise<void>;
+    moveVariableSfd(folder: string, id: string, x: number, y: number): Promise<void>;
+    pinSfdLayout(folder: string): Promise<void>;
     removeVariable(folder: string, id: string): Promise<void>;
+    setFlowEndpoints(folder: string, flowId: string, from: string, to: string): Promise<void>;
     addLink(folder: string, from: string, to: string, init?: LinkInit): Promise<void>;
     updateLink(folder: string, from: string, to: string, patch: LinkPatch): Promise<void>;
     removeLink(folder: string, from: string, to: string): Promise<void>;
     buildModel(folder: string, spec: BuildSpec): Promise<void>;
     relayout(folder: string): Promise<void>;
     setViewport(folder: string, viewport: Viewport): Promise<void>;
+    private liveLoopContext;
     getLoopNotes(folder: string): Promise<Record<string, string>>;
     setLoopNote(folder: string, key: string, text: string): Promise<void>;
     /**
@@ -102,6 +107,7 @@ export declare class NativeEngine implements NeoloopyEngine {
     loopNotePath(folder: string, key: string): Promise<string | null>;
     ensureSystemNote(folder: string): Promise<string>;
     deriveParents(folder: string): Promise<ParentAnchor[]>;
+    childInterface(folder: string, varId: string): Promise<ChildInterface | null>;
     export(folder: string, format: ExportFormat): Promise<Rendered>;
     /** The model's `Nodes/` subfolder, where variable notes now live. */
     private nodesDir;
@@ -110,6 +116,8 @@ export declare class NativeEngine implements NeoloopyEngine {
     /** Pre-`Nodes/` location of a variable note, flat at the model root. */
     private legacyNotePath;
     private readNote;
+    private removeNoteById;
+    private detachStockFlowEndpoints;
     private writeNote;
     private readManifest;
     private writeManifest;
@@ -134,13 +142,13 @@ export declare class NativeEngine implements NeoloopyEngine {
      * One-way, idempotent migration of legacy loop annotations from the
      * `model.json` maps into `Loops/*.md` files. Guard: if any `Loops/` file
      * exists the model is treated as migrated and this returns immediately. Each
-     * legacy key is matched to a live loop by its `loopKey`; a matched key keeps
+     * legacy key is matched to a live loop by its resolved note key; a match keeps
      * the loop's canonical member ids, an unmatched key becomes a pre-flagged
      * orphan (`members: []`, original key kept in `loop:`) so nothing is lost.
      * After writing, the four legacy keys are stripped from the manifest.
      */
     private migrateLoopNotesIfNeeded;
-    /** Find the live loop whose `loopKey` == `key`, then upsert its file. No-op
+    /** Find the live loop whose resolved note key == `key`, then upsert its file. No-op
      * (and no file) when the graph carries no such loop. */
     private upsertLoopFileByKey;
     /** Find-or-create the identity-matched `Loops/` file and apply `fields`