@stephen-netu/design-system 0.1.0 → 0.2.0

package/dist/n4-adaptive-manifold/orchestrator.d.ts

@@ -0,0 +1,61 @@
+import type { AlgorithmProvider, LayoutAlgorithm, ManifoldSnapshot, LayoutPreferences, ClassificationResult, LayoutSuggestion, NodeLayout } from './types.js';
+export interface OrchestratorState {
+    /** Currently active layout algorithm. */
+    activeAlgorithm: LayoutAlgorithm;
+    /** Current node positions (interpolated during transition). */
+    positions: Map<string, NodeLayout>;
+    /** Current BFS order for edge reveal. */
+    bfsOrder: ReadonlyArray<string>;
+    /** Whether a transition is in progress. */
+    transitioning: boolean;
+    /** Last classification result. */
+    lastClassification: ClassificationResult | null;
+    /** Current suggestion (null if none, or dismissed/pinned). */
+    suggestion: LayoutSuggestion | null;
+}
+export type OrchestratorListener = (state: OrchestratorState) => void;
+export declare class LayoutOrchestrator {
+    private providers;
+    private prefs;
+    private animator;
+    private listeners;
+    private _activeAlgorithm;
+    private _positions;
+    private _bfsOrder;
+    private _transitioning;
+    private _lastClassification;
+    private _suggestion;
+    private _abortTransition;
+    private _debounceTimer;
+    private _pendingSnapshot;
+    private _pendingWidth;
+    private _pendingHeight;
+    private _stabilityAlgorithm;
+    private _stabilityCount;
+    constructor(providers: AlgorithmProvider[], prefs?: LayoutPreferences);
+    get state(): OrchestratorState;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(listener: OrchestratorListener): () => void;
+    private notify;
+    /**
+     * Request layout for the given snapshot. Debounced to 500ms.
+     * If currently transitioning (AM-Morph), the request is queued.
+     */
+    requestLayout(snapshot: ManifoldSnapshot, canvasWidth: number, canvasHeight: number): void;
+    private executeLayout;
+    /** 3-tick stability: only suggest after classifier recommends the same alternative 3 times. */
+    private updateSuggestion;
+    /** Accept a layout suggestion — switch to suggested algorithm. */
+    acceptSuggestion(): void;
+    /** Dismiss a layout suggestion — keep current algorithm. */
+    dismissSuggestion(): void;
+    /** Pin the current layout (disable auto-classification). */
+    pinLayout(): void;
+    /** Unpin — re-enable auto-classification. */
+    unpinLayout(): void;
+    /** Update preferences (e.g. user toggles animation). */
+    setPreferences(prefs: Partial<LayoutPreferences>): void;
+    /** Clean up. */
+    destroy(): void;
+}
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/n4-adaptive-manifold/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/n4-adaptive-manifold/orchestrator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACX,MAAM,YAAY,CAAC;AAQpB,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,eAAe,EAAE,eAAe,CAAC;IACjC,+DAA+D;IAC/D,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,yCAAyC;IACzC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC,2CAA2C;IAC3C,aAAa,EAAE,OAAO,CAAC;IACvB,kCAAkC;IAClC,kBAAkB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAChD,8DAA8D;IAC9D,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEtE,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,SAAS,CAA0C;IAC3D,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,SAAS,CAA8B;IAG/C,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,UAAU,CAAsC;IACxD,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,mBAAmB,CAAqC;IAChE,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,gBAAgB,CAA6B;IAGrD,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAK;IAG3B,OAAO,CAAC,mBAAmB,CAAgC;IAC3D,OAAO,CAAC,eAAe,CAAK;gBAG1B,SAAS,EAAE,iBAAiB,EAAE,EAC9B,KAAK,GAAE,iBAA8C;IAUvD,IAAI,KAAK,IAAI,iBAAiB,CAS7B;IAED,gEAAgE;IAChE,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAOrD,OAAO,CAAC,MAAM;IAKd;;;OAGG;IACH,aAAa,CACX,QAAQ,EAAE,gBAAgB,EAC1B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI;YAyBO,aAAa;IAqF3B,+FAA+F;IAC/F,OAAO,CAAC,gBAAgB;IAkCxB,kEAAkE;IAClE,gBAAgB,IAAI,IAAI;IAcxB,4DAA4D;IAC5D,iBAAiB,IAAI,IAAI;IAQzB,4DAA4D;IAC5D,SAAS,IAAI,IAAI;IAMjB,6CAA6C;IAC7C,WAAW,IAAI,IAAI;IAMnB,wDAAwD;IACxD,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI;IAIvD,gBAAgB;IAChB,OAAO,IAAI,IAAI;CAKhB"}

package/dist/n4-adaptive-manifold/orchestrator.js

@@ -0,0 +1,231 @@
+// N4 LayoutOrchestrator — Coordinates algorithm providers, manages transitions
+// Owns the current layout state and drives the TransitionAnimator.
+// Includes 500ms debounce and 3-tick stability before suggesting.
+import { DEFAULT_LAYOUT_PREFERENCES } from './types.js';
+import { classifyTopology, STABILITY_TICKS } from './classifier.js';
+import { TransitionAnimator, EASING_FUNCTIONS } from './transition.js';
+/** Debounce interval matching REFLEX tick cadence. */
+const CLASSIFY_DEBOUNCE_MS = 500;
+export class LayoutOrchestrator {
+    providers;
+    prefs;
+    animator;
+    listeners = [];
+    // Current state
+    _activeAlgorithm = 'manifold';
+    _positions = new Map();
+    _bfsOrder = [];
+    _transitioning = false;
+    _lastClassification = null;
+    _suggestion = null;
+    _abortTransition = null;
+    // Debounce state
+    _debounceTimer = null;
+    _pendingSnapshot = null;
+    _pendingWidth = 0;
+    _pendingHeight = 0;
+    // 3-tick stability counter
+    _stabilityAlgorithm = null;
+    _stabilityCount = 0;
+    constructor(providers, prefs = DEFAULT_LAYOUT_PREFERENCES) {
+        this.providers = new Map();
+        for (const p of providers) {
+            this.providers.set(p.algorithm, p);
+        }
+        this.prefs = prefs;
+        this.animator = new TransitionAnimator();
+    }
+    get state() {
+        return {
+            activeAlgorithm: this._activeAlgorithm,
+            positions: this._positions,
+            bfsOrder: this._bfsOrder,
+            transitioning: this._transitioning,
+            lastClassification: this._lastClassification,
+            suggestion: this._suggestion,
+        };
+    }
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.push(listener);
+        return () => {
+            this.listeners = this.listeners.filter(l => l !== listener);
+        };
+    }
+    notify() {
+        const state = this.state;
+        for (const l of this.listeners)
+            l(state);
+    }
+    /**
+     * Request layout for the given snapshot. Debounced to 500ms.
+     * If currently transitioning (AM-Morph), the request is queued.
+     */
+    requestLayout(snapshot, canvasWidth, canvasHeight) {
+        this._pendingSnapshot = snapshot;
+        this._pendingWidth = canvasWidth;
+        this._pendingHeight = canvasHeight;
+        // If transitioning, don't schedule — will pick up after morph completes
+        if (this._transitioning)
+            return;
+        // Debounce
+        if (this._debounceTimer !== null) {
+            clearTimeout(this._debounceTimer);
+        }
+        // First layout (no positions yet) runs immediately
+        if (this._positions.size === 0) {
+            this.executeLayout();
+            return;
+        }
+        this._debounceTimer = setTimeout(() => {
+            this._debounceTimer = null;
+            this.executeLayout();
+        }, CLASSIFY_DEBOUNCE_MS);
+    }
+    async executeLayout() {
+        const snapshot = this._pendingSnapshot;
+        if (!snapshot || snapshot.nodes.length === 0)
+            return;
+        const canvasWidth = this._pendingWidth;
+        const canvasHeight = this._pendingHeight;
+        // Abort any in-flight transition
+        this._abortTransition?.();
+        // Classify
+        const classification = classifyTopology(snapshot);
+        this._lastClassification = classification;
+        // Determine target algorithm
+        let targetAlgorithm;
+        if (this.prefs.lockedAlgorithm !== null) {
+            targetAlgorithm = this.prefs.lockedAlgorithm;
+        }
+        else {
+            targetAlgorithm = classification.recommended;
+        }
+        // Update suggestion with 3-tick stability
+        this.updateSuggestion(classification, targetAlgorithm);
+        const provider = this.providers.get(targetAlgorithm);
+        if (!provider)
+            return;
+        // Compute target layout
+        const targetLayout = await provider.layout(snapshot, canvasWidth, canvasHeight);
+        // If no current positions or animation disabled, apply immediately
+        if (this._positions.size === 0 || !this.prefs.animate) {
+            this._activeAlgorithm = targetAlgorithm;
+            this._positions = targetLayout.positions;
+            this._bfsOrder = targetLayout.bfsOrder;
+            this._transitioning = false;
+            this.notify();
+            return;
+        }
+        // AM-Morph: animate from current → target
+        this._transitioning = true;
+        this._activeAlgorithm = targetAlgorithm;
+        this.notify();
+        const easing = EASING_FUNCTIONS[this.prefs.easing] ?? EASING_FUNCTIONS.easeInOutCubic;
+        await new Promise((resolve) => {
+            let cancelled = false;
+            this._abortTransition = () => { cancelled = true; };
+            this.animator.animate(this._positions, targetLayout.positions, this.prefs.morphDurationMs, easing, (frame) => {
+                if (cancelled)
+                    return;
+                this._positions = frame.positions;
+                this.notify();
+            }, () => {
+                this._abortTransition = null;
+                if (cancelled) {
+                    resolve();
+                    return;
+                }
+                this._positions = targetLayout.positions;
+                this._bfsOrder = targetLayout.bfsOrder;
+                this._transitioning = false;
+                this.notify();
+                // Check if a new snapshot arrived during the morph.
+                // Route through requestLayout (debounce) rather than calling executeLayout()
+                // directly — prevents unbounded promise chaining under fast data arrival.
+                if (this._pendingSnapshot !== snapshot) {
+                    this.requestLayout(this._pendingSnapshot, this._pendingWidth, this._pendingHeight);
+                }
+                resolve();
+            });
+        });
+    }
+    /** 3-tick stability: only suggest after classifier recommends the same alternative 3 times. */
+    updateSuggestion(classification, currentTarget) {
+        if (this.prefs.lockedAlgorithm !== null) {
+            // User has pinned — no suggestions
+            this._suggestion = null;
+            return;
+        }
+        if (classification.recommended === currentTarget) {
+            // Classifier agrees with current — clear stability counter
+            this._stabilityAlgorithm = null;
+            this._stabilityCount = 0;
+            this._suggestion = null;
+            return;
+        }
+        // Classifier disagrees — track stability
+        if (this._stabilityAlgorithm === classification.recommended) {
+            this._stabilityCount++;
+        }
+        else {
+            this._stabilityAlgorithm = classification.recommended;
+            this._stabilityCount = 1;
+        }
+        if (this._stabilityCount >= STABILITY_TICKS) {
+            this._suggestion = {
+                algorithm: classification.recommended,
+                confidence: classification.confidence,
+                reason: classification.reason,
+                dismissed: false,
+                pinned: false,
+            };
+        }
+    }
+    /** Accept a layout suggestion — switch to suggested algorithm. */
+    acceptSuggestion() {
+        if (!this._suggestion)
+            return;
+        this._activeAlgorithm = this._suggestion.algorithm;
+        this._suggestion = null;
+        this._stabilityCount = 0;
+        if (this._pendingSnapshot) {
+            // Set transitioning before executeLayout so requestLayout calls that arrive
+            // before executeLayout's first await are queued rather than double-fired.
+            this._transitioning = true;
+            this.setPreferences({ lockedAlgorithm: this._activeAlgorithm });
+            this.executeLayout();
+        }
+    }
+    /** Dismiss a layout suggestion — keep current algorithm. */
+    dismissSuggestion() {
+        if (this._suggestion) {
+            this._suggestion = { ...this._suggestion, dismissed: true };
+        }
+        this._stabilityCount = 0;
+        this.notify();
+    }
+    /** Pin the current layout (disable auto-classification). */
+    pinLayout() {
+        this.prefs.lockedAlgorithm = this._activeAlgorithm;
+        this._suggestion = null;
+        this.notify();
+    }
+    /** Unpin — re-enable auto-classification. */
+    unpinLayout() {
+        this.prefs.lockedAlgorithm = null;
+        this._stabilityCount = 0;
+        this.notify();
+    }
+    /** Update preferences (e.g. user toggles animation). */
+    setPreferences(prefs) {
+        this.prefs = { ...this.prefs, ...prefs };
+    }
+    /** Clean up. */
+    destroy() {
+        this._abortTransition?.();
+        if (this._debounceTimer !== null)
+            clearTimeout(this._debounceTimer);
+        this.listeners = [];
+    }
+}

package/dist/n4-adaptive-manifold/phase-theme.d.ts

@@ -0,0 +1,9 @@
+import type { PhaseTheme } from './types.js';
+/**
+ * Resolve PhaseTheme from CSS custom properties on a container element.
+ * Re-call on data-theme or class mutation.
+ */
+export declare function resolvePhaseTheme(el: HTMLElement): PhaseTheme;
+/** Fallback theme if CSS tokens are not set */
+export declare const DEFAULT_PHASE_THEME: PhaseTheme;
+//# sourceMappingURL=phase-theme.d.ts.map

package/dist/n4-adaptive-manifold/phase-theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-theme.d.ts","sourceRoot":"","sources":["../../src/n4-adaptive-manifold/phase-theme.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAqB,MAAM,YAAY,CAAC;AAoBhE;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,GAAG,UAAU,CAO7D;AAED,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB,EAAE,UAyDjC,CAAC"}

package/dist/n4-adaptive-manifold/phase-theme.js

@@ -0,0 +1,82 @@
+const PHASES = ['seed', 'sprout', 'go', 'consult', 'weed', 'freeze', 'compost', 'prune'];
+function resolvePhaseParams(style, phase) {
+    const get = (prop) => style.getPropertyValue(`--n4-phase-${phase}-${prop}`).trim();
+    return {
+        background: get('background') || '#1a1a1a',
+        brightness: parseFloat(get('brightness')) || 0.5,
+        indicatorIntensity: parseFloat(get('indicator-intensity')) || 0.5,
+        ambientPulseSpeed: parseFloat(get('pulse-speed')) || 3,
+        saturation: parseFloat(get('saturation')) || 0.8,
+    };
+}
+/**
+ * Resolve PhaseTheme from CSS custom properties on a container element.
+ * Re-call on data-theme or class mutation.
+ */
+export function resolvePhaseTheme(el) {
+    const style = getComputedStyle(el);
+    const theme = {};
+    for (const phase of PHASES) {
+        theme[phase] = resolvePhaseParams(style, phase);
+    }
+    return theme;
+}
+/** Fallback theme if CSS tokens are not set */
+export const DEFAULT_PHASE_THEME = {
+    seed: {
+        background: '#1a1a1a',
+        brightness: 0.4,
+        indicatorIntensity: 0.3,
+        ambientPulseSpeed: 4,
+        saturation: 0.6,
+    },
+    sprout: {
+        background: '#1a1c1a',
+        brightness: 0.7,
+        indicatorIntensity: 0.7,
+        ambientPulseSpeed: 2.5,
+        saturation: 0.85,
+    },
+    go: {
+        background: '#1c1a18',
+        brightness: 1.0,
+        indicatorIntensity: 1.0,
+        ambientPulseSpeed: 1.5,
+        saturation: 1.0,
+    },
+    consult: {
+        background: '#1b1a1c',
+        brightness: 0.85,
+        indicatorIntensity: 0.85,
+        ambientPulseSpeed: 2.0,
+        saturation: 0.9,
+    },
+    weed: {
+        background: '#1c1b18',
+        brightness: 0.65,
+        indicatorIntensity: 0.6,
+        ambientPulseSpeed: 2.5,
+        saturation: 0.75,
+    },
+    freeze: {
+        background: '#1a1a1e',
+        brightness: 0.2,
+        indicatorIntensity: 0.1,
+        ambientPulseSpeed: 8,
+        saturation: 0.2,
+    },
+    compost: {
+        background: '#1a1a1a',
+        brightness: 0.25,
+        indicatorIntensity: 0.15,
+        ambientPulseSpeed: 6,
+        saturation: 0.3,
+    },
+    prune: {
+        background: '#1c1a1a',
+        brightness: 0.2,
+        indicatorIntensity: 0.1,
+        ambientPulseSpeed: 8,
+        saturation: 0.2,
+    },
+};

package/dist/n4-adaptive-manifold/pinnacle-events.d.ts

@@ -0,0 +1,34 @@
+import type { PinnacleEvent, NodeIndicatorState } from './types.js';
+/**
+ * Tier A inference layer: derives PinnacleEvents from sigchain snapshot deltas.
+ *
+ * When tier B (direct Garden telemetry) arrives, this class is replaced.
+ * The PinnacleEvent shape is the same — canvas code doesn't change.
+ */
+export declare class PinnacleEventInferrer {
+    private agents;
+    /**
+     * Process a batch of sigchain-derived changes and return PinnacleEvents.
+     * Called by PinnacleView on each poller tick.
+     */
+    inferFromSnapshot(nodes: ReadonlyArray<{
+        id: string;
+        kind: string;
+        metadata: Record<string, unknown>;
+    }>, _edges: ReadonlyArray<{
+        source: string;
+        target: string;
+        relation: string;
+    }>, sequence: number): PinnacleEvent[];
+    /**
+     * Convert persistent agent tracker state into NodeIndicatorState map for the canvas.
+     *
+     * Reads from this.agents (updated by inferFromSnapshot), NOT from emitted events.
+     * Events only fire on state changes — reading from the tracker ensures a stable
+     * 'think' pulse persists across ticks where nothing changes.
+     *
+     * Must be called after inferFromSnapshot on the same tick.
+     */
+    toIndicatorStates(): Map<string, NodeIndicatorState>;
+}
+//# sourceMappingURL=pinnacle-events.d.ts.map

package/dist/n4-adaptive-manifold/pinnacle-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinnacle-events.d.ts","sourceRoot":"","sources":["../../src/n4-adaptive-manifold/pinnacle-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAa,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAa/E;;;;;GAKG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAwC;IAEtD;;;OAGG;IACH,iBAAiB,CACf,KAAK,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,EACrF,MAAM,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,EAC3E,QAAQ,EAAE,MAAM,GACf,aAAa,EAAE;IA+ElB;;;;;;;;OAQG;IACH,iBAAiB,IAAI,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC;CAgBrD"}

package/dist/n4-adaptive-manifold/pinnacle-events.js

@@ -0,0 +1,108 @@
+/** Minimum gap (ms) between claim and action to infer "thinking" */
+const THINK_GAP_MS = 2000;
+/**
+ * Tier A inference layer: derives PinnacleEvents from sigchain snapshot deltas.
+ *
+ * When tier B (direct Garden telemetry) arrives, this class is replaced.
+ * The PinnacleEvent shape is the same — canvas code doesn't change.
+ */
+export class PinnacleEventInferrer {
+    agents = new Map();
+    /**
+     * Process a batch of sigchain-derived changes and return PinnacleEvents.
+     * Called by PinnacleView on each poller tick.
+     */
+    inferFromSnapshot(nodes, _edges, sequence) {
+        const events = [];
+        const now = performance.now();
+        // Find all agent nodes
+        const agentNodes = nodes.filter((n) => n.kind === 'agent');
+        for (const agent of agentNodes) {
+            const existingTracker = this.agents.get(agent.id);
+            const isFirstSeen = !existingTracker;
+            const tracker = existingTracker ?? {
+                lastEventSequence: 0,
+                lastEventTime: now,
+                currentTask: null,
+                loopPhase: 'idle',
+            };
+            // Determine what the agent is doing from metadata
+            const claimedTask = agent.metadata?.current_task;
+            const actionSequence = agent.metadata?.last_action_sequence ?? 0;
+            let loopPhase = 'idle';
+            let targetId = null;
+            if (claimedTask && claimedTask !== tracker.currentTask) {
+                // Agent just claimed a new task (or first seen with a task) → perceive
+                loopPhase = 'perceive';
+                targetId = claimedTask;
+            }
+            else if (claimedTask && actionSequence > tracker.lastEventSequence) {
+                // Agent has a task and just performed an action → act
+                loopPhase = 'act';
+                targetId = claimedTask;
+            }
+            else if (!isFirstSeen && claimedTask && now - tracker.lastEventTime > THINK_GAP_MS) {
+                // Gap inference only after baseline established — avoids false 'think' on first poll.
+                // If constructed 3s before first poll, every agent would immediately enter think.
+                loopPhase = 'think';
+                targetId = claimedTask;
+            }
+            else if (claimedTask) {
+                // Agent has a task, recent action, within gap → still acting
+                loopPhase = tracker.loopPhase === 'idle' ? 'perceive' : tracker.loopPhase;
+                targetId = claimedTask;
+            }
+            // Only emit event if phase changed or target changed
+            if (loopPhase !== tracker.loopPhase || targetId !== tracker.currentTask) {
+                events.push({
+                    agentId: agent.id,
+                    targetId,
+                    loopPhase,
+                    sequence,
+                });
+            }
+            this.agents.set(agent.id, {
+                lastEventSequence: actionSequence || tracker.lastEventSequence,
+                lastEventTime: actionSequence > tracker.lastEventSequence ? now : tracker.lastEventTime,
+                currentTask: claimedTask ?? null,
+                loopPhase,
+            });
+        }
+        // Detect departed agents (were tracked, no longer in nodes)
+        const currentAgentIds = new Set(agentNodes.map((a) => a.id));
+        for (const [agentId, tracker] of this.agents) {
+            if (!currentAgentIds.has(agentId) && tracker.loopPhase !== 'idle') {
+                events.push({
+                    agentId,
+                    targetId: null,
+                    loopPhase: 'idle',
+                    sequence,
+                });
+                this.agents.delete(agentId);
+            }
+        }
+        return events;
+    }
+    /**
+     * Convert persistent agent tracker state into NodeIndicatorState map for the canvas.
+     *
+     * Reads from this.agents (updated by inferFromSnapshot), NOT from emitted events.
+     * Events only fire on state changes — reading from the tracker ensures a stable
+     * 'think' pulse persists across ticks where nothing changes.
+     *
+     * Must be called after inferFromSnapshot on the same tick.
+     */
+    toIndicatorStates() {
+        const states = new Map();
+        for (const [agentId, tracker] of this.agents) {
+            if (tracker.loopPhase !== 'idle') {
+                states.set(agentId, {
+                    loopPhase: tracker.loopPhase,
+                    phaseElapsedMs: 0,
+                    traceTargetId: tracker.currentTask,
+                });
+            }
+        }
+        return states;
+    }
+}

package/dist/n4-adaptive-manifold/providers/gravitational-provider.d.ts

@@ -0,0 +1,16 @@
+import type { ManifoldSnapshot, GravitationalConfig, AlgorithmProvider, LayoutAlgorithm } from '../types.js';
+import type { LayoutResult } from '../../n1-flow-canvas/types.js';
+/**
+ * Gravitational layout with deterministic spiral placement.
+ * Guarantees no overlap by construction using explicit overlap checking.
+ */
+export declare class GravitationalProvider implements AlgorithmProvider {
+    readonly algorithm: LayoutAlgorithm;
+    private config;
+    constructor(config?: Partial<GravitationalConfig>);
+    updateConfig(config: Partial<GravitationalConfig>): void;
+    layout(snapshot: ManifoldSnapshot, canvasWidth: number, canvasHeight: number): Promise<LayoutResult>;
+    /** Classify node into gravitational zone based on kind + metadata */
+    private classifyZone;
+}
+//# sourceMappingURL=gravitational-provider.d.ts.map

package/dist/n4-adaptive-manifold/providers/gravitational-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gravitational-provider.d.ts","sourceRoot":"","sources":["../../../src/n4-adaptive-manifold/providers/gravitational-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EAChB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,+BAA+B,CAAC;AA4B9E;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IAC7D,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAmB;IACtD,OAAO,CAAC,MAAM,CAAsB;gBAExB,MAAM,GAAE,OAAO,CAAC,mBAAmB,CAAM;IAIrD,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI;IAIlD,MAAM,CACV,QAAQ,EAAE,gBAAgB,EAC1B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,YAAY,CAAC;IAiGxB,qEAAqE;IACrE,OAAO,CAAC,YAAY;CAsCrB"}