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

package/dist/app/icons.js

@@ -0,0 +1,35 @@
+import sharp from 'sharp';
+/** Build-only conversion. No image library enters the app bundle. */
+export async function generateAppIcons(source) {
+    const image = sharp(source, { limitInputPixels: 4096 * 4096 });
+    const metadata = await image.metadata();
+    if (!metadata.width || metadata.width !== metadata.height || metadata.width < 512)
+        throw new Error('App icon source must be square and at least 512 pixels wide');
+    return new Map(await Promise.all([180, 192, 512].map(async (size) => [
+        size,
+        await image.clone().resize(size, size).toColourspace('srgb').png().toBuffer(),
+    ])));
+}
+/** Build-only native launch cover; alpha must survive the WebClip image cache. */
+export async function generateStartupImage(source, width, height, ratio, background) {
+    const size = 68 * ratio;
+    const radius = 15 * ratio;
+    const mask = Buffer.from(`<svg width="${size}" height="${size}"><rect width="${size}" height="${size}" rx="${radius}" fill="white"/></svg>`);
+    const icon = await sharp(source)
+        .resize(size, size, { fit: 'fill' })
+        .ensureAlpha()
+        .composite([{ input: mask, blend: 'dest-in' }])
+        .png()
+        .toBuffer();
+    return sharp({
+        create: {
+            width,
+            height,
+            channels: 4,
+            background: background ?? { r: 0, g: 0, b: 0, alpha: 0 },
+        },
+    })
+        .composite([{ input: icon, gravity: 'centre' }])
+        .png()
+        .toBuffer();
+}

package/dist/app/install.d.ts

@@ -0,0 +1,18 @@
+import type { AppDefinition } from './definition.js';
+export interface IOSWebKitSignals {
+    readonly touchCallout: boolean;
+    readonly gestureEvents: boolean;
+    readonly standalone: boolean;
+}
+export declare function isIOSWebKit(userAgent: string, platform: string, maxTouchPoints: number, signals: IOSWebKitSignals): boolean;
+/** Generated install and app heads share one idiom resolver and manifest URL policy. */
+export declare function appManifestHrefExpression(stemExpression: string): string;
+/** Public page URLs are projected under Vite's deployment base. */
+export declare function installRouteForBase(app: AppDefinition, base: string): string;
+/** Preview builds accept device/layout overrides; production never does. */
+export interface InstallPageOptions {
+    readonly preview?: boolean;
+    /** The author's bundled install page, set by satinApp(app, { installPage }). */
+    readonly customPage?: string;
+}
+export declare function installPage(app: AppDefinition, kind: 'landing' | 'install' | 'gate', base?: string, options?: InstallPageOptions): string;

package/dist/app/install.js

@@ -0,0 +1,82 @@
+import { resolveDeviceIdiom } from '../layout/deviceIdiom.js';
+import { checkDeployment, deploymentExpectation } from './deployment.js';
+import { installPageCheck } from './installCheck.js';
+import { customInstallPage, installCustomMount } from './installCustom.js';
+import { installExperiencePage } from './installExperience.js';
+import { ADAPTIVE_LAYOUT_POLICY } from '../layout/layoutClass.js';
+import { SATIN_VIEWPORT, resolveViewportFit } from './viewportValue.js';
+import { startupImages } from './startup.js';
+import { APP_MANIFEST_VARIANTS, appManifestStem } from './manifests.js';
+export function isIOSWebKit(userAgent, platform, maxTouchPoints, signals) {
+    if (!/AppleWebKit/i.test(userAgent) || /Android/i.test(userAgent))
+        return false;
+    const mobileIdentity = /iPhone|iPad|iPod/i.test(userAgent);
+    const touchMacIdentity = platform === 'MacIntel' && maxTouchPoints > 1;
+    // CSS parsing, gesture APIs and the standalone API are independent signals.
+    // GestureEvent and ongesturestart count together, not as two separate proofs.
+    const signalCount = Number(signals.touchCallout) + Number(signals.gestureEvents) + Number(signals.standalone);
+    // Some WKWebViews omit Safari's standalone/gesture API. Keep genuine mobile
+    // WebKit compatible when one signal survives; a spoofed UA alone never passes.
+    return mobileIdentity ? signalCount >= 1 : touchMacIdentity && signalCount >= 2;
+}
+/** Generated install and app heads share one idiom resolver and manifest URL policy. */
+export function appManifestHrefExpression(stemExpression) {
+    const suffixes = Object.fromEntries(APP_MANIFEST_VARIANTS.filter(variant => variant.selected).map(variant => [
+        variant.idiom,
+        variant.suffix,
+    ]));
+    return `${stemExpression} + ((${JSON.stringify(suffixes)})[(${resolveDeviceIdiom.toString()})(navigator.userAgent, navigator.platform, navigator.maxTouchPoints)] ?? ${JSON.stringify(suffixes.phone)})`;
+}
+/** Public page URLs are projected under Vite's deployment base. */
+export function installRouteForBase(app, base) {
+    const route = app.installRoute ?? '/install';
+    return route.startsWith(base) ? route : base + route.slice(1);
+}
+const escape = (text) => text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('"', '&quot;');
+export function installPage(app, kind, base = '/', options = {}) {
+    const icon = app.icons.find(icon => icon.type === 'image/png') ?? app.icons[0];
+    const dark = app.appearance.darkLaunch === 'match-light'
+        ? app.appearance.background
+        : app.appearance.darkLaunch.background;
+    const stem = appManifestStem(app);
+    // Keep the device asset table outside the bounded install-page payload.
+    // Constant palettes retain their existing no-JavaScript startup fallback.
+    const fallback = app.appearance.background === dark
+        ? '<noscript>' +
+            startupImages(stem, app.appearance.background, dark)
+                .map(image => `<link rel="apple-touch-startup-image" href="${base}${image.file}" media="${image.media}">`)
+                .join('') +
+            '</noscript>'
+        : '';
+    const startup = `<script src="${app.scope}${stem}-startup.js"></script>${fallback}`;
+    const status = `<meta name="apple-mobile-web-app-capable" content="yes"><meta id="satin-install-status" name="apple-mobile-web-app-status-bar-style" content="default"><meta name="theme-color" content="${app.appearance.background}" media="(prefers-color-scheme: light)"><meta name="theme-color" content="${dark}" media="(prefers-color-scheme: dark)">`;
+    const title = kind === 'gate' ? 'This app is designed for iPhone and iPad' : app.name;
+    const body = `<p>${escape(app.description)}</p><a href="${escape(installRouteForBase(app, base))}">Add to Home Screen</a>`;
+    const head = `<meta charset="utf-8"><meta name="viewport" content="${SATIN_VIEWPORT}"><script>(()=>{const fit=(${resolveViewportFit.toString()})(${JSON.stringify(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)})();</script><title>${escape(title)}</title>${status}${startup}<link rel="manifest" href="${base}${stem}.webmanifest"><script>(()=>{document.querySelector('link[rel="manifest"]').href=${appManifestHrefExpression(JSON.stringify(base + stem))}})();</script><link rel="apple-touch-icon" href="${escape(icon.src)}">`;
+    const scripts = `<script id="satin-deployment" type="application/json">${JSON.stringify([deploymentExpectation(app, base)]).replaceAll('<', '\\u003c')}</script>${kind === 'install' ? `<script data-satin-install-check${options.customPage ? ` data-satin-install-entry="${escape(options.customPage)}"` : ''}>(${installPageCheck.toString()})(${JSON.stringify(deploymentExpectation(app, base))},${checkDeployment.toString()},4000${options.customPage ? `,(${installCustomMount.toString()}).bind(null,${JSON.stringify(options.customPage)})` : ''}).catch(error=>{console.error("[Satin deployment]",error);const status=document.getElementById("satin-install-check");status.textContent="This app is misconfigured: configuration check failed. Reload and check the console.";status.setAttribute("role","alert");status.dataset.error="true";status.hidden=false;document.getElementById("satin-install-guide").hidden=true})</script>` : ''}`;
+    if (options.customPage && kind === 'install') {
+        return customInstallPage({
+            head,
+            scripts,
+            name: app.name,
+            icon: icon.src,
+            tint: app.appearance.tint ?? '#007aff',
+            installRoute: installRouteForBase(app, base),
+            background: app.appearance.background,
+            darkBackground: dark,
+            darkText: app.appearance.darkLaunch !== 'match-light',
+        });
+    }
+    if (kind !== 'landing') {
+        return installExperiencePage({
+            app,
+            base,
+            head,
+            kind,
+            scripts,
+            installRoute: installRouteForBase(app, base),
+            preview: options.preview ?? process.env.SATIN_INSTALL_PREVIEW === '1',
+        });
+    }
+    return `<!doctype html><html lang="en"><head>${head}<style>html{background:${app.appearance.background};color:#1c1c1e;font:17px/1.5 system-ui}@media(prefers-color-scheme:dark){html{background:${dark};color:${app.appearance.darkLaunch === 'match-light' ? '#1c1c1e' : '#fff'}}}body{margin:0}main{max-width:420px;margin:72px auto;padding:24px}img{border-radius:22px}h1{font-size:32px;line-height:1.15}a{color:#007aff}p{opacity:.8}</style></head><body data-satin-install-page><main><img src="${escape(icon.src)}" width="96" height="96" alt=""><h1>${escape(title)}</h1>${body}</main>${scripts}</body></html>`;
+}

package/dist/app/installCheck.d.ts

@@ -0,0 +1,2 @@
+import { checkDeployment, type DeploymentExpectation } from './deployment.js';
+export declare function installPageCheck(expected: DeploymentExpectation, check: typeof checkDeployment, requestTimeoutMs?: number, onPass?: () => void): Promise<void>;

package/dist/app/installCheck.js

@@ -0,0 +1,148 @@
+import { checkDeployment, } from './deployment.js';
+// All dependencies are passed in because this runs before any application modules.
+export async function installPageCheck(expected, check, requestTimeoutMs = 4000, 
+// Called once the check passes; a custom install page loads the author's code here.
+onPass) {
+    const guide = document.getElementById('satin-install-guide');
+    const status = document.getElementById('satin-install-check');
+    const standalone = matchMedia('(display-mode: standalone)').matches ||
+        navigator.standalone === true;
+    const pageUrl = new URL(location.href);
+    const local = ['localhost', '127.0.0.1', '[::1]'].includes(pageUrl.hostname);
+    const insecure = pageUrl.protocol !== 'https:' && !(local && pageUrl.protocol === 'http:');
+    const failures = standalone
+        ? []
+        : insecure
+            ? [
+                {
+                    reason: 'HTTPS is required for installation and service workers.',
+                    url: location.href,
+                    fix: 'Serve the app over trusted HTTPS.',
+                },
+            ]
+            : await check(expected, location.href, fetch, false, undefined, requestTimeoutMs);
+    const manifestLink = document.querySelector('link[rel="manifest"]');
+    if (!standalone &&
+        !insecure &&
+        (!manifestLink ||
+            new URL(manifestLink.href).origin !== location.origin ||
+            !expected.manifests.includes(new URL(manifestLink.href).pathname))) {
+        failures.unshift({
+            reason: 'The page manifest link does not match this build.',
+            url: manifestLink?.href ?? location.href,
+            fix: 'Rebuild and deploy the complete dist directory at the configured Vite base.',
+            check: 'Manifest link',
+            status: 'Does not match this build',
+        });
+    }
+    const directoryPath = (pathname) => pathname.replace(/\/index\.html$/, '/').replace(/\/$/, '');
+    const route = directoryPath(location.pathname);
+    const installRoute = directoryPath(expected.installRoute);
+    const wrongBase = route !== installRoute;
+    const installSuffix = installRoute.slice(expected.base.length);
+    const servedBase = route.endsWith(installSuffix)
+        ? route.slice(0, -installSuffix.length)
+        : location.pathname;
+    if (!failures.length && !wrongBase && !standalone) {
+        status.removeAttribute('data-error');
+        status.removeAttribute('role');
+        status.replaceChildren();
+        status.hidden = true;
+        status.style.display = 'none';
+        guide.hidden = false;
+        onPass?.();
+        return;
+    }
+    guide.hidden = true;
+    status.hidden = false;
+    status.style.removeProperty('display');
+    status.replaceChildren();
+    status.setAttribute('role', 'alert');
+    status.dataset.error = 'true';
+    const style = document.createElement('style');
+    style.textContent = `
+    #satin-install-check[data-error] {
+      position: fixed;
+      inset: 0;
+      z-index: 20002;
+      display: grid;
+      place-items: center;
+      overflow: auto;
+      padding: 32px;
+      box-sizing: border-box;
+      background: #f2f2f7;
+      color: #1c1c1e;
+      color-scheme: light dark;
+      font: 17px/1.45 -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+      text-align: center;
+    }
+    #satin-install-check button { font: inherit; border: 0; background: transparent; color: #007aff; min-height: 44px; cursor: pointer; }
+    #satin-install-check .install-error-content { width: min(100%, 560px); }
+    #satin-install-check h2 { font-size: 24px; margin: 0 0 12px; }
+    #satin-install-check p { opacity: 1; margin: 12px 0; }
+    #satin-install-check .install-error-detail {
+      font-size: 13px;
+      color: #6c6c70;
+      overflow-wrap: anywhere;
+    }
+    #satin-install-check ul { list-style: none; padding: 0; margin: 24px 0 0; }
+    #satin-install-check li { margin: 8px 0; font-size: 13px; overflow-wrap: anywhere; }
+    @media (prefers-color-scheme: dark) {
+      #satin-install-check[data-error] { background: #000; color: #fff; }
+      #satin-install-check .install-error-detail { color: #aeaeb2; }
+    }
+  `;
+    document.head.append(style);
+    const content = document.createElement('div');
+    content.className = 'install-error-content';
+    const title = document.createElement('h2');
+    const unverified = !wrongBase && failures.length > 0 && failures.every(failure => failure.transient);
+    title.textContent = standalone
+        ? 'Wrong Home Screen icon'
+        : unverified
+            ? 'Could not verify this app'
+            : 'This app is misconfigured';
+    const explanation = document.createElement('p');
+    const action = document.createElement('p');
+    content.append(title, explanation, action);
+    status.append(content);
+    for (const failure of failures) {
+        console.error('[Satin deployment]', failure.reason, failure.url, failure.fix);
+    }
+    if (standalone) {
+        explanation.textContent = 'This icon opens the install page instead of the app.';
+        action.textContent = 'Delete this icon, then reinstall from Safari.';
+        const detail = document.createElement('p');
+        detail.className = 'install-error-detail';
+        detail.textContent = location.href;
+        content.append(detail);
+        return;
+    }
+    if (unverified) {
+        explanation.textContent = 'The connection may be slow or offline.';
+        action.textContent = 'Try again when your connection is ready.';
+        const retry = document.createElement('button');
+        retry.textContent = 'Retry';
+        retry.addEventListener('click', () => {
+            void installPageCheck(expected, check, 30_000, onPass);
+        });
+        content.append(retry);
+        return;
+    }
+    explanation.textContent = wrongBase
+        ? `Built for ${expected.base} but served at ${servedBase}.`
+        : 'Required app files are missing or do not match this build.';
+    action.textContent = wrongBase
+        ? `Serve this build at ${expected.base}, or rebuild with Vite base ${servedBase}.`
+        : failures[0].fix;
+    const checks = document.createElement('ul');
+    checks.setAttribute('aria-label', 'Failed checks');
+    for (const failure of failures) {
+        const row = document.createElement('li');
+        const url = new URL(failure.url, location.href);
+        const address = url.origin === location.origin ? url.pathname + url.search : url.href;
+        row.textContent = `${failure.check ?? 'Configuration'} → ${address} → ${failure.status ?? failure.reason}`;
+        checks.append(row);
+    }
+    content.append(checks);
+}

package/dist/app/installContext.d.ts

@@ -0,0 +1,35 @@
+/**
+ * What a custom install page needs to know (public through `@satinhq/kit/install`). Every value is
+ * read from the browser as it is; nothing is inferred. In particular "installed" is only the
+ * standalone display mode: a Safari tab cannot tell whether the app is on the Home Screen.
+ */
+export type InstallDevice = 'iphone' | 'ipad' | 'other';
+export type InstallBrowser = 'safari' | 'in-app' | 'other';
+export interface InstallApp {
+    readonly name: string;
+    readonly icon: string;
+    /** The app's tint (appearance.tint, or the system blue). */
+    readonly tint: string;
+    /** The absolute address of the install page, for a QR code or Copy Link. */
+    readonly installUrl: string;
+}
+export interface InstallContext {
+    readonly device: InstallDevice;
+    readonly browser: InstallBrowser;
+    /** Safari's major version (27 for Safari 27), or null in any other browser. */
+    readonly safariVersion: number | null;
+    /** True when running as a Home Screen web app (standalone display mode). */
+    readonly standalone: boolean;
+    readonly app: InstallApp;
+}
+export interface CopyLinkResult {
+    readonly copied: boolean;
+    /** The address, so a failure can show it for the person to select. */
+    readonly url: string;
+}
+export declare function classifyInstallDevice(userAgent: string, platform: string, maxTouchPoints: number): InstallDevice;
+export declare function classifyInstallBrowser(userAgent: string): InstallBrowser;
+export declare function safariVersion(userAgent: string): number | null;
+export declare function readInstallContext(): InstallContext;
+/** Copies the install page's address. Never throws: a refusal is reported with the address. */
+export declare function copyInstallLink(): Promise<CopyLinkResult>;

package/dist/app/installContext.js

@@ -0,0 +1,45 @@
+import { classifyInstallSignals } from './installPolicy.js';
+export function classifyInstallDevice(userAgent, platform, maxTouchPoints) {
+    return classifyInstallSignals(userAgent, platform, maxTouchPoints).device;
+}
+export function classifyInstallBrowser(userAgent) {
+    return classifyInstallSignals(userAgent, '', 0).browser;
+}
+export function safariVersion(userAgent) {
+    return classifyInstallSignals(userAgent, '', 0).safariVersion;
+}
+function readApp() {
+    const element = document.getElementById('satin-install-context');
+    if (!element?.textContent)
+        throw new Error('@satinhq/kit/install is only available on the install page Satin builds (satinApp(app, { installPage })).');
+    const data = JSON.parse(element.textContent);
+    return {
+        name: data.name,
+        icon: data.icon,
+        tint: data.tint,
+        installUrl: new URL(data.installRoute, location.href).href,
+    };
+}
+export function readInstallContext() {
+    const { userAgent, platform, maxTouchPoints } = navigator;
+    const signals = classifyInstallSignals(userAgent, platform, maxTouchPoints);
+    return {
+        ...signals,
+        standalone: matchMedia('(display-mode: standalone)').matches ||
+            navigator.standalone === true,
+        app: readApp(),
+    };
+}
+/** Copies the install page's address. Never throws: a refusal is reported with the address. */
+export async function copyInstallLink() {
+    const url = readApp().installUrl;
+    try {
+        if (!navigator.clipboard?.writeText)
+            return { copied: false, url };
+        await navigator.clipboard.writeText(url);
+        return { copied: true, url };
+    }
+    catch {
+        return { copied: false, url };
+    }
+}

package/dist/app/installCustom.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Custom install pages (round ten): an app may replace Satin's install page with its own,
+ * entirely (`satinApp(app, { installPage: './src/Install.js' })`). Satin still owns the
+ * document around it: the head (manifest, icons, title, status bar), the deployment check and
+ * the app's context. The author's bundle is loaded only after the check passes, so a broken
+ * deploy shows Satin's loud failure and never the author's page.
+ */
+/**
+ * Loads the author's page once. Self-contained: embedded verbatim in the page and called by
+ * the deployment check when it passes (also after a Retry).
+ */
+export declare function installCustomMount(entry: string): void;
+export interface CustomInstallPageInput {
+    readonly head: string;
+    /** The deployment metadata and the check script, already serialized by install.ts. */
+    readonly scripts: string;
+    readonly name: string;
+    readonly icon: string;
+    readonly tint: string;
+    readonly installRoute: string;
+    readonly background: string;
+    readonly darkBackground: string;
+    readonly darkText: boolean;
+}
+export declare function customInstallPage(input: CustomInstallPageInput): string;

package/dist/app/installCustom.js

@@ -0,0 +1,55 @@
+/**
+ * Custom install pages (round ten): an app may replace Satin's install page with its own,
+ * entirely (`satinApp(app, { installPage: './src/Install.tsx' })`). Satin still owns the
+ * document around it: the head (manifest, icons, title, status bar), the deployment check and
+ * the app's context. The author's bundle is loaded only after the check passes, so a broken
+ * deploy shows Satin's loud failure and never the author's page.
+ */
+import { minifyInlineScripts } from './installExperience.js';
+const escape = (text) => text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('"', '&quot;');
+/**
+ * Loads the author's page once. Self-contained: embedded verbatim in the page and called by
+ * the deployment check when it passes (also after a Retry).
+ */
+export function installCustomMount(entry) {
+    if (document.querySelector('script[data-satin-install-author]'))
+        return;
+    const script = document.createElement('script');
+    script.type = 'module';
+    script.src = entry;
+    script.dataset.satinInstallAuthor = '';
+    document.body.append(script);
+}
+export function customInstallPage(input) {
+    const context = JSON.stringify({
+        name: input.name,
+        icon: input.icon,
+        tint: input.tint,
+        installRoute: input.installRoute,
+    }).replaceAll('<', '\\u003c');
+    // Without scripts neither the check nor the author's page can run, so the page states
+    // Satin's plain steps (the same words as the default page's no-script text).
+    const noScript = [
+        '<noscript><main class="satin-install-noscript">',
+        `<h1>Add ${escape(input.name)} to Home Screen</h1><ol>`,
+        '<li>In Safari, open the page menu, then tap Share.</li>',
+        '<li>Choose Add to Home Screen (under View More if needed).</li>',
+        '<li>Make sure Open as Web App is on, then tap Add.</li>',
+        '</ol></main></noscript>',
+    ].join('');
+    const style = [
+        `html{background:${input.background};color:#1c1c1e;font:17px/1.4 system-ui,-apple-system,sans-serif}`,
+        `@media(prefers-color-scheme:dark){html{background:${input.darkBackground};color:${input.darkText ? '#fff' : '#1c1c1e'}}}`,
+        'body{margin:0}.satin-install-noscript{max-width:420px;margin:72px auto;padding:24px}',
+    ].join('');
+    const page = [
+        `<!doctype html><html lang="en"><head>${input.head}<style>${style}</style></head>`,
+        '<body data-satin-install-page data-satin-install-custom>',
+        '<section id="satin-install-check" hidden></section><div id="satin-install-guide"></div>',
+        noScript,
+        `<script id="satin-install-context" type="application/json">${context}</script>`,
+        input.scripts,
+        '</body></html>',
+    ].join('');
+    return minifyInlineScripts(page);
+}

package/dist/app/installExperience.d.ts

@@ -0,0 +1,22 @@
+import type { AppDefinition } from './definition.js';
+import { GLYPHS, INSTALL_STRINGS, springEasing } from './installStrings.js';
+export { GLYPHS, INSTALL_STRINGS, springEasing };
+/**
+ * Minifies every inline script of the finished page with Vite's own minifier. The scripts
+ * are self-contained expressions, so renaming their locals cannot change what they do; the
+ * JSON data block has a `type` attribute and is left alone.
+ */
+/** Minifies every inline classic script (bare, or with only `data-` attributes). */
+export declare function minifyInlineScripts(html: string): string;
+export interface InstallExperienceInput {
+    readonly app: AppDefinition;
+    readonly base: string;
+    /** Everything install.ts already puts in the head before its style block. */
+    readonly head: string;
+    readonly kind: 'install' | 'gate';
+    /** The deployment check scripts, already serialized by install.ts. Empty for the gate. */
+    readonly scripts: string;
+    readonly installRoute: string;
+    readonly preview?: boolean;
+}
+export declare function installExperiencePage(input: InstallExperienceInput): string;