arcane-os 0.28.4 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

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/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

package/docs/reference/sdk-api.md

@@ -1041,6 +1041,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

package/package.json

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

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/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/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