arcane-os 0.25.0 → 0.27.0

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,
@@ -136,12 +138,13 @@ function isGlobLike(value){
     return /[*?\[\]{}]/u.test(value);
 }
 
-function validatePathList(value,label,{required=false}={}){
+function validatePathList(value,label,{required=false,allowRoot=false}={}){
     if(!is.array(value)||(required&&value.length===0)){
         fail(`${label} must be ${required?'a non-empty':'an'} array of literal relative paths.`);
     }
     const normalized=value.map((entry,index)=>{
-        const item=normalizeRelativePath(entry,`${label}[${index}]`);
+        const item=allowRoot?normalizeRelativeRoot(entry,`${label}[${index}]`)
+            :normalizeRelativePath(entry,`${label}[${index}]`);
         if(isGlobLike(item))fail(`${label}[${index}] must be literal; directories include descendants.`);
         return item;
     });
@@ -151,7 +154,8 @@ function validatePathList(value,label,{required=false}={}){
     if(required){
         for(let left=0;left<normalized.length;left+=1){
             for(let right=left+1;right<normalized.length;right+=1){
-                if(sameOrDescendant(normalized[left],normalized[right])
+                if(normalized[left]==='.'||normalized[right]==='.'
+                    ||sameOrDescendant(normalized[left],normalized[right])
                     ||sameOrDescendant(normalized[right],normalized[left])){
                     fail(`${label} has overlapping paths: ${normalized[left]} and ${normalized[right]}`);
                 }
@@ -256,7 +260,7 @@ function validateSharedRoute(route,label){
     assertOnlyKeys(route,new Set(['source','destination','include','exclude']),label);
     const source=normalizeRelativeRoot(route.source,`${label}.source`);
     const destination=normalizeRelativeRoot(route.destination,`${label}.destination`);
-    const include=validatePathList(route.include,`${label}.include`,{required:true});
+    const include=validatePathList(route.include,`${label}.include`,{required:true,allowRoot:true});
     const exclude=validatePathList(route.exclude??[],`${label}.exclude`);
     if(source==='.'||source==='apps'||source.startsWith('apps/')
         ||source==='dist'||source.startsWith('dist/')||source==='node_modules'
@@ -273,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.`);
@@ -289,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){
@@ -298,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);
@@ -404,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 {
@@ -421,11 +425,12 @@ async function loadContext(requestedWorkspaceRoot,appId){
 }
 
 function destinationJoin(root,relative){
-    return root==='.'?relative:`${root}/${relative}`;
+    return relative==='.'?root:root==='.'?relative:`${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) {
@@ -442,12 +447,13 @@ async function collectSelectedPath({
     records,
     destinations,
     signal,
-    label
+    label,
+    allowRoot=false
 }){
     throwIfAborted(signal);
     if(isExcluded(selected,excludes))return;
     if(reject(selected))fail(`${label} selects a reserved private or generated path: ${selected}.`);
-    const absolute=resolveInside(sourceRoot,selected,label);
+    const absolute=resolveInside(sourceRoot,selected,label,{allowRoot});
     let info;
     try{info=await lstat(absolute);}
     catch(error){
@@ -455,15 +461,16 @@ async function collectSelectedPath({
         throw error;
     }
     if(info.isSymbolicLink())fail(`${label} contains a symbolic link or junction: ${selected}.`);
+    if(selected==='.'&&!info.isDirectory())fail(`${label} root selection must be a directory.`);
     if(info.isDirectory()){
         const entries=await readdir(absolute,{withFileTypes:true});
         entries.sort((left,right)=>compareText(left.name,right.name));
         for(const entry of entries){
-            const child=`${selected}/${entry.name}`;
+            const child=destinationJoin(selected,entry.name);
             await collectSelectedPath({
                 sourceRoot,
                 selected:child,
-                destination:`${destination}/${entry.name}`,
+                destination:destinationJoin(destination,entry.name),
                 excludes,
                 reject,
                 records,
@@ -498,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`);
@@ -515,7 +526,8 @@ async function collectPackageRecords(context,{signal}={}){
                     records,
                     destinations,
                     signal,
-                    label:`sharedPayloads.${sharedId}`
+                    label:`sharedPayloads.${sharedId}`,
+                    allowRoot:true
                 });
             }
         }
@@ -527,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);
@@ -562,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,
@@ -578,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('/')
     };
 }
@@ -590,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=[];
@@ -729,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,
@@ -782,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.
@@ -802,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);
                 }
             }
@@ -828,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});
@@ -901,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,
@@ -909,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),

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

@@ -0,0 +1,112 @@
+import Is from 'strong-type';
+import {readFile,readdir} from 'node:fs/promises';
+import path from 'node:path';
+
+const is=new Is(false);
+
+// 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:[]
+        },
+        {
+            source:`${packageSource}/browser-runtime`,destination:'arcane/sdk',
+            include:['.'],exclude:[]
+        },
+        {
+            source:`${packageSource}/runtime/strong-type`,destination:'arcane/dependencies/strong-type',
+            include:['.'],exclude:[]
+        },
+        {
+            source:packageSource,destination:'licenses/arcane-os',
+            include:['LICENSE','COMMERCIAL-LICENSE.md','NOTICE'],exclude:[]
+        }
+    ];
+    return direct?routes.map(route=>({...route,destination:route.source})):routes;
+}
+
+export function installedSdkPackageSource(config){
+    const routes=config?.sharedPayloads?.['browser-runtime'];
+    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',
+        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
+            &&is.array(route.include)&&route.include.length===wanted.include.length
+            &&route.include.every(function matchesSelectedPath(value,item){return value===wanted.include[item];})
+            &&(route.exclude===undefined||(is.array(route.exclude)&&route.exclude.length===0));
+    })?source:null;
+}
+
+export async function readInstalledSdkLayout(workspaceRoot,config){
+    if(config===undefined){
+        try{config=JSON.parse(await readFile(path.join(workspaceRoot,'arcane-packager.json'),'utf8'));}
+        catch(error){if(error.code==='ENOENT')return null;throw error;}
+    }
+    const packageSource=installedSdkPackageSource(config);
+    if(packageSource===null)return null;
+    const packageRoot=path.join(workspaceRoot,...packageSource.split('/'));
+    const versionPath=path.join(packageRoot,'package.json');
+    const manifest=JSON.parse(await readFile(versionPath,'utf8'));
+    if(manifest.name!=='arcane-os'||!is.string(manifest.version)||!manifest.version){
+        const error=new Error('The installed SDK runtime must identify its arcane-os package version.');
+        error.code='ARCANE_WORKSPACE_INVALID';
+        throw error;
+    }
+    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){
+    const files=[];
+    async function visit(directory,logical){
+        signal?.throwIfAborted();
+        const entries=await readdir(directory,{withFileTypes:true});
+        for(const entry of entries){
+            signal?.throwIfAborted();
+            const relative=logical?`${logical}/${entry.name}`:entry.name;
+            if(entry.isDirectory())await visit(path.join(directory,entry.name),relative);
+            else if(entry.isFile())files.push(relative);
+        }
+    }
+    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(
+                path.join(workspaceRoot,...route.source.split('/'),suffix),
+                [prefix,suffix].filter(Boolean).join('/')
+            );
+        }
+    }
+    return {files:files.sort()};
+}
+
+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.logical}/`))continue;
+        const suffix=relative.slice(route.logical.length+1);
+        if(route.include.some(function includesRuntimeTarget(selected){
+            const pathname=suffix.split(/[?#]/u)[0];
+            return selected==='.'||pathname===selected||pathname.startsWith(`${selected}/`);
+        }))return `${browser?route.destination:route.source}/${suffix}`;
+    }
+    return relative;
+}