arcane-os 0.59.1 → 0.61.0

package/docs/reference/core/reference/arcane-api/ai-and-ollama.md

@@ -646,7 +646,7 @@ console.info({
 
 ### Overview
 
-`Arcane.speech.synthesize(request)` converts bounded text to local speech. Use
+`Arcane.speech.synthesize(request, options?)` converts bounded text to local speech. Use
 it only after checking synthesis readiness, and create an audio URL from the
 returned bytes without logging the base64 payload.
 
@@ -683,20 +683,29 @@ owned active operation before retrying.
 ### Streaming, cancellation, and events
 
 Synthesis returns one complete audio result and emits no method event. The
-wrapper timeout is 180 seconds, no signal is exposed, and timeout or page
-teardown does not promise cancellation of Core or Android speech work.
+wrapper timeout remains 180 seconds. Optional `{signal}` controls the Core
+request lifetime separately from the complete synthesis payload. Pre-abort
+sends no request; in-flight abort sends `request.cancel`, rejects with
+`ARCANE_REQUEST_ABORTED` and suppresses late responses. Unrelated requests
+continue. The registered native service owns actual synthesis interruption and
+resource release; the facade supplies no engine. `AI.fetchTTS(payload, signal)`
+forwards its signal through this call and normalizes cancellation to
+`AbortError` with `ARCANE_AI_REQUEST_ABORTED`.
 
 ### Example
 
 ```javascript
-const result = await globalThis.Arcane.speech.synthesize({
-    input: 'Your local speech service is ready.',
-    voice: 'af_heart',
-    responseFormat: 'opus',
-    speed: 1
-});
-
-console.info(result.contentType, result.audioBase64.length);
+async function synthesizeMoonEncore(input, signal) {
+    return globalThis.Arcane.speech.synthesize(
+        {
+            input,
+            voice: 'af_heart',
+            responseFormat: 'opus',
+            speed: 1
+        },
+        {signal}
+    );
+}
 ```
 
 ## Arcane.speech.transcribe()

package/docs/reference/core/reference/arcane-api/namespaces.md

@@ -1038,6 +1038,20 @@ const canReadPreferences = access.methods.includes('preferences.list');
 console.log('Preference inventory admitted:', canReadPreferences);
 ```
 
+## Arcane.window
+
+The SDK client exposes `Arcane.window.setTheme(presentation, {signal}?)` for
+the window hosting the calling document. The optional `backgroundColor` and
+`textColor` accept numeric RGBA records or `null` for platform-default reset.
+The host reports each applied or unsupported field independently. Rendering
+and browser theme changes continue without waiting for this request.
+
+Shared ThemeBootstrap forwards the app's computed semantic colors through
+this method when a native host is present. It does not change OS-user
+appearance. See the [current-window contract](../../../core-client.md#current-window-theme)
+for complete usage, accepted channel values, cancellation and current adapter
+availability. A facade method alone does not establish host support.
+
 ## Arcane.appearance
 
 ### Overview

package/docs/reference/core-client.md

@@ -83,6 +83,9 @@ the 180,000 ms timeout and pass the complete request unchanged. A pre-aborted
 signal sends no synthesis request; an in-flight abort sends `request.cancel`
 and suppresses late responses. Actual synthesis interruption depends on the
 registered speech service and its engine; the facade supplies no speech engine.
+`AI.fetchTTS(payload, signal)` carries its caller-owned signal into this native
+call and normalizes cancellation to `AbortError` with
+`ARCANE_AI_REQUEST_ABORTED`, preserving the original error as its cause.
 
 `Arcane.speech.transcribe(request, {signal})` forwards cancellation through the
 same request lifetime and retains its 180,000 ms timeout and complete request.
@@ -91,6 +94,70 @@ pre-aborted signal sends no transcription request; an in-flight abort sends
 `request.cancel` and suppresses late responses. The registered transcription
 service owns interruption and release of its actual engine operation.
 
+## Current-window theme
+
+`Arcane.window.setTheme(presentation, {signal}?)` changes only the window
+hosting the calling document. It uses the existing `window.setTheme` request
+and response correlation; it neither calls `appearance.apply` nor changes the
+operating-system user's appearance. The complete presentation object reaches
+the host unchanged.
+
+Each optional `backgroundColor` and `textColor` is either `null` to restore the
+platform default or `{red, green, blue, alpha}`. All four channels are numbers:
+finite sRGB red/green/blue from 0 through 255 and alpha from 0 through 1.
+Omitting a field leaves its current value unchanged. There is no scheme field.
+
+```js
+const host=globalThis.Arcane;
+if(host?.runtime?.current().native&&host.window?.setTheme){
+    host.window.setTheme(
+        {
+            backgroundColor:{red:29,green:22,blue:19,alpha:1},
+            textColor:{red:248,green:239,blue:229,alpha:1}
+        }
+    ).then(
+        function reportWindowColors(result){
+            console.log('Moon observatory window colors:',result);
+        }
+    ).catch(
+        function reportWindowFailure(error){
+            console.error('Window color update failed.',error);
+        }
+    );
+}
+// Page rendering continues independently of the host request.
+```
+
+The result is `{platform, supported, applied, unsupported}`. `applied` contains
+only requested fields the platform accepted in this call, including `null`
+for an accepted default reset. `unsupported` lists requested fields the adapter
+cannot apply. `supported` is true when at least one field was applied. These
+are accepted settings, not measured pixels, and the operation is not atomic.
+Malformed arguments reject with `INVALID_ARGUMENT`; native API failures reject
+with `ARCANE_WINDOW_THEME_FAILED`, preserving the native error and
+`details.applied`/`details.unsupported` for earlier results in this call.
+
+The Windows host maps background/text to DWM caption/text attributes supported
+on Windows 11 build 22000 and later, retaining normal system window controls.
+It rounds RGB channels to the nearest integer, with midpoint values rounded
+up, and returns those actual accepted values. Translucent colors remain
+unsupported without changing the existing field. Older Windows reports those
+fields unsupported. This contract makes no promise about caption-button colors.
+The current macOS and Linux hosts have no implementation of this method;
+their ordinary unavailable-method response remains observable. A new facade
+alone does not add the operation to an older native executable. Use the
+matching published host artifact for the selected SDK version.
+
+Cancellation uses the normal request lifetime and suppresses late responses;
+it does not roll back a setting the host already accepted. Window settings
+survive document navigation until a subsequent document changes them or the
+window closes. Responses belong to their originating document.
+
+The shared [ThemeBootstrap](runtime-modules.md#themebootstrapjs) automatically
+forwards the app's computed `--background` and `--text-color` in native hosts.
+Applications using that owner need no duplicate theme listener. Ordinary
+browsers keep their CSS presentation without making a native request.
+
 ## Events and request lifetime
 
 `events.on(name, listener)`, `once(name, listener)` and

package/docs/reference/core-native-packaging.md

@@ -303,6 +303,70 @@ observes complete diagnostics and exit. Cancelling that operation closes its
 input, allowing the window and accepted Core service work to drain without a
 forced process termination.
 
+### Application icon and window colors
+
+`appDescriptor.native.icon` selects the application's existing app-relative
+image. Windows assembly converts PNG images, including a 512-pixel source,
+into a derived `runtime/arcane-app.ico` with 16, 32, 48 and 256-pixel images.
+Aspect ratio and transparency are preserved. An ICO selection keeps its
+authored image set. The original application asset remains unchanged.
+
+The provider embeds the selected images in the copied `Arcane.exe` and records
+`manifest.host.icon` and `manifest.host.executableIcon:true`. It replaces the
+executable's main icon group while preserving other groups, languages, resources
+and file content. Conversion uses Node standard capabilities on every assembly
+platform; it adds no application compiler, image library or Windows-only build
+step. The selected host cache and Core executable remain unchanged.
+
+JPEG/JPG, WebP and other existing descriptor formats retain ordinary assembly.
+They currently report `native.icon.unsupported` through the builder's `onEvent`
+callback, as does a selected executable whose PE layout cannot accommodate the
+derived icon. The event identifies the app, icon, target, code and complete
+message; `manifest.host.executableIcon:false` reports that the executable keeps
+its prior icon. `host.icon` then points to the original selected image. This is
+an explicit unsupported branding result, not a claim that a generic icon was
+replaced. Unreadable files and malformed supported image data report their
+ordinary filesystem or image-parser error.
+
+The matching Windows launcher reads `host.icon` and loads it independently of
+Core and page startup. ICO and standard Windows image codecs supply the window
+and taskbar icon; JPEG/JPG can therefore work at runtime even while executable
+embedding is unsupported. WebP is outside the host's standard image codecs;
+runtime support is not promised. A runtime icon error preserves ordinary startup
+and reaches complete developer diagnostics as `ARCANE_WINDOW_ICON_UNAVAILABLE`.
+Hosts built before this option was introduced do not read the new icon field.
+
+`Arcane.window.setTheme(presentation,{signal}?)` changes only the requesting
+native window's chrome. The shared ThemeBootstrap supplies computed application
+background and text colors without delaying application CSS or rendering.
+Direct callers may supply `backgroundColor` and `textColor`, each either
+`{red,green,blue,alpha}` or `null` to restore the platform default. RGB channels
+are finite numbers from 0 through 255 and alpha is from 0 through 1. Omitted
+fields remain unchanged. The complete presentation follows the existing Core
+request transport; the window host handles `window.setTheme` before forwarding
+other methods to Core. No system appearance setting changes.
+
+Windows 11 build 22000 and later support titlebar background and text colors
+through DWM. The normal titlebar and window controls remain in place. DWM accepts
+opaque colors, so alpha values other than exactly 1 report that field as
+unsupported. RGB values round to the nearest integer, with midpoint values
+rounded upward. Older Windows versions report the requested fields unsupported.
+
+The result is `{platform:'windows',supported,applied,unsupported}`. `applied`
+contains only fields accepted during that call, including rounded channels or
+`null` for a successful default reset. `supported` is true when at least one
+field applied; `unsupported` lists requested fields the platform could not
+apply. These results report platform acceptance rather than measured pixels.
+An invalid argument uses `INVALID_ARGUMENT`; a platform API failure uses
+`ARCANE_WINDOW_THEME_FAILED`, preserving complete native details and any
+earlier changes in `error.details.applied` and `error.details.unsupported`.
+The call is not atomic across fields. Existing request cancellation and document
+lifetime semantics remain in effect; an already accepted native color change
+is not rolled back by later cancellation. See [the Core client](core-client.md)
+for the facade and browser behavior.
+
+### Launch configuration
+
 For explicit user-selected workspace/state locations, launch:
 
 ```sh
@@ -331,8 +395,8 @@ exit. It does not kill the child on an ordinary close.
 `ArcaneHost.cs` composes that process with a WebView2 window through
 `ArcaneHost.Run(options,onDiagnostic,onError)` or `ArcaneHostForm`. Options
 select the app root/start path, stable virtual HTTPS origin, profile directory,
-title, canonical classic-client source and Core process inputs. The form exposes
-`Ready`, `Completion` and `CloseAsync()`. Page navigation, transport connection,
+title, optional `IconPath`, canonical classic-client source and Core process
+inputs. The form exposes `Ready`, `Completion` and `CloseAsync()`. Page navigation, transport connection,
 Core readiness and service readiness are separate states. Accepted work drains
 before the window closes; complete engineering errors go to the supplied
 diagnostic/error callbacks. Callbacks must not synchronously wait for the

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

@@ -3898,7 +3898,7 @@
       "summary": "Projects a Core client into the established application-facing Arcane namespace.",
       "availability": "Browser and native WebView JavaScript hosts with a Core client",
       "protocol": "arcane/1 compatibility facade",
-      "normalization": "Routes existing namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation"
+      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance"
     },
     {
       "id": "core-client:installCoreClient",
@@ -4052,7 +4052,7 @@
       "summary": "Assembles selected application services and browser content with the SDK-owned Windows x64 WebView2 and SEA host.",
       "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
       "protocol": "arcane-native-builder/1 windows-x64 provider",
-      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; run cancellation closes stdin and waits for host-owned graceful shutdown"
+      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; native.icon PNG/ICO derives the copied executable and host.icon without an app compiler, while other formats retain assembly with native.icon.unsupported and executableIcon:false; the matching host loads the selected window/taskbar icon and handles window.setTheme with per-field applied/unsupported results; run cancellation closes stdin and waits for host-owned graceful shutdown"
     },
     {
       "id": "native-windows-provider:arcaneNativeBuilderProvider",

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

@@ -30,7 +30,7 @@
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
       "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Whisper STT and Kokoro TTS execution with default capacities 1 and 4 respectively, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, automatic repeated-formatting-mark removal from cloned outbound TTS input while caller and visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing, independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned. Both speech roles default execution.device to auto: webnn-npu when navigator.ml.createContext is exposed, then webgpu when navigator.gpu is exposed, then wasm for CPU execution. Failed backend loads clean up the pool before trying fresh Workers with the same prepared model and dtype; explicit devices never fall back. STT capacity only accepts 1; TTS accepts 1 through 4. Execution snapshots expose requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount for both roles; selectedDevice is null while unloaded and names the successful upstream session backend request when loaded. It does not prove every operation used the physical NPU: WebNN unsupported operations may use WASM, and compatibility depends on the browser, driver, hardware, and graph.",
-      "surface": "prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; automatic speech-input cleanup with SDK-internal preparation metadata; `prepareTTS({parts,storage,identity,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `playPreparedTTS(prepared,{signal,onState})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
+      "surface": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; automatic speech-input cleanup with SDK-internal preparation metadata; `prepareTTS({parts,storage,identity,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `playPreparedTTS(prepared,{signal,onState})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
     },
     {
       "file": "runtime/arcane/modules/AIModelSelectionController.js",
@@ -1364,7 +1364,7 @@
       "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. 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."
+      "surface": "`bootstrapArcaneTheme()`, `disposeArcaneThemeBootstrap()`, `arcaneThemeReady`, and default ready promise. Shared bootstrap replays an already-ready User. In native hosts it independently forwards computed --background/--text-color through Arcane.window.setTheme, observing shared theme events, root/body presentation attributes, stylesheets, device scheme and page restoration; browser CSS resolution retains alpha and converts modern colors to sRGB. Disposal releases appearance/user/theme subscriptions, native sampling observers and listeners, and pending window requests. Ordinary browsers remain silent. Presentation cache is nonauthoritative; use classic ThemePresentation after app-id and before CSS for early restoration."
     },
     {
       "file": "runtime/arcane/modules/ThemeManager.js",

package/docs/reference/local-image-editing.md

@@ -0,0 +1,79 @@
+# Local image edit inputs
+
+The SDK input decoder prepares a PNG raster for the shared native image
+runtime. Decoding does not load a model or perform inference. The runtime owns
+model selection, supported editing operations, native calls and their complete
+results. Applications retain the original image and decide whether to save a
+newly generated result.
+
+## Decoder contract
+
+`src/local-ai/image-editing.mjs` exports the internal worker function
+`decodeImage({data, mediaType, signal})`.
+
+| Field | Contract |
+| --- | --- |
+| `data` | Complete encoded PNG in a `Uint8Array`; a Node `Buffer` is also accepted. Only the supplied view is read. |
+| `mediaType` | `image/png`, an empty string, or omitted. The PNG signature is read from the actual input. Other declared formats report unsupported input. |
+| `signal` | Optional `AbortSignal` belonging to the image request. |
+
+The promise returns `{width, height, channel, data}`. Dimensions come from the
+source raster; `channel` is `3` for RGB or `4` for RGBA. Returned `data` is a
+separate contiguous `Uint8Array` containing interleaved samples, with pixels
+ordered left to right and rows ordered top to bottom. The native request owner
+retains this allocation until the native operation actually completes,
+including after a cancellation request.
+
+Input decoding accepts static, non-interlaced, 8-bit RGB and RGBA PNGs, all
+five PNG row filters, and image data spread across multiple `IDAT` chunks.
+RGB transparent-color information is represented as RGBA. An optional suggested
+palette on an RGB or RGBA image does not change its color type.
+
+Indexed-color, grayscale, 16-bit, interlaced and animated PNGs currently report
+unsupported input. JPEG and WebP are also unsupported by this decoder. The
+decoder does not silently convert those formats or select one animation frame.
+
+The original encoded image is copied for the operation and never modified or
+detached. Decoding preserves stored color samples and straight alpha, including
+RGB values underneath transparent pixels. It does not composite onto a chosen
+background, rotate pixels from metadata, apply a color-profile conversion,
+resize, crop or create a file. Metadata remains in the original image; the
+native raster record contains pixels and dimensions only.
+
+## Execution and cancellation
+
+Invoke the decoder inside the shared image runtime's existing worker.
+Inflation uses asynchronous Node zlib. Row reconstruction yields between
+scanlines so the worker can receive cancellation. An abort during inflation is
+observed after that native operation settles; it does not claim instant
+interruption. A cancelled decode returns no raster for inference.
+
+`ARCANE_IMAGE_INPUT_UNSUPPORTED` describes an unavailable input format or
+encoding. `ARCANE_IMAGE_DECODE_FAILED` describes unreadable PNG structure or
+scanlines. Node zlib failures retain their complete original errors, and
+cancellation retains the owning signal's reason or Node `AbortError`. A decode
+failure never returns partial imagery or substitutes a different image.
+
+## Editing semantics at the native owner
+
+Whole-image img2img uses an initial image, prompt and strength. Masked editing
+adds a separate mask; instruction/reference editing uses a model that supports
+reference conditioning. These are distinct operations and must be advertised
+only when the selected model and native path implement them. Ordinary img2img
+does not require LoRA training. The candidate engine documents this directly
+with its base SD1.4 model in the
+[tagged img2img example](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/docs/sd.md#img2img-example).
+
+Source dimensions are decoder output, not an implicit request to change the
+generation dimensions. The model owner documents its actual canvas adaptation
+and reports actual output dimensions. In the candidate engine, temporary
+initial images use model preprocessing while caller images remain unchanged;
+even `mode=none` does not suppress all later model adaptation. See the
+[native preprocessing contract](https://github.com/leejet/stable-diffusion.cpp/blob/master-929-3f8527a/docs/image_preprocessing.md).
+
+An RGB-only model such as the selected SD1.4 candidate consumes the stored RGB
+and does not preserve alpha. The SDK must not silently choose a compositing
+background or claim that passing RGBA preserves its displayed appearance.
+Strength zero is also not an exact-copy operation: native img2img still uses
+the model's encode, sampling and decode path. These model behaviors are
+separate from the decoder preserving the original input.

package/docs/reference/local-image-generation.md

@@ -0,0 +1,267 @@
+# Local image generation through Core
+
+The SDK's local image service runs selected stable-diffusion.cpp models in a
+retained native context. The browser uses Core for model lifecycle and complete
+PNG results. Applications own image prompts, style choices, character identity,
+associations and saved results.
+
+Runtime installation, model asset preparation, model loading and image
+generation are separate operations. The service starts promptly and retains
+runtime preparation in the background. `image.status` remains callable during
+preparation; rendering and unrelated Core services continue independently.
+
+## Selection and model assets
+
+Select the runtime in `arcane-app.json` under `native.localAI`, or in the
+corresponding package projection's `localAI` record:
+
+```json
+{
+    "runtimes": [
+        {
+            "id": "stable-diffusion.cpp",
+            "version": "master-929-3f8527a",
+            "backend": "auto",
+            "models": ["sd14"]
+        }
+    ]
+}
+```
+
+`sd14` selects the Stable Diffusion 1.4 definition and its official
+`sd-v1-4.ckpt` resource. A model definition contains `id`, `name`, `family`,
+`resources`, `context`, `defaults` and `operations`. Selection supplies the
+model's resource metadata; runtime installation does not independently download
+or bundle model files. The shared model asset owner prepares selected browser
+assets and supplies a Core working projection for native path-based loading.
+
+The first published distribution path selects CPU on Windows and Linux.
+On macOS, `auto` selects the same upstream universal runtime's built-in Metal
+backend, with CPU fallback; explicit `cpu` remains available. A caller-supplied
+runtime archive with `backend: 'auto'` uses its available accelerated device
+with CPU fallback. Built-in Windows CUDA distribution preparation is a separate
+pending addition. Actual backend/device availability and failures
+come from the runtime, separately from hardware metadata or an installed archive.
+Cancellation, invalid model input and inference failures retain their actual
+errors. Model loading has no native cancellation handle before its constructor
+returns; cancellation joins that call and releases its returned context before
+the operation settles.
+
+The complete prepared projection has an `id`, a `directory`, a `members` list
+and `release()`. `resourcePaths` maps native model resource roles to exact
+projection member paths. For the selected checkpoint, the role is `model`.
+The member name must match the preparation result. See
+[Model assets through Core](model-assets.md) for the shared preparation
+lifecycle. Core acquires its own
+retain before loading. The caller can release its preparation ownership after
+successful `load()` acknowledgement: Core retains the files while its native
+context needs them. Release caller ownership when loading fails too; native
+cleanup keeps its own retain through actual completion. A later
+`generate({model: 'sd14', ...})` reuses that prepared selection. Replacing or
+unloading the context releases displaced projections
+after actual native operations settle. Core shutdown joins owned operations
+before releasing retained model files.
+
+`model` also accepts a complete prepared model descriptor. Native callers can
+supply actual resource paths directly. The browser projection arguments supply
+the native paths through the shared asset service and preserve the remaining
+descriptor fields. The image service creates no second model downloader or
+durable model store.
+
+## Browser accessor
+
+```js
+import {createCoreImageRuntime} from 'arcane-os/ai/core-image';
+import {prepareCoreModelAssets} from 'arcane-os/ai/core-model-assets';
+import {createBrowserModelSource, createDbopfsModelStore} from 'arcane-os/ai/browser-wasm';
+
+const page = new AbortController();
+window.addEventListener(
+    'pagehide',
+    function detachImagePage() {
+        page.abort();
+    },
+    {once: true}
+);
+
+const images = createCoreImageRuntime(
+    {signal: page.signal}
+);
+
+images.subscribe(
+    function showImageStatus(snapshot) {
+        statusElement.textContent = snapshot.status ?? snapshot.state;
+    }
+);
+
+const selected = (await images.inspect()).models.find(
+    function selectedCheckpoint(model) {
+        return model.id === 'sd14';
+    }
+);
+const resource = selected.resources.model;
+const source = createBrowserModelSource(
+    {
+        id: selected.id,
+        files: [
+            {name: resource.filename, url: resource.url}
+        ]
+    }
+);
+const store = createDbopfsModelStore(
+    {dbopfs, downloadConcurrency: 4}
+);
+const stored = await store.ensure(
+    source,
+    {signal: page.signal, offline: false}
+);
+const projection = await prepareCoreModelAssets(
+    {
+        workingDirectory: '.arcane/model-working',
+        members: source.files.map(
+            function preparedCheckpoint(member, index) {
+                return {path: member.name, file: stored.files[index]};
+            }
+        ),
+        signal: page.signal
+    }
+);
+
+try {
+    await images.load(
+        {
+            model: 'sd14',
+            assetProjectionId: projection.id,
+            resourcePaths: {
+                model: 'sd-v1-4.ckpt'
+            },
+            signal: page.signal
+        }
+    );
+} finally {
+    await projection.release();
+}
+
+const result = await images.generate(
+    {
+        model: 'sd14',
+        prompt: 'Portrait of a dignified raccoon astronaut holding a tiny moon cactus.',
+        signal: page.signal,
+        onProgress(progress) {
+            console.log(progress);
+        }
+    }
+);
+
+for (const image of result.images) {
+    const url = URL.createObjectURL(image.blob);
+    const preview = new Image();
+    preview.alt = 'Generated raccoon astronaut portrait';
+    function releasePreviewURL() {
+        URL.revokeObjectURL(url);
+    }
+    preview.addEventListener(
+        'load',
+        releasePreviewURL,
+        {once: true}
+    );
+    preview.addEventListener(
+        'error',
+        releasePreviewURL,
+        {once: true}
+    );
+    preview.src = url;
+    imageContainer.append(preview);
+}
+```
+
+The example uses the application's existing `dbopfs` instance and existing
+`statusElement` and `imageContainer` elements. The published model store accepts
+the selected checkpoint as an ordinary resource: `ensure()` returns complete
+ordered `Blob` or `File` members after its resumable download. Range support
+allows concurrent transfer within a member; those transfer parts remain the
+store's concern. Use `offline: true` to require an already complete stored model.
+The store does not select or run the image engine. In source development,
+load the development Core bootstrap described
+in [Local AI through Core](local-ai.md#development) before constructing the
+accessor. Native hosts install their Core client through the existing host path.
+An ordinary browser without Core reports local image generation as unavailable.
+
+| Member | Contract |
+|---|---|
+| `createCoreImageRuntime({client?, signal?, onEvent?})` | Uses the installed Core client by default, subscribes to lifecycle events and asynchronously reads one initial status snapshot. It returns immediately. |
+| `load({model, context?, assetProjectionId?, resourcePaths?, signal?})` | Loads the selected model and returns authoritative service state after native completion. `context` supplies native context options. |
+| `generate({model, prompt, parameters?, assetProjectionId?, resourcePaths?, signal?, onProgress?})` | Returns the complete result with `images: [{blob, mediaType, width, height}]`. Additional runtime result metadata remains present. |
+| `unload({signal?})` | Explicitly unloads the shared selected native context and returns its resulting state. |
+| `inspect({signal?})` | Reads current Core status without waiting for model or runtime preparation. |
+| `current()` | Synchronously returns the retained lifecycle snapshot and this accessor's transient request status. |
+| `subscribe(listener, {replay = true, signal?})` | Observes `image.state` and immediately replays the current snapshot by default; returns an unsubscribe function. |
+| `close()` | Cancels this accessor's requests, removes subscriptions and joins its request promises. It leaves the shared Core client and selected model under their existing owners. |
+
+Generation publishes `status: 'Thinking'` synchronously when accepted, before
+transport, preparation, model loading or inference waits. This remains transient
+status until the complete image result arrives. Native sampling progress is
+reported as progress, with no fabricated image chunks or conversation turns.
+The accessor's `requests` records contain method, stream ID, status and progress;
+they contain no saved prompt or image history.
+
+The authoritative lifecycle snapshot includes `selectedModel`, `loaded`,
+`state`, `backend`, `progress`, `error`, native resource paths and device state.
+Service metadata adds runtime `id`, installation/availability state and selected
+model definitions, including their resource metadata before engine preparation
+finishes. Installed files do not imply a loaded model. A late status
+response never overwrites a newer lifecycle event.
+
+Prompts and parameters pass unchanged to the native runtime. Native option
+names, supported model operations and defaults belong to that runtime and the
+selected model definition. A prompt containing U+0000 or an unpaired UTF-16
+surrogate cannot pass unchanged through the native UTF-8 C-string boundary and
+reports that incompatibility.
+
+The request signal propagates through Core to the owning native operation.
+Aborted requests produce no late image result or progress callback. Request
+invocations use `timeoutMs: 0`; there is no arbitrary image-generation timeout.
+Errors retain their actual details on rejected promises and diagnostic events.
+Applications choose concise ordinary status text and keep complete engineering
+details in their diagnostic surface, outside durable chat history.
+
+`onEvent` observes `image.state`, `image.progress`, `image.request`,
+`image.result` and `image.error` records. Observer failures are reported to the
+developer console and do not replace inference results. Observers own their
+asynchronous callback lifetimes. The SDK persists no prompt, result, transcript
+or application-owned image association.
+
+## Core service and transport
+
+`createLocalImageService(configuration, options)` is exported from
+`arcane-os/core/image`. `configuration` is the selected `localAI` record.
+Options are `appRoot`, installed `runtimes`, `signal`, `onEvent`, an optional
+`prepare` callback and the existing `modelAssets` service instance.
+
+`prepare({appRoot, configuration, requirement, signal, onEvent})` returns one
+installed runtime record. Preparation runs once per service. That record carries
+`libraryPath`, `bindingModulePath`, `backend`, `variants` and model definitions.
+Runtime variants preserve their native backend, library path and runtime root.
+The service retains one native runtime and subscribes to its current-state
+replay. Expensive model execution belongs to that runtime's worker.
+
+| Method/event | Parameters or result |
+|---|---|
+| `image.status` | Immediate lifecycle snapshot. |
+| `image.load` | `{model, context?, assetProjectionId?, resourcePaths?}`; returns lifecycle snapshot. |
+| `image.generate` | `{model, prompt, parameters?, streamId?, assetProjectionId?, resourcePaths?}`; returns complete encoded images. |
+| `image.unload` | Empty parameters; returns lifecycle snapshot after unload. |
+| `image.state` | Complete service lifecycle snapshot. Service and browser `subscribe()` provide current-state replay. |
+| `image.progress` | `{streamId, requestId, status: 'Thinking', progress}` for the corresponding generation request. |
+
+Core's JSON transport represents each complete PNG as
+`{data, encoding: 'base64', mediaType: 'image/png', width, height}`. The browser
+decodes that complete representation into a `Blob` and preserves its metadata.
+There is no result resizing, clipping, storage write or application policy at
+this transport boundary.
+
+One service prepares one selected runtime, retains one selected native context
+and performs one native generation per request. The native owner serializes
+only competing operations on that context. Independent Core services and page
+rendering remain concurrent. Native platform execution evidence and package
+publication are separate from this source/API description.