arcane-os 0.51.1 → 0.52.0

package/docs/roadmap.md

@@ -1,22 +1,29 @@
 # Development roadmap
 
-The SDK contract keeps target names and operations stable while each current
-development provider gathers its remaining promotion evidence. Each item below
-is small enough to become a GitHub issue without combining every platform into
-one unbounded build.
+The SDK already provides root application scaffolding, direct npm browser
+routes, managed import maps, live source serving, browser/PWA packaging and
+explicit native provider pairing. This roadmap distinguishes those implemented
+contracts from remaining development work. Future items do not select an
+implementation, dependency, publication or deployment.
 
-## Publication prerequisites
+## Current delivery baseline
 
-- Mark the Arcane OS monorepo root package private or give it an internal-only
-  package name before the first `arcane-os` publication.
-- Decide and document the license that permits proprietary applications to
-  bundle the synchronized Arcane runtime.
-- Publish one fresh, never-reused prerelease candidate under only the npm `dev`
-  tag, verify the tarball and
-  provenance, add a second appropriate npm owner, and configure the exact
-  trusted-publisher workflow.
+- SDK publication uses the existing selected-package workflow. `dev` and
+  `latest` are npm channels; `main` remains the canonical source branch. See
+  [publishing](publishing.md) for the selected-artifact procedure.
+- License terms and commercial licensing information are already documented in
+  [LICENSE](../LICENSE), [COMMERCIAL-LICENSE.md](../COMMERCIAL-LICENSE.md) and
+  [NOTICE](../NOTICE).
+- Standalone apps use their repository root and installed npm resources.
+  Explicit multi-app and integrated workspaces retain their selected layout.
+- The browser path includes PWA installation, offline resource selection,
+  conditional refresh and the shared update prompt. Development and packaged
+  preview serving share the published `node-http-server` MIME map.
+- The reusable application release workflow remains unavailable until its
+  checked-in implementation matches the documented package-and-upload contract.
+  This is separate from SDK npm publication.
 
-## App admission and native extraction
+## Native provider continuity
 
 - Keep the implemented process-local `arcane-native-build-plan/1` and
   `arcane-native-builder/1` lifecycle as the single provider seam for the CLI,
@@ -31,16 +38,11 @@ one unbounded build.
 - Preserve the implemented portable, Windows x64, Linux x64, Linux ARM64, and
   Android ARM64 providers as one selected app plus its exact declared dependency
   closure. Add new providers without weakening that release-reader boundary.
-- Extend the implemented same-process retained receipt lifecycle through an
-  authenticated Arcane host broker only when persistent cross-process reuse or
-  restartable app-scoped Core sessions are required.
-- Preserve exact packaged-artifact authority across browser and native plan,
-  verify, and run boundaries; never regress to treating a mutable path or
-  manifest file as a reusable receipt.
-- Add a manifest-declared origin policy for native enforcement and an optional
-  policy-faithful development mode. The current capability-gated loopback host
-  deliberately uses a broad development-only policy so the shared runtime can
-  exercise remote providers, media, WebSockets, and embeds.
+- Keep native build and launch within the paired provider's process lifecycle.
+  Persistent sessions or restartable host integration require a separately
+  selected capability and its owning host implementation.
+- Preserve complete selected app releases through planning, build and run.
+  Explicit verification remains separate from the ordinary build/run lifecycle.
 
 ## Platform adapters
 
@@ -62,6 +64,9 @@ one unbounded build.
   reproducible. The APK contains no native ABI and is architecture-neutral. Add
   AAB, release signing, store publishing, and update continuity only as explicit
   later promotion work.
+- macOS: the current registry provides browser delivery and no native package
+  adapter. A native adapter remains additional platform work; shared portable
+  SDK behavior must keep its declared macOS support.
 
 ## Developer experience
 
@@ -70,8 +75,9 @@ one unbounded build.
   development check, never app discovery or an arbitrary package-script loop.
 - Add the Arcane Developer control panel as a client of the same operation API;
   it stores local repository paths per user and never becomes a second builder.
-- Add authenticated GitHub artifact admission so Arcane OS installs verified
-  releases without cloning proprietary source.
+- Add an Arcane-owned source-development native wrapper around the same live
+  browser surface when that capability is selected. The current native `run`
+  command packages and builds its selected app; it is a different lifecycle.
 - Preserve the implemented integrated app-scoped native path: `--workspace` and
   `--arcane-root` identify the same checkout, one app and one target are
   selected, and `--output-root` remains outside the checkout. Future GUI clients

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.51.1",
+  "version": "0.52.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/runtime/arcane/modules/AI.js

@@ -4448,7 +4448,8 @@ class AI {
             signal,
             payload.reasoningEffort,
             onRetry,
-            payload.model
+            payload.model,
+            payload.temperature
         );
     }
 
@@ -4480,7 +4481,8 @@ class AI {
             payload.reasoningEffort,
             observeToolText,
             onRetry,
-            payload.model
+            payload.model,
+            payload.temperature
         );
     }
 
@@ -4810,7 +4812,8 @@ class AI {
                 normalizedReasoningEffort,
                 observeToolText,
                 onRetry,
-                model
+                model,
+                temperature
             );
             const structuralToolCalls=normalizeAICompletionToolCalls(
                 completion
@@ -4920,7 +4923,8 @@ class AI {
         reasoningEffort,
         observeToolText=null,
         onRetry = null,
-        model=this.model
+        model=this.model,
+        temperature
     ){
         let speechTurnCompleted=false;
 
@@ -4949,6 +4953,10 @@ class AI {
             stream:true
         }
 
+        if(this.llmService==='TWIN' && temperature!==undefined){
+            request.temperature=temperature;
+        }
+
         if(structuredOutputFormat){
             request.response_format=openAIResponseFormat(
                 structuredOutputFormat
@@ -5740,7 +5748,8 @@ class AI {
             signal,
             normalizedReasoningEffort,
             onRetry,
-            model
+            model,
+            temperature
         );
     }
 
@@ -5795,7 +5804,8 @@ class AI {
         signal=null,
         reasoningEffort,
         onRetry = null,
-        model=this.model
+        model=this.model,
+        temperature
     ){
         validateAIStructuralRequest(messages,tools,parallel_tool_calls);
         this.#assertServiceConfigured(this.llmService);
@@ -5819,6 +5829,10 @@ class AI {
             stream:false
         }
 
+        if(this.llmService==='TWIN' && temperature!==undefined){
+            request.temperature=temperature;
+        }
+
         if(structuredOutputFormat){
             request.response_format=openAIResponseFormat(
                 structuredOutputFormat

package/schemas/arcane-app.schema.json

@@ -38,6 +38,11 @@
       "required": ["entry", "strategy", "include", "exclude", "shared"],
       "properties": {
         "entry": { "$ref": "#/$defs/relativePath" },
+        "documents": {
+          "type": "array",
+          "description": "Application-relative HTML/HTM pages managed by import-map and PWA processing. Entry is always first; an empty list selects entry only. Omission preserves automatic discovery. File inclusion and serving remain controlled by include/exclude.",
+          "items": { "allOf": [{ "$ref": "#/$defs/relativePath" }, { "pattern": "\\.[Hh][Tt][Mm][Ll]?$" }] }
+        },
         "strategy": { "enum": ["static", "adapter"] },
         "localAIModelPolicy": { "$ref": "#/$defs/localAIModelPolicy" },
         "pwa": { "$ref": "#/$defs/pwa" },

package/schemas/arcane-package.schema.json

@@ -34,6 +34,16 @@
     "entry": {
       "$ref": "#/$defs/relativePath"
     },
+    "documents": {
+      "type": "array",
+      "description": "Application-relative HTML/HTM pages managed by import-map and PWA processing. Entry is always first; an empty list selects entry only. Omission preserves automatic discovery. File inclusion and serving remain controlled by include/exclude.",
+      "items": {
+        "allOf": [
+          { "$ref": "#/$defs/relativePath" },
+          { "pattern": "\\.[Hh][Tt][Mm][Ll]?$" }
+        ]
+      }
+    },
     "outputDirectory": {
       "$ref": "#/$defs/relativePath",
       "description": "Final package directory relative to the workspace, with no appended app ID. Omission preserves dist/<id>. This directory is replaced when packaging succeeds; source layout and app identity remain unchanged."

package/src/app-descriptor.mjs

@@ -12,6 +12,7 @@ import {
 } from './constants.mjs';
 import {
     normalizeRelativePath,
+    normalizeAppDocuments,
     parseSemver,
     validateAppConfig as validateAppPackageConfig
 } from './packager/core.mjs';
@@ -110,9 +111,10 @@ function validateLocalAIModelPolicy(value,label){
 
 function validatePackage(value,appId){
     assertOnlyKeys(value,new Set([
-        'entry','strategy','include','exclude','shared','adapter','localAIModelPolicy','pwa'
+        'entry','strategy','include','exclude','shared','adapter','localAIModelPolicy','pwa','documents'
     ]),'descriptor.package');
     const entry=normalizeRelativePath(value.entry,'descriptor.package.entry');
+    const documents=normalizeAppDocuments(value.documents,'descriptor.package.documents');
     if(!['static','adapter'].includes(value.strategy))fail('descriptor.package.strategy must be static or adapter.');
     const include=relativePaths(value.include,'descriptor.package.include',{required:true});
     const exclude=relativePaths(value.exclude??[],'descriptor.package.exclude');
@@ -134,6 +136,7 @@ function validatePackage(value,appId){
     }
     return completeValue({
         entry,
+        ...(documents===undefined?{}:{documents}),
         strategy:value.strategy,
         include,
         exclude,
@@ -317,6 +320,7 @@ export function projectPackageManifest(descriptor){
         displayName:value.displayName,
         version:value.version,
         entry:value.package.entry,
+        ...(value.package.documents===undefined?{}:{documents:[...value.package.documents]}),
         strategy:value.package.strategy,
         ...(hasAuthoredSecurity?{security:{
             connectOrigins:[...value.security.connectOrigins],
@@ -381,6 +385,7 @@ function synthesizedDescriptor(packageManifest,nativeDescriptor){
         publisher:{id:'publisher-undeclared',name:'Publisher not declared'},
         package:{
             entry:packageManifest.entry,
+            ...(packageManifest.documents===undefined?{}:{documents:[...packageManifest.documents]}),
             strategy:packageManifest.strategy,
             ...(packageManifest.localAIModelPolicy?{localAIModelPolicy:packageManifest.localAIModelPolicy}:{}),
             ...(packageManifest.pwa===undefined?{}:{pwa:packageManifest.pwa}),

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,6 +533,10 @@ 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);
@@ -548,7 +571,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 +613,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 +632,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 +680,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 +971,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);
@@ -1089,7 +1130,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 +1165,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) {
@@ -1208,21 +1309,31 @@ async function startOwnedDevServer({
                 }
                 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 = target.path === 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(target.path);
                 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(target.path, selectedRoutes);
+                const retainedDocument=explicitDocuments&&html&&!selectedDocument&&!componentDocument;
+                const rewrite=!retainedDocument&&(runtimeResource||entryDocument||browserResource||managedMap
+                    ||componentDocument||resourcePaths.has(target.path));
                 const onReference = function observeServedResource(reference) {
                     const {url,kind,baseKind}=reference;
                     if (pwaEnabled && kind !== 'fetch'
@@ -1247,7 +1358,13 @@ async function startOwnedDevServer({
                         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 +1372,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 +1384,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)}),
@@ -888,9 +917,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 +957,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 +1020,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