arcane-os 0.27.1 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.28.0
+
+- Expose existing runtime modules and entities directly through
+  `arcane-os/modules/<filename>` and `arcane-os/entities/<filename>`, including
+  extensions. Package exports and managed maps point to the actual files, so
+  relative imports, component resources and `import.meta.resolve` keep their
+  established directory and lifecycle. Existing lowercase exports remain.
+- Root apps using direct npm routes generate package-namespaced maps without
+  the old `arcane/*` or `./arcane/*` keys. Update authored root-app bare imports
+  before regenerating the managed map. Installed `runtime/arcane/` directories
+  remain unchanged; physical, virtual and nested layouts retain compatibility.
+- Use the package namespace for generated root app code and shared PWA imports,
+  preserving parallel startup and the existing storage and installation owners.
+- New root apps declare the SDK as a runtime dependency. Init promotes their
+  SDK development declaration and preserves existing runtime or optional
+  classification in every layout, including aliases. Existing nested scaffold
+  defaults remain unchanged. No server, listener or application policy changes.
+
 ## 0.27.1
 
 - Preserve the previous `apps/<id>/arcane-sw.js` and `arcane-offline.json`

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.27.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.28.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -33,6 +33,12 @@ Select `appsRoot: "."` for a standalone root app, or scaffold one with
 `arcane new my-app --apps-root .`. After npm installation, `arcane import-map`
 refreshes managed maps and the root app's static PWA/navigation files for ordinary
 static hosting. Portable app packages still contain their selected runtime.
+Root/direct maps use `arcane-os/modules/<filename>` and
+`arcane-os/entities/<filename>` (including extensions) plus the focused lowercase
+exports, rather than `arcane/*` aliases. These paths resolve to the actual npm
+files, preserving relative component URLs. New root apps put the SDK in runtime
+`dependencies`; init preserves existing runtime/optional declarations and promotes
+a root app's SDK development declaration without changing its other packages.
 Existing `apps/<id>`, virtual `/arcane` routes, and materialized workspaces remain
 supported. Node services continue to
 use the installed CLI or public imports such as `arcane-os/mail`.

package/browser-runtime/pwa-install.mjs

@@ -89,7 +89,7 @@ export function getPwaInstall() {
 
     async function loadInstallStorage() {
         if (!globalThis.dbopfs) {
-            await import('arcane/DBOPFS');
+            await import('arcane-os/modules/DBOPFS.js');
         }
         const storage = globalThis.dbopfs;
         if (!storage) {
@@ -273,8 +273,8 @@ export function mountPwaInstallPrompt({appName = ''} = {}) {
         if (!globalThis.document) return null;
         // Both modules may start independently; saved theme loading is not a barrier.
         await Promise.all([
-            import('arcane/HTMLImport'),
-            import('arcane/ThemeBootstrap')
+            import('arcane-os/modules/HTMLImport.js'),
+            import('arcane-os/modules/ThemeBootstrap.js')
         ]);
         if (owner.state.status === 'disposed') return null;
         if (!document.body) {
@@ -295,7 +295,7 @@ export function mountPwaInstallPrompt({appName = ''} = {}) {
         host.hidden = true;
         host.dataset.appName = String(appName);
         host.dataset.arcanePwaInstall = '';
-        host.setAttribute('href', new URL('../components/pwa-install.html', import.meta.resolve('arcane/HTMLImport')).href);
+        host.setAttribute('href', new URL('../components/pwa-install.html', import.meta.resolve('arcane-os/modules/HTMLImport.js')).href);
         return new Promise(function waitForInstallComponent(resolve, reject) {
             const observer = new MutationObserver(function observeRemovedInstallComponent() {
                 if (!host.isConnected) cancelMount();

package/browser-runtime/pwa.mjs

@@ -156,7 +156,7 @@ export function registerPwa({workerUrl = './arcane-sw.js', scope} = {}) {
 
     async function loadCheckStorage() {
         if (!globalThis.dbopfs) {
-            await import('arcane/DBOPFS');
+            await import('arcane-os/modules/DBOPFS.js');
         }
         const storage = globalThis.dbopfs;
         if (!storage) {

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

@@ -7,6 +7,10 @@
     "moduleSystem": "ESM"
   },
   "memberCount": 210,
+  "runtimeSubpathPatterns": {
+    "arcane-os/modules/*": "./runtime/arcane/modules/*",
+    "arcane-os/entities/*": "./runtime/arcane/entities/*"
+  },
   "members": [
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",

package/docs/reference/protocols.md

@@ -146,7 +146,7 @@ all four source and destination paths. Package selection and SDK
 version come from the installed dependency, not a generated runtime lock.
 
 `arcane import-map`, `arcane dev`, packaging, and generated PWA inventories use
-the same actual npm destinations. For example, `arcane/HTMLImport` resolves to
+the same actual npm destinations. For example, `arcane-os/modules/HTMLImport.js` resolves to
 `./node_modules/arcane-os/runtime/arcane/modules/HTMLImport.js`, and
 `arcane-os/event-manager` resolves to
 `./node_modules/arcane-os/browser-runtime/event-manager.mjs`. A normal static
@@ -180,6 +180,20 @@ query strings and fragments. It preserves authored files at those destinations.
 For a direct-installed root PWA it generates the static PWA records at the root,
 so normal static hosting needs no SDK request handler or runtime copy.
 
+Direct-installed root maps expose `arcane-os/modules/<filename>` and
+`arcane-os/entities/<filename>` (including extensions), plus the existing
+focused lowercase package exports. They omit the old `arcane/*` and
+`./arcane/*` keys. Real installed `runtime/arcane/` directories are unchanged.
+Physical, nested and virtual layouts retain their established aliases and also
+support the package-namespaced module/entity keys. Relative module and component
+URLs still resolve from the actual selected file, not a reexport wrapper.
+
+New root apps declare the SDK in `dependencies` because serving their npm
+resources requires the installed package at runtime. Root `init` promotes an
+existing SDK development declaration while preserving other dependencies.
+Existing runtime or optional declarations retain their classification across
+layouts; the default nested scaffold continues to use its development dependency.
+
 ## Installed SDK runtime materialization
 
 `materializeInstalledSdkRuntime()` is the Node entrypoint for refreshing one

package/docs/reference/sdk-api.md

@@ -5,11 +5,16 @@ The npm package exposes a Node.js ESM control plane, the portable
 `arcane-os/preference-store`, `arcane-os/speech-playback`,
 `arcane-os/speech-text`, `arcane-os/ai/tool-text-stream`, and `arcane-os/browser-device` entrypoints, and the browser-only
 `arcane-os/pwa`, `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints.
+The `arcane-os/modules/<filename>` and `arcane-os/entities/<filename>` paths
+resolve directly to the existing runtime files, with their actual extension.
+They are public Node package exports and managed browser keys, without a wrapper.
+For example, `import.meta.resolve('arcane-os/modules/WaitForComponent.js')`
+retains the module directory needed to resolve `../components/modal.html`.
 Lowercase runtime subpaths also expose existing module namespaces through both
 Node package exports and managed browser imports, as listed below. Established
 browser names such as `arcane/AIProviderRuntime`, `arcane/AIRuntimeState`, and
-`arcane/ThemeBootstrap` remain managed-map names rather than Node package
-entrypoints. Applications call `globalThis.Arcane` for capability-gated host
+`arcane/ThemeBootstrap` remain compatibility names in physical/nested maps;
+direct-installed root maps use the package namespace instead. Applications call `globalThis.Arcane` for capability-gated host
 behavior.
 
 This page is the canonical inventory for every JavaScript name reachable through `package.json#exports`. The same binding can appear at the root and a focused subpath; those entrypoints are listed together. The root workspace `discoverApps` and the low-level packager `discoverApps` are intentionally separate records because they are different functions.
@@ -36,6 +41,8 @@ runtime layouts.
 | `arcane-os/packager` | Low-level browser app packager. |
 | `arcane-os/release-bundle` | Deterministic external release bundles. |
 | `arcane-os/event-manager` | Central synchronous events, complete time-travel history, playback, and optional DOM instrumentation. |
+| `arcane-os/modules/<filename>` | Direct existing runtime module, including its `.js` or `.mjs` extension. |
+| `arcane-os/entities/<filename>` | Direct existing runtime entity, including its extension. |
 | `arcane-os/logging` | Shared console diagnostics controlled by the existing `user.developer` preference. |
 | `arcane-os/preference-store` | Portable preference records and injected storage adapters. |
 | `arcane-os/ai` | Existing `AI.js` provider-neutral inference and speech namespace. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -13,6 +13,8 @@
     "./toolchain": "./src/toolchain.mjs",
     "./events": "./src/events.mjs",
     "./event-manager": "./src/event-manager.mjs",
+    "./modules/*": "./runtime/arcane/modules/*",
+    "./entities/*": "./runtime/arcane/entities/*",
     "./logging": "./browser-runtime/logging.mjs",
     "./browser-device": "./browser-runtime/browser-device.mjs",
     "./pwa": "./browser-runtime/pwa.mjs",

package/src/import-map.mjs

@@ -1390,6 +1390,9 @@ export async function buildImportMap({files,signal,version=SDK_VERSION,encodePat
     for(const relative of [...inventory].sort(compareText)){
         if(JAVASCRIPT_EXTENSION.test(relative)){
             const target=runtimeTarget(relative);
+            if(relative.startsWith('modules/')||relative.startsWith('entities/')){
+                registerSpecifier(namedRegistry,`arcane-os/${relative}`,target);
+            }
             registerSpecifier(namedRegistry,target,target);
         }
     }
@@ -1453,7 +1456,7 @@ async function physicalRuntime(workspaceRoot,signal){
     return {files};
 }
 
-async function managedImportMapBuild(resolvedWorkspace,signal,pwaEnabled=false){
+async function managedImportMapBuild(resolvedWorkspace,resolvedApp,signal,pwaEnabled=false){
     const installed=await readInstalledSdkLayout(resolvedWorkspace);
     const [runtime,version]=await Promise.all([
         installed?installedRuntimeFiles(resolvedWorkspace,installed,signal):physicalRuntime(resolvedWorkspace,signal),
@@ -1462,13 +1465,15 @@ async function managedImportMapBuild(resolvedWorkspace,signal,pwaEnabled=false){
     const built=await buildImportMap({files:runtime.files,signal,version});
     if(installed?.direct){
         const imports={};
+        const rootApplication=samePath(resolvedWorkspace,resolvedApp);
         function installedBrowserUrl(value){
             return value.startsWith('./')
                 ?`./${installedRuntimeTarget(value.slice(2),installed,{browser:true})}`:value;
         }
         for(const [specifier,target] of Object.entries(built.imports)){
+            if(rootApplication&&specifier.startsWith('arcane/'))continue;
             const selected=installedBrowserUrl(target);
-            imports[specifier]=selected;
+            if(!rootApplication)imports[specifier]=selected;
             // Relative module imports and bare names must resolve to the same instance.
             imports[installedBrowserUrl(specifier)]=selected;
         }
@@ -2846,7 +2851,7 @@ async function generateImportMapUnlocked({
     }catch(error){
         if(error?.code!=='ENOENT')throw error;
     }
-    const {built,json,version}=await managedImportMapBuild(resolvedWorkspace,signal,pwaEnabled);
+    const {built,json,version}=await managedImportMapBuild(resolvedWorkspace,resolvedApp,signal,pwaEnabled);
     const renderedDocuments=documentStates.map(item=>({
         ...item,
         content:rewriteAssetReferences(renderManagedHtml(item.html,json,item.baseHref),{

package/src/scaffold.mjs

@@ -192,21 +192,26 @@ async function prepareExistingPackage(workspaceRoot,files,existingPackage,sdkDec
     if(conflicts.length){
         fail(`Existing package.json conflicts with Arcane setup; no values were overwritten. Resolve: ${conflicts.join('; ')}.`);
     }
+    const dependencyGroup=sdkDeclaration.dependencyGroup==='optionalDependencies'
+        ?'optionalDependencies'
+        :generated.dependencies||sdkDeclaration.dependencyGroup==='dependencies'
+            ?'dependencies':'devDependencies';
     const merged={
         ...existing,
         private:true,
         type:'module',
         scripts:{...generated.scripts,...(existing.scripts||{})},
-        devDependencies:{
-            ...(existing.devDependencies||{}),
+        [dependencyGroup]:{
+            ...(existing[dependencyGroup]||{}),
             [sdkDeclaration.dependencyName]:sdkDeclaration.specifier
         },
         engines:{...generated.engines,...(existing.engines||{})}
     };
-    if(existing.dependencies?.[sdkDeclaration.dependencyName]!==undefined){
-        merged.dependencies={...existing.dependencies};
-        delete merged.dependencies[sdkDeclaration.dependencyName];
-        if(Object.keys(merged.dependencies).length===0)delete merged.dependencies;
+    if(dependencyGroup!=='devDependencies'
+        &&existing.devDependencies?.[sdkDeclaration.dependencyName]!==undefined){
+        merged.devDependencies={...existing.devDependencies};
+        delete merged.devDependencies[sdkDeclaration.dependencyName];
+        if(Object.keys(merged.devDependencies).length===0)delete merged.devDependencies;
     }
     if(JSON.stringify(existing)===JSON.stringify(merged)){
         return {exists:true,updated:false};

package/src/templates/workspace-template.mjs

@@ -159,7 +159,7 @@ appropriate.
 
 - Use plain JavaScript, HTML, and CSS; do not introduce TypeScript or TSX.
 - Keep reusable portable mechanisms in the Arcane SDK and app-specific behavior under \`${appPrefix||'./'}\`.
-- Keep \`${runtimePrefix}/css/theme.css\` before app styles and import \`arcane/ThemeBootstrap\` before app code runs.
+- Keep \`${runtimePrefix}/css/theme.css\` before app styles and import \`${directRuntime?'arcane-os/modules/ThemeBootstrap.js':'arcane/ThemeBootstrap'}\` before app code runs.
 - Use \`rgb(...)\` or \`rgba(...)\` for new CSS colors.
 - Build one named app and one explicit target at a time. Native targets may be unavailable until their adapters are installed.
 - Preserve complete application, model, document, message, log, diagnostic, process, and tool content. Do not truncate, clip, tail, elide, or silently discard it.
@@ -181,7 +181,7 @@ npm run dev
 
 Open the loopback URL printed by the development server. ${directRuntime?'This root app reads SDK files directly from its installed npm package; an ordinary static host uses the same resource paths.':'This app uses the existing physical arcane/ runtime layout.'} The SDK server does not expose an Ollama HTTP endpoint.
 
-Commit the generated \`package-lock.json\` after dependency installation. CI intentionally uses \`npm ci\` and therefore requires that lock. Before the SDK is published, install a locally packed \`${SDK_NAME}\` \`.tgz\` with \`npm install --save-dev --save-exact <path-to-tarball>\`; keep that tarball at the lock file's relative path for repeatable local \`npm ci\` runs.
+Commit the generated \`package-lock.json\` after dependency installation. CI intentionally uses \`npm ci\` and therefore requires that lock. ${directRuntime?'The SDK is a runtime dependency: keep it installed when serving this app directly from node_modules. ':''}Before the SDK is published, install a locally packed \`${SDK_NAME}\` \`.tgz\` with \`npm install ${directRuntime?'--save-prod':'--save-dev'} --save-exact <path-to-tarball>\`; keep that tarball at the lock file's relative path for repeatable local \`npm ci\` runs.
 
 ## Optional browser release commands
 
@@ -199,7 +199,7 @@ import map in every directly navigable descriptor-admitted \`.html\`/\`.htm\`
 document. HTML component fragments remain package files but do not receive a
 document-level base or managed import map.
 Development, package, and build refresh that shared inventory when the selected operation needs it.
-Named \`arcane/*\` imports resolve through the managed map to the selected SDK files. Packaging copies the complete selected application, runtime, and specifier
+Named \`${directRuntime?'arcane-os/modules/* and arcane-os/entities/*':'arcane/*'}\` imports resolve through the managed map to the selected SDK files. Packaging copies the complete selected application, runtime, and specifier
 map to \`dist/${appId}\` without running application tests. Run \`verify\` only when
 the user explicitly selects verification or a release artifact that requires it;
 \`bundle\` creates the distributable archive and \`run\` launches the selected
@@ -231,7 +231,7 @@ Every browser release also carries Arcane OS licensing material under \`${direct
                 'run:browser':'arcane run --target browser'
             }:{})
         },
-        devDependencies:{
+        [directRuntime?'dependencies':'devDependencies']:{
             [sdkDependencyName]:sdkDependencySpecifier
         },
         engines:{node:'>=22.23.2'}
@@ -369,9 +369,11 @@ ${bootstrapMarkup}</head>
         files.set(`${appPrefix}modules/arcane.importmap.json`,json({imports:{}}));
     }
     const themeSpecifier=namedImports
-        ?'arcane/ThemeBootstrap':`${appsRoot==='.'?'../':'../../../'}${runtimePrefix.slice(2)}/modules/ThemeBootstrap.js`;
+        ?directRuntime?'arcane-os/modules/ThemeBootstrap.js':'arcane/ThemeBootstrap'
+        :`${appsRoot==='.'?'../':'../../../'}${runtimePrefix.slice(2)}/modules/ThemeBootstrap.js`;
     const appDataSpecifier=namedImports
-        ?'arcane/AppDataScope':`${appsRoot==='.'?'../':'../../../'}${runtimePrefix.slice(2)}/modules/AppDataScope.js`;
+        ?directRuntime?'arcane-os/app-data-scope':'arcane/AppDataScope'
+        :`${appsRoot==='.'?'../':'../../../'}${runtimePrefix.slice(2)}/modules/AppDataScope.js`;
     const strongTypeSpecifier=namedImports
         ?'strong-type':directRuntime?`../${sdkPackageSource}/runtime/strong-type/index.js`:'../../../arcane/dependencies/strong-type/index.js';
     files.set(`${appPrefix}modules/App.js`,`import Is from '${strongTypeSpecifier}';

package/src/workspace.mjs

@@ -117,7 +117,7 @@ export function resolveSdkPackageDeclaration(rootPackage,{
 }={}){
     if(!isObject(rootPackage))fail('package.json must contain a JSON object.');
     const candidates=[];
-    for(const groupName of ['devDependencies','dependencies']){
+    for(const groupName of ['devDependencies','dependencies','optionalDependencies']){
         const group=rootPackage[groupName];
         if(group===undefined)continue;
         if(!isObject(group))fail(`package.json ${groupName} must be a JSON object.`);