arcane-os 0.13.0 → 0.13.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.13.2
+
+- Correct the PWA development guide to describe live descriptor refresh and
+  remove the superseded restart instruction. Runtime behavior is unchanged.
+
+## 0.13.1
+
+- Refresh live development app membership from the current authored descriptor
+  or package-only configuration. New explicit includes, exclusions, entry paths,
+  and PWA settings take effect on the next relevant request without a server
+  restart or writes to consumer projections.
+- Generate PWA metadata and offline inventories from the same app snapshot.
+  Coalesce concurrent metadata reads and inventory work within that snapshot,
+  and keep older inventory completion from replacing newer metadata.
+
 ## 0.13.0
 
 - Add the reusable `pwa-install.html` component and shared browser installation

package/docs/architecture.md

@@ -116,6 +116,15 @@ development-refresh lock, then releases the lock before binding the listener.
 The authored descriptor remains unchanged, and package-only apps retain their
 existing path. An enabled PWA receives generated manifests directly from this
 source server without creating `dist` output.
+While serving, the SDK rereads changed metadata for the selected app before
+application, root-navigation, and generated-PWA requests. It projects the current
+authored descriptor in memory, or reads the current package configuration for a
+package-only app, without writing either file. Include/exclude rules, entry
+selection, and PWA settings share one request snapshot. Overlapping reads reuse
+one metadata task; unchanged files reuse their parsed selection. Shared runtime
+requests do not wait for that refresh. Full offline inventories are enumerated
+only for worker/offline-manifest requests, with separate state for each selected
+app snapshot so an older inventory cannot overwrite newer generated metadata.
 Changed resource requests return the complete current saved source without
 packaging, copying files into `dist`, or restarting the server. Conditional
 requests for unchanged resources return `304`. Enabled PWAs check on page load

package/docs/reference/pwa.md

@@ -102,8 +102,11 @@ metadata; `arcane-offline.json` contains the selected offline resource inventory
 If `package.pwa.offline.include` is nonempty, the resource must also
 match that offline selection and must not match `offline.exclude`. Adding a
 path only to the offline selection does not add it to the app's resources.
-Restart after changing descriptor settings. Edits to selected source files are
-picked up by the next due page-load check while the server remains running.
+The running source server reads changed app descriptors before the next app,
+root-navigation or generated-PWA request. Include/exclude rules, the entry and
+PWA settings share the current selection; no restart or package projection
+write is needed. Edits to selected source files are picked up by the next due
+page-load check while the server remains running.
 
 For an enabled application, `arcane dev` serves the generated PWA files at the
 origin root and starts at the selected app page under `/apps/<id>/`. Use one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "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

@@ -6,6 +6,8 @@ import https from 'node:https';
 import os from 'node:os';
 import path from 'node:path';
 import {resolveWorkspace} from './workspace.mjs';
+import {APP_DESCRIPTOR_NAME, projectPackageManifest} from './app-descriptor.mjs';
+import {APP_CONFIG_NAME, validateAppConfig} from './packager/core.mjs';
 import {createEventQueue} from './event-queue.mjs';
 import {
     applyPwaEntryReferences,inspectImportMapHtml,MANAGED_IMPORT_MAP_ATTRIBUTE,
@@ -324,13 +326,15 @@ async function openSafeFile(root, segments, {readContent = true} = {}) {
 async function serveGeneratedRepresentation(fileServer, request, response, {
     lastModified, contentType, body
 }) {
-    const modified = lastModified.toUTCString();
-    response.setHeader('Last-Modified', modified);
-    const requested = Date.parse(request.headers['if-modified-since']);
-    if (Number.isFinite(requested) && Date.parse(modified) <= requested) {
-        response.writeHead(304);
-        response.end();
-        return;
+    if (lastModified) {
+        const modified = lastModified.toUTCString();
+        response.setHeader('Last-Modified', modified);
+        const requested = Date.parse(request.headers['if-modified-since']);
+        if (Number.isFinite(requested) && Date.parse(modified) <= requested) {
+            response.writeHead(304);
+            response.end();
+            return;
+        }
     }
     response.setHeader('Content-Type', contentType);
     await fileServer.serve(request, response, await body());
@@ -459,6 +463,7 @@ async function sourceRoutes(workspaceRoot,appId,{
         return {
             workspaceRoot:resolved.workspaceRoot,
             workspaceMode:resolved.config.workspaceMode,
+            config:resolved.config,
             appId:resolved.appId,
             app:resolved.app.manifest,
             startPath:`/apps/${resolved.appId}/${resolved.app.manifest.entry}`,
@@ -470,6 +475,7 @@ async function sourceRoutes(workspaceRoot,appId,{
         return {
             workspaceRoot:resolved.workspaceRoot,
             workspaceMode:'integrated',
+            config:resolved.config,
             appId:resolved.appId,
             app:resolved.app.manifest,
             startPath:`/apps/${resolved.appId}/${resolved.app.manifest.entry}`,
@@ -488,6 +494,7 @@ async function sourceRoutes(workspaceRoot,appId,{
     return {
         workspaceRoot:resolved.workspaceRoot,
         workspaceMode:'external',
+        config:resolved.config,
         appId:resolved.appId,
         app:resolved.app.manifest,
         startPath:`/apps/${resolved.appId}/${resolved.app.manifest.entry}`,
@@ -840,7 +847,6 @@ async function startOwnedDevServer({
         })
         :await packagedRoutes(releaseRoot);
     const mappings=deterministicMappings(routeSet.mappings);
-    const pwaEnabled = mode === 'source' ? routeSet.app?.pwa?.enabled === true : routeSet.pwa;
     const versionPath = mode === 'source'
         ? sdkRuntimeSourceRoot === undefined
             ? path.join(routeSet.workspaceRoot, 'arcane.lock.json')
@@ -928,24 +934,89 @@ async function startOwnedDevServer({
         if(info.isSymbolicLink()||!info.isDirectory())fail(`Server route root must be a real directory: ${mapping.root}.`);
         mapping.root=await realpath(mapping.root);
     }
-    let pwaArtifacts;
-    let pwaInventoryTask;
-    const generatedMetadata = new Map();
+    let currentSourceRoutes = {...routeSet, mappings};
+    let sourceManifestInput;
+    let sourceManifestTask;
+    const appMapping = mappings.find(
+        function selectedApplicationMapping(mapping) {
+            return mapping.prefix[0] === 'apps' && mapping.prefix[1] === routeSet.appId;
+        }
+    );
+    async function refreshSourceRoutes() {
+        // Share concurrent metadata reads; unchanged descriptors need no parse
+        // or projection, and unrelated runtime requests do not wait here.
+        if (!sourceManifestTask) {
+            sourceManifestTask = readCurrentSourceRoutes().finally(
+                function releaseSourceManifestTask() {
+                    sourceManifestTask = null;
+                }
+            );
+        }
+        return sourceManifestTask;
+    }
+    async function readCurrentSourceRoutes() {
+        throwIfAborted(signal);
+        let manifestPath = path.join(appMapping.root, APP_DESCRIPTOR_NAME);
+        let authored = true;
+        let input;
+        try {
+            input = await lstat(manifestPath);
+        } catch (error) {
+            if (error.code !== 'ENOENT') throw error;
+            authored = false;
+            manifestPath = path.join(appMapping.root, APP_CONFIG_NAME);
+            input = await lstat(manifestPath);
+        }
+        if (sourceManifestInput?.path === manifestPath
+            && sourceManifestInput.modifiedAt === input.mtimeMs) {
+            return currentSourceRoutes;
+        }
+        const value = JSON.parse(await readFile(manifestPath, 'utf8'));
+        const manifest = validateAppConfig(
+            authored ? projectPackageManifest(value) : value,
+            routeSet.appId,
+            routeSet.config,
+            manifestPath
+        );
+        const currentAppMapping = {
+            ...appMapping,
+            include: manifest.include,
+            allow: function currentSourcePathAllowed(relative) {
+                return sourcePathAllowed(relative, manifest);
+            }
+        };
+        // Each request retains its own selection while an inventory or file read
+        // runs. HTTP reads never rewrite the consumer's authored projections.
+        currentSourceRoutes = {
+            ...routeSet,
+            app: manifest,
+            startPath: `/apps/${routeSet.appId}/${manifest.entry}`,
+            mappings: mappings.map(
+                function currentSourceMapping(mapping) {
+                    return mapping === appMapping ? currentAppMapping : mapping;
+                }
+            )
+        };
+        sourceManifestInput = {path: manifestPath, modifiedAt: input.mtimeMs};
+        return currentSourceRoutes;
+    }
+    const pwaStates = new WeakMap();
+    let currentPwaState;
     const pwaResourceUrls = new Set();
-    function developmentPwaArtifacts(assets = []) {
+    function developmentPwaArtifacts(selectedRoutes, assets = [], version = assetVersion) {
         return createPwaArtifacts(
             {
                 app: {
                     id: routeSet.appId,
-                    displayName: routeSet.app.displayName,
-                    version: routeSet.app.version,
-                    entry: routeSet.startPath
+                    displayName: selectedRoutes.app.displayName,
+                    version: selectedRoutes.app.version,
+                    entry: selectedRoutes.startPath
                 },
-                sdkVersion: assetVersion,
-                pwa: routeSet.app.pwa,
+                sdkVersion: version,
+                pwa: selectedRoutes.app.pwa,
                 files: [],
                 assets,
-                navigationAliases: {'/': routeSet.startPath},
+                navigationAliases: {'/': selectedRoutes.startPath},
                 basePath: '/',
                 appBase: `/apps/${routeSet.appId}/`,
                 runtimeBase: '/arcane/sdk/',
@@ -953,46 +1024,66 @@ async function startOwnedDevServer({
             }
         );
     }
-    function rememberPwaArtifacts(artifacts) {
+    function rememberPwaArtifacts(state, artifacts, generatedAt = new Date()) {
         for (const file of artifacts.files) {
-            const previous = generatedMetadata.get(file.path);
+            const previous = state.metadata.get(file.path);
             const lastModified = previous?.content === file.content
                 ? previous.lastModified
-                : new Date();
-            generatedMetadata.set(
+                : generatedAt;
+            state.metadata.set(
                 file.path,
                 {content: file.content, lastModified}
             );
         }
-        pwaArtifacts = artifacts;
+        state.artifacts = artifacts;
         return artifacts;
     }
-    async function sourcePwaArtifact(targetPath) {
+    async function sourcePwaArtifact(targetPath, selectedRoutes) {
+        let state = pwaStates.get(selectedRoutes);
+        if (!state) {
+            state = {metadata: new Map(currentPwaState?.metadata)};
+            pwaStates.set(selectedRoutes, state);
+            if (selectedRoutes === currentSourceRoutes) currentPwaState = state;
+        }
         if (targetPath === '/arcane-sw.js'
             || targetPath === '/arcane-offline.json') {
-            if (!pwaInventoryTask) {
-                pwaInventoryTask = Promise.all(
-                    [sourcePwaAssets(routeSet, mappings, signal, pwaResourceUrls, resourcePaths), selectedAssetVersion()]
+            if (!state.inventoryTask) {
+                // Timestamp selection before traversal, so an older snapshot
+                // finishing later cannot acquire a newer HTTP modification date.
+                const generatedAt = new Date();
+                state.inventoryTask = Promise.all(
+                    [
+                        sourcePwaAssets(selectedRoutes, selectedRoutes.mappings, signal, pwaResourceUrls, resourcePaths),
+                        selectedAssetVersion().then(
+                            function rememberCurrentInventoryVersion(version) {
+                                if (selectedRoutes === currentSourceRoutes) rememberAssetVersion(version);
+                                return version;
+                            }
+                        )
+                    ]
                 ).then(
                     function prepareSourceOfflineInventory([assets, version]) {
-                        rememberAssetVersion(version);
-                        return rememberPwaArtifacts(developmentPwaArtifacts(assets));
+                        return rememberPwaArtifacts(
+                            state,
+                            developmentPwaArtifacts(selectedRoutes, assets, version),
+                            generatedAt
+                        );
                     }
                 ).finally(
                     function releaseSourceInventoryTask() {
-                        pwaInventoryTask = null;
+                        state.inventoryTask = null;
                     }
                 );
             }
-            await pwaInventoryTask;
+            await state.inventoryTask;
         }
-        const artifacts = pwaArtifacts ?? rememberPwaArtifacts(developmentPwaArtifacts());
+        const artifacts = state.artifacts ?? rememberPwaArtifacts(state, developmentPwaArtifacts(selectedRoutes));
         const file = artifacts.files.find(
             function requestedPwaFile(file) {
                 return `/${file.path}` === targetPath;
             }
         );
-        return {...file, lastModified: generatedMetadata.get(file.path).lastModified};
+        return {...file, lastModified: state.metadata.get(file.path).lastModified};
     }
     // Remember actual resource edges as their owners are served, not every
     // HTML/JS/CSS file in an application's document or attachment corpus.
@@ -1018,16 +1109,24 @@ async function startOwnedDevServer({
             const target=parseRequestTarget(request.url);
             if(!target){deny(response,400,'Invalid request path.');return;}
             const {segments}=target;
+            const generatedPwaPath = ['/arcane.webmanifest', '/arcane-offline.json', '/arcane-sw.js', '/arcane-pwa.mjs']
+                .includes(target.path);
+            const appRequest = segments[0] === 'apps' && segments[1] === routeSet.appId;
+            const selectedRoutes = mode === 'source' && (appRequest || segments.length === 0 || generatedPwaPath)
+                ? await refreshSourceRoutes() : currentSourceRoutes;
+            const pwaEnabled = mode === 'source' ? selectedRoutes.app?.pwa?.enabled === true : routeSet.pwa;
             if (mode === 'source' && pwaEnabled
-                && ['/arcane.webmanifest', '/arcane-offline.json', '/arcane-sw.js', '/arcane-pwa.mjs'].includes(target.path)) {
-                const generated = await sourcePwaArtifact(target.path);
+                && generatedPwaPath) {
+                const generated = await sourcePwaArtifact(target.path, selectedRoutes);
                 response.setHeader('Cache-Control', 'no-cache');
                 await serveGeneratedRepresentation(
                     fileServer,
                     request,
                     response,
                     {
-                        lastModified: generated.lastModified,
+                        // An older in-flight snapshot may finish after a newer
+                        // selection. Its body cannot validate that newer output.
+                        lastModified: selectedRoutes === currentSourceRoutes ? generated.lastModified : undefined,
                         contentType: MIME_TYPES.get(path.extname(generated.path)),
                         body: function generatedPwaBody() {
                             return generated.content;
@@ -1037,12 +1136,18 @@ async function startOwnedDevServer({
                 return;
             }
             if(segments.length===0){
-                response.writeHead(302,{location:routeSet.startPath});
+                response.writeHead(302,{location:selectedRoutes.startPath});
                 response.end();
                 return;
             }
-            const mapping=mappings.find(route=>
-                route.prefix.every((segment,index)=>segments[index]===segment)
+            const mapping = selectedRoutes.mappings.find(
+                function requestedSourceMapping(route) {
+                    return route.prefix.every(
+                        function matchingSourcePrefix(segment, index) {
+                            return segments[index] === segment;
+                        }
+                    );
+                }
             );
             if(!mapping){deny(response,404,'Not found.');return;}
             const relative=segments.slice(mapping.prefix.length);
@@ -1064,8 +1169,8 @@ async function startOwnedDevServer({
                 const html=extension==='.html'||extension==='.htm';
                 const selectedPwaDocument = mode === 'source' && pwaEnabled && html
                     && mapping.prefix[0] === 'apps' && mapping.prefix[1] === routeSet.appId
-                    && routeSet.app.include.includes(relative.join('/'));
-                const selectedDocument = target.path === routeSet.startPath || selectedPwaDocument;
+                    && selectedRoutes.app.include.includes(relative.join('/'));
+                const selectedDocument = target.path === selectedRoutes.startPath || selectedPwaDocument;
                 const managedDocument = !selectedDocument && html && await isManagedDocument(opened);
                 const entryDocument = selectedDocument || managedDocument;
                 const managedMap=path.basename(opened.candidate)==='arcane.importmap.json';