@driftengine/core 3.61.0

package/dist/render/renderQuality.js

@@ -0,0 +1,293 @@
+/** Construction-time GPU quality controls shared by every renderer resource. */
+import { MAX_AREA_LIGHTS } from './areaLights.js';
+import { MAX_GLOBAL_MEDIUM_STEPS } from './globalMedium.js';
+import { MAX_POINT_LIGHTS } from './lightBudget.js';
+import { PREFILTER_SAMPLE_COUNTS } from './prefilterEnvMap.js';
+export const MAX_SHADOW_FILTER_TAPS = 12;
+export const MAX_WATER_REFLECTION_FILTER_TAPS = 9;
+export const POINT_SHADOW_FADE_START = 0.35;
+export const DIRECTIONAL_SHADOW_FADE_START = 0.65;
+/**
+ * Current fidelity target. Different shadow projections use different texture
+ * dimensions for comparable visible detail: a cubemap spends its allocation
+ * six times, while the directional map spends all of it on one focused area.
+ */
+export const DEFAULT_RENDER_QUALITY = Object.freeze({
+    outputTransform: 'none',
+    outputExposure: 1,
+    pointLightFalloff: 'smooth',
+    /**
+     * Render at the display's own density, up to 2×.
+     *
+     * It was 1.75, which is a number that renders *nothing* at native resolution: every
+     * retina panel reports 2, so the drawing buffer was 87% of the pixels the screen has and
+     * the browser stretched the difference. It was found by comparing a small figure in a
+     * box against the world behind it: both were blurred, and for the same reason.
+     *
+     * 2 is where the ceiling belongs. It is what the overwhelming majority of high-density
+     * displays report, so it is the point at which a game stops being upscaled; past it the
+     * cost is quadratic for detail almost nobody can resolve, which is why there is a cap at
+     * all. A device that cannot hold its rate at 2 has the Low profile, which is a decision
+     * about pixels rather than a blur applied to everyone.
+     */
+    maxDevicePixelRatio: 2,
+    /**
+     * 12 megapixels, which is a guard rail rather than a haircut.
+     *
+     * At a density cap of 2 the drawing buffer is the panel's own pixels, so this does
+     * nothing at all up to and including 4K (8.3 MP) — the resolutions almost everybody is
+     * on keep every pixel they have. It starts holding at 5K and above, and on the
+     * high-density laptop panels whose logical size is large enough to ask for more than a
+     * 4K frame, which are exactly the cases where the density cap has stopped meaning
+     * anything about cost.
+     *
+     * A ceiling that never binds on common hardware is the point: the failure it exists to
+     * prevent is a frame that quietly grew past a vsync slot, and a cap only prevents that
+     * if it is above where people actually are. Consumers wanting the pixels set it to 0.
+     */
+    maxDrawingBufferPixels: 12_000_000,
+    directionalShadows: true,
+    pointShadows: true,
+    /* The engine's own budgets, which the renderer lowers per device when it has to. */
+    maxLights: MAX_POINT_LIGHTS,
+    maxAreaLights: MAX_AREA_LIGHTS,
+    directionalShadowMapSize: 2048,
+    pointShadowFaceSize: 512,
+    shadowFilterTaps: MAX_SHADOW_FILTER_TAPS,
+    lightVolumeSamples: 32,
+    directionalShadowDepthLayers: 2,
+    directionalShadowMaxDistance: 6,
+    directionalShadowMaxSlope: 3,
+    pointShadowRebakeDistance: 0.4,
+    pointShadowFacesPerFrame: 2,
+    /*
+     * Twelve, which is `LIVE_POINT_SHADOW_MAPS` cubemaps of six faces: exactly what the live
+     * loop took before it had a budget at all, so no existing consumer's shadows arrive at a
+     * different moment.
+     *
+     * **Six would have been the wrong default and looked like the right one.** The budget is
+     * shared across every live map rather than granted to each, so at six the first map takes
+     * the whole cubemap and the second — the one that exists only during an ownership handoff —
+     * gets nothing and never bakes. That is a mover's shadow vanishing exactly while a character
+     * crosses between two lamps, which is the moment the handoff exists to smooth over.
+     */
+    liveShadowFacesPerFrame: 12,
+    water: true,
+    screenEffects: true,
+    sceneSamples: 1,
+    planarReflections: false,
+    hdrScene: false,
+    cameraMotionBlur: 0,
+    temporalAa: false,
+    orderIndependent: false,
+    depthOfField: 0,
+    occlusionCulling: 0,
+    ambientOcclusion: 0,
+    nightEmissive: false,
+    bloom: 0,
+    /* Brighter than white, which is where a source of light sits and a reflecting surface does
+       not. Only consulted once the strength above is non-zero, and positive for the same reason
+       the occlusion radius is: a zero left sitting here would look legal and bloom the whole
+       frame the moment somebody turned the effect on. */
+    bloomThreshold: 1,
+    /* Off: a probe only exists once a caller bakes one, so nothing changes by default. */
+    reflectionProbeSize: 0,
+    /* On, because the cost of the feature is the probe and this only says whether one is allowed:
+       with the size at its own default of zero, leaving this true changes nothing at all. */
+    environmentReflections: true,
+    /* The medium tier. Powers of two only; see PREFILTER_SAMPLE_COUNTS for why. */
+    environmentPrefilterSamples: PREFILTER_SAMPLE_COUNTS.medium,
+    /* Off: the shipped look is the box chain. See the field for why the default is this way round. */
+    environmentPrefilter: false,
+    /* Half a metre, which is the scale of the gaps in a room and around a vehicle. Only
+       consulted when the strength above is non-zero, so it changes nothing by default. */
+    ambientOcclusionRadius: 0.5,
+    /* Off, so the medium costs nothing until a consumer asks for it. See the field. */
+    globalMediumSteps: 0,
+    /* Half, which is the resolution the upsample was designed against. */
+    globalMediumHalfResolution: true,
+    waterResolution: 128,
+    waterReflections: true,
+    /*
+     * Full, and deliberately not the half the GPU-budget design proposed as a free win.
+     *
+     * It is not free. The reflection is a second full submission of the scene, but with the
+     * GPU timer finally armed it measures **0.50 ms of an 18.00 ms frame** — the same 3%
+     * category the 72% shadow claim collapsed into. Trading a visibly softer reflection on
+     * every machine for 3% none of them needed is not a win, and it is worse than that in
+     * one place: this is construction-time, so a clip export cannot ask for full scale back,
+     * and an export is the one frame somebody keeps.
+     *
+     * The devices that genuinely cannot afford the target get it halved by the capability
+     * clamp in `renderer.ts` instead, where the cost is paid by the parts that need it paid.
+     */
+    waterReflectionScale: 1,
+    waterReflectionFilterTaps: MAX_WATER_REFLECTION_FILTER_TAPS,
+    underwaterAtmosphere: true,
+    plumeNoiseOctaves: 3,
+    capabilityClamp: true,
+    /*
+     * **Both back ON in 1.1.2, because the black screen they were turned off for was not them.**
+     *
+     * These are the only two changes in this engine whose correctness an immediate-mode desktop
+     * GPU physically cannot express: a discarded attachment costs nothing and changes nothing
+     * where the samples have nowhere else to be, and taking the swap chain late is
+     * indistinguishable from taking it early until a browser disagrees about when a frame is
+     * presented. So when all three consumers came back completely black on an iPhone 16 Pro,
+     * these two were the obvious suspects and both were defaulted off.
+     *
+     * They were not the cause and turning them off never lifted the black screen. It was a
+     * uniform array striding by four bytes where WGSL requires sixteen, which WebKit enforces
+     * and Dawn does not, so every shader that draws geometry failed to compile on iOS and
+     * nowhere else. Fixed in 1.1.1; the iOS black-screen investigation is
+     * the investigation, and the retreat here is the clearest thing it cost.
+     *
+     * **What leaving them off costs, measured on the gilded chamber at a phone viewport with
+     * `npm run frame-audit`:** 75.6 MB a frame against 49.7, which is 4.43 GB/s against 2.91 at
+     * 60 fps, and thirteen passes against twelve. Nearly all of it is the deferral — off it is
+     * 51.2 MB on its own, because opening the frame's pass eagerly forces a load and a store of
+     * the attachment for every mirror. The discard adds the last 1.5 MB and takes the frame's
+     * unreadable writes to zero. That is the entire mobile bandwidth result of 1.1.0, and it was
+     * being paid on exactly the devices it was measured for.
+     *
+     * **Still unverified on a tiler, and that has not changed.** What changed is that there is no
+     * longer an observed failure to attribute to them. `?discard=0` and `?defer=0` turn them off
+     * one at a time in all three consumers, so a device that misbehaves still names its own cause
+     * in two reloads.
+     */
+    discardResolvedAttachments: true,
+    deferFramePass: true,
+    frameGraph: true,
+    clusteredLights: false,
+    cullDraws: false,
+    /*
+     * The profiler stays off, and for its own reason rather than that one: it attaches a
+     * timestamp block to every render pass in the frame, which is a cost nobody who did not ask
+     * for a measurement should pay. `?gputiming=1` arms it.
+     */
+    gpuTiming: false,
+});
+/** Resolve and validate once at renderer construction, never in a hot path. */
+export function resolveRenderQuality(options = {}) {
+    const quality = {
+        outputTransform: options.outputTransform ?? DEFAULT_RENDER_QUALITY.outputTransform,
+        outputExposure: options.outputExposure ?? DEFAULT_RENDER_QUALITY.outputExposure,
+        pointLightFalloff: options.pointLightFalloff ?? DEFAULT_RENDER_QUALITY.pointLightFalloff,
+        maxDevicePixelRatio: options.maxDevicePixelRatio ?? DEFAULT_RENDER_QUALITY.maxDevicePixelRatio,
+        maxDrawingBufferPixels: options.maxDrawingBufferPixels ?? DEFAULT_RENDER_QUALITY.maxDrawingBufferPixels,
+        directionalShadows: options.directionalShadows ?? DEFAULT_RENDER_QUALITY.directionalShadows,
+        pointShadows: options.pointShadows ?? DEFAULT_RENDER_QUALITY.pointShadows,
+        /* Whole slots, at least one, never above what the shader is written for: these two are
+           interpolated into the source as array sizes, so a fractional or zero one is a shader that
+           does not compile and a larger one is arrays the uploads never fill. */
+        maxLights: Math.min(MAX_POINT_LIGHTS, Math.max(1, Math.round(options.maxLights ?? DEFAULT_RENDER_QUALITY.maxLights))),
+        maxAreaLights: Math.min(MAX_AREA_LIGHTS, Math.max(1, Math.round(options.maxAreaLights ?? DEFAULT_RENDER_QUALITY.maxAreaLights))),
+        directionalShadowMapSize: options.directionalShadowMapSize ?? DEFAULT_RENDER_QUALITY.directionalShadowMapSize,
+        pointShadowFaceSize: options.pointShadowFaceSize ?? DEFAULT_RENDER_QUALITY.pointShadowFaceSize,
+        shadowFilterTaps: options.shadowFilterTaps ?? DEFAULT_RENDER_QUALITY.shadowFilterTaps,
+        lightVolumeSamples: options.lightVolumeSamples ?? DEFAULT_RENDER_QUALITY.lightVolumeSamples,
+        directionalShadowDepthLayers: options.directionalShadowDepthLayers ?? DEFAULT_RENDER_QUALITY.directionalShadowDepthLayers,
+        directionalShadowMaxDistance: options.directionalShadowMaxDistance ?? DEFAULT_RENDER_QUALITY.directionalShadowMaxDistance,
+        directionalShadowMaxSlope: options.directionalShadowMaxSlope ?? DEFAULT_RENDER_QUALITY.directionalShadowMaxSlope,
+        pointShadowRebakeDistance: options.pointShadowRebakeDistance ?? DEFAULT_RENDER_QUALITY.pointShadowRebakeDistance,
+        pointShadowFacesPerFrame: options.pointShadowFacesPerFrame ?? DEFAULT_RENDER_QUALITY.pointShadowFacesPerFrame,
+        liveShadowFacesPerFrame: options.liveShadowFacesPerFrame ?? DEFAULT_RENDER_QUALITY.liveShadowFacesPerFrame,
+        water: options.water ?? DEFAULT_RENDER_QUALITY.water,
+        screenEffects: options.screenEffects ?? DEFAULT_RENDER_QUALITY.screenEffects,
+        sceneSamples: Math.max(1, Math.round(options.sceneSamples ?? DEFAULT_RENDER_QUALITY.sceneSamples)),
+        planarReflections: options.planarReflections ?? DEFAULT_RENDER_QUALITY.planarReflections,
+        hdrScene: options.hdrScene ?? DEFAULT_RENDER_QUALITY.hdrScene,
+        cameraMotionBlur: Math.min(1, Math.max(0, options.cameraMotionBlur ?? DEFAULT_RENDER_QUALITY.cameraMotionBlur)),
+        temporalAa: options.temporalAa ?? DEFAULT_RENDER_QUALITY.temporalAa,
+        orderIndependent: options.orderIndependent ?? DEFAULT_RENDER_QUALITY.orderIndependent,
+        depthOfField: Math.min(1, Math.max(0, options.depthOfField ?? DEFAULT_RENDER_QUALITY.depthOfField)),
+        occlusionCulling: Math.max(0, Math.round(options.occlusionCulling ?? DEFAULT_RENDER_QUALITY.occlusionCulling)),
+        ambientOcclusion: Math.min(1, Math.max(0, options.ambientOcclusion ?? DEFAULT_RENDER_QUALITY.ambientOcclusion)),
+        nightEmissive: options.nightEmissive ?? DEFAULT_RENDER_QUALITY.nightEmissive,
+        bloom: Math.min(1, Math.max(0, options.bloom ?? DEFAULT_RENDER_QUALITY.bloom)),
+        bloomThreshold: options.bloomThreshold ?? DEFAULT_RENDER_QUALITY.bloomThreshold,
+        reflectionProbeSize: Math.max(0, Math.round(options.reflectionProbeSize ?? DEFAULT_RENDER_QUALITY.reflectionProbeSize)),
+        environmentReflections: options.environmentReflections ?? DEFAULT_RENDER_QUALITY.environmentReflections,
+        /* At least one sample: zero would divide by an accumulated weight of zero and answer NaN,
+           which a half-float target spreads across every rough level rather than reporting. */
+        environmentPrefilterSamples: Math.max(1, Math.round(options.environmentPrefilterSamples ?? DEFAULT_RENDER_QUALITY.environmentPrefilterSamples)),
+        environmentPrefilter: options.environmentPrefilter ?? DEFAULT_RENDER_QUALITY.environmentPrefilter,
+        ambientOcclusionRadius: options.ambientOcclusionRadius ?? DEFAULT_RENDER_QUALITY.ambientOcclusionRadius,
+        /* Whole steps, and never past the shader's own loop bound: a uniform above it would make the
+           clamp inside the shader disagree with the step length computed from it, which is a march
+           that stops short of where it divided its distance. */
+        globalMediumSteps: Math.min(MAX_GLOBAL_MEDIUM_STEPS, Math.max(0, Math.round(options.globalMediumSteps ?? DEFAULT_RENDER_QUALITY.globalMediumSteps))),
+        globalMediumHalfResolution: options.globalMediumHalfResolution ?? DEFAULT_RENDER_QUALITY.globalMediumHalfResolution,
+        waterResolution: options.waterResolution ?? DEFAULT_RENDER_QUALITY.waterResolution,
+        waterReflections: options.waterReflections ?? DEFAULT_RENDER_QUALITY.waterReflections,
+        waterReflectionScale: options.waterReflectionScale ?? DEFAULT_RENDER_QUALITY.waterReflectionScale,
+        capabilityClamp: options.capabilityClamp ?? DEFAULT_RENDER_QUALITY.capabilityClamp,
+        gpuTiming: options.gpuTiming ?? DEFAULT_RENDER_QUALITY.gpuTiming,
+        discardResolvedAttachments: options.discardResolvedAttachments ?? DEFAULT_RENDER_QUALITY.discardResolvedAttachments,
+        deferFramePass: options.deferFramePass ?? DEFAULT_RENDER_QUALITY.deferFramePass,
+        frameGraph: options.frameGraph ?? DEFAULT_RENDER_QUALITY.frameGraph,
+        clusteredLights: options.clusteredLights ?? DEFAULT_RENDER_QUALITY.clusteredLights,
+        cullDraws: options.cullDraws ?? DEFAULT_RENDER_QUALITY.cullDraws,
+        waterReflectionFilterTaps: options.waterReflectionFilterTaps ?? DEFAULT_RENDER_QUALITY.waterReflectionFilterTaps,
+        underwaterAtmosphere: options.underwaterAtmosphere ?? DEFAULT_RENDER_QUALITY.underwaterAtmosphere,
+        plumeNoiseOctaves: options.plumeNoiseOctaves ?? DEFAULT_RENDER_QUALITY.plumeNoiseOctaves,
+    };
+    positive('maxDevicePixelRatio', quality.maxDevicePixelRatio);
+    // Zero is legal and means uncapped, so this is the non-negative check rather than
+    // the positive one.
+    nonNegative('maxDrawingBufferPixels', quality.maxDrawingBufferPixels);
+    positiveInteger('directionalShadowMapSize', quality.directionalShadowMapSize);
+    positiveInteger('pointShadowFaceSize', quality.pointShadowFaceSize);
+    positiveInteger('shadowFilterTaps', quality.shadowFilterTaps);
+    positiveInteger('lightVolumeSamples', quality.lightVolumeSamples);
+    positiveInteger('directionalShadowDepthLayers', quality.directionalShadowDepthLayers);
+    positive('directionalShadowMaxDistance', quality.directionalShadowMaxDistance);
+    positive('directionalShadowMaxSlope', quality.directionalShadowMaxSlope);
+    nonNegative('pointShadowRebakeDistance', quality.pointShadowRebakeDistance);
+    positiveInteger('pointShadowFacesPerFrame', quality.pointShadowFacesPerFrame);
+    positiveInteger('liveShadowFacesPerFrame', quality.liveShadowFacesPerFrame);
+    positiveInteger('waterResolution', quality.waterResolution);
+    positive('waterReflectionScale', quality.waterReflectionScale);
+    positiveInteger('waterReflectionFilterTaps', quality.waterReflectionFilterTaps);
+    positiveInteger('plumeNoiseOctaves', quality.plumeNoiseOctaves);
+    /* A radius of zero would ask every tap to land on the pixel it started from, which is not
+       "no occlusion" — it is a division by nothing in the estimator. Off is the strength. */
+    positive('ambientOcclusionRadius', quality.ambientOcclusionRadius);
+    /* Same shape as the radius above: a threshold of zero is not "bloom everything a little",
+       it is every pixel in the frame contributing its whole self. Off is the strength. */
+    positive('bloomThreshold', quality.bloomThreshold);
+    if (quality.shadowFilterTaps !== 4 &&
+        quality.shadowFilterTaps !== 8 &&
+        quality.shadowFilterTaps !== MAX_SHADOW_FILTER_TAPS) {
+        throw new Error(`RenderQuality.shadowFilterTaps must be 4, 8 or ${MAX_SHADOW_FILTER_TAPS}, got ${quality.shadowFilterTaps}`);
+    }
+    if (quality.directionalShadowDepthLayers !== 1 && quality.directionalShadowDepthLayers !== 2) {
+        throw new Error(`RenderQuality.directionalShadowDepthLayers must be 1 or 2, got ${quality.directionalShadowDepthLayers}`);
+    }
+    if (quality.plumeNoiseOctaves > 3) {
+        throw new Error(`RenderQuality.plumeNoiseOctaves must be <= 3, got ${quality.plumeNoiseOctaves}`);
+    }
+    if (quality.waterReflectionFilterTaps !== 1 &&
+        quality.waterReflectionFilterTaps !== 5 &&
+        quality.waterReflectionFilterTaps !== MAX_WATER_REFLECTION_FILTER_TAPS) {
+        throw new Error(`RenderQuality.waterReflectionFilterTaps must be 1, 5 or ${MAX_WATER_REFLECTION_FILTER_TAPS}, got ${quality.waterReflectionFilterTaps}`);
+    }
+    return Object.freeze(quality);
+}
+function positive(name, value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`RenderQuality.${name} must be a positive finite number, got ${value}`);
+    }
+}
+/** Zero is meaningful for a tolerance: it asks for the exact comparison. */
+function nonNegative(name, value) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`RenderQuality.${name} must be a non-negative finite number, got ${value}`);
+    }
+}
+function positiveInteger(name, value) {
+    positive(name, value);
+    if (!Number.isInteger(value)) {
+        throw new Error(`RenderQuality.${name} must be an integer, got ${value}`);
+    }
+}

package/dist/render/rendererHarness.d.ts

@@ -0,0 +1,39 @@
+export declare function recordingGl(options?: {
+    /**
+     * Extensions this context answers with an object rather than with `null`.
+     *
+     * **Opt-in, and the default of none is the honest one for most tests**: the shipped default
+     * answers `null` to everything, which is the weakest part this engine claims to run on and is
+     * what a test that does not care should be written against. A test that *is* about the branch
+     * an extension opens has to name it here, or the code under test refuses one step earlier and
+     * the test passes for the wrong reason — `EXT_color_buffer_float` is the worked example: with
+     * it absent, `OitPass` declines for the float colour buffer and every order-independent
+     * profile looks alike whatever its sample count.
+     */
+    readonly extensions?: readonly string[];
+    /**
+     * What this context reports for `MAX_FRAGMENT_UNIFORM_VECTORS`. 1024 by default.
+     *
+     * Named because it is a limit the renderer now *sizes a shader against* rather than merely
+     * compares: 256 is an Adreno 740 and 224 is what WebGL2 guarantees, and both are numbers at
+     * which the lit shader has to be built smaller than the engine's own budget.
+     */
+    readonly fragmentUniformVectors?: number;
+    /**
+     * The ceiling this fake driver actually enforces at link time, if it is not the one it admits.
+     *
+     * **For the gap between what a device reports and what it does.** `planLightBudget` counts an
+     * upper bound over the source, so the interesting failure is the other one: a program the
+     * arithmetic passed that the driver still refuses. Setting this below
+     * `fragmentUniformVectors` is that device, and it is what the renderer's retry is for.
+     * `Infinity` by default, so a link only ever fails where a test asked for it.
+     */
+    readonly refuseLinkAbove?: number;
+}): {
+    gl: WebGL2RenderingContext;
+    canvas: HTMLCanvasElement;
+    calls: {
+        name: string;
+        args: unknown[];
+    }[];
+};

package/dist/render/rendererHarness.js

@@ -0,0 +1,185 @@
+/**
+ * A WebGL2 context that answers everything, for tests that need a renderer and not a GPU.
+ *
+ * **Not a `.test.ts` file, and that is the point.** Vitest registers a test when the file
+ * declaring it is imported, so a second test file importing this from beside its own tests would
+ * re-run every test in that file as well — five today, and more with each one added. Split out so
+ * that importing the harness costs nothing but the harness.
+ *
+ * **Until this existed, nothing in this repository had ever constructed the WebGL2 `Renderer` in a
+ * test**, which is why every claim about that backend was settled by a capture — expensive, slow,
+ * and blind to anything the published scenes do not do. There is a `renderer.test.ts` beside that
+ * backend now, and what it pins is the shape a capture is worst at: a frame-wide decision taken
+ * from the profile, where the wrong answer still draws a plausible picture. The `Proxy` is the
+ * same trick `sceneTarget.test.ts` uses one level down: anything not named below is a recorded
+ * no-op returning a fresh object, so a constructor that touches several hundred entry points runs
+ * to completion and a test can assert the one thing it is about.
+ */
+import { countUniformVectors } from './uniformVectorBudget.js';
+export function recordingGl(options = {}) {
+    const extensions = new Set(options.extensions ?? []);
+    const reportedVectors = options.fragmentUniformVectors ?? 1024;
+    const enforcedVectors = options.refuseLinkAbove ?? Number.POSITIVE_INFINITY;
+    /** Fragment sources by shader handle, so a refusal can be decided from what was compiled. */
+    const fragmentSources = new WeakMap();
+    /** Each program's fragment source, gathered at `attachShader`. */
+    const programFragments = new WeakMap();
+    const calls = [];
+    const constants = {
+        ACTIVE_UNIFORMS: 0x8b86,
+        ACTIVE_ATTRIBUTES: 0x8b89,
+        COMPILE_STATUS: 0x8b81,
+        LINK_STATUS: 0x8b82,
+        FRAMEBUFFER_COMPLETE: 0x8cd5,
+        NO_ERROR: 0,
+        MAX_SAMPLES: 0x8d57,
+        MAX_TEXTURE_SIZE: 0x0d33,
+        MAX_TEXTURE_IMAGE_UNITS: 0x8872,
+        MAX_VERTEX_UNIFORM_VECTORS: 0x8dfb,
+        MAX_FRAGMENT_UNIFORM_VECTORS: 0x8dfd,
+        /*
+         * Enums a test needs to compare against, rather than merely to pass through.
+         *
+         * The `Proxy` below answers an unnamed property with a **fresh function**, so
+         * `gl.TEXTURE_2D_ARRAY` read twice is two different values and `toContain(gl.TEXTURE_2D)` can
+         * never match anything a call recorded. Anything a test asserts on has to be named here; a
+         * constant only ever passed along does not.
+         */
+        TEXTURE_2D: 0x0de1,
+        TEXTURE_2D_ARRAY: 0x8c1a,
+        DEPTH_COMPONENT24: 0x81a6,
+        DEPTH_ATTACHMENT: 0x8d00,
+        FRAMEBUFFER: 0x8d40,
+        NONE: 0,
+        ALWAYS: 0x0207,
+        LESS: 0x0201,
+        TEXTURE_MIN_FILTER: 0x2801,
+        TEXTURE_MAG_FILTER: 0x2800,
+        TEXTURE_WRAP_S: 0x2802,
+        TEXTURE_WRAP_T: 0x2803,
+        NEAREST: 0x2600,
+        CLAMP_TO_EDGE: 0x812f,
+        /* The blend factors, so a test can tell an additive stroke from a covering one. */
+        SRC_ALPHA: 0x0302,
+        ONE: 1,
+        ONE_MINUS_SRC_ALPHA: 0x0303,
+        TRIANGLES: 0x0004,
+        TEXTURE0: 0x84c0,
+        DEPTH_BUFFER_BIT: 0x00000100,
+        DEPTH_TEST: 0x0b71,
+        CULL_FACE: 0x0b44,
+        /* Named so a pass-owned attachment's two colour formats and its two attachment points can be
+           compared rather than merely passed along. See `passTarget.test.ts`. */
+        COLOR_ATTACHMENT0: 0x8ce0,
+        RGBA8: 0x8058,
+        RGBA16F: 0x881a,
+        RGBA: 0x1908,
+        UNSIGNED_BYTE: 0x1401,
+        HALF_FLOAT: 0x140b,
+        DEPTH_COMPONENT: 0x1902,
+        UNSIGNED_INT: 0x1405,
+        LINEAR: 0x2601,
+        COLOR_BUFFER_BIT: 0x00004000,
+        /* Named so a test can tell a mesh that declared itself deforming from one that did not. */
+        ARRAY_BUFFER: 0x8892,
+        STATIC_DRAW: 0x88e4,
+        DYNAMIC_DRAW: 0x88e8,
+    };
+    const answers = {
+        getParameter: (pname) => {
+            if (pname === constants.MAX_TEXTURE_SIZE)
+                return 4096;
+            if (pname === constants.MAX_TEXTURE_IMAGE_UNITS)
+                return 16;
+            if (pname === constants.MAX_SAMPLES)
+                return 4;
+            if (pname === constants.MAX_FRAGMENT_UNIFORM_VECTORS)
+                return reportedVectors;
+            if (pname === constants.MAX_VERTEX_UNIFORM_VECTORS)
+                return 1024;
+            /* Generous by default: every remaining limit is a ceiling something is checked against,
+               and a small answer is read as a device that cannot do the thing. */
+            return 4096;
+        },
+        getExtension: (name) => (extensions.has(String(name)) ? {} : null),
+        getShaderParameter: () => true,
+        /*
+         * A shader remembers its own source, and a program remembers its fragment one, so a link can
+         * be refused for the reason a real driver refuses it rather than by a flag. Both are no-ops
+         * for every test that does not set a ceiling.
+         */
+        createShader: (type) => ({ type }),
+        shaderSource: (shader, source) => {
+            if (typeof shader === 'object' && shader !== null && typeof source === 'string') {
+                fragmentSources.set(shader, source);
+            }
+        },
+        attachShader: (program, shader) => {
+            if (typeof program !== 'object' || program === null)
+                return;
+            if (typeof shader !== 'object' || shader === null)
+                return;
+            const source = fragmentSources.get(shader);
+            /* The fragment stage is the one with a `void main` and no attributes; `#version` is on both,
+               so the discriminator is the qualifier only a fragment stage declares. */
+            if (source !== undefined && source.includes('precision highp float;')) {
+                programFragments.set(program, source);
+            }
+        },
+        /* Linked yes; zero active uniforms and attributes, which ends every reflection loop at once
+           and is why this harness does not have to know a single uniform name. */
+        getProgramParameter: (program, pname) => {
+            if (pname === constants.ACTIVE_UNIFORMS || pname === constants.ACTIVE_ATTRIBUTES)
+                return 0;
+            if (pname !== constants.LINK_STATUS)
+                return true;
+            if (!Number.isFinite(enforcedVectors))
+                return true;
+            if (typeof program !== 'object' || program === null)
+                return true;
+            const source = programFragments.get(program);
+            return source === undefined || countUniformVectors(source) <= enforcedVectors;
+        },
+        getActiveUniform: () => ({ name: '', size: 1, type: 0 }),
+        getActiveAttrib: () => ({ name: '', size: 1, type: 0 }),
+        getUniformLocation: () => ({}),
+        getAttribLocation: () => -1,
+        checkFramebufferStatus: () => constants.FRAMEBUFFER_COMPLETE,
+        getError: () => constants.NO_ERROR,
+        getShaderInfoLog: () => '',
+        /* ANGLE's own words for this refusal, so a test asserting on the message is asserting on the
+           sentence a consumer actually pastes into a report. */
+        getProgramInfoLog: () => Number.isFinite(enforcedVectors)
+            ? `FRAGMENT shader uniforms count exceeds MAX_FRAGMENT_UNIFORM_VECTORS(${enforcedVectors})`
+            : '',
+        isContextLost: () => false,
+    };
+    const gl = new Proxy({}, {
+        get(_target, prop) {
+            if (prop in constants)
+                return constants[prop];
+            if (prop in answers) {
+                return (...args) => {
+                    calls.push({ name: prop, args });
+                    return answers[prop]?.(...args);
+                };
+            }
+            /* An unnamed call: recorded, and answered with a fresh object so a handle is a handle. */
+            return (...args) => {
+                calls.push({ name: prop, args });
+                return {};
+            };
+        },
+    });
+    const canvas = {
+        width: 640,
+        height: 480,
+        clientWidth: 640,
+        clientHeight: 480,
+        getContext: () => gl,
+        addEventListener: () => { },
+        removeEventListener: () => { },
+        getBoundingClientRect: () => ({ left: 0, top: 0, width: 640, height: 480 }),
+    };
+    return { gl, canvas, calls };
+}

package/dist/render/resolutionGovernor.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Hold a frame budget by moving the drawing-buffer scale, and nothing else.
+ *
+ * This is the safety net the GPU-budget design asks for, and the reason it is worth
+ * having is that it works on hardware nobody here owns — including hardware that does not
+ * exist yet. One of the three players whose reports started that design found the cure by
+ * hand: they shrank the browser window until the game was smooth. This does the same
+ * thing without asking anyone to.
+ *
+ * **Pure by design: no GL, no DOM, no clock.** Frame times come in, a new scale comes
+ * out, and the caller decides what to do with it. That is what makes it testable at all,
+ * because every device it exists for is one no test machine has.
+ *
+ * **Asymmetric on purpose.** Dropping is fast, because a player at 6 fps needs relief
+ * now. Raising is slow and waits behind several consecutive good windows, because a
+ * resolution that oscillates is more visible than one that is slightly too low.
+ */
+export interface GovernorLimits {
+    /**
+     * The frame time a frame is allowed, in milliseconds. Longer than this is a *long* frame.
+     *
+     * 40 rather than 16.67, and that gap is the tolerance. This is not a governor for
+     * squeezing a machine from 55 fps to 60: it exists for the parts that render at 4 to 9
+     * fps, and a trigger anywhere near the vsync interval would spend its life reacting to
+     * jitter on machines that are entirely fine. It is `LONG_FRAME_MS` from the consuming
+     * game's own frame health, deliberately, because that number has already been tuned
+     * against real false positives.
+     */
+    readonly budgetMs: number;
+    /**
+     * Share of a window's frames that must be long before the window counts as bad.
+     *
+     * **This is the guard that makes a busy high-end machine safe.** One hitch in sixty
+     * frames is a 1.7% share and decides nothing; a garbage collection, a shader compile, a
+     * texture upload or another application grabbing the GPU all look like that. Half the
+     * window being long is not a hitch, it is the machine.
+     */
+    readonly badShare: number;
+    /** Never go below this. A soft picture beats a slideshow. */
+    readonly minScale: number;
+    /** Frames per decision. One slow frame is noise; a window of them is evidence. */
+    readonly windowFrames: number;
+    /**
+     * Consecutive bad windows before the scale actually moves.
+     *
+     * The second half of the tolerance, and the same reasoning `SLOW_WINDOWS` carries in the
+     * game: one bad window is a level load, a world build, a tab that just came back. Two in
+     * a row is a machine, because none of those things happen twice in a row.
+     */
+    readonly badWindows: number;
+    /** How far to drop in one decision. */
+    readonly dropStep: number;
+    /** How far to raise in one decision. Deliberately smaller than `dropStep`. */
+    readonly raiseStep: number;
+    /** Consecutive clean windows required before raising at all. */
+    readonly raisePatience: number;
+}
+/**
+ * Deliberately hard to trigger. Work through what a healthy machine has to do to move it.
+ *
+ * At 120 fps, sixty frames is half a second. To drop one step a machine must spend **thirty
+ * of those sixty frames over 40 ms**, then do it again in the very next window: roughly a
+ * full second in which half the frames missed 25 fps. Nothing transient does that. A
+ * garbage collection is one frame, a shader compile is a handful, another application
+ * grabbing the GPU for a moment is a fraction of a window, and every one of them leaves the
+ * share far under a half.
+ *
+ * The devices this exists for are not marginal and do not need a sensitive trigger.
+ * `NFD6QQ`'s Adreno 619 held **156.66 ms** — every frame long, a share of 1.0 — so it
+ * clears two windows without ambiguity while a busy desktop never clears one.
+ *
+ * The 0.5 floor is `RESOLUTION_MIN` from the game's own settings screen, so the governor can
+ * never take a player somewhere they could not have gone themselves.
+ */
+export declare const DEFAULT_GOVERNOR_LIMITS: GovernorLimits;
+export declare class ResolutionGovernor {
+    private readonly limits;
+    private ceiling;
+    private current;
+    private frames;
+    private longFrames;
+    private badWindows;
+    private goodWindows;
+    constructor(ceiling: number, limits?: Partial<GovernorLimits>);
+    get scale(): number;
+    /**
+     * The player's own ceiling moved.
+     *
+     * A *lower* ceiling applies at once, because their choice is authority and waiting a
+     * window to honour it would be ignoring them. A *higher* one is only a permission: it
+     * does not raise the current scale, because jumping up would undo a drop the device had
+     * already earned. The patience path decides whether it can afford to climb back.
+     */
+    setCeiling(ceiling: number): void;
+    /** Start the window again, leaving the scale where it is. */
+    reset(): void;
+    /**
+     * One frame. Returns the new scale when it changed and `null` when it did not, so the
+     * caller does no GL or DOM work on an ordinary frame.
+     *
+     * `playable` exists because of `DZTF9F`, where an RTX 3060 filed a report calling
+     * itself unplayable from a menu: a menu frame and a hidden-tab frame are not verdicts
+     * about the machine. A governor that believed them would soften a game running
+     * perfectly, which is the same false positive with a more visible symptom.
+     */
+    sample(frameMs: number, playable: boolean): number | null;
+}