arcane-os 0.26.0 → 0.27.1

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';
 
@@ -202,6 +203,8 @@ export function createPwaArtifacts(
         mode = 'release',
         runtimeBase = './arcane/sdk/',
         appBase,
+        installationId,
+        legacyAppPath,
         appPath = '',
         navigationAliases,
         revision
@@ -218,7 +221,7 @@ export function createPwaArtifacts(
     // Relocating app files must not change an existing installed app's default identity.
     const installationBase = appBase ?? (mode === 'development' ? applicationBase : './');
     const manifest = {
-        id: installationBase,
+        id: installationId ?? installationBase,
         name: app.displayName,
         short_name: app.displayName,
         start_url: manifestUrl(app.entry, appPath ? basePath : applicationBase),
@@ -304,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

@@ -8,6 +8,7 @@ import {withWorkspaceOperationLock} from './workspace-operation-lock.mjs';
 import {SDK_NAME,SDK_VERSION,workspaceTemplate} from './templates/workspace-template.mjs';
 import {inspectWorkspaceProfile,resolveSdkPackageDeclaration} from './workspace.mjs';
 import {parseSemver} from './packager/core.mjs';
+import {resolveAppRoot} from './app-layout.mjs';
 
 const is = new Is(false);
 
@@ -310,6 +311,7 @@ async function runGitInit(workspaceRoot,signal,onEvent){
 export async function createWorkspace({
     targetPath,
     appId,
+    appsRoot='apps',
     displayName,
     target='browser',
     initializeGit=false,
@@ -318,6 +320,7 @@ export async function createWorkspace({
 }){
     validateInputs(appId,displayName);
     validateScaffoldTarget(target);
+    if(!['apps','.'].includes(appsRoot))fail('appsRoot must be apps or .','ARCANE_USAGE');
     if(!is.string(targetPath)||!targetPath.trim())fail('targetPath is required.','ARCANE_USAGE');
     if(!is.boolean(initializeGit))fail('initializeGit must be a boolean.','ARCANE_USAGE');
     throwIfAborted(signal);
@@ -332,20 +335,21 @@ export async function createWorkspace({
     },async workspaceOperationLease=>{
     const template=workspaceTemplate({
         appId,
+        appsRoot,
         displayName,
         target,
         appIcon:await scaffoldIcon(target)
     });
     const writtenFiles=await writeMissingFiles(workspaceRoot,template.files,{signal,onEvent});
-    const workspaceRuntime=await materializeWorkspaceRuntimeContent({
+    const workspaceRuntime=appsRoot==='.'?null:await materializeWorkspaceRuntimeContent({
         workspaceRoot,
         signal,
         onEvent
     });
-    const importMap=await generateImportMap({
+    const importMap=appsRoot==='.'?{pending:true,reason:'sdk-install-required'}:await generateImportMap({
         workspaceRoot,
         appId,
-        appRoot:path.join(workspaceRoot,'apps',appId),
+        appRoot:resolveAppRoot(workspaceRoot,{appsRoot},appId),
         workspaceOperationLease,
         signal,
         onEvent
@@ -354,6 +358,7 @@ export async function createWorkspace({
     const result={
         workspaceRoot,
         appId,
+        appsRoot,
         displayName:template.name,
         target,
         ...writtenFiles,
@@ -370,12 +375,13 @@ export async function createWorkspace({
 export async function initWorkspace({
     workspaceRoot=process.cwd(),
     appId,
+    appsRoot,
     displayName,
     target='browser',
     signal,
     onEvent
 }){
-    validateInputs(appId,displayName);
+    if(appId!==undefined)validateInputs(appId,displayName);
     validateScaffoldTarget(target);
     throwIfAborted(signal);
     const resolvedRoot=path.resolve(workspaceRoot);
@@ -389,6 +395,28 @@ export async function initWorkspace({
     },async workspaceOperationLease=>{
     const profile=await existingWorkspaceProfile(resolvedRoot);
     const workspaceMode=profile?.workspaceMode??'external';
+    const selectedAppsRoot=appsRoot??profile?.config.appsRoot??'apps';
+    if(!['apps','.'].includes(selectedAppsRoot))fail('appsRoot must be apps or .','ARCANE_USAGE');
+    if(profile&&selectedAppsRoot!==profile.config.appsRoot){
+        fail('appsRoot must match the existing workspace layout; init does not relocate an application.','ARCANE_USAGE');
+    }
+    if(workspaceMode==='integrated'&&selectedAppsRoot==='.'){
+        fail('The integrated workspace keeps applications under apps; root scaffolding selects a standalone workspace.','ARCANE_USAGE');
+    }
+    if(selectedAppsRoot==='.'){
+        let existingId;
+        try{existingId=JSON.parse(await readFile(path.join(resolvedRoot,'arcane-package.json'),'utf8')).id;}
+        catch(error){if(error?.code!=='ENOENT')throw error;}
+        if(existingId!==undefined){
+            if(appId!==undefined&&appId!==existingId){
+                fail(`The root application id is ${existingId}; init does not replace its identity.`,'ARCANE_USAGE');
+            }
+            appId=existingId;
+        }
+    }
+    appId??=path.basename(resolvedRoot).normalize('NFKD').toLowerCase()
+        .replace(/[^a-z0-9]+/gu,'-').replace(/^-+|-+$/gu,'')||'arcane-app';
+    validateInputs(appId,displayName);
     const existingPackage=workspaceMode==='external'
         ?await readExistingPackage(resolvedRoot)
         :null;
@@ -415,6 +443,7 @@ export async function initWorkspace({
         })
         :workspaceTemplate({
             appId,
+            appsRoot:selectedAppsRoot,
             displayName,
             sdkDependencyName:sdkDeclaration.dependencyName,
             sdkDependencySpecifier:sdkDeclaration.specifier,
@@ -451,17 +480,23 @@ export async function initWorkspace({
         await emit(onEvent,{type:'scaffold.file.replaced',path:'arcane.lock.json'});
     }
     const packageUpdated=await applyPackageMerge(resolvedRoot,packagePlan,{signal,onEvent});
-    const workspaceRuntime=workspaceMode==='external'
+    const directRuntime=workspaceMode==='external'&&selectedAppsRoot==='.';
+    const workspaceRuntime=workspaceMode==='external'&&!directRuntime
         ?await materializeWorkspaceRuntimeContent({
             workspaceRoot:resolvedRoot,
             signal,
             onEvent
         })
         :null;
-    const importMap=await generateImportMap({
+    let sdkInstalled=true;
+    if(directRuntime){
+        try{await lstat(path.join(resolvedRoot,sdkDeclaration.packageSource,'package.json'));}
+        catch(error){if(error?.code==='ENOENT')sdkInstalled=false;else throw error;}
+    }
+    const importMap=!sdkInstalled?{pending:true,reason:'sdk-install-required'}:await generateImportMap({
         workspaceRoot:resolvedRoot,
         appId,
-        appRoot:path.join(resolvedRoot,'apps',appId),
+        appRoot:resolveAppRoot(resolvedRoot,{appsRoot:selectedAppsRoot},appId),
         workspaceOperationLease,
         signal,
         onEvent
@@ -470,6 +505,7 @@ export async function initWorkspace({
         workspaceRoot:resolvedRoot,
         workspaceMode,
         appId,
+        appsRoot:selectedAppsRoot,
         displayName:template.name,
         target,
         ...writtenFiles,

package/src/sdk-runtime-layout.mjs

@@ -4,9 +4,9 @@ import path from 'node:path';
 
 const is=new Is(false);
 
-// The browser URLs stay the same; only the source of their files changes.
-export function installedSdkRoutes(packageSource,{security=false}={}){
-    return [
+// Direct routes use the installed npm paths in both the browser and selected output.
+export function installedSdkRoutes(packageSource,{security=false,direct=false}={}){
+    const routes=[
         {
             source:`${packageSource}/runtime/arcane`,destination:'arcane',
             include:['components','css','entities','img','modules',...(security?['security']:[])],exclude:[]
@@ -24,6 +24,7 @@ export function installedSdkRoutes(packageSource,{security=false}={}){
             include:['LICENSE','COMMERCIAL-LICENSE.md','NOTICE'],exclude:[]
         }
     ];
+    return direct?routes.map(route=>({...route,destination:route.source})):routes;
 }
 
 export function installedSdkPackageSource(config){
@@ -31,7 +32,10 @@ export function installedSdkPackageSource(config){
     if(!is.array(routes)||routes.length!==4)return null;
     const source=routes[3]?.source;
     if(!is.string(source)||!/^node_modules\/(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/u.test(source))return null;
-    const expected=installedSdkRoutes(source,{security:routes[0]?.include?.at(-1)==='security'});
+    const expected=installedSdkRoutes(source,{
+        security:routes[0]?.include?.at(-1)==='security',
+        direct:routes[0]?.destination===routes[0]?.source
+    });
     return routes.every(function matchesInstalledRoute(route,index){
         const wanted=expected[index];
         return route?.source===wanted.source&&route?.destination===wanted.destination
@@ -56,7 +60,13 @@ export async function readInstalledSdkLayout(workspaceRoot,config){
         error.code='ARCANE_WORKSPACE_INVALID';
         throw error;
     }
-    return {packageSource,packageRoot,versionPath,version:manifest.version,routes:config.sharedPayloads['browser-runtime']};
+    const routes=config.sharedPayloads['browser-runtime'];
+    return {
+        packageSource,packageRoot,versionPath,version:manifest.version,routes,
+        direct:routes[0].destination===routes[0].source,
+        runtimeBase:`/${routes[0].destination}/`,
+        browserRuntimeBase:`/${routes[1].destination}/`
+    };
 }
 
 export async function installedRuntimeFiles(workspaceRoot,layout,signal){
@@ -71,9 +81,9 @@ export async function installedRuntimeFiles(workspaceRoot,layout,signal){
             else if(entry.isFile())files.push(relative);
         }
     }
-    for(const route of layout.routes){
-        if(route.destination!=='arcane'&&!route.destination.startsWith('arcane/'))continue;
-        const prefix=route.destination==='arcane'?'':route.destination.slice('arcane/'.length);
+    for(const [index,route] of layout.routes.entries()){
+        if(index===3)continue;
+        const prefix=['','sdk','dependencies/strong-type'][index];
         for(const selected of route.include){
             const suffix=selected==='.'?'':selected;
             await visit(
@@ -85,15 +95,18 @@ export async function installedRuntimeFiles(workspaceRoot,layout,signal){
     return {files:files.sort()};
 }
 
-export function installedRuntimeTarget(relative,layout){
-    for(const route of [...layout.routes].sort(function longestDestinationFirst(left,right){
-        return right.destination.length-left.destination.length;
+export function installedRuntimeTarget(relative,layout,{browser=false}={}){
+    const logicalRoots=['arcane','arcane/sdk','arcane/dependencies/strong-type','licenses/arcane-os'];
+    const routes=layout.routes.map((route,index)=>({...route,logical:logicalRoots[index]}));
+    for(const route of routes.sort(function longestDestinationFirst(left,right){
+        return right.logical.length-left.logical.length;
     })){
-        if(!relative.startsWith(`${route.destination}/`))continue;
-        const suffix=relative.slice(route.destination.length+1);
+        if(!relative.startsWith(`${route.logical}/`))continue;
+        const suffix=relative.slice(route.logical.length+1);
         if(route.include.some(function includesRuntimeTarget(selected){
-            return selected==='.'||suffix===selected||suffix.startsWith(`${selected}/`);
-        }))return `${route.source}/${suffix}`;
+            const pathname=suffix.split(/[?#]/u)[0];
+            return selected==='.'||pathname===selected||pathname.startsWith(`${selected}/`);
+        }))return `${browser?route.destination:route.source}/${suffix}`;
     }
     return relative;
 }

package/src/templates/workspace-template.mjs

@@ -1,4 +1,5 @@
 import Is from 'strong-type';
+import {installedSdkRoutes} from '../sdk-runtime-layout.mjs';
 import {
     ARCANE_PROTOCOL,
     CLI_EVENT_PROTOCOL,
@@ -59,6 +60,7 @@ export function createWorkspaceLockDocument({
 
 export function workspaceTemplate({
     appId,
+    appsRoot='apps',
     displayName,
     sdkDependencyName=SDK_NAME,
     sdkDependencySpecifier=SDK_VERSION,
@@ -86,6 +88,12 @@ export function workspaceTemplate({
     if(!supportedTargets.includes(target)){
         throw new Error(`Unsupported scaffold target: ${String(target)}.`);
     }
+    if(!['apps','.'].includes(appsRoot))throw new Error('appsRoot must be apps or .');
+    if(appOnly&&appsRoot==='.')throw new Error('Root scaffolding selects a standalone workspace.');
+    const appPrefix=appsRoot==='.'?'':`apps/${appId}/`;
+    const directRuntime=appsRoot==='.'&&!appOnly;
+    const runtimePrefix=directRuntime?`./${sdkPackageSource}/runtime/arcane`:'./arcane';
+    const baseHref=appsRoot==='.'?'./':'../../';
     const native=target!=='browser';
     const buildTarget=native?target:'browser';
     const runTarget=native&&target!=='portable'?target:'browser';
@@ -125,7 +133,7 @@ appropriate.
     </script>
 `:'';
     const bootstrapMarkup=namedImports?'':
-        '    <script type="module" src="./arcane/modules/ThemeBootstrap.js?v=1"></script>\n';
+        `    <script type="module" src="${runtimePrefix}/modules/ThemeBootstrap.js?v=1"></script>\n`;
     const files=new Map();
     files.set('.gitignore',[
         'node_modules/',
@@ -150,8 +158,8 @@ appropriate.
     files.set('AGENTS.md',`# ${name} development instructions
 
 - 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 \`apps/${appId}/\`.
-- Keep \`arcane/css/theme.css\` before app styles and import \`arcane/ThemeBootstrap\` before app code runs.
+- 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.
 - 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.
@@ -167,10 +175,11 @@ This repository contains the portable Arcane application \`${appId}\`. It includ
 
 \`\`\`sh
 npm install
+npm run import-map
 npm run dev
 \`\`\`
 
-Open the loopback URL printed by the development server. The source server exposes this app and its physical \`arcane/\` runtime; it does not expose an Ollama HTTP endpoint.
+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.
 
@@ -185,13 +194,12 @@ npm run run
 \`\`\`
 
 The explicit \`import-map\` command refreshes
-\`apps/${appId}/modules/arcane.importmap.json\` and the managed inline browser
+\`${appPrefix}modules/arcane.importmap.json\` and the managed inline browser
 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 against the physical workspace \`arcane/\`
-tree. Packaging copies the complete selected application, runtime, and specifier
+Named \`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
@@ -201,7 +209,7 @@ Native targets are provider-supplied and must be scaffolded and selected
 explicitly; this browser workflow does not imply a standalone native executable.
 ${nativeGuide}
 
-Every browser release also carries Arcane OS licensing material under \`licenses/arcane-os/\`. Review those terms before distribution.
+Every browser release also carries Arcane OS licensing material under \`${directRuntime?sdkPackageSource:'licenses/arcane-os'}\`. Review those terms before distribution.
 `);
     files.set('package.json',json({
         name:packageName,
@@ -230,10 +238,10 @@ Every browser release also carries Arcane OS licensing material under \`licenses
     }));
     files.set('arcane-packager.json',json({
         schemaVersion:1,
-        appsRoot:'apps',
+        appsRoot,
         distRoot:'dist',
         sharedPayloads:{
-            'browser-runtime':[
+            'browser-runtime':directRuntime?installedSdkRoutes(sdkPackageSource,{direct:true}):[
                 {
                     source:'arcane',
                     destination:'arcane',
@@ -249,11 +257,11 @@ Every browser release also carries Arcane OS licensing material under \`licenses
             ]
         }
     }));
-    files.set('arcane.lock.json',json(createWorkspaceLockDocument({
+    if(!directRuntime)files.set('arcane.lock.json',json(createWorkspaceLockDocument({
         dependencyName:sdkDependencyName,
         packageSource:sdkPackageSource
     })));
-    files.set(`apps/${appId}/arcane-app.json`,json({
+    files.set(`${appPrefix}arcane-app.json`,json({
         schemaVersion:2,
         id:appId,
         displayName:name,
@@ -283,7 +291,7 @@ Every browser release also carries Arcane OS licensing material under \`licenses
         },
         targets:native?['browser',target].sort():['browser']
     }));
-    files.set(`apps/${appId}/arcane-package.json`,json({
+    files.set(`${appPrefix}arcane-package.json`,json({
         schemaVersion:1,
         id:appId,
         displayName:name,
@@ -294,7 +302,7 @@ Every browser release also carries Arcane OS licensing material under \`licenses
         exclude:[],
         shared:['browser-runtime']
     }));
-    files.set(`apps/${appId}/manifest.json`,json({
+    files.set(`${appPrefix}manifest.json`,json({
         name,
         short_name:titleCase(appId),
         start_url:'./index.html',
@@ -303,19 +311,19 @@ Every browser release also carries Arcane OS licensing material under \`licenses
         theme_color:'rgb(23, 34, 56)',
         icons:[]
     }));
-    files.set(`apps/${appId}/index.html`,`<!doctype html>
+    files.set(`${appPrefix}index.html`,`<!doctype html>
 <html lang="en">
 <head>
     <meta charset="utf-8">
     <meta name="arcane-app-id" content="${html(appId)}">
-    <base href="../../">
+    <base href="${baseHref}">
 ${importMapMarkup}    <meta name="viewport" content="width=device-width, initial-scale=1">
     <meta name="theme-color" content="rgb(23, 34, 56)">
     <title>${html(name)}</title>
-    <link rel="manifest" href="./apps/${html(appId)}/manifest.json">
-    <link rel="stylesheet" href="./arcane/css/theme.css?v=1">
-    <link rel="stylesheet" href="./arcane/css/primitives.css?v=1">
-    <link rel="stylesheet" href="./apps/${html(appId)}/${html(appId)}.css?v=1">
+    <link rel="manifest" href="./${html(appPrefix)}manifest.json">
+    <link rel="stylesheet" href="${runtimePrefix}/css/theme.css?v=1">
+    <link rel="stylesheet" href="${runtimePrefix}/css/primitives.css?v=1">
+    <link rel="stylesheet" href="./${html(appPrefix)}${html(appId)}.css?v=1">
 ${bootstrapMarkup}</head>
 <body>
     <main class="app-shell">
@@ -332,11 +340,11 @@ ${bootstrapMarkup}</head>
             </div>
         </section>
     </main>
-    <script type="module" src="./apps/${html(appId)}/modules/App.js?v=1"></script>
+    <script type="module" src="./${html(appPrefix)}modules/App.js?v=1"></script>
 </body>
 </html>
 `);
-    files.set(`apps/${appId}/${appId}.css`,`body {
+    files.set(`${appPrefix}${appId}.css`,`body {
     margin: 0;
     min-height: 100vh;
     background: var(--background, rgb(13, 18, 32));
@@ -358,15 +366,15 @@ ${bootstrapMarkup}</head>
 }
 `);
     if(namedImports){
-        files.set(`apps/${appId}/modules/arcane.importmap.json`,json({imports:{}}));
+        files.set(`${appPrefix}modules/arcane.importmap.json`,json({imports:{}}));
     }
     const themeSpecifier=namedImports
-        ?'arcane/ThemeBootstrap':'../../../arcane/modules/ThemeBootstrap.js';
+        ?'arcane/ThemeBootstrap':`${appsRoot==='.'?'../':'../../../'}${runtimePrefix.slice(2)}/modules/ThemeBootstrap.js`;
     const appDataSpecifier=namedImports
-        ?'arcane/AppDataScope':'../../../arcane/modules/AppDataScope.js';
+        ?'arcane/AppDataScope':`${appsRoot==='.'?'../':'../../../'}${runtimePrefix.slice(2)}/modules/AppDataScope.js`;
     const strongTypeSpecifier=namedImports
-        ?'strong-type':'../../../arcane/dependencies/strong-type/index.js';
-    files.set(`apps/${appId}/modules/App.js`,`import Is from '${strongTypeSpecifier}';
+        ?'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}';
 import arcaneThemeReady from '${themeSpecifier}';
 import {
     resolveApplicationId,
@@ -407,9 +415,9 @@ action?.addEventListener('click',()=>{
 });
 `);
     if(native){
-        files.set(`apps/${appId}/img/icon.png`,Buffer.from(appIcon));
+        files.set(`${appPrefix}img/icon.png`,Buffer.from(appIcon));
     }
-    files.set(`apps/${appId}/test/app.test.mjs`,`import assert from 'node:assert/strict';
+    files.set(`${appPrefix}test/app.test.mjs`,`import assert from 'node:assert/strict';
 import {readFile} from 'node:fs/promises';
 import test from '${SDK_NAME}/testing';
 
@@ -420,13 +428,13 @@ test('application shell uses the shared Arcane theme in order',async()=>{
         readFile(new URL('index.html',appRoot),'utf8'),
         readFile(new URL('modules/App.js',appRoot),'utf8')
     ]);
-    const theme=source.indexOf('./arcane/css/theme.css');
-    const primitives=source.indexOf('./arcane/css/primitives.css');
-    const appStyle=source.indexOf('./apps/${appId}/${appId}.css');
-    const importMap=source.indexOf('${namedImports?'data-arcane-import-map':'./arcane/modules/ThemeBootstrap.js'}');
-    const appModule=source.indexOf('./apps/${appId}/modules/App.js');
+    const theme=source.indexOf('${runtimePrefix}/css/theme.css');
+    const primitives=source.indexOf('${runtimePrefix}/css/primitives.css');
+    const appStyle=source.indexOf('./${appPrefix}${appId}.css');
+    const importMap=source.indexOf('${namedImports?'data-arcane-import-map':`${runtimePrefix}/modules/ThemeBootstrap.js`}');
+    const appModule=source.indexOf('./${appPrefix}modules/App.js');
 
-    assert.match(source,/<base href="\\.\\.\\/\\.\\.\\/">/);
+    assert.ok(source.includes('<base href="${baseHref}">'));
     assert.match(source,/<meta name="arcane-app-id" content="${appId}">/);
     assert.ok(theme>=0&&primitives>theme&&appStyle>primitives);
     assert.ok(importMap>=0&&appModule>importMap);
@@ -445,7 +453,7 @@ test('application package identity matches its directory',async()=>{
     if(appOnly){
         return {
             name,
-            files:new Map([...files].filter(([relative])=>relative.startsWith(`apps/${appId}/`)))
+            files:new Map([...files].filter(([relative])=>relative.startsWith(`${appPrefix}`)))
         };
     }
     return {name,files};

package/src/toolchain.mjs

@@ -1,6 +1,6 @@
 import Is from 'strong-type';
 import path from 'node:path';
-import {readdir,lstat,realpath} from 'node:fs/promises';
+import {readdir,lstat,realpath,mkdir,readFile,writeFile} from 'node:fs/promises';
 import {createWorkspace,initWorkspace} from './scaffold.mjs';
 import {
     discoverApps as discoverWorkspaceApps,
@@ -11,7 +11,10 @@ import {
 } from './workspace.mjs';
 import {loadArcaneIntegratedProvider} from './integrated-provider-loader.mjs';
 import {startDevServer} from './dev-server.mjs';
-import {generateImportMap,readApplicationTestImportMapContext} from './import-map.mjs';
+import {applyPwaEntryReferences,generateImportMap,readApplicationTestImportMapContext} from './import-map.mjs';
+import {rootAppNavigation} from './app-layout.mjs';
+import {createPwaArtifacts} from './pwa.mjs';
+import {readInstalledSdkLayout} from './sdk-runtime-layout.mjs';
 import {withWorkspaceOperationLock} from './workspace-operation-lock.mjs';
 import {refreshAppPackageProjection} from './app-descriptor.mjs';
 import {
@@ -303,7 +306,7 @@ async function refreshPreparedImportMap(prepared,{signal,onEvent,workspaceOperat
             'The selected application package descriptor changed before import-map refresh.'
         );
     }
-    return generateImportMap({
+    const importMap=await generateImportMap({
         workspaceRoot:prepared.workspaceRoot,
         appId:prepared.appId,
         appRoot:prepared.appRoot,
@@ -315,6 +318,76 @@ async function refreshPreparedImportMap(prepared,{signal,onEvent,workspaceOperat
         signal,
         onEvent
     });
+    if(prepared.validation.config.appsRoot==='.'){
+        await refreshRootApplicationFiles(prepared,inspected,importMap,{signal,onEvent});
+    }
+    return importMap;
+}
+
+async function refreshRootApplicationFiles(prepared,inspected,importMap,{signal,onEvent}){
+    const {workspaceRoot,appId}=prepared;
+    const manifest=prepared.validation.app.manifest;
+    const navigation=rootAppNavigation(appId,manifest.entry,inspected.browserDocuments.map(document=>document.path));
+    // These aliases belong to the SDK only after generation; retained app files stay authored.
+    for(const redirect of navigation){
+        throwIfAborted(signal);
+        try{
+            const current=await readFile(path.join(workspaceRoot,...redirect.path.split('/')),'utf8');
+            if(!current.includes('<!-- Arcane root application navigation -->')){
+                throw new ArcaneError(ERROR_CODES.workspaceInvalid,
+                    `Root application navigation would replace authored content: ${redirect.path}.`);
+            }
+        }catch(error){if(error.code!=='ENOENT')throw error;}
+    }
+    const installed=await readInstalledSdkLayout(workspaceRoot,prepared.validation.config);
+    const entry=`/${manifest.entry.split('/').map(encodeURIComponent).join('/')}`;
+    const navigationAliases={
+        '/':entry,
+        [`/apps/${appId}`]:entry,
+        [`/apps/${appId}/`]:entry,
+        ...Object.fromEntries(navigation.map(redirect=>[`/${redirect.path}`,redirect.target]))
+    };
+    // The source host serves the installed files in place. There is no runtime projection.
+    const files=[...new Set([
+        ...inspected.files.filter(file=>file!=='index.html'||manifest.include.includes('index.html')),
+        importMap.artifactRelativePath,
+        ...navigation.map(redirect=>redirect.path)
+    ])];
+    const pwa=installed?.direct&&manifest.pwa?.enabled?createPwaArtifacts({
+        app:{id:appId,displayName:manifest.displayName,version:manifest.version,entry},
+        sdkVersion:installed.version,
+        pwa:manifest.pwa,
+        files,
+        basePath:'/',
+        appBase:'/',
+        installationId:`/apps/${appId}/`,
+        legacyAppPath:`apps/${appId}`,
+        runtimeBase:installed.browserRuntimeBase,
+        mode:'development',
+        navigationAliases
+    }):null;
+    for(const file of [...navigation,...(pwa?.files??[])]){
+        throwIfAborted(signal);
+        const filePath=path.join(workspaceRoot,...file.path.split('/'));
+        await mkdir(path.dirname(filePath),{recursive:true});
+        await writeFile(filePath,file.content,'utf8');
+    }
+    if(pwa){
+        for(const document of inspected.browserDocuments){
+            throwIfAborted(signal);
+            const filePath=path.join(prepared.appRoot,...document.path.split('/'));
+            const content=await readFile(filePath,'utf8');
+            await writeFile(filePath,applyPwaEntryReferences(content,{
+                manifestUrl:`/${pwa.entryAssets.manifest}`,
+                bootstrapUrl:`/${pwa.entryAssets.bootstrap}`
+            }),'utf8');
+        }
+    }
+    await emit(onEvent,{
+        type:'import-map.root-files.completed',appId,
+        navigation:navigation.map(redirect=>redirect.path),
+        pwa:pwa?.files.map(file=>file.path)??[]
+    });
 }
 
 async function importMapApplication(options={}){