arcane-os 0.28.4 → 0.29.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.29.1
+
+- Preserve complete long and non-ASCII filenames in application release bundles
+  through standard per-file PAX path extensions. Public bundle creation and
+  verification retain logical payload paths and complete file content without
+  application-side renaming. Ordinary USTAR representation remains supported,
+  and the existing SDK-version metadata contract is unchanged. Bundles using
+  extended paths require the updated SDK reader or another PAX-capable reader.
+- Preserve application-authored resource URL queries, including `v`, encoded
+  and repeated fields, empty query segments, and fragments. Import-map refresh,
+  serving, packaging, and PWA delivery now change only SDK-owned `arcaneVersion`
+  fields through the existing shared transformer.
+
+## 0.29.0
+
+- Add `legacyAppPaths: false` to `arcane-packager.json` for root applications
+  using `appsRoot: "."`. Import-map refresh, source development, and packaging
+  omit SDK-generated `apps/<id>` navigation aliases and legacy PWA worker and
+  inventory files. Omission or `true` preserves the existing behavior.
+- Preserve application storage identity, explicit PWA manifest identity, direct
+  installed npm resource URLs, and selected authored files. The SDK does not
+  delete existing historical files. Applications choosing root-only output own
+  removal of those files and the resulting loss of old bookmark, launch, and
+  service-worker update URLs that depended on them.
+
 ## 0.28.4
 
 - Preserve installed component-relative browser-runtime and strong-type import

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.28.4` SDK contract. Applications pin one exact npm
+This checkout defines the `0.29.1` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -604,9 +604,13 @@ prior file until the replacement is complete. Cancellation or failure before
 commit restores the prior output when that can be done without overwriting a
 concurrent change. A conflicting or uncertain path is preserved for inspection.
 
-The archive uses the documented USTAR+gzip structure and publishes its v1 JSON
-contract at `arcane-os/schemas/arcane-app-bundle.json`. When the user explicitly
-selects bundle verification, it rejects malformed archives, links, devices,
+The archive uses USTAR+gzip with per-file PAX path extensions for long or
+non-ASCII filenames and publishes its v1 JSON contract at
+`arcane-os/schemas/arcane-app-bundle.json`. Logical filenames and content remain
+complete; ordinary USTAR paths retain their existing representation, and bundle
+metadata keeps its existing SDK-version matching contract. Readers must support
+PAX path extensions to consume bundles that need them. When the
+user explicitly selects bundle verification, it rejects malformed archives, links, devices,
 unsafe or colliding paths, unsupported archive members, trailing data, and
 inconsistent descriptor or inventory structure. These checks reject corrupt
 selected artifacts; they do not impose byte-count, hash, provenance, or

package/docs/architecture.md

@@ -273,16 +273,31 @@ External repository delivery adds a distinct schema-1
 `arcane-app-release-bundle` envelope. Bundle creation uses an authored schema-2
 `arcane-app.json`; a synthesized package or registry projection remains valid for integrated
 packaging but is not used for an external bundle. The
-archive contains exactly `ARCANE_APP_BUNDLE.json`, canonical `arcane-app.json`,
+logical file inventory contains exactly `ARCANE_APP_BUNDLE.json`, canonical `arcane-app.json`,
 `payload/ARCANE_APP_RELEASE.json`, and the release inventory beneath `payload/`
 in that order. The envelope adds no repository-only source or build tooling
 beyond that selected release inventory. Individual apps remain responsible for
 their authored source policy.
 
-The bundle contract uses the documented USTAR+gzip structure. Explicit bundle
-verification parses the selected archive without extraction and rejects
-genuinely malformed structures, unsafe or colliding paths, unsupported members,
-trailing data, and incompatible bundle generations. These corrupt-artifact
+The bundle contract retains schema 1 and the `ustar+gzip` format identifier.
+Ordinary representable ASCII paths use the existing USTAR headers. Long paths
+and non-ASCII names use a [POSIX PAX](https://docs.oracle.com/cd/E86824_01/html/E54763/pax-1.html)
+per-file `x` header containing the complete
+UTF-8 `path`, immediately before that file's regular header and content. This
+transport framing is not a payload member and never appears in the logical
+inventory or `readFile()` results. Path spelling and file content remain unchanged;
+the existing portable-path rules still apply. The public
+`createCanonicalUstarHeader()` helper remains a single USTAR header and retains
+its format-local field limits; complete bundles use `createAppReleaseBundle()`.
+
+The bundle reader consumes these `path` extensions for the following file only,
+as well as ordinary USTAR entries. Other PAX attributes and archive member
+types remain outside this bundle profile. Older SDK readers without PAX support
+cannot read bundles that require these extensions; update the consuming SDK
+before importing one. The existing same-SDK-version bundle condition is unchanged.
+Explicit bundle verification parses the selected archive without extraction and
+rejects genuinely malformed structures, unsafe or colliding paths, unsupported
+members, and incompatible bundle generations. These corrupt-artifact
 checks do not create byte-count, content-hash, provenance, or admission gates
 for ordinary development, packaging, serving, or running.
 

package/docs/reference/asset-versioning.md

@@ -3,7 +3,7 @@
 Applications that enable [PWA delivery](pwa.md) use clean local resource URLs.
 Their generated offline manifest and service worker own the selected application
 and SDK release information. In that mode, the delivery transformer removes
-both `v` and `arcaneVersion`, preserving other query fields and fragments.
+only the SDK-owned `arcaneVersion` field, preserving authored query fields and fragments.
 The behavior below continues to apply when PWA delivery is disabled and to native
 packages. Workspace runtime materialization remains usable by either target;
 the selected browser delivery applies its PWA URL policy.
@@ -15,11 +15,12 @@ SDK package metadata, not a timestamp, content measurement, or application
 constant.
 
 For example, an existing `./arcane/modules/HTMLImport.js?v=6#module` reference
-becomes `./arcane/modules/HTMLImport.js?arcaneVersion=${version}#module`.
-`arcaneVersion` is the sole resource version field: transformation removes `v`,
-updates the first existing `arcaneVersion`, and removes duplicate version fields.
-Regenerating for another SDK release replaces that version value. Unrelated
-query fields, their spelling, and fragments remain intact.
+becomes `./arcane/modules/HTMLImport.js?v=6&arcaneVersion=${version}#module`.
+`arcaneVersion` is the SDK's resource version field: transformation updates its
+first existing value and removes duplicate `arcaneVersion` fields, or appends it
+when absent. Regenerating for another SDK release replaces only that SDK value.
+Authored fields, including `v`, encoded keys and values, repeated or empty query
+segments, their source spelling, and fragments remain intact.
 
 ## Public tooling
 

package/docs/reference/cli.md

@@ -228,6 +228,16 @@ portable runtime subpaths such as `arcane-os/preference-store` and
 modules. The result reports the complete map written to the selected
 application; no fixed entry count is a release contract.
 
+For `appsRoot: "."`, the artifact is `modules/arcane.importmap.json` at the
+application root. Set `"legacyAppPaths": false` in `arcane-packager.json` to
+omit SDK-generated `apps/<id>/` navigation/PWA compatibility files and aliases.
+The same workspace choice applies to `arcane dev` and `arcane package`; restart
+an already running dev server after changing it. The default remains `true`.
+Root PWA files, app/installation identity and selected authored files are
+preserved. Existing files are never deleted by this option. See
+[root-only generated output](pwa.md#root-only-generated-output) before changing
+the URLs needed by previously installed apps.
+
 SDK `0.5.17` preserves the physical workspace route count and ordered include
 list. External and modern integrated routes require `components`, `css`,
 `dependencies`, `entities`, `img`, `modules`, and `sdk`; a physical workspace
@@ -532,6 +542,12 @@ selected SDK content directly from `node_modules`. Only the portable output
 receives copies; no workspace `arcane/` projection is required. Its runtime URLs,
 managed import-map targets, and PWA inventory destinations match source serving.
 
+With `appsRoot: "."`, app files retain their root-relative layout. The optional
+root-config `legacyAppPaths: false` omits SDK-generated compatibility files
+beneath `apps/<id>/` from the planned and actual output. It does not omit
+explicitly selected authored resources at those paths or change the default
+packaged installation identity. Omission or `true` preserves existing behavior.
+
 ```text
 arcane package [--app <id>] [--dry-run]
 ```

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

@@ -464,14 +464,14 @@
       "name": "createAppReleaseBundle",
       "displayName": "createAppReleaseBundle()",
       "kind": "function",
-      "signature": "async createAppReleaseBundle({ receipt, releaseRoot, outputPath, overwrite=false, signal, onEvent }={})",
+      "signature": "async createAppReleaseBundle({releaseRoot, appDescriptor, outputPath, overwrite=false, signal, onEvent}={})",
       "entrypoints": [
         "arcane-os",
         "arcane-os/release-bundle"
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Writes one deterministic USTAR+gzip external application bundle from the selected authored release state.",
+      "summary": "Writes one deterministic USTAR+gzip external application bundle, using per-file POSIX PAX path extensions for complete long or non-ASCII filenames.",
       "availability": "Node",
       "protocol": "SDK packager and deterministic bundle contract",
       "normalization": "Normalized SDK validation with complete canonical archive and release content"
@@ -2164,7 +2164,7 @@
       ],
       "primaryImport": "arcane-os",
       "group": "Packaging and release bundles",
-      "summary": "Parses and authenticates one deterministic app bundle without extraction.",
+      "summary": "Parses one deterministic app bundle without extraction, supporting ordinary USTAR entries and complete per-file POSIX PAX paths within the existing same-SDK-version contract.",
       "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

@@ -180,6 +180,24 @@ query strings and fragments. It preserves authored files at those destinations.
 For a direct-installed root PWA it generates the static PWA records at the root,
 so normal static hosting needs no SDK request handler or runtime copy.
 
+To select root-only generated output, set `"legacyAppPaths": false` beside
+`"appsRoot": "."` in `arcane-packager.json`. This optional boolean defaults to
+`true`; it has no effect on the `appsRoot: "apps"` layout. The shared import-map
+refresh, source dev server, package inspection, dry run and package output then
+omit SDK-generated `apps/<id>/` navigation pages, navigation aliases, and the
+legacy PWA worker/offline inventory. Root PWA files and normal managed imports
+remain available. Edit the root configuration before starting `arcane dev`;
+restart an existing server after changing this workspace-level choice.
+
+This option does not change the application ID, stored data, the existing
+default installation ID or an authored `pwa.manifest.id`. It neither deletes
+existing files nor removes authored resources from the app's include/exclude
+selection. Explicitly included files under `apps/<id>/` still serve and package
+as authored resources. Previously installed launch URLs and worker update URLs
+need their old resources to remain available; retain the default compatibility
+output when those URLs still need SDK support. See the
+[root PWA compatibility boundary](pwa.md#root-only-generated-output).
+
 Direct-installed root maps expose `arcane-os/modules/<filename>` and
 `arcane-os/entities/<filename>` (including extensions), plus the existing
 focused lowercase package exports. They omit the old `arcane/*` and

package/docs/reference/pwa.md

@@ -71,6 +71,38 @@ introduced. Offline clients require a later successful connection to receive
 updated files; fixture coverage does not establish a particular installed app's
 actual browser lifecycle.
 
+### Root-only generated output
+
+For a root application, add `"legacyAppPaths": false` to the workspace's
+`arcane-packager.json`, alongside `"appsRoot": "."`. The default is `true`.
+This selects root-only SDK-generated navigation and PWA output in import-map
+refresh, `arcane dev`, package inspection/dry run, and browser packaging:
+
+- The four root PWA files remain generated normally.
+- The SDK generates no `apps/<id>/` navigation pages, legacy worker or legacy
+  offline inventory, and adds no legacy navigation aliases or dev redirects.
+- The default source installation ID remains `/apps/<id>/`, the default
+  packaged installation ID remains `./`, and an explicit `manifest.id` remains
+  authoritative. An ID is an installation identifier, not a request to generate
+  a directory. App identity and saved application data remain unchanged.
+- Existing files are left on disk. Explicitly selected authored old-path
+  resources remain in the normal source/package/offline inventory; this setting
+  is not a deletion or migration command.
+
+Restart `arcane dev` after changing this workspace configuration. Omission or
+`true` retains the compatibility behavior described above. The option has no
+effect on apps whose configured `appsRoot` is `"apps"`.
+
+An installed app may still launch an old `/apps/<id>/` URL, and an existing
+worker registration may still update its old script/inventory URL. Disabling
+generation does not redirect those installed clients, unregister their worker,
+clear caches or guarantee their next update. Keep compatibility output enabled
+while old URLs still require SDK support, or supply the required resources
+through the application's own declared files and hosting policy. This SDK
+option alone makes no claim about any existing installation's adoption.
+
+### Offline resource selection
+
 `offline.include` and `offline.exclude` select literal paths or directory
 prefixes from the selected emitted inventory. An omitted or empty include list
 selects that inventory; exclusions subtract from it. App files use app-relative
@@ -118,9 +150,10 @@ The same bootstrap starts one initially hidden `pwa-install.html` component with
 the generated manifest's app name. Component loading and worker registration
 proceed independently.
 
-The selected PWA browser delivery removes `v` and `arcaneVersion` from actual
-local resource references, including the managed import map. Other query fields,
-fragments, source spelling and unrelated payloads are preserved. The offline
+The selected PWA browser delivery removes only SDK-owned `arcaneVersion` fields
+from actual local resource references, including the managed import map. Authored
+fields such as `v`, encoded and repeated fields, empty query segments, fragments,
+source spelling and unrelated payloads are preserved. The offline
 manifest now carries release information. Non-PWA and native delivery retain
 the [existing asset version contract](asset-versioning.md).
 

package/docs/reference/sdk-api.md

@@ -629,12 +629,17 @@ async function previewNextPrerelease(workspaceRoot) {
 
 ### Overview
 
-Writes one deterministic USTAR+gzip external application bundle from the selected authored release state.
+Writes one deterministic USTAR+gzip external application bundle from the selected
+authored release state. Long or non-ASCII filenames use per-file POSIX PAX `path`
+extensions, preserving their complete UTF-8 spelling and file content. Ordinary
+USTAR entries remain unchanged. Metadata framing is excluded from the manifest's
+logical file inventory. Existing portable-path rules, schema 1, and the
+`ustar+gzip` format identifier remain unchanged.
 
 ### Signature and result
 
 ```text
-async createAppReleaseBundle({ receipt, releaseRoot, outputPath, overwrite=false, signal, onEvent }={})
+async createAppReleaseBundle({releaseRoot, appDescriptor, outputPath, overwrite=false, signal, onEvent}={})
 ```
 
 Import it from `arcane-os` or `arcane-os/release-bundle`. The signature above states whether settlement is synchronous or promise-based. The overview and owning group define result authority, side effects, callbacks, events, cancellation, and lifecycle.
@@ -658,6 +663,9 @@ async function usecreateAppReleaseBundle(...arguments_) {
 ### Overview
 
 Builds the exact 512-byte canonical USTAR header for one validated bundle entry.
+This low-level helper remains a single regular-file header with the USTAR field
+limits. Use `createAppReleaseBundle()` to encode complete long or Unicode paths;
+the bundle writer supplies PAX framing where needed.
 
 ### Signature and result
 
@@ -1041,6 +1049,15 @@ async function usevalidateAppConfig(...arguments_) {
 
 Validates one root packager mapping and its fixed shared-route boundaries.
 
+The schema-1 `arcane-packager.json` accepts the optional boolean
+`legacyAppPaths`, normalized to `true` when omitted. With `appsRoot: "."`,
+setting it to `false` omits generated legacy `apps/<id>/` navigation/PWA output
+across managed-map refresh, development serving, inspection and packaging.
+It leaves installation identity and authored file selection unchanged and has
+no effect with `appsRoot: "apps"`. See
+[standalone root applications](protocols.md#optional-standalone-root-application)
+for configuration, retained-file and existing-installation behavior.
+
 ### Signature and result
 
 ```text
@@ -1095,7 +1112,14 @@ async function useverifyApp(...arguments_) {
 
 ### Overview
 
-Parses and authenticates one deterministic app bundle without extraction.
+Parses one deterministic app bundle without extraction and checks its structural
+manifest and complete logical file inventory. It supports ordinary USTAR entries
+and per-file POSIX PAX `path` extensions. The complete extended path is used by
+`files` and `readFile()`; the metadata and regular-header placeholder are not
+payload files. Malformed or orphaned PAX records produce `ARCANE_BUNDLE_INVALID`.
+Other PAX attributes and archive member types remain unsupported. The existing
+same-SDK-version condition remains unchanged. An older reader without PAX support
+must be updated before importing a bundle that requires these path extensions.
 
 ### Signature and result
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.28.4",
+  "version": "0.29.1",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/schemas/arcane-app-bundle.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/TheWizardNexus/arcane-os-sdk/schemas/arcane-app-bundle.schema.json",
   "title": "Arcane external application release bundle",
-  "description": "Structural manifest for one complete USTAR+gzip application bundle.",
+  "description": "Structural manifest for one complete USTAR+gzip application bundle, with per-file POSIX PAX path extensions for long or non-ASCII filenames. PAX framing is excluded from the logical file inventory.",
   "type": "object",
   "required": [
     "schemaVersion",

package/src/app-layout.mjs

@@ -5,6 +5,12 @@ export function appRelativeRoot(config, appId) {
     return config.appsRoot === '.' ? '' : `apps/${appId}`;
 }
 
+// Generated compatibility URLs are separate from installation and storage identity.
+export function rootAppLegacyPath(config, appId) {
+    return config.appsRoot === '.' && config.legacyAppPaths !== false
+        ? `apps/${appId}` : undefined;
+}
+
 export function resolveAppRoot(workspaceRoot, config, appId) {
     return path.resolve(workspaceRoot, appRelativeRoot(config, appId));
 }

package/src/dev-server.mjs

@@ -6,7 +6,7 @@ import https from 'node:https';
 import os from 'node:os';
 import path from 'node:path';
 import {resolveWorkspace} from './workspace.mjs';
-import {appRelativeRoot} from './app-layout.mjs';
+import {appRelativeRoot,rootAppLegacyPath} from './app-layout.mjs';
 import {readInstalledSdkLayout} from './sdk-runtime-layout.mjs';
 import {APP_DESCRIPTOR_NAME, projectPackageManifest} from './app-descriptor.mjs';
 import {APP_CONFIG_NAME, validateAppConfig} from './packager/core.mjs';
@@ -1047,10 +1047,11 @@ async function startOwnedDevServer({
     const pwaResourceUrls = new Set();
     function developmentPwaArtifacts(selectedRoutes, assets = [], version = assetVersion) {
         const rootApp = selectedRoutes.config.appsRoot === '.';
+        const legacyAppPath = rootAppLegacyPath(selectedRoutes.config, selectedRoutes.appId);
         const appBase = applicationSourcePath(selectedRoutes.config,selectedRoutes.appId);
         const navigationAliases = {'/': selectedRoutes.startPath};
-        if (rootApp) {
-            const legacyBase = `/apps/${selectedRoutes.appId}`;
+        if (legacyAppPath) {
+            const legacyBase = `/${legacyAppPath}`;
             navigationAliases[legacyBase] = selectedRoutes.startPath;
             navigationAliases[`${legacyBase}/`] = selectedRoutes.startPath;
             for (const asset of [selectedRoutes.startPath,...assets]) {
@@ -1082,9 +1083,9 @@ async function startOwnedDevServer({
                 basePath: '/',
                 appBase,
                 ...(rootApp ? {
-                    installationId:`/apps/${routeSet.appId}/`,
-                    legacyAppPath:`apps/${routeSet.appId}`
+                    installationId:`/apps/${routeSet.appId}/`
                 } : {}),
+                legacyAppPath,
                 runtimeBase: selectedRoutes.browserRuntimeBase
                     ?? selectedRoutes.installed?.browserRuntimeBase ?? '/arcane/sdk/',
                 mode: 'development'
@@ -1176,7 +1177,7 @@ async function startOwnedDevServer({
             const target=parseRequestTarget(request.url);
             if(!target){deny(response,400,'Invalid request path.');return;}
             const {segments}=target;
-            const legacyAppRequest = mode === 'source' && routeSet.config.appsRoot === '.'
+            const legacyAppRequest = mode === 'source' && rootAppLegacyPath(routeSet.config, routeSet.appId)
                 && segments[0] === 'apps' && segments[1] === routeSet.appId;
             const legacyPwaRequest = legacyAppRequest && segments.length === 3
                 && ['arcane-sw.js', 'arcane-offline.json'].includes(segments[2]);

package/src/import-map.mjs

@@ -847,7 +847,7 @@ function assetUrlVersionEdits(value,version){
         let decodedKey=key;
         try{decodedKey=decodeURIComponent(key.replaceAll('+',' '));}
         catch{decodedKey=key;}
-        const remove=decodedKey==='v'||(decodedKey==='arcaneVersion'&&(clean||versionFound));
+        const remove=decodedKey==='arcaneVersion'&&(clean||versionFound);
         parameters.push({start:offset,end:offset+parameter.length,remove});
         if(decodedKey==='arcaneVersion'&&!versionFound&&!clean){
             versionFound=true;
@@ -859,10 +859,10 @@ function assetUrlVersionEdits(value,version){
         }
         offset+=parameter.length+1;
     }
-    if(clean&&!parameters.some(function hasRemainingField(parameter){
-        return !parameter.remove&&parameter.end>parameter.start;
+    if(clean&&parameters.every(function removesSdkField(parameter){
+        return parameter.remove;
     }))return [{start:queryStart,end:address.length,value:''}];
-    // Remove adjacent obsolete fields together, including only their separator.
+    // Remove adjacent SDK version fields together, including only their separator.
     // Other field spelling and source-level escapes remain untouched.
     for(let index=0;index<parameters.length;index+=1){
         if(!parameters[index].remove)continue;
@@ -874,13 +874,10 @@ function assetUrlVersionEdits(value,version){
             value:''
         });
     }
-    const lastRetained=parameters.findLast(function retainedParameter(parameter){
-        return !parameter.remove;
-    });
     if(!clean&&!versionFound)edits.push({
         start:address.length,
         end:address.length,
-        value:`${lastRetained&&lastRetained.end>lastRetained.start?'&':''}arcaneVersion=${versionValue}`
+        value:`&arcaneVersion=${versionValue}`
     });
     return edits;
 }

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,rootAppNavigation} from '../app-layout.mjs';
+import {appRelativeRoot,resolveAppRoot,rootAppLegacyPath,rootAppNavigation} from '../app-layout.mjs';
 import {readInstalledSdkLayout} from '../sdk-runtime-layout.mjs';
 import {withWorkspaceOperationLock} from '../workspace-operation-lock.mjs';
 import {
@@ -275,11 +275,14 @@ function validateSharedRoute(route,label){
 }
 
 export function validateRootConfig(value,configPath=ROOT_CONFIG_NAME){
-    assertOnlyKeys(value,new Set(['schemaVersion','appsRoot','distRoot','sharedPayloads']),ROOT_CONFIG_NAME);
+    assertOnlyKeys(value,new Set(['schemaVersion','appsRoot','distRoot','sharedPayloads','legacyAppPaths']),ROOT_CONFIG_NAME);
     if(value.schemaVersion!==1)fail(`${ROOT_CONFIG_NAME}.schemaVersion must be 1.`);
     if(!['apps','.'].includes(value.appsRoot)||value.distRoot!=='dist'){
         fail(`${ROOT_CONFIG_NAME} must bind appsRoot to "apps" or "." and distRoot to "dist".`);
     }
+    if (value.legacyAppPaths !== undefined && !is.boolean(value.legacyAppPaths)) {
+        fail(`${ROOT_CONFIG_NAME}.legacyAppPaths must be a boolean.`);
+    }
     if(!isPlainObject(value.sharedPayloads)){
         fail(`${ROOT_CONFIG_NAME}.sharedPayloads must be an object.`);
     }
@@ -293,7 +296,10 @@ export function validateRootConfig(value,configPath=ROOT_CONFIG_NAME){
             validateSharedRoute(route,`sharedPayloads.${id}[${index}]`)
         );
     }
-    return {schemaVersion:1,appsRoot:value.appsRoot,distRoot:'dist',sharedPayloads,configPath};
+    return {
+        schemaVersion:1,appsRoot:value.appsRoot,distRoot:'dist',sharedPayloads,configPath,
+        legacyAppPaths:value.legacyAppPaths ?? true
+    };
 }
 
 function normalizeOptionalRecord(value,label){
@@ -575,7 +581,7 @@ async function optionalDescriptor(context){
 async function inspectContext(context,{signal}={}){
     const records=await collectPackageRecords(context,{signal});
     const documents=await browserDocuments(records,context.config.entry);
-    const navigation=context.rootConfig.appsRoot==='.'?rootAppNavigation(
+    const navigation=rootAppLegacyPath(context.rootConfig,context.appId)?rootAppNavigation(
         context.appId,context.config.entry,documents.map(document=>document.path)
     ):[];
     for(const redirect of navigation){
@@ -757,11 +763,11 @@ async function replaceDirectory(stagingRoot,outputRoot){
 async function packageWithContext(context,options={}){
     const {signal,onEvent,browserPwa=true}=options;
     const pwaEnabled=browserPwa&&context.config.pwa?.enabled===true;
-    const legacyAppPath=context.rootConfig.appsRoot==='.'?`apps/${context.appId}`:undefined;
+    const legacyAppPath=rootAppLegacyPath(context.rootConfig,context.appId);
     const appPath=appRelativeRoot(context.rootConfig,context.appId);
     const entryPath=appPackagePath(context,context.config.entry);
     const inspected=await inspectContext(context,{signal});
-    const navigation=context.rootConfig.appsRoot==='.'?rootAppNavigation(
+    const navigation=legacyAppPath?rootAppNavigation(
         context.appId,context.config.entry,inspected.browserDocuments.map(document=>document.path)
     ):[];
     if(options.dryRun){

package/src/release-bundle.mjs

@@ -93,7 +93,7 @@ function splitUstarPath(archivePath){
             return {name,prefix};
         }
     }
-    fail(`Archive path cannot be represented by ustar: ${normalized}.`);
+    return null;
 }
 
 function writeTextField(header,offset,length,value,label){
@@ -112,8 +112,10 @@ function writeOctalField(header,offset,length,value,label,{trailingSpace=false}=
     header.write(rendered,offset,length,'ascii');
 }
 
-export function createCanonicalUstarHeader(archivePath,size){
-    const {name,prefix}=splitUstarPath(archivePath);
+function createTarHeader(archivePath,size,type){
+    const fields=splitUstarPath(archivePath);
+    if(!fields)fail(`Archive path cannot be represented by ustar: ${archivePath}.`);
+    const {name,prefix}=fields;
     const header=Buffer.alloc(TAR_BLOCK_SIZE);
     writeTextField(header,0,100,name,'ustar name');
     writeOctalField(header,100,8,ARCHIVE_MODE,'ustar mode');
@@ -122,7 +124,7 @@ export function createCanonicalUstarHeader(archivePath,size){
     writeOctalField(header,124,12,size,'ustar size');
     writeOctalField(header,136,12,0,'ustar mtime');
     header.fill(0x20,148,156);
-    header[156]=0x30;
+    header[156]=type;
     header.write('ustar\0',257,6,'ascii');
     header.write('00',263,2,'ascii');
     writeTextField(header,265,32,'root','ustar owner');
@@ -134,13 +136,45 @@ export function createCanonicalUstarHeader(archivePath,size){
     return header;
 }
 
-function tarEntry(archivePath,content){
-    const header=createCanonicalUstarHeader(archivePath,content.length);
+export function createCanonicalUstarHeader(archivePath,size){
+    return createTarHeader(archivePath,size,0x30);
+}
+
+function tarRecord(archivePath,content,type=0x30){
+    const header=createTarHeader(archivePath,content.length,type);
     const remainder=content.length%TAR_BLOCK_SIZE;
     const padding=remainder===0?Buffer.alloc(0):Buffer.alloc(TAR_BLOCK_SIZE-remainder);
     return Buffer.concat([header,content,padding]);
 }
 
+function paxPathRecord(archivePath) {
+    const value = Buffer.from(` path=${archivePath}\n`, 'utf8');
+    // POSIX PAX framing includes the decimal prefix itself in the record length.
+    let length = value.length + 1;
+    while(String(length).length + value.length !== length) {
+        length = String(length).length + value.length;
+    }
+    const prefix = Buffer.from(String(length), 'ascii');
+    return Buffer.concat(
+        [prefix, value]
+    );
+}
+
+function tarEntry(archivePath, content) {
+    const fields = splitUstarPath(archivePath);
+    if(fields && !/[^\u0000-\u007f]/u.test(archivePath)) {
+        return tarRecord(archivePath, content);
+    }
+    // The following regular header is only a placeholder; PAX owns the complete path.
+    const extendedPath = paxPathRecord(archivePath);
+    return Buffer.concat(
+        [
+            tarRecord('PaxHeaders/entry', extendedPath, 0x78),
+            tarRecord('PaxPayload/entry', content)
+        ]
+    );
+}
+
 async function realDirectory(location,label){
     const requested=path.resolve(location);
     let info;
@@ -308,9 +342,53 @@ function readOctalField(header,offset,length,label){
     return value;
 }
 
+function readPaxPath(content) {
+    let offset = 0;
+    let archivePath;
+    while(offset < content.length) {
+        const separator = content.indexOf(0x20, offset);
+        if(separator < 0) {
+            fail('Bundle contains malformed PAX record framing.');
+        }
+        const lengthText = content.subarray(offset, separator).toString('latin1');
+        if(!/^[1-9][0-9]*$/u.test(lengthText)) {
+            fail('Bundle contains malformed PAX record framing.');
+        }
+        const length = Number(lengthText);
+        const end = offset + length;
+        if(!is.safeInteger(length) || end > content.length || end <= separator + 1
+            || content[end - 1] !== 0x0a) {
+            fail('Bundle contains an incomplete or malformed PAX record.');
+        }
+        const assignment = content.indexOf(0x3d, separator + 1);
+        if(assignment <= separator + 1 || assignment >= end - 1) {
+            fail('Bundle contains a malformed PAX assignment.');
+        }
+        const keyword = content.subarray(separator + 1, assignment).toString('utf8');
+        if(keyword !== 'path') {
+            fail(`Bundle contains an unsupported PAX field: ${keyword}.`);
+        }
+        try {
+            const decoder = new TextDecoder(
+                'utf-8',
+                {fatal: true, ignoreBOM: true}
+            );
+            archivePath = decoder.decode(content.subarray(assignment + 1, end - 1));
+        } catch (error) {
+            fail(`Bundle PAX path is not valid UTF-8: ${error.message}.`);
+        }
+        offset = end;
+    }
+    if(archivePath === undefined) {
+        fail('Bundle PAX header is missing its path.');
+    }
+    return archivePath;
+}
+
 function readTarEntries(archive){
     const entries=new Map();
     let offset=0;
+    let pendingPath;
     while(offset+TAR_BLOCK_SIZE<=archive.length){
         const header=archive.subarray(offset,offset+TAR_BLOCK_SIZE);
         if(header.every(value=>value===0))break;
@@ -321,21 +399,31 @@ function readTarEntries(archive){
         let actualChecksum=0;
         for(const value of checksumHeader)actualChecksum+=value;
         if(actualChecksum!==expectedChecksum)fail('Bundle contains a malformed ustar header.');
-        if(header[156]!==0&&header[156]!==0x30)fail('Bundle contains a non-file archive entry.');
+        const type=header[156];
+        if(type!==0&&type!==0x30&&type!==0x78)fail('Bundle contains a non-file archive entry.');
         const name=readStringField(header,0,100);
         const prefix=readStringField(header,345,155);
-        const archivePath=validateAppBundlePath(prefix?`${prefix}/${name}`:name,'archive path');
-        if(entries.has(pathKey(archivePath)))fail(`Bundle contains a duplicate path: ${archivePath}.`);
+        const headerPath=prefix?`${prefix}/${name}`:name;
         const size=readOctalField(header,124,12,'ustar size');
         const contentStart=offset+TAR_BLOCK_SIZE;
         const contentEnd=contentStart+size;
-        if(contentEnd>archive.length)fail(`Bundle entry is incomplete: ${archivePath}.`);
+        if(contentEnd>archive.length)fail(`Bundle entry is incomplete: ${pendingPath??headerPath}.`);
+        const content=archive.subarray(contentStart,contentEnd);
+        offset=contentStart+Math.ceil(size/TAR_BLOCK_SIZE)*TAR_BLOCK_SIZE;
+        if(type===0x78){
+            if(pendingPath!==undefined)fail('Bundle PAX path is missing its following file.');
+            pendingPath=readPaxPath(content);
+            continue;
+        }
+        const archivePath=validateAppBundlePath(pendingPath??headerPath,'archive path');
+        pendingPath=undefined;
+        if(entries.has(pathKey(archivePath)))fail(`Bundle contains a duplicate path: ${archivePath}.`);
         entries.set(pathKey(archivePath),{
             path:archivePath,
-            content:Buffer.from(archive.subarray(contentStart,contentEnd))
+            content:Buffer.from(content)
         });
-        offset=contentStart+Math.ceil(size/TAR_BLOCK_SIZE)*TAR_BLOCK_SIZE;
     }
+    if(pendingPath!==undefined)fail('Bundle PAX path is missing its following file.');
     return entries;
 }
 

package/src/toolchain.mjs

@@ -12,7 +12,7 @@ import {
 import {loadArcaneIntegratedProvider} from './integrated-provider-loader.mjs';
 import {startDevServer} from './dev-server.mjs';
 import {applyPwaEntryReferences,generateImportMap,readApplicationTestImportMapContext} from './import-map.mjs';
-import {rootAppNavigation} from './app-layout.mjs';
+import {rootAppLegacyPath,rootAppNavigation} from './app-layout.mjs';
 import {createPwaArtifacts} from './pwa.mjs';
 import {readInstalledSdkLayout} from './sdk-runtime-layout.mjs';
 import {withWorkspaceOperationLock} from './workspace-operation-lock.mjs';
@@ -327,7 +327,16 @@ async function refreshPreparedImportMap(prepared,{signal,onEvent,workspaceOperat
 async function refreshRootApplicationFiles(prepared,inspected,importMap,{signal,onEvent}){
     const {workspaceRoot,appId}=prepared;
     const manifest=prepared.validation.app.manifest;
-    const navigation=rootAppNavigation(appId,manifest.entry,inspected.browserDocuments.map(document=>document.path));
+    const legacyAppPath = rootAppLegacyPath(prepared.validation.config, appId);
+    const navigation = legacyAppPath ? rootAppNavigation(
+        appId,
+        manifest.entry,
+        inspected.browserDocuments.map(
+            function rootBrowserDocumentPath(document) {
+                return document.path;
+            }
+        )
+    ) : [];
     // These aliases belong to the SDK only after generation; retained app files stay authored.
     for(const redirect of navigation){
         throwIfAborted(signal);
@@ -343,9 +352,17 @@ async function refreshRootApplicationFiles(prepared,inspected,importMap,{signal,
     const entry=`/${manifest.entry.split('/').map(encodeURIComponent).join('/')}`;
     const navigationAliases={
         '/':entry,
-        [`/apps/${appId}`]:entry,
-        [`/apps/${appId}/`]:entry,
-        ...Object.fromEntries(navigation.map(redirect=>[`/${redirect.path}`,redirect.target]))
+        ...(legacyAppPath ? {
+            [`/${legacyAppPath}`]:entry,
+            [`/${legacyAppPath}/`]:entry,
+            ...Object.fromEntries(
+                navigation.map(
+                    function rootNavigationAlias(redirect) {
+                        return [`/${redirect.path}`,redirect.target];
+                    }
+                )
+            )
+        } : {})
     };
     // The source host serves the installed files in place. There is no runtime projection.
     const files=[...new Set([
@@ -361,7 +378,7 @@ async function refreshRootApplicationFiles(prepared,inspected,importMap,{signal,
         basePath:'/',
         appBase:'/',
         installationId:`/apps/${appId}/`,
-        legacyAppPath:`apps/${appId}`,
+        legacyAppPath,
         runtimeBase:installed.browserRuntimeBase,
         mode:'development',
         navigationAliases