arcane-os 0.9.0 → 0.10.0

package/src/pwa-worker.mjs

@@ -0,0 +1,227 @@
+export function createPwaWorkerScript(manifest) {
+    return `(${installPwaWorker.toString()})(${JSON.stringify(manifest, null, 4)});\n`;
+}
+
+function installPwaWorker(manifest) {
+    const scope = self.registration.scope;
+    const cachePrefix = `arcane-pwa|${JSON.stringify(
+        [manifest.appId, scope]
+    )}|`;
+    const cacheName = cachePrefix + JSON.stringify(
+        [
+            manifest.appVersion,
+            manifest.sdkVersion,
+            manifest.mode,
+            manifest.revision
+        ]
+    );
+
+    function cacheUrl(value) {
+        const url = new URL(value, scope);
+        // Cache matching excludes fragments; preserve queries and the original network request.
+        url.hash = '';
+        return url.href;
+    }
+
+    const assetUrls = [
+        ...new Set(
+            manifest.assets.map(cacheUrl)
+        )
+    ];
+    const ownedUrls = new Set(assetUrls);
+    const navigationAliases = new Map();
+    for (const [alias, asset] of Object.entries(manifest.navigationAliases)) {
+        navigationAliases.set(
+            cacheUrl(alias),
+            new URL(asset, scope).href
+        );
+    }
+
+    function errorDetails(error) {
+        if (!(error instanceof Error)) {
+            return error;
+        }
+        const detail = {name: error.name, message: error.message, stack: error.stack};
+        if ('cause' in error) {
+            detail.cause = errorDetails(error.cause);
+        }
+        if ('errors' in error) {
+            detail.errors = Array.from(error.errors, errorDetails);
+        }
+        if ('url' in error) {
+            detail.url = error.url;
+        }
+        return detail;
+    }
+
+    async function reportFailure(error) {
+        const clients = await self.clients.matchAll(
+            {type: 'window', includeUncontrolled: true}
+        );
+        const message = {type: 'arcane.pwa.error', error: errorDetails(error)};
+        for (const client of clients) {
+            if (client.url.startsWith(scope)) {
+                client.postMessage(message);
+            }
+        }
+    }
+
+    async function populateCache() {
+        const cache = await caches.open(cacheName);
+        const failures = [];
+        let nextAsset = 0;
+
+        async function fetchAssets() {
+            while (nextAsset < assetUrls.length) {
+                const url = assetUrls[nextAsset++];
+                try {
+                    const response = await fetch(
+                        new Request(
+                            url,
+                            {cache: manifest.mode === 'development' ? 'no-cache' : 'reload'}
+                        )
+                    );
+                    if (!response.ok) {
+                        throw new Error(`PWA resource returned HTTP ${response.status} ${response.statusText}: ${url}`);
+                    }
+                    await cache.put(url, response);
+                } catch (cause) {
+                    const error = new Error(
+                        `PWA resource could not be cached: ${url}`,
+                        {cause}
+                    );
+                    error.url = url;
+                    failures.push(error);
+                }
+            }
+        }
+
+        const workers = [];
+        for (let index = 0; index < Math.min(4, assetUrls.length); index += 1) {
+            workers.push(
+                fetchAssets()
+            );
+        }
+        await Promise.all(workers);
+        if (failures.length > 0) {
+            throw new AggregateError(failures, 'The PWA resource generation could not be installed.');
+        }
+    }
+
+    async function reportFailureAndReject(error) {
+        try {
+            await reportFailure(error);
+        } catch (reportError) {
+            console.error('PWA failure could not be sent to application clients.', reportError, error);
+        }
+        throw error;
+    }
+
+    function onInstall(event) {
+        event.waitUntil(
+            populateCache().catch(reportFailureAndReject)
+        );
+    }
+
+    async function retireOldCaches() {
+        const names = await caches.keys();
+        const retirements = [];
+        for (const name of names) {
+            if (name.startsWith(cachePrefix) && name !== cacheName) {
+                retirements.push(
+                    caches.delete(name)
+                );
+            }
+        }
+        await Promise.all(retirements);
+    }
+
+    function onActivate(event) {
+        event.waitUntil(
+            retireOldCaches().catch(reportFailureAndReject)
+        );
+    }
+
+    async function releaseResource(request, url) {
+        const cache = await caches.open(cacheName);
+        const cached = await cache.match(url);
+        if (cached) {
+            return cached;
+        }
+        return fetch(
+            new Request(
+                request,
+                {cache: 'no-cache'}
+            )
+        );
+    }
+
+    async function developmentResource(request, url) {
+        let response;
+        try {
+            response = await fetch(
+                new Request(
+                    request,
+                    {cache: 'no-cache'}
+                )
+            );
+        } catch (error) {
+            const cache = await caches.open(cacheName);
+            const cached = await cache.match(url);
+            if (cached) {
+                return {response: cached, fromNetwork: false, url};
+            }
+            throw error;
+        }
+        return {response, fromNetwork: true, url};
+    }
+
+    function resourceResponse(resource) {
+        return resource.response;
+    }
+
+    async function saveDevelopmentResource(resource) {
+        if (resource.fromNetwork && resource.response.ok) {
+            const response = resource.response.clone();
+            const cache = await caches.open(cacheName);
+            await cache.put(resource.url, response);
+        }
+    }
+
+    function onFetch(event) {
+        const request = event.request;
+        if (request.method !== 'GET' || request.headers.has('range')) {
+            return;
+        }
+        const requestUrl = cacheUrl(request.url);
+        const redirect = request.mode === 'navigate' ? navigationAliases.get(requestUrl) : null;
+        if (redirect && cacheUrl(redirect) !== requestUrl && ownedUrls.has(cacheUrl(redirect))) {
+            // Navigation retains its requested document URL unless it follows a redirect.
+            event.respondWith(
+                Response.redirect(redirect, 302)
+            );
+            return;
+        }
+        const url = requestUrl;
+        if (!ownedUrls.has(url)) {
+            return;
+        }
+        if (manifest.mode === 'development') {
+            const resource = developmentResource(request, url);
+            event.waitUntil(
+                resource.then(saveDevelopmentResource).catch(reportFailureAndReject)
+            );
+            event.respondWith(
+                resource.then(resourceResponse)
+            );
+            return;
+        }
+        event.respondWith(
+            releaseResource(request, url).catch(reportFailureAndReject)
+        );
+    }
+
+    self.addEventListener('install', onInstall);
+    self.addEventListener('activate', onActivate);
+    self.addEventListener('fetch', onFetch);
+}

package/src/pwa.mjs

@@ -0,0 +1,311 @@
+import Is from 'strong-type';
+import {randomUUID} from 'node:crypto';
+import {createPwaWorkerScript} from './pwa-worker.mjs';
+import {versionAssetUrl} from './import-map.mjs';
+
+const is = new Is(false);
+
+export const PWA_MANIFEST_NAME = 'arcane.webmanifest';
+export const PWA_OFFLINE_MANIFEST_NAME = 'arcane-offline.json';
+export const PWA_WORKER_NAME = 'arcane-sw.js';
+export const PWA_BOOTSTRAP_NAME = 'arcane-pwa.mjs';
+
+function record(value, label) {
+    if (value === null || !is.object(value) || is.array(value)) {
+        throw new TypeError(`${label} must be an object.`);
+    }
+    return value;
+}
+
+function pathList(value, label) {
+    function invalidPath(item) {
+        return !is.string(item) || !item;
+    }
+    if (!is.array(value) || value.some(invalidPath)) {
+        throw new TypeError(`${label} must be an array of nonempty paths.`);
+    }
+    return [...value];
+}
+
+export function normalizePwaConfig(value) {
+    if (value === undefined) return undefined;
+    record(value, 'pwa');
+    for (const key of Object.keys(value)) {
+        if (!['enabled', 'manifest', 'offline'].includes(key)) {
+            throw new TypeError(`pwa contains an unsupported field: ${key}.`);
+        }
+    }
+    if (value.enabled !== undefined && !is.boolean(value.enabled)) {
+        throw new TypeError('pwa.enabled must be a boolean.');
+    }
+    const manifest = record(
+        value.manifest === undefined ? {} : value.manifest,
+        'pwa.manifest'
+    );
+    const offline = record(
+        value.offline === undefined ? {} : value.offline,
+        'pwa.offline'
+    );
+    for (const key of Object.keys(offline)) {
+        if (key !== 'include' && key !== 'exclude') {
+            throw new TypeError(`pwa.offline contains an unsupported field: ${key}.`);
+        }
+    }
+    return {
+        enabled: value.enabled === true,
+        manifest: {...manifest},
+        offline: {
+            include: pathList(
+                offline.include === undefined ? [] : offline.include,
+                'pwa.offline.include'
+            ),
+            exclude: pathList(
+                offline.exclude === undefined ? [] : offline.exclude,
+                'pwa.offline.exclude'
+            )
+        }
+    };
+}
+
+function selectedPath(file, selection) {
+    const prefix = selection.endsWith('/') ? selection : `${selection}/`;
+    return file === selection || file.startsWith(prefix);
+}
+
+export function selectPwaFiles(files, pwa) {
+    const config = normalizePwaConfig(pwa);
+    const include = config?.offline.include ?? [];
+    const exclude = config?.offline.exclude ?? [];
+    return files.filter(
+        function selectedOfflineFile(file) {
+            function includedPath(selection) {
+                return selectedPath(file, selection);
+            }
+            function excludedPath(selection) {
+                return selectedPath(file, selection);
+            }
+            return (include.length === 0 || include.some(includedPath))
+                && !exclude.some(excludedPath);
+        }
+    );
+}
+
+function resourceUrl(basePath, file) {
+    const encoded = file.split('/').map(
+        function encodePathSegment(segment) {
+            return encodeURIComponent(segment);
+        }
+    ).join('/');
+    return `${basePath.endsWith('/') ? basePath : `${basePath}/`}${encoded}`;
+}
+
+function json(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function htmlAttribute(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;');
+}
+
+function manifestUrl(value, appBase) {
+    if (!is.string(value) || !value || value.startsWith('/')
+        || /^[A-Za-z][A-Za-z0-9+.-]*:/u.test(value) || /^\s/u.test(value)) {
+        return value;
+    }
+    const base = new URL(appBase, 'https://arcane.invalid/');
+    const resolved = new URL(value, base);
+    const relative = `${resolved.pathname}${resolved.search}${resolved.hash}`;
+    return appBase.startsWith('/') ? relative : `.${relative}`;
+}
+
+function manifestImages(images, appBase) {
+    if (!is.array(images)) return images;
+    return images.map(
+        function mapManifestImage(image) {
+            if (image === null || !is.object(image) || is.array(image)) return image;
+            if (!Object.hasOwn(image, 'src')) return {...image};
+            const url = manifestUrl(image.src, appBase);
+            return {...image, src: versionAssetUrl(url, null)};
+        }
+    );
+}
+
+function applicationManifest(value, appBase) {
+    const manifest = {...value};
+    for (const field of ['id', 'start_url', 'scope']) {
+        if (Object.hasOwn(manifest, field)) {
+            manifest[field] = manifestUrl(manifest[field], appBase);
+        }
+    }
+    for (const field of ['icons', 'screenshots']) {
+        if (Object.hasOwn(manifest, field)) {
+            manifest[field] = manifestImages(manifest[field], appBase);
+        }
+    }
+    if (is.array(manifest.shortcuts)) {
+        manifest.shortcuts = manifest.shortcuts.map(
+            function mapManifestShortcut(shortcut) {
+                if (shortcut === null || !is.object(shortcut) || is.array(shortcut)) return shortcut;
+                const mapped = {...shortcut};
+                if (Object.hasOwn(mapped, 'url')) {
+                    mapped.url = manifestUrl(mapped.url, appBase);
+                }
+                if (Object.hasOwn(mapped, 'icons')) {
+                    mapped.icons = manifestImages(mapped.icons, appBase);
+                }
+                return mapped;
+            }
+        );
+    }
+    return manifest;
+}
+
+function manifestAssets(manifest) {
+    const urls = [manifest.start_url];
+    function appendImages(images) {
+        if (!is.array(images)) return;
+        for (const image of images) {
+            if (is.string(image?.src)) urls.push(image.src);
+        }
+    }
+    appendImages(manifest.icons);
+    appendImages(manifest.screenshots);
+    if (is.array(manifest.shortcuts)) {
+        for (const shortcut of manifest.shortcuts) {
+            if (is.string(shortcut?.url)) urls.push(shortcut.url);
+            appendImages(shortcut?.icons);
+        }
+    }
+    return urls.filter(
+        function manifestUrlString(url) {
+            return is.string(url);
+        }
+    );
+}
+
+function assetPath(url) {
+    const resolved = new URL(url, 'https://arcane.invalid/');
+    return `${resolved.origin}${resolved.pathname}`;
+}
+
+export function createPwaArtifacts(
+    {
+        app,
+        sdkVersion,
+        pwa,
+        files = [],
+        assets,
+        basePath = './',
+        mode = 'release',
+        runtimeBase = './arcane/sdk/',
+        appBase,
+        navigationAliases,
+        revision
+    } = {}
+) {
+    const config = normalizePwaConfig(pwa);
+    if (!config?.enabled) return null;
+    if (mode !== 'release' && mode !== 'development') {
+        throw new TypeError('PWA mode must be release or development.');
+    }
+    const entryUrl = new URL(app.entry, 'https://arcane.invalid/');
+    const applicationBase = appBase ?? (mode === 'development'
+        ? new URL('./', entryUrl).pathname : './');
+    const manifest = applicationManifest(
+        {
+            id: applicationBase,
+            name: app.displayName,
+            short_name: app.displayName,
+            start_url: app.entry,
+            scope: applicationBase,
+            display: 'standalone',
+            ...config.manifest
+        },
+        applicationBase
+    );
+    const generatedAssets = [
+        PWA_MANIFEST_NAME,
+        PWA_OFFLINE_MANIFEST_NAME,
+        PWA_BOOTSTRAP_NAME
+    ].map(
+        function generatedResource(file) {
+            return resourceUrl(basePath, file);
+        }
+    );
+    const selectedFiles = selectPwaFiles(files, config);
+    const selectedAssets = [
+        ...selectedFiles.map(
+            function packagedResource(file) {
+                return resourceUrl(basePath, file);
+            }
+        ),
+        ...(assets ?? []),
+        app.entry
+    ];
+    const selectedPaths = new Set(
+        selectedAssets.map(assetPath)
+    );
+    // Manifest URLs may retain functional queries. Cache those variants only
+    // when their resource already belongs to the selected application inventory.
+    const metadataAssets = manifestAssets(manifest).filter(
+        function selectedManifestAsset(url) {
+            return selectedPaths.has(
+                assetPath(url)
+            );
+        }
+    );
+    const workerUrl = resourceUrl(basePath, PWA_WORKER_NAME);
+    const workerPath = new URL(workerUrl, 'https://arcane.invalid/').pathname;
+    const allAssets = new Set(
+        [
+            ...selectedAssets,
+            ...metadataAssets,
+            ...generatedAssets
+        ]
+    );
+    const offlineManifest = {
+        schemaVersion: 1,
+        appId: app.id,
+        appVersion: app.version,
+        sdkVersion,
+        revision: revision ?? (mode === 'development' ? 'development' : randomUUID()),
+        mode,
+        assets: [...allAssets].filter(
+            function excludeWorker(url) {
+                return new URL(url, 'https://arcane.invalid/').pathname !== workerPath;
+            }
+        ),
+        navigationAliases: navigationAliases ?? {[basePath]: app.entry}
+    };
+    const bootstrap = `import {registerPwa} from ${JSON.stringify(`${runtimeBase}pwa.mjs`)};
+
+const controller = registerPwa(
+    {
+        workerUrl: new URL('./${PWA_WORKER_NAME}', import.meta.url).href,
+        scope: new URL('./', import.meta.url).href
+    }
+);
+
+controller.ready.catch(
+    function reportPwaRegistrationFailure(error) {
+        console.error('Arcane PWA registration failed:', error);
+    }
+);
+`;
+    const entryAssets = {manifest: PWA_MANIFEST_NAME, bootstrap: PWA_BOOTSTRAP_NAME};
+    const manifestHref = resourceUrl(basePath, entryAssets.manifest);
+    const bootstrapHref = resourceUrl(basePath, entryAssets.bootstrap);
+    return {
+        manifest,
+        offlineManifest,
+        files: [
+            {path: PWA_MANIFEST_NAME, content: json(manifest)},
+            {path: PWA_OFFLINE_MANIFEST_NAME, content: json(offlineManifest)},
+            {path: PWA_WORKER_NAME, content: createPwaWorkerScript(offlineManifest)},
+            {path: PWA_BOOTSTRAP_NAME, content: bootstrap}
+        ],
+        entryAssets,
+        entryMarkup: `<link rel="manifest" href="${htmlAttribute(manifestHref)}">\n`
+            + `<script type="module" async data-arcane-pwa src="${htmlAttribute(bootstrapHref)}"></script>\n`
+    };
+}

package/src/targets/index.mjs

@@ -136,6 +136,7 @@ const browserAdapter={
         const release=await packageApp({
             workspaceRoot,
             appId,
+            browserPwa:true,
             dryRun,
             signal,
             onEvent,

package/src/toolchain.mjs

@@ -863,6 +863,7 @@ async function packageNativeRelease(prepared,app,{
     const release=await packageApp({
         workspaceRoot:prepared.workspaceRoot,
         appId:app.appId,
+        browserPwa:false,
         workspaceOperationLease,
         signal,
         onEvent