arcane-os 0.25.0 → 0.27.0

package/runtime/arcane/components/file-manager.html

@@ -352,6 +352,7 @@
     //importing Document at the end of the file to avoid blocking;
 
     const host=this;
+    const componentHref=new URL(host.getAttribute('href'),document.baseURI);
     const {default:waitForComponent}=await import('../modules/WaitForComponent.js');
     const {createArcaneEventSource,projectArcaneDOMEvent}=await import('arcane-os/event-manager');
     const events=createArcaneEventSource(host,{source:'arcane.component.file-manager',eventTypes:['file-manager-action','file-manager-select','file-manager-open','file-manager-ready']});
@@ -830,8 +831,8 @@
         icon.className='tree-entry-icon';
         icon.alt='';
         icon.src=entry.kind==='directory'
-            ?new URL('./arcane/img/folder.svg',document.baseURI).href
-            :new URL('./arcane/img/doc.svg',document.baseURI).href;
+            ?new URL('../img/folder.svg',componentHref).href
+            :new URL('../img/doc.svg',componentHref).href;
         name.className='tree-entry-name';
         name.innerText=entry.name;
         count.className='tree-file-count';
@@ -1409,7 +1410,7 @@
         deleteButton.innerText='Delete File';
         deleteIcon.alt='';
         deleteIcon.className='action-icon';
-        deleteIcon.src=new URL('./arcane/img/trash.svg',document.baseURI).href;
+        deleteIcon.src=new URL('../img/trash.svg',componentHref).href;
         deleteButton.prepend(deleteIcon);
         deleteButton.addEventListener(
             'click',
@@ -1615,7 +1616,7 @@
 
         fileIcon.alt='';
         fileIcon.className='icon file-icon';
-        fileIcon.src=new URL('./arcane/img/doc.svg',document.baseURI).href;
+        fileIcon.src=new URL('../img/doc.svg',componentHref).href;
         fileDetails.className='file-details';
         fileLabel.className='file-name';
         fileLabel.innerText=fileName;
@@ -1638,7 +1639,7 @@
 
         deleteIcon.alt='';
         deleteIcon.className='action-icon';
-        deleteIcon.src=new URL('./arcane/img/trash.svg',document.baseURI).href;
+        deleteIcon.src=new URL('../img/trash.svg',componentHref).href;
 
         openButton.addEventListener(
             'click',
@@ -1938,7 +1939,7 @@
             directory.dataset.directory=tableName;
             folder.className='file folder';
             folderIcon.className='icon';
-            folderIcon.src=new URL('./arcane/img/folder.svg',document.baseURI).href;
+            folderIcon.src=new URL('../img/folder.svg',componentHref).href;
             folderName.innerText=tableName;
             fileCount.className='file-count';
             fileCount.innerText=`${files.length} ${files.length===1?'file':'files'}`;

package/runtime/arcane/modules/MailApi.mjs

@@ -0,0 +1,19 @@
+export {
+    default,
+    default as Mail,
+    resolveMailConfig
+} from './Mail.js';
+export {
+    MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS,
+    MAIL_OUTBOX_PROTOCOL,
+    MAIL_OUTBOX_STATES,
+    MAIL_OUTBOX_TABLE,
+    MailOutbox,
+    createMailOutbox
+} from './MailOutbox.mjs';
+export {
+    MailTransportError,
+    normalizeMailEndpoint,
+    sendMailReport,
+    serializeMailReport
+} from './MailTransport.mjs';

package/src/app-descriptor.mjs

@@ -1,4 +1,5 @@
 import Is from 'strong-type';
+import {resolveAppRoot} from './app-layout.mjs';
 import {isDeepStrictEqual} from 'node:util';
 import {readFile, writeFile} from 'node:fs/promises';
 import path from 'node:path';
@@ -427,7 +428,8 @@ async function readJsonFile(filePath,label,{optional=false}={}){
 
 export async function refreshAppPackageProjection({workspaceRoot, appId, signal, onEvent}) {
     throwIfAborted(signal);
-    const appRoot = path.join(workspaceRoot, 'apps', appId);
+    const rootConfig=await readJsonFile(path.join(workspaceRoot,'arcane-packager.json'),'arcane-packager.json');
+    const appRoot = resolveAppRoot(workspaceRoot,rootConfig,appId);
     const descriptorPath = path.join(appRoot, APP_DESCRIPTOR_NAME);
     const authored = await readJsonFile(
         descriptorPath,

package/src/app-layout.mjs

@@ -0,0 +1,32 @@
+import path from 'node:path';
+
+// The app identity is independent of whether its files occupy a workspace root.
+export function appRelativeRoot(config, appId) {
+    return config.appsRoot === '.' ? '' : `apps/${appId}`;
+}
+
+export function resolveAppRoot(workspaceRoot, config, appId) {
+    return path.resolve(workspaceRoot, appRelativeRoot(config, appId));
+}
+
+export function appBaseHref(workspaceRoot, appRoot, document = 'index.html') {
+    const directory = path.dirname(path.resolve(appRoot, document));
+    const relative = path.relative(directory, workspaceRoot).split(path.sep).join('/');
+    return relative ? `${relative}/` : './';
+}
+
+export function rootAppNavigation(appId, entry, documents = []) {
+    const redirects=new Map();
+    for(const document of documents)redirects.set(`apps/${appId}/${document}`,document);
+    redirects.set(`apps/${appId}/index.html`,entry);
+    return [...redirects].map(([file,target])=>{
+        const relative=path.posix.relative(path.posix.dirname(file),target);
+        const destination=JSON.stringify(relative).replaceAll('<','\\u003c');
+        return {
+            path:file,target:`/${target}`,
+            content:'<!doctype html>\n<!-- Arcane root application navigation -->\n'
+                +'<meta charset="utf-8">\n<title>Opening application</title>\n'
+                +`<script>const target=new URL(${destination},location.href);target.search=location.search;target.hash=location.hash;location.replace(target.href);</script>\n`
+        };
+    });
+}

package/src/application-tests.mjs

@@ -124,7 +124,9 @@ async function selectedTestFiles({workspaceRoot,workspaceMode,appRoot,signal}){
     if(workspaceMode==='external'){
         await collectOptionalTests(path.join(workspaceRoot,'test'),workspaceRoot,files,signal);
     }
-    if(appRoot)await collectOptionalTests(path.join(appRoot,'test'),appRoot,files,signal);
+    if(appRoot&&(workspaceMode!=='external'||!samePath(workspaceRoot,appRoot))){
+        await collectOptionalTests(path.join(appRoot,'test'),appRoot,files,signal);
+    }
     return [...files].sort();
 }
 

package/src/cli/main.mjs

@@ -14,6 +14,7 @@ const VALUE_OPTIONS=new Set([
     'display-name',
     'workspace',
     'app',
+    'apps-root',
     'sdk-runtime-source',
     'arcane-root',
     'host',
@@ -60,8 +61,8 @@ const MAX_NODE_TIMER_DELAY_MS=2_147_483_647;
 export const HELP_TEXT=`Arcane OS application SDK ${SDK_VERSION}
 
 Usage:
-  ${CLI_NAME} new <id> [--path <directory>] [--display-name <name>] [--target <target>] [--git]
-  ${CLI_NAME} init [id] [--workspace <directory>] [--display-name <name>] [--target <target>]
+  ${CLI_NAME} new <id> [--path <directory>] [--apps-root apps|.] [--display-name <name>] [--target <target>] [--git]
+  ${CLI_NAME} init [id] [--workspace <directory>] [--apps-root apps|.] [--display-name <name>] [--target <target>]
   ${CLI_NAME} upgrade [--workspace <directory>] [--app <id>]
   ${CLI_NAME} doctor [--workspace <directory>] [--arcane-root <directory>]
   ${CLI_NAME} import-map [--workspace <directory>] [--app <id>]
@@ -421,15 +422,6 @@ function readScope(value){
     return scope;
 }
 
-function inferredAppId(workspaceRoot){
-    const id=path.basename(workspaceRoot)
-        .normalize('NFKD')
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/gu,'-')
-        .replace(/^-+|-+$/gu,'');
-    return id||'arcane-app';
-}
-
 function noExtraPositionals(command,positionals,expected=0){
     if(positionals.length>expected){
         usage(`Unexpected argument for ${command}.`);
@@ -503,6 +495,9 @@ function operationOptions(command,parsed,cwd){
     if(command!=='mail'&&flags.has('report-stdin')){
         usage('--report-stdin is supported only by mail send.');
     }
+    if(values['apps-root']!==undefined&&!['new','init'].includes(command)){
+        usage('--apps-root is supported only by new and init.');
+    }
 
     if(command==='new'){
         const appId=positionals[0];
@@ -511,6 +506,7 @@ function operationOptions(command,parsed,cwd){
         return {
             targetPath:path.resolve(cwd,values.path??appId),
             appId,
+            appsRoot:values['apps-root']??'apps',
             displayName:values['display-name'],
             target:values.target??'browser',
             initializeGit:flags.has('git')
@@ -520,7 +516,8 @@ function operationOptions(command,parsed,cwd){
         noExtraPositionals(command,positionals,1);
         return {
             workspaceRoot,
-            appId:positionals[0]??values.app??inferredAppId(workspaceRoot),
+            appId:positionals[0]??values.app,
+            appsRoot:values['apps-root'],
             displayName:values['display-name'],
             target:values.target??'browser'
         };

package/src/dev-server.mjs

@@ -6,6 +6,8 @@ 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';
 import {createEventQueue} from './event-queue.mjs';
@@ -96,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){
@@ -436,6 +438,7 @@ function sharedPathAllowed(relative,route){
     });
     if(excluded)return false;
     return route.include.some(item=>{
+        if(item==='.')return true;
         const candidate=inventoryKey(item);
         return comparable===candidate||comparable.startsWith(`${candidate}/`);
     });
@@ -448,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)
@@ -460,25 +464,39 @@ 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'){
+    if(resolved.config.workspaceMode==='integrated'
+        ||resolved.config.browserRuntimeLayout==='installed-v1'){
+        const installed=resolved.config.browserRuntimeLayout==='installed-v1'
+            ?await readInstalledSdkLayout(resolved.workspaceRoot,resolved.config)
+            :null;
         return {
             workspaceRoot:resolved.workspaceRoot,
-            workspaceMode:'integrated',
+            workspaceMode:resolved.config.workspaceMode,
             config:resolved.config,
+            ...(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=>({
@@ -497,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,
             {
@@ -510,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);
@@ -571,15 +594,14 @@ 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});
             }
         }
         for (const selected of mapping.include ?? ['']) {
-            await visitSourceResource(selected ? selected.split('/') : []);
+            await visitSourceResource(selected && selected!=='.' ? selected.split('/') : []);
         }
     }
     const origin = 'http://arcane.invalid';
@@ -590,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});
@@ -629,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});
                 }
@@ -866,7 +888,7 @@ async function startOwnedDevServer({
     const mappings=deterministicMappings(routeSet.mappings);
     const versionPath = mode === 'source'
         ? sdkRuntimeSourceRoot === undefined
-            ? path.join(routeSet.workspaceRoot, 'arcane.lock.json')
+            ? routeSet.installed?.versionPath ?? path.join(routeSet.workspaceRoot, 'arcane.lock.json')
             : path.join(routeSet.runtime.sourceRoot, 'package.json')
         : undefined;
     const [generatorInputs, initialAssetVersion, versionInput] = await Promise.all(
@@ -897,6 +919,9 @@ async function startOwnedDevServer({
     );
     async function selectedAssetVersion(){
         if(mode!=='source')return undefined;
+        if(routeSet.installed)return JSON.parse(await readFile(
+            routeSet.installed.versionPath,'utf8'
+        )).version;
         return sdkRuntimeSourceRoot===undefined
             ?readWorkspaceAssetVersion(routeSet.workspaceRoot)
             :JSON.parse(await readFile(
@@ -956,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() {
@@ -1007,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;
@@ -1021,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: {
@@ -1033,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'
             }
         );
@@ -1128,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);
@@ -1153,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;
             }
@@ -1185,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);
@@ -1194,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,9 +1,11 @@
 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';
 import {SDK_VERSION} from './constants.mjs';
 import {listRuntimeFiles} from './runtime.mjs';
+import {readInstalledSdkLayout,installedRuntimeFiles,installedRuntimeTarget} from './sdk-runtime-layout.mjs';
 
 const is = new Is(false);
 
@@ -19,7 +21,23 @@ const SDK_BROWSER_AI_ENTRY='sdk/ai/browser-wasm.mjs';
 const SDK_BROWSER_SPEECH_ENTRY='sdk/ai/browser-speech.mjs';
 const STATIC_RUNTIME_PACKAGE_IMPORTS=new Map([
     ['arcane-os/preference-store','modules/PreferenceStore.js'],
-    ['arcane-os/speech-playback','modules/SpeechPlayback.js']
+    ['arcane-os/speech-playback','modules/SpeechPlayback.js'],
+    ['arcane-os/ai','modules/AI.js'],
+    ['arcane-os/ai-preference-tuple','modules/AIPreferenceTuple.js'],
+    ['arcane-os/ai-preference-runtime','modules/AIPreferenceRuntime.js'],
+    ['arcane-os/ai-provider-runtime','modules/AIProviderRuntime.js'],
+    ['arcane-os/ai-runtime-state','modules/AIRuntimeState.js'],
+    ['arcane-os/model-definition','modules/ModelDefinition.js'],
+    ['arcane-os/conversation-timebox','modules/ConversationTimebox.js'],
+    ['arcane-os/conversation-action-items','modules/ConversationActionItems.js'],
+    ['arcane-os/conversation-closing-report','modules/ConversationClosingReport.js'],
+    ['arcane-os/chat-records','modules/ChatRecords.js'],
+    ['arcane-os/app-data-scope','modules/AppDataScope.js'],
+    ['arcane-os/core-local-model-catalog','modules/CoreLocalModelCatalog.js'],
+    ['arcane-os/dbopfs-document-library','modules/DBOPFSDocumentLibrary.js'],
+    ['arcane-os/local-ai-readiness','modules/LocalAIReadiness.js'],
+    ['arcane-os/ollama-model-identifier','modules/OllamaModelIdentifier.js'],
+    ['arcane-os/mail','modules/MailApi.mjs']
 ]);
 const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/event-manager',SDK_BROWSER_ENTRY],
@@ -1436,16 +1454,33 @@ async function physicalRuntime(workspaceRoot,signal){
 }
 
 async function managedImportMapBuild(resolvedWorkspace,signal,pwaEnabled=false){
+    const installed=await readInstalledSdkLayout(resolvedWorkspace);
     const [runtime,version]=await Promise.all([
-        physicalRuntime(resolvedWorkspace,signal),
-        pwaEnabled?null:readWorkspaceAssetVersion(resolvedWorkspace)
+        installed?installedRuntimeFiles(resolvedWorkspace,installed,signal):physicalRuntime(resolvedWorkspace,signal),
+        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};
 }
 
 export async function readWorkspaceAssetVersion(workspaceRoot){
+    const installed=await readInstalledSdkLayout(workspaceRoot);
+    if(installed)return installed.version;
     let source;
     try{source=await readFileFromDisk(path.join(workspaceRoot,'arcane.lock.json'),'utf8');}
     catch(error){
@@ -2158,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=>({
@@ -2320,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;
 }
@@ -2434,10 +2470,17 @@ export async function readApplicationTestImportMapContext({
         ||is.array(document.imports)){
         fail('Application test import-map artifact must contain an imports object.');
     }
+    const installed=await readInstalledSdkLayout(resolvedWorkspaceRoot);
+    const imports=installed?Object.fromEntries(Object.entries(document.imports).map(
+        function installedApplicationTestTarget([specifier,target]){
+            return [specifier,is.string(target)&&target.startsWith('./')
+                ?`./${installedRuntimeTarget(target.slice(2),installed)}`:target];
+        }
+    )):document.imports;
     return createApplicationTestImportMapContext({
         applicationRoot:resolvedWorkspaceRoot,
         boundary:'source',
-        imports:document.imports,
+        imports,
         signal
     });
 }
@@ -2762,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);
@@ -2792,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/mail-api.mjs

@@ -1,19 +1,2 @@
-export {
-    default,
-    default as Mail,
-    resolveMailConfig
-} from '../runtime/arcane/modules/Mail.js';
-export {
-    MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS,
-    MAIL_OUTBOX_PROTOCOL,
-    MAIL_OUTBOX_STATES,
-    MAIL_OUTBOX_TABLE,
-    MailOutbox,
-    createMailOutbox
-} from '../runtime/arcane/modules/MailOutbox.mjs';
-export {
-    MailTransportError,
-    normalizeMailEndpoint,
-    sendMailReport,
-    serializeMailReport
-} from '../runtime/arcane/modules/MailTransport.mjs';
+export {default} from '../runtime/arcane/modules/MailApi.mjs';
+export * from '../runtime/arcane/modules/MailApi.mjs';