arcane-os 0.25.0 → 0.27.0

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,75 @@ 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}/`,
+        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={}){

package/src/workspace.mjs

@@ -1,4 +1,5 @@
 import Is from 'strong-type';
+import {appRelativeRoot, resolveAppRoot, appBaseHref} from './app-layout.mjs';
 import {readFile,readdir,realpath,stat} from 'node:fs/promises';
 import path from 'node:path';
 import {
@@ -9,6 +10,7 @@ import {
 import {loadAppDescriptor} from './app-descriptor.mjs';
 import {SDK_NAME as EXPECTED_SDK_NAME} from './constants.mjs';
 import {inspectImportMapHtml} from './import-map.mjs';
+import {installedSdkPackageSource} from './sdk-runtime-layout.mjs';
 
 const is = new Is(false);
 
@@ -159,6 +161,13 @@ function classifyRootConfig(config){
     const validated=validatePackagerRootConfig(config,ROOT_CONFIG_NAME);
     const routes=validated.sharedPayloads['browser-runtime'];
     if(!is.array(routes))fail(`${ROOT_CONFIG_NAME} must define browser-runtime routes.`);
+    const installedPackageSource=installedSdkPackageSource(validated);
+    if(installedPackageSource!==null){
+        return {
+            ...validated,workspaceMode:'external',browserRuntimeLayout:'installed-v1',
+            sdkPackageSource:installedPackageSource
+        };
+    }
     const externalPackageSource=routes.length===2
         &&dependencyNameForSdkPackageSource(routes[1]?.source)!==null
         ?routes[1].source
@@ -220,6 +229,25 @@ async function discoverAppsInRoot(root,config,appId){
     if(appId!==undefined&&(!is.string(appId)||!APP_ID_PATTERN.test(appId))){
         fail(`Invalid app id: ${String(appId)}.`,'ARCANE_USAGE');
     }
+    async function readApp(appRoot,id,manifest){
+        const configPath=path.join(appRoot,APP_CONFIG_NAME);
+        manifest??=await readJson(configPath,`${appRelativeRoot(config,id) || '.'}/${APP_CONFIG_NAME}`);
+        const validatedManifest=validatePackagerAppConfig(manifest,id,config,configPath);
+        if(!validatedManifest.shared.includes('browser-runtime')){
+            fail(`${configPath} must include the browser-runtime shared payload.`);
+        }
+        const descriptor=await loadAppDescriptor({workspaceRoot:root,appRoot,appId:id,packageManifest:manifest});
+        return completeValue({
+            appId:id,appRoot,manifest:validatedManifest,
+            descriptor:descriptor.descriptor,descriptorSource:descriptor.source,
+            descriptorPath:descriptor.descriptorPath
+        });
+    }
+    if(config.appsRoot==='.'){
+        const manifest=await readJson(path.join(root,APP_CONFIG_NAME),APP_CONFIG_NAME);
+        if(appId!==undefined&&appId!==manifest.id)return [];
+        return [await readApp(root,manifest.id,manifest)];
+    }
     const appsRoot=path.join(root,'apps');
     await assertRealDirectory(appsRoot,'Workspace apps root');
     const entries=await readdir(appsRoot,{withFileTypes:true});
@@ -232,26 +260,7 @@ async function discoverAppsInRoot(root,config,appId){
         if(!entry.isDirectory())continue;
         const appRoot=path.join(appsRoot,entry.name);
         try{
-            const configPath=path.join(appRoot,APP_CONFIG_NAME);
-            const manifest=await readJson(configPath,`apps/${entry.name}/${APP_CONFIG_NAME}`);
-            const validatedManifest=validatePackagerAppConfig(manifest,entry.name,config,configPath);
-            if(!validatedManifest.shared.includes('browser-runtime')){
-                fail(`apps/${entry.name}/${APP_CONFIG_NAME} must include the browser-runtime shared payload.`);
-            }
-            const descriptor=await loadAppDescriptor({
-                workspaceRoot:root,
-                appRoot,
-                appId:entry.name,
-                packageManifest:manifest
-            });
-            apps.push(completeValue({
-                appId:entry.name,
-                appRoot,
-                manifest:validatedManifest,
-                descriptor:descriptor.descriptor,
-                descriptorSource:descriptor.source,
-                descriptorPath:descriptor.descriptorPath
-            }));
+            apps.push(await readApp(appRoot,entry.name));
         }catch(error){
             if(!String(error?.message).includes('does not exist'))throw error;
         }
@@ -286,7 +295,7 @@ export async function selectApp(workspaceRoot=process.cwd(),appId){
         if(!selected)fail(`Unknown app "${appId}".`);
         return selected;
     }
-    if(apps.length===0)fail('No Arcane applications were found under apps/.');
+    if(apps.length===0)fail('No Arcane applications were found at the configured appsRoot.');
     if(apps.length>1){
         fail(`This workspace contains multiple apps; select one explicitly: ${apps.map(app=>app.appId).join(', ')}.`,'ARCANE_USAGE');
     }
@@ -305,7 +314,7 @@ export async function resolveWorkspace({workspaceRoot=process.cwd(),appId}={}){
     }else if(apps.length===1){
         [app]=apps;
     }else if(apps.length===0){
-        fail('No Arcane applications were found under apps/.');
+        fail('No Arcane applications were found at the configured appsRoot.');
     }else{
         fail(`This workspace contains multiple apps; select one explicitly: ${apps.map(item=>item.appId).join(', ')}.`,'ARCANE_USAGE');
     }
@@ -355,39 +364,43 @@ export async function resolveInstalledSdkInstallation(workspaceRoot,declaration)
 
 function assertHtmlContract(source,appId,{
     entry='index.html',
+    appPath=`apps/${appId}`,
+    baseHref='../../',
+    runtimePath='arcane',
     strictStyles=true,
     allowMissingManagedImportMap=false
 }={}){
-    const entryLabel=`apps/${appId}/${entry}`;
+    const entryLabel=[appPath,entry].filter(Boolean).join('/');
     const htmlContract=inspectImportMapHtml(source);
     const appIdMetadata=htmlContract.metas.filter(meta=>meta.name==='arcane-app-id');
     if(appIdMetadata.length!==1||appIdMetadata[0].content!==appId){
         fail(`${entryLabel} must declare exactly one active matching arcane-app-id metadata element.`);
     }
-    if(htmlContract.bases.length!==1||htmlContract.bases[0].href!=='../../'){
-        fail(`${entryLabel} must declare exactly one active <base href="../../">.`);
+    if(htmlContract.bases.length!==1||htmlContract.bases[0].href!==baseHref){
+        fail(`${entryLabel} must declare exactly one active <base href="${baseHref}">.`);
     }
-    const resourcePath=value=>value.split(/[?#]/u,1)[0];
+    const resourcePath=value=>value.split(/[?#]/u,1)[0].replace(/^\.\//u,'/');
     const styles=htmlContract.links.filter(link=>link.rel
         .split(/[\t\n\f\r ]+/u).includes('stylesheet'));
     const positionOfStyle=expected=>styles.find(link=>resourcePath(link.href)===expected)?.start??-1;
-    const theme=positionOfStyle('./arcane/css/theme.css');
-    const primitives=positionOfStyle('./arcane/css/primitives.css');
-    const escapedAppId=appId.replace(/[.*+?^${}()|[\]\\]/gu,'\\$&');
+    const theme=positionOfStyle(`/${runtimePath}/css/theme.css`);
+    const primitives=positionOfStyle(`/${runtimePath}/css/primitives.css`);
+    const appPrefix=appPath?`${appPath}/`:'';
+    const escapedAppPrefix=appPrefix.replace(/[.*+?^${}()|[\]\\]/gu,'\\$&');
     const appStyle=styles.find(link=>new RegExp(
-        `^(?:\\./|/)apps/${escapedAppId}/[^/]+\\.css$`,
+        `^(?:\\./|/)${escapedAppPrefix}[^/]+\\.css$`,
         'u'
     ).test(resourcePath(link.href)))?.start??-1;
     const modules=htmlContract.scripts.filter(script=>script.type==='module'&&script.src);
     const bootstrap=modules.find(script=>resourcePath(script.src)
-        ==='./arcane/modules/ThemeBootstrap.js')?.start??-1;
+        ===`/${runtimePath}/modules/ThemeBootstrap.js`)?.start??-1;
     if(htmlContract.managedMaps.length>1){
         fail(`${entryLabel} must contain at most one active managed Arcane import map.`);
     }
     const managedImportMap=htmlContract.managedMaps[0]?.start??-1;
     const firstModule=htmlContract.firstModulePosition;
     const appModule=modules.find(script=>new RegExp(
-        `^(?:\\./|/)apps/${escapedAppId}/.+\\.(?:js|mjs)$`,
+        `^(?:\\./|/)${escapedAppPrefix}(?!arcane/|node_modules/).+\\.(?:js|mjs)$`,
         'u'
     ).test(resourcePath(script.src)))?.start??-1;
     if(theme<0){
@@ -436,12 +449,6 @@ export async function validateDiscoveredApplication({
         fail('A discovered Arcane application is required for focused validation.');
     }
     const canonicalWorkspaceRoot=await realpath(workspaceRoot);
-    await assertRealDirectory(path.join(canonicalWorkspaceRoot,'apps'),'Workspace apps root');
-    const expectedAppRoot=path.join(canonicalWorkspaceRoot,'apps',app.appId);
-    if(!sameDirectoryPath(app.appRoot,expectedAppRoot)){
-        fail(`Discovered app ${app.appId} does not belong to the selected workspace.`);
-    }
-    const canonicalAppRoot=await realpath(app.appRoot);
     let config=workspaceConfig;
     if(!config){
         const profile=await inspectWorkspaceProfile(canonicalWorkspaceRoot);
@@ -453,6 +460,12 @@ export async function validateDiscoveredApplication({
     if(!isObject(config?.sharedPayloads)){
         fail('The selected Arcane workspace configuration is unavailable for focused validation.');
     }
+    const expectedAppRoot=resolveAppRoot(canonicalWorkspaceRoot,config,app.appId);
+    await assertRealDirectory(expectedAppRoot,'Selected application root');
+    if(!sameDirectoryPath(app.appRoot,expectedAppRoot)){
+        fail(`Discovered app ${app.appId} does not belong to the selected workspace.`);
+    }
+    const canonicalAppRoot=await realpath(app.appRoot);
     const configPath=path.join(canonicalAppRoot,APP_CONFIG_NAME);
     const rawManifest=await readJson(
         configPath,
@@ -484,6 +497,9 @@ export async function validateDiscoveredApplication({
     }
     assertHtmlContract(await readFile(entryPath,'utf8'),app.appId,{
         entry:manifest.entry,
+        appPath:appRelativeRoot(config,app.appId),
+        baseHref:appBaseHref(canonicalWorkspaceRoot,canonicalAppRoot,manifest.entry),
+        runtimePath:config.sharedPayloads['browser-runtime'][0].destination,
         strictStyles:workspaceMode==='external',
         allowMissingManagedImportMap
     });