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

package/dist/styles.css.d.ts

@@ -0,0 +1,3 @@
+declare const stylesheet: string
+
+export default stylesheet

package/dist/sw/activationState.d.ts

@@ -0,0 +1,20 @@
+export interface AppShellActivationState {
+    readonly current: string | null;
+    readonly phase: 'idle' | 'applying';
+    readonly target: string | null;
+    readonly waiting: string | null;
+}
+export type AppShellActivationEvent = {
+    readonly current: string | null;
+    readonly type: 'discovered';
+    readonly waiting: string | null;
+} | {
+    readonly type: 'apply-requested';
+} | {
+    readonly type: 'activation-failed';
+} | {
+    readonly buildId: string | null;
+    readonly type: 'activated';
+};
+export declare const initialAppShellActivationState: AppShellActivationState;
+export declare function updateAppShellActivationState(state: AppShellActivationState, event: AppShellActivationEvent): AppShellActivationState;

package/dist/sw/activationState.js

@@ -0,0 +1,39 @@
+export const initialAppShellActivationState = {
+    current: null,
+    phase: 'idle',
+    target: null,
+    waiting: null,
+};
+export function updateAppShellActivationState(state, event) {
+    if (event.type === 'discovered') {
+        const waiting = state.phase === 'applying' && event.waiting === null ? state.target : event.waiting;
+        if (state.current === event.current && state.waiting === waiting)
+            return state;
+        return { ...state, current: event.current, waiting };
+    }
+    if (event.type === 'apply-requested') {
+        if (!state.waiting || state.phase === 'applying')
+            return state;
+        return {
+            ...state,
+            phase: 'applying',
+            target: state.waiting,
+        };
+    }
+    if (event.type === 'activation-failed') {
+        if (state.phase === 'idle')
+            return state;
+        return {
+            ...state,
+            phase: 'idle',
+            target: null,
+        };
+    }
+    const current = event.buildId ?? state.target ?? state.current;
+    return {
+        current,
+        phase: 'idle',
+        target: null,
+        waiting: null,
+    };
+}

package/dist/sw/generator.d.ts

@@ -0,0 +1,14 @@
+import { type AppShellPrecacheManifest, type DeriveAppShellManifestOptions } from './manifest.js';
+export interface GenerateAppShellOptions extends DeriveAppShellManifestOptions {
+    readonly publicRoutes?: readonly string[];
+    /** Read-only legacy asset fallbacks; ambiguous unscoped caches are retained. */
+    readonly legacyCacheNames?: readonly string[];
+    /** Explicit diagnostic build only; production serves cached responses unchanged. */
+    readonly diagnosticTimingHeaders?: boolean;
+}
+export interface GeneratedAppShellArtifacts {
+    readonly manifest: AppShellPrecacheManifest;
+    readonly manifestFile: string;
+    readonly serviceWorkerFile: string;
+}
+export declare function generateAppShell({ publicRoutes, legacyCacheNames, diagnosticTimingHeaders, ...manifestOptions }: GenerateAppShellOptions): Promise<GeneratedAppShellArtifacts>;

package/dist/sw/generator.js

@@ -0,0 +1,26 @@
+import { readdir, rm, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { deriveAppShellManifest, } from './manifest.js';
+import { APP_SHELL_VERSION_FILE } from './protocol.js';
+import { renderServiceWorker } from './renderServiceWorker.js';
+const GENERATED_MANIFEST = /^precache-manifest\.[a-f0-9]+\.json$/u;
+async function removePreviousArtifacts(outDir) {
+    await rm(resolve(outDir, 'sw.js'), { force: true });
+    await rm(resolve(outDir, APP_SHELL_VERSION_FILE), { force: true });
+    const files = await readdir(outDir);
+    await Promise.all(files
+        .filter(file => GENERATED_MANIFEST.test(file))
+        .map(file => rm(resolve(outDir, file), { force: true })));
+}
+export async function generateAppShell({ publicRoutes, legacyCacheNames, diagnosticTimingHeaders = false, ...manifestOptions }) {
+    const outDir = resolve(manifestOptions.outDir);
+    await removePreviousArtifacts(outDir);
+    const manifest = await deriveAppShellManifest({ ...manifestOptions, outDir });
+    const manifestFile = resolve(outDir, `precache-manifest.${manifest.buildId}.json`);
+    const serviceWorkerFile = resolve(outDir, 'sw.js');
+    await writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    await writeFile(serviceWorkerFile, renderServiceWorker({ legacyCacheNames, publicRoutes, diagnosticTimingHeaders, manifest }), 'utf8');
+    // This discovery hint is network-only and excluded from the bundle hash.
+    await writeFile(resolve(outDir, APP_SHELL_VERSION_FILE), JSON.stringify({ format: 1, buildId: manifest.buildId }) + '\n', 'utf8');
+    return { manifest, manifestFile, serviceWorkerFile };
+}

package/dist/sw/manifest.d.ts

@@ -0,0 +1,32 @@
+export interface AppShellPrecacheEntry {
+    readonly bytes?: number;
+    readonly revision: string | null;
+    readonly url: string;
+}
+export interface AppShellPrecacheManifest {
+    /** Network-only transport probe; null explicitly means no bundled media. */
+    readonly mediaProbe?: {
+        readonly url: string;
+        readonly bytes: number;
+        readonly prefix: string;
+        readonly type: string;
+    } | null;
+    readonly buildId: string;
+    /** Build-local identifier; the worker prefixes its exact registration scope at runtime. */
+    readonly cacheName: string;
+    readonly cachePrefix: string;
+    readonly entries: readonly AppShellPrecacheEntry[];
+    readonly format: 1;
+    readonly shellUrl: string;
+}
+export interface DeriveAppShellManifestOptions {
+    readonly mediaProbe?: string;
+    readonly shellFile?: string;
+    readonly shellUrl?: string;
+    readonly additionalPrecache?: readonly string[];
+    readonly base?: string;
+    readonly bundleFiles?: ReadonlySet<string>;
+    readonly cachePrefix?: string;
+    readonly outDir: string;
+}
+export declare function deriveAppShellManifest({ mediaProbe: requestedMediaProbe, shellFile, shellUrl: requestedShellUrl, additionalPrecache, base: requestedBase, bundleFiles, cachePrefix, outDir: requestedOutDir, }: DeriveAppShellManifestOptions): Promise<AppShellPrecacheManifest>;

package/dist/sw/manifest.js

@@ -0,0 +1,137 @@
+import { open } from 'node:fs/promises';
+import { mediaTypes } from '../app/mediaTypes.js';
+import { createHash } from 'node:crypto';
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, extname, join, posix, relative, resolve, sep } from 'node:path';
+const GENERATED_FILE = /(?:^|\/)(?:sw\.js|satin-version\.json|precache-manifest\.[a-f0-9]+\.json)$/u;
+const FONT_EXTENSIONS = new Set(['.otf', '.ttf', '.woff', '.woff2']);
+const ICON_EXTENSIONS = new Set(['.avif', '.ico', '.jpeg', '.jpg', '.png', '.svg', '.webp']);
+const SCRIPT_AND_STYLE_EXTENSIONS = new Set(['.css', '.js', '.mjs']);
+const ICON_FILE = /(?:^|[-_.])(?:apple-touch-)?(?:favicon|icon|icons)(?:[-_.]|$)/iu;
+const VITE_HASH = /(?:^|[-_.])[a-z0-9_-]{8,}(?=\.[^.]+$)/iu;
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function normalizeBase(base = '/') {
+    if (!base.startsWith('/')) {
+        throw new Error(`Satin app-shell base must be a same-origin absolute path; received ${JSON.stringify(base)}.`);
+    }
+    const normalized = posix.normalize(base);
+    return normalized === '/' ? '/' : `/${normalized.replace(/^\/+|\/+$/gu, '')}/`;
+}
+function normalizeOutputPath(file) {
+    const normalized = file.split(sep).join('/').replace(/^\/+/, '');
+    if (!normalized || normalized === '.' || normalized.startsWith('../')) {
+        throw new Error(`Satin app-shell entry escapes the build output: ${JSON.stringify(file)}.`);
+    }
+    return normalized;
+}
+function outputUrl(file, base) {
+    if (file === 'index.html')
+        return base;
+    return posix.join(base, file);
+}
+function isDefaultPrecacheFile(file) {
+    if (file === 'index.html')
+        return true;
+    const extension = extname(file).toLowerCase();
+    if (SCRIPT_AND_STYLE_EXTENSIONS.has(extension))
+        return true;
+    if (FONT_EXTENSIONS.has(extension))
+        return true;
+    if (extension === '.webmanifest')
+        return true;
+    return ICON_EXTENSIONS.has(extension) && ICON_FILE.test(basename(file));
+}
+function isHashedBuildAsset(file) {
+    return file.startsWith('assets/') && VITE_HASH.test(basename(file));
+}
+async function outputFiles(outDir) {
+    const files = [];
+    async function visit(directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        await Promise.all(entries.map(async (entry) => {
+            const absolute = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                await visit(absolute);
+                return;
+            }
+            if (!entry.isFile())
+                return;
+            files.push(normalizeOutputPath(relative(outDir, absolute)));
+        }));
+    }
+    await visit(outDir);
+    return files.sort();
+}
+function assertCachePrefix(cachePrefix) {
+    if (!cachePrefix || !/^[a-z0-9._-]+$/iu.test(cachePrefix)) {
+        throw new Error('Satin app-shell cachePrefix must contain only letters, numbers, dot, underscore, and hyphen.');
+    }
+}
+export async function deriveAppShellManifest({ mediaProbe: requestedMediaProbe, shellFile = 'index.html', shellUrl: requestedShellUrl, additionalPrecache = [], base: requestedBase, bundleFiles = new Set(), cachePrefix = 'satin-app-shell-', outDir: requestedOutDir, }) {
+    assertCachePrefix(cachePrefix);
+    const base = normalizeBase(requestedBase);
+    const outDir = resolve(requestedOutDir);
+    const actualFiles = await outputFiles(outDir);
+    const actualFileSet = new Set(actualFiles);
+    const probeFile = requestedMediaProbe === undefined
+        ? actualFiles.find(file => mediaTypes[extname(file).toLowerCase()])
+        : normalizeOutputPath(requestedMediaProbe);
+    let mediaProbe = null;
+    if (probeFile) {
+        if (!actualFileSet.has(probeFile) || !mediaTypes[extname(probeFile).toLowerCase()])
+            throw new Error(`Satin media probe must be an emitted media file: ${probeFile}.`);
+        const handle = await open(resolve(outDir, probeFile), 'r');
+        try {
+            const { size } = await handle.stat();
+            if (size < 2 || !Number.isSafeInteger(size))
+                throw new Error('Satin media probe needs at least two bytes.');
+            const prefix = Buffer.alloc(2);
+            const read = await handle.read(prefix, 0, 2, 0);
+            if (read.bytesRead !== 2)
+                throw new Error('Satin media probe changed during build.');
+            mediaProbe = {
+                url: outputUrl(probeFile, base),
+                bytes: size,
+                prefix: prefix.toString('hex'),
+                type: mediaTypes[extname(probeFile).toLowerCase()],
+            };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    const normalizedBundleFiles = new Set([...bundleFiles].map(normalizeOutputPath).filter(file => extname(file) !== '.map'));
+    const normalizedAdditional = additionalPrecache.map(normalizeOutputPath);
+    for (const file of [...normalizedBundleFiles, ...normalizedAdditional]) {
+        if (!actualFileSet.has(file)) {
+            throw new Error(`Satin precache entry ${JSON.stringify(file)} is absent from ${outDir}.`);
+        }
+    }
+    const selectedFiles = actualFiles.filter(file => !GENERATED_FILE.test(file) &&
+        (file === shellFile ||
+            normalizedBundleFiles.has(file) ||
+            normalizedAdditional.includes(file) ||
+            isDefaultPrecacheFile(file)));
+    if (!selectedFiles.includes(shellFile)) {
+        throw new Error(`Satin app-shell could not find index.html in ${outDir}.`);
+    }
+    const entries = await Promise.all(selectedFiles.map(async (file) => ({
+        bytes: (await readFile(resolve(outDir, file))).byteLength,
+        revision: isHashedBuildAsset(file) ? null : digest(await readFile(resolve(outDir, file))),
+        url: file === shellFile ? (requestedShellUrl ?? base) : outputUrl(file, base),
+    })));
+    entries.sort((left, right) => left.url.localeCompare(right.url));
+    const shellUrl = requestedShellUrl ?? base;
+    const buildId = digest(JSON.stringify({ entries, format: 1, shellUrl, mediaProbe })).slice(0, 20);
+    return {
+        buildId,
+        mediaProbe,
+        cacheName: `${cachePrefix}${buildId}`,
+        cachePrefix,
+        entries,
+        format: 1,
+        shellUrl,
+    };
+}

package/dist/sw/protocol.d.ts

@@ -0,0 +1,7 @@
+export declare const APP_SHELL_BUILD_ID_REQUEST = "SATIN_APP_SHELL_BUILD_ID_REQUEST";
+export declare const APP_SHELL_BUILD_ID_RESPONSE = "SATIN_APP_SHELL_BUILD_ID_RESPONSE";
+export declare const APP_SHELL_APPLY_UPDATE = "SATIN_APP_SHELL_APPLY_UPDATE";
+export declare const APP_SHELL_APPLY_COLD_UPDATE = "SATIN_APP_SHELL_APPLY_COLD_UPDATE";
+export declare const APP_SHELL_APPLY_BACKGROUND_UPDATE = "SATIN_APP_SHELL_APPLY_BACKGROUND_UPDATE";
+export declare const APP_SHELL_COLD_UPDATE_DENIED = "SATIN_APP_SHELL_COLD_UPDATE_DENIED";
+export declare const APP_SHELL_VERSION_FILE = "satin-version.json";

package/dist/sw/protocol.js

@@ -0,0 +1,7 @@
+export const APP_SHELL_BUILD_ID_REQUEST = 'SATIN_APP_SHELL_BUILD_ID_REQUEST';
+export const APP_SHELL_BUILD_ID_RESPONSE = 'SATIN_APP_SHELL_BUILD_ID_RESPONSE';
+export const APP_SHELL_APPLY_UPDATE = 'SATIN_APP_SHELL_APPLY_UPDATE';
+export const APP_SHELL_APPLY_COLD_UPDATE = 'SATIN_APP_SHELL_APPLY_COLD_UPDATE';
+export const APP_SHELL_APPLY_BACKGROUND_UPDATE = 'SATIN_APP_SHELL_APPLY_BACKGROUND_UPDATE';
+export const APP_SHELL_COLD_UPDATE_DENIED = 'SATIN_APP_SHELL_COLD_UPDATE_DENIED';
+export const APP_SHELL_VERSION_FILE = 'satin-version.json';

package/dist/sw/pushRuntime.d.ts

@@ -0,0 +1,2 @@
+/** Serialized into the one app-shell worker; no imports or build-scoped state. */
+export declare function installPushHandlers(self: any, shellPath: string): void;

package/dist/sw/pushRuntime.js

@@ -0,0 +1,161 @@
+/** Serialized into the one app-shell worker; no imports or build-scoped state. */
+export function installPushHandlers(self, shellPath) {
+    const shell = new URL(shellPath, self.location.origin);
+    // Deliberately outside the revisioned app-shell cache prefix: updates retain taps.
+    const inboxName = `satin-push-inbox-v1:${shell.pathname}`;
+    let operations = Promise.resolve();
+    const serial = (run) => {
+        const next = operations.then(run);
+        operations = next.catch(() => { });
+        return next;
+    };
+    const scoped = (input, descendants = false) => {
+        try {
+            const url = new URL(input);
+            return (!url.username &&
+                !url.password &&
+                url.origin === shell.origin &&
+                (descendants ? url.pathname.startsWith(shell.pathname) : url.pathname === shell.pathname));
+        }
+        catch {
+            return false;
+        }
+    };
+    const landing = (input) => {
+        if (typeof input !== 'string' || !scoped(input))
+            return null;
+        try {
+            const url = new URL(input);
+            const id = url.searchParams.get('satin-delivery');
+            const route = JSON.parse(url.searchParams.get('satin-push') ?? 'null');
+            if (!id ||
+                id.length > 128 ||
+                !route ||
+                typeof route.screen !== 'string' ||
+                !route.screen ||
+                (route.tab !== undefined && typeof route.tab !== 'string') ||
+                (route.params !== undefined &&
+                    (!route.params ||
+                        typeof route.params !== 'object' ||
+                        Array.isArray(route.params) ||
+                        Object.values(route.params).some(value => typeof value !== 'string' || value.length > 256))))
+                return null;
+            return { id, url: url.href };
+        }
+        catch {
+            return null;
+        }
+    };
+    const key = (id) => new URL(`__satin_push_pending/${encodeURIComponent(id)}`, shell).href;
+    const windows = async () => (await self.clients.matchAll({ type: 'window', includeUncontrolled: true })).filter((client) => scoped(client.url, true));
+    const wake = (client) => {
+        try {
+            client.postMessage({ type: 'SATIN_PUSH_PENDING' });
+        }
+        catch {
+            /* Inbox survives a suspended or disappearing client. */
+        }
+    };
+    self.addEventListener('push', (event) => {
+        // Legacy/external mutable declarative messages retain WebKit's visible fallback.
+        // WebKit forbids re-showing them without navigate; this sender never emits them.
+        if (event.notification)
+            return;
+        event.waitUntil((async () => {
+            let payload;
+            try {
+                payload = event.data?.json();
+            }
+            catch {
+                payload = null;
+            }
+            const notification = payload?.satin_push === 1 || payload?.web_push === 8030 ? payload.notification : null;
+            const valid = notification && typeof notification.title === 'string' && notification.title.trim();
+            const target = landing(payload?.routeURL ?? notification?.navigate);
+            await self.registration.showNotification(valid ? notification.title : 'New notification', {
+                body: valid && typeof notification.body === 'string'
+                    ? notification.body
+                    : 'Open the app to see what is new.',
+                data: { url: target?.url ?? null },
+            });
+            const badge = payload?.app_badge;
+            if ((typeof badge === 'string' || typeof badge === 'number') &&
+                /^[0-9]+$/.test(String(badge)) &&
+                Number.isSafeInteger(Number(badge))) {
+                try {
+                    if (Number(badge) === 0)
+                        await self.navigator.clearAppBadge?.();
+                    else
+                        await self.navigator.setAppBadge?.(Number(badge));
+                }
+                catch {
+                    /* Visibility remains platform-owned. */
+                }
+            }
+        })());
+    });
+    self.addEventListener('notificationclick', (event) => {
+        event.notification.close();
+        event.waitUntil(serial(async () => {
+            const target = landing(event.notification.data?.url);
+            const clients = await windows();
+            const client = clients.find((value) => value.focused) ??
+                clients.find((value) => value.visibilityState === 'visible') ??
+                clients[0];
+            if (target) {
+                const inbox = await caches.open(inboxName);
+                await inbox.put(key(target.id), new Response(JSON.stringify({ ...target, clientId: client?.id ?? null })));
+            }
+            if (client) {
+                // Never navigate an existing document, even if focus/message/decoding fails.
+                try {
+                    await client.focus();
+                }
+                catch {
+                    /* Keep the pending route for resume. */
+                }
+                if (target)
+                    wake(client);
+            }
+            else {
+                await self.clients.openWindow(target?.url ?? shell.href);
+            }
+        }));
+    });
+    self.addEventListener('message', (event) => {
+        if (!['SATIN_PUSH_CLAIM', 'SATIN_PUSH_ACK'].includes(event.data?.type) ||
+            !event.source?.id ||
+            !scoped(event.source.url, true))
+            return;
+        event.waitUntil(serial(async () => {
+            const inbox = await caches.open(inboxName);
+            const clients = await windows();
+            if (!clients.some((client) => client.id === event.source.id))
+                return;
+            if (event.data.type === 'SATIN_PUSH_ACK') {
+                if (typeof event.data.id !== 'string' ||
+                    !['accepted', 'rejected'].includes(event.data.result))
+                    return;
+                const request = key(event.data.id), response = await inbox.match(request);
+                const record = response ? await response.json() : null;
+                // A cold URL can be consumed before its first claim.
+                if (record && (record.clientId === null || record.clientId === event.source.id))
+                    await inbox.delete(request);
+                return;
+            }
+            for (const request of await inbox.keys()) {
+                const response = await inbox.match(request);
+                if (!response)
+                    continue;
+                const record = await response.json();
+                if (record.clientId &&
+                    record.clientId !== event.source.id &&
+                    clients.some((client) => client.id === record.clientId))
+                    continue;
+                record.clientId = event.source.id;
+                await inbox.put(request, new Response(JSON.stringify(record)));
+                event.source.postMessage({ type: 'SATIN_PUSH_ROUTE', id: record.id, url: record.url });
+            }
+        }));
+    });
+}

package/dist/sw/registerAppShell.d.ts

@@ -0,0 +1,25 @@
+export interface AppShellBuildState {
+    readonly applying: boolean;
+    readonly current: string | null;
+    readonly waiting: string | null;
+}
+export interface RegisterAppShellOptions {
+    readonly updateProfile?: 'release' | 'preview' | 'hot-reload' | 'dev';
+    readonly updateActivation?: 'cold-launch' | 'cold-launch-or-explicit';
+    readonly activationTimeoutMs?: number;
+    readonly messageTimeoutMs?: number;
+    readonly onStateChange?: (state: AppShellBuildState) => void;
+    readonly scope?: string;
+    readonly serviceWorkerUrl?: string;
+}
+export interface SatinAppShellRegistration {
+    readonly current: string | null;
+    readonly registration: ServiceWorkerRegistration;
+    readonly state: AppShellBuildState;
+    readonly waiting: string | null;
+    applyUpdate(): Promise<boolean>;
+    dispose(): void;
+    refresh(): Promise<AppShellBuildState>;
+    subscribe(listener: (state: AppShellBuildState) => void): () => void;
+}
+export declare function registerAppShell(options?: RegisterAppShellOptions): Promise<SatinAppShellRegistration | null>;