hcifootprint 0.2.0

package/dist/graph/builder.js

@@ -0,0 +1,165 @@
+/**
+ * skillGraph() — the fluent authoring surface.
+ *
+ * Authoring is the primary acquisition mode by design: guards and intent are
+ * semantic and unrecoverable from passive observation. The builder's job is
+ * the enforcement spine — every referential or shape mistake fails LOUDLY at
+ * build() so the graph can't silently drift into lying to a planner.
+ */
+import { detectSchema } from 'footprintjs';
+import { Session } from '../traverse/session.js';
+import { SkillGraphValidationError, guardStateKeys, validateGuardShape } from './guards.js';
+export { SkillGraphValidationError } from './guards.js';
+export function skillGraph(id, opts) {
+    return new SkillGraphBuilder(id, opts?.description);
+}
+export class SkillGraphBuilder {
+    #id;
+    #description;
+    #pages = new Map();
+    #affordances = new Map();
+    #skills = new Map();
+    constructor(id, description) {
+        if (!id || !id.trim())
+            throw new SkillGraphValidationError('skillGraph(id) requires a non-empty id.');
+        this.#id = id;
+        this.#description = description;
+    }
+    page(id, def = {}) {
+        if (this.#pages.has(id))
+            throw new SkillGraphValidationError(`duplicate page id '${id}'.`);
+        this.#pages.set(id, def);
+        return this;
+    }
+    affordance(id, def) {
+        if (id === 'leave-skill') {
+            throw new SkillGraphValidationError(`affordance id 'leave-skill' is reserved — it is the synthetic escape tool served while a skill frame is open.`);
+        }
+        if (this.#affordances.has(id))
+            throw new SkillGraphValidationError(`duplicate affordance id '${id}'.`);
+        if (!def.description || !def.description.trim()) {
+            throw new SkillGraphValidationError(`affordance '${id}' needs a description — it is the planner-facing text an LLM sees.`);
+        }
+        if (def.guard && Object.keys(def.guard).length === 0) {
+            throw new SkillGraphValidationError(`affordance '${id}' has an empty guard {} — footprint's evaluator deliberately NEVER matches ` +
+                `an empty filter (anti-vacuous-truth). Omit 'guard' entirely for an always-offered affordance.`);
+        }
+        if (def.guard)
+            this.#validateGuardShape(`affordance '${id}' guard`, def.guard);
+        if (Array.isArray(def.on) && def.on.length === 0) {
+            throw new SkillGraphValidationError(`affordance '${id}' has on: [] — it would never be offered anywhere. List at least one page.`);
+        }
+        if (def.schema !== undefined && detectSchema(def.schema) === 'none') {
+            throw new SkillGraphValidationError(`affordance '${id}' has an unrecognized schema — pass a Zod schema, a JSON Schema object, ` +
+                `or a validator with .safeParse/.parse.`);
+        }
+        this.#affordances.set(id, def);
+        return this;
+    }
+    skill(id, def) {
+        if (this.#skills.has(id))
+            throw new SkillGraphValidationError(`duplicate skill id '${id}'.`);
+        if (!def.description || !def.description.trim()) {
+            throw new SkillGraphValidationError(`skill '${id}' needs a description (planner-facing text).`);
+        }
+        if (!def.steps || def.steps.length === 0) {
+            throw new SkillGraphValidationError(`skill '${id}' needs at least one step (affordance id).`);
+        }
+        if (def.precondition && Object.keys(def.precondition).length === 0) {
+            throw new SkillGraphValidationError(`skill '${id}' has an empty precondition {} — it would never pass. Omit it instead.`);
+        }
+        if (def.precondition) {
+            this.#validateGuardShape(`skill '${id}' precondition`, def.precondition);
+        }
+        this.#skills.set(id, def);
+        return this;
+    }
+    build() {
+        if (this.#pages.size === 0) {
+            throw new SkillGraphValidationError(`graph '${this.#id}' has no pages — add at least one .page().`);
+        }
+        const pages = {};
+        for (const [id, def] of this.#pages)
+            pages[id] = { id, ...def };
+        const affordances = {};
+        for (const [id, def] of this.#affordances) {
+            const on = Array.isArray(def.on) ? [...def.on] : [def.on];
+            for (const pageId of on) {
+                if (!pages[pageId]) {
+                    throw new SkillGraphValidationError(`affordance '${id}' is offered on unknown page '${pageId}'. Known pages: ${[...this.#pages.keys()].join(', ')}.`);
+                }
+            }
+            if (def.effect?.navigatesTo && !pages[def.effect.navigatesTo]) {
+                throw new SkillGraphValidationError(`affordance '${id}' declares navigatesTo unknown page '${def.effect.navigatesTo}'.`);
+            }
+            // Clone + deep-freeze plain data so the compiled graph is decoupled from
+            // the author's live objects (post-build mutation must not silently change
+            // what a session offers). `schema` is the one exception: validators hold
+            // functions, so it stays by reference and MCP emission clones on the way out.
+            affordances[id] = deepFreeze({
+                id,
+                on,
+                description: def.description,
+                binding: structuredClone(def.binding),
+                guard: def.guard ? structuredClone(def.guard) : undefined,
+                effect: def.effect ? structuredClone(def.effect) : undefined,
+                schema: def.schema,
+                highEffect: def.highEffect ?? false,
+                role: deriveRole(def),
+            });
+        }
+        const skills = {};
+        for (const [id, def] of this.#skills) {
+            for (const step of def.steps) {
+                if (!affordances[step]) {
+                    throw new SkillGraphValidationError(`skill '${id}' step '${step}' is not a known affordance. Known: ${[...this.#affordances.keys()].join(', ')}.`);
+                }
+            }
+            skills[id] = deepFreeze({
+                id,
+                description: def.description,
+                steps: [...def.steps],
+                precondition: def.precondition ? structuredClone(def.precondition) : undefined,
+            });
+        }
+        for (const page of Object.values(pages))
+            Object.freeze(page);
+        const spec = Object.freeze({
+            id: this.#id,
+            description: this.#description,
+            pages: Object.freeze(pages),
+            affordances: Object.freeze(affordances),
+            skills: Object.freeze(skills),
+        });
+        return {
+            spec,
+            createSession: (opts) => new Session(spec, opts),
+            requiredStateKeys: () => guardStateKeys([
+                ...Object.values(spec.affordances).map((aff) => aff.guard),
+                ...Object.values(spec.skills).map((skill) => skill.precondition),
+            ]),
+        };
+    }
+    /** Catch shape mistakes at build time — shared spine with appMap() (guards.ts). */
+    #validateGuardShape(owner, guard) {
+        validateGuardShape(owner, guard);
+    }
+}
+function deriveRole(def) {
+    if (def.role)
+        return def.role;
+    if (def.effect?.navigatesTo)
+        return 'next';
+    return 'action';
+}
+/** Freeze an object and every plain nested object/array. Skips the (unfrozen) `schema` field. */
+function deepFreeze(value) {
+    for (const [key, child] of Object.entries(value)) {
+        if (key === 'schema')
+            continue;
+        if (child && typeof child === 'object')
+            deepFreeze(child);
+    }
+    return Object.freeze(value);
+}
+//# sourceMappingURL=builder.js.map

package/dist/graph/builder.js.map

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

package/dist/graph/guards.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared guard-shape enforcement — one spine for BOTH authoring surfaces
+ * (the v1 fluent skillGraph() and the D18 appMap() object literal).
+ *
+ * footprint's evaluator fails shape mistakes SILENTLY at runtime (unknown
+ * operators are ignored; denied keys never match). Authoring is where they
+ * must die loudly.
+ */
+export declare const FILTER_OPERATORS: Set<string>;
+/** Mirrors footprint evaluator's DENIED_KEYS — guards on these silently never match at runtime. */
+export declare const DENIED_GUARD_KEYS: Set<string>;
+export declare class SkillGraphValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * AND-compose a guard chain (root → leaf → own). Children may only NARROW:
+ * the same key+operator appearing twice with different values is a
+ * contradiction the author must resolve, not a silent override.
+ */
+export declare function composeGuards(owner: string, layers: Record<string, unknown>[]): Record<string, unknown> | undefined;
+/**
+ * The sorted, deduped set of top-level state keys a collection of guards
+ * (WhereFilters) reads. A WhereFilter is a FLAT `key → { op: value }` map, so
+ * its own-enumerable keys ARE the state keys the evaluator looks up — the same
+ * `Object.keys(guard)` set #evalGuard tests for presence before deciding. Both
+ * authoring surfaces build their `requiredStateKeys()` on this.
+ */
+export declare function guardStateKeys(guards: Iterable<Record<string, unknown> | undefined>): string[];
+/** Catch shape mistakes at authoring time — the evaluator fails them silently at runtime. */
+export declare function validateGuardShape(owner: string, guard: Record<string, unknown>): void;
+//# sourceMappingURL=guards.d.ts.map

package/dist/graph/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/graph/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,gBAAgB,aAAiE,CAAC;AAE/F,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,aAa5B,CAAC;AAEH,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAChC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAiBrC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,GAAG,MAAM,EAAE,CAO9F;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAiCtF"}

package/dist/graph/guards.js

@@ -0,0 +1,94 @@
+/**
+ * Shared guard-shape enforcement — one spine for BOTH authoring surfaces
+ * (the v1 fluent skillGraph() and the D18 appMap() object literal).
+ *
+ * footprint's evaluator fails shape mistakes SILENTLY at runtime (unknown
+ * operators are ignored; denied keys never match). Authoring is where they
+ * must die loudly.
+ */
+export const FILTER_OPERATORS = new Set(['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn']);
+/** Mirrors footprint evaluator's DENIED_KEYS — guards on these silently never match at runtime. */
+export const DENIED_GUARD_KEYS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+    'toString',
+    'valueOf',
+    'hasOwnProperty',
+    'isPrototypeOf',
+    'propertyIsEnumerable',
+    '__defineGetter__',
+    '__defineSetter__',
+    '__lookupGetter__',
+    '__lookupSetter__',
+]);
+export class SkillGraphValidationError extends Error {
+    constructor(message) {
+        super(`hcifootprint: ${message}`);
+        this.name = 'SkillGraphValidationError';
+    }
+}
+/**
+ * AND-compose a guard chain (root → leaf → own). Children may only NARROW:
+ * the same key+operator appearing twice with different values is a
+ * contradiction the author must resolve, not a silent override.
+ */
+export function composeGuards(owner, layers) {
+    const merged = {};
+    for (const layer of layers) {
+        for (const [key, ops] of Object.entries(layer)) {
+            const target = (merged[key] ??= {});
+            for (const [op, value] of Object.entries(ops)) {
+                if (op in target && JSON.stringify(target[op]) !== JSON.stringify(value)) {
+                    throw new SkillGraphValidationError(`tool '${owner}': ancestor and descendant guards disagree on '${key}.${op}' ` +
+                        `(${JSON.stringify(target[op])} vs ${JSON.stringify(value)}) — children can only narrow.`);
+                }
+                target[op] = structuredClone(value);
+            }
+        }
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+/**
+ * The sorted, deduped set of top-level state keys a collection of guards
+ * (WhereFilters) reads. A WhereFilter is a FLAT `key → { op: value }` map, so
+ * its own-enumerable keys ARE the state keys the evaluator looks up — the same
+ * `Object.keys(guard)` set #evalGuard tests for presence before deciding. Both
+ * authoring surfaces build their `requiredStateKeys()` on this.
+ */
+export function guardStateKeys(guards) {
+    const keys = new Set();
+    for (const guard of guards) {
+        if (!guard)
+            continue;
+        for (const key of Object.keys(guard))
+            keys.add(key);
+    }
+    return [...keys].sort();
+}
+/** Catch shape mistakes at authoring time — the evaluator fails them silently at runtime. */
+export function validateGuardShape(owner, guard) {
+    for (const [key, ops] of Object.entries(guard)) {
+        if (DENIED_GUARD_KEYS.has(key)) {
+            throw new SkillGraphValidationError(`${owner} key '${key}' is on footprint's denied list — it would silently never match at runtime.`);
+        }
+        if (!ops || typeof ops !== 'object' || Array.isArray(ops)) {
+            throw new SkillGraphValidationError(`${owner} key '${key}' must map to an operator object like { eq: value } ` +
+                `(operators: ${[...FILTER_OPERATORS].join(', ')}).`);
+        }
+        if (Object.keys(ops).length === 0) {
+            throw new SkillGraphValidationError(`${owner} key '${key}' has an empty operator object {} — the evaluator would silently ignore it ` +
+                `(or never match if it is the only key). Give it an operator like { eq: value } or remove the key.`);
+        }
+        for (const [op, value] of Object.entries(ops)) {
+            if (!FILTER_OPERATORS.has(op)) {
+                throw new SkillGraphValidationError(`${owner} key '${key}' uses unknown operator '${op}' (valid: ${[...FILTER_OPERATORS].join(', ')}).`);
+            }
+            if ((op === 'in' || op === 'notIn') && !Array.isArray(value)) {
+                throw new SkillGraphValidationError(`${owner} key '${key}' operator '${op}' needs an ARRAY (got ${typeof value}) — ` +
+                    `a non-array compiles but silently never matches at runtime.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=guards.js.map

package/dist/graph/guards.js.map

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

package/dist/graph/skill-deps.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The intra-skill dependency rule, in ONE place.
+ *
+ * Step B depends on step A when A's declared `effect.writes` overlap B's guard
+ * keys — the guard×effect atoms already encode the ordering, so the dependency
+ * DAG is DERIVED, never authored, and cannot drift from the graph.
+ *
+ * This is shared on purpose: Session.skillPlan() computes the live DAG from it,
+ * and the testing linter (hcifootprint/testing) reasons about skill
+ * completability from the SAME rule. If they used two copies, the linter could
+ * green-light a skill the runtime then reports as blocked (or vice versa) — the
+ * exact drift this library exists to catch. One function, no disagreement.
+ */
+import type { Affordance, DependencyEdge } from '../atom/types.js';
+/**
+ * The steps that must run before `stepId` for its guard to be satisfiable by
+ * in-skill writes — each with the specific keys that create the dependency.
+ */
+export declare function stepDependencies(affordances: Record<string, Affordance>, steps: readonly string[], stepId: string): DependencyEdge[];
+//# sourceMappingURL=skill-deps.d.ts.map

package/dist/graph/skill-deps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-deps.d.ts","sourceRoot":"","sources":["../../src/graph/skill-deps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEnE;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACvC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,MAAM,EAAE,MAAM,GACb,cAAc,EAAE,CAWlB"}

package/dist/graph/skill-deps.js

@@ -0,0 +1,15 @@
+/**
+ * The steps that must run before `stepId` for its guard to be satisfiable by
+ * in-skill writes — each with the specific keys that create the dependency.
+ */
+export function stepDependencies(affordances, steps, stepId) {
+    const guardKeys = Object.keys(affordances[stepId]?.guard ?? {});
+    return steps
+        .filter((otherId) => otherId !== stepId)
+        .map((otherId) => {
+        const viaKeys = (affordances[otherId]?.effect?.writes ?? []).filter((key) => guardKeys.includes(key));
+        return { affordanceId: otherId, viaKeys };
+    })
+        .filter((dep) => dep.viaKeys.length > 0);
+}
+//# sourceMappingURL=skill-deps.js.map

package/dist/graph/skill-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-deps.js","sourceRoot":"","sources":["../../src/graph/skill-deps.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,WAAuC,EACvC,KAAwB,EACxB,MAAc;IAEd,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IAChE,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,MAAM,CAAC;SACvC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QACf,MAAM,OAAO,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAC1E,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CACxB,CAAC;QACF,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC5C,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * hcifootprint — turn a web app's interaction surface into a typed,
+ * traversable skill graph an LLM can plan over.
+ *
+ * The frontend sibling of footprintjs (backend flowcharts) and agentfootprint
+ * (self-explaining agents): one self-explaining trace substrate underneath.
+ *
+ * ```ts
+ * import { buildNavigationGraph } from 'hcifootprint';
+ *
+ * const graph = buildNavigationGraph('shop', {
+ *   pages: {
+ *     catalog: {
+ *       tools: {
+ *         'add-to-cart': { does: 'Add the open dress to the cart', when: { authenticated: { eq: true } }, writes: ['cart'] },
+ *       },
+ *     },
+ *   },
+ *   skills: { purchase: { does: 'Buy a dress end to end', steps: ['add-to-cart'] } },
+ * });
+ *
+ * const session = graph.createSession({ node: 'catalog', state: { authenticated: true } });
+ * session.available();                        // → guard-passing edges = the LLM's action space
+ * session.registerToolGroup('catalog', { handlers: { 'add-to-cart': (i) => shop.add(i) } });
+ * session.fire('catalog.add-to-cart', { source: 'agent' });  // → settlement: 'awaiting-state'
+ * session.updateState({ cart: 1 });           // your store tap settles the pending write
+ * session.why('cart');                        // footprint backward slice over the session
+ *
+ * // v1 skillGraph() — the fluent builder — remains as legacy sugar.
+ * ```
+ */
+export { skillGraph, SkillGraphBuilder, SkillGraphValidationError } from './graph/builder.js';
+export type { SkillGraph } from './graph/builder.js';
+export { Session } from './traverse/session.js';
+export type { RegisteredTools, RegisterToolsOptions } from './traverse/session.js';
+export { buildNavigationGraph } from './tree/appmap.js';
+export type { NavigationGraph, NavigationGraphDef, NodePathsOf, MapNode, ModalDef, NodeDef, NodeKind, PageNodeDef, SkillDef2, ToolDef, } from './tree/types.js';
+export { InteractionSession } from './traverse/nav-session.js';
+export type { RegisterToolGroupOptions, ToolGroupHandle, RegisteredToolDef, InteractionSessionOptions, } from './traverse/nav-session.js';
+export type { SessionEventName, SessionEvents, ToolGroup, ToolHandle } from './atom/types.js';
+export { PresenceIndex } from './presence/presence.js';
+export type { PresenceHandle } from './presence/presence.js';
+export { ToolRegistry } from './registry/registry.js';
+export type { Registration, ToolHandler } from './registry/registry.js';
+export { edgesToMCPTools, leaveSkillTool } from './serve/mcp.js';
+export { skillsAsTools } from './serve/modes.js';
+export type { DoActionArgs, ServeResult, SkillCallArgs, SkillToolsOptions, SkillToolsPort, } from './serve/modes.js';
+export type { ActivationLevel, Actuation, Affordance, AffordanceDef, AvailableEdge, AvailableSkill, AvailableSlice, Binding, CanonicalRole, Cause, CommitSkillResult, ContextBrief, ContextBriefOptions, DependencyEdge, Effect, ElementLocator, Explanation, FireOptions, FireResult, FrameStatus, GapReason, GapRecord, ReportGapOptions, Page, PageDef, PendingInfo, Principal, SessionOptions, Settlement, Skill, SkillDef, SkillFrame, SkillGraphSpec, SkillPlan, SkillPlanStep, StepStatus, StimulusKind, SyncResult, TransitionRecord, UpdateOptions, UpdateResult, } from './atom/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC9F,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAEnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,OAAO,EACP,QAAQ,EACR,OAAO,EACP,QAAQ,EACR,WAAW,EACX,SAAS,EACT,OAAO,GACR,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EACV,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,SAAS,EACT,UAAU,EACV,aAAa,EACb,aAAa,EACb,cAAc,EACd,cAAc,EACd,OAAO,EACP,aAAa,EACb,KAAK,EACL,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,cAAc,EACd,MAAM,EACN,cAAc,EACd,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,IAAI,EACJ,OAAO,EACP,WAAW,EACX,SAAS,EACT,cAAc,EACd,UAAU,EACV,KAAK,EACL,QAAQ,EACR,UAAU,EACV,cAAc,EACd,SAAS,EACT,aAAa,EACb,UAAU,EACV,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * hcifootprint — turn a web app's interaction surface into a typed,
+ * traversable skill graph an LLM can plan over.
+ *
+ * The frontend sibling of footprintjs (backend flowcharts) and agentfootprint
+ * (self-explaining agents): one self-explaining trace substrate underneath.
+ *
+ * ```ts
+ * import { buildNavigationGraph } from 'hcifootprint';
+ *
+ * const graph = buildNavigationGraph('shop', {
+ *   pages: {
+ *     catalog: {
+ *       tools: {
+ *         'add-to-cart': { does: 'Add the open dress to the cart', when: { authenticated: { eq: true } }, writes: ['cart'] },
+ *       },
+ *     },
+ *   },
+ *   skills: { purchase: { does: 'Buy a dress end to end', steps: ['add-to-cart'] } },
+ * });
+ *
+ * const session = graph.createSession({ node: 'catalog', state: { authenticated: true } });
+ * session.available();                        // → guard-passing edges = the LLM's action space
+ * session.registerToolGroup('catalog', { handlers: { 'add-to-cart': (i) => shop.add(i) } });
+ * session.fire('catalog.add-to-cart', { source: 'agent' });  // → settlement: 'awaiting-state'
+ * session.updateState({ cart: 1 });           // your store tap settles the pending write
+ * session.why('cart');                        // footprint backward slice over the session
+ *
+ * // v1 skillGraph() — the fluent builder — remains as legacy sugar.
+ * ```
+ */
+export { skillGraph, SkillGraphBuilder, SkillGraphValidationError } from './graph/builder.js';
+export { Session } from './traverse/session.js';
+// The navigation graph: buildNavigationGraph() authoring, InteractionSession runtime
+export { buildNavigationGraph } from './tree/appmap.js';
+export { InteractionSession } from './traverse/nav-session.js';
+export { PresenceIndex } from './presence/presence.js';
+export { ToolRegistry } from './registry/registry.js';
+export { edgesToMCPTools, leaveSkillTool } from './serve/mcp.js';
+// D18 serving modes — Mode B: skills as fixed tools, disclosure in results
+export { skillsAsTools } from './serve/modes.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEhD,qFAAqF;AACrF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAaxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAS/D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACjE,2EAA2E;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/mcp.d.ts

@@ -0,0 +1,16 @@
+/**
+ * hcifootprint/mcp — the OPTIONAL Model Context Protocol surface.
+ *
+ * Import from here (not the main entry) to expose a session as a real MCP
+ * server. This subpath is the ONLY place `@modelcontextprotocol/sdk` — an
+ * optional peer dependency — is imported, so the core entry stays zero-dep and
+ * anyone who does not need MCP never pulls the SDK.
+ *
+ * ```ts
+ * import { skillsAsTools } from 'hcifootprint';       // primitive — bind to any framework, zero deps
+ * import { mcpServer }     from 'hcifootprint/mcp';    // full MCP server — needs the SDK peer dep
+ * ```
+ */
+export { mcpServer } from './serve/mcp-server.js';
+export type { McpServerOptions } from './serve/mcp-server.js';
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/mcp.js

@@ -0,0 +1,15 @@
+/**
+ * hcifootprint/mcp — the OPTIONAL Model Context Protocol surface.
+ *
+ * Import from here (not the main entry) to expose a session as a real MCP
+ * server. This subpath is the ONLY place `@modelcontextprotocol/sdk` — an
+ * optional peer dependency — is imported, so the core entry stays zero-dep and
+ * anyone who does not need MCP never pulls the SDK.
+ *
+ * ```ts
+ * import { skillsAsTools } from 'hcifootprint';       // primitive — bind to any framework, zero deps
+ * import { mcpServer }     from 'hcifootprint/mcp';    // full MCP server — needs the SDK peer dep
+ * ```
+ */
+export { mcpServer } from './serve/mcp-server.js';
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/presence/presence.d.ts

@@ -0,0 +1,50 @@
+/**
+ * PresenceIndex — the pure presence sensor (D18).
+ *
+ * Registration observes MOUNTED, nothing more. This index is deliberately a
+ * plain refcounted data structure that knows nothing about sessions, trees,
+ * routers, or footprint — the meaning of presence (dormancy below the router,
+ * overlay masking, tab exclusivity, assumed-active defaults) lives one layer
+ * up in NavSession, which COMPOSES this with the authored tree.
+ *
+ * Contract points that make React StrictMode/HMR safe by construction:
+ * - Handles are identities: open() returns a token, close(token) is
+ *   idempotent per token. setup→cleanup→setup nets to one open handle.
+ * - Instance handles (repeats containers) are tracked separately and are
+ *   EXCLUDED from the fingerprint — a scrolling virtualized list must never
+ *   look like world motion (that scoping rule is enforced here, at the
+ *   lowest layer that can).
+ * - Visibility is an EXPLICIT signal store (set by show()/setVisible()/the
+ *   `visible:` mount option). No amount of mount-counting can see CSS; when
+ *   no signal exists the layer above serves honesty markers instead of
+ *   guessing.
+ */
+export interface PresenceHandle {
+    readonly node: string;
+    readonly instance?: string;
+    /** Idempotent. */
+    release(): void;
+}
+export declare class PresenceIndex {
+    #private;
+    open(node: string, instance?: string): PresenceHandle;
+    /** A node is present when at least one NODE handle is open on it. */
+    isPresent(node: string): boolean;
+    presentNodes(): string[];
+    /** Mounted instance keys of a repeats node (the mounted WINDOW, not existence). */
+    instancesOf(node: string): string[];
+    hasInstance(node: string, instance: string): boolean;
+    /** True when ANY node handle is open — the signal that presence is in use at all. */
+    hasAnyHandles(): boolean;
+    /** True when ANY handle (node OR instance) is open — "the mount layer is in use". */
+    hasAny(): boolean;
+    setVisible(node: string, visible: boolean): void;
+    /** The explicit signal, or undefined when none was ever given (→ honesty markers above). */
+    visibility(node: string): boolean | undefined;
+    /**
+     * The served-structure identity used for coalesced world-motion detection:
+     * node presence + visibility signals. Instance churn is EXCLUDED by design.
+     */
+    fingerprint(): string;
+}
+//# sourceMappingURL=presence.d.ts.map

package/dist/presence/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../src/presence/presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB;IAClB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,qBAAa,aAAa;;IAWxB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,cAAc;IA8CrD,qEAAqE;IACrE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC,YAAY,IAAI,MAAM,EAAE;IAIxB,mFAAmF;IACnF,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAInC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIpD,qFAAqF;IACrF,aAAa,IAAI,OAAO;IAIxB,qFAAqF;IACrF,MAAM,IAAI,OAAO;IAIjB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAIhD,4FAA4F;IAC5F,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI7C;;;OAGG;IACH,WAAW,IAAI,MAAM;CAQtB"}