arcane-os 0.26.0 → 0.27.0

package/src/dev-server.mjs

@@ -6,6 +6,7 @@ import https from 'node:https';
 import os from 'node:os';
 import path from 'node:path';
 import {resolveWorkspace} from './workspace.mjs';
+import {appRelativeRoot} from './app-layout.mjs';
 import {readInstalledSdkLayout} from './sdk-runtime-layout.mjs';
 import {APP_DESCRIPTOR_NAME, projectPackageManifest} from './app-descriptor.mjs';
 import {APP_CONFIG_NAME, validateAppConfig} from './packager/core.mjs';
@@ -97,7 +98,7 @@ function parseRequestTarget(rawUrl){
     let parsed;
     try{parsed=new URL(raw,'http://127.0.0.1');}
     catch{return null;}
-    return {segments,path:decoded,searchParams:parsed.searchParams};
+    return {segments,path:decoded,pathname:parsed.pathname,search:parsed.search,searchParams:parsed.searchParams};
 }
 
 function resolveInside(root,segments){
@@ -450,7 +451,8 @@ async function sourceRoutes(workspaceRoot,appId,{
 }){
     const resolved=await resolveWorkspace({workspaceRoot,appId});
     const appMapping={
-        prefix:['apps',resolved.appId],
+        kind:'app',
+        prefix:appRelativeRoot(resolved.config,resolved.appId).split('/').filter(Boolean),
         root:resolved.appRoot,
         include:resolved.app.manifest.include,
         allow:relative=>sourcePathAllowed(relative,resolved.app.manifest)
@@ -462,15 +464,24 @@ async function sourceRoutes(workspaceRoot,appId,{
             resolved.appId,
             {signal,onEvent}
         );
+        const installedRoutes=resolved.config.browserRuntimeLayout==='installed-v1'
+            ?resolved.config.sharedPayloads['browser-runtime']:null;
+        const sourceMappings=installedRoutes?sdkSource.mappings.map(
+            function selectLiveSourceDestination(mapping,index){
+                const route=installedRoutes[[0,2,1][index]];
+                return {...mapping,prefix:route.destination.split('/')};
+            }
+        ):sdkSource.mappings;
         return {
             workspaceRoot:resolved.workspaceRoot,
             workspaceMode:resolved.config.workspaceMode,
             config:resolved.config,
             appId:resolved.appId,
             app:resolved.app.manifest,
-            startPath:`/apps/${resolved.appId}/${resolved.app.manifest.entry}`,
+            startPath:applicationSourcePath(resolved.config,resolved.appId,resolved.app.manifest.entry),
             runtime:sdkSource.runtime,
-            mappings:[appMapping,...sdkSource.mappings]
+            ...(installedRoutes?{browserRuntimeBase:`/${installedRoutes[1].destination}/`}:{}),
+            mappings:[appMapping,...sourceMappings]
         };
     }
     if(resolved.config.workspaceMode==='integrated'
@@ -485,7 +496,7 @@ async function sourceRoutes(workspaceRoot,appId,{
             ...(installed?{installed}:{}),
             appId:resolved.appId,
             app:resolved.app.manifest,
-            startPath:`/apps/${resolved.appId}/${resolved.app.manifest.entry}`,
+            startPath:applicationSourcePath(resolved.config,resolved.appId,resolved.app.manifest.entry),
             mappings:[
                 appMapping,
                 ...resolved.config.sharedPayloads['browser-runtime'].map(route=>({
@@ -504,7 +515,7 @@ async function sourceRoutes(workspaceRoot,appId,{
         config:resolved.config,
         appId:resolved.appId,
         app:resolved.app.manifest,
-        startPath:`/apps/${resolved.appId}/${resolved.app.manifest.entry}`,
+        startPath:applicationSourcePath(resolved.config,resolved.appId,resolved.app.manifest.entry),
         mappings:[
             appMapping,
             {
@@ -517,6 +528,11 @@ async function sourceRoutes(workspaceRoot,appId,{
     };
 }
 
+function applicationSourcePath(config,appId,relative='') {
+    const root=appRelativeRoot(config,appId);
+    return `/${root?`${root}/`:''}${relative}`;
+}
+
 async function packagedRoutes(releaseRoot){
     if(!is.string(releaseRoot)||!releaseRoot.trim())fail('releaseRoot is required in packaged mode.','ARCANE_USAGE');
     const requested=path.resolve(releaseRoot);
@@ -578,8 +594,7 @@ async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourc
             } else if (info.isFile()) {
                 const segments = [...mapping.prefix, ...relative];
                 const url = `/${segments.map(encodeURIComponent).join('/')}`;
-                const appResource = mapping.prefix[0] === 'apps'
-                    && mapping.prefix[1] === routeSet.appId;
+                const appResource = mapping.kind === 'app';
                 const logical = (appResource ? relative : segments).join('/');
                 records.set(logical, url);
                 resources.set(url, {mapping, relative});
@@ -597,7 +612,7 @@ async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourc
     for (const selected of routeSet.app.include) {
         if (!/\.html?$/iu.test(selected)) continue;
         const url = new URL(
-            `/apps/${routeSet.appId}/${selected.split('/').map(encodeURIComponent).join('/')}`,
+            applicationSourcePath(routeSet.config,routeSet.appId,selected.split('/').map(encodeURIComponent).join('/')),
             origin
         );
         pending.push({url, documentUrl: url});
@@ -636,8 +651,8 @@ async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourc
         const documentUrl = authoredBase ? new URL(authoredBase, current.url) : current.documentUrl;
         if (!runtimeRootsAdded && pathname === entryUrl.pathname) {
             runtimeRootsAdded = true;
-            for (const url of resources.keys()) {
-                if (/^\/arcane\/.*\.(?:m?js|html?|css)$/iu.test(url)
+            for (const [url, resource] of resources) {
+                if ((resource.mapping.kind !== 'app' && /\.(?:m?js|html?|css)$/iu.test(url))
                     || path.posix.basename(url) === 'arcane.importmap.json') {
                     pending.push({url: new URL(url, origin), documentUrl});
                 }
@@ -966,7 +981,7 @@ async function startOwnedDevServer({
     let sourceManifestTask;
     const appMapping = mappings.find(
         function selectedApplicationMapping(mapping) {
-            return mapping.prefix[0] === 'apps' && mapping.prefix[1] === routeSet.appId;
+            return mapping.kind === 'app';
         }
     );
     async function refreshSourceRoutes() {
@@ -1017,7 +1032,7 @@ async function startOwnedDevServer({
         currentSourceRoutes = {
             ...routeSet,
             app: manifest,
-            startPath: `/apps/${routeSet.appId}/${manifest.entry}`,
+            startPath: applicationSourcePath(routeSet.config,routeSet.appId,manifest.entry),
             mappings: mappings.map(
                 function currentSourceMapping(mapping) {
                     return mapping === appMapping ? currentAppMapping : mapping;
@@ -1031,6 +1046,26 @@ async function startOwnedDevServer({
     let currentPwaState;
     const pwaResourceUrls = new Set();
     function developmentPwaArtifacts(selectedRoutes, assets = [], version = assetVersion) {
+        const rootApp = selectedRoutes.config.appsRoot === '.';
+        const appBase = applicationSourcePath(selectedRoutes.config,selectedRoutes.appId);
+        const navigationAliases = {'/': selectedRoutes.startPath};
+        if (rootApp) {
+            const legacyBase = `/apps/${selectedRoutes.appId}`;
+            navigationAliases[legacyBase] = selectedRoutes.startPath;
+            navigationAliases[`${legacyBase}/`] = selectedRoutes.startPath;
+            for (const asset of [selectedRoutes.startPath,...assets]) {
+                const pathname = new URL(asset,'http://arcane.invalid').pathname;
+                if (!/\.html?$/iu.test(pathname)) continue;
+                const segments = decodeURIComponent(pathname).split('/').filter(Boolean);
+                const mapping = selectedRoutes.mappings.find(function matchingNavigationRoute(route) {
+                    return route.prefix.every(function matchingNavigationSegment(segment,index) {
+                        return segments[index] === segment;
+                    });
+                });
+                if (mapping?.kind === 'app') navigationAliases[`${legacyBase}${pathname}`] = pathname;
+            }
+            navigationAliases[`${legacyBase}/index.html`] = selectedRoutes.startPath;
+        }
         return createPwaArtifacts(
             {
                 app: {
@@ -1043,10 +1078,12 @@ async function startOwnedDevServer({
                 pwa: selectedRoutes.app.pwa,
                 files: [],
                 assets,
-                navigationAliases: {'/': selectedRoutes.startPath},
+                navigationAliases,
                 basePath: '/',
-                appBase: `/apps/${routeSet.appId}/`,
-                runtimeBase: '/arcane/sdk/',
+                appBase,
+                ...(rootApp ? {installationId:`/apps/${routeSet.appId}/`} : {}),
+                runtimeBase: selectedRoutes.browserRuntimeBase
+                    ?? selectedRoutes.installed?.browserRuntimeBase ?? '/arcane/sdk/',
                 mode: 'development'
             }
         );
@@ -1138,10 +1175,25 @@ async function startOwnedDevServer({
             const {segments}=target;
             const generatedPwaPath = ['/arcane.webmanifest', '/arcane-offline.json', '/arcane-sw.js', '/arcane-pwa.mjs']
                 .includes(target.path);
-            const appRequest = segments[0] === 'apps' && segments[1] === routeSet.appId;
+            const legacyAppRequest = mode === 'source' && routeSet.config.appsRoot === '.'
+                && segments[0] === 'apps' && segments[1] === routeSet.appId;
+            const requestedMapping = currentSourceRoutes.mappings.find(function currentRequestMapping(route) {
+                return route.prefix.every(function currentRequestSegment(segment,index) {
+                    return segments[index] === segment;
+                });
+            });
+            const appRequest = requestedMapping?.kind === 'app' || legacyAppRequest;
             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) {
+                const legacyPath = target.pathname.slice(`/apps/${routeSet.appId}`.length);
+                const location = !legacyPath || legacyPath === '/' || legacyPath === '/index.html'
+                    ? selectedRoutes.startPath : legacyPath;
+                response.writeHead(302,{location:`${location}${target.search}`});
+                response.end();
+                return;
+            }
             if (mode === 'source' && pwaEnabled
                 && generatedPwaPath) {
                 const generated = await sourcePwaArtifact(target.path, selectedRoutes);
@@ -1163,7 +1215,7 @@ async function startOwnedDevServer({
                 return;
             }
             if(segments.length===0){
-                response.writeHead(302,{location:selectedRoutes.startPath});
+                response.writeHead(302,{location:`${selectedRoutes.startPath}${target.search}`});
                 response.end();
                 return;
             }
@@ -1195,7 +1247,7 @@ async function startOwnedDevServer({
                 const extension=path.extname(opened.candidate).toLowerCase();
                 const html=extension==='.html'||extension==='.htm';
                 const selectedPwaDocument = mode === 'source' && pwaEnabled && html
-                    && mapping.prefix[0] === 'apps' && mapping.prefix[1] === routeSet.appId
+                    && mapping.kind === 'app'
                     && selectedRoutes.app.include.includes(relative.join('/'));
                 const selectedDocument = target.path === selectedRoutes.startPath || selectedPwaDocument;
                 const managedDocument = !selectedDocument && html && await isManagedDocument(opened);
@@ -1204,7 +1256,7 @@ async function startOwnedDevServer({
                 // A live server can span an SDK upgrade. Refresh the small
                 // version record on navigation, not on each resource request.
                 if(entryDocument||managedMap)rememberAssetVersion(await selectedAssetVersion());
-                const runtimeResource=segments[0]==='arcane';
+                const runtimeResource=mapping.kind!=='app';
                 const browserResource=['script','style','worker','sharedworker','serviceworker']
                     .includes(request.headers['sec-fetch-dest']);
                 const rewrite=runtimeResource||entryDocument||browserResource||managedMap

package/src/import-map.mjs

@@ -1,4 +1,5 @@
 import Is from 'strong-type';
+import {appBaseHref,resolveAppRoot} from './app-layout.mjs';
 import {lstat,mkdir,readFile as readFileFromDisk,readdir,realpath,writeFile} from 'node:fs/promises';
 import path from 'node:path';
 import {pathToFileURL} from 'node:url';
@@ -1459,6 +1460,20 @@ async function managedImportMapBuild(resolvedWorkspace,signal,pwaEnabled=false){
         pwaEnabled?null:installed?.version??readWorkspaceAssetVersion(resolvedWorkspace)
     ]);
     const built=await buildImportMap({files:runtime.files,signal,version});
+    if(installed?.direct){
+        const imports={};
+        function installedBrowserUrl(value){
+            return value.startsWith('./')
+                ?`./${installedRuntimeTarget(value.slice(2),installed,{browser:true})}`:value;
+        }
+        for(const [specifier,target] of Object.entries(built.imports)){
+            const selected=installedBrowserUrl(target);
+            imports[specifier]=selected;
+            // Relative module imports and bare names must resolve to the same instance.
+            imports[installedBrowserUrl(specifier)]=selected;
+        }
+        built.imports=imports;
+    }
     const json=`${JSON.stringify({imports:built.imports},null,2).replaceAll('<','\\u003c')}\n`;
     return {built,json,version};
 }
@@ -2178,12 +2193,6 @@ export function inspectImportMapHtml(html){
     };
 }
 
-function documentBaseHref(relative){
-    const directory=path.posix.dirname(relative);
-    const depth=directory==='.'?0:directory.split('/').length;
-    return '../'.repeat(depth+2);
-}
-
 function renderManagedHtml(html,json,baseHref='../../'){
     const structure=scanHtmlStructure(html);
     const activeBases=structure.bases.map(base=>({
@@ -2340,11 +2349,18 @@ async function writeGeneratedFiles({root,files,signal,onEvent}){
     return eventError;
 }
 
-function resolvedAppRoot(workspaceRoot,appId,appRoot){
+async function resolvedAppRoot(workspaceRoot,appId,appRoot){
     if(!is.string(appId)||appId.trim()===''){
         throw new TypeError('Import-map app id must be a nonempty string.');
     }
-    const resolved=path.resolve(appRoot??path.join(workspaceRoot,'apps',appId));
+    let selected=appRoot;
+    if(selected===undefined){
+        let config={appsRoot:'apps'};
+        try{config=JSON.parse(await readFileFromDisk(path.join(workspaceRoot,'arcane-packager.json'),'utf8'));}
+        catch(error){if(error?.code!=='ENOENT')throw error;}
+        selected=resolveAppRoot(workspaceRoot,config,appId);
+    }
+    const resolved=path.resolve(selected);
     if(!pathInside(workspaceRoot,resolved))fail('Import-map application root must stay inside the workspace.');
     return resolved;
 }
@@ -2789,7 +2805,7 @@ async function generateImportMapUnlocked({
     }
     throwIfAborted(signal);
     const resolvedWorkspace=path.resolve(workspaceRoot);
-    const resolvedApp=resolvedAppRoot(resolvedWorkspace,appId,appRoot);
+    const resolvedApp=await resolvedAppRoot(resolvedWorkspace,appId,appRoot);
     await physicalDirectory(resolvedWorkspace,resolvedApp);
     const safeEntry=safeRelativePath(entry,'application entry');
     const safeDocuments=normalizedDocumentPaths(safeEntry,documents);
@@ -2819,7 +2835,7 @@ async function generateImportMapUnlocked({
         const html=await readPhysicalTextFile(resolvedApp,documentPath,label);
         throwIfAborted(signal);
         // Reject malformed application structure before traversing the runtime inventory.
-        const baseHref=documentBaseHref(safeDocuments[index]);
+        const baseHref=appBaseHref(resolvedWorkspace,resolvedApp,safeDocuments[index]);
         renderManagedHtml(html,'{"imports":{}}\n',baseHref);
         documentStates.push({filePath:documentPath,html,label,baseHref});
     }

package/src/packager/core.mjs

@@ -12,6 +12,8 @@ import {
 } from 'node:fs/promises';
 import path from 'node:path';
 import {pathToFileURL} from 'node:url';
+import {appRelativeRoot,resolveAppRoot,rootAppNavigation} from '../app-layout.mjs';
+import {readInstalledSdkLayout} from '../sdk-runtime-layout.mjs';
 import {withWorkspaceOperationLock} from '../workspace-operation-lock.mjs';
 import {
     applyPwaEntryReferences,
@@ -275,8 +277,8 @@ function validateSharedRoute(route,label){
 export function validateRootConfig(value,configPath=ROOT_CONFIG_NAME){
     assertOnlyKeys(value,new Set(['schemaVersion','appsRoot','distRoot','sharedPayloads']),ROOT_CONFIG_NAME);
     if(value.schemaVersion!==1)fail(`${ROOT_CONFIG_NAME}.schemaVersion must be 1.`);
-    if(value.appsRoot!=='apps'||value.distRoot!=='dist'){
-        fail(`${ROOT_CONFIG_NAME} must bind appsRoot to "apps" and distRoot to "dist".`);
+    if(!['apps','.'].includes(value.appsRoot)||value.distRoot!=='dist'){
+        fail(`${ROOT_CONFIG_NAME} must bind appsRoot to "apps" or "." and distRoot to "dist".`);
     }
     if(!isPlainObject(value.sharedPayloads)){
         fail(`${ROOT_CONFIG_NAME}.sharedPayloads must be an object.`);
@@ -291,7 +293,7 @@ export function validateRootConfig(value,configPath=ROOT_CONFIG_NAME){
             validateSharedRoute(route,`sharedPayloads.${id}[${index}]`)
         );
     }
-    return {schemaVersion:1,appsRoot:'apps',distRoot:'dist',sharedPayloads,configPath};
+    return {schemaVersion:1,appsRoot:value.appsRoot,distRoot:'dist',sharedPayloads,configPath};
 }
 
 function normalizeOptionalRecord(value,label){
@@ -300,14 +302,14 @@ function normalizeOptionalRecord(value,label){
     return copyJson(value);
 }
 
-export function validateAppConfig(value,appId,rootConfig,configPath=`apps/${appId}/${APP_CONFIG_NAME}`){
+export function validateAppConfig(value,appId,rootConfig,configPath=path.posix.join(appRelativeRoot(rootConfig,appId),APP_CONFIG_NAME)){
     assertOnlyKeys(value,new Set([
         'schemaVersion','id','displayName','version','entry','strategy','security',
         'localAIModelPolicy','include','exclude','shared','adapter','pwa'
     ]),`${appId}/${APP_CONFIG_NAME}`);
     if(value.schemaVersion!==1)fail(`${appId}/${APP_CONFIG_NAME}.schemaVersion must be 1.`);
-    if(value.id!==appId||!APP_ID_PATTERN.test(value.id)){
-        fail(`${appId}/${APP_CONFIG_NAME}.id must exactly match its apps directory.`);
+    if(!is.string(value.id)||value.id!==appId||!APP_ID_PATTERN.test(value.id)){
+        fail(`${APP_CONFIG_NAME}.id must be a valid application id matching the selected application: ${String(appId)}.`);
     }
     const displayName=assertPresentationText(value.displayName,`${appId}/${APP_CONFIG_NAME}.displayName`);
     parseSemver(value.version);
@@ -406,8 +408,8 @@ async function loadContext(requestedWorkspaceRoot,appId){
     const rootConfig=validateRootConfig(await readJson(rootConfigPath,ROOT_CONFIG_NAME),rootConfigPath);
     if(!is.string(appId)||!APP_ID_PATTERN.test(appId))fail(`Unsafe app id: ${String(appId)}`);
     const appsRoot=await realDirectory(path.join(workspaceRoot,rootConfig.appsRoot),'Apps root');
-    const appRoot=resolveInside(appsRoot,appId,'app id');
-    await assertContainedRealPath(appsRoot,appRoot,`apps/${appId}`);
+    const appRoot=resolveAppRoot(workspaceRoot,rootConfig,appId);
+    await assertContainedRealPath(appsRoot,appRoot,appId);
     const configPath=path.join(appRoot,APP_CONFIG_NAME);
     const config=validateAppConfig(await readJson(configPath,`${appId}/${APP_CONFIG_NAME}`),appId,rootConfig,configPath);
     return {
@@ -427,7 +429,8 @@ function destinationJoin(root,relative){
 }
 
 function appPackagePath(context, relative) {
-    return `apps/${context.appId}/${relative}`;
+    const root=appRelativeRoot(context.rootConfig,context.appId);
+    return root?`${root}/${relative}`:relative;
 }
 
 function packageResourceUrl(relative) {
@@ -502,9 +505,13 @@ async function collectPackageRecords(context,{signal}={}){
             records,
             destinations,
             signal,
-            label:`apps/${context.appId}`
+            label:context.appId
         });
     }
+    // App ownership comes from its selected files, including in a root layout.
+    for(const record of records){
+        record.appRelativePath=path.relative(context.appRoot,record.source).split(path.sep).join('/');
+    }
     for(const sharedId of context.config.shared){
         for(const route of context.rootConfig.sharedPayloads[sharedId]){
             const sourceRoot=resolveInside(context.workspaceRoot,route.source,`sharedPayloads.${sharedId}.source`);
@@ -532,19 +539,19 @@ async function collectPackageRecords(context,{signal}={}){
     return records;
 }
 
-async function browserDocuments(records,entry,appPrefix){
+async function browserDocuments(records,entry){
     let entryDocument=null;
     const documents=[];
     for(const record of records){
+        if(record.appRelativePath===undefined)continue;
         const extension=path.posix.extname(record.destination).toLocaleLowerCase('en-US');
         if(extension!=='.html'&&extension!=='.htm')continue;
-        const documentPath=record.destination.startsWith(appPrefix)
-            ?record.destination.slice(appPrefix.length):record.destination;
+        const documentPath=record.appRelativePath;
         const inspected=inspectImportMapHtml(await readFile(record.source,'utf8'),{
             documentPath
         });
         const document={path:documentPath,packagePath:record.destination,...copyJson(inspected)};
-        if(record.destination===`${appPrefix}${entry}`){
+        if(documentPath===entry){
             entryDocument=document;
         }else if(inspected.bases.length>0){
             documents.push(document);
@@ -567,6 +574,16 @@ async function optionalDescriptor(context){
 
 async function inspectContext(context,{signal}={}){
     const records=await collectPackageRecords(context,{signal});
+    const documents=await browserDocuments(records,context.config.entry);
+    const navigation=context.rootConfig.appsRoot==='.'?rootAppNavigation(
+        context.appId,context.config.entry,documents.map(document=>document.path)
+    ):[];
+    for(const redirect of navigation){
+        const selected=records.find(record=>pathKey(record.destination)===pathKey(redirect.path));
+        if(selected&&!(await readFile(selected.source,'utf8')).includes('<!-- Arcane root application navigation -->')){
+            fail(`Root application navigation would replace selected content: ${redirect.path}.`);
+        }
+    }
     return {
         appId:context.appId,
         displayName:context.config.displayName,
@@ -583,8 +600,8 @@ async function inspectContext(context,{signal}={}){
         }),
         ...(context.config.adapter===undefined?{}:{adapter:context.config.adapter}),
         descriptor:await optionalDescriptor(context),
-        browserDocuments:await browserDocuments(records,context.config.entry,appPackagePath(context,'')),
-        files:[...new Set(['index.html',...records.map(record=>record.destination)])].sort(compareText),
+        browserDocuments:documents,
+        files:[...new Set(['index.html',...records.map(record=>record.destination),...navigation.map(redirect=>redirect.path)])].sort(compareText),
         output:path.relative(context.workspaceRoot,context.outputRoot).split(path.sep).join('/')
     };
 }
@@ -595,6 +612,12 @@ export async function discoverApps({workspaceRoot:requestedWorkspaceRoot}={}){
         await readJson(path.join(workspaceRoot,ROOT_CONFIG_NAME),ROOT_CONFIG_NAME),
         path.join(workspaceRoot,ROOT_CONFIG_NAME)
     );
+    if(rootConfig.appsRoot==='.'){
+        const configPath=path.join(workspaceRoot,APP_CONFIG_NAME);
+        const value=await readJson(configPath,APP_CONFIG_NAME);
+        const config=validateAppConfig(value,value?.id,rootConfig,configPath);
+        return [config.id];
+    }
     const appsRoot=await realDirectory(path.join(workspaceRoot,rootConfig.appsRoot),'Apps root');
     const entries=await readdir(appsRoot,{withFileTypes:true});
     const apps=[];
@@ -734,9 +757,12 @@ 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 appPath=`apps/${context.appId}`;
+    const appPath=appRelativeRoot(context.rootConfig,context.appId);
     const entryPath=appPackagePath(context,context.config.entry);
     const inspected=await inspectContext(context,{signal});
+    const navigation=context.rootConfig.appsRoot==='.'?rootAppNavigation(
+        context.appId,context.config.entry,inspected.browserDocuments.map(document=>document.path)
+    ):[];
     if(options.dryRun){
         return {
             appId:context.appId,
@@ -787,6 +813,18 @@ async function packageWithContext(context,options={}){
         }else{
             await copyBase();
         }
+        for(const redirect of navigation){
+            throwIfAborted(signal);
+            const filePath=path.join(stagingRoot,...redirect.path.split('/'));
+            try{
+                const current=await readFile(filePath,'utf8');
+                if(!current.includes('<!-- Arcane root application navigation -->')){
+                    fail(`Root application navigation would replace package content: ${redirect.path}.`);
+                }
+            }catch(error){if(error.code!=='ENOENT')throw error;}
+            await mkdir(path.dirname(filePath),{recursive:true});
+            await writeFile(filePath,redirect.content,'utf8');
+        }
         const files=await listOutputFiles(stagingRoot,{signal});
         // Traverse actual browser resources after the adapter finishes. Files
         // included only as application documents retain their original content.
@@ -807,7 +845,7 @@ async function packageWithContext(context,options={}){
                 const appDocument=context.config.include.some(function includesAppDocument(selected){
                     return sameOrDescendant(document.path,selected);
                 });
-                if(appDocument&&document.managedMaps.length>0&&inventory.has(document.packagePath)){
+                if(appDocument&&(appPath===''||document.managedMaps.length>0)&&inventory.has(document.packagePath)){
                     documentPaths.add(document.packagePath);
                 }
             }
@@ -833,8 +871,9 @@ async function packageWithContext(context,options={}){
         const documentUrl=entryDocument?.bases[0]?.href
             ?new URL(entryDocument.bases[0].href,entryUrl):entryUrl;
         const pending=[{file:entryPath,documentUrl}];
+        const sharedFiles=new Set(records.filter(record=>record.appRelativePath===undefined).map(record=>record.destination));
         for(const file of files){
-            if(/^arcane\/(?:modules|entities|components|css|sdk|dependencies)\//u.test(file)
+            if((sharedFiles.has(file)||/^arcane\/(?:modules|entities|components|css|sdk|dependencies)\//u.test(file))
                 &&/\.(?:m?js|html?|css)$/iu.test(file))pending.push({file,documentUrl});
             if(pwaEnabled&&path.posix.basename(file)==='arcane.importmap.json'){
                 pending.push({file,documentUrl});
@@ -906,6 +945,15 @@ async function packageWithContext(context,options={}){
         if(!files.some(file=>pathKey(file)===pathKey(entryPath))){
             fail(`Package output is missing its entry file: ${context.config.entry}.`);
         }
+        const installed=pwaEnabled?await readInstalledSdkLayout(context.workspaceRoot,context.rootConfig):null;
+        const navigationAliases=navigation.length?{
+            './':packageResourceUrl(entryPath),
+            [`./apps/${context.appId}`]:packageResourceUrl(entryPath),
+            [`./apps/${context.appId}/`]:packageResourceUrl(entryPath),
+            ...Object.fromEntries(navigation.map(redirect=>[
+                packageResourceUrl(redirect.path),packageResourceUrl(redirect.target.slice(1))
+            ]))
+        }:undefined;
         const pwaArtifacts=pwaEnabled?createPwaArtifacts({
             app:{
                 id:context.appId,
@@ -914,6 +962,8 @@ async function packageWithContext(context,options={}){
                 entry:packageResourceUrl(entryPath)
             },
             appPath,
+            ...(installed?.direct?{runtimeBase:`.${installed.browserRuntimeBase}`} : {}),
+            ...(navigationAliases?{navigationAliases}:{}),
             sdkVersion:assetVersion,
             pwa:context.config.pwa,
             files,

package/src/pwa-worker.mjs

@@ -394,11 +394,25 @@ function installPwaWorker(manifest, clientUrl) {
         );
     }
 
+    function navigationRedirect(url) {
+        const exact = navigationAliases.get(url);
+        if (exact) return {location: exact, resource: cacheUrl(exact)};
+        const source = new URL(url);
+        const query = source.search;
+        if (!query) return null;
+        source.search = '';
+        const selected = navigationAliases.get(source.href);
+        if (!selected) return null;
+        const destination = new URL(selected);
+        destination.search = destination.search ? `${destination.search}&${query.slice(1)}` : query;
+        return {location: destination.href, resource: cacheUrl(selected)};
+    }
+
     async function requestedResource(request, url) {
         await restored;
-        const redirect = request.mode === 'navigate' ? navigationAliases.get(url) : null;
-        if (redirect && cacheUrl(redirect) !== url && ownedUrls.has(cacheUrl(redirect))) {
-            return {response: Response.redirect(redirect, 302), done: Promise.resolve(null)};
+        const redirect = request.mode === 'navigate' ? navigationRedirect(url) : null;
+        if (redirect && cacheUrl(redirect.location) !== url && ownedUrls.has(redirect.resource)) {
+            return {response: Response.redirect(redirect.location, 302), done: Promise.resolve(null)};
         }
         if (!ownedUrls.has(url)) {
             return {response: await fetch(request), done: Promise.resolve(null)};
@@ -422,7 +436,7 @@ function installPwaWorker(manifest, clientUrl) {
             return;
         }
         if (manifestRestored && !ownedUrls.has(url)
-            && !(request.mode === 'navigate' && navigationAliases.has(url))) {
+            && !(request.mode === 'navigate' && navigationRedirect(url))) {
             return;
         }
         const resource = requestedResource(request, url);

package/src/pwa.mjs

@@ -202,6 +202,7 @@ export function createPwaArtifacts(
         mode = 'release',
         runtimeBase = './arcane/sdk/',
         appBase,
+        installationId,
         appPath = '',
         navigationAliases,
         revision
@@ -218,7 +219,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),