@vitreajs/vitrea 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -997,7 +997,7 @@ interface ZSlot {
     readonly order: number;
 }
 /** Viewport-space rectangle in CSS px, measured by platform-web and handed in as data. */
-interface Rect {
+interface Rect$1 {
     readonly x: number;
     readonly y: number;
     readonly width: number;
@@ -1006,9 +1006,9 @@ interface Rect {
 /** Back-to-front ordering: every base node before every overlay node, then by `order`. */
 declare function compareZSlot(a: ZSlot, b: ZSlot): number;
 /** Smallest rect containing both. */
-declare function unionRect(a: Rect, b: Rect): Rect;
+declare function unionRect(a: Rect$1, b: Rect$1): Rect$1;
 /** Grow a rect outwards on every side — how a group's proxy gets its padding. */
-declare function inflateRect(rect: Rect, by: number): Rect;
+declare function inflateRect(rect: Rect$1, by: number): Rect$1;
 /**
  * The part of `rect` that survives every clip in the chain.
  *
@@ -1031,13 +1031,13 @@ declare function inflateRect(rect: Rect, by: number): Rect;
  * — an overlap check that over-reports warns about something real-ish, one that
  * under-reports misses a genuine double-filter.
  */
-declare function clipRect(rect: Rect, clip: readonly Rect[] | undefined): Rect;
+declare function clipRect(rect: Rect$1, clip: readonly Rect$1[] | undefined): Rect$1;
 /**
  * Positive-area intersection. Touching edges are not an overlap — adjacent
  * surfaces in a toolbar are the common case and are legal. A degenerate rect
  * (an unmeasured or collapsed host) overlaps nothing.
  */
-declare function rectsOverlap(a: Rect, b: Rect): boolean;
+declare function rectsOverlap(a: Rect$1, b: Rect$1): boolean;
 
 /**
  * The scene model (§Core model): the three registries and everything that
@@ -1236,9 +1236,9 @@ interface GlassNodeDescriptor {
 interface GlassNodeRecord {
     readonly descriptor: GlassNodeDescriptor;
     /** Measured by platform-web in the read phase; absent until then. */
-    readonly bounds?: Rect;
+    readonly bounds?: Rect$1;
     /** Ancestor clip chain, viewport space. */
-    readonly clip?: readonly Rect[];
+    readonly clip?: readonly Rect$1[];
 }
 /** One pyramid rebuild. `groupIds` is why there is one request and not one per group. */
 interface BackdropRebuildRequest {
@@ -1335,7 +1335,7 @@ interface GlassScene {
     glassNode(id: string): GlassNodeRecord | undefined;
     nodesOfGroup(groupId: string): readonly GlassNodeRecord[];
     /** Measured viewport geometry, from the read phase. */
-    setNodeBounds(id: string, bounds: Rect, clip?: readonly Rect[]): void;
+    setNodeBounds(id: string, bounds: Rect$1, clip?: readonly Rect$1[]): void;
     /**
      * Scene-wide by default; per group when `groupId` is given.
      *
@@ -1747,11 +1747,12 @@ interface MaterialProfile {
      * substantial material. It casts deeper, richer shadows, has more pronounced
      * lensing and refraction effects, and a softer scattering of light" (S219). One
      * mechanism means one curve: `sizeThickness(span)` is a smoothstep from
-     * `sizeSpanMin` to `sizeSpanMax`, and **every** thickness-derived facet is a
-     * gain on it — the lens (`lensSizeGainMax`), the scattering
-     * (`sizeScatterGainMax`), the occlusion (`sizeOcclusionGain`) and the inner
-     * shadow (`sizeShadowGainMax`). Two curves would be two mechanisms, and the
-     * reference only has one.
+     * `sizeSpanMin` to `sizeSpanMax`, and the thickness-derived facets are gains
+     * on it — the lens (`lensSizeGainMax`), the occlusion (`sizeOcclusionGain`)
+     * and the inner shadow (`sizeShadowGainMax`). The scattering was one of them
+     * until W11c measured its curve to be a different one (a floor at small
+     * spans, a band top past 96 — see `sizeScatterFloor`); it now rides its own,
+     * from the same `sizeSpanMin`, and this band is untouched by it.
      *
      * A smoothstep rather than a straight ratio, so two surfaces of nearly the same
      * size never read as differently thick, and so every gain saturates instead of
@@ -1796,8 +1797,39 @@ interface MaterialProfile {
      * Both tiers carry it, from one function (`sizeScatterSigma`): the CSS tier
      * multiplies its `blur()` σ, and the GPU tier lerps its body sample toward the
      * chain level whose blur is that σ.
+     *
+     * MEASURED (W11c G1, claims §5.41), and no longer a gain on `sizeThickness`
+     * alone — see `sizeScatterFloor` and `sizeScatterSpanMax` below for the curve
+     * it rides. 8: the heavy component of the reference's interior sits near σ 10
+     * CSS px against a body σ of 1.25, and the gain sweep has a clear minimum at
+     * 8 (RMS 0.0164 against 0.0180 at 6 and 0.0191 at 10 on the probe bed).
      */
     readonly sizeScatterGainMax: number;
+    /**
+     * **The scattering facet's own curve** (W11c G1, claims §5.41).
+     *
+     * The reference's interior over structured content is two components, read
+     * off the W9 probe bed across four checkerboard pitches and five spans: a
+     * sharp one near σ 1.25 CSS px and a heavy one near σ 10, mixed by a share
+     * that is already ≈ 0.4 at spans of 32–44 and still rising at 160 (0.52 at
+     * 96, 0.64 at 128, 0.76 at 160). `sizeThickness` — zero at `sizeSpanMin` and
+     * saturated at `sizeSpanMax` = 96 — can express neither the floor nor a band
+     * top past 96, and moving `sizeSpanMax` would move the lens, the occlusion,
+     * the inner shadow and W9's thin/thick response rows with it. So the scatter
+     * mix rides its own curve:
+     *
+     * ```
+     * kScatter = floor + (1 − floor) · smoothstep(sizeSpanMin, sizeScatterSpanMax, span) · fold
+     * ```
+     *
+     * The floor is the material's own frost and is **not** folded under an
+     * accessibility preference; the span-dependent rise is a depth effect and
+     * folds like every other facet (`scatterThickness`). Fitted with `rrect-lg`
+     * held out: floor 0.40 (0.0175 at 0.3, 0.0174 at 0.45), band top 256 (0.0182
+     * at 224, 0.0174 at 320); the held-out cell's residual 0.0366 → 0.0174.
+     */
+    readonly sizeScatterFloor: number;
+    readonly sizeScatterSpanMax: number;
     /**
      * The occlusion gain — "a larger size is more opaque. A smaller size is
      * clearer" (S284). The fraction of the *remaining* transparency the size law
@@ -1828,9 +1860,17 @@ interface MaterialProfile {
      * an outer `box-shadow` the reference does not cast at all (Decision Log #32(c)).
      */
     readonly sizeShadowGainMax: number;
-    /** Chain LOD per CSS px of lens depth, and how much sharper the rim samples. */
-    readonly lensBodyLodPerPx: number;
-    readonly lensRimLodBias: number;
+    /**
+     * The lens's magnitude: the contour displacement in lens depths (W11c G2).
+     *
+     * The shader reads the body from `lensDepth × lensRefractionGain × (1 − depth)²`
+     * further inside, so the band is the plate folded back from that far in. The
+     * two rim-LOD constants that used to sit here (`lensBodyLodPerPx`,
+     * `lensRimLodBias`) are retired: the reference's band is not sharper than its
+     * interior — W11c G2 measured σ 6 → 4 → 3 → the deep value across the band —
+     * and the "sharper rim" was the fold, not a finer sample.
+     */
+    readonly lensRefractionGain: number;
     /**
      * What each accessibility regime does to the numbers above. The multipliers
      * match `platform-web`'s CSS tier so the two renderers degrade the same way
@@ -1859,28 +1899,39 @@ interface MaterialProfile {
     readonly strongBorderRim: MaterialRim;
     readonly reducedTintAdaptation: number;
     /**
-     * The author tint's tone map — Apple's "range of tones **mapped to content
-     * brightness underneath**" (S219), as four numbers.
+     * The author tint's shade law (W10) — Apple's "range of tones **mapped to
+     * content brightness underneath**" (S219), measured per pixel on the frozen
+     * bed and the W9 probe (claims §5.36).
      *
-     * The seed the author gives is not the colour the material paints. It is the
-     * middle of a range: over a dark backdrop the material shows a shade of the
-     * seed (`tintToneFloor`, a multiple of it in linear light, so hue and
-     * chromaticity survive); over a bright one it shows the seed washed toward
-     * white (`tintToneCeilMix`), which is what Apple's "changing its hue,
-     * brightness and saturation… without deviating too much from the intended
-     * color" describes. `tintToneLow`/`tintToneHigh` are the backdrop luminances
-     * the two ends are reached at, crossed with a smoothstep for the same reason
-     * `lensSpanMin`/`lensSpanMax` are.
+     * The tinted material is an OPAQUE, hue-preserving shade of the seed: the seed
+     * times a scalar, and the scalar is linear in the luminance the untinted
+     * material shows at the same pixel — `mix(tintShadeDark, tintShadeLight, u)`,
+     * clamped so a shade is never brighter than the seed. Over black content the
+     * reference shows about half the seed's light; over white it shows the seed
+     * itself; over a checkerboard it shows both, cell by cell, with the seed's
+     * chromaticity intact to three decimals at every pitch measured. That layer
+     * composites over the material at the AUTHOR's opacity (the colour's alpha) in
+     * the encoded space — the half-strength cell is the 0.501 encoded-space mix
+     * of its untinted and full-tinted twins, per channel — so the material's own
+     * alpha is not what a tinted surface shows.
+     *
+     * `tintShadeStrength` is the law's provenance gate: 1 where the constants were
+     * measured (the light scheme), 0 where they were not — the dark scheme
+     * renders the pure seed over every backdrop it was measured on, which is
+     * consistent with "a shade relative to the material's own body level" but is
+     * not yet separable from "no shading in the dark scheme". The collapse (W7)
+     * folds the shade out the same way, because a collapsed material IS a dark
+     * body and the reference renders the pure seed there too.
      *
-     * **Advisory and calibration-delegated**, like every other number in this
-     * profile: they are chosen so a tinted surface reads as coloured glass rather
-     * than as paint, and the tinted-capture extension fits them. Nothing here is
-     * measured yet, and no claim rests on these values.
+     * MEASURED, both scales, twelve light-standard cells across three pitches:
+     * fitted on the five probe cells only (17 700 px, RMS 0.0035) and refereed by
+     * every canonical tinted row. Mirrored by `@vitreajs/vitrea-web`'s
+     * `TINT_SHADE`, pinned in both directions by
+     * `packages/calibration/test/tier-coherence.test.ts`.
      */
-    readonly tintToneFloor: number;
-    readonly tintToneCeilMix: number;
-    readonly tintToneLow: number;
-    readonly tintToneHigh: number;
+    readonly tintShadeDark: number;
+    readonly tintShadeLight: number;
+    readonly tintShadeStrength: number;
     /**
      * **Backdrop tone adaptation (W7)** — the axis Apple's material has and this
      * one did not: over a dark enough backdrop the material stops being a lighter
@@ -1918,6 +1969,58 @@ interface MaterialProfile {
     readonly backdropToneLow: number;
     readonly backdropToneHigh: number;
     readonly backdropToneSizeBias: number;
+    /**
+     * **The backdrop tone response (W9)** — the law that owns the interior MEAN,
+     * where the four constants above own texture collapse and nothing else.
+     *
+     * The W9 probe falsified the mix-toward-backdrop form outright (claims
+     * §5.33): six cells need mix strengths outside [0, 1], because the
+     * reference adapts toward the material's own light/dark appearance, which
+     * coincides with the backdrop's tone only over `dark-solid` — the one
+     * background the mix was fitted on. What the probe measured instead is a
+     * LAW: at equal encoded-space backdrop mean the reference's settled
+     * interior is the same number regardless of the backdrop's structure
+     * (checker vs text rows, 0.81 both at input 0.69), so the interior level is
+     * a function `R(encodedMean, thickness)` and these constants are that
+     * function's anchors.
+     *
+     * `backdropToneAnchorX` is the three solid anchors' encoded-space means —
+     * measured backdrop luminances, not tuned. `backdropToneResponseThin` and
+     * `...Thick` are the reference's settled interior levels at those anchors
+     * for a thin surface (`sizeThickness` 0, the 32 px rrect) and a thick one
+     * (saturated, the 96 px+ rrects pooled — their residual spread ±0.012 is
+     * the accepted cost of `sizeSpanMax` saturation, claims §5.33). Between
+     * the rows: smoothstep in thickness; between the anchors: monotone
+     * (Fritsch–Carlson) interpolation in the ENCODED input, the space the
+     * probe validated to RMS 0.034 with zero fitting.
+     *
+     * Below the dark anchor the surface has no data (the probe's grid floor
+     * is `dark-solid`), and the one validation cell down there —
+     * `impulse__rrect-md`, backdrop 0.0039, reference 0.4358 — reads DARKER
+     * than the dark anchor's thick row, so clamping would regress it. The
+     * solve's authority fades to zero from the dark anchor downward
+     * (smoothstep over the anchor's own lower half, no new constant); the
+     * extreme-dark region stays with the collapse constants that were fitted
+     * on it.
+     */
+    readonly backdropToneAnchorX: readonly [number, number, number];
+    readonly backdropToneResponseThin: readonly [number, number, number];
+    readonly backdropToneResponseThick: readonly [number, number, number];
+    /**
+     * How much authority the response law has in THIS profile, 0…1 (W9).
+     *
+     * The anchors above are measurements of the LIGHT reference's settled
+     * appearance. The dark scheme's material settles at its own levels over the
+     * same backdrops (0.809 light against 0.055 dark over one checkerboard,
+     * §5.8), so a dark profile running the light response surface brightens the
+     * dark material toward the wrong scheme's appearance — measured on the
+     * canonical dark bed as ΔE p95 0.08 → 0.58 before this constant existed.
+     * The dark profiles set it to 0: the collapse (whose target is the
+     * backdrop, not a scheme's appearance) still runs there, and a dark
+     * response surface is follow-up work that needs the dark reference probed,
+     * not an assumption.
+     */
+    readonly backdropToneResponseStrength: number;
     /** The outer shadow (W8) — see `MaterialOuterShadow`. */
     readonly outerShadow: MaterialOuterShadow;
     /**
@@ -1950,22 +2053,26 @@ interface MaterialProfilePatch {
     readonly sizeSpanMax?: number;
     readonly lensSizeGainMax?: number;
     readonly sizeScatterGainMax?: number;
+    readonly sizeScatterFloor?: number;
+    readonly sizeScatterSpanMax?: number;
     readonly sizeOcclusionGain?: number;
     readonly sizeShadowGainMax?: number;
-    readonly lensBodyLodPerPx?: number;
-    readonly lensRimLodBias?: number;
+    readonly lensRefractionGain?: number;
     readonly reducedTransparencyFrost?: number;
     readonly increasedOcclusionLift?: number;
     readonly strongBorderRim?: Readonly<Partial<MaterialRim>>;
     readonly reducedTintAdaptation?: number;
-    readonly tintToneFloor?: number;
-    readonly tintToneCeilMix?: number;
-    readonly tintToneLow?: number;
-    readonly tintToneHigh?: number;
+    readonly tintShadeDark?: number;
+    readonly tintShadeLight?: number;
+    readonly tintShadeStrength?: number;
     readonly backdropToneMax?: number;
     readonly backdropToneLow?: number;
     readonly backdropToneHigh?: number;
     readonly backdropToneSizeBias?: number;
+    readonly backdropToneAnchorX?: readonly [number, number, number];
+    readonly backdropToneResponseThin?: readonly [number, number, number];
+    readonly backdropToneResponseThick?: readonly [number, number, number];
+    readonly backdropToneResponseStrength?: number;
     readonly outerShadow?: Readonly<Partial<MaterialOuterShadow>>;
     readonly lightDirection?: readonly [number, number];
     readonly sweepBandRadians?: number;
@@ -2189,137 +2296,6 @@ interface VideoProviderOptions {
     readonly generation?: number;
 }
 
-/**
- * Device ownership, loss teardown, and rebuild (§GPU device ownership).
- *
- * `platform-web` owns the *browser* half of the story — is there an adapter, get
- * a device, notice when it goes away. This module owns the *resource* half: what
- * has to be thrown away when a device dies, when it is safe to build again, and
- * what core's capability inputs should read while that is in flight.
- *
- * ## The two ownership modes, and why they are not symmetric
- *
- * - **vitrea-owned** — this module can re-request a device by itself, so loss is
- *   a transient it recovers from: tear down, re-request, re-attach, rebuild.
- *   Every backdrop source is re-imported on the next frame because loss marks
- *   them all dirty, which routes recovery through the same
- *   one-rebuild-per-dirty-source-per-frame path a content change takes rather
- *   than through a special case.
- * - **app-owned** — the app owns the resources that would have to be
- *   re-registered, so this module reports the loss, raises
- *   `replacementPending`, and **waits**. Groups stay demoted until
- *   `replaceDevice` arrives and the re-registration handshake completes. Inventing
- *   a device the app did not give us would break the one guarantee app-ownership
- *   exists for: that every texture the renderer samples came from the app's own
- *   device, because WebGPU has no cross-device sharing.
- *
- * `info.reason === "destroyed"` is our own teardown and is not recovered from —
- * re-requesting there would resurrect a renderer the host just destroyed.
- *
- * ## Generations
- *
- * Every attach bumps a generation counter, and every GPU object this package
- * holds is tagged with the generation it was made under. A resource from a lost
- * device is unusable forever, and the failure mode is silent — bindings simply
- * produce nothing — so "is this from the current device" has to be a cheap
- * integer comparison somewhere. It is here.
- */
-/**
- * Structurally identical to `vitrea`'s `WebGPUAvailability` (X2's K1
- * amendment, Decision Log #21c). Declared here rather than imported because this
- * package sits *below* core in the dependency graph — core reaches the renderer
- * through a dynamic import, so an import back would close a cycle. A test pins
- * the two unions to the same members.
- */
-type WebGPUAvailability = "not-requested" | "unavailable" | "available";
-type DeviceOwnership = "vitrea" | "app";
-interface RendererDeviceStatus {
-    /** Feeds core's `PlatformProbe.webgpu` unchanged. */
-    readonly webgpu: WebGPUAvailability;
-    readonly deviceHealth: "ok" | "lost";
-    readonly ownership: DeviceOwnership;
-    readonly device: GPUDevice | undefined;
-    /** Bumped on every attach. Tags every resource built under it. */
-    readonly generation: number;
-    /** True while an app-owned device is lost and no replacement has arrived. */
-    readonly replacementPending: boolean;
-    /** Why there is no device, when there is a reason worth reporting. */
-    readonly unavailableReason?: "no-adapter" | "device-request-failed" | "lost";
-}
-/** The capability facts a host folds into core's `PlatformProbe`. */
-interface DeviceCapabilityInput {
-    readonly webgpu: WebGPUAvailability;
-    readonly deviceHealth: "ok" | "lost";
-}
-
-/**
- * The governor's knobs.
- *
- * §Performance envelope: "The governor degrades **within** a tier first
- * (refraction resolution, adaptation cadence, edge analysis) and switches tiers
- * only with long hysteresis and cooldown." Decision Log #19 adds that intra-tier
- * degradation is **not a state change** — a group under `degrade-in-tier`
- * pressure keeps `activeRenderer: "webgpu"` and its whole resolved state.
- *
- * So the split is: **the policy lives in core, the knobs live here.** This module
- * exposes what can be turned and publishes a suggested ladder as *data*; it never
- * decides to turn anything, never reads a clock, and never applies hysteresis.
- * A governor that lived in the renderer would be a governor that could not see
- * the scene it is governing.
- *
- * ## The three knobs, weakest cost first
- *
- * 1. **`fieldFamily`** — `rsupn` → `rsup`. S2 priced this at 29% of the field's
- *    cost for a bound that degrades from 0.170 px / 2.91° to 0.574 px / 4.26°.
- *    It is the *first* step because it is one uniform and one pipeline: no
- *    resolution change, so nothing resamples and nothing shimmers as it engages.
- *    **Conditional on the f32 cross-check** (Decision Log #20) — and the check
- *    has now been run, so the condition is met. See `FAMILY_C_CROSS_CHECK`.
- * 2. **`refractionResolutionScale`** — the group's **field** targets are
- *    rasterised at a fraction of device resolution, and the optics and highlight
- *    passes filter them instead of indexing them (`passes.ts`, and the
- *    `fieldUpsampled` flag both shaders branch on). Quadratic saving on the pass
- *    that evaluates the pseudo-SDF union per pixel per member, and the most
- *    visible step, so it comes second.
- *
- *    What it does **not** yet do is shrink the optics and highlight passes
- *    themselves: those still render at full device resolution into the plane
- *    canvases, because rendering them smaller means an offscreen target and a
- *    resolve pass rather than a change of extent. So rungs 2 and 3 deliver the
- *    field's quadratic saving and the cadence saving, not the full quadratic
- *    saving on both heavy passes. Recorded here rather than implied, because a
- *    ladder whose rungs are priced for savings they do not deliver is a ladder
- *    core's policy will walk too far down.
- * 3. **`adaptationCadenceHz`** — how often analysis is reduced and read back.
- *    Cheapest of the three in visual terms because the values it feeds are
- *    already low-passed over hundreds of milliseconds; dropping the cadence
- *    mostly changes how quickly a scroll's new backdrop is noticed.
- */
-type FieldFamily = "rsupn" | "rsup";
-interface GovernorKnobs {
-    /** Which pseudo-SDF family the field pass compiles. */
-    readonly fieldFamily: FieldFamily;
-    /**
-     * Device-resolution fraction the group's field targets are rasterised at,
-     * 0 < s <= 1. The optics and highlight passes upsample what they read. See the
-     * module note for what this does and does not save.
-     */
-    readonly refractionResolutionScale: number;
-    /** Analysis reduction + readback rate. 0 disables adaptation entirely. */
-    readonly adaptationCadenceHz: number;
-}
-interface Governor {
-    readonly knobs: GovernorKnobs;
-    /** True when `fieldFamily: "rsup"` is permitted to engage. */
-    readonly familyCVerified: boolean;
-    set(patch: Partial<GovernorKnobs>): GovernorKnobs;
-    /** Move to a rung of the suggested ladder. Out-of-range clamps to the ends. */
-    setLevel(level: number): GovernorKnobs;
-    reset(): GovernorKnobs;
-    /** Record that the cross-check passed, unlocking family C. */
-    recordFamilyCVerified(): void;
-}
-
 /**
  * What the renderer consumes each frame, and why it is declared here rather than
  * imported from `vitrea`.
@@ -2351,6 +2327,13 @@ interface Governor {
  * none in core.
  */
 
+/** Viewport-space rectangle in CSS px. Matches core's `Rect`. */
+interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
 /** Motion-driver outputs for one surface. Every one is a value, never a time. */
 interface SurfaceChannels {
     /** `pressCompression`, 0..1. Scaled by motion's `pressCompressionScale`. */
@@ -2440,6 +2423,45 @@ interface GroupRenderInput {
      * back to a level nobody measured.
      */
     readonly backdropTone?: Rgb;
+    /**
+     * The backdrop's ENCODED-space tone level (W9, claims §5.31–§5.34): the mean
+     * taken in sRGB-encoded space, decoded once — the input the reference's tone
+     * response tracks, feeding the collapse band's argument and the response
+     * curve. Distinct from `backdropTone` on any structured backdrop: the
+     * COLOUR is the physical linear mean (what the collapse converges onto —
+     * on the impulse grid the two differ 2.6×, and converging onto the encoded
+     * reading was a measured ΔE p95 0.03 → 0.12 regression), while the LEVEL is
+     * the encoded reading. Absent falls back to `backdropTone`'s own luminance.
+     */
+    readonly backdropToneLevel?: number;
+    /**
+     * The backdrop's LINEAR-space mean luminance, beside `backdropToneLevel`'s
+     * encoded-space reading (W9, claims §5.31). The per-pixel tint-tone input
+     * samples a chain that averages linearly, so the optics pass multiplies it by
+     * `backdropToneLevel / backdropToneLinearLuminance` — locality is
+     * preserved and the input's spatial mean matches the model exactly. Absent
+     * (or equal to the tone's level) collapses the ratio to 1.
+     */
+    readonly backdropToneLinearLuminance?: number;
+    /**
+     * The material's tint and alpha for a group that samples NOTHING (W11a) — a
+     * `css-backdrop` group whose blurred backdrop is a DOM proxy beneath the
+     * canvas, or a `none` group over the page itself. Such a group's body is
+     * not composited in the shader: the optics pass writes the material as a
+     * premultiplied layer and the browser composites it over the DOM, in
+     * encoded sRGB. A linear-light alpha written into that composite lands the
+     * surface darker than the same material sampled on the GPU — the gap
+     * `cssTintAlpha` closes for the CSS tier, at a declared reference level —
+     * so the host, which owns that mapping, resolves the pair once and hands
+     * the same numbers to both tiers. Linear light; the renderer folds the
+     * accessibility policy over it exactly as over the profile's own. Ignored
+     * wherever the group samples a backdrop; absent, the profile's pair is
+     * written as it is (the golden harness, which has no host).
+     */
+    readonly unsampledMaterial?: {
+        readonly tint: Rgb;
+        readonly tintAlpha: number;
+    };
     readonly variant?: MaterialVariant;
     /** Overrides the calibration-delegated union defaults. */
     readonly union?: GroupUnionParams;
@@ -2488,6 +2510,173 @@ interface FrameParticipantView {
     readonly render?: (context: FrameContextView) => void;
 }
 
+/**
+ * Where a backdrop texture sits on the plane, and what that makes of a CSS px.
+ *
+ * The optics pass samples the backdrop through one uv transform on
+ * viewport-normalised coordinates — `uv = viewport01 · scale + offset` — and
+ * the pyramid converts the material's CSS-px σ into source texels once, at build.
+ * Both numbers are functions of the same thing: the rectangle of the viewport the
+ * texture's pixels actually occupy. This module is the one place that rectangle
+ * turns into either.
+ *
+ * ## Placed
+ *
+ * A texture handed over from a DOM element — an `<img>`, a `<canvas>`, a
+ * `<video>` — has a box the host measures every read phase, in CSS px relative
+ * to the viewport, and that box IS the placement: a 320 px raster in the corner
+ * of a 1440 px page maps the 320 px, not the page. The source's own extent is
+ * still what the pyramid is built from; the placement only says where on the
+ * plane its texels land, so one texel is `placement.width / sourceWidth` CSS px.
+ *
+ * Outside the placement the sampler clamps to the edge. A surface hanging past
+ * the texture's box reads the nearest edge texel rather than nothing; the
+ * unsampled layer (W11a) is not applied to partial overlap in this cut.
+ *
+ * ## Cover
+ *
+ * A source with no placement — an `ImageBitmap`, an `OffscreenCanvas`, an
+ * element not in the document, or a renderer driven without a host at all —
+ * keeps the original rule: the backdrop fills the viewport and the overflow is
+ * cropped symmetrically. Every golden and every calibration capture was taken
+ * with the texture the size of the stage, where the two rules coincide exactly;
+ * the demo's reference panel is where they came apart (claims §5.47).
+ */
+
+/** A backdrop source's box on the plane, in CSS px relative to the viewport. */
+type BackdropPlacement = Rect;
+
+/**
+ * Device ownership, loss teardown, and rebuild (§GPU device ownership).
+ *
+ * `platform-web` owns the *browser* half of the story — is there an adapter, get
+ * a device, notice when it goes away. This module owns the *resource* half: what
+ * has to be thrown away when a device dies, when it is safe to build again, and
+ * what core's capability inputs should read while that is in flight.
+ *
+ * ## The two ownership modes, and why they are not symmetric
+ *
+ * - **vitrea-owned** — this module can re-request a device by itself, so loss is
+ *   a transient it recovers from: tear down, re-request, re-attach, rebuild.
+ *   Every backdrop source is re-imported on the next frame because loss marks
+ *   them all dirty, which routes recovery through the same
+ *   one-rebuild-per-dirty-source-per-frame path a content change takes rather
+ *   than through a special case.
+ * - **app-owned** — the app owns the resources that would have to be
+ *   re-registered, so this module reports the loss, raises
+ *   `replacementPending`, and **waits**. Groups stay demoted until
+ *   `replaceDevice` arrives and the re-registration handshake completes. Inventing
+ *   a device the app did not give us would break the one guarantee app-ownership
+ *   exists for: that every texture the renderer samples came from the app's own
+ *   device, because WebGPU has no cross-device sharing.
+ *
+ * `info.reason === "destroyed"` is our own teardown and is not recovered from —
+ * re-requesting there would resurrect a renderer the host just destroyed.
+ *
+ * ## Generations
+ *
+ * Every attach bumps a generation counter, and every GPU object this package
+ * holds is tagged with the generation it was made under. A resource from a lost
+ * device is unusable forever, and the failure mode is silent — bindings simply
+ * produce nothing — so "is this from the current device" has to be a cheap
+ * integer comparison somewhere. It is here.
+ */
+/**
+ * Structurally identical to `vitrea`'s `WebGPUAvailability` (X2's K1
+ * amendment, Decision Log #21c). Declared here rather than imported because this
+ * package sits *below* core in the dependency graph — core reaches the renderer
+ * through a dynamic import, so an import back would close a cycle. A test pins
+ * the two unions to the same members.
+ */
+type WebGPUAvailability = "not-requested" | "unavailable" | "available";
+type DeviceOwnership = "vitrea" | "app";
+interface RendererDeviceStatus {
+    /** Feeds core's `PlatformProbe.webgpu` unchanged. */
+    readonly webgpu: WebGPUAvailability;
+    readonly deviceHealth: "ok" | "lost";
+    readonly ownership: DeviceOwnership;
+    readonly device: GPUDevice | undefined;
+    /** Bumped on every attach. Tags every resource built under it. */
+    readonly generation: number;
+    /** True while an app-owned device is lost and no replacement has arrived. */
+    readonly replacementPending: boolean;
+    /** Why there is no device, when there is a reason worth reporting. */
+    readonly unavailableReason?: "no-adapter" | "device-request-failed" | "lost";
+}
+/** The capability facts a host folds into core's `PlatformProbe`. */
+interface DeviceCapabilityInput {
+    readonly webgpu: WebGPUAvailability;
+    readonly deviceHealth: "ok" | "lost";
+}
+
+/**
+ * The governor's knobs.
+ *
+ * §Performance envelope: "The governor degrades **within** a tier first
+ * (refraction resolution, adaptation cadence, edge analysis) and switches tiers
+ * only with long hysteresis and cooldown." Decision Log #19 adds that intra-tier
+ * degradation is **not a state change** — a group under `degrade-in-tier`
+ * pressure keeps `activeRenderer: "webgpu"` and its whole resolved state.
+ *
+ * So the split is: **the policy lives in core, the knobs live here.** This module
+ * exposes what can be turned and publishes a suggested ladder as *data*; it never
+ * decides to turn anything, never reads a clock, and never applies hysteresis.
+ * A governor that lived in the renderer would be a governor that could not see
+ * the scene it is governing.
+ *
+ * ## The three knobs, weakest cost first
+ *
+ * 1. **`fieldFamily`** — `rsupn` → `rsup`. S2 priced this at 29% of the field's
+ *    cost for a bound that degrades from 0.170 px / 2.91° to 0.574 px / 4.26°.
+ *    It is the *first* step because it is one uniform and one pipeline: no
+ *    resolution change, so nothing resamples and nothing shimmers as it engages.
+ *    **Conditional on the f32 cross-check** (Decision Log #20) — and the check
+ *    has now been run, so the condition is met. See `FAMILY_C_CROSS_CHECK`.
+ * 2. **`refractionResolutionScale`** — the group's **field** targets are
+ *    rasterised at a fraction of device resolution, and the optics and highlight
+ *    passes filter them instead of indexing them (`passes.ts`, and the
+ *    `fieldUpsampled` flag both shaders branch on). Quadratic saving on the pass
+ *    that evaluates the pseudo-SDF union per pixel per member, and the most
+ *    visible step, so it comes second.
+ *
+ *    What it does **not** yet do is shrink the optics and highlight passes
+ *    themselves: those still render at full device resolution into the plane
+ *    canvases, because rendering them smaller means an offscreen target and a
+ *    resolve pass rather than a change of extent. So rungs 2 and 3 deliver the
+ *    field's quadratic saving and the cadence saving, not the full quadratic
+ *    saving on both heavy passes. Recorded here rather than implied, because a
+ *    ladder whose rungs are priced for savings they do not deliver is a ladder
+ *    core's policy will walk too far down.
+ * 3. **`adaptationCadenceHz`** — how often analysis is reduced and read back.
+ *    Cheapest of the three in visual terms because the values it feeds are
+ *    already low-passed over hundreds of milliseconds; dropping the cadence
+ *    mostly changes how quickly a scroll's new backdrop is noticed.
+ */
+type FieldFamily = "rsupn" | "rsup";
+interface GovernorKnobs {
+    /** Which pseudo-SDF family the field pass compiles. */
+    readonly fieldFamily: FieldFamily;
+    /**
+     * Device-resolution fraction the group's field targets are rasterised at,
+     * 0 < s <= 1. The optics and highlight passes upsample what they read. See the
+     * module note for what this does and does not save.
+     */
+    readonly refractionResolutionScale: number;
+    /** Analysis reduction + readback rate. 0 disables adaptation entirely. */
+    readonly adaptationCadenceHz: number;
+}
+interface Governor {
+    readonly knobs: GovernorKnobs;
+    /** True when `fieldFamily: "rsup"` is permitted to engage. */
+    readonly familyCVerified: boolean;
+    set(patch: Partial<GovernorKnobs>): GovernorKnobs;
+    /** Move to a rung of the suggested ladder. Out-of-range clamps to the ends. */
+    setLevel(level: number): GovernorKnobs;
+    reset(): GovernorKnobs;
+    /** Record that the cross-check passed, unlocking family C. */
+    recordFamilyCVerified(): void;
+}
+
 /**
  * Pass-by-pass timing, for the benchmark §Performance envelope pins the ~2 ms
  * hypothesis to.
@@ -2654,6 +2843,17 @@ interface PyramidResources {
      * from without knowing where the body already sits.
      */
     readonly bodySigmaTexels: number;
+    /**
+     * Source texels per CSS px the build converted `bodySigmaCss` with — the placed
+     * density where the source had a placement, the cover ratio where it did not
+     * (`backdrop-fit.ts`) — and the source extent it was computed from. Recorded so
+     * a later request can tell whether the body it would produce differs from the
+     * one on the chain: a static image never re-dirties, so a placement whose SIZE
+     * moved is the only signal that the σ in texels has gone stale.
+     */
+    readonly texelsPerCss: number;
+    readonly sourceWidth: number;
+    readonly sourceHeight: number;
 }
 interface PyramidInstrumentation {
     /** Successful rebuilds since the store was created. */
@@ -2684,6 +2884,11 @@ interface PyramidBuildRequest {
      */
     readonly bodySigmaCss: number;
     readonly viewportCss: readonly [number, number];
+    /**
+     * Where the source sits on the plane, in CSS px relative to the viewport, if
+     * the host measured one. Absent, the source is cover-fit to the viewport.
+     */
+    readonly placement?: BackdropPlacement;
 }
 type PyramidBuildOutcome = {
     readonly status: "built";
@@ -2868,6 +3073,16 @@ interface GlassRenderer {
     registerBackdrop(provider: BackdropProvider): void;
     unregisterBackdrop(sourceId: string): void;
     backdrop(sourceId: string): BackdropProvider | undefined;
+    /**
+     * Where a source's pixels sit on the plane, in CSS px relative to the viewport
+     * (`backdrop-fit.ts`). Set every read phase by a host that measured the source
+     * element's box; `undefined` (or never set) is the cover fit, the rule every
+     * golden and calibration capture was taken under. Accepted before the provider
+     * is registered and kept across device generations; cleared by
+     * `unregisterBackdrop`.
+     */
+    setBackdropPlacement(sourceId: string, placement: BackdropPlacement | undefined): void;
+    backdropPlacement(sourceId: string): BackdropPlacement | undefined;
     setViewport(viewport: ViewportState): void;
     readonly viewport: ViewportState;
     setGroup(input: GroupRenderInput): void;
@@ -2963,4 +3178,4 @@ declare const VITREA_CONTRACTS: {
 declare const RENDERER_TIERS: readonly ["webgpu", "css"];
 type RendererTier = (typeof RENDERER_TIERS)[number];
 
-export { ACCESSIBILITY_BEHAVIOR_TABLE, ACCESSIBILITY_FLAGS, ACCESSIBILITY_PRECEDENCE, type AccessibilityConsequences, type AccessibilityFlag, type AccessibilityOverride, type AccessibilityOverrides, type ActiveRenderer, type AnalysisQuality, type BackdropEstimatorProvider, type BackdropHint, type BackdropHintRequest, type BackdropProvider, type BackdropRebuildRequest, type BackdropResolutionPolicy, type BackdropSourceDescriptor, type BackdropSourceRecord, type BackdropTone, type CapabilityInputs, type ConcentricParent, type ConfiguredSource, type CopyProviderOptions, type CornerProfile, type CornerRadii, type CornerReference, DEFAULT_BACKDROP_RESOLUTION, DEFAULT_CLEAR_DIMMING, DEFAULT_GROUP_SAMPLING, DEMOTION_REASONS, DEMOTION_RECOVERY, DIAGNOSTIC_CODES, type DemotionReason, type DescriptorPatch, type Diagnostic, type DiagnosticCode, type DiagnosticSeverity, type DiagnosticSink, type DiagnosticsChannel, type DiagnosticsChannelOptions, type DimmingPolicy, type DomBackdropSource, FOREGROUND_MODES, FRAME_PHASES, type ForegroundAdaptation, type ForegroundMode, type ForegroundResolutionOptions, type FrameContext, type FrameInfo, type FrameParticipant, type FramePhase, type FrameReport, type FrameScheduler, type FrameSchedulerOptions, GLASS_PLANES, GOVERNOR_PRESSURES, type GlassGroupDescriptor, type GlassGroupRecord, type GlassGroupState, type GlassNodeDescriptor, type GlassNodeRecord, type GlassPlane, type GlassRenderer, type GlassScene, GlassSceneError, type GlassSceneErrorCode, type GlassSceneOptions, type GlassTint, type GovernorPressure, type GroupHealth, type GroupSamplingGeometry, type GroupStateChange, HINT_AVAILABILITIES, type HintAvailability, type InteractionState, MATERIAL_VARIANTS$1 as MATERIAL_VARIANTS, type MaterialProfile$1 as MaterialProfile, type MaterialRequest, type MaterialVariant$1 as MaterialVariant, type MotionChannel, type MotionDriverKind, NOMINAL_ACCESSIBILITY_POLICY, OVERRIDABLE_ACCESSIBILITY_FLAGS, type OverridableAccessibilityFlag, type PlaneOverlap, type PlatformProbe, type ProxyOverlap, RENDERER_TIERS, type RecoveryContract, type RecoveryTrigger, type Rect, type RefractionQuality, type RendererTier, type ResolvedAccessibilityPolicy, type ResolvedBackdropHint, type ResolvedForegroundAdaptation, type ResolvedGroup, type ResolvedMaterial, type ResolvedMaterialPolicy, type ResolvedMotionPolicy, type ResolvedNode, SAMPLED_ASYNC_DEFAULTS, SAMPLED_ASYNC_RATE_LIMITS, type SamplingBackend, type SceneResolution, type ShapeChannels, type ShapeFamily, type SourceProbe, type StateChange, type SystemAccessibilityPreferences, type TextureBackdropSource, type TintColor, type TintMixingCheck, VITREA_CONTRACTS, type VariantMixingCheck, type Vec2, type VideoProviderOptions, WEBGPU_AVAILABILITIES, type WebGPUAvailability$1 as WebGPUAvailability, type WebGPURendererModule, type ZSlot, checkTintMixing, checkVariantMixing, classifyStateChange, clipRect, compareZSlot, createDiagnosticsChannel, createFrameScheduler, createGlassScene, defaultForegroundAdaptation, glassTint, inflateRect, isHealthy, loadWebGPURenderer, loadWebGPURendererModule, rectsOverlap, resolveAccessibilityPolicy, resolveBackdropHint, resolveForegroundAdaptation, resolveGlassGroupState, resolveMaterial, unionRect };
+export { ACCESSIBILITY_BEHAVIOR_TABLE, ACCESSIBILITY_FLAGS, ACCESSIBILITY_PRECEDENCE, type AccessibilityConsequences, type AccessibilityFlag, type AccessibilityOverride, type AccessibilityOverrides, type ActiveRenderer, type AnalysisQuality, type BackdropEstimatorProvider, type BackdropHint, type BackdropHintRequest, type BackdropProvider, type BackdropRebuildRequest, type BackdropResolutionPolicy, type BackdropSourceDescriptor, type BackdropSourceRecord, type BackdropTone, type CapabilityInputs, type ConcentricParent, type ConfiguredSource, type CopyProviderOptions, type CornerProfile, type CornerRadii, type CornerReference, DEFAULT_BACKDROP_RESOLUTION, DEFAULT_CLEAR_DIMMING, DEFAULT_GROUP_SAMPLING, DEMOTION_REASONS, DEMOTION_RECOVERY, DIAGNOSTIC_CODES, type DemotionReason, type DescriptorPatch, type Diagnostic, type DiagnosticCode, type DiagnosticSeverity, type DiagnosticSink, type DiagnosticsChannel, type DiagnosticsChannelOptions, type DimmingPolicy, type DomBackdropSource, FOREGROUND_MODES, FRAME_PHASES, type ForegroundAdaptation, type ForegroundMode, type ForegroundResolutionOptions, type FrameContext, type FrameInfo, type FrameParticipant, type FramePhase, type FrameReport, type FrameScheduler, type FrameSchedulerOptions, GLASS_PLANES, GOVERNOR_PRESSURES, type GlassGroupDescriptor, type GlassGroupRecord, type GlassGroupState, type GlassNodeDescriptor, type GlassNodeRecord, type GlassPlane, type GlassRenderer, type GlassScene, GlassSceneError, type GlassSceneErrorCode, type GlassSceneOptions, type GlassTint, type GovernorPressure, type GroupHealth, type GroupSamplingGeometry, type GroupStateChange, HINT_AVAILABILITIES, type HintAvailability, type InteractionState, MATERIAL_VARIANTS$1 as MATERIAL_VARIANTS, type MaterialProfile$1 as MaterialProfile, type MaterialRequest, type MaterialVariant$1 as MaterialVariant, type MotionChannel, type MotionDriverKind, NOMINAL_ACCESSIBILITY_POLICY, OVERRIDABLE_ACCESSIBILITY_FLAGS, type OverridableAccessibilityFlag, type PlaneOverlap, type PlatformProbe, type ProxyOverlap, RENDERER_TIERS, type RecoveryContract, type RecoveryTrigger, type Rect$1 as Rect, type RefractionQuality, type RendererTier, type ResolvedAccessibilityPolicy, type ResolvedBackdropHint, type ResolvedForegroundAdaptation, type ResolvedGroup, type ResolvedMaterial, type ResolvedMaterialPolicy, type ResolvedMotionPolicy, type ResolvedNode, SAMPLED_ASYNC_DEFAULTS, SAMPLED_ASYNC_RATE_LIMITS, type SamplingBackend, type SceneResolution, type ShapeChannels, type ShapeFamily, type SourceProbe, type StateChange, type SystemAccessibilityPreferences, type TextureBackdropSource, type TintColor, type TintMixingCheck, VITREA_CONTRACTS, type VariantMixingCheck, type Vec2, type VideoProviderOptions, WEBGPU_AVAILABILITIES, type WebGPUAvailability$1 as WebGPUAvailability, type WebGPURendererModule, type ZSlot, checkTintMixing, checkVariantMixing, classifyStateChange, clipRect, compareZSlot, createDiagnosticsChannel, createFrameScheduler, createGlassScene, defaultForegroundAdaptation, glassTint, inflateRect, isHealthy, loadWebGPURenderer, loadWebGPURendererModule, rectsOverlap, resolveAccessibilityPolicy, resolveBackdropHint, resolveForegroundAdaptation, resolveGlassGroupState, resolveMaterial, unionRect };