@webstir-io/webstir-frontend 0.1.40 → 0.1.41

package/dist/modes/ssg/views.js

@@ -42,17 +42,17 @@ export async function generateSsgViewData(config) {
             try {
                 data = await spec.load(ssrContext);
             }
-            catch {
-                // Best-effort only; skip paths that fail to load.
-                continue;
+            catch (error) {
+                const viewLabel = viewName || viewPathTemplate || normalizedPath;
+                throw new Error(`[webstir-frontend] failed to load SSG view data for "${viewLabel}" at ${normalizedPath}: ${formatErrorMessage(error)}`);
             }
-            const pageName = normalizedPath === '/' ? FOLDERS.home : firstPathSegment(normalizedPath) ?? FOLDERS.home;
+            const pageName = normalizedPath === '/' ? FOLDERS.home : (firstPathSegment(normalizedPath) ?? FOLDERS.home);
             const entries = perPageData.get(pageName) ?? [];
             entries.push({
                 viewName: viewName || viewPathTemplate || normalizedPath,
                 path: normalizedPath,
                 // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-                data
+                data,
             });
             perPageData.set(pageName, entries);
         }
@@ -82,7 +82,7 @@ async function loadBackendModuleDefinition(workspaceRoot) {
         path.join(buildRoot, 'module.js'),
         path.join(buildRoot, 'module.mjs'),
         path.join(buildRoot, 'module', 'index.js'),
-        path.join(buildRoot, 'module', 'index.mjs')
+        path.join(buildRoot, 'module', 'index.mjs'),
     ];
     for (const fullPath of candidates) {
         if (!(await pathExists(fullPath))) {
@@ -96,8 +96,8 @@ async function loadBackendModuleDefinition(workspaceRoot) {
                 return candidate;
             }
         }
-        catch {
-            // Best-effort only.
+        catch (error) {
+            throw new Error(`[webstir-frontend] failed to import backend module definition from ${fullPath}: ${formatErrorMessage(error)}`);
         }
     }
     return undefined;
@@ -124,6 +124,12 @@ function normalizePath(value) {
     }
     return s;
 }
+function formatErrorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
 function firstPathSegment(pathname) {
     const [, segment] = pathname.split('/');
     if (!segment) {
@@ -172,7 +178,7 @@ function createMinimalSsrContext(pathname, params) {
         },
         entries() {
             return process.env;
-        }
+        },
     };
     const logger = {
         level: 'info',
@@ -193,7 +199,7 @@ function createMinimalSsrContext(pathname, params) {
         },
         with(_bindings) {
             return this;
-        }
+        },
     };
     return {
         url,
@@ -204,7 +210,7 @@ function createMinimalSsrContext(pathname, params) {
         session: null,
         env: envAccessor,
         logger,
-        now: () => new Date()
+        now: () => new Date(),
     };
 }
 function getEffectiveStaticPaths(meta, definition, isSsgWorkspace) {

package/dist/operations.js

@@ -2,7 +2,7 @@ import { readdir } from 'node:fs/promises';
 import { runPipeline } from './pipeline.js';
 import { createPageScaffold } from './html/pageScaffold.js';
 import { prepareWorkspaceConfig } from './config/setup.js';
-import { applySsgRouting, assertNoSsgRoutes, ensureSsgViewMetadataForPage, generateSsgViewData } from './modes/ssg/index.js';
+import { applySsgRouting, assertNoSsgRoutes, ensureSsgViewMetadataForPage, generateSsgViewData, } from './modes/ssg/index.js';
 import path from 'node:path';
 import { FOLDERS } from './core/constants.js';
 import { pathExists, readJson, remove } from './utils/fs.js';
@@ -10,7 +10,11 @@ export async function runBuild(options) {
     const config = await prepareWorkspaceConfig(options.workspaceRoot);
     const enable = await readWorkspaceEnableFlags(options.workspaceRoot);
     console.info('[webstir-frontend] Running build pipeline...');
-    await runPipeline(config, 'build', { changedFile: options.changedFile, enable });
+    await runPipeline(config, 'build', {
+        changedFile: options.changedFile,
+        enable,
+        env: process.env,
+    });
     console.info('[webstir-frontend] Build pipeline completed.');
 }
 export async function runPublish(options) {
@@ -22,7 +26,7 @@ export async function runPublish(options) {
     if (options.publishMode === 'ssg') {
         await assertNoSsgRoutes(config.paths.workspace);
     }
-    await runPipeline(publishConfig, 'publish', { enable });
+    await runPipeline(publishConfig, 'publish', { enable, env: process.env });
     if (options.publishMode === 'ssg') {
         await generateSsgViewData(publishConfig);
         await applySsgRouting(publishConfig);
@@ -34,7 +38,11 @@ export async function runRebuild(options) {
     const config = await prepareWorkspaceConfig(options.workspaceRoot);
     const enable = await readWorkspaceEnableFlags(options.workspaceRoot);
     console.info('[webstir-frontend] Running rebuild pipeline...');
-    await runPipeline(config, 'build', { changedFile: options.changedFile, enable });
+    await runPipeline(config, 'build', {
+        changedFile: options.changedFile,
+        enable,
+        env: process.env,
+    });
     console.info('[webstir-frontend] Rebuild pipeline completed.');
 }
 export async function runAddPage(options) {
@@ -48,13 +56,13 @@ export async function runAddPage(options) {
         mode: effectiveSsg ? 'ssg' : 'standard',
         paths: {
             pages: config.paths.src.pages,
-            app: config.paths.src.app
-        }
+            app: config.paths.src.app,
+        },
     });
     if (effectiveSsg) {
         await ensureSsgViewMetadataForPage({
             workspaceRoot: options.workspaceRoot,
-            pageName: options.pageName
+            pageName: options.pageName,
         });
     }
     console.info('[webstir-frontend] Page scaffold created.');
@@ -76,9 +84,9 @@ function applySsgPublishLayout(config) {
             dist: {
                 ...config.paths.dist,
                 pages: distPages,
-                content: distContent
-            }
-        }
+                content: distContent,
+            },
+        },
     };
 }
 async function readWorkspaceEnableFlags(workspaceRoot) {

package/dist/pipeline.d.ts

@@ -2,6 +2,7 @@ import type { EnableFlags, FrontendConfig } from './types.js';
 export interface PipelineOptions {
     readonly changedFile?: string;
     readonly enable?: EnableFlags;
+    readonly env?: Record<string, string | undefined>;
 }
 export type PipelineMode = 'build' | 'publish';
 export declare function runPipeline(config: FrontendConfig, mode: PipelineMode, options?: PipelineOptions): Promise<void>;

package/dist/pipeline.js

@@ -2,7 +2,12 @@ import { performance } from 'node:perf_hooks';
 import { createBuilders } from './builders/index.js';
 import { createHookContext, executeHooks, loadHooks } from './hooks.js';
 export async function runPipeline(config, mode, options = {}) {
-    const context = { config, changedFile: options.changedFile, enable: options.enable };
+    const context = {
+        config,
+        changedFile: options.changedFile,
+        enable: options.enable,
+        env: options.env,
+    };
     const builders = createBuilders(context);
     const hooks = await loadHooks(config.paths.workspace, mode === 'build');
     const pipelineContext = createHookContext(config, mode, options.changedFile);

package/dist/provider.js

@@ -2,11 +2,11 @@ import path from 'node:path';
 import { readdir } from 'node:fs/promises';
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
-import { glob } from 'glob';
 import { runPipeline } from './pipeline.js';
 import { prepareWorkspaceConfig } from './config/setup.js';
 import { FOLDERS } from './core/constants.js';
 import { pathExists, readJson, remove } from './utils/fs.js';
+import { scanGlob } from './utils/glob.js';
 import { applySsgRouting, assertNoSsgRoutes, generateSsgViewData } from './modes/ssg/index.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
@@ -14,7 +14,7 @@ function resolveWorkspacePaths(workspaceRoot) {
     return {
         sourceRoot: path.join(workspaceRoot, 'src', 'frontend'),
         buildRoot: path.join(workspaceRoot, 'build', 'frontend'),
-        testsRoot: path.join(workspaceRoot, 'src', 'frontend', 'tests')
+        testsRoot: path.join(workspaceRoot, 'src', 'frontend', 'tests'),
     };
 }
 async function buildModule(options) {
@@ -22,12 +22,20 @@ async function buildModule(options) {
     const mode = normalizeMode(options.env?.WEBSTIR_MODULE_MODE);
     const workspaceMode = await readWorkspaceMode(options.workspaceRoot);
     const frontendMode = normalizeFrontendMode(options.env?.WEBSTIR_FRONTEND_MODE);
-    const shouldRunSsgPublish = mode === 'publish' && (frontendMode === 'ssg' || (frontendMode === undefined && workspaceMode.mode === 'ssg'));
+    const shouldRunSsgPublish = mode === 'publish' &&
+        (frontendMode === 'ssg' || (frontendMode === undefined && workspaceMode.mode === 'ssg'));
     const publishConfig = shouldRunSsgPublish ? applySsgPublishLayout(config) : config;
     if (shouldRunSsgPublish) {
         await assertNoSsgRoutes(config.paths.workspace);
     }
-    await runPipeline(publishConfig, mode, { changedFile: undefined, enable: workspaceMode.enable });
+    await runPipeline(publishConfig, mode, {
+        changedFile: undefined,
+        enable: workspaceMode.enable,
+        env: {
+            ...process.env,
+            ...options.env,
+        },
+    });
     if (shouldRunSsgPublish) {
         await generateSsgViewData(publishConfig);
         await applySsgRouting(publishConfig);
@@ -37,7 +45,7 @@ async function buildModule(options) {
     const manifest = createManifest(config, artifacts, workspaceMode.mode, workspaceMode.isSsg);
     return {
         artifacts,
-        manifest
+        manifest,
     };
 }
 function applySsgPublishLayout(config) {
@@ -51,9 +59,9 @@ function applySsgPublishLayout(config) {
             dist: {
                 ...config.paths.dist,
                 pages: distPages,
-                content: distContent
-            }
-        }
+                content: distContent,
+            },
+        },
     };
 }
 async function removeLegacyPagesFolder(config) {
@@ -81,10 +89,9 @@ async function getScaffoldAssets() {
 }
 async function collectArtifacts(config) {
     const buildRoot = config.paths.build.frontend;
-    const matches = await glob('**/*', {
+    const matches = await scanGlob('**/*', {
         cwd: buildRoot,
-        nodir: true,
-        dot: false
+        dot: false,
     });
     return matches.map((relative) => {
         const absolutePath = path.join(buildRoot, relative);
@@ -92,7 +99,7 @@ async function collectArtifacts(config) {
         const artifactType = ext === '.js' || ext === '.mjs' ? 'bundle' : 'asset';
         return {
             path: absolutePath,
-            type: artifactType
+            type: artifactType,
         };
     });
 }
@@ -120,14 +127,14 @@ function createManifest(config, assets, workspaceMode, isSsgWorkspace) {
         else if (!isSsg) {
             diagnostics.push({
                 severity: 'warn',
-                message: 'No JavaScript entry points found under build/frontend.'
+                message: 'No JavaScript entry points found under build/frontend.',
             });
         }
     }
     return {
         entryPoints,
         staticAssets,
-        diagnostics
+        diagnostics,
     };
 }
 async function readWorkspaceMode(workspaceRoot) {
@@ -136,11 +143,11 @@ async function readWorkspaceMode(workspaceRoot) {
     const mode = pkg?.webstir?.mode;
     const normalizedMode = typeof mode === 'string' ? mode.toLowerCase() : undefined;
     const views = pkg?.webstir?.moduleManifest?.views;
-    const hasSsgView = Array.isArray(views) && views.some(view => view.renderMode?.toLowerCase() === 'ssg');
+    const hasSsgView = Array.isArray(views) && views.some((view) => view.renderMode?.toLowerCase() === 'ssg');
     return {
         mode,
         isSsg: normalizedMode === 'ssg' || hasSsgView,
-        enable: pkg?.webstir?.enable
+        enable: pkg?.webstir?.enable,
     };
 }
 function normalizeFrontendMode(value) {
@@ -148,11 +155,7 @@ function normalizeFrontendMode(value) {
         return undefined;
     }
     const normalized = value.trim().toLowerCase();
-    return normalized === 'ssg'
-        ? 'ssg'
-        : normalized === 'bundle'
-            ? 'bundle'
-            : undefined;
+    return normalized === 'ssg' ? 'ssg' : normalized === 'bundle' ? 'bundle' : undefined;
 }
 export const frontendProvider = {
     metadata: {
@@ -161,8 +164,9 @@ export const frontendProvider = {
         version: pkg.version ?? '0.0.0',
         compatibility: {
             minCliVersion: '0.1.0',
-            nodeRange: pkg.engines?.node ?? '>=20.18.1'
-        }
+            nodeRange: pkg.engines?.node ?? '>=20.18.1',
+            ...(pkg.engines?.bun ? { notes: `Requires Bun ${pkg.engines.bun} at runtime.` } : {}),
+        },
     },
     resolveWorkspace(options) {
         return resolveWorkspacePaths(options.workspaceRoot);
@@ -172,5 +176,5 @@ export const frontendProvider = {
     },
     async getScaffoldAssets() {
         return await getScaffoldAssets();
-    }
+    },
 };

package/dist/runtime/boundary.d.ts

@@ -0,0 +1,28 @@
+export type CleanupHandler = () => void | Promise<void>;
+export interface CleanupScope {
+    add(cleanup: CleanupHandler): void;
+    dispose(): Promise<void>;
+}
+export interface ManagedObserver {
+    disconnect(): void;
+}
+export interface BoundaryScope extends CleanupScope {
+    mountChild<TState>(boundary: Boundary<TState>, root: Element): Promise<Boundary<TState>>;
+}
+export interface BoundarySpec<TState = void> {
+    mount(root: Element, scope: BoundaryScope): TState | Promise<TState>;
+    unmount?(state: TState, scope: BoundaryScope): void | Promise<void>;
+    snapshotState?(state: TState): unknown | Promise<unknown>;
+    restoreState?(root: Element, scope: BoundaryScope, state: unknown): TState | Promise<TState>;
+}
+export interface Boundary<TState = void> {
+    mount(root: Element): Promise<TState>;
+    unmount(): Promise<void>;
+}
+export declare function createCleanupScope(): CleanupScope;
+export declare function listen(scope: CleanupScope, target: EventTarget, type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+export declare function scheduleTimeout(scope: CleanupScope, callback: TimerHandler, delay?: number, ...args: unknown[]): Parameters<typeof clearTimeout>[0];
+export declare function scheduleInterval(scope: CleanupScope, callback: TimerHandler, delay?: number, ...args: unknown[]): Parameters<typeof clearInterval>[0];
+export declare function trackObserver<TObserver extends ManagedObserver>(scope: CleanupScope, observer: TObserver): TObserver;
+export declare function createAbortController(scope: CleanupScope): AbortController;
+export declare function defineBoundary<TState = void>(spec: BoundarySpec<TState>): Boundary<TState>;

package/dist/runtime/boundary.js

@@ -0,0 +1,247 @@
+export function createCleanupScope() {
+    const cleanups = [];
+    let disposed = false;
+    let disposePromise = null;
+    return {
+        add(cleanup) {
+            if (disposed) {
+                throw new Error('Cleanup scope has already been disposed.');
+            }
+            cleanups.push(cleanup);
+        },
+        dispose() {
+            if (disposePromise) {
+                return disposePromise;
+            }
+            disposed = true;
+            disposePromise = (async () => {
+                let firstError;
+                for (let index = cleanups.length - 1; index >= 0; index -= 1) {
+                    const cleanup = cleanups[index];
+                    if (!cleanup) {
+                        continue;
+                    }
+                    try {
+                        await cleanup();
+                    }
+                    catch (error) {
+                        if (firstError === undefined) {
+                            firstError = error;
+                        }
+                    }
+                }
+                cleanups.length = 0;
+                if (firstError !== undefined) {
+                    throw firstError;
+                }
+            })();
+            return disposePromise;
+        },
+    };
+}
+export function listen(scope, target, type, listener, options) {
+    target.addEventListener(type, listener, options);
+    scope.add(() => {
+        target.removeEventListener(type, listener, options);
+    });
+}
+export function scheduleTimeout(scope, callback, delay = 0, ...args) {
+    const handle = setTimeout(callback, delay, ...args);
+    scope.add(() => {
+        clearTimeout(handle);
+    });
+    return handle;
+}
+export function scheduleInterval(scope, callback, delay = 0, ...args) {
+    const handle = setInterval(callback, delay, ...args);
+    scope.add(() => {
+        clearInterval(handle);
+    });
+    return handle;
+}
+export function trackObserver(scope, observer) {
+    scope.add(() => {
+        observer.disconnect();
+    });
+    return observer;
+}
+export function createAbortController(scope) {
+    const controller = new AbortController();
+    scope.add(() => {
+        controller.abort();
+    });
+    return controller;
+}
+function createBoundaryScope() {
+    const scope = createCleanupScope();
+    const children = new Set();
+    let disposed = false;
+    let disposeChildrenPromise = null;
+    return {
+        ...scope,
+        async mountChild(boundary, root) {
+            if (disposed) {
+                throw new Error('Boundary scope has already been disposed.');
+            }
+            await boundary.mount(root);
+            children.delete(boundary);
+            children.add(boundary);
+            return boundary;
+        },
+        async disposeChildren() {
+            if (disposeChildrenPromise) {
+                return disposeChildrenPromise;
+            }
+            disposed = true;
+            disposeChildrenPromise = (async () => {
+                let firstError;
+                const orderedChildren = Array.from(children);
+                for (let index = orderedChildren.length - 1; index >= 0; index -= 1) {
+                    const child = orderedChildren[index];
+                    if (!child) {
+                        continue;
+                    }
+                    try {
+                        await child.unmount();
+                    }
+                    catch (error) {
+                        if (firstError === undefined) {
+                            firstError = error;
+                        }
+                    }
+                }
+                children.clear();
+                if (firstError !== undefined) {
+                    throw firstError;
+                }
+            })();
+            return disposeChildrenPromise;
+        },
+    };
+}
+export function defineBoundary(spec) {
+    let currentRoot = null;
+    let currentScope = null;
+    let currentChildScope = null;
+    let currentState;
+    let pendingHotState;
+    let hasPendingHotState = false;
+    let mountPromise = null;
+    let unmountPromise = null;
+    const reset = (preserveHotState = false) => {
+        currentRoot = null;
+        currentScope = null;
+        currentChildScope = null;
+        currentState = undefined;
+        mountPromise = null;
+        unmountPromise = null;
+        if (!preserveHotState) {
+            pendingHotState = undefined;
+            hasPendingHotState = false;
+        }
+    };
+    return {
+        async mount(root) {
+            if (currentScope || mountPromise || unmountPromise) {
+                throw new Error('Boundary is already mounted.');
+            }
+            currentRoot = root;
+            currentChildScope = createBoundaryScope();
+            currentScope = currentChildScope;
+            const scope = currentScope;
+            const hotState = hasPendingHotState ? pendingHotState : undefined;
+            pendingHotState = undefined;
+            hasPendingHotState = false;
+            mountPromise = (async () => {
+                try {
+                    const state = hotState !== undefined && spec.restoreState
+                        ? await spec.restoreState(root, scope, hotState)
+                        : await spec.mount(root, scope);
+                    currentState = state;
+                    return state;
+                }
+                catch (error) {
+                    await currentChildScope?.disposeChildren().catch(() => undefined);
+                    await scope.dispose().catch(() => undefined);
+                    reset();
+                    throw error;
+                }
+            })();
+            return await mountPromise;
+        },
+        async unmount() {
+            if (!currentScope) {
+                return;
+            }
+            if (unmountPromise) {
+                return await unmountPromise;
+            }
+            const scope = currentScope;
+            const childScope = currentChildScope;
+            const state = currentState;
+            const mountTask = mountPromise;
+            const root = currentRoot;
+            unmountPromise = (async () => {
+                let firstError;
+                let capturedHotState;
+                let hasCapturedHotState = false;
+                if (mountTask) {
+                    try {
+                        await mountTask;
+                    }
+                    catch (error) {
+                        firstError = error;
+                    }
+                }
+                if (!firstError && spec.snapshotState) {
+                    try {
+                        capturedHotState = await spec.snapshotState(state);
+                        hasCapturedHotState = capturedHotState !== undefined;
+                    }
+                    catch (error) {
+                        firstError = error;
+                    }
+                }
+                if (childScope) {
+                    try {
+                        await childScope.disposeChildren();
+                    }
+                    catch (error) {
+                        if (firstError === undefined) {
+                            firstError = error;
+                        }
+                    }
+                }
+                if (!firstError && spec.unmount && root) {
+                    try {
+                        await spec.unmount(state, scope);
+                    }
+                    catch (error) {
+                        firstError = error;
+                    }
+                }
+                try {
+                    await scope.dispose();
+                }
+                catch (error) {
+                    if (firstError === undefined) {
+                        firstError = error;
+                    }
+                }
+                if (firstError === undefined && hasCapturedHotState) {
+                    pendingHotState = capturedHotState;
+                    hasPendingHotState = true;
+                }
+                else {
+                    pendingHotState = undefined;
+                    hasPendingHotState = false;
+                }
+                reset(hasCapturedHotState && firstError === undefined);
+                if (firstError !== undefined) {
+                    throw firstError;
+                }
+            })();
+            return await unmountPromise;
+        },
+    };
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1 @@
+export * from './boundary.js';

package/dist/runtime/index.js

@@ -0,0 +1 @@
+export * from './boundary.js';

package/dist/types.d.ts

@@ -52,6 +52,7 @@ export interface FrontendPathConfig {
 }
 export interface FrontendFeatureFlags {
     readonly htmlSecurity: boolean;
+    readonly externalResourceIntegrity: boolean;
     readonly imageOptimization: boolean;
     readonly precompression: boolean;
 }
@@ -59,3 +60,54 @@ export interface AddPageCommandOptions extends FrontendCommandOptions {
     readonly pageName: string;
     readonly ssg?: boolean;
 }
+export interface FrontendWorkspaceKnownEnableFlags {
+    readonly spa: boolean;
+    readonly clientNav: boolean;
+    readonly backend: boolean;
+    readonly search: boolean;
+    readonly contentNav: boolean;
+}
+export interface FrontendWorkspaceEnableFlagsInspect {
+    readonly raw?: Record<string, unknown>;
+    readonly known: FrontendWorkspaceKnownEnableFlags;
+}
+export interface FrontendWorkspacePackageInspect {
+    readonly path: string;
+    readonly exists: boolean;
+    readonly mode?: string;
+    readonly enable: FrontendWorkspaceEnableFlagsInspect;
+}
+export interface FrontendWorkspaceAppShellInspect {
+    readonly root: string;
+    readonly exists: boolean;
+    readonly templatePath: string;
+    readonly templateExists: boolean;
+    readonly stylesheetPath: string;
+    readonly stylesheetExists: boolean;
+    readonly scriptPath: string;
+    readonly scriptExists: boolean;
+}
+export interface FrontendWorkspacePageInspect {
+    readonly name: string;
+    readonly directory: string;
+    readonly htmlPath: string;
+    readonly htmlExists: boolean;
+    readonly stylesheetPath: string;
+    readonly stylesheetExists: boolean;
+    readonly scriptPath: string;
+    readonly scriptExists: boolean;
+}
+export interface FrontendWorkspaceContentInspect {
+    readonly root: string;
+    readonly exists: boolean;
+    readonly sidebarOverridePath: string;
+    readonly sidebarOverrideExists: boolean;
+}
+export interface FrontendWorkspaceInspectResult {
+    readonly workspaceRoot: string;
+    readonly config: FrontendConfig;
+    readonly packageJson: FrontendWorkspacePackageInspect;
+    readonly appShell: FrontendWorkspaceAppShellInspect;
+    readonly pages: readonly FrontendWorkspacePageInspect[];
+    readonly content: FrontendWorkspaceContentInspect;
+}