arcane-os 0.52.0 → 0.52.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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

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.52.0` 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

@@ -245,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
@@ -373,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
@@ -550,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.
 
@@ -584,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.
 
@@ -749,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

@@ -251,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

@@ -102,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
@@ -304,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
@@ -319,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

@@ -882,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.52.0",
+  "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/src/dev-server.mjs

@@ -543,11 +543,13 @@ async function packagedRoutes(releaseRoot){
     const canonical=await canonicalRealDirectory(requested,'Packaged release root');
     let pwa = false;
     let startPath = '/index.html';
+    let rootDocument = null;
     try {
         const release = JSON.parse(
             await readFile(path.join(canonical, 'ARCANE_APP_RELEASE.json'), 'utf8')
         );
         const start = release.app.start ?? release.app.entry;
+        if (release.app.rootDocument === './index.html') rootDocument = '/index.html';
         const startUrl = new URL(start, 'http://arcane.invalid/');
         startPath = `${startUrl.pathname}${startUrl.search}${startUrl.hash}`;
     } catch (error) {
@@ -564,6 +566,7 @@ async function packagedRoutes(releaseRoot){
         appId:null,
         pwa,
         startPath,
+        rootDocument,
         mappings:[{
             prefix:[],
             root:canonical
@@ -1026,19 +1029,30 @@ async function startOwnedDevServer({
     }
     async function readCurrentSourceRoutes() {
         throwIfAborted(signal);
+        function optionalSourceMetadata(error) {
+            if (error.code !== 'ENOENT') throw error;
+            return null;
+        }
         let manifestPath = path.join(appMapping.root, APP_DESCRIPTOR_NAME);
+        const [rootIndex, descriptorInput] = await Promise.all(
+            [
+                lstat(path.join(routeSet.workspaceRoot, 'index.html')).catch(optionalSourceMetadata),
+                lstat(manifestPath).catch(optionalSourceMetadata)
+            ]
+        );
+        const rootDocument = rootIndex?.isFile() ? '/index.html' : null;
         let authored = true;
-        let input;
-        try {
-            input = await lstat(manifestPath);
-        } catch (error) {
-            if (error.code !== 'ENOENT') throw error;
+        let input = descriptorInput;
+        if (!input) {
             authored = false;
             manifestPath = path.join(appMapping.root, APP_CONFIG_NAME);
             input = await lstat(manifestPath);
         }
         if (sourceManifestInput?.path === manifestPath
             && sourceManifestInput.modifiedAt === input.mtimeMs) {
+            if (currentSourceRoutes.rootDocument !== rootDocument) {
+                currentSourceRoutes = {...currentSourceRoutes, rootDocument};
+            }
             return currentSourceRoutes;
         }
         const value = JSON.parse(await readFile(manifestPath, 'utf8'));
@@ -1060,6 +1074,7 @@ async function startOwnedDevServer({
         currentSourceRoutes = {
             ...routeSet,
             app: manifest,
+            rootDocument,
             startPath: applicationSourcePath(routeSet.config,routeSet.appId,manifest.entry),
             mappings: mappings.map(
                 function currentSourceMapping(mapping) {
@@ -1076,7 +1091,7 @@ async function startOwnedDevServer({
     function developmentPwaArtifacts(selectedRoutes, assets = [], version = assetVersion) {
         const rootApp = selectedRoutes.config.appsRoot === '.';
         const appBase = applicationSourcePath(selectedRoutes.config,selectedRoutes.appId);
-        const navigationAliases = {'/': selectedRoutes.startPath};
+        const navigationAliases = selectedRoutes.rootDocument ? {} : {'/': selectedRoutes.startPath};
         return createPwaArtifacts(
             {
                 app: {
@@ -1104,12 +1119,21 @@ async function startOwnedDevServer({
     function rememberPwaArtifacts(state, artifacts, generatedAt = new Date()) {
         for (const file of artifacts.files) {
             const previous = state.metadata.get(file.path);
-            const lastModified = previous?.content === file.content
+            const previousTime = previous?.lastModified
+                ? Date.parse(previous.lastModified.toUTCString()) : previous?.ambiguousThrough;
+            let lastModified = previous?.content === file.content
                 ? previous.lastModified
                 : generatedAt;
+            if (!lastModified && generatedAt.getTime() >= previousTime + 1000) {
+                lastModified = generatedAt;
+            }
+            // A changed alias must not validate the prior body within one HTTP second.
+            const ambiguous = previous?.content !== file.content && previousTime !== undefined
+                && Date.parse(generatedAt.toUTCString()) <= previousTime;
+            if (ambiguous) lastModified = undefined;
             state.metadata.set(
                 file.path,
-                {content: file.content, lastModified}
+                {content: file.content, lastModified, ambiguousThrough: lastModified ? undefined : previousTime}
             );
         }
         state.artifacts = artifacts;
@@ -1277,22 +1301,29 @@ async function startOwnedDevServer({
                 );
                 return;
             }
-            if(segments.length===0){
+            const rootRequest = segments.length === 0;
+            if (rootRequest && !selectedRoutes.rootDocument) {
                 response.writeHead(302,{location:`${selectedRoutes.startPath}${target.search}`});
                 response.end();
                 return;
             }
-            const mapping = selectedRoutes.mappings.find(
-                function requestedSourceMapping(route) {
-                    return route.prefix.every(
-                        function matchingSourcePrefix(segment, index) {
-                            return segments[index] === segment;
-                        }
-                    );
-                }
-            );
+            const resourceSegments = rootRequest ? ['index.html'] : segments;
+            const hostRoot = rootRequest && mode === 'source'
+                && (selectedRoutes.config.appsRoot !== '.' || !sourcePathAllowed(resourceSegments, selectedRoutes.app));
+            // Only the host's exact root document is outside app selection.
+            // Its direct URL and every other resource keep the selected routes.
+            const mapping = hostRoot ? {kind: 'host', root: selectedRoutes.workspaceRoot, prefix: []}
+                : selectedRoutes.mappings.find(
+                    function requestedSourceMapping(route) {
+                        return route.prefix.every(
+                            function matchingSourcePrefix(segment, index) {
+                                return resourceSegments[index] === segment;
+                            }
+                        );
+                    }
+                );
             if(!mapping){deny(response,404,'Not found.');return;}
-            const relative=segments.slice(mapping.prefix.length);
+            const relative=resourceSegments.slice(mapping.prefix.length);
             if(relative.length===0){deny(response,404,'Not found.');return;}
             if(mapping.allow&&!mapping.allow(relative)){deny(response,404,'Not found.');return;}
             await runFileWork(async function serveMappedResource() {
@@ -1307,6 +1338,18 @@ async function startOwnedDevServer({
                     deny(response,404,'Not found.');
                     return;
                 }
+                if (hostRoot) {
+                    const representation = sourceRepresentation(opened, assetVersion, false, false);
+                    await serveSourceFile(
+                        fileServer,
+                        request,
+                        response,
+                        opened,
+                        {lastModified: representation.lastModified, representationTracked: true}
+                    );
+                    return;
+                }
+                const resourcePath = rootRequest ? selectedRoutes.rootDocument : target.path;
                 const extension=path.extname(opened.candidate).toLowerCase();
                 const html=extension==='.html'||extension==='.htm';
                 const explicitDocuments = mode === 'source' && mapping.kind === 'app'
@@ -1316,7 +1359,7 @@ async function startOwnedDevServer({
                 const selectedPwaDocument = mode === 'source' && pwaEnabled && html
                     && mapping.kind === 'app'
                     && !explicitDocuments && selectedRoutes.app.include.includes(relative.join('/'));
-                const selectedDocument = target.path === selectedRoutes.startPath || explicitDocument || selectedPwaDocument;
+                const selectedDocument = resourcePath === selectedRoutes.startPath || explicitDocument || selectedPwaDocument;
                 const managedDocument = !selectedDocument && !explicitDocuments && html && await isManagedDocument(opened);
                 const entryDocument = selectedDocument || managedDocument;
                 const managedMap=path.basename(opened.candidate)==='arcane.importmap.json';
@@ -1324,22 +1367,22 @@ async function startOwnedDevServer({
                 // 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);
+                if (runtimeResource && html) runtimeDocuments.add(resourcePath);
                 const browserResource=['script','style','worker','sharedworker','serviceworker']
                     .includes(request.headers['sec-fetch-dest']);
                 // 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);
+                    &&await isCurrentComponent(resourcePath, selectedRoutes);
                 const retainedDocument=explicitDocuments&&html&&!selectedDocument&&!componentDocument;
                 const rewrite=!retainedDocument&&(runtimeResource||entryDocument||browserResource||managedMap
-                    ||componentDocument||resourcePaths.has(target.path));
+                    ||componentDocument||resourcePaths.has(resourcePath));
                 const onReference = function observeServedResource(reference) {
                     const {url,kind,baseKind}=reference;
                     if (pwaEnabled && kind !== 'fetch'
                         && !(kind === 'import' && !/^(?:\.{1,2}\/|\/)/u.test(url))) {
                         try {
-                            const documentUrl = new URL(target.path, 'http://arcane.invalid');
+                            const documentUrl = new URL(resourcePath, 'http://arcane.invalid');
                             const resource = resolveAssetReference(
                                 {...reference,url:versionAssetUrl(url,null)},
                                 {ownerUrl:documentUrl}
@@ -1354,7 +1397,7 @@ async function startOwnedDevServer({
                     if(baseKind==='document'||kind==='fetch'||(kind==='asset'&&!/\.css(?:[?#]|$)/iu.test(url))
                         ||(kind==='import'&&!/^(?:\.{1,2}\/|\/)/u.test(url)))return;
                     try{
-                        const documentUrl=new URL(target.path,'http://arcane.invalid');
+                        const documentUrl=new URL(resourcePath,'http://arcane.invalid');
                         const resource=resolveAssetReference(reference,{ownerUrl:documentUrl});
                         if(resource.origin===documentUrl.origin
                             &&/\.(?:m?js|html?|css)$/iu.test(resource.pathname)){

package/src/packager/core.mjs

@@ -788,7 +788,7 @@ async function loadAdapter(context){
     return module;
 }
 
-function releaseManifest(context,files,pwaArtifacts){
+function releaseManifest(context,files,pwaArtifacts,rootDocument){
     return {
         schemaVersion:1,
         kind:'arcane-app-release',
@@ -799,6 +799,7 @@ function releaseManifest(context,files,pwaArtifacts){
             version:context.config.version,
             entry:context.config.entry,
             start:packageResourceUrl(appPackagePath(context, context.config.entry)),
+            ...(rootDocument ? {rootDocument} : {}),
             strategy:context.config.strategy,
             shared:[...context.config.shared],
             ...(pwaArtifacts?{pwa:{
@@ -845,6 +846,11 @@ async function packageWithContext(context,options={}){
     const appPath=appRelativeRoot(context.rootConfig,context.appId);
     const entryPath=appPackagePath(context,context.config.entry);
     const records=await collectPackageRecords(context,{signal});
+    const rootDocument = records.some(
+        function selectedRootIndex(record) {
+            return record.destination === 'index.html';
+        }
+    ) ? './index.html' : undefined;
     const inspected=await inspectContext(context,{signal,records});
     if(options.dryRun){
         return {
@@ -888,9 +894,7 @@ async function packageWithContext(context,options={}){
     try{
         async function copyBase() {
             await copyRecords(records,stagingRoot,{signal,onEvent});
-            if (!records.some(function selectedRootIndex(record) {
-                return record.destination === 'index.html';
-            })) {
+            if (!rootDocument) {
                 await writePackageLauncher(context, stagingRoot);
             }
         }
@@ -1050,6 +1054,7 @@ async function packageWithContext(context,options={}){
             sdkVersion:assetVersion,
             pwa:context.config.pwa,
             files,
+            navigationAliases: rootDocument ? {} : {'./': packageResourceUrl(entryPath)},
             assets:[...offlineReferences]
         }):null;
         if(pwaArtifacts){
@@ -1080,7 +1085,7 @@ async function packageWithContext(context,options={}){
             }
             files.sort(compareText);
         }
-        const manifest=releaseManifest(context,files,pwaArtifacts);
+        const manifest=releaseManifest(context,files,pwaArtifacts,rootDocument);
         await writeFile(
             path.join(stagingRoot,RELEASE_MANIFEST_NAME),
             `${JSON.stringify(manifest,null,2)}\n`,

package/src/pwa-worker.mjs

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

package/src/toolchain.mjs

@@ -330,24 +330,41 @@ async function refreshRootApplicationFiles(prepared,inspected,importMap,{signal,
     const manifest=prepared.validation.app.manifest;
     const installed=await readInstalledSdkLayout(workspaceRoot,prepared.validation.config);
     const entry=`/${manifest.entry.split('/').map(encodeURIComponent).join('/')}`;
-    const navigationAliases={
-        '/':entry
-    };
+    const pwaEnabled = installed?.direct && manifest.pwa?.enabled;
+    let authoredRoot = false;
+    if (pwaEnabled) {
+        try {
+            authoredRoot = (await lstat(path.join(workspaceRoot, 'index.html'))).isFile();
+        } catch (error) {
+            if (error.code !== 'ENOENT') throw error;
+        }
+    }
+    // A host homepage need not belong to the selected application or its cache.
+    const navigationAliases = authoredRoot ? {} : {'/': entry};
+    function rootIndexPath(relative) {
+        return (process.platform === 'win32' ? relative.toLowerCase() : relative) === 'index.html';
+    }
+    const selectedRootIndex = authoredRoot && manifest.include.some(rootIndexPath)
+        && !manifest.exclude.some(rootIndexPath);
     // The source host serves the installed files in place. There is no runtime projection.
     const files=[...new Set([
-        ...inspected.files.filter(file=>file!=='index.html'||manifest.include.includes('index.html')),
+        ...inspected.files.filter(
+            function selectedSourceFile(file) {
+                return file !== 'index.html' || selectedRootIndex;
+            }
+        ),
         importMap.artifactRelativePath
     ])];
     const sourceOrigin='http://arcane.invalid';
     const selectedPaths=new Set(files.map(function selectedStaticPath(file){
         return new URL(`/${file.split('/').map(encodeURIComponent).join('/')}`,sourceOrigin).pathname;
     }));
-    const assets=installed?.direct&&manifest.pwa?.enabled
+    const assets=pwaEnabled
         ?(await collectSourcePwaAssets({workspaceRoot,appId,signal,onEvent})).filter(function selectedStaticVariant(value){
             const url=new URL(value,sourceOrigin);
             return url.origin===sourceOrigin&&selectedPaths.has(url.pathname);
         }):[];
-    const pwa=installed?.direct&&manifest.pwa?.enabled?createPwaArtifacts({
+    const pwa=pwaEnabled?createPwaArtifacts({
         app:{id:appId,displayName:manifest.displayName,version:manifest.version,entry},
         sdkVersion:installed.version,
         pwa:manifest.pwa,