@grafloria/element 0.3.17 → 0.3.19

package/src/libs/renderer/src/lazy/progressive-mounter.js.map

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

package/src/libs/renderer/src/lazy/types.d.ts

@@ -0,0 +1,43 @@
+/** The two things that have views. */
+export type EntityKind = 'node' | 'link';
+/**
+ * The gate the renderer consults before instantiating an entity's VIEW.
+ *
+ * A gate can only ever SUBTRACT from what culling already admitted — it never adds
+ * an off-screen entity back in. That asymmetry is deliberate: a gate bug can make
+ * something arrive late, never wrong.
+ */
+export interface MountGate {
+    /** May the renderer build (or refresh) this entity's view on this frame? */
+    admits(kind: EntityKind, id: string): boolean;
+    /**
+     * True while a progressive mount is running — the renderer's cue that the scene
+     * is being brought up in slices and is not yet whole.
+     */
+    isDeferring?(): boolean;
+}
+/** What one `mount()` actually did — the numbers the claim lives on. */
+export interface MountStats {
+    /** ms from `mount()` to the first frame that reached the screen. */
+    firstPaintMs: number;
+    /** Wall clock from `mount()` to the last entity mounted — INCLUDING the rAF waits. */
+    completeMs: number;
+    /**
+     * CPU actually spent, summed over the slices — i.e. `completeMs` minus the time spent
+     * yielded to the browser.
+     *
+     * This is the number that says whether slicing costs anything REAL. Wall clock has to
+     * grow (that is what yielding means: ~16.7ms of vsync per slice, during which the tab
+     * paints and handles input). Work is what must not grow, and this is what proves it.
+     */
+    cpuMs: number;
+    /** rAF slices used (1 = it all fitted in the first frame). */
+    slices: number;
+    /** Entities whose views were built. */
+    nodesMounted: number;
+    linksMounted: number;
+    /** The worst single slice — the jank a user would actually feel. */
+    worstSliceMs: number;
+    /** True if the mount was cancelled or pre-empted by a model change. */
+    aborted: boolean;
+}

package/src/libs/renderer/src/lazy/types.js

@@ -0,0 +1,14 @@
+"use strict";
+// Wave 8 — Card 3: deferred / lazy view instantiation.
+//
+// The renderer already CULLS: it asks the spatial index which entities intersect
+// the viewport and builds VNodes only for those. What it did not have was a say in
+// the matter — culling is recomputed from geometry every frame, and every entity it
+// admits pays the full price of a view (route + style + VNode) on the very first
+// frame, all of it before anything reaches the screen.
+//
+// A `MountGate` is that say. It sits between "the spatial index says this is on
+// screen" and "build its view", and it is what lets a huge graph reach first paint
+// without routing every link first.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/libs/renderer/src/lazy/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../renderer/src/lazy/types.ts"],"names":[],"mappings":";AAAA,uDAAuD;AACvD,EAAE;AACF,iFAAiF;AACjF,mFAAmF;AACnF,oFAAoF;AACpF,iFAAiF;AACjF,uDAAuD;AACvD,EAAE;AACF,gFAAgF;AAChF,mFAAmF;AACnF,oCAAoC"}

package/src/libs/renderer/src/lazy/view-lifecycle.d.ts

@@ -0,0 +1,97 @@
+import type { EntityKind, MountGate } from './types';
+export interface ViewLifecycleOptions {
+    /**
+     * Drop the view of any entity that leaves the viewport. Default false — the
+     * historical behaviour (views linger in the LRU until evicted by pressure).
+     */
+    autoFreeze?: boolean;
+}
+export declare class ViewLifecycle implements MountGate {
+    /** Explicitly frozen by the host. Survives everything until unfrozen. */
+    private readonly frozen;
+    /** Frozen by autoFreeze because they left the viewport. Thawed on return. */
+    private readonly autoFrozen;
+    /** What the last frame could see — the set autoFreeze diffs against. */
+    private retained;
+    private autoFreeze;
+    /** While true, NOTHING is admitted except what `admit()` has let through. */
+    private deferring;
+    /** Admitted so far by the mount in progress (cumulative across slices). */
+    private readonly admitted;
+    /** Kinds admitted wholesale — nodes are cheap, so slice 0 takes all of them. */
+    private readonly openKinds;
+    /**
+     * Called when an entity's view is dropped, so the renderer can evict its cache
+     * entry. Set by `SVGRenderer.setViewLifecycle`.
+     */
+    private evictHook;
+    /**
+     * Called whenever THIS OBJECT changes what the renderer would draw — a freeze, an
+     * unfreeze, a progressive-mount admission, an autoFreeze toggle.
+     *
+     * This hook exists because of a bug the wave-8 merge produced and neither branch
+     * could have caught alone. The frame gate (Card 0) skips a frame whose MODEL and
+     * VIEWPORT are unchanged — and freezing a node changes neither. Nor does admitting
+     * the next mount slice. So the gate correctly concluded "you have already drawn
+     * this frame" and handed back the previous picture, and freeze/lazy-mount silently
+     * did nothing: five tests that passed on both branches in isolation failed the
+     * moment they were composed.
+     *
+     * The lesson generalises, and it is the same one three times over in this wave:
+     * ask what can change the PICTURE without changing the MODEL. The answer is always
+     * longer than it looks — the route solver's refined answer, the quality governor's
+     * tier bias, and now this.
+     */
+    private changeHook;
+    constructor(options?: ViewLifecycleOptions);
+    /**
+     * Give up this entity's view. It keeps its model and its spatial-index entry;
+     * it stops being drawn and stops costing anything per frame.
+     */
+    freeze(kind: EntityKind, id: string): void;
+    /** Give it a view again. It is rebuilt on the next frame that can see it. */
+    unfreeze(kind: EntityKind, id: string): void;
+    isFrozen(kind: EntityKind, id: string): boolean;
+    /** Explicitly frozen only — NOT the ones autoFreeze is holding off-screen. */
+    isExplicitlyFrozen(kind: EntityKind, id: string): boolean;
+    unfreezeAll(): void;
+    setAutoFreeze(on: boolean): void;
+    isAutoFreeze(): boolean;
+    /**
+     * The views currently retained — i.e. what the renderer is paying for.
+     *
+     * This is the number autoFreeze exists to bound, so it is measurable rather
+     * than asserted.
+     */
+    retainedCount(): number;
+    frozenCount(): number;
+    /**
+     * Called by the renderer each frame with what culling admitted, BEFORE the gate
+     * is applied. Anything that was on screen and no longer is gets its view dropped.
+     *
+     * Not called at all when autoFreeze is off — the whole feature is one Set diff
+     * per frame, and a host that has not asked for it pays nothing.
+     */
+    retainVisible(visible: ReadonlyArray<readonly [EntityKind, string]>): void;
+    /** Defer EVERYTHING. Nothing has a view until `admit()` says so. */
+    beginDeferred(): void;
+    /** Let this entity's view be built from now on. */
+    admit(kind: EntityKind, id: string): void;
+    /**
+     * Admit a whole KIND without naming its members. Slice 0 uses this for nodes: a
+     * node's view is cheap (no routing), and enumerating 10k ids to admit them one
+     * at a time would cost more than building the ~56 views culling actually keeps.
+     */
+    admitAll(kind: EntityKind): void;
+    /** The mount is over (finished, cancelled, or pre-empted). Gate opens fully. */
+    endDeferred(): void;
+    admits(kind: EntityKind, id: string): boolean;
+    isDeferring(): boolean;
+    /** @internal — wired by SVGRenderer.setViewLifecycle. */
+    setEvictHook(hook: ((kind: EntityKind, id: string) => void) | null): void;
+    /**
+     * Tell the renderer that what it would draw has changed, even though the model
+     * has not. Set by `SVGRenderer.setViewLifecycle`; see `changeHook`.
+     */
+    setChangeHook(hook: (() => void) | null): void;
+}

package/src/libs/renderer/src/lazy/view-lifecycle.js

@@ -0,0 +1,221 @@
+"use strict";
+// Wave 8 — Card 3: freeze / unfreeze / autoFreeze, and the admission set a
+// progressive mount admits into.
+//
+// FREEZE is the explicit form of "this entity has a model, and a place in the
+// spatial index, and NO view". A frozen entity is not routed, not styled, not
+// turned into a VNode, and holds no cache entry. It still exists: it still has a
+// position, it still answers a spatial query, it still serialises. It simply is not
+// drawn, and costs nothing per frame.
+//
+// AUTOFREEZE applies that automatically to everything outside the viewport. On its
+// face that is what culling already does — but culling is a per-frame geometric
+// decision that leaves the entity's CACHED VNODE behind. Pan a 10k-node graph from
+// end to end with autoFreeze off and the renderer accumulates cached views for
+// every entity it ever passed over (bounded only by `maxCacheSize`, which is a
+// backstop, not a policy). With autoFreeze on, a view is dropped the moment its
+// entity leaves the viewport, and the retained set stays O(on screen) instead of
+// O(everything ever seen). That is the difference between a cache and a leak.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewLifecycle = void 0;
+/** `node:n12` / `link:l7` — one keyspace, so a node and a link can share an id. */
+const keyOf = (kind, id) => `${kind}:${id}`;
+class ViewLifecycle {
+    constructor(options = {}) {
+        var _a;
+        /** Explicitly frozen by the host. Survives everything until unfrozen. */
+        this.frozen = new Set();
+        /** Frozen by autoFreeze because they left the viewport. Thawed on return. */
+        this.autoFrozen = new Set();
+        /** What the last frame could see — the set autoFreeze diffs against. */
+        this.retained = new Set();
+        // --- progressive mount ----------------------------------------------------
+        /** While true, NOTHING is admitted except what `admit()` has let through. */
+        this.deferring = false;
+        /** Admitted so far by the mount in progress (cumulative across slices). */
+        this.admitted = new Set();
+        /** Kinds admitted wholesale — nodes are cheap, so slice 0 takes all of them. */
+        this.openKinds = new Set();
+        /**
+         * Called when an entity's view is dropped, so the renderer can evict its cache
+         * entry. Set by `SVGRenderer.setViewLifecycle`.
+         */
+        this.evictHook = null;
+        /**
+         * Called whenever THIS OBJECT changes what the renderer would draw — a freeze, an
+         * unfreeze, a progressive-mount admission, an autoFreeze toggle.
+         *
+         * This hook exists because of a bug the wave-8 merge produced and neither branch
+         * could have caught alone. The frame gate (Card 0) skips a frame whose MODEL and
+         * VIEWPORT are unchanged — and freezing a node changes neither. Nor does admitting
+         * the next mount slice. So the gate correctly concluded "you have already drawn
+         * this frame" and handed back the previous picture, and freeze/lazy-mount silently
+         * did nothing: five tests that passed on both branches in isolation failed the
+         * moment they were composed.
+         *
+         * The lesson generalises, and it is the same one three times over in this wave:
+         * ask what can change the PICTURE without changing the MODEL. The answer is always
+         * longer than it looks — the route solver's refined answer, the quality governor's
+         * tier bias, and now this.
+         */
+        this.changeHook = null;
+        this.autoFreeze = (_a = options.autoFreeze) !== null && _a !== void 0 ? _a : false;
+    }
+    // =========================================================================
+    // Freeze
+    // =========================================================================
+    /**
+     * Give up this entity's view. It keeps its model and its spatial-index entry;
+     * it stops being drawn and stops costing anything per frame.
+     */
+    freeze(kind, id) {
+        var _a, _b;
+        const key = keyOf(kind, id);
+        if (this.frozen.has(key))
+            return;
+        this.frozen.add(key);
+        (_a = this.evictHook) === null || _a === void 0 ? void 0 : _a.call(this, kind, id);
+        (_b = this.changeHook) === null || _b === void 0 ? void 0 : _b.call(this);
+    }
+    /** Give it a view again. It is rebuilt on the next frame that can see it. */
+    unfreeze(kind, id) {
+        var _a;
+        if (!this.frozen.delete(keyOf(kind, id)))
+            return;
+        (_a = this.changeHook) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    isFrozen(kind, id) {
+        const key = keyOf(kind, id);
+        return this.frozen.has(key) || this.autoFrozen.has(key);
+    }
+    /** Explicitly frozen only — NOT the ones autoFreeze is holding off-screen. */
+    isExplicitlyFrozen(kind, id) {
+        return this.frozen.has(keyOf(kind, id));
+    }
+    unfreezeAll() {
+        var _a;
+        if (this.frozen.size === 0)
+            return;
+        this.frozen.clear();
+        (_a = this.changeHook) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    setAutoFreeze(on) {
+        var _a;
+        if (this.autoFreeze === on)
+            return;
+        this.autoFreeze = on;
+        if (!on) {
+            // Everything autoFreeze was holding gets its view back on the next frame.
+            this.autoFrozen.clear();
+        }
+        (_a = this.changeHook) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    isAutoFreeze() {
+        return this.autoFreeze;
+    }
+    /**
+     * The views currently retained — i.e. what the renderer is paying for.
+     *
+     * This is the number autoFreeze exists to bound, so it is measurable rather
+     * than asserted.
+     */
+    retainedCount() {
+        return this.retained.size;
+    }
+    frozenCount() {
+        return this.frozen.size + this.autoFrozen.size;
+    }
+    /**
+     * Called by the renderer each frame with what culling admitted, BEFORE the gate
+     * is applied. Anything that was on screen and no longer is gets its view dropped.
+     *
+     * Not called at all when autoFreeze is off — the whole feature is one Set diff
+     * per frame, and a host that has not asked for it pays nothing.
+     */
+    retainVisible(visible) {
+        var _a;
+        if (!this.autoFreeze)
+            return;
+        const next = new Set();
+        for (const [kind, id] of visible) {
+            const key = keyOf(kind, id);
+            next.add(key);
+            // Back on screen: thaw it, so the next frame builds its view again.
+            this.autoFrozen.delete(key);
+        }
+        for (const key of this.retained) {
+            if (next.has(key))
+                continue;
+            // Left the viewport. Drop the view; keep the model.
+            this.autoFrozen.add(key);
+            const sep = key.indexOf(':');
+            (_a = this.evictHook) === null || _a === void 0 ? void 0 : _a.call(this, key.slice(0, sep), key.slice(sep + 1));
+        }
+        this.retained = next;
+    }
+    // =========================================================================
+    // Progressive mount (the admission set)
+    // =========================================================================
+    /** Defer EVERYTHING. Nothing has a view until `admit()` says so. */
+    beginDeferred() {
+        var _a;
+        this.deferring = true;
+        this.admitted.clear();
+        this.openKinds.clear();
+        (_a = this.changeHook) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    /** Let this entity's view be built from now on. */
+    admit(kind, id) {
+        var _a;
+        this.admitted.add(keyOf(kind, id));
+        (_a = this.changeHook) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    /**
+     * Admit a whole KIND without naming its members. Slice 0 uses this for nodes: a
+     * node's view is cheap (no routing), and enumerating 10k ids to admit them one
+     * at a time would cost more than building the ~56 views culling actually keeps.
+     */
+    admitAll(kind) {
+        var _a;
+        this.openKinds.add(kind);
+        (_a = this.changeHook) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    /** The mount is over (finished, cancelled, or pre-empted). Gate opens fully. */
+    endDeferred() {
+        var _a;
+        this.deferring = false;
+        this.admitted.clear();
+        this.openKinds.clear();
+        (_a = this.changeHook) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    // =========================================================================
+    // MountGate
+    // =========================================================================
+    admits(kind, id) {
+        const key = keyOf(kind, id);
+        // An explicit freeze outranks a mount admission: a host that froze something
+        // did so on purpose, and a mount is no reason to overrule it.
+        if (this.frozen.has(key) || this.autoFrozen.has(key))
+            return false;
+        if (this.deferring)
+            return this.openKinds.has(kind) || this.admitted.has(key);
+        return true;
+    }
+    isDeferring() {
+        return this.deferring;
+    }
+    // =========================================================================
+    /** @internal — wired by SVGRenderer.setViewLifecycle. */
+    setEvictHook(hook) {
+        this.evictHook = hook;
+    }
+    /**
+     * Tell the renderer that what it would draw has changed, even though the model
+     * has not. Set by `SVGRenderer.setViewLifecycle`; see `changeHook`.
+     */
+    setChangeHook(hook) {
+        this.changeHook = hook;
+    }
+}
+exports.ViewLifecycle = ViewLifecycle;
+//# sourceMappingURL=view-lifecycle.js.map

package/src/libs/renderer/src/lazy/view-lifecycle.js.map

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

package/src/libs/renderer/src/perf/index.d.ts

@@ -0,0 +1,2 @@
+export * from './quality-governor';
+export * from './perf-hud';

package/src/libs/renderer/src/perf/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// Wave 8 (Performance & scale) — Card 7: runtime instrumentation.
+tslib_1.__exportStar(require("./quality-governor"), exports);
+tslib_1.__exportStar(require("./perf-hud"), exports);
+//# sourceMappingURL=index.js.map

package/src/libs/renderer/src/perf/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../renderer/src/perf/index.ts"],"names":[],"mappings":";;;AAAA,kEAAkE;AAClE,6DAAmC;AACnC,qDAA2B"}

package/src/libs/renderer/src/perf/perf-hud.d.ts

@@ -0,0 +1,46 @@
+import type { GovernorState } from './quality-governor';
+export interface PerfSnapshot {
+    /** Rolling FPS. */
+    fps: number;
+    /** Last frame, ms. */
+    frameMs: number;
+    /** Entities in the model. */
+    nodes: number;
+    links: number;
+    /** Entities that survived viewport culling — i.e. what we actually paid for. */
+    visibleNodes: number;
+    visibleLinks: number;
+    /** Entities whose views exist in the DOM right now (lazy mounting, Card 3). */
+    mountedViews: number;
+    /** Entities re-rendered this frame (the dirty set, Card 0). */
+    dirtyNodes: number;
+    dirtyLinks: number;
+    /** Links whose route was recomputed this frame (Card 6). Should be ~0 on an idle frame. */
+    routedLinks: number;
+    /** The LOD tier actually rendered, and the governor's reasoning. */
+    tier: string;
+    governor?: GovernorState;
+}
+export declare const EMPTY_SNAPSHOT: PerfSnapshot;
+/**
+ * Format a snapshot for a human.
+ *
+ * Deliberately calls out the ratios that reveal a bug rather than just printing
+ * numbers: "culled 0/10000" reads as fine until you notice it means nothing was
+ * culled. The HUD's job is to make that impossible to miss.
+ */
+export declare function formatSnapshot(s: PerfSnapshot): string[];
+/**
+ * A DOM overlay, framework-free.
+ *
+ * Absolutely positioned, `pointer-events: none` — a debug HUD that eats clicks is a
+ * bug generator of its own. It is opt-in and never mounted unless asked for.
+ */
+export declare class PerfHud {
+    private readonly host;
+    private el?;
+    constructor(host: HTMLElement);
+    show(): void;
+    update(snapshot: PerfSnapshot): void;
+    hide(): void;
+}

package/src/libs/renderer/src/perf/perf-hud.js

@@ -0,0 +1,105 @@
+"use strict";
+// Wave 8 (Performance & scale) — Card 7: the runtime perf HUD.
+//
+// The card asks for "a runtime perf HUD (FPS, dirty/culled/mounted-view counts)".
+// The counts are the point, not the FPS. FPS tells you THAT the frame was slow; the
+// counts tell you WHY — and in this engine the why has been the story every time:
+//
+//   • "culled 0 of 10,000" would have shown at a glance that viewport culling was
+//     not culling.
+//   • "routed 9,998 links" on a frame where nothing moved is the 5.5-second drag,
+//     visible without a profiler.
+//   • "governor: stepped-down (median 41ms)" is the difference between a governor
+//     that is working and one that is silently doing nothing.
+//
+// So the HUD is a DATA structure first and a DOM overlay second. The data is what
+// the benchmark harness and the tests consume; the overlay is a convenience for a
+// human with a real diagram in front of them.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerfHud = exports.EMPTY_SNAPSHOT = void 0;
+exports.formatSnapshot = formatSnapshot;
+exports.EMPTY_SNAPSHOT = {
+    fps: 0,
+    frameMs: 0,
+    nodes: 0,
+    links: 0,
+    visibleNodes: 0,
+    visibleLinks: 0,
+    mountedViews: 0,
+    dirtyNodes: 0,
+    dirtyLinks: 0,
+    routedLinks: 0,
+    tier: 'high',
+};
+/**
+ * Format a snapshot for a human.
+ *
+ * Deliberately calls out the ratios that reveal a bug rather than just printing
+ * numbers: "culled 0/10000" reads as fine until you notice it means nothing was
+ * culled. The HUD's job is to make that impossible to miss.
+ */
+function formatSnapshot(s) {
+    const culledNodes = s.nodes - s.visibleNodes;
+    const culledLinks = s.links - s.visibleLinks;
+    const lines = [
+        `${s.fps.toFixed(0)} fps   ${s.frameMs.toFixed(1)} ms/frame`,
+        `nodes  ${s.visibleNodes}/${s.nodes} visible   (culled ${culledNodes})`,
+        `links  ${s.visibleLinks}/${s.links} visible   (culled ${culledLinks})`,
+        `views  ${s.mountedViews} mounted`,
+        `dirty  ${s.dirtyNodes} nodes, ${s.dirtyLinks} links`,
+        `routed ${s.routedLinks} links this frame`,
+        `tier   ${s.tier}`,
+    ];
+    if (s.governor) {
+        const g = s.governor;
+        lines.push(`gov    bias ${g.bias} · median ${g.medianMs.toFixed(1)}ms · ${g.lastDecision}`);
+    }
+    return lines;
+}
+/**
+ * A DOM overlay, framework-free.
+ *
+ * Absolutely positioned, `pointer-events: none` — a debug HUD that eats clicks is a
+ * bug generator of its own. It is opt-in and never mounted unless asked for.
+ */
+class PerfHud {
+    constructor(host) {
+        this.host = host;
+    }
+    show() {
+        if (this.el)
+            return;
+        const el = this.host.ownerDocument.createElement('div');
+        el.setAttribute('data-grafloria-perf-hud', '');
+        // A debug overlay must never intercept input, and must never be picked up by a
+        // screen reader — it is developer instrumentation, not content.
+        el.setAttribute('aria-hidden', 'true');
+        el.style.cssText = [
+            'position:absolute',
+            'top:8px',
+            'left:8px',
+            'z-index:2147483000',
+            'pointer-events:none',
+            'font:11px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace',
+            'white-space:pre',
+            'padding:8px 10px',
+            'border-radius:6px',
+            'background:rgba(15,23,42,.82)',
+            'color:#e2e8f0',
+        ].join(';');
+        this.host.appendChild(el);
+        this.el = el;
+    }
+    update(snapshot) {
+        if (!this.el)
+            return;
+        this.el.textContent = formatSnapshot(snapshot).join('\n');
+    }
+    hide() {
+        var _a;
+        (_a = this.el) === null || _a === void 0 ? void 0 : _a.remove();
+        this.el = undefined;
+    }
+}
+exports.PerfHud = PerfHud;
+//# sourceMappingURL=perf-hud.js.map

package/src/libs/renderer/src/perf/perf-hud.js.map

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

package/src/libs/renderer/src/perf/quality-governor.d.ts

@@ -0,0 +1,77 @@
+/** How many tiers below the zoom-derived one we are currently rendering. */
+export type QualityBias = 0 | 1 | 2;
+export interface GovernorOptions {
+    /** The frame budget. 16.7ms = 60fps. */
+    budgetMs?: number;
+    /**
+     * Step DOWN when the median frame exceeds budget × this. Default 1.0 — the budget
+     * IS the line; there is no point having a budget you are content to miss.
+     */
+    downFactor?: number;
+    /**
+     * Step UP only when the median frame is below budget × this. Default 0.55 — the
+     * DEAD BAND. A tier that renders at 0.9× budget is doing its job; restoring detail
+     * would put us straight back over it, which is the oscillation this exists to
+     * prevent.
+     */
+    upFactor?: number;
+    /** Frames in the rolling window. */
+    window?: number;
+    /** Consecutive fast windows required before restoring a tier. Recovery is patient. */
+    recoveryWindows?: number;
+    /** Worst tier the governor may impose. */
+    maxBias?: QualityBias;
+    /**
+     * ESCALATION. A frame this many times over budget is not a slow frame, it is a
+     * structurally wrong one — and waiting a full window to notice means 12 frames
+     * of a visibly locked-up canvas. Default 4× (≈67ms: a third of a second of
+     * these and the user is already reaching for the tab close button).
+     */
+    panicFactor?: number;
+    /**
+     * How many frames the escalation path looks at. THREE, NOT ONE — and that is the
+     * whole subtlety. Reacting to a single catastrophic frame would make one GC pause
+     * indistinguishable from a scene the machine genuinely cannot draw. A median over
+     * three still rejects a lone spike (two of the three must be bad for the median to
+     * be bad) while reacting 4× sooner than the main window.
+     */
+    panicWindow?: number;
+}
+export interface GovernorState {
+    bias: QualityBias;
+    /** Median frame time over the window — what the decision is actually made on. */
+    medianMs: number;
+    /** Frames recorded so far in the current window. */
+    samples: number;
+    /** Consecutive fast windows accumulated toward a step back up. */
+    recoveryStreak: number;
+    /** Why the governor last changed its mind — surfaced in the HUD, because an
+     *  invisible governor is indistinguishable from a bug. */
+    lastDecision: 'steady' | 'stepped-down' | 'stepped-up' | 'escalated';
+}
+export declare class QualityGovernor {
+    private readonly options;
+    private frames;
+    private bias;
+    private recoveryStreak;
+    private lastDecision;
+    private lastMedian;
+    constructor(options?: GovernorOptions);
+    /** Feed the governor one frame time (ms). Returns the bias to render the NEXT frame at. */
+    record(frameMs: number): QualityBias;
+    /** The bias to apply right now. */
+    getBias(): QualityBias;
+    getState(): GovernorState;
+    /**
+     * Apply the bias to a zoom-derived tier.
+     *
+     * `tiers` must be ordered richest → poorest, which is the order the LOD config
+     * declares them in. The governor can only ever make the picture SIMPLER than the
+     * zoom asked for — never richer. A governor that could upgrade detail beyond what
+     * the zoom wants would draw labels on 4px nodes to fill spare budget, which is
+     * not a feature.
+     */
+    effectiveTier(zoomTier: string, tiers: readonly string[]): string;
+    /** Forget everything — e.g. after a diagram swap, where past frames say nothing. */
+    reset(): void;
+}