arcane-os 0.11.3 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.12.0
+
+- Refresh the selected authored app descriptor's package projection before
+  development startup, so file and PWA configuration changes take effect through
+  the ordinary dev command without packaging.
+- Use published `node-http-server` 9.1.1 for development and packaged-preview HTTPS
+  serving, preserving source mounts and generated resource transformations.
+  Supply modification dates for conditional GET and HEAD requests.
+  Enforce HTTPS for every Arcane app, including localhost and packaged browser
+  previews, using the configured workspace certificate pair or public TLS options.
+  Redirect the paired HTTP listener with status 308 while preserving the request
+  path and query; select its port with `httpPort` or CLI `--http-port`.
+- Keep complete PWA resource responses across app and SDK version changes.
+  Check on page load after 120 seconds in development or 15 minutes otherwise,
+  with one DBOPFS timestamp updated only after the whole check succeeds. Reuse
+  cached responses on `304`, replace them after a successful current response, and retain offline
+  copies on network failures. No SDK cache expiration or polling is added.
+
 ## 0.11.3
 
 - Require Wllama's model-context load result to report success before publishing

package/NOTICE

@@ -8,6 +8,7 @@ informational notice and is not itself a grant of commercial rights.
 Third-party material retains its own terms:
 
 - event-pubsub 6.1.0: MIT License; see its installed `licence` file.
+- node-http-server 9.1.1: MIT License; see its installed `licence` file.
 - strong-type 2.0.1: MIT License; see its installed `licence` file.
 - vanilla-test 2.1.3: MIT License; see its installed `licence` file.
 - ansi-colors-es6 5.0.0: MIT License; see its installed `LICENSE` file.

package/README.md

@@ -19,15 +19,17 @@ 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.11.3` SDK contract. Applications pin one exact npm
+This checkout defines the `0.12.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.
+page-load revalidation and persistent resource caches. The SDK records one
+completed-check timestamp per app/cache in DBOPFS and checks after 120 seconds
+in development or 15 minutes in packaged browser delivery. 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.
@@ -41,9 +43,15 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.11.3 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.12.0 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
+```
+
+Configure the workspace's HTTPS certificate pair as described in
+[development HTTPS setup](docs/reference/cli.md#development-https-setup), then start:
+
+```bash
 npm run dev
 ```
 
@@ -62,9 +70,12 @@ each device. Keep these local files ignored by Git. The same certificate pair
 works for any selected app in that workspace. The command reports missing TLS
 files instead of starting an HTTP listener.
 
-Plain `npm run dev` keeps its HTTP localhost default. An explicit `--host`
-overrides the public bind address, and `--port` selects the port. Use `--https`
-for HTTPS on localhost, or `--cert <file> --key <file>` for an explicit PEM pair;
+Every Arcane app uses HTTPS for development and packaged browser previews.
+Plain `npm run dev` binds to localhost with the same workspace certificate pair.
+An explicit `--host` overrides the bind address, and `--port` selects the HTTPS port.
+The paired HTTP listener returns 308 redirects and uses an OS-assigned port
+unless selected with `--http-port`. The command prints its redirect URL.
+Use `--cert <file> --key <file>` for an explicit PEM pair;
 relative paths resolve from the workspace. The server prints HTTPS network URLs
 for public mode. Network reachability depends on the machine's firewall and
 network. See the [development HTTPS setup](docs/reference/cli.md#development-https-setup)
@@ -392,7 +403,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.11.3 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.12.0 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run dev
@@ -402,7 +413,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.11.3
+npm install --save-dev --save-exact arcane-os@0.12.0
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -418,7 +429,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.11.3` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.12.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`,
@@ -438,7 +449,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.11.3.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.12.0.tgz
 npm ci
 ```
 
@@ -447,7 +458,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.11.3` registry package and
+the local declaration with the exact `arcane-os@0.12.0` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -586,7 +597,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.11.3` exposes one browser target and five explicitly paired
+Version `0.12.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/pwa.mjs

@@ -24,6 +24,11 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
     const container = globalThis.navigator?.serviceWorker;
     const listeners = [];
     const workers = new Map();
+    const queriedWorkers = new WeakSet();
+    const refreshedWorkers = new WeakSet();
+    const pendingRefreshes = new Set();
+    const refreshTasks = new Set();
+    let storageTask = null;
     let registration = null;
     let disposed = false;
     let current = {
@@ -83,6 +88,13 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
     function onWorkerStateChange(event) {
         const previousState = workers.get(event.target);
         workers.set(event.target, event.target.state);
+        if (event.target.state === 'redundant') {
+            for (const operation of pendingRefreshes) {
+                if (operation.worker === event.target) {
+                    operation.cancel();
+                }
+            }
+        }
         // A newer installation normally supersedes an already waiting worker.
         if (event.target.state === 'redundant'
             && previousState !== 'activated' && previousState !== 'installed') {
@@ -107,7 +119,118 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
         watchWorker(registration.installing);
         watchWorker(registration.waiting);
         watchWorker(registration.active);
+        watchWorker(container.controller);
         publish(currentStatus());
+        const worker = registration.active ?? container.controller;
+        if (worker?.state === 'activated' && !queriedWorkers.has(worker)) {
+            queriedWorkers.add(worker);
+            try {
+                worker.postMessage({type: 'arcane.pwa.capabilities'});
+            } catch (error) {
+                publish('error', error);
+            }
+        }
+    }
+
+    function startResourceRefresh(worker, cacheName) {
+        if (disposed || worker.state !== 'activated' || refreshedWorkers.has(worker)) {
+            return;
+        }
+        refreshedWorkers.add(worker);
+        const task = refreshCachedResources(worker, cacheName);
+        refreshTasks.add(task);
+        task.then(
+            function resourceRefreshComplete() {
+                refreshTasks.delete(task);
+            },
+            function resourceRefreshFailed(error) {
+                refreshTasks.delete(task);
+                if (error?.code !== 'ARCANE_PWA_REFRESH_CANCELLED') {
+                    publish('error', error);
+                }
+            }
+        );
+    }
+
+    async function loadCheckStorage() {
+        if (!globalThis.dbopfs) {
+            await import('arcane/DBOPFS');
+        }
+        const storage = globalThis.dbopfs;
+        if (!storage) {
+            throw new Error('PWA check history could not open DBOPFS.');
+        }
+        await storage.readyPromise;
+        return storage;
+    }
+
+    function requestResourceRefresh(worker, lastChecked) {
+        const channel = new MessageChannel();
+        return new Promise(
+            function resourceRefreshReply(resolve, reject) {
+                function cleanup() {
+                    pendingRefreshes.delete(operation);
+                    channel.port1.onmessage = null;
+                    channel.port1.onmessageerror = null;
+                    channel.port1.close();
+                    channel.port2.close();
+                }
+                function cancel() {
+                    cleanup();
+                    const error = new Error('The PWA resource refresh owner is no longer active.');
+                    error.code = 'ARCANE_PWA_REFRESH_CANCELLED';
+                    reject(error);
+                }
+                const operation = {worker, cancel};
+                pendingRefreshes.add(operation);
+                channel.port1.onmessage = function receiveResourceRefresh(event) {
+                    if (event.data?.type === 'arcane.pwa.refreshed') {
+                        cleanup();
+                        resolve(event.data);
+                    }
+                };
+                channel.port1.onmessageerror = function unreadableResourceRefresh() {
+                    cleanup();
+                    reject(new Error('The PWA resource refresh reply could not be read.'));
+                };
+                channel.port1.start();
+                try {
+                    worker.postMessage({type: 'arcane.pwa.refresh', lastChecked}, [channel.port2]);
+                } catch (error) {
+                    cleanup();
+                    reject(error);
+                }
+            }
+        );
+    }
+
+    async function refreshCachedResources(worker, cacheName) {
+        storageTask ??= loadCheckStorage();
+        const storage = await storageTask;
+        const key = `${encodeURIComponent(cacheName)}.json`;
+        async function refreshStoredChecks() {
+            if (disposed || worker.state !== 'activated') {
+                return;
+            }
+            // A fresh read under the shared lock preserves checks made by another tab.
+            const record = await storage.get('pwa', key, true);
+            if (disposed || worker.state !== 'activated') {
+                return;
+            }
+            const result = await requestResourceRefresh(worker, record?.lastChecked ?? null);
+            if (!result.error && Number.isFinite(result.lastChecked) && result.lastChecked !== record?.lastChecked) {
+                await storage.set('pwa', key, {lastChecked: result.lastChecked});
+            }
+            if (result.error) {
+                publish('error', result.error);
+            }
+        }
+        const locks = globalThis.navigator?.locks;
+        if (locks?.request) {
+            await locks.request(`arcane-pwa-checks|${cacheName}`, refreshStoredChecks);
+        } else {
+            await refreshStoredChecks();
+        }
     }
 
     function onControllerChange() {
@@ -115,6 +238,9 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
     }
 
     function onWorkerMessage(event) {
+        if (event.data?.type === 'arcane.pwa.capabilities' && event.data.refresh === true && workers.has(event.source)) {
+            startResourceRefresh(event.source, event.data.cacheName);
+        }
         if (event.data?.type === 'arcane.pwa.error' && workers.has(event.source)) {
             publish('error', event.data.error);
         }
@@ -205,6 +331,9 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
         for (const removeListener of listeners) {
             removeListener();
         }
+        for (const operation of pendingRefreshes) {
+            operation.cancel();
+        }
         listeners.length = 0;
         workers.clear();
         source.dispose();

package/docs/architecture.md

@@ -110,21 +110,37 @@ behavior or claiming that the capability exists.
 
 Rapid development uses `arcane dev`. The development server maps the selected
 application's canonical source tree and the live installed SDK/runtime routes.
-Each request reads and returns the complete current saved source, so a browser
-refresh shows source changes without packaging, copying
-files into `dist`, or restarting the server. Restarting is not a content
-synchronization step; when a refresh is stale, first verify the command, URL,
-workspace, selected app, and resolved source route.
-
-The shared dev server owns HTTP and HTTPS transport for the same selected
-routes. `arcane dev --public` selects HTTPS on the IPv4 wildcard address;
-explicit `--host` controls the bind address, while `--https` selects HTTPS
-without changing it. Public/HTTPS CLI startup reads one workspace-local PEM
-pair before binding. The certificate covers the device-facing address, and
+At startup, the SDK refreshes only the selected authored app descriptor's
+schema-1 package projection and managed import maps under the existing
+development-refresh lock, then releases the lock before binding the listener.
+The authored descriptor remains unchanged, and package-only apps retain their
+existing path. An enabled PWA receives generated manifests directly from this
+source server without creating `dist` output.
+Changed resource requests return the complete current saved source without
+packaging, copying files into `dist`, or restarting the server. Conditional
+requests for unchanged resources return `304`. Enabled PWAs check on page load
+when their single DBOPFS `lastChecked` value is older than 120 seconds in
+development or 15 minutes in packaged browser delivery. Cached resource bodies have no SDK
+expiration. The timestamp advances only after the whole resource check succeeds.
+Restarting is not a content synchronization step; inspect the
+selected source route and the last successful check when evaluating freshness.
+
+The shared dev server uses RIAEvangelist's `node-http-server` public interface
+for HTTPS and conditional responses on those selected routes. The SDK
+owns source selection and generated representations. Every Arcane development
+server and packaged browser preview serves content on HTTPS and redirects its
+paired HTTP listener with status 308 through the public request hook.
+`arcane dev --public` selects the IPv4 wildcard address;
+explicit `--host` controls the bind address. CLI startup reads one workspace-local
+PEM pair before binding, including ordinary localhost startup.
+The certificate covers the device-facing address, and
 each client trusts its issuing CA through that platform's certificate setup.
 This supplies the secure origin required by OPFS/DBOPFS on LAN devices. The
 server does not install trust, generate certificates, or expose private TLS
-material through CLI events. Ordinary localhost development remains HTTP.
+material through CLI events. `port` selects HTTPS; `httpPort` selects the HTTP
+redirect listener, defaulting to an OS-assigned port. Existing raw `tls` inputs
+retain their native HTTPS transport under the SDK, as described by the module's
+advanced TLS extension guidance; all content uses its public serving methods.
 
 Development is an intentionally fast feedback loop. Keep each increment small
 and independently understandable so its effect has one clear cause and a

package/docs/reference/cli.md

@@ -48,10 +48,11 @@ meaning and cardinality rules:
 | `--workspace` | directory | Commands that select an external or integrated workspace; defaults to `.`. |
 | `--app` | app id | Workspace/app operations except shared scope and `verify-bundle`; also the exact `mail serve` caller id. |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
-| `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to `127.0.0.1:8000`; `mail serve` defaults to `127.0.0.1:8025` and admits numeric loopback only. |
+| `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTP at `127.0.0.1:8025` and admits numeric loopback only. |
+| `--http-port` | integer 0–65535 | Browser `dev`/`run` HTTP redirect listener; defaults to `0`, which selects an available port. |
 | `--public` | flag | `dev`; serves HTTPS and binds to `0.0.0.0` unless `--host` explicitly selects another address. |
-| `--https` | flag | `dev`; serves HTTPS with the configured or default workspace PEM pair. |
-| `--cert` / `--key` | PEM file paths | `dev`; supply both to select HTTPS with an explicit certificate chain and private key. Relative paths resolve from the workspace. |
+| `--https` | flag | Browser `dev`/`run`; retained explicitly, while HTTPS is always enabled. |
+| `--cert` / `--key` | PEM file paths | Browser `dev`/`run`; supply both for an explicit certificate chain and private key. Relative paths resolve from the workspace. |
 | `--target` | target id | `new`, `init`, native diagnostics, `build`, `run` |
 | `--format` / `--signing` | target-supported values | Native diagnostics, `build`, `run` |
 | `--output-root` | directory | Native `build` and `run` |
@@ -311,7 +312,7 @@ npm exec -- arcane upgrade --workspace . --app hello-world
 ### Overview
 
 Starts one development server for one selected app and maps the exact
-workspace/runtime routes. It defaults to localhost; `--public` enables access
+workspace/runtime routes. It defaults to HTTPS on localhost; `--public` enables access
 from other devices on the network over HTTPS.
 
 For an external workspace, the server exposes the selected projected
@@ -321,11 +322,19 @@ The explicit live-source SDK mapping remains unchanged and does not replace the
 installed projection.
 
 ```text
-arcane dev [--app <id>] [--public] [--https] [--cert <file> --key <file>] [--host <address>] [--port 8000]
+arcane dev [--app <id>] [--public] [--https] [--cert <file> --key <file>] [--host <address>] [--port 8000] [--http-port 0]
 ```
 
 ### Lifecycle
 
+Startup refreshes the selected authored `arcane-app.json` projection into
+`arcane-package.json`, then refreshes its managed import maps under one
+development-refresh operation lock. The lock is released before the server
+starts. Package-only apps retain their existing manifest. This operation does
+not package the app or produce `dist` output. With PWA enabled, the server
+generates the installation and offline manifests directly; see
+[PWA development and versioning](pwa.md#development-and-hosting).
+
 The command reports acceptance before bind/start work, emits the final URL,
 owns the server until cancellation, and restores failure to the process exit.
 The default host is `127.0.0.1`. `--public` selects `0.0.0.0` (all IPv4
@@ -335,25 +344,33 @@ device, since `localhost` refers to that device and `0.0.0.0` is a bind address.
 Network URLs come from one interface snapshot at startup and do not establish
 remote reachability through the machine's firewall or network.
 
-Public mode also selects HTTPS. Plain localhost development stays HTTP.
-`--https` selects HTTPS without changing the bind address; supplying both
-`--cert` and `--key` also selects HTTPS. The command does not configure a
-firewall, router forwarding, or an internet tunnel.
+Every Arcane app uses HTTPS for development and packaged browser previews.
+`--https` remains accepted but is no longer needed to select the transport.
+`--port` selects the HTTPS application port. A second HTTP listener returns
+`308` redirects to that HTTPS port, preserving the requested path and query.
+`--http-port` selects its port; the default `0` lets the operating system choose
+an available port. Both listeners use the selected host and must be ready
+before startup completes. Cancellation or a listener failure closes both.
+Human output prints `HTTP redirect: <url>` alongside the HTTPS application URL;
+JSON/NDJSON server results include `httpPort`, `httpOrigin`, and `httpUrl` for
+the redirect endpoint.
+Supplying both `--cert` and `--key` selects an explicit PEM pair. The command
+does not configure a firewall, router forwarding, or an internet tunnel.
 
 ### Development HTTPS setup
 
-Before starting public mode, place the development server's PEM certificate
-chain at `.arcane/dev/server-cert.pem` and its PEM private key at
+Before starting `arcane dev` or a packaged browser preview, place the server's
+PEM certificate chain at `.arcane/dev/server-cert.pem` and its PEM private key at
 `.arcane/dev/server-key.pem`, relative to the workspace. Alternatively, pass
-`--cert <file> --key <file>` together. The certificate must cover the LAN IP
+`--cert <file> --key <file>` together. The certificate must cover localhost or the LAN IP
 address or hostname opened by each device. Certificate creation and renewal
 belong to the developer's certificate tooling; the server does not generate a
 CA or alter device trust stores. Keep `.arcane/dev/` ignored by Git and keep the
 private key on the development computer.
 
-The server reads the selected pair once asynchronously per startup, before
-binding. Missing files or certificate/key parse errors produce a startup error; public
-mode never silently falls back to HTTP. Certificate/key contents are not
+The server reads the selected pair during startup, before binding.
+Missing files or certificate/key parse errors produce a startup error;
+Arcane never silently falls back to HTTP. Certificate/key contents are not
 included in operation events or JSON/NDJSON output. Restart the server after
 replacing its certificate pair; ordinary app source edits still appear on
 refresh without restarting.
@@ -383,6 +400,9 @@ npm run dev -- --app hello-world --public
 
 # Equivalent direct CLI invocation, with an optional port.
 npm exec -- arcane dev --app hello-world --public --port 8000
+
+# Select a stable HTTP entry that redirects to HTTPS on port 8000.
+npm exec -- arcane dev --app hello-world --port 8000 --http-port 8080
 ```
 
 ## `arcane test`
@@ -617,11 +637,17 @@ npm exec -- arcane build \
 
 For `--target browser`, starts the existing current `dist/<app>` release; it
 does not package, rebuild, test, check, or verify that release automatically.
+The preview always uses HTTPS with the workspace certificate pair. Supply
+`--cert <file> --key <file>` together to use another pair; see
+[development HTTPS setup](#development-https-setup).
+`--port` selects the HTTPS application port, and `--http-port` selects the
+paired HTTP `308` redirect port. The HTTP port defaults to an available port;
+the CLI prints its actual redirect URL and reports both listener endpoints.
 For a paired native target, it performs package, prepare, plan, build, launch,
 readiness, and owned cancellation in one process.
 
 ```text
-arcane run [--target <target>] [--app <id>] [--arcane-root <directory>] [--output-root <directory>] [--format <format>] [--signing <mode>]
+arcane run [--target <target>] [--app <id>] [--cert <file> --key <file>] [--port 8000] [--http-port 0] [--arcane-root <directory>] [--output-root <directory>] [--format <format>] [--signing <mode>]
 ```
 
 ### Availability

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

@@ -2991,7 +2991,7 @@
       "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.",
+      "summary": "Starts PWA registration and DBOPFS-backed page-load resource checks without blocking rendering, returning 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."

package/docs/reference/pwa.md

@@ -83,31 +83,90 @@ the [existing asset version contract](asset-versioning.md).
 
 ## Development and hosting
 
+Use the ordinary `arcane dev --app <id>` command after editing the selected
+app's `arcane-app.json`. Startup refreshes that app's generated
+`arcane-package.json` from the authored descriptor before refreshing its import
+maps and starting the server. No packaging or `dist` output is required.
+Package-only applications retain their existing descriptor workflow.
+
+Add a file or directory to `package.include` to make it part of the app's
+resources. A new file inside an already included directory needs no separate
+entry. If `package.pwa.offline.include` is nonempty, the resource must also
+match that offline selection and must not match `offline.exclude`. Adding a
+path only to the offline selection does not add it to the app's resources.
+Restart after changing descriptor settings. Edits to selected source files are
+picked up by the next due page-load check while the server remains running.
+
 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;
+selected app per development origin. The SDK uses `node-http-server` for source
+and packaged-preview serving, including conditional resource responses.
+Every Arcane development server and packaged browser preview serves HTTPS,
+including localhost. Configure the workspace certificate pair before starting
+the ordinary command; see [development HTTPS setup](cli.md#development-https-setup).
+
+Source inventory work begins when the browser requests the worker or current
+offline manifest, after the page can start. It traverses the selected route
+inventory once for that request, follows page and runtime resource references
+to retain selected query variants, and shares an in-flight traversal with
+concurrent 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.
+the application. Installation metadata and bootstrap requests reuse the current
+generated bundle.
+
+The SDK owns version information in `arcane-offline.json`:
+
+| Field | Owner and update rule |
+| --- | --- |
+| `schemaVersion` | SDK offline-manifest format; currently `1`. |
+| `appVersion` | The app descriptor's top-level `version`. |
+| `sdkVersion` | The selected installed SDK or explicit live SDK source version. |
+| `revision` | `development` for the source server; a fresh generated deployment ID for each packaged output. |
 
-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.
+Do not hand-edit generated manifests or bump a version for every source edit.
+`arcane.webmanifest` holds installation metadata and has no separate SDK-managed
+release counter. Resource freshness uses each response's `Last-Modified` header.
+
+On each page load, the SDK reads one `lastChecked` value for the app and worker
+scope from DBOPFS in the background. When that value is missing or older than
+the delivery mode's interval, it checks the current offline manifest and every
+selected resource:
+
+| Mode | Page-load check interval |
+| --- | --- |
+| Development | 120 seconds |
+| Packaged browser delivery | 15 minutes |
+
+These intervals schedule revalidation; they never expire a cached file. The
+worker sends `GET` with `If-Modified-Since` using the cached response's
+`Last-Modified`. A `304 Not Modified` retains the complete cached response. A
+successful `200` replaces it after the new response is stored. Missing cached
+resources are downloaded. Network and server failures retain an existing
+offline copy and remain observable through SDK diagnostics. A host without
+modification headers must send the current response because freshness cannot
+be established from a missing header.
+
+Complete resource responses remain in browser CacheStorage. DBOPFS stores one
+successful whole-cycle timestamp, updated only after the manifest and every
+selected resource have been checked successfully. A partial failure preserves
+the previous timestamp so the next page load can retry. Each cached response
+retains its own `Last-Modified` header, but there are no per-file check times.
+The SDK imposes no age-based cache deletion and
+retains resource bodies across app and SDK version changes. Requests for a page
+do not wait for the complete resource inventory to finish checking. The SDK
+uses at most four concurrent background resource requests and starts no timer
+or polling loop between page loads.
+
+During initial installation, selected resources are cached before the browser
+activates the worker. Failures remain observable through native worker state
+and SDK diagnostics. HTTP modification dates have second-level precision;
+hosts must report changes to the served representation, including generated
+output, rather than only the date of an unrelated source file.
 
 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.
+An independent static host should support `Last-Modified` and conditional GET
+for stable HTML, module, style and import-map URLs, revalidate 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.
@@ -132,9 +191,15 @@ 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.
+restart a model or poll for updates. Worker activation preserves cached
+resources and the DBOPFS check history for the same app and registration scope.
+Saved application data and caches owned by other capabilities are untouched.
+
+When importing caches from an older SDK worker, the new worker fetches the
+SDK-owned registration bootstrap and PWA client once so the page can use the
+current cache-check protocol. Other cached resource bodies retain the normal
+check cadence. This transition follows native worker installation and
+activation without forcing a page reload.
 
 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