@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/npc/inspect.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatNpcInspection = void 0;
+exports.inspectNpc = inspectNpc;
+const metrics_1 = require("./metrics");
+const session_1 = require("./session");
+var format_1 = require("./format");
+Object.defineProperty(exports, "formatNpcInspection", { enumerable: true, get: function () { return format_1.formatNpcInspection; } });
+const DEFAULT_SECONDS = 8;
+const DEFAULT_SAMPLE_HZ = 10;
+/** Above this the sample loop costs more page time than it observes; the driver runs at frame rate anyway. */
+const MAX_SAMPLE_HZ = 60;
+async function inspectNpc(opts) {
+    const onProgress = opts.onProgress ?? (() => undefined);
+    const seconds = Math.max(0.1, opts.seconds ?? DEFAULT_SECONDS);
+    const sampleHz = Math.min(MAX_SAMPLE_HZ, Math.max(1, opts.sampleHz ?? DEFAULT_SAMPLE_HZ));
+    const settleMs = opts.settleMs ?? session_1.DEFAULT_SETTLE_MS;
+    const session = await (0, session_1.openNpcSession)({
+        directory: opts.directory,
+        timeoutMs: opts.timeoutMs ?? session_1.DEFAULT_TIMEOUT_MS,
+        browser: opts.browser,
+        fallbackMounts: opts.fallbackMounts,
+        onProgress,
+    });
+    try {
+        if (settleMs > 0)
+            await session.page.waitForTimeout(settleMs);
+        onProgress(`helper ready — sampling ${seconds}s at ${sampleHz}Hz after ${settleMs}ms settle`);
+        // A fixed sample COUNT on an absolute schedule: `await` latency would otherwise compound into a run
+        // that watches noticeably longer than it was asked to, and the page clock (not this one) times the rows.
+        const intervalMs = 1000 / sampleHz;
+        const total = Math.max(2, Math.round(seconds * sampleHz));
+        const startedAt = Date.now();
+        const frames = [];
+        for (let i = 0; i < total; i++) {
+            const wait = startedAt + i * intervalMs - Date.now();
+            if (wait > 0)
+                await session.page.waitForTimeout(wait);
+            frames.push((await (0, session_1.readSample)(session.page)));
+        }
+        onProgress(`sampled ${frames.length} frames`);
+        return (0, metrics_1.summarizeSamples)(frames, {
+            seconds,
+            sampleHz,
+            settleMs,
+            npc: opts.npc ?? null,
+            target: opts.target ?? null,
+        });
+    }
+    finally {
+        await session.close();
+    }
+}
+//# sourceMappingURL=inspect.js.map

package/dist/npc/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/npc/inspect.ts"],"names":[],"mappings":";;;AAsCA,gCAyCC;AAxED,uCAA6C;AAC7C,uCAA8F;AAG9F,mCAA+C;AAAtC,6GAAA,mBAAmB,OAAA;AAG5B,MAAM,eAAe,GAAG,CAAC,CAAC;AAC1B,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAC7B,8GAA8G;AAC9G,MAAM,aAAa,GAAG,EAAE,CAAC;AAqBlB,KAAK,UAAU,UAAU,CAAC,IAAuB;IACtD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,GAAS,EAAE,CAAC,SAAS,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC,CAAC,CAAC;IAC1F,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,2BAAiB,CAAC;IAEpD,MAAM,OAAO,GAAG,MAAM,IAAA,wBAAc,EAAC;QACnC,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,4BAAkB;QAC/C,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,UAAU;KACX,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,IAAI,QAAQ,GAAG,CAAC;YAAE,MAAM,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QAC9D,UAAU,CAAC,2BAA2B,OAAO,QAAQ,QAAQ,YAAY,QAAQ,WAAW,CAAC,CAAC;QAE9F,oGAAoG;QACpG,yGAAyG;QACzG,MAAM,UAAU,GAAG,IAAI,GAAG,QAAQ,CAAC;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC;QAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAkB,EAAE,CAAC;QACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,SAAS,GAAG,CAAC,GAAG,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACrD,IAAI,IAAI,GAAG,CAAC;gBAAE,MAAM,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YACtD,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,IAAA,oBAAU,EAAC,OAAO,CAAC,IAAI,CAAC,CAAgB,CAAC,CAAC;QAC/D,CAAC;QACD,UAAU,CAAC,WAAW,MAAM,CAAC,MAAM,SAAS,CAAC,CAAC;QAE9C,OAAO,IAAA,0BAAgB,EAAC,MAAM,EAAE;YAC9B,OAAO;YACP,QAAQ;YACR,QAAQ;YACR,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,IAAI;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;SAC5B,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/npc/metrics.d.ts

@@ -0,0 +1,132 @@
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+/** MIRRORS @helix/engine-core's NpcSample — structural, so this repo takes no engine dependency. */
+export interface NpcSample {
+    id: string;
+    /** Monotonic page clock, MILLISECONDS — what rows are ordered and differenced by. */
+    t: number;
+    position: Vec3 | null;
+    arrived?: boolean;
+    hasPath: boolean;
+    pathLength?: number;
+    speed?: number;
+    locomotionState?: string;
+    dead?: boolean;
+    ragdolled?: boolean;
+    state?: Record<string, unknown>;
+}
+/** A sample re-clocked onto seconds-since-the-run-started, which is what every reported time is in. */
+export type TimedSample = NpcSample & {
+    tS: number;
+};
+export declare const STUCK_WINDOW_S = 1.5;
+export declare const STUCK_MIN_PROGRESS_M = 0.35;
+/** Below this over the whole run the NPC is reported as never having moved (sensor noise, not travel). */
+export declare const MOVED_EPSILON_M = 0.05;
+export interface StuckWindow {
+    fromS: number;
+    toS: number;
+    durationS: number;
+    /** The MOST any 1.5 s sub-window inside this run made — an upper bound on the progress it achieved. */
+    progressM: number;
+}
+export interface Transition {
+    atS: number;
+    /** null on the first observed value — the timeline opens with what the NPC started on. */
+    from: string | null;
+    to: string;
+}
+export interface ArrivedEdge {
+    atS: number;
+    arrived: boolean;
+}
+export interface TargetProgress {
+    target: Vec3;
+    startM: number;
+    finalM: number;
+    closestM: number;
+    closestAtS: number;
+    /** startM − finalM: positive means the NPC closed distance, negative means it lost ground. */
+    closedM: number;
+}
+export type NpcFlag = 'never-moved' | 'dead-throughout' | 'no-position-reads' | 'moving-without-a-path';
+export interface NpcMetrics {
+    id: string;
+    samples: number;
+    /** Seconds between this NPC's first and last row (it may appear late — ids are re-scanned per sample). */
+    spanS: number;
+    firstSeenAtS: number;
+    position: {
+        first: Vec3 | null;
+        last: Vec3 | null;
+    };
+    pathTracedM: number;
+    netDisplacementM: number;
+    /** net / traced. 1.00 = a straight run, near 0 = it went nowhere. null when nothing was traced. */
+    progressRatio: number | null;
+    averageSpeedMps: number;
+    /** Max of the blackboard `speed` reads, when the world's NPCs publish one. */
+    topReportedSpeedMps: number | null;
+    target: TargetProgress | null;
+    stuckWindows: StuckWindow[];
+    stuckSeconds: number;
+    arrivedEdges: ArrivedEdge[];
+    /** What `arrived` read on the first row that carried it — the baseline the edges move away from. */
+    arrivedInitial: boolean | null;
+    /** Fraction of rows whose driver was following a planned path (nav) rather than steering direct. */
+    hasPathRatio: number;
+    maxPathLength: number | null;
+    locomotionTimeline: Transition[];
+    stateTimeline: Transition[];
+    deadThroughout: boolean;
+    ragdolledAnySample: boolean;
+    flags: NpcFlag[];
+}
+export interface NpcInspection {
+    seconds: number;
+    sampleHz: number;
+    settleMs: number;
+    /** How many times npcSample() was actually called (a slow page yields fewer than seconds × sampleHz). */
+    sampleCount: number;
+    /** The id the run was filtered to, or null for every NPC the world reported. */
+    npcFilter: string | null;
+    target: Vec3 | null;
+    /** Every id seen across the run, in first-seen order — including ones the filter excluded. */
+    roster: string[];
+    npcs: NpcMetrics[];
+    notes: string[];
+}
+/** Re-clocks raw rows onto seconds since `t0Ms` — the shared origin every NPC's timeline is read against. */
+export declare function timeline(rows: readonly NpcSample[], t0Ms: number): TimedSample[];
+/** Sum of successive position deltas — how far the NPC actually walked, not how far it got. */
+export declare function pathTraced(rows: readonly TimedSample[]): number;
+/** First position to last — how far it GOT. Traced minus this is what pacing and circling cost. */
+export declare function netDisplacement(rows: readonly TimedSample[]): number;
+/**
+ * Windows where the NPC made less than STUCK_MIN_PROGRESS_M across at least STUCK_WINDOW_S — AIDriver's
+ * own rule, evaluated on a SLIDING window (the driver resets its anchor, so its non-overlapping windows
+ * depend on when the seek began; sliding finds the same stalls regardless of phase). Overlapping hits
+ * merge into one reported window so a 6 s grind reads as one problem, not thirty.
+ */
+export declare function stuckWindows(rows: readonly TimedSample[]): StuckWindow[];
+/** Value changes over time, opening with the first value observed (from: null). */
+export declare function transitionsOf(rows: readonly TimedSample[], read: (row: TimedSample) => string | undefined): Transition[];
+/** Edges of the driver's `arrived` flag — the seek's completion, which no position number states. */
+export declare function arrivedEdges(rows: readonly TimedSample[]): ArrivedEdge[];
+/** Rows whose driver was on a planned path. 0 while the NPC moves = the NavGrid degraded to direct steering. */
+export declare function hasPathRatio(rows: readonly TimedSample[]): number;
+export declare function targetProgress(rows: readonly TimedSample[], target: Vec3): TargetProgress | null;
+/** Everything above for one NPC's rows. `rows` must be that id's samples, in sample order. */
+export declare function summarizeNpc(id: string, rows: readonly TimedSample[], target: Vec3 | null): NpcMetrics;
+export interface SummarizeOptions {
+    seconds: number;
+    sampleHz: number;
+    settleMs: number;
+    npc?: string | null;
+    target?: Vec3 | null;
+}
+/** Frames (one npcSample() call each) → the whole inspection. Ids are grouped in first-seen order. */
+export declare function summarizeSamples(frames: readonly (readonly NpcSample[])[], opts: SummarizeOptions): NpcInspection;

package/dist/npc/metrics.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOVED_EPSILON_M = exports.STUCK_MIN_PROGRESS_M = exports.STUCK_WINDOW_S = void 0;
+exports.timeline = timeline;
+exports.pathTraced = pathTraced;
+exports.netDisplacement = netDisplacement;
+exports.stuckWindows = stuckWindows;
+exports.transitionsOf = transitionsOf;
+exports.arrivedEdges = arrivedEdges;
+exports.hasPathRatio = hasPathRatio;
+exports.targetProgress = targetProgress;
+exports.summarizeNpc = summarizeNpc;
+exports.summarizeSamples = summarizeSamples;
+// SYNC: humanoid-character AIDriver.ts:30-32 (DEFAULT_WINDOW_S / DEFAULT_MIN_PROGRESS_M). Reusing the
+// driver's own thresholds is the point — a window reported here is a window the driver itself would
+// have committed sideways out of, so the report and the runtime never disagree about "stuck".
+exports.STUCK_WINDOW_S = 1.5;
+exports.STUCK_MIN_PROGRESS_M = 0.35;
+/** Below this over the whole run the NPC is reported as never having moved (sensor noise, not travel). */
+exports.MOVED_EPSILON_M = 0.05;
+const round = (n, digits = 3) => {
+    const f = 10 ** digits;
+    return Number.isFinite(n) ? Math.round(n * f) / f : n;
+};
+const dist3 = (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
+/** The driver measures progress on the ground plane, so anything compared against its thresholds does too. */
+const distPlanar = (a, b) => Math.hypot(a.x - b.x, a.z - b.z);
+const positionedOf = (rows) => rows.filter((r) => r.position !== null);
+/** Re-clocks raw rows onto seconds since `t0Ms` — the shared origin every NPC's timeline is read against. */
+function timeline(rows, t0Ms) {
+    return rows.map((r) => ({ ...r, tS: round((r.t - t0Ms) / 1000) }));
+}
+/** Sum of successive position deltas — how far the NPC actually walked, not how far it got. */
+function pathTraced(rows) {
+    const p = positionedOf(rows);
+    let total = 0;
+    for (let i = 1; i < p.length; i++)
+        total += dist3(p[i - 1].position, p[i].position);
+    return total;
+}
+/** First position to last — how far it GOT. Traced minus this is what pacing and circling cost. */
+function netDisplacement(rows) {
+    const p = positionedOf(rows);
+    return p.length < 2 ? 0 : dist3(p[0].position, p[p.length - 1].position);
+}
+/**
+ * Windows where the NPC made less than STUCK_MIN_PROGRESS_M across at least STUCK_WINDOW_S — AIDriver's
+ * own rule, evaluated on a SLIDING window (the driver resets its anchor, so its non-overlapping windows
+ * depend on when the seek began; sliding finds the same stalls regardless of phase). Overlapping hits
+ * merge into one reported window so a 6 s grind reads as one problem, not thirty.
+ */
+function stuckWindows(rows) {
+    const p = positionedOf(rows);
+    const merged = [];
+    let j = 0;
+    for (let i = 1; i < p.length; i++) {
+        while (j + 1 <= i && p[i].tS - p[j + 1].tS >= exports.STUCK_WINDOW_S)
+            j++;
+        if (p[i].tS - p[j].tS < exports.STUCK_WINDOW_S)
+            continue;
+        const progress = distPlanar(p[j].position, p[i].position);
+        if (progress >= exports.STUCK_MIN_PROGRESS_M)
+            continue;
+        const last = merged[merged.length - 1];
+        if (last !== undefined && p[j].tS <= last.toS) {
+            last.toS = Math.max(last.toS, p[i].tS);
+            last.durationS = round(last.toS - last.fromS);
+            last.progressM = Math.max(last.progressM, round(progress));
+        }
+        else {
+            merged.push({ fromS: p[j].tS, toS: p[i].tS, durationS: round(p[i].tS - p[j].tS), progressM: round(progress) });
+        }
+    }
+    return merged;
+}
+/** Value changes over time, opening with the first value observed (from: null). */
+function transitionsOf(rows, read) {
+    const out = [];
+    let current = null;
+    let seen = false;
+    for (const row of rows) {
+        const value = read(row);
+        if (value === undefined)
+            continue;
+        if (seen && value === current)
+            continue;
+        out.push({ atS: row.tS, from: seen ? current : null, to: value });
+        current = value;
+        seen = true;
+    }
+    return out;
+}
+/** Edges of the driver's `arrived` flag — the seek's completion, which no position number states. */
+function arrivedEdges(rows) {
+    return transitionsOf(rows, (r) => (r.arrived === undefined ? undefined : String(r.arrived)))
+        .filter((t) => t.from !== null)
+        .map((t) => ({ atS: t.atS, arrived: t.to === 'true' }));
+}
+/** Rows whose driver was on a planned path. 0 while the NPC moves = the NavGrid degraded to direct steering. */
+function hasPathRatio(rows) {
+    if (rows.length === 0)
+        return 0;
+    return round(rows.filter((r) => r.hasPath === true).length / rows.length);
+}
+function targetProgress(rows, target) {
+    const p = positionedOf(rows);
+    if (p.length === 0)
+        return null;
+    let closestM = Infinity;
+    let closestAtS = p[0].tS;
+    for (const row of p) {
+        const d = dist3(row.position, target);
+        if (d < closestM) {
+            closestM = d;
+            closestAtS = row.tS;
+        }
+    }
+    const startM = dist3(p[0].position, target);
+    const finalM = dist3(p[p.length - 1].position, target);
+    return {
+        target,
+        startM: round(startM),
+        finalM: round(finalM),
+        closestM: round(closestM),
+        closestAtS,
+        closedM: round(startM - finalM),
+    };
+}
+/** Everything above for one NPC's rows. `rows` must be that id's samples, in sample order. */
+function summarizeNpc(id, rows, target) {
+    const p = positionedOf(rows);
+    const traced = pathTraced(rows);
+    const net = netDisplacement(rows);
+    const spanS = rows.length < 2 ? 0 : round(rows[rows.length - 1].tS - rows[0].tS);
+    const speeds = rows.map((r) => r.speed).filter((s) => typeof s === 'number');
+    const pathLengths = rows.map((r) => r.pathLength).filter((n) => typeof n === 'number');
+    const deadRows = rows.filter((r) => r.dead !== undefined);
+    const arrivedRow = rows.find((r) => r.arrived !== undefined);
+    const stuck = stuckWindows(rows);
+    const pathRatio = hasPathRatio(rows);
+    const flags = [];
+    if (p.length === 0)
+        flags.push('no-position-reads');
+    else if (traced < exports.MOVED_EPSILON_M)
+        flags.push('never-moved');
+    if (deadRows.length > 0 && deadRows.every((r) => r.dead === true))
+        flags.push('dead-throughout');
+    if (traced >= exports.MOVED_EPSILON_M && pathRatio === 0)
+        flags.push('moving-without-a-path');
+    return {
+        id,
+        samples: rows.length,
+        spanS,
+        firstSeenAtS: rows.length === 0 ? 0 : rows[0].tS,
+        position: { first: p[0]?.position ?? null, last: p[p.length - 1]?.position ?? null },
+        pathTracedM: round(traced),
+        netDisplacementM: round(net),
+        progressRatio: traced > exports.MOVED_EPSILON_M ? round(net / traced, 2) : null,
+        averageSpeedMps: spanS > 0 ? round(traced / spanS, 2) : 0,
+        topReportedSpeedMps: speeds.length > 0 ? round(Math.max(...speeds), 2) : null,
+        target: target !== null ? targetProgress(rows, target) : null,
+        stuckWindows: stuck,
+        stuckSeconds: round(stuck.reduce((sum, w) => sum + w.durationS, 0)),
+        arrivedEdges: arrivedEdges(rows),
+        arrivedInitial: arrivedRow?.arrived ?? null,
+        hasPathRatio: pathRatio,
+        maxPathLength: pathLengths.length > 0 ? Math.max(...pathLengths) : null,
+        locomotionTimeline: transitionsOf(rows, (r) => r.locomotionState),
+        stateTimeline: transitionsOf(rows, (r) => (r.state === undefined ? undefined : JSON.stringify(r.state))),
+        deadThroughout: flags.includes('dead-throughout'),
+        ragdolledAnySample: rows.some((r) => r.ragdolled === true),
+        flags,
+    };
+}
+/** Frames (one npcSample() call each) → the whole inspection. Ids are grouped in first-seen order. */
+function summarizeSamples(frames, opts) {
+    const flat = frames.flat();
+    const t0Ms = flat.length > 0 ? Math.min(...flat.map((r) => r.t)) : 0;
+    const rows = timeline(flat, t0Ms);
+    const byId = new Map();
+    for (const row of rows) {
+        const bucket = byId.get(row.id);
+        if (bucket === undefined)
+            byId.set(row.id, [row]);
+        else
+            bucket.push(row);
+    }
+    const roster = [...byId.keys()];
+    const filter = opts.npc ?? null;
+    const target = opts.target ?? null;
+    const notes = [];
+    if (frames.length === 0)
+        notes.push('the run collected no samples at all — the page never answered npcSample().');
+    else if (roster.length === 0) {
+        notes.push('the world handed over an NPC pool but it was EMPTY for the whole run — nothing had been added yet, or every NPC was removed before the first sample.');
+    }
+    if (filter !== null && !byId.has(filter)) {
+        notes.push(`no NPC with id '${filter}' appeared in any sample` +
+            (roster.length > 0 ? ` — the world reported: ${roster.join(', ')}.` : '.'));
+    }
+    const selected = filter !== null ? roster.filter((id) => id === filter) : roster;
+    return {
+        seconds: opts.seconds,
+        sampleHz: opts.sampleHz,
+        settleMs: opts.settleMs,
+        sampleCount: frames.length,
+        npcFilter: filter,
+        target,
+        roster,
+        npcs: selected.map((id) => summarizeNpc(id, byId.get(id) ?? [], target)),
+        notes,
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/npc/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/npc/metrics.ts"],"names":[],"mappings":";;;AA+HA,4BAEC;AAGD,gCAKC;AAGD,0CAGC;AAQD,oCAmBC;AAGD,sCAaC;AAGD,oCAIC;AAGD,oCAGC;AAED,wCAsBC;AAGD,oCA0CC;AAWD,4CAuCC;AAlSD,sGAAsG;AACtG,oGAAoG;AACpG,8FAA8F;AACjF,QAAA,cAAc,GAAG,GAAG,CAAC;AACrB,QAAA,oBAAoB,GAAG,IAAI,CAAC;AACzC,0GAA0G;AAC7F,QAAA,eAAe,GAAG,IAAI,CAAC;AA+EpC,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,MAAM,GAAG,CAAC,EAAU,EAAE;IAC9C,MAAM,CAAC,GAAG,EAAE,IAAI,MAAM,CAAC;IACvB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC,CAAC;AAEF,MAAM,KAAK,GAAG,CAAC,CAAO,EAAE,CAAO,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACxF,8GAA8G;AAC9G,MAAM,UAAU,GAAG,CAAC,CAAO,EAAE,CAAO,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAGlF,MAAM,YAAY,GAAG,CAAC,IAA4B,EAAgB,EAAE,CAClE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAmB,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;AAE3D,6GAA6G;AAC7G,SAAgB,QAAQ,CAAC,IAA0B,EAAE,IAAY;IAC/D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,+FAA+F;AAC/F,SAAgB,UAAU,CAAC,IAA4B;IACrD,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC,CAAC;IACtF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mGAAmG;AACnG,SAAgB,eAAe,CAAC,IAA4B;IAC1D,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,QAAQ,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,IAA4B;IACvD,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,EAAE,IAAI,sBAAc;YAAE,CAAC,EAAE,CAAC;QACpE,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,GAAG,sBAAc;YAAE,SAAS;QACnD,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC,CAAC;QAC5D,IAAI,QAAQ,IAAI,4BAAoB;YAAE,SAAS;QAC/C,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACvC,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YAC/C,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC,CAAC;YACxC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;YAC9C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC7D,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACrH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,mFAAmF;AACnF,SAAgB,aAAa,CAAC,IAA4B,EAAE,IAA8C;IACxG,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,IAAI,OAAO,GAAkB,IAAI,CAAC;IAClC,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,IAAI,IAAI,KAAK,KAAK,OAAO;YAAE,SAAS;QACxC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAClE,OAAO,GAAG,KAAK,CAAC;QAChB,IAAI,GAAG,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,qGAAqG;AACrG,SAAgB,YAAY,CAAC,IAA4B;IACvD,OAAO,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;SACzF,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,gHAAgH;AAChH,SAAgB,YAAY,CAAC,IAA4B;IACvD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5E,CAAC;AAED,SAAgB,cAAc,CAAC,IAA4B,EAAE,MAAY;IACvE,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,QAAQ,GAAG,QAAQ,CAAC;IACxB,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;IAC1B,KAAK,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC;YACjB,QAAQ,GAAG,CAAC,CAAC;YACb,UAAU,GAAG,GAAG,CAAC,EAAE,CAAC;QACtB,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxD,OAAO;QACL,MAAM;QACN,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;QACrB,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;QACrB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC;QACzB,UAAU;QACV,OAAO,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;KAChC,CAAC;AACJ,CAAC;AAED,8FAA8F;AAC9F,SAAgB,YAAY,CAAC,EAAU,EAAE,IAA4B,EAAE,MAAmB;IACxF,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC,CAAC;IACnF,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;IAC1F,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;IACpG,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;IAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAErC,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;SAC/C,IAAI,MAAM,GAAG,uBAAe;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC7D,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACjG,IAAI,MAAM,IAAI,uBAAe,IAAI,SAAS,KAAK,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAEtF,OAAO;QACL,EAAE;QACF,OAAO,EAAE,IAAI,CAAC,MAAM;QACpB,KAAK;QACL,YAAY,EAAE,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,EAAE;QACjD,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,QAAQ,IAAI,IAAI,EAAE;QACpF,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC;QAC1B,gBAAgB,EAAE,KAAK,CAAC,GAAG,CAAC;QAC5B,aAAa,EAAE,MAAM,GAAG,uBAAe,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QACvE,eAAe,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,mBAAmB,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI;QAC7E,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI;QAC7D,YAAY,EAAE,KAAK;QACnB,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;QACnE,YAAY,EAAE,YAAY,CAAC,IAAI,CAAC;QAChC,cAAc,EAAE,UAAU,EAAE,OAAO,IAAI,IAAI;QAC3C,YAAY,EAAE,SAAS;QACvB,aAAa,EAAE,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI;QACvE,kBAAkB,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC;QACjE,aAAa,EAAE,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QACxG,cAAc,EAAE,KAAK,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QACjD,kBAAkB,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,CAAC;QAC1D,KAAK;KACN,CAAC;AACJ,CAAC;AAUD,sGAAsG;AACtG,SAAgB,gBAAgB,CAAC,MAAyC,EAAE,IAAsB;IAChG,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAElC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC9C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;;YAC7C,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAChC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC;IAChC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;IAEnC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,4EAA4E,CAAC,CAAC;SAC7G,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,sJAAsJ,CAAC,CAAC;IACrK,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACzC,KAAK,CAAC,IAAI,CACR,mBAAmB,MAAM,0BAA0B;YACjD,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,0BAA0B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAC7E,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACjF,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,WAAW,EAAE,MAAM,CAAC,MAAM;QAC1B,SAAS,EAAE,MAAM;QACjB,MAAM;QACN,MAAM;QACN,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,CAAC;QACxE,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/npc/session.d.ts

@@ -0,0 +1,35 @@
+import type { Page } from 'playwright';
+import { type BrowserKey } from '../browser/launch';
+export declare const DEFAULT_SETTLE_MS = 750;
+export declare const DEFAULT_TIMEOUT_MS = 60000;
+/** What the BUILD says about NPC inspection, read off the installed module rather than guessed. */
+export type NpcInspectSupport = 'supported' | 'predates' | 'unknown';
+/**
+ * Does the engine-core inspect module in this build know about NPCs at all? Only INSTALLED worlds carry
+ * helix_modules/, so a bare bundle answers 'unknown' — which is why the guidance below keeps both causes
+ * in play there instead of confidently naming the wrong one.
+ */
+export declare function detectNpcInspectSupport(directory: string): NpcInspectSupport;
+/** Pure so both causes are unit-testable, and so the two tools word the same failure identically. */
+export declare function composeNpcWiringGuidance(support: NpcInspectSupport): string;
+export interface NpcSessionOptions {
+    directory: string;
+    timeoutMs?: number | undefined;
+    /** Diagnostic override: launch only this candidate, no fallback (default: try the whole chain). */
+    browser?: BrowserKey | undefined;
+    /** URL-prefix → dir fallbacks (e.g. a shared character-asset tree at /assets, /basis). */
+    fallbackMounts?: Record<string, string> | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    onProgress?: ((message: string) => void) | undefined;
+}
+export interface NpcSession {
+    page: Page;
+    close: () => Promise<void>;
+}
+/** Boots the world with the NPC protocol proven live; the caller owns the sampling and MUST close(). */
+export declare function openNpcSession(opts: NpcSessionOptions): Promise<NpcSession>;
+/** One npcSample() call — every read off a world-supplied handle is already guarded page-side. */
+export declare function readSample(page: Page): Promise<unknown[]>;

package/dist/npc/session.js

@@ -0,0 +1,172 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_SETTLE_MS = void 0;
+exports.detectNpcInspectSupport = detectNpcInspectSupport;
+exports.composeNpcWiringGuidance = composeNpcWiringGuidance;
+exports.openNpcSession = openNpcSession;
+exports.readSample = readSample;
+// The transport half of the NPC tools: serve an already-built world, drive it through the in-page
+// inspect helper's NPC protocol (window.__helixInspect.npcSample), and hand back a live page. Modelled
+// on world/snapshotWorld — same launch chain, same page-error ring buffer, same timeout diagnosis —
+// with ONE extra gate: the helper can be ready and still expose no NPC surface, which is a different
+// failure with a different fix, so it gets its own message instead of a TypeError from the page.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const hostSlots_1 = require("../browser/hostSlots");
+const nonSystemChrome_1 = require("../browser/nonSystemChrome");
+const launch_1 = require("../browser/launch");
+const staticServe_1 = require("../screenshot/staticServe");
+const snapshotWorld_1 = require("../world/snapshotWorld");
+const MAX_DIAGNOSTIC_LINES = 6;
+const DIAGNOSTIC_LINE_MAX_CHARS = 300;
+exports.DEFAULT_SETTLE_MS = 750;
+exports.DEFAULT_TIMEOUT_MS = 60000;
+/**
+ * Does the engine-core inspect module in this build know about NPCs at all? Only INSTALLED worlds carry
+ * helix_modules/, so a bare bundle answers 'unknown' — which is why the guidance below keeps both causes
+ * in play there instead of confidently naming the wrong one.
+ */
+function detectNpcInspectSupport(directory) {
+    const module = (0, node_path_1.join)(directory, 'helix_modules', 'engine-core', 'inspect', 'index.js');
+    if (!(0, node_fs_1.existsSync)(module))
+        return 'unknown';
+    try {
+        return (0, node_fs_1.readFileSync)(module, 'utf8').includes('npcSample') ? 'supported' : 'predates';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+const WIRE_LINE = 'world.ready({ scene, body, spawn, npcs, npcState }) — `npcs` is the NpcScene itself, `npcState` an optional ' +
+    '(id) => your own per-NPC behaviour state';
+/** Pure so both causes are unit-testable, and so the two tools word the same failure identically. */
+function composeNpcWiringGuidance(support) {
+    const head = 'This world is ready to inspect but exposes no NPC surface (window.__helixInspect.npcSample is absent).';
+    if (support === 'supported') {
+        return (`${head} The engine-core inspect module IS current in this build, so the world simply never handed over its ` +
+            `NPC pool: pass it — ${WIRE_LINE} — and rebuild. No pin or install change is needed.`);
+    }
+    if (support === 'predates') {
+        return (`${head} The engine-core inspect module in this build predates the NPC leg of the inspect protocol (it has ` +
+            'snapshot() but no npcSample()). Any existing ^0.1 pin already allows the newer one — no helix.json edit ' +
+            'needed, just rerun the install (MCP: install_world_packages · CLI: helix install), pass the pool — ' +
+            `${WIRE_LINE} — and rebuild.`);
+    }
+    return (`${head} Two causes, both fixed before the next build: the world never passed \`npcs\` to world.ready — ` +
+        `${WIRE_LINE} — or the engine-core it was built against predates NPC inspection, in which case rerun the ` +
+        'install (MCP: install_world_packages · CLI: helix install) first. A world with no NPCs at all is the third ' +
+        'possibility, and needs no fix.');
+}
+/** Boots the world with the NPC protocol proven live; the caller owns the sampling and MUST close(). */
+async function openNpcSession(opts) {
+    const onProgress = opts.onProgress ?? (() => undefined);
+    const timeoutMs = opts.timeoutMs ?? exports.DEFAULT_TIMEOUT_MS;
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(opts.directory, 'index.html'))) {
+        throw new Error(`${opts.directory} is not a built world dir (no index.html) — point at the bundle build output (usually <world>/dist).`);
+    }
+    const playwright = await Promise.resolve().then(() => __importStar(require('playwright')));
+    const server = await (0, staticServe_1.startStaticServer)(opts.directory, opts.fallbackMounts ?? {});
+    let browser;
+    try {
+        const attempts = [];
+        for (const candidate of (0, launch_1.selectBrowserCandidates)(opts.browser)) {
+            try {
+                (0, nonSystemChrome_1.assertNotSystemChrome)(candidate.launchOptions.executablePath, candidate.launchOptions.channel);
+                browser = await (0, hostSlots_1.launchWithBrowserSlot)(() => playwright.chromium.launch(candidate.launchOptions), 'disconnected', { identity: `npc-session:${opts.directory}` });
+            }
+            catch (err) {
+                attempts.push({ key: candidate.key, label: candidate.label, message: err instanceof Error ? err.message : String(err) });
+                continue;
+            }
+            onProgress(`using ${candidate.label}`);
+            break;
+        }
+        if (!browser)
+            throw new Error((0, launch_1.composeLaunchFailure)(attempts));
+        const page = await browser.newPage({ viewport: opts.viewport ?? { width: 1280, height: 720 }, deviceScaleFactor: 1 });
+        const pageErrors = [];
+        const recordPageError = (line) => {
+            const truncated = line.length > DIAGNOSTIC_LINE_MAX_CHARS ? `${line.slice(0, DIAGNOSTIC_LINE_MAX_CHARS)}…` : line;
+            pageErrors.push(truncated);
+            if (pageErrors.length > MAX_DIAGNOSTIC_LINES)
+                pageErrors.shift();
+        };
+        page.on('pageerror', (err) => recordPageError(err.message));
+        page.on('console', (msg) => {
+            if (msg.type() === 'error')
+                recordPageError(msg.text());
+        });
+        await page.goto(`http://127.0.0.1:${server.port}/?helixInspect=1`);
+        try {
+            await page.waitForFunction('window.__helixInspect?.ready === true', undefined, { timeout: timeoutMs });
+        }
+        catch {
+            const helperState = await page.evaluate(() => typeof window.__helixInspect === 'undefined' ? 'absent' : 'present');
+            const engineCoreInstalled = (0, node_fs_1.existsSync)((0, node_path_1.join)(opts.directory, 'helix_modules'))
+                ? (0, node_fs_1.existsSync)((0, node_path_1.join)(opts.directory, 'helix_modules', 'engine-core', 'inspect', 'index.js'))
+                : undefined;
+            throw new Error(`Timed out after ${timeoutMs}ms waiting for the inspect helper (window.__helixInspect) to become ready. ` +
+                (0, snapshotWorld_1.composeInspectTimeoutDiagnosis)(helperState, pageErrors, engineCoreInstalled));
+        }
+        const hasNpcs = await page.evaluate(() => typeof window.__helixInspect?.npcSample === 'function');
+        if (!hasNpcs)
+            throw new Error(composeNpcWiringGuidance(detectNpcInspectSupport(opts.directory)));
+        const close = async () => {
+            try {
+                await browser?.close();
+            }
+            finally {
+                await server.close();
+            }
+        };
+        return { page, close };
+    }
+    catch (err) {
+        try {
+            await browser?.close();
+        }
+        finally {
+            await server.close();
+        }
+        throw err;
+    }
+}
+/** One npcSample() call — every read off a world-supplied handle is already guarded page-side. */
+async function readSample(page) {
+    const rows = await page.evaluate(() => window.__helixInspect.npcSample());
+    return Array.isArray(rows) ? rows : [];
+}
+//# sourceMappingURL=session.js.map

package/dist/npc/session.js.map

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