arcane-os 0.51.2 → 0.52.1

package/src/dev-server.mjs

@@ -324,7 +324,8 @@ async function serveGeneratedRepresentation(fileServer, request, response, {
 }
 
 async function serveSourceFile(fileServer, request, response, opened, {
-    assetVersion, revalidate = false, onReference, pwaEntry = false, lastModified
+    assetVersion, revalidate = false, onReference, pwaEntry = false, lastModified,
+    representationTracked = false
 } = {}) {
     const extension = path.extname(opened.candidate).toLowerCase();
     const rewrite = assetVersion !== undefined && /\.(?:m?js|html?|css|json)$/iu.test(extension);
@@ -336,9 +337,27 @@ async function serveSourceFile(fileServer, request, response, opened, {
         response.writeHead = function writeDevelopmentHeaders(...arguments_) {
             this.removeHeader('ETag');
             this.removeHeader('X-Content-Type-Options');
+            if (representationTracked) {
+                if (lastModified) this.setHeader('Last-Modified', lastModified.toUTCString());
+                else this.removeHeader('Last-Modified');
+            }
             return writeHead.apply(this, arguments_);
         };
-        await fileServer.serveFile(opened.candidate, request, response);
+        const modifiedSince = request.headers['if-modified-since'];
+        const range = request.headers.range;
+        if (representationTracked) {
+            const currentTime = lastModified ? Date.parse(lastModified.toUTCString()) : NaN;
+            if (!(Date.parse(modifiedSince) >= currentTime)) delete request.headers['if-modified-since'];
+            if (request.headers['if-range'] && !(Date.parse(request.headers['if-range']) >= currentTime)) {
+                delete request.headers.range;
+            }
+        }
+        try {
+            await fileServer.serveFile(opened.candidate, request, response);
+        } finally {
+            if (modifiedSince !== undefined) request.headers['if-modified-since'] = modifiedSince;
+            if (range !== undefined) request.headers.range = range;
+        }
         return;
     }
     await serveGeneratedRepresentation(
@@ -514,17 +533,23 @@ function applicationSourcePath(config,appId,relative='') {
     return `/${root?`${root}/`:''}${relative}`;
 }
 
+function selectedApplicationDocument(app,relative){
+    return app.documents===undefined||relative===app.entry||app.documents.includes(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);
     const canonical=await canonicalRealDirectory(requested,'Packaged release root');
     let pwa = false;
     let startPath = '/index.html';
+    let rootDocument = null;
     try {
         const release = JSON.parse(
             await readFile(path.join(canonical, 'ARCANE_APP_RELEASE.json'), 'utf8')
         );
         const start = release.app.start ?? release.app.entry;
+        if (release.app.rootDocument === './index.html') rootDocument = '/index.html';
         const startUrl = new URL(start, 'http://arcane.invalid/');
         startPath = `${startUrl.pathname}${startUrl.search}${startUrl.hash}`;
     } catch (error) {
@@ -541,6 +566,7 @@ async function packagedRoutes(releaseRoot){
         appId:null,
         pwa,
         startPath,
+        rootDocument,
         mappings:[{
             prefix:[],
             root:canonical
@@ -548,7 +574,7 @@ async function packagedRoutes(releaseRoot){
     };
 }
 
-async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourcePaths) {
+async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourcePaths, runtimeDocuments = new Set()) {
     const records = new Map();
     const resources = new Map();
     for (const mapping of mappings) {
@@ -590,7 +616,7 @@ async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourc
     const pending = [{url: entryUrl, documentUrl: entryUrl}];
     const visited = new Set();
     const referencesByPath = new Map();
-    for (const selected of routeSet.app.include) {
+    for (const selected of routeSet.app.documents ?? routeSet.app.include) {
         if (!/\.html?$/iu.test(selected)) continue;
         const url = new URL(
             applicationSourcePath(routeSet.config,routeSet.appId,selected.split('/').map(encodeURIComponent).join('/')),
@@ -609,6 +635,9 @@ async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourc
         if (!/\.(?:m?js|html?|css)$/iu.test(pathname) && !managedMap) continue;
         visited.add(context);
         resourcePaths.add(decodeURIComponent(pathname));
+        if (record.mapping.kind !== 'app' && /\.html?$/iu.test(pathname)) {
+            runtimeDocuments.add(decodeURIComponent(pathname));
+        }
         let references = referencesByPath.get(pathname);
         if (!references) {
             const opened = await openSafeFile(record.mapping.root, record.relative);
@@ -654,6 +683,9 @@ async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourc
             }
             if (target.origin !== origin || !resources.has(target.pathname)) continue;
             resourceUrls.add(`${target.pathname}${target.search}`);
+            const targetRecord = resources.get(target.pathname);
+            if (kind === 'document' && targetRecord.mapping.kind === 'app'
+                && !selectedApplicationDocument(routeSet.app, targetRecord.relative.join('/'))) continue;
             const traversable = kind !== 'fetch'
                 && (kind !== 'asset' || /\.css(?:[?#]|$)/iu.test(url));
             if (traversable) {
@@ -942,21 +974,33 @@ async function startOwnedDevServer({
         );
         return managed;
     }
-    function sourceRepresentationModifiedAt(opened, version, pwaEntry) {
+    function sourceRepresentation(opened, version, pwaEntry, rewritten) {
         const modifiedAt = opened.modifiedAt.getTime();
         const previous = representationMetadata.get(opened.candidate);
         if (previous?.modifiedAt === modifiedAt
-            && previous.version === version && previous.pwaEntry === pwaEntry) {
-            return previous.lastModified;
+            && previous.version === version && previous.pwaEntry === pwaEntry
+            && previous.rewritten === rewritten) {
+            if (!previous.lastModified && Date.now() >= previous.ambiguousThrough + 1000) {
+                previous.lastModified = new Date();
+            }
+            return previous;
         }
         const lastModified = new Date(
             Math.max(modifiedAt, generatorModifiedAt, assetVersionModifiedAt, previous ? Date.now() : 0)
         );
-        representationMetadata.set(
-            opened.candidate,
-            {modifiedAt, version, pwaEntry, lastModified}
-        );
-        return lastModified;
+        const previousTime = previous?.lastModified
+            ? Date.parse(previous.lastModified.toUTCString()) : previous?.ambiguousThrough;
+        // HTTP dates cannot distinguish two representations within one second.
+        // Omit that ambiguous validator until a later request can date it honestly.
+        const ambiguous = previousTime !== undefined
+            && Date.parse(lastModified.toUTCString()) <= previousTime;
+        const record = {
+            modifiedAt, version, pwaEntry, rewritten,
+            lastModified: ambiguous ? undefined : lastModified,
+            ambiguousThrough: ambiguous ? previousTime : undefined
+        };
+        representationMetadata.set(opened.candidate, record);
+        return record;
     }
     for(const mapping of mappings){
         const info=await lstat(mapping.root);
@@ -985,19 +1029,30 @@ async function startOwnedDevServer({
     }
     async function readCurrentSourceRoutes() {
         throwIfAborted(signal);
+        function optionalSourceMetadata(error) {
+            if (error.code !== 'ENOENT') throw error;
+            return null;
+        }
         let manifestPath = path.join(appMapping.root, APP_DESCRIPTOR_NAME);
+        const [rootIndex, descriptorInput] = await Promise.all(
+            [
+                lstat(path.join(routeSet.workspaceRoot, 'index.html')).catch(optionalSourceMetadata),
+                lstat(manifestPath).catch(optionalSourceMetadata)
+            ]
+        );
+        const rootDocument = rootIndex?.isFile() ? '/index.html' : null;
         let authored = true;
-        let input;
-        try {
-            input = await lstat(manifestPath);
-        } catch (error) {
-            if (error.code !== 'ENOENT') throw error;
+        let input = descriptorInput;
+        if (!input) {
             authored = false;
             manifestPath = path.join(appMapping.root, APP_CONFIG_NAME);
             input = await lstat(manifestPath);
         }
         if (sourceManifestInput?.path === manifestPath
             && sourceManifestInput.modifiedAt === input.mtimeMs) {
+            if (currentSourceRoutes.rootDocument !== rootDocument) {
+                currentSourceRoutes = {...currentSourceRoutes, rootDocument};
+            }
             return currentSourceRoutes;
         }
         const value = JSON.parse(await readFile(manifestPath, 'utf8'));
@@ -1019,6 +1074,7 @@ async function startOwnedDevServer({
         currentSourceRoutes = {
             ...routeSet,
             app: manifest,
+            rootDocument,
             startPath: applicationSourcePath(routeSet.config,routeSet.appId,manifest.entry),
             mappings: mappings.map(
                 function currentSourceMapping(mapping) {
@@ -1035,7 +1091,7 @@ async function startOwnedDevServer({
     function developmentPwaArtifacts(selectedRoutes, assets = [], version = assetVersion) {
         const rootApp = selectedRoutes.config.appsRoot === '.';
         const appBase = applicationSourcePath(selectedRoutes.config,selectedRoutes.appId);
-        const navigationAliases = {'/': selectedRoutes.startPath};
+        const navigationAliases = selectedRoutes.rootDocument ? {} : {'/': selectedRoutes.startPath};
         return createPwaArtifacts(
             {
                 app: {
@@ -1063,12 +1119,21 @@ async function startOwnedDevServer({
     function rememberPwaArtifacts(state, artifacts, generatedAt = new Date()) {
         for (const file of artifacts.files) {
             const previous = state.metadata.get(file.path);
-            const lastModified = previous?.content === file.content
+            const previousTime = previous?.lastModified
+                ? Date.parse(previous.lastModified.toUTCString()) : previous?.ambiguousThrough;
+            let lastModified = previous?.content === file.content
                 ? previous.lastModified
                 : generatedAt;
+            if (!lastModified && generatedAt.getTime() >= previousTime + 1000) {
+                lastModified = generatedAt;
+            }
+            // A changed alias must not validate the prior body within one HTTP second.
+            const ambiguous = previous?.content !== file.content && previousTime !== undefined
+                && Date.parse(generatedAt.toUTCString()) <= previousTime;
+            if (ambiguous) lastModified = undefined;
             state.metadata.set(
                 file.path,
-                {content: file.content, lastModified}
+                {content: file.content, lastModified, ambiguousThrough: lastModified ? undefined : previousTime}
             );
         }
         state.artifacts = artifacts;
@@ -1089,7 +1154,7 @@ async function startOwnedDevServer({
                 const generatedAt = new Date();
                 state.inventoryTask = Promise.all(
                     [
-                        sourcePwaAssets(selectedRoutes, selectedRoutes.mappings, signal, pwaResourceUrls, resourcePaths),
+                        sourcePwaAssets(selectedRoutes, selectedRoutes.mappings, signal, pwaResourceUrls, resourcePaths, runtimeDocuments),
                         selectedAssetVersion().then(
                             function rememberCurrentInventoryVersion(version) {
                                 if (selectedRoutes === currentSourceRoutes) rememberAssetVersion(version);
@@ -1124,6 +1189,66 @@ async function startOwnedDevServer({
     // Remember actual resource edges as their owners are served, not every
     // HTML/JS/CSS file in an application's document or attachment corpus.
     const resourcePaths=new Set([routeSet.startPath]);
+    const runtimeDocuments=new Set();
+    const componentReferences=new Map();
+    async function isCurrentComponent(targetPath, selectedRoutes) {
+        // Retain parsed edges, not lifetime classifications. Only current page
+        // roots and observed runtime documents can make an original a component.
+        const pending = [selectedRoutes.startPath, ...runtimeDocuments];
+        for (const document of selectedRoutes.app.documents) {
+            pending.push(applicationSourcePath(selectedRoutes.config, selectedRoutes.appId, document));
+        }
+        const visited = new Set();
+        for (const ownerPath of pending) {
+            throwIfAborted(signal);
+            if (visited.has(ownerPath)) continue;
+            visited.add(ownerPath);
+            const target = parseRequestTarget(ownerPath.split('/').map(encodeURIComponent).join('/'));
+            if (!target) continue;
+            const mapping = selectedRoutes.mappings.find(function componentOwnerMapping(route) {
+                return route.prefix.every(function componentOwnerSegment(segment, index) {
+                    return target.segments[index] === segment;
+                });
+            });
+            if (!mapping) continue;
+            const relative = target.segments.slice(mapping.prefix.length);
+            if (!relative.length || (mapping.allow && !mapping.allow(relative))) continue;
+            if (!/\.html?$/iu.test(ownerPath)) continue;
+            const opened = await openSafeFile(mapping.root, relative, {readContent: false});
+            if (!opened) continue;
+            const modifiedAt = opened.modifiedAt.getTime();
+            let record = componentReferences.get(opened.candidate);
+            if (record?.modifiedAt !== modifiedAt) {
+                const references = [];
+                rewriteAssetReferences(await readFile(opened.candidate, 'utf8'), {
+                    filePath: opened.candidate,
+                    version: null,
+                    onReference: function currentComponentReference(reference) {
+                        if (reference.kind === 'component') references.push(reference);
+                    }
+                });
+                record = {modifiedAt, references};
+                componentReferences.set(opened.candidate, record);
+            }
+            const ownerUrl = new URL(target.pathname, 'http://arcane.invalid');
+            for (const reference of record.references) {
+                let component;
+                try {
+                    component = resolveAssetReference(reference, {ownerUrl});
+                } catch {
+                    // Non-URL values retain their authored behavior.
+                    continue;
+                }
+                if (component.origin !== ownerUrl.origin) continue;
+                const componentTarget = parseRequestTarget(component.pathname);
+                if (!componentTarget) continue;
+                const componentPath = componentTarget.path;
+                if (componentPath === targetPath) return true;
+                pending.push(componentPath);
+            }
+        }
+        return false;
+    }
     const requestTasks=new Set();
     const runFileWork=createFileWorkLimiter();
     async function serveDevelopmentRequest(request, response) {
@@ -1176,22 +1301,29 @@ async function startOwnedDevServer({
                 );
                 return;
             }
-            if(segments.length===0){
+            const rootRequest = segments.length === 0;
+            if (rootRequest && !selectedRoutes.rootDocument) {
                 response.writeHead(302,{location:`${selectedRoutes.startPath}${target.search}`});
                 response.end();
                 return;
             }
-            const mapping = selectedRoutes.mappings.find(
-                function requestedSourceMapping(route) {
-                    return route.prefix.every(
-                        function matchingSourcePrefix(segment, index) {
-                            return segments[index] === segment;
-                        }
-                    );
-                }
-            );
+            const resourceSegments = rootRequest ? ['index.html'] : segments;
+            const hostRoot = rootRequest && mode === 'source'
+                && (selectedRoutes.config.appsRoot !== '.' || !sourcePathAllowed(resourceSegments, selectedRoutes.app));
+            // Only the host's exact root document is outside app selection.
+            // Its direct URL and every other resource keep the selected routes.
+            const mapping = hostRoot ? {kind: 'host', root: selectedRoutes.workspaceRoot, prefix: []}
+                : selectedRoutes.mappings.find(
+                    function requestedSourceMapping(route) {
+                        return route.prefix.every(
+                            function matchingSourcePrefix(segment, index) {
+                                return resourceSegments[index] === segment;
+                            }
+                        );
+                    }
+                );
             if(!mapping){deny(response,404,'Not found.');return;}
-            const relative=segments.slice(mapping.prefix.length);
+            const relative=resourceSegments.slice(mapping.prefix.length);
             if(relative.length===0){deny(response,404,'Not found.');return;}
             if(mapping.allow&&!mapping.allow(relative)){deny(response,404,'Not found.');return;}
             await runFileWork(async function serveMappedResource() {
@@ -1206,29 +1338,51 @@ async function startOwnedDevServer({
                     deny(response,404,'Not found.');
                     return;
                 }
+                if (hostRoot) {
+                    const representation = sourceRepresentation(opened, assetVersion, false, false);
+                    await serveSourceFile(
+                        fileServer,
+                        request,
+                        response,
+                        opened,
+                        {lastModified: representation.lastModified, representationTracked: true}
+                    );
+                    return;
+                }
+                const resourcePath = rootRequest ? selectedRoutes.rootDocument : target.path;
                 const extension=path.extname(opened.candidate).toLowerCase();
                 const html=extension==='.html'||extension==='.htm';
+                const explicitDocuments = mode === 'source' && mapping.kind === 'app'
+                    && selectedRoutes.app.documents !== undefined;
+                const explicitDocument = explicitDocuments && html
+                    && selectedApplicationDocument(selectedRoutes.app, relative.join('/'));
                 const selectedPwaDocument = mode === 'source' && pwaEnabled && html
                     && mapping.kind === 'app'
-                    && selectedRoutes.app.include.includes(relative.join('/'));
-                const selectedDocument = target.path === selectedRoutes.startPath || selectedPwaDocument;
-                const managedDocument = !selectedDocument && html && await isManagedDocument(opened);
+                    && !explicitDocuments && selectedRoutes.app.include.includes(relative.join('/'));
+                const selectedDocument = resourcePath === selectedRoutes.startPath || explicitDocument || selectedPwaDocument;
+                const managedDocument = !selectedDocument && !explicitDocuments && html && await isManagedDocument(opened);
                 const entryDocument = selectedDocument || managedDocument;
                 const managedMap=path.basename(opened.candidate)==='arcane.importmap.json';
                 // 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=mapping.kind!=='app';
+                if (runtimeResource && html) runtimeDocuments.add(resourcePath);
                 const browserResource=['script','style','worker','sharedworker','serviceworker']
                     .includes(request.headers['sec-fetch-dest']);
-                const rewrite=runtimeResource||entryDocument||browserResource||managedMap
-                    ||resourcePaths.has(target.path);
+                // Selecting application pages does not turn retained originals
+                // into resources. HTML components remain owned by html-import.
+                const componentDocument=explicitDocuments&&html&&!selectedDocument
+                    &&await isCurrentComponent(resourcePath, selectedRoutes);
+                const retainedDocument=explicitDocuments&&html&&!selectedDocument&&!componentDocument;
+                const rewrite=!retainedDocument&&(runtimeResource||entryDocument||browserResource||managedMap
+                    ||componentDocument||resourcePaths.has(resourcePath));
                 const onReference = function observeServedResource(reference) {
                     const {url,kind,baseKind}=reference;
                     if (pwaEnabled && kind !== 'fetch'
                         && !(kind === 'import' && !/^(?:\.{1,2}\/|\/)/u.test(url))) {
                         try {
-                            const documentUrl = new URL(target.path, 'http://arcane.invalid');
+                            const documentUrl = new URL(resourcePath, 'http://arcane.invalid');
                             const resource = resolveAssetReference(
                                 {...reference,url:versionAssetUrl(url,null)},
                                 {ownerUrl:documentUrl}
@@ -1243,11 +1397,17 @@ async function startOwnedDevServer({
                     if(baseKind==='document'||kind==='fetch'||(kind==='asset'&&!/\.css(?:[?#]|$)/iu.test(url))
                         ||(kind==='import'&&!/^(?:\.{1,2}\/|\/)/u.test(url)))return;
                     try{
-                        const documentUrl=new URL(target.path,'http://arcane.invalid');
+                        const documentUrl=new URL(resourcePath,'http://arcane.invalid');
                         const resource=resolveAssetReference(reference,{ownerUrl:documentUrl});
                         if(resource.origin===documentUrl.origin
                             &&/\.(?:m?js|html?|css)$/iu.test(resource.pathname)){
-                            resourcePaths.add(decodeURIComponent(resource.pathname));
+                            const resourcePath=decodeURIComponent(resource.pathname);
+                            const appPrefix=applicationSourcePath(selectedRoutes.config,selectedRoutes.appId);
+                            const appRelative=resourcePath.startsWith(appPrefix)?resourcePath.slice(appPrefix.length):null;
+                            if(kind==='document'&&mode==='source'&&appRelative!==null
+                                &&sourcePathAllowed(appRelative.split('/'),selectedRoutes.app)
+                                &&!selectedApplicationDocument(selectedRoutes.app,appRelative))return;
+                            resourcePaths.add(resourcePath);
                         }
                     }catch{ /* Non-URL values remain under their existing owner. */ }
                 };
@@ -1255,6 +1415,8 @@ async function startOwnedDevServer({
                 const pwaEntry = mode === 'source' && pwaEnabled && entryDocument;
                 const transformed = pwaEntry || (selectedVersion !== undefined
                     && /\.(?:m?js|html?|css|json)$/iu.test(extension));
+                const representation = transformed || retainedDocument
+                    ? sourceRepresentation(opened, assetVersion, pwaEntry, transformed) : undefined;
                 await serveSourceFile(
                     fileServer,
                     request,
@@ -1265,9 +1427,8 @@ async function startOwnedDevServer({
                         revalidate: pwaEnabled || entryDocument || managedMap,
                         pwaEntry,
                         onReference,
-                        lastModified: transformed
-                            ? sourceRepresentationModifiedAt(opened, assetVersion, pwaEntry)
-                            : undefined
+                        lastModified: representation?.lastModified,
+                        representationTracked: representation !== undefined
                     }
                 );
             });

package/src/packager/core.mjs

@@ -166,6 +166,16 @@ function validatePathList(value,label,{required=false,allowRoot=false}={}){
     return normalized;
 }
 
+export function normalizeAppDocuments(value,label='documents'){
+    if(value===undefined)return undefined;
+    if(!is.array(value))fail(`${label} must be an array of application-relative HTML paths.`);
+    return value.map(function normalizeDocumentPath(entry,index){
+        const document=normalizeRelativePath(entry,`${label}[${index}]`);
+        if(!/\.html?$/iu.test(document))fail(`${label}[${index}] must name an HTML or HTM file.`);
+        return document;
+    });
+}
+
 function isAlwaysForbidden(relative){
     return relative.split('/').some(segment=>{
         const key=pathKey(segment);
@@ -308,7 +318,7 @@ function normalizeOptionalRecord(value,label){
 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','outputDirectory'
+        'localAIModelPolicy','include','exclude','shared','adapter','pwa','outputDirectory','documents'
     ]),`${appId}/${APP_CONFIG_NAME}`);
     if(value.schemaVersion!==1)fail(`${appId}/${APP_CONFIG_NAME}.schemaVersion must be 1.`);
     if(!is.string(value.id)||value.id!==appId||!APP_ID_PATTERN.test(value.id)){
@@ -317,6 +327,7 @@ export function validateAppConfig(value,appId,rootConfig,configPath=path.posix.j
     const displayName=assertPresentationText(value.displayName,`${appId}/${APP_CONFIG_NAME}.displayName`);
     parseSemver(value.version);
     const entry=normalizeRelativePath(value.entry,`${appId}/${APP_CONFIG_NAME}.entry`);
+    const documents=normalizeAppDocuments(value.documents,`${appId}/${APP_CONFIG_NAME}.documents`);
     const outputDirectory=value.outputDirectory===undefined?undefined:normalizeRelativePath(
         value.outputDirectory,`${appId}/${APP_CONFIG_NAME}.outputDirectory`
     );
@@ -355,6 +366,7 @@ export function validateAppConfig(value,appId,rootConfig,configPath=path.posix.j
         displayName,
         version:value.version,
         entry,
+        ...(documents===undefined?{}:{documents}),
         ...(outputDirectory===undefined?{}:{outputDirectory}),
         strategy:value.strategy,
         ...(value.pwa===undefined?{}:{pwa:normalizePwaConfig(value.pwa)}),
@@ -603,7 +615,23 @@ async function collectPackageRecords(context,{signal}={}){
     return records;
 }
 
-async function browserDocuments(records,entry){
+async function browserDocuments(records,entry,selected){
+    if(selected!==undefined){
+        const appRecords=new Map(records.filter(function applicationRecord(record){
+            return record.appRelativePath!==undefined;
+        }).map(function applicationRecordPath(record){
+            return [record.appRelativePath,record];
+        }));
+        const documentPaths=[entry,...[...new Set(selected)].filter(function secondaryDocument(document){
+            return document!==entry;
+        }).sort(compareText)];
+        return Promise.all(documentPaths.map(async function inspectSelectedDocument(documentPath){
+            const record=appRecords.get(documentPath);
+            if(!record)fail(`Application document is missing from the selected files: ${documentPath}.`);
+            const inspected=inspectImportMapHtml(await readFile(record.source,'utf8'),{documentPath});
+            return {path:documentPath,packagePath:record.destination,...copyJson(inspected)};
+        }));
+    }
     let entryDocument=null;
     const documents=[];
     for(const record of records){
@@ -638,12 +666,13 @@ async function optionalDescriptor(context){
 
 async function inspectContext(context,{signal,records}={}){
     const selectedRecords=records??await collectPackageRecords(context,{signal});
-    const documents=await browserDocuments(selectedRecords,context.config.entry);
+    const documents=await browserDocuments(selectedRecords,context.config.entry,context.config.documents);
     return {
         appId:context.appId,
         displayName:context.config.displayName,
         version:context.config.version,
         entry:context.config.entry,
+        ...(context.config.documents===undefined?{}:{documents:[...context.config.documents]}),
         ...(context.config.outputDirectory===undefined?{}:{outputDirectory:context.config.outputDirectory}),
         strategy:context.config.strategy,
         ...(context.config.pwa===undefined?{}:{pwa:copyJson(context.config.pwa)}),
@@ -759,7 +788,7 @@ async function loadAdapter(context){
     return module;
 }
 
-function releaseManifest(context,files,pwaArtifacts){
+function releaseManifest(context,files,pwaArtifacts,rootDocument){
     return {
         schemaVersion:1,
         kind:'arcane-app-release',
@@ -770,6 +799,7 @@ function releaseManifest(context,files,pwaArtifacts){
             version:context.config.version,
             entry:context.config.entry,
             start:packageResourceUrl(appPackagePath(context, context.config.entry)),
+            ...(rootDocument ? {rootDocument} : {}),
             strategy:context.config.strategy,
             shared:[...context.config.shared],
             ...(pwaArtifacts?{pwa:{
@@ -816,6 +846,11 @@ async function packageWithContext(context,options={}){
     const appPath=appRelativeRoot(context.rootConfig,context.appId);
     const entryPath=appPackagePath(context,context.config.entry);
     const records=await collectPackageRecords(context,{signal});
+    const rootDocument = records.some(
+        function selectedRootIndex(record) {
+            return record.destination === 'index.html';
+        }
+    ) ? './index.html' : undefined;
     const inspected=await inspectContext(context,{signal,records});
     if(options.dryRun){
         return {
@@ -859,9 +894,7 @@ async function packageWithContext(context,options={}){
     try{
         async function copyBase() {
             await copyRecords(records,stagingRoot,{signal,onEvent});
-            if (!records.some(function selectedRootIndex(record) {
-                return record.destination === 'index.html';
-            })) {
+            if (!rootDocument) {
                 await writePackageLauncher(context, stagingRoot);
             }
         }
@@ -888,9 +921,12 @@ async function packageWithContext(context,options={}){
         const offlineReferences=new Set();
         const entryUrl=new URL(packageResourceUrl(entryPath),'http://arcane.invalid/');
         const pwaDocumentSources=new Map();
+        const explicitDocumentPaths=context.config.documents===undefined?null:new Set(
+            inspected.browserDocuments.map(function selectedDocumentPath(document){return document.packagePath;})
+        );
         if(pwaEnabled){
-            const documentPaths=new Set([entryPath]);
-            for(const selected of context.config.include){
+            const documentPaths=new Set(explicitDocumentPaths??[entryPath]);
+            for(const selected of explicitDocumentPaths===null?context.config.include:[]){
                 const selectedPath=appPackagePath(context,selected);
                 if(/\.html?$/iu.test(selected)&&inventory.has(selectedPath))documentPaths.add(selectedPath);
             }
@@ -925,6 +961,9 @@ async function packageWithContext(context,options={}){
             ?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));
+        const applicationFiles=new Set(records.filter(function applicationRecord(record){
+            return record.appRelativePath!==undefined;
+        }).map(function applicationDestination(record){return record.destination;}));
         for(const file of files){
             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});
@@ -985,7 +1024,9 @@ async function packageWithContext(context,options={}){
                         if(pwaEnabled&&offlineInventory.has(file)){
                             offlineReferences.add(versionAssetUrl(`.${target.pathname}${target.search}`,null));
                         }
-                        if(traversable)pending.push({
+                        const selectedDocument=kind!=='document'||!applicationFiles.has(file)||explicitDocumentPaths===null
+                            ||explicitDocumentPaths.has(file);
+                        if(traversable&&selectedDocument)pending.push({
                             file,
                             documentUrl:kind==='document'?target
                                 :baseHref?new URL(baseHref,ownerUrl):current.documentUrl
@@ -1013,6 +1054,7 @@ async function packageWithContext(context,options={}){
             sdkVersion:assetVersion,
             pwa:context.config.pwa,
             files,
+            navigationAliases: rootDocument ? {} : {'./': packageResourceUrl(entryPath)},
             assets:[...offlineReferences]
         }):null;
         if(pwaArtifacts){
@@ -1043,7 +1085,7 @@ async function packageWithContext(context,options={}){
             }
             files.sort(compareText);
         }
-        const manifest=releaseManifest(context,files,pwaArtifacts);
+        const manifest=releaseManifest(context,files,pwaArtifacts,rootDocument);
         await writeFile(
             path.join(stagingRoot,RELEASE_MANIFEST_NAME),
             `${JSON.stringify(manifest,null,2)}\n`,

package/src/pwa-worker.mjs

@@ -496,8 +496,10 @@ function installPwaWorker(manifest, clientUrl) {
 
     function staticNavigationResource(url) {
         const document = new URL(url);
-        if (document.origin !== scopeOrigin || !document.search
-            || !/\.html?$/iu.test(document.pathname)) {
+        if (document.origin !== scopeOrigin) return null;
+        if (document.pathname.endsWith('/')) {
+            document.pathname += 'index.html';
+        } else if (!document.search || !/\.html?$/iu.test(document.pathname)) {
             return null;
         }
         document.search = '';

package/src/templates/workspace-template.mjs

@@ -195,10 +195,20 @@ npm run run
 
 The explicit \`import-map\` command refreshes
 \`${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.
+import map in each selected application \`.html\`/\`.htm\` document.
+Optional \`package.documents\` in \`arcane-app.json\` selects literal app-root-relative
+HTML paths already included and not excluded, for example \`["index.html"]\`.
+The entry is always selected first; \`[]\` selects only the entry. Omission
+retains automatic discovery of the entry and included secondary pages with an
+active base. The schema-1 package projection preserves this as \`documents\`,
+including the distinction between omission and an empty list.
+Selected pages retain their existing path-correct base requirement. With an
+explicit list, other included HTML documents retain their exact content, even
+when referenced by an iframe. Document selection leaves serving, packaging and
+offline resource membership unchanged. HTML component processing and shared
+runtime-resource traversal retain their existing behavior.
+Development startup refreshes the selected managed maps; package and build
+consume the saved source maps and the same document selection.
 Commit generated import maps and enabled offline app files. Hosting workflows consume those committed files rather than generating them.
 Named \`${directRuntime?'arcane-os/modules/* and arcane-os/entities/*':'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