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

package/dist/actions/rowScrub.js

@@ -1,5 +1,4 @@
 import { cornerClipPath, roundedCornerPath } from '../shapes/corners.js';
-import { takeoverSample } from './swipeSpring.js';
 import { swipeEdge } from './types.js';
 // iOS 27 matched phone reference, light/dark, 1/2/3 actions, both edges:
 // color-mask width 60pt, gap 10pt, outer padding 10pt. Capsule 44pt layout / 42-43pt solid mask.
@@ -63,9 +62,16 @@ function inlineEntrance(distance, buttonWidth) {
     }
     return { scale, opacity };
 }
+/** A destructive takeover keeps the other actions visible and dimmed. Native tall
+ * Delete row (r3 receipts): More fades from 0.73 at 142pt revealed to 0.30 at 381pt. */
+function destructiveSecondaryOpacity(distance) {
+    return clamp(0.73 - ((0.73 - 0.3) / (381 - 142)) * (distance - 142));
+}
 /** Spatial fit of native's sequential capsule reveal. Rest interpolates the
- * contact pose into the fully revealed spring target; it is never a DOM writer. */
-export function swipeActionPose(position, index, count, takeover = 0, rest = 0, buttonWidth = 60, inline = false, allowsFullSwipe = false) {
+ * contact pose into the fully revealed spring target; it is never a DOM writer.
+ * A destructive takeover packs the other actions against the row and the primary
+ * fills the rest (native: primary = revealed - 80 on a tall two-action row). */
+export function swipeActionPose(position, index, count, takeover = 0, rest = 0, buttonWidth = 60, inline = false, allowsFullSwipe = false, destructive = false) {
     const distance = Math.abs(position);
     const open = swipeOpenWidth(count, buttonWidth);
     const excess = Math.max(0, distance - open);
@@ -77,15 +83,17 @@ export function swipeActionPose(position, index, count, takeover = 0, rest = 0,
     const entrance = inline ? inlineEntrance(localDistance + revealLead, buttonWidth) : undefined;
     const contactScale = entrance?.scale ?? revealScale(localDistance);
     const reveal = contactScale + (clamp(distance / open) - contactScale) * rest;
-    const spread = (((index + 0.5) * excess) / (count + 0.5)) * (1 - takeover);
+    const packed = destructive && index > 0 ? takeover * excess : 0;
+    const spread = (((index + 0.5) * excess) / (count + 0.5)) * (1 - takeover) + packed;
+    const opacity = (entrance?.opacity ?? contactScale) + (1 - (entrance?.opacity ?? contactScale)) * rest;
+    const takenOver = destructive ? destructiveSecondaryOpacity(distance) : 0;
     return {
         scale: reveal,
         spread,
-        opacity: ((entrance?.opacity ?? contactScale) + (1 - (entrance?.opacity ?? contactScale)) * rest) *
-            (index === 0 ? 1 : 1 - takeover),
+        opacity: index === 0 ? opacity : opacity * (1 - takeover) + takenOver * takeover,
         growth: index === 0
             ? (inline && allowsFullSwipe ? excess * (1 - takeover) : 0) +
-                takeover * Math.max(0, distance - buttonWidth - 20)
+                takeover * (destructive ? excess : Math.max(0, distance - buttonWidth - 20))
             : 0,
     };
 }
@@ -102,6 +110,7 @@ export function swipeActionTracks(primary, count, width, allowsFullSwipe) {
     const trailing = primary.parentElement?.dataset.satinSwipeTray === 'trailing';
     const inline = primary.closest('[data-satin-row-actions]')?.dataset.satinSwipeLabelLayout ===
         'inline';
+    const destructive = primary.dataset.satinSwipeRole === 'destructive';
     return buttons.flatMap((button, index) => {
         const buttonWidth = Number.parseFloat(getComputedStyle(button).width) || 60;
         const middleWidth = Math.max(1, buttonWidth - capsuleHeight(primary));
@@ -118,7 +127,7 @@ export function swipeActionTracks(primary, count, width, allowsFullSwipe) {
                     : count === 1 || raw === Infinity
                         ? 1
                         : progress * progress * (3 - 2 * progress));
-            return swipeActionPose(position, index, count, raw === Infinity ? takeover : takeover * (1 - rest), rest, buttonWidth, inline, allowsFullSwipe);
+            return swipeActionPose(position, index, count, raw === Infinity ? takeover : takeover * (1 - rest), rest, buttonWidth, inline, allowsFullSwipe, destructive);
         };
         return [
             {
@@ -208,15 +217,20 @@ export function presentedTakeover(primary, position) {
     const count = primary.parentElement?.children.length ?? 1;
     const inline = primary.closest('[data-satin-row-actions]')?.dataset.satinSwipeLabelLayout ===
         'inline';
-    const ordinary = inline ? Math.max(0, Math.abs(position) - swipeOpenWidth(count, buttonWidth)) : 0;
-    const expanded = Math.max(0, Math.abs(position) - buttonWidth - 20);
+    const excess = Math.max(0, Math.abs(position) - swipeOpenWidth(count, buttonWidth));
+    const ordinary = inline ? excess : 0;
+    // A destructive takeover grows only into the excess; inline rows grow that much
+    // before takeover too, so their caught takeover reads as none.
+    const expanded = primary.dataset.satinSwipeRole === 'destructive'
+        ? excess
+        : Math.max(0, Math.abs(position) - buttonWidth - 20);
     if (expanded <= ordinary)
         return 0;
     const matrix = new DOMMatrixReadOnly(getComputedStyle(middle).transform);
     const growth = (matrix.a - 1) * Math.max(1, buttonWidth - capsuleHeight(primary));
     return clamp((growth - ordinary) / (expanded - ordinary));
 }
-export function createRowScrub(host, source, content, initial, width, configuration) {
+export function createRowScrub(host, source, content, initial, width, configuration, contact) {
     if (!width || source.scrollWidth <= source.clientWidth)
         return undefined;
     const widths = swipeWidths(host);
@@ -234,34 +248,18 @@ export function createRowScrub(host, source, content, initial, width, configurat
         if (primary) {
             const edge = swipeEdge(configuration, side);
             const actions = swipeActionTracks(primary, edge.actions.length, width, edge.allowsFullSwipe);
-            const reducedMotion = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
-            const caught = initial ? presentedTakeover(primary, initial) : 0;
-            const state = { from: caught, target: caught, velocity: 0, started: performance.now() };
-            const threshold = fullSwipeThreshold(width, edge.actions.length, side, widths[side], host.dataset.satinSwipeLabelLayout === 'inline');
             const openWidth = swipeOpenWidth(edge.actions.length, widths[side]);
-            let previousRaw = Number.NaN;
+            let previousPosition = Number.NaN;
             let previousTakeover = Number.NaN;
             const update = (now, raw, position) => {
-                const sample = takeoverSample(state.from, state.target, state.velocity, (now - state.started) / 1000);
-                const target = edge.allowsFullSwipe && raw * sign >= threshold ? 1 : 0;
-                if (target !== state.target) {
-                    state.from = sample.position;
-                    state.velocity = sample.velocity;
-                    state.target = target;
-                    state.started = now;
-                }
-                // Both spring states advance across reversals, but the hidden tray has
+                // Both takeover springs advance across reversals, but the hidden tray has
                 // no pixels to update. Read the scroll source before either tray writes.
+                const takeover = contact.takeover(side, raw, now);
                 if (position * sign <= 0)
                     return;
-                const takeover = edge.actions.length === 1 && edge.allowsFullSwipe
-                    ? 1
-                    : reducedMotion
-                        ? target
-                        : Math.max(0, Math.min(1, sample.position));
-                if (raw === previousRaw && takeover === previousTakeover)
+                if (position === previousPosition && takeover === previousTakeover)
                     return;
-                previousRaw = raw;
+                previousPosition = position;
                 previousTakeover = takeover;
                 const rest = initial ? clamp(1 - Math.abs(raw - initialRaw) / openWidth) : 0;
                 for (const action of actions) {
@@ -279,10 +277,14 @@ export function createRowScrub(host, source, content, initial, width, configurat
     // WebKit owns touch arbitration and the scroll offset. Sample it once per
     // frame and present the row, trays, and fitted takeover together. Mixing a
     // compositor row with main-thread pills exposes every delayed main-thread frame.
+    // The contact maps the raw offset, so a takeover's anchor moves row and pills alike.
     let actionFrame = 0;
-    const flush = (now = performance.now()) => {
-        const raw = initialRaw + origin - source.scrollLeft;
-        const position = rowSwipePosition(raw, width, configuration, widths);
+    const rawPosition = () => initialRaw + origin - source.scrollLeft;
+    /** Present the current scroll sample. A release passes `evaluate: false`: lifting
+     * the finger cannot start a takeover that no frame has shown. */
+    const flush = (now = performance.now(), evaluate = true) => {
+        const raw = rawPosition();
+        const position = contact.present(raw, now, evaluate);
         Object.assign(content.style, contentFrame(position, initial ? 1 : 0));
         for (const update of actionUpdates)
             update(now, raw, position);
@@ -295,8 +297,8 @@ export function createRowScrub(host, source, content, initial, width, configurat
     paintActions(performance.now());
     return {
         flush,
-        rawPosition: () => initialRaw + origin - source.scrollLeft,
-        position: () => rowSwipePosition(initialRaw + origin - source.scrollLeft, width, configuration, widths),
+        rawPosition,
+        position: () => contact.present(rawPosition(), performance.now(), false),
         cancel: () => {
             cancelAnimationFrame(actionFrame);
             // Outside contact, the settled side's visibility belongs to the row CSS.

package/dist/actions/types.d.ts

@@ -1,7 +1,8 @@
 import type { ReactNode } from 'react';
 import type { SymbolName } from '../symbols/Symbol.js';
 import type { CornerShape } from '../shapes/corners.js';
-/** Shared by menus, context menus and row swipe actions. */
+/** An entry in a menu, context menu or swipe action list: a command, a titled section of
+ * entries, or a submenu. */
 export type Action = ActionItem | Readonly<{
     section: readonly Action[];
     label?: string;
@@ -13,7 +14,8 @@ export type Action = ActionItem | Readonly<{
     disabled?: boolean;
     submenu: readonly Action[];
 }>;
-/** A leaf command shared by menus, swipe actions, alerts and confirmation dialogs. */
+/** A single command with an id, a label, an optional symbol and role, and an `onPress` handler.
+ * Menus, swipe actions, alerts and confirmation dialogs all use it. */
 export type ActionItem = Readonly<{
     id: string;
     label: string;
@@ -27,7 +29,8 @@ export type ActionItem = Readonly<{
     onPress?: (() => void) | (() => Promise<void>);
     tint?: string;
 }>;
-/** A swipe command may omit its visible title while retaining an accessible name. */
+/** A swipe action command. It may drop its visible label if it has a symbol or icon and an
+ * `accessibilityLabel`. */
 export type SwipeActionItem = ActionItem | Readonly<Omit<ActionItem, 'label' | 'accessibilityLabel'> & {
     label?: never;
     accessibilityLabel: string;
@@ -36,18 +39,21 @@ export type SwipeActionItem = ActionItem | Readonly<Omit<ActionItem, 'label' | '
 } | {
     icon: ReactNode;
 })>;
+/** An entry in a row's swipe actions: any menu entry, or a swipe command that shows only a
+ * symbol. */
 export type SwipeAction = Action | SwipeActionItem;
-/** `swipeActions`: one or more edge configurations for a row. */
+/** The `swipeActions` prop of a row: actions for one edge, or a list with one entry per edge. */
 export type SwipeActions = SwipeActionsConfiguration | readonly SwipeActionsConfiguration[];
-/** Swipe actions on one row edge. Full swipe is enabled unless explicitly disabled. */
+/** The swipe actions on one row edge, `trailing` by default. A full swipe runs the first action
+ * unless `allowsFullSwipe` is false. */
 export type SwipeActionsConfiguration = Readonly<{
     edge?: 'leading' | 'trailing';
-    /** Revealed row face. Omit for the native default; custom shapes are unrestricted. */
+    /** The shape of the revealed row face. Omit it for the system default. */
     shape?: CornerShape;
     allowsFullSwipe?: boolean;
     actions: readonly SwipeAction[];
 }>;
-/** `contextMenu`: row commands and an optional preview. */
+/** The `contextMenu` prop of a row: a list of actions, or actions with a custom `preview`. */
 export type ContextMenuConfiguration = readonly Action[] | Readonly<{
     actions: readonly Action[];
     preview?: ReactNode;

package/dist/app/InstallComponents.d.ts

@@ -1,12 +1,9 @@
 import { type InstallContext } from './installContext.js';
-/**
- * Optional building blocks for a custom install page (public through `@satinhq/kit/install`): the
- * context hook, the steps list and the tip, with the default page's words and look. Styles
- * are scoped to `satin-` classes; `--satin-install-tint` overrides the app's tint.
- */
-/** The install context, read once on the page (it does not change while the page is open). */
+/** Returns the install context, read once when the page opens. It throws outside the install
+ * page. */
 export declare function useInstallContext(): InstallContext;
-/** The three steps, in the words of Satin's page, for this device, browser and Safari layout. */
+/** The three install steps for this device, browser and Safari layout, worded as on Satin's own
+ * install page. */
 export declare function InstallSteps(): import("react").JSX.Element;
 /**
  * The tip at Safari's real control ("Page Menu, then Share" or "Share"), in Satin's glass.

package/dist/app/InstallComponents.js

@@ -6,12 +6,11 @@ import { deviceTokens } from './installExperienceDevice.js';
 import { TIP_GLASS } from './installExperienceHome.js';
 import { readInstallContext } from './installContext.js';
 import { classifySafariBar, tipPath } from './installTipPath.js';
-/**
- * Optional building blocks for a custom install page (public through `@satinhq/kit/install`): the
- * context hook, the steps list and the tip, with the default page's words and look. Styles
- * are scoped to `satin-` classes; `--satin-install-tint` overrides the app's tint.
- */
-/** The install context, read once on the page (it does not change while the page is open). */
+// Optional building blocks for a custom install page (public through `@satinhq/kit/install`): the
+// context hook, the steps list and the tip, with the default page's words and look. Styles
+// are scoped to `satin-` classes; `--satin-install-tint` overrides the app's tint.
+/** Returns the install context, read once when the page opens. It throws outside the install
+ * page. */
 export function useInstallContext() {
     const [context] = useState(readInstallContext);
     return context;
@@ -52,7 +51,8 @@ function useAppTint(context) {
         document.documentElement.style.setProperty('--satin-app-tint', context.app.tint);
     }, [context.app.tint]);
 }
-/** The three steps, in the words of Satin's page, for this device, browser and Safari layout. */
+/** The three install steps for this device, browser and Safari layout, worded as on Satin's own
+ * install page. */
 export function InstallSteps() {
     const context = useInstallContext();
     const bar = useSafariBar(context);

package/dist/app/InstallationDiagnostics.d.ts

@@ -3,5 +3,6 @@ export { readInstallationFailure, type InstallationFailure } from './installatio
 export type InstallationDiagnosticsProps = {
     scope: string;
 };
-/** Installation receipts for an optional Settings diagnostics screen. Use the app's scope. */
+/** Shows the app's installation receipts, for an optional diagnostics screen in Settings. Pass the
+ * app's scope. */
 export declare function InstallationDiagnostics({ scope }: InstallationDiagnosticsProps): import("react").JSX.Element;

package/dist/app/InstallationDiagnostics.js

@@ -3,7 +3,8 @@ import { useEffect, useState } from 'react';
 import { NavigationRow, Section, ValueRow } from '../list-form/ListForm.js';
 import { readInstallationFailure, readInstallationSuccess } from './installationFailure.js';
 export { readInstallationFailure } from './installationFailure.js';
-/** Installation receipts for an optional Settings diagnostics screen. Use the app's scope. */
+/** Shows the app's installation receipts, for an optional diagnostics screen in Settings. Pass the
+ * app's scope. */
 export function InstallationDiagnostics({ scope }) {
     const [failure, setFailure] = useState(() => readInstallationFailure(scope));
     const [success, setSuccess] = useState(() => readInstallationSuccess(scope));

package/dist/app/appearance.d.ts

@@ -2,7 +2,8 @@ import { type PreferredColorScheme } from './appearanceStore.js';
 export declare const readDarkAppearance: () => boolean;
 export declare const subscribeAppearance: (listener: () => void) => () => void;
 export declare function useDarkAppearance(): boolean;
-/** Bounded trait and lifecycle log for installed-runtime resume diagnostics. */
+/** Returns a short log of appearance changes and lifecycle events, for diagnosing appearance
+ * after a resume. */
 export declare const readAppearanceDiagnostics: () => readonly Readonly<{
     at: number;
     event: string;
@@ -12,7 +13,8 @@ export declare const readAppearanceDiagnostics: () => readonly Readonly<{
     eventDark?: boolean;
     heldDark: boolean;
 }>[];
-/** Set this installed scene's appearance. System or null resumes the retained system trait.
- * Store a user's choice with useAppStorage; the override itself lasts for this document. */
+/** Forces the whole app into `light` or `dark`. `system` or null follows the system again. The
+ * override lasts until the page reloads, so store the user's choice with `useAppStorage` and
+ * apply it at launch. */
 export declare function preferredColorScheme(scheme: PreferredColorScheme): void;
 export type { PreferredColorScheme };

package/dist/app/appearance.js

@@ -6,10 +6,12 @@ export const subscribeAppearance = (listener) => store().subscribe(listener);
 export function useDarkAppearance() {
     return useSyncExternalStore(subscribeAppearance, readDarkAppearance, () => false);
 }
-/** Bounded trait and lifecycle log for installed-runtime resume diagnostics. */
+/** Returns a short log of appearance changes and lifecycle events, for diagnosing appearance
+ * after a resume. */
 export const readAppearanceDiagnostics = () => store().getDiagnostics();
-/** Set this installed scene's appearance. System or null resumes the retained system trait.
- * Store a user's choice with useAppStorage; the override itself lasts for this document. */
+/** Forces the whole app into `light` or `dark`. `system` or null follows the system again. The
+ * override lasts until the page reloads, so store the user's choice with `useAppStorage` and
+ * apply it at launch. */
 export function preferredColorScheme(scheme) {
     store().setPreferredColorScheme(scheme);
 }

package/dist/app/appearanceStore.d.ts

@@ -1,10 +1,11 @@
-/** `preferredColorScheme`: a whole-scene appearance override, or system appearance. */
+/** An appearance override for the whole app: `light`, `dark`, or `system` (or null) to follow the
+ * system. */
 export type PreferredColorScheme = 'light' | 'dark' | 'system' | null;
 export type AppearanceSnapshot = Readonly<{
     dark: boolean;
     pending: boolean;
 }>;
-/** A diagnostic appearance event and its observed state. */
+/** One entry in the appearance diagnostics log: what happened and the appearance seen then. */
 export type AppearanceEvent = Readonly<{
     at: number;
     event: string;

package/dist/app/buildInfo.d.ts

@@ -1,11 +1,11 @@
-/** Identity embedded in the running app's JavaScript bundle. The app build ID is
- * a unique build identifier, not a git revision or the service worker's cache hash. */
+/** The framework version, build id, build time and build kind baked into the running bundle.
+ * The build id is unique per build. */
 export type BuildInfo = Readonly<{
     frameworkVersion: string;
     appBuildId: string;
     builtAt: string | null;
     buildKind: 'development' | 'production' | 'unavailable';
 }>;
-/** The build loaded by this app, including offline launches. Metadata comes from
- * satinApp at build time; it never reads the server's latest deployment. */
+/** Returns the build that is running, even offline. The values are written by `satinApp` at
+ * build time; it never asks the server for the latest deployment. */
 export declare function useBuildInfo(): BuildInfo;

package/dist/app/buildInfo.js

@@ -5,8 +5,8 @@ const buildInfo = Object.freeze(import.meta.env
     builtAt: null,
     buildKind: 'unavailable',
 });
-/** The build loaded by this app, including offline launches. Metadata comes from
- * satinApp at build time; it never reads the server's latest deployment. */
+/** Returns the build that is running, even offline. The values are written by `satinApp` at
+ * build time; it never asks the server for the latest deployment. */
 export function useBuildInfo() {
     return buildInfo;
 }

package/dist/app/definition.d.ts

@@ -2,14 +2,18 @@ import type { ViewportFitPolicy } from './viewportValue.js';
 import type { LaunchScreenSlot } from './launchScreen.js';
 import type { ServerReachabilityConfig } from '../reachability/model.js';
 declare const DEFINITION: unique symbol;
-/** A declared app capability that requires framework-owned runtime support. */
+/** A capability the app declares so Satin sets up its runtime support: `push`, `badging` or
+ * `background-work`. */
 export type AppCapability = 'badging' | 'background-work' | 'push';
 /** An orientation that the app supports. */
 export type AppOrientation = 'landscape' | 'portrait';
-/** The presentation policy when the window uses an unsupported orientation. */
+/** What the app shows when the device is in an orientation it does not support: a rotation
+ * prompt, a letterboxed layout, a responsive layout, or nothing. */
 export type OrientationFallback = 'letterbox' | 'none' | 'rotation-overlay' | 'responsive';
-/** When a prepared app update may activate. */
+/** When a downloaded update may apply: `cold-launch`, the default, or `cold-launch-or-explicit`,
+ * which also lets it apply on request, as the development menu does. */
 export type UpdateActivation = 'cold-launch' | 'cold-launch-or-explicit';
+/** One generated app icon file: its URL, pixel sizes, image type and purpose. */
 export interface AppIcon {
     readonly purpose?: 'any' | 'maskable' | 'monochrome';
     readonly sizes: string;
@@ -72,12 +76,16 @@ export type AppDeploymentInput = AppDeploymentOptions & ({
     readonly connectivity: 'server';
     readonly reachability: ServerReachabilityConfig;
 });
+/** A validated app definition, returned by `defineApp`. Pass it to `runApp` and to the Vite
+ * plugin. */
 export type AppDefinition = AppDeploymentInput & {
     readonly [DEFINITION]: true;
 };
 export interface SatinAppShellPluginOptions {
     readonly additionalPrecache: readonly string[];
 }
+/** Validates a full app definition and fills in its defaults. `defineApp` uses it; lab fixtures
+ * call it directly. */
 export declare function defineSatinApp(input: AppDeploymentInput): AppDefinition;
 export declare function generateSatinManifestJson(definition: AppDefinition, idiom?: 'phone' | 'pad'): string;
 export declare function generatePreReactAppearanceScript(definition: AppDefinition): string;

package/dist/app/definition.js

@@ -185,6 +185,8 @@ function cloneReachability(value) {
         surfaces: Object.freeze({ ...value.surfaces }),
     });
 }
+/** Validates a full app definition and fills in its defaults. `defineApp` uses it; lab fixtures
+ * call it directly. */
 export function defineSatinApp(input) {
     assertRecord(input, 'app');
     assertString(input.id, 'id');

package/dist/app/head.d.ts

@@ -1,5 +1,6 @@
 import type { AppDefinition } from './definition.js';
 export { appManifestStem, appManifestFiles } from './manifests.js';
+/** One app definition in a multi-install lab build, chosen by exact query parameters. */
 export interface AppFixture {
     /** Legacy display-mode capability rig only, never a production option. */
     readonly display?: 'standalone' | 'fullscreen' | 'minimal-ui';
@@ -7,4 +8,4 @@ export interface AppFixture {
     /** 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;
+export declare function generateAppHead(fixtures: readonly AppFixture[], base: string, production?: boolean, devServer?: boolean, covers?: ReadonlyMap<string, string>, buildId?: string): string;

package/dist/app/head.js

@@ -1,18 +1,18 @@
 import { registerEarlyWorker } from './earlyWorker.js';
 import { deploymentExpectation } from './deployment.js';
 import { installLaunchWatchdog } from './launchWatchdog.js';
-import { installLaunchScreenRuntime } from './launchScreenRuntime.js';
+import { installLaunchScreenRuntime, resumeAppliedUpdate } 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 { launchScreenMarkup, prelaunchCSS } 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) {
+export function generateAppHead(fixtures, base, production = true, devServer = false, covers = new Map(), buildId) {
     const appearance = fixtures[0]?.app.appearance;
     const lightBackground = appearance?.background ?? '#ffffff';
     const darkBackground = appearance?.darkLaunch === 'match-light'
@@ -20,6 +20,7 @@ export function generateAppHead(fixtures, base, production = true, devServer = f
         : (appearance?.darkLaunch.background ?? '#000000');
     const data = JSON.stringify(fixtures.map(({ app, query }) => ({
         app,
+        cover: covers.get(app.id) ?? launchScreenMarkup(app),
         query,
         installRoute: installRouteForBase(app, base),
         startupStem: appManifestStem(app),
@@ -27,7 +28,7 @@ export function generateAppHead(fixtures, base, production = true, devServer = f
     }))).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>
+    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}}}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};
@@ -68,7 +69,13 @@ export function generateAppHead(fixtures, base, production = true, devServer = f
  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()})();
+ (${installLaunchScreenRuntime.toString()})({
+  markup: selected.cover, css: ${JSON.stringify(prelaunchCSS)}, scope: app.scope,
+  background: app.appearance.background,
+  darkBackground: app.appearance.darkLaunch === 'match-light' ? app.appearance.background : app.appearance.darkLaunch.background,
+  darkInk: app.appearance.darkLaunch === 'match-light' ? '#1c1c1e' : '#ffffff'
+ });
+ (${resumeAppliedUpdate.toString()})(app.scope, app.updateProfile === 'release' ? ${JSON.stringify(buildId)} : undefined);
  (${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.
@@ -89,18 +96,7 @@ export function generateAppHead(fixtures, base, production = true, devServer = f
  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;
@@ -109,6 +105,7 @@ export function generateAppHead(fixtures, base, production = true, devServer = f
   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);
+  window.__SATIN_PRELAUNCH__.appearance(appearance.background, dark ? darkInk : '#1c1c1e');
   document.getElementById('satin-theme-color').content = appearance.background;
   document.getElementById('satin-manifest').href = ${appManifestHrefExpression('selected.manifest')};
  };

package/dist/app/inlineCSP.d.ts

@@ -0,0 +1,6 @@
+/** Add these sources to a deployment's existing policy. Satin does not impose
+ * a site-wide CSP. Hashes cover exact final bytes, including the shadow style. */
+export declare function inlinePolicySources(html: string, shadowStyle: string): {
+    scriptSrc: string[];
+    styleSrc: string[];
+};

package/dist/app/inlineCSP.js

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+/** Add these sources to a deployment's existing policy. Satin does not impose
+ * a site-wide CSP. Hashes cover exact final bytes, including the shadow style. */
+export function inlinePolicySources(html, shadowStyle) {
+    const digest = (value) => `'sha256-${createHash('sha256').update(value).digest('base64')}'`;
+    const scripts = new Set();
+    const styles = new Set([digest(shadowStyle)]);
+    for (const match of html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/gi)) {
+        if (/\b(?:src|type\s*=\s*["']application\/json)/i.test(match[1]) || !match[2].trim())
+            continue;
+        scripts.add(digest(match[2]));
+        // Platform admission reinserts the original parser script. A hash policy
+        // must admit that script as well as the small admission wrapper.
+        const original = match[2].match(/const script = ("(?:[^"\\]|\\.)*");/);
+        if (original) {
+            const tag = JSON.parse(original[1]);
+            const body = tag.match(/<script\b([^>]*)>([\s\S]*?)<\/script>/i);
+            if (body && !/\bsrc\s*=/.test(body[1]) && body[2].trim())
+                scripts.add(digest(body[2]));
+        }
+    }
+    for (const match of html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi))
+        styles.add(digest(match[1]));
+    return { scriptSrc: [...scripts], styleSrc: [...styles] };
+}

package/dist/app/install.d.ts

@@ -11,6 +11,7 @@ export declare function appManifestHrefExpression(stemExpression: string): strin
 export declare function installRouteForBase(app: AppDefinition, base: string): string;
 /** Preview builds accept device/layout overrides; production never does. */
 export interface InstallPageOptions {
+    readonly cover?: string;
     readonly preview?: boolean;
     /** The author's bundled install page, set by satinApp(app, { installPage }). */
     readonly customPage?: string;

package/dist/app/install.js

@@ -1,3 +1,5 @@
+import { installLaunchScreenRuntime } from './launchScreenRuntime.js';
+import { launchScreenMarkup, prelaunchCSS } from './launchScreen.js';
 import { resolveDeviceIdiom } from '../layout/deviceIdiom.js';
 import { checkDeployment, deploymentExpectation } from './deployment.js';
 import { installPageCheck } from './installCheck.js';
@@ -48,12 +50,13 @@ export function installPage(app, kind, base = '/', options = {}) {
                 .join('') +
             '</noscript>'
         : '';
-    const startup = `<script src="${app.scope}${stem}-startup.js"></script>${fallback}`;
+    const startup = `<script defer 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>` : ''}`;
+    const environment = `<script id="satin-prelaunch-install">(${installLaunchScreenRuntime.toString()})(${JSON.stringify({ markup: options.cover ?? launchScreenMarkup({ ...app, launchScreen: { icon: 'data:,' } }), css: prelaunchCSS, scope: app.scope, background: app.appearance.background, darkBackground: dark, darkInk: app.appearance.darkLaunch === 'match-light' ? '#1c1c1e' : '#fff', cover: false }).replaceAll('<', '\\u003c')});</script>`;
+    const scripts = `${kind === 'install' ? environment : ''}<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);window.__SATIN_PRELAUNCH__.error("Configuration check failed. Reload and check the console.","This app is misconfigured");document.getElementById("satin-install-guide").hidden=true})</script>` : ''}`;
     if (options.customPage && kind === 'install') {
         return customInstallPage({
             head,