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

package/dist/push/routes.js

@@ -0,0 +1,63 @@
+export function validatePushRoute(route, rules) {
+    const rule = Object.hasOwn(rules, route?.screen ?? '') ? rules[route.screen] : undefined;
+    if (!rule || (route.tab !== undefined && !rule.tabs?.includes(route.tab)))
+        throw new Error('Unknown push destination');
+    if (route.version !== undefined && !Number.isInteger(route.version))
+        throw new Error('Invalid route version');
+    if (rule.version !== undefined && route.version !== rule.version)
+        throw new Error('Incompatible route version');
+    const params = route.params ?? {};
+    if (!params ||
+        typeof params !== 'object' ||
+        Array.isArray(params) ||
+        (rule.schemaOwned
+            ? Object.keys(params).some(key => !rule.params.includes(key) ||
+                !['string', 'number', 'boolean'].includes(typeof params[key]) ||
+                (typeof params[key] === 'number' && !Number.isFinite(params[key])) ||
+                (typeof params[key] === 'string' && params[key].length > 256))
+            : Object.keys(params).length !== rule.params.length ||
+                rule.params.some(key => !Object.hasOwn(params, key) ||
+                    typeof params[key] !== 'string' ||
+                    params[key].length > 256)))
+        throw new Error('Invalid route parameters');
+    if (rule.validate && !rule.validate(route.params))
+        throw new Error('Invalid route parameters');
+    return {
+        screen: route.screen,
+        ...(route.params === undefined ? {} : { params }),
+        ...(route.tab ? { tab: route.tab } : {}),
+        ...(route.version !== undefined ? { version: route.version } : {}),
+    };
+}
+export function encodePushRoute(base, route, rules, deliveryId) {
+    if (typeof deliveryId !== 'string' || !deliveryId || deliveryId.length > 128)
+        throw new Error('Invalid delivery ID');
+    const url = new URL(base);
+    if (url.protocol !== 'https:' ||
+        url.username ||
+        url.password ||
+        !url.pathname.endsWith('/') ||
+        url.search ||
+        url.hash)
+        throw new Error('Use an HTTPS app scope URL');
+    url.searchParams.set('satin-push', JSON.stringify(validatePushRoute(route, rules)));
+    url.searchParams.set('satin-delivery', deliveryId);
+    return url.href;
+}
+export function decodePushRoute(input, base, rules) {
+    try {
+        const url = new URL(input, base), scope = new URL(base);
+        if (url.username ||
+            url.password ||
+            url.origin !== scope.origin ||
+            url.pathname !== scope.pathname)
+            return null;
+        const raw = url.searchParams.get('satin-push'), id = url.searchParams.get('satin-delivery');
+        return raw && id && id.length <= 128
+            ? { route: validatePushRoute(JSON.parse(raw), rules), id }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/push/schema.d.ts

@@ -0,0 +1,42 @@
+/** One route parameter's validator, made by `param`. */
+export interface Parameter<T> {
+    readonly accepts: (value: unknown) => value is T;
+    optional(): Parameter<T | undefined>;
+}
+/**
+ * Route parameter types: `string`, `int`, `number` (finite), `boolean` and `enum`, each with
+ * `.optional()`. The same schema validates navigation, restoration and notification deep links.
+ *
+ * @example
+ * const params = { id: param.string(), tab: param.enum(['notes', 'files']).optional() }
+ */
+export declare const param: Readonly<{
+    string: () => Parameter<string>;
+    int: () => Parameter<number>;
+    number: () => Parameter<number>;
+    boolean: () => Parameter<boolean>;
+    enum: <const T extends readonly string[]>(values: T) => Parameter<T[number]>;
+}>;
+/** A route's parameters by name. */
+export type ParameterSchema = Readonly<Record<string, Parameter<unknown>>>;
+/** The value described by a route parameter declaration. */
+export type RouteParameterValue<P> = P extends Parameter<infer T> ? T : never;
+/** The props a route component receives for a parameter schema; optional params are optional. */
+export type RouteParameters<S extends ParameterSchema> = {
+    [K in keyof S as undefined extends RouteParameterValue<S[K]> ? never : K]: RouteParameterValue<S[K]>;
+} & {
+    [K in keyof S as undefined extends RouteParameterValue<S[K]> ? K : never]?: RouteParameterValue<S[K]>;
+};
+/** Shared by app declarations and the server relay; contains no UI imports. */
+export declare function validateParameters(schema: ParameterSchema, value: unknown): boolean;
+export declare function notificationRoutes(definitions: Readonly<Record<string, {
+    params?: ParameterSchema;
+}>>, tabs?: readonly string[]): {
+    [k: string]: {
+        params: string[];
+        version: number;
+        schemaOwned: boolean;
+        tabs?: readonly string[] | undefined;
+        validate: (value: unknown) => boolean;
+    };
+};

package/dist/push/schema.js

@@ -0,0 +1,41 @@
+function parameter(accepts) {
+    return Object.freeze({
+        accepts,
+        optional: () => parameter((value) => value === undefined || accepts(value)),
+    });
+}
+/**
+ * Route parameter types: `string`, `int`, `number` (finite), `boolean` and `enum`, each with
+ * `.optional()`. The same schema validates navigation, restoration and notification deep links.
+ *
+ * @example
+ * const params = { id: param.string(), tab: param.enum(['notes', 'files']).optional() }
+ */
+export const param = Object.freeze({
+    string: () => parameter((value) => typeof value === 'string'),
+    int: () => parameter((value) => typeof value === 'number' && Number.isSafeInteger(value)),
+    number: () => parameter((value) => typeof value === 'number' && Number.isFinite(value)),
+    boolean: () => parameter((value) => typeof value === 'boolean'),
+    enum: (values) => parameter((value) => typeof value === 'string' && values.includes(value)),
+});
+/** Shared by app declarations and the server relay; contains no UI imports. */
+export function validateParameters(schema, value) {
+    if (value === undefined)
+        value = {};
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    return (Object.keys(descriptors).every(key => Object.hasOwn(schema, key) && 'value' in descriptors[key]) && Object.entries(schema).every(([key, field]) => field.accepts(descriptors[key]?.value)));
+}
+export function notificationRoutes(definitions, tabs) {
+    return Object.fromEntries(Object.entries(definitions).map(([id, options]) => [
+        id,
+        {
+            params: Object.keys(options.params ?? {}),
+            version: 1,
+            schemaOwned: true,
+            ...(tabs ? { tabs } : {}),
+            validate: (value) => validateParameters(options.params ?? {}, value),
+        },
+    ]));
+}

package/dist/push/urlProjection.d.ts

@@ -0,0 +1,24 @@
+import { type PushRoute, type PushRouteRules } from './routes.js';
+/** One ordered queue for direct URLs and worker deliveries. Rejected navigation
+ * stays pending until navigation or presentation ownership changes. */
+export declare function createRouteIntentQueue(subscribeNavigation: (listener: () => void) => () => void): {
+    enqueue(id: string, activate: () => boolean): void;
+    drain: () => void;
+    connect(): () => void;
+};
+/** Pending taps are acknowledged after acceptance and the optional durability gate. */
+export declare function connectPushRoutes<Params extends Record<string, string | number | boolean> = Record<string, string>>(options: {
+    scope: string;
+    queue?: ReturnType<typeof createRouteIntentQueue>;
+    hasAccepted?: (id: string) => boolean;
+    didAccept?: (id: string) => void;
+    /** A restoring scene keeps the worker inbox until its destination is durable. */
+    canAcknowledge?: (id: string) => boolean;
+    routes: PushRouteRules;
+    navigate: (route: PushRoute<Params>) => boolean;
+    subscribeNavigation: (listener: () => void) => () => void;
+}): () => void;
+/** Consume a launch/shortcut intent after the navigator accepts it. */
+export declare function consumeSceneLaunchURL(input: string): void;
+/** Remove authorization response parameters only after the callback is durable. */
+export declare function consumeWebAuthenticationURL(input: string): void;

package/dist/push/urlProjection.js

@@ -0,0 +1,207 @@
+import { hasActivePresentation, subscribePresentationActivity } from '../presentation/activity.js';
+import { decodePushRoute } from './routes.js';
+/** One ordered queue for direct URLs and worker deliveries. Rejected navigation
+ * stays pending until navigation or presentation ownership changes. */
+export function createRouteIntentQueue(subscribeNavigation) {
+    const pending = new Map();
+    let draining = false, queued = false, connections = 0;
+    const drain = () => {
+        if (draining || hasActivePresentation())
+            return;
+        draining = true;
+        try {
+            for (const [id, activate] of pending) {
+                if (!activate())
+                    break;
+                pending.delete(id);
+            }
+        }
+        finally {
+            draining = false;
+        }
+    };
+    const changed = () => {
+        if (!queued) {
+            queued = true;
+            queueMicrotask(() => {
+                queued = false;
+                if (connections)
+                    drain();
+            });
+        }
+    };
+    return {
+        enqueue(id, activate) {
+            pending.set(id, activate);
+            drain();
+        },
+        drain,
+        connect() {
+            connections++;
+            let active = true;
+            const notify = () => {
+                if (active)
+                    changed();
+            };
+            const stopNavigation = subscribeNavigation(notify);
+            const stopPresentation = subscribePresentationActivity(notify);
+            drain();
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                connections--;
+                stopNavigation();
+                stopPresentation();
+            };
+        },
+    };
+}
+/** Pending taps are acknowledged after acceptance and the optional durability gate. */
+export function connectPushRoutes(options) {
+    const scope = new URL(options.scope, location.origin).href;
+    const seen = new Set();
+    const queue = options.queue ?? createRouteIntentQueue(options.subscribeNavigation);
+    let worker = navigator.serviceWorker?.controller, disposed = false;
+    const ack = (id, result) => {
+        try {
+            worker?.postMessage({ type: 'SATIN_PUSH_ACK', id, result });
+        }
+        catch {
+            /* Retry after reconnect; do not consume the worker inbox. */
+        }
+    };
+    const awaitingPersistence = new Set();
+    const acknowledgeReady = () => {
+        for (const id of awaitingPersistence) {
+            if (options.canAcknowledge && !options.canAcknowledge(id))
+                continue;
+            if (decodePushRoute(location.href, scope, options.routes)?.id === id) {
+                const clean = new URL(location.href);
+                clean.searchParams.delete('satin-push');
+                clean.searchParams.delete('satin-delivery');
+                window.history.replaceState(window.history.state, '', clean.href);
+            }
+            ack(id, 'accepted');
+            awaitingPersistence.delete(id);
+        }
+    };
+    const accept = (url, messageId) => {
+        const decoded = decodePushRoute(url, scope, options.routes);
+        if (!decoded || (messageId !== undefined && decoded.id !== messageId)) {
+            if (messageId) {
+                // Do not log the URL or params: notification routes can contain private data.
+                console.warn('[Satin push] Rejected delivery: route scope, version, schema or delivery ID did not match.');
+                ack(messageId, 'rejected');
+            }
+            return;
+        }
+        queue.enqueue(`push:${decoded.id}`, () => {
+            if (disposed)
+                return true;
+            if (!seen.has(decoded.id) && !options.hasAccepted?.(decoded.id)) {
+                if (!options.navigate(decoded.route))
+                    return false;
+                seen.add(decoded.id);
+                options.didAccept?.(decoded.id);
+            }
+            awaitingPersistence.add(decoded.id);
+            acknowledgeReady();
+            return true;
+        });
+    };
+    const claim = () => {
+        try {
+            if (!disposed)
+                worker?.postMessage({ type: 'SATIN_PUSH_CLAIM' });
+        }
+        catch {
+            /* Resume/controllerchange retries. */
+        }
+    };
+    const resume = () => {
+        accept(location.href);
+        queue.drain();
+        acknowledgeReady();
+        claim();
+    };
+    const message = (event) => {
+        if (!worker || event.source !== worker)
+            return;
+        if (event.data?.type === 'SATIN_PUSH_PENDING')
+            claim();
+        if (event.data?.type === 'SATIN_PUSH_ROUTE' &&
+            typeof event.data.url === 'string' &&
+            typeof event.data.id === 'string')
+            accept(event.data.url, event.data.id);
+    };
+    const controllerChanged = () => {
+        worker = navigator.serviceWorker?.controller;
+        resume();
+    };
+    // Durability must not hold the navigation queue hostage when storage fails.
+    let persistenceQueued = false;
+    const unsubscribePersistence = options.canAcknowledge
+        ? options.subscribeNavigation(() => {
+            if (persistenceQueued)
+                return;
+            persistenceQueued = true;
+            queueMicrotask(() => {
+                persistenceQueued = false;
+                if (!disposed)
+                    acknowledgeReady();
+            });
+        })
+        : () => { };
+    const unsubscribe = queue.connect();
+    navigator.serviceWorker?.addEventListener('message', message);
+    navigator.serviceWorker?.addEventListener('controllerchange', controllerChanged);
+    window.addEventListener('pageshow', resume);
+    document.addEventListener('visibilitychange', resume);
+    resume();
+    // An existing uncontrolled document must claim from the same scoped registration too.
+    void navigator.serviceWorker
+        ?.getRegistration?.(scope)
+        .then(registration => {
+        if (!disposed && !worker && registration?.scope === scope && registration.active) {
+            worker = registration.active;
+            resume();
+        }
+    })
+        .catch(() => { });
+    return () => {
+        disposed = true;
+        unsubscribe();
+        unsubscribePersistence();
+        navigator.serviceWorker?.removeEventListener('message', message);
+        navigator.serviceWorker?.removeEventListener('controllerchange', controllerChanged);
+        window.removeEventListener('pageshow', resume);
+        document.removeEventListener('visibilitychange', resume);
+    };
+}
+/** Consume a launch/shortcut intent after the navigator accepts it. */
+export function consumeSceneLaunchURL(input) {
+    if (typeof location === 'undefined' || location.href !== input)
+        return;
+    const clean = new URL(input);
+    clean.searchParams.delete('satin-route');
+    clean.searchParams.delete('satin-tab');
+    window.history.replaceState(window.history.state, '', clean.href);
+}
+/** Remove authorization response parameters only after the callback is durable. */
+export function consumeWebAuthenticationURL(input) {
+    if (typeof location === 'undefined' || location.href !== input)
+        return;
+    const clean = new URL(input);
+    for (const name of [
+        'code',
+        'state',
+        'error',
+        'error_description',
+        'error_uri',
+        'session_state',
+        'iss',
+    ])
+        clean.searchParams.delete(name);
+    window.history.replaceState(window.history.state, '', clean.href);
+}

package/dist/reachability/controller.d.ts

@@ -0,0 +1,21 @@
+import { type ReachabilityProfile } from './model.js';
+export interface ReachabilityEnvironment {
+    online(): boolean;
+    fetch: typeof fetch;
+    listen(event: 'online' | 'offline' | 'resume', callback: () => void): () => void;
+    observeImageFailures?(callback: (source: string) => void): () => void;
+    retryImages?(serverOrigin: string): void;
+}
+export declare const browserReachabilityEnvironment: ReachabilityEnvironment;
+/** Effect-owned adapter: construction is inert, start/dispose own all browser work. */
+export declare function createReachabilityController(profile: ReachabilityProfile, route: string, env: ReachabilityEnvironment): {
+    getSnapshot: () => import("./model.js").ReachabilityState;
+    subscribe(listener: () => void): () => void;
+    setRoute: (nextRoute: string) => void;
+    recheck: () => void;
+    fetch: typeof fetch;
+    /** Report only app-server transport outcomes, never JSON or application errors. */
+    reportFetchOutcome: (outcome: 'response' | 'network-failure' | 'aborted') => void;
+    start(): void;
+    dispose(): void;
+};

package/dist/reachability/controller.js

@@ -0,0 +1,202 @@
+import { createReachabilityState, reduceReachability, } from './model.js';
+export const browserReachabilityEnvironment = {
+    online: () => navigator.onLine,
+    fetch: (...args) => fetch(...args),
+    retryImages(serverOrigin) {
+        for (const image of document.images) {
+            if (image.dataset.satinImageSource || !image.complete || image.naturalWidth !== 0)
+                continue;
+            const source = image.currentSrc || image.src;
+            if (source && new URL(source, location.href).origin === serverOrigin)
+                image.src = source;
+        }
+    },
+    observeImageFailures(callback) {
+        const failed = (event) => {
+            if (!(event.target instanceof HTMLImageElement))
+                return;
+            const image = event.target;
+            callback(image.dataset.satinImageSource || image.currentSrc || image.src);
+        };
+        document.addEventListener('error', failed, true);
+        return () => document.removeEventListener('error', failed, true);
+    },
+    listen(event, callback) {
+        if (event === 'resume') {
+            const resume = () => {
+                if (document.visibilityState === 'visible')
+                    callback();
+            };
+            document.addEventListener('visibilitychange', resume);
+            return () => document.removeEventListener('visibilitychange', resume);
+        }
+        window.addEventListener(event, callback);
+        return () => window.removeEventListener(event, callback);
+    },
+};
+/** Effect-owned adapter: construction is inert, start/dispose own all browser work. */
+export function createReachabilityController(profile, route, env) {
+    let reduction = createReachabilityState(profile, {
+        navigatorOnline: profile.connectivity === 'local' ? true : env.online(),
+        route,
+    });
+    let state = reduction.state;
+    let active = false;
+    let observationEpoch = 0;
+    let cancelProbe;
+    let cleanups = [];
+    const listeners = new Set();
+    const notify = (previous) => {
+        for (const listener of listeners)
+            listener();
+        const material = previous.connectivity === 'server' &&
+            state.connectivity === 'server' &&
+            (previous.status === 'device-offline' || previous.status === 'server-unreachable') &&
+            state.status === 'reachable';
+        if (material && profile.connectivity === 'server') {
+            const base = typeof location === 'undefined' ? 'http://satin.local/' : location.href;
+            env.retryImages?.(new URL(profile.reachability.probe.url, base).origin);
+        }
+    };
+    const apply = (next) => {
+        const previous = state;
+        reduction = next;
+        state = next.state;
+        if (!active)
+            return;
+        cancelProbe?.();
+        cancelProbe = undefined;
+        for (const command of next.commands) {
+            if (command.type !== 'probe')
+                continue;
+            const controller = new AbortController();
+            let cancelled = false;
+            const timeout = setTimeout(() => controller.abort(), command.probe.timeoutMs);
+            cancelProbe = () => {
+                cancelled = true;
+                clearTimeout(timeout);
+                controller.abort();
+            };
+            void env
+                .fetch(command.probe.url, {
+                method: command.probe.method,
+                cache: 'no-store',
+                redirect: 'error',
+                signal: controller.signal,
+            })
+                .then(() => 'reachable', () => 'unreachable')
+                .then(result => {
+                clearTimeout(timeout);
+                if (!cancelled && active)
+                    dispatch({ type: 'probe-result', probeId: command.probeId, result });
+            });
+        }
+        notify(previous);
+    };
+    const dispatch = (event) => {
+        if (event.type === 'browser-offline' ||
+            event.type === 'browser-online' ||
+            event.type === 'resume')
+            observationEpoch++;
+        const next = reduceReachability(state, event);
+        // Route changes and ignored stale/aborted outcomes must not cancel an in-flight probe.
+        if (state.connectivity === 'server' &&
+            next.state.connectivity === 'server' &&
+            next.state.pendingProbeId === state.pendingProbeId &&
+            !next.commands.some(c => c.type === 'probe')) {
+            const previous = state;
+            state = next.state;
+            notify(previous);
+            return;
+        }
+        apply(next);
+    };
+    const serverRequest = (input) => {
+        if (profile.connectivity !== 'server')
+            return false;
+        const base = typeof location === 'undefined' ? 'http://satin.local/' : location.href;
+        const url = new URL(typeof input === 'string' || input instanceof URL ? input : input.url, base);
+        return url.origin === new URL(profile.reachability.probe.url, base).origin;
+    };
+    const serverFetch = async (input, init) => {
+        const reportsOutcome = serverRequest(input);
+        const epoch = observationEpoch;
+        const signal = init?.signal !== undefined
+            ? init.signal
+            : typeof input === 'object' && 'signal' in input
+                ? input.signal
+                : undefined;
+        const canReport = () => active && epoch === observationEpoch && reportsOutcome;
+        try {
+            const response = await env.fetch(input, init);
+            if (canReport() &&
+                state.connectivity === 'server' &&
+                state.navigatorOnline &&
+                state.status !== 'reachable' &&
+                state.pendingProbeId === undefined) {
+                // Fetch preserves the caller's caching policy. A response proves data
+                // availability, not transport recovery; only the uncached probe does that.
+                dispatch({ type: 'recheck' });
+            }
+            return response;
+        }
+        catch (error) {
+            if (canReport())
+                dispatch({
+                    type: 'fetch-outcome',
+                    outcome: signal?.aborted || (error instanceof Error && error.name === 'AbortError')
+                        ? 'aborted'
+                        : 'network-failure',
+                });
+            throw error;
+        }
+    };
+    return {
+        getSnapshot: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        setRoute: (nextRoute) => dispatch({ type: 'route-changed', route: nextRoute }),
+        recheck: () => dispatch({ type: 'recheck' }),
+        fetch: serverFetch,
+        /** Report only app-server transport outcomes, never JSON or application errors. */
+        reportFetchOutcome: (outcome) => dispatch({ type: 'fetch-outcome', outcome }),
+        start() {
+            if (active || profile.connectivity === 'local')
+                return;
+            active = true;
+            observationEpoch++;
+            apply(createReachabilityState(profile, {
+                navigatorOnline: env.online(),
+                route: state.connectivity === 'server' ? state.route : route,
+            }));
+            cleanups = [
+                env.listen('online', () => dispatch({ type: 'browser-online' })),
+                env.listen('offline', () => dispatch({ type: 'browser-offline' })),
+                env.listen('resume', () => dispatch({ type: 'resume', navigatorOnline: env.online() })),
+            ];
+            if (env.observeImageFailures)
+                cleanups.push(env.observeImageFailures(source => {
+                    // An img error cannot distinguish a 404/corrupt image from transport
+                    // loss. Confirm with the declared probe, and coalesce an error burst.
+                    if (state.connectivity !== 'server' ||
+                        !serverRequest(source) ||
+                        state.pendingProbeId !== undefined ||
+                        (state.status !== 'reachable' && state.status !== 'unknown'))
+                        return;
+                    dispatch({ type: 'recheck' });
+                }));
+        },
+        dispose() {
+            active = false;
+            observationEpoch++;
+            cancelProbe?.();
+            cancelProbe = undefined;
+            cleanups.forEach(fn => fn());
+            cleanups = [];
+        },
+    };
+}