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

package/dist/app/installPolicy.js

@@ -0,0 +1,90 @@
+/** Pure naming policy. App admission deliberately requires additional WebKit signals. */
+export function classifyInstallSignals(userAgent, platform, maxTouchPoints) {
+    const webkit = /AppleWebKit/i.test(userAgent) && !/Android/i.test(userAgent);
+    const device = !webkit
+        ? 'other'
+        : /iPhone|iPod/.test(userAgent)
+            ? 'iphone'
+            : /iPad/.test(userAgent) || (platform === 'MacIntel' && maxTouchPoints > 1)
+                ? 'ipad'
+                : 'other';
+    const other = /CriOS|FxiOS|EdgiOS|OPiOS|OPT\/|DuckDuckGo|Brave|YaBrowser|Focus\//.test(userAgent);
+    const embedded = /FBAN|FBAV|FB_IAB|Instagram|Line\/|MicroMessenger|TikTok|musical_ly|Snapchat|Twitter|LinkedInApp|Pinterest|GSA\//.test(userAgent);
+    const browser = !webkit || /Chrome\//i.test(userAgent) || other
+        ? 'other'
+        : !/Safari\//.test(userAgent) || embedded
+            ? 'in-app'
+            : 'safari';
+    const version = browser === 'safari' ? /Version\/(\d+)/.exec(userAgent)?.[1] : undefined;
+    return { device, browser, safariVersion: version ? Number(version) : null };
+}
+/** Geometry stays pure; callers supply the measured dynamic viewport collapse. */
+export function safariBarGeometry(version, device, width, height, collapse) {
+    if (version !== 27 || device === 'other')
+        return 'unknown';
+    if (device === 'ipad')
+        return width < 600 ? 'unknown' : 'top';
+    if (width > height)
+        return 'top';
+    return collapse >= 70 ? 'toolbar' : 'compact';
+}
+export function safariToolbarCollapse(version, device, width, height) {
+    // Only portrait iPhone Safari 27 needs a dynamic toolbar measurement.
+    if (version !== 27 || device !== 'iphone' || width > height)
+        return 0;
+    const unit = (name) => {
+        const probe = document.createElement('div');
+        probe.style.cssText = 'position:fixed;top:0;width:0;visibility:hidden;height:100' + name;
+        document.documentElement.append(probe);
+        const height = probe.offsetHeight;
+        probe.remove();
+        return height;
+    };
+    return unit('lvh') - unit('svh');
+}
+/** Static HTML and React render this same step model. */
+export function installSteps(browser, bar, text) {
+    const safari = browser === 'safari';
+    return [
+        {
+            symbol: safari && bar === 'compact' ? 'menu' : 'share',
+            action: safari && bar === 'compact' ? text.rowMenu : text.rowShare,
+            where: safari ? '' : text.rowShareBrowser,
+        },
+        {
+            symbol: 'home',
+            action: text.rowHome,
+            where: safari ? text.rowHomeWhere : text.rowHomeBrowser,
+        },
+        { symbol: 'put', action: text.rowAdd, where: text.keepWebApp },
+    ];
+}
+export const installPolicy = {
+    classifyInstallSignals,
+    safariBarGeometry,
+    safariToolbarCollapse,
+    tipPath,
+};
+/** Only browser-safe functions are embedded; no React or app startup dependency. */
+export function serializeInstallPolicy() {
+    return ('{' +
+        Object.entries(installPolicy)
+            .map(([name, implementation]) => `${name}:${implementation.toString()}`)
+            .join(',') +
+        '}');
+}
+export function tipPath(w, h, bar) {
+    const r = Math.round(h * 0.405);
+    const top = bar === 'top';
+    const at = bar === 'compact' ? 105 : bar === 'toolbar' ? w / 2 : w - 42;
+    const edge = top ? 0 : h;
+    const point = (dx, dy) => `${at + (top ? -dx : dx)} ${edge + (top ? -dy : dy)}`;
+    const tail = [
+        `L${point(17, 0)}C${point(10.7, 0)} ${point(9.35, 1.36)} ${point(8, 3.23)}`,
+        `L${point(1.96, 9.18)}Q${point(0, 11.05)} ${point(-1.96, 9.18)}`,
+        `L${point(-8, 3.23)}C${point(-9.35, 1.36)} ${point(-10.7, 0)} ${point(-17, 0)}`,
+    ].join('');
+    const arc = (x, y) => `A${r} ${r} 0 0 1 ${x} ${y}`;
+    return (`M${r} 0${top ? tail : ''}L${w - r} 0${arc(w, r)}L${w} ${h - r}${arc(w - r, h)}` +
+        `${top ? '' : tail}L${r} ${h}${arc(0, h - r)}L0 ${r}${arc(r, 0)}Z`);
+}

package/dist/app/installQr.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A small QR encoder for the install page's "open this on your iPhone" code.
+ *
+ * Byte mode, error correction level L, versions 1 to 5 (up to 106 bytes), mask 0.
+ * Returns the module rows (true = dark), or null when the text is too long.
+ *
+ * Self-contained: embedded verbatim in the install page, so it must not reference
+ * anything outside its own body.
+ */
+export declare function installQrMatrix(text: string): boolean[][] | null;

package/dist/app/installQr.js

@@ -0,0 +1,139 @@
+/**
+ * A small QR encoder for the install page's "open this on your iPhone" code.
+ *
+ * Byte mode, error correction level L, versions 1 to 5 (up to 106 bytes), mask 0.
+ * Returns the module rows (true = dark), or null when the text is too long.
+ *
+ * Self-contained: embedded verbatim in the install page, so it must not reference
+ * anything outside its own body.
+ */
+export function installQrMatrix(text) {
+    const bytes = Array.from(new TextEncoder().encode(text));
+    // [data codewords, error correction codewords] for versions 1 to 5 at level L.
+    const capacities = [
+        [19, 7],
+        [34, 10],
+        [55, 15],
+        [80, 20],
+        [108, 26],
+    ];
+    const version = capacities.findIndex(([data]) => bytes.length <= data - 2) + 1;
+    if (!version)
+        return null;
+    const [dataLength, eccLength] = capacities[version - 1];
+    const size = 17 + 4 * version;
+    // Data codewords: mode 0100, an 8-bit length, the bytes, a terminator, then pad bytes.
+    const bits = [];
+    const push = (value, length) => {
+        for (let bit = length - 1; bit >= 0; bit--)
+            bits.push((value >>> bit) & 1);
+    };
+    push(4, 4);
+    push(bytes.length, 8);
+    for (const byte of bytes)
+        push(byte, 8);
+    push(0, Math.min(4, dataLength * 8 - bits.length));
+    while (bits.length % 8)
+        bits.push(0);
+    for (let pad = 0xec; bits.length < dataLength * 8; pad ^= 0xec ^ 0x11)
+        push(pad, 8);
+    const codewords = [];
+    for (let index = 0; index < bits.length; index += 8) {
+        codewords.push(bits.slice(index, index + 8).reduce((sum, bit) => (sum << 1) | bit, 0));
+    }
+    // Reed-Solomon error correction over GF(256), polynomial 0x11d.
+    const multiply = (left, right) => {
+        let product = 0;
+        for (let bit = 7; bit >= 0; bit--) {
+            product = (product << 1) ^ ((product >>> 7) * 0x11d);
+            product ^= ((right >>> bit) & 1) * left;
+        }
+        return product;
+    };
+    const divisor = new Array(eccLength).fill(0);
+    divisor[eccLength - 1] = 1;
+    for (let degree = 0, root = 1; degree < eccLength; degree++, root = multiply(root, 2)) {
+        for (let index = 0; index < eccLength; index++) {
+            divisor[index] = multiply(divisor[index], root) ^ (divisor[index + 1] ?? 0);
+        }
+    }
+    const remainder = new Array(eccLength).fill(0);
+    for (const codeword of codewords) {
+        const factor = codeword ^ remainder.shift();
+        remainder.push(0);
+        divisor.forEach((coefficient, index) => {
+            remainder[index] ^= multiply(coefficient, factor);
+        });
+    }
+    const stream = codewords.concat(remainder);
+    // Function patterns. `reserved` marks every module the data must skip.
+    const modules = Array.from({ length: size }, () => new Array(size).fill(false));
+    const reserved = Array.from({ length: size }, () => new Array(size).fill(false));
+    const set = (column, row, dark) => {
+        if (column < 0 || row < 0 || column >= size || row >= size)
+            return;
+        modules[row][column] = dark;
+        reserved[row][column] = true;
+    };
+    for (let index = 0; index < size; index++) {
+        set(6, index, index % 2 === 0);
+        set(index, 6, index % 2 === 0);
+    }
+    const finder = (centreColumn, centreRow) => {
+        for (let dy = -4; dy <= 4; dy++) {
+            for (let dx = -4; dx <= 4; dx++) {
+                const ring = Math.max(Math.abs(dx), Math.abs(dy));
+                set(centreColumn + dx, centreRow + dy, ring !== 2 && ring !== 4);
+            }
+        }
+    };
+    finder(3, 3);
+    finder(size - 4, 3);
+    finder(3, size - 4);
+    if (version > 1) {
+        for (let dy = -2; dy <= 2; dy++) {
+            for (let dx = -2; dx <= 2; dx++) {
+                set(size - 7 + dx, size - 7 + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);
+            }
+        }
+    }
+    // Format information for level L and mask 0, with its BCH check bits.
+    const format = 1 << 3;
+    let check = format;
+    for (let step = 0; step < 10; step++)
+        check = (check << 1) ^ ((check >>> 9) * 0x537);
+    const formatBits = ((format << 10) | check) ^ 0x5412;
+    const formatBit = (index) => ((formatBits >>> index) & 1) === 1;
+    for (let index = 0; index <= 5; index++)
+        set(8, index, formatBit(index));
+    set(8, 7, formatBit(6));
+    set(8, 8, formatBit(7));
+    set(7, 8, formatBit(8));
+    for (let index = 9; index < 15; index++)
+        set(14 - index, 8, formatBit(index));
+    for (let index = 0; index < 8; index++)
+        set(size - 1 - index, 8, formatBit(index));
+    for (let index = 8; index < 15; index++)
+        set(8, size - 15 + index, formatBit(index));
+    set(8, size - 8, true);
+    // Data modules in the zigzag order, with mask 0 applied: (row + column) is even.
+    let position = 0;
+    for (let right = size - 1; right >= 1; right -= 2) {
+        if (right === 6)
+            right = 5;
+        for (let step = 0; step < size; step++) {
+            for (let side = 0; side < 2; side++) {
+                const column = right - side;
+                const upward = ((right + 1) & 2) === 0;
+                const row = upward ? size - 1 - step : step;
+                if (reserved[row][column])
+                    continue;
+                const bit = position < stream.length * 8 &&
+                    ((stream[position >>> 3] >>> (7 - (position & 7))) & 1) === 1;
+                modules[row][column] = bit !== ((row + column) % 2 === 0);
+                position++;
+            }
+        }
+    }
+    return modules;
+}

package/dist/app/installStrings.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The install page's words, glyphs and spring: browser-safe (no build-time imports), shared by
+ * the default page and the components custom install pages can use (`@satinhq/kit/install`).
+ */
+/** Every user-facing string of the install experience. `{app}` is the app's name. */
+export declare const INSTALL_STRINGS: {
+    readonly keepWebApp: 'Make sure Open as Web App is on.';
+    readonly addTitle: 'Add {app} to Home Screen';
+    readonly rowMenu: 'Tap Page Menu, then Share';
+    readonly rowShare: 'Tap Share';
+    readonly rowShareBrowser: 'It’s in this browser’s toolbar or menu.';
+    readonly rowHome: 'Choose Add to Home Screen';
+    readonly rowHomeWhere: 'Tap View More if it isn’t in the list.';
+    readonly rowHomeBrowser: 'Not in the list? Open this page in Safari.';
+    readonly rowAdd: 'Tap Add';
+    readonly tipMenu: 'Page Menu, then Share';
+    readonly tipShare: 'Share';
+    readonly menuName: 'the page menu';
+    readonly shareName: '';
+    readonly homeName: '';
+    readonly backHint: 'Not added yet. Add to Home Screen is under View More, and Add finishes it.';
+    readonly alreadyAdded: 'Already added? Open {app} from your Home Screen.';
+    readonly inAppTitle: 'Open this page in Safari';
+    readonly inAppBody: 'This browser can’t add apps to your Home Screen.';
+    readonly openSafari: 'Open in Safari';
+    readonly copyLink: 'Copy Link';
+    readonly copied: 'Link copied';
+    readonly copyFailed: 'Couldn’t copy the link. Select the address to copy it.';
+    readonly inAppFoot: 'Or open this browser’s menu and choose Open in Safari.';
+    readonly deviceAny: 'iPhone or iPad';
+    readonly devicePhone: 'iPhone';
+    readonly devicePad: 'iPad';
+    readonly gateTitle: 'Open {app} on your {device}';
+    readonly gateBody: 'Scan the code with the Camera on your {device}, or open this address in Safari there.';
+    readonly gateNoScript: 'Open this page’s address in Safari on your {device}.';
+};
+/**
+ * The shared system spring (mass 1, stiffness 186.57, damping 25.13) as a CSS `linear()`
+ * easing, sampled every 30 ms over 600 ms.
+ */
+export declare function springEasing(): string;
+/** Our own drawings of the glyphs Safari shows, on a 24 x 24 canvas, stroked in currentColor. */
+export declare const GLYPHS: {
+    readonly menu: '<path d="M5 7.5h14M5 12h14M5 16.5h8.5"/>';
+    readonly share: '<path d="M12 14.5v-11M8 7l4-4 4 4M8.5 10H7a2 2 0 0 0-2 2v6.5a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V12a2 2 0 0 0-2-2h-1.5"/>';
+    readonly home: '<rect x="4" y="4" width="16" height="16" rx="4.5"/><path d="M12 8.5v7M8.5 12h7"/>';
+    readonly more: '<path d="M6.5 9.5 12 15l5.5-5.5"/>';
+    readonly check: '<path d="M5.5 12.5l4.5 4.5 8.5-9.5"/>';
+    readonly arrow: '<path d="M12 4.5v14M6.5 13.5l5.5 5.5 5.5-5.5"/>';
+    readonly plus: '<path d="M12 5.5v13M5.5 12h13"/>';
+    readonly put: '<path d="M12 3.5v11M8 10.5l4 4 4-4M5 16v2a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2v-2"/>';
+};

package/dist/app/installStrings.js

@@ -0,0 +1,75 @@
+/**
+ * The install page's words, glyphs and spring: browser-safe (no build-time imports), shared by
+ * the default page and the components custom install pages can use (`@satinhq/kit/install`).
+ */
+/** Every user-facing string of the install experience. `{app}` is the app's name. */
+export const INSTALL_STRINGS = {
+    keepWebApp: 'Make sure Open as Web App is on.',
+    // The action is the title.
+    addTitle: 'Add {app} to Home Screen',
+    // Each step is a bold action and one line saying where to find it. Safari's Page Menu
+    // gives the page no signal when it opens, so where Share sits inside it the first step
+    // and the tip name both taps at once and stay true while nothing on the page moves.
+    rowMenu: 'Tap Page Menu, then Share',
+    rowShare: 'Tap Share',
+    rowShareBrowser: 'It’s in this browser’s toolbar or menu.',
+    rowHome: 'Choose Add to Home Screen',
+    rowHomeWhere: 'Tap View More if it isn’t in the list.',
+    rowHomeBrowser: 'Not in the list? Open this page in Safari.',
+    rowAdd: 'Tap Add',
+    tipMenu: 'Page Menu, then Share',
+    tipShare: 'Share',
+    // Spoken names for the drawn glyphs.
+    menuName: 'the page menu',
+    shareName: '',
+    homeName: '',
+    backHint: 'Not added yet. Add to Home Screen is under View More, and Add finishes it.',
+    alreadyAdded: 'Already added? Open {app} from your Home Screen.',
+    inAppTitle: 'Open this page in Safari',
+    inAppBody: 'This browser can’t add apps to your Home Screen.',
+    openSafari: 'Open in Safari',
+    copyLink: 'Copy Link',
+    copied: 'Link copied',
+    copyFailed: 'Couldn’t copy the link. Select the address to copy it.',
+    inAppFoot: 'Or open this browser’s menu and choose Open in Safari.',
+    // Device words. The page is written with `{device}` = "iPhone or iPad"; on an iPhone or an
+    // iPad the runtime puts that device's name in its place.
+    deviceAny: 'iPhone or iPad',
+    devicePhone: 'iPhone',
+    devicePad: 'iPad',
+    gateTitle: 'Open {app} on your {device}',
+    gateBody: 'Scan the code with the Camera on your {device}, or open this address in Safari there.',
+    gateNoScript: 'Open this page’s address in Safari on your {device}.',
+};
+/**
+ * The shared system spring (mass 1, stiffness 186.57, damping 25.13) as a CSS `linear()`
+ * easing, sampled every 30 ms over 600 ms.
+ */
+export function springEasing() {
+    const stiffness = 186.57;
+    const damping = 25.13;
+    const natural = Math.sqrt(stiffness);
+    const ratio = damping / (2 * natural);
+    const damped = natural * Math.sqrt(1 - ratio * ratio);
+    const points = [];
+    for (let step = 0; step <= 20; step++) {
+        const time = step * 0.03;
+        const envelope = Math.exp(-ratio * natural * time);
+        const value = 1 -
+            envelope * (Math.cos(damped * time) + ((ratio * natural) / damped) * Math.sin(damped * time));
+        points.push(step === 20 ? '1' : value.toFixed(3).replace(/^0\./, '.'));
+    }
+    return `linear(${points.join(',')})`;
+}
+/** Our own drawings of the glyphs Safari shows, on a 24 x 24 canvas, stroked in currentColor. */
+export const GLYPHS = {
+    menu: '<path d="M5 7.5h14M5 12h14M5 16.5h8.5"/>',
+    share: '<path d="M12 14.5v-11M8 7l4-4 4 4M8.5 10H7a2 2 0 0 0-2 2v6.5a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V12a2 2 0 0 0-2-2h-1.5"/>',
+    home: '<rect x="4" y="4" width="16" height="16" rx="4.5"/><path d="M12 8.5v7M8.5 12h7"/>',
+    more: '<path d="M6.5 9.5 12 15l5.5-5.5"/>',
+    check: '<path d="M5.5 12.5l4.5 4.5 8.5-9.5"/>',
+    arrow: '<path d="M12 4.5v14M6.5 13.5l5.5 5.5 5.5-5.5"/>',
+    plus: '<path d="M12 5.5v13M5.5 12h13"/>',
+    // Add: an arrow coming down into a tray, the counterpart of Share's arrow going up out of one.
+    put: '<path d="M12 3.5v11M8 10.5l4 4 4-4M5 16v2a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2v-2"/>',
+};

package/dist/app/installTipPath.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The tip's panel and tail as one closed path, for its size and Safari's layout. The default
+ * page's standalone runtime embeds this same function; it also
+ * serves the `InstallTip` component of custom install pages.
+ */
+export type SafariBar = 'compact' | 'toolbar' | 'top' | 'unknown';
+export { tipPath } from './installPolicy.js';
+/**
+ * Where this Safari keeps the control that starts the flow, from the dynamic toolbar's size
+ * (measured on Safari 27 only, like the default page; anything else is 'unknown').
+ */
+export declare function classifySafariBar(safariVersion: number | null, device: 'iphone' | 'ipad' | 'other'): SafariBar;

package/dist/app/installTipPath.js

@@ -0,0 +1,9 @@
+import { safariBarGeometry, safariToolbarCollapse } from './installPolicy.js';
+export { tipPath } from './installPolicy.js';
+/**
+ * Where this Safari keeps the control that starts the flow, from the dynamic toolbar's size
+ * (measured on Safari 27 only, like the default page; anything else is 'unknown').
+ */
+export function classifySafariBar(safariVersion, device) {
+    return safariBarGeometry(safariVersion, device, innerWidth, innerHeight, safariToolbarCollapse(safariVersion, device, innerWidth, innerHeight));
+}

package/dist/app/installationFailure.d.ts

@@ -0,0 +1,14 @@
+/** A diagnostic installation failure recorded before app launch. */
+export interface InstallationFailure {
+    buildId: string;
+    url: string;
+    reason: string;
+    networkFailure: boolean;
+    recordedAt?: number;
+}
+/** Reads the recorded installation failure for acceptance fixtures. */
+export declare function readInstallationFailure(scope: string): InstallationFailure | null;
+export declare function readInstallationSuccess(scope: string): {
+    buildId: string;
+    recordedAt?: number;
+} | null;

package/dist/app/installationFailure.js

@@ -0,0 +1,38 @@
+/** Reads the recorded installation failure for acceptance fixtures. */
+export function readInstallationFailure(scope) {
+    try {
+        const value = JSON.parse(localStorage.getItem('satin-install-failure:' + scope) ?? 'null');
+        if (!value || typeof value !== 'object')
+            return null;
+        const failure = value;
+        if (typeof failure.url !== 'string' || typeof failure.reason !== 'string')
+            return null;
+        const success = readInstallationSuccess(scope);
+        if (success) {
+            const successTime = Number.isFinite(success.recordedAt) ? success.recordedAt : undefined;
+            const failureTime = Number.isFinite(failure.recordedAt) ? failure.recordedAt : undefined;
+            if (successTime !== undefined && (failureTime === undefined || successTime >= failureTime))
+                return null;
+            // Legacy records have no timestamp; success for that exact build supersedes its failure.
+            if (successTime === undefined &&
+                failureTime === undefined &&
+                success.buildId === failure.buildId)
+                return null;
+        }
+        return failure;
+    }
+    catch {
+        return null;
+    }
+}
+export function readInstallationSuccess(scope) {
+    try {
+        const value = JSON.parse(localStorage.getItem('satin-install-success:' + scope) ?? 'null');
+        return typeof value?.buildId === 'string'
+            ? { buildId: value.buildId, recordedAt: value.recordedAt }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/app/launch.d.ts

@@ -0,0 +1,7 @@
+import type { DownloadProgress } from './launchScreen.js';
+/** Resolves only after the worker has atomically installed the complete bundle.
+ * An existing active worker is sufficient offline; never await an update fetch. */
+export declare function prepareOfflineBundle(scope: string, timeoutMs?: number, onProgress?: (progress: DownloadProgress | null) => void): Promise<boolean>;
+/** Admission owns the entire five-second launch deadline. A stuck required
+ * Image reports the existing retry screen rather than revealing undecoded art. */
+export declare function prepareLaunchContent(root: HTMLElement, signal?: AbortSignal): Promise<void>;