arcane-os 0.39.1 → 0.40.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.40.1
+
+- Include complete selected local resource URL variants in generated static
+  PWA inventories. Reuse the source resource graph, resolve shared component
+  styles and modules against their runtime root, and retain speech worker mode
+  queries. Application selection, source content and output locations remain
+  unchanged; regenerate through the public import-map workflow to receive the
+  corrected offline inventory.
+- Space DigitalOcean FAL inference request starts by one second while retaining
+  four concurrent jobs and ordered playback. Retry a readable rate-limit
+  rejection once, honoring longer readable Retry-After values, and retry a
+  same-job status network failure once. An ambiguous submission network failure
+  is surfaced without submitting another potentially paid job.
+- Preserve the user's enabled speech intent after a synthesis, playback or
+  provider lifecycle failure. A failed job leaves unrelated queued jobs intact;
+  explicit Retry, Load, Mute and Cancel remain user-controlled.
+
+## 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.1` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/browser-runtime/ai/digitalocean-speech.mjs

@@ -113,6 +113,7 @@ export function createDigitalOceanFalTTSProvider({
     let generation = 0;
     let unloadOperation = null;
     let disposeOperation = null;
+    let nextInferenceStart = 0;
 
     function authority() {
         return {
@@ -214,12 +215,62 @@ export function createDigitalOceanFalTTSProvider({
         };
     }
 
+    async function fetchInference(url, options, operation) {
+        const signal = options.signal;
+        let retryError = null;
+        while (true) {
+            // Space request starts across jobs, not their completion. Remote jobs
+            // still run concurrently and the runtime retains ordered playback.
+            while (true) {
+                assertNotAborted(signal);
+                const delay = nextInferenceStart - Date.now();
+                if (delay <= 0) break;
+                await waitForStatus(delay, signal);
+            }
+            nextInferenceStart = Date.now() + POLL_INTERVAL_MS;
+            let response;
+            try {
+                response = await fetchImpl(url, options);
+            } catch (error) {
+                assertNotAborted(signal);
+                // A lost POST response may represent an accepted paid job. Only
+                // an identified job's status read can retry a network failure.
+                if (!retryError && options.method === 'GET' && error instanceof TypeError) {
+                    nextInferenceStart = Math.max(nextInferenceStart, Date.now() + POLL_INTERVAL_MS);
+                    retryError = error;
+                    console.warn('Retrying the cloud speech status read once.', error);
+                    continue;
+                }
+                throw error;
+            }
+            assertNotAborted(signal);
+            if (response.status === 429) {
+                // A readable rejection is safe to retry. Its cooldown also
+                // applies to waiting siblings, including when this retry ends.
+                const delay = Math.max(POLL_INTERVAL_MS, retryAfterDelay(response) ?? POLL_INTERVAL_MS);
+                nextInferenceStart = Math.max(nextInferenceStart, Date.now() + delay);
+            }
+            try {
+                await requireSuccessfulResponse(response, signal, operation);
+            } catch (error) {
+                assertNotAborted(signal);
+                if (!retryError && response.status === 429) {
+                    retryError = error;
+                    console.warn(`Retrying the cloud speech ${operation} once.`, error);
+                    continue;
+                }
+                throw error;
+            }
+            return response;
+        }
+    }
+
     async function synthesize(payload, controller, requestGeneration) {
         const signal = controller.signal;
         const apiKey = await readApiKey(signal);
         assertNotAborted(signal);
         const headers = {Authorization: `Bearer ${apiKey}`};
-        const response = await fetchImpl(
+        const response = await fetchInference(
             INVOKE_URL,
             {
                 method: 'POST',
@@ -235,9 +286,9 @@ export function createDigitalOceanFalTTSProvider({
                     }
                 ),
                 signal
-            }
+            },
+            'submission'
         );
-        await requireSuccessfulResponse(response, signal, 'submission');
         let result = await response.json();
         assertNotAborted(signal);
         const requestId = result?.request_id;
@@ -249,22 +300,11 @@ export function createDigitalOceanFalTTSProvider({
                 );
             }
             await waitForStatus(POLL_INTERVAL_MS, signal);
-            let statusResponse;
-            do {
-                statusResponse = await fetchImpl(
-                    `${INVOKE_URL}/${encodeURIComponent(requestId)}`,
-                    {method: 'GET', headers, signal}
-                );
-                assertNotAborted(signal);
-                const retryDelay = statusResponse.status === 429
-                    ? retryAfterDelay(statusResponse)
-                    : null;
-                if (retryDelay === null) break;
-                // Only status reads may be retried; submitting twice can create two paid jobs.
-                await statusResponse.text();
-                await waitForStatus(retryDelay, signal);
-            } while (true);
-            await requireSuccessfulResponse(statusResponse, signal, 'status read');
+            const statusResponse = await fetchInference(
+                `${INVOKE_URL}/${encodeURIComponent(requestId)}`,
+                {method: 'GET', headers, signal},
+                'status read'
+            );
             result = await statusResponse.json();
             assertNotAborted(signal);
         }

package/browser-runtime/ai/speech-worker-runtime.mjs

@@ -844,11 +844,10 @@ function validateConfiguration(configuration, role) {
 function nestedWorkerUrl(role) {
   const url = new URL(
     role === "stt"
-      ? "./browser-whisper-worker.mjs"
-      : "./browser-kokoro-worker.mjs",
+      ? "./browser-whisper-worker.mjs?arcaneSpeechWorkerMode=artifact-module-worker"
+      : "./browser-kokoro-worker.mjs?arcaneSpeechWorkerMode=artifact-module-worker",
     import.meta.url,
   );
-  url.searchParams.set("arcaneSpeechWorkerMode", "artifact-module-worker");
   return url;
 }
 

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/ai/browser-speech.md

@@ -56,8 +56,21 @@ punctuation boundary should submit promptly. This is incremental playback of
 completed synthesis jobs, not a live audio stream from DigitalOcean.
 
 The transport submits `POST https://inference.do-ai.run/v1/async-invoke`, then
-reads that job until its completed `output.audio.url` is available. Each
-segment is submitted once; only status reads retry a `429` with `Retry-After`.
+reads that job until its completed `output.audio.url` is available. One provider
+spaces inference request starts at least one second apart across its concurrent
+jobs; it does not wait for one remote job to finish before starting another.
+A readable `429` rejection permits one retry of the same submission or status
+request after at least one second. A longer readable `Retry-After` postpones
+all pending inference starts for that provider. A failed status Fetch may also
+retry once for the same accepted job. Repeated failures surface their complete
+diagnostics without an endless retry loop; a failed job does not cancel siblings.
+Retry diagnostics remain in the developer console, outside conversation history.
+
+An ambiguous submission network failure is not automatically resubmitted: a
+browser cannot distinguish a rejected preflight from an accepted paid job whose
+response was lost. This contract has no submission idempotency mechanism, and
+unreadable response headers cannot supply a server cooldown. Pacing reduces local
+request bursts; it does not claim to free upstream concurrency slots or fix CORS.
 The audio download never receives the inference Authorization header.
 The selected multilingual-v2 service supports speed `0.7` through `1.2`;
 unsupported speeds reject rather than being silently clamped. Complete

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

@@ -93,6 +93,16 @@ The application entry and generated PWA shell records are retained. Select the
 resources needed by every offline page, including its shared modules and styles.
 The worker script itself is never an application cache entry.
 
+For direct installed-package root applications, public `arcane import-map`
+generation follows the same source resource graph as `arcane dev` before writing
+the static offline inventory. Imports from unvisited pages, shared runtime
+modules, component styles, and statically declared Worker URLs retain their
+authored query values. SDK component `./arcane/` resource attributes resolve from
+that component's actual runtime root, including installed package aliases and
+nested component directories; ordinary application document bases keep their
+normal meaning. The graph selects resources already present in the configured
+routes. It does not invent resource paths or enumerate user-specific page URLs.
+
 These settings describe published application resources. They do not select
 user uploads, provider responses, live API requests, saved conversations,
 preferences, IndexedDB, OPFS, or a model owner's download/cache lifecycle.
@@ -180,7 +190,7 @@ without loading certificates; see [explicit HTTP development](cli.md#explicit-ht
 `--public` selects the IPv4 wildcard bind address; it does not enable PWA
 configuration, change manifest metadata, or determine browser installability.
 
-Source inventory work begins when the browser requests the worker or current
+Live source inventory work begins when the browser requests the worker or current
 offline manifest, after the page can start. It traverses the selected route
 inventory once for that request, follows page and runtime resource references
 to retain selected query variants, and shares an in-flight traversal with
@@ -189,6 +199,11 @@ document corpus bodies remain under their existing owner. It does not rebuild
 the application. Installation metadata and bootstrap requests reuse the current
 generated bundle.
 
+An explicit root import-map refresh also performs that traversal to produce the
+committed static PWA files. It opens no server or listener. Its generated
+inventory is available to ordinary static hosting without first visiting each
+page through the development server.
+
 The SDK owns version information in `arcane-offline.json`:
 
 | Field | Owner and update rule |
@@ -262,6 +277,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/runtime-components.md

@@ -1566,8 +1566,10 @@ boundary applies to STT activation, transcription, TTS lifecycle, synthesis,
 and playback failures.
 
 `reportTTSError()` recognizes `synthesis`, `decode`, `playback-start`, and
-`playback-resume`. It mutes and stops the failed operation, preserves sticky
-provider readiness, and emits `speech-synthesis-error` with the exact boundary,
+`playback-resume`. It preserves the user's mute choice, sticky provider
+readiness, and accepted sibling speech jobs. The AI runtime owns settlement of
+the failed job; reporting an error neither stops the queue nor retries it. The
+component emits `speech-synthesis-error` with the exact boundary,
 stable reason/code, generic user-safe status, and complete Error in the local
 event detail.
 
@@ -1600,8 +1602,16 @@ same capture operation id rather than inventing a second correlation boundary.
 User Unmute calls the shared `AI.setSpeechMuted(false)` lifecycle owner before
 or with publishing the TTS load intent, so the runtime can legally load TTS.
 Configured `initialMuted:false` records that same unmute intent even when the
-TTS route is still unselected or loading; the component remains publicly muted
-until the selected role reaches `ready`, then applies the preserved intent.
+TTS route is still unselected or loading. Public `muted` expresses the user's
+choice; role availability and the AI runtime still prevent playback until the
+selected role reaches `ready`, when the waiting intent is applied. A failed
+load ends its activation attempt without changing that choice or starting
+another attempt. Retry voice explicitly starts a new attempt, including when
+the preserved choice is unmuted; an unloaded selected voice offers Load voice.
+When a role returns to ready, permitted queued playback resumes through the
+existing AI owner without repeating activation or replaying failed jobs.
+Synthesis, decode, and playback failures also
+preserve that choice and do not automatically replay failed speech.
 Mute calls `AI.setSpeechMuted(true)`, stops playback, cancels active TTS work,
 and unloads the selected TTS role. Lifecycle failures remain visible through
 `speech-tts-lifecycle-error` and sticky role state.

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.1",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/runtime/arcane/components/speech.html

@@ -518,7 +518,7 @@
             requestUserMute();
         } else {
             pendingUnmute = true;
-            host.muted = true;
+            host.muted = false;
             if (!settleSuccessfulUnmute()) {
                 synchronizeAIMutedState();
                 continuePendingUnmute();
@@ -567,21 +567,24 @@
         if (sttBecameUnready) {
             cancelSTTOperation('runtime-unready');
         }
-        if (ttsBecameUnready) {
+        if (ttsBecameUnready && ttsRole.state !== 'error') {
             pendingUnmute = false;
-            host.muted = true;
             stopTTSPlayback();
         }
-        if (ttsRole.state === 'error' && (pendingUnmute || !host.muted)) {
+        if (ttsRole.state === 'error') {
             pendingUnmute = false;
-            host.muted = true;
-            stopTTSPlayback();
         }
 
-        settleSuccessfulUnmute();
+        const unmuteSettled = settleSuccessfulUnmute();
         continuePendingUnmute();
 
         synchronizeAIMutedState();
+        if (!unmuteSettled
+            && previousTTSRole.state !== 'ready'
+            && ttsRole.state === 'ready'
+            && !host.muted) {
+            resumeTTSPlayback();
+        }
         renderControls();
         renderStatus();
     }
@@ -720,6 +723,9 @@
             if (pendingTTSIntent === 'load') {
                 label = 'Cancel voice load';
                 description = 'Cancel loading the selected voice.';
+            } else if (!host.muted) {
+                label = 'Load voice';
+                description = 'Load the selected voice.';
             }
         } else if (ttsRole.state === 'error') {
             disabled = !providerSelected;
@@ -960,7 +966,7 @@
             return;
         }
 
-        if (host.muted) {
+        if (host.muted || ['unloaded', 'error'].includes(ttsRole.state)) {
             void requestUserUnmute();
         } else {
             requestUserMute();
@@ -976,7 +982,7 @@
         }
         const wasMuted = host.muted;
         pendingUnmute = false;
-        const shouldUnload = !wasMuted
+        const shouldUnload = (!wasMuted && is.function(globalThis.ai?.setSpeechMuted))
             || pendingTTSIntent === 'load'
             || ['loading', 'ready', 'error'].includes(ttsRole.state);
         host.muted = true;
@@ -1004,9 +1010,9 @@
         ) {
             return false;
         }
+        host.muted = false;
         if (!is.function(globalThis.ai?.setSpeechMuted)) {
             pendingUnmute = true;
-            host.muted = true;
             renderControls();
             renderStatus();
             return false;
@@ -1021,8 +1027,7 @@
                 && ['unloaded', 'loading', 'error'].includes(ttsRole.state)
             );
         if (!canRequestLoad) {
-            host.muted = true;
-            stopTTSPlayback();
+            pendingUnmute = false;
             reportTTSLifecycleError(
                 new Error('No selected speech provider is available to load.'),
                 'load'
@@ -1038,8 +1043,6 @@
         }
         if (!requested) {
             pendingUnmute = false;
-            host.muted = true;
-            stopTTSPlayback();
             renderControls();
             renderStatus();
             return false;
@@ -1117,8 +1120,6 @@
             pendingTTSIntent = null;
             if (action === 'load') {
                 pendingUnmute = false;
-                host.muted = true;
-                stopTTSPlayback();
             }
             reportTTSLifecycleError(error, action, operationId);
             return false;
@@ -1211,8 +1212,6 @@
             : 'synthesis';
         const failure = failures[normalizedBoundary];
         const message = visibleErrorMessage(error, failure.message);
-        host.muted = true;
-        stopTTSPlayback();
         localStatus = {
             message,
             tone: 'error'

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/dev-server.mjs

@@ -13,7 +13,7 @@ import {APP_CONFIG_NAME, validateAppConfig} from './packager/core.mjs';
 import {createEventQueue} from './event-queue.mjs';
 import {
     applyPwaEntryReferences,inspectImportMapHtml,MANAGED_IMPORT_MAP_ATTRIBUTE,
-    readWorkspaceAssetVersion,rewriteAssetReferences,versionAssetUrl
+    readWorkspaceAssetVersion,resolveAssetReference,rewriteAssetReferences,versionAssetUrl
 } from './import-map.mjs';
 import {createPwaArtifacts,selectPwaFiles} from './pwa.mjs';
 
@@ -658,14 +658,15 @@ async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourc
                 }
             }
         }
-        for (const {url, kind, baseHref, baseKind} of references) {
+        for (const reference of references) {
+            const {url, kind} = reference;
             if (kind === 'import' && !/^(?:\.{1,2}\/|\/)/u.test(url)) continue;
             let target;
-            let base;
             try {
-                base = baseHref ? new URL(baseHref, current.url)
-                    : managedMap || baseKind === 'document' ? documentUrl : current.url;
-                target = new URL(versionAssetUrl(url, null), base);
+                target = resolveAssetReference(
+                    {...reference, url: versionAssetUrl(url, null)},
+                    {ownerUrl: current.url, documentUrl, managedMap}
+                );
             } catch {
                 // Non-URL source values retain their authored behavior.
                 continue;
@@ -695,6 +696,11 @@ async function sourcePwaAssets(routeSet, mappings, signal, resourceUrls, resourc
     return [...selectedUrls].sort();
 }
 
+export async function collectSourcePwaAssets({workspaceRoot,appId,signal,onEvent}={}){
+    const routes=await sourceRoutes(workspaceRoot,appId,{signal,onEvent});
+    return sourcePwaAssets(routes,routes.mappings,signal,new Set(),new Set());
+}
+
 function closeDevelopmentListeners(fileServer, tlsServer) {
     const closeTls = tlsServer ? new Promise(
         function closeRawTlsListener(resolve, reject) {
@@ -1236,13 +1242,16 @@ async function startOwnedDevServer({
                     .includes(request.headers['sec-fetch-dest']);
                 const rewrite=runtimeResource||entryDocument||browserResource||managedMap
                     ||resourcePaths.has(target.path);
-                const onReference = function observeServedResource({url,kind,baseHref,baseKind}) {
+                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 base = baseHref ? new URL(baseHref, documentUrl) : documentUrl;
-                            const resource = new URL(versionAssetUrl(url, null), base);
+                            const resource = resolveAssetReference(
+                                {...reference,url:versionAssetUrl(url,null)},
+                                {ownerUrl:documentUrl}
+                            );
                             if (resource.origin === documentUrl.origin) {
                                 pwaResourceUrls.add(`${resource.pathname}${resource.search}`);
                             }
@@ -1254,8 +1263,7 @@ async function startOwnedDevServer({
                         ||(kind==='import'&&!/^(?:\.{1,2}\/|\/)/u.test(url)))return;
                     try{
                         const documentUrl=new URL(target.path,'http://arcane.invalid');
-                        const base=baseHref?new URL(baseHref,documentUrl):documentUrl;
-                        const resource=new URL(url,base);
+                        const resource=resolveAssetReference(reference,{ownerUrl:documentUrl});
                         if(resource.origin===documentUrl.origin
                             &&/\.(?:m?js|html?|css)$/iu.test(resource.pathname)){
                             resourcePaths.add(decodeURIComponent(resource.pathname));

package/src/import-map.mjs

@@ -1281,6 +1281,23 @@ export function rewriteAssetReferences(source,{filePath,version=SDK_VERSION,onRe
     return source;
 }
 
+export function resolveAssetReference({url,baseHref,baseKind},{ownerUrl,documentUrl=ownerUrl,managedMap=false}){
+    if(baseKind==='component-runtime'&&url.startsWith('./arcane/')){
+        const owner=new URL(ownerUrl);
+        const marker='/arcane/components/';
+        const componentIndex=owner.pathname.lastIndexOf(marker);
+        if(componentIndex>=0){
+            // HTMLImport resolves these component attributes against their
+            // installed runtime, independently of the host document's base.
+            const runtimeRoot=new URL(owner.pathname.slice(0,componentIndex+'/arcane/'.length),owner.origin);
+            return new URL(url.slice('./arcane/'.length),runtimeRoot);
+        }
+    }
+    const base=baseHref?new URL(baseHref,ownerUrl)
+        :managedMap||baseKind==='document'?documentUrl:ownerUrl;
+    return new URL(url,base);
+}
+
 function registerSpecifier(registry,specifier,target){
     registry.set(specifier,{specifier,target});
 }
@@ -2071,7 +2088,9 @@ function htmlReferenceEdits(source,version,onReference){
                 :element.tag==='link'&&relationships.includes('preload')
                     &&['script','worker','style'].includes(destination)?destination==='style'?'style':'script':'asset';
             const view=htmlAttributeView(original);
-            if(view)reportAssetReference(reportHtmlReference,view.decoded,kind);
+            if(view)reportAssetReference(reportHtmlReference,view.decoded,kind,
+                (name==='href'||name==='src')&&view.decoded.startsWith('./arcane/')
+                    ?'component-runtime':undefined);
             const value=versionHtmlAttribute(original,version);
             if(value===original)continue;
             const position=attributes.positions.get(name);

package/src/packager/core.mjs

@@ -12,13 +12,14 @@ 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 {
     applyPwaEntryReferences,
     inspectImportMapHtml,
     readWorkspaceAssetVersion,
+    resolveAssetReference,
     rewriteAssetReferences,
     versionAssetUrl
 } from '../import-map.mjs';
@@ -307,7 +308,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 +317,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 +355,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 +426,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 +556,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 +636,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 +657,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 +815,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 +834,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) {
@@ -892,17 +968,19 @@ async function packageWithContext(context,options={}){
                 resource={references,...(pwaDocumentSources.has(relative)?{content}:{})};
                 resources.set(relative,resource);
             }
-            for(const {url,kind,baseHref,baseKind} of resource.references){
+            for(const reference of resource.references){
+                const {url,kind,baseHref}=reference;
                 const traversable=kind!=='fetch'&&(kind!=='asset'||/\.css(?:[?#]|$)/iu.test(url))
                     &&(kind!=='import'||/^(?:\.{1,2}\/|\/)/u.test(url));
                 if(!pwaEnabled&&!traversable)continue;
                 if(kind==='import'&&!/^(?:\.{1,2}\/|\/)/u.test(url))continue;
                 try{
                     const ownerUrl=new URL(packageResourceUrl(relative),entryUrl.origin);
-                    const base=baseHref?new URL(baseHref,ownerUrl)
-                        :baseKind==='document'||path.posix.basename(relative)==='arcane.importmap.json'
-                            ?current.documentUrl:ownerUrl;
-                    const target=new URL(url,base);
+                    const target=resolveAssetReference(reference,{
+                        ownerUrl,
+                        documentUrl:current.documentUrl,
+                        managedMap:path.posix.basename(relative)==='arcane.importmap.json'
+                    });
                     if(target.origin===entryUrl.origin){
                         const file=decodeURIComponent(target.pathname).replace(/^\//u,'');
                         if(pwaEnabled&&offlineInventory.has(file)){
@@ -1009,7 +1087,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 {
@@ -10,7 +11,7 @@ import {
     validateWorkspace
 } from './workspace.mjs';
 import {loadArcaneIntegratedProvider} from './integrated-provider-loader.mjs';
-import {startDevServer} from './dev-server.mjs';
+import {collectSourcePwaAssets,startDevServer} from './dev-server.mjs';
 import {applyPwaEntryReferences,generateImportMap,readApplicationTestImportMapContext} from './import-map.mjs';
 import {createPwaArtifacts} from './pwa.mjs';
 import {readInstalledSdkLayout} from './sdk-runtime-layout.mjs';
@@ -336,11 +337,21 @@ async function refreshRootApplicationFiles(prepared,inspected,importMap,{signal,
         ...inspected.files.filter(file=>file!=='index.html'||manifest.include.includes('index.html')),
         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
+        ?(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({
         app:{id:appId,displayName:manifest.displayName,version:manifest.version,entry},
         sdkVersion:installed.version,
         pwa:manifest.pwa,
         files,
+        assets,
         basePath:'/',
         appBase:'/',
         installationId:`/apps/${appId}/`,
@@ -1022,6 +1033,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 +1205,9 @@ export async function runApplication(options={}){
     return runTarget({
         ...selectedOptions,
         ...prepared,
+        releaseRoot:resolvePackageOutputRoot(
+            prepared.workspaceRoot,prepared.validation.config,prepared.validation.app.manifest
+        ),
         target
     });
 }