@satinhq/kit 0.1.0-beta.3 → 0.1.0-beta.4

package/dist/app/installCheck.js

@@ -3,6 +3,7 @@ import { checkDeployment, } from './deployment.js';
 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 environment = window.__SATIN_PRELAUNCH__;
     const guide = document.getElementById('satin-install-guide');
     const status = document.getElementById('satin-install-check');
     const standalone = matchMedia('(display-mode: standalone)').matches ||
@@ -50,100 +51,45 @@ onPass) {
         status.hidden = true;
         status.style.display = 'none';
         guide.hidden = false;
+        environment.recover();
         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');
+    status.hidden = true;
     const unverified = !wrongBase && failures.length > 0 && failures.every(failure => failure.transient);
-    title.textContent = standalone
+    for (const failure of failures)
+        console.error('[Satin deployment]', failure.reason, failure.url, failure.fix);
+    const title = standalone
         ? 'Wrong Home Screen icon'
         : unverified
             ? "Can't reach the app right now"
             : '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 = 'Check your connection and try again.';
-        action.remove();
-        const retry = document.createElement('button');
-        retry.textContent = 'Retry';
-        retry.addEventListener('click', () => {
-            retry.disabled = true;
-            void installPageCheck(expected, check, 30_000, onPass);
+    const reason = standalone
+        ? 'This icon opens the install page instead of the app. Reinstall from Safari.'
+        : unverified
+            ? 'Check your connection and try again.'
+            : wrongBase
+                ? `Built for ${expected.base} but served at ${servedBase}. Serve this build at ${expected.base}, or rebuild with Vite base ${servedBase}.`
+                : 'Required app files are missing or do not match this build. ' + failures[0].fix;
+    const detail = standalone
+        ? location.href
+        : unverified
+            ? undefined
+            : failures
+                .map(failure => {
+                const url = new URL(failure.url, location.href);
+                const address = url.origin === location.origin ? url.pathname + url.search : url.href;
+                return `${failure.check ?? 'Configuration'} → ${address} → ${failure.status ?? failure.reason}`;
+            })
+                .join('\n');
+    let retrying = false;
+    environment.error(reason, title, () => {
+        if (retrying)
+            return;
+        retrying = true;
+        void installPageCheck(expected, check, 30_000, onPass).finally(() => {
+            retrying = false;
         });
-        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);
+    }, detail);
 }

package/dist/app/installContext.d.ts

@@ -1,10 +1,9 @@
-/**
- * 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.
- */
+/** The device the install page is open on: `iphone`, `ipad` or `other`. */
 export type InstallDevice = 'iphone' | 'ipad' | 'other';
+/** The browser the install page is open in. `in-app` is a browser inside another app, which
+ * cannot add to the Home Screen. */
 export type InstallBrowser = 'safari' | 'in-app' | 'other';
+/** The app being installed: its name, icon, tint and install page address. */
 export interface InstallApp {
     readonly name: string;
     readonly icon: string;
@@ -13,6 +12,9 @@ export interface InstallApp {
     /** The absolute address of the install page, for a QR code or Copy Link. */
     readonly installUrl: string;
 }
+/** What a custom install page knows about where it is open: device, browser, Safari version,
+ * standalone mode and the app. A Safari tab cannot tell whether the app is already on the Home
+ * Screen. */
 export interface InstallContext {
     readonly device: InstallDevice;
     readonly browser: InstallBrowser;
@@ -22,6 +24,7 @@ export interface InstallContext {
     readonly standalone: boolean;
     readonly app: InstallApp;
 }
+/** Whether `copyInstallLink` copied the address, and the address itself. */
 export interface CopyLinkResult {
     readonly copied: boolean;
     /** The address, so a failure can show it for the person to select. */
@@ -30,6 +33,8 @@ export interface CopyLinkResult {
 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;
+/** Reads the install context from the browser. It throws outside the install page that
+ * `satinApp` builds. */
 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

@@ -20,6 +20,8 @@ function readApp() {
         installUrl: new URL(data.installRoute, location.href).href,
     };
 }
+/** Reads the install context from the browser. It throws outside the install page that
+ * `satinApp` builds. */
 export function readInstallContext() {
     const { userAgent, platform, maxTouchPoints } = navigator;
     const signals = classifyInstallSignals(userAgent, platform, maxTouchPoints);

package/dist/app/installCustom.js

@@ -18,6 +18,7 @@ export function installCustomMount(entry) {
     script.type = 'module';
     script.src = entry;
     script.dataset.satinInstallAuthor = '';
+    script.onerror = () => window.__SATIN_PRELAUNCH__?.error('The install page failed to load. Please retry.');
     document.body.append(script);
 }
 export function customInstallPage(input) {

package/dist/app/installExperience.js

@@ -217,66 +217,6 @@ html:not([data-ready]) [data-js], html[data-ready] [data-nojs], [data-copy-faile
 }
 html[data-env="gate"] .ix { max-width: 440px; margin: 0 auto; }
 
-/*
- * The deployment check's failure report keeps its words and gets the page's voice. The
- * check injects its own styles later, so each rule here starts at the body element to outrank them.
- */
-body:has(#satin-install-check[data-error]) :is(.ix-hero, .ix-pointer) { visibility: hidden; }
-/* Nested, so the long selector is written once. */
-body #satin-install-check {
-  &[data-error] {
-    padding: 32px 24px;
-    background: var(--bg);
-    color: var(--label);
-    font: inherit;
-  }
-  & .install-error-content::before {
-    content: "!";
-    display: grid;
-    place-items: center;
-    width: 44px;
-    height: 44px;
-    margin: 0 auto 16px;
-    border-radius: 50%;
-    background: #ff3b30;
-    color: #fff;
-    font-size: 26px;
-    font-weight: 700;
-    line-height: 1;
-  }
-  & .install-error-content:has(button)::before {
-    content: "?";
-    background: var(--third);
-  }
-  & h2 { font-size: 1.294rem; margin: 0 0 8px; }
-  & p { margin: 6px 0; color: var(--second); }
-  & p:nth-of-type(2) { color: var(--label); }
-  & button {
-    min-height: 50px;
-    margin-top: 20px;
-    padding: 0 36px;
-    border-radius: 25px;
-    background: var(--tint);
-    color: var(--on-tint);
-    font-weight: 600;
-  }
-  & ul {
-    margin-top: 24px;
-    padding: 4px 16px;
-    border-radius: 20px;
-    background: var(--fill);
-    text-align: left;
-  }
-  & li {
-    margin: 0;
-    padding: 10px 0;
-    color: var(--label);
-    font: 0.706rem/1.45 ui-monospace, SFMono-Regular, Menlo, monospace;
-  }
-  & li + li { border-top: 1px solid var(--hair); }
-  & .install-error-detail { color: var(--second); }
-}
-
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation: none !important; transition: none !important; }
 }

package/dist/app/installationFailure.d.ts

@@ -1,4 +1,5 @@
-/** A diagnostic installation failure recorded before app launch. */
+/** An installation failure recorded before the app launched: the build, the URL, the reason and
+ * whether the network failed. */
 export interface InstallationFailure {
     buildId: string;
     url: string;
@@ -6,7 +7,7 @@ export interface InstallationFailure {
     networkFailure: boolean;
     recordedAt?: number;
 }
-/** Reads the recorded installation failure for acceptance fixtures. */
+/** Reads the last recorded installation failure for an app scope, or null when there is none. */
 export declare function readInstallationFailure(scope: string): InstallationFailure | null;
 export declare function readInstallationSuccess(scope: string): {
     buildId: string;

package/dist/app/installationFailure.js

@@ -1,4 +1,4 @@
-/** Reads the recorded installation failure for acceptance fixtures. */
+/** Reads the last recorded installation failure for an app scope, or null when there is none. */
 export function readInstallationFailure(scope) {
     try {
         const value = JSON.parse(localStorage.getItem('satin-install-failure:' + scope) ?? 'null');

package/dist/app/launchScreen.d.ts

@@ -1,5 +1,6 @@
 import type { AppDefinition } from './definition.js';
-/** Serializable so the same slot paints before JavaScript modules load. */
+/** The launch screen's icon and optional label. The inline environment paints it before application JavaScript loads, so
+ * both must be plain strings. */
 export interface LaunchScreenSlot {
     readonly icon?: string;
     readonly label?: string;
@@ -7,10 +8,13 @@ export interface LaunchScreenSlot {
 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 declare const launchScreenCSS = "\n#satin-launch-screen {\n  position:fixed;\n  inset:calc(-1 * var(--satin-launch-excluded-top, 0px)) 0 0;\n  z-index:20000;\n  display:flex;\n  flex-direction:column;\n  align-items:center;\n  justify-content:center;\n  background:var(--satin-launch-background);\n  color:var(--satin-launch-ink);\n  font:17px system-ui;\n  pointer-events:none\n}\n#satin-launch-screen[hidden],#satin-launch-progress[hidden] {\n  display:none\n}\n.satin-launch-icon {\n  position:relative;\n  width:108px;\n  height:108px;\n  display:grid;\n  place-items:center\n}\n#satin-launch-screen>p {\n  position:absolute;\n  top:calc(50% + 54px);\n  margin:16px 0 0\n}\n.satin-launch-icon img {\n  border-radius:15px\n}\n#satin-launch-progress {\n  position:absolute;\n  inset:0;\n  width:108px;\n  height:108px;\n  transform:rotate(-90deg)\n}\n";
 export interface DownloadProgress {
     /** Monotonic response-header progress, independent of downloaded bytes. */
     activity?: number;
     readonly loaded: number;
     readonly total: number;
 }
+/** Closed-shadow styles. Inner !important declarations protect the host itself
+ * from author resets; descendants never participate in the app cascade. */
+export declare const prelaunchCSS = "\n:host {\n  all:initial !important;\n  display:block !important;\n  position:fixed !important;\n  inset:0 !important;\n  z-index:20004 !important;\n  opacity:1 !important;\n  visibility:visible !important;\n  transform:none !important;\n  filter:none !important;\n  clip-path:none !important;\n  overflow:visible !important;\n  pointer-events:none !important;\n  contain:none !important;\n  isolation:isolate !important;\n  color-scheme:light dark !important\n}\n* {\n  box-sizing:border-box\n}\n [hidden] {\n  display:none !important\n}\n\n#satin-launch-screen {\n  position:fixed;\n  inset:calc(-1 * var(--satin-launch-excluded-top, 0px)) 0 0;\n  z-index:20000;\n  display:flex;\n  flex-direction:column;\n  align-items:center;\n  justify-content:center;\n  background:var(--satin-launch-background);\n  color:var(--satin-launch-ink);\n  font:17px system-ui;\n  pointer-events:none\n}\n#satin-launch-screen[hidden],#satin-launch-progress[hidden] {\n  display:none\n}\n.satin-launch-icon {\n  position:relative;\n  width:108px;\n  height:108px;\n  display:grid;\n  place-items:center\n}\n#satin-launch-screen>p {\n  position:absolute;\n  top:calc(50% + 54px);\n  margin:16px 0 0\n}\n.satin-launch-icon img {\n  border-radius:15px\n}\n#satin-launch-progress {\n  position:absolute;\n  inset:0;\n  width:108px;\n  height:108px;\n  transform:rotate(-90deg)\n}\n#satin-launch-error {\n  position:fixed;\n  inset:0;\n  display:flex;\n  flex-direction:column;\n  align-items:center;\n  justify-content:center;\n  padding:32px;\n  background:var(--satin-launch-background);\n  color:var(--satin-launch-ink);\n  font:17px/1.45 system-ui;\n  text-align:center;\n  pointer-events:auto;\n  overflow:auto\n}\n#satin-launch-error h1 {\n  font-size:24px;\n  margin:0 0 12px\n}\n#satin-launch-error p {\n  max-width:420px;\n  margin:17px 0;\n  white-space:pre-wrap;\n  overflow-wrap:anywhere\n}\n#satin-launch-error .detail {\n  font-size:13px;\n  opacity:.65\n}\n#satin-launch-error button {\n  font:600 17px system-ui;\n  color:#007aff;\n  background:transparent;\n  border:0;\n  padding:16px 32px;\n  min-height:44px\n}\n";

package/dist/app/launchScreen.js

@@ -11,4 +11,107 @@ export function launchScreenMarkup(app) {
 // 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)}`;
+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)
+}
+`;
+/** Closed-shadow styles. Inner !important declarations protect the host itself
+ * from author resets; descendants never participate in the app cascade. */
+export const prelaunchCSS = `
+:host {
+  all:initial !important;
+  display:block !important;
+  position:fixed !important;
+  inset:0 !important;
+  z-index:20004 !important;
+  opacity:1 !important;
+  visibility:visible !important;
+  transform:none !important;
+  filter:none !important;
+  clip-path:none !important;
+  overflow:visible !important;
+  pointer-events:none !important;
+  contain:none !important;
+  isolation:isolate !important;
+  color-scheme:light dark !important
+}
+* {
+  box-sizing:border-box
+}
+ [hidden] {
+  display:none !important
+}
+${launchScreenCSS}#satin-launch-error {
+  position:fixed;
+  inset:0;
+  display:flex;
+  flex-direction:column;
+  align-items:center;
+  justify-content:center;
+  padding:32px;
+  background:var(--satin-launch-background);
+  color:var(--satin-launch-ink);
+  font:17px/1.45 system-ui;
+  text-align:center;
+  pointer-events:auto;
+  overflow:auto
+}
+#satin-launch-error h1 {
+  font-size:24px;
+  margin:0 0 12px
+}
+#satin-launch-error p {
+  max-width:420px;
+  margin:17px 0;
+  white-space:pre-wrap;
+  overflow-wrap:anywhere
+}
+#satin-launch-error .detail {
+  font-size:13px;
+  opacity:.65
+}
+#satin-launch-error button {
+  font:600 17px system-ui;
+  color:#007aff;
+  background:transparent;
+  border:0;
+  padding:16px 32px;
+  min-height:44px
+}
+`;

package/dist/app/launchScreenRuntime.d.ts

@@ -1,5 +1,21 @@
 import type { DownloadProgress } from './launchScreen.js';
-interface LaunchScreenController {
+export interface LaunchScreenController {
+    readonly version: 1;
+    stylesReady(): Promise<void>;
+    error(reason: string, title?: string, retry?: () => void, detail?: string): void;
+    recover(): void;
+    appearance(background: string, ink: string): void;
+    snapshot(): {
+        version: 1;
+        state: string;
+        error: string;
+        coverVisible: boolean;
+        ringVisible: boolean;
+        label: string | null;
+        offset: string;
+        box: number[];
+        background: string;
+    };
     progress(progress: DownloadProgress | null): void;
     updated(start?: 0 | 100): Promise<boolean>;
     complete(): Promise<boolean>;
@@ -7,13 +23,24 @@ interface LaunchScreenController {
     fail(onRetired: () => void): void;
     restore(): void;
 }
-export declare function installLaunchScreenRuntime(): LaunchScreenController;
+export interface PrelaunchOptions {
+    readonly markup: string;
+    readonly css: string;
+    readonly scope: string;
+    readonly background: string;
+    readonly darkBackground: string;
+    readonly darkInk: string;
+    readonly nonce?: string;
+    readonly cover?: boolean;
+}
+export declare function installLaunchScreenRuntime(options: PrelaunchOptions): LaunchScreenController;
+export declare function prelaunchController(): LaunchScreenController;
+export declare function showLaunchFailure(reason: string, title?: string): void;
 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. */
+/** Runs immediately after the inline environment, before application modules. */
 export declare function resumeAppliedUpdate(scope: string, buildId?: string): void;
-export {};