arcane-os 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.2
+
+- Added transparent Browser-WASM model loading status across cache checks,
+  ordered model-file downloads, and WebGPU initialization, including file
+  counts, elapsed time, and five-second heartbeats so long downloads remain
+  visibly active without byte-based progress.
+
+## 0.4.1
+
+- Preserved complete DirectoryPicker titles, paths, caller options, and
+  provider result fields without application clipping, trimming, freezing, or
+  generic path-character policy while retaining selected/cancelled semantics
+  and provider-owned path failures.
+
 ## 0.4.0
 
 - Preserved complete finite provider progress values and units as

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.4.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.4.2` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -126,7 +126,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.4.0 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.4.2 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run check
@@ -137,7 +137,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.4.0
+npm install --save-dev --save-exact arcane-os@0.4.2
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -153,7 +153,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.4.0` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.4.2` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -174,7 +174,7 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.4.0.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.4.2.tgz
 npm run check
 npm ci
 ```
@@ -184,7 +184,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.4.0` registry package and
+the local declaration with the exact `arcane-os@0.4.2` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -322,7 +322,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.4.0` exposes one browser target and five explicitly paired
+Version `0.4.2` exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The

package/browser-runtime/ai/browser-wasm-llm-provider.mjs

@@ -24,6 +24,7 @@ const WEBGPU_ADAPTER_SELECTED_EVENT = "arcane.ai.browser-wasm.webgpu.adapter.sel
 const WEBGPU_ADAPTER_SELECTION_PROTOCOL = "arcane-ai-webgpu-adapter-selection/1";
 const CHROME_HIGH_PERFORMANCE_GPU_FLAG_URL =
   "chrome://flags/#force-high-performance-gpu";
+const MODEL_LOAD_HEARTBEAT_MS = 5_000;
 const INTEL_VENDOR_ID = 0x8086;
 const CAPABILITY_POLICY_PROTOCOL = "arcane-ai-browser-capability-policy/1";
 let highPerformanceGpuNoticeShown = false;
@@ -561,7 +562,10 @@ export function createDbopfsModelStore({
     }
   }
 
-  async function install(source, { signal } = {}) {
+  async function install(source, { signal, onProgress = null } = {}) {
+    if (onProgress !== null && typeof onProgress !== "function") {
+      throw new TypeError("Model store onProgress must be a function or null.");
+    }
     const names = storageName(source);
     const members = sourceMetadata(source).files;
     await remove(source);
@@ -569,6 +573,13 @@ export function createDbopfsModelStore({
     try {
       for (let index = 0; index < members.length; index += 1) {
         const member = members[index];
+        onProgress?.(completeValue({
+          phase: "download",
+          completed: index,
+          total: members.length,
+          unit: "files",
+          heartbeat: false,
+        }));
         const opened = await source.open(index, { signal });
         try {
           await write(names.models[index].name, opened.body, { signal });
@@ -585,6 +596,13 @@ export function createDbopfsModelStore({
           throw error;
         }
       }
+      onProgress?.(completeValue({
+        phase: "download",
+        completed: members.length,
+        total: members.length,
+        unit: "files",
+        heartbeat: false,
+      }));
       return completeValue({
         files: completeValue(modelFiles),
         file: modelFiles.length === 1 ? modelFiles[0] : null,
@@ -598,8 +616,20 @@ export function createDbopfsModelStore({
   async function ensure(source, {
     signal,
     onCapabilityPolicy,
+    onProgress = null,
     offline = false,
   } = {}) {
+    if (onProgress !== null && typeof onProgress !== "function") {
+      throw new TypeError("Model store onProgress must be a function or null.");
+    }
+    const total = sourceMetadata(source).files.length;
+    onProgress?.(completeValue({
+      phase: "cache-check",
+      completed: 0,
+      total,
+      unit: "files",
+      heartbeat: false,
+    }));
     const cached = await openCached(source, { signal });
     if (cached) {
       const storage = await storagePolicy({ cached: true });
@@ -611,7 +641,7 @@ export function createDbopfsModelStore({
     }
     const storage = await storagePolicy();
     onCapabilityPolicy?.(storage);
-    const installed = await install(source, { signal });
+    const installed = await install(source, { signal, onProgress });
     const admittedStorage = await storagePolicy({ cached: true });
     onCapabilityPolicy?.(admittedStorage);
     return completeValue({ ...installed, cache: "installed", storage: admittedStorage });
@@ -2068,16 +2098,54 @@ export function createBrowserWasmLlmProvider({
       activeSecurity = effectiveSecurity;
       return loadPromise;
     }
+    if (
+      options.onProgress !== undefined
+      && options.onProgress !== null
+      && typeof options.onProgress !== "function"
+    ) {
+      throw new TypeError("Browser-WASM load onProgress must be a function or null.");
+    }
     const externalSignal = options.signal ?? context.signal ?? null;
     const linked = linkAbortSignal(externalSignal);
     const signal = linked.controller.signal;
     const generation = ++lifecycleGeneration;
+    const reportProgress = typeof context.reportProgress === "function"
+      ? context.reportProgress
+      : options.onProgress ?? null;
+    const progressStartedAt = Date.now();
+    let currentProgress = null;
+    let progressHeartbeat = null;
+
+    function publishModelLoadProgress(progress) {
+      if (!reportProgress) return;
+      currentProgress = { ...progress, heartbeat: false };
+      reportProgress(completeValue({
+        ...currentProgress,
+        elapsedMs: Math.max(0, Date.now() - progressStartedAt),
+      }));
+    }
+
+    function publishModelLoadHeartbeat() {
+      if (!reportProgress || !currentProgress) return;
+      reportProgress(completeValue({
+        ...currentProgress,
+        heartbeat: true,
+        elapsedMs: Math.max(0, Date.now() - progressStartedAt),
+      }));
+    }
+
     loadAbort = linked.controller;
     activeSource = requestedSource;
     activeSecurity = effectiveSecurity;
     activeLoadPlan = requestedLoadPlan;
     state = "loading";
     errorState = null;
+    if (reportProgress) {
+      progressHeartbeat = globalThis.setInterval(
+        publishModelLoadHeartbeat,
+        MODEL_LOAD_HEARTBEAT_MS,
+      );
+    }
     loadPromise = (async () => {
       try {
         throwIfAborted(signal, "load");
@@ -2085,6 +2153,7 @@ export function createBrowserWasmLlmProvider({
           signal,
           offline: options.offline === true,
           onCapabilityPolicy: (value) => { storagePolicies.set(activeSource.id, value); },
+          onProgress: publishModelLoadProgress,
         });
         cacheState = admitted.cache;
         throwIfAborted(signal, "load");
@@ -2096,6 +2165,13 @@ export function createBrowserWasmLlmProvider({
           throw fail("ARCANE_AI_OPERATION_SUPERSEDED", "The model load was superseded by unload.");
         }
         const members = sourceMetadata(activeSource).files;
+        publishModelLoadProgress({
+          phase: "initialize",
+          completed: members.length,
+          total: members.length,
+          unit: "files",
+          heartbeat: false,
+        });
         const modelFiles = admitted.files.map((file, index) => (
           typeof globalThis.File === "function"
             ? new File([file], members[index].name, { type: "application/octet-stream" })
@@ -2148,6 +2224,10 @@ export function createBrowserWasmLlmProvider({
         }
         throw normalized;
       } finally {
+        if (progressHeartbeat !== null) {
+          globalThis.clearInterval(progressHeartbeat);
+          progressHeartbeat = null;
+        }
         if (loadAbort === linked.controller) loadAbort = null;
         linked.release();
         loadPromise = null;
@@ -2478,6 +2558,7 @@ export function adaptV1LlmProvider(provider) {
         ...loadOptions,
         modelId: selection.modelId,
         signal,
+        onProgress: progress,
         ...(security?.secure===true?{security:{secure:true}}:{}),
       });
       return status();

package/package.json

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

package/runtime/arcane/components/chat.html

@@ -2072,17 +2072,51 @@
             };
         }
 
+        function progressElapsedText(){
+            const elapsedMilliseconds=Number(role?.progress?.elapsedMs);
+            if(!Number.isFinite(elapsedMilliseconds)||elapsedMilliseconds<0){
+                return '';
+            }
+            const elapsedSeconds=Math.floor(elapsedMilliseconds/1000);
+            const hours=Math.floor(elapsedSeconds/3600);
+            const minutes=Math.floor(elapsedSeconds%3600/60);
+            const seconds=elapsedSeconds%60;
+            if(hours>0){
+                return `${hours}h ${minutes}m elapsed`;
+            }
+            if(minutes>0){
+                return `${minutes}m ${String(seconds).padStart(2,'0')}s elapsed`;
+            }
+            return `${seconds}s elapsed`;
+        }
+
         function progressMessage(){
             const measured=determinateProgress();
-            const phase=typeof role?.progress?.phase==='string'&&role.progress.phase
+            const phaseValue=typeof role?.progress?.phase==='string'&&role.progress.phase
                 ?role.progress.phase
                 :'loading';
+            const phase=phaseValue.replaceAll('-',' ');
             const parts=[
                 `Loading ${modelDisplayName()} through the Arcane SDK`,
                 phase
             ];
             if(measured){
-                parts.push(`${measured.completed} of ${measured.total} ${measured.unit}`);
+                if(
+                    phaseValue==='download'
+                    &&measured.unit==='files'
+                    &&measured.completed<measured.total
+                ){
+                    parts.push(`part ${measured.completed+1} of ${measured.total}`);
+                }else{
+                    parts.push(`${measured.completed} of ${measured.total} ${measured.unit}`);
+                }
+            }
+            const elapsed=progressElapsedText();
+            if(elapsed){
+                parts.push(elapsed);
+                if(role?.progress?.heartbeat===true){
+                    parts.push('Still working');
+                }
             }
             parts.push('The first activation can take several minutes; keep this tab open');
             return parts.join(' · ');

package/runtime/arcane/components/directory-picker.html

@@ -165,11 +165,7 @@
     }
 
     function normalizeValue(value=''){
-        const next=`${value??''}`.trim();
-        if(/[\u0000-\u001f\u007f]/.test(next)){
-            throw new TypeError('The directory path must be plain text.');
-        }
-        return next;
+        return `${value??''}`;
     }
 
     function setDisabled(value=false){

package/runtime/arcane/modules/DirectoryPicker.js

@@ -1,12 +1,7 @@
-const TITLE_MAX_LENGTH=160;
-const PATH_MAX_LENGTH=4096;
-const CONTROL_CHARACTERS=/[\u0000-\u001f\u007f]/;
-
-function isPlainRecord(value){
+function isRecord(value){
     return Boolean(value)
         &&typeof value==='object'
-        &&!Array.isArray(value)
-        &&Object.getPrototypeOf(value)===Object.prototype;
+        &&!Array.isArray(value);
 }
 
 function coded(error,code){
@@ -14,37 +9,27 @@ function coded(error,code){
     return error;
 }
 
-function optionalText(value,label,maximum){
-    if(value===undefined||value===null||value==='') return null;
+function optionalText(value,label){
+    if(value===undefined||value===null) return value;
     if(typeof value!=='string') throw new TypeError(`${label} must be a string when provided.`);
-    const normalized=value.trim();
-    if(!normalized) return null;
-    if(normalized.length>maximum) throw new RangeError(`${label} exceeds ${maximum} characters.`);
-    if(CONTROL_CHARACTERS.test(normalized)) throw new TypeError(`${label} cannot contain control characters.`);
-    return normalized;
+    return value;
 }
 
 function normalizeDirectoryPickerOptions(input={}){
-    if(!isPlainRecord(input)) throw new TypeError('Directory picker options must be a plain object.');
-    const allowed=new Set(['initialPath','title']);
-    const unsupported=Object.keys(input).find(key=>!allowed.has(key));
-    if(unsupported) throw new TypeError(`Unsupported directory picker option: ${unsupported}`);
-
-    const title=optionalText(input.title,'title',TITLE_MAX_LENGTH);
-    const initialPath=optionalText(input.initialPath,'initialPath',PATH_MAX_LENGTH);
-    return Object.freeze({
-        ...(title?{title}:{}),
-        ...(initialPath?{initialPath}:{}),
-    });
+    if(!isRecord(input)) throw new TypeError('Directory picker options must be an object.');
+    const normalized={...input};
+    if(Object.prototype.hasOwnProperty.call(input,'title')){
+        normalized.title=optionalText(input.title,'title');
+    }
+    if(Object.prototype.hasOwnProperty.call(input,'initialPath')){
+        normalized.initialPath=optionalText(input.initialPath,'initialPath');
+    }
+    return normalized;
 }
 
 function normalizeDirectorySelection(input){
-    const keys=isPlainRecord(input)?Object.keys(input):[];
     if(
-        !isPlainRecord(input)
-        ||keys.length!==2
-        ||!keys.includes('cancelled')
-        ||!keys.includes('path')
+        !isRecord(input)
         ||typeof input.cancelled!=='boolean'
     ){
         throw coded(
@@ -53,17 +38,15 @@ function normalizeDirectorySelection(input){
         );
     }
     if(input.cancelled){
-        if(input.path!==null){
-            throw coded(
-                new TypeError('A canceled directory selection must return a null path.'),
-                'DIRECTORY_PICKER_INVALID_RESULT',
-            );
-        }
-        return Object.freeze({cancelled:true,path:null});
+        return {
+            ...input,
+            cancelled:true,
+            path:input.path===undefined?null:input.path,
+        };
     }
     let path;
     try{
-        path=optionalText(input.path,'The selected directory path',PATH_MAX_LENGTH);
+        path=optionalText(input.path,'The selected directory path');
     }catch(error){
         throw coded(error,'DIRECTORY_PICKER_INVALID_RESULT');
     }
@@ -73,7 +56,7 @@ function normalizeDirectorySelection(input){
             'DIRECTORY_PICKER_INVALID_RESULT',
         );
     }
-    return Object.freeze({cancelled:false,path});
+    return {...input,cancelled:false,path};
 }
 
 /**
@@ -81,7 +64,8 @@ function normalizeDirectorySelection(input){
  *
  * This wrapper does not enumerate directories, persist a selected path, or use
  * a browser file picker. The injected provider must expose
- * `selectDirectory(options)` and return `{cancelled, path}`.
+ * `selectDirectory(options)` and return a record with `cancelled` and `path`.
+ * Caller options and additional provider result fields pass through unchanged.
  */
 export default class DirectoryPicker{
     constructor(provider=globalThis.Arcane?.filesystem){