@vitreajs/vitrea 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2450 @@
+/**
+ * X8 — the shape channel set, and the vocabulary every other module speaks.
+ *
+ * `{ center, size, radii, smoothing, thickness }`. Every channel is numeric,
+ * which is what makes v1's morphs parametric rather than crossfaded: capsule
+ * <-> rounded rect, button <-> menu platter, indicator slides.
+ *
+ * Two conventions worth stating once, because mixing them up is the easiest way
+ * to get corner math subtly wrong:
+ *
+ *  - `size` is the FULL width and height. Corner math works in half-extents
+ *    (`halfW`, `halfH`), which is what the pseudo-SDF families are written in.
+ *  - `smoothing` here is the value the author wrote. The budget clamp
+ *    (§corner.ts) is applied at derivation and lands in `ResolvedCorner`, so
+ *    shrinking a shape and growing it back is lossless (X8 rider 1).
+ */
+type Vec2 = readonly [x: number, y: number];
+/** Corner radii, clockwise from top-left. */
+type CornerRadii = readonly [
+    topLeft: number,
+    topRight: number,
+    bottomRight: number,
+    bottomLeft: number
+];
+/** The v1 shape families (§Geometry). Not "Apple's taxonomy" — vitrea's supported set. */
+declare const SHAPE_FAMILIES: readonly ["fixed-rounded-rect", "capsule", "concentric-rounded-rect"];
+type ShapeFamily = (typeof SHAPE_FAMILIES)[number];
+/**
+ * Public sugar over the internal numeric corner profile: `"circular"` is
+ * `smoothing: 0`, `"continuous"` is the calibration-determined Apple-matching
+ * corner (§apple.ts). Authoring a number instead puts the shape on the Figma
+ * smoothing axis, which is the interpolable authoring family.
+ */
+type CornerProfile = "continuous" | "circular";
+/**
+ * X8 — the shape channel set. Every channel is numeric, which is what makes
+ * v1's parametric morphs total: capsule <-> rounded rect, button <-> platter.
+ */
+interface ShapeChannels {
+    readonly center: Vec2;
+    readonly size: Vec2;
+    readonly radii: CornerRadii;
+    /** 0 = circular arc corners, 1 = maximum continuous-curvature smoothing. */
+    readonly smoothing: number;
+    /** Material thickness, in CSS px, driving lensing depth and shadow. */
+    readonly thickness: number;
+}
+
+/**
+ * ShapeSpec -> ResolvedShape: authoring input to the X8 channel vector plus
+ * everything derived from it.
+ *
+ * A resolved shape carries three layers, and keeping them separate is what makes
+ * morphs lossless:
+ *
+ *   - `channels`  — X8 exactly, holding the AUTHORED values. `smoothing` here is
+ *                   what the author wrote, never the clamped value.
+ *   - `corner`    — the derivation: budget, clamped radius, effective smoothing,
+ *                   corner reach, and the five fitted coefficients. For C6 this
+ *                   is the six derived floats the instance buffer widens by
+ *                   (`reach` + `k`), recomputed per frame during a morph.
+ *   - `reference` — which curve the corner is fit against.
+ *
+ * ## Two corner references, and why there are two
+ *
+ * S2 measured that the reference curve, not the field family, is the fidelity
+ * bottleneck. That leaves a genuine tension the spec resolves in both
+ * directions at once, so the kernel carries both:
+ *
+ *   - **`"figma-smoothing"`** — the interpolable authoring axis. `smoothing` is
+ *     a free channel over [0, 1], the budget clamp applies to it, and this is
+ *     the axis the declared error bound is measured on (§Geometry binds a
+ *     continuous numeric corner profile clamped by a budget derived from size
+ *     and radii).
+ *   - **`"apple-continuous"`** — the Apple-direct fit. Apple's curve has no
+ *     smoothing parameter, so `smoothing` is pinned at the seed and Apple's own
+ *     budget policy applies (clamp the RADIUS, not the smoothing). This is what
+ *     `profile: "continuous"` resolves to, per Decision Log #20.
+ *
+ * `profile: "circular"` is smoothing 0, which is the same exact circular corner
+ * under either reference and is therefore the member they share.
+ *
+ * The two references are not points on one axis and the kernel does not pretend
+ * otherwise: `morph.ts` refuses a morph that crosses them rather than inventing
+ * a blend the error bound does not cover. In practice v1's morph pairs share a
+ * profile, and `APPLE_BEST_FIGMA_SMOOTHING` is the documented way onto the
+ * interpolable axis for a caller that needs one.
+ */
+
+type CornerReference = "figma-smoothing" | "apple-continuous";
+
+/**
+ * Group union: bounded smooth-min over member fields.
+ *
+ * §Geometry: group rendering goes through a per-group field pass (instances ->
+ * group SDF/coverage field -> one optical pass), "which makes bounded smooth-min
+ * proximity union within a group nearly free; union aesthetics (neck width, max
+ * bulge, separation threshold) are **capped** and calibration-tuned so nothing
+ * reads as jelly."
+ *
+ * The three tunables the spec names, and what each one actually does:
+ *
+ *  - **`neckWidth`** — the polynomial smooth-min's blend width `k`. Two members
+ *    closer than about `k/2` grow a neck between them.
+ *  - **`maxBulge`** — the cap. A quadratic smooth-min deviates from `min` by at
+ *    most `k/4`, so capping the deviation caps `k` at `4 * maxBulge`; the total
+ *    over an n-member fold is clamped once at the end, which makes the bound
+ *    hold for any member count and any fold order.
+ *  - **`separationThreshold`** — the gate. Without it, two members far apart
+ *    still depress the field on the segment between them, because a smooth min
+ *    of two equal values dips even when both are large. That depression is what
+ *    reads as jelly. The gate switches blending off wherever the nearest member
+ *    is farther than half the threshold, which is exactly where a neck could no
+ *    longer form.
+ *
+ * Both gates are load-bearing and they catch different cases: `|a - b| >= k`
+ * saturates the blend next to one member when the other is far, and the
+ * separation gate kills the midpoint depression between two distant members.
+ * With both, the union is EXACTLY `min` everywhere except near a real seam.
+ */
+
+interface GroupUnionParams {
+    /** Blend width in px. Larger means a wider, softer neck. */
+    readonly neckWidth: number;
+    /** Hard cap on how far the union may deviate from `min`, in px. */
+    readonly maxBulge: number;
+    /** Members whose gap exceeds this never blend, in px. */
+    readonly separationThreshold: number;
+}
+
+/**
+ * The binding driver-per-channel table (§Motion).
+ *
+ * Every animated channel names exactly one driver family. The table is the
+ * contract; the constants that configure each driver live in `tunables.ts` and
+ * are advisory until calibration (C7) replaces them.
+ */
+/** Animated channels. Each has exactly one driver family (§Motion, binding). */
+declare const MOTION_CHANNELS: readonly ["position", "size", "radius", "pressCompression", "lensStrength", "glow", "backdropAdaptation", "foregroundTone", "materialization", "disabled", "qualityTier"];
+type MotionChannel = (typeof MOTION_CHANNELS)[number];
+/**
+ * Driver families. `interruptible-spring` is the velocity-preserving one:
+ * a redirect continues from current position and velocity, never restarts.
+ */
+declare const MOTION_DRIVER_KINDS: readonly ["interruptible-spring", "critically-damped", "attack-decay", "low-pass-hysteresis", "threshold-crossfade", "monotonic-ease", "step", "hysteresis-cooldown"];
+type MotionDriverKind = (typeof MOTION_DRIVER_KINDS)[number];
+declare const MOTION_DRIVER_BY_CHANNEL: Readonly<Record<MotionChannel, MotionDriverKind>>;
+
+/** v1 interaction states (§Motion). Neighbor glow diffusion is post-v1. */
+declare const INTERACTION_STATES: readonly ["idle", "hover", "pressed", "focused", "disabled", "morphing"];
+type InteractionState = (typeof INTERACTION_STATES)[number];
+
+/**
+ * The diagnostics channel — how core reports authoring problems it detects but
+ * must not silently fix.
+ *
+ * Core is passive and DOM-free (X4), so it neither writes to a console nor
+ * decides what a host does with a finding: the host supplies a sink. Findings
+ * are deduplicated by default, because several of them are produced by checks
+ * that run every frame (same-plane overlap, variant mixing) and a firehose is
+ * worse than silence.
+ *
+ * Structural mistakes — an unknown id, a duplicate id, a still-referenced
+ * source — are *not* diagnostics. Those throw `GlassSceneError`, because
+ * continuing past them would leave a half-built scene. Diagnostics carry the
+ * recoverable, per-frame, policy-level findings instead.
+ */
+type DiagnosticSeverity = "warning" | "error";
+/** Everything core can report. Owned here so a host can switch exhaustively. */
+declare const DIAGNOSTIC_CODES: readonly ["same-plane-overlap", "variant-mixing", "merge-distance-below-padding", "group-proxy-overlap", "clear-variant-needs-dimming", "foreground-mode-illegal", "foreground-rate-clamped", "backdrop-hint-out-of-range", "backdrop-hint-redundant-estimator", "reduced-transparency-undetectable", "frame-phase-violation"];
+type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
+interface Diagnostic {
+    readonly code: DiagnosticCode;
+    readonly severity: DiagnosticSeverity;
+    /**
+     * The ids this finding is about — group, node, or source. Together with
+     * `code` this is the dedupe key, so "these two nodes overlap" is one finding
+     * however many frames it survives.
+     */
+    readonly subjects: readonly string[];
+    readonly message: string;
+}
+type DiagnosticSink = (diagnostic: Diagnostic) => void;
+interface DiagnosticsChannel {
+    report(diagnostic: Diagnostic): void;
+    /** Findings retained since construction or the last `clear()`. */
+    readonly reported: readonly Diagnostic[];
+    /** Forget what was seen, so a condition that returns is reported again. */
+    clear(): void;
+}
+interface DiagnosticsChannelOptions {
+    /** Where findings go. Omitted in tests and in hosts that only read `reported`. */
+    readonly sink?: DiagnosticSink;
+    /** Collapse repeats of the same code+subjects. Default true. */
+    readonly dedupe?: boolean;
+}
+declare function createDiagnosticsChannel(options?: DiagnosticsChannelOptions): DiagnosticsChannel;
+
+/**
+ * Accessibility policy (§Accessibility policy, plus the Reduced Motion
+ * paragraph of §Motion).
+ *
+ * The spec puts this in `core` as *policy*: what an accessibility preference
+ * means for the material and for motion. `platform-web` reads the media queries
+ * and hands the answers in as plain booleans (X4 — core never touches a media
+ * query, a `window`, or anything else browser-shaped), and `vitrea-react`'s
+ * `GlassRoot` supplies the per-root prop overrides. The decision itself is one
+ * pure fold, so the same inputs always yield the same policy and a test can
+ * enumerate every input there is.
+ *
+ * §Accessibility states four consequences in prose. They are encoded here as a
+ * **table**, one row per preference, each row a partial override of the nominal
+ * policy — so the table can be diffed against the spec paragraph line by line
+ * instead of being reverse-engineered out of branching code. The resolver folds
+ * the active rows over `NOMINAL_ACCESSIBILITY_POLICY` in a fixed precedence
+ * order; adding a preference means adding a row, not editing a resolver.
+ *
+ * Every consequence is a small closed union rather than a number. The numbers —
+ * blur radii, tint strengths, spring constants, morph durations — are
+ * calibration-delegated unknowns owned by `@vitrea/geometry` and
+ * `@vitrea/motion` (§Calibration harness). Core's job is to say *which regime*
+ * applies; it would be inventing fidelity it has not measured if it said by how
+ * much.
+ */
+
+/**
+ * What the platform detected. `platform-web` fills this from media queries;
+ * core never reads one (X4).
+ */
+interface SystemAccessibilityPreferences {
+    readonly reducedTransparency: boolean;
+    readonly reducedMotion: boolean;
+    readonly increasedContrast: boolean;
+    readonly forcedColors: boolean;
+    /**
+     * Whether `prefers-reduced-transparency` is even queryable here. It is not
+     * Baseline, which is exactly why the explicit override is load-bearing rather
+     * than a courtesy (§Accessibility policy). Where this is `false`,
+     * `reducedTransparency` above is an absence of evidence, not evidence of
+     * absence — and the resolver says so through the diagnostics channel.
+     */
+    readonly reducedTransparencySupported: boolean;
+}
+/** The preferences the policy reasons about, and the table's row keys. */
+declare const ACCESSIBILITY_FLAGS: readonly ["reducedTransparency", "reducedMotion", "increasedContrast", "forcedColors"];
+type AccessibilityFlag = (typeof ACCESSIBILITY_FLAGS)[number];
+/**
+ * The three preferences a `GlassRoot` may overrule (§Accessibility policy names
+ * exactly this prop set). `forcedColors` is absent by design: a forced-colors
+ * mandate comes from an operating-system accessibility setting that exists to
+ * override author styling, so it is not an app's to switch off. The type — not
+ * a runtime guard — is what makes that impossible to express.
+ */
+type OverridableAccessibilityFlag = Exclude<AccessibilityFlag, "forcedColors">;
+declare const OVERRIDABLE_ACCESSIBILITY_FLAGS: readonly ["reducedTransparency", "reducedMotion", "increasedContrast"];
+/** `"system"` defers to the platform; a boolean states the answer outright. */
+type AccessibilityOverride = "system" | boolean;
+/** Per-`GlassRoot` overrides. An absent key means `"system"`. */
+type AccessibilityOverrides = {
+    readonly [K in OverridableAccessibilityFlag]?: AccessibilityOverride;
+};
+/**
+ * How the material is allowed to behave.
+ *
+ * The axes are named for what §Accessibility talks about, and each carries the
+ * nominal regime, the regime its preference asks for, and — where forced-colors
+ * removes the glass entirely — the degenerate regime that leaves.
+ *
+ * `refraction` here is an *accessibility* ceiling, not the capability-derived
+ * `RefractionQuality` of X2 (state.ts). A group can be capped by either; the
+ * renderer honours whichever is lower.
+ */
+interface ResolvedMaterialPolicy {
+    /** Whether a glass body is drawn at all, or a flat system-coloured surface replaces it. */
+    readonly glass: "material" | "none";
+    /** Where colour comes from: the adaptive material, or the platform's forced palette. */
+    readonly colorSource: "material" | "system";
+    /** Backdrop diffusion. Reduced transparency asks for *more* frosted, so `increased`. */
+    readonly frost: "nominal" | "increased" | "none";
+    /** Edge lensing. Reduced transparency asks for *less* refraction — reduced, not removed. */
+    readonly refraction: "nominal" | "reduced" | "none";
+    /**
+     * How much of the backdrop the surface hides. Reduced transparency raises it;
+     * forced-colors' flat system fill hides the backdrop completely, which is
+     * `opaque` rather than `none` — no glass means maximal occlusion, not minimal.
+     */
+    readonly occlusion: "nominal" | "increased" | "opaque";
+    /**
+     * Nominal glass is bounded by a rim highlight; `strong` is a drawn border.
+     * Increased contrast asks for stronger borders, and forced-colors needs a
+     * border because a flattened palette leaves nothing else to define the shape.
+     */
+    readonly border: "nominal" | "strong";
+    /** The material's colour cast picked up from the backdrop. */
+    readonly ambientTint: "nominal" | "reduced" | "none";
+    /**
+     * `adaptive` is the sampled/hinted light-dark foreground of §Foreground
+     * adaptation. `near-monochrome` is a flat high-contrast foreground — which is
+     * also what forced-colors gets, since adapting to a glass body that no longer
+     * exists is not available there; `colorSource` records that the flat colour
+     * comes from the system palette.
+     */
+    readonly foreground: "adaptive" | "near-monochrome";
+}
+/**
+ * How motion is allowed to behave (§Motion, Reduced Motion).
+ *
+ * Reduced Motion "shortens morphs to non-elastic interpolation": the shortening
+ * is a property of the driver kind, so `morph: "non-elastic"` carries both
+ * halves and `@vitrea/motion` owns the calibrated duration for each kind.
+ */
+interface ResolvedMotionPolicy {
+    /** Spring overshoot past the target. */
+    readonly overshoot: "elastic" | "none";
+    /** Press compression and lensing deformation of the surface. */
+    readonly deformation: "nominal" | "none";
+    /** Travelling specular shimmer across the rim. */
+    readonly shimmer: "travel" | "none";
+    /** Morph driver family: an elastic spring, or plain shortened interpolation. */
+    readonly morph: "elastic" | "non-elastic";
+    /**
+     * Crossfading one *surface transition* into another. Nominal glass never
+     * does it — a morph is one continuous material transition, not two surfaces
+     * dissolving. Reduced Motion reserves it for large plane shifts. (The
+     * foreground light/dark crossfade of §Motion's driver table is a different,
+     * unconditional channel and is not governed here.)
+     */
+    readonly crossfade: "never" | "large-plane-shifts";
+    /**
+     * Reduced Motion "keeps direct-manipulation positional continuity": a surface
+     * being dragged still tracks the pointer. That holds under every preference,
+     * so it is an invariant of the model, typed as the literal `true` — there is
+     * no combination of inputs that can turn it off.
+     */
+    readonly positionalContinuity: true;
+}
+/**
+ * What renderers consume. The four resolved booleans travel with the
+ * consequences so a consumer (or `useGlassCapabilities()`) can see *what* was
+ * decided and *why*, in the same spirit as X2's `configuredSource` surviving a
+ * demotion.
+ */
+interface ResolvedAccessibilityPolicy {
+    readonly reducedTransparency: boolean;
+    readonly reducedMotion: boolean;
+    readonly increasedContrast: boolean;
+    readonly forcedColors: boolean;
+    readonly material: ResolvedMaterialPolicy;
+    readonly motion: ResolvedMotionPolicy;
+}
+/**
+ * One table row: the axes a preference changes, and nothing else.
+ *
+ * `positionalContinuity` is excluded from the motion partial so no row can
+ * reach the invariant, whatever a future editor intends.
+ */
+interface AccessibilityConsequences {
+    readonly material?: Partial<ResolvedMaterialPolicy>;
+    readonly motion?: Partial<Omit<ResolvedMotionPolicy, "positionalContinuity">>;
+}
+/** Full-fidelity glass: no preference detected, nothing capped. */
+declare const NOMINAL_ACCESSIBILITY_POLICY: ResolvedAccessibilityPolicy;
+/**
+ * §Accessibility, encoded. Each row is that paragraph's sentence for one
+ * preference and carries only the axes the sentence names:
+ *
+ * - "Reduced transparency → more frosted, less refraction, higher occlusion."
+ * - "Increased contrast → stronger borders, near-monochrome foregrounds,
+ *   reduced ambient tint."
+ * - "`forced-colors` → system colors, borders, no glass."
+ * - "Reduced Motion removes elastic overshoot, deformation, and shimmer travel;
+ *   keeps direct-manipulation positional continuity; shortens morphs to
+ *   non-elastic interpolation; reserves crossfade for large plane shifts."
+ *   (§Motion)
+ *
+ * Reduced Motion is the only motion row, and the other three are the only
+ * material rows — the spec draws no line between a colour preference and a
+ * motion one, so neither does the table.
+ */
+declare const ACCESSIBILITY_BEHAVIOR_TABLE: {
+    readonly [K in AccessibilityFlag]: AccessibilityConsequences;
+};
+/**
+ * Fold order, weakest first.
+ *
+ * `reducedMotion` touches only motion axes, and `reducedTransparency` and
+ * `increasedContrast` touch disjoint material axes — those three commute, so
+ * two preferences at once compose instead of one silently erasing the other.
+ * `forcedColors` is the one row that spans every material axis, and it is last
+ * because a platform-level colour mandate outranks every softening an app or a
+ * softer preference asked for.
+ */
+declare const ACCESSIBILITY_PRECEDENCE: readonly ["reducedMotion", "reducedTransparency", "increasedContrast", "forcedColors"];
+/**
+ * Resolve one `GlassRoot`'s accessibility policy.
+ *
+ * Purely functional: no state, no I/O, no clock. `diagnostics` is a side
+ * channel — passing one never changes the policy that comes back.
+ */
+declare function resolveAccessibilityPolicy(system: SystemAccessibilityPreferences, overrides?: AccessibilityOverrides, diagnostics?: DiagnosticsChannel): ResolvedAccessibilityPolicy;
+
+/**
+ * X2 — the resolved-state model (§Backdrop & analysis contracts).
+ *
+ * Configuration and resolution are separate: an app *configures* a source, the
+ * runtime *resolves* one of an enumerated set of states. Only enumerated states
+ * are legal, every demotion names its reason, and `configuredSource` survives
+ * demotion so an app can always see what it asked for versus what it got.
+ *
+ * C1 ships the shape; C4 ships the resolver.
+ */
+type ConfiguredSource = "texture" | "dom";
+type ActiveRenderer = "webgpu" | "css";
+type SamplingBackend = "gpu-texture" | "css-backdrop" | "none";
+type RefractionQuality$1 = "true" | "approximate" | "none";
+type AnalysisQuality = "exact" | "hint" | "none";
+type GroupHealth = "ok" | "demoted";
+declare const DEMOTION_REASONS: readonly ["no-webgpu", "no-backdrop-filter", "tainted-source", "incompatible-texture", "no-texture-supplied", "device-lost", "probe-failed", "governor"];
+type DemotionReason = (typeof DEMOTION_REASONS)[number];
+interface GlassGroupState {
+    /** What the app declared — never mutated by the runtime. */
+    readonly configuredSource: ConfiguredSource;
+    /** What is actually drawing. */
+    readonly activeRenderer: ActiveRenderer;
+    readonly samplingBackend: SamplingBackend;
+    readonly refraction: RefractionQuality$1;
+    readonly analysis: AnalysisQuality;
+    readonly health: GroupHealth;
+    readonly demotionReason?: DemotionReason;
+}
+declare function isHealthy(state: GlassGroupState): boolean;
+
+/**
+ * X2 — the capability state machine (§Backdrop & analysis contracts, the
+ * honesty core).
+ *
+ * Capability is not a free tuple. The app *configures* a source; the runtime
+ * *resolves* one of an enumerated set of states from probe results that arrive
+ * as plain data. Nothing here touches a GPU, a browser or a clock: platform-web
+ * probes, C6 renders, this file only decides.
+ *
+ * ## Resolution rules
+ *
+ * 0. **WebGPU not requested is not a fault, and neither is WebGPU not ready
+ *    yet.** A root configured for the CSS tier never had WebGPU in play;
+ *    `platform.webgpu: "not-requested"` forces `activeRenderer: "css"` the same
+ *    way a renderer fault would, but names no fault, so a group with nothing
+ *    else wrong resolves `health: "ok"` — labeling intent as a fault would
+ *    invert the honesty doctrine (X2's K1 amendment, Decision Log #21c).
+ *    `"pending"` resolves identically, for the same reason read forwards: a root
+ *    that asked for WebGPU and is still bringing it up has not failed at
+ *    anything, and answering `no-webgpu` — whose recovery is honestly `"none"` —
+ *    would be a terminal answer to a request still in flight.
+ * 1. **Renderer faults** — no WebGPU, a lost device, or a governor tier switch —
+ *    drop `activeRenderer` to `"css"`. Nothing else can.
+ * 2. **Sampling faults** demote the backdrop path without touching the
+ *    renderer. A tainted or incompatible texture leaves WebGPU drawing tint,
+ *    rim and glow with nothing to sample (`samplingBackend: "none"`); it does
+ *    *not* silently re-point the group at the DOM behind it, because the app
+ *    asked for a texture and swapping backdrops underneath it would be exactly
+ *    the pretence this model exists to prevent.
+ * 3. **Refraction follows what is actually sampled.** `"true"` needs GPU-texture
+ *    sampling; `"approximate"` is the shader's rim-lensing over a CSS proxy;
+ *    the CSS tier gets `"none"` because `backdrop-filter` blurs, it does not
+ *    bend.
+ * 4. **`exact` analysis needs a GPU texture.** Otherwise a declared hint or an
+ *    estimator provider yields `"hint"` (X6), and nothing yields `"none"`.
+ * 5. **One reason is reported, by precedence** — see `REASON_PRECEDENCE`.
+ * 6. **A texture source with no pixels behind it is a sampling fault.** The app
+ *    declared a texture and the runtime has nothing to read, so the group draws
+ *    tint, rim and glow over an unsampled backdrop and says so
+ *    (`no-texture-supplied`). Reporting `gpu-texture` / `true` / `exact` for a
+ *    source nobody supplied is the loudest possible version of the pretence this
+ *    file exists to prevent.
+ */
+
+/**
+ * Whether WebGPU is in play for this root at all, distinct from whether it
+ * *works* — a root configured for the CSS tier never asks, and that is a
+ * choice, not a fault (X2's K1 amendment, Decision Log #21c).
+ *
+ * The question is three-state on the way up, not two: between "asked for" and
+ * "answered" there is a startup window in which the answer is not known yet, and
+ * a host that has to publish *something* during it has only honest options if
+ * the union has a name for it. `"pending"` is that name.
+ */
+declare const WEBGPU_AVAILABILITIES: readonly ["not-requested", "pending", "unavailable", "available"];
+type WebGPUAvailability$1 = (typeof WEBGPU_AVAILABILITIES)[number];
+/** Platform-wide probe results. platform-web produces these; core only reads them. */
+interface PlatformProbe {
+    /**
+     * `"available"` — a WebGPU adapter and device were obtained *and* whatever
+     * draws with them is ready to paint. `"unavailable"` — WebGPU was requested
+     * but no adapter, device or renderer could be had. `"pending"` — requested,
+     * and the answer has not arrived yet; resolves exactly as `"not-requested"`
+     * does, so a group is on the CSS tier without being demoted while the GPU tier
+     * starts. `"not-requested"` — this root never asked for WebGPU at all (its
+     * renderer is CSS by choice), which resolves honestly rather than as a fault.
+     *
+     * The two CSS-without-a-fault values resolve alike and stay tellable apart on
+     * purpose: a host reads them back to distinguish "CSS by choice" from "CSS
+     * while WebGPU starts", which is the difference between a final answer and a
+     * provisional one.
+     */
+    readonly webgpu: WebGPUAvailability$1;
+    /** `backdrop-filter` is supported and actually filters. */
+    readonly backdropFilter: boolean;
+    /**
+     * S1's startup conformance probe: does a portaled masked proxy sample the
+     * same pixels as an in-place `backdrop-filter`? Filter Effects 2's Backdrop
+     * Root lacks WG consensus, so this is probed, never assumed.
+     */
+    readonly backdropProxyConformance: "pass" | "fail";
+    readonly deviceHealth: "ok" | "lost";
+}
+/** Per-source facts. Meaningful for `texture` sources only. */
+interface SourceProbe {
+    /** CORS taint. A tainted source cannot be read into a GPU texture at all. */
+    readonly taint: "clean" | "tainted";
+    /** Whether an app-supplied view satisfies the declared usage/format/dimension requirements. */
+    readonly textureCompatibility: "compatible" | "incompatible";
+    /**
+     * Whether pixels have actually been handed over for this source.
+     *
+     * `TextureBackdropSource` declares that a source *is* a texture and carries no
+     * pixels — core may not know what an `HTMLCanvasElement` is (X4) — so the
+     * declaration and the supply are two separate events, and a group can sit
+     * between them for as long as the app takes. Only the platform layer knows
+     * which side of that gap a source is on, so it folds the fact in here, exactly
+     * as it folds a per-group proxy verdict into `backdropProxyConformance`
+     * (Decision Log #21a).
+     *
+     * Optional, defaulting to `"supplied"`: core cannot see the pixels either way,
+     * and a resolver that assumed absence would demote every source registered
+     * through a host that does not report this at all.
+     */
+    readonly supply?: "supplied" | "absent";
+}
+/**
+ * Quality-governor pressure (§Performance envelope). The governor degrades
+ * *within* a tier before it switches tiers, so only `"demote-tier"` is a
+ * demotion; `"degrade-in-tier"` changes render quality knobs C6 owns and leaves
+ * the resolved state untouched.
+ */
+declare const GOVERNOR_PRESSURES: readonly ["none", "degrade-in-tier", "demote-tier"];
+type GovernorPressure = (typeof GOVERNOR_PRESSURES)[number];
+/**
+ * X6 — which of the one hint mechanism is in play. Both an author-declared
+ * `backdrop` prop and an estimator provider produce `analysis: "hint"`; the
+ * distinction is kept for developer-facing reporting, never smuggled into the
+ * state, whose shape is frozen.
+ */
+declare const HINT_AVAILABILITIES: readonly ["none", "author-hint", "estimator"];
+type HintAvailability = (typeof HINT_AVAILABILITIES)[number];
+/** Everything the resolver needs. A texture group must declare its source probe. */
+type CapabilityInputs = {
+    readonly configuredSource: "texture";
+    readonly platform: PlatformProbe;
+    readonly source: SourceProbe;
+    readonly governor: GovernorPressure;
+    readonly hint: HintAvailability;
+} | {
+    readonly configuredSource: "dom";
+    readonly platform: PlatformProbe;
+    readonly source?: undefined;
+    readonly governor: GovernorPressure;
+    readonly hint: HintAvailability;
+};
+/** What clears a demotion. `"none"` is the honest answer for a platform fact. */
+type RecoveryTrigger = "device-restored" | "source-replaced" | "probe-repassed" | "pressure-released" | "none";
+interface RecoveryContract {
+    readonly trigger: RecoveryTrigger;
+    readonly explanation: string;
+}
+/**
+ * Every demotion names its recovery transition (§honesty core). This table is
+ * the contract; the resolver is stateless, so recovery *is* re-resolution once
+ * the named input changes.
+ */
+declare const DEMOTION_RECOVERY: Readonly<Record<DemotionReason, RecoveryContract>>;
+/**
+ * Resolve one group's state. Pure, total, and deterministic: the same inputs
+ * always produce the same state, and `configuredSource` is copied through
+ * untouched by every path.
+ */
+declare function resolveGlassGroupState(inputs: CapabilityInputs): GlassGroupState;
+/** How one group's state moved between two resolutions. */
+type StateChange = {
+    readonly kind: "unchanged";
+}
+/** The group's first resolution — there was no previous state to move from. */
+ | {
+    readonly kind: "initial";
+    readonly reason?: DemotionReason;
+} | {
+    readonly kind: "demoted";
+    readonly reason: DemotionReason;
+} | {
+    readonly kind: "recovered";
+    readonly from: DemotionReason;
+} | {
+    readonly kind: "changed";
+    readonly reason?: DemotionReason;
+};
+/**
+ * Name a transition, so a host can log "recovered from device-lost" rather than
+ * diff two records. Used by the scene when it re-resolves during a frame. A
+ * missing `previous` is a group's first resolution, not a change.
+ */
+declare function classifyStateChange(previous: GlassGroupState | undefined, next: GlassGroupState): StateChange;
+
+/**
+ * X6 — the hint contract (§Backdrop & analysis contracts).
+ *
+ * A `dom` group has no pixels vitrea may read, so its adaptation data comes
+ * from exactly one mechanism: an author-declared `backdrop` on the GlassGroup,
+ * or an estimator provider that supplies the same shape. Three parallel hint
+ * mechanisms were consolidated into this one on purpose (Decision Log #13).
+ *
+ * The word "estimator" is load-bearing. A built-in DOM estimator may read known
+ * background colours and images where CORS permits, and it is documented as an
+ * estimator everywhere it appears — never as pixel analysis, which vitrea does
+ * not promise for arbitrary DOM and never will.
+ */
+
+/** Coarse light/dark/mixed classification. The one field a hint must carry. */
+type BackdropTone = "light" | "dark" | "mixed";
+interface BackdropHint {
+    readonly tone: BackdropTone;
+    /** Relative luminance of the backdrop under the group, 0..1. */
+    readonly luminance?: number;
+    /** Busyness of the backdrop, 0..1 — how hard the foreground has to fight. */
+    readonly complexity?: number;
+}
+/**
+ * The provider form of the same contract. `kind` is a literal so the shape is
+ * self-describing wherever it surfaces in developer tooling.
+ */
+interface BackdropEstimatorProvider {
+    readonly kind: "estimator";
+    /** Names the estimator in diagnostics and developer output. */
+    readonly id: string;
+    /** Called per group. Returning `undefined` means "no opinion here". */
+    estimate(groupId: string): BackdropHint | undefined;
+}
+interface BackdropHintRequest {
+    readonly groupId: string;
+    readonly backdrop?: BackdropHint;
+    readonly estimator?: BackdropEstimatorProvider;
+    readonly diagnostics?: DiagnosticsChannel;
+}
+interface ResolvedBackdropHint {
+    readonly availability: HintAvailability;
+    /** Absent exactly when `availability` is `"none"`. */
+    readonly hint?: BackdropHint;
+}
+/**
+ * Resolve a group's hint. An explicit `backdrop` beats an estimator: the author
+ * stated a fact, the estimator guessed one. Configuring both is reported once,
+ * because it usually means the author forgot they had a provider installed.
+ */
+declare function resolveBackdropHint(request: BackdropHintRequest): ResolvedBackdropHint;
+
+/**
+ * §Foreground adaptation — the GPU → DOM data path's policy half.
+ *
+ * `ForegroundAdaptation = fixed | author-hint | sampled-async { rateHz,
+ * hysteresis }`. The interesting part is legality: `sampled-async` needs GPU
+ * classification results, so it is available only where `analysis: "exact"` —
+ * "exactly", per the honesty doctrine. An illegal combination is neither
+ * honoured nor silently dropped: it resolves to the nearest legal mode and the
+ * downgrade is both returned and reported.
+ *
+ * Nothing here reads a clock or schedules anything. `rateHz` is a declared
+ * cadence platform-web drives; core only validates it.
+ */
+
+/** The three modes, ordered most adaptive first — the order the fallback walks. */
+declare const FOREGROUND_MODES: readonly ["sampled-async", "author-hint", "fixed"];
+type ForegroundMode = (typeof FOREGROUND_MODES)[number];
+type ForegroundAdaptation = {
+    readonly mode: "fixed";
+} | {
+    readonly mode: "author-hint";
+} | {
+    readonly mode: "sampled-async";
+    /** Readback cadence. Low-frequency by contract — never per-frame. */
+    readonly rateHz: number;
+    /** Threshold band, 0..1, that keeps scrolling from pumping the foreground. */
+    readonly hysteresis: number;
+};
+/**
+ * Advisory bounds. `maxHz` exists to keep "low-frequency async readback" true
+ * rather than aspirational: a quarter of a 60Hz frame budget is already far
+ * more often than a foreground tone needs to change. Calibration (C7) may
+ * replace these numbers; the invariant that readback is not per-frame is not
+ * negotiable.
+ */
+declare const SAMPLED_ASYNC_RATE_LIMITS: {
+    readonly minHz: 1;
+    readonly maxHz: 15;
+    readonly minHysteresis: 0.02;
+    readonly maxHysteresis: 0.5;
+};
+/** Advisory defaults, replaced by calibration profiles (§Calibration). */
+declare const SAMPLED_ASYNC_DEFAULTS: {
+    readonly rateHz: 4;
+    readonly hysteresis: 0.06;
+};
+interface ForegroundResolutionOptions {
+    /**
+     * What a finding is about — a group id, or a node id where a surface
+     * overrides its group's mode. Also the dedupe subject, so a standing
+     * downgrade is reported once rather than once per frame.
+     */
+    readonly subject?: string;
+    readonly diagnostics?: DiagnosticsChannel;
+}
+interface ResolvedForegroundAdaptation {
+    readonly adaptation: ForegroundAdaptation;
+    /** Present only when the requested mode was not legal for this state. */
+    readonly downgraded?: {
+        readonly from: ForegroundMode;
+        readonly to: ForegroundMode;
+    };
+}
+/**
+ * Resolve a requested mode against a resolved group state. Total: every
+ * request produces a legal adaptation, because `fixed` is legal everywhere.
+ */
+declare function resolveForegroundAdaptation(requested: ForegroundAdaptation, state: GlassGroupState, options?: ForegroundResolutionOptions): ResolvedForegroundAdaptation;
+/**
+ * The mode a group gets when the app states none: adapt wherever that is
+ * honest, hint where the author supplied one, fixed tones for arbitrary DOM.
+ */
+declare function defaultForegroundAdaptation(state: GlassGroupState): ForegroundAdaptation;
+
+/**
+ * The frame vocabulary, shared by the scene and the scheduler.
+ *
+ * It lives in its own module because both need it: the scheduler drives the
+ * phases, and the scene uses the current phase to gate the operations that only
+ * make sense in one of them.
+ *
+ * The five phases are the pipeline the spec describes: collect what changed,
+ * read the DOM once in a batch, update the scene from those reads, write the GPU
+ * resources, then render. Their point is ordering discipline — every layout read
+ * in one place so the steady state performs none, and every scene mutation
+ * finished before the renderer starts walking the graph.
+ */
+declare const FRAME_PHASES: readonly ["collect", "read", "update", "write", "render"];
+type FramePhase = (typeof FRAME_PHASES)[number];
+/**
+ * What a host knows about the frame it is driving. `timeMs` arrives as a number
+ * because core reads no clock (X4) — it is the host's monotonic timestamp.
+ */
+interface FrameInfo {
+    /** Monotonically increasing. Also the scope for at-most-once-per-frame work. */
+    readonly id: number;
+    readonly timeMs: number;
+}
+
+/**
+ * §Material variants.
+ *
+ * `regular` is the adaptive default. `clear` is persistently more transparent
+ * with constrained adaptation, and it *requires* a dimming policy — without one
+ * there is nothing keeping foreground content legible over a busy backdrop.
+ *
+ * Two deliberate choices here:
+ *
+ * - A `clear` surface with no dimming policy resolves to `regular` and raises a
+ *   dev-mode **error**. Applying an invented policy silently would be the one
+ *   thing this codebase refuses: pretending to a capability the author never
+ *   configured. Falling back to `regular` cannot produce an illegible surface,
+ *   and `DEFAULT_CLEAR_DIMMING` makes satisfying the requirement a one-liner.
+ * - Mixing variants inside one GlassGroup **warns** and changes nothing. Apple's
+ *   guidance is not to mix; coercing one of the two would silently discard an
+ *   author's intent, which is worse than a surface that looks wrong on purpose.
+ */
+
+declare const MATERIAL_VARIANTS$1: readonly ["regular", "clear"];
+type MaterialVariant$1 = (typeof MATERIAL_VARIANTS$1)[number];
+/** The scrim laid beneath clear glass so foreground content stays legible. */
+interface DimmingPolicy {
+    /** Scrim opacity, 0..1. */
+    readonly scrim: number;
+    /** Which way the scrim pushes the backdrop — dark content over light, or the reverse. */
+    readonly direction: "darken" | "lighten";
+}
+/**
+ * Advisory default, named as a delegated unknown in §Calibration: the harness
+ * fits the real value. Its purpose here is to make the requirement cheap to
+ * satisfy, not to be correct.
+ */
+declare const DEFAULT_CLEAR_DIMMING: DimmingPolicy;
+/** A group's material defaults. A node inherits `variant` when it declares none. */
+interface MaterialProfile$1 {
+    readonly variant: MaterialVariant$1;
+    /** Required for any clear surface in the group. */
+    readonly dimming?: DimmingPolicy;
+}
+interface ResolvedMaterial {
+    readonly variant: MaterialVariant$1;
+    /** Regular adapts to the backdrop; clear's response is deliberately constrained. */
+    readonly adaptation: "adaptive" | "constrained";
+    /** Present exactly when `variant` is `"clear"`. */
+    readonly dimming?: DimmingPolicy;
+}
+interface MaterialRequest {
+    readonly variant: MaterialVariant$1;
+    readonly dimming?: DimmingPolicy;
+    /** Named in diagnostics; also the dedupe subject. */
+    readonly nodeId?: string;
+    readonly diagnostics?: DiagnosticsChannel;
+}
+declare function resolveMaterial(request: MaterialRequest): ResolvedMaterial;
+interface VariantMixingCheck {
+    readonly groupId: string;
+    readonly members: readonly {
+        readonly nodeId: string;
+        readonly variant: MaterialVariant$1;
+    }[];
+    readonly diagnostics?: DiagnosticsChannel;
+}
+/**
+ * Report a group whose members do not agree on a variant. Returns whether they
+ * were mixed; changes nothing either way.
+ */
+declare function checkVariantMixing(check: VariantMixingCheck): boolean;
+
+/**
+ * The z-slot model (§Core model: `z-slot (plane + order)`) and the geometry
+ * primitives core needs to reason about it.
+ *
+ * Plane identity lives here rather than in platform-web because it is part of
+ * the scene model: a GlassNode's slot is (plane, order), and the same-plane
+ * overlap check is a core invariant. platform-web owns the *DOM realisation* of
+ * a plane — the canvas pair and the paint order inside it (X1) — and re-exports
+ * these names so there is one vocabulary.
+ *
+ * `Rect` is plain data. The numbers arrive from platform-web's batched layout
+ * read; core never measures anything (X4).
+ */
+/** v1 ships exactly two managed stacking planes (X1). More overlays are out of scope. */
+declare const GLASS_PLANES: readonly ["base", "overlay"];
+type GlassPlane = (typeof GLASS_PLANES)[number];
+/**
+ * Where a node sits. `plane` picks the canvas pair; `order` sequences nodes
+ * within it. Nodes in one plane must not overlap (X1) — order breaks ties for
+ * paint sequence, it does not license stacking.
+ */
+interface ZSlot {
+    readonly plane: GlassPlane;
+    readonly order: number;
+}
+/** Viewport-space rectangle in CSS px, measured by platform-web and handed in as data. */
+interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** 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;
+/** Grow a rect outwards on every side — how a group's proxy gets its padding. */
+declare function inflateRect(rect: Rect, by: number): Rect;
+/**
+ * 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;
+
+/**
+ * The scene model (§Core model): the three registries and everything that
+ * follows from their references.
+ *
+ * ```
+ * BackdropSource            GlassGroup                GlassNode
+ * ├─ kind: texture | dom    ├─ backdropSourceId       ├─ shape family params
+ * ├─ raw texture/source     ├─ morph namespace        ├─ viewport bounds, clip
+ * ├─ blur pyramid           ├─ material profile       ├─ z-slot (plane + order)
+ * ├─ analysis maps          ├─ adaptation policy      ├─ variant
+ * ├─ dirty epoch            ├─ mergeDistance          ├─ interaction state
+ * └─ resolution policy      └─ samplingPadding        └─ foreground policy
+ * ```
+ *
+ * Core owns the *bookkeeping* half of each row. The raw texture, the blur
+ * pyramid and the analysis maps are GPU objects C6 owns; what lives here is the
+ * fact that they belong to the **source** and not to the group, plus the
+ * dirty-epoch accounting that makes the invariant enforceable: a dirty source
+ * yields **at most one rebuild per frame**, serving every group that samples it.
+ * That hand-out is provisional for as long as the frame is — a frame that throws
+ * gives its claims back (`rollbackDirtyBackdropSources`), because a spent claim
+ * with nothing built behind it would leave the source clean forever.
+ *
+ * Two failure modes are kept deliberately distinct:
+ *
+ * - **Structural** mistakes throw `GlassSceneError` — a duplicate id, a dangling
+ *   reference, removing something still in use. Continuing past one leaves a
+ *   scene whose references lie, so there is nothing to report and recover from.
+ * - **Policy** findings go to the diagnostics channel — overlap, variant mixing,
+ *   an illegal foreground mode. Those are recoverable, often per-frame, and the
+ *   host decides what to do about them.
+ *
+ * Nothing here measures, schedules, or draws. Viewport rects arrive as data from
+ * platform-web's batched read; frames are driven from outside (see
+ * `scheduler.ts`).
+ */
+
+type GlassSceneErrorCode = "duplicate-id" | "unknown-id" | "in-use" | "wrong-source-kind";
+/** A structural violation. Distinct from a diagnostic: the scene refuses the change. */
+declare class GlassSceneError extends Error {
+    readonly code: GlassSceneErrorCode;
+    constructor(code: GlassSceneErrorCode, message: string);
+}
+/**
+ * How large the derived pyramids for a texture source are. Effect-texture
+ * resolution is decoupled from DOM DPR on purpose (§Performance envelope).
+ */
+interface BackdropResolutionPolicy {
+    /** Effect-texture scale relative to CSS px. */
+    readonly scale: number;
+    /** Cap on a pyramid level's longest side, in texture px. */
+    readonly maxDimension: number;
+}
+/** Advisory default; the governor and calibration both move it. */
+declare const DEFAULT_BACKDROP_RESOLUTION: BackdropResolutionPolicy;
+/** How far a group samples beyond its member union, and how near members merge. */
+interface GroupSamplingGeometry {
+    /** Padding on the proxy's border box, in CSS px. */
+    readonly samplingPadding: number;
+    /** Proximity-union threshold within the group, in CSS px. */
+    readonly mergeDistance: number;
+}
+/**
+ * Advisory defaults, chosen so X1's constraints hold out of the box rather than
+ * being numbers worth trusting.
+ *
+ * S1 measured that `samplingPadding` must be at least 3σ of the group's blur:
+ * Filter Effects 2 clips a filter's input to the filtered element's own border
+ * box, so an unpadded box starves its own blur at the edges. 24 is 3σ at
+ * σ = 8 CSS px, a plausible regular-material blur — calibration (C7) replaces
+ * it, and the *actual* 3σ check cannot live here because core carries no blur
+ * radius (see the note on `GlassGroupDescriptor.samplingPadding`).
+ *
+ * `mergeDistance` defaults to the same number because X1 requires
+ * `mergeDistance ≥ samplingPadding`: any two members close enough for their
+ * padded proxies to overlap must already have merged into one, or the filter
+ * applies twice — measured at 1.5625× for `brightness(1.25)`, paint-order
+ * dependent, drifting up to 17/255 even in legal 8px-gap geometry.
+ */
+declare const DEFAULT_GROUP_SAMPLING: GroupSamplingGeometry;
+interface TextureBackdropSource {
+    readonly id: string;
+    readonly kind: "texture";
+    /**
+     * Probed *before* registration. Reporting `analysis: "exact"` for a frame and
+     * then withdrawing it would be exactly the pretence X2 exists to prevent.
+     */
+    readonly probe: SourceProbe;
+    readonly resolution?: BackdropResolutionPolicy;
+}
+interface DomBackdropSource {
+    readonly id: string;
+    readonly kind: "dom";
+}
+type BackdropSourceDescriptor = TextureBackdropSource | DomBackdropSource;
+interface BackdropSourceRecord {
+    readonly descriptor: BackdropSourceDescriptor;
+    /** Bumped whenever the source's content changes. */
+    readonly dirtyEpoch: number;
+    /** The epoch a rebuild was last handed out for. Dirty means `dirtyEpoch > builtEpoch`. */
+    readonly builtEpoch: number;
+}
+interface GlassGroupDescriptor {
+    readonly id: string;
+    readonly backdropSourceId: string;
+    /** Scope for matched-geometry ids, so two morph pairs cannot collide. */
+    readonly morphNamespace?: string;
+    readonly material?: MaterialProfile$1;
+    /** Requested adaptation. Resolved against the group's state, never assumed legal. */
+    readonly foreground?: ForegroundAdaptation;
+    /**
+     * Proximity-union threshold within the group, in CSS px (§Geometry). X1
+     * requires it to be at least `samplingPadding`; core checks that, since both
+     * numbers live here.
+     */
+    readonly mergeDistance?: number;
+    /**
+     * Padding on the group proxy's border box, in CSS px. X1 also requires it to
+     * be at least 3σ of the group's blur — core cannot check *that* one, because
+     * it carries no blur radius; platform-web owns it, where the material's blur
+     * is known.
+     */
+    readonly samplingPadding?: number;
+    /** X6: the author's declared hint. */
+    readonly backdrop?: BackdropHint;
+    /** X6: the provider form of the same contract. */
+    readonly estimator?: BackdropEstimatorProvider;
+}
+interface GlassGroupRecord {
+    readonly descriptor: GlassGroupDescriptor;
+    /** Set once the group has been resolved at least once. */
+    readonly state?: GlassGroupState;
+    /** Per-group governor override; falls back to the scene-wide pressure. */
+    readonly governor?: GovernorPressure;
+}
+interface GlassNodeDescriptor {
+    readonly id: string;
+    readonly groupId: string;
+    readonly shapeFamily: ShapeFamily;
+    readonly shape: ShapeChannels;
+    readonly zSlot: ZSlot;
+    /** Inherits the group's material profile when absent. */
+    readonly variant?: MaterialVariant$1;
+    readonly interaction?: InteractionState;
+    /** Overrides the group's adaptation for this surface. */
+    readonly foreground?: ForegroundAdaptation;
+}
+interface GlassNodeRecord {
+    readonly descriptor: GlassNodeDescriptor;
+    /** Measured by platform-web in the read phase; absent until then. */
+    readonly bounds?: Rect;
+    /** Ancestor clip chain, viewport space. */
+    readonly clip?: readonly Rect[];
+}
+/** One pyramid rebuild. `groupIds` is why there is one request and not one per group. */
+interface BackdropRebuildRequest {
+    readonly sourceId: string;
+    /** The dirty epoch this rebuild satisfies. */
+    readonly epoch: number;
+    readonly resolution: BackdropResolutionPolicy;
+    /** Every group the rebuild serves. */
+    readonly groupIds: readonly string[];
+}
+interface ResolvedGroup {
+    readonly groupId: string;
+    readonly state: GlassGroupState;
+    readonly hint: ResolvedBackdropHint;
+    readonly foreground: ResolvedForegroundAdaptation;
+    /** Defaults filled in, so a consumer reads one pair of numbers and not two optionals. */
+    readonly sampling: GroupSamplingGeometry;
+}
+interface ResolvedNode {
+    readonly nodeId: string;
+    readonly groupId: string;
+    readonly material: ResolvedMaterial;
+    readonly foreground: ResolvedForegroundAdaptation;
+}
+interface GroupStateChange {
+    readonly groupId: string;
+    /** Absent on a group's first resolution. */
+    readonly previous?: GlassGroupState;
+    readonly next: GlassGroupState;
+    readonly change: StateChange;
+}
+interface SceneResolution {
+    readonly groups: readonly ResolvedGroup[];
+    readonly nodes: readonly ResolvedNode[];
+    /** Only the groups whose state moved, plus every group's first resolution. */
+    readonly changes: readonly GroupStateChange[];
+    /**
+     * One policy for the whole root, carried here so a renderer has everything a
+     * frame decided in one object rather than two.
+     */
+    readonly accessibility: ResolvedAccessibilityPolicy;
+}
+/** One overlapping pair of surfaces inside one plane (X1). */
+interface PlaneOverlap {
+    readonly plane: GlassPlane;
+    readonly nodeIds: readonly [string, string];
+}
+/** Two groups whose padded backdrop proxies would overlap in one plane (X1). */
+interface ProxyOverlap {
+    readonly plane: GlassPlane;
+    readonly groupIds: readonly [string, string];
+}
+interface GlassSceneOptions {
+    readonly platform: PlatformProbe;
+    readonly accessibility?: SystemAccessibilityPreferences;
+    readonly accessibilityOverrides?: AccessibilityOverrides;
+    readonly diagnostics?: DiagnosticsChannel;
+    /**
+     * Dev-only checks — same-plane overlap, variant mixing — run only here.
+     * Default true: they are cheap at v1's surface counts, and what they catch is
+     * invisible otherwise.
+     */
+    readonly devMode?: boolean;
+}
+interface GlassScene {
+    readonly diagnostics: DiagnosticsChannel;
+    /**
+     * The phase of the frame in flight, or `undefined` outside one. The scheduler
+     * sets it; the scene uses it to gate phase-scoped operations. Outside a frame
+     * the scene has no opinion — a host may register and measure whenever it likes.
+     */
+    readonly framePhase: FramePhase | undefined;
+    setFramePhase(phase: FramePhase | undefined): void;
+    registerBackdropSource(descriptor: BackdropSourceDescriptor): void;
+    /** Only the resolution policy is patchable: `kind` is identity, the probe has its own setter. */
+    updateBackdropSource(id: string, patch: {
+        readonly resolution: BackdropResolutionPolicy;
+    }): void;
+    removeBackdropSource(id: string): void;
+    backdropSource(id: string): BackdropSourceRecord | undefined;
+    registerGlassGroup(descriptor: GlassGroupDescriptor): void;
+    /** A key present with `undefined` clears that override; an absent key keeps it. */
+    updateGlassGroup(id: string, patch: DescriptorPatch<Omit<GlassGroupDescriptor, "id">>): void;
+    removeGlassGroup(id: string): void;
+    glassGroup(id: string): GlassGroupRecord | undefined;
+    groupsOfSource(sourceId: string): readonly GlassGroupRecord[];
+    registerGlassNode(descriptor: GlassNodeDescriptor): void;
+    /** A key present with `undefined` clears that override; an absent key keeps it. */
+    updateGlassNode(id: string, patch: DescriptorPatch<Omit<GlassNodeDescriptor, "id">>): void;
+    removeGlassNode(id: string): void;
+    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;
+    setPlatformProbe(probe: PlatformProbe): void;
+    setSourceProbe(sourceId: string, probe: SourceProbe): void;
+    /** Scene-wide by default; per group when `groupId` is given. */
+    setGovernorPressure(pressure: GovernorPressure, groupId?: string): void;
+    setSystemAccessibility(preferences: SystemAccessibilityPreferences): void;
+    setAccessibilityOverrides(overrides: AccessibilityOverrides): void;
+    accessibilityPolicy(): ResolvedAccessibilityPolicy;
+    markBackdropSourceDirty(id: string): void;
+    /** Peek without consuming. */
+    dirtyBackdropSources(): readonly BackdropSourceRecord[];
+    /**
+     * Hand out the frame's rebuilds. The frame id *is* the scope: a second call
+     * with the same id returns nothing, which is the §Core model invariant.
+     */
+    consumeDirtyBackdropSources(frameId: number): readonly BackdropRebuildRequest[];
+    /**
+     * Give back what `frameId` took, because the frame did not finish.
+     *
+     * Consuming commits `builtEpoch` at hand-out rather than at completion — core
+     * has no view of the wire and cannot wait for one. That is right while the
+     * frame runs to its end, and a lie the moment it does not: a claim spent on a
+     * frame that threw leaves the source sitting clean at an epoch whose pixels
+     * were never imported, and nothing ever marks it dirty again. Restoring the
+     * pre-consume epochs makes the commit provisional for exactly as long as the
+     * frame is.
+     *
+     * Returns the source ids restored. Idempotent, and a no-op for any frame id
+     * other than the one that consumed.
+     */
+    rollbackDirtyBackdropSources(frameId: number): readonly string[];
+    resolve(): SceneResolution;
+    checkSamePlaneOverlap(): readonly PlaneOverlap[];
+    /**
+     * The cross-group half of X1's proxy geometry. `mergeDistance` only unions
+     * members *within* a group, so two neighbouring groups can still put two
+     * padded proxies over the same pixels — which S1 measured double-filtering.
+     */
+    checkGroupProxyOverlap(): readonly ProxyOverlap[];
+}
+/**
+ * A descriptor patch. Unlike `Partial`, a key present with `undefined` is
+ * meaningful: it *clears* the override and restores the inherited default.
+ * Without that, a declarative binding could never take a prop back — React
+ * re-rendering `<GlassGroup backdrop={undefined}>` would have no way to say
+ * "this group no longer declares a hint" short of tearing the entry down.
+ */
+type DescriptorPatch<D> = {
+    readonly [K in keyof D]?: D[K] | undefined;
+};
+declare function createGlassScene(options: GlassSceneOptions): GlassScene;
+
+/**
+ * The frame-phase contract, and a reference implementation of it.
+ *
+ * Core is **passive**. There is no timer, no `requestAnimationFrame`, and no
+ * clock read anywhere here — a host calls `runFrame` and supplies the frame's
+ * time as a number. platform-web owns the rAF loop and drives this; the same
+ * scheduler runs in a test with hand-written frame ids and no browser at all.
+ *
+ * The pipeline is fixed:
+ *
+ * ```
+ * collect  what changed since the last frame is marked dirty
+ * read     every layout measurement, batched, so the steady state performs none
+ * update   the scene resolves: capability state, policies, dev-mode checks
+ * write    GPU resources are brought up to date — where rebuilds are handed out
+ * render   drawing, with the graph frozen
+ * ```
+ *
+ * `update` resolves the scene *before* the first update hook runs, and that
+ * ordering is the contract rather than an implementation detail: every phase from
+ * `update` onward reads a resolution describing the graph as it stood at the top
+ * of that phase. So the graph is structurally frozen from `update` on — the scene
+ * reports a register or a remove there as a `frame-phase-violation`, because a
+ * hook that restructures the graph leaves the frame's resolution describing a
+ * graph that no longer exists. Structural reconciliation belongs in `collect`;
+ * `update` is where reads become resolved state.
+ *
+ * Phase discipline is enforced, not documented. Consuming the dirty set outside
+ * `write`, measuring outside `read`, and restructuring the graph once it has
+ * resolved each report a `frame-phase-violation`. None of them throws: a violated
+ * frame still draws, and a diagnostic that costs a frame is one a host will
+ * silence rather than fix.
+ */
+
+/** What a hook is handed. Valid for the phase it was passed to, and no longer. */
+interface FrameContext {
+    readonly frame: FrameInfo;
+    readonly phase: FramePhase;
+    readonly scene: GlassScene;
+    /** The frame's resolution. Absent before the update phase has produced it. */
+    readonly resolution?: SceneResolution;
+    /**
+     * The backdrop sources needing a pyramid rebuild this frame. Legal in the
+     * `write` phase, and at most once per frame however many participants ask —
+     * the §Core model invariant, enforced rather than asserted.
+     */
+    consumeDirtyBackdropSources(): readonly BackdropRebuildRequest[];
+}
+/**
+ * A hook per phase; every one optional. platform-web registers one participant
+ * for the DOM host layer and the renderer registers another, so neither has to
+ * know the other exists.
+ */
+interface FrameParticipant {
+    readonly id: string;
+    readonly collect?: (context: FrameContext) => void;
+    readonly read?: (context: FrameContext) => void;
+    readonly update?: (context: FrameContext) => void;
+    readonly write?: (context: FrameContext) => void;
+    readonly render?: (context: FrameContext) => void;
+}
+interface FrameReport {
+    readonly frame: FrameInfo;
+    readonly resolution: SceneResolution;
+    /** Same-plane surface overlaps found after the read phase, in dev mode. */
+    readonly overlaps: readonly PlaneOverlap[];
+    /** Groups whose padded proxies would cover the same pixels — X1's other half. */
+    readonly proxyOverlaps: readonly ProxyOverlap[];
+    /**
+     * The rebuilds a write participant actually claimed — nothing more. The
+     * scheduler never consumes on the frame's own behalf, because consuming
+     * advances the source's `builtEpoch`: a rebuild taken so the report could be
+     * "complete" would leave the source looking clean with no renderer having built
+     * anything, and the pyramid would never be rebuilt. A frame with nobody to do
+     * the work — no renderer registered yet, or one sitting out a device-loss
+     * recovery — must therefore hand out nothing at all.
+     */
+    readonly rebuilds: readonly BackdropRebuildRequest[];
+    /**
+     * The source ids still dirty when the frame ended: whatever no participant
+     * claimed, plus sources no group samples yet. Read with the non-consuming peek,
+     * so a frame is never charged a rebuild for being reported on. A rebuild
+     * survives here until a renderer takes it, which is precisely what lets
+     * device-loss recovery pick the work back up instead of losing it.
+     */
+    readonly pendingSources: readonly string[];
+}
+interface FrameScheduler {
+    /** Registering an existing id replaces that participant. */
+    addParticipant(participant: FrameParticipant): void;
+    removeParticipant(id: string): void;
+    readonly participants: readonly FrameParticipant[];
+    runFrame(frame: FrameInfo): FrameReport;
+}
+interface FrameSchedulerOptions {
+    readonly scene: GlassScene;
+}
+declare function createFrameScheduler(options: FrameSchedulerOptions): FrameScheduler;
+
+/**
+ * X5 — the colour pipeline, CPU side.
+ *
+ * The contract in one line: **internal optical maths in linear light,
+ * compositing premultiplied, output sRGB, v1 locked to the sRGB gamut.** Without
+ * that lock golden images destabilise across GPUs and browsers and blur energy
+ * drifts from the reference, which is the whole reason §Color pipeline exists.
+ *
+ * Three concrete consequences the rest of the renderer leans on:
+ *
+ * 1. **Every internal texture is `rgba16float` and holds linear light.** 8-bit
+ *    linear would band visibly in a blur pyramid; `rgba16float` is renderable and
+ *    filterable everywhere WebGPU is, so no adapter feature is required.
+ * 2. **Alpha is normalised at import** (X3). `copyExternalImageToTexture`
+ *    delivers premultiplied; `importExternalTexture` delivers unpremultiplied.
+ *    Whichever arrives, level 0 of the pyramid is premultiplied linear — one
+ *    invariant, checked once at import, instead of an alpha mode threaded
+ *    through every downstream pass.
+ * 3. **Output is encoded once, at the end of the last pass.** The optics and
+ *    highlight canvases are configured `alphaMode: "premultiplied"` in a plain
+ *    (non-`-srgb`) 8-bit format, and the browser composites those bytes as sRGB.
+ *    So the final step is `encode(linear)` and then `* alpha` — premultiplying in
+ *    the *encoded* space, which is what canvas compositing expects. Premultiplying
+ *    in linear and then encoding would darken every edge pixel.
+ *
+ * The transfer functions here are the exact piecewise sRGB curve, not the 2.2
+ * approximation: the WGSL uses the same piecewise form, and a test asserts the
+ * two agree, so a golden regenerated on one and asserted on the other cannot
+ * drift by a code unit.
+ */
+/**
+ * The colour spaces v1 accepts on an imported backdrop.
+ *
+ * `display-p3` is *accepted and tagged*, never silently treated as sRGB — but v1
+ * converts it into the sRGB working space rather than carrying a wide gamut
+ * through the pipeline (§Color pipeline: "Display-P3 and HDR/extended-range are
+ * future profiles"). Tagging it is what makes the future profile a data change.
+ */
+declare const BACKDROP_COLOR_SPACES: readonly ["srgb", "display-p3"];
+type BackdropColorSpace = (typeof BACKDROP_COLOR_SPACES)[number];
+/** How a provider's pixels arrive. Normalised to `premultiplied` at import. */
+declare const BACKDROP_ALPHA_MODES: readonly ["premultiplied", "unpremultiplied", "opaque"];
+type BackdropAlphaMode = (typeof BACKDROP_ALPHA_MODES)[number];
+type Rgb = readonly [r: number, g: number, b: number];
+
+/**
+ * The optical constants, and the two foldings that decide what the shader
+ * actually gets: the dual cap, and the size-parameterised lens.
+ *
+ * **Every number here is advisory and calibration-delegated (C7).** They are
+ * chosen so the material is coherent out of the box — a plausible glass, not a
+ * measured one — and §Calibration names exactly this kind of value as a delegated
+ * unknown. They live in one profile object (`MaterialProfile`) so replacing them
+ * with fitted values is a data change (`withMaterialOverrides`), and no shader
+ * carries a literal of its own. The named constants below are re-exports of that
+ * profile's defaults, kept because a reader wants a name for σ = 8 more often
+ * than a whole profile.
+ *
+ * ## The dual cap (Decision Log #19)
+ *
+ * Two independent things cap refraction: the accessibility policy's regime
+ * (`nominal | reduced | none`) and the group's resolved capability state
+ * (`true | approximate | none` — what the sampling backend can actually deliver).
+ * **The lower of the two wins**, and this module folds them into one scalar before
+ * anything reaches a uniform, so the shader has no way to honour the wrong one.
+ *
+ * The ordering mirrors `platform-web`'s `REFRACTION_LADDER`, which serves the CSS
+ * tier. It is restated rather than imported because this package sits *below*
+ * core in the dependency graph and platform-web sits above it. That the two
+ * copies must agree is a real (if small) seam — see the note in the C6 report.
+ */
+
+/** X2's `RefractionQuality`, restated. Weakest first — the declaration order IS the ladder. */
+declare const REFRACTION_LADDER: readonly ["none", "approximate", "true"];
+type RefractionQuality = (typeof REFRACTION_LADDER)[number];
+/**
+ * The slice of core's `ResolvedAccessibilityPolicy["material"]` the renderer
+ * reads. core's type is assignable to this; a test pins that.
+ */
+interface MaterialPolicyView {
+    readonly glass: "material" | "none";
+    readonly frost: "nominal" | "increased" | "none";
+    readonly refraction: "nominal" | "reduced" | "none";
+    readonly occlusion: "nominal" | "increased" | "opaque";
+    readonly border: "nominal" | "strong";
+    readonly ambientTint: "nominal" | "reduced" | "none";
+    readonly foreground: "adaptive" | "near-monochrome";
+}
+/** The two variants, declared as data so a profile merge can walk them. */
+declare const MATERIAL_VARIANTS: readonly ["regular", "clear"];
+type MaterialVariant = (typeof MATERIAL_VARIANTS)[number];
+interface MaterialOptics {
+    /** Body blur σ in CSS px. Matches `platform-web`'s `MATERIAL_OPTICS.blurRadius`. */
+    readonly blurSigma: number;
+    /** Tint over the blurred backdrop, linear light. */
+    readonly tint: Rgb;
+    readonly tintAlpha: number;
+    /** Rim band half-width in CSS px, and its ambient brightness. */
+    readonly rimWidth: number;
+    readonly rimAlpha: number;
+    /** Specular exponent and gain on the rim. */
+    readonly specularPower: number;
+    readonly specularGain: number;
+    /** Inner-shadow depth (0..1) and how much of it is applied. */
+    readonly shadowDepth: number;
+    readonly shadowAlpha: number;
+    /** Highlight colour for the sweep and press glow, linear light. */
+    readonly highlight: Rgb;
+}
+/** The rim a `border: "strong"` policy substitutes, whatever the variant asked for. */
+interface MaterialRim {
+    readonly rimWidth: number;
+    readonly rimAlpha: number;
+}
+/**
+ * Every number the material runs on, in one place.
+ *
+ * The same seam `@vitrea/motion`'s `MotionProfile` opens for the drivers, for the
+ * optics: C7's harness measures these against `apple-macos-26.5-*` fixtures and
+ * replaces what is here, so nothing downstream may hard-code an optical constant
+ * of its own. A profile overrides every one of them (`withMaterialOverrides`),
+ * which makes landing a calibrated set a data change rather than a code change.
+ *
+ * Units: CSS px for distance, linear light for colour, viewport coordinates with
+ * y pointing down for direction.
+ */
+interface MaterialProfile {
+    /** Per-variant optics. `clear` is persistently more transparent than `regular`. */
+    readonly optics: Readonly<Record<MaterialVariant, MaterialOptics>>;
+    /** The two ends of adaptation: what the tint becomes over a dark and a light backdrop. */
+    readonly adaptiveTintDark: Rgb;
+    readonly adaptiveTintLight: Rgb;
+    /** Luminance band the tint crosses over. Hysteresis in time is the driver's job. */
+    readonly adaptiveLuminanceLow: number;
+    readonly adaptiveLuminanceHigh: number;
+    /**
+     * How much of the lens the shader is allowed to apply, per rung.
+     *
+     * `approximate` is not "half of true": it is the rim-lensing approximation, a
+     * shallower bend confined nearer the edge, which is what a group sampling a CSS
+     * proxy can honestly claim. Reduced transparency lands here too, which is the
+     * point of the ladder having three rungs and not two.
+     */
+    readonly refractionScale: Readonly<Record<RefractionQuality, number>>;
+    /**
+     * The size-parameterised lens depth — parent acceptance #2's mechanism.
+     *
+     * Below `lensSpanMin` a surface gets its authored thickness and nothing more;
+     * above `lensSpanMax` it gets `lensSizeGainMax` times it. The final clamp to the
+     * shorter *half* extent is what keeps a small control from being all lens: a
+     * 24 px-tall button cannot bend more than 12 px of backdrop however thick it is
+     * authored.
+     *
+     * A smoothstep rather than a straight ratio, so two surfaces of nearly the same
+     * size never read as differently thick, and so the gain saturates instead of
+     * growing without bound on a full-width platter.
+     */
+    readonly lensSpanMin: number;
+    readonly lensSpanMax: number;
+    readonly lensSizeGainMax: number;
+    /** Chain LOD per CSS px of lens depth, and how much sharper the rim samples. */
+    readonly lensBodyLodPerPx: number;
+    readonly lensRimLodBias: 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
+     * under the same preference.
+     */
+    readonly reducedTransparencyFrost: number;
+    /**
+     * How much of the *remaining* transparency reduced transparency closes.
+     *
+     * **Relative, not absolute (Decision Log #32(d)).** This was
+     * `increasedOcclusionAlpha`, an absolute floor of 0.62 applied as
+     * `Math.max(nominal, floor)` — a real lift while nominal was the advisory 0.28,
+     * and a no-op from the moment C9a measured nominal at 0.62. The policy died
+     * without being touched and nothing noticed for a whole child. A fraction of the
+     * headroom cannot die that way: it lifts strictly for every nominal below 1,
+     * whatever a later tuning pass moves nominal to.
+     *
+     * The fraction is the pre-C9a lift, restored rather than invented:
+     * (0.62 − 0.28) / (1 − 0.28) = 0.4722, which reproduces the old floor exactly at
+     * the old nominal. At today's nominal it reads 0.62 → 0.799.
+     *
+     * Mirrored by `@vitrea/platform-web`'s `INCREASED_OCCLUSION_LIFT`, and pinned in
+     * both directions by `packages/calibration/test/tier-coherence.test.ts`.
+     */
+    readonly increasedOcclusionLift: number;
+    readonly strongBorderRim: MaterialRim;
+    readonly reducedTintAdaptation: number;
+    /**
+     * Advisory light direction, in viewport coordinates with y pointing down: a
+     * little left of straight overhead, which is where Apple's material reads its
+     * specular from.
+     */
+    readonly lightDirection: readonly [number, number];
+    /** Specular sweep band width in radians, and the press glow's reach in CSS px. */
+    readonly sweepBandRadians: number;
+    readonly glowRadiusCss: number;
+    readonly glowGain: number;
+    readonly sweepGain: number;
+}
+/**
+ * A profile patch: any subset, to any depth, of what a profile holds.
+ *
+ * A colour is one leaf, not three: patching a tint means naming the whole triple,
+ * because two channels of a fitted colour and one of the default is not a colour
+ * anybody measured.
+ */
+interface MaterialProfilePatch {
+    readonly optics?: Readonly<Partial<Record<MaterialVariant, Readonly<Partial<MaterialOptics>>>>>;
+    readonly adaptiveTintDark?: Rgb;
+    readonly adaptiveTintLight?: Rgb;
+    readonly adaptiveLuminanceLow?: number;
+    readonly adaptiveLuminanceHigh?: number;
+    readonly refractionScale?: Readonly<Partial<Record<RefractionQuality, number>>>;
+    readonly lensSpanMin?: number;
+    readonly lensSpanMax?: number;
+    readonly lensSizeGainMax?: number;
+    readonly lensBodyLodPerPx?: number;
+    readonly lensRimLodBias?: number;
+    readonly reducedTransparencyFrost?: number;
+    readonly increasedOcclusionLift?: number;
+    readonly strongBorderRim?: Readonly<Partial<MaterialRim>>;
+    readonly reducedTintAdaptation?: number;
+    readonly lightDirection?: readonly [number, number];
+    readonly sweepBandRadians?: number;
+    readonly glowRadiusCss?: number;
+    readonly glowGain?: number;
+    readonly sweepGain?: number;
+}
+
+/**
+ * Backdrop analysis on the CPU side: the stats a reduction produced, and the
+ * temporal hysteresis that makes them usable.
+ *
+ * §Motion binds `backdrop-adaptation values` to the *exponential low-pass +
+ * hysteresis* driver, and §Motion also puts every driver on the CPU. So the shape
+ * is: the GPU reduces (exactly — X2's `analysis: "exact"`), the result is read
+ * back at a low rate, and `LowPassHysteresisDriver` from `@vitrea/motion` — the
+ * same class the rest of the runtime uses, not a reimplementation — smooths it.
+ * The shader reads the driver's output as a uniform and never sees the raw stat.
+ *
+ * ## Why the readback is not a per-frame cost
+ *
+ * §Foreground adaptation caps the readback at an advisory 15 Hz (Decision Log
+ * #19), and the governor lowers it further. That is not a performance
+ * concession — it is what keeps the adaptation honest. A per-frame readback would
+ * either stall the pipeline waiting for the map, or produce a value two frames old
+ * and pretend it was current. At 15 Hz with a 500 ms low-pass the staleness is far
+ * inside the filter's own time constant, so it is invisible in the output.
+ *
+ * ## The band is on the input, not the output
+ *
+ * `LowPassHysteresisDriver` commits a new observation only once it departs the
+ * *committed* value by more than the band, then low-passes the committed
+ * staircase. Measuring against the moving output instead would let a slow drift
+ * leak through one small step at a time, which is exactly the foreground pumping
+ * §Foreground adaptation rules out. That property is the driver's, and it is the
+ * reason to use the driver rather than an `exp()` here.
+ */
+
+/** The four floats the reduction writes. */
+interface BackdropStats {
+    /** Mean linear luminance, 0..1-ish (an HDR-ish source can exceed 1). */
+    readonly luminance: number;
+    /** Variance of linear luminance. */
+    readonly variance: number;
+    /** Mean luminance-gradient magnitude per texel — the edge-density measure. */
+    readonly edgeDensity: number;
+    /** Samples the reduction actually took. 0 means "never reduced". */
+    readonly sampleCount: number;
+}
+
+/**
+ * X3 — the BackdropFrame acquisition protocol, and a provider for every source
+ * kind §Backdrop contracts names.
+ *
+ * The spec calls this contract "operational, not aspirational", and the reason is
+ * a hard WebGPU fact: **there is no cross-device texture sharing.** So every
+ * source, however it arrives, is normalised through one protocol —
+ * `acquire(frame)` at frame start, `release()` after submit — and the frame
+ * carries the four things a consumer cannot infer: the binding, the size epoch,
+ * the colour space, and the alpha mode.
+ *
+ * ## The five kinds, and what is actually different about each
+ *
+ * | kind | mechanism | alpha | re-acquired |
+ * | --- | --- | --- | --- |
+ * | `image` | `copyExternalImageToTexture` | premultiplied | only when dirty |
+ * | `video` | `importExternalTexture` | **unpremultiplied** | **every sampling frame** |
+ * | `canvas` | `copyExternalImageToTexture` | premultiplied | every frame by default |
+ * | `gradient` | `queue.writeTexture` of CPU-generated texels | opaque | never |
+ * | `app-texture-view` | the app's own `GPUTexture` | declared by the app | every frame |
+ *
+ * Two of those cells are WebGPU semantics rather than choices, and §Surprises
+ * records them as such: `importExternalTexture` handles **expire at task end**, so
+ * a video must be re-imported on every frame that samples it; and imported video
+ * arrives **unpremultiplied** while copied images arrive premultiplied. The import
+ * pass normalises both to premultiplied linear, so nothing downstream branches on
+ * either fact.
+ *
+ * ## VideoFrame ownership
+ *
+ * X3: "`VideoFrame` close ownership held by the provider." When the app hands in a
+ * `VideoFrame`, this provider closes it in `release()` — after submit, because an
+ * imported external texture must outlive the submission that samples it. When the
+ * app hands in an `HTMLVideoElement` the browser owns the frames and the provider
+ * closes nothing. Getting that backwards leaks decoder buffers until playback
+ * stalls, which is why the two cases are separate provider inputs rather than one
+ * permissive union.
+ *
+ * ## Device generations
+ *
+ * The same WebGPU fact has a second consequence, and it is the one easiest to get
+ * wrong: a provider closes over the device it was built with, so when that device
+ * dies the provider holds storage nothing can bind and a texture handle nothing
+ * will complain about. `invalidate(generation, device)` is how a provider crosses
+ * that boundary — new device adopted, old storage dropped, re-import armed — and
+ * `generation` is the tag that says which side of it the provider is on. The
+ * app-texture provider is the exception on purpose: the renderer cannot re-make
+ * someone else's texture, so it refuses rather than binding a foreign-device view
+ * that would render nothing and report nothing.
+ *
+ * ## Validation at registration
+ *
+ * Also X3: app-supplied views "must satisfy declared usage/format/dimension
+ * requirements — validated at registration with a typed error, never discovered at
+ * draw time." `registerAppTexture` therefore takes the `GPUTexture`, not just a
+ * view: a `GPUTextureView` exposes none of its own properties, so a contract that
+ * accepted only a view could not be checked at all.
+ */
+
+declare const BACKDROP_KINDS: readonly ["image", "video", "canvas", "gradient", "app-texture-view"];
+type BackdropKind = (typeof BACKDROP_KINDS)[number];
+/** How the import pass binds the source. `external` needs its own pipeline. */
+type BackdropBinding = {
+    readonly kind: "sampled";
+    readonly view: GPUTextureView;
+} | {
+    readonly kind: "external";
+    readonly texture: GPUExternalTexture;
+};
+interface BackdropFrame {
+    readonly sourceId: string;
+    readonly binding: BackdropBinding;
+    /** Source extent in texture px. */
+    readonly width: number;
+    readonly height: number;
+    /** Bumped when the extent changes; invalidates every dependent allocation. */
+    readonly sizeEpoch: number;
+    readonly colorSpace: BackdropColorSpace;
+    readonly alphaMode: BackdropAlphaMode;
+    /** True when the sampled values are sRGB-encoded rather than linear. */
+    readonly encoded: boolean;
+}
+/** The frame facts a provider is handed. Matches core's `FrameInfo`. */
+interface FrameInfoView {
+    readonly id: number;
+    readonly timeMs: number;
+}
+interface BackdropProvider {
+    readonly id: string;
+    readonly kind: BackdropKind;
+    /**
+     * The device generation this provider's storage belongs to (`device.ts`'s
+     * counter). A provider built under one generation holds nothing a later
+     * generation can bind, and the failure is silent — so the number is here to be
+     * compared, cheaply, before anything of the provider's is used.
+     */
+    readonly generation: number;
+    /** True when content may have changed since the last successful import. */
+    isDirty(): boolean;
+    /** X3: at frame start. Throws `source-unavailable` if the source cannot serve. */
+    acquire(frame: FrameInfoView): BackdropFrame;
+    /** X3: after submit. Releases whatever the acquire took ownership of. */
+    release(): void;
+    /** Called once the import pass has consumed the frame's pixels. */
+    markImported(): void;
+    /**
+     * Adopt `device` at `generation`: the device that built this provider's storage
+     * is gone.
+     *
+     * Every provider closes over the device it was built with, so a reset that only
+     * cleared the dirty flags would re-import onto the dead device and hand the new
+     * one a foreign texture. Hence the device travels with the call.
+     *
+     * A provider whose storage the renderer allocated drops it and arms a
+     * re-import, so recovery flows through the ordinary dirty path. A provider
+     * wrapping the *app's* own texture cannot be re-pointed at all — WebGPU has no
+     * cross-device sharing, and the app owns the texture — so it refuses every
+     * later `acquire` with a typed error instead of binding a foreign-device view.
+     */
+    invalidate(generation: number, device: BackdropDevice): void;
+    /**
+     * Re-declare the source's extent. Implemented where the renderer allocates the
+     * storage (image, canvas); absent where the source declares its own size.
+     */
+    resize?(width: number, height: number): void;
+    destroy(): void;
+}
+/** The slice of `GPUDevice` the providers need. `GPUDevice` satisfies it as-is. */
+interface BackdropDevice {
+    readonly queue: GPUQueue;
+    readonly limits: GPUSupportedLimits;
+    createTexture(descriptor: GPUTextureDescriptor): GPUTexture;
+    importExternalTexture(descriptor: GPUExternalTextureDescriptor): GPUExternalTexture;
+}
+/** Anything `copyExternalImageToTexture` accepts as a source. */
+type CopyableSource = ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageData | VideoFrame;
+interface CopyProviderOptions {
+    readonly id: string;
+    readonly kind: "image" | "canvas";
+    readonly device: BackdropDevice;
+    readonly source: CopyableSource;
+    readonly width: number;
+    readonly height: number;
+    readonly colorSpace?: BackdropColorSpace;
+    /**
+     * Whether content changes every frame. `true` for a live canvas, `false` for a
+     * decoded image — which is what makes a static backdrop rebuild nothing at all
+     * (§Core model invariant).
+     */
+    readonly live?: boolean;
+    /** The device generation this provider is being built under. See `BackdropProvider.generation`. */
+    readonly generation?: number;
+}
+interface VideoProviderOptions {
+    readonly id: string;
+    readonly device: BackdropDevice;
+    /**
+     * Either a live element the browser keeps frames for, or a callback producing a
+     * `VideoFrame` this provider then owns and closes. The two are separate because
+     * their ownership rules are opposite — see the module note.
+     */
+    readonly source: {
+        readonly kind: "element";
+        readonly element: HTMLVideoElement;
+    } | {
+        readonly kind: "frames";
+        readonly next: () => VideoFrame | undefined;
+    };
+    readonly colorSpace?: BackdropColorSpace;
+    /** The device generation this provider is being built under. See `BackdropProvider.generation`. */
+    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`.
+ *
+ * The renderer sits **below** core in the dependency graph: core reaches it
+ * through a dynamic import (X7's lazy seam), so importing core back would close a
+ * cycle that neither `pnpm -r build` nor `tsc` can order. The types below are
+ * therefore declared as the *minimal structural contract* the renderer reads, and
+ * core's own types satisfy them without an adapter — `SceneResolution`,
+ * `FrameContext` and `FrameParticipant` are assignable to the views here, which
+ * `test/core-contract.test.ts` asserts against core's real modules.
+ *
+ * Two things genuinely do not come from core, and both are flagged as
+ * parent-impact rather than papered over:
+ *
+ *  - **The corner reference.** `GlassNodeDescriptor` carries `shapeFamily` and
+ *    the X8 channel vector but not which of the two corner references the shape
+ *    is fit against (Decision Log #22a made those two separate references, not
+ *    one axis). It defaults to `"apple-continuous"`, which is what the public
+ *    `profile: "continuous"` — the default — resolves to.
+ *  - **The concentric parent link.** X8 rider 2 binds the renderer to draw a
+ *    concentric child as a level set *of its parent's field*, which needs to know
+ *    which surface the parent is. core's node descriptor has no parent edge, so it
+ *    arrives as a render input.
+ *
+ * Interaction values arrive as **numbers**, never as time. §Motion puts the
+ * drivers on the CPU and the spec is explicit that this package consumes their
+ * outputs; there is no clock anywhere in this package for the same reason there is
+ * none in core.
+ */
+
+/** Motion-driver outputs for one surface. Every one is a value, never a time. */
+interface SurfaceChannels {
+    /** `pressCompression`, 0..1. Scaled by motion's `pressCompressionScale`. */
+    readonly press: number;
+    /** `glow`, 0..1, from the fast-attack / slow-decay driver. */
+    readonly glow: number;
+    /** Specular sweep position, 0..1 around the contour. */
+    readonly sweep: number;
+    /** `lensStrength`, 0..1. Multiplies the resolved refraction scale. */
+    readonly lensStrength: number;
+    /** Press point in viewport CSS px. Defaults to the surface's centre. */
+    readonly pressPoint?: readonly [number, number];
+}
+interface SurfaceInput {
+    readonly nodeId: string;
+    readonly family: ShapeFamily;
+    /** X8, in viewport CSS px. `centre` is the surface's centre, `size` its full extent. */
+    readonly shape: ShapeChannels;
+    /** Defaults to `"apple-continuous"` — see the module note. */
+    readonly reference?: CornerReference;
+    readonly variant?: MaterialVariant;
+    readonly channels?: Partial<SurfaceChannels>;
+    /**
+     * X8 rider 2. When present this surface renders as `parentField + inset`, and
+     * the parent must be declared in the same group — as a member, or as a
+     * `fieldReferenceOnly` shape.
+     */
+    readonly concentricOf?: {
+        readonly nodeId: string;
+        readonly inset: number;
+    };
+    /**
+     * Declared so a concentric child can be a level set of it, but not itself
+     * drawn.
+     *
+     * This exists because of what a union is: a concentric child's field is its
+     * parent's plus a positive inset, so inside the parent the child is always the
+     * larger value and `min` discards it. A child nested in the same union as its
+     * parent is therefore invisible *by construction* — correct, and not what an
+     * inset indicator inside a segmented control's track wants. There, the track
+     * and the indicator are separate surfaces with separate material, and the
+     * indicator's group needs the track's geometry only as the field its own
+     * contour is offset from.
+     */
+    readonly fieldReferenceOnly?: boolean;
+}
+interface GroupRenderInput {
+    readonly groupId: string;
+    readonly surfaces: readonly SurfaceInput[];
+    /** The backdrop source to sample. Absent means the group draws with no backdrop. */
+    readonly backdropSourceId?: string;
+    /** X2's resolved refraction quality for this group. Half of the dual cap. */
+    readonly refraction: RefractionQuality;
+    /** True where X2 resolved `analysis: "exact"`; gates adaptive tint. */
+    readonly analysisExact: boolean;
+    readonly variant?: MaterialVariant;
+    /** Overrides the calibration-delegated union defaults. */
+    readonly union?: GroupUnionParams;
+}
+/**
+ * The structural view of core's `SceneResolution` the renderer reads, so a host
+ * can hand core's own object straight through.
+ */
+interface SceneResolutionView {
+    readonly groups: readonly {
+        readonly groupId: string;
+        readonly state: {
+            readonly refraction: RefractionQuality;
+            readonly analysis: "exact" | "hint" | "none";
+            readonly samplingBackend: "gpu-texture" | "css-backdrop" | "none";
+        };
+    }[];
+    readonly accessibility: {
+        readonly material: MaterialPolicyView;
+    };
+}
+/** The structural view of core's `BackdropRebuildRequest`. */
+interface RebuildRequestView {
+    readonly sourceId: string;
+    readonly epoch: number;
+    readonly resolution: {
+        readonly scale: number;
+        readonly maxDimension: number;
+    };
+    readonly groupIds: readonly string[];
+}
+/** The structural view of core's `FrameContext`. */
+interface FrameContextView {
+    readonly frame: {
+        readonly id: number;
+        readonly timeMs: number;
+    };
+    readonly phase: "collect" | "read" | "update" | "write" | "render";
+    readonly resolution?: SceneResolutionView;
+    consumeDirtyBackdropSources(): readonly RebuildRequestView[];
+}
+/** The structural view of core's `FrameParticipant`. */
+interface FrameParticipantView {
+    readonly id: string;
+    readonly write?: (context: FrameContextView) => void;
+    readonly render?: (context: FrameContextView) => void;
+}
+
+/**
+ * Pass-by-pass timing, for the benchmark §Performance envelope pins the ~2 ms
+ * hypothesis to.
+ *
+ * The spec asks for the budget to be "measured per pass (backdrop import, blur,
+ * analysis, body, highlight, composite) alongside browser end-to-end frame time",
+ * which needs GPU-side timestamps: wall-clock around `submit()` measures the
+ * queue, not the work. WebGPU's only timestamp mechanism is `timestampWrites` on
+ * a pass descriptor — `encoder.writeTimestamp` was removed from the spec — so the
+ * timeline hands out begin/end query indices by label and each pass spreads them
+ * into its descriptor.
+ *
+ * Where `timestamp-query` is unavailable the timeline is simply absent and the
+ * benchmark falls back to wall-clock totals, reported as such. A number labelled
+ * as a GPU pass time that was actually a CPU submit time would be worse than no
+ * number, and §Risks already names timestamp-query availability as an engine
+ * variance to record rather than to assume.
+ *
+ * One caveat worth stating because it changes how the results read: Chrome
+ * quantises timestamp results to 100 µs by default, so a single short pass reads
+ * as 0. The benchmark works around it the way S2's harness did — by launching with
+ * `--disable-dawn-features=timestamp_quantization`, and by measuring many
+ * repetitions when it cannot.
+ */
+interface PassTimeline {
+    /** Query indices for a render pass, or undefined when timing is off. */
+    renderSlot(label: string): GPURenderPassTimestampWrites | undefined;
+    computeSlot(label: string): GPUComputePassTimestampWrites | undefined;
+}
+interface TimingCollector extends PassTimeline {
+    readonly capacity: number;
+    readonly used: number;
+    /** Queue the resolve + copy. Call once, after the last pass of the frame. */
+    resolve(encoder: GPUCommandEncoder): void;
+    /** Read the resolved timings. Labels map to elapsed nanoseconds. */
+    read(): Promise<ReadonlyMap<string, number>>;
+    /**
+     * Slots whose resolved pair was not a positive duration, since the collector
+     * was created. A non-zero count means some number reported here is missing a
+     * pass, and saying so is better than quietly averaging it in.
+     */
+    readonly anomalies: number;
+    reset(): void;
+    destroy(): void;
+}
+
+interface PyramidPlan {
+    /** Level 0 size in texture px. */
+    readonly width: number;
+    readonly height: number;
+    readonly levelCount: number;
+    /** The highest LOD the optics pass may sample: `levelCount - 1`. */
+    readonly maxLod: number;
+    /** Which level the analysis reduction reads. */
+    readonly analysisLevel: number;
+    /** Per-level sizes, index 0 = level 0. */
+    readonly levels: readonly {
+        readonly width: number;
+        readonly height: number;
+    }[];
+}
+interface ResolutionPolicyView {
+    readonly scale: number;
+    readonly maxDimension: number;
+}
+
+/**
+ * The §Core model invariant, as a testable object.
+ *
+ * > blur/analysis pyramids belong to `BackdropSource`, rebuilt **at most once per
+ * > dirty source per frame** — never per group.
+ *
+ * core enforces one half of that: `consumeDirtyBackdropSources(frameId)` hands out
+ * one pass over the dirty set per frame id, so a second caller in the same frame
+ * gets nothing. What core cannot see is the renderer's side — a renderer that also
+ * rebuilt lazily on first draw, or that rebuilt once per group from a single
+ * request, would satisfy core's guard and still violate the invariant.
+ *
+ * So the ledger lives here, apart from the GPU work it guards, for one reason: it
+ * makes the invariant assertable against core's real scheduler with no adapter and
+ * no device. `pyramid.ts` claims through it before it encodes a single pass, and
+ * `test/dirty-epoch.test.ts` drives core's own scene and scheduler over this same
+ * object. An invariant tested only through a GPU is an invariant tested only where
+ * a GPU exists.
+ */
+interface RebuildLedger {
+    /**
+     * Begin a frame. Clears the per-frame tally — unless `frameId` is the frame
+     * already being recorded, which is not a new frame and must not reopen the
+     * tally. The renderer draws one plane per call with the same `FrameInfo`, so
+     * that case is the ordinary one rather than the exception.
+     */
+    beginFrame(frameId: number): void;
+    readonly frameId: number | undefined;
+    /**
+     * Claim the one rebuild this source is allowed this frame. `false` means it has
+     * already had it — the caller must not encode a second one.
+     */
+    claim(sourceId: string): boolean;
+    /** Record that a claim did no work because the source was clean. */
+    recordClean(): void;
+    /** Rebuilds recorded for `sourceId` in the frame being recorded. */
+    countInFrame(sourceId: string): number;
+    readonly rebuilds: number;
+    readonly refusedDuplicates: number;
+    readonly skippedClean: number;
+    /**
+     * Highest per-source rebuild count seen in any single frame. The invariant is
+     * exactly the statement that this never exceeds 1.
+     */
+    readonly peakPerSourcePerFrame: number;
+}
+
+/**
+ * The blur/analysis pyramid, one per `BackdropSource`, and the ledger that proves
+ * the §Core model invariant.
+ *
+ * > **Invariant:** blur/analysis pyramids belong to `BackdropSource`, rebuilt **at
+ * > most once per dirty source per frame** — never per group. Static backdrops
+ * > rebuild nothing.
+ *
+ * core enforces half of that already: `consumeDirtyBackdropSources(frameId)`
+ * hands out one pass over the dirty set per frame id, so however many
+ * participants ask, the second call returns nothing. What core *cannot* see is
+ * this side of the wire — a renderer that also rebuilt lazily on first draw, or
+ * that rebuilt once per group from one request, would satisfy core's guard and
+ * violate the invariant. So the ledger here counts rebuilds per source per frame
+ * on the renderer's own books, refuses a second one, and exposes the counters.
+ * That is what makes the invariant *instrumented* rather than asserted.
+ *
+ * ## Pass structure per rebuild
+ *
+ * ```
+ * import      provider frame  ->  chain mip 0     (premultiplied linear, X5)
+ * downsample  mip n-1         ->  chain mip n     (13-tap, one pass per level)
+ * blur x2     chain[bodyLvl]  ->  body            (separable, residual sigma)
+ * analysis    chain[anaLvl]   ->  stats buffer    (compute, one workgroup)
+ * ```
+ *
+ * Reading mip n-1 while rendering into mip n is legal because they are distinct
+ * subresources, and every view here is created with an explicit
+ * `baseMipLevel`/`mipLevelCount: 1` so that is true by construction rather than by
+ * the driver's interpretation of a full-texture view.
+ */
+
+interface PyramidResources {
+    readonly sourceId: string;
+    readonly plan: PyramidPlan;
+    readonly chain: GPUTexture;
+    readonly body: GPUTexture;
+    readonly stats: GPUBuffer;
+    /** Source size epoch this allocation was made for. */
+    readonly sizeEpoch: number;
+    /** The dirty epoch the last successful rebuild satisfied. */
+    readonly builtEpoch: number;
+}
+interface PyramidInstrumentation {
+    /** Successful rebuilds since the store was created. */
+    readonly rebuilds: number;
+    /** Rebuild attempts refused because the source had already rebuilt this frame. */
+    readonly refusedDuplicates: number;
+    /** Rebuilds skipped because the source was clean. */
+    readonly skippedClean: number;
+    readonly reallocations: number;
+    /** Rebuild count for one source within the frame currently being recorded. */
+    rebuildsInFrame(sourceId: string): number;
+    /** Highest per-source rebuild count seen in any single frame. Must stay <= 1. */
+    readonly peakRebuildsPerSourcePerFrame: number;
+}
+interface PyramidBuildRequest {
+    readonly sourceId: string;
+    readonly epoch: number;
+    readonly resolution: ResolutionPolicyView;
+    /**
+     * The material's body blur, in **CSS px**, with the viewport it is measured
+     * against.
+     *
+     * Not in source texels, because the conversion between the two is a property of
+     * the frame that has not been acquired yet: a 3840-wide video behind a 390 px
+     * viewport packs ten source texels into every CSS px, so a σ of 8 texels would
+     * be a σ of 0.8 CSS px on screen — a tenth of the frost the material asked for.
+     * The build resolves it once the frame's real extent is known.
+     */
+    readonly bodySigmaCss: number;
+    readonly viewportCss: readonly [number, number];
+}
+type PyramidBuildOutcome = {
+    readonly status: "built";
+    readonly resources: PyramidResources;
+} | {
+    readonly status: "duplicate";
+} | {
+    readonly status: "clean";
+    readonly resources: PyramidResources;
+} | {
+    readonly status: "unavailable";
+    readonly reason: string;
+};
+interface PyramidStore {
+    readonly instrumentation: PyramidInstrumentation;
+    /** The invariant's ledger, exposed so a test can drive it without a device. */
+    readonly ledger: RebuildLedger;
+    /** Start recording a new frame. Clears the per-frame rebuild tally. */
+    beginFrame(frameId: number): void;
+    /** Attach a timing collector for this frame, or `undefined` to time nothing. */
+    setTimeline(timeline: PassTimeline | undefined): void;
+    build(request: PyramidBuildRequest, provider: BackdropProvider, encoder: GPUCommandEncoder): PyramidBuildOutcome;
+    /**
+     * Release every provider acquired this frame.
+     *
+     * Split from `afterSubmit` because the two halves have opposite failure rules.
+     * A release is owed whether or not the frame reached the queue — an acquired
+     * `VideoFrame` held across a frame stalls decoding — so this belongs in a
+     * `finally` around the whole encode/submit. Call it after `queue.submit` on the
+     * success path: an imported external texture must outlive the submission that
+     * samples it.
+     */
+    releaseAcquired(): void;
+    /**
+     * Start the analysis readback maps. **Success path only**: `mapAsync` makes a
+     * buffer unavailable to submits from the moment it is called, so starting a map
+     * for a copy that was never submitted is its own bug — see `requestStats`.
+     */
+    afterSubmit(): void;
+    /**
+     * The source's pyramid, or `undefined` when it has none the pool still owns.
+     * A caller may bind what this returns without checking anything further.
+     */
+    resources(sourceId: string): PyramidResources | undefined;
+    /** Copy a source's stats into a staging buffer and map it. Cadence-gated by the caller. */
+    requestStats(sourceId: string, encoder: GPUCommandEncoder): boolean;
+    /** Resolve any completed stats readbacks. Returns what arrived. */
+    collectStats(): Promise<ReadonlyMap<string, BackdropStats>>;
+    forget(sourceId: string): void;
+    destroy(): void;
+}
+
+/**
+ * The renderer: device, resources, and the frame.
+ *
+ * Two entry points, deliberately:
+ *
+ *  - **`drawFrame`** — draw one frame into two texture views. No scene, no
+ *    scheduler, no DOM. This is what the golden suite and the benchmark drive, and
+ *    what makes the optical maths testable without standing up the whole runtime.
+ *  - **`frameParticipant`** — the same work split across core's `write` and
+ *    `render` phases, so `vitrea`'s scheduler drives it alongside
+ *    platform-web's DOM participant. Pyramid rebuilds land in `write` because that
+ *    is the phase core hands them out in; drawing lands in `render`, with the graph
+ *    frozen.
+ *
+ * The participant reads the frame's `resolution` when core supplies one, and
+ * prefers it over the group input's own `refraction`/`analysis` — core is the
+ * authority on resolved state (X2), and it is the frame's resolution that has been
+ * through the whole transition table. The group input's copies are the fallback for
+ * `drawFrame`, where there is no core.
+ *
+ * ## Device generations
+ *
+ * Everything GPU-shaped hangs off a `GpuContext` tagged with the device generation
+ * that made it. On loss the context is dropped whole, and the first frame on the
+ * replacement re-points every registered provider at the new device and marks it
+ * for re-import — so recovery flows through the ordinary
+ * one-rebuild-per-dirty-source-per-frame path instead of a special case, which
+ * means the recovery path is exercised by the same tests as the steady state.
+ *
+ * `ensureContext` is where that happens rather than the loss teardown, and the
+ * reason is timing: the teardown runs while there is no device to adopt, and this
+ * is the one place that knows both that a generation was superseded and what
+ * replaced it. It also runs before anything acquires on the new device, which the
+ * teardown cannot promise.
+ *
+ * The one provider that cannot be re-pointed is a backdrop over the *app's* own
+ * texture: WebGPU has no cross-device sharing and the renderer does not own the
+ * texture, so that provider refuses instead, and the refused rebuild is reported
+ * through `unbuiltSources` for the host to act on.
+ */
+
+interface ViewportState {
+    /** Viewport size in CSS px. */
+    readonly widthCss: number;
+    readonly heightCss: number;
+    readonly devicePixelRatio: number;
+}
+interface RendererInstrumentation {
+    readonly pyramid: PyramidStore["instrumentation"];
+    readonly texturePool: {
+        readonly live: number;
+        readonly created: number;
+        readonly destroyed: number;
+    };
+    readonly pipelines: {
+        readonly renderPipelines: number;
+        readonly computePipelines: number;
+    };
+    readonly framesDrawn: number;
+    readonly deviceGenerations: number;
+}
+interface DrawFrameArgs {
+    readonly frame: {
+        readonly id: number;
+        readonly timeMs: number;
+    };
+    /** The optics canvas' current texture view. */
+    readonly optics: GPUTextureView;
+    /** The highlight canvas' view. Omit to skip the highlight pass entirely. */
+    readonly highlight?: GPUTextureView;
+    readonly format?: GPUTextureFormat;
+    /**
+     * The rebuild requests core handed out. Omitted means "ask every registered
+     * provider whether it is dirty", which is what `drawFrame` does standalone.
+     */
+    readonly rebuild?: readonly RebuildRequestView[];
+    /** Core's resolved state for this frame. Overrides the group inputs' copies. */
+    readonly resolution?: SceneResolutionView;
+    readonly timing?: TimingCollector;
+    /** Clear the targets first. Default true. */
+    readonly clear?: boolean;
+}
+interface DrawFrameResult {
+    readonly groupsDrawn: number;
+    readonly rebuilds: number;
+    readonly skipped: readonly {
+        readonly groupId: string;
+        readonly reason: string;
+    }[];
+    /**
+     * Source ids core handed out a rebuild for that this frame did **not** build.
+     * The same list as `GlassRenderer.unbuiltSources` — see it for what a caller
+     * owes.
+     */
+    readonly unbuilt: readonly string[];
+}
+interface GlassRenderer {
+    readonly backend: "webgpu";
+    /** True only with a live, unlost device attached. */
+    readonly ready: boolean;
+    readonly passes: readonly string[];
+    readonly shaderSource: string;
+    readonly deviceStatus: RendererDeviceStatus;
+    /** The facts a host folds into core's `PlatformProbe`. */
+    readonly capabilityInput: DeviceCapabilityInput;
+    readonly governor: Governor;
+    readonly instrumentation: RendererInstrumentation;
+    /**
+     * The source ids the most recent frame was handed a rebuild for and did not
+     * build — because no provider is registered under the id, or because the
+     * provider could not serve a frame.
+     *
+     * This exists because core commits `builtEpoch` when it *hands out* the
+     * request, not when the renderer finishes: a request dropped here is a claim
+     * spent on nothing, and the source would sit clean at an epoch whose pixels
+     * were never imported. Core has no view of this side of the wire, so the
+     * renderer names the losses and the platform layer re-dirties them — one frame
+     * of latency, and no new core surface.
+     *
+     * Accumulated across the frame's planes, not per `drawFrame` call: a host draws
+     * one plane per call with the same frame id and hands the dirty set to the
+     * first of them only, so a later plane's empty answer must not erase what the
+     * first one found. Read after the frame's last plane, or after the
+     * participant's `render` phase. Empty on every ordinary frame.
+     */
+    readonly unbuiltSources: readonly string[];
+    attachDevice(device: GPUDevice, ownership?: DeviceOwnership): void;
+    replaceDevice(device: GPUDevice): void;
+    markWebGPUUnavailable(reason: "no-adapter" | "device-request-failed"): void;
+    registerBackdrop(provider: BackdropProvider): void;
+    unregisterBackdrop(sourceId: string): void;
+    backdrop(sourceId: string): BackdropProvider | undefined;
+    setViewport(viewport: ViewportState): void;
+    readonly viewport: ViewportState;
+    setGroup(input: GroupRenderInput): void;
+    removeGroup(groupId: string): void;
+    setAccessibility(policy: MaterialPolicyView): void;
+    /**
+     * Replace the optical tunables. The patch is applied to
+     * `DEFAULT_MATERIAL_PROFILE`, never to the profile currently in force, so two
+     * calls do not compound — a profile is a set of measurements, and half of one
+     * measurement set over half of another describes no material.
+     */
+    setMaterialProfile(patch: MaterialProfilePatch): void;
+    /** The tunables in force. Read-only; `setMaterialProfile` is the way in. */
+    readonly materialProfile: MaterialProfile;
+    drawFrame(args: DrawFrameArgs): DrawFrameResult;
+    /** Targets for the participant path, where core drives the phases. */
+    setTargets(targets: {
+        readonly optics: GPUTextureView;
+        readonly highlight?: GPUTextureView;
+        readonly format?: GPUTextureFormat;
+    }): void;
+    frameParticipant(): FrameParticipantView;
+    /** Resolve any completed analysis readbacks into the adaptation drivers. */
+    collectAdaptation(): Promise<number>;
+    destroy(): void;
+}
+
+/**
+ * X7 — the lazy renderer seam.
+ *
+ * The static import below is type-only, so it is erased at build time; the
+ * dynamic import is the only edge from core to the WebGPU renderer. That keeps
+ * every byte of WGSL out of core's entry chunk, so a CSS-tier consumer never
+ * downloads a shader. `packages/core/test/bundle-shape.test.ts` asserts it on
+ * the built artifact rather than trusting this comment.
+ */
+
+/**
+ * The renderer's constructors, as the seam's consumers need them.
+ *
+ * A host that attaches the renderer to real canvases also has to build the
+ * backdrop providers that feed it, and both must come through the *same* dynamic
+ * import — a second entry edge would emit a second chunk and split the renderer
+ * in two. Declared as an interface rather than `typeof import(...)` so the seam
+ * states exactly what it promises, and the real module is checked against it.
+ */
+interface WebGPURendererModule {
+    createWebGPURenderer(): GlassRenderer;
+    createCopyProvider(options: CopyProviderOptions): BackdropProvider;
+    createVideoProvider(options: VideoProviderOptions): BackdropProvider;
+}
+/** Resolve the renderer module. Call only after a capability probe says yes. */
+declare function loadWebGPURendererModule(): Promise<WebGPURendererModule>;
+/** Resolve the WebGPU renderer. Call only after a capability probe says yes. */
+declare function loadWebGPURenderer(): Promise<GlassRenderer>;
+
+/**
+ * vitrea — the platform-free heart of the runtime.
+ *
+ * One of the two published packages (X7). The internal @vitrea/* packages are
+ * bundled into this artifact at build time, so this package's published
+ * dependency list is empty.
+ *
+ * Pure and passive: no DOM, no Node built-ins (X4), no timers and no clocks.
+ * Every probe result, media-query answer and layout rect arrives as plain data;
+ * @vitrea/platform-web owns the browser and drives the frames.
+ *
+ * The modules, roughly in dependency order:
+ *
+ * - `state`, `capability` — X2's resolved-state model and the transition table
+ *   that produces it: what the app configured versus what it actually got.
+ * - `diagnostics` — how core reports what it will not silently fix.
+ * - `planes`, `frame` — the z-slot vocabulary and the frame-phase vocabulary.
+ * - `backdrop-hint` (X6), `foreground`, `material`, `accessibility` — the four
+ *   policy resolvers.
+ * - `scene` — the three registries, their references, and the dirty-epoch
+ *   bookkeeping behind the one-rebuild-per-dirty-source-per-frame invariant.
+ * - `scheduler` — the frame-phase contract plus a reference implementation.
+ * - `renderer-seam` — the lazy edge to the WebGPU renderer (X7).
+ */
+
+/**
+ * The contract sets core owns, re-exported so a consumer never installs an
+ * internal package. Reading these values here is also what makes the internal
+ * packages part of core's bundle — the property X7's bundle test checks.
+ */
+declare const VITREA_CONTRACTS: {
+    readonly shapeFamilies: readonly ShapeFamily[];
+    readonly interactionStates: readonly InteractionState[];
+    readonly motionDrivers: typeof MOTION_DRIVER_BY_CHANNEL;
+};
+/** Renderer tiers in v1's ladder. WebGL2 is out of scope; SVG displacement is a reserved seam. */
+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 ConfiguredSource, type CopyProviderOptions, type CornerProfile, type CornerRadii, 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 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$1 as 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, VITREA_CONTRACTS, type VariantMixingCheck, type Vec2, type VideoProviderOptions, WEBGPU_AVAILABILITIES, type WebGPUAvailability$1 as WebGPUAvailability, type WebGPURendererModule, type ZSlot, checkVariantMixing, classifyStateChange, compareZSlot, createDiagnosticsChannel, createFrameScheduler, createGlassScene, defaultForegroundAdaptation, inflateRect, isHealthy, loadWebGPURenderer, loadWebGPURendererModule, rectsOverlap, resolveAccessibilityPolicy, resolveBackdropHint, resolveForegroundAdaptation, resolveGlassGroupState, resolveMaterial, unionRect };