@neoloopy/cld-canvas 0.1.3 → 0.1.4

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,6 +467,10 @@ 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";
 

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.3",
+  "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"