arcane-os 0.37.0 → 0.39.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.39.0
+
+- Add application-owned assistant display names to new Chat turns through
+  `aiName` and the `addAIMessage`/`addTurn` name option. Capture the selected
+  display name before asynchronous work and preserve complete nonblank names
+  in new ordinary saved records. Restored turns use their saved name or `AI`;
+  existing history is not rewritten, and display labels stay outside model
+  context and memory. Request-only `persist:false` behavior is unchanged.
+- Add shared `applyUserSkin(skin,{root,body,cache})`, named light/dark palettes,
+  and classic `ThemePresentation.js` for cached appearance before styles load.
+  Cache presentation under the declared application ID without delaying page
+  rendering or profile readiness. Preserve unrelated body classes, custom theme
+  values and saved profile data. Scoped `data-arcane-palette` previews may select
+  their own `data-color-scheme` without changing the current page theme.
+- Extend the shared Install presentation with an explicit Update action after
+  a complete successful cache refresh detects a server-declared modification
+  or a new resource in an established inventory. Preserve change evidence
+  through interrupted refreshes and worker restarts. Initial fills, unchanged
+  resources and failed refreshes do not announce an update. Reload occurs only
+  on the user's action and preserves ordinary unsaved-work cancellation.
+
+## 0.38.0
+
+- Add `User.AI_name` as an application-owned complete string with an empty-string
+  default, ordinary getter/setter, profile loading and `updateExplicit` support.
+  Preserve older saved profiles and restore the hydrated baseline after a failed
+  save; no existing history or provider/model selection is rewritten.
+- Distinguish saved conversation speakers in file previews using the shared
+  action/action-text colors for user cards and surface/text colors for assistant
+  cards. Assistant headings use the complete saved nonblank string name or `AI`,
+  without a role suffix. Preserve other role labels, timestamps, status, complete
+  content and persistence. Capturing names on new Chat turns is separate work.
+
 ## 0.37.0
 
 - Add opt-in `markdown-editor` fit layout and preview following through

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.37.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.39.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/browser-runtime/pwa-install.mjs

@@ -1,10 +1,19 @@
 import Is from './dependencies/strong-type/index.js';
-import {createArcaneEventSource} from './event-manager.mjs';
+import {arcaneEvents, 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;
+const registrationOwners = new Set();
+
+// Internal connection to the registration owner, not a second copy of its state.
+export function observePwaRegistration(owner) {
+    registrationOwners.add(owner);
+    return function releasePwaRegistration() {
+        registrationOwners.delete(owner);
+    };
+}
 
 /** Capture native installation availability once per page, before loading UI. */
 export function getPwaInstall() {
@@ -14,7 +23,7 @@ export function getPwaInstall() {
     const owner = {
         get state() { return snapshot(); },
         get ready() { return ready; },
-        subscribe, prompt, dismiss, dispose
+        subscribe, prompt, dismiss, update, dismissUpdate, dispose
     };
     const source = createArcaneEventSource(owner, {
         source: 'arcane.pwa.install', eventTypes: [PWA_INSTALL_STATE_EVENT]
@@ -32,6 +41,8 @@ export function getPwaInstall() {
     let deferredPrompt = null;
     let disposed = false;
     let dismissed = false;
+    let updateAvailable = false;
+    let updateDismissed = false;
     let status = isRunningAsApp() ? 'running' : 'waiting';
     let outcome = null;
     let error = null;
@@ -59,7 +70,7 @@ export function getPwaInstall() {
         return {
             status,
             available: storageReady && deferredPrompt !== null && !installed && !isRunningAsApp() && !disposed,
-            installed, dismissed, outcome, error, storageError
+            installed, dismissed, updateAvailable, updateDismissed, outcome, error, storageError
         };
     }
 
@@ -237,6 +248,32 @@ export function getPwaInstall() {
         return snapshot();
     }
 
+    function onPwaState(event) {
+        if (event.source === 'arcane.pwa') receivePwaState(event.detail);
+    }
+
+    function receivePwaState(state) {
+        const pageUrl = globalThis.location?.href ?? globalThis.document?.baseURI ?? manifestUrl;
+        if (state.status === 'disposed' || state.updateAvailable !== true
+            || !state.scope || !pageUrl?.startsWith(state.scope) || updateAvailable) return;
+        updateAvailable = true;
+        publish(status, error);
+    }
+
+    function update() {
+        if (disposed || !updateAvailable) return false;
+        // Ordinary reload leaves native unload handlers and application draft ownership intact.
+        globalThis.location.reload();
+        return true;
+    }
+
+    function dismissUpdate() {
+        if (disposed) return snapshot();
+        updateDismissed = true;
+        publish(status, error);
+        return snapshot();
+    }
+
     function dispose() {
         if (disposed) return;
         deferredPrompt = null;
@@ -252,9 +289,11 @@ export function getPwaInstall() {
     observe(displayMode, 'change', onDisplayModeChange);
     observe(installedDisplayMode, 'change', onDisplayModeChange);
     observe(globalThis, 'pagehide', onPageHide);
+    listeners.push(arcaneEvents.subscribe('arcane.pwa.state', onPwaState));
     sharedOwner = owner;
     const storageTask = loadInstallStorage();
     const ready = restoreInstallation();
+    for (const registration of registrationOwners) receivePwaState(registration.state);
     if (installed) rememberInstallation();
     return owner;
 }

package/browser-runtime/pwa.mjs

@@ -1,4 +1,5 @@
 import {createArcaneEventSource} from './event-manager.mjs';
+import {observePwaRegistration} from './pwa-install.mjs';
 
 export {PWA_INSTALL_STATE_EVENT, getPwaInstall, mountPwaInstallPrompt} from './pwa-install.mjs';
 
@@ -41,6 +42,7 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
         installing: null,
         waiting: null,
         active: null,
+        updateAvailable: false,
         error: null
     };
 
@@ -60,6 +62,7 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
             installing: registration?.installing?.state ?? null,
             waiting: registration?.waiting?.state ?? null,
             active: registration?.active?.state ?? null,
+            updateAvailable: current.updateAvailable,
             error
         };
         source.dispatch(
@@ -220,6 +223,7 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
                 return;
             }
             const result = await requestResourceRefresh(worker, record?.lastChecked ?? null);
+            receiveRefresh(result);
             if (!result.error && Number.isFinite(result.lastChecked) && result.lastChecked !== record?.lastChecked) {
                 await storage.set('pwa', key, {lastChecked: result.lastChecked});
             }
@@ -239,7 +243,18 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
         refreshRegistration();
     }
 
+    function receiveRefresh(result) {
+        if (disposed || result.error || result.updateAvailable !== true || current.updateAvailable) {
+            return;
+        }
+        current.updateAvailable = true;
+        publish(current.status, current.error);
+    }
+
     function onWorkerMessage(event) {
+        if (event.data?.type === 'arcane.pwa.refreshed' && workers.has(event.source)) {
+            receiveRefresh(event.data);
+        }
         if (event.data?.type === 'arcane.pwa.capabilities' && event.data.refresh === true && workers.has(event.source)) {
             startResourceRefresh(event.source, event.data.cacheName);
         }
@@ -341,6 +356,7 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
         source.dispose();
     }
 
+    listeners.push(observePwaRegistration(owner));
     const ready = startRegistration();
     return owner;
 }

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

@@ -3013,7 +3013,7 @@
       "entrypoints": ["arcane-os/pwa"],
       "primaryImport": "arcane-os/pwa",
       "group": "Progressive web applications",
-      "summary": "Names the shared PWA lifecycle state event.",
+      "summary": "Names the shared PWA lifecycle and page-local update availability 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."
@@ -3030,7 +3030,7 @@
       "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."
+      "normalization": "Synchronous owner exposes ready, state, subscribe, update and dispose; current state replays by default. updateAvailable latches after a complete successful refresh with different parseable modification dates or a successfully checked addition to the prior durable inventory; initial fill, eviction repair, unchanged or unknown responses and partial failure do not announce updates. Pending evidence survives worker termination. update only checks the native worker, without reloading the page. Failures remain observable; disposal does not unregister the worker or delete saved data."
     },
     {
       "id": "pwa:PWA_INSTALL_STATE_EVENT",
@@ -3041,7 +3041,7 @@
       "entrypoints": ["arcane-os/pwa"],
       "primaryImport": "arcane-os/pwa",
       "group": "Progressive web applications",
-      "summary": "Names the shared native installation availability and choice state event.",
+      "summary": "Names the shared native installation availability, choice and update-prompt state event.",
       "availability": "Browser installation lifecycle; importable without starting observation",
       "protocol": "Existing Arcane event owner and native browser installation events",
       "normalization": "The exact event name is arcane.pwa.install.state."
@@ -3055,10 +3055,10 @@
       "entrypoints": ["arcane-os/pwa"],
       "primaryImport": "arcane-os/pwa",
       "group": "Progressive web applications",
-      "summary": "Returns one shared page owner for native installation availability, prompt choices and session dismissal.",
+      "summary": "Returns one shared page owner for native installation, prompt choices, independent update availability and explicit page reload.",
       "availability": "Browser native installation events; waiting state while no prompt is available",
       "protocol": "Native beforeinstallprompt, appinstalled and display-mode change events",
-      "normalization": "Synchronous owner exposes state, subscribe, prompt, dismiss and dispose; subscriptions replay current state, prompt invokes the native event directly in the user click and consumes it once, and session dismissal preserves a retained event for explicit inline installation."
+      "normalization": "Synchronous owner exposes ready, state, subscribe, prompt, dismiss, update, dismissUpdate and dispose; subscriptions replay current state. prompt invokes the native event directly in the user click and consumes it once; installation dismissal preserves that event. updateAvailable and updateDismissed are independent page-local fields. A late prompt reads current state from live registration owners; the generated bootstrap observes before registration. Explicit update synchronously calls ordinary location.reload and returns true, returns false when unavailable/disposed, and propagates native errors. Native unload cancellation leaves Update available. dismissUpdate returns state without a durable write. Installed/running status and earlier installation dismissal do not suppress updates. Native unload handling and application draft ownership remain unchanged."
     },
     {
       "id": "pwa:mountPwaInstallPrompt",
@@ -3069,7 +3069,7 @@
       "entrypoints": ["arcane-os/pwa"],
       "primaryImport": "arcane-os/pwa",
       "group": "Progressive web applications",
-      "summary": "Starts shared installation observation and mounts one initially hidden, themed installation suggestion without delaying application rendering.",
+      "summary": "Starts shared installation/update observation and mounts one initially hidden, themed suggestion without delaying application rendering.",
       "availability": "Browser document and managed HTML import; resolves to null without a document",
       "protocol": "Shared native install owner and pwa-install.html component lifecycle",
       "normalization": "Repeated calls return the same mounting promise; the first appName initializes the component, success resolves to its ready html-import host, absence of a document or disposal before mounting resolves to null, and component loading failures reject. Removal or disposal during loading rejects with AbortError. A rejected mount permits another explicit attempt. Generated PWA bootstraps invoke it automatically."

package/docs/reference/inventory/runtime-components.json

@@ -195,7 +195,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "UI/runtime state, honest model progress, complete timestamped transcript including ui_hidden stored records, user-facing structural arguments.message, nonblank all-ID tool-result restoration, collapsed complete raw inspection, ordered parallel-call replay validation, per-choice streamed/terminal complete-envelope correlation, complete nonstructural stream rendering, automatic repeated-formatting-mark removal from only the outbound speech-input copy while displayed and stored Markdown stays exact, generic visible failure outcomes with complete console diagnostics, atomic executed/declined/cancelled/not-executed result batches with one continuation, plural pending-call reload recovery, reentrant terminal-event ownership, and BFCache-preserving page lifecycle are normalized; destroy aborts observation and returns true once/false thereafter; AI/storage/media behavior remains mixed"
+      "normalization": "UI/runtime state, honest model progress, complete timestamped transcript including ui_hidden stored records, exact saved nonblank assistant display names with AI fallback rather than current-name inference, live session name capture with host.aiName display fallback, user-facing structural arguments.message, nonblank all-ID tool-result restoration, collapsed complete raw inspection, ordered parallel-call replay validation, per-choice streamed/terminal complete-envelope correlation, complete nonstructural stream rendering, automatic repeated-formatting-mark removal from only the outbound speech-input copy while displayed and stored Markdown stays exact, generic visible failure outcomes with complete console diagnostics, atomic executed/declined/cancelled/not-executed result batches with one continuation, plural pending-call reload recovery, reentrant terminal-event ownership, and BFCache-preserving page lifecycle are normalized; destroy aborts observation and returns true once/false thereafter; AI/storage/media behavior remains mixed"
     },
     {
       "file": "runtime/arcane/components/conversation-view.html",
@@ -421,7 +421,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Selection/filter state and neutral previews normalized; storage/provider behavior mixed. Initial directoryFilter and setDirectoryFilter(fn|null) use false-only exclusion before built-in DBOPFS key/metadata reads; data-hidden-prefixes also applies to directories unless data-show-hidden is present. Existing file predicates preserve their first argument and receive optional directory/fileName/path/layout context. previewDescriptor(original File,{directory,fileName,extension,path,mimeType,signal}) may asynchronously return text/markdown/html/json content, conversation messages with role/content/real timestamp and optional name/status, collection items, or image/audio/pdf/download content as Blob/File or a lazy ({signal}) loader. Downloads require fileName; descriptors accept title and images accept alt. Lazy items load only on explicit request and retain item-local retry. Close, replacement, and destroy abort the preview signal, suppress late output, remove iframe srcdoc, stop audio, and revoke all owned object URLs. HTML preserves the exact string in iframe srcdoc; HTML/Markdown MIME fallback supports extensionless files. Nullish descriptors preserve previewTransform for JSON-family files and native previews; untransformed JSONL/NDJSON retains complete raw text, and other binary files download the original File."
+      "normalization": "Selection/filter state and neutral previews normalized; storage/provider behavior mixed. Initial directoryFilter and setDirectoryFilter(fn|null) use false-only exclusion before built-in DBOPFS key/metadata reads; data-hidden-prefixes also applies to directories unless data-show-hidden is present. Existing file predicates preserve their first argument and receive optional directory/fileName/path/layout context. previewDescriptor(original File,{directory,fileName,extension,path,mimeType,signal}) may asynchronously return text/markdown/html/json content, conversation messages with role/content/real timestamp and optional name/status, collection items, or image/audio/pdf/download content as Blob/File or a lazy ({signal}) loader. Assistant conversation labels use the exact nonblank string name or AI without a role suffix; other role labels retain existing name/role presentation. User and assistant cards have distinct theme backgrounds and preserve data-role. Downloads require fileName; descriptors accept title and images accept alt. Lazy items load only on explicit request and retain item-local retry. Close, replacement, and destroy abort the preview signal, suppress late output, remove iframe srcdoc, stop audio, and revoke all owned object URLs. HTML preserves the exact string in iframe srcdoc; HTML/Markdown MIME fallback supports extensionless files. Nullish descriptors preserve previewTransform for JSON-family files and native previews; untransformed JSONL/NDJSON retains complete raw text, and other binary files download the original File."
     },
     {
       "file": "runtime/arcane/components/header.html",
@@ -650,11 +650,13 @@
     {
       "file": "runtime/arcane/components/pwa-install.html",
       "name": "pwa-install.html",
-      "purpose": "Presents a dismissible browser installation action with floating or inline placement.",
+      "purpose": "Presents independent installation and explicit update/reload actions with floating or inline placement.",
       "methods": [
         "configure()",
         "install()",
         "dismiss()",
+        "update()",
+        "dismissUpdate()",
         "destroy()",
         "state",
         "ready"
@@ -671,9 +673,9 @@
         "arcane-os/event-manager",
         "arcane-os/logging"
       ],
-      "availability": "Browser installation requires a browser-provided beforeinstallprompt event; otherwise hidden",
-      "transport": "HTMLImport + DOM; shared PWA installation owner and browser-native prompt",
-      "normalization": "Browser install availability and outcome supplied by the shared PWA owner"
+      "availability": "Installation requires beforeinstallprompt; a completed changed refresh independently enables the Update action",
+      "transport": "HTMLImport + DOM; shared PWA owner, browser-native install prompt and explicit ordinary page reload",
+      "normalization": "Complete labels and independent installation/update state; update dismissal is page-local, and native unload cancellation leaves Update available"
     },
     {
       "file": "runtime/arcane/components/record-timeline.html",

package/docs/reference/inventory/runtime-entities.json

@@ -9,7 +9,7 @@
   "modules": [
     {"file":"runtime/arcane/entities/ApiModelRecord.js","exports":["default"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/Calculation.js","exports":["default"],"availability":"cross-host","normalization":"normalized"},
-    {"file":"runtime/arcane/entities/Chat.js","exports":["default"],"availability":"browser/native-webview","normalization":"Provider-facing recurring messages preserve raw structural protocol only for the one active matching continuation, then replace settled exchanges with complete ordinary visible content; transcript records remain sanitized and readable, including ui_hidden rows; ordered parallel structural calls require one exact nonblank result for every pending ID in one atomic turn, with rollback-safe persistence."},
+    {"file":"runtime/arcane/entities/Chat.js","exports":["default"],"availability":"browser/native-webview","normalization":"Provider-facing recurring messages preserve raw structural protocol only for the one active matching continuation, then replace settled exchanges with complete ordinary visible content; transcript records remain sanitized and readable, including ui_hidden rows. aiName defaults to empty; addAIMessage and addTurn capture an optional exact nonblank application-owned name on new assistant records only. Provider names do not establish display attribution; assistant display names stay out of messages and memory extraction, and existing records are never renamed or rewritten. ordered parallel structural calls require one exact nonblank result for every pending ID in one atomic turn, with rollback-safe persistence."},
     {"file":"runtime/arcane/entities/CommunicationMessage.js","exports":["communicationChannels","default"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/CommunicationThread.js","exports":["default"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/Document.js","exports":["default"],"availability":"browser/native-webview","normalization":"mixed"},
@@ -19,7 +19,7 @@
     {"file":"runtime/arcane/entities/Preference.js","exports":["default","preferenceSchema"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/TerminalSession.js","exports":["default","terminalShells"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/Theme.js","exports":["arcaneDarkThemeTokens","arcaneLightThemeTokens","default","themeColorToHex","themeTokens"],"availability":"cross-host/dom-when-applied","normalization":"normalized/mixed"},
-    {"file":"runtime/arcane/entities/User.js","exports":["default","profileUpdateFromSearchParams"],"availability":"browser/native-webview","normalization":"updateExplicit accepts existing partial/JSON updates or an awaited fresh-profile callback under the existing serialized write owner; callback null skips saving and returns the fresh profile, while failed writes restore the fresh baseline. Timestamp setters persist partial fields through that owner. profileUpdateFromSearchParams purely maps nonempty supplied URLSearchParams values without further decoding, trimming, or persistence."},
+    {"file":"runtime/arcane/entities/User.js","exports":["default","profileUpdateFromSearchParams"],"availability":"browser/native-webview","normalization":"AI_name is a persisted string preference with an empty-string default that preserves complete supplied text alongside AI_personality; loading older records does not rewrite them. updateExplicit accepts existing partial/JSON updates or an awaited fresh-profile callback under the existing serialized write owner; callback null skips saving and returns the fresh profile, while failed writes restore the fresh baseline. Timestamp setters persist partial fields through that owner. profileUpdateFromSearchParams purely maps nonempty supplied URLSearchParams values without further decoding, trimming, or persistence."},
     {"file":"runtime/arcane/entities/Weather.js","exports":["WeatherDay","WeatherLocation","WeatherObservation","WeatherSnapshot"],"availability":"cross-host","normalization":"normalized"}
   ]
 }

package/docs/reference/inventory/runtime-modules.json

@@ -8,9 +8,9 @@
     "sdkVersion": "0.6.0",
     "protocol": "arcane/1"
   },
-  "artifactCount": 88,
-  "javascriptArtifactCount": 86,
-  "esmExportCount": 356,
+  "artifactCount": 89,
+  "javascriptArtifactCount": 87,
+  "esmExportCount": 357,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -1010,7 +1010,7 @@
       "availability": "Browser or native WebView with the projected ChatEntity, DBOPFS, and a configured chat function or normalized Arcane.ai surface",
       "protocol": "Existing ChatEntity/DBOPFS methods plus provider-neutral chat request/result records",
       "normalization": "Preserves complete ordinary visible recurring provider history, one active raw structural continuation, every sanitized timestamped transcript record, and arbitrary nonempty caller-owned chat file names; commits live context atomically; falls back from optional streaming to configured non-stream transport; carries per-turn generation options while owning lifecycle callbacks; exposes complete data callbacks; accepts terminal-only structural calls; correlates every observed per-choice call against the exact validated terminal envelope before callback/persistence; atomically settles every pending ID once; and keeps malformed stored records readable without inventing or rewriting messages.",
-      "surface": "Default/named `PersistentAIChatSession`, `createPersistentAIChatSession()`; `create()`, `ai`, `chatEntity`, `fileName`, `ready()`, `history()`, `transcript()`, `settleMemory()`, `send()`, and `stream()`."
+      "surface": "Default/named `PersistentAIChatSession`, `createPersistentAIChatSession()`; `create()`, `ai`, `chatEntity`, `fileName`, `ready()`, `history()`, `transcript()`, `settleMemory()`, `open()`, `send()`, and `stream()`. Optional constructor aiName and getter/setter accept a string; open/send/stream capture it before their first await. A nonblank application name is preserved exactly on the copied terminal message and retained assistant transcript, with the actual assistant record timestamp when available. Complete raw providerResponse stays unchanged; configured model context and memory omit the application display name. Existing history is never renamed or rewritten, and persist:false remains operation-only."
     },
     {
       "file": "runtime/arcane/modules/PreferenceStore.js",
@@ -1292,25 +1292,37 @@
         "default",
         "disposeArcaneThemeBootstrap"
       ],
-      "summary": "Performs import-time Arcane theme loading and subscribes to native appearance changes.",
+      "summary": "Reuses the shared presentation owner, loads authoritative preferences, and observes native appearance and existing canonical User readiness without blocking rendering or starting User storage.",
       "availability": "Browser/native hybrid",
       "protocol": "ThemeManager + host Arcane.events projected once through the per-realm globalThis.arcaneEvents authority",
       "normalization": "Theme state normalized; storage/native errors mixed.",
-      "surface": "`bootstrapArcaneTheme()`, `disposeArcaneThemeBootstrap()`, `arcaneThemeReady`, and default ready promise."
+      "surface": "`bootstrapArcaneTheme()`, `disposeArcaneThemeBootstrap()`, `arcaneThemeReady`, and default ready promise. Shared bootstrap replays an already-ready User and disposes both appearance and user-ready subscriptions; presentation cache is nonauthoritative. Its module graph does not guarantee restoration before first paint; use the classic ThemePresentation entry after app-id and before CSS."
     },
     {
       "file": "runtime/arcane/modules/ThemeManager.js",
       "name": "ThemeManager.js",
       "kind": "esm",
       "exports": [
+        "applyUserSkin",
         "default",
         "loadAndApplyTheme"
       ],
       "summary": "Loads, applies, previews, saves, resets, and synchronizes semantic Arcane themes.",
       "availability": "Browser/native hybrid",
       "protocol": "PreferenceStore, DOM, Arcane.appearance",
-      "normalization": "Theme values/events normalized; storage/native failures mixed.",
-      "surface": "default `ThemeManager`, `loadAndApplyTheme()`; scheme/custom/system APIs and `arcane-theme-change`."
+      "normalization": "Theme values/events normalized; storage/native failures mixed. Scoped data-arcane-palette previews follow the page unless their own data-color-scheme is light or dark; this preview override leaves page mode unchanged, with chooser order/layout/toggle owned by the application.",
+      "surface": "default `ThemeManager`, `loadAndApplyTheme()`, synchronous `applyUserSkin(skin,{root?,body?,cache=true}={})` delegated to ThemePresentation; complete skin classes preserve unrelated body classes, names default/warm/curious/hopeful/harmony/warrior follow light/dark/system, custom themes retain precedence, and data-arcane-palette scopes shared-color previews. Bare root retains generic neutral colors. Complete strings and numeric class text are cached without a User write. apply() records only applied appearance attributes and Theme-owned custom properties; preview() stays transient. Cache is reconciled by saved preferences and existing User readiness; no profile migration or first-paint guarantee from module-only use. Existing scheme/custom/system APIs and arcane-theme-change remain."
+    },
+    {
+      "file": "runtime/arcane/modules/ThemePresentation.js",
+      "name": "ThemePresentation.js",
+      "kind": "classic-script",
+      "exports": [],
+      "summary": "Restores app-scoped presentation before CSS and owns complete skin-class application without starting profile storage.",
+      "availability": "Browser / native WebView classic script",
+      "protocol": "DOM and optional application-scoped localStorage",
+      "normalization": "Synchronous presentation only; complete strings and numeric class text remain usable, cache failures preserve rendering, and authoritative profile and appearance loads reconcile the cache.",
+      "surface": "No ESM exports; globalThis.arcaneThemePresentation with applyUserSkin(skin,{root?,body?,cache?}) returning palette|null, remember(fields,root?) returning boolean, restore(root?) returning cached record ({} on miss) or null when unavailable/failed, and reportError(message,error). Classic script runs after the existing app-id declaration and before CSS without type=module, async, or defer; first evaluation restores automatically. Cache fields: skin, palette, appearance:{colorScheme,density,reduceMotion,fontSize}, customProperties (Theme-owned applied CSS map or null). Complete Error goes to console.warn initially and shared logging after ThemeManager import. No User import, OPFS, model wait, profile snapshot, unrelated inline style capture, or migration; missing cache cannot supply an unloaded profile skin."
     },
     {
       "file": "runtime/arcane/modules/TimeGuard.js",

package/docs/reference/pwa.md

@@ -266,6 +266,33 @@ 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.
 
+After a complete successful refresh, `updateAvailable` becomes true for an
+already-open page when at least one cached replacement has different parseable
+old and new `Last-Modified` dates, or a successfully checked resource was absent
+from the prior durable offline inventory. Different modification dates are the
+server's declaration of modification, not a comparison of response content.
+Initial cache population, eviction repair of a previously selected URL, `304`,
+and `200` responses with equal, missing or unreadable modification dates do not
+establish an update. Such successful responses still follow the existing cache
+replacement behavior. A host without meaningful modification dates cannot
+announce same-URL changes through this contract.
+
+The resource cache privately retains the pre-refresh inventory membership and
+a pending-change flag while a refresh is incomplete. Before replacing a resource
+with a different modification date, it also saves that resource's prior date.
+Writes to this one metadata entry are ordered; independent resource fetches
+remain concurrent. This lifecycle record is outside the resource inventory and
+is never fetched from the server. A change becomes evidence only after the
+resource's cache write succeeds. After interruption, the cached response's date
+is compared with the retained prior date, so a failed later metadata write cannot
+lose that evidence. Failed replacements alone establish no update. The record
+survives worker termination and partial refresh failure and is cleared after
+complete success.
+Partial failure never announces a newly available update. The completed worker
+reply and a scoped message to existing window clients carry the result; each
+page owner keeps its own sticky availability state. A new page does not replay
+an old completed notification.
+
 ## Updates and stored data
 
 An updated worker installs alongside the current worker, then waits for the
@@ -273,7 +300,7 @@ 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,
+The SDK does not call `skipWaiting`, claim the initial page, automatically reload a page,
 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.
@@ -284,6 +311,15 @@ 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.
 
+When a complete resource refresh establishes an update, the shared prompt shows
+**Update available** and **Update**, including in an installed or running app
+and after an earlier installation suggestion was dismissed. Update dismissal
+is separate and lasts for this page owner's lifetime. Clicking Update calls
+ordinary `location.reload()` for the current page, with no extra SDK
+confirmation or cache reset. Native `beforeunload` handling and application-owned
+draft/session persistence retain their normal ownership. This is a page reload,
+not a promise to preserve transient application state or an active chat.
+
 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.
@@ -308,7 +344,8 @@ configuration, methods and events.
 
 The browser controls the URL-bar installation indicator and native prompt.
 The SDK cannot force either to appear. Without a captured
-`beforeinstallprompt`, the component remains hidden; that waiting state does
+`beforeinstallprompt`, installation remains hidden; an available update can
+still show. That waiting installation state does
 not establish that installation is unsupported. The browser may still be
 evaluating the app, may already have it installed, or may only support a
 manual browser-menu installation path.
@@ -354,12 +391,13 @@ does not infer installation support from the user-agent string. See
 
 Import `getPwaInstall` and `PWA_INSTALL_STATE_EVENT` from `arcane-os/pwa`.
 `getPwaInstall()` synchronously returns the shared page owner with `state`, `ready`,
-`subscribe`, `prompt`, `dismiss` and `dispose`. Call it early when owning a
+`subscribe`, `prompt`, `dismiss`, `update`, `dismissUpdate` and `dispose`. Call it early when owning a
 separate install entry point so it can capture `beforeinstallprompt` before
 loading the UI. The generated bootstrap already does this through
 `mountPwaInstallPrompt()`.
 
-`state` contains `status`, `available`, `installed`, `dismissed`, `outcome`,
+`state` contains `status`, `available`, `installed`, `dismissed`, `updateAvailable`,
+`updateDismissed`, `outcome`,
 `error` and `storageError`.
 Status is `waiting`, `available`, `prompting`, `accepted`, `dismissed`,
 `installed`, `running`, `error` or `disposed`. `available` means a native event
@@ -371,6 +409,15 @@ or restoration of that app's saved installation record.
 choice. `error` carries the complete prompt error, or `null`; `storageError`
 carries the complete DBOPFS read or write error, or `null`.
 
+`updateAvailable` starts false and remains true after this owner observes a
+completed changed refresh for the current page's worker scope through
+`arcane.pwa.state`. `updateDismissed` starts false and is independent of
+installation dismissal and saved installation status. Neither field changes
+native installation `status` or `available`. A late-created prompt reads the
+current state of live registration owners before returning; earlier creation
+is still needed to capture a browser installation event that has not yet fired.
+The generated bootstrap establishes observation before registering the worker.
+
 `ready` resolves to the state after the initial DBOPFS read settles. Native
 events are captured synchronously while this read runs. Only installation
 availability waits for it; page rendering, component loading and worker
@@ -425,6 +472,15 @@ newly observed installation, and a confirmed installation's pending write is
 retained through owner disposal. A write failure remains observable without
 making the current installed session eligible again.
 
+`update()` synchronously calls the current page's ordinary `location.reload()`
+and returns `true` when an update is available, including after dismissal.
+It returns `false` when unavailable or disposed. A native reload error propagates
+to the caller. It leaves availability unchanged so a cancelled native unload
+does not discard the update. `dismissUpdate()` hides the update suggestion for
+this page owner and returns the current state, without changing installation
+dismissal or writing a durable record. A disposed owner returns its current
+state unchanged. Call `update()` only from the user's explicit Update action.
+
 Running in an app display mode publishes `running`. These states
 do not establish offline readiness. On Android, `appinstalled` can arrive
 before WebAPK creation finishes. See the
@@ -494,14 +550,20 @@ 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
+`waiting`, `active`, `updateAvailable` 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`.
+`updateAvailable` starts false and latches true after a successful full refresh
+with known change evidence; later native lifecycle/error events preserve it,
+and subscriptions replay it. Duplicate worker replies and broadcasts do not
+produce another availability transition. It is page-local, not persisted in
+DBOPFS, and remains separate from native worker activation.
 
 `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
+`update()` requests the browser's normal worker update check on demand, not a
+page reload or a forced resource refresh; 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.