@pascal-app/viewer 1.0.0-beta.5 → 1.0.1

package/dist/lib/perf-actions.d.ts

@@ -0,0 +1,55 @@
+export type PerfActionReceipt = {
+    name: string;
+    /** Free-form context, e.g. the node id or kind. */
+    detail: string;
+    /** begin → commit (the human gesture; 0 for instant actions like undo). */
+    dragMs: number;
+    /** commit → fully settled (rebuilds + one GPU sample after quiet). */
+    settleMs: number;
+    /** begin → settled. */
+    totalMs: number;
+    /** Frames observed between commit and settled. */
+    settleFrames: number;
+    /** Per-track attribution over begin → settled, sorted by totalMs desc. */
+    tracks: Array<{
+        name: string;
+        totalMs: number;
+        count: number;
+    }>;
+    outcome: 'settled' | 'interrupted' | 'timeout';
+    endedAt: number;
+};
+/**
+ * Start attributing samples to a named action. Interrupts any active one.
+ * Returns an id the caller can compare against `getActivePerfActionId()` to
+ * commit only the action it actually began.
+ */
+export declare function beginPerfAction(name: string, detail?: string): number | null;
+/** The gesture ended (pointer up / operation dispatched); settling begins. */
+export declare function commitPerfAction(): void;
+/** The gesture was aborted (Escape mid-drag); discard without a settle wait. */
+export declare function cancelPerfAction(): void;
+/** Convenience for instant actions (undo, level switch): begin + commit. */
+export declare function markPerfAction(name: string, detail?: string): void;
+/**
+ * Whether an action is currently being attributed. Lets a generic call site
+ * (the interaction scope) yield to a more specific one that began first.
+ */
+export declare function hasActivePerfAction(): boolean;
+/**
+ * Like `hasActivePerfAction`, but false once the active action has committed.
+ * A generic bracket yields to an UNCOMMITTED action (a gesture in flight) but
+ * must be free to start a new receipt while the previous one is merely
+ * settling — beginPerfAction then finalizes the settling one as interrupted.
+ */
+export declare function hasUncommittedPerfAction(): boolean;
+/** Id of the action currently attributing samples, if any. */
+export declare function getActivePerfActionId(): number | null;
+/**
+ * Called once per frame by the viewer settle system with the current dirty
+ * count and the wall system's deferred-neighbour backlog. Also the ledger's
+ * only heartbeat, so it is where a stuck action gets released.
+ */
+export declare function notifyPerfActionFrame(dirtyCount: number, pendingRebuilds: number): void;
+export declare function usePerfActionReceipts(): PerfActionReceipt[];
+//# sourceMappingURL=perf-actions.d.ts.map

package/dist/lib/perf-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-actions.d.ts","sourceRoot":"","sources":["../../src/lib/perf-actions.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAA;IAChB,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC/D,OAAO,EAAE,SAAS,GAAG,aAAa,GAAG,SAAS,CAAA;IAC9C,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AA8FD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,GAAG,IAAI,CAmCxE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,IAAI,CAG9D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED,8DAA8D;AAC9D,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,CAgBvF;AAgBD,wBAAgB,qBAAqB,IAAI,iBAAiB,EAAE,CAE3D"}

package/dist/lib/perf-actions.js

@@ -0,0 +1,211 @@
+// Action-cost ledger for `?perf`.
+//
+// An "action" is one user edit gesture: a wall-endpoint drag, a door move, an
+// undo, a level switch. The editor package brackets the gesture with
+// `beginPerfAction` / `commitPerfAction`; every perf-tracks sample recorded in
+// between (wall-csg, geometry, react-render, gpu-render, …) is attributed to
+// it. The action is "settled" only when the scene has finished digesting the
+// edit: dirty queue empty, deferred wall neighbour rebuilds flushed, and one
+// more GPU sample resolved after that — i.e. the user actually sees the final
+// result. The settle system in the viewer feeds that state per frame via
+// `notifyPerfActionFrame`.
+//
+// Everything is a no-op without `?perf`.
+import { useSyncExternalStore } from 'react';
+import { PERF_OVERLAY_ENABLED } from './gpu-perf';
+import { subscribePerfSamples } from './perf-tracks';
+const SETTLE_TIMEOUT_MS = 5000;
+// A gesture that begins and never commits (a hover preview, a drag whose
+// pointerup never reached the caller) is never settle-checked, so without an
+// absolute cap it would hold its sample subscription — and keep growing its
+// buckets — for the rest of the session.
+const UNCOMMITTED_TIMEOUT_MS = 60_000;
+const MAX_RECEIPTS = 5;
+let active = null;
+let actionSeq = 0;
+// Whether this device has ever produced a real timestamp-query sample. Without
+// `timestamp-query` support no 'gpu-render' sample can ever arrive, so settle
+// falls back to the queue fence — see the sample listener below.
+let gpuTimestampsSeen = false;
+let receipts = [];
+const listeners = new Set();
+function emitReceipts() {
+    for (const listener of listeners)
+        listener();
+}
+function finalize(outcome) {
+    const action = active;
+    if (!action)
+        return;
+    active = null;
+    action.unsubscribe();
+    const now = performance.now();
+    const committedAt = action.committedAt ?? now;
+    const receipt = {
+        name: action.name,
+        detail: action.detail,
+        dragMs: committedAt - action.startedAt,
+        settleMs: now - committedAt,
+        totalMs: now - action.startedAt,
+        settleFrames: action.settleFrames,
+        tracks: [...action.buckets.entries()]
+            .map(([name, b]) => ({ name, totalMs: b.totalMs, count: b.count }))
+            .sort((a, b) => b.totalMs - a.totalMs),
+        outcome,
+        endedAt: now,
+    };
+    receipts = [receipt, ...receipts].slice(0, MAX_RECEIPTS);
+    emitReceipts();
+    // One timeline entry per action so recordings show the full span with its
+    // breakdown attached.
+    try {
+        performance.measure(`${action.name}${action.detail ? ` ${action.detail}` : ''}`, {
+            start: action.startedAt,
+            end: now,
+            detail: {
+                devtools: {
+                    dataType: 'track-entry',
+                    track: 'Actions',
+                    trackGroup: 'Pascal',
+                    color: outcome === 'settled' ? 'secondary' : 'error',
+                    properties: [
+                        ['outcome', outcome],
+                        ['drag ms', receipt.dragMs.toFixed(1)],
+                        ['settle ms', receipt.settleMs.toFixed(1)],
+                        ...receipt.tracks
+                            .slice(0, 6)
+                            .map((t) => [t.name, `${t.totalMs.toFixed(1)}ms (${t.count}×)`]),
+                    ],
+                },
+            },
+        });
+    }
+    catch { }
+    // eslint-disable-next-line no-console
+    console.log(`[perf] ${action.name}${action.detail ? ` (${action.detail})` : ''}: ` +
+        `${receipt.totalMs.toFixed(0)}ms total — drag ${receipt.dragMs.toFixed(0)}, ` +
+        `settle ${receipt.settleMs.toFixed(0)} over ${receipt.settleFrames} frames [${outcome}] — ` +
+        receipt.tracks
+            .slice(0, 6)
+            .map((t) => `${t.name} ${t.totalMs.toFixed(1)}ms`)
+            .join(', '));
+}
+/**
+ * Start attributing samples to a named action. Interrupts any active one.
+ * Returns an id the caller can compare against `getActivePerfActionId()` to
+ * commit only the action it actually began.
+ */
+export function beginPerfAction(name, detail = '') {
+    if (!PERF_OVERLAY_ENABLED)
+        return null;
+    if (active)
+        finalize('interrupted');
+    const id = ++actionSeq;
+    const buckets = new Map();
+    active = {
+        id,
+        name,
+        detail,
+        startedAt: performance.now(),
+        committedAt: null,
+        settleFrames: 0,
+        awaitingGpu: false,
+        buckets,
+        unsubscribe: subscribePerfSamples((track, ms) => {
+            const bucket = buckets.get(track);
+            if (bucket) {
+                bucket.totalMs += ms;
+                bucket.count += 1;
+            }
+            else {
+                buckets.set(track, { totalMs: ms, count: 1 });
+            }
+            if (track === 'gpu-render')
+                gpuTimestampsSeen = true;
+            // A GPU sample landing after the quiet point is the settle signal. On
+            // devices without timestamp-query no 'gpu-render' sample ever arrives —
+            // the queue fence is the closest "the user saw it" stand-in there.
+            if (active?.awaitingGpu &&
+                (track === 'gpu-render' || (!gpuTimestampsSeen && track === 'gpu-queue'))) {
+                finalize('settled');
+            }
+        }),
+    };
+    return id;
+}
+/** The gesture ended (pointer up / operation dispatched); settling begins. */
+export function commitPerfAction() {
+    if (!active || active.committedAt !== null)
+        return;
+    active.committedAt = performance.now();
+}
+/** The gesture was aborted (Escape mid-drag); discard without a settle wait. */
+export function cancelPerfAction() {
+    if (!active)
+        return;
+    finalize('interrupted');
+}
+/** Convenience for instant actions (undo, level switch): begin + commit. */
+export function markPerfAction(name, detail = '') {
+    beginPerfAction(name, detail);
+    commitPerfAction();
+}
+/**
+ * Whether an action is currently being attributed. Lets a generic call site
+ * (the interaction scope) yield to a more specific one that began first.
+ */
+export function hasActivePerfAction() {
+    return active !== null;
+}
+/**
+ * Like `hasActivePerfAction`, but false once the active action has committed.
+ * A generic bracket yields to an UNCOMMITTED action (a gesture in flight) but
+ * must be free to start a new receipt while the previous one is merely
+ * settling — beginPerfAction then finalizes the settling one as interrupted.
+ */
+export function hasUncommittedPerfAction() {
+    return active !== null && active.committedAt === null;
+}
+/** Id of the action currently attributing samples, if any. */
+export function getActivePerfActionId() {
+    return active?.id ?? null;
+}
+/**
+ * Called once per frame by the viewer settle system with the current dirty
+ * count and the wall system's deferred-neighbour backlog. Also the ledger's
+ * only heartbeat, so it is where a stuck action gets released.
+ */
+export function notifyPerfActionFrame(dirtyCount, pendingRebuilds) {
+    const action = active;
+    if (!action)
+        return;
+    const now = performance.now();
+    if (action.committedAt === null) {
+        if (now - action.startedAt > UNCOMMITTED_TIMEOUT_MS)
+            finalize('interrupted');
+        return;
+    }
+    action.settleFrames += 1;
+    if (now - action.committedAt > SETTLE_TIMEOUT_MS) {
+        finalize('timeout');
+        return;
+    }
+    if (!action.awaitingGpu && dirtyCount === 0 && pendingRebuilds === 0) {
+        action.awaitingGpu = true;
+    }
+}
+// Module-level so the panel's twice-a-second re-render doesn't tear the
+// subscription down and rebuild it; `receipts` is replaced, never mutated, so
+// the snapshot is stable between finalizes.
+function subscribeReceipts(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+function getReceipts() {
+    return receipts;
+}
+export function usePerfActionReceipts() {
+    return useSyncExternalStore(subscribeReceipts, getReceipts, getReceipts);
+}

package/dist/lib/perf-observers.d.ts

@@ -0,0 +1,2 @@
+export declare function initPerfObservers(): void;
+//# sourceMappingURL=perf-observers.d.ts.map

package/dist/lib/perf-observers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-observers.d.ts","sourceRoot":"","sources":["../../src/lib/perf-observers.ts"],"names":[],"mappings":"AAKA,wBAAgB,iBAAiB,IAAI,IAAI,CAYxC"}

package/dist/lib/perf-observers.js

@@ -0,0 +1,17 @@
+import { PERF_OVERLAY_ENABLED } from './gpu-perf';
+import { recordPerfSample } from './perf-tracks';
+let initialized = false;
+export function initPerfObservers() {
+    if (!PERF_OVERLAY_ENABLED || initialized)
+        return;
+    initialized = true;
+    try {
+        const observer = new PerformanceObserver((list) => {
+            for (const entry of list.getEntries()) {
+                recordPerfSample('long-task', entry.duration);
+            }
+        });
+        observer.observe({ type: 'longtask', buffered: true });
+    }
+    catch { }
+}

package/dist/lib/perf-panel-store.d.ts

@@ -0,0 +1,71 @@
+export type PerfTrackLine = {
+    name: string;
+    totalMs: number;
+    count: number;
+    maxMs: number;
+};
+export type PerfStats = {
+    fps: number;
+    frameMs: number;
+    frameMaxMs: number;
+    encodeMs: number;
+    encodeMaxMs: number;
+    gpuMs: number;
+    gpuMaxMs: number;
+    gpuTracked: boolean;
+    queueMs: number;
+    queueMaxMs: number;
+    drawCalls: number;
+    triangles: number;
+    batch: PerfBatchStats;
+    dirty: number;
+    dirtyDetail: string;
+    geometries: number;
+    textures: number;
+    gpuBytes: number;
+    heapBytes: number;
+    meshes: number;
+    lines: number;
+    sprites: number;
+    lights: number;
+    tracks: PerfTrackLine[];
+};
+export declare function publishPerfStats(stats: PerfStats): void;
+export declare function usePerfStats(): PerfStats | null;
+/**
+ * Batch membership, published by the batch systems themselves (the panel's
+ * collector cannot read their stores across packages). Stable truth — items
+ * and instances currently drawn through batch containers — unlike the
+ * per-pass `_multiDrawCount`, which snapshots whichever camera (main, shadow,
+ * outline) culled the batch last and flips between passes. On WebGPU each
+ * batched instance still counts once in `drawCalls` (the backend loops
+ * drawIndexed per visible instance), so without this row a batched scene
+ * looks no cheaper than an unbatched one — the saving is encode cost per
+ * call, not call count.
+ */
+export type PerfBatchStats = {
+    items: number;
+    instances: number;
+    containers: number;
+    releases?: number;
+    joins?: number;
+    geometryReplacements?: number;
+    overflowRebuilds?: number;
+    wallDrain?: {
+        initialBuildActive: boolean;
+        wallsConsumedThisFrame: number;
+        budgetExits: number;
+        heavyExits: number;
+        drainedExits: number;
+        capExits: number;
+        pendingNeighbours: number;
+        firstBuilds: number;
+        reinvalidationBuilds: number;
+        neighbourEnqueues: number;
+    };
+    geometryBytesCopied?: number;
+};
+export declare function publishPerfBatchStats(stats: Partial<PerfBatchStats>): void;
+export declare function publishPerfWallDrainStats(stats: NonNullable<PerfBatchStats['wallDrain']>): void;
+export declare function readPerfBatchStats(): PerfBatchStats;
+//# sourceMappingURL=perf-panel-store.d.ts.map

package/dist/lib/perf-panel-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-panel-store.d.ts","sourceRoot":"","sources":["../../src/lib/perf-panel-store.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3F,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,OAAO,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,cAAc,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,aAAa,EAAE,CAAA;CACxB,CAAA;AAKD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAGvD;AAOD,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAM/C;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,SAAS,CAAC,EAAE;QACV,kBAAkB,EAAE,OAAO,CAAA;QAC3B,sBAAsB,EAAE,MAAM,CAAA;QAC9B,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,EAAE,MAAM,CAAA;QAClB,YAAY,EAAE,MAAM,CAAA;QACpB,QAAQ,EAAE,MAAM,CAAA;QAChB,iBAAiB,EAAE,MAAM,CAAA;QACzB,WAAW,EAAE,MAAM,CAAA;QACnB,oBAAoB,EAAE,MAAM,CAAA;QAC5B,iBAAiB,EAAE,MAAM,CAAA;KAC1B,CAAA;IACD,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AAID,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAE1E;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,WAAW,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC,GAAG,IAAI,CAE/F;AAED,wBAAgB,kBAAkB,IAAI,cAAc,CAEnD"}

package/dist/lib/perf-panel-store.js

@@ -0,0 +1,29 @@
+// Bridge between the in-canvas collector (perf-monitor.tsx, R3F reconciler)
+// and the DOM panel (perf-panel.tsx). react-dom portals can't cross the R3F
+// renderer boundary, so the collector publishes here and the panel — mounted
+// outside <Canvas> — subscribes via useSyncExternalStore.
+import { useSyncExternalStore } from 'react';
+let current = null;
+const listeners = new Set();
+export function publishPerfStats(stats) {
+    current = stats;
+    for (const listener of listeners)
+        listener();
+}
+function subscribe(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+export function usePerfStats() {
+    return useSyncExternalStore(subscribe, () => current, () => null);
+}
+let batchStats = { items: 0, instances: 0, containers: 0 };
+export function publishPerfBatchStats(stats) {
+    batchStats = { ...batchStats, ...stats };
+}
+export function publishPerfWallDrainStats(stats) {
+    batchStats.wallDrain = stats;
+}
+export function readPerfBatchStats() {
+    return batchStats;
+}

package/dist/lib/perf-tracks.d.ts

@@ -0,0 +1,43 @@
+export type PerfCounterBucket = {
+    totalMs: number;
+    maxMs: number;
+    count: number;
+};
+/** DevTools palette names accepted by the extensibility API. */
+export type PerfTrackColor = 'primary' | 'primary-light' | 'primary-dark' | 'secondary' | 'secondary-light' | 'secondary-dark' | 'tertiary' | 'tertiary-light' | 'tertiary-dark' | 'error';
+type PerfSampleListener = (track: string, ms: number) => void;
+export declare function subscribePerfSamples(listener: PerfSampleListener): () => void;
+/**
+ * Time a synchronous block and file it under `track`. The label defaults to
+ * the track name; pass `name` for per-entry granularity (e.g. a node id) —
+ * it only affects the DevTools lane, not the aggregate bucket.
+ */
+export declare function timeSpan<T>(track: string, fn: () => T, opts?: {
+    name?: string;
+    color?: PerfTrackColor;
+    properties?: Array<[string, string]>;
+}): T;
+/**
+ * Span for non-callback shapes (spans crossing await points or frames).
+ * `beginSpan` returns null when perf is off — callers pass the handle back to
+ * `endSpan`, which no-ops on null.
+ */
+export type PerfSpanHandle = {
+    track: string;
+    name: string;
+    start: number;
+    color: PerfTrackColor;
+};
+export declare function beginSpan(track: string, opts?: {
+    name?: string;
+    color?: PerfTrackColor;
+}): PerfSpanHandle | null;
+export declare function endSpan(handle: PerfSpanHandle | null, properties?: Array<[string, string]>): void;
+/** Record a duration measured externally (no measure emitted). */
+export declare function recordPerfSample(track: string, ms: number): void;
+/** Hand the current window's buckets to the overlay and start a new window. */
+export declare function drainPerfCounters(): Map<string, PerfCounterBucket>;
+/** Drop accumulated timeline entries so long `?perf` sessions don't leak. */
+export declare function clearPerfMeasures(): void;
+export {};
+//# sourceMappingURL=perf-tracks.d.ts.map

package/dist/lib/perf-tracks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-tracks.d.ts","sourceRoot":"","sources":["../../src/lib/perf-tracks.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,gEAAgE;AAChE,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,eAAe,GACf,cAAc,GACd,WAAW,GACX,iBAAiB,GACjB,gBAAgB,GAChB,UAAU,GACV,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAA;AAOX,KAAK,kBAAkB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;AAG7D,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAG7E;AAyCD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,CAAC,EACX,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GACrF,CAAC,CAUH;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAA;AAElG,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,cAAc,CAAA;CAAE,GAC/C,cAAc,GAAG,IAAI,CAQvB;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,EAAE,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAKjG;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAGhE;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,IAAI,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAIlE;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,IAAI,IAAI,CAOxC"}

package/dist/lib/perf-tracks.js

@@ -0,0 +1,113 @@
+// Shared sink for `?perf` instrumentation.
+//
+// Two outputs from one call site:
+//  1. Chrome DevTools Performance panel custom tracks — every span becomes a
+//     `performance.measure` with a `detail.devtools` payload, so Pascal systems
+//     show up as named lanes in the flame chart while recording.
+//  2. Per-window aggregates — `drainPerfCounters()` hands the overlay one
+//     bucket per track (total/max/count since the last drain), so the panel can
+//     print "wall-csg 9.8ms" without touching the timeline.
+//
+// Everything is gated on PERF_OVERLAY_ENABLED: when `?perf` is absent the
+// helpers reduce to calling `fn()` directly / returning early, so hot paths pay
+// only a boolean check. Measures otherwise accumulate in the browser's
+// timeline buffer indefinitely — the overlay is responsible for calling
+// `clearPerfMeasures()` on its drain tick.
+import { PERF_OVERLAY_ENABLED } from './gpu-perf';
+const counters = new Map();
+const sampleListeners = new Set();
+export function subscribePerfSamples(listener) {
+    sampleListeners.add(listener);
+    return () => sampleListeners.delete(listener);
+}
+function record(track, ms) {
+    const bucket = counters.get(track);
+    if (bucket) {
+        bucket.totalMs += ms;
+        bucket.count += 1;
+        if (ms > bucket.maxMs)
+            bucket.maxMs = ms;
+    }
+    else {
+        counters.set(track, { totalMs: ms, maxMs: ms, count: 1 });
+    }
+    for (const listener of sampleListeners)
+        listener(track, ms);
+}
+function emitMeasure(track, name, start, end, color, properties) {
+    try {
+        performance.measure(name, {
+            start,
+            end,
+            detail: {
+                devtools: {
+                    dataType: 'track-entry',
+                    track,
+                    trackGroup: 'Pascal',
+                    color,
+                    ...(properties ? { properties } : {}),
+                },
+            },
+        });
+    }
+    catch {
+        // Older browsers reject the options bag — aggregates still work.
+    }
+}
+/**
+ * Time a synchronous block and file it under `track`. The label defaults to
+ * the track name; pass `name` for per-entry granularity (e.g. a node id) —
+ * it only affects the DevTools lane, not the aggregate bucket.
+ */
+export function timeSpan(track, fn, opts) {
+    if (!PERF_OVERLAY_ENABLED)
+        return fn();
+    const start = performance.now();
+    try {
+        return fn();
+    }
+    finally {
+        const end = performance.now();
+        record(track, end - start);
+        emitMeasure(track, opts?.name ?? track, start, end, opts?.color ?? 'primary', opts?.properties);
+    }
+}
+export function beginSpan(track, opts) {
+    if (!PERF_OVERLAY_ENABLED)
+        return null;
+    return {
+        track,
+        name: opts?.name ?? track,
+        start: performance.now(),
+        color: opts?.color ?? 'primary',
+    };
+}
+export function endSpan(handle, properties) {
+    if (!handle)
+        return;
+    const end = performance.now();
+    record(handle.track, end - handle.start);
+    emitMeasure(handle.track, handle.name, handle.start, end, handle.color, properties);
+}
+/** Record a duration measured externally (no measure emitted). */
+export function recordPerfSample(track, ms) {
+    if (!PERF_OVERLAY_ENABLED)
+        return;
+    record(track, ms);
+}
+/** Hand the current window's buckets to the overlay and start a new window. */
+export function drainPerfCounters() {
+    const out = new Map(counters);
+    counters.clear();
+    return out;
+}
+/** Drop accumulated timeline entries so long `?perf` sessions don't leak. */
+export function clearPerfMeasures() {
+    try {
+        performance.clearMeasures();
+        performance.clearMarks();
+    }
+    catch {
+        // ignore
+    }
+}

package/dist/lib/pointer-events.d.ts

@@ -0,0 +1,7 @@
+import { events as createWebEvents, type EventManager, type RootStore } from '@react-three/fiber';
+import * as THREE from 'three';
+/** Opt in only when the raycast appends hits without reading prior hits or mutating scene/query state. */
+export declare function markPureRaycast<T extends THREE.Object3D['raycast']>(raycast: T): T;
+export declare function choosePointerEvents(search?: string): typeof createWebEvents;
+export declare function createPascalPointerEvents(store: RootStore): EventManager<HTMLElement>;
+//# sourceMappingURL=pointer-events.d.ts.map

package/dist/lib/pointer-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer-events.d.ts","sourceRoot":"","sources":["../../src/lib/pointer-events.ts"],"names":[],"mappings":"AA6BA,OAAO,EACL,MAAM,IAAI,eAAe,EAGzB,KAAK,YAAY,EAMjB,KAAK,SAAS,EAEf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAqC9B,0GAA0G;AAC1G,wBAAgB,eAAe,CAAC,CAAC,SAAS,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAGlF;AAYD,wBAAgB,mBAAmB,CACjC,MAAM,SAA8D,GACnE,OAAO,eAAe,CAIxB;AAiLD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAAC,WAAW,CAAC,CAmBrF"}