arcane-os 0.51.2 → 0.52.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.52.1
+
+- Preserve an authored host `index.html` at `/` independently of application
+  entry and offline selection. Root import-map/PWA generation no longer aliases
+  that public homepage to the app entry. Existing app-only roots retain their
+  launcher behavior; excluded homepage content and assets stay outside the
+  application's managed documents and offline inventory.
+- Source development follows root-file creation/removal without a descriptor
+  edit, serves an unselected host root unchanged, and avoids stale conditional
+  responses when generated aliases change within one HTTP second. Ordinary
+  selected routes, startup entry, manifest identity and worker lifecycle remain
+  unchanged.
+- Packaged authored roots carry optional generated `app.rootDocument` metadata
+  so preview serves them at `/`; older and app-only packages retain their
+  existing redirects and queries. Worker directory navigation uses only indexes
+  already selected in its current offline inventory, with exact-query priority.
+  No dependency, configuration option, saved-data migration or cache reset is
+  introduced. Consumers regenerate their normal public SDK outputs after update.
+
+## 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.1` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/architecture.md

@@ -145,6 +145,19 @@ one metadata task; unchanged files reuse their parsed selection. Shared runtime
 requests do not wait for that refresh. Full offline inventories are enumerated
 only for worker/offline-manifest requests, with separate state for each selected
 app snapshot so an older inventory cannot overwrite newer generated metadata.
+
+Authored host-root `index.html` presence is refreshed independently of descriptor
+edits. Development serves that host index at `/` instead of redirecting to the
+app entry and suppresses the root PWA alias. An index outside the selected app
+mapping uses an unchanged exact-root response; `/index.html` and other resource
+URLs retain their existing selection rules. A selected index keeps its existing
+document classification. This broadens no app or offline inventory and adds no
+managed maps or bootstrap. With no host index, the app-entry redirect remains.
+A worker serves a directory's cached index body only when that index is already
+in its current offline selection; otherwise the host owns the unchanged request.
+The selected app launch and installation identity remain independent of this
+host-root navigation.
+
 Changed resource requests return the complete current saved source without
 packaging, copying files into `dist`, or restarting the server. Conditional
 requests for unchanged resources return `304`. Enabled PWAs check on page load
@@ -253,9 +266,12 @@ separate. See the [complete output contract](reference/protocols.md#app-selected
 
 Packaging keeps standalone app files at the release root and places an explicitly
 nested app beneath `apps/<id>/`. It preserves every shared route destination.
-When selected content supplies no root `index.html`, the SDK generates one that
-opens the selected app entry. Authored document bases, app URLs, relative module
-imports and shared runtime paths therefore resolve through the same layout in
+A selected authored output-root `index.html` is preserved and suppresses the
+deployment-root PWA navigation alias. When selected content supplies no root
+index, the SDK generates a launcher and retains the selected app-entry alias;
+an excluded source-host index does not alter that package result. Authored
+document bases, app URLs, relative module imports and shared runtime paths
+therefore resolve through the same layout in
 source development and packaged delivery. Packaging consumes the saved source
 and managed import maps; use `arcane import-map` to refresh those maps, or the
 ordinary `arcane dev` startup that performs that refresh.
@@ -266,6 +282,13 @@ entry, or `./apps/hello-world/index.html` for a nested app. Its complete `files`
 inventory follows the selected layout and includes the root `index.html`.
 Packaged browser serving opens `app.start`; a previously generated flat release without `app.start` retains
 its `app.entry` launch path.
+Only selected records supplying an authored output-root index add the optional
+generated `app.rootDocument: "./index.html"` release field. Preview serves that
+document at `/` without inferring ownership from HTML content. When the field is
+absent, older releases and generated-launcher packages retain their existing
+`302` root redirect to `app.start` or the older `app.entry` fallback, preserving
+the request query. This release fact adds no app configuration or API option and
+does not change `app.start`.
 
 The authored schema-2 descriptor is canonical for new apps and projects an
 exact schema-1 `arcane-package.json` for current consumers. Existing Arcane

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>]
@@ -240,6 +245,12 @@ files remain unchanged. The same layout applies to `arcane dev` and
 `arcane package`. Generated and offline app files are committed; GitHub Actions
 consume those committed files. See [root generated output](pwa.md#root-generated-output).
 
+An existing authored source-host `index.html` suppresses the generated `/`
+navigation alias even when the page is outside the application or offline
+selection. It is not automatically added to either inventory or given managed
+maps or PWA bootstrap. The selected app entry and installation identity remain
+unchanged; see [authored host roots](pwa.md#authored-host-root-and-app-entry).
+
 The supported physical layout preserves its route count and ordered include
 list. External and modern integrated physical routes require `components`, `css`,
 `dependencies`, `entities`, `img`, `modules`, and `sdk`; a physical workspace
@@ -279,11 +290,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.
@@ -367,6 +379,16 @@ not package the app or produce `dist` output. With PWA enabled, the server
 generates the installation and offline manifests directly; see
 [PWA development and versioning](pwa.md#development-and-hosting).
 
+The startup URL remains the selected app entry. At `/`, the server serves an
+existing authored host-root `index.html` and suppresses the app-entry redirect
+and PWA alias. A root outside the selected app mapping is served unchanged only
+through this exact-root route; `/index.html` and other resource URLs retain their
+existing selection rules. A selected root follows its existing document
+classification. Root presence does not expand either inventory or cause
+bootstrap injection. With no host index, the app-entry redirect remains.
+Root-file creation or removal is reflected in subsequent root-navigation and
+generated-PWA requests without a restart or a descriptor edit.
+
 The command reports acceptance before bind/start work, emits the final URL,
 owns the server until cancellation, and restores failure to the process exit.
 The default host is `127.0.0.1`. `--public` selects `0.0.0.0` (all IPv4
@@ -544,8 +566,11 @@ defaulting to `dist/<id>/`, and preserves the prior output until the replacement
 is complete. It consumes saved source and managed
 import maps, keeps standalone app files at the output root, and retains the
 configured shared route destinations. Explicit multi-app workspaces retain
-their selected app beneath `apps/<id>/`. When selected shared content supplies no root
-`index.html`, the SDK generates one that opens the selected app entry.
+their selected app beneath `apps/<id>/`. A selected authored output-root
+`index.html` is preserved and suppresses the deployment-root PWA navigation
+alias. When selected content supplies no root index, the SDK generates a launcher
+and retains the app-entry alias. An excluded source-host root does not change
+that package selection.
 Source document bases and resource URLs therefore retain their development
 layout. Packaging does not run tests or checks automatically.
 
@@ -578,6 +603,10 @@ The result includes the release root, manifest, and complete selected inventory.
 the package launch URL in `app.start`: `./index.html` for a root app with that
 entry, or `./apps/hello-world/index.html` for a nested app. The complete file
 inventory follows the selected layout and includes the root `index.html`.
+Only selected records supplying an authored output-root index add
+`app.rootDocument: "./index.html"`. This optional generated release fact selects
+root-document serving in preview; it is not an app configuration or CLI option
+and does not change `app.start`.
 `--dry-run` plans the package without refreshing source, running tests, or
 replacing output.
 
@@ -743,6 +772,11 @@ For `--target browser`, starts the existing release in the app's configured
 does not package, rebuild, test, check, or verify that release automatically.
 It opens the release manifest's `app.start` URL. Older flat releases without
 that field continue to open their `app.entry` path.
+Requests to `/` serve the explicit `app.rootDocument` when that generated
+release field is present. With no field, including older releases and app-only
+packages with a generated launcher, `/` retains its `302` redirect to
+`app.start` or the older `app.entry` fallback, preserving the request query.
+Preview does not infer root ownership from HTML content.
 The preview always uses HTTPS with the workspace certificate pair. Supply
 `--cert <file> --key <file>` together to use another pair; see
 [development HTTPS setup](#development-https-setup).

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
@@ -213,15 +251,34 @@ The declared application ID remains unchanged. `appsRoot: "apps"` continues
 to discover `apps/<id>` and supports the existing integrated and multi-app
 layouts. Entries and include/exclude paths remain relative to the application.
 
-Root HTML uses `<base href="./">`; nested navigable documents use their actual
-depth back to the workspace. Managed bare imports remain the public interface;
-their targets follow the selected npm routes. `arcane import-map` generates
-enabled static PWA records at the app root, so normal static hosting needs no
+SDK-managed root HTML uses `<base href="./">`; nested navigable documents use
+their actual depth back to the workspace. Managed bare imports remain the
+public interface; their targets follow the selected npm routes. `arcane import-map`
+generates enabled static PWA records at the app root, so normal static hosting needs no
 SDK request handler or runtime copy. Managed refresh, development serving,
 inspection, dry run and packaging add no nested `apps/<id>/` navigation pages,
 redirects, or duplicate PWA worker/inventory files. There is no output-retention
 switch for those retired records.
 
+An authored source-host `index.html` suppresses the root app-entry redirect and
+generated PWA navigation alias even when that file is outside the application's
+include or offline selection. Development serves that host index at `/`. An
+index outside the selected app mapping uses an unchanged exact-root response;
+`/index.html` and other resource URLs retain their existing selection rules.
+A selected index follows the existing document classification. Root presence
+adds no page, assets, managed maps, or PWA bootstrap to the application. With no
+host index, development retains the app-entry redirect. In a package, only a
+selected authored output-root index suppresses the alias; an absent or excluded
+root retains the generated launcher and app-entry alias. Selected records that
+supply an authored output-root index add the optional generated release field
+`app.rootDocument: "./index.html"`. Preview serves that document at `/`; absence
+retains the existing `302` to `app.start` or the older `app.entry` fallback with
+the request query preserved. This is a release fact, not an app setting or HTML
+content inference, and `app.start` remains unchanged. The worker can answer a
+directory navigation from an index only when that index already belongs to its
+current offline selection and has a cached response; otherwise the unchanged
+request remains host-owned. See [authored host roots](pwa.md#authored-host-root-and-app-entry).
+
 Application identity, stored data, the existing default installation ID and an
 authored `pwa.manifest.id` remain unchanged. Authored resources continue to
 follow the app's include/exclude selection; generation does not delete existing

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
@@ -81,6 +102,38 @@ committed files rather than generating them. Actual multi-app workspaces keep
 their explicit `appsRoot: "apps"` layout. This source/package contract does not
 establish any particular installed application's browser lifecycle.
 
+### Authored host root and app entry
+
+An authored `index.html` at the source host root keeps `/` separate from the
+selected application entry. Root import-map generation and development PWA
+generation omit the `/`-to-entry navigation alias whenever that file exists,
+including when it is outside `package.include` or the offline selection.
+Development serving answers `/` with that host index. An index outside the app's
+selected source mapping is served unchanged through this exact-root route;
+`/index.html` and other resource URLs retain their existing selection rules.
+A selected index follows its existing managed-document classification. Root
+presence alone adds no page or assets to the application or offline inventory
+and adds no managed maps or PWA bootstrap. The host owns a root response outside
+the worker's selected offline resources. With no host index, development retains
+its app-entry redirect.
+
+Packaging considers the selected output instead of unrelated source-host files.
+A selected authored output-root `index.html` is preserved and suppresses the
+deployment-root navigation alias. When selected content supplies no output-root
+index, the package retains its generated launcher and app-entry alias. An
+authored source root excluded from the package does not replace that launcher.
+Only when selected records supply an authored output-root index does packaging
+write `app.rootDocument: "./index.html"` in `ARCANE_APP_RELEASE.json`.
+Packaged preview uses that generated field to serve the authored document at
+`/`; it does not inspect HTML to infer root ownership. Without the field,
+including older releases and generated-launcher packages, preview retains its
+`302` redirect to `app.start` (or the older `app.entry` fallback), preserving the
+request query. The startup URL remains the selected app launch URL.
+
+This behavior requires no new setting. The application entry, default install
+start URL, manifest identity and scope, worker registration scope, cache
+identity, and saved application data keep their existing contracts.
+
 ### Offline resource selection
 
 `offline.include` and `offline.exclude` select literal paths or directory
@@ -136,16 +189,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 +234,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
@@ -281,8 +336,10 @@ therefore matters even when an offline cache exists. Updating files in place
 while installation fetches them is not an atomic release snapshot; the host owns
 consistent deployment of the selected output.
 
-An offline navigation alias redirects to its selected entry page, preserving the
-document URL used to resolve relative modules and styles.
+Where an app-entry navigation alias remains, it redirects to the selected entry
+page, preserving the document URL used to resolve relative modules and styles.
+An authored host root suppresses that alias as described above; merely retaining
+an old cached root resource does not add it to the current offline selection.
 
 For a same-origin navigation to a selected static `.html` or `.htm` document,
 the worker can reuse that document's cached body while leaving the complete
@@ -296,6 +353,14 @@ document. This does not change query matching for assets, API calls, ordinary
 fetch requests, unselected documents or other origins. Cache refresh and the
 Update prompt keep their existing lifecycle.
 
+For a same-origin directory navigation without an app-entry alias, the worker
+can likewise reuse that directory's `index.html` body only when the index is
+already in the current offline selection and has a retained cached response.
+The directory URL and its query remain unchanged, including beneath a deployment
+subpath. An exact query-specific selected resource takes precedence. Otherwise,
+the original request passes to the host unchanged. This adds no page or asset to
+the inventory and does not save a host response over the selected index.
+
 Browser storage eviction can remove an offline cache. A missing release cache
 entry falls back to the network, so offline availability still depends on the
 browser retaining the selected resources.

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
@@ -872,7 +882,14 @@ generates one that opens the selected app page. The result
 contains `outputRoot`, `manifest`, and the complete `files` inventory.
 `manifest.app.entry` stays app-relative, while `manifest.app.start`
 is the package launch URL, such as `./index.html` for a root app or
-`./apps/hello-world/index.html` for a nested app. Release
+`./apps/hello-world/index.html` for a nested app. Only when selected records
+supply an authored output-root index does the release add
+`manifest.app.rootDocument: "./index.html"`. Preview serves that explicit
+document at `/`; without the field, older releases and generated-launcher
+packages retain the `302` redirect to `app.start` or the older `app.entry`
+fallback with the request query preserved. This generated release fact adds no
+app configuration or API option, changes no `app.start`, and requires no HTML
+content inference. Release
 schema `1`, kind `arcane-app-release`, and packager identity
 `arcane-app-packager-v1` remain unchanged. A dry run returns the planned output
 and file inventory without writing source or output.
@@ -2111,6 +2128,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 +4299,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.1",
   "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}),