arcane-os 0.7.3 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.8.1
+
+- Use `arcaneVersion` as the sole local resource version field across import maps,
+  runtime materialization, source serving, packaged applications, and dynamic
+  components. Remove `v` and duplicate version fields while preserving unrelated
+  query parameters, fragments, and ordinary caching.
+- Reuse the registered `html-import` constructor across module URL variants,
+  including overlapping application startup and developer error-dialog imports.
+  Prevent duplicate custom-element registration from raising `NotSupportedError`
+  while preserving component loading, readiness, teardown, and existing instances.
+
+## 0.8.0
+
+- Add `removeBrowserSpeechModelCache()` to remove an explicitly retired Hugging
+  Face speech model from the current browser origin's upstream cache. Preserve
+  other models, voices, runtimes, DBOPFS artifacts, and preferences; report each
+  completed removal and surface cancellation or partial failure.
+- Keep model retirement policy in consuming applications. The operation starts
+  no model download or inference and leaves NPU, GPU, and CPU selection unchanged.
+
 ## 0.7.3
 
 - Correct public development serving for OPFS/DBOPFS and other browser APIs

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.7.3` SDK contract. Applications pin one exact npm
+This checkout defines the `0.8.1` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -35,7 +35,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.7.3 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.8.1 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -386,7 +386,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.7.3 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.8.1 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run dev
@@ -396,7 +396,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.7.3
+npm install --save-dev --save-exact arcane-os@0.8.1
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -412,7 +412,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.7.3` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.8.1` 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`,
@@ -432,7 +432,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.7.3.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.8.1.tgz
 npm ci
 ```
 
@@ -441,7 +441,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.7.3` registry package and
+the local declaration with the exact `arcane-os@0.8.1` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -580,7 +580,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.7.3` exposes one browser target and five explicitly paired
+Version `0.8.1` 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-speech-artifacts.mjs

@@ -2331,6 +2331,53 @@ export function createDbopfsSpeechArtifactStore({
   return store;
 }
 
+export async function removeBrowserSpeechModelCache(
+    {repository, cacheStorage = globalThis.caches, signal} = {}
+) {
+    const selectedRepository = requiredText(repository, 'repository');
+    const removed = [];
+    const result = {repository: selectedRepository, removed};
+    const modelPath = `/${selectedRepository.split('/').map(encodeURIComponent).join('/')}/resolve/`;
+
+    try {
+        throwIfAborted(signal);
+        if (!is.function(cacheStorage?.has) || !is.function(cacheStorage?.open)) {
+            throw speechError(
+                'ARCANE_AI_STORAGE_UNAVAILABLE',
+                'Browser model cache storage is unavailable.',
+                undefined,
+                'browser-speech-model-cache-unavailable'
+            );
+        }
+        const cached = await cacheStorage.has('transformers-cache');
+        throwIfAborted(signal);
+        if (!cached) return result;
+        const cache = await cacheStorage.open('transformers-cache');
+        const requests = await cache.keys();
+        for (const request of requests) {
+            throwIfAborted(signal);
+            const url = new URL(request.url);
+            if (url.origin !== 'https://huggingface.co' || !url.pathname.startsWith(modelPath)) {
+                continue;
+            }
+            if (await cache.delete(request)) removed.push(request.url);
+        }
+        throwIfAborted(signal);
+        return result;
+    } catch (cause) {
+        const error = cause?.name === 'AbortError' || isBrowserSpeechArtifactError(cause)
+            ? cause
+            : speechError(
+                'ARCANE_AI_STORAGE_DELETE_FAILED',
+                'Unable to remove the selected browser speech model download.',
+                cause,
+                'browser-speech-model-cache-delete-rejected'
+            );
+        error.removed = removed;
+        throw error;
+    }
+}
+
 export function isBrowserSpeechAuthority(value) {
   return AUTHORITIES.has(value);
 }

package/browser-runtime/ai/browser-speech.mjs

@@ -4,6 +4,7 @@ export {
   createBrowserSpeechArtifactGraph,
   createBrowserSpeechAuthority,
   createDbopfsSpeechArtifactStore,
+  removeBrowserSpeechModelCache,
 } from "./browser-speech-artifacts.mjs";
 export {
   createBrowserKokoroProvider,

package/docs/architecture.md

@@ -289,7 +289,7 @@ paths are withheld from the native provider. The provider copies the complete
 selected release rather than accepting an unrelated source path. Verification
 is a separate explicit operation for a selected release artifact.
 
-The SDK `0.7.3` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.8.1` runtime requires Arcane `0.8.12` or newer. Compatibility
 is contractual rather than exact-version pinning: the prepared Core must meet
 the highest minimum declared by the runtime, selected app, and bundled app
 dependencies; keep each app's Arcane protocol generation; and provide every

package/docs/reference/ai/browser-speech.md

@@ -1027,6 +1027,33 @@ forward a security payload to the Worker and performs no security work. Passing
 `{secure:true}` does not activate hardening. Any future hardening stage requires
 a separate user review and an explicit implementation change before it may execute.
 
+## `removeBrowserSpeechModelCache()`
+
+```javascript
+const removal = await removeBrowserSpeechModelCache(
+    {repository: 'Xenova/whisper-small', signal}
+);
+```
+
+Exported by `arcane-os/ai/browser-speech`. This explicit operation removes all
+cached revisions of the exact selected Hugging Face model from the current
+origin's existing `transformers-cache`. It returns `{repository,removed}`,
+where `removed` contains the complete URLs actually deleted. An absent cache or
+model returns an empty list. Other models, runtime files, the Kokoro voice
+cache, DBOPFS files, and preferences remain untouched. No model is loaded or
+downloaded and no inference is started.
+
+The caller owns model retirement policy and must stop using the retired model
+before removal so a live provider cannot download it again. This operation is
+separate from `store.remove(authority)`, which removes declared DBOPFS files.
+`cacheStorage` may explicitly supply a CacheStorage implementation; it defaults
+to `globalThis.caches`. Missing storage rejects with
+`ARCANE_AI_STORAGE_UNAVAILABLE`; cache failures reject with
+`ARCANE_AI_STORAGE_DELETE_FAILED`. An aborted `signal` stops further removals
+with `AbortError`. Deletions already completed are retained in `error.removed`;
+removal is repeatable and does not claim transactional rollback. The operation
+enumerates one cache once and awaits each matching deletion in order.
+
 ## Ordinary module routing
 
 Artifact-graph preparation reads each stored JavaScript module, discovers

package/docs/reference/asset-versioning.md

@@ -7,10 +7,11 @@ SDK package metadata, not a timestamp, content measurement, or application
 constant.
 
 For example, an existing `./arcane/modules/HTMLImport.js?v=6#module` reference
-retains its application revision and fragment and gains
-`&arcaneVersion=${version}` before the fragment. Regenerating for another SDK
-release replaces only the `arcaneVersion` value. Existing query spelling and
-application parameters remain intact.
+becomes `./arcane/modules/HTMLImport.js?arcaneVersion=${version}#module`.
+`arcaneVersion` is the sole resource version field: transformation removes `v`,
+updates the first existing `arcaneVersion`, and removes duplicate version fields.
+Regenerating for another SDK release replaces that version value. Unrelated
+query fields, their spelling, and fragments remain intact.
 
 ## Public tooling
 
@@ -57,6 +58,12 @@ take effect on ordinary navigation or refresh; they do not replace live module
 instances, force a reload, restart a model, or erase a conversation. The SDK does
 not retain earlier installed runtime trees after materialization.
 
+`HTMLImport` registers its element once per browser custom-element registry.
+Previously authored revision URLs and the developer error dialog's module URL
+can be different; each import exports the constructor already registered in that
+document. Repeated imports do not replace existing component instances or
+register a second `html-import` definition.
+
 ## Scope and work
 
 One invocation acts on the selected workspace/application. Runtime

package/docs/reference/runtime-modules.md

@@ -2052,6 +2052,15 @@ Defines the same-origin `<html-import>` loader with open shadow root, inline scr
 
 default `HTMLImport`; registers `html-import`; `connectedCallback()` and `ready`.
 
+Registration occurs once per custom-element registry. Imports through different
+module URLs reuse and export the registered constructor, including overlapping
+application startup and developer error-dialog imports. Existing component
+instances, loading, readiness events, and teardown keep that same constructor.
+
+Local component resources use the loader's `arcaneVersion` as their sole version
+field. Existing `v` fields are removed; unrelated query fields and fragments
+remain intact.
+
 Exact exports: `default`.
 
 ### Availability and normalization

package/docs/reference/sdk-api.md

@@ -125,6 +125,7 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | `createCanonicalUstarHeader()` | function | `arcane-os` | Packaging and release bundles | Node |
 | `createDbopfsModelStore()` | function | `arcane-os/ai/browser-wasm` | Browser-WASM local AI | Browser with a ready DBOPFS instance and OPFS |
 | `createDbopfsSpeechArtifactStore()` | function | `arcane-os/ai/browser-speech` | Browser speech providers | Browser with ready DBOPFS, Web Locks, Fetch, File/Blob, and object URLs |
+| `removeBrowserSpeechModelCache()` | function | `arcane-os/ai/browser-speech` | Browser speech providers | Browser CacheStorage; explicit removal of one selected upstream model |
 | `createNativeBuildPlan()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `createNativeTargetAdapter()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `createReporter()` | function | `arcane-os` | Events, processes, and testing | Node |
@@ -6396,6 +6397,24 @@ const authority = createBrowserSpeechAuthority({
 });
 ```
 
+## removeBrowserSpeechModelCache()
+
+```text
+removeBrowserSpeechModelCache({ repository, cacheStorage=globalThis.caches, signal }={})
+```
+
+Removes cached Hugging Face resources for the exact selected repository, across
+all revisions, from the current origin's existing `transformers-cache`.
+Returns `{repository,removed}`, including each complete URL actually deleted.
+An absent model or cache returns an empty list. The caller must stop using the
+retired model first; this operation does not unload providers or start inference.
+Other models, runtime resources, voice caches, declared DBOPFS artifacts, and
+preferences are preserved. Use `store.remove(authority)` separately for declared
+DBOPFS artifacts. Missing storage and cache failures surface
+`ARCANE_AI_STORAGE_UNAVAILABLE` and `ARCANE_AI_STORAGE_DELETE_FAILED`.
+Cancellation stops subsequent deletions with `AbortError`; `error.removed`
+retains the complete list of deletions already completed.
+
 ## createDbopfsSpeechArtifactStore()
 
 ### Overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -67,7 +67,7 @@
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
     "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/packaging.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/wllama-webgpu-runtime.test.mjs",
-    "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
+    "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",
     "check:release": "node tools/check-source.mjs --package-only && npm run test:release",
     "pack:local": "npm pack --ignore-scripts",

package/runtime/arcane/modules/HTMLImport.js

@@ -43,14 +43,21 @@ function versionComponentResource(value,baseHref){
   const versionField=`arcaneVersion=${encodeURIComponent(htmlImportAssetVersion)}`;
   let replaced=false;
   const fields=query?query.split('&').map(function versionQueryField(field){
-    if(!new URLSearchParams(field).has('arcaneVersion'))return field;
+    const parameter=new URLSearchParams(field);
+    if(parameter.has('v'))return null;
+    if(!parameter.has('arcaneVersion'))return field;
     if(replaced)return null;
     replaced=true;
-    return versionField;
+    const equals=field.indexOf('=');
+    const key=equals<0?field:field.slice(0,equals);
+    return `${key}=${encodeURIComponent(htmlImportAssetVersion)}`;
   }).filter(function retainQueryField(field){
     return field!==null;
   }):[];
-  if(!replaced)fields.push(versionField);
+  if(!replaced){
+    if(fields.at(-1)==='')fields[fields.length-1]=versionField;
+    else fields.push(versionField);
+  }
   return `${pathname}?${fields.join('&')}${fragment}`;
 }
 
@@ -538,6 +545,12 @@ class HTMLImport extends HTMLElement {
   }
 }
   
-customElements.define('html-import', HTMLImport);
+// Application startup and error dialogs can import different URL variants.
+// Each variant must use the constructor already owned by this registry.
+const RegisteredHTMLImport = customElements.get('html-import') || HTMLImport;
+
+if(RegisteredHTMLImport === HTMLImport){
+  customElements.define('html-import', HTMLImport);
+}
 
-export default HTMLImport;
+export default RegisteredHTMLImport;

package/src/import-map.mjs

@@ -814,6 +814,8 @@ function assetUrlVersionEdits(value,version){
     if(queryStart<0)return [{start:address.length,end:address.length,value:`?arcaneVersion=${versionValue}`}];
     const query=address.slice(queryStart+1);
     const edits=[];
+    const parameters=[];
+    let versionFound=false;
     let offset=queryStart+1;
     for(const parameter of query.split('&')){
         const equals=parameter.indexOf('=');
@@ -821,7 +823,10 @@ function assetUrlVersionEdits(value,version){
         let decodedKey=key;
         try{decodedKey=decodeURIComponent(key.replaceAll('+',' '));}
         catch{decodedKey=key;}
-        if(decodedKey==='arcaneVersion'){
+        const remove=decodedKey==='v'||(decodedKey==='arcaneVersion'&&versionFound);
+        parameters.push({start:offset,end:offset+parameter.length,remove});
+        if(decodedKey==='arcaneVersion'&&!versionFound){
+            versionFound=true;
             edits.push({
                 start:offset+(equals<0?parameter.length:equals+1),
                 end:offset+parameter.length,
@@ -830,10 +835,25 @@ function assetUrlVersionEdits(value,version){
         }
         offset+=parameter.length+1;
     }
-    if(edits.length===0)edits.push({
+    // Remove adjacent obsolete fields together, including only their separator.
+    // Other field spelling and source-level escapes remain untouched.
+    for(let index=0;index<parameters.length;index+=1){
+        if(!parameters[index].remove)continue;
+        const first=index;
+        while(parameters[index+1]?.remove)index+=1;
+        edits.push({
+            start:parameters[first].start-(first>0?1:0),
+            end:parameters[index].end+(first===0&&index<parameters.length-1?1:0),
+            value:''
+        });
+    }
+    const lastRetained=parameters.findLast(function retainedParameter(parameter){
+        return !parameter.remove;
+    });
+    if(!versionFound)edits.push({
         start:address.length,
         end:address.length,
-        value:`${query&&!query.endsWith('&')?'&':''}arcaneVersion=${versionValue}`
+        value:`${lastRetained&&lastRetained.end>lastRetained.start?'&':''}arcaneVersion=${versionValue}`
     });
     return edits;
 }
@@ -841,7 +861,7 @@ function assetUrlVersionEdits(value,version){
 function applyReferenceEdits(source,edits){
     let result=source;
     for(const edit of edits.sort(function descendingReferenceOffset(left,right){
-        return right.start-left.start;
+        return right.start-left.start||right.end-left.end;
     })){
         result=result.slice(0,edit.start)+edit.value+result.slice(edit.end);
     }