@neoloopy/cld-canvas 0.1.0

package/dist/engine/subsystemLinks.js

@@ -0,0 +1,55 @@
+/**
+ * Subsystem-link resolution + parent-anchor derivation — the TypeScript mirror
+ * of `core/lib/vault/subsystem_link.dart`. A node's `subsystem` field holds a
+ * relative wikilink `[[../<dir>/System|<alias>]]` pointing DOWN into a child
+ * model; deriving parents is the inverse — scanning other models for nodes that
+ * point at us. Pure: IO is injected via `readNodes` so it stays unit-testable.
+ */
+/** Parse `[[../<dir>/System|<alias>]]` into its folder-basename hint + alias. */
+export function parseSubsystemLink(raw) {
+    const trimmed = (raw ?? "").trim();
+    if (!trimmed)
+        return { dir: null, alias: null };
+    let body = trimmed;
+    if (body.startsWith("[[") && body.endsWith("]]"))
+        body = body.slice(2, -2);
+    const bar = body.indexOf("|");
+    const alias = bar >= 0 ? body.slice(bar + 1).trim() : null;
+    const target = (bar >= 0 ? body.slice(0, bar) : body).trim();
+    const dir = target
+        .split("/")
+        .filter((s) => s && s !== ".." && s.toLowerCase() !== "system")
+        .pop() ?? null;
+    return { dir, alias };
+}
+/** Does a stored subsystem link resolve to `model`? Folder basename, then name. */
+export function linkPointsToModel(raw, model) {
+    const { dir, alias } = parseSubsystemLink(raw);
+    if (dir == null && alias == null)
+        return false;
+    const base = model.folder.split("/").filter(Boolean).pop() ?? model.folder;
+    return ((dir != null && base.toLowerCase() === dir.toLowerCase()) ||
+        (alias != null && model.name.toLowerCase() === alias.toLowerCase()));
+}
+/** Scan `others` for nodes whose `subsystem` link points back at `current`. */
+export async function deriveParentAnchors(current, others, readNodes) {
+    const out = [];
+    for (const m of others) {
+        if (m.folder === current.folder)
+            continue;
+        const nodes = await readNodes(m.folder);
+        for (const n of nodes) {
+            if (!n.subsystem)
+                continue;
+            if (linkPointsToModel(n.subsystem, current)) {
+                out.push({
+                    modelFolder: m.folder,
+                    modelName: m.name,
+                    anchorVarId: n.id,
+                    anchorVarLabel: n.label || n.id,
+                });
+            }
+        }
+    }
+    return out;
+}

package/dist/engine/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * File-format domain types for the local-first vault — a TypeScript port of
+ * `core/lib/vault/vault_model.dart` and the loop types from
+ * `core/lib/graph/loop_graph.dart`.
+ *
+ * These mirror the on-disk shape: a model is a folder of variable notes
+ * (`<id>.md`, YAML frontmatter + Markdown body) plus a `model.json` manifest.
+ * Timestamps are stored as UTC ISO-8601 strings (the codec normalizes on parse,
+ * matching Dart's `DateTime.toUtc().toIso8601String()`; sub-millisecond
+ * precision is not preserved, but timestamps are excluded from the content
+ * signature so this never causes a false external-edit flag).
+ */
+export type VarType = "stock" | "flow" | "auxiliary";
+export declare function varTypeFrom(s: string | null | undefined): VarType;
+export declare function varTypeName(t: VarType): string;
+/** Loop classification. Order matters: matches Dart `enum LoopType`. */
+export declare enum LoopType {
+    reinforcing = 0,
+    balancing = 1
+}
+/**
+ * A directed causal link, stored **outgoing** on the source variable note.
+ * `weight`/`curvature` are cosmetic fidelity carries; `confidence`/`basis` are
+ * evidence carries. All are omitted when unset so plain notes stay clean and
+ * pre-existing vaults round-trip byte-identically.
+ */
+export interface VaultLink {
+    to: string;
+    polarity: "+" | "-";
+    delay: boolean;
+    indirect: boolean;
+    nonlinear: boolean;
+    weight?: number;
+    curvature?: number;
+    confidence?: number;
+    basis?: string;
+}
+/** Clamp a raw confidence to [0,1]; null/NaN -> undefined (unspecified). */
+export declare function normalizeConfidence(v: unknown): number | undefined;
+/** Trim a raw basis; empty -> undefined. */
+export declare function normalizeBasis(v: unknown): string | undefined;
+export declare function linkFromMap(m: Record<string, unknown>): VaultLink;
+/**
+ * Ordered map for YAML emission (only meaningful keys, in the exact order and
+ * with the exact inclusion rules of Dart `VaultLink.toMap`).
+ */
+export declare function linkToMap(l: VaultLink): Array<[string, string | number | boolean]>;
+/** One variable note: structured frontmatter + free Markdown body. */
+export interface VariableFile {
+    id: string;
+    type: VarType;
+    label: string;
+    group?: string;
+    claLayer?: string;
+    shared?: string;
+    x: number;
+    y: number;
+    links: VaultLink[];
+    body: string;
+    /** Unknown frontmatter keys, preserved verbatim on write (format rule §3). */
+    extra: Record<string, unknown>;
+    tags: string[];
+    status?: string;
+    created?: string;
+    modified?: string;
+    rev: number;
+    source?: string;
+    reviewed?: string;
+    reviewedBy?: string;
+    h?: string;
+    subsystem?: string;
+}
+export declare function emptyVariable(id: string, label?: string): VariableFile;
+export interface Viewport {
+    x: number;
+    y: number;
+    zoom: number;
+}
+export declare function viewportFromMap(m: Record<string, unknown> | null | undefined): Viewport;
+/** Model-level metadata (`model.json`). */
+export interface ModelManifest {
+    id: string;
+    name: string;
+    schemaVersion: number;
+    viewport: Viewport;
+    created: string;
+    modified: string;
+    folder?: string;
+    order: number;
+    extra: Record<string, unknown>;
+}
+/** Normalize a timestamp value to UTC ISO; undefined-safe. */
+export declare function toUtcIso(v: unknown): string | undefined;
+export declare function manifestFromJson(j: Record<string, unknown>): ModelManifest;
+export declare function manifestToJson(m: ModelManifest): Record<string, unknown>;
+/** A detected feedback loop: variable ids in cycle order + R/B classification. */
+export declare class DetectedLoop {
+    readonly nodeIds: string[];
+    readonly type: LoopType;
+    constructor(nodeIds: string[], type: LoopType);
+    /** Stable identity = type + the sorted unique node ids (one badge per loop). */
+    get key(): string;
+}

package/dist/engine/types.js

@@ -0,0 +1,155 @@
+/**
+ * File-format domain types for the local-first vault — a TypeScript port of
+ * `core/lib/vault/vault_model.dart` and the loop types from
+ * `core/lib/graph/loop_graph.dart`.
+ *
+ * These mirror the on-disk shape: a model is a folder of variable notes
+ * (`<id>.md`, YAML frontmatter + Markdown body) plus a `model.json` manifest.
+ * Timestamps are stored as UTC ISO-8601 strings (the codec normalizes on parse,
+ * matching Dart's `DateTime.toUtc().toIso8601String()`; sub-millisecond
+ * precision is not preserved, but timestamps are excluded from the content
+ * signature so this never causes a false external-edit flag).
+ */
+export function varTypeFrom(s) {
+    return s === "stock" || s === "flow" ? s : "auxiliary";
+}
+export function varTypeName(t) {
+    return t;
+}
+/** Loop classification. Order matters: matches Dart `enum LoopType`. */
+export var LoopType;
+(function (LoopType) {
+    LoopType[LoopType["reinforcing"] = 0] = "reinforcing";
+    LoopType[LoopType["balancing"] = 1] = "balancing";
+})(LoopType || (LoopType = {}));
+/** Clamp a raw confidence to [0,1]; null/NaN -> undefined (unspecified). */
+export function normalizeConfidence(v) {
+    const d = typeof v === "number" ? v : typeof v === "string" ? Number(v) : NaN;
+    if (d === null || Number.isNaN(d))
+        return undefined;
+    return d < 0 ? 0 : d > 1 ? 1 : d;
+}
+/** Trim a raw basis; empty -> undefined. */
+export function normalizeBasis(v) {
+    if (v === null || v === undefined)
+        return undefined;
+    const s = String(v).trim();
+    return s.length === 0 ? undefined : s;
+}
+export function linkFromMap(m) {
+    const pol = m["polarity"];
+    return {
+        to: String(m["to"]),
+        polarity: pol === "-" || pol === -1 ? "-" : "+",
+        delay: m["delay"] === true,
+        indirect: m["indirect"] === true,
+        nonlinear: m["nonlinear"] === true,
+        weight: typeof m["weight"] === "number" ? Math.trunc(m["weight"]) : undefined,
+        curvature: typeof m["curvature"] === "number" ? (m["curvature"]) : undefined,
+        confidence: normalizeConfidence(m["confidence"]),
+        basis: normalizeBasis(m["basis"]),
+    };
+}
+/**
+ * Ordered map for YAML emission (only meaningful keys, in the exact order and
+ * with the exact inclusion rules of Dart `VaultLink.toMap`).
+ */
+export function linkToMap(l) {
+    const out = [
+        ["to", l.to],
+        ["polarity", l.polarity],
+        ["delay", l.delay],
+        ["indirect", l.indirect],
+        ["nonlinear", l.nonlinear],
+    ];
+    if (l.weight !== undefined && l.weight !== 0)
+        out.push(["weight", l.weight]);
+    if (l.curvature !== undefined)
+        out.push(["curvature", l.curvature]);
+    if (l.confidence !== undefined)
+        out.push(["confidence", l.confidence]);
+    if (l.basis !== undefined && l.basis.length > 0)
+        out.push(["basis", l.basis]);
+    return out;
+}
+export function emptyVariable(id, label = "") {
+    return {
+        id,
+        type: "auxiliary",
+        label,
+        x: 0,
+        y: 0,
+        links: [],
+        body: "",
+        extra: {},
+        tags: [],
+        rev: 0,
+    };
+}
+export function viewportFromMap(m) {
+    const num = (v, d) => (typeof v === "number" ? v : d);
+    return {
+        x: num(m?.["x"], 0),
+        y: num(m?.["y"], 0),
+        zoom: num(m?.["zoom"], 1),
+    };
+}
+const MANIFEST_KNOWN = new Set([
+    "id",
+    "name",
+    "schemaVersion",
+    "viewport",
+    "created",
+    "modified",
+    "folder",
+    "order",
+]);
+/** Normalize a timestamp value to UTC ISO; undefined-safe. */
+export function toUtcIso(v) {
+    if (v === null || v === undefined || v === "")
+        return undefined;
+    const d = new Date(String(v));
+    return Number.isNaN(d.getTime()) ? undefined : d.toISOString();
+}
+export function manifestFromJson(j) {
+    const ts = (v) => toUtcIso(v) ?? new Date().toISOString();
+    const f = typeof j["folder"] === "string" ? (j["folder"]).trim() : undefined;
+    return {
+        id: String(j["id"]),
+        name: String(j["name"] ?? "Untitled"),
+        schemaVersion: typeof j["schemaVersion"] === "number" ? Math.trunc(j["schemaVersion"]) : 1,
+        viewport: viewportFromMap(j["viewport"]),
+        created: ts(j["created"]),
+        modified: ts(j["modified"]),
+        folder: f && f.length > 0 ? f : undefined,
+        order: typeof j["order"] === "number" ? Math.trunc(j["order"]) : 0,
+        extra: Object.fromEntries(Object.entries(j).filter(([k]) => !MANIFEST_KNOWN.has(k))),
+    };
+}
+export function manifestToJson(m) {
+    const out = {
+        id: m.id,
+        name: m.name,
+        schemaVersion: m.schemaVersion,
+        viewport: { x: m.viewport.x, y: m.viewport.y, zoom: m.viewport.zoom },
+        created: m.created,
+        modified: m.modified,
+    };
+    if (m.folder && m.folder.length > 0)
+        out["folder"] = m.folder;
+    if (m.order !== 0)
+        out["order"] = m.order;
+    return { ...out, ...m.extra };
+}
+/** A detected feedback loop: variable ids in cycle order + R/B classification. */
+export class DetectedLoop {
+    constructor(nodeIds, type) {
+        this.nodeIds = nodeIds;
+        this.type = type;
+    }
+    /** Stable identity = type + the sorted unique node ids (one badge per loop). */
+    get key() {
+        const names = [...this.nodeIds].sort();
+        return `${this.type}:${names.join("|")}`;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export * from "./view/painter";
+export * from "./view/sceneCache";
+export * from "./view/camera";
+export * from "./view/theme";
+export * from "./view/geometry";
+export * from "./engine/types";
+export * from "./engine/loopGraph";
+export * from "./engine/layout";
+export * from "./engine/storage";
+export * from "./engine/nativeEngine";
+export * from "./engine/noteCodec";
+export * from "./engine/engine";
+export * from "./engine/exporters";
+export * from "./engine/analysis";
+export * from "./engine/subsystemLinks";
+export * from "./engine/loopKey";
+export * from "./engine/loopNote";
+export * from "./engine/noteNaming";
+export * from "./engine/specHash";

package/dist/index.js

@@ -0,0 +1,19 @@
+export * from "./view/painter";
+export * from "./view/sceneCache";
+export * from "./view/camera";
+export * from "./view/theme";
+export * from "./view/geometry";
+export * from "./engine/types";
+export * from "./engine/loopGraph";
+export * from "./engine/layout";
+export * from "./engine/storage";
+export * from "./engine/nativeEngine";
+export * from "./engine/noteCodec";
+export * from "./engine/engine";
+export * from "./engine/exporters";
+export * from "./engine/analysis";
+export * from "./engine/subsystemLinks";
+export * from "./engine/loopKey";
+export * from "./engine/loopNote";
+export * from "./engine/noteNaming";
+export * from "./engine/specHash";

package/dist/view/camera.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 2D pan/zoom camera. Mirrors the transform model in
+ * `app/lib/features/canvas/canvas_screen.dart`:
+ *   screen = world * scale + translate
+ *   world  = (screen - translate) / scale
+ * Zoom is clamped to [0.08, 3.0]; zoom-to-cursor keeps the focal world point
+ * pinned under the cursor.
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Bounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export declare const MIN_SCALE = 0.08;
+export declare const MAX_SCALE = 3;
+/** Zoom a fresh model opens at when there's nothing to fit (no nodes yet). */
+export declare const DEFAULT_SCALE = 1.2;
+export declare class Camera {
+    scale: number;
+    tx: number;
+    ty: number;
+    toScreen(wx: number, wy: number): Point;
+    toWorld(sx: number, sy: number): Point;
+    panBy(dxScreen: number, dyScreen: number): void;
+    /** Zoom by `factor` keeping the world point under (sx,sy) fixed on screen. */
+    zoomAt(sx: number, sy: number, factor: number): void;
+    setScaleAt(sx: number, sy: number, scale: number): void;
+    /** Frame `bounds` (world) within a viewport of `vw`×`vh` screen px. */
+    fit(bounds: Bounds, vw: number, vh: number, pad?: number): void;
+    /** Pan (no zoom) so world point (wx,wy) sits at the center of a vw×vh view. */
+    centerOn(wx: number, wy: number, vw: number, vh: number): void;
+    /** Restore the default zoom and center world origin in a vw×vh viewport. Used
+     *  when opening a model with no saved viewport so an empty model can't inherit
+     *  the previous view's scale (which could be tiny → first node invisibly small). */
+    reset(vw: number, vh: number): void;
+}
+export declare function clamp(v: number, lo: number, hi: number): number;

package/dist/view/camera.js

@@ -0,0 +1,75 @@
+/**
+ * 2D pan/zoom camera. Mirrors the transform model in
+ * `app/lib/features/canvas/canvas_screen.dart`:
+ *   screen = world * scale + translate
+ *   world  = (screen - translate) / scale
+ * Zoom is clamped to [0.08, 3.0]; zoom-to-cursor keeps the focal world point
+ * pinned under the cursor.
+ */
+export const MIN_SCALE = 0.08;
+export const MAX_SCALE = 3.0;
+/** Zoom a fresh model opens at when there's nothing to fit (no nodes yet). */
+export const DEFAULT_SCALE = 1.2;
+export class Camera {
+    constructor() {
+        this.scale = DEFAULT_SCALE;
+        this.tx = 40;
+        this.ty = 120;
+    }
+    toScreen(wx, wy) {
+        return { x: wx * this.scale + this.tx, y: wy * this.scale + this.ty };
+    }
+    toWorld(sx, sy) {
+        return { x: (sx - this.tx) / this.scale, y: (sy - this.ty) / this.scale };
+    }
+    panBy(dxScreen, dyScreen) {
+        this.tx += dxScreen;
+        this.ty += dyScreen;
+    }
+    /** Zoom by `factor` keeping the world point under (sx,sy) fixed on screen. */
+    zoomAt(sx, sy, factor) {
+        const before = this.toWorld(sx, sy);
+        this.scale = clamp(this.scale * factor, MIN_SCALE, MAX_SCALE);
+        const after = this.toWorld(sx, sy);
+        this.tx += (after.x - before.x) * this.scale;
+        this.ty += (after.y - before.y) * this.scale;
+    }
+    setScaleAt(sx, sy, scale) {
+        const before = this.toWorld(sx, sy);
+        this.scale = clamp(scale, MIN_SCALE, MAX_SCALE);
+        const after = this.toWorld(sx, sy);
+        this.tx += (after.x - before.x) * this.scale;
+        this.ty += (after.y - before.y) * this.scale;
+    }
+    /** Frame `bounds` (world) within a viewport of `vw`×`vh` screen px. */
+    fit(bounds, vw, vh, pad = 120) {
+        const w = Math.max(1, bounds.maxX - bounds.minX);
+        const h = Math.max(1, bounds.maxY - bounds.minY);
+        // Cap padding to a fraction of the viewport so a fixed margin can't exceed a
+        // small (mobile) viewport — a 120px pad on a ~390px phone would leave a
+        // negative content box and pin the camera at MIN_SCALE (nodes invisibly tiny).
+        const p = Math.min(pad, vw * 0.15, vh * 0.15);
+        const sx = (vw - p * 2) / w;
+        const sy = (vh - p * 2) / h;
+        this.scale = clamp(Math.min(sx, sy), MIN_SCALE, MAX_SCALE);
+        const cx = (bounds.minX + bounds.maxX) / 2;
+        const cy = (bounds.minY + bounds.maxY) / 2;
+        this.tx = vw / 2 - cx * this.scale;
+        this.ty = vh / 2 - cy * this.scale;
+    }
+    /** Pan (no zoom) so world point (wx,wy) sits at the center of a vw×vh view. */
+    centerOn(wx, wy, vw, vh) {
+        this.tx = vw / 2 - wx * this.scale;
+        this.ty = vh / 2 - wy * this.scale;
+    }
+    /** Restore the default zoom and center world origin in a vw×vh viewport. Used
+     *  when opening a model with no saved viewport so an empty model can't inherit
+     *  the previous view's scale (which could be tiny → first node invisibly small). */
+    reset(vw, vh) {
+        this.scale = DEFAULT_SCALE;
+        this.centerOn(0, 0, vw, vh);
+    }
+}
+export function clamp(v, lo, hi) {
+    return v < lo ? lo : v > hi ? hi : v;
+}

package/dist/view/geometry.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Canvas geometry — node boxes, curved-edge construction, decoration anchors,
+ * loop-badge placement, and hit-testing. A faithful port of the geometry in
+ * `app/lib/painters/graph_painter.dart`: edges are TRUE CIRCULAR arcs through
+ * start → apex → end (constant curvature, so dragging an edge out bulges it into
+ * a round arc, not a pinched parabola), trimmed to the node rims. Pure module —
+ * no `obsidian`, no canvas — so the math is unit-testable.
+ */
+import { DetectedLoop, VariableFile, VaultLink } from "../engine/types";
+import { Bounds, Point } from "./camera";
+export interface NodeBox {
+    id: string;
+    cx: number;
+    cy: number;
+    w: number;
+    h: number;
+    type: string;
+}
+export interface EdgeRef {
+    id: string;
+    source: string;
+    target: string;
+    link: VaultLink;
+}
+export interface EdgeGeom extends EdgeRef {
+    points: Point[];
+    mid: Point;
+    midAngle: number;
+    delay: Point;
+    delayAngle: number;
+    nl: Point;
+    nlAngle: number;
+    arrowTip: Point;
+    arrowAngle: number;
+}
+/**
+ * Node (x,y) is the box center, matching the Dart painter + autoLayout.
+ *
+ * The app's painter (`NodeBox.sizeFor`) sizes each box to the *measured* label
+ * width plus padding — `max(60, textWidth + (flow ? 40 : 36))`, height 40 for a
+ * stock else 34. Pass `measure` (a canvas `measureText` at the label font) to
+ * match it exactly; without one (tests/headless) fall back to the same
+ * character-count estimate `layout.boxSize`/`autoLayout` use, so positions stay
+ * deterministic.
+ */
+export declare function buildNodeBoxes(nodes: VariableFile[], measure?: (label: string) => number): Map<string, NodeBox>;
+export declare function collectEdges(nodes: VariableFile[]): EdgeRef[];
+/**
+ * @param bowCache Per-edge frozen bow signs (keyed by edge id). Lone edges pick
+ *   a bow side from the graph centroid **once** and reuse it; without this, a
+ *   node drag moves the centroid and can flip an unrelated edge to the far side.
+ *   Pass a stable Map (cleared per model) to get app-faithful, jitter-free arcs.
+ */
+export declare function buildEdgeGeoms(edges: EdgeRef[], boxes: Map<string, NodeBox>, bowCache?: Map<string, number>): EdgeGeom[];
+/**
+ * Loop-badge centers — centroid of member nodes, then light overlap spread.
+ * `overrides` (loop.key → world point) pins badges the user has dragged: a pinned
+ * badge sits exactly where it was dropped and does not move during relaxation;
+ * unpinned badges relax around it. Mirrors the app's `loopBadgeOverrides`
+ * (session-only, keyed by loop key — not persisted to the vault).
+ */
+export declare function computeBadges(loops: DetectedLoop[], boxes: Map<string, NodeBox>, overrides?: Map<string, Point>): Map<string, Point>;
+/**
+ * Directed edge ids (`source__target`, matching `collectEdges`) that close a
+ * detected loop's cycle. `nodeIds` is the open path, so the last node wraps back
+ * to the first. Used to highlight the loop when its badge is selected.
+ */
+export declare function loopEdgeIds(loop: DetectedLoop): Set<string>;
+export declare function hitNode(boxes: Map<string, NodeBox>, p: Point): string | null;
+export declare function hitEdge(geoms: EdgeGeom[], p: Point, scale: number): string | null;
+/**
+ * Generous grab zone for an already-selected edge, mirroring the native app's
+ * `_nearSelectedEdge`: within 26/scale of the midpoint handle, OR within
+ * 22/scale of the curve. Bowing uses this (not the tight 14/scale `hitEdge`
+ * select zone) so "select then drag to bow" is reliable instead of needing a
+ * pixel-perfect second press on the line.
+ */
+export declare function nearSelectedEdge(g: EdgeGeom, p: Point, scale: number): boolean;
+export declare function hitBadge(badges: Map<string, Point>, p: Point, scale: number): string | null;
+/** True if `p` is in the connect-ring band just outside a node's rim. */
+export declare function inConnectBand(box: NodeBox, p: Point, tol: number, gap?: number): boolean;
+export declare function distToSegment(p: Point, a: Point, b: Point): number;
+export declare function nodeBounds(boxes: Map<string, NodeBox>): Bounds;