arcane-os 0.11.3 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.13.0
+
+- Add the reusable `pwa-install.html` component and shared browser installation
+  lifecycle through `arcane-os/pwa`. Offer a compact themed Install action and
+  explicit Close, retain session dismissal, support inline placement, and surface
+  native prompt errors without claiming installation completion.
+- Mount the component from generated PWA bootstraps independently of service
+  worker registration and application rendering. Use native installation and
+  display-mode events without polling, automatic native prompts, or focus capture.
+- Return cached resources immediately while conditional background refreshes
+  are pending or in flight, so page requests do not wait on network revalidation.
+- Document browser icon eligibility and the separate responsibilities of the
+  Web App Manifest, application file selection, and offline resource inventory.
+
+## 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,20 @@ 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.13.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.
+Enabled browser delivery also mounts the shared, themed installation suggestion.
+It appears when the browser offers installation, includes Install and Close,
+and remembers dismissal for the tab session without interrupting page startup.
 
 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 +46,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 +73,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 +406,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 +416,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 +432,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 +452,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 +461,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 +600,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-install.mjs

@@ -0,0 +1,242 @@
+import Is from './dependencies/strong-type/index.js';
+import {createArcaneEventSource} from './event-manager.mjs';
+
+const is = new Is(false);
+export const PWA_INSTALL_STATE_EVENT = 'arcane.pwa.install.state';
+let sharedOwner = null;
+let mountedPrompt = null;
+
+/** Capture native installation availability once per page, before loading UI. */
+export function getPwaInstall() {
+    if (sharedOwner && sharedOwner.state.status !== 'disposed') {
+        return sharedOwner;
+    }
+    const owner = {get state() { return snapshot(); }, subscribe, prompt, dismiss, dispose};
+    const source = createArcaneEventSource(owner, {
+        source: 'arcane.pwa.install', eventTypes: [PWA_INSTALL_STATE_EVENT]
+    });
+    const listeners = [];
+    const displayMode = globalThis.matchMedia?.(
+        '(display-mode: standalone), (display-mode: minimal-ui), '
+        + '(display-mode: fullscreen), (display-mode: window-controls-overlay)'
+    );
+    const manifestUrl = globalThis.document?.querySelector('link[rel~="manifest"]')?.href;
+    const dismissalKey = `arcane.pwa.install.dismissed:${manifestUrl ?? globalThis.location?.href ?? ''}`;
+    let deferredPrompt = null;
+    let disposed = false;
+    let dismissed = false;
+    let status = isRunningAsApp() ? 'running' : 'waiting';
+    let outcome = null;
+    let error = null;
+    try {
+        dismissed = globalThis.sessionStorage?.getItem(dismissalKey) === 'true';
+    } catch (storageError) {
+        console.warn('Arcane PWA install dismissal could not be read:', storageError);
+    }
+
+    function isRunningAsApp() {
+        return displayMode?.matches === true || globalThis.navigator?.standalone === true;
+    }
+
+    function snapshot() {
+        return {status, available: deferredPrompt !== null && !disposed,
+            dismissed, outcome, error};
+    }
+
+    function publish(nextStatus, nextError = null) {
+        if (disposed) return;
+        status = nextStatus;
+        error = nextError;
+        source.dispatch(PWA_INSTALL_STATE_EVENT, snapshot());
+    }
+
+    function observe(target, type, listener) {
+        if (!is.function(target?.addEventListener)) return;
+        target.addEventListener(type, listener);
+        listeners.push(function removeInstallListener() {
+            target.removeEventListener(type, listener);
+        });
+    }
+
+    function rememberDismissal() {
+        dismissed = true;
+        try {
+            globalThis.sessionStorage?.setItem(dismissalKey, 'true');
+        } catch (storageError) {
+            console.warn('Arcane PWA install dismissal could not be saved:', storageError);
+        }
+    }
+
+    function onBeforeInstallPrompt(event) {
+        if (disposed || isRunningAsApp() || status === 'installed' || status === 'accepted') return;
+        event.preventDefault();
+        deferredPrompt = event;
+        outcome = null;
+        publish('available');
+    }
+
+    function onInstalled() {
+        deferredPrompt = null;
+        // This event may precede Android's completion of WebAPK creation.
+        publish('installed');
+    }
+
+    function onDisplayModeChange() {
+        if (isRunningAsApp()) {
+            deferredPrompt = null;
+            publish('running');
+        } else if (status === 'running') {
+            publish('waiting');
+        }
+    }
+
+    function onPageHide(event) {
+        if (!event.persisted) dispose();
+    }
+
+    function subscribe(listener, {emitCurrent = true, signal} = {}) {
+        function forwardInstallState(event) { listener(event.detail); }
+        const unsubscribe = source.on(PWA_INSTALL_STATE_EVENT, forwardInstallState,
+            signal ? {signal} : undefined);
+        try {
+            if (emitCurrent && !signal?.aborted) listener(snapshot());
+        } catch (listenerError) {
+            unsubscribe();
+            throw listenerError;
+        }
+        return unsubscribe;
+    }
+
+    function prompt() {
+        if (disposed || !deferredPrompt) return Promise.resolve(null);
+        const event = deferredPrompt;
+        deferredPrompt = null;
+        publish('prompting');
+        let result;
+        try {
+            // Native user activation must reach prompt() in the same click stack.
+            result = event.prompt();
+        } catch (promptError) {
+            return rejectPrompt(promptError);
+        }
+        return Promise.resolve(result).then(async function receiveInstallChoice(value) {
+            const choice = value ?? await event.userChoice;
+            if (!choice || !['accepted', 'dismissed'].includes(choice.outcome)) {
+                throw new Error('The browser did not return an installation choice.');
+            }
+            if (!disposed) {
+                outcome = choice.outcome;
+                if (status === 'installed' || status === 'running') {
+                    publish(status);
+                } else {
+                    if (outcome === 'dismissed') rememberDismissal();
+                    publish(outcome);
+                }
+            }
+            return choice;
+        }).catch(rejectPrompt);
+    }
+
+    function rejectPrompt(promptError) {
+        if (status !== 'installed' && status !== 'running') publish('error', promptError);
+        return Promise.reject(promptError);
+    }
+
+    function dismiss() {
+        if (disposed) return snapshot();
+        rememberDismissal();
+        publish(status, error);
+        return snapshot();
+    }
+
+    function dispose() {
+        if (disposed) return;
+        deferredPrompt = null;
+        publish('disposed');
+        disposed = true;
+        for (const removeListener of listeners) removeListener();
+        listeners.length = 0;
+        source.dispose();
+    }
+
+    observe(globalThis, 'beforeinstallprompt', onBeforeInstallPrompt);
+    observe(globalThis, 'appinstalled', onInstalled);
+    observe(displayMode, 'change', onDisplayModeChange);
+    observe(globalThis, 'pagehide', onPageHide);
+    sharedOwner = owner;
+    return owner;
+}
+
+/** Mount one shared, initially hidden install component without delaying the app. */
+export function mountPwaInstallPrompt({appName = ''} = {}) {
+    const owner = getPwaInstall();
+    if (mountedPrompt) return mountedPrompt;
+    mountedPrompt = mountComponent().catch(function releaseFailedMount(error) {
+        mountedPrompt = null;
+        throw error;
+    });
+    return mountedPrompt;
+
+    async function mountComponent() {
+        if (!globalThis.document) return null;
+        // Both modules may start independently; saved theme loading is not a barrier.
+        await Promise.all([
+            import(new URL('../modules/HTMLImport.js', import.meta.url).href),
+            import(new URL('../modules/ThemeBootstrap.js', import.meta.url).href)
+        ]);
+        if (owner.state.status === 'disposed') return null;
+        if (!document.body) {
+            await new Promise(function waitForComponentParent(resolve) {
+                const unsubscribe = owner.subscribe(function observeParentWaitDisposal(state) {
+                    if (state.status === 'disposed') completeParentWait();
+                }, {emitCurrent: false});
+                function completeParentWait() {
+                    document.removeEventListener('DOMContentLoaded', completeParentWait);
+                    unsubscribe();
+                    resolve();
+                }
+                document.addEventListener('DOMContentLoaded', completeParentWait, {once: true});
+            });
+        }
+        if (owner.state.status === 'disposed') return null;
+        const host = document.createElement('html-import');
+        host.hidden = true;
+        host.dataset.appName = String(appName);
+        host.dataset.arcanePwaInstall = '';
+        host.setAttribute('href', new URL('../components/pwa-install.html', import.meta.url).href);
+        return new Promise(function waitForInstallComponent(resolve, reject) {
+            const observer = new MutationObserver(function observeRemovedInstallComponent() {
+                if (!host.isConnected) cancelMount();
+            });
+            const unsubscribe = owner.subscribe(function observeDisposedInstallOwner(state) {
+                if (state.status === 'disposed') cancelMount();
+            }, {emitCurrent: false});
+            function cleanup() {
+                observer.disconnect();
+                unsubscribe();
+                host.removeEventListener('html-import-ready', onReady);
+                host.removeEventListener('html-import-error', onError);
+            }
+            function cancelMount() {
+                cleanup();
+                host.remove();
+                const error = new Error('The PWA install component was removed before it became ready.');
+                error.name = 'AbortError';
+                reject(error);
+            }
+            function onReady() {
+                cleanup();
+                resolve(host);
+            }
+            function onError(event) {
+                cleanup();
+                host.remove();
+                reject(event.detail?.error ?? new Error('The PWA install component could not load.'));
+            }
+            host.addEventListener('html-import-ready', onReady);
+            host.addEventListener('html-import-error', onError);
+            document.body.append(host);
+            observer.observe(document.documentElement, {childList: true, subtree: true});
+        });
+    }
+}

package/browser-runtime/pwa.mjs

@@ -1,5 +1,7 @@
 import {createArcaneEventSource} from './event-manager.mjs';
 
+export {PWA_INSTALL_STATE_EVENT, getPwaInstall, mountPwaInstallPrompt} from './pwa-install.mjs';
+
 export const PWA_STATE_EVENT = 'arcane.pwa.state';
 
 export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
@@ -24,6 +26,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 +90,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 +121,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 +240,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 +333,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