arcane-os 0.39.1 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.40.0
+
+- Add optional `arcane-package.json` `outputDirectory` to select the final
+  workspace-relative package directory without an appended application ID.
+  For example, `"ai"` selects `<workspace>/ai`; omission preserves `dist/<id>`.
+  Descriptor refresh retains this package-local setting, and preview,
+  verification, bundles and native browser-content inputs use the selected
+  root. Source layout, app identity and internal release URLs are unchanged.
+  Packaging replaces only the selected destination through its existing staged
+  swap, preserving old destinations and siblings when that selection changes.
+- Serve selected cached static HTML documents for navigation query variants
+  without redirecting or losing the requested URL. Exact selected query
+  variants retain precedence; a missing cached document fetches the original
+  request without replacing the canonical cached body. Assets, API requests,
+  non-navigation requests and update/refresh lifecycle remain unchanged.
+
 ## 0.39.1
 
 - Preserve the Markdown editor's current source viewport and selection during

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.39.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.40.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/architecture.md

@@ -200,12 +200,13 @@ available until this wrapper and its explicit capability boundary are actually
 implemented.
 
 Packaging and release verification are separate explicit operations. Run
-`arcane package` to generate `dist/<id>`, then use
+`arcane package` to generate the selected app's `outputDirectory`, defaulting
+to `dist/<id>`, then use
 `arcane run --target browser` to serve that selected release. Packaging does
 not automatically run tests or checks; those run only when the user expressly
 requests them or when required for a separately selected release output. The browser
 run command does not substitute source files. If source changes after
-packaging, the prior `dist` remains intentionally unchanged until the next
+packaging, the prior packaged output remains intentionally unchanged until the next
 explicit package operation. Never use packaged `dist` as the everyday
 development tree, and never treat source-serving behavior as evidence for the
 release artifact.
@@ -224,6 +225,17 @@ dist/<id>/apps/<id>/index.html
 dist/<id>/ARCANE_APP_RELEASE.json
 ```
 
+These release paths show the default output location. An app's optional
+schema-1 `arcane-package.json` field `outputDirectory` selects the final
+workspace-relative directory instead: `"ai"` means `<workspace>/ai`, with no
+app-ID suffix. The selected directory is wholly replaced through the existing
+staged package swap; a changed destination preserves the old output and sibling
+directories. Input/source conflicts fail before output writes. This changes
+only package placement, not source layout, app identity, OPFS scope, or internal
+release URLs. Preview, verification, bundling, and native browser-content input
+consume that same selected release root; native executable output remains
+separate. See the [complete output contract](reference/protocols.md#app-selected-package-output).
+
 Packaging places each selected app file beneath `apps/<id>/` in the release
 and preserves every shared route destination. When no selected shared payload
 supplies a root `index.html`, the SDK generates one that opens the selected app

package/docs/reference/cli.md

@@ -529,8 +529,9 @@ npm exec -- arcane check --app hello-world
 
 ### Overview
 
-Creates one complete browser release beneath `dist/<id>/`, preserving the prior
-output until the replacement is complete. It consumes saved source and managed
+Creates one complete browser release in the app's selected output directory,
+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
@@ -538,6 +539,14 @@ their selected app beneath `apps/<id>/`. When selected shared content supplies n
 Source document bases and resource URLs therefore retain their development
 layout. Packaging does not run tests or checks automatically.
 
+Set `"outputDirectory": "ai"` in the selected app's `arcane-package.json`
+to emit directly to `<workspace>/ai`; the SDK appends no app ID. Omit the field
+to retain the default. There is no new CLI flag. The selected directory is
+wholly replaced, not merged; choose a directory dedicated to the release.
+Changing this setting preserves the old output and its siblings. Source/input
+overlap fails before output writes. App identity, source layout, and saved
+data remain unchanged. See the [output contract](protocols.md#app-selected-package-output).
+
 For `installed-v1`, the same four configured source routes supply the complete
 selected SDK content directly from `node_modules`. Only the portable output
 receives copies; no workspace `arcane/` projection is required. Its runtime URLs,
@@ -603,7 +612,10 @@ arcane bundle [--app <id>] [--artifact <file>.arcane-app.tar.gz] [--overwrite]
 
 ### Replacement behavior
 
-The default output is `dist/<id>-<version>.arcane-app.tar.gz`. An existing path
+The default archive is `<id>-<version>.arcane-app.tar.gz` beside the app's
+selected package directory. With the default package location, this remains
+`dist/<id>-<version>.arcane-app.tar.gz`. Bundling reads the same selected release
+root used by packaging and preview. An existing path
 is refused unless `--overwrite` is explicit. Even then, the prior artifact is
 retained until the replacement is complete. A conflicting or uncertain path is
 preserved rather than overwritten.
@@ -697,6 +709,8 @@ The command selects one workspace, app, target, architecture, format, signing
 profile, and output root. Current providers emit a portable directory,
 Windows x64 EXE bundle, Linux x64/ARM64 DEB, or development-signed Android APK.
 The output remains target-specific inside the common plan contract.
+The app's `outputDirectory` selects its packaged browser-content input;
+native `--output-root` independently selects native build output.
 `--dry-run` is implemented for the browser build path. Native builds reject it
 rather than returning a fictional native artifact plan.
 
@@ -713,7 +727,8 @@ npm exec -- arcane build \
 
 ### Overview
 
-For `--target browser`, starts the existing current `dist/<app>` release; it
+For `--target browser`, starts the existing release in the app's configured
+`outputDirectory`, or `dist/<app>` when omitted; it
 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.

package/docs/reference/inventory/package-api.json

@@ -902,7 +902,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Loads one validated packager app plan, including the shared descriptor-admitted browser document inventory.",
+      "summary": "Loads one validated packager app plan, including the shared descriptor-admitted browser document inventory and final workspace-relative output selected by app outputDirectory or default dist/appId.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -1197,7 +1197,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Builds one selected browser application release through the low-level packager API; it never runs tests or checks automatically.",
+      "summary": "Builds one selected browser application release into app outputDirectory or default dist/appId through staged whole-directory replacement, preserving source and unrelated prior destinations; it never runs tests or checks automatically.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -1214,7 +1214,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Headless toolchain operations",
-      "summary": "Runs the high-level package operation for one selected application.",
+      "summary": "Runs the high-level package operation for one selected application using the same app-selected final outputDirectory, defaulting to dist/appId, with no separate destination override.",
       "availability": "Node; selected operation may produce browser or native output",
       "protocol": "Shared headless operation API + arcane-cli-events/1",
       "normalization": "SDK-normalized inputs, errors, events, and documented result"
@@ -2031,7 +2031,7 @@
       ],
       "primaryImport": "arcane-os/packager",
       "group": "Packaging and release bundles",
-      "summary": "Validates one schema-1 packager app configuration and its relationship to the root config.",
+      "summary": "Validates one schema-1 packager app configuration and its relationship to the root config, including optional workspace-relative final outputDirectory without changing source layout or app identity.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"

package/docs/reference/protocols.md

@@ -96,6 +96,44 @@ 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.
 
+## App-selected package output
+
+An app may set `"outputDirectory": "ai"` in its schema-1
+`arcane-package.json`. This selects the final directory relative to the
+workspace: `<workspace>/ai`, not `<workspace>/ai/<app-id>`. Omitting the
+field retains `dist/<app-id>`. The root `arcane-packager.json` configuration
+and simple scaffold defaults remain unchanged.
+The destination is local to `arcane-package.json`, including apps with a
+schema-2 `arcane-app.json`. Descriptor refresh preserves it; no matching
+descriptor property or identity change is required.
+
+This field controls the destination of the complete packaged release. It does
+not relocate application source, rename the app, change its identity or OPFS
+scope, or alter the package's internal file paths. Source development continues
+to serve the same source tree. There is no migration of existing source,
+saved data, or previously generated output.
+
+The selected directory is wholly replaced through the packager's staged
+replacement operation, so it must be dedicated to that release. The prior
+contents remain until the replacement is ready; this is not an in-place merge.
+Changing the configured destination leaves the former output directory and
+unrelated siblings untouched. Output that would replace the app's source root,
+selected inputs, or required control files fails with `ARCANE_PACKAGE_INVALID`
+before output writes rather than overwriting those inputs.
+If an included source directory contains the output directory, use the existing
+`exclude` selection to keep that generated subtree outside the package inputs.
+
+Inspection and dry runs report this selected destination. Packaging,
+verification, and `arcane run --target browser` use the same release root.
+The normal bundle destination is beside that release directory as
+`<app-id>-<version>.arcane-app.tar.gz`; an explicit artifact path retains its
+existing meaning. Native packaging supplies the selected release root to the
+native provider, while native executable `outputRoot` remains a separate
+target-output setting. Selected app package directories and native artifact
+output must remain separate; a conflicting native assembly fails before it
+packages any app. App launch paths, resource URLs, and enabled PWA
+representations retain their package-relative layout.
+
 ## Installed-package browser routes
 
 An external application can serve and package its installed SDK directly,
@@ -340,7 +378,8 @@ catch-all `arcane/` prefix. Classic scripts, workers, stylesheets, and other
 non-ESM assets use their documented URL or host loading contract rather than
 invented package bindings. Development serves the selected app plus the
 complete selected tree.
-Packaging copies the same map, app entry, and physical content into `dist/<id>`;
+Packaging copies the same map, app entry, and physical content into the
+[selected package output](#app-selected-package-output), defaulting to `dist/<id>`;
 targets never resolve through the consumer workspace's root `node_modules/`.
 The two lowercase static runtime package specifiers above and the shared
 speech-text helper are exact npm package exports, so Node and managed-browser

package/docs/reference/pwa.md

@@ -262,6 +262,18 @@ 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.
 
+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
+query and fragment in the browser's navigation URL. Pages such as
+`dashboard.html?id=person` therefore retain their application-owned parameters
+without enumerating people or saving a cache entry for every query. An exact
+query-specific resource already selected in the inventory takes precedence.
+When the plain document has no retained cached body, the original navigation
+request goes to the network unchanged; its response is not saved over the plain
+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.
+
 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,6 +779,10 @@ such as `apps/hello-world/index.html`. The complete `files` inventory uses
 package-relative paths and includes the root `index.html`. Shared
 files retain their configured route destinations.
 
+`output` is the selected workspace-relative final package directory. It uses
+the app's optional `arcane-package.json` `outputDirectory` directly, or
+`dist/<app-id>` when omitted; the SDK appends no app ID to an explicit value.
+
 ### Availability and normalization
 
 **Node.** Normalized SDK validation with complete canonical archive and release content. Deep protocol: [SDK packager and deterministic bundle contract](protocols.md).
@@ -839,6 +843,15 @@ The package preserves the complete selected content, applying the documented
 asset-version and enabled browser-PWA transformations to resource references.
 Malformed configuration or descriptors fail while preserving the prior output.
 
+The app's optional schema-1 `outputDirectory` selects the final
+workspace-relative destination. For example, `"ai"` emits directly into
+`<workspace>/ai`; omission retains `dist/<app-id>`. The selected directory is
+wholly replaced through the existing staged swap, not merged. Changing the
+destination preserves the former output and siblings. Conflicting source,
+selected input, or required control paths fail before output writes. Source
+layout, app identity, OPFS scope, and internal package paths remain unchanged.
+See [app-selected package output](protocols.md#app-selected-package-output).
+
 Selected app files are emitted beneath `apps/<id>/`; shared files retain their
 configured route destinations. When selected shared content supplies no root
 `index.html`, the SDK generates one that opens the selected app page. The result
@@ -1030,6 +1043,13 @@ console.log(validateAppBundlePath('payload/apps/example/index.html'));
 
 Validates one schema-1 packager app configuration and its relationship to the root config.
 
+Optional `outputDirectory` is the final workspace-relative package directory;
+omission preserves `dist/<app-id>`. It is an app package field, not a change to
+the root configuration's `distRoot` or the schema-2 app identity. Packaging
+reports conflicting output/input selections with `ARCANE_PACKAGE_INVALID`
+before output writes. Authored-descriptor comparison treats the destination
+as package-local, and descriptor refresh preserves the existing setting.
+
 ### Signature and result
 
 ```text
@@ -2650,6 +2670,11 @@ async function useresolveNativeBuildOutputRoot(...arguments_) {
 
 Invokes one target adapter run method and fails honestly when the artifact kind is not runnable.
 
+For the browser adapter, optional `releaseRoot` selects an existing packaged
+directory directly. Omission keeps the direct adapter's `dist/<app-id>`
+default, including callers with only a release workspace. The high-level
+`runApplication()` supplies the app-configured destination automatically.
+
 ### Signature and result
 
 ```text
@@ -4024,6 +4049,10 @@ async function usebuildApplication(...arguments_) {
 
 Creates one deterministic external application bundle from one authenticated packaged release.
 
+The high-level operation reads the app's selected package directory. Its
+default archive is placed beside that directory; an explicit artifact path
+retains the existing output-path contract.
+
 ### Signature and result
 
 ```text
@@ -4280,6 +4309,12 @@ import maps through `packageApp()`. Map generation remains the explicit
 Selected app files retain their `apps/<id>/` paths alongside the shared routes
 and root launcher described by `packageApp()`.
 
+The same low-level operation resolves the app's optional `outputDirectory`;
+there is no separate high-level destination override. `release.outputRoot`
+names the resulting complete release directory, with omitted configuration
+retaining `dist/<app-id>`. Browser preview, bundle creation, and native
+browser-content input use that selected root.
+
 Packaging does not automatically run tests or checks. Verification occurs only
 when explicitly requested or when required for the selected release output.
 A failure leaves the prior distribution untouched. Success returns the selected
@@ -4375,6 +4410,10 @@ async function userepositoryApplication(...arguments_) {
 
 Runs a browser app or performs the selected native build/launch lifecycle for one target. It does not run tests or checks automatically; selected release-output verification remains explicit to that release operation.
 
+Browser runs resolve the app's current `outputDirectory`, defaulting to
+`dist/<app-id>`, and preview that existing release without repackaging it.
+Native artifact output remains separately selected by its target contract.
+
 ### Signature and result
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.39.1",
+  "version": "0.40.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-package.schema.json

@@ -34,6 +34,10 @@
     "entry": {
       "$ref": "#/$defs/relativePath"
     },
+    "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."
+    },
     "strategy": {
       "enum": [
         "static",

package/src/app-descriptor.mjs

@@ -448,6 +448,11 @@ export async function refreshAppPackageProjection({workspaceRoot, appId, signal,
         packagePath,
         `apps/${appId}/arcane-package.json`
     );
+    // The output destination belongs to this workspace's package configuration,
+    // not the portable application descriptor or its identity.
+    if (packageManifest.outputDirectory !== undefined) {
+        projection.outputDirectory = packageManifest.outputDirectory;
+    }
     const packageProjection = packageManifest.pwa === undefined ? packageManifest : {
         ...packageManifest,
         pwa: normalizePwaConfig(packageManifest.pwa)
@@ -474,10 +479,11 @@ export async function loadAppDescriptor({workspaceRoot,appRoot,appId,packageMani
     if(authored){
         const descriptor=validateAppDescriptor(authored,{appId});
         const projection=projectPackageManifest(authored);
-        const packageProjection=packageManifest.pwa===undefined?packageManifest:{
+        const packageProjection={
             ...packageManifest,
-            pwa:normalizePwaConfig(packageManifest.pwa)
+            ...(packageManifest.pwa===undefined?{}:{pwa:normalizePwaConfig(packageManifest.pwa)})
         };
+        delete packageProjection.outputDirectory;
         if(!isDeepStrictEqual(projection,packageProjection)){
             fail(`${APP_DESCRIPTOR_NAME} does not project exactly to arcane-package.json.`);
         }

package/src/app-layout.mjs

@@ -9,6 +9,10 @@ export function resolveAppRoot(workspaceRoot, config, appId) {
     return path.resolve(workspaceRoot, appRelativeRoot(config, appId));
 }
 
+export function resolvePackageOutputRoot(workspaceRoot, config, app) {
+    return path.resolve(workspaceRoot, app.outputDirectory ?? `${config.distRoot}/${app.id}`);
+}
+
 export function appBaseHref(workspaceRoot, appRoot, document = 'index.html') {
     const directory = path.dirname(path.resolve(appRoot, document));
     const relative = path.relative(directory, workspaceRoot).split(path.sep).join('/');

package/src/packager/core.mjs

@@ -12,7 +12,7 @@ import {
 } from 'node:fs/promises';
 import path from 'node:path';
 import {pathToFileURL} from 'node:url';
-import {appRelativeRoot,resolveAppRoot} from '../app-layout.mjs';
+import {appRelativeRoot,resolveAppRoot,resolvePackageOutputRoot} from '../app-layout.mjs';
 import {readInstalledSdkLayout} from '../sdk-runtime-layout.mjs';
 import {withWorkspaceOperationLock} from '../workspace-operation-lock.mjs';
 import {
@@ -307,7 +307,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'
+        'localAIModelPolicy','include','exclude','shared','adapter','pwa','outputDirectory'
     ]),`${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)){
@@ -316,6 +316,9 @@ 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 outputDirectory=value.outputDirectory===undefined?undefined:normalizeRelativePath(
+        value.outputDirectory,`${appId}/${APP_CONFIG_NAME}.outputDirectory`
+    );
     const include=validatePathList(value.include,`${appId}/${APP_CONFIG_NAME}.include`,{required:true});
     const exclude=validatePathList(value.exclude??[],`${appId}/${APP_CONFIG_NAME}.exclude`);
     if(include.some(allowed=>sameOrDescendant(APP_CONFIG_NAME,allowed))){
@@ -351,6 +354,7 @@ export function validateAppConfig(value,appId,rootConfig,configPath=path.posix.j
         displayName,
         version:value.version,
         entry,
+        ...(outputDirectory===undefined?{}:{outputDirectory}),
         strategy:value.strategy,
         ...(value.pwa===undefined?{}:{pwa:normalizePwaConfig(value.pwa)}),
         ...(value.security===undefined?{}:{security:normalizeOptionalRecord(
@@ -421,11 +425,67 @@ async function loadContext(requestedWorkspaceRoot,appId){
         appRoot,
         appId,
         config,
-        distRoot:path.join(workspaceRoot,rootConfig.distRoot),
-        outputRoot:path.join(workspaceRoot,rootConfig.distRoot,appId)
+        outputRoot:resolvePackageOutputRoot(workspaceRoot,rootConfig,config)
     };
 }
 
+async function assertPackageOutputLocation(context){
+    const output=context.outputRoot.split(path.sep).join('/');
+    const absolute=location=>path.resolve(location).split(path.sep).join('/');
+    const controls=[
+        context.appRoot,
+        path.join(context.workspaceRoot,ROOT_CONFIG_NAME),
+        path.join(context.appRoot,APP_CONFIG_NAME),
+        path.join(context.appRoot,APP_DESCRIPTOR_NAME),
+        ...(context.config.adapter?[path.join(context.appRoot,context.config.adapter)]:[])
+    ];
+    for(const control of controls){
+        if(sameOrDescendant(absolute(control),output)){
+            fail(`Package output would replace application source or configuration: ${control}.`);
+        }
+    }
+    for(const name of ['.git','.arcane','.agents','.codex','node_modules']){
+        const control=absolute(path.join(context.workspaceRoot,name));
+        if(sameOrDescendant(output,control)||sameOrDescendant(control,output)){
+            fail(`Package output overlaps the workspace control directory: ${name}.`);
+        }
+    }
+    if(context.rootConfig.appsRoot!=='.'){
+        const relative=path.relative(context.appsRoot,context.outputRoot);
+        if(relative&&!relative.startsWith(`..${path.sep}`)&&relative!=='..'&&!path.isAbsolute(relative)){
+            const [otherAppId]=relative.split(path.sep);
+            if(pathKey(otherAppId)!==pathKey(context.appId)){
+                const otherAppRoot=path.join(context.appsRoot,otherAppId);
+                for(const manifest of [APP_CONFIG_NAME,APP_DESCRIPTOR_NAME]){
+                    try{await lstat(path.join(otherAppRoot,manifest));}
+                    catch(error){if(error?.code==='ENOENT')continue;throw error;}
+                    fail(`Package output overlaps another application's source directory: ${otherAppRoot}.`);
+                }
+            }
+        }
+    }
+    function assertSelectedInput(sourceRoot,selected,excludes,label){
+        if(isExcluded(selected,excludes))return;
+        const source=absolute(path.resolve(sourceRoot,selected));
+        const relativeOutput=path.relative(sourceRoot,context.outputRoot).split(path.sep).join('/');
+        if(sameOrDescendant(source,output)
+            ||(sameOrDescendant(output,source)&&!isExcluded(relativeOutput,excludes))){
+            fail(`Package output overlaps selected ${label} content: ${selected}.`);
+        }
+    }
+    for(const selected of context.config.include){
+        assertSelectedInput(context.appRoot,selected,context.config.exclude,context.appId);
+    }
+    for(const sharedId of context.config.shared){
+        for(const route of context.rootConfig.sharedPayloads[sharedId]){
+            const sourceRoot=path.resolve(context.workspaceRoot,route.source);
+            for(const selected of route.include){
+                assertSelectedInput(sourceRoot,selected,route.exclude,`sharedPayloads.${sharedId}`);
+            }
+        }
+    }
+}
+
 function destinationJoin(root,relative){
     return relative==='.'?root:root==='.'?relative:`${root}/${relative}`;
 }
@@ -495,6 +555,7 @@ async function collectSelectedPath({
 }
 
 async function collectPackageRecords(context,{signal}={}){
+    await assertPackageOutputLocation(context);
     const records=[];
     const destinations=new Set();
     for(const selected of context.config.include){
@@ -574,14 +635,15 @@ async function optionalDescriptor(context){
     }
 }
 
-async function inspectContext(context,{signal}={}){
-    const records=await collectPackageRecords(context,{signal});
-    const documents=await browserDocuments(records,context.config.entry);
+async function inspectContext(context,{signal,records}={}){
+    const selectedRecords=records??await collectPackageRecords(context,{signal});
+    const documents=await browserDocuments(selectedRecords,context.config.entry);
     return {
         appId:context.appId,
         displayName:context.config.displayName,
         version:context.config.version,
         entry:context.config.entry,
+        ...(context.config.outputDirectory===undefined?{}:{outputDirectory:context.config.outputDirectory}),
         strategy:context.config.strategy,
         ...(context.config.pwa===undefined?{}:{pwa:copyJson(context.config.pwa)}),
         include:[...context.config.include],
@@ -594,7 +656,7 @@ async function inspectContext(context,{signal}={}){
         ...(context.config.adapter===undefined?{}:{adapter:context.config.adapter}),
         descriptor:await optionalDescriptor(context),
         browserDocuments:documents,
-        files:[...new Set(['index.html',...records.map(record=>record.destination)])].sort(compareText),
+        files:[...new Set(['index.html',...selectedRecords.map(record=>record.destination)])].sort(compareText),
         output:path.relative(context.workspaceRoot,context.outputRoot).split(path.sep).join('/')
     };
 }
@@ -752,7 +814,8 @@ async function packageWithContext(context,options={}){
     const pwaEnabled=browserPwa&&context.config.pwa?.enabled===true;
     const appPath=appRelativeRoot(context.rootConfig,context.appId);
     const entryPath=appPackagePath(context,context.config.entry);
-    const inspected=await inspectContext(context,{signal});
+    const records=await collectPackageRecords(context,{signal});
+    const inspected=await inspectContext(context,{signal,records});
     if(options.dryRun){
         return {
             appId:context.appId,
@@ -770,17 +833,29 @@ async function packageWithContext(context,options={}){
             ].sort(compareText)
         };
     }
-    await mkdir(context.distRoot,{recursive:true});
-    const distInfo=await lstat(context.distRoot);
-    if(distInfo.isSymbolicLink()||!distInfo.isDirectory())fail('dist must be a real directory.');
+    // Directory replacement must stay on the requested physical path before
+    // mkdir or rename can affect an existing source tree through an ancestor.
+    let current=context.workspaceRoot;
+    for(const segment of path.relative(context.workspaceRoot,context.outputRoot).split(path.sep)){
+        current=path.join(current,segment);
+        let info;
+        try{info=await lstat(current);}
+        catch(error){if(error?.code==='ENOENT')break;throw error;}
+        if(info.isSymbolicLink()||!info.isDirectory()){
+            fail(`Package output must use real directories: ${current}.`);
+        }
+    }
+    const outputParent=path.dirname(context.outputRoot);
+    await mkdir(outputParent,{recursive:true});
+    const parentInfo=await lstat(outputParent);
+    if(parentInfo.isSymbolicLink()||!parentInfo.isDirectory())fail('Package output parent must be a real directory.');
     const stagingRoot=path.join(
-        context.distRoot,
+        outputParent,
         `.${context.appId}-staging-${process.pid}-${Date.now()}`
     );
     await mkdir(stagingRoot);
     let promoted=false;
     try{
-        const records=await collectPackageRecords(context,{signal});
         async function copyBase() {
             await copyRecords(records,stagingRoot,{signal,onEvent});
             if (!records.some(function selectedRootIndex(record) {
@@ -1009,7 +1084,7 @@ export async function packageApp(options={}){
 export async function verifyApp({workspaceRoot,appId,signal,onEvent}={}){
     throwIfAborted(signal);
     const context=await loadContext(workspaceRoot,appId);
-    const outputRoot=await realDirectory(context.outputRoot,`dist/${appId}`);
+    const outputRoot=await realDirectory(context.outputRoot,'Package output');
     const manifest=await readJson(path.join(outputRoot,RELEASE_MANIFEST_NAME),RELEASE_MANIFEST_NAME);
     if(!isPlainObject(manifest)||manifest.schemaVersion!==1||manifest.kind!=='arcane-app-release'
         ||manifest.packagerVersion!==PACKAGER_VERSION||manifest.app?.id!==appId

package/src/pwa-worker.mjs

@@ -494,13 +494,39 @@ function installPwaWorker(manifest, clientUrl) {
         return {location: destination.href, resource: cacheUrl(selected)};
     }
 
+    function staticNavigationResource(url) {
+        const document = new URL(url);
+        if (document.origin !== scopeOrigin || !document.search
+            || !/\.html?$/iu.test(document.pathname)) {
+            return null;
+        }
+        document.search = '';
+        return ownedUrls.has(document.href) ? document.href : null;
+    }
+
     async function requestedResource(request, url) {
         await restored;
-        const redirect = request.mode === 'navigate' ? navigationRedirect(url) : null;
+        const selectedQuery = ownedUrls.has(url) && new URL(url).search;
+        const redirect = request.mode === 'navigate' && !selectedQuery ? navigationRedirect(url) : null;
         if (redirect && cacheUrl(redirect.location) !== url && ownedUrls.has(redirect.resource)) {
             return {response: Response.redirect(redirect.location, 302), done: Promise.resolve(null)};
         }
         if (!ownedUrls.has(url)) {
+            const document = request.mode === 'navigate' ? staticNavigationResource(url) : null;
+            if (document) {
+                // Reuse only the selected static document body. Keep the navigation URL
+                // intact; a query-specific response must never replace this shared entry.
+                const cached = await findCachedResource(document);
+                if (cached.response) {
+                    return {
+                        response: cached.response,
+                        done: cached.current ? Promise.resolve(null)
+                            : cached.cache.put(document, cached.response.clone()).then(function retainedDocument() {
+                                return null;
+                            })
+                    };
+                }
+            }
             return {response: await fetch(request), done: Promise.resolve(null)};
         }
         const cache = await caches.open(cacheName);
@@ -522,7 +548,7 @@ function installPwaWorker(manifest, clientUrl) {
             return;
         }
         if (manifestRestored && !ownedUrls.has(url)
-            && !(request.mode === 'navigate' && navigationRedirect(url))) {
+            && !(request.mode === 'navigate' && (navigationRedirect(url) || staticNavigationResource(url)))) {
             return;
         }
         const resource = requestedResource(request, url);

package/src/targets/index.mjs

@@ -148,9 +148,8 @@ const browserAdapter={
         throwIfAborted(signal);
         return {target:'browser',release:await verifyApp({workspaceRoot,appId,signal,onEvent})};
     },
-    async run({workspaceRoot,appId,host='127.0.0.1',port=0,httpPort=0,tls,certPath,keyPath,signal,onEvent}={}){
+    async run({workspaceRoot,appId,releaseRoot=path.join(workspaceRoot,'dist',appId),host='127.0.0.1',port=0,httpPort=0,tls,certPath,keyPath,signal,onEvent}={}){
         throwIfAborted(signal);
-        const releaseRoot=path.join(workspaceRoot,'dist',appId);
         const server=await startDevServer({
             workspaceRoot,
             appId,

package/src/toolchain.mjs

@@ -1,5 +1,6 @@
 import Is from 'strong-type';
 import path from 'node:path';
+import {resolvePackageOutputRoot} from './app-layout.mjs';
 import {readdir,lstat,realpath,mkdir,readFile,writeFile} from 'node:fs/promises';
 import {createWorkspace,initWorkspace} from './scaffold.mjs';
 import {
@@ -1022,6 +1023,20 @@ async function executePairedNativeBuild(options,adapter,{
     }
     const dependencyApps=await nativeDependencyClosure(initialPrepared,{target,signal,onEvent});
     const prepared=initialPrepared;
+    const packageOutputs=[];
+    for(const app of [prepared.validation.app,...dependencyApps]){
+        const releaseRoot=resolvePackageOutputRoot(
+            prepared.workspaceRoot,prepared.validation.config,app.manifest
+        );
+        if(pathsOverlap(releaseRoot,outputRoot)
+            ||packageOutputs.some(existing=>pathsOverlap(existing,releaseRoot))){
+            throw new ArcaneError(
+                'ARCANE_PACKAGE_INVALID',
+                `Package output for ${app.appId} overlaps another selected package or native output directory.`
+            );
+        }
+        packageOutputs.push(releaseRoot);
+    }
     const selectedRelease=await packageNativeRelease(prepared,{
         appId:prepared.appId,
         appRoot:prepared.appRoot,
@@ -1180,6 +1195,9 @@ export async function runApplication(options={}){
     return runTarget({
         ...selectedOptions,
         ...prepared,
+        releaseRoot:resolvePackageOutputRoot(
+            prepared.workspaceRoot,prepared.validation.config,prepared.validation.app.manifest
+        ),
         target
     });
 }