@sailfish-ai/recorder 1.12.4 → 1.12.6

package/README.md

@@ -239,6 +239,14 @@ initRecorder({
 
 `scripts/bench-perf.js` loads the same page twice — once with capture on, once with capture off — under headless Chrome, and reports CPU, JS heap, FCP/LCP, long-task time, and total load time side-by-side.
 
+> **Canvas recording** has its own full, customer-facing cost/fidelity report —
+> per-frame slowdown, CPU, RAM, recorded size and page weight for **2D, WebGL and
+> WebGPU** canvases, on **desktop and (CPU-throttled) mobile**, plus replay SSIM,
+> Lighthouse page-level deltas, and a glossary explaining every metric. See
+> **[PERFORMANCE.md](./PERFORMANCE.md)**. Headline: lossless replay (SSIM 1.0),
+> **~0.5 µs per draw** (~1% of a 60 fps frame for typical scenes), **0 ms** added
+> Total Blocking Time, no memory leak, **~10 KB gzipped**.
+
 #### One-time app change (required before running the bench)
 
 The bench needs a way to flip capture on/off without rebuilding your app between variants. Wire `?sf_perf=off` in your `initRecorder` call so the URL controls the option — paste this where you call `initRecorder`:

package/dist/canvas/adapters.js

@@ -0,0 +1,382 @@
+/**
+ * Phase 4 — framework semantic adapters (contract §9).
+ *
+ * Canvas pixels know WHERE a click landed (the pick buffer resolves that to a
+ * draw command / source line). Frameworks additionally know WHAT logical
+ * object the user clicked: a Konva "Upgrade CTA" shape, a Chart.js datapoint,
+ * a Three.js mesh. These adapters capture that semantic target on pointerdown
+ * and emit it as a `sf-canvas` op:"hit" index event:
+ *
+ *   {tag:"sf-canvas", op:"hit", canvasId, t, x, y,
+ *    target:{framework, label, objectType?, path?}}
+ *
+ * The SDK cannot import the customer's framework (three/konva/fabric/pixi/
+ * chart.js), so the customer (or a future build plugin) registers their live
+ * instance via the exported register* helpers below — each returns an
+ * unregister fn for component teardown. A window-global fallback covers
+ * script-tag (UMD) usage where the framework publishes a global.
+ *
+ * Every adapter callback is try/catch'd: a framework hiccup never breaks
+ * recording. SSR-safe: no window/document access at module scope.
+ */
+// [creation-site stamping] object -> build-time creation id. Set by:
+//  - Layer A: the build plugin's `__sfnew` helper via globalThis.__sfCreateSite
+//    (marks a `new X()` result directly), and
+//  - Layer B: the build plugin's `__sfcreate` helper via globalThis.__sfCreateFrom
+//    (marks a loader/clone/factory RESULT subtree — see markSubtree).
+// WeakMap -> no retention.
+const createIdOf = new WeakMap();
+/** Creation provenance for the clicked object: nearest stamped createId (self or
+ * up the `.parent` chain). Never throws. */
+function creationOf(obj) {
+    const out = {};
+    try {
+        let o = obj;
+        for (let i = 0; i < 8 && o && typeof o === "object"; i++) {
+            const id = createIdOf.get(o);
+            if (id) {
+                out.createId = id;
+                break;
+            }
+            o = o.parent;
+        }
+    }
+    catch { /* best effort */ }
+    return out;
+}
+// ─── Layer B: produced-object subtree marking (globalThis.__sfCreateFrom) ─────
+/** Depth and total-node caps for markSubtree — bound the walk so a pathological
+ * scene graph can never stall the click path or hold work proportional to N. */
+const MARK_MAX_DEPTH = 6;
+const MARK_MAX_NODES = 2000;
+/** Framework child collections for an object: three.js `.children` (+ GLTF result
+ * `.scene`/`.scenes`), pixi `.children`, fabric/konva `getObjects?.()`. Returns the
+ * direct child objects to descend into. Never throws. */
+function frameworkChildren(node) {
+    const out = [];
+    const push = (v) => { if (v && typeof v === "object")
+        out.push(v); };
+    try {
+        const n = node;
+        // three.js Object3D / pixi Container: `.children` array
+        if (Array.isArray(n.children))
+            for (const c of n.children)
+                push(c);
+        // GLTF loader result: `.scene` (a Group) and/or `.scenes` (Group[])
+        push(n.scene);
+        if (Array.isArray(n.scenes))
+            for (const s of n.scenes)
+                push(s);
+        // fabric.Group / konva.Container: `getObjects()` returns the child array
+        if (typeof n.getObjects === "function") {
+            const objs = n.getObjects();
+            if (Array.isArray(objs))
+                for (const o of objs)
+                    push(o);
+        }
+    }
+    catch { /* best effort — a hostile getter must never break marking */ }
+    return out;
+}
+/** Mark a produced object and its bounded framework subtree with the creation-site
+ * id. Sets createId ONLY where none exists (Layer A / a nearer site wins). Walks
+ * breadth-first to MARK_MAX_DEPTH and MARK_MAX_NODES; WeakMap only (no retention);
+ * never throws. */
+function markSubtree(root, id) {
+    try {
+        if (!root || typeof root !== "object")
+            return;
+        // BFS with a visited set so cyclic graphs (a child re-added to an ancestor)
+        // cannot loop, and the node cap bounds total work.
+        const seen = new WeakSet();
+        let frontier = [root];
+        seen.add(root);
+        let nodes = 0;
+        for (let depth = 0; depth <= MARK_MAX_DEPTH && frontier.length; depth++) {
+            const next = [];
+            for (const node of frontier) {
+                if (nodes >= MARK_MAX_NODES)
+                    return;
+                nodes++;
+                try {
+                    if (!createIdOf.has(node))
+                        createIdOf.set(node, id);
+                }
+                catch { /* best effort */ }
+                if (depth < MARK_MAX_DEPTH) {
+                    for (const child of frameworkChildren(node)) {
+                        if (!seen.has(child)) {
+                            seen.add(child);
+                            next.push(child);
+                        }
+                    }
+                }
+            }
+            frontier = next;
+        }
+    }
+    catch { /* never throw out of the marker */ }
+}
+/** True for a thenable (Promise / promise-like). Guarded `.then` read. */
+function isThenable(v) {
+    try {
+        return !!v && (typeof v === "object" || typeof v === "function") &&
+            typeof v.then === "function";
+    }
+    catch {
+        return false;
+    }
+}
+/** Runtime hook for Layer B build-time `__sfcreate(() => EXPR.method(args), id)`.
+ * Marks the producer's RESULT subtree with the call-site id so a later click on a
+ * loaded/cloned object resolves to the producer's source line. Async producers
+ * (loadAsync / promise loaders) resolve later — attach `.then` and mark the
+ * resolved value; rejection behavior is untouched. Fully guarded, SSR-safe. */
+function createFrom(result, siteId) {
+    try {
+        if (!siteId)
+            return;
+        if (isThenable(result)) {
+            // Mark on fulfillment; swallow rejection so we never alter the promise's
+            // own rejection handling (the returned promise is the original — see helper).
+            result.then((v) => { markSubtree(v, siteId); }, () => { });
+            return;
+        }
+        markSubtree(result, siteId);
+    }
+    catch { /* best effort — never throw into the producer's call path */ }
+}
+/** canvas element -> its framework resolver (explicit registrations) */
+const resolvers = new Map();
+function isCanvas(v) {
+    return (typeof HTMLCanvasElement !== "undefined" &&
+        v instanceof HTMLCanvasElement);
+}
+function bind(canvas, resolver) {
+    if (!isCanvas(canvas))
+        return () => { };
+    resolvers.set(canvas, resolver);
+    return () => {
+        if (resolvers.get(canvas) === resolver)
+            resolvers.delete(canvas);
+    };
+}
+// ─── Register helpers (public API; re-exported from index.tsx) ────────────────
+/** Konva: hit-test the stage's hit graph; label from node name()/id()/class. */
+export function registerKonvaStage(stage) {
+    try {
+        const s = stage;
+        // Konva layer canvases are all stage-sized and stacked at (0,0), so binding
+        // any one of them covers the whole stage, and getIntersection hit-tests across
+        // every layer regardless of which canvas element received the pointer. Bind
+        // the first layer's canvas (binding all would just emit N redundant hits).
+        const layers = s.getLayers?.() ?? [];
+        const canvas = layers[0]?.getCanvas?.()?._canvas;
+        return bind(canvas, (cv, ev) => {
+            const rect = cv.getBoundingClientRect();
+            const node = s.getIntersection?.({ x: ev.clientX - rect.left, y: ev.clientY - rect.top });
+            if (!node)
+                return null;
+            const cls = node.getClassName?.();
+            const label = node.name?.() || node.id?.() || cls || "shape";
+            return { framework: "konva", label, objectType: cls, ...creationOf(node) };
+        });
+    }
+    catch {
+        return () => { };
+    }
+}
+/** Fabric: findTarget(ev) on the canvas; label from object name/id/type. */
+export function registerFabricCanvas(fabricCanvas) {
+    try {
+        const fc = fabricCanvas;
+        return bind(fc.lowerCanvasEl, (_cv, ev) => {
+            const t = fc.findTarget?.(ev);
+            if (!t)
+                return null;
+            const label = t.name || t.id || t.type || "object";
+            return { framework: "fabric", label, objectType: t.type, ...creationOf(t) };
+        });
+    }
+    catch {
+        return () => { };
+    }
+}
+/** Chart.js: getElementsAtEventForMode -> "datasetLabel[index]". */
+export function registerChart(chart) {
+    try {
+        const c = chart;
+        return bind(c.canvas, (_cv, ev) => {
+            const els = c.getElementsAtEventForMode?.(ev, "nearest", { intersect: true }, false);
+            if (!els || !els.length)
+                return null;
+            const { datasetIndex, index } = els[0];
+            const dsLabel = c.data?.datasets?.[datasetIndex]?.label ?? `dataset${datasetIndex}`;
+            // Chart.js has no per-datum object; Layer A stamps the `new Chart(...)` site
+            // (createId of the chart instance), and configRef pins which datum. [Layer D]
+            return {
+                framework: "chartjs", label: `${dsLabel}[${index}]`, objectType: c.config?.type,
+                ...creationOf(c), configRef: { datasetIndex, index },
+            };
+        });
+    }
+    catch {
+        return () => { };
+    }
+}
+/**
+ * Three.js: raycast on pointerdown. The customer passes their THREE namespace
+ * (the SDK must not bundle three) plus the scene/camera/renderer.
+ */
+export function registerThreeScene(scene, camera, renderer, three) {
+    try {
+        const THREE = three;
+        const r = renderer;
+        const sc = scene;
+        const raycaster = new THREE.Raycaster();
+        const v2 = new THREE.Vector2();
+        return bind(r.domElement, (cv, ev) => {
+            const rect = cv.getBoundingClientRect();
+            v2.x = ((ev.clientX - rect.left) / rect.width) * 2 - 1;
+            v2.y = -((ev.clientY - rect.top) / rect.height) * 2 + 1;
+            raycaster.setFromCamera(v2, camera);
+            const hits = raycaster.intersectObjects(sc.children ?? [], true);
+            if (!hits.length)
+                return null;
+            const obj = hits[0].object;
+            let named = obj;
+            while (named && !named.name && named.parent)
+                named = named.parent;
+            const label = named?.name || obj.name || obj.uuid || "mesh";
+            // Read creation provenance from the LEAF `obj`. Layer B's markSubtree stamps
+            // every node of a loaded/cloned subtree, and creationOf also walks `.parent`
+            // for a stamped ancestor — so loader-produced meshes resolve to their `load`
+            // call site and `new`-stamped ancestors are still found. [audit]
+            return { framework: "three", label, objectType: obj.type, path: obj.uuid, ...creationOf(obj) };
+        });
+    }
+    catch {
+        return () => { };
+    }
+}
+/** PixiJS (v8): hit-test the event boundary; label from object label/name. */
+export function registerPixiApp(app) {
+    try {
+        const a = app;
+        const canvas = a.canvas ?? a.view;
+        return bind(canvas, (cv, ev) => {
+            const rect = cv.getBoundingClientRect();
+            const x = ev.clientX - rect.left;
+            const y = ev.clientY - rect.top;
+            const obj = a.renderer?.events?.rootBoundary?.hitTest?.(x, y);
+            if (!obj)
+                return null;
+            const objectType = pixiObjectType(obj);
+            const label = obj.label || obj.name || objectType || "displayObject";
+            return { framework: "pixi", label, objectType, ...creationOf(obj) };
+        });
+    }
+    catch {
+        return () => { };
+    }
+}
+/** Best-effort stable Pixi (v8) type name. Production builds minify
+ * `constructor.name` (→ "t", "e"), so duck-type the common display objects by
+ * their distinguishing fields first; fall back to the ctor name only when it
+ * survived minification (length > 1). [audit MEDIUM] */
+function pixiObjectType(obj) {
+    // Order matters: `texture` is NOT unique to Sprite in Pixi v8 — a Mesh exposes
+    // it as a data getter and a Graphics as a METHOD — so test the distinctive
+    // fields first, and treat `texture` as a Sprite signal only when it's a real
+    // object (not a function). [audit MEDIUM]
+    if (typeof obj.text === "string")
+        return "Text";
+    const hasTextureObj = !!obj.texture && typeof obj.texture !== "function";
+    if (hasTextureObj && (obj.tilePosition || obj.tileScale))
+        return "TilingSprite";
+    if (obj.geometry && obj.shader)
+        return "Mesh";
+    if (obj.context)
+        return "Graphics";
+    if (hasTextureObj)
+        return "Sprite";
+    if (Array.isArray(obj.children))
+        return "Container";
+    const ctor = obj.constructor?.name;
+    return ctor && ctor.length > 1 ? ctor : undefined;
+}
+let deps = null;
+let listening = false;
+function onPointerDown(ev) {
+    const d = deps;
+    if (!d)
+        return;
+    for (const [canvas, resolver] of resolvers) {
+        try {
+            // Prune detached canvases (SPA route changes that re-register without an
+            // intervening uninstall leave stale entries holding detached elements). [audit LOW]
+            if (!canvas.isConnected) {
+                resolvers.delete(canvas);
+                continue;
+            }
+            const rect = canvas.getBoundingClientRect();
+            if (ev.clientX < rect.left || ev.clientX > rect.right ||
+                ev.clientY < rect.top || ev.clientY > rect.bottom)
+                continue;
+            const canvasId = d.canvasIdFor(canvas);
+            if (!canvasId)
+                continue;
+            const target = resolver(canvas, ev);
+            if (!target)
+                continue;
+            const w = canvas.width, h = canvas.height;
+            const x = rect.width ? Math.round((ev.clientX - rect.left) * w / rect.width) : 0;
+            const y = rect.height ? Math.round((ev.clientY - rect.top) * h / rect.height) : 0;
+            d.emitHit({ op: "hit", canvasId, t: d.now(), x, y, target });
+        }
+        catch {
+            /* a framework hiccup must never break recording */
+        }
+    }
+}
+export function installAdapters(d) {
+    deps = d;
+    // [creation-site stamping — Layer A] The build plugin rewrites `new X(...)` to
+    // `__sfnew(new X(...), id)`, whose helper invokes globalThis.__sfCreateSite(obj,
+    // id). Mark the object with its construction-site id so a later click resolves
+    // to the exact `new X()` line. Always safe to define (SSR: globalThis exists).
+    const g = globalThis;
+    g.__sfCreateSite = (o, id) => {
+        try {
+            if (o && typeof o === "object")
+                createIdOf.set(o, id);
+        }
+        catch { /* best effort */ }
+    };
+    // [creation-site stamping — Layer B] The build plugin rewrites object-PRODUCING
+    // calls `EXPR.method(args)` (load/loadAsync/parse/parseAsync/clone/copy) to
+    // `__sfcreate(() => EXPR.method(args), id)`, whose helper invokes
+    // globalThis.__sfCreateFrom(result, id). Mark the produced object subtree with
+    // the producer's call-site id so a later click on a loaded/cloned object
+    // resolves to that line. Async results (loadAsync/promise loaders) mark on
+    // resolution. Always safe to define (SSR: globalThis exists).
+    g.__sfCreateFrom = (result, id) => { createFrom(result, id); };
+    if (listening || typeof window === "undefined")
+        return;
+    window.addEventListener("pointerdown", onPointerDown, { capture: true, passive: true });
+    listening = true;
+}
+export function uninstallAdapters() {
+    deps = null;
+    if (listening && typeof window !== "undefined") {
+        window.removeEventListener("pointerdown", onPointerDown, { capture: true });
+    }
+    listening = false;
+    resolvers.clear();
+    try {
+        const g = globalThis;
+        delete g.__sfCreateSite;
+        delete g.__sfCreateFrom;
+    }
+    catch { /* ignore */ }
+}