arcane-os 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # 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`
+  endpoints when generating a root-layout PWA. Both use the canonical worker
+  and current root inventory, including navigation aliases and installed npm
+  resource paths; portable output also retains deployment-relative URLs.
+- Serve those previous worker and inventory endpoints directly during SDK
+  development instead of redirecting worker-script requests. Retain ordinary
+  browser update/activation, caches, application identity and saved data.
+- Keep root layout optional and existing multi-app and Node server behavior
+  unchanged. Installed-application execution remains consumer-owned.
+
 ## 0.27.0
 
 - Add optional standalone `appsRoot: "."` discovery and `new`/`init --apps-root .`.

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.0` 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/pwa.md

@@ -59,6 +59,18 @@ authored `manifest.id` remains authoritative. Packaged default identity remains
 fragments and lead to the selected root document. No stored application data is
 rewritten by changing the layout.
 
+Root PWA generation also retains `apps/<id>/arcane-sw.js` and
+`apps/<id>/arcane-offline.json`. These are ordinary generated files served at
+their original URLs, including on a static host. The same canonical worker and
+current inventory use root resource/navigation URLs, rebased for the previous
+scope when deployed beneath a directory. An existing worker's inventory refresh
+can learn the new navigation destinations; the browser can update the worker at
+its retained script URL through normal update and activation. No cache deletion,
+forced activation, user-data migration or application-owned server handler is
+introduced. Offline clients require a later successful connection to receive
+updated files; fixture coverage does not establish a particular installed app's
+actual browser lifecycle.
+
 `offline.include` and `offline.exclude` select literal paths or directory
 prefixes from the selected emitted inventory. An omitted or empty include list
 selects that inventory; exclusions subtract from it. App files use app-relative

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.0",
+  "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/dev-server.mjs

@@ -1081,7 +1081,10 @@ async function startOwnedDevServer({
                 navigationAliases,
                 basePath: '/',
                 appBase,
-                ...(rootApp ? {installationId:`/apps/${routeSet.appId}/`} : {}),
+                ...(rootApp ? {
+                    installationId:`/apps/${routeSet.appId}/`,
+                    legacyAppPath:`apps/${routeSet.appId}`
+                } : {}),
                 runtimeBase: selectedRoutes.browserRuntimeBase
                     ?? selectedRoutes.installed?.browserRuntimeBase ?? '/arcane/sdk/',
                 mode: 'development'
@@ -1109,8 +1112,8 @@ async function startOwnedDevServer({
             pwaStates.set(selectedRoutes, state);
             if (selectedRoutes === currentSourceRoutes) currentPwaState = state;
         }
-        if (targetPath === '/arcane-sw.js'
-            || targetPath === '/arcane-offline.json') {
+        if (targetPath.endsWith('/arcane-sw.js')
+            || targetPath.endsWith('/arcane-offline.json')) {
             if (!state.inventoryTask) {
                 // Timestamp selection before traversal, so an older snapshot
                 // finishing later cannot acquire a newer HTTP modification date.
@@ -1173,10 +1176,13 @@ async function startOwnedDevServer({
             const target=parseRequestTarget(request.url);
             if(!target){deny(response,400,'Invalid request path.');return;}
             const {segments}=target;
-            const generatedPwaPath = ['/arcane.webmanifest', '/arcane-offline.json', '/arcane-sw.js', '/arcane-pwa.mjs']
-                .includes(target.path);
             const legacyAppRequest = mode === 'source' && routeSet.config.appsRoot === '.'
                 && segments[0] === 'apps' && segments[1] === routeSet.appId;
+            const legacyPwaRequest = legacyAppRequest && segments.length === 3
+                && ['arcane-sw.js', 'arcane-offline.json'].includes(segments[2]);
+            const generatedPwaPath = legacyPwaRequest
+                || ['/arcane.webmanifest', '/arcane-offline.json', '/arcane-sw.js', '/arcane-pwa.mjs']
+                    .includes(target.path);
             const requestedMapping = currentSourceRoutes.mappings.find(function currentRequestMapping(route) {
                 return route.prefix.every(function currentRequestSegment(segment,index) {
                     return segments[index] === segment;
@@ -1186,7 +1192,7 @@ async function startOwnedDevServer({
             const selectedRoutes = mode === 'source' && (appRequest || segments.length === 0 || generatedPwaPath)
                 ? await refreshSourceRoutes() : currentSourceRoutes;
             const pwaEnabled = mode === 'source' ? selectedRoutes.app?.pwa?.enabled === true : routeSet.pwa;
-            if (legacyAppRequest) {
+            if (legacyAppRequest && !(pwaEnabled && legacyPwaRequest)) {
                 const legacyPath = target.pathname.slice(`/apps/${routeSet.appId}`.length);
                 const location = !legacyPath || legacyPath === '/' || legacyPath === '/index.html'
                     ? selectedRoutes.startPath : legacyPath;

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/packager/core.mjs

@@ -757,6 +757,7 @@ async function replaceDirectory(stagingRoot,outputRoot){
 async function packageWithContext(context,options={}){
     const {signal,onEvent,browserPwa=true}=options;
     const pwaEnabled=browserPwa&&context.config.pwa?.enabled===true;
+    const legacyAppPath=context.rootConfig.appsRoot==='.'?`apps/${context.appId}`:undefined;
     const appPath=appRelativeRoot(context.rootConfig,context.appId);
     const entryPath=appPackagePath(context,context.config.entry);
     const inspected=await inspectContext(context,{signal});
@@ -775,7 +776,11 @@ async function packageWithContext(context,options={}){
                     PWA_MANIFEST_NAME,
                     PWA_OFFLINE_MANIFEST_NAME,
                     PWA_WORKER_NAME,
-                    PWA_BOOTSTRAP_NAME
+                    PWA_BOOTSTRAP_NAME,
+                    ...(legacyAppPath?[
+                        `${legacyAppPath}/${PWA_WORKER_NAME}`,
+                        `${legacyAppPath}/${PWA_OFFLINE_MANIFEST_NAME}`
+                    ]:[])
                 ]:[])
             ].sort(compareText)
         };
@@ -962,6 +967,7 @@ async function packageWithContext(context,options={}){
                 entry:packageResourceUrl(entryPath)
             },
             appPath,
+            ...(legacyAppPath?{legacyAppPath}:{}),
             ...(installed?.direct?{runtimeBase:`.${installed.browserRuntimeBase}`} : {}),
             ...(navigationAliases?{navigationAliases}:{}),
             sdkVersion:assetVersion,
@@ -974,7 +980,9 @@ async function packageWithContext(context,options={}){
                 if(inventory.has(artifact.path)){
                     fail(`Package content overlaps generated PWA file: ${artifact.path}.`);
                 }
-                await writeFile(path.join(stagingRoot,artifact.path),artifact.content,'utf8');
+                const artifactPath=path.join(stagingRoot,...artifact.path.split('/'));
+                await mkdir(path.dirname(artifactPath),{recursive:true});
+                await writeFile(artifactPath,artifact.content,'utf8');
                 files.push(artifact.path);
             }
             for(const [documentPath,document] of pwaDocumentSources){

package/src/pwa.mjs

@@ -1,5 +1,6 @@
 import Is from 'strong-type';
 import {randomUUID} from 'node:crypto';
+import path from 'node:path';
 import {createPwaWorkerScript} from './pwa-worker.mjs';
 import {versionAssetUrl} from './import-map.mjs';
 
@@ -203,6 +204,7 @@ export function createPwaArtifacts(
         runtimeBase = './arcane/sdk/',
         appBase,
         installationId,
+        legacyAppPath,
         appPath = '',
         navigationAliases,
         revision
@@ -305,18 +307,60 @@ controller.ready.catch(
     const entryAssets = {manifest: PWA_MANIFEST_NAME, bootstrap: PWA_BOOTSTRAP_NAME};
     const manifestHref = resourceUrl(basePath, entryAssets.manifest);
     const bootstrapHref = resourceUrl(basePath, entryAssets.bootstrap);
+    const generatedFiles = [
+        {path: PWA_MANIFEST_NAME, content: json(manifest)},
+        {path: PWA_OFFLINE_MANIFEST_NAME, content: json(offlineManifest)},
+        {
+            path: PWA_WORKER_NAME,
+            content: createPwaWorkerScript(offlineManifest, `${runtimeBase}pwa.mjs`)
+        },
+        {path: PWA_BOOTSTRAP_NAME, content: bootstrap}
+    ];
+    if (legacyAppPath) {
+        const directory = legacyAppPath.endsWith('/') ? legacyAppPath : `${legacyAppPath}/`;
+        const priorDirectory = new URL(resourceUrl('./', directory), 'https://arcane.invalid/').pathname;
+        // Existing registrations continue updating their own script and inventory URLs.
+        function priorScopeUrl(value) {
+            if (value.startsWith('/') || /^[A-Za-z][A-Za-z0-9+.-]*:/u.test(value)) return value;
+            const resolved = new URL(value, 'https://arcane.invalid/');
+            let relative = path.posix.relative(priorDirectory, resolved.pathname);
+            if (!relative) {
+                relative = resolved.pathname.endsWith('/')
+                    ? './'
+                    : `../${path.posix.basename(resolved.pathname)}`;
+            }
+            else {
+                if (!relative.startsWith('.')) relative = `./${relative}`;
+                if (resolved.pathname.endsWith('/') && !relative.endsWith('/')) relative += '/';
+            }
+            return `${relative}${resolved.search}${resolved.hash}`;
+        }
+        const legacyOfflineManifest = {
+            ...offlineManifest,
+            assets: [...new Set([
+                ...offlineManifest.assets.map(priorScopeUrl),
+                `./${PWA_OFFLINE_MANIFEST_NAME}`
+            ])],
+            navigationAliases: Object.fromEntries(
+                Object.entries(offlineManifest.navigationAliases).map(
+                    function priorScopeNavigation([alias, target]) {
+                        return [priorScopeUrl(alias), priorScopeUrl(target)];
+                    }
+                )
+            )
+        };
+        generatedFiles.push(
+            {
+                path: `${directory}${PWA_WORKER_NAME}`,
+                content: createPwaWorkerScript(legacyOfflineManifest, priorScopeUrl(`${runtimeBase}pwa.mjs`))
+            },
+            {path: `${directory}${PWA_OFFLINE_MANIFEST_NAME}`, content: json(legacyOfflineManifest)}
+        );
+    }
     return {
         manifest,
         offlineManifest,
-        files: [
-            {path: PWA_MANIFEST_NAME, content: json(manifest)},
-            {path: PWA_OFFLINE_MANIFEST_NAME, content: json(offlineManifest)},
-            {
-                path: PWA_WORKER_NAME,
-                content: createPwaWorkerScript(offlineManifest, `${runtimeBase}pwa.mjs`)
-            },
-            {path: PWA_BOOTSTRAP_NAME, content: bootstrap}
-        ],
+        files: generatedFiles,
         entryAssets,
         entryMarkup: `<link rel="manifest" href="${htmlAttribute(manifestHref)}">\n`
             + `<script type="module" async data-arcane-pwa src="${htmlAttribute(bootstrapHref)}"></script>\n`

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/toolchain.mjs

@@ -361,6 +361,7 @@ async function refreshRootApplicationFiles(prepared,inspected,importMap,{signal,
         basePath:'/',
         appBase:'/',
         installationId:`/apps/${appId}/`,
+        legacyAppPath:`apps/${appId}`,
         runtimeBase:installed.browserRuntimeBase,
         mode:'development',
         navigationAliases

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.`);