arcane-os 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.3.3
+
+- Corrected installed-workspace import-map refresh to preserve rich browser
+  document inspection records while passing only navigable document paths to
+  the public generator, including `.html` and `.htm` pages without modifying
+  HTML fragments.
+- Restored one semantic `arcane.lock.json` contract across scaffold, init, and
+  installed runtime materialization, replacing stale versions with the exact
+  installed package version and npm-alias roots without byte or security
+  metadata.
+- Added selected installed-package coverage for stale-lock replacement and the
+  public multi-document import-map command through the packed npm artifact.
+
 ## 0.3.2
 
 - Preserved complete application, document, model, message, event, process,

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.3.2` SDK contract. Applications pin one exact npm
+This checkout defines the `0.3.3` 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.3.2 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.3.3 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.3.2
+npm install --save-dev --save-exact arcane-os@0.3.3
 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.3.2` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.3.3` 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.3.2.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.3.3.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.3.2` registry package and
+the local declaration with the exact `arcane-os@0.3.3` 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.3.2` exposes one browser target and five explicitly paired
+Version `0.3.3` 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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/speech.html

@@ -1380,7 +1380,7 @@
     function stop() {
         recordingRequested = false;
         clearSilenceTimer();
-        if (captureSession?.recorder.state !== 'inactive') {
+        if (captureSession && captureSession.recorder.state !== 'inactive') {
             captureSession.recorder.stop();
         }
         return true;

package/schemas/arcane-lock.schema.json

@@ -14,7 +14,10 @@
       "required": ["name", "version"],
       "properties": {
         "name": {"const": "arcane-os"},
-        "version": {"const": "0.3.2"}
+        "version": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[0-9A-Za-z.-]+)?$"
+        }
       }
     },
     "runtime": {

package/src/dev-server.mjs

@@ -31,6 +31,11 @@ const SDK_RUNTIME_SOURCE_PROTOCOL='arcane-sdk-runtime-source/1';
 const SDK_RUNTIME_SOURCE_ARCANE_ROOTS=new Set([
     'components','css','entities','img','modules','security'
 ]);
+const SDK_INSTALLED_ARCANE_ROOTS=new Set([
+    ...SDK_RUNTIME_SOURCE_ARCANE_ROOTS,
+    'dependencies',
+    'sdk'
+]);
 const SDK_RUNTIME_SOURCE_PRIVATE_SEGMENTS=new Set([
     'node_modules','.git','.hg','.svn','cvs'
 ]);
@@ -126,7 +131,7 @@ async function canonicalRealDirectory(requested,label){
     return canonical;
 }
 
-function sdkRuntimeSourcePathAllowed(relative,{arcaneRoot=false}={}){
+function sdkRuntimeSourcePathAllowed(relative,{arcaneRoots=null}={}){
     if(relative.length===0)return false;
     const normalized=relative.map(function normalizeRuntimeSourceSegment(segment){
         return segment.normalize('NFC').toLowerCase();
@@ -135,11 +140,15 @@ function sdkRuntimeSourcePathAllowed(relative,{arcaneRoot=false}={}){
         return segment.startsWith('.')||SDK_RUNTIME_SOURCE_PRIVATE_SEGMENTS.has(segment)
             ||SDK_RUNTIME_SOURCE_PRIVATE_MANIFESTS.has(segment);
     }))return false;
-    return !arcaneRoot||SDK_RUNTIME_SOURCE_ARCANE_ROOTS.has(normalized[0]);
+    return arcaneRoots===null||arcaneRoots.has(normalized[0]);
 }
 
 function sdkArcaneSourcePathAllowed(relative){
-    return sdkRuntimeSourcePathAllowed(relative,{arcaneRoot:true});
+    return sdkRuntimeSourcePathAllowed(relative,{arcaneRoots:SDK_RUNTIME_SOURCE_ARCANE_ROOTS});
+}
+
+function sdkInstalledArcanePathAllowed(relative){
+    return sdkRuntimeSourcePathAllowed(relative,{arcaneRoots:SDK_INSTALLED_ARCANE_ROOTS});
 }
 
 function sdkDependencySourcePathAllowed(relative){
@@ -418,7 +427,7 @@ async function sourceRoutes(workspaceRoot,appId,{
             {
                 prefix:['arcane'],
                 root:runtimeRoot,
-                allow:sdkArcaneSourcePathAllowed
+                allow:sdkInstalledArcanePathAllowed
             }
         ]
     };

package/src/installed-sdk-runtime.mjs

@@ -1,7 +1,8 @@
-import {readFile,realpath,stat} from 'node:fs/promises';
+import {lstat,readFile,realpath,stat,writeFile} from 'node:fs/promises';
 import path from 'node:path';
 import {materializeWorkspaceRuntimeContent} from './workspace-runtime.mjs';
 import {withWorkspaceOperationLock} from './workspace-operation-lock.mjs';
+import {createWorkspaceLockDocument} from './templates/workspace-template.mjs';
 import {
     resolveInstalledSdkInstallation,
     resolveSdkPackageDeclaration
@@ -55,6 +56,18 @@ async function installedSdkAuthority(canonicalRoot,{sdkPackageSource}={}){
     return {declaration,installation};
 }
 
+async function writeWorkspaceLock(lockPath,lock){
+    try{
+        const info=await lstat(lockPath);
+        if(info.isSymbolicLink()||!info.isFile()){
+            fail(`Workspace SDK lock must be a real file: ${lockPath}.`);
+        }
+    }catch(error){
+        if(error?.code!=='ENOENT')throw error;
+    }
+    await writeFile(lockPath,`${JSON.stringify(lock,null,2)}\n`,'utf8');
+}
+
 export async function materializeInstalledSdkRuntime({
     workspaceRoot,
     sdkPackageSource,
@@ -79,12 +92,21 @@ export async function materializeInstalledSdkRuntime({
             signal,
             onEvent
         });
+        const lockPath=path.join(canonicalRoot,'arcane.lock.json');
+        const lock=createWorkspaceLockDocument({
+            dependencyName:authority.installation.dependencyName,
+            packageName:authority.installation.packageName,
+            packageVersion:authority.installation.packageVersion,
+            packageSource:authority.installation.packageSource
+        });
+        await writeWorkspaceLock(lockPath,lock);
         return {
             schemaVersion:1,
             kind:'arcane-installed-sdk-runtime-materialization',
             status:'materialized',
             installation:authority.installation,
-            workspaceRuntime
+            workspaceRuntime,
+            workspaceLock:{path:lockPath,document:lock}
         };
     });
 }

package/src/packager/core.mjs

@@ -499,16 +499,23 @@ async function collectPackageRecords(context,{signal}={}){
     return records;
 }
 
-async function browserDocuments(records){
+async function browserDocuments(records,entry){
+    let entryDocument=null;
     const documents=[];
     for(const record of records){
-        if(path.posix.extname(record.destination).toLocaleLowerCase('en-US')!=='.html')continue;
+        const extension=path.posix.extname(record.destination).toLocaleLowerCase('en-US');
+        if(extension!=='.html'&&extension!=='.htm')continue;
         const inspected=inspectImportMapHtml(await readFile(record.source,'utf8'),{
             documentPath:record.destination
         });
-        documents.push({path:record.destination,...copyJson(inspected)});
+        const document={path:record.destination,...copyJson(inspected)};
+        if(record.destination===entry){
+            entryDocument=document;
+        }else if(inspected.bases.length>0){
+            documents.push(document);
+        }
     }
-    return documents;
+    return entryDocument===null?documents:[entryDocument,...documents];
 }
 
 async function optionalDescriptor(context){
@@ -540,7 +547,7 @@ async function inspectContext(context,{signal}={}){
         }),
         ...(context.config.adapter===undefined?{}:{adapter:context.config.adapter}),
         descriptor:await optionalDescriptor(context),
-        browserDocuments:await browserDocuments(records),
+        browserDocuments:await browserDocuments(records,context.config.entry),
         files:records.map(record=>record.destination),
         output:path.relative(context.workspaceRoot,context.outputRoot).split(path.sep).join('/')
     };

package/src/scaffold.mjs

@@ -430,6 +430,25 @@ export async function initWorkspace({
             sdkDeclaration
         );
     const writtenFiles=await writeMissingFiles(resolvedRoot,template.files,{signal,onEvent});
+    if(workspaceMode==='external'&&writtenFiles.skippedFiles.includes('arcane.lock.json')){
+        throwIfAborted(signal);
+        await assertNoLinkedAncestors(resolvedRoot,'arcane.lock.json');
+        const lockPath=path.join(resolvedRoot,'arcane.lock.json');
+        const lockInfo=await lstat(lockPath);
+        if(lockInfo.isSymbolicLink()||!lockInfo.isFile()){
+            fail('Existing arcane.lock.json must be a real file.');
+        }
+        await writeFile(
+            lockPath,
+            template.files.get('arcane.lock.json'),
+            'utf8'
+        );
+        writtenFiles.skippedFiles=writtenFiles.skippedFiles.filter(
+            relative=>relative!=='arcane.lock.json'
+        );
+        writtenFiles.replacedFiles=['arcane.lock.json'];
+        await emit(onEvent,{type:'scaffold.file.replaced',path:'arcane.lock.json'});
+    }
     const packageUpdated=await applyPackageMerge(resolvedRoot,packagePlan,{signal,onEvent});
     const workspaceRuntime=workspaceMode==='external'
         ?await materializeWorkspaceRuntimeContent({

package/src/templates/workspace-template.mjs

@@ -1,4 +1,10 @@
-import {SDK_NAME,SDK_VERSION} from '../constants.mjs';
+import {
+    ARCANE_PROTOCOL,
+    CLI_EVENT_PROTOCOL,
+    SDK_NAME,
+    SDK_VERSION,
+    TARGET_ADAPTER_PROTOCOL
+} from '../constants.mjs';
 
 const NPM_PACKAGE_NAME_PATTERN=/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;
 const LOCAL_TARBALL_PATTERN=/^file:.+\.tgz$/iu;
@@ -22,6 +28,32 @@ function titleCase(appId){
         .join(' ');
 }
 
+export function createWorkspaceLockDocument({
+    dependencyName=SDK_NAME,
+    packageName=SDK_NAME,
+    packageVersion=SDK_VERSION,
+    packageSource=`node_modules/${dependencyName}`
+}={}){
+    if(packageName!==SDK_NAME||typeof packageVersion!=='string'
+        ||!/^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/u.test(packageVersion)
+        ||typeof dependencyName!=='string'||dependencyName.length>214
+        ||!NPM_PACKAGE_NAME_PATTERN.test(dependencyName)
+        ||packageSource!==`node_modules/${dependencyName}`){
+        throw new Error('Invalid workspace SDK lock authority.');
+    }
+    return {
+        schemaVersion:1,
+        sdk:{name:packageName,version:packageVersion},
+        runtime:{root:`${packageSource}/runtime`},
+        sdkBrowserRuntime:{root:`${packageSource}/browser-runtime`},
+        protocols:{
+            arcane:ARCANE_PROTOCOL,
+            cliEvents:CLI_EVENT_PROTOCOL,
+            targetAdapter:TARGET_ADAPTER_PROTOCOL
+        }
+    };
+}
+
 export function workspaceTemplate({
     appId,
     displayName,
@@ -212,6 +244,10 @@ Every browser release also carries Arcane OS licensing material under \`licenses
             ]
         }
     }));
+    files.set('arcane.lock.json',json(createWorkspaceLockDocument({
+        dependencyName:sdkDependencyName,
+        packageSource:sdkPackageSource
+    })));
     files.set(`apps/${appId}/arcane-app.json`,json({
         schemaVersion:2,
         id:appId,

package/src/toolchain.mjs

@@ -314,7 +314,9 @@ async function refreshPreparedImportMap(prepared,{signal,onEvent,workspaceOperat
         appId:prepared.appId,
         appRoot:prepared.appRoot,
         entry:manifest.entry,
-        documents:inspected.browserDocuments,
+        documents:inspected.browserDocuments.map(function selectBrowserDocumentPath(document){
+            return document.path;
+        }),
         workspaceOperationLease,
         signal,
         onEvent