@toyz/loom 0.9.0 → 0.11.0

package/dist/trace.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Loom — Traced Template Projection
+ *
+ * Phase 1: Dependency tracking for update().
+ *   - Traces which Reactive instances are read during update()
+ *   - On subsequent scheduleUpdate() calls, checks if any tracked
+ *     dependency actually changed before running update()+morph().
+ *   - Eliminates unnecessary renders when unrelated state changes.
+ *
+ * Phase 2: Fine-grained DOM patching via Closure Bindings.
+ *   - During traced update(), function children/props are executed
+ *     within a sub-trace to capture their specific dependencies.
+ *   - A Binding is created linking those dependencies to the DOM node.
+ *   - On subsequent updates, if all dirty deps have bindings,
+ *     the element fast-patches those DOM nodes directly.
+ */
+import type { Reactive } from "./store/reactive";
+/** A single Reactive→DOM binding created during traced update() */
+export interface Binding {
+    /** The set of reactives that trigger this binding */
+    reactives: Set<Reactive<any>>;
+    /** The DOM node to patch */
+    target: Node | Element;
+    /** The closure that updates the DOM (re-evaluates the binding) */
+    patcher: () => void;
+}
+/** Dependency set: the Reactives that were read during a single update() call */
+export interface TraceDeps {
+    /** Set of Reactives read during the traced update() */
+    deps: Set<Reactive<any>>;
+    /** Snapshot of each dependency's version at trace time */
+    versions: Map<Reactive<any>, number>;
+    /** Phase 2 — Reactive→DOM bindings for fast-patching */
+    bindings: Map<Reactive<any>, Binding[]>;
+}
+/**
+ * Begin tracing. Called before update().
+ * All Reactive.value reads will be recorded.
+ */
+export declare function startTrace(): void;
+/**
+ * End tracing and return the dependency set + version snapshots + bindings.
+ * Called after update() completes.
+ */
+export declare function endTrace(): TraceDeps;
+/**
+ * Check if tracing is currently active.
+ */
+export declare function isTracing(): boolean;
+/**
+ * Record a Reactive read. Called from Reactive.value getter
+ * when a trace is active.
+ */
+export declare function recordRead(reactive: Reactive<any>): void;
+/**
+ * Start a sub-trace for a closure binding.
+ * Pushes the current activeDeps to the stack and starts a fresh set.
+ */
+export declare function startSubTrace(): void;
+/**
+ * End a sub-trace and return the captured dependencies.
+ * Merges the captured deps back into the parent trace (so the component remains dirty).
+ */
+export declare function endSubTrace(): Set<Reactive<any>>;
+/**
+ * Register a Reactive→DOM binding.
+ * Called by the JSX runtime when a closure binding is detected.
+ */
+export declare function addBinding(reactives: Set<Reactive<any>>, target: Node | Element, patcher: () => void): void;
+/**
+ * Check if any dependency in the trace has changed since the snapshot.
+ * Returns true if at least one dependency's version differs.
+ * Returns true if trace is null (first render, always dirty).
+ */
+export declare function hasDirtyDeps(trace: TraceDeps | null): boolean;
+/**
+ * Check if all dirty dependencies have bindings — if so, we can
+ * fast-patch the DOM without running update()+morph().
+ * Returns false for null trace or if any dirty dep has no binding.
+ */
+export declare function canFastPatch(trace: TraceDeps | null): boolean;
+/**
+ * Apply all dirty bindings.
+ * Only patches bindings for deps that actually changed.
+ * Uses a Set to deduplicate patchers (one binding might depend on multiple changed reactives).
+ */
+export declare function applyBindings(trace: TraceDeps): void;
+/**
+ * Update the snapshot versions to current.
+ * Called after a successful update()+morph() or fast-patch.
+ */
+export declare function refreshSnapshots(trace: TraceDeps): void;
+//# sourceMappingURL=trace.d.ts.map

package/dist/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAIjD,mEAAmE;AACnE,MAAM,WAAW,OAAO;IACtB,qDAAqD;IACrD,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,4BAA4B;IAC5B,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IACvB,kEAAkE;IAClE,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,uDAAuD;IACvD,IAAI,EAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IACrC,wDAAwD;IACxD,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;CACzC;AAkBD;;;GAGG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAIjC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,SAAS,CAepC;AAED;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAEnC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,CAIxD;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAKpC;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAYhD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAC7B,MAAM,EAAE,IAAI,GAAG,OAAO,EACtB,OAAO,EAAE,MAAM,IAAI,GAClB,IAAI,CAcN;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAM7D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAW7D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAkBpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAIvD"}

package/dist/trace.js

@@ -0,0 +1,176 @@
+/**
+ * Loom — Traced Template Projection
+ *
+ * Phase 1: Dependency tracking for update().
+ *   - Traces which Reactive instances are read during update()
+ *   - On subsequent scheduleUpdate() calls, checks if any tracked
+ *     dependency actually changed before running update()+morph().
+ *   - Eliminates unnecessary renders when unrelated state changes.
+ *
+ * Phase 2: Fine-grained DOM patching via Closure Bindings.
+ *   - During traced update(), function children/props are executed
+ *     within a sub-trace to capture their specific dependencies.
+ *   - A Binding is created linking those dependencies to the DOM node.
+ *   - On subsequent updates, if all dirty deps have bindings,
+ *     the element fast-patches those DOM nodes directly.
+ */
+// ── Tracer state (module-scoped) ──
+/**
+ * The current set of dependencies being tracked.
+ * When nested tracing occurs, the parent set is pushed to `traceStack`.
+ */
+let activeDeps = null;
+/** Stack of dependency sets for nested tracing (e.g. inside a binding closure) */
+let traceStack = [];
+/** Active bindings being collected during a traced update() */
+let activeBindings = null;
+// ── Public API ──
+/**
+ * Begin tracing. Called before update().
+ * All Reactive.value reads will be recorded.
+ */
+export function startTrace() {
+    activeDeps = new Set();
+    traceStack = [];
+    activeBindings = new Map();
+}
+/**
+ * End tracing and return the dependency set + version snapshots + bindings.
+ * Called after update() completes.
+ */
+export function endTrace() {
+    const deps = activeDeps ?? new Set();
+    activeDeps = null;
+    // Snapshot current versions for dirty checking
+    const versions = new Map();
+    for (const r of deps) {
+        versions.set(r, r.peekVersion());
+    }
+    const bindings = activeBindings ?? new Map();
+    activeBindings = null;
+    traceStack = [];
+    return { deps, versions, bindings };
+}
+/**
+ * Check if tracing is currently active.
+ */
+export function isTracing() {
+    return activeDeps !== null;
+}
+/**
+ * Record a Reactive read. Called from Reactive.value getter
+ * when a trace is active.
+ */
+export function recordRead(reactive) {
+    if (activeDeps) {
+        activeDeps.add(reactive);
+    }
+}
+/**
+ * Start a sub-trace for a closure binding.
+ * Pushes the current activeDeps to the stack and starts a fresh set.
+ */
+export function startSubTrace() {
+    if (activeDeps) {
+        traceStack.push(activeDeps);
+    }
+    activeDeps = new Set();
+}
+/**
+ * End a sub-trace and return the captured dependencies.
+ * Merges the captured deps back into the parent trace (so the component remains dirty).
+ */
+export function endSubTrace() {
+    const captured = activeDeps ?? new Set();
+    activeDeps = traceStack.pop() || null;
+    // Merge sub-trace deps into parent trace
+    if (activeDeps) {
+        for (const r of captured) {
+            activeDeps.add(r);
+        }
+    }
+    return captured;
+}
+/**
+ * Register a Reactive→DOM binding.
+ * Called by the JSX runtime when a closure binding is detected.
+ */
+export function addBinding(reactives, target, patcher) {
+    if (!activeBindings)
+        return;
+    const binding = { reactives, target, patcher };
+    // Register this binding for every reactive it depends on
+    for (const r of reactives) {
+        let list = activeBindings.get(r);
+        if (!list) {
+            list = [];
+            activeBindings.set(r, list);
+        }
+        list.push(binding);
+    }
+}
+/**
+ * Check if any dependency in the trace has changed since the snapshot.
+ * Returns true if at least one dependency's version differs.
+ * Returns true if trace is null (first render, always dirty).
+ */
+export function hasDirtyDeps(trace) {
+    if (!trace)
+        return true;
+    for (const [r, ver] of trace.versions) {
+        if (r.peekVersion() !== ver)
+            return true;
+    }
+    return false;
+}
+/**
+ * Check if all dirty dependencies have bindings — if so, we can
+ * fast-patch the DOM without running update()+morph().
+ * Returns false for null trace or if any dirty dep has no binding.
+ */
+export function canFastPatch(trace) {
+    if (!trace)
+        return false;
+    if (trace.bindings.size === 0)
+        return false;
+    for (const [r, ver] of trace.versions) {
+        if (r.peekVersion() !== ver) {
+            // This dep is dirty — does it have bindings?
+            if (!trace.bindings.has(r))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Apply all dirty bindings.
+ * Only patches bindings for deps that actually changed.
+ * Uses a Set to deduplicate patchers (one binding might depend on multiple changed reactives).
+ */
+export function applyBindings(trace) {
+    const patchersToRun = new Set();
+    for (const [r, ver] of trace.versions) {
+        if (r.peekVersion() !== ver) {
+            const bindings = trace.bindings.get(r);
+            if (bindings) {
+                for (const b of bindings) {
+                    patchersToRun.add(b.patcher);
+                }
+            }
+        }
+    }
+    // Execute unique patchers
+    for (const patcher of patchersToRun) {
+        patcher();
+    }
+}
+/**
+ * Update the snapshot versions to current.
+ * Called after a successful update()+morph() or fast-patch.
+ */
+export function refreshSnapshots(trace) {
+    for (const r of trace.deps) {
+        trace.versions.set(r, r.peekVersion());
+    }
+}
+//# sourceMappingURL=trace.js.map

package/dist/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../src/trace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toyz/loom",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Decorator-driven web component framework with reactive state, DOM morphing, DI, and JSX",
   "license": "MIT",