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

package/dist/app/installExperience.js

@@ -0,0 +1,389 @@
+import { installSteps, serializeInstallPolicy } from './installPolicy.js';
+import { deviceTokens } from './installExperienceDevice.js';
+import { CSS_D, homeScene, homeStep, TIP_GLASS } from './installExperienceHome.js';
+import { installExperienceRuntime, } from './installExperienceRuntime.js';
+import { installQrMatrix } from './installQr.js';
+import { minifySync } from 'vite';
+import { GLYPHS, INSTALL_STRINGS, springEasing } from './installStrings.js';
+export { GLYPHS, INSTALL_STRINGS, springEasing };
+/**
+ * The install page as an experience: one screen, the app as the hero, and instructions that
+ * point at Safari's real control instead of showing a picture of it.
+ *
+ * The approved Mist Home Screen design is the default for install and gate pages.
+ */
+const SYSTEM_BLUE = { light: '#007aff', dark: '#0a84ff' };
+const escapeHtml = (text) => text.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('"', '&quot;');
+/** Black or white, whichever reads better on the given six-digit hex colour. */
+function labelOn(hex) {
+    const channel = (offset) => {
+        const value = Number.parseInt(hex.slice(offset, offset + 2), 16) / 255;
+        return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+    };
+    const luminance = 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
+    return luminance > 0.36 ? '#000' : '#fff';
+}
+/** Mixes two six-digit hex colours; `amount` is how much of the second one. */
+function mixHex(from, to, amount) {
+    const channel = (offset) => {
+        const start = Number.parseInt(from.slice(offset, offset + 2), 16);
+        const end = Number.parseInt(to.slice(offset, offset + 2), 16);
+        return Math.round(start + (end - start) * amount)
+            .toString(16)
+            .padStart(2, '0');
+    };
+    return `#${channel(1)}${channel(3)}${channel(5)}`;
+}
+/**
+ * The raised surface for grouped content on a given background, as the system pairs them:
+ * white on a light grouped background, light grey on white, and a lifted grey in the dark.
+ */
+function cardOn(background) {
+    if (labelOn(background) === '#fff')
+        return mixHex(background, '#ffffff', 0.11);
+    const nearWhite = mixHex(background, '#000000', 0.05) === mixHex('#ffffff', '#000000', 0.05);
+    return nearWhite ? '#f2f2f7' : mixHex(background, '#ffffff', 0.86);
+}
+/** A glyph from the inline symbol sheet. */
+const glyph = (name) => `<svg class="ix-g" aria-hidden="true"><use href="#ix-${name}"/></svg>`;
+/** Fills `{app}` and the glyph placeholders of one string. Glyphs get a spoken name. */
+function phrase(text, app) {
+    const spoken = (name) => (name ? `<span class="ix-sr">${name}</span>` : '');
+    return escapeHtml(text)
+        .replaceAll('{app}', `<bdi>${escapeHtml(app)}</bdi>`)
+        .replace('{menu}', spoken(INSTALL_STRINGS.menuName) + glyph('menu'))
+        .replace('{share}', spoken(INSTALL_STRINGS.shareName) + glyph('share'))
+        .replace('{home}', spoken(INSTALL_STRINGS.homeName) + glyph('home'))
+        .replaceAll('{device}', `<span data-device-name>${INSTALL_STRINGS.deviceAny}</span>`);
+}
+/** Joins markup fragments; lets long templates be written one element per line. */
+const join = (...parts) => parts.join('');
+/** The symbol sheet for one page: only the glyphs its markup uses. */
+function sprite(markup) {
+    const symbols = Object.entries(GLYPHS)
+        .filter(([name]) => markup.includes(`#ix-${name}"`))
+        .map(([name, drawing]) => `<symbol id="ix-${name}" viewBox="0 0 24 24">${drawing}</symbol>`);
+    return join('<svg class="ix-sprite" width="0" height="0" aria-hidden="true"><defs>', ...symbols, '</defs></svg>');
+}
+/** Foundation for the install experience: tokens, type scale, states, panels, failure styling. */
+function baseCss(colors) {
+    const darkPage = labelOn(colors.darkBackground) === '#fff';
+    return `
+:root {
+  color-scheme: light dark;
+  --bg: ${colors.background};
+  --card: ${cardOn(colors.background)};
+  ${deviceTokens(labelOn(colors.background) === '#fff')}
+  --label: ${labelOn(colors.background)};
+  --tint: ${colors.tint};
+  --on-tint: ${labelOn(colors.tint)};
+  --spring: ${springEasing()};
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: ${colors.darkBackground};
+    --card: ${cardOn(colors.darkBackground)};
+    ${deviceTokens(darkPage)}
+    --label: ${labelOn(colors.darkBackground)};
+    ${colors.darkTint === colors.tint ? '' : `--tint: ${colors.darkTint}; --on-tint: ${labelOn(colors.darkTint)};`}
+  }
+}
+:root {
+  --second: color-mix(in srgb, var(--label) 60%, transparent);
+  --third: color-mix(in srgb, var(--label) 30%, transparent);
+  --fill: color-mix(in srgb, var(--label) 6%, transparent);
+  --hair: color-mix(in srgb, var(--label) 14%, transparent);
+  --tint-soft: color-mix(in srgb, var(--tint) 15%, transparent);
+}
+html {
+  height: 100%;
+  background: var(--bg);
+  color: var(--label);
+  font: 17px/1.294 system-ui, -apple-system, sans-serif;
+  -webkit-text-size-adjust: 100%;
+  -webkit-tap-highlight-color: transparent;
+}
+@supports (-webkit-touch-callout: none) {
+  html { font: -apple-system-body; font-family: system-ui, -apple-system, sans-serif; }
+}
+body { height: 100%; min-height: 100lvh; margin: 0; overflow: hidden; }
+h1, h2, p, ol { margin: 0; padding: 0; }
+ol { list-style: none; }
+.ix {
+  box-sizing: border-box;
+  height: 100vh;
+  height: 100svh;
+  overflow-y: auto;
+  padding: 0 24px 96px;
+  padding-inline: max(24px, env(safe-area-inset-left)) max(24px, env(safe-area-inset-right));
+}
+.ix-sprite { position: absolute; }
+/*
+ * No fixed footer (round six): Safari 26 and later extend a fixed element at the bottom edge
+ * into the area under its floating toolbar as a flat colour, which cut the tip's shadow off in
+ * a hard line. The page's own background already reaches the screen's bottom.
+ */
+.ix-sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+.ix-g {
+  width: 1.3em;
+  height: 1.3em;
+  vertical-align: -0.3em;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.9;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+h1 { font-size: min(1.294rem, 34px); line-height: 1.27; font-weight: 700; letter-spacing: -0.01em; }
+.ix-about { color: var(--second); font-size: 0.882rem; line-height: 1.33; }
+h2 { font-size: min(1.294rem, 34px); line-height: 1.27; font-weight: 700; letter-spacing: -0.01em; text-wrap: balance; }
+.ix-foot { color: var(--second); font-size: 0.765rem; font-weight: 400; line-height: 1.38; }
+.ix-foot { margin-top: 20px; }
+.ix-hint { display: none; margin-top: 16px; font-size: 0.882rem; font-weight: 600; }
+html[data-state="back"] .ix-hint { display: block; }
+
+/* One panel at a time. Without the runtime the steps stay readable. */
+[data-panel], [data-for] { display: none; }
+html:not([data-env]) [data-panel="steps"],
+html[data-env="safari"] [data-panel="steps"],
+html[data-env="inapp"] [data-panel="inapp"],
+html[data-env="browser"] [data-panel="browser"],
+html[data-env="gate"] [data-panel="gate"] { display: block; }
+html:not([data-bar]) [data-for="any"],
+html[data-bar="unknown"] [data-for="any"],
+html[data-bar="compact"] [data-for="compact"],
+html[data-bar="toolbar"] [data-for="toolbar"],
+html[data-bar="top"] [data-for="toolbar"] { display: revert; }
+html:not([data-env="safari"]) .ix-pointer,
+html:not([data-bar]) .ix-pointer,
+html[data-bar="unknown"] .ix-pointer,
+html:not([data-ready]) .ix-pointer { display: none; }
+
+/* The deployment check runs silently; this element is only shown when it fails. */
+#satin-install-check { margin-top: 28px; color: var(--second); font-size: 0.882rem; }
+
+/* Buttons. */
+.ix-button {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.4em;
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 50px;
+  margin-top: 12px;
+  padding: 0 20px;
+  border: 0;
+  border-radius: 25px;
+  background: var(--tint);
+  color: var(--on-tint);
+  font: inherit;
+  font-weight: 600;
+  text-decoration: none;
+}
+.ix-button.ix-quiet { background: var(--fill); color: var(--tint); }
+.ix-button[data-copied]::after { content: " ✓"; }
+
+[data-panel] > p:not([class]) { margin-top: 8px; color: var(--second); }
+[data-panel] > .ix-button:first-of-type { margin-top: 24px; }
+
+/* Not an iPhone or iPad: hand the page over. Parts that need the script wait for it. */
+html:not([data-ready]) [data-js], html[data-ready] [data-nojs], [data-copy-failed][hidden] { display: none; }
+.ix-copy-failed { margin-top: 10px; color: var(--second); font-size: 0.882rem; }
+.ix-copy-failed .ix-address { display: block; margin-top: 4px; color: var(--label); }
+.ix-qr {
+  box-sizing: border-box;
+  width: 176px;
+  margin: 22px 0 16px;
+  padding: 10px;
+  border-radius: 22px;
+  background: #fff;
+  color: #000;
+  box-shadow: 0 0 0 1px var(--hair);
+}
+.ix-qr svg { display: block; }
+.ix-address {
+  font: 0.765rem/1.4 ui-monospace, SFMono-Regular, Menlo, monospace;
+  overflow-wrap: anywhere;
+  user-select: all;
+  -webkit-user-select: all;
+}
+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; }
+}
+`;
+}
+/** `rgb(255 255 255 / 0.36)` as `#ffffff5c`: the same colour in fewer bytes. */
+const hexColor = (_match, red, green, blue, alpha) => '#' +
+    [Number(red), Number(green), Number(blue), Math.round(Number(alpha) * 255)]
+        .map(channel => channel.toString(16).padStart(2, '0'))
+        .join('');
+const minifyCss = (css) => css
+    .replace(/rgb\((\d+) (\d+) (\d+) \/ ([\d.]+)\)/g, hexColor)
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\s+/g, ' ')
+    .replace(/\s*([{};,])\s*/g, '$1')
+    .replace(/:\s+/g, ':')
+    .replace(/(^|[^\d.])0\.(\d)/g, '$1.$2')
+    .replaceAll(';}', '}')
+    .trim();
+/**
+ * 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 function minifyInlineScripts(html) {
+    const inline = /<script((?:\s+data-[\w-]+(?:="[^"]*")?)*)>([\s\S]*?)<\/script>/g;
+    return html.replace(inline, (_tag, attributes, source) => {
+        const result = minifySync('install-page.js', source);
+        if (result.errors.length) {
+            throw new Error(`Satin could not minify an install page script: ${result.errors[0].message}`);
+        }
+        return `<script${attributes}>${result.code.trim()}</script>`;
+    });
+}
+/** One fragment per place Safari keeps Share; the runtime shows the one that applies. */
+function perBar(any, compact, toolbar) {
+    return join(`<span data-for="any">${any}</span>`, `<span data-for="compact">${compact}</span>`, `<span data-for="toolbar">${toolbar}</span>`);
+}
+function heroMarkup(name, about, icon, kind) {
+    const title = kind === 'gate'
+        ? 'This app is designed for iPhone and iPad'
+        : phrase(INSTALL_STRINGS.addTitle, name);
+    return `<header class="ix-hero">${homeScene(escapeHtml(icon))}<h1 class="ix-title">${title}</h1><p class="ix-about" dir="auto">${about}</p></header>`;
+}
+function stepsMarkup(app, browser = 'safari') {
+    const rows = (bar) => installSteps(browser, bar, INSTALL_STRINGS);
+    const content = (index, part) => {
+        const render = (bar) => {
+            const value = rows(bar)[index][part];
+            return part === 'symbol' ? glyph(value) : phrase(value, app);
+        };
+        return browser === 'safari' && index === 0 && part !== 'where'
+            ? perBar(render('unknown'), render('compact'), render('toolbar'))
+            : render('unknown');
+    };
+    return rows('unknown')
+        .map((_, index) => homeStep(content(index, 'symbol'), content(index, 'action'), index === 0 && browser === 'safari' ? '' : content(index, 'where')))
+        .join('');
+}
+export function installExperiencePage(input) {
+    const { app, kind } = input;
+    const text = (key) => phrase(INSTALL_STRINGS[key], app.name);
+    const dark = app.appearance.darkLaunch === 'match-light'
+        ? app.appearance.background
+        : app.appearance.darkLaunch.background;
+    const icons = app.icons.filter(icon => icon.type === 'image/png');
+    const largest = (icons.length ? icons : app.icons).reduce((best, icon) => Number.parseInt(icon.sizes, 10) > Number.parseInt(best.sizes, 10) ? icon : best);
+    const css = minifyCss(baseCss({
+        background: app.appearance.background,
+        darkBackground: dark,
+        tint: app.appearance.tint ?? SYSTEM_BLUE.light,
+        darkTint: app.appearance.tint ?? SYSTEM_BLUE.dark,
+    }) + CSS_D);
+    // The cue at Safari's real control. Concept a turns its first step into the cue instead.
+    const tip = join(`<span data-for="compact">${glyph('menu')}${text('tipMenu')}</span>`, `<span data-for="toolbar">${glyph('share')}${text('tipShare')}</span>`, TIP_GLASS);
+    const pointer = `<div class="ix-pointer" aria-hidden="true">${tip}</div>`;
+    const browserSteps = stepsMarkup(app.name, 'other');
+    const openSafari = (quiet) => `<a class="ix-button${quiet ? ' ix-quiet' : ''}" data-open-safari href="#">${text('openSafari')}</a>`;
+    // Copying needs the script and a clipboard that allows it. When it fails, the page says so
+    // and shows the address to select (the gate shows it already).
+    const copyLink = (withAddress) => join(`<button type="button" class="ix-button ix-quiet" data-js data-copy="${text('copied')}">`, `${text('copyLink')}</button>`, `<p class="ix-copy-failed" data-copy-failed hidden>${text('copyFailed')}`, withAddress ? '<span class="ix-address" data-address></span>' : '', '</p>');
+    // One panel per situation; the stylesheet shows the one the runtime selects. The lists
+    // carry an explicit role: Safari drops list semantics from lists styled without markers.
+    // Nothing the page observes ever replaces the steps: an install cannot be told apart from
+    // a cancelled dialog followed by leaving Safari, so "already added" is the person's call.
+    const stepsPanel = join('<div data-panel="steps">', `<ol class="ix-steps" role="list">${stepsMarkup(app.name)}</ol>`, `<p class="ix-hint" data-say="back">${text('backHint')}</p>`, `<p class="ix-foot">${text('alreadyAdded')}</p></div>`);
+    const inAppPanel = join(`<div data-panel="inapp"><h2>${text('inAppTitle')}</h2><p>${text('inAppBody')}</p>`, openSafari(false), copyLink(true), `<p class="ix-foot">${text('inAppFoot')}</p></div>`);
+    const browserPanel = join('<div data-panel="browser">', `<ol class="ix-steps" role="list">${browserSteps}</ol>`, openSafari(true), '</div>');
+    // Without scripts there is no code and no copying: the gate then asks for the address bar.
+    const gatePanel = join(`<div data-panel="gate"><h2>${text('gateTitle')}</h2>`, '<div class="ix-qr" data-qr data-js></div>', `<p data-js>${text('gateBody')}</p><p class="ix-address" data-address data-js></p>`, `<p data-nojs>${text('gateNoScript')}</p>`, copyLink(false), '</div>');
+    const liveRegion = '<p class="ix-sr" role="status" aria-live="polite" data-live></p>';
+    const panels = join(stepsPanel, inAppPanel, browserPanel, gatePanel, liveRegion);
+    const check = kind === 'install' ? '<section id="satin-install-check" hidden></section>' : '';
+    const config = {
+        installRoute: input.installRoute,
+        kind,
+        preview: input.preview === true,
+        devices: [INSTALL_STRINGS.devicePhone, INSTALL_STRINGS.devicePad],
+    };
+    const runtime = join(`<script>(${installExperienceRuntime.toString()})(`, `${JSON.stringify(config).replaceAll('<', '\\u003c')},`, `${installQrMatrix.toString()},${serializeInstallPolicy()})</script>`);
+    const gateAttribute = kind === 'gate' ? ' data-env="gate"' : '';
+    const rootAttributes = `lang="en" data-install-design="home-screen"${gateAttribute}`;
+    // The guide is the page's normal state from the first frame. The deployment check runs
+    // behind it and replaces it only on deployment failure.
+    const guideAttributes = 'id="satin-install-guide" class="ix-panels"';
+    const main = join(heroMarkup(app.name, escapeHtml(app.description), largest.src, kind), check, `<section ${guideAttributes}>${panels}</section>`, pointer);
+    const page = join(`<!doctype html><html ${rootAttributes}>`, `<head>${input.head}<style>${css}</style></head>`, `<body data-satin-install-page>${sprite(main)}<main class="ix">${main}</main>`, `${input.scripts}${runtime}</body></html>`);
+    return minifyInlineScripts(page);
+}

package/dist/app/installExperienceDevice.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Our own drawings of the lower part of an iPhone and an iPad showing a Home Screen, for the
+ * install page.
+ *
+ * Built only from publicly known proportions (iPhone 17 Pro: a 402 x 874 pt screen, about
+ * 16 pt of frame and border around it; iPad Pro 11-inch: an 834 x 1210 pt screen, about 44 pt
+ * of border). No Apple artwork, product images or Design Resources are used or traced; see
+ * the implementation contract Units are points of the drawn screen.
+ *
+ * Colours come from CSS custom properties, so one drawing serves light and dark:
+ * `--metal-a`/`--metal-b` (the frame), `--w1`..`--w3` (the mist wallpaper),
+ * `--g1`..`--g4` and `--label-bar` (placeholder apps), `--dock-glass`, `--dock-rim` and `--ink` (page dots, Home
+ * indicator).
+ */
+/**
+ * The lower part of an iPhone in portrait, drawn large (owner, round five): the frame and its
+ * rounded bottom corners, one row of apps with the app in the next free place, page dots, the
+ * dock and the Home indicator. The top of the device is cut off; CSS fades the cut edge.
+ */
+export declare function phoneDrawing(icon: string): string;
+/**
+ * The lower part of an iPad in portrait (iPad Pro 11-inch: an 834 x 1210 pt screen, about
+ * 44 pt of border), drawn the same way: frame and rounded bottom corners, one row of apps with
+ * the app in the next free place, page dots, the floating dock and the Home indicator.
+ * Portrait, because the lower part of a landscape iPad is a thin strip with tiny apps.
+ */
+export declare function padDrawing(icon: string): string;
+/** The drawing's tokens and the tip's glass tokens in one appearance, as CSS declarations. */
+export declare function deviceTokens(dark: boolean): string;

package/dist/app/installExperienceDevice.js

@@ -0,0 +1,160 @@
+/**
+ * Our own drawings of the lower part of an iPhone and an iPad showing a Home Screen, for the
+ * install page.
+ *
+ * Built only from publicly known proportions (iPhone 17 Pro: a 402 x 874 pt screen, about
+ * 16 pt of frame and border around it; iPad Pro 11-inch: an 834 x 1210 pt screen, about 44 pt
+ * of border). No Apple artwork, product images or Design Resources are used or traced; see
+ * the implementation contract Units are points of the drawn screen.
+ *
+ * Colours come from CSS custom properties, so one drawing serves light and dark:
+ * `--metal-a`/`--metal-b` (the frame), `--w1`..`--w3` (the mist wallpaper),
+ * `--g1`..`--g4` and `--label-bar` (placeholder apps), `--dock-glass`, `--dock-rim` and `--ink` (page dots, Home
+ * indicator).
+ */
+/**
+ * The app's icon in its place, slightly lifted with a soft shadow, as when placing it on the
+ * Home Screen (round ten: no dashed outline; iOS never draws one).
+ */
+function appSlot(icon, x, y, size, clip) {
+    return `<image class="ix-app" href="${icon}" x="${x}" y="${y}" width="${size}" height="${size}" clip-path="url(#${clip})"/>`;
+}
+/**
+ * The Home Screen icon shape for the app's own icon, in the icon's bounding box, with the same
+ * corner ratio as the placeholder apps. Each device drawing defines its own copy because a
+ * hidden drawing's definitions don't apply in WebKit.
+ */
+function iconShape(id) {
+    return `<clipPath id="${id}" clipPathUnits="objectBoundingBox"><rect width="1" height="1" rx="0.23"/></clipPath>`;
+}
+/**
+ * Placeholder apps that read as a Home Screen without being real apps: rounded squares in a few
+ * soft tints (`--g1`..`--g4`), with a faint short label under those in the grid.
+ */
+function ghosts(size, y, xs, labels) {
+    return xs
+        .map((x, index) => {
+        const tone = `ix-t${(index % 4) + 1}`;
+        const icon = `<rect class="${tone}" x="${x}" y="${y}" width="${size}" height="${size}" rx="${size * 0.23}"/>`;
+        const width = size * (index % 2 ? 0.42 : 0.56);
+        const label = labels
+            ? `<rect class="ix-label" x="${x + (size - width) / 2}" y="${y + size + 7}" width="${width}" height="6" rx="3"/>`
+            : '';
+        return icon + label;
+    })
+        .join('');
+}
+/** The mist wallpaper over the visible part of the screen: a grey gradient and a soft light. */
+function wallpaper(id, width, height, top) {
+    return [
+        `<linearGradient id="${id}-w" x2="0" y1="${top}" y2="${height}" gradientUnits="userSpaceOnUse">`,
+        '<stop style="stop-color:var(--w1)"/><stop offset="1" style="stop-color:var(--w2)"/></linearGradient>',
+        `<radialGradient id="${id}-g"><stop style="stop-color:var(--w3)"/>`,
+        '<stop offset="1" style="stop-color:var(--w3);stop-opacity:0"/></radialGradient>',
+        `<rect width="${width}" height="${height}" fill="url(#${id}-w)"/>`,
+        `<ellipse cx="${width * 0.2}" cy="${top + 20}" rx="${width * 0.8}" ry="${(height - top) * 0.7}" fill="url(#${id}-g)"/>`,
+    ].join('');
+}
+/**
+ * The lower part of an iPhone in portrait, drawn large (owner, round five): the frame and its
+ * rounded bottom corners, one row of apps with the app in the next free place, page dots, the
+ * dock and the Home indicator. The top of the device is cut off; CSS fades the cut edge.
+ */
+export function phoneDrawing(icon) {
+    const screen = [
+        wallpaper('ix-p', 402, 874, 580),
+        ghosts(62, 636, [27.5, 122.5], true),
+        '<g class="ix-ink"><circle cx="193" cy="737" r="3.5"/><circle cx="209" cy="737" r="3.5" opacity=".4"/></g>',
+        '<rect class="ix-dock" x="13" y="755" width="376" height="96" rx="38"/>',
+        ghosts(62, 772, [27.5, 122.5, 217.5, 312.5], false),
+        '<rect class="ix-ink" x="134" y="861" width="134" height="5" rx="2.5"/>',
+        appSlot(icon, 217.5, 636, 62, 'ix-icon-p'),
+    ].join('');
+    return [
+        '<svg class="ix-device ix-phone" viewBox="-12 584 458 346" aria-hidden="true">',
+        '<linearGradient id="ix-pm" x2="1"><stop style="stop-color:var(--metal-a)"/>',
+        '<stop offset=".5" style="stop-color:var(--metal-b)"/><stop offset="1" style="stop-color:var(--metal-a)"/></linearGradient>',
+        '<rect class="ix-frame" width="434" height="906" rx="78" fill="url(#ix-pm)"/>',
+        '<rect class="ix-border" x="4" y="4" width="426" height="898" rx="74"/>',
+        '<clipPath id="ix-ps"><rect width="402" height="874" rx="62"/></clipPath>',
+        iconShape('ix-icon-p'),
+        `<g transform="translate(16 16)" clip-path="url(#ix-ps)">${screen}</g>`,
+        '</svg>',
+    ].join('');
+}
+/**
+ * The lower part of an iPad in portrait (iPad Pro 11-inch: an 834 x 1210 pt screen, about
+ * 44 pt of border), drawn the same way: frame and rounded bottom corners, one row of apps with
+ * the app in the next free place, page dots, the floating dock and the Home indicator.
+ * Portrait, because the lower part of a landscape iPad is a thin strip with tiny apps.
+ */
+export function padDrawing(icon) {
+    const screen = [
+        wallpaper('ix-t', 834, 1210, 860),
+        ghosts(74, 930, [100, 240, 380], true),
+        '<g class="ix-ink"><circle cx="409" cy="1042" r="4"/><circle cx="425" cy="1042" r="4" opacity=".4"/></g>',
+        '<rect class="ix-dock" x="40" y="1060" width="754" height="110" rx="36"/>',
+        ghosts(74, 1078, [92, 188, 284, 380, 476, 572, 668], false),
+        '<rect class="ix-ink" x="317" y="1196" width="200" height="5" rx="2.5"/>',
+        appSlot(icon, 520, 930, 74, 'ix-icon-t'),
+    ].join('');
+    return [
+        '<svg class="ix-device ix-tablet" viewBox="-14 880 950 442" aria-hidden="true">',
+        '<linearGradient id="ix-tm" x2="1"><stop style="stop-color:var(--metal-a)"/>',
+        '<stop offset=".5" style="stop-color:var(--metal-b)"/><stop offset="1" style="stop-color:var(--metal-a)"/></linearGradient>',
+        '<rect class="ix-frame" width="922" height="1298" rx="64" fill="url(#ix-tm)"/>',
+        '<rect class="ix-border" x="4" y="4" width="914" height="1290" rx="60"/>',
+        '<clipPath id="ix-ts"><rect width="834" height="1210" rx="20"/></clipPath>',
+        iconShape('ix-icon-t'),
+        `<g transform="translate(44 44)" clip-path="url(#ix-ts)">${screen}</g>`,
+        '</svg>',
+    ].join('');
+}
+/** The mist wallpaper (owner's pick, round five), light and dark: top, bottom, soft light. */
+const MIST = {
+    light: ['#dfe1e6', '#b3b7c1', 'rgb(255 255 255 / 0.7)'],
+    dark: ['#36373d', '#111114', '#55585f'],
+};
+/** The drawing's tokens and the tip's glass tokens in one appearance, as CSS declarations. */
+export function deviceTokens(dark) {
+    const tokens = [
+        ...MIST[dark ? 'dark' : 'light'].map((color, index) => `--w${index + 1}: ${color}`),
+        // Placeholder apps: soft tints, still clearly not real apps.
+        ...(dark
+            ? [
+                'rgb(150 170 210 / 0.22)',
+                'rgb(170 200 170 / 0.2)',
+                'rgb(220 180 150 / 0.2)',
+                'rgb(190 170 220 / 0.22)',
+            ]
+            : [
+                'rgb(214 226 246 / 0.85)',
+                'rgb(222 238 222 / 0.85)',
+                'rgb(246 230 214 / 0.85)',
+                'rgb(232 222 246 / 0.85)',
+            ]).map((tone, i) => `--g${i + 1}: ${tone}`),
+        `--label-bar: rgb(${dark ? '255 255 255 / 0.14' : '255 255 255 / 0.5'})`,
+        `--dock-glass: rgb(255 255 255 / ${dark ? 0.12 : 0.4})`,
+        `--dock-rim: rgb(255 255 255 / ${dark ? 0.2 : 0.75})`,
+        `--ink: ${dark ? 'rgb(255 255 255 / 0.85)' : 'rgb(0 0 0 / 0.72)'}`,
+        `--metal-a: ${dark ? '#3a3b40' : '#b9bcc3'}`,
+        `--metal-b: ${dark ? '#77797f' : '#eef0f3'}`,
+        // The tip's glass, measured from iOS 27's popover tip over these page colours (round six).
+        `--glass: color-mix(in srgb, var(--bg), #fff ${dark ? 12.5 : 67}%)`,
+        `--glass-band: ${dark ? 'transparent' : 'var(--bg)'}`,
+        // Inner light lines (round six's measured strengths): the crisp line at the top edge, a soft
+        // falloff inside it, and the bottom's strength relative to the top.
+        `--hl-line: ${dark ? 0.27 : 1}`,
+        `--hl-soft: ${dark ? 0.08 : 0.45}`,
+        `--hl-bottom: ${dark ? 0.74 : 1}`,
+        '--one: 1',
+        // The squared falloff around the corners, for the top and for the bottom's strength.
+        ...[0.5625, 0.25, 0.0625].map((q, i) => `--q${i + 1}: ${q}`),
+        ...[0.5625, 0.25, 0.0625].map((q, i) => `--qb${i + 1}: ${+(q * (dark ? 0.74 : 1)).toFixed(3)}`),
+        `--ht: ${dark ? 0 : 0.08}`,
+        `--hs: ${dark ? 0.85 : 0.35}`,
+        `--hb: ${dark ? 0 : 0.14}`,
+        '--zero: 0',
+    ];
+    return tokens.map(token => token + ';').join(' ');
+}

package/dist/app/installExperienceHome.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The install page leads with the action, "Add {app} to Home Screen". Above it, a drawing of the
+ * device in hand (an iPhone, or an iPad on an iPad) shows a Home Screen with the app's icon
+ * hovering over the next free place among greyed-out apps; the app's description sits under
+ * the title. Then the steps in the grammar of Apple's onboarding sheets, one emphasised at a
+ * time, and a tip in the style of the system's popover tips at Safari's real control.
+ *
+ * Layouts: iPhone portrait (one column), iPhone landscape and iPad landscape (the drawing
+ * beside the text), iPad portrait (one centred column with room around it), and a narrow
+ * iPad window (the phone's column with the iPad drawing).
+ */
+export declare function homeScene(icon: string): string;
+/** One row: a symbol, the bold action, and where to find it. */
+export declare function homeStep(symbol: string, action: string, where?: string): string;
+export declare const TIP_GLASS: string;
+export declare const CSS_D = "\n.ix { text-align: center; padding-inline: max(20px, env(safe-area-inset-left)) max(20px, env(safe-area-inset-right)); }\n.ix-hero { padding-top: clamp(14px, 3svh, 32px); }\n\n/* The drawing. Height drives its size; the large-text levels shrink it. */\n/* The drawing: the lower part of the device, large, its cut edge fading into the page.\n * --art is its width; the large-text levels narrow it. */\n.ix-art { --art: min(100%, 360px, 48svh); display: flex; justify-content: center; }\n.ix-device {\n  display: block;\n  width: var(--art);\n  height: auto;\n  max-width: 100%;\n  -webkit-mask-image: linear-gradient(transparent, #000 18%);\n  mask-image: linear-gradient(transparent, #000 18%);\n}\n.ix-tablet, html[data-device=\"pad\"] .ix-phone { display: none; }\nhtml[data-device=\"pad\"] .ix-tablet { display: block; }\n.ix-frame { filter: drop-shadow(0 10px 14px rgb(0 0 0 / 0.16)); }\n.ix-frame { stroke: rgb(0 0 0 / 0.12); stroke-width: 1; }\n.ix-border { fill: #0b0b0c; }\n.ix-t1 { fill: var(--g1); }\n.ix-t2 { fill: var(--g2); }\n.ix-t3 { fill: var(--g3); }\n.ix-t4 { fill: var(--g4); }\n.ix-label { fill: var(--label-bar); }\n.ix-ink { fill: var(--ink); }\n.ix-dock { fill: var(--dock-glass); stroke: var(--dock-rim); stroke-width: 1.5; }\n.ix-app { filter: drop-shadow(0 6px 8px rgb(0 0 0 / 0.25)); }\n\n/* The action is the title; the description supports it. */\n.ix-title {\n  margin-top: 18px;\n  font-size: min(1.765rem, 40px);\n  font-weight: 700;\n  letter-spacing: 0;\n  line-height: 1.17;\n  text-wrap: balance;\n  overflow-wrap: anywhere;\n}\n.ix-about {\n  margin-top: 6px;\n  color: var(--second);\n  font-size: min(1rem, 28px);\n  line-height: 1.294;\n  text-wrap: balance;\n}\n[data-panel] { margin-top: 22px; }\n[data-panel] h2 { font-size: min(1.176rem, 28px); font-weight: 600; }\n[data-panel] h2 bdi { overflow-wrap: anywhere; }\n\n/* The steps, in the grammar of the system's own onboarding sheets. */\n.ix-steps {\n  --sym: min(2.118rem, 52px);\n  border-radius: 26px;\n  background: var(--card);\n  text-align: start;\n}\n[data-panel] h2 + .ix-steps { margin-top: 14px; }\n.ix-steps li {\n  position: relative;\n  display: grid;\n  grid-template-columns: var(--sym) 1fr;\n  column-gap: 12px;\n  align-items: center;\n  min-height: 60px;\n  box-sizing: border-box;\n  padding-block: 10px;\n  padding-inline: 14px 16px;\n}\n.ix-steps li + li::before {\n  content: \"\";\n  position: absolute;\n  top: 0;\n  inset-inline: calc(var(--sym) + 26px) 0;\n  height: 0.5px;\n  background: var(--hair);\n}\n/*\n * Round ten: every row's symbol has the same treatment, as in iOS lists: the symbol in the\n * tint on a soft tinted rounded square. No row is styled as \"current\" and nothing joins them.\n */\n/* A one-line row is a native one-line list row: title centred, 52 pt tall. */\n.ix-steps li:not(:has(.ix-where)) { min-height: 52px; padding-block: 8px; }\n.ix-sym {\n  display: grid;\n  place-items: center;\n  width: var(--sym);\n  height: var(--sym);\n  border-radius: calc(var(--sym) * 0.27);\n  background: var(--tint-soft);\n  color: var(--tint);\n}\n.ix-sym .ix-g { width: calc(var(--sym) * 0.61); height: calc(var(--sym) * 0.61); vertical-align: 0; }\n.ix-sym [data-for] { grid-area: 1 / 1; line-height: 0; }\n.ix-row b { display: block; font-size: 1rem; font-weight: 600; line-height: 1.294; }\n.ix-where { display: block; color: var(--second); font-size: 0.882rem; line-height: 1.33; }\n.ix-hint { margin-top: 14px; }\nhtml[data-state=\"back\"] [data-panel=\"steps\"] .ix-foot { display: none; }\n.ix-foot { margin-top: 14px; }\n\n/*\n * The tip: a small one-line callout (round eight: 42 pt tall, 15 pt semibold, corners 17 pt)\n * in round six's material, measured from iOS 27's popover tip. It grows out of Safari's\n * control the way a native popover appears. Round nine: as low as the page can draw. Safari's\n * page area ends about 16 pt above its address bar (measured: 858 pt against 873.7 pt with the\n * compact bar, 794 against 810.3 with the full toolbar), so the tail cannot reach the control;\n * its point sits about 3 pt above the page area's bottom, leaving the shadow room to fade.\n */\n.ix-pointer {\n  position: fixed;\n  z-index: 2;\n  left: 9px;\n  bottom: 13px;\n  display: flex;\n  align-items: center;\n  min-height: 42px;\n  box-sizing: border-box;\n  padding: 0 15px;\n  color: var(--label);\n  font-size: 15px;\n  font-weight: 600;\n  line-height: 20px;\n  white-space: nowrap;\n  transform-origin: 105px calc(100% + 11px);\n}\nhtml[data-ready] .ix-pointer { animation: ix-tip 0.45s 0.3s var(--spring) both; }\n@keyframes ix-tip { from { transform: scale(0.2); opacity: 0; filter: blur(4px); } }\n.ix-glass {\n  position: absolute;\n  inset: 0;\n  z-index: -1;\n  width: 100%;\n  height: 100%;\n  overflow: visible;\n}\n.ix-glass-fill { fill: var(--glass); }\n.ix-glass-band { stroke: var(--glass-band); }\n.ix-glass-line { opacity: var(--hl-line); }\n.ix-glass-soft { opacity: var(--hl-soft); }\nhtml[data-state=\"back\"] .ix-pointer { animation: ix-tip-again 0.45s var(--spring) both; }\n/* The symbol scaled with the words: its lines span about 19 x 12 pt. */\n.ix-pointer .ix-g {\n  flex: none;\n  width: 32px;\n  height: 32px;\n  margin: -6px 3.5px -6px -6.6px;\n  color: var(--tint);\n  stroke-width: 1.4;\n}\nhtml[data-bar=\"toolbar\"] .ix-pointer { right: 16px; width: fit-content; margin: 0 auto; transform-origin: 50% calc(100% + 11px); }\nhtml[data-bar=\"top\"] .ix-pointer {\n  left: auto;\n  right: calc(env(safe-area-inset-right) + 78px);\n  bottom: auto;\n  top: 12px;\n  transform-origin: calc(100% - 42px) -11px;\n}\nhtml:not([data-step=\"1\"]) .ix-pointer { display: none; }\n@keyframes ix-tip-again { from { transform: scale(0.2); opacity: 0; filter: blur(4px); } }\nhtml[data-bar=\"top\"] .ix { padding-top: 80px; }\n\n.ix-qr { margin-inline: auto; }\n@media (min-width: 600px) { .ix-panels, #satin-install-check { max-width: 460px; margin-inline: auto; } }\n\n/*\n * iPad portrait (any window at least 600 wide and 700 tall, upright): one column with space,\n * about centred. The offset is fixed rather than measured, so the page does not move when\n * the deployment check hands over to the steps.\n */\n@media (min-width: 600px) and (min-height: 700px) and (orientation: portrait) {\n  .ix-hero, html[data-bar=\"top\"] .ix-hero { padding-top: max(24px, calc(50svh - 400px)); }\n  html[data-device=\"pad\"] .ix-art { --art: min(100%, 560px); }\n  .ix-title { margin-top: 28px; font-size: min(2.118rem, 44px); }\n  .ix-panels, #satin-install-check { width: 100%; max-width: 480px; }\n}\n/* A narrow iPad window: the phone's column, with the iPad drawn. */\n@media (max-width: 599px) { html[data-device=\"pad\"] .ix-art { --art: 100%; } }\n\n/* Landscape with room (iPad): the drawing on the left, the title and steps beside it. */\n@media (orientation: landscape) and (min-width: 900px) and (min-height: 600px) {\n  .ix {\n    display: grid;\n    grid-template-columns: minmax(0, 1fr) minmax(320px, 440px);\n    grid-auto-rows: min-content;\n    align-content: center;\n    column-gap: clamp(32px, 6vw, 88px);\n    max-width: 1120px;\n    margin-inline: auto;\n    text-align: start;\n  }\n  .ix-hero { display: contents; }\n  html .ix-art { grid-column: 1; grid-row: 1 / span 4; align-self: center; --art: min(100%, 540px); }\n  .ix-hero > :not(.ix-art), #satin-install-check, .ix-panels { grid-column: 2; }\n  .ix-title { margin-top: 0; font-size: min(2.118rem, 44px); }\n  .ix-panels, #satin-install-check { max-width: none; margin-inline: 0; }\n  .ix-qr { margin-inline: 0; }\n}\n/* iPhone landscape: little height, so the same two columns, tighter. */\n@media (orientation: landscape) and (max-height: 500px) {\n  .ix {\n    display: grid;\n    grid-template-columns: 0.75fr 1.25fr;\n    grid-auto-rows: min-content;\n    align-content: center;\n    column-gap: 24px;\n    padding-top: 52px;\n    padding-bottom: max(8px, env(safe-area-inset-bottom));\n    text-align: start;\n  }\n  .ix-hero { display: contents; }\n  html .ix-art { grid-column: 1; grid-row: 1 / span 4; align-self: center; --art: min(100%, 300px, 88svh); }\n  .ix-hero > :not(.ix-art), #satin-install-check, .ix-panels { grid-column: 2; }\n  .ix-title { margin-top: 0; font-size: min(1.412rem, 30px); }\n  .ix-about { margin-top: 2px; }\n  [data-panel] { margin-top: 10px; }\n  html[data-tight=\"3x\"] .ix-foot { display: none; }\n  .ix-steps li { min-height: 48px; padding-block: 5px; }\n}\n\n/* When the text is large the drawing steps back so the steps keep their room. */\nhtml[data-tight=\"1\"] .ix-art { --art: 260px; }\nhtml[data-tight=\"2\"] .ix-art { --art: 200px; }\nhtml[data-tight=\"3\"] .ix-art { --art: 140px; }\nhtml[data-tight=\"3x\"] :is(.ix-art, .ix-about) { display: none; }\nhtml[data-tight] .ix-hero { padding-top: 6px; }\n";