hcifootprint 0.2.0

package/dist/traverse/nav-session.d.ts

@@ -0,0 +1,108 @@
+/**
+ * InteractionSession — the composition layer: core Session (driver, frames,
+ * gap ledger, trace) × the authored tree (buildNavigationGraph) × the presence
+ * sensor (PresenceIndex). Each ingredient stays independently testable; THIS
+ * file is where their meanings meet:
+ *
+ *   router sync owns the page level, always
+ *   → authored semantics own meaning (modal overlay, tab exclusivity, repeats)
+ *   → mount handles own presence strictly below the router-confirmed page
+ *   → explicit visibility signals (show/setVisible/`visible:`) own shown/hidden
+ *
+ * Focus ("You are on", below page level) is set ONLY by sync() and fire()
+ * evidence — never by registration, never by recency (React commits effects
+ * bottom-up; a lazy sidebar must not steal focus from a modal). When the
+ * focus node deactivates, focus falls back to the nearest active ancestor —
+ * modal-close auto-resume for free.
+ *
+ * Everything the runtime DERIVES rather than observes is stamped with an
+ * honesty marker; every refused fire is a typed, gap-ledger-recorded
+ * rejection. Never a silent exclusion, never a guessed winner.
+ */
+import type { AvailableSlice, ContextBrief, ContextBriefOptions, FireOptions, FireResult, Principal, SessionOptions, SkillGraphSpec, StimulusKind, SyncResult, ToolGroup, ToolHandle } from '../atom/types.js';
+import type { NavigationGraph, ToolDef } from '../tree/types.js';
+import { Session } from './session.js';
+import type { ToolHandler } from '../registry/registry.js';
+export interface InteractionSessionOptions extends Omit<SessionOptions, 'node'> {
+    /** Starting page id. Default: the first declared page. */
+    node?: string;
+    /**
+     * How long a registration outside the router-confirmed page may persist
+     * before drift telemetry fires (a dev warning + one sensor-drift gap row).
+     * Registrations in that window are DORMANT: held, not offered, activated
+     * instantly if the router then confirms their page. Default 3000ms.
+     */
+    dormantGraceMs?: number;
+    /**
+     * The clock the dormancy / overlay-grace timers read (epoch ms). Defaults to
+     * `Date.now`. Inject a controllable clock to test time-dependent staleness
+     * deterministically — a dormant registration, a mount-grace warning — without
+     * real waits (hcifootprint/testing's harness wires one for you).
+     */
+    now?: () => number;
+}
+/** A tool declared at mount time. `does` is a registration-site source-code literal — still authored. */
+export interface RegisteredToolDef extends ToolDef {
+    handler?: ToolHandler;
+}
+export interface RegisterToolGroupOptions {
+    /** Bind the app's EXISTING handlers (by reference) to tools declared on this node. */
+    handlers?: Record<string, ToolHandler>;
+    /** Declare new leaf tools here-and-now (the register-with-just-a-description path). */
+    tools?: Record<string, RegisteredToolDef>;
+    /** Instance key when registering one card of a repeats container ('o-123'). */
+    instance?: string;
+    /** Initial visibility signal (same wire as setVisible). */
+    visible?: boolean;
+    /** Initial disabled state per tool (leaf name → enabled). Flip later via handle.setEnabled. */
+    enabled?: Record<string, boolean>;
+}
+/**
+ * The handle returned by registerToolGroup — the group's IDENTITY (see
+ * ToolGroup). Hold it and call `unregister()` on unmount; `setEnabled(id, …)`
+ * greys a tool out.
+ */
+export interface ToolGroupHandle extends ToolGroup {
+    /** Instance key, when this group registered one card of a repeats container. */
+    readonly instance?: string;
+}
+export declare class InteractionSession<Paths extends string = string> extends Session {
+    #private;
+    constructor(map: NavigationGraph, opts?: InteractionSessionOptions);
+    protected get spec(): SkillGraphSpec;
+    /**
+     * 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: Paths, opts?: RegisterToolGroupOptions): ToolGroupHandle;
+    /**
+     * 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: Paths, toolId: string, def: RegisteredToolDef & {
+        handler: ToolHandler;
+    }): ToolHandle;
+    setVisible(path: Paths, visible: boolean): void;
+    /** Show a node; for a tab this also hides its tab siblings (at most one shown). */
+    show(path: Paths): void;
+    get focus(): string;
+    available(): AvailableSlice;
+    fire(affordanceId: string, opts: FireOptions): FireResult;
+    protected handlerFor(affordanceId: string, opts: FireOptions): ToolHandler | undefined;
+    /**
+     * 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.
+     */
+    protected isToolDisabled(affordanceId: string, opts: FireOptions): boolean;
+    sync(observedNode: string, opts?: {
+        stimulus?: StimulusKind;
+        principal?: Principal;
+    }): SyncResult;
+    contextBrief(opts?: ContextBriefOptions): ContextBrief;
+    protected structureFingerprint(): string;
+}
+//# sourceMappingURL=nav-session.d.ts.map

package/dist/traverse/nav-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav-session.d.ts","sourceRoot":"","sources":["../../src/traverse/nav-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAIV,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,YAAY,EACZ,UAAU,EACV,SAAS,EACT,UAAU,EACX,MAAM,kBAAkB,CAAC;AAK1B,OAAO,KAAK,EAAE,eAAe,EAAW,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,MAAM,WAAW,yBAA0B,SAAQ,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC;IAC7E,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,yGAAyG;AACzG,MAAM,WAAW,iBAAkB,SAAQ,OAAO;IAChD,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvC,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,SAAS;IAChD,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAOD,qBAAa,kBAAkB,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,OAAO;;gBAsBhE,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,yBAAyB;IAYlE,cAAuB,IAAI,IAAI,cAAc,CAQ5C;IAgBD;;;;;OAKG;IACH,iBAAiB,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,wBAAwB,GAAG,eAAe;IA2EhF;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,GAAG,UAAU;IAiIxG,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAM/C,mFAAmF;IACnF,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,IAAI;IA2BvB,IAAI,KAAK,IAAI,MAAM,CAUlB;IAqJQ,SAAS,IAAI,cAAc;IA6B3B,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU;cA6C/C,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS;IAU/F;;;;OAIG;cACgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO;IAQ1E,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,YAAY,CAAC;QAAC,SAAS,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG,UAAU;IAmBjG,YAAY,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,YAAY;cA8E5C,oBAAoB,IAAI,MAAM;CAelD"}