@dikshanty94/webnav 0.2.0

package/dist/graph/edit.d.ts

@@ -0,0 +1,47 @@
+import type { MapStore } from '../mapstore/store.js';
+import { type AffordanceKind, type ElementFingerprint, type DeclaredShadow } from '../mapstore/types.js';
+export interface EditAffordanceObj {
+    id?: string;
+    label: string;
+    kind?: AffordanceKind;
+    scope?: 'row' | 'widget';
+    to?: string;
+    commit?: boolean;
+    needs?: string[];
+    addressableUrl?: string;
+    acceptsInput?: string;
+    core?: boolean;
+    children?: EditAffordance[];
+    elementFp?: ElementFingerprint;
+}
+export type EditAffordance = string | EditAffordanceObj;
+export interface EditState {
+    label: string;
+    urlPattern?: string;
+    fingerprint?: string[];
+    affordances?: EditAffordance[];
+    declaredShadow?: DeclaredShadow;
+    role?: string;
+    parentState?: string | null;
+    provisional?: string | null;
+    template?: string | null;
+}
+export interface EditEdge {
+    from: string;
+    to: string;
+    via: string;
+    needsInput?: boolean;
+    why?: string;
+    requiresAffordances?: string[];
+    core?: boolean;
+}
+export interface EditGraph {
+    states: EditState[];
+    edges: EditEdge[];
+}
+export interface EditResult {
+    node: string;
+    statesWritten: number;
+    edgesWritten: number;
+}
+export declare function editGraph(store: MapStore, node: string, graph: EditGraph): EditResult;

package/dist/graph/edit.js

@@ -0,0 +1,211 @@
+import { makeState, makeEdge, makeAffordance } from '../mapstore/types.js';
+let _affSeq = 0;
+const slug = (s) => s.replace(/\W+/g, '_').slice(0, 24);
+// `stateId` maps an author's state LABEL to its full id (`node:label`); `to` in a
+// teach affordance is a label, so we resolve it here.
+const VALID_KINDS = new Set(['navigate', 'reveal', 'mutate', 'input']);
+function toAffordance(a, stateId) {
+    if (typeof a === 'string') {
+        return makeAffordance({ id: 'aff_' + (_affSeq++) + '_' + slug(a), label: a, kind: 'mutate' });
+    }
+    // Validate LOUDLY — a teach payload using the wrong field names (e.g. `type`
+    // instead of `kind`, `name` instead of `label`) must fail, not silently store
+    // a `mutate:undefined` affordance. (Found via dogfooding: an agent invented its
+    // own schema and editGraph happily stored garbage.)
+    if (typeof a.label !== 'string' || !a.label) {
+        throw new Error(`editGraph: affordance is missing a string "label" (got keys: ${Object.keys(a).join(',')})`);
+    }
+    if (a.kind !== undefined && !VALID_KINDS.has(a.kind)) {
+        throw new Error(`editGraph: affordance "${a.label}" has invalid kind "${a.kind}" (expected navigate|reveal|mutate|input)`);
+    }
+    return makeAffordance({
+        id: a.id ?? 'aff_' + (_affSeq++) + '_' + slug(a.label),
+        label: a.label,
+        kind: a.kind ?? 'mutate',
+        ...(a.scope ? { scope: a.scope } : {}),
+        toState: a.to ? stateId(a.to) : null,
+        commit: a.commit ?? false,
+        needs: a.needs ?? [],
+        addressableUrl: a.addressableUrl ?? null,
+        acceptsInput: a.acceptsInput ?? null,
+        core: a.core ?? false,
+        elementFp: a.elementFp ?? null,
+        children: a.children ? a.children.map((c) => toAffordance(c, stateId)) : null,
+    });
+}
+// Find the ONE navigate/reveal affordance (recursing into reveal children) that
+// carries the (toState, via) transition an edge declares. Prefers an exact
+// label/semanticStep match on `via`; falls back to destination-only when it is
+// unambiguous. Returns null when several candidates exist and none matches the
+// label — we never guess among genuinely-equivalent targets (#5a).
+function findNavTarget(affs, toId, via) {
+    const flat = [];
+    const walk = (list) => {
+        for (const a of list) {
+            flat.push(a);
+            if (a.children)
+                walk(a.children);
+        }
+    };
+    walk(affs);
+    const targets = flat.filter((a) => (a.kind === 'navigate' || a.kind === 'reveal') && a.toState === toId);
+    const byLabel = targets.find((a) => a.label === via || a.semanticStep === via);
+    if (byLabel)
+        return byLabel;
+    return targets.length === 1 ? targets[0] : null;
+}
+// Dedup key = the affordance's SEMANTIC identity, NOT its id (toAffordance auto-generates a fresh
+// id per call, so the same logical affordance from two edits would double under an id key). The
+// identity is kind|label|toState PLUS the elementFp — critically the `near` content-anchor, which
+// is what distinguishes same-(role,label) SIBLINGS (row-1 vs row-2 "Press Space to toggle", each
+// with a different `near`). Omitting the fp collapsed 50 distinct row buttons into 1. True
+// duplicates (identical role+name+near) still dedupe; genuinely-distinct siblings stay separate.
+function affKey(a) {
+    const fp = a.elementFp ? `${a.elementFp.role ?? ''}~${a.elementFp.name ?? ''}~${a.elementFp.near ?? ''}` : '';
+    return `${a.kind}|${a.label}|${a.toState ?? ''}|${fp}`;
+}
+// The semantic tuple WITHOUT the fp — same role+label+dest but possibly differing fp. Used for
+// the "fp upgrade" pass: a no-fp affordance that later gains an fp should be UPGRADED, not doubled.
+function affSemanticKey(a) { return `${a.kind}|${a.label}|${a.toState ?? ''}`; }
+/** Merge `incoming` affordances into `existing`, KEEPING existing (commons) and ADDING new ones.
+ *  Distinct same-(role,label) siblings (different `near`) stay separate (affKey includes the fp).
+ *  A no-fp entry that a later capture upgrades WITH an fp is replaced, not doubled. Recurses into
+ *  reveal children. Pure. */
+function mergeAffordances(existing, incoming) {
+    const byKey = new Map();
+    const add = (a) => {
+        const k = affKey(a);
+        const prev = byKey.get(k);
+        if (prev && (prev.children || a.children))
+            prev.children = mergeAffordances(prev.children ?? [], a.children ?? []);
+        if (!prev)
+            byKey.set(k, a);
+    };
+    for (const a of existing)
+        add(a);
+    for (const a of incoming)
+        add(a);
+    // fp-upgrade pass: if a FP-carrying affordance shares the semantic tuple with a NO-FP one,
+    // drop the no-fp one (the fp is the richer, healed coordinate — never keep both).
+    const out = [...byKey.values()];
+    const fpSemantics = new Set(out.filter((a) => a.elementFp).map(affSemanticKey));
+    return out.filter((a) => a.elementFp || !fpSemantics.has(affSemanticKey(a)));
+}
+/** Merge two DeclaredShadows: union collections/filters/subTabs, keep an existing createsEntity. */
+function mergeShadow(existing, incoming) {
+    if (!existing)
+        return incoming ?? null;
+    if (!incoming)
+        return existing;
+    const uniq = (arr) => { const seen = new Set(); return arr.filter((x) => { const k = JSON.stringify(x); if (seen.has(k))
+        return false; seen.add(k); return true; }); };
+    return {
+        collections: uniq([...(existing.collections ?? []), ...(incoming.collections ?? [])]),
+        filters: uniq([...(existing.filters ?? []), ...(incoming.filters ?? [])]),
+        createsEntity: existing.createsEntity ?? incoming.createsEntity ?? null,
+        subTabs: uniq([...(existing.subTabs ?? []), ...(incoming.subTabs ?? [])]),
+    };
+}
+export function editGraph(store, node, graph) {
+    // Tolerate a graph missing `edges`/`states` (e.g. a `--draft` piped through `jq '{node,states}'`,
+    // or a hand-authored spec with only states). The draft carries edges AS navigate affordances on
+    // states, so `edges: []` is the common, valid case — never throw "edges is not iterable" on it.
+    graph = { ...graph, states: graph.states ?? [], edges: graph.edges ?? [] };
+    const stateId = (label) => `${node}:${label}`;
+    // Labels that will exist after this edit: payload states + already-stored states.
+    const payloadLabels = new Set(graph.states.map((s) => s.label));
+    const knownLabel = (label) => payloadLabels.has(label) || store.getState(stateId(label)) !== null;
+    // Validate edge endpoints BEFORE any write (fail fast, atomic).
+    for (const e of graph.edges) {
+        for (const ep of [e.from, e.to]) {
+            if (!knownLabel(ep)) {
+                throw new Error(`editGraph: edge endpoint "${ep}" is not a declared or stored state for node "${node}"`);
+            }
+        }
+    }
+    // Build payload states up front so the edge pass can author onto their affordances before
+    // anything is written. RE-EDIT MERGES, never clobbers: when a state already exists, keep its
+    // affordances (commons) + union the incoming ones, so extending a map with a new session that
+    // shares some steps and adds new ones preserves both. (Without this, upsertState's
+    // affordances=@aff replaces the whole blob — a partial re-edit would wipe prior captures.)
+    const payloadStates = new Map(graph.states.map((s) => {
+        const incomingAff = (s.affordances ?? []).map((a) => toAffordance(a, stateId));
+        const prior = store.getState(stateId(s.label));
+        // Always run through mergeAffordances — even first-time (prior=[]) — so the payload dedups
+        // WITHIN itself too. Two sessions' fragments of one page can each carry the same "Help
+        // Center" link with different auto-ids; without this self-merge, both survived as an exact
+        // duplicate edge (live finding: report-list → help-center appeared twice).
+        const affordances = mergeAffordances(prior?.affordances ?? [], incomingAff);
+        const fingerprint = prior ? [...new Set([...(prior.fingerprint ?? []), ...(s.fingerprint ?? [])])] : (s.fingerprint ?? []);
+        const declaredShadow = prior ? mergeShadow(prior.declaredShadow, s.declaredShadow) : (s.declaredShadow ?? null);
+        // hierarchy: role + parentState. On RE-EDIT the PRIOR wins — it was computed from the full
+        // (multi-session) build, whereas a partial single-session re-edit sees an incomplete nav
+        // structure and would mis-derive (e.g. call a known 'detail' a 'section' because this session
+        // never captured the parent edge). Only take the incoming when there's no prior (first write).
+        const role = prior?.role ?? s.role ?? 'detail';
+        const parentState = prior ? (prior.parentState ?? (s.parentState != null ? stateId(s.parentState) : null))
+            : (s.parentState != null ? stateId(s.parentState) : null);
+        // provisional is a tri-state: `s.provisional === undefined` (key omitted — the common case;
+        // draftFromEffects only emits the key when it has a note) means LEAVE the prior note as-is;
+        // `null` means the incoming edit explicitly CLEARS it (a confirming re-record removing the
+        // seen-once flag); a string SETS/replaces it. Never merge/append here — that's draft's job
+        // (it appends onto ITS OWN provisional before this ever reaches editGraph).
+        const provisional = s.provisional !== undefined ? s.provisional : (prior?.provisional ?? null);
+        // template: additive like urlPattern — take the incoming template, else keep the prior's.
+        const template = s.template !== undefined ? s.template : (prior?.template ?? null);
+        return [s.label, makeState({
+                id: stateId(s.label), nodeId: node, semanticName: s.label,
+                urlPattern: s.urlPattern ?? prior?.urlPattern ?? '', role,
+                fingerprint, affordances, declaredShadow, parentState, provisional, template,
+            })];
+    }));
+    let statesWritten = 0, edgesWritten = 0;
+    store.transaction(() => {
+        const existing = store.getNode(node);
+        store.upsertNode({
+            id: node,
+            homeUrl: existing?.homeUrl ?? `https://${node}`,
+        });
+        // Edge pass FIRST (it may author onto payload/stored states, written after).
+        // Affordances are the SOURCE OF TRUTH: when the from-state has a matching
+        // navigate affordance, the edge's gate is authored as that affordance's
+        // `needs` (and core merged) and NO edge row is written — a stored row would
+        // shadow the gated projection on dedup. Edge rows remain only for edge-only
+        // authoring (no backing affordance) and needsInput/unclassified forks.
+        const patchedStored = new Map();
+        for (const e of graph.edges) {
+            if (!e.needsInput) {
+                const owner = payloadStates.get(e.from)
+                    ?? patchedStored.get(e.from)
+                    ?? store.getState(stateId(e.from)) ?? undefined;
+                const aff = owner ? findNavTarget(owner.affordances ?? [], stateId(e.to), e.via) : null;
+                if (owner && aff) {
+                    for (const id of e.requiresAffordances ?? []) {
+                        if (!aff.needs.includes(id))
+                            aff.needs.push(id);
+                    }
+                    aff.core = aff.core || (e.core ?? false);
+                    if (!payloadStates.has(e.from))
+                        patchedStored.set(e.from, owner);
+                    edgesWritten++;
+                    continue;
+                }
+            }
+            const step = e.needsInput ? `${e.via} [needs-input: ${e.why ?? 'unspecified'}]` : e.via;
+            store.upsertEdge(makeEdge({
+                fromState: stateId(e.from), toState: stateId(e.to),
+                semanticStep: step, kind: e.needsInput ? 'unclassified' : 'navigate',
+                requiresAffordances: e.requiresAffordances ?? [],
+                core: e.core ?? false,
+            }));
+            edgesWritten++;
+        }
+        for (const s of payloadStates.values()) {
+            store.upsertState(s);
+            statesWritten++;
+        }
+        for (const s of patchedStored.values())
+            store.upsertState(s);
+    });
+    return { node, statesWritten, edgesWritten };
+}

package/dist/graph/frontier.d.ts

@@ -0,0 +1,24 @@
+import type { State, Affordance } from '../mapstore/types.js';
+export type FrontierReason = 'dangling-target' | 'ambiguous-action' | 'unopened-panel';
+export interface FrontierItem {
+    state: string;
+    kind: Affordance['kind'];
+    label: string;
+    reason: FrontierReason;
+    hint: string;
+}
+export interface Frontier {
+    status: 'ok';
+    node: string;
+    total: number;
+    frontier: FrontierItem[];
+    excluded: FrontierItem[];
+    byState: Record<string, number>;
+}
+/**
+ * Compute a node's unexplored frontier from its stored states. Pure: takes the
+ * states, returns the report. `exclude` = the caller's hard "never click" labels
+ * (matched case-insensitively as a substring); matched items are moved to
+ * `excluded` (visible, not on the worklist) rather than dropped.
+ */
+export declare function computeFrontier(node: string, states: State[], exclude?: string[]): Frontier;

package/dist/graph/frontier.js

@@ -0,0 +1,95 @@
+// In-place-action shapes: labels that CLEARLY don't open a new surface, so a
+// mutate/input carrying one is NOT frontier. Declared-evidence only — matched on
+// the affordance's own label text, case-insensitively, as a whole-word/substring
+// signal. Grouped by the shape the task named (sort/refresh/pagination/toggle)
+// plus the obviously-in-place widget controls the demo maps declare. This list is
+// the knob: too broad and a real switcher hides; too narrow and every button
+// screams "explore me". Tune it here, never downstream.
+// SAFETY INVARIANT: this list only ever prunes mutate/input affordances — never navigate/reveal
+// (consider() checks kind first), so it can never hide a dangling opener from the frontier.
+const IN_PLACE_SHAPES = [
+    // pagination
+    /\bpage\b/i, /\bpage size\b/i, /first page/i, /previous page/i, /next page/i, /last page/i,
+    // refresh / reload
+    /\brefresh\b/i, /\breload\b/i,
+    // sort / order
+    /\bsort\b/i, /ascending/i, /descending/i, /order by/i,
+    // toggle / select / check (row + column selection, dark mode, legend items)
+    /toggle/i, /\bcheck(ed|box)?\b/i, /uncheck/i, /select all/i, /deselect/i, /row selection/i,
+    /dark mode/i, /light mode/i, /\blegend\b/i,
+    // dismiss / close / cancel (overlay teardown, never a new surface)
+    /\bclose\b/i, /\bcancel\b/i, /dismiss/i, /\bdone\b/i,
+    // in-place view controls the analytics maps declare (chart axis / column tweaks)
+    /secondary axis/i, /^remove\b/i, /view all/i, /expand drilldown/i, /full screen/i,
+    /\bcolumns?\b/i, /\bfunctions?\b/i,
+    // search / filter inputs (an input labeled "search…" filters in place; opens nothing)
+    /search/i, /\bfilter\b/i,
+    // form-fill inputs — a field you type INTO (login creds, checkout, "enter X").
+    // Per the affordance model an input never routes; it's a precondition, not a
+    // surface to open. So a plainly-labeled field is in-place, not frontier.
+    /^enter /i, /^type /i, /username/i, /password/i, /e-?mail/i,
+    // add-to-cart / add-X is the canonical declared in-place MUTATE (affordance
+    // model: add-to-cart never routes; the empty cart is a valid state).
+    /add .*(to|an item)/i, /^add\b/i,
+];
+function isInPlace(label) {
+    return IN_PLACE_SHAPES.some((re) => re.test(label));
+}
+// A reveal that exposes children is already-explored; a navigate/reveal that
+// resolved to a state is already-explored. `scope` templates are generalized.
+function isGeneralized(a) {
+    return a.scope === 'row' || a.scope === 'widget';
+}
+const HINTS = {
+    'dangling-target': 'follow this to capture where it leads',
+    'ambiguous-action': 'fire this and see if it opens a new surface to map',
+    'unopened-panel': 'open this and record the panel contents',
+};
+/**
+ * Compute a node's unexplored frontier from its stored states. Pure: takes the
+ * states, returns the report. `exclude` = the caller's hard "never click" labels
+ * (matched case-insensitively as a substring); matched items are moved to
+ * `excluded` (visible, not on the worklist) rather than dropped.
+ */
+export function computeFrontier(node, states, exclude = []) {
+    const frontier = [];
+    const excluded = [];
+    const exLower = exclude.map((e) => e.toLowerCase());
+    // A reveal's children are its EXPOSED affordances, not a separate frontier item
+    // to open — so we do NOT recurse into children here (unlike coverage's flatten).
+    // We only judge each state's TOP-LEVEL declared affordances.
+    const consider = (state, a) => {
+        if (isGeneralized(a))
+            return null;
+        if (a.kind === 'navigate') {
+            // resolved navigate → done; dangling navigate → frontier
+            return a.toState ? null
+                : { state, kind: a.kind, label: a.label, reason: 'dangling-target', hint: HINTS['dangling-target'] };
+        }
+        if (a.kind === 'reveal') {
+            if (a.children && a.children.length)
+                return null; // panel captured
+            // an unopened reveal: opener seen, no children (and no toState) → frontier
+            return { state, kind: a.kind, label: a.label, reason: 'unopened-panel', hint: HINTS['unopened-panel'] };
+        }
+        // mutate | input: frontier only if the label is NOT a known in-place shape
+        if (isInPlace(a.label))
+            return null;
+        return { state, kind: a.kind, label: a.label, reason: 'ambiguous-action', hint: HINTS['ambiguous-action'] };
+    };
+    for (const s of states) {
+        for (const a of s.affordances ?? []) {
+            const item = consider(s.id, a);
+            if (!item)
+                continue;
+            if (exLower.some((e) => item.label.toLowerCase().includes(e)))
+                excluded.push(item);
+            else
+                frontier.push(item);
+        }
+    }
+    const byState = {};
+    for (const item of frontier)
+        byState[item.state] = (byState[item.state] ?? 0) + 1;
+    return { status: 'ok', node, total: frontier.length, frontier, excluded, byState };
+}

package/dist/graph/seed.d.ts

@@ -0,0 +1,23 @@
+import type { MapStore } from '../mapstore/store.js';
+/**
+ * Seed the out-of-the-box map for a FRESH install (idempotent upserts).
+ *
+ * Deliberately MINIMAL: the ONLY thing seeded is the **saucedemo** walk map — a
+ * single, complete worked example (login → checkout-complete + the burger menu)
+ * so `webnav walk` does something real on first run. Everything else a new user
+ * builds themselves (record → graph-analyse --draft → graph-edit). webnav is a
+ * blank-slate map tool; saucedemo is just the example that proves it works.
+ */
+export declare function seedGraph(store: MapStore): void;
+/**
+ * Ensure the default out-of-the-box map is present — but ONLY on a DB where the
+ * user has never touched saucedemo (no node row). The old guard keyed on a known
+ * interior STATE (checkout-complete), which meant any user-authored saucedemo map
+ * lacking that exact state was force-re-seeded on EVERY open: `dev node-clear`
+ * (the documented re-learn flow) was silently undone, and a human-recorded map
+ * collided with the resurrected seed (live finding: walk matched both the seeded
+ * `inventory` and the drafted `inventory-html` → ambiguous). A node-row guard
+ * respects clear/re-author; the trade-off: `node-rm` of saucedemo brings the
+ * shipped example back on next open (to re-learn, use node-clear — that sticks).
+ */
+export declare function ensureSeeded(store: MapStore): void;

package/dist/graph/seed.js

@@ -0,0 +1,29 @@
+import { seedSaucedemoComplete } from '../router/walk-live.js';
+/**
+ * Seed the out-of-the-box map for a FRESH install (idempotent upserts).
+ *
+ * Deliberately MINIMAL: the ONLY thing seeded is the **saucedemo** walk map — a
+ * single, complete worked example (login → checkout-complete + the burger menu)
+ * so `webnav walk` does something real on first run. Everything else a new user
+ * builds themselves (record → graph-analyse --draft → graph-edit). webnav is a
+ * blank-slate map tool; saucedemo is just the example that proves it works.
+ */
+export function seedGraph(store) {
+    seedSaucedemoComplete(store);
+}
+/**
+ * Ensure the default out-of-the-box map is present — but ONLY on a DB where the
+ * user has never touched saucedemo (no node row). The old guard keyed on a known
+ * interior STATE (checkout-complete), which meant any user-authored saucedemo map
+ * lacking that exact state was force-re-seeded on EVERY open: `dev node-clear`
+ * (the documented re-learn flow) was silently undone, and a human-recorded map
+ * collided with the resurrected seed (live finding: walk matched both the seeded
+ * `inventory` and the drafted `inventory-html` → ambiguous). A node-row guard
+ * respects clear/re-author; the trade-off: `node-rm` of saucedemo brings the
+ * shipped example back on next open (to re-learn, use node-clear — that sticks).
+ */
+export function ensureSeeded(store) {
+    if (store.getNode('www.saucedemo.com') === null) {
+        seedGraph(store);
+    }
+}

package/dist/graph/show.d.ts

@@ -0,0 +1,8 @@
+import type { MapStore } from '../mapstore/store.js';
+import type { State, Edge } from '../mapstore/types.js';
+export interface Interior {
+    node: string;
+    states: State[];
+    edges: Edge[];
+}
+export declare function showInterior(store: MapStore, node: string): Interior;

package/dist/graph/show.js

@@ -0,0 +1,6 @@
+export function showInterior(store, node) {
+    const states = store.statesForNode(node);
+    const prefix = `${node}:`;
+    const edges = store.allEdges().filter((e) => e.fromState.startsWith(prefix));
+    return { node, states, edges };
+}

package/dist/graph/teach.d.ts

@@ -0,0 +1,8 @@
+import type { MapStore } from '../mapstore/store.js';
+import type { SiteNode } from '../mapstore/types.js';
+export interface AddNodeInput {
+    id: string;
+    homeUrl: string;
+}
+/** Teach webnav a new site (or update an existing one). Returns the stored node. */
+export declare function addNode(store: MapStore, input: AddNodeInput): SiteNode;

package/dist/graph/teach.js

@@ -0,0 +1,10 @@
+/** Teach webnav a new site (or update an existing one). Returns the stored node. */
+export function addNode(store, input) {
+    if (!input.id.trim())
+        throw new Error('node-add: id must not be empty');
+    if (!input.homeUrl.trim())
+        throw new Error('node-add: url must not be empty');
+    const node = { id: input.id, homeUrl: input.homeUrl };
+    store.upsertNode(node);
+    return node;
+}

package/dist/hosted.d.ts

@@ -0,0 +1,36 @@
+import { type MapPack } from './contract.js';
+import type { IMapStore } from './mapstore/store.js';
+export type { MapPack } from './contract.js';
+export interface HostedConfig {
+    apiKey?: string;
+    apiBase?: string;
+}
+/** Where the CLI looks for the hosted API base + key, in priority order:
+ *  explicit arg → env (WEBNAV_API / WEBNAV_KEY) → ~/.webnav/config.json → default. */
+export declare function readConfig(): HostedConfig;
+/** Persist the hosted API key (and optional base) to ~/.webnav/config.json.
+ *  This file holds ONLY the service key — never site credentials. */
+export declare function saveConfig(cfg: HostedConfig): void;
+export declare function resolveApiBase(explicit?: string): string;
+export declare function resolveApiKey(explicit?: string): string | undefined;
+export type FetchFn = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+/**
+ * Fetch one site's map pack LIVE from the hosted service (the metered hot path).
+ * Sends ONLY the site id (in the URL) and the API key (header) — never any
+ * credential. Throws a clear, actionable error on missing key / quota / network.
+ * `fetchImpl` is injectable for tests (defaults to global fetch).
+ */
+export declare function fetchHostedMap(site: string, opts?: {
+    key?: string;
+    apiBase?: string;
+    fetchImpl?: FetchFn;
+}): Promise<MapPack>;
+/** Import a fetched map pack into a store via the existing idempotent upserts, so
+ *  the SAME walkRoute can travel it. Pure map data — no credentials involved. */
+export declare function importMapPack(store: IMapStore, pack: MapPack): void;

package/dist/hosted.js

@@ -0,0 +1,69 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { WEBNAV_KEY_HEADER, mapFetchPath } from './contract.js';
+import { configPath } from './paths.js';
+const DEFAULT_API_BASE = 'https://webnav-site.vercel.app';
+/** Where the CLI looks for the hosted API base + key, in priority order:
+ *  explicit arg → env (WEBNAV_API / WEBNAV_KEY) → ~/.webnav/config.json → default. */
+export function readConfig() {
+    const path = configPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Persist the hosted API key (and optional base) to ~/.webnav/config.json.
+ *  This file holds ONLY the service key — never site credentials. */
+export function saveConfig(cfg) {
+    const path = configPath();
+    const merged = { ...readConfig(), ...cfg };
+    writeFileSync(path, JSON.stringify(merged, null, 2), { mode: 0o600 });
+}
+export function resolveApiBase(explicit) {
+    return explicit ?? process.env.WEBNAV_API ?? readConfig().apiBase ?? DEFAULT_API_BASE;
+}
+export function resolveApiKey(explicit) {
+    return explicit ?? process.env.WEBNAV_KEY ?? readConfig().apiKey;
+}
+/**
+ * Fetch one site's map pack LIVE from the hosted service (the metered hot path).
+ * Sends ONLY the site id (in the URL) and the API key (header) — never any
+ * credential. Throws a clear, actionable error on missing key / quota / network.
+ * `fetchImpl` is injectable for tests (defaults to global fetch).
+ */
+export async function fetchHostedMap(site, opts = {}) {
+    const key = resolveApiKey(opts.key);
+    if (!key) {
+        throw new Error('hosted route needs an API key. Get a free key at the webnav site, then run ' +
+            '`webnav login <key>` — or use the free self-host route (drop --hosted).');
+    }
+    const base = resolveApiBase(opts.apiBase).replace(/\/$/, '');
+    const doFetch = opts.fetchImpl ?? globalThis.fetch;
+    const url = `${base}${mapFetchPath(site)}`;
+    const res = await doFetch(url, { headers: { [WEBNAV_KEY_HEADER]: key } });
+    if (res.status === 401)
+        throw new Error('hosted route: invalid or unknown API key (re-run `webnav login <key>`).');
+    if (res.status === 429)
+        throw new Error('hosted route: usage quota exceeded for this key — upgrade your tier or use the self-host route.');
+    if (res.status === 404)
+        throw new Error(`hosted route: no shared map for "${site}" yet.`);
+    if (!res.ok)
+        throw new Error(`hosted route: API error ${res.status} fetching "${site}".`);
+    const pack = await res.json();
+    if (!pack || !pack.node || !Array.isArray(pack.states)) {
+        throw new Error(`hosted route: malformed map pack for "${site}".`);
+    }
+    return pack;
+}
+/** Import a fetched map pack into a store via the existing idempotent upserts, so
+ *  the SAME walkRoute can travel it. Pure map data — no credentials involved. */
+export function importMapPack(store, pack) {
+    store.transaction(() => {
+        store.upsertNode(pack.node);
+        for (const s of pack.states)
+            store.upsertState(s);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { VERSION } from './cli-spec.js';
+export * from './contract.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { VERSION } from './cli-spec.js';
+// The CLI <-> hosted-service contract (MapPack, map types, API protocol) —
+// also importable directly as `@dikshanty94/webnav/contract`.
+export * from './contract.js';