arcane-os 0.51.2 → 0.52.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.52.0
+
+- Add optional `package.documents` to select managed application HTML separately
+  from files retained by `include` and `exclude`. The schema-1 projection uses
+  top-level `documents`. The entry is always first, `[]` selects the entry only,
+  and omission preserves automatic discovery. Secondary paths retain existing
+  deterministic ordering while the authored declaration remains unchanged.
+- Use that selection across ordinary inspection, import-map generation,
+  development serving, packaging and PWA document processing. Explicitly
+  unselected HTML originals retain their content, including iframe-referenced
+  documents, while remaining included, served, packaged and offline-eligible
+  under the existing resource selection. HTML-import components and shared
+  runtime resources retain their existing processing. No dependency, migration,
+  default selection change or extra CLI flag is introduced.
+
 ## 0.51.2
 
 - Forward caller-selected `temperature` through the focused TWiN Cloud

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.51.2` SDK contract. Applications pin one exact npm
+This checkout defines the `0.52.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/reference/cli.md

@@ -197,19 +197,24 @@ npm exec -- arcane doctor --workspace . --arcane-root "../Arcane OS"
 
 ### Overview
 
-Refreshes one selected application's browser runtime map, generates
-its standard browser import map, discovers every directly navigable
-`.html`/`.htm` document admitted by the selected descriptor's existing
-include/exclude rules, and prepares the map artifact plus those managed documents
-before writing them in order. A directly navigable entry document declares exactly
-one `<meta name="arcane-app-id" content="<selected-id>">`; an unmarked secondary
-document may instead carry an active `<base>`.
-Wrong or duplicate explicit app identity fails. The renderer then requires one
-path-correct base for every selected document. Included HTML files with neither
-the identity marker nor an active base are component fragments: they remain
-package files and are not rewritten with a document-level import map.
-Packaging and development use the same discovery owner. Packaging consumes
-the saved managed import maps in directly navigable source pages.
+Refreshes one selected application's browser runtime map, generates its standard
+browser import map, and prepares the map artifact plus the selected managed
+`.html`/`.htm` documents before writing them in order. Optional
+`package.documents` in `arcane-app.json` selects literal app-root-relative HTML
+paths that are already included and not excluded. The entry is always first;
+`[]` selects only the entry. Omitting the field retains automatic selection of
+the entry and included secondary pages with an active `<base>`. An app identity
+meta tag does not select a page. The renderer requires one path-correct active
+base for each selected document.
+
+The schema-1 package projection carries this field as `documents`, preserving
+the distinction between omission and `[]`. With explicit selection, other
+included HTML documents keep their exact content, including originals referenced
+through iframes. Selection does not change serving, packaging or offline resource
+membership; component processing and shared runtime-resource traversal retain
+their existing behavior. Inspection, packaging and development use the same
+[document-selection contract](protocols.md#application-document-selection).
+Packaging consumes the saved managed import maps in selected source pages.
 
 ```text
 arcane import-map [--workspace <directory>] [--app <id>]
@@ -279,11 +284,12 @@ Success returns the normal selected-workspace wrapper:
 }
 ```
 
-For the direct CLI command, `documentPaths` contains the configured entry first
-and every other descriptor-selected HTML/HTM document afterward in
-deterministic order. The generated artifact is written first, followed by the
-selected documents. A write failure or cancellation can leave earlier writes
-in place; the operation does not restore them automatically. After successful
+For the direct CLI command, `documentPaths` contains the configured entry first.
+Other selected paths follow in deterministic lexical order without duplicates.
+The authored `documents` declaration remains as supplied, including `[]`.
+The generated artifact is written first, followed by the selected documents.
+A write failure or cancellation can leave earlier writes in place; the operation
+does not restore them automatically. After successful
 writes, an observer failure preserves delivery with
 `eventDelivery.status === 'degraded'` and `ARCANE_EVENT_DELIVERY_FAILED`; it
 does not roll back complete application content.

package/docs/reference/protocols.md

@@ -51,16 +51,12 @@ App-scoped managed browser imports have three supported control-plane entrypoint
 uses `arcane import-map`; Node callers use
 `executeOperation('import-map', options)` or
 `createToolchain(defaults).importMap(options)`. These are three routes to the
-same app-scoped operation, not three import-map formats. Each route discovers
-the selected descriptor's directly navigable admitted `.html`/`.htm` documents
-through the package include/exclude rules and writes one canonical map to the
-artifact plus every such document. The current marker is exactly one matching
-`meta[name="arcane-app-id"]`; an unmarked secondary page with an active `base`
-remains admitted under the current secondary-document rule. Wrong or duplicate
-explicit identity fails, and the selected page then must pass exact path-relative
-base validation.
-Included HTML with neither signal is a component fragment and remains a
-complete package file.
+same app-scoped operation, not three import-map formats. Each route uses the
+[application document selection](#application-document-selection) shared by
+inspection, development and packaging, and writes one canonical map to the
+artifact plus every selected document. Each selected page retains the existing
+path-relative base requirement. Included component fragments remain complete
+package files and keep their existing component processing.
 Public lowercase runtime subpaths resolve directly to canonical runtime-module
 namespaces from both Node package exports and managed browser keys. These
 include `arcane-os/preference-store`, `arcane-os/speech-playback`,
@@ -98,6 +94,48 @@ materializes the complete required SDK runtime,
 browser-runtime, and managed-import-map closure inside that app's own artifact.
 No application polls for SDK changes.
 
+## Application document selection
+
+An authored schema-2 `arcane-app.json` may select the HTML pages that receive
+application-document processing through `package.documents`:
+
+```json
+{
+  "package": {
+    "entry": "index.html",
+    "include": ["index.html", "pages", "originals", "modules", "css"],
+    "documents": ["index.html", "pages/viewer.html"]
+  }
+}
+```
+
+This is a package excerpt. Each `documents` member is a literal app-root-relative
+`.html` or `.htm` file path, not a directory or glob. Every selected document
+must already be present in the app's included, non-excluded files. The entry is
+always selected first, followed by the other selected paths in deterministic
+lexical order without duplicates. An empty list selects only the entry. The
+authored `documents` declaration remains as supplied, including `[]`.
+
+Omitting `documents` preserves automatic discovery: the SDK selects the entry
+and included secondary HTML pages with an active `<base>`. A
+`meta[name="arcane-app-id"]` marker does not select a page. Selected pages retain
+the existing requirement for one path-correct active base.
+
+The schema-1 `arcane-package.json` field is `documents` at the top level.
+Descriptor projection and synthesis preserve an omitted property as omitted
+and an authored empty list as `[]`. Package-only applications may author that
+schema-1 field directly. Ordinary inspect, import-map, dev and package operations
+use the same declaration; there is no document-selection CLI flag.
+
+Document selection controls application-document scanning, base handling,
+managed import maps and PWA injection. It does not change `include`/`exclude`,
+serving, package membership or offline resource selection. With an explicit
+list, other included HTML documents retain their exact content, even when a
+selected page references them through an iframe. They remain available as
+included resources without receiving application-document processing.
+Component processing and shared runtime-resource traversal retain their existing
+behavior. Offline inclusion still follows the app's PWA resource selection.
+
 ## App-selected package output
 
 An app may set `"outputDirectory": "ai"` in its schema-1

package/docs/reference/pwa.md

@@ -58,6 +58,27 @@ previous source identity while its start URL and scope move to the root. An
 authored `manifest.id` remains authoritative. Packaged default identity remains
 `./`. App identity and saved application data remain unchanged.
 
+### Application pages and preserved HTML resources
+
+Optional `package.documents` in `arcane-app.json` selects the app-root-relative
+`.html`/`.htm` pages that receive managed import maps and PWA links/bootstrap.
+Its schema-1 projection is `arcane-package.json`'s top-level `documents`.
+For example, `"documents": ["index.html"]` selects the entry while other
+included HTML documents retain their exact content. The entry is always selected;
+`[]` also selects only the entry. Omitting the property preserves automatic
+discovery of the entry and included secondary pages with an active `<base>`.
+Selected pages retain the existing path-correct base requirement.
+
+This declaration does not add or remove resources from `package.include`,
+`package.exclude`, serving, packaging or the offline inventory. Included
+originals remain available and can be cached under the normal offline selection,
+including when a selected page displays them in an iframe. With an explicit
+list, those unselected documents are not scanned as application pages or given
+managed import maps, base handling or PWA injection. HTML-import components and
+shared runtime-resource traversal keep their existing processing. See
+[application document selection](protocols.md#application-document-selection)
+for ordering and the complete declaration contract.
+
 ### Root generated output
 
 For a standalone application, `appsRoot: "."` places the app at its repository
@@ -136,16 +157,18 @@ their app and SDK versions match. It is not a content measurement.
 
 The package owns its selected inventory once, after any app adapter finishes.
 It follows actual resource references to include meaningful query variants.
-Generated application pages receive a manifest link and an `async` module
+Selected application pages receive a manifest link and an `async` module
 marked `data-arcane-pwa`. Existing application scripts retain their order.
 PWA registration does not wait for models, storage, preferences or page rendering.
 The same bootstrap starts one initially hidden `pwa-install.html` component with
 the generated manifest's app name. Component loading and worker registration
 proceed independently.
 
-All SDK browser-resource delivery removes only SDK-owned `arcaneVersion` fields
-from actual local resource references, including the managed import map. Authored
-fields such as `v`, encoded and repeated fields, empty query segments, fragments,
+SDK processing of selected application pages, components and runtime resources
+removes only SDK-owned `arcaneVersion` fields from actual local resource references,
+including the managed import map. Explicitly unselected HTML documents keep their
+exact content. Authored fields such as `v`, encoded and repeated fields, empty
+query segments, fragments,
 source spelling and unrelated payloads are preserved. The offline
 manifest carries release information. Non-PWA and native packaging use the same
 [clean local resource URLs](asset-versioning.md). Native packaging does not
@@ -179,9 +202,9 @@ If `package.pwa.offline.include` is nonempty, the resource must also
 match that offline selection and must not match `offline.exclude`. Adding a
 path only to the offline selection does not add it to the app's resources.
 The running source server reads changed app descriptors before the next app,
-root-navigation or generated-PWA request. Include/exclude rules, the entry and
-PWA settings share the current selection; no restart or package projection
-write is needed. Edits to selected source files are picked up by the next due
+root-navigation or generated-PWA request. Include/exclude rules, the entry,
+document selection and PWA settings share the current selection; no restart or
+package projection write is needed. Edits to selected source files are picked up by the next due
 page-load check while the server remains running.
 
 For an enabled application, `arcane dev` serves the generated PWA files at the

package/docs/reference/sdk-api.md

@@ -779,12 +779,22 @@ async inspectApp({workspaceRoot, appId, signal}={})
 ```
 
 Import it from `arcane-os` or `arcane-os/packager`. The result includes the
-configured `entry`, `include`, and `exclude` values plus `browserDocuments`, the
-entry-first ordered `.html`/`.htm` paths selected by the same package traversal
-used by import-map refresh and packaging. Current pages declare exactly one
-matching `meta[name="arcane-app-id"]`; unmarked pages with an active `base`
-remain selected for patch compatibility. Included HTML with neither signal is
-retained as a package fragment rather than rewritten as a document.
+configured `entry`, `include`, and `exclude` values, the optional `documents`
+declaration when authored, and `browserDocuments`, the entry-first ordered
+`.html`/`.htm` paths shared by import-map refresh, development and packaging.
+`package.documents` in an authored descriptor, or `documents` in a schema-1
+package, selects literal app-root-relative paths already included and not
+excluded. Other selected paths follow the entry in deterministic lexical order
+without duplicates. The authored `documents` declaration remains as supplied,
+including `[]`, which selects only the entry. Omitting the property retains
+automatic discovery of the entry and included secondary pages with an active `<base>`. App identity
+meta tags do not select documents.
+
+Selected pages retain their existing base requirements. Explicit selection
+leaves other included HTML documents unchanged, including iframe-referenced
+originals, while preserving package, serving and offline resource membership.
+Component processing and shared runtime-resource traversal retain their existing
+behavior. See [application document selection](protocols.md#application-document-selection).
 
 `entry` and each app browser document's `path` stay relative to the app
 directory. Each browser document also reports `packagePath`, the emitted path
@@ -2111,6 +2121,11 @@ async function useprojectNativeDescriptor(...arguments_) {
 
 Projects a schema-2 descriptor into the compatible schema-1 application package contract.
 
+Optional `package.documents` becomes top-level `documents`. Omission stays
+omitted and an authored empty list stays `[]`, so projection preserves automatic
+discovery versus entry-only selection. See
+[application document selection](protocols.md#application-document-selection).
+
 ### Signature and result
 
 ```text
@@ -4277,9 +4292,9 @@ async function usedevelopApplication(...arguments_) {
 
 Dispatches one named headless SDK operation with normalized acceptance, events, cancellation, and failure.
 
-The exact command `'import-map'` dispatches one app-scoped refresh
-across directly navigable `.html`/`.htm` documents selected by the descriptor's
-existing include/exclude rules, excluding component fragments, and returns
+The exact command `'import-map'` dispatches one app-scoped refresh across the
+`.html`/`.htm` documents selected by
+[`package.documents` or automatic discovery](protocols.md#application-document-selection), and returns
 `{workspaceRoot, workspaceMode, appId,
 importMap}`. The `importMap` value reports the generated imports and complete
 ordered `documentPaths`. This route mutates the map artifact and selected managed HTML

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.51.2",
+  "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/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

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

package/src/toolchain.mjs

@@ -299,6 +299,7 @@ async function refreshPreparedImportMap(prepared,{signal,onEvent,workspaceOperat
         signal
     });
     if(inspected.entry!==manifest.entry
+        ||JSON.stringify(inspected.documents)!==JSON.stringify(manifest.documents)
         ||JSON.stringify(inspected.include)!==JSON.stringify(manifest.include)
         ||JSON.stringify(inspected.exclude)!==JSON.stringify(manifest.exclude)){
         throw new ArcaneError(