@n-dx/web 0.1.0

package/dist/viewer/polling/tick-visibility-gate.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Tick visibility gate — pauses elapsed time timer updates during tab inactivity.
+ *
+ * Bridges the Page Visibility API (via tab-visibility) to the tick timer's
+ * suspend/resume lifecycle. When the browser tab is backgrounded, the tick
+ * timer's shared setInterval is cleared to conserve CPU and battery. When the
+ * tab returns to the foreground, the timer is resumed with an immediate
+ * catch-up tick so elapsed time displays jump to the correct current value.
+ *
+ * Pipeline position:
+ *
+ *   tab-visibility → **tick-visibility-gate** → tick-timer → batched-tick-dispatcher → useTick → render
+ *
+ * When visible:  tick timer runs normally (1s interval)
+ * When hidden:   tick timer is suspended (no interval, no ticks, zero CPU)
+ * On resume:     immediate catch-up tick → restart interval
+ *
+ * Lifecycle:
+ *
+ *   Tab goes hidden:
+ *     1. Immediately suspend the tick timer (clearInterval).
+ *     2. No ticks fire while the tab is hidden — zero overhead.
+ *
+ *   Tab becomes visible (after resume debounce):
+ *     1. Resume the tick timer — fires an immediate tick for catch-up,
+ *        then restarts the 1-second interval.
+ *     2. The immediate tick causes all elapsed time displays to recompute
+ *        from their absolute startedAt timestamps, jumping to the correct
+ *        current value without waiting up to 1 second.
+ *
+ * The resume is debounced (100ms default) to prevent thrashing during rapid
+ * tab switching (e.g. quick alt-tab sequences). Suspension is always immediate
+ * to stop unnecessary work as fast as possible.
+ *
+ * This module complements the polling-manager (which manages its own set of
+ * registered pollers) and the DOM update gate (which gates state updates).
+ * Together they form a complete tab-inactivity optimization pipeline.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ */
+/** Configuration for the tick visibility gate. */
+export interface TickVisibilityGateConfig {
+    /**
+     * Debounce delay in milliseconds before resuming the tick timer after
+     * the tab becomes visible. Prevents thrashing on rapid tab switches.
+     * Default: 100ms (matches polling-manager and DOM update gate debounce).
+     */
+    resumeDebounceMs?: number | undefined;
+    /**
+     * Called when the tick timer is suspended (tab went hidden).
+     * Optional — useful for monitoring and debugging.
+     */
+    onSuspend?: (() => void) | undefined;
+    /**
+     * Called when the tick timer is resumed (tab became visible, after debounce).
+     * Optional — useful for monitoring and debugging.
+     */
+    onResume?: (() => void) | undefined;
+}
+/** Read-only snapshot of the gate's current state. */
+export interface TickVisibilityGateSnapshot {
+    /** Whether the tick timer is currently running (gate is open). */
+    readonly isRunning: boolean;
+    /** Number of times the timer has been suspended. */
+    readonly suspensionCount: number;
+    /** Number of times the timer has been resumed (after debounce). */
+    readonly resumeCount: number;
+    /** Whether the gate has been disposed. */
+    readonly disposed: boolean;
+}
+/** A tick visibility gate instance. */
+export interface TickVisibilityGate {
+    /** Whether the tick timer is currently running. */
+    isRunning(): boolean;
+    /** Get a snapshot of the gate's current state. */
+    getSnapshot(): TickVisibilityGateSnapshot;
+    /** Dispose: unsubscribe from visibility events, clear debounce timer. */
+    dispose(): void;
+}
+/**
+ * Create a new tick visibility gate.
+ *
+ * Usage:
+ * ```ts
+ * // During app initialization (after startTabVisibilityMonitor):
+ * const gate = createTickVisibilityGate();
+ *
+ * // On app shutdown:
+ * gate.dispose();
+ * ```
+ */
+export declare function createTickVisibilityGate(config?: TickVisibilityGateConfig): TickVisibilityGate;

package/dist/viewer/polling/tick-visibility-gate.js

@@ -0,0 +1,146 @@
+/**
+ * Tick visibility gate — pauses elapsed time timer updates during tab inactivity.
+ *
+ * Bridges the Page Visibility API (via tab-visibility) to the tick timer's
+ * suspend/resume lifecycle. When the browser tab is backgrounded, the tick
+ * timer's shared setInterval is cleared to conserve CPU and battery. When the
+ * tab returns to the foreground, the timer is resumed with an immediate
+ * catch-up tick so elapsed time displays jump to the correct current value.
+ *
+ * Pipeline position:
+ *
+ *   tab-visibility → **tick-visibility-gate** → tick-timer → batched-tick-dispatcher → useTick → render
+ *
+ * When visible:  tick timer runs normally (1s interval)
+ * When hidden:   tick timer is suspended (no interval, no ticks, zero CPU)
+ * On resume:     immediate catch-up tick → restart interval
+ *
+ * Lifecycle:
+ *
+ *   Tab goes hidden:
+ *     1. Immediately suspend the tick timer (clearInterval).
+ *     2. No ticks fire while the tab is hidden — zero overhead.
+ *
+ *   Tab becomes visible (after resume debounce):
+ *     1. Resume the tick timer — fires an immediate tick for catch-up,
+ *        then restarts the 1-second interval.
+ *     2. The immediate tick causes all elapsed time displays to recompute
+ *        from their absolute startedAt timestamps, jumping to the correct
+ *        current value without waiting up to 1 second.
+ *
+ * The resume is debounced (100ms default) to prevent thrashing during rapid
+ * tab switching (e.g. quick alt-tab sequences). Suspension is always immediate
+ * to stop unnecessary work as fast as possible.
+ *
+ * This module complements the polling-manager (which manages its own set of
+ * registered pollers) and the DOM update gate (which gates state updates).
+ * Together they form a complete tab-inactivity optimization pipeline.
+ *
+ * Designed as a standalone module with zero framework dependencies.
+ */
+import { onVisibilityChange, isTabVisible, } from "./tab-visibility.js";
+import { suspendTickTimer, resumeTickTimer } from "./tick-timer.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+const DEFAULT_RESUME_DEBOUNCE_MS = 100;
+// ─── Factory ─────────────────────────────────────────────────────────────────
+/**
+ * Create a new tick visibility gate.
+ *
+ * Usage:
+ * ```ts
+ * // During app initialization (after startTabVisibilityMonitor):
+ * const gate = createTickVisibilityGate();
+ *
+ * // On app shutdown:
+ * gate.dispose();
+ * ```
+ */
+export function createTickVisibilityGate(config = {}) {
+    const resumeDebounceMs = config.resumeDebounceMs ?? DEFAULT_RESUME_DEBOUNCE_MS;
+    const onSuspend = config.onSuspend;
+    const onResume = config.onResume;
+    let running = true;
+    let suspensionCount = 0;
+    let resumeCount = 0;
+    let resumeTimer = null;
+    let disposed = false;
+    // ─── Internal helpers ─────────────────────────────────────────────
+    function clearResumeTimer() {
+        if (resumeTimer !== null) {
+            clearTimeout(resumeTimer);
+            resumeTimer = null;
+        }
+    }
+    function suspend() {
+        if (!running)
+            return;
+        running = false;
+        suspensionCount++;
+        suspendTickTimer();
+        if (onSuspend) {
+            try {
+                onSuspend();
+            }
+            catch {
+                // Swallow errors from the suspend callback.
+            }
+        }
+    }
+    function resume() {
+        if (running)
+            return;
+        running = true;
+        resumeCount++;
+        resumeTickTimer();
+        if (onResume) {
+            try {
+                onResume();
+            }
+            catch {
+                // Swallow errors from the resume callback.
+            }
+        }
+    }
+    function handleVisibilityChange(snapshot) {
+        if (disposed)
+            return;
+        if (snapshot.isVisible) {
+            // Tab became visible — resume with debounce to prevent thrash.
+            clearResumeTimer();
+            resumeTimer = setTimeout(() => {
+                resumeTimer = null;
+                resume();
+            }, resumeDebounceMs);
+        }
+        else {
+            // Tab became hidden — suspend immediately.
+            clearResumeTimer();
+            suspend();
+        }
+    }
+    // Subscribe to tab visibility changes.
+    const unsubVisibility = onVisibilityChange(handleVisibilityChange);
+    // If the tab is currently hidden, suspend immediately.
+    if (!isTabVisible()) {
+        suspend();
+    }
+    // ─── Public methods ─────────────────────────────────────────────────
+    function isRunning() {
+        return running;
+    }
+    function getSnapshot() {
+        return {
+            isRunning: running,
+            suspensionCount,
+            resumeCount,
+            disposed,
+        };
+    }
+    function dispose() {
+        disposed = true;
+        clearResumeTimer();
+        unsubVisibility();
+    }
+    return { isRunning, getSnapshot, dispose };
+}
+//# sourceMappingURL=tick-visibility-gate.js.map

package/dist/viewer/polling/tick-visibility-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tick-visibility-gate.js","sourceRoot":"","sources":["../../../src/viewer/polling/tick-visibility-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EACL,kBAAkB,EAClB,YAAY,GAEb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAkDpE,gFAAgF;AAEhF,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAEvC,gFAAgF;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CACtC,SAAmC,EAAE;IAErC,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,IAAI,0BAA0B,CAAC;IAC/E,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IACnC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAEjC,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,WAAW,GAAyC,IAAI,CAAC;IAC7D,IAAI,QAAQ,GAAG,KAAK,CAAC;IAErB,qEAAqE;IAErE,SAAS,gBAAgB;QACvB,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,YAAY,CAAC,WAAW,CAAC,CAAC;YAC1B,WAAW,GAAG,IAAI,CAAC;QACrB,CAAC;IACH,CAAC;IAED,SAAS,OAAO;QACd,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,OAAO,GAAG,KAAK,CAAC;QAChB,eAAe,EAAE,CAAC;QAElB,gBAAgB,EAAE,CAAC;QAEnB,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,CAAC;gBACH,SAAS,EAAE,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,4CAA4C;YAC9C,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS,MAAM;QACb,IAAI,OAAO;YAAE,OAAO;QAEpB,OAAO,GAAG,IAAI,CAAC;QACf,WAAW,EAAE,CAAC;QAEd,eAAe,EAAE,CAAC;QAElB,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,QAAQ,EAAE,CAAC;YACb,CAAC;YAAC,MAAM,CAAC;gBACP,2CAA2C;YAC7C,CAAC;QACH,CAAC;IACH,CAAC;IAED,SAAS,sBAAsB,CAAC,QAA+B;QAC7D,IAAI,QAAQ;YAAE,OAAO;QAErB,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;YACvB,+DAA+D;YAC/D,gBAAgB,EAAE,CAAC;YACnB,WAAW,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,WAAW,GAAG,IAAI,CAAC;gBACnB,MAAM,EAAE,CAAC;YACX,CAAC,EAAE,gBAAgB,CAAC,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,2CAA2C;YAC3C,gBAAgB,EAAE,CAAC;YACnB,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,uCAAuC;IACvC,MAAM,eAAe,GAAG,kBAAkB,CAAC,sBAAsB,CAAC,CAAC;IAEnE,uDAAuD;IACvD,IAAI,CAAC,YAAY,EAAE,EAAE,CAAC;QACpB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,uEAAuE;IAEvE,SAAS,SAAS;QAChB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,SAAS,WAAW;QAClB,OAAO;YACL,SAAS,EAAE,OAAO;YAClB,eAAe;YACf,WAAW;YACX,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,SAAS,OAAO;QACd,QAAQ,GAAG,IAAI,CAAC;QAChB,gBAAgB,EAAE,CAAC;QACnB,eAAe,EAAE,CAAC;IACpB,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AAC7C,CAAC"}

package/dist/viewer/route-state.d.ts

@@ -0,0 +1,8 @@
+import type { ViewId } from "./types.js";
+export interface ParsedRoute {
+    view: ViewId;
+    subId: string | null;
+}
+export declare function parsePathnameRoute(pathname: string, validViews: Set<ViewId>): ParsedRoute | null;
+export declare function parseLegacyHashRoute(hash: string, validViews: Set<ViewId>): ParsedRoute | null;
+export declare function resolveLocationRoute(pathname: string, hash: string, validViews: Set<ViewId>): ParsedRoute | null;

package/dist/viewer/route-state.js

@@ -0,0 +1,77 @@
+const DEEP_LINK_VIEWS = new Set(["prd", "hench-runs"]);
+function resolveLegacyViewAlias(base, sub) {
+    const normalizedBase = base.trim().toLowerCase();
+    const normalizedSub = (sub ?? "").trim().toLowerCase();
+    if ((normalizedBase === "rex-dashboard" || normalizedBase === "rex")
+        && (normalizedSub === "token-usage" || normalizedSub === "token_usage" || normalizedSub === "llm-utilization")) {
+        return "token-usage";
+    }
+    return null;
+}
+function normalizeHashRoute(hash) {
+    const raw = hash.startsWith("#") ? hash.slice(1) : hash;
+    let decoded = raw.trim();
+    try {
+        decoded = decodeURIComponent(decoded);
+    }
+    catch {
+        // Keep raw hash text when decoding fails.
+    }
+    decoded = decoded.replace(/^\/+/, "");
+    if (decoded.startsWith("sourcevision/"))
+        decoded = decoded.slice("sourcevision/".length);
+    if (decoded.startsWith("sourcevision:"))
+        decoded = decoded.slice("sourcevision:".length);
+    const queryIdx = decoded.search(/[?&]/);
+    if (queryIdx >= 0)
+        decoded = decoded.slice(0, queryIdx);
+    return decoded.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function normalizeHashView(base) {
+    const normalized = base.trim().toLowerCase();
+    if (normalized === "prmarkdown" || normalized === "pr_markdown")
+        return "pr-markdown";
+    return normalized;
+}
+export function parsePathnameRoute(pathname, validViews) {
+    const raw = pathname.slice(1).replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!raw)
+        return null;
+    const slashIdx = raw.indexOf("/");
+    const base = slashIdx > 0 ? raw.slice(0, slashIdx) : raw;
+    const sub = slashIdx > 0 ? raw.slice(slashIdx + 1) : "";
+    const legacyAlias = resolveLegacyViewAlias(base, sub || null);
+    if (legacyAlias && validViews.has(legacyAlias))
+        return { view: legacyAlias, subId: null };
+    if (validViews.has(raw))
+        return { view: raw, subId: null };
+    if (slashIdx > 0) {
+        const view = base;
+        if (validViews.has(view) && sub && DEEP_LINK_VIEWS.has(view))
+            return { view, subId: sub };
+    }
+    return null;
+}
+export function parseLegacyHashRoute(hash, validViews) {
+    if (!hash)
+        return null;
+    const normalized = normalizeHashRoute(hash);
+    if (!normalized)
+        return null;
+    const slashIdx = normalized.indexOf("/");
+    const base = slashIdx > 0 ? normalized.slice(0, slashIdx) : normalized;
+    const sub = slashIdx > 0 ? normalized.slice(slashIdx + 1) : "";
+    const legacyAlias = resolveLegacyViewAlias(base, sub || null);
+    if (legacyAlias && validViews.has(legacyAlias))
+        return { view: legacyAlias, subId: null };
+    const normalizedBase = normalizeHashView(base);
+    const normalizedPath = sub ? `/${normalizedBase}/${sub}` : `/${normalizedBase}`;
+    const parsed = parsePathnameRoute(normalizedPath, validViews);
+    if (!parsed)
+        return null;
+    return parsed;
+}
+export function resolveLocationRoute(pathname, hash, validViews) {
+    return parseLegacyHashRoute(hash, validViews) ?? parsePathnameRoute(pathname, validViews);
+}
+//# sourceMappingURL=route-state.js.map

package/dist/viewer/route-state.js.map

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

package/dist/viewer/schema-compat.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Schema version migrations.
+ * Ensures older output formats can be rendered by newer viewers.
+ */
+import type { LoadedData } from "./types.js";
+type ModuleKey = keyof LoadedData;
+/**
+ * Apply any needed migrations to bring data up to the current schema version.
+ * Returns the migrated data (or the original if no migrations needed).
+ */
+export declare function migrateData(module: string, data: unknown): unknown;
+/**
+ * Register a migration for a module.
+ * Used for future schema updates.
+ */
+export declare function registerMigration(module: ModuleKey, from: string, to: string, migrate: (data: unknown) => unknown): void;
+export {};

package/dist/viewer/schema-compat.js

@@ -0,0 +1,49 @@
+/**
+ * Schema version migrations.
+ * Ensures older output formats can be rendered by newer viewers.
+ */
+/** Current schema version. Inlined to avoid runtime import from schema/. */
+const SCHEMA_VERSION = "1.0.0";
+const migrations = {
+    manifest: [],
+    inventory: [],
+    imports: [],
+    zones: [],
+    components: [],
+    callGraph: [],
+};
+/**
+ * Apply any needed migrations to bring data up to the current schema version.
+ * Returns the migrated data (or the original if no migrations needed).
+ */
+export function migrateData(module, data) {
+    if (!data || typeof data !== "object")
+        return data;
+    const record = data;
+    const dataVersion = module === "manifest"
+        ? record.schemaVersion
+        : undefined;
+    // If version matches current, no migration needed
+    if (dataVersion === SCHEMA_VERSION)
+        return data;
+    const moduleMigrations = migrations[module];
+    if (!moduleMigrations?.length)
+        return data;
+    let current = data;
+    let currentVersion = dataVersion || "0.0.0";
+    for (const migration of moduleMigrations) {
+        if (currentVersion === migration.from) {
+            current = migration.migrate(current);
+            currentVersion = migration.to;
+        }
+    }
+    return current;
+}
+/**
+ * Register a migration for a module.
+ * Used for future schema updates.
+ */
+export function registerMigration(module, from, to, migrate) {
+    migrations[module].push({ from, to, migrate });
+}
+//# sourceMappingURL=schema-compat.js.map

package/dist/viewer/schema-compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-compat.js","sourceRoot":"","sources":["../../src/viewer/schema-compat.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4EAA4E;AAC5E,MAAM,cAAc,GAAG,OAAO,CAAC;AAW/B,MAAM,UAAU,GAAmC;IACjD,QAAQ,EAAE,EAAE;IACZ,SAAS,EAAE,EAAE;IACb,OAAO,EAAE,EAAE;IACX,KAAK,EAAE,EAAE;IACT,UAAU,EAAE,EAAE;IACd,SAAS,EAAE,EAAE;CACd,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,IAAa;IACvD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEnD,MAAM,MAAM,GAAG,IAAwC,CAAC;IACxD,MAAM,WAAW,GACf,MAAM,KAAK,UAAU;QACnB,CAAC,CAAE,MAAM,CAAC,aAAoC;QAC9C,CAAC,CAAC,SAAS,CAAC;IAEhB,kDAAkD;IAClD,IAAI,WAAW,KAAK,cAAc;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,gBAAgB,GAAG,UAAU,CAAC,MAAmB,CAAC,CAAC;IACzD,IAAI,CAAC,gBAAgB,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAE3C,IAAI,OAAO,GAAY,IAAI,CAAC;IAC5B,IAAI,cAAc,GAAG,WAAW,IAAI,OAAO,CAAC;IAE5C,KAAK,MAAM,SAAS,IAAI,gBAAgB,EAAE,CAAC;QACzC,IAAI,cAAc,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YACtC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACrC,cAAc,GAAG,SAAS,CAAC,EAAE,CAAC;QAChC,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAiB,EACjB,IAAY,EACZ,EAAU,EACV,OAAmC;IAEnC,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;AACjD,CAAC"}

package/dist/viewer/types.d.ts

@@ -0,0 +1,66 @@
+import type { Manifest, Inventory, Imports, Zones, Components, CallGraph, ViewId } from "./external.js";
+export type { ViewId };
+export interface LoadedData {
+    manifest: Manifest | null;
+    inventory: Inventory | null;
+    imports: Imports | null;
+    zones: Zones | null;
+    components: Components | null;
+    callGraph: CallGraph | null;
+}
+export type NavigateTo = (view: ViewId, opts?: {
+    file?: string;
+    zone?: string;
+    runId?: string;
+    taskId?: string;
+}) => void;
+export interface FileDetail {
+    type: "file";
+    title: string;
+    path: string;
+    language?: string;
+    size?: string;
+    lines?: number;
+    role?: string;
+    category?: string;
+    hash?: string;
+    zone?: string;
+    incomingImports?: number;
+}
+export interface ZoneDetail {
+    type: "zone";
+    title: string;
+    id: string;
+    zoneId?: string;
+    description: string;
+    files: number;
+    entryPoints: string[];
+    cohesion: string;
+    coupling: string;
+}
+export interface GenericDetail {
+    type: "generic";
+    title: string;
+    [key: string]: unknown;
+}
+export interface PRDDetail {
+    type: "prd";
+    title: string;
+    id: string;
+    level: string;
+    status: string;
+    description?: string;
+    acceptanceCriteria?: string[];
+    priority?: string;
+    tags?: string[];
+    blockedBy?: string[];
+    startedAt?: string;
+    completedAt?: string;
+    children?: Array<{
+        id: string;
+        title: string;
+        status: string;
+        level: string;
+    }>;
+}
+export type DetailItem = FileDetail | ZoneDetail | GenericDetail | PRDDetail;

package/dist/viewer/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/viewer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/viewer/types.ts"],"names":[],"mappings":""}

package/dist/viewer/usage/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared constants for token usage functionality.
+ *
+ * Centralises polling key, interval, and view identifier so that the
+ * token-usage view, polling integration tests, and navigation tests
+ * all reference the same source of truth.
+ */
+import type { ViewId } from "../types.js";
+/** Polling-manager registration key for the token usage poller. */
+export declare const TOKEN_USAGE_POLL_KEY = "token-usage";
+/** Polling interval for automatic usage data refresh (ms). */
+export declare const USAGE_POLL_INTERVAL_MS = 10000;
+/** View ID used in routing and sidebar navigation. */
+export declare const TOKEN_USAGE_VIEW_ID: ViewId;

package/dist/viewer/usage/constants.js

@@ -0,0 +1,14 @@
+/**
+ * Shared constants for token usage functionality.
+ *
+ * Centralises polling key, interval, and view identifier so that the
+ * token-usage view, polling integration tests, and navigation tests
+ * all reference the same source of truth.
+ */
+/** Polling-manager registration key for the token usage poller. */
+export const TOKEN_USAGE_POLL_KEY = "token-usage";
+/** Polling interval for automatic usage data refresh (ms). */
+export const USAGE_POLL_INTERVAL_MS = 10_000;
+/** View ID used in routing and sidebar navigation. */
+export const TOKEN_USAGE_VIEW_ID = "token-usage";
+//# sourceMappingURL=constants.js.map

package/dist/viewer/usage/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/viewer/usage/constants.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,mEAAmE;AACnE,MAAM,CAAC,MAAM,oBAAoB,GAAG,aAAa,CAAC;AAElD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C,sDAAsD;AACtD,MAAM,CAAC,MAAM,mBAAmB,GAAW,aAAa,CAAC"}

package/dist/viewer/usage/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Token usage module barrel.
+ *
+ * Re-exports shared constants used across the token-usage view,
+ * polling integration, and navigation tests.
+ */
+export { TOKEN_USAGE_POLL_KEY, USAGE_POLL_INTERVAL_MS, TOKEN_USAGE_VIEW_ID, } from "./constants.js";

package/dist/viewer/usage/index.js

@@ -0,0 +1,8 @@
+/**
+ * Token usage module barrel.
+ *
+ * Re-exports shared constants used across the token-usage view,
+ * polling integration, and navigation tests.
+ */
+export { TOKEN_USAGE_POLL_KEY, USAGE_POLL_INTERVAL_MS, TOKEN_USAGE_VIEW_ID, } from "./constants.js";
+//# sourceMappingURL=index.js.map

package/dist/viewer/usage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/viewer/usage/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/viewer/utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared viewer utilities — path display helpers.
+ *
+ * Color, metric, and flow-diagram utilities have been extracted to the
+ * `visualization/` layer (colors.ts, metrics.ts, flow.ts) to reduce this
+ * module's hub status and consolidate visualization concerns.
+ *
+ * Re-exports are provided below for backward compatibility so existing
+ * consumers don't break.  New code should import from `visualization/`
+ * directly.
+ */
+/** Extract the filename from a path (last segment after '/'). */
+export declare function basename(path: string): string;
+/**
+ * Truncate a filename for graph labels, preserving extension and meaningful prefix.
+ * Returns a shortened name with ellipsis when the name exceeds maxLen characters.
+ *
+ * Examples:
+ *   truncateFilename("very-long-component-name.tsx", 16) → "very-long…e.tsx"
+ *   truncateFilename("short.ts", 16) → "short.ts"
+ */
+export declare function truncateFilename(name: string, maxLen?: number): string;
+export { getZoneColorByIndex, getZoneColor, buildZoneColorMap, } from "./visualization/colors.js";
+export { meterClass } from "./visualization/metrics.js";
+export { buildFileToZoneMap, buildFlowEdges, buildCallFlowEdges, buildExternalImportEdges, buildFlowNodes, } from "./visualization/flow.js";

package/dist/viewer/utils.js

@@ -0,0 +1,48 @@
+/**
+ * Shared viewer utilities — path display helpers.
+ *
+ * Color, metric, and flow-diagram utilities have been extracted to the
+ * `visualization/` layer (colors.ts, metrics.ts, flow.ts) to reduce this
+ * module's hub status and consolidate visualization concerns.
+ *
+ * Re-exports are provided below for backward compatibility so existing
+ * consumers don't break.  New code should import from `visualization/`
+ * directly.
+ */
+// ── Path display helpers (owned here) ───────────────────────────────
+/** Extract the filename from a path (last segment after '/'). */
+export function basename(path) {
+    return path.split("/").pop() || path;
+}
+/**
+ * Truncate a filename for graph labels, preserving extension and meaningful prefix.
+ * Returns a shortened name with ellipsis when the name exceeds maxLen characters.
+ *
+ * Examples:
+ *   truncateFilename("very-long-component-name.tsx", 16) → "very-long…e.tsx"
+ *   truncateFilename("short.ts", 16) → "short.ts"
+ */
+export function truncateFilename(name, maxLen = 18) {
+    if (name.length <= maxLen)
+        return name;
+    const dotIdx = name.lastIndexOf(".");
+    if (dotIdx <= 0) {
+        // No extension — simple truncation
+        return name.slice(0, maxLen - 1) + "…";
+    }
+    const ext = name.slice(dotIdx); // e.g. ".tsx"
+    // Keep at least 4 chars of the stem visible + ellipsis + extension
+    const stemBudget = maxLen - ext.length - 1; // -1 for the "…"
+    if (stemBudget < 4) {
+        // Extension too long relative to budget — just truncate the whole thing
+        return name.slice(0, maxLen - 1) + "…";
+    }
+    const stem = name.slice(0, dotIdx);
+    return stem.slice(0, stemBudget) + "…" + ext;
+}
+// ── Backward-compatible re-exports from visualization layer ─────────
+// New code should import from `visualization/` directly.
+export { getZoneColorByIndex, getZoneColor, buildZoneColorMap, } from "./visualization/colors.js";
+export { meterClass } from "./visualization/metrics.js";
+export { buildFileToZoneMap, buildFlowEdges, buildCallFlowEdges, buildExternalImportEdges, buildFlowNodes, } from "./visualization/flow.js";
+//# sourceMappingURL=utils.js.map

package/dist/viewer/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/viewer/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uEAAuE;AAEvE,iEAAiE;AACjE,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,SAAiB,EAAE;IAChE,IAAI,IAAI,CAAC,MAAM,IAAI,MAAM;QAAE,OAAO,IAAI,CAAC;IAEvC,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,mCAAmC;QACnC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;IACzC,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,cAAc;IAC9C,mEAAmE;IACnE,MAAM,UAAU,GAAG,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,iBAAiB;IAC7D,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,wEAAwE;QACxE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;IACzC,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC;AAC/C,CAAC;AAED,uEAAuE;AACvE,yDAAyD;AACzD,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAExD,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,GACf,MAAM,yBAAyB,CAAC"}

package/dist/viewer/validate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Client-side data validation for the sourcevision viewer.
+ *
+ * Zod schemas that validate JSON fetched from the server or dropped
+ * as files. Lives in the viewer layer because the viewer is the sole
+ * consumer — the server layer does its own domain-specific validation
+ * independently.
+ */
+import { z } from "zod";
+import type { V1 } from "./external.js";
+export type ValidationResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    errors: z.ZodError;
+};
+export declare function validateManifest(data: unknown): ValidationResult<V1.Manifest>;
+export declare function validateInventory(data: unknown): ValidationResult<V1.Inventory>;
+export declare function validateImports(data: unknown): ValidationResult<V1.Imports>;
+export declare function validateZones(data: unknown): ValidationResult<V1.Zones>;
+export declare function validateComponents(data: unknown): ValidationResult<V1.Components>;
+export declare function validateCallGraph(data: unknown): ValidationResult<V1.CallGraph>;