arcane-os 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.20.0
+
+- Restore repository-shaped application packages: selected app files remain
+  under `apps/<id>/`, alongside shared `arcane/` and configured runtime routes.
+  Authored document bases, import maps, module-relative imports and application
+  resource paths retain their development layout without rewriting product
+  documents or application code to relocate them.
+- Restore deployment-relative `ARCANE_APP_RELEASE.app.start` and a root
+  `index.html` launcher while preserving the app-relative `app.entry` identity.
+  Package consumers use `app.start` for navigation. SDK packaged previews honor
+  that field and retain support for earlier flat packages through `app.entry`.
+- Keep generated PWA files at the deployment root, resolve manifest metadata
+  against the packaged app directory, and preserve app-relative offline
+  selections alongside shared runtime paths. Source import-map inspection keeps
+  app-relative document paths and separately reports emitted package paths.
+- Align packaging references with the current public return values and explicit
+  source import-map generation. Add package-layout and nested-deployment test
+  source while retaining complete authored-content coverage.
+
 ## 0.19.0
 
 - Read mail credentials from `.env.json` in the invocation directory through

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.19.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.20.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/architecture.md

@@ -199,9 +199,27 @@ URLs and release schema:
 apps/<id>/arcane-app.json
 apps/<id>/arcane-package.json
 apps/<id>/index.html
+dist/<id>/index.html
+dist/<id>/apps/<id>/index.html
 dist/<id>/ARCANE_APP_RELEASE.json
 ```
 
+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
+entry. Authored document bases, app URLs, relative module imports, and shared
+runtime paths therefore resolve through the same layout in
+source development and packaged delivery. Packaging consumes the saved source
+and managed import maps; use `arcane import-map` to refresh those maps, or the
+ordinary `arcane dev` startup that performs that refresh.
+
+The release manifest keeps `app.entry` relative to the app directory and records
+the package launch URL in `app.start`, such as
+`./apps/hello-world/index.html`. Its complete `files` inventory includes the
+root `index.html` and the prefixed app files. Packaged browser serving opens
+`app.start`; a previously generated flat release without `app.start` retains
+its `app.entry` launch path.
+
 The authored schema-2 descriptor is canonical for new apps and projects an
 exact schema-1 `arcane-package.json` for current consumers. Existing Arcane
 apps synthesize that descriptor from their schema-1 package plus the current

package/docs/reference/cli.md

@@ -195,8 +195,8 @@ Wrong or duplicate explicit app identity fails. The renderer then requires one
 path-correct base for every selected document. Included HTML files with neither
 the identity marker nor an active base are component fragments: they remain
 package files and are not rewritten with a document-level import map.
-Packaging and development use the same discovery owner, so directly navigable
-source pages and packaged pages receive the same complete managed import-map JSON.
+Packaging and development use the same discovery owner. Packaging consumes
+the saved managed import maps in directly navigable source pages.
 
 ```text
 arcane import-map [--workspace <directory>] [--app <id>]
@@ -254,19 +254,12 @@ together. A post-commit observer failure preserves delivery with
 `eventDelivery.status === 'degraded'` and `ARCANE_EVENT_DELIVERY_FAILED`; it
 does not roll back complete application content.
 
-An external package also publishes `/ARCANE_RUNTIME_PROJECTION.json`. The JSON
-is `{schemaVersion:1,kind:'arcane-app-runtime-projection',sdkVersion,
-pathPrefix:'arcane/',files:[{path}]}` and lists the complete packaged runtime.
-The development server exposes the same public route from its workspace
-projection. The private `/ARCANE_APP_RELEASE.json` record is not served to
-application code. Malformed projection data fails
-`ARCANE_RUNTIME_PROJECTION_INVALID`.
-
 `new` and `init` generate the map during scaffolding. `dev` refreshes all
-selected documents once before binding; non-dry-run `package` refreshes them
-once, then collects the complete release. Packaging does not run tests or
-checks automatically. Browser `build` and paired native packaging reuse the
-package flow. Explicit `test` and `check` operations read the existing map without regenerating it;
+selected documents once before binding. `package` consumes the saved source
+and maps; use `import-map` to refresh them explicitly before selecting output
+that needs updated maps. Packaging does not run tests or checks automatically.
+Browser `build` and paired native packaging reuse the package flow.
+Explicit `test` and `check` operations read the existing map without regenerating it;
 `verify`, `bundle`, and browser `run` do not regenerate it. There is no
 watcher, polling, scheduled refresh, download, or self-update behavior.
 
@@ -504,9 +497,12 @@ 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 refreshes the selected document
-map once, then assembles `dist`. Packaging does not run tests or checks
-automatically.
+output until the replacement is complete. It consumes saved source and managed
+import maps, places app files beneath `apps/<id>/`, and retains the configured
+shared route destinations. When selected shared content supplies no root
+`index.html`, the SDK generates one that opens the selected app entry.
+Source document bases and resource URLs therefore retain their development
+layout. Packaging does not run tests or checks automatically.
 
 ```text
 arcane package [--app <id>] [--dry-run]
@@ -515,6 +511,9 @@ arcane package [--app <id>] [--dry-run]
 ### Result
 
 The result includes the release root, manifest, and complete selected inventory.
+`ARCANE_APP_RELEASE.json` keeps the authored app-relative `app.entry` and records
+the package launch URL in `app.start`, such as `./apps/hello-world/index.html`.
+The file inventory includes that app tree and the root `index.html`.
 `--dry-run` plans the package without refreshing source, running tests, or
 replacing output.
 
@@ -672,6 +671,8 @@ npm exec -- arcane build \
 
 For `--target browser`, starts the existing current `dist/<app>` release; 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.
 The preview always uses HTTPS with the workspace certificate pair. Supply
 `--cert <file> --key <file>` together to use another pair; see
 [development HTTPS setup](#development-https-setup).

package/docs/reference/pwa.md

@@ -39,13 +39,20 @@ display preference, routes and descriptions. Use real app icons; the SDK does
 not invent branding or claim that a browser has installed the app.
 
 Manifest URL fields are relative to the application directory. Source delivery
-and packaged delivery resolve those fields into their respective layouts.
-Absolute URL fields retain their authored destination.
+and packaged delivery retain the app tree at `apps/<id>/`. For packaged output,
+the default `start_url` is `./apps/<id>/<entry>`, resolved from the generated
+root manifest. The default `id` and `scope` remain `./`, preserving the existing
+deployment-root installation identity. Authored relative URL fields, including
+explicit `id` and `scope` values, resolve against `./apps/<id>/`; an icon such
+as `img/library.png` therefore remains beneath the app directory. Absolute URL
+fields retain their authored destination.
 
 `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
 paths and shared runtime files use paths such as `arcane/sdk/pwa.mjs`.
+For example, selecting `modules` matches packaged
+`apps/<id>/modules/...`; emitted offline URLs keep the `apps/<id>/` prefix.
 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.
@@ -67,6 +74,13 @@ Browser packaging emits these files at the selected deployment root:
 | `arcane-sw.js` | Stable worker URL with the selected offline manifest embedded in its source. |
 | `arcane-pwa.mjs` | Independent registration and installation-component bootstrap importing the SDK client. |
 
+The selected app files remain under `apps/<id>/`, with shared runtime routes
+alongside them. The SDK supplies a root `index.html` launcher when selected
+shared content has no root page. The generated PWA files stay at the deployment
+root so their worker can serve the selected app and shared resources. The
+worker is registered for the deployment root independently of any app-authored
+manifest scope.
+
 Each packaged output gets one deployment revision shared by its offline
 manifest and worker. It distinguishes separately generated outputs even when
 their app and SDK versions match. It is not a content measurement.

package/docs/reference/sdk-api.md

@@ -719,6 +719,12 @@ matching `meta[name="arcane-app-id"]`; unmarked pages with an active `base`
 remain selected for patch compatibility. Included HTML with neither signal is
 retained as a package fragment rather than rewritten as a document.
 
+`entry` and each app browser document's `path` stay relative to the app
+directory. Each browser document also reports `packagePath`, the emitted path
+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.
+
 ### Availability and normalization
 
 **Node.** Normalized SDK validation with complete canonical archive and release content. Deep protocol: [SDK packager and deterministic bundle contract](protocols.md).
@@ -772,27 +778,22 @@ when explicitly requested or when required for this selected release output.
 async packageApp(options)
 ```
 
-Import it from `arcane-os` or `arcane-os/packager`. Packaging refreshes the
-managed map once and preserves the complete selected source and browser
-document inventory. It rejects malformed configuration, descriptors,
-and the malformed selected release archive while preserving the previously
-selected output on failure. Each selected browser document receives the same
-deterministic map. The package root also contains the public
-`ARCANE_RUNTIME_PROJECTION.json` inventory:
-
-```javascript
-{
-  schemaVersion: 1,
-  kind: 'arcane-app-runtime-projection',
-  sdkVersion: '0.5.18',
-  pathPrefix: 'arcane/',
-  files: [{path}]
-}
-```
+Import it from `arcane-os` or `arcane-os/packager`. Packaging consumes the saved
+source and managed import maps. Refresh maps through `arcane import-map` or
+ordinary `arcane dev` startup before selecting output that needs updated maps.
+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 projection is an inventory, not an ordinary execution gate. Malformed or
-internally inconsistent selected projection data rejects with
-`ARCANE_RUNTIME_PROJECTION_INVALID`.
+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
+contains `outputRoot`, `manifest`, and the complete `files` inventory.
+`manifest.app.entry` stays app-relative, while `manifest.app.start`
+is the package launch URL, such as `./apps/hello-world/index.html`. Release
+schema `1`, kind `arcane-app-release`, and packager identity
+`arcane-app-packager-v1` remain unchanged. A dry run returns the planned output
+and file inventory without writing source or output.
 
 ### Availability and normalization
 
@@ -808,7 +809,7 @@ const packaged = await packageApp({
     appId: 'hello-world'
 });
 
-console.log(packaged.importMap.documentPaths);
+console.log(packaged.manifest.app.start, packaged.files);
 ```
 
 ## PACKAGER_VERSION
@@ -4038,17 +4039,19 @@ console.log(result.importMap.documentPaths, result.importMap.documentCount);
 ### Overview
 
 Runs the high-level package operation for one selected application. It reads
-the installed SDK/runtime selection, injects one deterministic
-managed import map into every directly navigable included `.html`/`.htm`
-browser document while preserving component fragments as package files, and
-then packages the complete selected content without automatically running tests
-or checks. Verification occurs only when explicitly requested or when required
-for the selected release output. A failure leaves the previously accepted
-distribution untouched. Success returns the low-level package result and
-complete import-map document inventory. External
-packages publish `ARCANE_RUNTIME_PROJECTION.json`; private
-`ARCANE_APP_RELEASE.json` remains an internal verification authority rather
-than an application route.
+the installed SDK/runtime selection and packages the saved source and managed
+import maps through `packageApp()`. Map generation remains the explicit
+`arcane import-map` operation and the ordinary `arcane dev` startup refresh.
+Selected app files retain their `apps/<id>/` paths alongside the shared routes
+and root launcher described by `packageApp()`.
+
+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
+workspace and app identity plus `release`, containing the low-level package
+result, manifest, and complete file inventory. `ARCANE_APP_RELEASE.json` records
+that inventory and the distinct app-relative `app.entry` and package-relative
+`app.start`; it remains package metadata rather than an application route.
 
 ### Signature and result
 
@@ -4072,7 +4075,7 @@ const result = await packageApplication({
     appId: 'hello-world'
 });
 
-console.log(result.release.importMap.documentPaths);
+console.log(result.release.manifest.app.start, result.release.files);
 ```
 
 ## planApplication()

package/package.json

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

package/src/dev-server.mjs

@@ -516,15 +516,19 @@ async function packagedRoutes(releaseRoot){
     const canonical=await canonicalRealDirectory(requested,'Packaged release root');
     let pwa = false;
     let startPath = '/index.html';
+    try {
+        const release = JSON.parse(
+            await readFile(path.join(canonical, 'ARCANE_APP_RELEASE.json'), 'utf8')
+        );
+        const start = release.app.start ?? release.app.entry;
+        const startUrl = new URL(start, 'http://arcane.invalid/');
+        startPath = `${startUrl.pathname}${startUrl.search}${startUrl.hash}`;
+    } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+    }
     try {
         const manifest = JSON.parse(await readFile(path.join(canonical, 'arcane-offline.json'), 'utf8'));
         pwa = manifest.schemaVersion === 1;
-        if (pwa) {
-            const release = JSON.parse(
-                await readFile(path.join(canonical, 'ARCANE_APP_RELEASE.json'), 'utf8')
-            );
-            startPath = `/${release.app.entry}`;
-        }
     } catch (error) {
         if (error.code !== 'ENOENT') throw error;
     }

package/src/packager/core.mjs

@@ -424,6 +424,15 @@ function destinationJoin(root,relative){
     return root==='.'?relative:`${root}/${relative}`;
 }
 
+function appPackagePath(context, relative) {
+    return `apps/${context.appId}/${relative}`;
+}
+
+function packageResourceUrl(relative) {
+    const segments = relative.split('/');
+    return `./${segments.map(encodeURIComponent).join('/')}`;
+}
+
 async function collectSelectedPath({
     sourceRoot,
     selected,
@@ -483,7 +492,7 @@ async function collectPackageRecords(context,{signal}={}){
         await collectSelectedPath({
             sourceRoot:context.appRoot,
             selected,
-            destination:selected,
+            destination:appPackagePath(context, selected),
             excludes:context.config.exclude,
             reject:isAppSourceForbidden,
             records,
@@ -512,23 +521,25 @@ async function collectPackageRecords(context,{signal}={}){
         }
     }
     records.sort((left,right)=>compareText(left.destination,right.destination));
-    if(!records.some(record=>pathKey(record.destination)===pathKey(context.config.entry))){
+    if(!records.some(record=>pathKey(record.destination)===pathKey(appPackagePath(context, context.config.entry)))){
         fail(`Package entry is missing from the selected files: ${context.config.entry}.`);
     }
     return records;
 }
 
-async function browserDocuments(records,entry){
+async function browserDocuments(records,entry,appPrefix){
     let entryDocument=null;
     const documents=[];
     for(const record of records){
         const extension=path.posix.extname(record.destination).toLocaleLowerCase('en-US');
         if(extension!=='.html'&&extension!=='.htm')continue;
+        const documentPath=record.destination.startsWith(appPrefix)
+            ?record.destination.slice(appPrefix.length):record.destination;
         const inspected=inspectImportMapHtml(await readFile(record.source,'utf8'),{
-            documentPath:record.destination
+            documentPath
         });
-        const document={path:record.destination,...copyJson(inspected)};
-        if(record.destination===entry){
+        const document={path:documentPath,packagePath:record.destination,...copyJson(inspected)};
+        if(record.destination===`${appPrefix}${entry}`){
             entryDocument=document;
         }else if(inspected.bases.length>0){
             documents.push(document);
@@ -567,8 +578,8 @@ async function inspectContext(context,{signal}={}){
         }),
         ...(context.config.adapter===undefined?{}:{adapter:context.config.adapter}),
         descriptor:await optionalDescriptor(context),
-        browserDocuments:await browserDocuments(records,context.config.entry),
-        files:records.map(record=>record.destination),
+        browserDocuments:await browserDocuments(records,context.config.entry,appPackagePath(context,'')),
+        files:[...new Set(['index.html',...records.map(record=>record.destination)])].sort(compareText),
         output:path.relative(context.workspaceRoot,context.outputRoot).split(path.sep).join('/')
     };
 }
@@ -611,6 +622,28 @@ async function copyRecords(records,stagingRoot,{signal,onEvent}={}){
     }
 }
 
+async function writePackageLauncher(context, stagingRoot) {
+    function escapeHtml(value) {
+        return value.replaceAll('&', '&').replaceAll('"', '"')
+            .replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+    }
+    const start = escapeHtml(packageResourceUrl(appPackagePath(context, context.config.entry)));
+    const title = escapeHtml(context.config.displayName);
+    const content = `<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=${start}">
+    <title>${title}</title>
+</head>
+<body>
+    <a href="${start}">Open ${title}</a>
+</body>
+</html>
+`;
+    await writeFile(path.join(stagingRoot, 'index.html'), content, 'utf8');
+}
+
 async function listOutputFiles(root,{signal}={}){
     const files=[];
     async function visit(directory,relativeRoot=''){
@@ -652,6 +685,7 @@ function releaseManifest(context,files,pwaArtifacts){
             displayName:context.config.displayName,
             version:context.config.version,
             entry:context.config.entry,
+            start:packageResourceUrl(appPackagePath(context, context.config.entry)),
             strategy:context.config.strategy,
             shared:[...context.config.shared],
             ...(pwaArtifacts?{pwa:{
@@ -695,6 +729,8 @@ 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 appPath=`apps/${context.appId}`;
+    const entryPath=appPackagePath(context,context.config.entry);
     const inspected=await inspectContext(context,{signal});
     if(options.dryRun){
         return {
@@ -724,7 +760,14 @@ async function packageWithContext(context,options={}){
     let promoted=false;
     try{
         const records=await collectPackageRecords(context,{signal});
-        const copyBase=()=>copyRecords(records,stagingRoot,{signal,onEvent});
+        async function copyBase() {
+            await copyRecords(records,stagingRoot,{signal,onEvent});
+            if (!records.some(function selectedRootIndex(record) {
+                return record.destination === 'index.html';
+            })) {
+                await writePackageLauncher(context, stagingRoot);
+            }
+        }
         const adapter=await loadAdapter(context);
         if(adapter){
             await adapter.buildArcanePackage({
@@ -745,21 +788,22 @@ async function packageWithContext(context,options={}){
         const assetVersion=await readWorkspaceAssetVersion(context.workspaceRoot);
         const version=pwaEnabled?null:assetVersion;
         const inventory=new Set(files);
-        const offlineInventory=pwaEnabled?new Set(selectPwaFiles(files,context.config.pwa)):null;
+        const offlineInventory=pwaEnabled?new Set(selectPwaFiles(files,context.config.pwa,appPath)):null;
         const offlineReferences=new Set();
-        const entryUrl=new URL(context.config.entry,'http://arcane.invalid/');
+        const entryUrl=new URL(packageResourceUrl(entryPath),'http://arcane.invalid/');
         const pwaDocumentSources=new Map();
         if(pwaEnabled){
-            const documentPaths=new Set([context.config.entry]);
+            const documentPaths=new Set([entryPath]);
             for(const selected of context.config.include){
-                if(/\.html?$/iu.test(selected)&&inventory.has(selected))documentPaths.add(selected);
+                const selectedPath=appPackagePath(context,selected);
+                if(/\.html?$/iu.test(selected)&&inventory.has(selectedPath))documentPaths.add(selectedPath);
             }
             for(const document of inspected.browserDocuments){
                 const appDocument=context.config.include.some(function includesAppDocument(selected){
                     return sameOrDescendant(document.path,selected);
                 });
-                if(appDocument&&document.managedMaps.length>0&&inventory.has(document.path)){
-                    documentPaths.add(document.path);
+                if(appDocument&&document.managedMaps.length>0&&inventory.has(document.packagePath)){
+                    documentPaths.add(document.packagePath);
                 }
             }
             await Promise.all(
@@ -777,13 +821,13 @@ async function packageWithContext(context,options={}){
                 )
             );
         }
-        const entryDocument=pwaEnabled?pwaDocumentSources.get(context.config.entry).inspected
+        const entryDocument=pwaEnabled?pwaDocumentSources.get(entryPath).inspected
             :inspected.browserDocuments.find(function matchingEntryDocument(document){
                 return document.path===context.config.entry;
             });
         const documentUrl=entryDocument?.bases[0]?.href
             ?new URL(entryDocument.bases[0].href,entryUrl):entryUrl;
-        const pending=[{file:context.config.entry,documentUrl}];
+        const pending=[{file:entryPath,documentUrl}];
         for(const file of files){
             if(/^arcane\/(?:modules|entities|components|css|sdk|dependencies)\//u.test(file)
                 &&/\.(?:m?js|html?|css)$/iu.test(file))pending.push({file,documentUrl});
@@ -792,15 +836,15 @@ async function packageWithContext(context,options={}){
             }
         }
         for(const document of inspected.browserDocuments){
-            if(document.managedMaps.length>0&&!pwaDocumentSources.has(document.path)){
-                const url=new URL(document.path,entryUrl.origin);
-                pending.push({file:document.path,documentUrl:document.bases[0]?.href
+            if(document.managedMaps.length>0&&!pwaDocumentSources.has(document.packagePath)){
+                const url=new URL(packageResourceUrl(document.packagePath),entryUrl.origin);
+                pending.push({file:document.packagePath,documentUrl:document.bases[0]?.href
                     ?new URL(document.bases[0].href,url):url});
             }
         }
         for(const [file,document] of pwaDocumentSources){
-            if(file===context.config.entry)continue;
-            const url=new URL(file,entryUrl.origin);
+            if(file===entryPath)continue;
+            const url=new URL(packageResourceUrl(file),entryUrl.origin);
             pending.push({file,documentUrl:document.inspected.bases[0]?.href
                 ?new URL(document.inspected.bases[0].href,url):url});
         }
@@ -832,7 +876,7 @@ async function packageWithContext(context,options={}){
                 if(!pwaEnabled&&!traversable)continue;
                 if(kind==='import'&&!/^(?:\.{1,2}\/|\/)/u.test(url))continue;
                 try{
-                    const ownerUrl=new URL(relative,entryUrl.origin);
+                    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;
@@ -854,7 +898,7 @@ async function packageWithContext(context,options={}){
         if(files.some(file=>pathKey(file)===pathKey(RELEASE_MANIFEST_NAME))){
             fail(`Package content must not author ${RELEASE_MANIFEST_NAME}.`);
         }
-        if(!files.some(file=>pathKey(file)===pathKey(context.config.entry))){
+        if(!files.some(file=>pathKey(file)===pathKey(entryPath))){
             fail(`Package output is missing its entry file: ${context.config.entry}.`);
         }
         const pwaArtifacts=pwaEnabled?createPwaArtifacts({
@@ -862,8 +906,9 @@ async function packageWithContext(context,options={}){
                 id:context.appId,
                 displayName:context.config.displayName,
                 version:context.config.version,
-                entry:context.config.entry
+                entry:packageResourceUrl(entryPath)
             },
+            appPath,
             sdkVersion:assetVersion,
             pwa:context.config.pwa,
             files,
@@ -878,7 +923,7 @@ async function packageWithContext(context,options={}){
                 files.push(artifact.path);
             }
             for(const [documentPath,document] of pwaDocumentSources){
-                const documentUrl=new URL(documentPath,entryUrl.origin);
+                const documentUrl=new URL(packageResourceUrl(documentPath),entryUrl.origin);
                 const outputBase=document.inspected.bases[0]?.href
                     ?new URL(document.inspected.bases[0].href,documentUrl):documentUrl;
                 const outputDirectory=new URL('./',outputBase).pathname;

package/src/pwa.mjs

@@ -72,17 +72,20 @@ function selectedPath(file, selection) {
     return file === selection || file.startsWith(prefix);
 }
 
-export function selectPwaFiles(files, pwa) {
+export function selectPwaFiles(files, pwa, appPath = '') {
     const config = normalizePwaConfig(pwa);
     const include = config?.offline.include ?? [];
     const exclude = config?.offline.exclude ?? [];
+    const appPrefix = appPath ? `${appPath}/` : '';
     return files.filter(
         function selectedOfflineFile(file) {
+            const relative = appPrefix && file.startsWith(appPrefix)
+                ? file.slice(appPrefix.length) : file;
             function includedPath(selection) {
-                return selectedPath(file, selection);
+                return selectedPath(relative, selection);
             }
             function excludedPath(selection) {
-                return selectedPath(file, selection);
+                return selectedPath(relative, selection);
             }
             return (include.length === 0 || include.some(includedPath))
                 && !exclude.some(excludedPath);
@@ -199,6 +202,7 @@ export function createPwaArtifacts(
         mode = 'release',
         runtimeBase = './arcane/sdk/',
         appBase,
+        appPath = '',
         navigationAliases,
         revision
     } = {}
@@ -209,20 +213,19 @@ export function createPwaArtifacts(
         throw new TypeError('PWA mode must be release or development.');
     }
     const entryUrl = new URL(app.entry, 'https://arcane.invalid/');
-    const applicationBase = appBase ?? (mode === 'development'
-        ? new URL('./', entryUrl).pathname : './');
-    const manifest = applicationManifest(
-        {
-            id: applicationBase,
-            name: app.displayName,
-            short_name: app.displayName,
-            start_url: app.entry,
-            scope: applicationBase,
-            display: 'standalone',
-            ...config.manifest
-        },
-        applicationBase
-    );
+    const applicationBase = appBase ?? (appPath ? `./${appPath}/`
+        : mode === 'development' ? new URL('./', entryUrl).pathname : './');
+    // Relocating app files must not change an existing installed app's default identity.
+    const installationBase = appBase ?? (mode === 'development' ? applicationBase : './');
+    const manifest = {
+        id: installationBase,
+        name: app.displayName,
+        short_name: app.displayName,
+        start_url: manifestUrl(app.entry, appPath ? basePath : applicationBase),
+        scope: installationBase,
+        display: 'standalone',
+        ...applicationManifest(config.manifest, applicationBase)
+    };
     const generatedAssets = [
         PWA_MANIFEST_NAME,
         PWA_OFFLINE_MANIFEST_NAME,
@@ -232,7 +235,7 @@ export function createPwaArtifacts(
             return resourceUrl(basePath, file);
         }
     );
-    const selectedFiles = selectPwaFiles(files, config);
+    const selectedFiles = selectPwaFiles(files, config, appPath);
     const selectedAssets = [
         ...selectedFiles.map(
             function packagedResource(file) {