hcifootprint 0.2.0

package/dist/traverse/nav-session.js

@@ -0,0 +1,637 @@
+import { detectSchema } from 'footprintjs';
+import { SkillGraphValidationError, composeGuards, validateGuardShape } from '../graph/guards.js';
+import { PresenceIndex } from '../presence/presence.js';
+import { Session } from './session.js';
+export class InteractionSession extends Session {
+    #map;
+    #presence = new PresenceIndex();
+    /** Deepest node evidenced by sync()/fire(). Registration NEVER writes this. */
+    #focusPath;
+    /**
+     * Mount-declared tool overlay: qualified id → a STACK of declarations
+     * (newest last = the served one). A stack, not a slot: two components may
+     * declare the same tool (StrictMode, list twins); releasing one must never
+     * delete the tool out from under the other — the newest survivor serves.
+     */
+    #dynamic = new Map();
+    #mergedSpec = null;
+    /** Foreign (off-router-page) registrations: node path → first seen (ms). */
+    #foreignSeen = new Map();
+    /** Overlay modals shown by presence alone (no signal): path → first seen (ms). */
+    #overlaySeen = new Map();
+    #warnedOnce = new Set();
+    #graceMs;
+    /** Clock for the grace timers (injectable for deterministic staleness tests). */
+    #now;
+    constructor(map, opts) {
+        const node = opts?.node ?? Object.keys(map.spec.pages)[0];
+        super(map.spec, { ...(opts ?? {}), node });
+        this.#map = map;
+        this.#focusPath = node;
+        this.#graceMs = opts?.dormantGraceMs ?? 3000;
+        this.#now = opts?.now ?? Date.now;
+        // Our fingerprint override reads the fields above — re-baseline now so the
+        // first real mutation (not construction itself) is what flushes a row.
+        this.resetStructureBaseline();
+    }
+    get spec() {
+        try {
+            if (this.#dynamic.size === 0)
+                return super.spec;
+        }
+        catch {
+            // super() is still constructing this instance — no overlay can exist yet.
+            return super.spec;
+        }
+        return (this.#mergedSpec ??= this.#buildMergedSpec());
+    }
+    #buildMergedSpec() {
+        const base = super.spec;
+        const affordances = { ...base.affordances };
+        for (const [qualifiedId, stack] of this.#dynamic) {
+            if (Object.hasOwn(base.affordances, qualifiedId))
+                continue; // declared-wins (warned at mount)
+            if (stack.length > 0)
+                affordances[qualifiedId] = stack[stack.length - 1].affordance;
+        }
+        return { ...base, affordances };
+    }
+    // -------------------------------------------------------------------------
+    // mount — one handle per rendered thing (presence + handlers + declarations)
+    // -------------------------------------------------------------------------
+    /**
+     * Register a component's handlers/tools ON a node when it renders. You never
+     * name a group — this RETURNS a ToolGroupHandle that is the identity (with a
+     * generated `id`). Hold it in a ref; call `handle.unregister()` on unmount.
+     * `handle.setEnabled(toolId, false)` greys one tool out (a disabled button).
+     */
+    registerToolGroup(path, opts) {
+        const node = this.#map.nodes[path];
+        if (!node) {
+            throw new Error(`hcifootprint: unknown node '${path}'. Known nodes: ${Object.keys(this.#map.nodes).join(', ')}.`);
+        }
+        if (opts?.instance !== undefined && !node.repeats) {
+            throw new Error(`hcifootprint: node '${path}' is not repeats: true — instance keys only apply to repeats containers.`);
+        }
+        const owner = Symbol(path);
+        const group = this.nextGroupId(`mount:${path}`);
+        const declaredHere = [];
+        // 1. Mount-declared leaf tools go into the overlay FIRST so handler
+        //    resolution below (and every later lookup) sees them.
+        for (const [name, toolDef] of Object.entries(opts?.tools ?? {})) {
+            const qualifiedId = this.#declareMountTool(path, node, name, toolDef, owner, group, opts?.instance);
+            if (qualifiedId)
+                declaredHere.push(qualifiedId);
+        }
+        // 2. Bind existing app handlers (by reference) to declared tools.
+        for (const [name, handler] of Object.entries(opts?.handlers ?? {})) {
+            const qualifiedId = this.#resolveToolOnNode(path, name);
+            const enabled = opts?.enabled?.[name] ?? opts?.enabled?.[qualifiedId] ?? true;
+            this.registry.register(group, this.#registryKey(qualifiedId, opts?.instance), handler, enabled);
+        }
+        // 3. Presence + optional initial visibility signal.
+        const presenceHandle = this.#presence.open(path, opts?.instance);
+        if (opts?.visible !== undefined)
+            this.#presence.setVisible(path, opts.visible);
+        // 4. Dormancy bookkeeping: a mount outside the router-confirmed page is
+        //    held, not offered — its clock starts now.
+        if (node.page !== this.node && !this.#foreignSeen.has(path)) {
+            this.#foreignSeen.set(path, this.#now());
+        }
+        this.noteStructureChange();
+        let released = false;
+        const unregister = () => {
+            if (released)
+                return;
+            released = true;
+            presenceHandle.release();
+            this.unregisterGroup(group);
+            let removedAny = false;
+            for (const qualifiedId of declaredHere) {
+                const stack = this.#dynamic.get(qualifiedId);
+                if (!stack)
+                    continue;
+                const remaining = stack.filter((entry) => entry.owner !== owner);
+                if (remaining.length !== stack.length) {
+                    if (remaining.length === 0)
+                        this.#dynamic.delete(qualifiedId);
+                    else
+                        this.#dynamic.set(qualifiedId, remaining);
+                    removedAny = true;
+                }
+            }
+            if (removedAny)
+                this.#mergedSpec = null;
+            this.noteStructureChange();
+        };
+        return {
+            id: group,
+            node: path,
+            ...(opts?.instance !== undefined ? { instance: opts.instance } : {}),
+            // Map a leaf/qualified toolId to its registry key (instance-aware).
+            setEnabled: (toolId, enabled) => {
+                const qualifiedId = this.#resolveToolOnNode(path, toolId);
+                this.setToolEnabled(this.#registryKey(qualifiedId, opts?.instance), enabled);
+            },
+            unregister,
+        };
+    }
+    /**
+     * Register ONE tool on a node (convenience over registerToolGroup). `def`
+     * either binds an existing declared tool (`{ handler }`) or declares a new
+     * leaf here (`{ does, handler }`). Returns a single-tool handle.
+     */
+    registerTool(path, toolId, def) {
+        // 'declared' covers BOTH node-scoped tools ('path.toolId') and root/
+        // multi-attach tools (bare 'toolId' offered on this page) — bind the handler
+        // to the existing tool; only declare a NEW leaf when neither exists.
+        const declared = this.spec.affordances[`${path}.${toolId}`] !== undefined ||
+            this.spec.affordances[toolId] !== undefined;
+        const group = declared
+            ? this.registerToolGroup(path, { handlers: { [toolId]: def.handler } })
+            : this.registerToolGroup(path, { tools: { [toolId]: def } });
+        return {
+            id: group.id,
+            ...(group.node !== undefined ? { node: group.node } : {}),
+            toolId,
+            setEnabled: (enabled) => group.setEnabled(toolId, enabled),
+            unregister: () => group.unregister(),
+        };
+    }
+    #declareMountTool(path, node, name, toolDef, owner, group, instance) {
+        if (/[.[\]#/|]/.test(name)) {
+            throw new SkillGraphValidationError(`mount('${path}') tool '${name}' contains a reserved character (. [ ] # / |).`);
+        }
+        const qualifiedId = `${path}.${name}`;
+        if (name === 'leave-skill') {
+            throw new SkillGraphValidationError(`tool name 'leave-skill' is reserved.`);
+        }
+        if (super.spec.affordances[qualifiedId]) {
+            // Declared-wins precedence: the central declaration is the audited one.
+            this.warn(`hcifootprint: mount('${path}') re-declares '${qualifiedId}' — the declared tool wins; ` +
+                `only the handler was bound.`);
+            if (toolDef.handler)
+                this.registry.register(group, this.#registryKey(qualifiedId, instance), toolDef.handler);
+            return null;
+        }
+        if (!toolDef.does || !toolDef.does.trim()) {
+            throw new SkillGraphValidationError(`mount-declared tool '${qualifiedId}' needs a 'does'.`);
+        }
+        if (toolDef.when) {
+            if (Object.keys(toolDef.when).length === 0) {
+                throw new SkillGraphValidationError(`mount-declared tool '${qualifiedId}' has an empty when {} — omit it.`);
+            }
+            validateGuardShape(`mount-declared tool '${qualifiedId}' when`, toolDef.when);
+        }
+        if (toolDef.goTo && !super.spec.pages[toolDef.goTo]) {
+            throw new SkillGraphValidationError(`mount-declared tool '${qualifiedId}' goTo unknown page '${toolDef.goTo}'.`);
+        }
+        if (toolDef.input !== undefined && detectSchema(toolDef.input) === 'none') {
+            throw new SkillGraphValidationError(`mount-declared tool '${qualifiedId}' has an unrecognized input schema.`);
+        }
+        const existing = this.#dynamic.get(qualifiedId);
+        if (existing && existing.length > 0) {
+            this.warn(`hcifootprint: '${qualifiedId}' mount-declared twice — the newest declaration serves (common ` +
+                `cause: a component mounted twice without releasing its handle).`);
+        }
+        const guard = composeGuards(qualifiedId, [
+            ...this.#guardChain(path),
+            ...(toolDef.when ? [toolDef.when] : []),
+        ]);
+        const affordance = Object.freeze({
+            id: qualifiedId,
+            on: [node.page],
+            description: toolDef.does,
+            binding: toolDef.binding ? structuredClone(toolDef.binding) : undefined,
+            guard,
+            effect: toolDef.writes || toolDef.goTo
+                ? {
+                    ...(toolDef.writes ? { writes: [...toolDef.writes] } : {}),
+                    ...(toolDef.goTo ? { navigatesTo: toolDef.goTo } : {}),
+                }
+                : undefined,
+            schema: toolDef.input,
+            highEffect: toolDef.confirm ?? false,
+            role: toolDef.role ?? (toolDef.goTo ? 'next' : 'action'),
+            descriptionSource: 'registration',
+        });
+        this.#dynamic.set(qualifiedId, [...(existing ?? []), { owner, affordance }]);
+        this.#mergedSpec = null;
+        if (toolDef.handler)
+            this.registry.register(group, this.#registryKey(qualifiedId, instance), toolDef.handler);
+        return qualifiedId;
+    }
+    #resolveToolOnNode(path, name) {
+        const qualified = `${path}.${name}`;
+        if (this.spec.affordances[qualified])
+            return qualified;
+        if (this.spec.affordances[name])
+            return name; // already-qualified id or root tool
+        throw new Error(`hcifootprint: mount('${path}') binds unknown tool '${name}' — declare it in appMap (or pass it in ` +
+            `mount({tools})). Known here: ${Object.keys(this.spec.affordances)
+                .filter((id) => id.startsWith(`${path}.`) || !id.includes('.'))
+                .join(', ')}.`);
+    }
+    #registryKey(qualifiedId, instance) {
+        return instance === undefined ? qualifiedId : `${qualifiedId}[${instance}]`;
+    }
+    #guardChain(path) {
+        const chain = [];
+        for (let cursor = this.#map.nodes[path]; cursor;) {
+            if (cursor.guard)
+                chain.unshift(cursor.guard);
+            cursor = cursor.parent ? this.#map.nodes[cursor.parent] : undefined;
+        }
+        return chain;
+    }
+    // -------------------------------------------------------------------------
+    // visibility wire — the one signal registration cannot infer
+    // -------------------------------------------------------------------------
+    setVisible(path, visible) {
+        this.#requireNode(path);
+        this.#presence.setVisible(path, visible);
+        this.noteStructureChange();
+    }
+    /** Show a node; for a tab this also hides its tab siblings (at most one shown). */
+    show(path) {
+        const node = this.#requireNode(path);
+        if (node.kind === 'tab' && node.parent) {
+            for (const siblingPath of this.#map.nodes[node.parent].children) {
+                const sibling = this.#map.nodes[siblingPath];
+                if (sibling.kind === 'tab')
+                    this.#presence.setVisible(siblingPath, siblingPath === path);
+            }
+        }
+        else {
+            this.#presence.setVisible(path, true);
+        }
+        this.noteStructureChange();
+    }
+    #requireNode(path) {
+        const node = this.#map.nodes[path];
+        if (!node) {
+            throw new Error(`hcifootprint: unknown node '${path}'. Known nodes: ${Object.keys(this.#map.nodes).join(', ')}.`);
+        }
+        return node;
+    }
+    // -------------------------------------------------------------------------
+    // focus — evidence-based "you are here", with ancestor fallback
+    // -------------------------------------------------------------------------
+    get focus() {
+        let cursor = this.#focusPath;
+        while (true) {
+            const node = this.#map.nodes[cursor];
+            if (!node || node.page !== this.node)
+                return this.node; // stale/off-graph focus → page floor
+            if (node.kind === 'page')
+                return cursor;
+            const gate = this.#gateNode(cursor);
+            if (gate.served)
+                return cursor;
+            cursor = node.parent ?? this.node; // nearest active ancestor = auto-resume
+        }
+    }
+    // -------------------------------------------------------------------------
+    // the fused activation model
+    // -------------------------------------------------------------------------
+    /**
+     * Shown blocking modals on the current page: signal true, or present without
+     * a contrary signal — AND whose ancestor chain allows visibility. A modal
+     * kept mounted inside a hidden tab is NOT shown and must not mask anything.
+     */
+    #shownOverlays() {
+        const shown = [];
+        for (const node of Object.values(this.#map.nodes)) {
+            if (!node.overlay || node.page !== this.node)
+                continue;
+            const visibility = this.#presence.visibility(node.path);
+            const present = this.#presence.isPresent(node.path);
+            const selfShown = visibility === true || (visibility === undefined && present);
+            const ancestorsAllow = node.parent === null || this.#gateChain(node.parent).served;
+            if (selfShown && ancestorsAllow) {
+                shown.push(node.path);
+                if (visibility === undefined)
+                    this.#overlayGraceCheck(node.path);
+                else
+                    this.#overlaySeen.delete(node.path);
+            }
+            else {
+                this.#overlaySeen.delete(node.path);
+            }
+        }
+        return shown;
+    }
+    /** Overlay self-defense: a modal masking its page on presence alone, past grace, names the missing wire. */
+    #overlayGraceCheck(path) {
+        const firstSeen = this.#overlaySeen.get(path);
+        if (firstSeen === undefined) {
+            this.#overlaySeen.set(path, this.#now());
+            return;
+        }
+        const warnKey = `overlay:${path}`;
+        if (this.#now() - firstSeen >= this.#graceMs && !this.#warnedOnce.has(warnKey)) {
+            this.#warnedOnce.add(warnKey);
+            this.warn(`hcifootprint: modal '${path}' has been masking its page on mount-presence alone for over ` +
+                `${this.#graceMs}ms with no visibility signal. If it is actually closed (kept mounted for ` +
+                `animation), wire session.setVisible('${path}', false) — mounts cannot see CSS.`);
+        }
+    }
+    #gateNode(path) {
+        // Overlay masking first. With shown blocking modals, a node is served only
+        // if it lives inside AT LEAST ONE of them — "outside ANY shown modal"
+        // would make two simultaneously-shown modals mask each other (total page
+        // deadlock, both modals' own close buttons included).
+        const overlays = this.#shownOverlays();
+        if (overlays.length > 0) {
+            const inside = overlays.some((overlay) => path === overlay || path.startsWith(`${overlay}.`));
+            if (!inside)
+                return { served: false, reason: 'BLOCKED_BY_OVERLAY', overlay: overlays[0] };
+        }
+        return this.#gateChain(path);
+    }
+    /** The chain walk (visibility, modal-shown, tab prior) WITHOUT overlay masking. */
+    #gateChain(path) {
+        // Walk root → node; containers can only reject or degrade certainty.
+        const chain = [];
+        for (let cursor = this.#map.nodes[path]; cursor;) {
+            chain.unshift(cursor);
+            cursor = cursor.parent ? this.#map.nodes[cursor.parent] : undefined;
+        }
+        let presenceUnknown = false;
+        let activation = 'assumed';
+        for (const node of chain) {
+            const visibility = this.#presence.visibility(node.path);
+            if (visibility === false)
+                return { served: false, reason: 'NODE_NOT_VISIBLE', node: node.path };
+            const present = this.#presence.isPresent(node.path);
+            if (node.kind === 'page') {
+                activation = 'synced'; // router-confirmed
+                continue;
+            }
+            if (node.kind === 'modal') {
+                // NEVER assumed: closed until registered or shown.
+                if (visibility !== true && !present) {
+                    return { served: false, reason: 'NODE_NOT_VISIBLE', node: node.path };
+                }
+                activation = visibility === true ? 'shown' : 'registered';
+                continue;
+            }
+            if (node.kind === 'tab') {
+                const gate = this.#gateTab(node, visibility, present);
+                if (!gate.served)
+                    return gate;
+                activation = gate.activation;
+                presenceUnknown ||= gate.presenceUnknown ?? false;
+                continue;
+            }
+            // areas / plain containers: mounted sharpens, signals decide, absence stays assumed
+            activation = visibility === true ? 'shown' : present ? 'registered' : 'assumed';
+        }
+        return { served: true, activation, ...(presenceUnknown ? { presenceUnknown: true } : {}) };
+    }
+    #gateTab(tab, visibility, present) {
+        if (visibility === true)
+            return { served: true, activation: 'shown' };
+        const siblings = tab.parent
+            ? this.#map.nodes[tab.parent].children
+                .map((childPath) => this.#map.nodes[childPath])
+                .filter((child) => child.kind === 'tab')
+            : [tab];
+        // The exclusivity PRIOR: a sibling explicitly shown means this one is not.
+        const siblingShown = siblings.some((sibling) => sibling.path !== tab.path && this.#presence.visibility(sibling.path) === true);
+        if (siblingShown)
+            return { served: false, reason: 'NODE_NOT_VISIBLE', node: tab.path };
+        // Explicitly-hidden siblings are not candidates: with tab A mounted-but-
+        // signaled-hidden and tab B unmounted, B is the plausibly-shown one — a
+        // hidden mount must not make its siblings unreachable.
+        const mountedSiblings = siblings.filter((sibling) => this.#presence.isPresent(sibling.path) && this.#presence.visibility(sibling.path) !== false);
+        if (mountedSiblings.length === 0) {
+            // L0: nothing registers → the flagged union (assumed), never a guessed winner.
+            return { served: true, activation: 'assumed', presenceUnknown: siblings.length > 1 };
+        }
+        if (!present) {
+            // Mounts exist and none of them is this tab: it is really not there (yet).
+            return { served: false, reason: 'NODE_NOT_VISIBLE', node: tab.path };
+        }
+        if (mountedSiblings.length > 1) {
+            // Keep-mounted panels with no wire: serve the union, flagged, and say the one-line upgrade once.
+            const warnKey = `tabs:${tab.parent ?? tab.path}`;
+            if (!this.#warnedOnce.has(warnKey)) {
+                this.#warnedOnce.add(warnKey);
+                this.warn(`hcifootprint: ${mountedSiblings.length} tab siblings under '${tab.parent}' are mounted at once ` +
+                    `and no visibility signal exists — serving all of them flagged presence:'unknown'. One line fixes ` +
+                    `it: session.show('<the visible tab>') on tab change (or pass visible: at mount).`);
+            }
+            return { served: true, activation: 'registered', presenceUnknown: true };
+        }
+        return { served: true, activation: 'registered' };
+    }
+    // -------------------------------------------------------------------------
+    // available / fire / sync / brief — the Session surface, tree-gated
+    // -------------------------------------------------------------------------
+    available() {
+        this.#driftCheck();
+        const base = super.available();
+        const edges = [];
+        for (const edge of base.edges) {
+            const path = this.#pathOnCurrentPage(edge.affordanceId);
+            if (!path) {
+                edges.push(edge); // defensive: a projection tool with no tree node keeps v1 semantics
+                continue;
+            }
+            const gate = this.#gateNode(path);
+            if (!gate.served)
+                continue; // fire() on it returns the typed reason — available() just omits
+            const node = this.#map.nodes[path];
+            const stamped = {
+                ...edge,
+                node: path,
+                activation: gate.activation,
+                ...(gate.presenceUnknown ? { presence: 'unknown' } : {}),
+            };
+            if (node.repeats) {
+                const existence = this.#instanceExistence(node);
+                stamped.instances = existence.keys.slice(0, 50); // render cap only — fireability is uncapped
+                stamped.enumeration = existence.enumeration;
+            }
+            edges.push(stamped);
+        }
+        return { ...base, edges };
+    }
+    fire(affordanceId, opts) {
+        const affordance = this.spec.affordances[affordanceId];
+        if (affordance) {
+            const path = this.#pathOnCurrentPage(affordanceId);
+            if (path) {
+                const gate = this.#gateNode(path);
+                if (!gate.served) {
+                    this.recordRejection(affordanceId, gate.reason, opts.source);
+                    return gate.reason === 'BLOCKED_BY_OVERLAY'
+                        ? { ok: false, reason: 'BLOCKED_BY_OVERLAY', overlay: gate.overlay }
+                        : { ok: false, reason: 'NODE_NOT_VISIBLE', node: gate.node };
+                }
+                const node = this.#map.nodes[path];
+                if (node.repeats) {
+                    const existence = this.#instanceExistence(node);
+                    if (opts.instance === undefined) {
+                        this.recordRejection(affordanceId, 'INSTANCE_REQUIRED', opts.source);
+                        return { ok: false, reason: 'INSTANCE_REQUIRED', instances: existence.keys.slice(0, 50) };
+                    }
+                    // Membership against the FULL set — the render cap must never make
+                    // instance #51 unfireable.
+                    if (!existence.keys.includes(opts.instance)) {
+                        this.recordRejection(affordanceId, 'INSTANCE_UNKNOWN', opts.source);
+                        return { ok: false, reason: 'INSTANCE_UNKNOWN', instances: existence.keys.slice(0, 50) };
+                    }
+                }
+                if (gate.activation === 'assumed' &&
+                    opts.invoke !== false &&
+                    this.#presence.hasAny() &&
+                    this.handlerFor(affordanceId, opts) === undefined) {
+                    // The session runs on mounts, this node's have not arrived, and the
+                    // caller wanted execution: retriable, and never a fake GUARD_FAILED.
+                    this.recordRejection(affordanceId, 'STILL_MOUNTING', opts.source);
+                    return { ok: false, reason: 'STILL_MOUNTING', node: path };
+                }
+                const result = super.fire(affordanceId, opts);
+                if (result.ok)
+                    this.#focusPath = path; // fire evidence moves focus
+                return result;
+            }
+        }
+        return super.fire(affordanceId, opts);
+    }
+    handlerFor(affordanceId, opts) {
+        if (opts.instance !== undefined) {
+            return (this.registry.handlerFor(this.#registryKey(affordanceId, opts.instance)) ??
+                this.registry.handlerFor(affordanceId));
+        }
+        return super.handlerFor(affordanceId, opts);
+    }
+    /**
+     * Instance-aware disabled gate: a per-row button registered disabled under
+     * 'id[instance]' must block, matching how handlerFor resolves it. Falls back
+     * to the base (non-instance) registration.
+     */
+    isToolDisabled(affordanceId, opts) {
+        if (opts.instance !== undefined) {
+            const keyed = this.registry.isEnabled(this.#registryKey(affordanceId, opts.instance));
+            if (keyed !== undefined)
+                return keyed === false;
+        }
+        return this.registry.isEnabled(affordanceId) === false;
+    }
+    sync(observedNode, opts) {
+        const result = super.sync(observedNode, opts);
+        if (result.changed) {
+            this.#focusPath = this.node; // router evidence resets focus to the page
+            // Dormant registrations under the now-confirmed page become native…
+            for (const path of [...this.#foreignSeen.keys()]) {
+                if (this.#map.nodes[path]?.page === this.node)
+                    this.#foreignSeen.delete(path);
+            }
+            // …and still-mounted nodes elsewhere start (or keep) their drift clocks.
+            for (const path of this.#presence.presentNodes()) {
+                const node = this.#map.nodes[path];
+                if (node && node.page !== this.node && !this.#foreignSeen.has(path)) {
+                    this.#foreignSeen.set(path, this.#now());
+                }
+            }
+        }
+        return result;
+    }
+    contextBrief(opts) {
+        this.#driftCheck();
+        const brief = super.contextBrief(opts);
+        const lines = [];
+        if (this.focus !== this.node)
+            lines.push(`Focus: ${this.focus}.`);
+        const frontier = this.#presence
+            .presentNodes()
+            .filter((path) => this.#map.nodes[path]?.page === this.node)
+            .sort();
+        if (frontier.length > 0)
+            lines.push(`Mounted here: ${frontier.join(', ')}.`);
+        return lines.length > 0 ? { ...brief, text: `${brief.text}\n${lines.join('\n')}` } : brief;
+    }
+    // -------------------------------------------------------------------------
+    // internals
+    // -------------------------------------------------------------------------
+    /** The tool's node on the CURRENT page, or null (root tools resolve to the page node). */
+    #pathOnCurrentPage(affordanceId) {
+        const declared = this.#map.toolNodes[affordanceId];
+        if (declared) {
+            return declared.find((path) => this.#map.nodes[path]?.page === this.node) ?? null;
+        }
+        if (this.#dynamic.has(affordanceId)) {
+            const path = affordanceId.split('.').slice(0, -1).join('.');
+            return this.#map.nodes[path]?.page === this.node ? path : null;
+        }
+        return null;
+    }
+    /**
+     * The FULL existence set (sanitized, unbounded). Fire-time membership checks
+     * run against ALL of it — instance #51 is real. Serving layers cap what they
+     * RENDER (50 keys on an edge), never what is fireable.
+     */
+    #instanceExistence(node) {
+        if (node.instances) {
+            try {
+                const keys = node.instances(this.state());
+                if (Array.isArray(keys)) {
+                    return { keys: keys.map(sanitizeKey), enumeration: 'selector' };
+                }
+                this.warn(`hcifootprint: instances source for '${node.path}' returned a non-array — using the mounted window.`);
+            }
+            catch (error) {
+                this.warn(`hcifootprint: instances source for '${node.path}' threw: ${String(error)} — using the mounted window.`);
+            }
+        }
+        return {
+            keys: this.#presence.instancesOf(node.path).map(sanitizeKey),
+            enumeration: 'mounted-window',
+        };
+    }
+    /** Foreign registrations past grace = sensor drift: one dev warning + one gap row, per node. */
+    #driftCheck() {
+        const now = this.#now();
+        for (const [path, firstSeen] of [...this.#foreignSeen]) {
+            if (!this.#presence.isPresent(path) || this.#map.nodes[path]?.page === this.node) {
+                this.#foreignSeen.delete(path);
+                continue;
+            }
+            const warnKey = `foreign:${path}`;
+            if (now - firstSeen >= this.#graceMs && !this.#warnedOnce.has(warnKey)) {
+                this.#warnedOnce.add(warnKey);
+                this.warn(`hcifootprint: '${path}' has been mounted for over ${this.#graceMs}ms while the router says ` +
+                    `'${this.node}' — its tools are dormant. Either sync() is missing a page change or a component ` +
+                    `outlived its page (exit animation / portal). Recorded as a sensor-drift gap row.`);
+                this.reportGap({
+                    request: `dormant registration: node '${path}' mounted while router-confirmed page is '${this.node}'`,
+                    reason: 'sensor-drift',
+                    principal: 'system',
+                });
+            }
+        }
+    }
+    structureFingerprint() {
+        // Instance-keyed handler registrations ('id[key]') are EXCLUDED: a
+        // scrolling virtualized list must never bump the cursor or write rows.
+        // Enabled state IS included — a setEnabled flip changes the served surface.
+        const handlers = this.registry
+            .registrations()
+            // Enabled instance-keyed registrations ('id[key]') are excluded (scroll
+            // churn is not world motion) — but a DISABLED instance tool IS kept, so a
+            // per-row setEnabled(false) flip changes the fingerprint and flushes.
+            .filter((registration) => !registration.affordanceId.includes('[') || !registration.enabled)
+            .map((registration) => registration.affordanceId + (registration.enabled ? '' : ':off'))
+            .sort()
+            .join('|');
+        return `${handlers}::${this.#presence.fingerprint()}::dyn=${[...this.#dynamic.keys()].sort().join('|')}`;
+    }
+}
+function sanitizeKey(key) {
+    // eslint-disable-next-line no-control-regex
+    return String(key).replace(/[\u0000-\u001f\u007f]/g, '').slice(0, 120);
+}
+//# sourceMappingURL=nav-session.js.map