@satinhq/kit 0.0.0-stage → 0.1.0-beta.0

package/dist/glass/contactPhysics.js

@@ -0,0 +1,214 @@
+// The contact physics of interactive glass: how a glass shape answers a finger (light, growth,
+// follow, squish, release), one table for every interactive glass surface. The menu gesture
+// (document) and every interactive glass press (glass worker, InteractiveContact,
+// InteractivePress) read it. No DOM access: the glass worker imports it.
+//
+// The menu's measured laws come first; GLASS_CONTACT_PHYSICS below gives each kind of
+// interactive glass its parameters for those laws.
+// iOS 26.5 Menu observations, measured-reference. These bounded 2D fits approximate
+// the visible contour; native's optical warp is not its UIView transform.
+export function menuPull(displacement, gain, range) {
+    return (displacement * gain) / (1 + Math.abs(displacement) / range);
+}
+export const MENU_RELEASE_SPRING = Object.freeze({
+    stiffness: 111.73389187035956,
+    damping: 10.51444760548088,
+    delayMilliseconds: 4.941103419008078,
+});
+export function menuReturn(milliseconds) {
+    if (milliseconds >= 850)
+        return 0;
+    const t = Math.max(0, milliseconds - MENU_RELEASE_SPRING.delayMilliseconds) / 1000;
+    const a = MENU_RELEASE_SPRING.damping / 2;
+    const w = Math.sqrt(MENU_RELEASE_SPRING.stiffness - a * a);
+    return Math.exp(-a * t) * (Math.cos(w * t) + (a / w) * Math.sin(w * t));
+}
+export const MENU_STRAIN_RESPONSE_MS = 109.7745877972179;
+/* The closed Menu trigger trailing a held finger (measured-reference): per-axis gains of menuPull over a
+ * 300 pt rational range, approached with a 211 ms response. */
+export const MENU_TRIGGER_FOLLOW = Object.freeze({
+    gainX: 0.028852199054395337,
+    gainY: 0.01683370428028321,
+    rangePt: 300,
+    responseMs: 211.1299624689032,
+});
+/** The menu panel's velocity strain, in seconds of finger velocity: the panel leads along the
+ * motion (x, y), stretches along it and narrows across it. */
+export const MENU_STRAIN = Object.freeze({
+    leadXSeconds: 0.003524681648458459,
+    leadYSeconds: 0.0042655868076027946,
+    stretchSeconds: 0.004789086076060811,
+    narrowSeconds: 0.006870711203430614,
+});
+/**
+ * OWNER DECISION PENDING (Oct 12): which kinds of interactive glass let a horizontal drag that
+ * starts on them start the navigation back swipe.
+ *
+ * - `[]` (current): every interactive glass owns its horizontal drag; it stretches toward the
+ *   finger and never navigates.
+ * - `['button']` (native, iPad catalog Oct 13): a rightward drag that starts on a content glass
+ *   button drives the back swipe while the button stays pressed and moves with the page; its tap
+ *   cancels. Add `'bar'` / `'menu'` to extend that to toolbar buttons and menu triggers.
+ *
+ * Fields always own their drag (a composer drag must not open the iPad split pane), as do
+ * surfaces, Toggles and Sliders.
+ */
+export const GLASS_BACK_SWIPE = {
+    // Owner decision (Oct 13): match native. A content glass button lets a back swipe through
+    // and stays pressed while the page moves; fields, chrome, surfaces and thumbs keep their drag.
+    yieldingKinds: ['button'],
+};
+/*
+ * Native glass buttons on iPad (iPadOS 27, Oct 12; native reference `glass-press`, fit-grade counter
+ * captures: skips 1.4-3.1%, max skip 1; evidence `native-refs-iPad/glass-{inline,toolbar}-*`,
+ * fits in `glass-contact-one-path/native-fit/`):
+ * - A 60 pt drag over 400 ms moves the held Actions and Save buttons' centre 0.8 pt toward the
+ *   finger. With the menu strain's lead that is a follow gain of 0.010 per point (x); y keeps
+ *   the menu trigger's y/x ratio.
+ * - Dark: the glass whitens to a steady plateau (sRGB +51 of 223 over the backdrop, about 0.25
+ *   white) by ~170 ms, with no flash, and clears ~240 ms after release.
+ * - Light: the glass is white from the first pressed frame and stays white while held; it clears
+ *   over ~500 ms.
+ * - Labels: a content button's label stays at full strength (light 0 → 18 of 255, dark 255).
+ *   A toolbar button's light label washes out into the white glass while held (2 → 255) and its
+ *   dark label dips for one frame (188 of 255) at touch-down.
+ *
+ * Shape (native-contact-catalog, iPad, Oct 13; single captures, optical envelopes):
+ * - Growth depends on shape through the width: one uniform scale 1 + growthPt / width. Circle
+ *   composer + 46 pt: native rim ×1.39, this law ×1.35. Capsule "Actions" 82 pt: native ×1.21
+ *   wide, this law ×1.20.
+ * - Follow does not depend on shape. The circle + holds within ~1.5 pt of its place over a 60 pt
+ *   drag. The capsule's "+31 pt" track in that catalog is the page, not the button: the untouched
+ *   "Separate" button beside it moves the same +29 / −17 pt in the same frames (the native back
+ *   swipe, started by the right-drag). Relative to the page the capsule stays put.
+ * - Release: circle k 337 c 11.1, capsule k 384 c 12.2, prominent k 373 c 13.7 (ζ 0.30–0.35),
+ *   inside the fitted INTERACTIVE_GLASS_PRESS release (k 324, c 12.24, ζ 0.34).
+ */
+const BUTTON_FOLLOW = Object.freeze({
+    gainX: 0.01,
+    gainY: 0.01 * (MENU_TRIGGER_FOLLOW.gainY / MENU_TRIGGER_FOLLOW.gainX),
+    rangePt: MENU_TRIGGER_FOLLOW.rangePt,
+    responseMs: MENU_TRIGGER_FOLLOW.responseMs,
+});
+const BUTTON_LIGHT = Object.freeze({
+    kind: 'whole',
+    light: [
+        [0, 0],
+        [17, 0.65],
+        [50, 0.9],
+    ],
+    dark: [
+        [0, 0],
+        [17, 0.07],
+        [50, 0.22],
+        [167, 0.25],
+    ],
+    releaseMs: { light: 500, dark: 240 },
+});
+const BAR_LABEL = Object.freeze({
+    light: [
+        [0, 1],
+        [17, 0.35],
+        [50, 0],
+    ],
+    dark: [
+        [0, 1],
+        [8, 0.7],
+        [50, 1],
+    ],
+});
+const POSE_LIMITS = { maxOffset: 8, maxSizeChange: 12 };
+/** The contact kind of an interactive glass material. */
+export function glassContactKind(material) {
+    return material.press ?? (material.field ? 'field' : 'surface');
+}
+export const GLASS_CONTACT_PHYSICS = {
+    button: {
+        growthPt: 16,
+        follow: BUTTON_FOLLOW,
+        strain: MENU_STRAIN,
+        ...POSE_LIMITS,
+        light: BUTTON_LIGHT,
+        label: { light: 'steady', dark: 'steady' },
+    },
+    bar: {
+        // Toolbar Save: 69 x 44 → 85 x 54 pt held.
+        growthPt: 16,
+        follow: BUTTON_FOLLOW,
+        strain: MENU_STRAIN,
+        ...POSE_LIMITS,
+        light: BUTTON_LIGHT,
+        label: BAR_LABEL,
+    },
+    menu: {
+        // The stock toolbar Menu's 44 pt circle is 48 pt while held (iPhone 17 Pro Max Simulator,
+        // native recording toolbar menu measurements). It trails the finger with the closed Menu
+        // trigger's measured law (measured-reference).
+        growthPt: 4,
+        follow: MENU_TRIGGER_FOLLOW,
+        strain: MENU_STRAIN,
+        ...POSE_LIMITS,
+        light: BUTTON_LIGHT,
+        // A dark trigger keeps its light glyph at full strength (the ellipsis reads 253 of 255 on
+        // its held glass); a light one washes out like a toolbar button's.
+        label: { light: BAR_LABEL.light, dark: 'steady' },
+    },
+    field: {
+        // Native glass TextField (iPad, iPadOS 27, native-contact-catalog): held, the field is 8 pt
+        // wider in two captures by two methods: `glass-field` envelope 609 → 616-618 pt over four
+        // holds, `glass-field-quiet` rim 587 → 595 pt (cadence VALID). Twice a card's growth.
+        growthPt: 8,
+        follow: MENU_TRIGGER_FOLLOW,
+        strain: MENU_STRAIN,
+        ...POSE_LIMITS,
+        light: { kind: 'finger', scale: 0.26, floor: 0.033, menuPeak: 0.175 },
+        label: { light: 'steady', dark: 'steady' },
+    },
+    surface: {
+        // A 404 pt card grows to 408-410 pt; a 160 pt circle to 164 pt (Simulator, Sep 25).
+        growthPt: 4,
+        // Native App-defined card (iPad, Oct 12): ~1.5 pt for a 60 pt drag, the trigger's law.
+        follow: MENU_TRIGGER_FOLLOW,
+        strain: MENU_STRAIN,
+        ...POSE_LIMITS,
+        // Native dark card: 46 under the finger and 36 elsewhere while held, over 29 at rest (a
+        // white mix of ~0.075 at the touch and ~0.033 across the shape); the menu field peaks at
+        // ~0.175, so a surface's light is 0.26 of it over a 0.033 floor.
+        light: { kind: 'finger', scale: 0.26, floor: 0.033, menuPeak: 0.175 },
+        label: { light: 'steady', dark: 'steady' },
+    },
+    segmented: {
+        // The search scope bar, pressed anywhere (stock `.searchScopes`, iPhone 17 Pro Max Simulator,
+        // iOS 27.0, held 1.2 s; measured scope thumb, Oct 13): the 400 pt bar is 416 pt wide and keeps its
+        // 36 pt height, and its labels and pill grow by the same 1.04 about the bar's centre
+        // (webgpu/selectionThumb.ts applies both). The bar holds its place under the finger.
+        growthPt: 16,
+        follow: { ...MENU_TRIGGER_FOLLOW, gainX: 0, gainY: 0 },
+        strain: MENU_STRAIN,
+        ...POSE_LIMITS,
+        // Dark, over 31 at rest: 44 across the bar and 67 at the finger (a white mix of 0.058 and
+        // 0.16), about twice a card's light.
+        light: { kind: 'finger', scale: 0.59, floor: 0.058, menuPeak: 0.175 },
+        label: { light: 'steady', dark: 'steady' },
+    },
+};
+/**
+ * Track thumbs: a Toggle's or a Slider's thumb is a lens on a track. Its finger arrives through
+ * the same GlassContact as every interactive glass (glassContact.ts); its response differs from a
+ * free shape's in ways native shows, so it has its own rows:
+ *
+ * - Follow: the thumb follows the finger 1:1 along its track, clamped to the travel's ends (the
+ *   value moves with it), and never leaves the track. A free shape trails the finger by ~1% of the
+ *   drag (follow gains above). Native catalog `toggle-thumb-quiet` / `slider-thumb-quiet` (iPad,
+ *   cadence VALID): the held lens rides the finger to the ends; across the track it moves ≤1.4 pt.
+ * - Growth: the white thumb lifts into a clear lens after a stationary hold of `activationMs`, or
+ *   as soon as it drags, with the control's own springs (CONTROL_LIFT); a free shape grows at
+ *   touch-down.
+ * - Light: none. The lens is clear; the track shows through it.
+ * - A gesture that claims the touch before the thumb drags (a vertical scroll) cancels it; once it
+ *   drags the thumb keeps the finger (GlassContactOptions.yieldsTo).
+ *
+ * The page owns a thumb's value, so its response model runs in the document (toggleContact.ts,
+ * sliderContact.ts) and the renderer draws the lens it is sent (ControlLens). Values live in
+ * lens/controlLift.ts (CONTROL_LIFT, ControlLiftKind) beside the scope bar's selection lens.
+ */

package/dist/glass/context.d.ts

@@ -0,0 +1,37 @@
+import type { GlassAccessibilityPreferences, GlassCapabilityDecision, GlassRenderTestState } from './capability.js';
+import type { GlassVariant } from './tokens.js';
+export type GlassMaterialDiagnostics = Readonly<{
+    accessibility: GlassAccessibilityPreferences;
+    capability: GlassCapabilityDecision;
+    lensBoost: number;
+    mapRegenerationCount: number;
+    renderTest: GlassRenderTestState;
+}>;
+export type GlassRegionRegistration = Readonly<{
+    element: HTMLElement;
+    id: string;
+    radius: number;
+    variant: GlassVariant;
+}>;
+export type GlassMaterialContextValue = Readonly<{
+    chromeLayer: HTMLElement | null;
+    diagnostics: GlassMaterialDiagnostics;
+    registerRegion: (registration: GlassRegionRegistration) => () => void;
+}>;
+export declare const GlassMaterialContext: import("react").Context<Readonly<{
+    chromeLayer: HTMLElement | null;
+    diagnostics: GlassMaterialDiagnostics;
+    registerRegion: (registration: GlassRegionRegistration) => () => void;
+}> | null>;
+export declare function useGlassMaterialContext(): Readonly<{
+    chromeLayer: HTMLElement | null;
+    diagnostics: GlassMaterialDiagnostics;
+    registerRegion: (registration: GlassRegionRegistration) => () => void;
+}>;
+export declare function useGlassMaterialDiagnostics(): Readonly<{
+    accessibility: GlassAccessibilityPreferences;
+    capability: GlassCapabilityDecision;
+    lensBoost: number;
+    mapRegenerationCount: number;
+    renderTest: GlassRenderTestState;
+}>;

package/dist/glass/context.js

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react';
+export const GlassMaterialContext = createContext(null);
+export function useGlassMaterialContext() {
+    const value = useContext(GlassMaterialContext);
+    if (!value)
+        throw new Error('Glass primitives must be rendered inside SatinRoot.');
+    return value;
+}
+export function useGlassMaterialDiagnostics() {
+    return useGlassMaterialContext().diagnostics;
+}

package/dist/glass/errorAlert.d.ts

@@ -0,0 +1,6 @@
+import { type GlassError } from './errors.js';
+/** One entry per distinct failure: a cause that propagates through several stages
+ * (worker → startup → runtime) is listed once, with every stage it reached. */
+export declare function formatGlassErrors(errors: readonly GlassError[]): string;
+/** Strict builds retain the loud error surface; release apps retain diagnostics only. */
+export declare function installGlassErrorAlert(): void;

package/dist/glass/errorAlert.js

@@ -0,0 +1,57 @@
+import { automaticGlassFallbackAllowed } from './failurePolicy.js';
+import { getGlassErrors, subscribeGlassErrors } from './errors.js';
+let installed = false;
+/** One entry per distinct failure: a cause that propagates through several stages
+ * (worker → startup → runtime) is listed once, with every stage it reached. */
+export function formatGlassErrors(errors) {
+    const cause = (message) => message.replace(/^(Error: )+/, '');
+    const groups = new Map();
+    for (const error of errors) {
+        if (error.transient)
+            continue;
+        const key = JSON.stringify([error.code, cause(error.message), error.reason]);
+        const group = groups.get(key) ?? {
+            code: error.code,
+            message: cause(error.message),
+            reason: error.reason,
+            stages: [],
+        };
+        if (!group.stages.includes(error.stage))
+            group.stages.push(error.stage);
+        groups.set(key, group);
+    }
+    return [...groups.values()]
+        .map(g => `Glass failed — ${g.code} — ${g.stages.join(' → ')}\n${g.message}${g.reason ? '\nReason: ' + g.reason : ''}`)
+        .join('\n\n');
+}
+/** Strict builds retain the loud error surface; release apps retain diagnostics only. */
+export function installGlassErrorAlert() {
+    if (installed || typeof document === 'undefined' || automaticGlassFallbackAllowed())
+        return;
+    installed = true;
+    const paint = () => {
+        const errors = getGlassErrors().filter(error => !error.transient);
+        if (!errors.length)
+            return;
+        if (document.getElementById('satin-launch-error')) {
+            document.querySelector(':root > pre[data-satin-glass-error]')?.remove();
+            return;
+        }
+        // Only this alert (a child of <html>): SatinRoot's launch-failure screen also carries
+        // data-satin-glass-error, and writing textContent there would erase its React tree.
+        let panel = document.querySelector(':root > pre[data-satin-glass-error]');
+        // Loud but never modal: it must not swallow taps on the navigation bar and tabs it
+        // covers, or the only way to keep using the app is to hide it.
+        if (!panel) {
+            panel = document.createElement('pre');
+            panel.dataset.satinGlassError = 'true';
+            panel.setAttribute('role', 'alert');
+            panel.style.cssText =
+                'position:fixed;inset:max(16px,env(safe-area-inset-top)) 16px auto;margin:0;z-index:2147483647;max-height:70%;overflow:auto;padding:16px;background:#380b0b;color:white;white-space:pre-wrap;font:14px/1.5 monospace;pointer-events:none';
+            document.documentElement.append(panel);
+        }
+        panel.textContent = formatGlassErrors(errors);
+    };
+    subscribeGlassErrors(paint);
+    paint();
+}

package/dist/glass/errors.d.ts

@@ -0,0 +1,22 @@
+/** Serializable across the renderer worker boundary. Release failures may select the fallback material. */
+export type GlassErrorCode = 'gpu-unavailable' | 'adapter-unavailable' | 'device-request' | 'context-configure' | 'device-lost' | 'validation' | 'out-of-memory' | 'shader-compilation' | 'worker-startup' | 'readiness-timeout' | 'presentation' | 'unsupported-configuration';
+export type GlassError = Readonly<{
+    code: GlassErrorCode;
+    message: string;
+    stage: string;
+    reason?: string;
+    at: number;
+    /** Null adapters can recover on the next foreground burst; history is diagnostic. */
+    transient?: true;
+    /** The owner still has a bounded recovery attempt in flight. */
+    recovering?: true;
+}>;
+export declare function subscribeGlassFallback(listener: () => void): () => void;
+/** Successful resource reconstruction can retire only an adapter-outage fallback. */
+export declare function setGlassAdapterRecovery(pending: boolean): void;
+export declare function glassFallbackRequired(): boolean;
+export declare function reportGlassError(code: GlassErrorCode, cause: unknown, stage: string, reason?: string, recovery?: {
+    recovering: boolean;
+}): GlassError;
+export declare function subscribeGlassErrors(listener: (error: GlassError) => void): () => void;
+export declare function getGlassErrors(): readonly GlassError[];

package/dist/glass/errors.js

@@ -0,0 +1,78 @@
+import { automaticGlassFallbackAllowed, strictGlassRequested } from './failurePolicy.js';
+import { recordGraphicsEvent } from '../graphicsProbe.js';
+const history = [];
+// Independent of diagnostic history. Only a reconstructed adapter outage can clear fallback.
+let fallbackRequired = false;
+let permanentFallback = false;
+let adapterRecoveryPending = false;
+const fallbackListeners = new Set();
+export function subscribeGlassFallback(listener) {
+    fallbackListeners.add(listener);
+    return () => {
+        fallbackListeners.delete(listener);
+    };
+}
+/** Successful resource reconstruction can retire only an adapter-outage fallback. */
+export function setGlassAdapterRecovery(pending) {
+    adapterRecoveryPending = pending;
+    if (!pending && fallbackRequired && !permanentFallback) {
+        fallbackRequired = false;
+        for (const listener of fallbackListeners)
+            listener();
+    }
+}
+export function glassFallbackRequired() {
+    return fallbackRequired;
+}
+const listeners = new Set();
+export function reportGlassError(code, cause, stage, reason, recovery) {
+    // GPUError objects are not required to inherit from JavaScript Error.
+    const message = cause instanceof Error
+        ? `${cause.name}: ${cause.message}`
+        : cause !== null && typeof cause === 'object' && 'message' in cause
+            ? String(cause.message)
+            : String(cause);
+    const transient = code === 'adapter-unavailable' &&
+        !strictGlassRequested() &&
+        message.includes('navigator.gpu.requestAdapter returned null');
+    const error = {
+        code,
+        message,
+        stage,
+        reason,
+        at: Date.now(),
+        ...(recovery?.recovering ? { recovering: true } : {}),
+        ...(transient ? { transient: true } : {}),
+    };
+    recordGraphicsEvent('glass-error', { ...error });
+    history.push(error);
+    if (history.length > 100)
+        history.shift();
+    const release = automaticGlassFallbackAllowed();
+    if (release && !error.recovering) {
+        if (!adapterRecoveryPending || (code !== 'adapter-unavailable' && code !== 'readiness-timeout'))
+            permanentFallback = true;
+        fallbackRequired = true;
+        for (const listener of fallbackListeners)
+            listener();
+    }
+    // Exhausted null-adapter bursts remain retryable in strict development. Release
+    // apps use CSS now; they must not wait for another foreground event to launch.
+    if (transient && !release)
+        return error;
+    console.error(`[Satin glass: ${code}] ${stage}: ${error.message}`, reason ?? '');
+    if (typeof window !== 'undefined')
+        window.dispatchEvent(new CustomEvent('satin-glass-error', { detail: error }));
+    for (const listener of listeners)
+        listener(error);
+    return error;
+}
+export function subscribeGlassErrors(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+export function getGlassErrors() {
+    return history.slice();
+}

package/dist/glass/failurePolicy.d.ts

@@ -0,0 +1,4 @@
+/** Explicit strict glass always wins, even over an explicit fallback request. */
+export declare function strictGlassRequested(): boolean;
+/** Release apps keep working. Development and test modes never demote implicitly. */
+export declare function automaticGlassFallbackAllowed(): boolean;

package/dist/glass/failurePolicy.js

@@ -0,0 +1,20 @@
+/** Explicit strict glass always wins, even over an explicit fallback request. */
+export function strictGlassRequested() {
+    if (import.meta.env.SATIN_STRICT_GLASS === true || import.meta.env.SATIN_STRICT_GLASS === '1')
+        return true;
+    if (typeof document === 'undefined')
+        return false;
+    const query = new URLSearchParams(window.location.search).get('glass');
+    const attribute = document.documentElement.dataset.satinGlass;
+    return (query === 'strict' ||
+        attribute === 'strict' ||
+        query === 'webgpu' ||
+        (query === null && attribute === 'webgpu'));
+}
+/** Release apps keep working. Development and test modes never demote implicitly. */
+export function automaticGlassFallbackAllowed() {
+    return (import.meta.env.DEV === false &&
+        import.meta.env.MODE !== 'test' &&
+        typeof document !== 'undefined' &&
+        !strictGlassRequested());
+}

package/dist/glass/fallback/material.d.ts

@@ -0,0 +1,16 @@
+import type { SurfaceRenderSpec } from '../renderSpecs.js';
+/** CSS owns backdrop sampling, including video that cannot be read into a GPU texture. */
+export declare class FallbackMaterial {
+    readonly element: HTMLDivElement;
+    private parts;
+    private animations;
+    constructor(host: HTMLElement);
+    private shapes;
+    private frame;
+    private ensure;
+    paint(spec: SurfaceRenderSpec, appearance: 'light' | 'dark'): void;
+    /** A sampled track is submitted once. Width/radius may paint, but never need a JS frame loop. */
+    play(specs: readonly SurfaceRenderSpec[], duration: number, at: number, appearance: 'light' | 'dark'): Promise<void>;
+    private cancel;
+    dispose(): void;
+}

package/dist/glass/fallback/material.js

@@ -0,0 +1,87 @@
+import { animateElement } from '../../motion/animate.js';
+/** CSS owns backdrop sampling, including video that cannot be read into a GPU texture. */
+export class FallbackMaterial {
+    element = document.createElement('div');
+    parts = [];
+    animations = [];
+    constructor(host) {
+        this.element.dataset.satinFallbackMaterial = 'true';
+        this.element.setAttribute('aria-hidden', 'true');
+        this.element.style.cssText =
+            'position:absolute;inset:0;z-index:-1;pointer-events:none;overflow:visible;';
+        host.prepend(this.element);
+    }
+    shapes(spec) {
+        return (spec.shape.members ?? [spec.shape.first, ...(spec.shape.second ? [spec.shape.second] : [])]);
+    }
+    frame(shape, spec) {
+        return {
+            transform: `translate3d(${spec.frameX + shape.centerX - shape.halfWidth}px,${spec.frameY + shape.centerY - shape.halfHeight}px,0)`,
+            width: `${Math.max(0, shape.halfWidth * 2)}px`,
+            height: `${Math.max(0, shape.halfHeight * 2)}px`,
+            borderRadius: `${shape.radius}px ${shape.radius}px ${shape.bottomRadius ?? shape.radius}px ${shape.bottomRadius ?? shape.radius}px`,
+            opacity: spec.restHidden ? 0 : (spec.opacity ?? 1),
+        };
+    }
+    ensure(count, appearance, spec) {
+        while (this.parts.length > count)
+            this.parts.pop().remove();
+        while (this.parts.length < count) {
+            const part = document.createElement('div');
+            part.style.cssText =
+                'position:absolute;left:0;top:0;box-sizing:border-box;pointer-events:none;';
+            this.element.append(part);
+            this.parts.push(part);
+        }
+        const reduced = matchMedia('(prefers-reduced-transparency: reduce)').matches;
+        const dark = appearance === 'dark';
+        const tint = spec.tint;
+        const background = tint
+            ? `rgba(${tint[0] * 255},${tint[1] * 255},${tint[2] * 255},${tint[3]})`
+            : dark
+                ? `rgba(35,35,38,${reduced ? 1 : 0.68})`
+                : `rgba(250,250,252,${reduced ? 1 : 0.58})`;
+        for (const part of this.parts) {
+            part.style.background = background;
+            part.style.backdropFilter = reduced
+                ? 'none'
+                : `blur(${spec.variant === 'clear' ? 4 : 18}px) saturate(1.4)`;
+            part.style.setProperty('-webkit-backdrop-filter', part.style.backdropFilter);
+            part.style.boxShadow = `inset 0 0 0 0.5px rgba(255,255,255,${dark ? 0.25 : 0.7}),0 2px 10px rgba(0,0,0,0.08)`;
+        }
+    }
+    paint(spec, appearance) {
+        this.cancel();
+        const shapes = this.shapes(spec);
+        this.ensure(shapes.length, appearance, spec);
+        shapes.forEach((shape, index) => Object.assign(this.parts[index].style, this.frame(shape, spec)));
+    }
+    /** A sampled track is submitted once. Width/radius may paint, but never need a JS frame loop. */
+    play(specs, duration, at, appearance) {
+        this.paint(specs[specs.length - 1], appearance);
+        const count = Math.max(...specs.map(spec => this.shapes(spec).length));
+        this.ensure(count, appearance, specs[specs.length - 1]);
+        this.parts.forEach((part, index) => {
+            const frames = specs.map((spec, sample) => {
+                const shape = this.shapes(spec)[index];
+                return {
+                    offset: sample / (specs.length - 1),
+                    ...(shape ? this.frame(shape, spec) : { opacity: 0 }),
+                };
+            });
+            const animation = animateElement(part, frames, { duration, easing: 'linear', fill: 'both' });
+            animation.startTime = at;
+            this.animations.push(animation);
+        });
+        return Promise.all(this.animations.map(animation => animation.finished)).then(() => { }, () => { });
+    }
+    cancel() {
+        for (const animation of this.animations)
+            animation.cancel();
+        this.animations = [];
+    }
+    dispose() {
+        this.cancel();
+        this.element.remove();
+    }
+}

package/dist/glass/fallback/regions.d.ts

@@ -0,0 +1,16 @@
+import type { GlassRegionRegistry } from '../regionRegistry.js';
+/** Registered DOM owners already follow scroll, sheets and navigation on the compositor. */
+export declare class FallbackRegions {
+    private entries;
+    private unsubscribe;
+    private frame;
+    private commitFrame;
+    private disposed;
+    private registry;
+    private appearance;
+    constructor(registry: GlassRegionRegistry | undefined, appearance: 'light' | 'dark');
+    private schedule;
+    setAppearance(appearance: 'light' | 'dark'): void;
+    refresh(): void;
+    dispose(): void;
+}