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

package/dist/lib/merged-outline-node.js

@@ -2,20 +2,17 @@
 // this file is a fork of OutlineNode and is intentionally exempt from strict TS checking.
 /**
  * MergedOutlineNode — a fork of Three.js OutlineNode that processes two object
- * groups (primary = selected, secondary = hovered) in a single pass, sharing the
- * expensive non-selected depth pre-render between both groups.
- *
- * Cost comparison vs two separate OutlineNode instances:
- *   Before: depth_A + mask_A + edge_A×6 + depth_B + mask_B + edge_B×6 = 2 depth passes
- *   After:  depth_AB (shared) + mask_A + edge_A×6 + mask_B + edge_B×6 = 1 depth pass
+ * groups (primary = selected, secondary = hovered), reusing scene depth when
+ * supplied and rendering masks from small private scenes. Callers without scene
+ * depth retain one shared non-selected depth pass for both groups.
  *
  * Additional early-outs:
  *   - Both empty       → skip everything (0 passes)
  *   - Only primary     → skip secondary mask/edge/blur
  *   - Only secondary   → skip primary mask/edge/blur
  */
-import { DepthTexture, FloatType, RenderTarget, Vector2 } from 'three';
-import { color, exp, Fn, float, int, Loop, min, mul, nodeObject, orthographicDepthToViewZ, passTexture, perspectiveDepthToViewZ, positionView, reference, screenUV, texture, textureSize, uniform, uv, vec2, vec3, vec4, } from 'three/tsl';
+import { DepthTexture, FloatType, Mesh, Object3D, RenderTarget, Scene, Sprite, Vector2, } from 'three';
+import { builtin, color, exp, Fn, float, floatBitsToUint, int, Loop, min, mul, nodeObject, orthographicDepthToViewZ, passTexture, perspectiveDepthToViewZ, positionView, reference, screenUV, texture, textureSize, uniform, uv, vec2, vec3, vec4, } from 'three/tsl';
 import { NodeMaterial, NodeUpdateType, QuadMesh, RendererUtils, SpriteNodeMaterial, TempNode, } from 'three/webgpu';
 import { hasDrawableGeometry } from './drawable-geometry';
 const _quadMesh = new QuadMesh();
@@ -27,6 +24,8 @@ let _rendererState; // eslint-disable-line @typescript-eslint/no-explicit-any
 // Helper: render targets for one outline group
 // ---------------------------------------------------------------------------
 function makeGroupTargets(downSampleRatio) {
+    // Preserve the original pixel-center mask coverage. MSAA-resolved masks mix
+    // visible/background samples into hidden edges before edge detection.
     const maskBuffer = new RenderTarget();
     const maskDownSample = new RenderTarget(1, 1, { depthBuffer: false });
     const edgeBuffer1 = new RenderTarget(1, 1, { depthBuffer: false });
@@ -85,6 +84,7 @@ export class MergedOutlineNode extends TempNode {
     secondaryEdgeGlowNode;
     downSampleRatio;
     updateBeforeType;
+    _sceneDepthNode;
     _depthRT;
     _depthTexUniform;
     _groupA;
@@ -121,6 +121,11 @@ export class MergedOutlineNode extends TempNode {
     _compositeMatB;
     _cacheA = new Set();
     _cacheB = new Set();
+    _proxiesA = new Map();
+    _proxiesB = new Map();
+    _proxyMaskMaterials = new WeakMap();
+    _maskSceneA = new Scene();
+    _maskSceneB = new Scene();
     // Tracks whether either group rendered last frame. We use this to decide
     // when it's safe to skip renderer state manipulation entirely — touching
     // the renderer (resetRendererAndSceneState + setRenderTarget + clearColor)
@@ -132,7 +137,12 @@ export class MergedOutlineNode extends TempNode {
     _textureNodeB;
     constructor(scene, camera, params = {}) {
         super('vec4');
-        const { primaryObjects = [], secondaryObjects = [], primaryEdgeThickness = float(1), secondaryEdgeThickness = float(1), primaryEdgeGlow = float(0), secondaryEdgeGlow = float(0), downSampleRatio = 2, } = params;
+        const { primaryObjects = [], secondaryObjects = [], primaryEdgeThickness = float(1), secondaryEdgeThickness = float(1), primaryEdgeGlow = float(0), secondaryEdgeGlow = float(0), downSampleRatio = 2, sceneDepthNode = null, } = params;
+        this._sceneDepthNode = sceneDepthNode;
+        this._maskSceneA.matrixWorldAutoUpdate = false;
+        this._maskSceneB.matrixWorldAutoUpdate = false;
+        this._maskSceneA.name = 'MergedOutline [ Mask A ]';
+        this._maskSceneB.name = 'MergedOutline [ Mask B ]';
         this.scene = scene;
         this.camera = camera;
         this.primaryObjects = primaryObjects;
@@ -233,6 +243,11 @@ export class MergedOutlineNode extends TempNode {
         }
         const { renderer } = frame;
         const { camera, scene } = this;
+        // Update the producer before resetting renderer state, even if this outline
+        // is the first consumer in the graph. NodeFrame deduplicates FRAME updates.
+        if (hasAny && this._sceneDepthNode?.passNode) {
+            frame.updateBeforeNode(this._sceneDepthNode.passNode);
+        }
         _rendererState = RendererUtils.resetRendererAndSceneState(renderer, scene, _rendererState);
         const size = renderer.getDrawingBufferSize(_size);
         this.setSize(size.width, size.height);
@@ -248,6 +263,10 @@ export class MergedOutlineNode extends TempNode {
             renderer.clearColor();
             this._wroteGroupBLastFrame = false;
         }
+        this._buildCache(this.primaryObjects, this._cacheA);
+        this._buildCache(this.secondaryObjects, this._cacheB);
+        const useProxiesA = this._syncProxies(this._cacheA, this._proxiesA, this._maskSceneA);
+        const useProxiesB = this._syncProxies(this._cacheB, this._proxiesB, this._maskSceneB);
         if (!hasAny) {
             RendererUtils.restoreRendererAndSceneState(renderer, scene, _rendererState);
             return;
@@ -255,55 +274,26 @@ export class MergedOutlineNode extends TempNode {
         renderer.setClearColor(0xff_ff_ff, 1);
         this._wroteGroupALastFrame = hasPrimary;
         this._wroteGroupBLastFrame = hasSecondary;
-        if (hasPrimary)
-            this._buildCache(this.primaryObjects, this._cacheA);
-        if (hasSecondary)
-            this._buildCache(this.secondaryObjects, this._cacheB);
         const savedName = scene.name;
-        // ── 1. Shared depth pass: all objects NOT in either group ─────────────────
-        renderer.setRenderTarget(this._depthRT);
-        renderer.setRenderObjectFunction((obj, sc, cam, geo, _mat, grp, lights, clip) => {
-            if (!hasDrawableGeometry(geo))
-                return;
-            const inCache = this._cacheA.has(obj) || this._cacheB.has(obj);
-            if (!inCache) {
-                const m = obj.isSprite ? this._depthSpriteMaterial : this._depthMaterial;
-                renderer.renderObject(obj, sc, cam, geo, m, grp, lights, clip);
-            }
-        });
-        scene.name = 'MergedOutline [ Depth ]';
-        renderer.render(scene, camera);
-        // ── 2a. Primary mask pass ─────────────────────────────────────────────────
-        if (hasPrimary) {
-            renderer.setRenderTarget(this._groupA.maskBuffer);
-            renderer.setRenderObjectFunction((obj, sc, cam, geo, _mat, grp, lights, clip) => {
-                if (!hasDrawableGeometry(geo))
-                    return;
-                if (this._cacheA.has(obj)) {
-                    const m = obj.isSprite ? this._prepareMaskSpriteMatA : this._prepareMaskMatA;
-                    renderer.renderObject(obj, sc, cam, geo, m, grp, lights, clip);
-                }
-            });
-            scene.name = 'MergedOutline [ Mask A ]';
-            renderer.render(scene, camera);
-        }
-        // ── 2b. Secondary mask pass ───────────────────────────────────────────────
-        if (hasSecondary) {
-            renderer.setRenderTarget(this._groupB.maskBuffer);
+        if (!this._sceneDepthNode) {
+            renderer.setRenderTarget(this._depthRT);
             renderer.setRenderObjectFunction((obj, sc, cam, geo, _mat, grp, lights, clip) => {
                 if (!hasDrawableGeometry(geo))
                     return;
-                if (this._cacheB.has(obj)) {
-                    const m = obj.isSprite ? this._prepareMaskSpriteMatB : this._prepareMaskMatB;
+                if (!(this._cacheA.has(obj) || this._cacheB.has(obj))) {
+                    const m = obj.isSprite ? this._depthSpriteMaterial : this._depthMaterial;
                     renderer.renderObject(obj, sc, cam, geo, m, grp, lights, clip);
                 }
             });
-            scene.name = 'MergedOutline [ Mask B ]';
+            scene.name = 'MergedOutline [ Depth ]';
             renderer.render(scene, camera);
         }
+        // The fallback depth render may have updated source matrices since sync.
+        if (hasPrimary)
+            this._renderMask(renderer, 'A', useProxiesA);
+        if (hasSecondary)
+            this._renderMask(renderer, 'B', useProxiesB);
         renderer.setRenderObjectFunction(_rendererState.renderObjectFunction);
-        this._cacheA.clear();
-        this._cacheB.clear();
         scene.name = savedName;
         // ── 3–7. Edge detect + blur + composite per active group ──────────────────
         if (hasPrimary)
@@ -312,6 +302,117 @@ export class MergedOutlineNode extends TempNode {
             this._runEdgePipeline(renderer, 'B');
         RendererUtils.restoreRendererAndSceneState(renderer, scene, _rendererState);
     }
+    _renderMask(renderer, group, useProxies) {
+        const isA = group === 'A';
+        const cache = isA ? this._cacheA : this._cacheB;
+        const proxies = isA ? this._proxiesA : this._proxiesB;
+        const maskScene = isA ? this._maskSceneA : this._maskSceneB;
+        const material = isA ? this._prepareMaskMatA : this._prepareMaskMatB;
+        const spriteMaterial = isA ? this._prepareMaskSpriteMatA : this._prepareMaskSpriteMatB;
+        if (useProxies) {
+            for (const [source, proxy] of proxies)
+                proxy.matrixWorld.copy(source.matrixWorld);
+        }
+        renderer.setRenderTarget((isA ? this._groupA : this._groupB).maskBuffer);
+        // Keep source materials on proxies for material visibility and geometry
+        // groups; substitute only at submission, just like the full-scene path.
+        renderer.setRenderObjectFunction((obj, sc, cam, geo, _mat, grp, lights, clip) => {
+            if (!hasDrawableGeometry(geo))
+                return;
+            if (useProxies || cache.has(obj)) {
+                let maskMaterial = obj.isSprite ? spriteMaterial : material;
+                if (useProxies) {
+                    let ownedMaterial = this._proxyMaskMaterials.get(obj);
+                    if (!ownedMaterial) {
+                        // Disposing this private material releases the proxy's RenderObjects
+                        // without disposing geometry or materials owned by the source scene.
+                        ownedMaterial = maskMaterial.clone();
+                        this._proxyMaskMaterials.set(obj, ownedMaterial);
+                    }
+                    if (ownedMaterial.colorNode !== maskMaterial.colorNode) {
+                        ownedMaterial.colorNode = maskMaterial.colorNode;
+                        ownedMaterial.needsUpdate = true;
+                    }
+                    maskMaterial = ownedMaterial;
+                }
+                renderer.renderObject(obj, sc, cam, geo, maskMaterial, grp, lights, clip);
+            }
+        });
+        renderer.render(useProxies ? maskScene : this.scene, this.camera);
+    }
+    _syncProxies(cache, proxies, scene) {
+        const supported = this._supportsProxies(cache);
+        for (const [source, proxy] of proxies) {
+            if (!supported || !cache.has(source) || !hasDrawableGeometry(source.geometry)) {
+                this._disposeProxyMaterial(proxy);
+                scene.remove(proxy);
+                proxies.delete(source);
+            }
+        }
+        if (!supported)
+            return false;
+        for (const source of cache) {
+            if (!hasDrawableGeometry(source.geometry))
+                continue;
+            let proxy = proxies.get(source);
+            if (!proxy) {
+                proxy = source.isSprite
+                    ? new Sprite(source.material)
+                    : new Mesh(source.geometry, source.material);
+                proxy.matrixAutoUpdate = false;
+                proxy.matrixWorldAutoUpdate = false;
+                proxy.frustumCulled = false;
+                proxies.set(source, proxy);
+                scene.add(proxy);
+            }
+            else if (proxy.geometry !== source.geometry) {
+                // Three's RenderObject.setGeometry does not move its dispose listener.
+                this._disposeProxyMaterial(proxy);
+            }
+            let visible = true;
+            let attached = false;
+            for (let ancestor = source; ancestor; ancestor = ancestor.parent) {
+                if (!ancestor.visible)
+                    visible = false;
+                if (ancestor === this.scene)
+                    attached = true;
+            }
+            proxy.geometry = source.geometry;
+            proxy.material = source.material;
+            proxy.matrixWorld.copy(source.matrixWorld);
+            proxy.layers.mask = source.layers.mask;
+            proxy.visible = visible && attached;
+            proxy.renderOrder = source.renderOrder;
+            proxy.morphTargetInfluences = source.morphTargetInfluences;
+            proxy.morphTargetDictionary = source.morphTargetDictionary;
+            proxy.count = source.count;
+            if (source.isSprite)
+                proxy.center.copy(source.center);
+        }
+        return true;
+    }
+    _supportsProxies(cache) {
+        for (const source of cache) {
+            const prototype = Object.getPrototypeOf(source);
+            if ((prototype !== Mesh.prototype && prototype !== Sprite.prototype) ||
+                source.onBeforeRender !== Object3D.prototype.onBeforeRender ||
+                source.onAfterRender !== Object3D.prototype.onAfterRender) {
+                return false;
+            }
+            for (let ancestor = source; ancestor; ancestor = ancestor.parent) {
+                if (ancestor.isLOD ||
+                    ancestor.isClippingGroup ||
+                    (ancestor.isGroup && ancestor.renderOrder !== 0)) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    _disposeProxyMaterial(proxy) {
+        this._proxyMaskMaterials.get(proxy)?.dispose();
+        this._proxyMaskMaterials.delete(proxy);
+    }
     _runEdgePipeline(renderer, group) {
         const isA = group === 'A';
         const g = isA ? this._groupA : this._groupB;
@@ -350,15 +451,45 @@ export class MergedOutlineNode extends TempNode {
         renderer.setRenderTarget(g.composite);
         _quadMesh.render(renderer);
     }
-    setup(_builder) {
+    setup(builder) {
+        if (this._sceneDepthNode) {
+            builder.getNodeProperties(this).sceneDepthNode = this._sceneDepthNode;
+        }
+        const reversed = builder.renderer.reversedDepthBuffer;
+        const depthTexture = this._sceneDepthNode?.value;
+        const floatDepth = reversed || depthTexture?.type === FloatType;
+        const depthSamples = this._sceneDepthNode && builder.renderer.backend.isWebGPUBackend
+            ? (this._sceneDepthNode.passNode?.options.samples ?? builder.renderer.samples)
+            : 0;
         // ── prepareMask ───────────────────────────────────────────────────────────
         const buildPrepareMask = () => {
-            const depth = this._depthTexUniform.sample(screenUV);
+            let depth = (this._sceneDepthNode ?? this._depthTexUniform).sample(screenUV).r;
+            if (this._sceneDepthNode) {
+                // The symmetric MSAA sample positions average to the pixel center where
+                // the mask rasterizes. Average differences to avoid rounding a sum of
+                // nearly-one depths and consuming the one-ULP allowance below.
+                let depthOffset = float(0);
+                for (let sampleIndex = 1; sampleIndex < depthSamples; sampleIndex++) {
+                    const sampleDepth = this._sceneDepthNode.sample(screenUV).level(sampleIndex).r;
+                    depthOffset = depthOffset.add(sampleDepth.sub(depth));
+                }
+                if (depthSamples > 1)
+                    depth = depth.add(depthOffset.div(depthSamples));
+                // Extract the float exponent for one ULP; a relative epsilon can hide
+                // centimetre-scale occlusion at long distances with conventional depth.
+                const bias = floatDepth
+                    ? float(floatBitsToUint(depth.abs()).shiftRight(23).bitAnd(255).max(1)).sub(150).exp2()
+                    : float(2 ** -24);
+                // Both Three builders expose fragCoord.xy; read rasterized z directly
+                // so view-Z reconstruction cannot consume the small depth allowance.
+                const fragmentDepth = Fn((_, shaderBuilder) => builtin(shaderBuilder.getFragCoord().replace(/\.xy$/, '.z')))();
+                const separation = reversed ? depth.sub(fragmentDepth) : fragmentDepth.sub(depth);
+                return vec3(0.0, separation.greaterThan(bias).select(1, 0), 1.0);
+            }
             const viewZ = this.camera.isPerspectiveCamera
                 ? perspectiveDepthToViewZ(depth, this._cameraNear, this._cameraFar)
                 : orthographicDepthToViewZ(depth, this._cameraNear, this._cameraFar);
-            const depthTest = positionView.z.lessThanEqual(viewZ).select(1, 0);
-            return vec3(0.0, depthTest, 1.0);
+            return vec3(0.0, positionView.z.lessThanEqual(viewZ).select(1, 0), 1.0);
         };
         const maskColorA = buildPrepareMask();
         this._prepareMaskMatA.colorNode = maskColorA;
@@ -445,6 +576,16 @@ export class MergedOutlineNode extends TempNode {
     dispose() {
         this.primaryObjects.length = 0;
         this.secondaryObjects.length = 0;
+        for (const proxy of this._proxiesA.values())
+            this._disposeProxyMaterial(proxy);
+        for (const proxy of this._proxiesB.values())
+            this._disposeProxyMaterial(proxy);
+        this._maskSceneA.clear();
+        this._maskSceneB.clear();
+        this._proxiesA.clear();
+        this._proxiesB.clear();
+        this._cacheA.clear();
+        this._cacheB.clear();
         this._depthRT.dispose();
         this._groupA.dispose();
         this._groupB.dispose();
@@ -466,6 +607,7 @@ export class MergedOutlineNode extends TempNode {
         this._compositeMatB.dispose();
     }
     _buildCache(objects, cache) {
+        cache.clear();
         for (const obj of objects) {
             obj.traverse((child) => {
                 if (child.isMesh || child.isSprite)

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 { }
+}