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

package/dist/app/mediaCheck.js

@@ -0,0 +1,122 @@
+import { mediaTypes } from './mediaTypes.js';
+/** CLI full-deployment check; not embedded into the lightweight install page. */
+export async function checkMediaDeployment(inventory, entries, pageUrl, timeoutMs, base) {
+    const page = new URL(pageUrl);
+    const mime = (url) => mediaTypes['.' + new URL(url, page).pathname.split('.').at(-1).toLowerCase()];
+    const entry = entries.find(entry => mime(entry.url));
+    let probe = inventory.mediaProbe;
+    const failures = [];
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let url = page.href;
+    // Bound retained bytes, cancel ignored-range bodies without downloading them.
+    const prefix = async (response, exact) => {
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new Error('missing range body');
+        const bytes = [];
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (exact && bytes.length + value.length > 2)
+                    throw new Error('range body exceeds two bytes');
+                bytes.push(...value.subarray(0, 2 - bytes.length));
+                if (!exact && bytes.length === 2)
+                    break;
+            }
+        }
+        finally {
+            await reader.cancel();
+            reader.releaseLock();
+        }
+        if (bytes.length !== 2)
+            throw new Error('media probe needs two bytes');
+        return bytes.map(value => value.toString(16).padStart(2, '0')).join('');
+    };
+    const request = (url, range = false) => fetch(url, {
+        headers: { 'Accept-Encoding': 'identity', ...(range ? { Range: 'bytes=0-1' } : {}) },
+        signal: controller.signal,
+        cache: 'no-store',
+        redirect: 'manual',
+    });
+    try {
+        // Legacy precache metadata lacks a prefix. Read two ordinary GET bytes,
+        // then compare the range response; the existing precache check verifies the full asset.
+        if (probe === undefined && entry) {
+            url = new URL(entry.url, page).href;
+            const response = await request(url);
+            try {
+                if (response.status !== 200 || (response.url && response.url !== url))
+                    throw new Error('invalid legacy media response');
+                const length = entry.bytes ?? Number(response.headers.get('content-length'));
+                probe = {
+                    url: entry.url,
+                    bytes: length,
+                    prefix: await prefix(response, false),
+                    type: mime(entry.url),
+                };
+            }
+            finally {
+                await response.body?.cancel().catch(() => { });
+            }
+        }
+        if (probe == null)
+            return { applicable: false, failures };
+        const target = new URL(probe.url, page);
+        // The inventory is deployment data, never authority to request another origin.
+        if (typeof probe.url !== 'string' ||
+            !probe.url.startsWith(base) ||
+            !target.pathname.startsWith(base) ||
+            target.origin !== page.origin ||
+            target.search ||
+            target.hash ||
+            target.username ||
+            target.password ||
+            !Number.isSafeInteger(probe.bytes) ||
+            probe.bytes < 2 ||
+            !/^[a-f0-9]{4}$/.test(probe.prefix) ||
+            mime(probe.url) !== probe.type)
+            throw new Error('invalid media probe metadata');
+        url = target.href;
+        const response = await request(url, true);
+        try {
+            if (response.status !== 206)
+                throw new Error(`expected HTTP 206, received HTTP ${response.status}`);
+            if (response.url && response.url !== url)
+                throw new Error('unexpected final URL');
+            const type = (response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+            const encoding = response.headers.get('content-encoding');
+            if (response.headers.get('content-range') !== `bytes 0-1/${probe.bytes}` ||
+                response.headers.get('content-length') !== '2' ||
+                type !== probe.type ||
+                (encoding && encoding !== 'identity'))
+                throw new Error('incorrect range, length, MIME or encoding headers');
+            if ((await prefix(response, true)) !== probe.prefix)
+                throw new Error('range body differs from the built probe bytes');
+        }
+        finally {
+            await response.body?.cancel().catch(() => { });
+        }
+    }
+    catch (error) {
+        const reason = controller.signal.aborted
+            ? 'request timed out'
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        failures.push({
+            reason: `Media byte-range check failed: ${reason}`,
+            url,
+            check: 'Media transport',
+            status: reason,
+            transient: controller.signal.aborted,
+            fix: 'Serve this media file with single byte ranges and its audio/video MIME type. Rebuild if its bytes changed.',
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return { applicable: true, failures };
+}

package/dist/app/mediaTypes.d.ts

@@ -0,0 +1,2 @@
+/** Container MIME types, not a promise of installed WebKit codec support. */
+export declare const mediaTypes: Readonly<Record<string, string>>;

package/dist/app/mediaTypes.js

@@ -0,0 +1,13 @@
+/** Container MIME types, not a promise of installed WebKit codec support. */
+export const mediaTypes = {
+    '.m4a': 'audio/mp4',
+    '.mp3': 'audio/mpeg',
+    '.aac': 'audio/aac',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.opus': 'audio/ogg',
+    '.mp4': 'video/mp4',
+    '.m4v': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.webm': 'video/webm',
+};

package/dist/app/platformPolicy.d.ts

@@ -0,0 +1,3 @@
+import type { AppDefinition } from './definition.js';
+/** Device support and installed-app admission are separate decisions. No URL can override them. */
+export declare function resolvePlatformGate(platforms: AppDefinition['platforms'], iosWebKit: boolean, standalone: boolean, updateProfile: AppDefinition['updateProfile'], devServer: boolean): 'run' | 'install' | 'unsupported';

package/dist/app/platformPolicy.js

@@ -0,0 +1,10 @@
+/** Device support and installed-app admission are separate decisions. No URL can override them. */
+export function resolvePlatformGate(platforms, iosWebKit, standalone, updateProfile, devServer) {
+    if (platforms === 'all')
+        return 'run';
+    if (!iosWebKit)
+        return 'unsupported';
+    if (standalone || devServer || updateProfile === 'preview')
+        return 'run';
+    return 'install';
+}

package/dist/app/platformScripts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A redirect cannot cancel deferred modules. Convert executable app scripts
+ * after Vite has emitted its entry tags, so even their imports wait for the gate.
+ * Preloads can still fetch bytes, but no app module evaluates on a blocked page.
+ */
+export declare function gateAppScripts(html: string): string;

package/dist/app/platformScripts.js

@@ -0,0 +1,65 @@
+function scriptAttributes(source) {
+    const attributes = new Map();
+    const pattern = /([^\s=/>]+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s"'=<>`]+))?/g;
+    for (const match of source.matchAll(pattern)) {
+        const name = match[1].toLowerCase();
+        const quotedValue = match[2] ?? '';
+        const value = /^["']/.test(quotedValue) ? quotedValue.slice(1, -1) : quotedValue;
+        if (!attributes.has(name))
+            attributes.set(name, { value, original: match[0] });
+    }
+    return attributes;
+}
+/**
+ * A redirect cannot cancel deferred modules. Convert executable app scripts
+ * after Vite has emitted its entry tags, so even their imports wait for the gate.
+ * Preloads can still fetch bytes, but no app module evaluates on a blocked page.
+ */
+export function gateAppScripts(html) {
+    if (!html.includes('id="satin-platform-gate"'))
+        return html;
+    const scriptPattern = /<!--[\s\S]*?-->|<script\b((?:[^>"']|"[^"]*"|'[^']*')*)>([\s\S]*?)<\/script\s*>/gi;
+    const scripts = [...html.matchAll(scriptPattern)].filter(match => match[1] !== undefined);
+    const gate = scripts.find(match => scriptAttributes(match[1]).get('id')?.value === 'satin-platform-gate');
+    const firstScript = scripts[0];
+    // Vite and React prepend development scripts after Satin's pre hook.
+    // Move only DOM-free admission before parser loaders. Head initialization
+    // remains after the metadata and links it reads.
+    if (gate && firstScript && firstScript.index < gate.index) {
+        html =
+            html.slice(0, firstScript.index) +
+                gate[0] +
+                html.slice(firstScript.index, gate.index) +
+                html.slice(gate.index + gate[0].length);
+    }
+    return html.replace(scriptPattern, (original, attributes) => {
+        if (attributes === undefined)
+            return original;
+        // Parse whole values so neither data-id nor quoted text can impersonate
+        // a framework ID. CSP plugins may place a nonce before the actual ID.
+        const parsedAttributes = scriptAttributes(attributes);
+        const id = parsedAttributes.get('id')?.value;
+        if (id === 'satin-platform-gate' ||
+            id === 'satin-head-init' ||
+            id === 'satin-launch-cover' ||
+            (id === 'satin-deployment' && parsedAttributes.get('type')?.value === 'application/json')) {
+            return original;
+        }
+        // Wrap all other script types, including data and import maps. Reinserting
+        // their original tags preserves browser parsing without guessing which
+        // encoded type attributes the engine would treat as executable.
+        const script = JSON.stringify(original).replaceAll('<', '\\u003c');
+        const nonce = parsedAttributes.get('nonce')?.original ?? '';
+        // These loaders are synchronous parser scripts. Reinsert allowed scripts
+        // into that parser so modules/defer still precede DOMContentLoaded and
+        // classic scripts retain their original ordering and attributes.
+        return `<script ${nonce} data-satin-script-loader>if (window.__SATIN_PLATFORM_BLOCKED__ === false) {
+      const script = ${script};
+      const nonce = document.currentScript && document.currentScript.nonce;
+      // Vite injects html.cspNonce after this transform. Read the final wrapper
+      // nonce at execution time and give it to the script the parser receives.
+      document.write(nonce ? script.replace(/^<script\\b/i,
+        '<script nonce="' + nonce.replace(/&/g, '&amp;').replace(/"/g, '&quot;') + '"') : script);
+    }</script>`;
+    });
+}

package/dist/app/releaseUpdates.d.ts

@@ -0,0 +1,7 @@
+/** Once launch reveals the app, only suspension may replace its document.
+ * A late download stays ready for that boundary instead of flashing visible
+ * content back to the launch cover, even before the user's first input. */
+export declare function watchReleaseUpdates(scope: string, canApply: () => boolean): {
+    attempt: () => void;
+    dispose(): void;
+};

package/dist/app/releaseUpdates.js

@@ -0,0 +1,53 @@
+import { watchBackgroundUpdates } from './backgroundUpdate.js';
+import { prepareColdLaunchUpdate } from './coldLaunchUpdate.js';
+/** Once launch reveals the app, only suspension may replace its document.
+ * A late download stays ready for that boundary instead of flashing visible
+ * content back to the launch cover, even before the user's first input. */
+export function watchReleaseUpdates(scope, canApply) {
+    let disposed = false;
+    let checking = false;
+    let hidden = document.hidden;
+    let boundary = 0;
+    let retryBoundary = false;
+    const attempt = () => {
+        if (disposed || checking || !document.hidden || !canApply())
+            return;
+        const startedAt = boundary;
+        const safe = () => !disposed && startedAt === boundary && document.hidden && canApply();
+        checking = true;
+        void prepareColdLaunchUpdate(scope, () => { }, {
+            background: true,
+            canActivate: safe,
+        }).finally(() => {
+            checking = false;
+            // A claim/check from the previous boundary may finish after visibility
+            // changes. Retry that new boundary once, never loop on a denied worker.
+            if (retryBoundary) {
+                retryBoundary = false;
+                attempt();
+            }
+        });
+    };
+    const visibilityChanged = () => {
+        if (hidden !== document.hidden) {
+            hidden = document.hidden;
+            boundary++;
+            if (checking)
+                retryBoundary = true;
+        }
+        attempt();
+    };
+    document.addEventListener('visibilitychange', visibilityChanged);
+    window.addEventListener('pagehide', visibilityChanged);
+    const stopChecks = watchBackgroundUpdates(scope, attempt);
+    attempt();
+    return {
+        attempt,
+        dispose() {
+            disposed = true;
+            stopChecks();
+            document.removeEventListener('visibilitychange', visibilityChanged);
+            window.removeEventListener('pagehide', visibilityChanged);
+        },
+    };
+}

package/dist/app/runtime.d.ts

@@ -0,0 +1,9 @@
+import { type AppDefinition } from './definition.js';
+declare global {
+    interface Window {
+        __SATIN_DEFINITION__?: AppDefinition;
+    }
+}
+export declare function getBuiltApp(): AppDefinition | undefined;
+export declare function useAppBackground(app: AppDefinition | undefined, legacy: string | undefined): string;
+export declare function registerDefinedAppShell(app: AppDefinition): Promise<import('../sw/registerAppShell.js').SatinAppShellRegistration | null>;

package/dist/app/runtime.js

@@ -0,0 +1,38 @@
+import { useDarkAppearance } from './appearance.js';
+import { defineSatinApp } from './definition.js';
+import { registerAppShell } from '../sw/registerAppShell.js';
+let source;
+let validated;
+export function getBuiltApp() {
+    const next = window.__SATIN_DEFINITION__;
+    if (next !== source) {
+        source = next;
+        validated = next ? defineSatinApp(next) : undefined;
+    }
+    return validated;
+}
+export function useAppBackground(app, legacy) {
+    const dark = useDarkAppearance();
+    if (app && legacy !== undefined)
+        throw new Error('SatinRoot background is owned by the app definition; remove background.');
+    return app
+        ? dark && app.appearance.darkLaunch !== 'match-light'
+            ? app.appearance.darkLaunch.background
+            : app.appearance.background
+        : (legacy ?? '#ffffff');
+}
+let shell;
+export function registerDefinedAppShell(app) {
+    shell ??= registerAppShell({
+        updateProfile: app.updateProfile ?? 'release',
+        updateActivation: import.meta.env.SATIN_DEV_MENU
+            ? 'cold-launch-or-explicit'
+            : app.updateActivation,
+        scope: app.scope,
+        serviceWorkerUrl: `${app.scope}sw.js`,
+    }).catch(error => {
+        shell = undefined;
+        throw error;
+    });
+    return shell;
+}

package/dist/app/startup.d.ts

@@ -0,0 +1,30 @@
+/** Calibrated acceptance devices, in portrait CSS screen coordinates. */
+export declare const STARTUP_SCREENS: readonly [{
+    readonly width: 402;
+    readonly height: 874;
+    readonly ratio: 3;
+}, {
+    readonly width: 440;
+    readonly height: 956;
+    readonly ratio: 3;
+}, {
+    readonly width: 1024;
+    readonly height: 1366;
+    readonly ratio: 2;
+}, {
+    readonly width: 1032;
+    readonly height: 1376;
+    readonly ratio: 2;
+}];
+export declare function startupImages(stem: string, light: string, dark: string, screens?: readonly {
+    width: number;
+    height: number;
+    ratio: number;
+}[]): {
+    file: string;
+    media: string;
+    width: number;
+    height: number;
+    ratio: number;
+    color: string | null;
+}[];

package/dist/app/startup.js

@@ -0,0 +1,24 @@
+/** Calibrated acceptance devices, in portrait CSS screen coordinates. */
+export const STARTUP_SCREENS = [
+    { width: 402, height: 874, ratio: 3 },
+    { width: 440, height: 956, ratio: 3 },
+    { width: 1024, height: 1366, ratio: 2 },
+    { width: 1032, height: 1376, ratio: 2 },
+];
+export function startupImages(stem, light, dark, screens = STARTUP_SCREENS) {
+    // WebClips cache one startup bitmap at installation. Distinct palettes use
+    // an icon on transparent pixels so the native cover can supply its current
+    // system background. Identical palettes can safely bake in their color.
+    return screens.flatMap(screen => ['portrait', 'landscape'].flatMap(orientation => [false, true].map(isDark => {
+        const width = (orientation === 'portrait' ? screen.width : screen.height) * screen.ratio;
+        const height = (orientation === 'portrait' ? screen.height : screen.width) * screen.ratio;
+        return {
+            file: `${stem}-launch-${screen.width}-${orientation}-${isDark ? 'dark' : 'light'}.png`,
+            media: `(device-width: ${screen.width}px) and (device-height: ${screen.height}px) and (-webkit-device-pixel-ratio: ${screen.ratio}) and (orientation: ${orientation}) and (prefers-color-scheme: ${isDark ? 'dark' : 'light'})`,
+            width,
+            height,
+            ratio: screen.ratio,
+            color: light === dark ? light : null,
+        };
+    })));
+}

package/dist/app/statusBand.d.ts

@@ -0,0 +1,11 @@
+/** Fitted viewports cannot paint the clock band. Supply WebKit's under-page
+ * colour from visible screen backgrounds; no second navigation clock or spring. */
+type RGB = readonly [number, number, number];
+export type BandPlane = {
+    left: number;
+    right: number;
+    color: RGB;
+};
+export declare function blendBand(width: number, base: RGB, planes: readonly BandPlane[]): RGB;
+export declare function installStatusBand(root: HTMLElement): () => void;
+export {};

package/dist/app/statusBand.js

@@ -0,0 +1,257 @@
+export function blendBand(width, base, planes) {
+    if (width <= 0)
+        return base;
+    const edges = [
+        ...new Set([
+            0,
+            width,
+            ...planes.flatMap(p => [
+                Math.max(0, Math.min(width, p.left)),
+                Math.max(0, Math.min(width, p.right)),
+            ]),
+        ]),
+    ].sort((a, b) => a - b);
+    const result = [0, 0, 0];
+    for (let i = 1; i < edges.length; i++) {
+        const left = edges[i - 1], right = edges[i], x = (left + right) / 2;
+        const color = planes.findLast(p => p.left <= x && p.right > x)?.color ?? base;
+        for (let c = 0; c < 3; c++)
+            result[c] += (color[c] * (right - left)) / width;
+    }
+    return result;
+}
+function rgba(value) {
+    const match = value.match(/^rgba?\(([^)]+)\)$/);
+    if (!match)
+        return [0, 0, 0, 0];
+    const values = match[1]
+        .split(/[\s,/]+/)
+        .filter(Boolean)
+        .map(Number);
+    return [values[0], values[1], values[2], values[3] ?? 1];
+}
+function background(element, root, base) {
+    const layers = [];
+    for (let node = element; node && node !== root; node = node.parentElement)
+        layers.push(rgba(getComputedStyle(node).backgroundColor));
+    let color = base;
+    for (const [r, g, b, a] of layers.reverse())
+        color = [r * a + color[0] * (1 - a), g * a + color[1] * (1 - a), b * a + color[2] * (1 - a)];
+    return color;
+}
+/** Elements whose own style or attributes decide a screen's resting band colour. Anything else
+ * (glass canvases, tab ink, row swipes, menus, dialogs) mutates at animation rates and never
+ * changes the band, so it does not trigger a read pass. */
+const BAND_INPUTS = '[data-satin-screen-container], [data-satin-navigation-motion-layer], [data-satin-navigation-dim], [data-satin-scroll], [data-satin-scroll-edge], [data-satin-navigator-host], [data-satin-tab-active], [data-satin-root], [data-satin-status-band-source]';
+export function installStatusBand(root) {
+    let frame = 0, disposed = false, moving = false;
+    const html = document.documentElement;
+    const previous = html.style.getPropertyValue('--satin-status-band');
+    // Resolves the accepted app appearance without reading our own output colour.
+    const probe = document.createElement('span');
+    probe.hidden = true;
+    probe.style.backgroundColor = 'var(--satin-background)';
+    root.append(probe);
+    // Resting fills (ancestor background walks) are cached until an input changes; scroll frames
+    // and navigation frames only read geometry, the dim and the scroll edge.
+    let fills = new WeakMap(), scrolled = new WeakMap();
+    let base;
+    // During a transition the band is written straight to its consumers' background-color: the
+    // inherited root custom property restyled the whole document on every frame.
+    const consumers = () => [
+        html,
+        document.body,
+        root,
+        ...root.querySelectorAll('[data-satin-status-band-source="scene"]'),
+        ...root.querySelectorAll('[data-satin-scroll-edge-cap]'),
+    ];
+    // The app's own inline background on a consumer is saved on the first direct write and put
+    // back when the motion ends (never wiped).
+    const saved = new Map();
+    const writeDirect = (value) => {
+        for (const element of consumers()) {
+            if (!saved.has(element))
+                saved.set(element, {
+                    value: element.style.getPropertyValue('background-color'),
+                    priority: element.style.getPropertyPriority('background-color'),
+                });
+            if (element.style.getPropertyValue('background-color') !== value ||
+                element.style.getPropertyPriority('background-color') !== 'important')
+                element.style.setProperty('background-color', value, 'important');
+        }
+    };
+    const clearDirect = () => {
+        for (const [element, { value, priority }] of saved) {
+            if (value)
+                element.style.setProperty('background-color', value, priority);
+            else
+                element.style.removeProperty('background-color');
+        }
+        saved.clear();
+    };
+    const invalidate = () => {
+        fills = new WeakMap();
+        scrolled = new WeakMap();
+        base = undefined;
+    };
+    const paint = () => {
+        frame = 0;
+        if (disposed || document.hidden)
+            return;
+        const fitted = html.dataset.satinViewportFit === 'auto' || html.dataset.satinViewportFit === 'contain';
+        if (!fitted) {
+            clearDirect();
+            html.style.removeProperty('--satin-status-band');
+            return;
+        }
+        if (!base) {
+            const [r, g, b, alpha] = rgba(getComputedStyle(probe).backgroundColor);
+            // An unresolved appearance token is not black. Keep the CSS launch/app
+            // background until the observed root/appearance update supplies a colour.
+            if (alpha !== 1 || ![r, g, b].every(Number.isFinite))
+                return;
+            base = [r, g, b];
+        }
+        const planes = [];
+        let inMotion = false;
+        for (const screen of root.querySelectorAll('[data-satin-screen-container]')) {
+            if (screen.closest('[hidden], [data-satin-tab-active="false"], dialog') ||
+                screen.dataset.satinRenderSuspended === 'true')
+                continue;
+            const motion = screen.querySelector(':scope > [data-satin-navigation-motion-layer]');
+            if (!motion)
+                continue;
+            const transition = screen.dataset.satinTransition ?? 'settled';
+            if (transition === 'settled') {
+                const style = getComputedStyle(screen);
+                if (style.display === 'none' || style.visibility === 'hidden')
+                    continue;
+            }
+            const rect = motion.getBoundingClientRect();
+            if (rect.width <= 0 || rect.bottom <= 0 || rect.top > 1)
+                continue;
+            inMotion ||= transition !== 'settled';
+            let color = fills.get(motion);
+            if (!color) {
+                // Only a screen's own top-reaching primary scroller supplies its fill.
+                const scroll = [
+                    ...motion.querySelectorAll('[data-satin-scroll][data-satin-primary="true"]'),
+                ].find(node => node.closest('[data-satin-screen-container]') === screen &&
+                    node.getBoundingClientRect().top <= 1);
+                color = background(scroll ?? motion, root, base);
+                fills.set(motion, color);
+                scrolled.set(motion, Boolean(scroll));
+            }
+            // Reuse the measured edge's current tint/strength. This is an average
+            // resting-background approximation; it cannot sample blurred row pixels.
+            const host = screen.closest('[data-satin-navigator-host]');
+            const edgeHost = [
+                ...(host?.querySelectorAll('[data-satin-navigation-edge-host]') ?? []),
+            ].find(node => node.closest('[data-satin-navigator-host]') === host &&
+                node.dataset.satinPane === screen.dataset.satinPane);
+            const edge = scrolled.get(motion)
+                ? edgeHost?.querySelector('[data-satin-scroll-edge]')
+                : undefined;
+            if (edge?.dataset.satinScrollEdgeVisible === 'true') {
+                const edgeStyle = getComputedStyle(edge);
+                const [er, eg, eb, alpha] = rgba(edgeStyle.backgroundColor);
+                const amount = alpha * Number(edgeStyle.opacity);
+                color = [
+                    er * amount + color[0] * (1 - amount),
+                    eg * amount + color[1] * (1 - amount),
+                    eb * amount + color[2] * (1 - amount),
+                ];
+            }
+            const dim = motion.querySelector(':scope > [data-satin-navigation-dim]');
+            const opacity = dim ? Number(getComputedStyle(dim).opacity) : 0;
+            color = [color[0] * (1 - opacity), color[1] * (1 - opacity), color[2] * (1 - opacity)];
+            planes.push({ left: rect.left, right: rect.right, color });
+        }
+        const color = blendBand(window.innerWidth, base, planes);
+        const value = `rgb(${color.map(v => Math.round(v)).join(' ')})`;
+        if (inMotion)
+            writeDirect(value);
+        else {
+            // At rest the published custom property is the band (identical resting colours).
+            if (html.style.getPropertyValue('--satin-status-band') !== value)
+                html.style.setProperty('--satin-status-band', value);
+            clearDirect();
+        }
+        if (inMotion)
+            frame = requestAnimationFrame(paint);
+        // Motion ended: refresh every resting fill once (inputs changed during the transition were
+        // not re-read per frame).
+        else if (moving) {
+            invalidate();
+            frame = requestAnimationFrame(paint);
+        }
+        moving = inMotion;
+    };
+    const schedule = () => {
+        if (!frame && !disposed)
+            frame = requestAnimationFrame(paint);
+    };
+    const changed = () => {
+        invalidate();
+        schedule();
+    };
+    // While a transition runs its own writes (screen, motion and dim styles) change nothing but the
+    // geometry read every frame; fills are refreshed when it settles.
+    const observer = new MutationObserver(records => {
+        if (moving)
+            return;
+        if (records.some(record => record.type === 'childList' ||
+            record.target === root ||
+            (record.target instanceof Element &&
+                (record.target.matches(BAND_INPUTS) ||
+                    // An ancestor of a screen or of its primary scroller: its class or style can change the
+                    // backgrounds a cached fill composited.
+                    record.target.querySelector(':scope [data-satin-screen-container], :scope [data-satin-scroll][data-satin-primary="true"]')))))
+            changed();
+    });
+    observer.observe(root, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: [
+            'style',
+            'class',
+            'hidden',
+            'data-satin-transition',
+            'data-satin-render-suspended',
+            'data-satin-covered',
+            'data-satin-tab-active',
+            'data-satin-scroll-edge-visible',
+        ],
+    });
+    const appearance = new MutationObserver(changed);
+    appearance.observe(html, {
+        attributes: true,
+        attributeFilter: ['data-satin-appearance', 'data-satin-viewport-fit', 'class'],
+    });
+    // Document ancestors of the root (body and anything between): class changes restyle the fills.
+    for (let node = root.parentElement; node && node !== html; node = node.parentElement)
+        appearance.observe(node, { attributes: true, attributeFilter: ['class'] });
+    window.addEventListener('resize', changed);
+    window.addEventListener('pageshow', changed);
+    document.addEventListener('visibilitychange', changed);
+    // Scrolling moves a scroller under the edge: geometry and edge strength only, fills stay cached.
+    root.addEventListener('scroll', schedule, true);
+    paint();
+    return () => {
+        disposed = true;
+        cancelAnimationFrame(frame);
+        observer.disconnect();
+        appearance.disconnect();
+        window.removeEventListener('pageshow', changed);
+        window.removeEventListener('resize', changed);
+        document.removeEventListener('visibilitychange', changed);
+        root.removeEventListener('scroll', schedule, true);
+        probe.remove();
+        clearDirect();
+        if (previous)
+            html.style.setProperty('--satin-status-band', previous);
+        else
+            html.style.removeProperty('--satin-status-band');
+    };
+}