@neoloopy/cld-canvas 0.1.2 → 0.1.4

package/README.md

@@ -2,14 +2,20 @@
 
 Framework-agnostic causal loop diagram (CLD) canvas renderer and in-memory edit
 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.
 
-The package is pure TypeScript, ESM-only, and has no runtime dependency on
-Obsidian, React, Vue, or a server. It gives you two pieces:
+![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)
 
-- A vault-compatible CLD engine for creating, editing, loading, exporting, and
-  analyzing neoloopy models.
-- A canvas rendering layer for drawing nodes, causal links, polarity chips,
-  loop badges, selection state, and pan/zoom views.
+<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:
+
+1. [React, in one tag](#1-react-in-one-tag-easiest) — easiest
+2. [Build and render it yourself](#2-build-and-render-it-yourself) — any framework / full control
+3. [The engine](#3-the-engine) — create, edit, and load models
+4. [Exporting](#4-exporting) and [analysis](#5-analysis-helpers) — advanced
 
 ## Install
 
@@ -17,30 +23,280 @@ Obsidian, React, Vue, or a server. It gives you two pieces:
 npm install @neoloopy/cld-canvas
 ```
 
-If you use `NativeEngine`, provide a YAML parser for note frontmatter. The
-package does not bundle one:
+If you use the engine (`NativeEngine`), also install a YAML parser for note
+frontmatter — the package does not bundle one:
 
 ```sh
 npm install yaml
 ```
 
-## Requirements
+## 1. React, in one tag (easiest)
 
-- TypeScript or JavaScript with ESM imports
-- `ES2020` runtime support
-- A `CanvasRenderingContext2D` if you use the painter
+Drop the [`<CldCanvas>` component](#the-cldcanvas-component) below into your
+project, hand it a spec, and you're done:
 
-## Quick Start
+```tsx
+import { CldCanvas } from "./CldCanvas";
+
+export default function App() {
+  return (
+    <CldCanvas
+      spec={{
+        variables: [
+          { label: "Users", type: "stock" },
+          { label: "Word of mouth" },
+          { label: "Signups" },
+        ],
+        links: [
+          { from: "Users", to: "Word of mouth", polarity: "+" },
+          { from: "Word of mouth", to: "Signups", polarity: "+" },
+          { from: "Signups", to: "Users", polarity: "+" },
+        ],
+      }}
+    />
+  );
+}
+```
 
-```ts
+It builds the model, detects the feedback loops, frames the diagram, and gives
+you pan (drag) + zoom (wheel) — with no surrounding CSS required. Props: `spec`
+(required), `theme` (`"light"` | `"dark"` | a custom `Theme`), `interactive`
+(default `true`), `height` (number px or CSS string, default `400`), plus
+`onReady(graph)` / `onError(error)` callbacks.
+
+### The `<CldCanvas>` component
+
+Copy this one file into your project; its only dependencies are
+`@neoloopy/cld-canvas` and `yaml`.
+
+```tsx
+// CldCanvas.tsx — a drop-in React wrapper around @neoloopy/cld-canvas.
+import { useEffect, useMemo, useRef } from "react";
+import type { CSSProperties } from "react";
 import { parse } from "yaml";
 import {
   MemoryStorage,
   NativeEngine,
+  Camera,
+  SceneCache,
+  paint,
+  LIGHT,
+  DARK,
 } from "@neoloopy/cld-canvas";
+import type { BuildSpec, GraphView, PaintUi, Theme } from "@neoloopy/cld-canvas";
+
+export interface CldCanvasProps {
+  /** The causal-loop diagram to render: variables + polarized links. */
+  spec: BuildSpec;
+  /** Color tokens — "light" / "dark", or a custom Theme. Default "light". */
+  theme?: "light" | "dark" | Theme;
+  /** Pan (drag) + zoom (wheel). Default true. */
+  interactive?: boolean;
+  /**
+   * Canvas height. A number is pixels (default 400); a string is used verbatim,
+   * so pass "100%" / "60vh" to fill a sized parent. Width always fills the
+   * parent, so `<CldCanvas spec={...} />` works with no surrounding CSS.
+   */
+  height?: number | string;
+  className?: string;
+  style?: CSSProperties;
+  /** Called with the loaded graph (detected loops, badge labels) after a build. */
+  onReady?: (graph: GraphView) => void;
+  /** Called if the spec is invalid or the model fails to build. */
+  onError?: (error: Error) => void;
+}
+
+// Interaction fields the painter wants every frame; we drive only pan/zoom, so
+// the rest stay inert.
+const PAINT_DEFAULTS = {
+  selectedNodeId: null,
+  selectedEdgeId: null,
+  selectedLoopKey: null,
+  liveNodeIds: new Set<string>(),
+  linkPreview: null,
+  connectNodeId: null,
+  loopHighlight: null,
+  pulsePhase: 0,
+  flowPhase: 0,
+} satisfies Omit<PaintUi, "cssWidth" | "cssHeight" | "dpr">;
+
+// The full engine path: an in-memory vault, build the model, load the detected
+// graph. NativeEngine needs a YAML parser for note frontmatter (yaml).
+async function buildGraph(spec: BuildSpec): Promise<GraphView> {
+  const engine = new NativeEngine(new MemoryStorage(), parse, {
+    modelsRoot: "Models",
+  });
+  const model = await engine.createModel("model");
+  await engine.buildModel(model.folder, spec); // layout defaults to true
+  return engine.loadGraph(model.folder);
+}
 
-const storage = new MemoryStorage();
-const engine = new NativeEngine(storage, parse, {
+function resolveTheme(t: CldCanvasProps["theme"]): Theme {
+  if (t === "dark") return DARK;
+  if (t === "light" || t == null) return LIGHT;
+  return t;
+}
+
+export function CldCanvas({
+  spec,
+  theme = "light",
+  interactive = true,
+  height = 400,
+  className,
+  style,
+  onReady,
+  onError,
+}: CldCanvasProps) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const camera = useRef(new Camera()).current;
+  const sceneCache = useRef(new SceneCache()).current;
+  const graphRef = useRef<GraphView | null>(null);
+  const fitted = useRef(false);
+  const drag = useRef<{ x: number; y: number } | null>(null);
+
+  const resolved = useMemo(() => resolveTheme(theme), [theme]);
+
+  // Mutable mirrors so the build effect and the once-registered listeners read
+  // current values without re-subscribing.
+  const themeRef = useRef(resolved);
+  themeRef.current = resolved;
+  const interactiveRef = useRef(interactive);
+  interactiveRef.current = interactive;
+  const onReadyRef = useRef(onReady);
+  onReadyRef.current = onReady;
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+
+  const render = () => {
+    const canvas = canvasRef.current;
+    const ctx = canvas?.getContext("2d");
+    if (!canvas || !ctx) return;
+
+    const dpr = window.devicePixelRatio || 1;
+    const width = canvas.clientWidth;
+    const height = canvas.clientHeight;
+    const bw = Math.max(1, Math.floor(width * dpr));
+    const bh = Math.max(1, Math.floor(height * dpr));
+    if (canvas.width !== bw) canvas.width = bw;
+    if (canvas.height !== bh) canvas.height = bh;
+
+    const scene = sceneCache.build(graphRef.current, new Map(), new Map());
+    ctx.clearRect(0, 0, bw, bh);
+    if (!scene) return;
+
+    if (!fitted.current && sceneCache.fit(camera, width, height)) {
+      fitted.current = true; // frame once per spec; pan/zoom persists after
+    }
+
+    paint(ctx, scene, camera, themeRef.current, {
+      ...PAINT_DEFAULTS,
+      cssWidth: width,
+      cssHeight: height,
+      dpr,
+    });
+  };
+  const renderRef = useRef(render);
+  renderRef.current = render;
+
+  // Rebuild only when the spec's content changes (not on every parent render).
+  const specKey = useMemo(() => JSON.stringify(spec), [spec]);
+  useEffect(() => {
+    let cancelled = false;
+    buildGraph(spec)
+      .then((graph) => {
+        if (cancelled) return;
+        graphRef.current = graph;
+        fitted.current = false;
+        renderRef.current();
+        onReadyRef.current?.(graph);
+      })
+      .catch((e) => {
+        if (!cancelled) {
+          onErrorRef.current?.(e instanceof Error ? e : new Error(String(e)));
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [specKey]);
+
+  // Repaint (no refit) when the theme changes.
+  useEffect(() => {
+    renderRef.current();
+  }, [resolved]);
+
+  // Register resize + wheel once; both read live state via refs.
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+
+    const ro = new ResizeObserver(() => renderRef.current());
+    ro.observe(canvas);
+
+    const onWheel = (e: WheelEvent) => {
+      if (!interactiveRef.current) return;
+      e.preventDefault();
+      camera.zoomAt(e.offsetX, e.offsetY, Math.exp(-e.deltaY * 0.0015));
+      renderRef.current();
+    };
+    canvas.addEventListener("wheel", onWheel, { passive: false });
+
+    return () => {
+      ro.disconnect();
+      canvas.removeEventListener("wheel", onWheel);
+    };
+  }, [camera]);
+
+  return (
+    <canvas
+      ref={canvasRef}
+      className={className}
+      style={{
+        display: "block",
+        width: "100%",
+        height: typeof height === "number" ? `${height}px` : height,
+        touchAction: "none",
+        background: resolved.paper,
+        cursor: interactive ? "grab" : "default",
+        ...style,
+      }}
+      onPointerDown={(e) => {
+        if (!interactive) return;
+        e.currentTarget.setPointerCapture(e.pointerId);
+        drag.current = { x: e.clientX, y: e.clientY };
+      }}
+      onPointerMove={(e) => {
+        if (!drag.current) return;
+        camera.panBy(e.clientX - drag.current.x, e.clientY - drag.current.y);
+        drag.current = { x: e.clientX, y: e.clientY };
+        renderRef.current();
+      }}
+      onPointerUp={(e) => {
+        drag.current = null;
+        e.currentTarget.releasePointerCapture(e.pointerId);
+      }}
+    />
+  );
+}
+```
+
+The same wrapper shape works in Vue, Svelte, or vanilla DOM — only the lifecycle
+hook around `buildGraph` + `paint` changes.
+
+## 2. Build and render it yourself
+
+Not on React, or want full control? The wrapper above is just two steps: build
+a graph with the engine, then paint it. You need an `ES2020` ESM runtime and a
+`CanvasRenderingContext2D`.
+
+**Step 1 — build a model and load its graph:**
+
+```ts
+import { parse } from "yaml";
+import { MemoryStorage, NativeEngine } from "@neoloopy/cld-canvas";
+
+const engine = new NativeEngine(new MemoryStorage(), parse, {
   modelsRoot: "Models",
 });
 
@@ -59,24 +315,13 @@ await engine.buildModel(model.folder, {
   ],
 });
 
-const graph = await engine.loadGraph(model.folder);
-
-console.log(graph.nodes.map((node) => node.label));
-console.log(graph.loops.length);
+const graph = await engine.loadGraph(model.folder); // detects R/B loops
 ```
 
-## Rendering to Canvas
-
-The renderer is intentionally UI-framework neutral. Build a renderable scene
-from a `GraphView`, configure a `Camera`, then call `paint`.
+**Step 2 — paint the graph to a canvas:**
 
 ```ts
-import {
-  Camera,
-  LIGHT,
-  SceneCache,
-  paint,
-} from "@neoloopy/cld-canvas";
+import { Camera, LIGHT, SceneCache, paint } from "@neoloopy/cld-canvas";
 
 const canvas = document.querySelector("canvas")!;
 const ctx = canvas.getContext("2d")!;
@@ -111,124 +356,17 @@ if (scene) {
 }
 ```
 
-Use `Camera.panBy`, `Camera.zoomAt`, `Camera.setScaleAt`, and
-`Camera.centerOn` to wire your own pointer, wheel, trackpad, minimap, or toolbar
-controls.
+Wire `Camera.panBy`, `Camera.zoomAt`, `Camera.setScaleAt`, and `Camera.centerOn`
+to your own pointer, wheel, trackpad, minimap, or toolbar controls. Canvas
+rendering is stateless: keep selection, hover, and animation clocks in your app
+state and pass them into `SceneCache` / `paint`.
 
-## Using It in React (or any framework)
+## 3. The engine
 
-There is no framework-specific component — `paint` only needs a `<canvas>` 2D
-context, so a thin wrapper is all it takes. A minimal React component that turns
-a spec into a rendered diagram:
+Past rendering, `NativeEngine` is a full create/edit/load API for neoloopy
+models.
 
-```tsx
-import { useEffect, useRef } from "react";
-import { parse } from "yaml";
-import {
-  MemoryStorage,
-  NativeEngine,
-  Camera,
-  SceneCache,
-  paint,
-  LIGHT,
-} from "@neoloopy/cld-canvas";
-import type { BuildSpec } from "@neoloopy/cld-canvas";
-
-export function CldCanvas({ spec }: { spec: BuildSpec }) {
-  const ref = useRef<HTMLCanvasElement>(null);
-
-  useEffect(() => {
-    let alive = true;
-    (async () => {
-      const engine = new NativeEngine(new MemoryStorage(), parse, {
-        modelsRoot: "Models",
-      });
-      const model = await engine.createModel("model");
-      await engine.buildModel(model.folder, spec);
-      const graph = await engine.loadGraph(model.folder);
-
-      const canvas = ref.current;
-      const ctx = canvas?.getContext("2d");
-      if (!alive || !canvas || !ctx) return;
-
-      const dpr = window.devicePixelRatio || 1;
-      const w = canvas.clientWidth;
-      const h = canvas.clientHeight;
-      canvas.width = Math.floor(w * dpr);
-      canvas.height = Math.floor(h * dpr);
-
-      const camera = new Camera();
-      const sceneCache = new SceneCache();
-      const scene = sceneCache.build(graph, new Map(), new Map());
-      if (!scene) return;
-      sceneCache.fit(camera, w, h);
-
-      paint(ctx, scene, camera, LIGHT, {
-        cssWidth: w,
-        cssHeight: h,
-        dpr,
-        selectedNodeId: null,
-        selectedEdgeId: null,
-        selectedLoopKey: null,
-        liveNodeIds: new Set(),
-        linkPreview: null,
-        connectNodeId: null,
-        loopHighlight: null,
-        pulsePhase: 0,
-        flowPhase: 0,
-      });
-    })();
-    return () => {
-      alive = false;
-    };
-  }, [spec]);
-
-  return <canvas ref={ref} style={{ width: "100%", height: 400 }} />;
-}
-```
-
-To make it interactive, keep one `Camera` and one `SceneCache` across renders,
-wire `Camera.panBy` / `Camera.zoomAt` to pointer and wheel events, and repaint.
-The same wrapper shape works in Vue, Svelte, or plain DOM — only the lifecycle
-hook changes.
-
-## Engine Concepts
-
-### Storage
-
-`NativeEngine` works against a small filesystem-like `VaultStorage` interface:
-
-```ts
-interface VaultStorage {
-  exists(path: string): Promise<boolean>;
-  read(path: string): Promise<string>;
-  write(path: string, data: string): Promise<void>;
-  remove(path: string): Promise<void>;
-  mkdirs(path: string): Promise<void>;
-  rmdir(path: string): Promise<void>;
-  move(from: string, to: string): Promise<void>;
-  list(path: string): Promise<{ files: string[]; folders: string[] }>;
-}
-```
-
-Use `MemoryStorage` for tests, demos, and server-side transforms. In production,
-adapt this interface to your host filesystem, browser persistence layer.
-
-All paths are vault-relative and use `/` separators.
-
-### Model Format
-
-A model is stored as:
-
-- `model.json` for model metadata and viewport
-- `Nodes/*.md` for variable notes with YAML frontmatter and Markdown body
-- `Loops/*.md` for feedback loop notes
-- optional system notes such as `System.md`
-
-The engine preserves unknown frontmatter keys so other neoloopy tools can add
-metadata without being clobbered.
-
-### Main Engine Methods
+### Engine methods
 
 ```ts
 const model = await engine.createModel("Model name");
@@ -256,7 +394,8 @@ await engine.relayout(model.folder);
 await engine.setViewport(model.folder, { x: 0, y: 0, zoom: 1 });
 ```
 
-Bulk build is useful when importing generated or external CLD specs:
+Bulk build (used above) is the fastest path for importing generated or external
+CLD specs:
 
 ```ts
 await engine.buildModel(model.folder, {
@@ -272,7 +411,43 @@ await engine.buildModel(model.folder, {
 });
 ```
 
-## Exporting
+### Storage
+
+`NativeEngine` works against a small filesystem-like `VaultStorage` interface:
+
+```ts
+interface VaultStorage {
+  exists(path: string): Promise<boolean>;
+  read(path: string): Promise<string>;
+  write(path: string, data: string): Promise<void>;
+  remove(path: string): Promise<void>;
+  mkdirs(path: string): Promise<void>;
+  rmdir(path: string): Promise<void>;
+  move(from: string, to: string): Promise<void>;
+  list(path: string): Promise<{ files: string[]; folders: string[] }>;
+}
+```
+
+Use `MemoryStorage` for tests, demos, and server-side transforms (it is not
+persistent). In production, adapt this interface to your host filesystem or
+browser persistence layer. All paths are vault-relative and use `/` separators.
+`move` should preserve or update links when your host supports it — the Obsidian
+adapter routes folder moves through Obsidian's file manager so wikilinks remain
+valid.
+
+### Model format
+
+A model is stored as:
+
+- `model.json` for model metadata and viewport
+- `Nodes/*.md` for variable notes with YAML frontmatter and Markdown body
+- `Loops/*.md` for feedback loop notes
+- optional system notes such as `System.md`
+
+The engine preserves unknown frontmatter keys so other neoloopy tools can add
+metadata without being clobbered.
+
+## 4. Exporting
 
 `NativeEngine.export` supports `json`, `mermaid`, and `markdown`.
 
@@ -290,7 +465,11 @@ You can also use the lower-level renderer functions directly:
 import { buildMermaid, render } from "@neoloopy/cld-canvas";
 ```
 
-## Analysis Helpers
+## 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";
@@ -301,7 +480,7 @@ const metrics = loopGraph.metrics();
 const summary = endogeneity(graph.nodes, loops);
 ```
 
-## What Is Exported
+## What is exported
 
 The package exports the public modules from `src/index.ts`, including:
 
@@ -313,13 +492,10 @@ The package exports the public modules from `src/index.ts`, including:
 - Exporters: `render`, `buildMermaid`, `loopNoteKey`
 - Analysis: `endogeneity`
 
-## Notes for Integrators
+## Notes for integrators
 
 - The package is ESM-only. Use `import`, not `require`.
 - The engine is asynchronous because real storage adapters usually perform I/O.
-- `move` should preserve or update links when your host platform supports it.
-  The Obsidian adapter, for example, should route folder moves through Obsidian's
-  file manager so wikilinks remain valid.
 - Canvas rendering is stateless. Keep selection, hover, animation clocks, bow
   caches, and badge overrides in your application state and pass them to
   `SceneCache` or `paint`.

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;
@@ -200,4 +201,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/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;
@@ -102,6 +103,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;

package/dist/engine/nativeEngine.js

@@ -30,7 +30,8 @@ import { autoLayout } from "./layout";
 import { render, } from "./exporters";
 import { LoopType } from "./types";
 import { baseName, joinPath, parentPath, } from "./storage";
-import { deriveParentAnchors } from "./subsystemLinks";
+import { deriveParentAnchors, linkPointsToModel, parseSubsystemLink, } from "./subsystemLinks";
+import { isPublicInput, isPublicOutput, } from "./publicInterface";
 /** Non-variable notes that share a model folder. */
 const SPECIAL_NOTES = new Set(["System.md", "Futures.md", "CLA.md"]);
 const MAX_SCAN_DEPTH = 12;
@@ -532,6 +533,33 @@ export class NativeEngine {
             return [];
         return deriveParentAnchors({ folder: current.folder, name: current.name }, models.filter((m) => m.folder !== folder).map((m) => ({ folder: m.folder, name: m.name })), (f) => this.loadNotes(f));
     }
+    async childInterface(folder, varId) {
+        const nodes = await this.loadNotes(folder);
+        const anchor = nodes.find((n) => n.id === varId);
+        const raw = (anchor?.subsystem ?? "").trim();
+        if (!raw)
+            return null;
+        const { alias } = parseSubsystemLink(raw);
+        const models = await this.listModels();
+        const match = models.find((m) => linkPointsToModel(raw, { folder: m.folder, name: m.name }));
+        if (!match)
+            return null;
+        try {
+            const childNodes = await this.loadNotes(match.folder);
+            const outputs = [];
+            const inputs = [];
+            for (const v of childNodes) {
+                if (isPublicOutput(v))
+                    outputs.push(v.label || v.id);
+                if (isPublicInput(v))
+                    inputs.push(v.label || v.id);
+            }
+            return { qualifier: alias ?? match.name, outputs, inputs };
+        }
+        catch {
+            return null;
+        }
+    }
     // ---- export --------------------------------------------------------------
     async export(folder, format) {
         const view = await this.loadGraph(folder);
@@ -1091,18 +1119,11 @@ function slug(s) {
 }
 function randomHex(bytes) {
     const arr = new Uint8Array(bytes);
-    // Web Crypto is exposed as the global `crypto` in both Obsidian (Electron)
-    // and Node (this pure engine's vitest tests). Referenced bare — not via
-    // `window`/`globalThis` — so it resolves under Node too; `typeof`-guarded so
-    // it falls back to Math.random anywhere it is unavailable.
     const c = typeof crypto !== "undefined" ? crypto : undefined;
-    if (c && typeof c.getRandomValues === "function") {
-        c.getRandomValues(arr);
-    }
-    else {
-        for (let i = 0; i < bytes; i++)
-            arr[i] = Math.floor(Math.random() * 256);
+    if (!c || typeof c.getRandomValues !== "function") {
+        throw new Error("Web Crypto is required to generate neoloopy ids.");
     }
+    c.getRandomValues(arr);
     let s = "";
     for (const b of arr)
         s += b.toString(16).padStart(2, "0");
@@ -1112,9 +1133,7 @@ function genVarId() {
     return `var_${randomHex(4)}`;
 }
 function genModelId() {
-    const n = Date.now() * 1000 + Math.floor(Math.random() * 1000);
-    const hex = n.toString(16);
-    return `mdl_${hex.slice(-6)}`;
+    return `mdl_${randomHex(4)}`;
 }
 /** Re-export so callers don't need a second import for the signature helper. */
 export { contentSignature };

package/dist/engine/noteCodec.js

@@ -79,10 +79,18 @@ function tagsFrom(v) {
 function rawScalar(frontmatter, key) {
     if (frontmatter === null)
         return undefined;
-    const m = new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, "m").exec(frontmatter);
-    if (!m)
+    let s;
+    for (const line of frontmatter.split("\n")) {
+        const colon = line.indexOf(":");
+        if (colon < 0)
+            continue;
+        if (line.slice(0, colon).trim() !== key)
+            continue;
+        s = line.slice(colon + 1).trim();
+        break;
+    }
+    if (s === undefined)
         return undefined;
-    let s = m[1];
     if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
         s = s.slice(1, -1);
     }

package/dist/engine/publicInterface.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Public-interface readers — the TypeScript mirror of the READ side of
+ * `core/lib/quant/public_interface.dart`. In a subsystem-composed model a
+ * variable is exposed to its parent by tagging it under `extra.quant.visibility`
+ * (`'input'` | `'output'`; absent ⇒ private); a parent drives a child's public
+ * input via `inputBindings` declared on the anchor node (the node carrying the
+ * `subsystem` link). The qualitative plugin only READS these — publishing and
+ * binding are quant authoring, which lives in the app/CLI/MCP. Both fields are
+ * preserved verbatim on write (unknown-key carry, format rule §3), so reading
+ * them never risks the data.
+ */
+import { VariableFile } from "./types";
+export type Visibility = "input" | "output";
+/** `'input'` | `'output'` | `null` (private — the default). */
+export declare function quantVisibility(v: VariableFile): Visibility | null;
+export declare function isPublicInput(v: VariableFile): boolean;
+export declare function isPublicOutput(v: VariableFile): boolean;
+/** A parent-side wiring that drives a linked child's public input. */
+export interface InputBinding {
+    /** Qualifier of the linked child (link alias or model name). */
+    child: string;
+    /** Child public-input label or id. */
+    target: string;
+    /** Parent-scope expression that drives the input. */
+    expr: string;
+}
+/** Input bindings declared on this anchor node (empty when none). */
+export declare function quantInputBindings(v: VariableFile): InputBinding[];
+/** A child model's public interface as resolved through a parent's subsystem link. */
+export interface ChildInterface {
+    /** Display qualifier — the link alias, else the child model name. */
+    qualifier: string;
+    /** Labels of the child's public outputs (offered to the parent). */
+    outputs: string[];
+    /** Labels of the child's public inputs (the parent may drive). */
+    inputs: string[];
+}
+/**
+ * A child output as a qualified reference: bracket form when the label has a
+ * space (`ReworkCycle.[Defect Rate]`), bare otherwise. Mirrors the app's `_ref`
+ * in `subsystem_interface_section.dart`.
+ */
+export declare function qualifiedRef(qualifier: string, label: string): string;

package/dist/engine/publicInterface.js

@@ -0,0 +1,52 @@
+/**
+ * Public-interface readers — the TypeScript mirror of the READ side of
+ * `core/lib/quant/public_interface.dart`. In a subsystem-composed model a
+ * variable is exposed to its parent by tagging it under `extra.quant.visibility`
+ * (`'input'` | `'output'`; absent ⇒ private); a parent drives a child's public
+ * input via `inputBindings` declared on the anchor node (the node carrying the
+ * `subsystem` link). The qualitative plugin only READS these — publishing and
+ * binding are quant authoring, which lives in the app/CLI/MCP. Both fields are
+ * preserved verbatim on write (unknown-key carry, format rule §3), so reading
+ * them never risks the data.
+ */
+function quantBlock(v) {
+    const q = v.extra["quant"];
+    return q && typeof q === "object" ? q : {};
+}
+/** `'input'` | `'output'` | `null` (private — the default). */
+export function quantVisibility(v) {
+    const s = String(quantBlock(v)["visibility"] ?? "").trim();
+    return s === "input" || s === "output" ? s : null;
+}
+export function isPublicInput(v) {
+    return quantVisibility(v) === "input";
+}
+export function isPublicOutput(v) {
+    return quantVisibility(v) === "output";
+}
+/** Input bindings declared on this anchor node (empty when none). */
+export function quantInputBindings(v) {
+    const raw = quantBlock(v)["inputBindings"];
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const e of raw) {
+        if (e && typeof e === "object") {
+            const m = e;
+            out.push({
+                child: String(m["child"] ?? ""),
+                target: String(m["target"] ?? ""),
+                expr: String(m["expr"] ?? ""),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * A child output as a qualified reference: bracket form when the label has a
+ * space (`ReworkCycle.[Defect Rate]`), bare otherwise. Mirrors the app's `_ref`
+ * in `subsystem_interface_section.dart`.
+ */
+export function qualifiedRef(qualifier, label) {
+    return `${qualifier}.${label.includes(" ") ? `[${label}]` : label}`;
+}

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from "./engine/engine";
 export * from "./engine/exporters";
 export * from "./engine/analysis";
 export * from "./engine/subsystemLinks";
+export * from "./engine/publicInterface";
 export * from "./engine/loopKey";
 export * from "./engine/loopNote";
 export * from "./engine/noteNaming";

package/dist/index.js

@@ -13,6 +13,7 @@ export * from "./engine/engine";
 export * from "./engine/exporters";
 export * from "./engine/analysis";
 export * from "./engine/subsystemLinks";
+export * from "./engine/publicInterface";
 export * from "./engine/loopKey";
 export * from "./engine/loopNote";
 export * from "./engine/noteNaming";

package/package.json

@@ -1,17 +1,27 @@
 {
   "name": "@neoloopy/cld-canvas",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "author": "neoloopy",
   "license": "MIT",
   "description": "Framework-agnostic CLD canvas renderer + in-memory edit engine (shared by the neoloopy Obsidian plugin and neoloopy.com).",
   "keywords": [
     "cld",
     "causal-loop-diagram",
+    "causal loop diagram",
     "systems-thinking",
+    "systems thinking",
     "system-dynamics",
+    "system dynamics",
     "feedback-loops",
+    "feedback loops",
+    "systems diagram",
+    "systems mapping",
+    "causal map",
+    "loopy",
     "canvas",
     "diagram",
+    "diagram renderer",
+    "cld renderer",
     "visualization",
     "graph",
     "neoloopy"