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

package/dist/app/launch.js

@@ -0,0 +1,241 @@
+import { prepareDestinationImages } from '../image/resource.js';
+/** Resolves only after the worker has atomically installed the complete bundle.
+ * An existing active worker is sufficient offline; never await an update fetch. */
+export async function prepareOfflineBundle(scope, timeoutMs = 20_000, onProgress) {
+    const online = navigator.onLine;
+    if (!('serviceWorker' in navigator)) {
+        if (online === false)
+            throw new Error('Connect to open this app. Offline installation is unavailable in this browser.');
+        performance.mark('satin-connected-only-launch');
+        console.info('Satin: service workers are unavailable; launching connected-only. Offline launch is not available on this origin.');
+        performance.mark('satin-launch-connected-only');
+        return true;
+    }
+    const { existing, expectedScript } = await findOwnRegistration(scope);
+    // Updates are optional. The worker activates a completed replacement after
+    // all clients close; the next process launch then receives that bundle.
+    if (existing?.active?.state === 'activated') {
+        performance.mark('satin-worker-active');
+        return true;
+    }
+    // WebKit can expose the registration before its first worker is assigned.
+    // Re-registering joins that job; update() requires a newest worker and throws
+    // InvalidStateError in this interval. It also retries an empty failed install.
+    let registration = existing;
+    if (!registration) {
+        try {
+            registration = await navigator.serviceWorker.register(`${scope}sw.js`, {
+                scope,
+                updateViaCache: 'none',
+            });
+        }
+        catch (error) {
+            if (navigator.onLine === false) {
+                throw new Error('Check your connection and try again. Resource: ' + expectedScript, {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    }
+    if (registration.active?.state === 'activated') {
+        performance.mark('satin-worker-active');
+        return true;
+    }
+    // Do not await this job: on WebKit it may resolve only after installation.
+    // Attach the progress and updatefound listeners while the bytes are arriving.
+    const registrationJob = existing && !existing.installing && !existing.waiting && !existing.active
+        ? navigator.serviceWorker.register(`${scope}sw.js`, { scope, updateViaCache: 'none' })
+        : null;
+    await waitForActivation(registration, registrationJob, timeoutMs, onProgress);
+    performance.mark('satin-worker-active');
+    return true;
+}
+/** The scope's registration, when its worker is this app's script. Finishes a worker reset the
+ * document head started first, and gives the lookup 3 s. */
+async function findOwnRegistration(scope) {
+    // The head may be replacing an interrupted first install. Finish that lookup
+    // before subscribing, or this page could keep watching the discarded worker.
+    const workerJob = globalThis
+        .__SATIN_WORKER_LOOKUP__;
+    if (workerJob)
+        await workerJob;
+    const lookupError = globalThis
+        .__SATIN_WORKER_LOOKUP_ERROR__;
+    if (lookupError)
+        throw lookupError;
+    performance.mark('satin-worker-lookup-start');
+    let lookupTimer;
+    let found;
+    try {
+        found = await Promise.race([
+            navigator.serviceWorker.getRegistration(scope),
+            new Promise((_resolve, reject) => {
+                lookupTimer = setTimeout(() => reject(new Error('Service worker reset did not finish. Please retry.')), 3000);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(lookupTimer);
+    }
+    const expectedScope = new URL(scope, location.href).href;
+    const expectedScript = new URL(scope + 'sw.js', location.href).href;
+    const newest = found?.installing ?? found?.waiting ?? found?.active;
+    const existing = found &&
+        (!found.scope || found.scope === expectedScope) &&
+        (!newest?.scriptURL || newest.scriptURL === expectedScript)
+        ? found
+        : undefined;
+    performance.mark('satin-worker-lookup-end');
+    return { existing, expectedScript };
+}
+/** The worker's install failure as a message the launch screen can show. */
+function installFailureMessage(failure) {
+    if (failure.stalled)
+        return 'The server stopped responding. Resource: ' + failure.url + '. Please retry.';
+    if (failure.networkFailure)
+        return 'Check your connection and try again. Resource: ' + failure.url;
+    return ('Could not prepare ' +
+        failure.url +
+        ': ' +
+        failure.reason +
+        '. Deploy the complete matching build, then retry.');
+}
+/** Resolves once the registration's worker is activated. Download progress (forwarded to
+ * `onProgress`) extends the deadline; an install failure or a stall past `timeoutMs` rejects. */
+function waitForActivation(registration, registrationJob, timeoutMs, onProgress) {
+    return new Promise((resolve, reject) => {
+        let lastLoaded = 0;
+        let lastActivity = 0;
+        let timer;
+        let redundantTimer;
+        const deadline = () => {
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                cleanup();
+                reject(new Error('Offline installation timed out without download progress. Retry with a connection.'));
+            }, timeoutMs);
+        };
+        const receive = (event) => {
+            if (!watched.has(event.source))
+                return;
+            const data = event.data;
+            if (data?.type === 'SATIN_INSTALL_FAILURE') {
+                cleanup();
+                reject(new Error(installFailureMessage(data)));
+                return;
+            }
+            if (data?.type === 'SATIN_DOWNLOAD_PROGRESS' &&
+                Number.isFinite(data.loaded) &&
+                Number.isFinite(data.total)) {
+                if (data.downloading && (data.loaded > lastLoaded || (data.activity ?? 0) > lastActivity)) {
+                    lastLoaded = data.loaded;
+                    lastActivity = data.activity ?? 0;
+                    deadline();
+                }
+                onProgress?.(data.downloading ? data : null);
+            }
+        };
+        navigator.serviceWorker.addEventListener?.('message', receive);
+        // Worker messages are queued until DOMContentLoaded unless the queue is opened (see the head watchdog).
+        navigator.serviceWorker.startMessages?.();
+        const watched = new Set();
+        const cleanup = () => {
+            clearTimeout(timer);
+            clearTimeout(redundantTimer);
+            navigator.serviceWorker.removeEventListener?.('message', receive);
+            onProgress?.(null);
+            registration.removeEventListener('updatefound', check);
+            for (const worker of watched)
+                worker.removeEventListener('statechange', check);
+        };
+        const check = () => {
+            if (registration.active?.state === 'activated') {
+                cleanup();
+                resolve();
+                return;
+            }
+            for (const worker of [registration.installing, registration.waiting, registration.active]) {
+                if (worker && !watched.has(worker)) {
+                    watched.add(worker);
+                    worker.addEventListener('statechange', check);
+                    worker.postMessage?.({ type: 'SATIN_DOWNLOAD_PROGRESS_REQUEST' });
+                }
+            }
+            if ([...watched].some(worker => worker.state === 'redundant') &&
+                !registration.installing &&
+                !registration.active) {
+                // WebKit can report redundant before delivering this worker's failure message.
+                // Keep listening briefly; persisted diagnostics belong to earlier attempts.
+                if (redundantTimer === undefined) {
+                    clearTimeout(timer);
+                    redundantTimer = setTimeout(() => {
+                        cleanup();
+                        reject(new Error('The offline bundle did not finish installing.'));
+                    }, Math.min(timeoutMs, 250));
+                }
+            }
+        };
+        deadline();
+        registration.addEventListener('updatefound', check);
+        registrationJob?.catch(error => {
+            cleanup();
+            reject(error);
+        });
+        check();
+    });
+}
+/** Admission owns the entire five-second launch deadline. A stuck required
+ * Image reports the existing retry screen rather than revealing undecoded art. */
+export async function prepareLaunchContent(root, signal) {
+    performance.mark('satin-content-prepare-start');
+    const controller = new AbortController();
+    let requiredReady = false;
+    let finish = () => { };
+    const cancelled = () => {
+        controller.abort();
+        finish();
+    };
+    const optional = [
+        document.fonts.ready,
+        ...[...root.querySelectorAll('img')].map(image => {
+            image.loading = 'eager';
+            return image.decode();
+        }),
+    ];
+    const required = prepareDestinationImages(root, controller.signal).then(() => {
+        if (!controller.signal.aborted)
+            requiredReady = true;
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            finish = resolve;
+            signal?.addEventListener('abort', cancelled, { once: true });
+            if (signal?.aborted) {
+                cancelled();
+                return;
+            }
+            const timer = setTimeout(() => {
+                if (requiredReady)
+                    resolve();
+                else
+                    reject(new Error('Artwork did not finish preparing. Please retry.'));
+            }, 5_000);
+            const complete = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            finish = complete;
+            void Promise.all([required, Promise.allSettled(optional)]).then(complete, error => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    }
+    finally {
+        controller.abort();
+        signal?.removeEventListener('abort', cancelled);
+    }
+    if (!signal?.aborted)
+        performance.mark('satin-content-prepared');
+}

package/dist/app/launchReadiness.d.ts

@@ -0,0 +1,9 @@
+export declare const GLASS_LAUNCH_BUDGET_MS = 2500;
+/** Bound idle preparation by visible time. Suspension pauses the remaining
+ * budget; download progress resets it. A timeout is terminal until Retry. */
+export declare function armPreparationBudget(expire: () => void, lastProgress: () => number, doc?: Document): () => void;
+export declare function glassLaunchTimedOut(prepared: boolean, glassReady: boolean, elapsedMs: number): boolean;
+/** Run `expire` once the page has been visible for `budgetMs` without interruption.
+ * A hidden page cannot present (WebKit defers its GPU work), so hidden time never
+ * counts; each return to visible starts a fresh budget. Returns a disposer. */
+export declare function armVisibleLaunchBudget(expire: () => void, budgetMs?: number, doc?: Document): () => void;

package/dist/app/launchReadiness.js

@@ -0,0 +1,72 @@
+// Bound presentation readiness. Expiration is a visible error, never a material substitution.
+export const GLASS_LAUNCH_BUDGET_MS = 2_500;
+/** Bound idle preparation by visible time. Suspension pauses the remaining
+ * budget; download progress resets it. A timeout is terminal until Retry. */
+export function armPreparationBudget(expire, lastProgress, doc = document) {
+    let idleVisibleMs = 0;
+    let previousTime = performance.now();
+    let previousProgress = lastProgress();
+    let visible = doc.visibilityState === 'visible';
+    let timer;
+    let disposed = false;
+    const dispose = () => {
+        disposed = true;
+        clearInterval(timer);
+        doc.removeEventListener('visibilitychange', visibilityChanged);
+    };
+    const update = () => {
+        if (disposed)
+            return;
+        const now = performance.now();
+        const progress = lastProgress();
+        if (progress > previousProgress) {
+            idleVisibleMs = 0;
+            previousTime = Math.max(previousTime, progress);
+            previousProgress = progress;
+        }
+        if (visible)
+            idleVisibleMs += now - previousTime;
+        previousTime = now;
+        visible = doc.visibilityState === 'visible';
+        if (visible && idleVisibleMs >= 30_000) {
+            dispose();
+            expire();
+        }
+    };
+    const visibilityChanged = () => {
+        update();
+        clearInterval(timer);
+        timer = undefined;
+        if (visible && !disposed)
+            timer = setInterval(update, 1000);
+    };
+    doc.addEventListener('visibilitychange', visibilityChanged);
+    if (visible)
+        timer = setInterval(update, 1000);
+    return dispose;
+}
+export function glassLaunchTimedOut(prepared, glassReady, elapsedMs) {
+    return prepared && !glassReady && elapsedMs >= GLASS_LAUNCH_BUDGET_MS;
+}
+/** Run `expire` once the page has been visible for `budgetMs` without interruption.
+ * A hidden page cannot present (WebKit defers its GPU work), so hidden time never
+ * counts; each return to visible starts a fresh budget. Returns a disposer. */
+export function armVisibleLaunchBudget(expire, budgetMs = GLASS_LAUNCH_BUDGET_MS, doc = document) {
+    let timer;
+    const arm = () => {
+        clearTimeout(timer);
+        timer = undefined;
+        if (doc.visibilityState === 'visible')
+            timer = setTimeout(() => {
+                timer = undefined;
+                if (doc.visibilityState === 'visible')
+                    expire();
+            }, budgetMs);
+    };
+    arm();
+    doc.addEventListener('visibilitychange', arm);
+    return () => {
+        clearTimeout(timer);
+        doc.removeEventListener('visibilitychange', arm);
+    };
+}

package/dist/app/launchScreen.d.ts

@@ -0,0 +1,16 @@
+import type { AppDefinition } from './definition.js';
+/** Serializable so the same slot paints before JavaScript modules load. */
+export interface LaunchScreenSlot {
+    readonly icon?: string;
+    readonly label?: string;
+}
+export declare function launchScreenMarkup(app: AppDefinition): string;
+export declare const launchScreenLayer = 20000;
+export declare const launchErrorLayer: number;
+export declare const launchScreenCSS = "#satin-launch-screen{position:fixed;inset:calc(-1 * var(--satin-launch-excluded-top, 0px)) 0 0;z-index:20000;display:flex;flex-direction:column;align-items:center;justify-content:center;background:var(--satin-launch-background);color:var(--satin-launch-ink);font:17px system-ui;pointer-events:none}#satin-launch-screen[hidden],#satin-launch-progress[hidden]{display:none}.satin-launch-icon{position:relative;width:108px;height:108px;display:grid;place-items:center}#satin-launch-screen>p{position:absolute;top:calc(50% + 54px);margin:16px 0 0}.satin-launch-icon img{border-radius:15px}#satin-launch-progress{position:absolute;inset:0;width:108px;height:108px;transform:rotate(-90deg)}";
+export interface DownloadProgress {
+    /** Monotonic response-header progress, independent of downloaded bytes. */
+    activity?: number;
+    readonly loaded: number;
+    readonly total: number;
+}

package/dist/app/launchScreen.js

@@ -0,0 +1,14 @@
+export function launchScreenMarkup(app) {
+    const escape = (value) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('"', '&quot;');
+    const icon = app.launchScreen?.icon ??
+        app.icons.find(icon => icon.type === 'image/png')?.src ??
+        app.icons[0].src;
+    // Inlining removes the fetch, not the decode. Paint the icon atomically with
+    // the cover and SVG ring instead of letting the first arc appear on its own.
+    return `<div id="satin-launch-screen" role="status" aria-label="Opening ${escape(app.name)}"><div class="satin-launch-icon"><img src="${escape(icon)}" width="68" height="68" decoding="sync" alt="" draggable="false"><svg id="satin-launch-progress" viewBox="0 0 108 108" role="progressbar" aria-label="Downloading app" aria-valuemin="0" aria-valuemax="100" hidden><circle cx="54" cy="54" r="51" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" pathLength="100" stroke-dasharray="100" stroke-dashoffset="100"/></svg></div>${app.launchScreen?.label ? `<p>${escape(app.launchScreen.label)}</p>` : ''}</div>`;
+}
+// Launch overlays sit above framework chrome (up to 15000). Keep their
+// ordering away from the maximum CSS integer boundary.
+export const launchScreenLayer = 20_000;
+export const launchErrorLayer = launchScreenLayer + 1;
+export const launchScreenCSS = `#satin-launch-screen{position:fixed;inset:calc(-1 * var(--satin-launch-excluded-top, 0px)) 0 0;z-index:${launchScreenLayer};display:flex;flex-direction:column;align-items:center;justify-content:center;background:var(--satin-launch-background);color:var(--satin-launch-ink);font:17px system-ui;pointer-events:none}#satin-launch-screen[hidden],#satin-launch-progress[hidden]{display:none}.satin-launch-icon{position:relative;width:108px;height:108px;display:grid;place-items:center}#satin-launch-screen>p{position:absolute;top:calc(50% + 54px);margin:16px 0 0}.satin-launch-icon img{border-radius:15px}#satin-launch-progress{position:absolute;inset:0;width:108px;height:108px;transform:rotate(-90deg)}`;

package/dist/app/launchScreenRuntime.d.ts

@@ -0,0 +1,19 @@
+import type { DownloadProgress } from './launchScreen.js';
+interface LaunchScreenController {
+    progress(progress: DownloadProgress | null): void;
+    updated(start?: 0 | 100): Promise<boolean>;
+    complete(): Promise<boolean>;
+    reveal(): void;
+    fail(onRetired: () => void): void;
+    restore(): void;
+}
+export declare function installLaunchScreenRuntime(): LaunchScreenController;
+export declare function setLaunchScreen(visible: boolean): void;
+export declare function setLaunchProgress(progress: DownloadProgress | null): void;
+/** Complete a visible arc before a cold-update document replacement. */
+export declare function completeLaunchProgress(): Promise<boolean>;
+/** Confirm an applied update on its successor document before revealing the app. */
+export declare function showAppliedUpdate(): Promise<boolean>;
+/** Serialized after the declarative cover, before modules and their first paint. */
+export declare function resumeAppliedUpdate(scope: string, buildId?: string): void;
+export {};