arcane-os 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.10.0
+
+- Add opt-in application PWA configuration, generated installation and offline
+  manifests, a stable service worker and asynchronous registration bootstrap.
+  Keep branding and offline resource selection application-owned.
+- Expose `registerPwa()` and `PWA_STATE_EVENT` through `arcane-os/pwa`, with
+  current-state replay, native update lifecycle, complete errors and disposal.
+  Keep registration independent of rendering, preferences and model startup.
+- Use clean local resource URLs for enabled PWA browser delivery. Remove `v`
+  and `arcaneVersion` from actual references and managed import-map aliases,
+  preserving meaningful queries, fragments and unrelated payloads. Dynamic
+  HTML imports follow the same document-owned selection.
+- Revalidate PWA source resources for live development and retain selected
+  successful responses offline. Packaged output uses a separate cache generation
+  for each deployment revision, bounded concurrent installation and normal
+  browser activation. Preserve user data, model caches and native packaging.
+
+## 0.9.0
+
+- Add `getBrowserDeviceClass()` through the dependency-free
+  `arcane-os/browser-device` entrypoint and managed browser import map. Return
+  `mobile` or `desktop` from browser identity hints, including Android tablets
+  and iPadOS Mac-platform touch identity, for application-owned settings.
+- Keep classification independent of model imports, GPU requests, network,
+  storage, listeners, and viewport changes. Missing or unrecognized identity
+  defaults to `desktop`; the result does not claim hardware capability or
+  model readiness, and existing provider defaults remain unchanged.
+
 ## 0.8.1
 
 - Use `arcaneVersion` as the sole local resource version field across import maps,

package/README.md

@@ -19,10 +19,16 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.8.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.10.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
+Applications can enable [PWA installation and offline resources](docs/reference/pwa.md)
+through their app descriptor. The SDK generates manifests, an independent
+registration module and a service worker, with clean browser resource URLs,
+live-source revalidation and selected release caches. Apps retain ownership of
+branding, offline page selection and network-dependent product behavior.
+
 That registry query is a maintainer action, not an application behavior. Apps
 never poll npm for SDK updates or replace their own SDK or synchronized runtime.
 The app repository's exact dependency and lockfile select the SDK; changing that
@@ -35,7 +41,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.8.1 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.10.0 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -386,7 +392,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.8.1 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.10.0 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run dev
@@ -396,7 +402,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.8.1
+npm install --save-dev --save-exact arcane-os@0.10.0
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -412,7 +418,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.8.1` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.10.0` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -432,7 +438,7 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.8.1.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.10.0.tgz
 npm ci
 ```
 
@@ -441,7 +447,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.8.1` registry package and
+the local declaration with the exact `arcane-os@0.10.0` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -580,7 +586,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.8.1` exposes one browser target and five explicitly paired
+Version `0.10.0` exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The

package/browser-runtime/browser-device.mjs

@@ -0,0 +1,13 @@
+/** Selects application settings from browser identity hints, including tablets. */
+export function getBrowserDeviceClass(navigatorObject = globalThis.navigator) {
+    const userAgent = String(navigatorObject?.userAgent ?? '');
+    const clientHints = navigatorObject?.userAgentData;
+    const platform = String(clientHints?.platform || navigatorObject?.platform || '');
+    const mobile = clientHints?.mobile === true
+        || /\b(?:Android|iOS|iPhone|iPad|iPod)\b/iu.test(platform)
+        || /\b(?:Android|iPhone|iPad|iPod|Mobile)\b/iu.test(userAgent)
+        // iPadOS can identify as a Mac while retaining its touch capabilities.
+        || (/\b(?:MacIntel|Macintosh|macOS)\b/iu.test(platform)
+            && navigatorObject?.maxTouchPoints > 1);
+    return mobile ? 'mobile' : 'desktop';
+}

package/browser-runtime/pwa.mjs

@@ -0,0 +1,215 @@
+import {createArcaneEventSource} from './event-manager.mjs';
+
+export const PWA_STATE_EVENT = 'arcane.pwa.state';
+
+export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
+    const owner = {
+        get ready() {
+            return ready;
+        },
+        get state() {
+            return snapshot();
+        },
+        subscribe,
+        dispose,
+        update
+    };
+    const source = createArcaneEventSource(
+        owner,
+        {
+            source: 'arcane.pwa',
+            eventTypes: [PWA_STATE_EVENT]
+        }
+    );
+    const container = globalThis.navigator?.serviceWorker;
+    const listeners = [];
+    const workers = new Map();
+    let registration = null;
+    let disposed = false;
+    let current = {
+        status: 'registering',
+        workerUrl: String(workerUrl),
+        scope: scope === undefined ? null : String(scope),
+        controller: null,
+        installing: null,
+        waiting: null,
+        active: null,
+        error: null
+    };
+
+    function snapshot() {
+        return {...current};
+    }
+
+    function publish(status, error = null) {
+        if (disposed) {
+            return;
+        }
+        current = {
+            status,
+            workerUrl: current.workerUrl,
+            scope: registration?.scope ?? current.scope,
+            controller: container?.controller?.state ?? null,
+            installing: registration?.installing?.state ?? null,
+            waiting: registration?.waiting?.state ?? null,
+            active: registration?.active?.state ?? null,
+            error
+        };
+        source.dispatch(
+            PWA_STATE_EVENT,
+            snapshot()
+        );
+    }
+
+    function observe(target, eventName, listener) {
+        target.addEventListener(eventName, listener);
+        listeners.push(
+            function removeNativeListener() {
+                target.removeEventListener(eventName, listener);
+            }
+        );
+    }
+
+    function currentStatus() {
+        if (registration.waiting) {
+            return 'waiting';
+        }
+        if (registration.installing) {
+            return 'installing';
+        }
+        return registration.active ? 'active' : 'registered';
+    }
+
+    function onWorkerStateChange(event) {
+        const previousState = workers.get(event.target);
+        workers.set(event.target, event.target.state);
+        // A newer installation normally supersedes an already waiting worker.
+        if (event.target.state === 'redundant'
+            && previousState !== 'activated' && previousState !== 'installed') {
+            publish('error', current.error ?? new Error('The PWA worker became redundant before activation.'));
+            return;
+        }
+        refreshRegistration();
+    }
+
+    function watchWorker(worker) {
+        if (!worker || workers.has(worker)) {
+            return;
+        }
+        workers.set(worker, worker.state);
+        observe(worker, 'statechange', onWorkerStateChange);
+    }
+
+    function refreshRegistration() {
+        if (disposed) {
+            return;
+        }
+        watchWorker(registration.installing);
+        watchWorker(registration.waiting);
+        watchWorker(registration.active);
+        publish(currentStatus());
+    }
+
+    function onControllerChange() {
+        refreshRegistration();
+    }
+
+    function onWorkerMessage(event) {
+        if (event.data?.type === 'arcane.pwa.error' && workers.has(event.source)) {
+            publish('error', event.data.error);
+        }
+    }
+
+    function onRegistered(value) {
+        registration = value;
+        if (!disposed) {
+            observe(registration, 'updatefound', refreshRegistration);
+            observe(container, 'controllerchange', onControllerChange);
+            observe(container, 'message', onWorkerMessage);
+            refreshRegistration();
+        }
+        return registration;
+    }
+
+    function onRegistrationError(error) {
+        publish('error', error);
+        throw error;
+    }
+
+    function startRegistration() {
+        if (!container) {
+            publish('unsupported');
+            return Promise.resolve(null);
+        }
+        try {
+            const url = new URL(workerUrl, globalThis.document?.baseURI ?? globalThis.location?.href);
+            const registrationScope = new URL(scope ?? './', url);
+            current.workerUrl = url.href;
+            current.scope = registrationScope.href;
+            const registered = container.register(
+                url.href,
+                {
+                    scope: registrationScope.href,
+                    updateViaCache: 'none'
+                }
+            );
+            return Promise.resolve(registered).then(onRegistered).catch(onRegistrationError);
+        } catch (error) {
+            publish('error', error);
+            return Promise.reject(error);
+        }
+    }
+
+    function subscribe(listener, {emitCurrent = true, signal} = {}) {
+        function forwardPwaState(event) {
+            listener(event.detail);
+        }
+        const unsubscribe = source.on(PWA_STATE_EVENT, forwardPwaState, signal ? {signal} : undefined);
+        try {
+            if (emitCurrent && !signal?.aborted) {
+                listener(snapshot());
+            }
+        } catch (error) {
+            unsubscribe();
+            throw error;
+        }
+        return unsubscribe;
+    }
+
+    async function update() {
+        const value = await ready;
+        if (disposed) {
+            throw new Error('The PWA registration owner has been disposed.');
+        }
+        if (!value) {
+            return null;
+        }
+        try {
+            return await value.update();
+        } catch (error) {
+            publish('error', error);
+            throw error;
+        }
+    }
+
+    function dispose() {
+        if (disposed) {
+            return;
+        }
+        current = {...current, status: 'disposed'};
+        disposed = true;
+        source.dispatch(
+            PWA_STATE_EVENT,
+            snapshot()
+        );
+        for (const removeListener of listeners) {
+            removeListener();
+        }
+        listeners.length = 0;
+        workers.clear();
+        source.dispose();
+    }
+
+    const ready = startRegistration();
+    return owner;
+}

package/docs/architecture.md

@@ -289,7 +289,7 @@ paths are withheld from the native provider. The provider copies the complete
 selected release rather than accepting an unrelated source path. Verification
 is a separate explicit operation for a selected release artifact.
 
-The SDK `0.8.1` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.9.0` runtime requires Arcane `0.8.12` or newer. Compatibility
 is contractual rather than exact-version pinning: the prepared Core must meet
 the highest minimum declared by the runtime, selected app, and bundled app
 dependencies; keep each app's Arcane protocol generation; and provide every

package/docs/reference/README.md

@@ -36,6 +36,7 @@ alone does not make bare module names resolve in a browser.
 | Publish central events, capture complete time-travel history, or observe the DOM | [EventManager and event-stack reference](event-manager.md) |
 | Inspect complete AI and speech calls using the shared developer-mode preference | [Shared logger](sdk-api.md#arcanelogging) and [speech developer diagnostics](ai/browser-speech.md#developer-diagnostics) |
 | Use the `arcane` command | [CLI reference](cli.md) |
+| Install an app and cache selected resources offline | [Progressive web applications](pwa.md) |
 | Generate named browser imports or inspect the selected physical runtime | [`arcane import-map`](cli.md#arcane-import-map) and [browser runtime delivery](protocols.md#browser-runtime-delivery) |
 | Choose browser, native, cloud, or cross-host behavior | [Availability and normalization](availability-and-normalization.md) |
 | Import a shipped renderer module | [Runtime module catalog](runtime-modules.md) |
@@ -124,12 +125,13 @@ Public reference entries follow the established Arcane documentation model:
 
 ## Public runtime inventory
 
-The package exposes 202 semantic JavaScript records across 18 JavaScript
+The package exposes 205 semantic JavaScript records across 20 JavaScript
 entrypoints, plus eight JSON Schemas and package metadata. Ten entrypoints are
 Node.js control-plane surfaces,
 `arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`, `arcane-os/preference-store`, and
-`arcane-os/speech-playback` plus `arcane-os/speech-text` run in Node and browsers, and
-`arcane-os/ai/browser-wasm` plus `arcane-os/ai/browser-speech` are browser-only.
+`arcane-os/speech-playback`, `arcane-os/speech-text`, and `arcane-os/browser-device`
+run in Node and browsers, and
+`arcane-os/pwa`, `arcane-os/ai/browser-wasm` plus `arcane-os/ai/browser-speech` are browser-only.
 The [machine-readable package
 inventory](inventory/package-api.json) and [SDK member reference](sdk-api.md)
 are checked bidirectionally against every declared JavaScript export.

package/docs/reference/ai/browser-wasm.md

@@ -61,6 +61,25 @@ model source. Each file needs only a name and HTTPS URL. A positive optional
 `bytes` value supplies observational progress and transport-planning metadata;
 it never validates, admits, identifies, or decides cache reuse for content.
 
+## Mobile and desktop settings
+
+`getBrowserDeviceClass(navigatorObject = globalThis.navigator)`, exported from
+`arcane-os/browser-device`, returns `mobile` or `desktop` for choosing
+application-owned settings. Mobile includes a positive mobile client hint,
+Android or iOS platform information, mobile user-agent identifiers, and iPadOS
+reporting a Mac platform with multiple touch points. Missing or unrecognized
+identity defaults to `desktop`; a browser hiding all mobile hints may therefore
+receive that profile. This classification is a settings hint, not evidence of
+GPU capability, available memory, or model readiness.
+
+Keep complete mobile and desktop load profiles at the application owner and
+pass the selected profile as `createBrowserWasmLlmProvider({loadDefaults})`.
+Choose it once before provider creation so catalog inspection and model loading
+use the same settings. The helper reads identity synchronously and starts no
+GPU request, model operation, listener, or viewport-dependent reload. Its
+dependency-free entrypoint does not import the inference runtime. Profile
+selection does not alter prompts, documents, history, or output limits.
+
 ## Lifecycle at a glance
 
 `createArcaneAI()` owns one LLM controller. Its default `loadPolicy` is

package/docs/reference/asset-versioning.md

@@ -1,5 +1,13 @@
 # Release-derived browser asset URLs
 
+Applications that enable [PWA delivery](pwa.md) use clean local resource URLs.
+Their generated offline manifest and service worker own the selected application
+and SDK release information. In that mode, the delivery transformer removes
+both `v` and `arcaneVersion`, preserving other query fields and fragments.
+The behavior below continues to apply when PWA delivery is disabled and to native
+packages. Workspace runtime materialization remains usable by either target;
+the selected browser delivery applies its PWA URL policy.
+
 The SDK's public import-map generator, runtime materializer, source server and
 application packager use the selected SDK package version for local browser
 resource references. The query field is `arcaneVersion`. Its value comes from
@@ -49,6 +57,11 @@ HTML and managed import-map JSON. This allows storage but requests revalidation,
 or refresh obtains the current entry document and release URLs. Other assets
 retain ordinary caching; no cache or user storage is cleared.
 
+For PWA delivery the SDK server revalidates all served resources, including
+the stable worker script. A static host serving a PWA package must likewise
+revalidate stable resource URLs. The service worker maintains its own selected
+offline resource cache independently of the HTTP cache.
+
 An independently configured static host must likewise revalidate entry HTML
 and managed import-map JSON. The generated package supplies versioned resource
 references; it cannot configure another server's HTTP headers.

package/docs/reference/inventory/package-api.json

@@ -6,7 +6,7 @@
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 202,
+  "memberCount": 205,
   "members": [
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
@@ -2952,6 +2952,50 @@
       "protocol": "Resumable ordered model members and deterministic per-member Range parts over existing DBOPFS method semantics",
       "normalization": "Uses one bounded transfer axis, preserves ordered completed shards and deterministic current Range parts within any member across interruption, emits coalesced additive loaded/total/remaining/rate/ETA/active-worker telemetry, rolls discarded partial writes back out of progress, cleans superseded current Range parts after a complete replacement exists, and settles failed or cancelled peers while retaining completed work for retry"
     },
+    {
+      "id": "browser-device:getBrowserDeviceClass",
+      "name": "getBrowserDeviceClass",
+      "displayName": "getBrowserDeviceClass()",
+      "kind": "function",
+      "signature": "getBrowserDeviceClass(navigatorObject = globalThis.navigator)",
+      "entrypoints": [
+        "arcane-os/browser-device"
+      ],
+      "primaryImport": "arcane-os/browser-device",
+      "group": "Browser device settings",
+      "summary": "Returns a mobile or desktop browser identity hint for application-owned settings.",
+      "availability": "Node and Browser; no model, storage, or GPU capability required",
+      "protocol": "Synchronous optional navigator-like identity input and mobile or desktop string result",
+      "normalization": "Positive mobile hints, Android or iOS identity, and iPadOS Mac-platform touch identity select mobile; missing or unrecognized identity selects desktop. Importing the dependency-free entrypoint loads no AI runtime, and classification performs no model, GPU, storage, network, or listener operation."
+    },
+    {
+      "id": "pwa:PWA_STATE_EVENT",
+      "name": "PWA_STATE_EVENT",
+      "displayName": "PWA_STATE_EVENT",
+      "kind": "constant",
+      "signature": "const PWA_STATE_EVENT",
+      "entrypoints": ["arcane-os/pwa"],
+      "primaryImport": "arcane-os/pwa",
+      "group": "Progressive web applications",
+      "summary": "Names the shared PWA lifecycle state event.",
+      "availability": "Browser lifecycle; importable without registration",
+      "protocol": "Existing Arcane event owner and native service worker lifecycle",
+      "normalization": "The exact event name is arcane.pwa.state."
+    },
+    {
+      "id": "pwa:registerPwa",
+      "name": "registerPwa",
+      "displayName": "registerPwa()",
+      "kind": "function",
+      "signature": "registerPwa({workerUrl = './arcane-sw.js', scope} = {})",
+      "entrypoints": ["arcane-os/pwa"],
+      "primaryImport": "arcane-os/pwa",
+      "group": "Progressive web applications",
+      "summary": "Starts PWA registration without blocking page rendering and returns an observable lifecycle owner.",
+      "availability": "Browser service workers; explicit unsupported state elsewhere",
+      "protocol": "Native registration, updatefound, statechange and controllerchange events",
+      "normalization": "Synchronous owner exposes ready, state, subscribe, update and dispose; current state replays by default, failures remain observable, disposal does not unregister the worker or delete saved data."
+    },
     {
       "id": "browser-speech:BROWSER_SPEECH_ARTIFACT_GRAPH_PROTOCOL",
       "name": "BROWSER_SPEECH_ARTIFACT_GRAPH_PROTOCOL",

package/docs/reference/pwa.md

@@ -0,0 +1,183 @@
+# Progressive web applications
+
+An application supplies its installation identity and offline resource selection.
+The SDK generates the Web App Manifest, offline inventory, service worker and
+nonblocking registration module. Native packages keep their existing lifecycle.
+
+## Application configuration
+
+Set `package.pwa` in the application's `arcane-app.json`. Its ordinary package
+projection carries the same `pwa` record in `arcane-package.json`:
+
+```json
+{
+  "enabled": true,
+  "manifest": {
+    "name": "Example Library",
+    "short_name": "Library",
+    "display": "standalone",
+    "icons": [
+      {
+        "src": "img/library.png",
+        "sizes": "512x512",
+        "type": "image/png"
+      }
+    ]
+  },
+  "offline": {
+    "exclude": ["documents"]
+  }
+}
+```
+
+`enabled` defaults to `false`. `manifest` contains ordinary Web App Manifest
+metadata. Its default name comes from `displayName`; its default start page
+comes from the selected application entry. The app owns names, icons, colors,
+display preference, routes and descriptions. Use real app icons; the SDK does
+not invent branding or claim that a browser has installed the app.
+
+Manifest URL fields are relative to the application directory. Source delivery
+and packaged delivery resolve those fields into their respective layouts.
+Absolute URL fields retain their authored destination.
+
+`offline.include` and `offline.exclude` select literal paths or directory
+prefixes from the selected emitted inventory. An omitted or empty include list
+selects that inventory; exclusions subtract from it. App files use app-relative
+paths and shared runtime files use paths such as `arcane/sdk/pwa.mjs`.
+The application entry and generated PWA shell records are retained. Select the
+resources needed by every offline page, including its shared modules and styles.
+The worker script itself is never an application cache entry.
+
+These settings describe published application resources. They do not select
+user uploads, provider responses, live API requests, saved conversations,
+preferences, IndexedDB, OPFS, or a model owner's download/cache lifecycle.
+Offline page availability does not imply that cloud inference or other network
+services work offline. Applications own the corresponding visible behavior.
+
+## Generated output
+
+Browser packaging emits these files at the selected deployment root:
+
+| File | Purpose |
+| --- | --- |
+| `arcane.webmanifest` | Browser installation metadata. |
+| `arcane-offline.json` | App ID/version, SDK version, deployment revision, resource URLs and explicit navigation aliases. |
+| `arcane-sw.js` | Stable worker URL with the selected offline manifest embedded in its source. |
+| `arcane-pwa.mjs` | Independent registration module importing the SDK client. |
+
+Each packaged output gets one deployment revision shared by its offline
+manifest and worker. It distinguishes separately generated outputs even when
+their app and SDK versions match. It is not a content measurement.
+
+The package owns its selected inventory once, after any app adapter finishes.
+It follows actual resource references to include meaningful query variants.
+Generated application pages receive a manifest link and an `async` module
+marked `data-arcane-pwa`. Existing application scripts retain their order.
+PWA registration does not wait for models, storage, preferences or page rendering.
+
+The selected PWA browser delivery removes `v` and `arcaneVersion` from actual
+local resource references, including the managed import map. Other query fields,
+fragments, source spelling and unrelated payloads are preserved. The offline
+manifest now carries release information. Non-PWA and native delivery retain
+the [existing asset version contract](asset-versioning.md).
+
+## Development and hosting
+
+For an enabled application, `arcane dev` serves the generated PWA files at the
+origin root and starts at the selected app page under `/apps/<id>/`. Use one
+selected app per development origin. Its worker uses network revalidation first
+and retains successful selected resource responses for offline use, so saved
+source edits remain visible on an ordinary online refresh.
+
+Source inventory work begins when the browser requests the worker update, after
+the page can start. It traverses the selected route inventory once for that
+request, follows application page and runtime resource references to retain
+selected query variants, and shares an in-flight traversal with concurrent
+manifest requests. Each referenced source file is read once per traversal;
+document corpus bodies remain under their existing owner. It does not rebuild
+the application. Generated metadata and bootstrap requests reuse the current
+bundle.
+
+Packaged workers use their selected cache generation first. During installation,
+at most four resource requests run together; each response is fetched from the
+network with the browser's reload cache mode before it enters the candidate
+cache. The candidate must finish
+installation before the browser activates it. Failures retain the prior active
+worker and remain observable through native worker state and SDK diagnostics.
+
+The SDK development server sends `Cache-Control: no-cache` for PWA resources.
+An independent static host must also revalidate stable HTML, module, style,
+import-map and worker URLs, and serve JavaScript with a JavaScript content type.
+Keep the worker beside the deployment root it controls. The browser requires a
+supported secure context, such as trusted HTTPS or localhost, to register it.
+The SDK does not change certificates or browser permissions.
+
+An initial visit can load before a worker controls the document. Revalidation
+therefore matters even when an offline cache exists. Updating files in place
+while installation fetches them is not an atomic release snapshot; the host owns
+consistent deployment of the selected output.
+
+An offline navigation alias redirects to its selected entry page, preserving the
+document URL used to resolve relative modules and styles.
+
+Browser storage eviction can remove an offline cache. A missing release cache
+entry falls back to the network, so offline availability still depends on the
+browser retaining the selected resources.
+
+## Updates and stored data
+
+An updated worker installs alongside the current worker, then waits for the
+browser's normal activation boundary. Existing controlled pages retain their
+worker while they are open. Closing those pages allows activation; a refresh
+can leave overlapping document clients and keep the update waiting.
+
+The SDK does not call `skipWaiting`, claim the initial page, reload a page,
+restart a model or poll for updates. Activation retires only obsolete resource
+caches belonging to that exact app and registration scope. Saved application
+data and caches owned by other capabilities are untouched.
+
+Switching a server from a packaged release to live development does not replace
+an already active release worker inside an open document. The same native
+worker lifecycle applies.
+
+## registerPwa()
+
+Import `registerPwa` and `PWA_STATE_EVENT` from `arcane-os/pwa` through the
+managed browser import map. The generated bootstrap already calls this API;
+manual callers use it when they own a separate registration entry point.
+
+```javascript
+import {registerPwa} from 'arcane-os/pwa';
+
+const pwa = registerPwa(
+    {
+        workerUrl: new URL('./arcane-sw.js', import.meta.url).href,
+        scope: new URL('./', import.meta.url).href
+    }
+);
+
+pwa.subscribe(function showPwaState(state) {
+    console.log(state);
+});
+pwa.ready.catch(function reportRegistrationFailure(error) {
+    console.error(error);
+});
+```
+
+The function returns synchronously with `{ready, state, subscribe, update,
+dispose}`. `ready` settles with the native registration, or `null` when service
+workers are unavailable. A registration failure rejects it and publishes error
+state. Do not await it before rendering or confuse it with a controlled page.
+
+`state` reports `status`, `workerUrl`, `scope`, `controller`, `installing`,
+`waiting`, `active` and the complete `error` when present. Status is one of
+`registering`, `unsupported`, `registered`, `installing`, `waiting`, `active`,
+`error` or `disposed`. Native worker state fields are strings or `null`.
+
+`subscribe(listener, {emitCurrent: true, signal} = {})` immediately replays the
+current state by default and returns an unsubscribe function. Subsequent state
+uses the existing Arcane event owner and `PWA_STATE_EVENT` (`arcane.pwa.state`).
+`update()` requests the browser's normal update check on demand; failure is
+observable in state and through its returned promise. `dispose()` removes
+page-owned listeners and subscriptions without unregistering the persistent
+worker or deleting stored data.