@webstir-io/webstir-frontend 0.1.40 → 0.1.41

package/src/runtime/boundary.ts

@@ -0,0 +1,325 @@
+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 function createCleanupScope(): CleanupScope {
+  const cleanups: CleanupHandler[] = [];
+  let disposed = false;
+  let disposePromise: Promise<void> | null = null;
+
+  return {
+    add(cleanup: CleanupHandler): void {
+      if (disposed) {
+        throw new Error('Cleanup scope has already been disposed.');
+      }
+
+      cleanups.push(cleanup);
+    },
+    dispose(): Promise<void> {
+      if (disposePromise) {
+        return disposePromise;
+      }
+
+      disposed = true;
+      disposePromise = (async () => {
+        let firstError: unknown;
+
+        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: CleanupScope,
+  target: EventTarget,
+  type: string,
+  listener: EventListenerOrEventListenerObject,
+  options?: boolean | AddEventListenerOptions,
+): void {
+  target.addEventListener(type, listener, options);
+  scope.add(() => {
+    target.removeEventListener(type, listener, options);
+  });
+}
+
+export function scheduleTimeout(
+  scope: CleanupScope,
+  callback: TimerHandler,
+  delay = 0,
+  ...args: unknown[]
+): Parameters<typeof clearTimeout>[0] {
+  const handle = setTimeout(callback, delay, ...args) as Parameters<typeof clearTimeout>[0];
+  scope.add(() => {
+    clearTimeout(handle);
+  });
+  return handle;
+}
+
+export function scheduleInterval(
+  scope: CleanupScope,
+  callback: TimerHandler,
+  delay = 0,
+  ...args: unknown[]
+): Parameters<typeof clearInterval>[0] {
+  const handle = setInterval(callback, delay, ...args) as Parameters<typeof clearInterval>[0];
+  scope.add(() => {
+    clearInterval(handle);
+  });
+  return handle;
+}
+
+export function trackObserver<TObserver extends ManagedObserver>(
+  scope: CleanupScope,
+  observer: TObserver,
+): TObserver {
+  scope.add(() => {
+    observer.disconnect();
+  });
+  return observer;
+}
+
+export function createAbortController(scope: CleanupScope): AbortController {
+  const controller = new AbortController();
+  scope.add(() => {
+    controller.abort();
+  });
+  return controller;
+}
+
+function createBoundaryScope() {
+  const scope = createCleanupScope();
+  const children = new Set<Boundary<unknown>>();
+  let disposed = false;
+  let disposeChildrenPromise: Promise<void> | null = null;
+
+  return {
+    ...scope,
+    async mountChild<TState>(boundary: Boundary<TState>, root: Element): Promise<Boundary<TState>> {
+      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(): Promise<void> {
+      if (disposeChildrenPromise) {
+        return disposeChildrenPromise;
+      }
+
+      disposed = true;
+      disposeChildrenPromise = (async () => {
+        let firstError: unknown;
+
+        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<TState = void>(spec: BoundarySpec<TState>): Boundary<TState> {
+  let currentRoot: Element | null = null;
+  let currentScope: BoundaryScope | null = null;
+  let currentChildScope: ReturnType<typeof createBoundaryScope> | null = null;
+  let currentState: TState | undefined;
+  let pendingHotState: unknown;
+  let hasPendingHotState = false;
+  let mountPromise: Promise<TState> | null = null;
+  let unmountPromise: Promise<void> | null = null;
+
+  const reset = (preserveHotState = false): void => {
+    currentRoot = null;
+    currentScope = null;
+    currentChildScope = null;
+    currentState = undefined;
+    mountPromise = null;
+    unmountPromise = null;
+    if (!preserveHotState) {
+      pendingHotState = undefined;
+      hasPendingHotState = false;
+    }
+  };
+
+  return {
+    async mount(root: Element): Promise<TState> {
+      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(): Promise<void> {
+      if (!currentScope) {
+        return;
+      }
+
+      if (unmountPromise) {
+        return await unmountPromise;
+      }
+
+      const scope = currentScope;
+      const childScope = currentChildScope;
+      const state = currentState as TState;
+      const mountTask = mountPromise;
+      const root = currentRoot;
+
+      unmountPromise = (async () => {
+        let firstError: unknown;
+        let capturedHotState: unknown;
+        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/src/runtime/index.ts

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

package/src/types.ts

@@ -1,67 +1,126 @@
 export type FrontendPublishMode = 'bundle' | 'ssg';
 
 export interface FrontendCommandOptions {
-    readonly workspaceRoot: string;
-    readonly changedFile?: string;
-    readonly watch?: boolean;
-    readonly publishMode?: FrontendPublishMode;
+  readonly workspaceRoot: string;
+  readonly changedFile?: string;
+  readonly watch?: boolean;
+  readonly publishMode?: FrontendPublishMode;
 }
 
 export interface FrontendConfig {
-    readonly version: 1;
-    readonly paths: FrontendPathConfig;
-    readonly features: FrontendFeatureFlags;
+  readonly version: 1;
+  readonly paths: FrontendPathConfig;
+  readonly features: FrontendFeatureFlags;
 }
 
 export interface EnableFlags {
-    readonly spa?: boolean;
-    readonly clientNav?: boolean;
-    readonly backend?: boolean;
-    readonly search?: boolean;
-    readonly contentNav?: boolean;
+  readonly spa?: boolean;
+  readonly clientNav?: boolean;
+  readonly backend?: boolean;
+  readonly search?: boolean;
+  readonly contentNav?: boolean;
 }
 
 export interface FrontendPathConfig {
-    readonly workspace: string;
-    readonly src: {
-        readonly root: string;
-        readonly frontend: string;
-        readonly app: string;
-        readonly pages: string;
-        readonly content: string;
-        readonly images: string;
-        readonly fonts: string;
-        readonly media: string;
-    };
-    readonly build: {
-        readonly root: string;
-        readonly frontend: string;
-        readonly app: string;
-        readonly pages: string;
-        readonly content: string;
-        readonly images: string;
-        readonly fonts: string;
-        readonly media: string;
-    };
-    readonly dist: {
-        readonly root: string;
-        readonly frontend: string;
-        readonly app: string;
-        readonly pages: string;
-        readonly content: string;
-        readonly images: string;
-        readonly fonts: string;
-        readonly media: string;
-    };
+  readonly workspace: string;
+  readonly src: {
+    readonly root: string;
+    readonly frontend: string;
+    readonly app: string;
+    readonly pages: string;
+    readonly content: string;
+    readonly images: string;
+    readonly fonts: string;
+    readonly media: string;
+  };
+  readonly build: {
+    readonly root: string;
+    readonly frontend: string;
+    readonly app: string;
+    readonly pages: string;
+    readonly content: string;
+    readonly images: string;
+    readonly fonts: string;
+    readonly media: string;
+  };
+  readonly dist: {
+    readonly root: string;
+    readonly frontend: string;
+    readonly app: string;
+    readonly pages: string;
+    readonly content: string;
+    readonly images: string;
+    readonly fonts: string;
+    readonly media: string;
+  };
 }
 
 export interface FrontendFeatureFlags {
-    readonly htmlSecurity: boolean;
-    readonly imageOptimization: boolean;
-    readonly precompression: boolean;
+  readonly htmlSecurity: boolean;
+  readonly externalResourceIntegrity: boolean;
+  readonly imageOptimization: boolean;
+  readonly precompression: boolean;
 }
 
 export interface AddPageCommandOptions extends FrontendCommandOptions {
-    readonly pageName: string;
-    readonly ssg?: boolean;
+  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;
 }

package/src/utils/changedFile.ts

@@ -2,38 +2,38 @@ import path from 'node:path';
 import type { BuilderContext } from '../builders/types.js';
 
 interface Rule {
-    readonly directory: string;
-    readonly extensions?: readonly string[];
+  readonly directory: string;
+  readonly extensions?: readonly string[];
 }
 
 export function shouldProcess(context: BuilderContext, rules: readonly Rule[]): boolean {
-    const changed = context.changedFile;
-    if (!changed) {
-        return true;
-    }
+  const changed = context.changedFile;
+  if (!changed) {
+    return true;
+  }
 
-    const normalizedChanged = path.resolve(changed);
+  const normalizedChanged = path.resolve(changed);
 
-    for (const rule of rules) {
-        const normalizedDir = path.resolve(rule.directory);
-        if (!isPathInside(normalizedChanged, normalizedDir)) {
-            continue;
-        }
+  for (const rule of rules) {
+    const normalizedDir = path.resolve(rule.directory);
+    if (!isPathInside(normalizedChanged, normalizedDir)) {
+      continue;
+    }
 
-        if (!rule.extensions || rule.extensions.length === 0) {
-            return true;
-        }
+    if (!rule.extensions || rule.extensions.length === 0) {
+      return true;
+    }
 
-        const extension = path.extname(normalizedChanged).toLowerCase();
-        if (rule.extensions.includes(extension)) {
-            return true;
-        }
+    const extension = path.extname(normalizedChanged).toLowerCase();
+    if (rule.extensions.includes(extension)) {
+      return true;
     }
+  }
 
-    return false;
+  return false;
 }
 
 export function isPathInside(target: string, directory: string): boolean {
-    const relative = path.relative(directory, target);
-    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+  const relative = path.relative(directory, target);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }

package/src/utils/fs.ts

@@ -1,48 +1,95 @@
-import fs from 'fs-extra';
+import path from 'node:path';
+import type { Stats } from 'node:fs';
+import { lstat, mkdir, readdir, rm, stat as statFs } from 'node:fs/promises';
 
-export async function ensureDir(path: string): Promise<void> {
-    await fs.ensureDir(path);
+type BunFileLike = {
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+};
+
+interface BunLike {
+  file(path: string): BunFileLike;
+  write(path: string, data: string | ArrayBufferView | Blob | BunFileLike): Promise<number>;
+}
+
+function getBunRuntime(): BunLike {
+  const runtime = globalThis as typeof globalThis & { Bun?: BunLike };
+  if (typeof runtime.Bun?.file === 'function' && typeof runtime.Bun?.write === 'function') {
+    return runtime.Bun;
+  }
+
+  throw new Error('[webstir-frontend] Bun runtime is required for package-level IO.');
+}
+
+export async function ensureDir(targetPath: string): Promise<void> {
+  await mkdir(targetPath, { recursive: true });
 }
 
-export async function emptyDir(path: string): Promise<void> {
-    await fs.emptyDir(path);
+export async function emptyDir(targetPath: string): Promise<void> {
+  await rm(targetPath, { recursive: true, force: true });
+  await mkdir(targetPath, { recursive: true });
 }
 
-export async function remove(path: string): Promise<void> {
-    await fs.remove(path);
+export async function remove(targetPath: string): Promise<void> {
+  await rm(targetPath, { recursive: true, force: true });
 }
 
 export async function copy(source: string, destination: string): Promise<void> {
-    await fs.copy(source, destination, { overwrite: true, errorOnExist: false });
+  const sourceInfo = await lstat(source);
+
+  if (sourceInfo.isDirectory()) {
+    await ensureDir(destination);
+    const entries = await readdir(source, { withFileTypes: true });
+    await Promise.all(
+      entries.map((entry) =>
+        copy(path.join(source, entry.name), path.join(destination, entry.name)),
+      ),
+    );
+    return;
+  }
+
+  await ensureDir(path.dirname(destination));
+  const bun = getBunRuntime();
+  await bun.write(destination, bun.file(source));
 }
 
-export async function pathExists(path: string): Promise<boolean> {
-    return fs.pathExists(path);
+export async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await statFs(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
-export async function stat(path: string): Promise<fs.Stats> {
-    return fs.stat(path);
+export async function stat(targetPath: string): Promise<Stats> {
+  return await statFs(targetPath);
 }
 
-export async function readJson<T>(path: string): Promise<T | null> {
-    try {
-        return await fs.readJson(path);
-    } catch (error) {
-        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-            return null;
-        }
-        throw error;
+export async function readJson<T>(targetPath: string): Promise<T | null> {
+  try {
+    return JSON.parse(await readFile(targetPath)) as T;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
     }
+    throw error;
+  }
+}
+
+export async function writeJson(targetPath: string, data: unknown): Promise<void> {
+  await writeFile(targetPath, JSON.stringify(data, undefined, 2));
 }
 
-export async function writeJson(path: string, data: unknown): Promise<void> {
-    await fs.writeJson(path, data, { spaces: 2 });
+export async function readFile(targetPath: string): Promise<string> {
+  return await getBunRuntime().file(targetPath).text();
 }
 
-export async function readFile(path: string): Promise<string> {
-    return fs.readFile(path, 'utf8');
+export async function readBinaryFile(targetPath: string): Promise<Uint8Array> {
+  return new Uint8Array(await getBunRuntime().file(targetPath).arrayBuffer());
 }
 
-export async function writeFile(path: string, contents: string): Promise<void> {
-    await fs.outputFile(path, contents, 'utf8');
+export async function writeFile(targetPath: string, contents: string): Promise<void> {
+  await ensureDir(path.dirname(targetPath));
+  await getBunRuntime().write(targetPath, contents);
 }