arcane-os 0.61.0 → 0.62.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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.62.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/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

package/docs/reference/model-assets.md

@@ -1,9 +1,9 @@
 # Native working files from stored model assets
 
-The selected `0.60.0` package contains the model-assets helpers as internal
-preparation. The public imports and Core registration shown below belong to
-the pending local-image integration and are unavailable through `0.60.0`.
-These examples document that integration's intended public contract.
+These public APIs were first published in `arcane-os@0.61.0`. Browser
+preparation is exported by `arcane-os/ai/core-model-assets`, and the native
+service by `arcane-os/core/model-assets`. The image example below uses
+`arcane-os/ai/core-image`, published in the same release.
 
 `prepareCoreModelAssets()` streams complete browser `File` or `Blob` members
 through the existing Core connection into native working files. DBOPFS keeps

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/core/services/image.mjs

@@ -534,6 +534,48 @@ export function createLocalImageService(
                     operationSignal
                 );
             },
+            'image.edit': function editImage(
+                {model, image, prompt, strength, parameters, streamId, assetProjectionId, resourcePaths} = {},
+                request
+            ) {
+                const operationSignal = AbortSignal.any([lifetimeSignal, request.signal]);
+                operationSignal.throwIfAborted();
+                request.emit(
+                    'image.progress',
+                    {streamId, requestId: request.requestId, status: 'Thinking', progress: {phase: 'accepted'}}
+                );
+                return track(
+                    (async function editSelectedImage() {
+                        if (image?.encoding !== 'base64' || !is.string(image.data)) {
+                            throw new TypeError('Core image input requires complete base64 transport encoding.');
+                        }
+                        const input = {data: Buffer.from(image.data, 'base64'), mediaType: image.mediaType};
+                        const selected = await selectedRuntime(operationSignal);
+                        const prepared = await projectedModel(model, assetProjectionId, resourcePaths, operationSignal);
+                        const result = await selected.edit(
+                            {
+                                model: prepared,
+                                image: input,
+                                prompt,
+                                strength,
+                                parameters,
+                                signal: operationSignal,
+                                onProgress(progress) {
+                                    if (!operationSignal.aborted) {
+                                        request.emit(
+                                            'image.progress',
+                                            {streamId, requestId: request.requestId, status: 'Thinking', progress}
+                                        );
+                                    }
+                                }
+                            }
+                        );
+                        operationSignal.throwIfAborted();
+                        return {...result, images: result.images.map(encodeImage)};
+                    })(),
+                    operationSignal
+                );
+            },
             'image.unload': function unloadImage(_parameters, request) {
                 const operationSignal = AbortSignal.any([lifetimeSignal, request.signal]);
                 return track(

package/src/local-ai/image-models/sd14.mjs

@@ -11,5 +11,5 @@ export const SD14_MODEL = {
     },
     context: {},
     defaults: {},
-    operations: ['txt2img']
+    operations: ['txt2img', 'img2img']
 };

package/src/local-ai/image-runtime.mjs

@@ -1,7 +1,9 @@
 import {Worker} from 'node:worker_threads';
 import {isDeepStrictEqual} from 'node:util';
+import Is from 'strong-type';
 import {createArcaneEventSource} from '../event-manager.mjs';
 
+const is = new Is(false);
 const brokers = new Map();
 
 /** Share the native library owner between Core services in this host. */
@@ -81,6 +83,26 @@ export function createImageRuntime(
         );
     }
 
+    function edit({model, image, prompt, strength, parameters, signal: operationSignal, onProgress} = {}) {
+        if (!is.number(strength) || !is.finite(strength)) {
+            throw new TypeError('Image editing requires an explicit finite strength.');
+        }
+        if (strength < 0 || strength > 1) {
+            throw new RangeError('Image editing strength must be between 0 and 1.');
+        }
+        // The accepted input must survive caller reuse while this request queues.
+        const input = {
+            ...image,
+            data: image?.data instanceof Uint8Array ? new Uint8Array(image.data) : image?.data
+        };
+        return operation(
+            'edit',
+            {...selectedModel(model), image: input, prompt, strength, parameters},
+            operationSignal,
+            onProgress
+        );
+    }
+
     function unload({signal: operationSignal} = {}) {
         return operation('unload', {}, operationSignal);
     }
@@ -133,7 +155,7 @@ export function createImageRuntime(
     function abortRuntime() { close().catch(reportError); }
     lifetimeSignal.addEventListener('abort', abortRuntime, {once: true});
     if (lifetimeSignal.aborted) abortRuntime();
-    return {load, generate, unload, current: broker.current, subscribe, close};
+    return {load, generate, edit, unload, current: broker.current, subscribe, close};
 }
 
 function createBroker(configuration, predecessor) {

package/src/local-ai/image-worker.mjs

@@ -1,6 +1,7 @@
 import {parentPort, workerData} from 'node:worker_threads';
 import {createImageLibrary} from './image-library.mjs';
 import {encodePNG} from './image-png.mjs';
+import {decodeImage} from './image-editing.mjs';
 
 let library;
 let active;
@@ -136,6 +137,17 @@ async function execute(message, signal) {
         return state;
     }
     const parameters = message.parameters;
+    let image;
+    if (message.operation === 'edit') {
+        try {
+            image = await decodeImage({...parameters.image, signal});
+        } catch (error) {
+            // Decoding leaves the selected context unchanged. Replay its actual
+            // state so a broker cancellation cannot remain visibly unsettled.
+            publish({error: describeError(error)});
+            throw error;
+        }
+    }
     await load(parameters, signal);
     if (message.operation === 'load') return state;
     signal.throwIfAborted();
@@ -148,11 +160,13 @@ async function execute(message, signal) {
                 prompt: parameters.prompt,
                 parameters: {
                     ...defaults, ...supplied,
+                    ...(message.operation === 'edit' ? {strength: parameters.strength} : {}),
                     sample_params: {
                         ...defaults.sample_params, ...supplied.sample_params,
                         guidance: {...defaults.sample_params?.guidance, ...supplied.sample_params?.guidance}
                     }
                 },
+                image,
                 signal
             }
         );