arcane-os 0.61.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.63.0
+
+- Add the approved FLUX.2 Klein 4B text-to-image model descriptor to the
+  existing retained local image runtime, with its separate diffusion, VAE
+  and text-encoder resources and four-step Euler defaults. Applications keep
+  their model choice, complete prompts and image persistence.
+- Name assembled Windows launchers from the application display name, with a
+  matching executable configuration and manifest-selected launch path.
+  Preserve supported spaces, case and Unicode, existing generic artifacts,
+  icon embedding and the unchanged shared host archive.
+- Add `createSpeechService({stt, tts, signal})` through `arcane-os/core/speech`
+  for independently supplied native engines, immediate service registration,
+  sticky role state, complete requests/results, cancellation and joined close.
+  This service does not install or select a speech engine.
+- Preserve existing image generation/editing and native host behavior. No
+  additional GPU setup, SDXL, Whisper engine, Kokoro/Sherpa adoption or browser
+  AI native-speech readiness correction is included in this increment.
+
+## 0.62.0
+
+- Add whole-image PNG editing through the existing local image runtime, Core
+  service and browser accessor: `edit({model, image, prompt, strength, ...})`
+  and `image.edit` share the retained generation context and lifecycle.
+- Preserve complete original PNG input and prompts through lossless transport,
+  copy queued native input, and pass explicit finite strength without clamping.
+  Return a separate complete PNG result; applications own persistence.
+- Preserve synchronous Thinking, progress, ordered context work, cancellation,
+  unload and close. SD1.4 now advertises `img2img` beside `txt2img`.
+- Support static non-interlaced 8-bit RGB/RGBA PNG input using the existing
+  worker decoder. Unsupported formats report their actual limitation; model
+  cropping, resizing and alpha behavior remain explicit in the editing guide.
+- Reuse the approved runtime and model workflow with no dependency change.
+  This increment does not add masks, reference editing, new models or GPU
+  installation, and does not claim exact visual instruction adherence.
+
 ## 0.61.0
 
 - Add retained local image generation through Core, with public native runtime,

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.61.0` SDK contract. Development applications declare
+This checkout defines the `0.63.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;

package/browser-runtime/ai/core-image.mjs

@@ -30,6 +30,24 @@ function decodeImage(image) {
     return {...metadata, blob};
 }
 
+/** Preserve the complete encoded input at the JSON transport boundary. */
+async function encodeImage(image, signal) {
+    if (!(image instanceof Blob)) {
+        throw new TypeError('Image editing requires the original PNG Blob or File.');
+    }
+    const content = new Uint8Array(await image.arrayBuffer());
+    signal.throwIfAborted();
+    let data;
+    if (is.function(content.toBase64)) {
+        data = content.toBase64();
+    } else {
+        let binary = '';
+        for (const value of content) binary += String.fromCharCode(value);
+        data = globalThis.btoa(binary);
+    }
+    return {data, encoding: 'base64', mediaType: image.type};
+}
+
 /** Browser access to the selected native image service; no result persistence. */
 export function createCoreImageRuntime(
     {client = getInstalledCoreClient(), signal, onEvent} = {}
@@ -145,7 +163,7 @@ export function createCoreImageRuntime(
             method,
             revision,
             streamId: parameters.streamId,
-            status: method === 'image.generate' ? 'Thinking' : null,
+            status: method === 'image.generate' || method === 'image.edit' ? 'Thinking' : null,
             progress: null,
             task: null
         };
@@ -176,18 +194,21 @@ export function createCoreImageRuntime(
         request.task = Promise.resolve().then(
             async function executeImageRequest() {
                 operationSignal.throwIfAborted();
+                const requestParameters = method === 'image.edit'
+                    ? {...parameters, image: await encodeImage(parameters.image, operationSignal)} : parameters;
+                operationSignal.throwIfAborted();
                 observe(
                     onEvent,
-                    {type: 'image.request', data: {method, parameters}}
+                    {type: 'image.request', data: {method, parameters: requestParameters}}
                 );
                 operationSignal.throwIfAborted();
                 const result = await client.invoke(
                     method,
-                    parameters,
+                    requestParameters,
                     {signal: operationSignal, timeoutMs: 0}
                 );
                 operationSignal.throwIfAborted();
-                if (method === 'image.generate') {
+                if (method === 'image.generate' || method === 'image.edit') {
                     const images = result.images.map(decodeImage);
                     operationSignal.throwIfAborted();
                     const decoded = {...result, images};
@@ -274,6 +295,17 @@ export function createCoreImageRuntime(
         );
     }
 
+    function edit(
+        {model, image, prompt, strength, parameters, assetProjectionId, resourcePaths, signal: requestSignal, onProgress} = {}
+    ) {
+        const streamId = client?.uuid?.() ?? globalThis.crypto.randomUUID();
+        return invoke(
+            'image.edit',
+            {model, image, prompt, strength, parameters, streamId, assetProjectionId, resourcePaths},
+            {signal: requestSignal, onProgress}
+        );
+    }
+
     async function unload({signal: requestSignal} = {}) {
         const before = revision;
         const result = await invoke(
@@ -356,5 +388,5 @@ export function createCoreImageRuntime(
         );
     }
 
-    return {load, generate, unload, inspect, current, subscribe, close};
+    return {load, generate, edit, unload, inspect, current, subscribe, close};
 }

package/docs/reference/README.md

@@ -55,6 +55,9 @@ alone does not make bare module names resolve in a browser.
 | Cancel one Core speech synthesis request without changing its payload | [Speech request lifetime](core-client.md#events-and-request-lifetime) and [Core facade](sdk-api.md#createcorefacade) |
 | Compose native Core dispatch, service lifecycle, and stdio hosting | [Native Core runtime](core-runtime.md) |
 | Run application-selected llama.cpp, Ollama or ONNX through Core | [Local AI through Core](local-ai.md) |
+| Generate complete local PNG images with a retained native model | [Local image generation](local-image-generation.md) |
+| Edit an original PNG with a complete prompt and explicit strength | [Local image editing](local-image-editing.md) |
+| Project complete stored model files into native working files | [Model assets through Core](model-assets.md) |
 | Retain a Nemotron model and diarize caller-fed audio streams | [Native speaker diarization](diarization.md) |
 | Persist application-selected preferences through Core | [Core preferences service](core-preferences.md) |
 | Read complete selected Git text without changing a checkout | [Git text snapshots](git-text-snapshot.md) |
@@ -223,6 +226,8 @@ Ollama, Wllama, Whisper, Kokoro, native, or cloud transport:
 | Run a caller-selected GGUF LLM locally | [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) | Browser secure context with WebAssembly and OPFS/DBOPFS; explicit CPU selection or WebGPU with full offload and no automatic CPU fallback. |
 | Run application-selected native llama.cpp/Ollama chat | [`arcane-os/ai/core-local`, `arcane-os/core/local-ai`](local-ai.md) | Explicit Core connection and selected native runtimes; installation, availability and loaded-model readiness remain distinct. |
 | Run a local ONNX graph with named tensors | [`arcane-os/local-ai/onnx`, `arcane-os/ai/core-onnx`](local-ai.md#native-onnx-sessions) | Retained native workers; browser access requires an available Core ONNX service. |
+| Generate local images from complete prompts and selected model resources | [`arcane-os/local-ai/image`, `arcane-os/ai/core-image`](local-image-generation.md) | Prepared native image runtime; browser access requires its Core service. CPU Windows/Linux and Mac Metal/CPU paths have distinct actual host requirements. |
+| Supply complete stored model members to a native engine | [`arcane-os/ai/core-model-assets`, `arcane-os/core/model-assets`](model-assets.md) | Available Core service; DBOPFS originals stay authoritative while native owners retain working files. |
 | Run caller-selected Whisper/Kokoro locally | [`arcane-os/ai/browser-speech`](ai/browser-speech.md) | Browser with DBOPFS, Web Locks, Workers and selected upstream sources; automatic WebNN NPU, WebGPU, then WASM loading, or an explicit backend. |
 | Use native browser recognition/voices or selected cloud TTS | [Speech provider choices](ai/browser-speech.md) | Native APIs depend on the browser and may use remote services; cloud TTS requires the application key and endpoint access. |
 | Send complete chat, System One or image requests without retained history | [`arcane-os/ai/twin-cloud`](ai/twin-cloud.md) | Node or browser with Fetch and explicit model/credentials; image results contain every returned image as a Blob. |

package/docs/reference/cli.md

@@ -49,7 +49,7 @@ meaning and cardinality rules:
 | `--app` | app id or label | Workspace/app operations except shared scope and `verify-bundle`; optional diagnostic label for `mail serve`. |
 | `--apps-root` | `.` or `apps` | `new`, `init`; standalone setup defaults to the repository root. |
 | `--sdk-runtime-source` | SDK checkout directory | `dev` only; maps live SDK source through the selected browser destinations for that server process. |
-| `--local-ai` | comma-separated runtime IDs | `dev` only; adds `llama.cpp`, `ollama` and/or `onnx` requirements to application configuration and prepares missing runtimes alongside serving. See [local AI through Core](local-ai.md). |
+| `--local-ai` | comma-separated runtime IDs | `dev` only; adds `llama.cpp`, `ollama`, `onnx` and/or `stable-diffusion.cpp` requirements to application configuration and prepares missing runtimes alongside serving. See [local AI through Core](local-ai.md). |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
 | `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTPS with HTTP/2 at `0.0.0.0:4433` and accepts an explicit bind host. |
 | `--http-port` | integer 0–65535 | Browser `dev`/`run` HTTP redirect listener; defaults to `0`, which selects an available port. |
@@ -375,6 +375,10 @@ arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file
 reuse them. Available services and executables are reused; missing runtimes
 are installed inside the application while serving starts independently.
 Applications choose their model files and optional browser Core connection.
+`--local-ai stable-diffusion.cpp` prepares the selected native image runtime;
+configure its `models` separately in the application's runtime record.
+The [image service](local-image-generation.md) reports installation and model
+readiness independently, with complete PNG results and explicit cancellation.
 See [local AI through Core](local-ai.md) for configuration and native bundling.
 
 ### Lifecycle

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

@@ -248,8 +248,9 @@ to the artifact root. Only the explicitly configured entry imports
 `createLocalAIService` from `arcane-os/core/local-ai`. It resolves those bundled
 locations against the installed artifact and supplies them in the launch
 context's `runtimes` array, alongside `appRoot`, before applying explicit launch
-configuration. It passes the complete authored `native.localAI` record to the
-factory. Applications without that selection have no generated local-AI import
+configuration. It passes chat/ONNX requirements to that factory and routes
+selected image requirements to their separate service as described below.
+Applications without that selection have no generated local-AI import
 or service. Availability of a particular engine belongs to the selected
 local-AI installer and service; a generic ONNX runtime is not a speech model.
 
@@ -260,6 +261,25 @@ service exposes retained worker sessions through `onnx.load/run/unload/status`;
 model files remain caller-selected application resources. See
 [native ONNX sessions](local-ai.md#native-onnx-sessions).
 
+Selected `stable-diffusion.cpp` additionally composes
+`createLocalImageService` from `arcane-os/core/image` and one shared
+`createModelAssetService` from `arcane-os/core/model-assets`. The image factory
+receives the full authored selection plus that same model-assets instance.
+Library, Koffi binding and variant paths resolve from the artifact root;
+ordinary browser imports use `arcane-os/ai/core-image` and
+`arcane-os/ai/core-model-assets` through the managed import map.
+
+The runtime bundle preserves the complete selected native distribution and
+binding tree. It does not load or download a model. Original model URL
+descriptors remain available for preparation after launch; runtime-contained
+model paths relocate with the artifact. An external native working path
+reports its portability incompatibility. Supply those files through the
+application's native resources or the shared
+[stored-model projection](model-assets.md). Native use retains that projection
+until actual unload or shutdown completes. See
+[local image generation](local-image-generation.md) for selection, complete
+results and CPU/Metal platform boundaries.
+
 ## Windows executable
 
 The ordinary application command is:

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

@@ -1,17 +1,115 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.57.0",
+  "sdkVersion": "0.62.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 267,
+  "memberCount": 274,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
   },
   "members": [
+    {
+      "id": "local-ai-image:createImageRuntime",
+      "name": "createImageRuntime",
+      "displayName": "createImageRuntime()",
+      "kind": "function",
+      "signature": "createImageRuntime({libraryPath,bindingModulePath,variants=[],models=[],backend='auto',signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai/image"],
+      "primaryImport": "arcane-os/local-ai/image",
+      "group": "Core local images",
+      "summary": "Retains selected stable-diffusion.cpp generation and PNG img2img execution in a shared native worker and returns complete PNG results.",
+      "availability": "Node with prepared upstream image library, Koffi binding and caller-selected model resources",
+      "protocol": "Shared per-library worker/context lifetime with ordered native operations and replaying state",
+      "normalization": "Returns load/generate/edit/unload/current/subscribe/close; edit copies complete PNG input at acceptance and takes explicit strength; prompts remain complete and cancellation/close join native completion before resource release"
+    },
+    {
+      "id": "core-image:createCoreImageRuntime",
+      "name": "createCoreImageRuntime",
+      "displayName": "createCoreImageRuntime()",
+      "kind": "function",
+      "signature": "createCoreImageRuntime({client=getInstalledCoreClient(),signal,onEvent}={})",
+      "entrypoints": ["arcane-os/ai/core-image"],
+      "primaryImport": "arcane-os/ai/core-image",
+      "group": "Core local images",
+      "summary": "Uses an available Core image service for generation and original-PNG editing with synchronous Thinking acknowledgement, lifecycle replay and complete PNG Blobs.",
+      "availability": "Browser/native WebView with an available Core image service; construction opens no connection or model",
+      "protocol": "arcane/1 image.status/load/generate/edit/unload and image.state/progress",
+      "normalization": "Returns load/generate/edit/unload/inspect/current/subscribe/close; edit preserves the complete original PNG Blob/File through transport with explicit strength; timeoutMs is zero, close cancels only this accessor and explicit unload owns the shared model"
+    },
+    {
+      "id": "core-image-service:createLocalImageService",
+      "name": "createLocalImageService",
+      "displayName": "createLocalImageService()",
+      "kind": "function",
+      "signature": "createLocalImageService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare,modelAssets}={})",
+      "entrypoints": ["arcane-os/core/image"],
+      "primaryImport": "arcane-os/core/image",
+      "group": "Core local images",
+      "summary": "Composes independent image-runtime preparation, retained native model use and complete PNG transport as a Core service.",
+      "availability": "Node Core with selected stable-diffusion.cpp configuration and prepared runtime or preparation callback",
+      "protocol": "arcane/1 image lifecycle, generate/edit and progress; base64 framing only at complete PNG input/result transport boundaries",
+      "normalization": "Status remains callable during preparation; shared model-assets handles remain retained through actual model unload, worker completion and disposal"
+    },
+    {
+      "id": "core-image-service:default",
+      "name": "default",
+      "displayName": "createLocalImageService default export",
+      "kind": "function",
+      "signature": "default as createLocalImageService",
+      "entrypoints": ["arcane-os/core/image"],
+      "primaryImport": "arcane-os/core/image",
+      "group": "Core local images",
+      "summary": "Default binding for the same native image service factory.",
+      "availability": "Node Core runtime",
+      "protocol": "arcane/1 service definition",
+      "normalization": "Binding identity equals the named createLocalImageService export"
+    },
+    {
+      "id": "core-model-assets:prepareCoreModelAssets",
+      "name": "prepareCoreModelAssets",
+      "displayName": "prepareCoreModelAssets()",
+      "kind": "function",
+      "signature": "async prepareCoreModelAssets({client=getInstalledCoreClient(),workingDirectory,members,signal,onProgress}={})",
+      "entrypoints": ["arcane-os/ai/core-model-assets"],
+      "primaryImport": "arcane-os/ai/core-model-assets",
+      "group": "Core model assets",
+      "summary": "Projects complete caller-owned Blob/File members through Core into native working files without changing their durable store.",
+      "availability": "Browser with an available model-assets Core service and complete selected members",
+      "protocol": "arcane/1 modelAssets open/write/complete/release operations with transport-local base64",
+      "normalization": "Returns id/directory/ordered members/release; independent files transfer concurrently, each file writes in order, and cancellation joins cleanup"
+    },
+    {
+      "id": "core-model-assets-service:createModelAssetService",
+      "name": "createModelAssetService",
+      "displayName": "createModelAssetService()",
+      "kind": "function",
+      "signature": "createModelAssetService({appRoot=process.cwd()}={})",
+      "entrypoints": ["arcane-os/core/model-assets"],
+      "primaryImport": "arcane-os/core/model-assets",
+      "group": "Core model assets",
+      "summary": "Owns selected native working-file projections and engine retain handles while original stored model files remain unchanged.",
+      "availability": "Node Core with an application-selected working directory",
+      "protocol": "arcane/1 modelAssets.open/write/complete/release/status and modelAssets.state",
+      "normalization": "Returns current/retain/dispose and Core service lifecycle; final native release joins writes and closes before deleting only its working projection"
+    },
+    {
+      "id": "core-model-assets-service:default",
+      "name": "default",
+      "displayName": "createModelAssetService default export",
+      "kind": "function",
+      "signature": "default as createModelAssetService",
+      "entrypoints": ["arcane-os/core/model-assets"],
+      "primaryImport": "arcane-os/core/model-assets",
+      "group": "Core model assets",
+      "summary": "Default binding for the same native working-file service factory.",
+      "availability": "Node Core runtime",
+      "protocol": "arcane/1 service definition",
+      "normalization": "Binding identity equals the named createModelAssetService export"
+    },
     {
       "id": "local-ai-onnx:createONNXRuntime",
       "name": "createONNXRuntime",
@@ -129,14 +227,14 @@
       "name": "createLocalAIService",
       "displayName": "createLocalAIService()",
       "kind": "function",
-      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent}={})",
+      "signature": "createLocalAIService(configuration,{appRoot,runtimes=[],signal,onEvent,prepare}={})",
       "entrypoints": ["arcane-os/core/local-ai"],
       "primaryImport": "arcane-os/core/local-ai",
       "group": "Core local AI",
       "summary": "Composes selected native llama.cpp, Ollama and ONNX engines as a Core service with retained process/worker ownership and model lifecycle.",
       "availability": "Node with selected upstream runtime distributions or available configured system services",
       "protocol": "arcane/1 methods and events; llama.cpp OpenAI HTTP/SSE, Ollama native HTTP/NDJSON and ONNX tensor transport",
-      "normalization": "Application-owned runtime and model requirements; independent startup, complete responses and exact owned-process cleanup"
+      "normalization": "Application-owned runtime and model requirements; optional prepare supplies installed records during this service startup; independent services, complete responses and exact owned-process cleanup"
     },
     {
       "id": "core-local-ai:default",
@@ -161,10 +259,10 @@
       "entrypoints": ["arcane-os/local-ai"],
       "primaryImport": "arcane-os/local-ai",
       "group": "Core local AI",
-      "summary": "Reuses selected managed native runtimes or installs complete official llama.cpp/Ollama distributions, ONNX npm runtime trees or NeMo libraries.",
+      "summary": "Reuses selected managed native runtimes or installs complete official llama.cpp/Ollama/image distributions, ONNX npm runtime trees or NeMo libraries.",
       "availability": "Node; upstream platform and architecture assets determine runtime availability",
-      "protocol": "Official upstream release archives or selected ONNX npm installation",
-      "normalization": "Returns absolute runtime records; shares matching concurrent installs, preserves libraries and reports failures without changing global PATH or services"
+      "protocol": "Official upstream release archives and selected ONNX/Koffi npm runtime installations",
+      "normalization": "Returns absolute runtime records, including image library/binding/variant/model metadata; shares matching installs, preserves libraries, reports failures without changing global PATH or services and prepares no model files"
     },
     {
       "id": "local-ai:bundleLocalAIRuntimes",
@@ -178,7 +276,7 @@
       "summary": "Copies selected complete runtime distributions into a fresh native artifact staging root.",
       "availability": "Node; supports bundling published upstream platform assets independently of the build host",
       "protocol": "Artifact-relative runtime/local-ai layout",
-      "normalization": "Returns {runtimes,files} with relative runtime records and the complete emitted inventory; model resources remain application-owned"
+      "normalization": "Returns {runtimes,files} with artifact-relative runtime/variant paths and complete inventory; image URL descriptors remain for post-launch preparation and external model working paths report portability incompatibility"
     },
     {
       "id": "root:WS",

package/docs/reference/local-ai.md

@@ -1,6 +1,7 @@
 # Local AI through Core
 
-Core owns native llama.cpp and Ollama processes and ONNX worker sessions. The browser retains its own
+Core owns native llama.cpp and Ollama processes, ONNX worker sessions and
+selected local image generation. The browser retains its own
 Wllama and ONNX implementations, and can also use an explicitly connected Core
 when that system service is available. Runtime installation, model loading and
 inference are separate operations.
@@ -20,7 +21,8 @@ Existing native fields remain alongside this record:
   "runtimes": [
     {"id": "llama.cpp"},
     {"id": "ollama"},
-    {"id": "onnx"}
+    {"id": "onnx"},
+    {"id": "stable-diffusion.cpp", "backend": "auto", "models": ["sd14"]}
   ],
   "llamaCpp": {
     "modelsDirectory": "models/llama"
@@ -34,11 +36,22 @@ Existing native fields remain alongside this record:
 Each runtime requirement accepts `id`, optional upstream `version`, and an
 optional runtime archive `url`. ONNX resolves its official npm package or an
 explicitly supplied package archive. A string runtime ID is also accepted.
-Omitting the version allows reuse of an available runtime. Explicit versions
+For chat runtimes, omitting the version allows reuse of an available runtime. Explicit versions
 select that upstream distribution; an existing service must match the requested
 version before it is reused. A service occupying the selected address is
 preserved when its version cannot be established.
 
+Both public application/package schemas accept `stable-diffusion.cpp` as a
+string or runtime-record ID. Its record additionally accepts `backend`
+(`auto`, `cpu` or `metal`) and `models`, an array of `sd14` or complete model
+descriptors. Omitted image version selects `master-929-3f8527a`; omitted backend
+selects `auto`; omitted models leaves model selection empty. Windows/Linux
+distribution defaults use CPU; the selected universal Mac archive supports
+Metal with CPU fallback. Installation obtains the upstream library and its
+managed `koffi@3.3.2` binding, without installing a model. Complete model
+descriptors keep their resources, context, defaults and operations separate.
+See [image selection and model preparation](local-image-generation.md#selection-and-model-assets).
+
 `llamaCpp` accepts `url`, `model`, `modelsDirectory`, and an `args` string array.
 `model` selects a single GGUF file; `modelsDirectory` selects llama.cpp router
 mode. Paths resolve from the application root. Ollama accepts `url`,
@@ -55,6 +68,10 @@ arcane dev --local-ai llama.cpp,ollama,onnx
 
 The option adds those runtime requirements to the authored application
 configuration. Subsequent `arcane dev` runs reuse the saved requirements.
+`--local-ai stable-diffusion.cpp` also selects image runtime preparation; the
+application selects its `models` in the runtime record before requesting a
+load or generation. The development owner composes separate image and
+model-assets services alongside the existing chat/ONNX service.
 Development checks selected endpoints and existing executable paths, then
 installs missing runtimes under the application's `.arcane/local-ai/runtimes`.
 Runtime preparation runs alongside HTTP serving. Browser rendering continues
@@ -89,9 +106,12 @@ processes. An already running external service remains running.
 
 `developApplication()` returns its usual server handle and an optional `localAI`
 handle with `ready`, `current()`, `handler()` and `close()`. Its `ready` promise
-means installation and Core composition completed. Runtime/model readiness is
-reported separately by Core status and lifecycle events. Preparation failures
-remain on that promise and the operation event stream.
+means Core composition has started, not that installation or a selected model
+is ready. Runtime preparation continues at each owning service. `current()`
+includes separate `core`, `localAI` and optional `image` state; image status
+remains callable during preparation. Composition failures reject `ready`;
+later service preparation failures remain on Core lifecycle and diagnostic
+events. Page rendering waits for neither.
 
 ## Core service
 
@@ -112,6 +132,14 @@ application. `current()` returns the current snapshot without starting another
 process. The service starts each selected runtime independently, retains its
 process between requests, and joins cleanup during disposal.
 
+Optional `prepare({signal,onEvent})` returns resolved runtime records before
+this service starts its selected engines. The managed development owner uses
+that callback without delaying the HTTP listener or independent services.
+This factory accepts chat/ONNX requirements; the separate
+[`createLocalImageService()`](local-image-generation.md#core-service-and-transport)
+owns image requirements. The development and generated native composition
+split the shared application record accordingly.
+
 `localai.status` returns `{runtimes}` and, when Ollama is selected, the existing
 `ollama` and `models.ollama` catalog fields. Runtime records distinguish
 `installed`, `available`, `state`, `models`, ownership and errors. A listening
@@ -305,11 +333,24 @@ archive in this installer.
 
 Ensure returns absolute `{id,version,platform,architecture,root}` records.
 Server runtimes also include `executable`; ONNX includes `modulePath` pointing
-to its public package entry. Bundle returns `{runtimes,files}`,
+to its public package entry. Image records include `libraryPath`,
+`bindingModulePath`, requested `backend`, installed `variants` and selected
+`models` metadata. Variant records carry backend, runtime root and library path.
+Bundle returns `{runtimes,files}`,
 with artifact-relative runtime paths and a complete emitted file inventory.
 Bundling requires a fresh native staging destination, preserving existing
 completed outputs.
 
+Image assembly preserves the complete runtime/binding tree and relocates
+library, binding and variant paths into the artifact. It retains original
+model URL descriptors for preparation after launch. A model file already
+inside the runtime tree becomes artifact-relative; an external native working
+path reports its portability incompatibility. Use the explicit native-resource
+workflow or [model-assets preparation](model-assets.md) for those files.
+Model acquisition, context loading and inference remain separate from runtime
+assembly. Platform availability depends on the selected upstream archive;
+this contract does not establish execution on every supported host.
+
 ### NeMo Speech library runtime
 
 The runtime helpers also accept `{id: 'nemo-speech', version: '0.2.0'}` to

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

@@ -1,10 +1,97 @@
-# Local image edit inputs
+# Local image editing through Core
 
-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.
+`createCoreImageRuntime()` exposes whole-image img2img through `edit()`, using
+the same retained native context as generation. The selected SD1.4 model
+advertises `txt2img` and `img2img`. Applications supply the original PNG, the
+complete prompt and explicit strength, retain the original, and decide whether
+to save the separate generated result.
+
+## Browser accessor
+
+Prepare and load the selected model using the
+[shared generation and model-asset lifecycle](local-image-generation.md).
+Then pass a generated PNG Blob or a supported PNG File directly:
+
+```js
+import {createCoreImageRuntime} from 'arcane-os/ai/core-image';
+
+const images = createCoreImageRuntime({signal: page.signal});
+images.subscribe(function showImageStatus(snapshot) {
+    statusElement.textContent = snapshot.status ?? snapshot.state;
+});
+
+const result = await images.edit({
+    model: 'sd14',
+    image: originalPNG,
+    prompt: 'A dignified raccoon astronaut wearing a purple knitted helmet, holding a tiny moon cactus.',
+    strength: 0.6,
+    parameters: {
+        width: 512,
+        height: 512,
+        sample_params: {sample_steps: 20}
+    },
+    signal: page.signal,
+    onProgress(progress) {
+        console.log(progress);
+    }
+});
+
+const editedPNG = result.images[0].blob;
+```
+
+The example uses the application's existing `page` AbortController,
+`statusElement` and original `originalPNG` Blob or File. It assumes that the
+selected model has already been loaded. `edit()` can also prepare a selected
+model on demand using the same `assetProjectionId` and `resourcePaths` fields
+as `generate()`.
+
+| Member or field | Contract |
+| --- | --- |
+| `edit({model, image, prompt, strength, parameters?, assetProjectionId?, resourcePaths?, signal?, onProgress?})` | Returns the complete result with `images: [{blob, mediaType, width, height}]`, preserving additional runtime result metadata. |
+| `image` | Original complete PNG `Blob` or `File`, with `image/png` or an empty declared media type. Supported PNG encodings are listed below. |
+| `prompt` | Complete caller-authored string, passed unchanged. Native C-string incompatibilities retain the generation error contract. |
+| `strength` | Explicit finite number from `0` through `1`, mapped to native img2img strength. It takes precedence over a model default or `parameters.strength`; it is never clamped. |
+| `parameters` | Native generation options, including canvas dimensions, seed, sampling and `image_preprocess`. The top-level image supplies native `init_image`; the top-level strength supplies native `strength`. Other options retain the generation contract. |
+
+`Thinking` is published synchronously when the browser accepts the edit, before
+reading the Blob, sending the request, preparing the runtime or loading the
+model. Native sampling progress uses the existing progress surface. Complete
+PNG results arrive after native completion; the SDK fabricates no image chunks
+or assistant turns. Closing the accessor cancels and joins its requests while
+preserving the shared Core client and model ownership.
+
+The original encoded input is preserved through lossless Core JSON framing.
+The browser does not decode, draw, re-encode, resize, crop, composite or save it.
+The request signal reaches input preparation, worker decoding and cooperative
+native cancellation. Cancellation during `Blob.arrayBuffer()` is observed
+after that platform operation completes. An aborted edit produces no late
+success or progress callback. Request invocation retains `timeoutMs: 0`.
+
+## Core and native request
+
+The `arcane-os/core/image` service adds `image.edit` with
+`{model, image, prompt, strength, parameters?, streamId?, assetProjectionId?, resourcePaths?}`.
+At this JSON boundary only, `image` is
+`{data: completeBase64PNG, encoding: 'base64', mediaType}`. The service emits
+the existing accepted `image.progress` event before preparation, then forwards
+the decoded transport content to the shared image worker. Results use the
+same complete PNG transport records as `image.generate`.
+
+The native runtime's `edit()` takes the same operation fields, with
+`image: {data: Uint8Array, mediaType}` and no Core projection arguments.
+It copies the supplied data view at acceptance so caller reuse cannot change
+an input waiting behind another operation.
+The worker decodes once, loads or reuses the exact selected context, and passes
+the raster as native `init_image` with explicit `strength`. The existing native
+binding retains input memory through completion and copies complete output
+rasters before native cleanup. The same queue, cancellation, unload and close
+owners serve generation and editing; no second engine or model store is created.
+
+Unreadable or unsupported input rejects the edit without substituting an
+image. Errors retain their complete details on rejected promises and diagnostic
+events. Applications keep those engineering diagnostics outside ordinary status
+surfaces and durable chat history. No prompt, input or result is persisted by
+this operation.
 
 ## Decoder contract
 
@@ -56,22 +143,21 @@ 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
+Whole-image img2img uses an initial image, prompt and strength. This `edit()`
+contract selects that operation. Masked and reference editing require their
+own model-specific contracts and are outside this PNG img2img operation.
+Ordinary img2img does not require LoRA training. The selected 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;
+generation dimensions. The engine center-crops and resizes temporary initial
+images to the selected canvas by default and reports actual output dimensions.
+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
+An RGB-only model such as the selected SD1.4 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