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

package/dist/app/deployment.js

@@ -0,0 +1,352 @@
+import { appManifestPaths } from './manifests.js';
+export function deploymentExpectation(app, base) {
+    const route = app.installRoute ?? '/install';
+    return {
+        base,
+        id: app.id,
+        start_url: app.startRoute,
+        scope: app.scope,
+        installRoute: route.startsWith(base) ? route : base + route.slice(1),
+        manifests: appManifestPaths(app, base),
+        icons: app.icons.map(icon => icon.src),
+        launchColors: {
+            light: app.appearance.background,
+            dark: app.appearance.darkLaunch === 'match-light'
+                ? app.appearance.background
+                : app.appearance.darkLaunch.background,
+        },
+    };
+}
+// Self-contained: embedded verbatim in the install page and used by the CLI.
+export async function checkDeployment(expected, pageUrl, fetcher = fetch, includePrecache = false, decodeImage, requestTimeoutMs = 4000, checkMedia) {
+    const failures = [];
+    const page = new URL(pageUrl);
+    const fix = `Deploy this build at ${expected.base}, or rebuild with Vite base matching the deployment path and app scope.`;
+    const label = (url) => {
+        const path = new URL(url, page).pathname;
+        if (path === expected.manifests[1])
+            return 'Dark-mode manifest';
+        if (expected.manifests.includes(path))
+            return 'Manifest';
+        if (path.endsWith('/sw.js'))
+            return 'Service worker';
+        if (path === expected.start_url)
+            return 'App page';
+        if (expected.icons.includes(path))
+            return 'Icon';
+        if (path === expected.installRoute)
+            return 'Install page';
+        if (path.includes('precache-manifest.'))
+            return 'Precache inventory';
+        return 'Resource';
+    };
+    const fail = (reason, url, transient = false, remedy = fix) => {
+        failures.push({ reason, url, fix: remedy, check: label(url), status: reason, transient });
+    };
+    const launchColors = expected.launchColors;
+    if (!launchColors ||
+        typeof launchColors.light !== 'string' ||
+        typeof launchColors.dark !== 'string' ||
+        !/^#[\da-f]{6}$/i.test(launchColors.light) ||
+        !/^#[\da-f]{6}$/i.test(launchColors.dark)) {
+        fail(`Missing or invalid launch colors for ${expected.id}.`, page.href, false, 'Rebuild and deploy with the current Satin plugin so launch colors can be checked.');
+        return failures;
+    }
+    if (page.protocol !== 'https:' &&
+        !(['localhost', '127.0.0.1', '[::1]'].includes(page.hostname) && page.protocol === 'http:')) {
+        fail('HTTPS is required for installation and service workers.', page.href, false, 'Serve the app over trusted HTTPS.');
+        return failures;
+    }
+    const request = async (path, kind, allowDirectoryCanonicalization = false) => {
+        const url = new URL(path, page).href;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), requestTimeoutMs);
+        let definite = false;
+        try {
+            const response = await fetcher(url, {
+                signal: controller.signal,
+                cache: 'no-store',
+                redirect: path === expected.scope + 'sw.js' ? 'manual' : 'follow',
+            });
+            definite = true;
+            if (response.status !== 200)
+                throw new Error(`HTTP ${response.status}`);
+            const finalUrl = new URL(response.url || url);
+            const requestedUrl = new URL(url);
+            const directoryPath = (pathname) => pathname.replace(/\/index\.html$/, '/').replace(/\/$/, '');
+            if (finalUrl.origin !== page.origin ||
+                (allowDirectoryCanonicalization
+                    ? directoryPath(finalUrl.pathname) !== directoryPath(requestedUrl.pathname) ||
+                        finalUrl.search !== requestedUrl.search
+                    : finalUrl.href !== url)) {
+                throw new Error(`unexpected final URL ${finalUrl.href}`);
+            }
+            const type = (response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+            const valid = kind === 'json'
+                ? /^(application\/(json|manifest\+json))$/.test(type)
+                : kind === 'javascript'
+                    ? /^(text|application)\/(javascript|ecmascript|x-javascript)$/.test(type)
+                    : kind === 'image'
+                        ? type.startsWith('image/')
+                        : kind === 'html'
+                            ? type === 'text/html'
+                            : kind === 'css'
+                                ? type === 'text/css'
+                                : type !== 'text/html' && type.length > 0;
+            if (!valid)
+                throw new Error(`expected ${kind}, received ${type || 'no Content-Type'}`);
+            definite = false;
+            const bytes = new Uint8Array(await response.arrayBuffer());
+            definite = true;
+            if (kind === 'image' && includePrecache) {
+                if (decodeImage)
+                    await decodeImage(bytes, type);
+                else {
+                    const image = new Image();
+                    const objectUrl = URL.createObjectURL(new Blob([bytes], { type }));
+                    try {
+                        image.src = objectUrl;
+                        await image.decode();
+                        if (!image.naturalWidth || !image.naturalHeight)
+                            throw new Error('empty image');
+                    }
+                    finally {
+                        URL.revokeObjectURL(objectUrl);
+                    }
+                }
+            }
+            return { body: new TextDecoder().decode(bytes), bytes, url: finalUrl.href };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            if (controller.signal.aborted) {
+                fail(`${label(url)} did not finish within ${requestTimeoutMs / 1000} s`, url, true, 'Check the server or connection, then try again.');
+            }
+            else {
+                fail(`${label(url)} check failed: ${reason}`, url, !definite, definite ? fix : 'Check the server or connection, then try again.');
+            }
+            return null;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const parse = (response) => {
+        if (!response)
+            return null;
+        try {
+            const value = JSON.parse(response.body);
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                throw new Error('expected an object');
+            return value;
+        }
+        catch {
+            fail('Invalid JSON.', response.url);
+            return null;
+        }
+    };
+    const matchesManifestInventory = (body) => {
+        try {
+            const metadata = body.match(/<script id="satin-deployment" type="application\/json">([^<]+)<\/script>/);
+            const apps = JSON.parse(metadata?.[1] ?? 'null');
+            const app = Array.isArray(apps)
+                ? apps.find(app => app.id === expected.id && app.scope === expected.scope)
+                : undefined;
+            return (Array.isArray(app?.manifests) &&
+                app.manifests.length === expected.manifests.length &&
+                new Set(app.manifests).size === app.manifests.length &&
+                expected.manifests.every(path => app.manifests.includes(path)));
+        }
+        catch {
+            return false;
+        }
+    };
+    const workerTask = request(expected.scope + 'sw.js', 'javascript');
+    const inventoryTask = (async () => {
+        const versionResponse = await request(expected.scope + 'satin-version.json', 'json');
+        const version = parse(versionResponse);
+        if (!version)
+            return;
+        if (typeof version.buildId !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(version.buildId)) {
+            fail('Build version is missing or invalid.', versionResponse.url);
+            return;
+        }
+        const worker = await workerTask;
+        if (worker) {
+            const workerBuildId = worker.body.match(/\bconst\s+BUILD_ID\s*=\s*"([a-zA-Z0-9_-]+)"/)?.[1];
+            if (!workerBuildId) {
+                fail('Service worker build ID is missing or invalid.', worker.url);
+            }
+            else if (workerBuildId !== version.buildId) {
+                fail(`Service worker is from build ${workerBuildId}, the deployment is build ${version.buildId}: redeploy sw.js / purge the CDN cache for it`, worker.url, false, 'Redeploy sw.js / purge the CDN cache for it.');
+            }
+        }
+        const inventoryResponse = await request(expected.base + 'precache-manifest.' + version.buildId + '.json', 'json');
+        const inventory = parse(inventoryResponse);
+        if (!inventory)
+            return;
+        if (!Array.isArray(inventory.entries) || !inventory.entries.length) {
+            fail('Precache inventory is empty or invalid.', inventoryResponse.url);
+            return;
+        }
+        const entries = inventory.entries;
+        for (const entry of entries) {
+            let valid = false;
+            try {
+                const url = new URL(entry.url, page);
+                valid =
+                    typeof entry.url === 'string' &&
+                        entry.url.startsWith(expected.base) &&
+                        url.origin === page.origin &&
+                        url.pathname.startsWith(expected.base) &&
+                        !url.search &&
+                        !url.hash &&
+                        !url.username &&
+                        !url.password &&
+                        (entry.bytes === undefined || (Number.isSafeInteger(entry.bytes) && entry.bytes >= 0)) &&
+                        (entry.revision == null || /^[a-f0-9]{64}$/.test(entry.revision));
+            }
+            catch {
+                /* Report the inventory rather than requesting an unsafe URL. */
+            }
+            if (!valid) {
+                fail('Precache inventory contains invalid URLs or metadata.', inventoryResponse.url);
+                return;
+            }
+        }
+        if (includePrecache && checkMedia)
+            failures.push(...(await checkMedia(inventory, entries)));
+        if (!includePrecache)
+            return;
+        for (let offset = 0; offset < entries.length; offset += 8) {
+            await Promise.all(entries.slice(offset, offset + 8).map(async (entry) => {
+                const path = new URL(entry.url, page).pathname;
+                const kind = /\.m?js$/.test(path)
+                    ? 'javascript'
+                    : /\.css$/.test(path)
+                        ? 'css'
+                        : /\.(json|webmanifest)$/.test(path)
+                            ? 'json'
+                            : /\.(png|svg|webp|jpg|jpeg|avif|ico|gif)$/.test(path)
+                                ? 'image'
+                                : /\.html$/.test(path) || path.endsWith('/')
+                                    ? 'html'
+                                    : 'asset';
+                const response = await request(entry.url, kind);
+                if (!response)
+                    return;
+                if (entry.bytes !== undefined && response.bytes.byteLength !== entry.bytes) {
+                    fail(`Precache size mismatch: expected ${entry.bytes}, received ${response.bytes.byteLength} decoded bytes.`, response.url);
+                }
+                if (entry.revision) {
+                    const digest = await crypto.subtle.digest('SHA-256', response.bytes);
+                    const actual = Array.from(new Uint8Array(digest), value => value.toString(16).padStart(2, '0')).join('');
+                    if (actual !== entry.revision)
+                        fail('Precache SHA-256 mismatch.', response.url);
+                }
+            }));
+        }
+    })();
+    await Promise.all([
+        inventoryTask,
+        ...expected.manifests.map(async (path) => {
+            const response = await request(path, 'json');
+            const manifest = parse(response);
+            if (!manifest || !response)
+                return;
+            for (const field of ['id', 'start_url', 'scope']) {
+                if (manifest[field] !== expected[field])
+                    fail(`Manifest ${field} must be ${expected[field]}; received ${String(manifest[field])}.`, response.url);
+            }
+            const dark = manifest.color_scheme_dark;
+            for (const [appearance, colors] of [
+                ['light', manifest],
+                ['dark', dark],
+            ]) {
+                for (const field of ['background_color', 'theme_color']) {
+                    const wanted = launchColors[appearance];
+                    const actual = colors?.[field];
+                    if (typeof actual !== 'string' || actual.toLowerCase() !== wanted.toLowerCase()) {
+                        fail(`Manifest ${appearance} ${field} must match the launch color ${wanted}; received ${String(actual)}.`, response.url, false, 'Rebuild and deploy the complete app so manifest colors match its declared launch colors.');
+                    }
+                }
+            }
+            try {
+                new URL(String(manifest.start_url), response.url);
+            }
+            catch {
+                fail('Manifest start_url is not a valid URL.', response.url);
+            }
+            if (!Array.isArray(manifest.icons) || !manifest.icons.length)
+                fail('Manifest has no icons.', response.url);
+            else if (expected.icons.some(icon => !manifest.icons.some(value => value?.src === icon))) {
+                fail('Manifest is missing a required icon.', response.url);
+            }
+        }),
+        ...expected.icons.map(icon => request(icon, 'image')),
+        workerTask,
+        (async () => {
+            const start = await request(expected.start_url, 'html', true);
+            if (!start)
+                return;
+            const metadata = start.body.match(/<script id="satin-deployment" type="application\/json">([^<]+)<\/script>/);
+            let matching = false;
+            try {
+                const apps = JSON.parse(metadata?.[1] ?? 'null');
+                matching =
+                    Array.isArray(apps) &&
+                        apps.some(app => app.id === expected.id && app.scope === expected.scope);
+            }
+            catch {
+                /* The identity check below reports malformed metadata. */
+            }
+            if (start.body.includes('data-satin-install-page') ||
+                !start.body.includes('satin-document-head') ||
+                !matching) {
+                fail('start_url serves the install page or a different app identity.', start.url);
+            }
+            if (matching && !matchesManifestInventory(start.body)) {
+                fail('App page manifest inventory does not match this build.', start.url);
+            }
+        })(),
+        ...(includePrecache
+            ? [
+                (async () => {
+                    const install = await request(expected.installRoute, 'html', true);
+                    if (!install)
+                        return;
+                    if (!install.body.includes('data-satin-install-page'))
+                        fail('Install route does not serve the install page.', install.url);
+                    if (!matchesManifestInventory(install.body))
+                        fail('Install page manifest inventory does not match this build.', install.url);
+                    // A custom install page is still Satin's page around the author's: the check must
+                    // run before any author code, and the author's bundle must load.
+                    if (!/<script data-satin-install-check[\s>]/.test(install.body))
+                        fail('Install page does not run the Satin deployment check.', install.url, false, 'Serve the install page Satin builds. A custom page is set with satinApp(app, { installPage }) and Satin wraps it.');
+                    // `entr[y]`: this source is embedded in install pages, so the pattern must not match
+                    // its own text there.
+                    const entry = install.body.match(/<script data-satin-install-check data-satin-install-entr[y]="([^"]+)"/)?.[1];
+                    if (entry)
+                        await request(entry, 'javascript');
+                    const links = install.body.match(/<link\b[^>]*>/gi) ?? [];
+                    const manifestLink = links.find(link => /\brel\s*=\s*["']manifest["']/i.test(link));
+                    const href = manifestLink?.match(/\bhref\s*=\s*["']([^"']+)["']/i)?.[1];
+                    if (!href ||
+                        !expected.manifests.some(path => new URL(path, page).href === new URL(href, install.url).href)) {
+                        fail('Install page links to a missing or different manifest.', install.url);
+                    }
+                    if (href) {
+                        const linked = parse(await request(new URL(href, install.url).href, 'json'));
+                        if (linked &&
+                            (linked.id !== expected.id ||
+                                linked.scope !== expected.scope ||
+                                linked.start_url !== expected.start_url)) {
+                            fail('Install page manifest does not identify this app.', install.url);
+                        }
+                    }
+                })(),
+            ]
+            : []),
+    ]);
+    return failures;
+}

package/dist/app/deploymentBuild.d.ts

@@ -0,0 +1,3 @@
+import type { DeploymentExpectation } from './deployment.js';
+/** Final check runs after all shell and public-page emission has completed. */
+export declare function validateBuiltDeployment(output: string, expected: DeploymentExpectation): Promise<void>;

package/dist/app/deploymentBuild.js

@@ -0,0 +1,55 @@
+import { access, readFile } from 'node:fs/promises';
+import { resolve, sep } from 'node:path';
+/** Final check runs after all shell and public-page emission has completed. */
+export async function validateBuiltDeployment(output, expected) {
+    const root = resolve(output);
+    const fileForUrl = (url) => {
+        const path = new URL(url, 'https://satin.invalid').pathname;
+        if (!path.startsWith(expected.base)) {
+            throw new Error(`Satin malformed package: ${url} is outside Vite base ${expected.base}.`);
+        }
+        const relative = path.slice(expected.base.length);
+        const file = resolve(root, relative + (path.endsWith('/') ? 'index.html' : ''));
+        if (!file.startsWith(root + sep))
+            throw new Error(`Satin malformed package: invalid path ${url}.`);
+        return file;
+    };
+    const required = async (url) => {
+        const file = fileForUrl(url);
+        try {
+            await access(file);
+        }
+        catch {
+            throw new Error(`Satin malformed package: required file ${url} is missing from dist.`);
+        }
+        return file;
+    };
+    for (const url of [
+        ...expected.manifests,
+        ...expected.icons,
+        expected.start_url,
+        expected.installRoute + '/',
+        expected.scope + 'sw.js',
+    ]) {
+        await required(url);
+    }
+    for (const url of expected.manifests) {
+        const manifest = JSON.parse(await readFile(fileForUrl(url), 'utf8'));
+        const icons = manifest.icons;
+        if (!Array.isArray(icons) ||
+            new Set(icons.map(icon => icon?.src)).size !== new Set(expected.icons).size ||
+            !expected.icons.every(source => icons.some(icon => icon?.src === source))) {
+            throw new Error('Satin malformed package: manifest icons do not match this build.');
+        }
+        for (const field of ['id', 'start_url', 'scope']) {
+            if (manifest[field] !== expected[field]) {
+                throw new Error(`Satin malformed package: manifest ${field} must equal ${expected[field]}.`);
+            }
+        }
+    }
+    const version = JSON.parse(await readFile(await required(expected.scope + 'satin-version.json'), 'utf8'));
+    const inventoryUrl = expected.base + `precache-manifest.${version.buildId}.json`;
+    const inventory = JSON.parse(await readFile(await required(inventoryUrl), 'utf8'));
+    for (const entry of inventory.entries)
+        await required(entry.url);
+}

package/dist/app/earlyWorker.d.ts

@@ -0,0 +1,3 @@
+export declare function registerEarlyWorker(scope: string, onLookupComplete?: (error?: Error) => void, resetRequested?: boolean, registerAfterLookup?: boolean): Promise<void>;
+/** Restart preparation after an explicit failure retry without reloading. */
+export declare function retryFailedInstallation(scope: string): Promise<void>;

package/dist/app/earlyWorker.js

@@ -0,0 +1,77 @@
+// Serialized into the head. Keep the handshake independent of modules.
+export async function registerEarlyWorker(scope, onLookupComplete, resetRequested = false, registerAfterLookup = true) {
+    const workers = navigator.serviceWorker;
+    if (!workers) {
+        onLookupComplete?.();
+        return;
+    }
+    const resetKey = 'satin-install-reset:' + scope;
+    try {
+        resetRequested ||= sessionStorage.getItem(resetKey) === '1';
+        sessionStorage.removeItem(resetKey);
+    }
+    catch {
+        // Explicit in-app retry still works without session storage.
+    }
+    const bounded = async (operation) => {
+        let timer;
+        try {
+            return await Promise.race([
+                operation,
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(new Error('Service worker reset did not finish. Please retry.')), 3000);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const expectedScope = new URL(scope, location.href).href;
+    const expectedScript = new URL(scope + 'sw.js', location.href).href;
+    let existing;
+    try {
+        existing = await bounded(workers.getRegistration(scope));
+        const worker = existing?.installing ?? existing?.waiting ?? existing?.active;
+        if (resetRequested &&
+            existing?.scope === expectedScope &&
+            worker?.scriptURL === expectedScript &&
+            !existing.active &&
+            existing.installing &&
+            !existing.waiting) {
+            if (!(await bounded(existing.unregister()))) {
+                throw new Error('Service worker reset did not finish. Please retry.');
+            }
+            existing = undefined;
+        }
+    }
+    catch (error) {
+        const failure = error instanceof Error ? error : new Error(String(error));
+        onLookupComplete?.(failure);
+        throw failure;
+    }
+    onLookupComplete?.();
+    if (!registerAfterLookup)
+        return;
+    performance.mark('satin-worker-registration-start');
+    const worker = existing?.installing ?? existing?.waiting ?? existing?.active;
+    const registration = existing?.scope === expectedScope && worker?.scriptURL === expectedScript
+        ? existing
+        : await workers.register(expectedScript, { scope, updateViaCache: 'none' });
+    const current = registration.installing ?? registration.waiting ?? registration.active;
+    current?.postMessage({ type: 'SATIN_DOWNLOAD_PROGRESS_REQUEST' });
+}
+/** Restart preparation after an explicit failure retry without reloading. */
+export function retryFailedInstallation(scope) {
+    return new Promise((resolve, reject) => {
+        void registerEarlyWorker(scope, error => {
+            if (error)
+                reject(error);
+            else {
+                delete globalThis
+                    .__SATIN_WORKER_LOOKUP_ERROR__;
+                resolve();
+            }
+        }, true, false).catch(reject);
+    });
+}

package/dist/app/head.d.ts

@@ -0,0 +1,10 @@
+import type { AppDefinition } from './definition.js';
+export { appManifestStem, appManifestFiles } from './manifests.js';
+export interface AppFixture {
+    /** Legacy display-mode capability rig only, never a production option. */
+    readonly display?: 'standalone' | 'fullscreen' | 'minimal-ui';
+    readonly app: AppDefinition;
+    /** Exact query parameters for this lab-only installed app. First match wins. */
+    readonly query: Readonly<Record<string, string>>;
+}
+export declare function generateAppHead(fixtures: readonly AppFixture[], base: string, production?: boolean, devServer?: boolean): string;

package/dist/app/head.js

@@ -0,0 +1,120 @@
+import { registerEarlyWorker } from './earlyWorker.js';
+import { deploymentExpectation } from './deployment.js';
+import { installLaunchWatchdog } from './launchWatchdog.js';
+import { installLaunchScreenRuntime } from './launchScreenRuntime.js';
+import { GLASS_LAUNCH_BUDGET_MS } from './launchReadiness.js';
+import { appManifestHrefExpression, isIOSWebKit, installRouteForBase } from './install.js';
+import { resolvePlatformGate } from './platformPolicy.js';
+import { launchScreenCSS } from './launchScreen.js';
+import { installAppearanceStore } from './appearanceStore.js';
+import { ADAPTIVE_LAYOUT_POLICY } from '../layout/layoutClass.js';
+import { SATIN_VIEWPORT, resolveViewportFit } from './viewportValue.js';
+import { STARTUP_SCREENS, startupImages } from './startup.js';
+import { appManifestStem } from './manifests.js';
+export { appManifestStem, appManifestFiles } from './manifests.js';
+export function generateAppHead(fixtures, base, production = true, devServer = false) {
+    const appearance = fixtures[0]?.app.appearance;
+    const lightBackground = appearance?.background ?? '#ffffff';
+    const darkBackground = appearance?.darkLaunch === 'match-light'
+        ? lightBackground
+        : (appearance?.darkLaunch.background ?? '#000000');
+    const data = JSON.stringify(fixtures.map(({ app, query }) => ({
+        app,
+        query,
+        installRoute: installRouteForBase(app, base),
+        startupStem: appManifestStem(app),
+        manifest: `${base}${appManifestStem(app)}`,
+    }))).replaceAll('<', '\\u003c');
+    // A cached navigation must paint its launch surface even before head scripts
+    // run. Match the manifest's two backgrounds, including match-light apps.
+    return `<style id="satin-launch-paint">:root{--satin-launch-background:${lightBackground};--satin-launch-ink:#1c1c1e;--satin-background:${lightBackground}}@media(prefers-color-scheme:dark){:root{--satin-launch-background:${darkBackground};--satin-launch-ink:${appearance?.darkLaunch === 'match-light' ? '#1c1c1e' : '#ffffff'};--satin-background:${darkBackground}}}${launchScreenCSS}html,body{background:var(--satin-background);margin:0} [data-satin-root][data-satin-launch]:not([data-satin-launch="ready"]){opacity:0;pointer-events:none}</style>
+<script id="satin-platform-gate">(() => {
+ performance.mark('satin-document-head');
+ const fixtures = ${data};
+ const query = new URLSearchParams(location.search);
+ const selected = fixtures.find(f => Object.entries(f.query).every(([k,v]) => query.get(k) === v));
+ const app = selected.app;
+ window.__SATIN_DEFINITION__ = app;
+ const iosWebKit = (${isIOSWebKit.toString()})(
+  navigator.userAgent, navigator.platform, navigator.maxTouchPoints, {
+  touchCallout: typeof CSS !== 'undefined' && CSS.supports('-webkit-touch-callout', 'none'),
+  gestureEvents: 'GestureEvent' in window || 'ongesturestart' in window,
+  standalone: typeof navigator.standalone === 'boolean'
+ });
+ const standalone = navigator.standalone === true ||
+  (typeof matchMedia === 'function' && matchMedia('(display-mode: standalone)').matches);
+ const decision = (${resolvePlatformGate.toString()})(
+  app.platforms, iosWebKit, standalone, app.updateProfile, ${devServer}
+ );
+ window.__SATIN_PLATFORM_BLOCKED__ = decision !== 'run';
+ if(window.__SATIN_PLATFORM_BLOCKED__) {
+  location.replace(decision === 'install' ? selected.installRoute : app.scope + 'unsupported.html');
+ }
+})();</script>
+<meta name="viewport" content="${SATIN_VIEWPORT}">
+<meta name="apple-mobile-web-app-capable" content="yes">
+<meta id="satin-theme-color" name="theme-color" content="${fixtures[0]?.app.appearance.background ?? '#ffffff'}">
+<meta id="satin-status-bar-style" name="apple-mobile-web-app-status-bar-style" content="default">
+<meta name="color-scheme" content="light dark">
+<script id="satin-deployment" type="application/json">${JSON.stringify(fixtures.map(({ app }) => deploymentExpectation(app, base))).replaceAll('<', '\\u003c')}</script>
+<link id="satin-manifest" rel="manifest">
+<link id="satin-touch-icon" rel="apple-touch-icon">
+<script id="satin-head-init">(() => {
+ if(window.__SATIN_PLATFORM_BLOCKED__ !== false) return;
+ const fixtures = ${data};
+ const query = new URLSearchParams(location.search);
+ const selected = fixtures.find(f => Object.entries(f.query).every(([k,v]) => query.get(k) === v));
+ const app = selected.app;
+ const fit = (${resolveViewportFit.toString()})(app.viewportFit || 'adaptive', navigator.userAgent, navigator.platform, navigator.maxTouchPoints, innerWidth, innerHeight, ${ADAPTIVE_LAYOUT_POLICY.horizontal.regularMinimum}, ${ADAPTIVE_LAYOUT_POLICY.vertical.regularMinimum});
+ document.querySelector('meta[name="viewport"]').content = ${JSON.stringify(SATIN_VIEWPORT)}.replace('viewport-fit=cover', 'viewport-fit=' + fit);
+ document.documentElement.dataset.satinViewportFit = fit;
+ (${installLaunchScreenRuntime.toString()})();
+ (${installLaunchWatchdog.toString()})(${Math.max(10_000, GLASS_LAUNCH_BUDGET_MS)});
+ // First installation can overlap module loading. Existing registrations,
+ // with active or waiting versions, remain under the normal launch/update policy.
+ if (${production} && typeof navigator !== 'undefined' && 'serviceWorker' in navigator) {
+  window.__SATIN_WORKER_LOOKUP__ = new Promise(resolve => {
+   (${registerEarlyWorker.toString()})(app.scope, error => { window.__SATIN_WORKER_LOOKUP_ERROR__ = error; if (error) window.dispatchEvent(new CustomEvent('satin-worker-lookup-error', { detail: error.message })); resolve(); }).catch(() => resolve());
+  });
+ }
+ document.title = app.name;
+ const launchBackground = app.appearance.darkLaunch === 'match-light' ? app.appearance.background : app.appearance.darkLaunch.background;
+ const startup = (${startupImages.toString()})(selected.startupStem, app.appearance.background, launchBackground, ${JSON.stringify(STARTUP_SCREENS)});
+ for (const image of startup) {
+  const link = document.createElement('link');
+  link.rel = 'apple-touch-startup-image'; link.href = ${JSON.stringify(base)} + image.file; link.media = image.media;
+  document.head.appendChild(link);
+ }
+ document.getElementById('satin-touch-icon').href = app.icons.find(i => i.type === 'image/png')?.src || app.icons[0].src;
+ const darkBackground = app.appearance.darkLaunch === 'match-light' ? app.appearance.background : app.appearance.darkLaunch.background;
+ // CSS can select the cold background before the controller runs. Once
+ // installed, the shared controller owns every root color, in every session.
+ const field = document.createElement('style');
+ const darkInk = app.appearance.darkLaunch === 'match-light' ? '#1c1c1e' : '#ffffff';
+ field.textContent = [
+  ':root{--satin-launch-background:' + app.appearance.background + ';--satin-launch-ink:#1c1c1e}',
+  '@media(prefers-color-scheme:dark){:root:not([data-satin-appearance]){',
+  '--satin-launch-background:' + darkBackground + ';--satin-launch-ink:' + darkInk + '}}',
+  ':root[data-satin-appearance="light"]{--satin-launch-background:' + app.appearance.background,
+  ';--satin-launch-ink:#1c1c1e}',
+  ':root[data-satin-appearance="dark"]{--satin-launch-background:' + darkBackground,
+  ';--satin-launch-ink:' + darkInk + '}',
+ ].join('');
+ document.head.appendChild(field);
+ const store = (${installAppearanceStore.toString()})();
+ const apply = () => {
+  const dark = store.getSnapshot().dark;
+  const appearance = dark && app.appearance.darkLaunch !== 'match-light' ? app.appearance.darkLaunch : app.appearance;
+  document.documentElement.style.backgroundColor = appearance.background;
+  document.documentElement.style.setProperty('--satin-launch-background', appearance.background);
+  document.documentElement.style.setProperty('--satin-launch-ink', dark ? darkInk : '#1c1c1e');
+  document.documentElement.style.setProperty('--satin-background', appearance.background);
+  document.getElementById('satin-theme-color').content = appearance.background;
+  document.getElementById('satin-manifest').href = ${appManifestHrefExpression('selected.manifest')};
+ };
+ apply();
+ store.subscribe(apply);
+ document.addEventListener('visibilitychange', apply);
+ addEventListener('pagehide', apply);
+})();</script>`;
+}

package/dist/app/icons.d.ts

@@ -0,0 +1,4 @@
+/** Build-only conversion. No image library enters the app bundle. */
+export declare function generateAppIcons(source: Uint8Array): Promise<Map<number, Buffer<ArrayBuffer>>>;
+/** Build-only native launch cover; alpha must survive the WebClip image cache. */
+export declare function generateStartupImage(source: Uint8Array, width: number, height: number, ratio: number, background: string | null): Promise<Buffer<ArrayBuffer>>;