arcane-os 0.38.0 → 0.39.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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

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.38.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",
@@ -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"},

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.

package/docs/reference/runtime-components.md

@@ -82,7 +82,7 @@ appropriate.
 | [`modal.html`](#modalhtml) | Generic modal with population, configurable user dismissal, actions, and concurrent task execution. | `configure()`<br>`populate()`<br>`open()`<br>`close()`<br>`runTasks()`<br>`destroy()`<br>`running`<br>`opened` | `modal-ready`<br>`modal-opened`<br>`modal-closed`<br>`modal-action` | Modal state normalized; injected task results mixed |
 | [`output-panel.html`](#output-panelhtml) | Presents status, output, body, coverage, actions, pending, error, and cleared states. | `configure()`<br>`setOutput()`<br>`setBody()`<br>`setCoverage()`<br>`setActions()`<br>`setPending()`<br>`setStatus()`<br>`setError()`<br>`clear()`<br>`destroy()` | `output-panel-ready`<br>`output-panel-state`<br>`output-panel-change`<br>`output-panel-action`<br>`output-panel-error`<br>`output-panel-cleared` | DOM-normalized |
 | [`preferences-form.html`](#preferences-formhtml) | Builds a schema-driven preferences form with submit, reset, busy, and status behavior. | `configure()`<br>`getValues()`<br>`setValues()`<br>`setBusy()`<br>`setStatus()`<br>`destroy()` | `preferences-form-ready`<br>`preferences-change`<br>`preferences-submit`<br>`preferences-reset` | Normalized form values |
-| [`pwa-install.html`](#pwa-installhtml) | Presents a dismissible browser installation action with floating or inline placement. | `configure()`<br>`install()`<br>`dismiss()`<br>`destroy()`<br>`state`<br>`ready` | `pwa-install-ready`<br>`pwa-install-change`<br>`pwa-install-dismissed` | Browser install availability and outcome supplied by the shared PWA owner |
+| [`pwa-install.html`](#pwa-installhtml) | Presents independent installation and explicit update/reload actions with floating or inline placement. | `configure()`<br>`install()`<br>`dismiss()`<br>`update()`<br>`dismissUpdate()`<br>`destroy()`<br>`state`<br>`ready` | `pwa-install-ready`<br>`pwa-install-change`<br>`pwa-install-dismissed` | Complete labels and independent installation/update state; native unload cancellation leaves Update available |
 | [`record-timeline.html`](#record-timelinehtml) | Displays complete chronological records/evidence and emits open actions. | `setItems()`<br>`populate()`<br>`destroy()` | `record-timeline-ready`<br>`record-timeline-open` | Complete item fields and inventories preserved |
 | [`relationship-board.html`](#relationship-boardhtml) | Displays complete normalized relationship nodes/edges in graph and list forms. | `setGraph()`<br>`populate()`<br>`destroy()` | `relationship-board-ready`<br>`relationship-node-open`<br>`relationship-edge-open` | Complete graph inventories and fields preserved |
 | [`screen-capture.html`](#screen-capturehtml) | Presents image, video, or GIF display-capture workflow. | `capture` (`ScreenCapture` instance)<br>`destroy()` | `screen-capture-ready`<br>`screen-capture-result` | State/result normalized; media permission/codec failures mixed |
@@ -351,6 +351,15 @@ restored or new message uses a separate semantic `<time>` element at the card's
 lower-right with an ISO `datetime`, full local title, and local 24-hour `HH:MM`
 text.
 
+Restored assistant cards use the record's exact nonblank string `name`, or
+`AI` when absent. The current profile/model/voice name never renames older
+messages. For live session replies, the card starts with `session.aiName`
+when nonblank, otherwise the existing `host.aiName` display value; the terminal
+result aligns it with the name captured by the session for that operation.
+Set the session/entity name as well as the live component label when the
+application intends new saved turns to retain that attribution. The shared
+component does not persist the profile name or choose a naming policy.
+
 Assistant structural calls render their nonempty `function.arguments.message`
 as ordinary visible progress. The exact call name and argument string are
 retained inside a collapsed `Tool call details` inspection surface. Displaying
@@ -1257,9 +1266,10 @@ Events: `preferences-form-ready`, `preferences-change`, `preferences-submit`, `p
 
 ### Overview
 
-A compact installation suggestion using the shared [PWA installation owner](pwa.md).
-The default floating panel appears near the top right only when the browser offers
-installation. It has an Install action and an explicit close button, takes no
+A compact installation and update suggestion using the shared [PWA owner](pwa.md).
+The default floating panel appears near the top right when the browser offers
+installation or a completed resource refresh establishes an update. It has an
+Install or Update action and an explicit close button, takes no
 focus automatically, and has no dismissal timer. It uses the Arcane theme and
 primitives, wraps complete labels and errors, and scrolls its own content when
 the available height is limited. The parent page loads `ThemeBootstrap.js` to
@@ -1268,7 +1278,8 @@ apply the user's appearance preferences.
 ### Public surface
 
 `configure({appName, installLabel, closeLabel, promptingLabel, description,
-presentation})` updates display configuration and returns its current record.
+updateTitle, updateLabel, updateDescription, updateCloseLabel, presentation})`
+updates display configuration and returns its current record.
 Labels remain complete strings. `appName` initially uses `data-app-name` or
 `this app`; the default button label is `Install`. `presentation` is `floating`
 by default or `inline`, initially read from `data-presentation`. Inline placement
@@ -1282,6 +1293,20 @@ An explicit request's complete failure message remains visible until dismissed;
 the method rejects with the same error. The browser controls actual installation.
 Acceptance hides the suggestion without claiming installation has completed.
 
+When an update is available, the same panel shows `Update available`, `Update`,
+`Reload this page to use the updated app.`, and the close label `Close update
+suggestion`. Each string has its matching configuration key. This presentation
+takes precedence over installation, including for installed/running apps and
+previously dismissed installation suggestions.
+
+`update()` calls the shared owner's ordinary `location.reload()` synchronously,
+returning true when available and false when unavailable or destroyed. It leaves
+availability intact if a native unload handler cancels navigation. Native reload
+errors propagate; the button observes them through developer diagnostics. There
+is no automatic reload, extra SDK confirmation, cache reset, or guarantee of
+preserving transient application state. `dismissUpdate()` hides only the update
+suggestion for this page owner and returns true, or false after destruction.
+
 `dismiss()` closes the component. Floating dismissal also uses the owner's
 session dismissal; an explicit inline component ignores that shared dismissal
 and closes only its own instance. Closing retains any unused native prompt at
@@ -1290,22 +1315,28 @@ disposes its event source, hides its host, and marks `ready` false; it does not
 dispose the shared owner or change browser installation state. Both methods
 return true while active and false after destruction; `destroy()` is idempotent.
 
-The readonly `state` property returns the shared owner's current install-state
+The readonly `state` property returns the shared owner's current install/update-state
 record; `ready` becomes true after methods and the state subscription are attached.
 `pwa-install-ready` carries `{ready, state}`; `pwa-install-change` carries
 `{state, visible}` for each observed owner update; `pwa-install-dismissed` carries
-`{presentation, state}`. These follow the canonical event projection contract.
+`{presentation, state}`, with `kind: 'update'` for update dismissal. These follow
+the canonical event projection contract.
 
 ### Availability and normalization
 
 The component requires HTMLImport and a DOM renderer. Native installation
 availability comes from the browser's `beforeinstallprompt` event through
-`getPwaInstall()`. Without an available event, the suggestion stays hidden;
+`getPwaInstall()`. Without an available event, the installation suggestion stays hidden;
 absence does not identify why installation is unavailable. Installed-app events,
 accepted prompts, and an already running installed display mode hide it.
 The shared SDK owner persists browser-reported installation in app-scoped
 DBOPFS. Both floating and inline controls stay hidden while that record is
 loading and remain hidden on later visits when installation is remembered.
+Those installation conditions do not hide an available update. Update state
+comes from the existing page-scoped registration owner, including a current-state
+read when the prompt is created after the refresh. A new page does not replay a
+completed update from an earlier page. Update dismissal is independent of saved
+installation state and performs no durable write.
 Acceptance alone does not save installation. The component's `ready` means
 its methods and subscription are attached; storage completion belongs to the
 shared owner's `ready` promise and does not delay page rendering.

package/docs/reference/runtime-entities.md

@@ -78,8 +78,9 @@ call and its matching results remain raw only through their one active provider
 continuation. Once that continuation settles, `messages` replaces the protocol
 with complete ordinary visible call, public result, and assistant content.
 `transcript` returns the narrow human-readable projection owned by the durable
-storage boundary. User and assistant records contain only role, complete
-visible content, and their real timestamp. A visible tool record may
+storage boundary. User and assistant records contain role, complete
+visible content, and their real timestamp. An assistant record may also carry
+its application-owned display `name`. A visible tool record may
 additionally carry its public name and plain result status, while its `content`
 comes only from the tool call's required user-facing `message`. System prompts,
 reasoning, provider-extension fields, memory flags, raw tool calls, call IDs,
@@ -90,6 +91,15 @@ One complete nonblank assistant record is also a durable conversation entry, so
 a model-authored opening can be stored and survive maintenance before the first
 ordinary user turn. No synthetic user record is required or written.
 
+`aiName` defaults to an empty string. `addAIMessage(text,{name=chat.aiName,...})`
+and `addTurn({name=chat.aiName,...})` capture that application-owned name on the
+new assistant record. A nonblank string is preserved exactly; blank or
+nonstring names are omitted. Provider `message.name` never establishes that
+display attribution. The name is transcript-only metadata: `messages` and
+memory extraction omit it, including during a pending tool continuation.
+Changing `aiName` affects later messages only; loading existing records does
+not rename or rewrite them.
+
 An assistant record may open an ordered array of structural calls with unique
 IDs in transient provider state. Until every pending ID receives exactly one
 matching nonblank `role:'tool'` result in the same active session, another