@noego/wood 0.4.9 → 0.5.0

package/dist/frontend/frontend_surface.d.ts

@@ -0,0 +1,64 @@
+import { Navigation } from '../navigation/index.js';
+import { ViewDef } from '../types/views.js';
+import { PageCatalog } from './page_catalog.js';
+import { WorkRegistry, WorkFailure } from './work_registry.js';
+export { FrontendWorkError } from './work_registry.js';
+export { FrontendLifecycle } from './frontend_lifecycle.js';
+import { FrontendPage } from './frontend_page.js';
+import '../navigation/automation_introspection.js';
+
+interface FrontendOpenOptions {
+    /** Required production page identity (`window.page`, or unambiguous leaf). */
+    page: string;
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+}
+interface FrontendApplicationSurface {
+    open(options: FrontendOpenOptions): Promise<FrontendPage>;
+    current(): FrontendPage | null;
+    act(action: () => unknown | Promise<unknown>): Promise<void>;
+    settle(): Promise<void>;
+    readonly errors: readonly WorkFailure[];
+    /** The environment-local production Navigation instance. */
+    readonly navigation: Navigation;
+    /** Internal: dispose the active page and application lifecycles. */
+    dispose(): Promise<void>;
+}
+interface ScopeLike {
+    extend(): ScopeLike;
+    get(token: unknown): Promise<unknown>;
+    registerClass?(target: unknown, options?: unknown): void;
+    registerFunction?(token: unknown, factory: () => unknown, options?: unknown): void;
+    registerValue?(token: unknown, value: unknown): void;
+    dispose?(): Promise<void>;
+}
+interface PageScopeContext {
+    kind: 'page' | 'layout';
+    /** Layout index within the view's layout stack (layout scopes only). */
+    layoutIndex?: number;
+    /** Controller identity bound to this scope. */
+    controller: string;
+}
+interface CreateFrontendSurfaceOptions {
+    /** The selected renderer aperture. */
+    catalog: PageCatalog;
+    /** Fresh renderer root for this environment (separate from the main root). */
+    rendererRoot: ScopeLike;
+    registry: WorkRegistry;
+    /** Environment-local Navigation (also registered on the renderer root). */
+    navigation: Navigation;
+    /** Resolve a production controller identity to its class. */
+    resolveController: (identity: string, view: ViewDef) => Promise<new (...args: never[]) => unknown>;
+    /** Per-pass reactive flush hooks from the active runtime adapter (Node: none). */
+    flushHooks?: ReadonlyArray<() => void | Promise<void>>;
+    /**
+     * Register per-scope services on a newly created scope (bridge client,
+     * etc.). Called for the page scope, and once for each PRESERVED layout
+     * that owns a dedicated scope — `context.kind` says which, so a caller
+     * that tracks "the page scope" does not mistake a layout scope for it.
+     */
+    configurePageScope?: (scope: ScopeLike, view: ViewDef, context: PageScopeContext) => void | Promise<void>;
+}
+declare function createFrontendSurface(options: CreateFrontendSurfaceOptions): FrontendApplicationSurface;
+
+export { type CreateFrontendSurfaceOptions, type FrontendApplicationSurface, type FrontendOpenOptions, type PageScopeContext, createFrontendSurface };

package/dist/frontend/frontend_surface.js

@@ -0,0 +1,224 @@
+import { ExecutionContext, LoadAs } from "@noego/ioc";
+import { computePreservedLayoutDepth } from "../navigation/layout_preservation.js";
+import { disposeControllerLifecycle } from "../controller/controller_lifecycle.js";
+import { PageCatalogError, pageIdentity } from "./page_catalog.js";
+import { FrontendWorkError } from "./work_registry.js";
+import { FrontendLifecycleOwner } from "./frontend_lifecycle.js";
+import { createFrontendPage } from "./frontend_page.js";
+function registerControllerUnlessBound(scope, ControllerClass) {
+  const registrable = scope;
+  if (typeof registrable.isRegistered === "function" && registrable.isRegistered(ControllerClass)) return;
+  if (typeof scope.registerClass === "function") scope.registerClass(ControllerClass);
+}
+function guardControllerLifecycleOnce(instance) {
+  if (!instance || typeof instance !== "object") return;
+  const target = instance;
+  for (const hook of ["dispose", "destroy"]) {
+    const original = target[hook];
+    if (typeof original !== "function") continue;
+    if (Object.prototype.hasOwnProperty.call(target, hook)) continue;
+    let called = false;
+    Object.defineProperty(target, hook, {
+      configurable: true,
+      writable: true,
+      enumerable: false,
+      value: function guarded(...args) {
+        if (called) return void 0;
+        called = true;
+        return original.apply(this, args);
+      }
+    });
+  }
+}
+function createFrontendSurface(options) {
+  const { catalog, rendererRoot, registry, navigation } = options;
+  const flushHooks = options.flushHooks ?? [];
+  const application = new FrontendLifecycleOwner(registry, "application");
+  let active = null;
+  let transitioning = false;
+  let disposed = false;
+  const currentOwner = () => active ? `page ${active.identity}` : "application";
+  async function constructPage(view, params, query, preserved = []) {
+    const identity = pageIdentity(view);
+    if (!view.controller) {
+      throw new PageCatalogError(
+        `page "${identity}" declares no controller in its view definition; the Node application slice drives public PageController input and needs one.`
+      );
+    }
+    const ControllerClass = await options.resolveController(view.controller, view);
+    const scope = rendererRoot.extend();
+    const lifecycle = new FrontendLifecycleOwner(registry, `page ${identity}`);
+    scope.registerFunction?.(FrontendLifecycleOwner, () => lifecycle, { loadAs: LoadAs.Scoped });
+    await options.configurePageScope?.(scope, view, {
+      kind: "page",
+      controller: view.controller
+    });
+    registerControllerUnlessBound(scope, ControllerClass);
+    const layouts = [...preserved];
+    for (let index = preserved.length; index < view.layouts.length; index += 1) {
+      const layoutIdentity = view.layoutControllers?.[index];
+      if (!layoutIdentity) continue;
+      const preserve = view.layoutPreserve?.[index] === true;
+      const LayoutClass = await options.resolveController(layoutIdentity, view);
+      const ownScope = preserve ? rendererRoot.extend() : null;
+      const ownLifecycle = ownScope ? new FrontendLifecycleOwner(registry, `layout ${layoutIdentity}`) : null;
+      const layoutScope = ownScope ?? scope;
+      if (ownScope) {
+        ownScope.registerFunction?.(FrontendLifecycleOwner, () => ownLifecycle, { loadAs: LoadAs.Scoped });
+        await options.configurePageScope?.(ownScope, view, {
+          kind: "layout",
+          layoutIndex: index,
+          controller: layoutIdentity
+        });
+      }
+      registerControllerUnlessBound(layoutScope, LayoutClass);
+      const instance = await ExecutionContext.run(
+        layoutScope,
+        () => layoutScope.get(LayoutClass)
+      );
+      guardControllerLifecycleOnce(instance);
+      layouts.push({
+        index,
+        path: view.layouts[index],
+        controller: layoutIdentity,
+        preserve,
+        instance,
+        scope: layoutScope,
+        ownScope,
+        ownLifecycle
+      });
+    }
+    const controller = await ExecutionContext.run(
+      scope,
+      () => scope.get(ControllerClass)
+    );
+    guardControllerLifecycleOnce(controller);
+    if (typeof controller.initialize === "function") {
+      await registry.track(
+        Promise.resolve(
+          ExecutionContext.run(
+            scope,
+            () => controller.initialize({ params, query })
+          )
+        ).then(() => void 0),
+        { label: `initialize ${identity}`, kind: "initialize", owner: `page ${identity}` }
+      );
+    }
+    const handle = createFrontendPage({
+      identity,
+      controller,
+      scope,
+      layouts,
+      onClose: async () => {
+        await disposePage(identity);
+      }
+    });
+    return { identity, view, scope, lifecycle, handle, controller, layouts };
+  }
+  async function endPage(page, preservedDepth = 0) {
+    page.handle.invalidate();
+    await disposeControllerLifecycle(page.controller);
+    for (const layout of page.layouts) {
+      if (layout.index < preservedDepth) continue;
+      await disposeControllerLifecycle(layout.instance);
+    }
+    await page.lifecycle.dispose();
+    if (typeof page.scope.dispose === "function") {
+      await page.scope.dispose();
+    }
+    for (const layout of page.layouts) {
+      if (layout.index < preservedDepth) continue;
+      await layout.ownLifecycle?.dispose();
+      if (layout.ownScope && typeof layout.ownScope.dispose === "function") {
+        await layout.ownScope.dispose();
+      }
+    }
+  }
+  async function disposePage(identity) {
+    if (!active || active.identity !== identity) return;
+    const ended = active;
+    active = null;
+    await endPage(ended);
+  }
+  async function transitionTo(entry) {
+    const view = catalog.resolve(entry.page);
+    const previous = active;
+    const depth = previous ? computePreservedLayoutDepth(
+      { layoutPaths: previous.view.layouts, layoutControllers: previous.view.layoutControllers, layoutPreserve: previous.view.layoutPreserve },
+      { layoutPaths: view.layouts, layoutControllers: view.layoutControllers, layoutPreserve: view.layoutPreserve },
+      entry.options ?? {}
+    ) : 0;
+    const carried = previous ? previous.layouts.filter((layout) => layout.index < depth) : [];
+    const next = await constructPage(view, entry.params, entry.query, carried);
+    active = next;
+    if (previous) {
+      await endPage(previous, depth);
+    }
+  }
+  navigation.subscribe((entry) => {
+    if (!entry || transitioning || disposed) return;
+    if (active && entry.page === active.identity) return;
+    if (!active) return;
+    registry.track(transitionTo(entry), {
+      label: `navigate ${active.identity} -> ${entry.page}`,
+      kind: "navigation",
+      owner: currentOwner()
+    });
+  });
+  return {
+    navigation,
+    async open(openOptions) {
+      if (!openOptions || typeof openOptions.page !== "string" || !openOptions.page.length) {
+        throw new PageCatalogError("frontend.open() requires an explicit { page } identity");
+      }
+      if (active) {
+        throw new PageCatalogError(
+          `frontend.open() is test bootstrap; page "${active.identity}" is already open. Drive production navigation for subsequent route changes, or close() the page first.`
+        );
+      }
+      const view = catalog.resolve(openOptions.page);
+      const params = openOptions.params ?? {};
+      const query = openOptions.query ?? {};
+      transitioning = true;
+      try {
+        navigation.replace(pageIdentity(view), params, query);
+        active = await constructPage(view, params, query);
+      } finally {
+        transitioning = false;
+      }
+      return active.handle.page;
+    },
+    current() {
+      return active ? active.handle.page : null;
+    },
+    async act(action) {
+      await registry.track(
+        Promise.resolve().then(() => action()).then(() => void 0),
+        { label: "act()", kind: "tracked", owner: currentOwner() }
+      ).catch(() => {
+      });
+      await registry.drain(flushHooks);
+    },
+    async settle() {
+      await registry.drain(flushHooks);
+    },
+    get errors() {
+      return registry.errors();
+    },
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      if (active) {
+        const ended = active;
+        active = null;
+        await endPage(ended);
+      }
+      await application.dispose();
+    }
+  };
+}
+export {
+  FrontendWorkError,
+  createFrontendSurface
+};
+//# sourceMappingURL=frontend_surface.js.map

package/dist/frontend/frontend_surface.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/frontend/frontend_surface.ts"],"sourcesContent":["/**\n * The Node frontend application surface (spec 18 §12–13, 18A D-FAS-01/02).\n *\n *   frontend.open({ page, params, query })  — explicit initial page\n *   frontend.current()                      — production navigation result\n *   frontend.act(fn) / frontend.settle()    — owned-work fixed-point drains\n *   frontend.errors                         — observed owned-work failures\n *\n * Runtime honesty (D-FAS-02): this is the plain-Node tier. It proves\n * explicit PageController behavior, $state/$derived reachable through it,\n * backend calls, events, and navigation identity/lifecycle. It does not\n * create a Svelte component/root context and therefore proves no $effect,\n * mount/unmount, or DOM behavior — those belong to the happy-dom tier.\n *\n * Isolation: every environment owns its own Navigation instance, renderer\n * root, transport, and work registry. Nothing here writes globalThis and\n * nothing calls the production client getters — two environments run\n * concurrently without cross-talk. A controller that calls the module-level\n * `go()`/`getNavigation()` free functions bypasses its environment; this\n * tier requires constructor-injected `Navigation`.\n */\nimport { ExecutionContext, LoadAs } from '@noego/ioc';\nimport { Navigation, type NavigationEntry } from '../navigation/index.js';\nimport { computePreservedLayoutDepth } from '../navigation/layout_preservation.js';\nimport { disposeControllerLifecycle } from '../controller/controller_lifecycle.js';\nimport type { ViewDef } from '../types/index.js';\nimport { PageCatalog, PageCatalogError, pageIdentity } from './page_catalog.js';\nimport { WorkRegistry, FrontendWorkError, type WorkFailure } from './work_registry.js';\nimport { FrontendLifecycleOwner, type FrontendLifecycle } from './frontend_lifecycle.js';\nimport { createFrontendPage, type FrontendPage, type FrontendPageHandle, type MountedLayout } from './frontend_page.js';\n\nexport interface FrontendOpenOptions {\n  /** Required production page identity (`window.page`, or unambiguous leaf). */\n  page: string;\n  params?: Record<string, string>;\n  query?: Record<string, string>;\n}\n\nexport interface FrontendApplicationSurface {\n  open(options: FrontendOpenOptions): Promise<FrontendPage>;\n  current(): FrontendPage | null;\n  act(action: () => unknown | Promise<unknown>): Promise<void>;\n  settle(): Promise<void>;\n  readonly errors: readonly WorkFailure[];\n  /** The environment-local production Navigation instance. */\n  readonly navigation: Navigation;\n  /** Internal: dispose the active page and application lifecycles. */\n  dispose(): Promise<void>;\n}\n\ninterface ScopeLike {\n  extend(): ScopeLike;\n  get(token: unknown): Promise<unknown>;\n  registerClass?(target: unknown, options?: unknown): void;\n  registerFunction?(token: unknown, factory: () => unknown, options?: unknown): void;\n  registerValue?(token: unknown, value: unknown): void;\n  dispose?(): Promise<void>;\n}\n\n/**\n * A mounted layout controller and the scope that owns it. A layout declared\n * `preserve: true` owns a DEDICATED scope that survives page transitions\n * (production parity: `createControllerSet`); every other layout shares the\n * page scope and dies with the page.\n */\ninterface ActiveLayout extends MountedLayout {\n  index: number;\n  /** Non-null only for a preserved layout that owns its scope. */\n  ownScope: ScopeLike | null;\n  /**\n   * A preserved layout outlives the page that built it, so it cannot borrow\n   * that page's lifecycle owner — it owns one, disposed when the layout is\n   * finally dropped.\n   */\n  ownLifecycle: FrontendLifecycleOwner | null;\n}\n\ninterface ActivePage {\n  identity: string;\n  view: ViewDef;\n  scope: ScopeLike;\n  lifecycle: FrontendLifecycleOwner;\n  handle: FrontendPageHandle;\n  controller: unknown;\n  layouts: ActiveLayout[];\n}\n\nexport interface PageScopeContext {\n  kind: 'page' | 'layout';\n  /** Layout index within the view's layout stack (layout scopes only). */\n  layoutIndex?: number;\n  /** Controller identity bound to this scope. */\n  controller: string;\n}\n\nexport interface CreateFrontendSurfaceOptions {\n  /** The selected renderer aperture. */\n  catalog: PageCatalog;\n  /** Fresh renderer root for this environment (separate from the main root). */\n  rendererRoot: ScopeLike;\n  registry: WorkRegistry;\n  /** Environment-local Navigation (also registered on the renderer root). */\n  navigation: Navigation;\n  /** Resolve a production controller identity to its class. */\n  resolveController: (identity: string, view: ViewDef) => Promise<new (...args: never[]) => unknown>;\n  /** Per-pass reactive flush hooks from the active runtime adapter (Node: none). */\n  flushHooks?: ReadonlyArray<() => void | Promise<void>>;\n  /**\n   * Register per-scope services on a newly created scope (bridge client,\n   * etc.). Called for the page scope, and once for each PRESERVED layout\n   * that owns a dedicated scope — `context.kind` says which, so a caller\n   * that tracks \"the page scope\" does not mistake a layout scope for it.\n   */\n  configurePageScope?: (\n    scope: ScopeLike,\n    view: ViewDef,\n    context: PageScopeContext,\n  ) => void | Promise<void>;\n}\n\n/**\n * Plain (undecorated) controller classes are registered on their scope so\n * they resolve — unless the hierarchy already decided how the token resolves\n * (a renderer-root substitution of the controller class), which keeps\n * winning inside the page scope.\n */\nfunction registerControllerUnlessBound(scope: ScopeLike, ControllerClass: unknown): void {\n  const registrable = scope as { isRegistered?(token: unknown): boolean };\n  if (typeof registrable.isRegistered === 'function' && registrable.isRegistered(ControllerClass)) return;\n  if (typeof scope.registerClass === 'function') scope.registerClass(ControllerClass);\n}\n\n/**\n * Make a controller's production teardown hook run at most once.\n *\n * Two owners legitimately end a controller: this surface (production\n * parity — the renderer's NavigationShell calls the hook explicitly, and\n * for a Transient controller that is the ONLY call) and IoC scope\n * disposal (which calls `dispose()`/`destroy()` on the scoped instances it\n * owns). Shadowing the hook with a once-guard means a controller sees the\n * same single teardown whichever way it was registered.\n */\nfunction guardControllerLifecycleOnce(instance: unknown): void {\n  if (!instance || typeof instance !== 'object') return;\n  const target = instance as Record<string, unknown>;\n  for (const hook of ['dispose', 'destroy'] as const) {\n    const original = target[hook];\n    if (typeof original !== 'function') continue;\n    if (Object.prototype.hasOwnProperty.call(target, hook)) continue;\n    let called = false;\n    Object.defineProperty(target, hook, {\n      configurable: true,\n      writable: true,\n      enumerable: false,\n      value: function guarded(this: unknown, ...args: unknown[]) {\n        if (called) return undefined;\n        called = true;\n        return (original as (...rest: unknown[]) => unknown).apply(this, args);\n      },\n    });\n  }\n}\n\nexport function createFrontendSurface(options: CreateFrontendSurfaceOptions): FrontendApplicationSurface {\n  const { catalog, rendererRoot, registry, navigation } = options;\n  const flushHooks = options.flushHooks ?? [];\n  const application = new FrontendLifecycleOwner(registry, 'application');\n\n  let active: ActivePage | null = null;\n  let transitioning = false;\n  let disposed = false;\n\n  const currentOwner = (): string => (active ? `page ${active.identity}` : 'application');\n\n  async function constructPage(\n    view: ViewDef,\n    params: Record<string, string>,\n    query: Record<string, string>,\n    preserved: ActiveLayout[] = [],\n  ): Promise<ActivePage> {\n    const identity = pageIdentity(view);\n    if (!view.controller) {\n      throw new PageCatalogError(\n        `page \"${identity}\" declares no controller in its view definition; ` +\n        'the Node application slice drives public PageController input and needs one.',\n      );\n    }\n\n    const ControllerClass = await options.resolveController(view.controller, view);\n    const scope = rendererRoot.extend();\n    const lifecycle = new FrontendLifecycleOwner(registry, `page ${identity}`);\n\n    // The page lifecycle is injectable so controllers can register\n    // deliberately detached finite work (D-FAS-01 §2.2). Scoped, not\n    // Singleton: the lifecycle belongs to this page scope alone — a\n    // Singleton would store at the hierarchy root and leak the first\n    // page's lifecycle into every later page.\n    scope.registerFunction?.(FrontendLifecycleOwner, () => lifecycle, { loadAs: LoadAs.Scoped });\n    await options.configurePageScope?.(scope, view, {\n      kind: 'page',\n      controller: view.controller,\n    });\n    registerControllerUnlessBound(scope, ControllerClass);\n\n    // Layout controllers mount BEFORE the view controller (production\n    // ordering in `createControllerSet`): a page controller may legitimately\n    // read state a layout controller published during construction.\n    const layouts: ActiveLayout[] = [...preserved];\n    for (let index = preserved.length; index < view.layouts.length; index += 1) {\n      const layoutIdentity = view.layoutControllers?.[index];\n      if (!layoutIdentity) continue;\n      const preserve = view.layoutPreserve?.[index] === true;\n      const LayoutClass = await options.resolveController(layoutIdentity, view);\n      const ownScope = preserve ? rendererRoot.extend() : null;\n      const ownLifecycle = ownScope\n        ? new FrontendLifecycleOwner(registry, `layout ${layoutIdentity}`)\n        : null;\n      const layoutScope = ownScope ?? scope;\n      if (ownScope) {\n        ownScope.registerFunction?.(FrontendLifecycleOwner, () => ownLifecycle!, { loadAs: LoadAs.Scoped });\n        await options.configurePageScope?.(ownScope, view, {\n          kind: 'layout',\n          layoutIndex: index,\n          controller: layoutIdentity,\n        });\n      }\n      registerControllerUnlessBound(layoutScope, LayoutClass);\n      const instance = (await ExecutionContext.run(layoutScope as never, () =>\n        layoutScope.get(LayoutClass),\n      )) as Record<string, unknown>;\n      guardControllerLifecycleOnce(instance);\n      layouts.push({\n        index,\n        path: view.layouts[index],\n        controller: layoutIdentity,\n        preserve,\n        instance,\n        scope: layoutScope,\n        ownScope,\n        ownLifecycle,\n      });\n    }\n\n    const controller = (await ExecutionContext.run(scope as never, () =>\n      scope.get(ControllerClass),\n    )) as Record<string, unknown>;\n\n    guardControllerLifecycleOnce(controller);\n\n    if (typeof controller.initialize === 'function') {\n      await registry.track(\n        Promise.resolve(\n          ExecutionContext.run(scope as never, () =>\n            (controller.initialize as (load: unknown) => unknown)({ params, query }),\n          ),\n        ).then(() => undefined),\n        { label: `initialize ${identity}`, kind: 'initialize', owner: `page ${identity}` },\n      );\n    }\n\n    const handle = createFrontendPage({\n      identity,\n      controller,\n      scope,\n      layouts,\n      onClose: async () => {\n        await disposePage(identity);\n      },\n    });\n\n    return { identity, view, scope, lifecycle, handle, controller, layouts };\n  }\n\n  /**\n   * End a page: the page lifecycle owner first (abort signal, owned\n   * resources), then the IoC scopes — scope disposal is what runs each\n   * controller's production `dispose()`/`destroy()` hook, so nothing here\n   * calls those directly. Layouts in the preserved prefix keep running:\n   * they belong to the next page now.\n   */\n  async function endPage(page: ActivePage, preservedDepth = 0): Promise<void> {\n    page.handle.invalidate();\n    // Production teardown order (NavigationShell.disposeControllerSet): the\n    // page controller's hook, then each ending layout's, then the lifecycle\n    // owner and the IoC scopes. The hooks are once-guarded, so the scope\n    // disposal below does not run them a second time.\n    await disposeControllerLifecycle(page.controller);\n    for (const layout of page.layouts) {\n      if (layout.index < preservedDepth) continue;\n      await disposeControllerLifecycle(layout.instance);\n    }\n    await page.lifecycle.dispose();\n    // Page scope first, then dropped preserved layouts — production's\n    // disposeControllerSet order (view controller, then layouts).\n    if (typeof page.scope.dispose === 'function') {\n      await page.scope.dispose();\n    }\n    for (const layout of page.layouts) {\n      if (layout.index < preservedDepth) continue;\n      await layout.ownLifecycle?.dispose();\n      if (layout.ownScope && typeof layout.ownScope.dispose === 'function') {\n        await layout.ownScope.dispose();\n      }\n    }\n  }\n\n  async function disposePage(identity: string): Promise<void> {\n    if (!active || active.identity !== identity) return;\n    const ended = active;\n    active = null;\n    await endPage(ended);\n  }\n\n  async function transitionTo(entry: NavigationEntry): Promise<void> {\n    // Resolve the destination through the selected aperture — navigation\n    // outside it fails without widening the environment.\n    const view = catalog.resolve(entry.page);\n    const previous = active;\n    // Preserved layouts carry over as live instances — the transition never\n    // reconstructs them (production `preserve: true` semantics).\n    // Same preservation rule the renderer's NavigationShell applies.\n    const depth = previous\n      ? computePreservedLayoutDepth(\n          { layoutPaths: previous.view.layouts, layoutControllers: previous.view.layoutControllers, layoutPreserve: previous.view.layoutPreserve },\n          { layoutPaths: view.layouts, layoutControllers: view.layoutControllers, layoutPreserve: view.layoutPreserve },\n          entry.options ?? {},\n        )\n      : 0;\n    const carried = previous ? previous.layouts.filter((layout) => layout.index < depth) : [];\n    const next = await constructPage(view, entry.params, entry.query, carried);\n    active = next;\n    if (previous) {\n      await endPage(previous, depth);\n    }\n  }\n\n  // Production navigation drives page transitions: a controller calling its\n  // injected Navigation.go()/replace() inside the aperture triggers one\n  // tracked finite navigation transition (18A D-FAS-01 §2.2).\n  navigation.subscribe((entry) => {\n    if (!entry || transitioning || disposed) return;\n    if (active && entry.page === active.identity) return;\n    if (!active) return; // initial open() seeds navigation itself\n    registry.track(transitionTo(entry), {\n      label: `navigate ${active.identity} -> ${entry.page}`,\n      kind: 'navigation',\n      owner: currentOwner(),\n    });\n  });\n\n  return {\n    navigation,\n\n    async open(openOptions: FrontendOpenOptions): Promise<FrontendPage> {\n      if (!openOptions || typeof openOptions.page !== 'string' || !openOptions.page.length) {\n        throw new PageCatalogError('frontend.open() requires an explicit { page } identity');\n      }\n      if (active) {\n        throw new PageCatalogError(\n          `frontend.open() is test bootstrap; page \"${active.identity}\" is already open. ` +\n          'Drive production navigation for subsequent route changes, or close() the page first.',\n        );\n      }\n      const view = catalog.resolve(openOptions.page);\n      const params = openOptions.params ?? {};\n      const query = openOptions.query ?? {};\n\n      transitioning = true;\n      try {\n        // Seed production navigation state BEFORE construction: controllers\n        // and their services legitimately read the current route (params,\n        // query) during construction/initialize, exactly as in production\n        // where the route exists before the page loads.\n        navigation.replace(pageIdentity(view), params, query);\n        active = await constructPage(view, params, query);\n      } finally {\n        transitioning = false;\n      }\n      return active.handle.page;\n    },\n\n    current(): FrontendPage | null {\n      return active ? active.handle.page : null;\n    },\n\n    async act(action: () => unknown | Promise<unknown>): Promise<void> {\n      await registry.track(\n        Promise.resolve().then(() => action()).then(() => undefined),\n        { label: 'act()', kind: 'tracked', owner: currentOwner() },\n      ).catch(() => {\n        // The failure is recorded by the registry; drain reports it with\n        // its owner rather than losing the aggregate view.\n      });\n      await registry.drain(flushHooks);\n    },\n\n    async settle(): Promise<void> {\n      await registry.drain(flushHooks);\n    },\n\n    get errors(): readonly WorkFailure[] {\n      return registry.errors();\n    },\n\n    async dispose(): Promise<void> {\n      if (disposed) return;\n      disposed = true;\n      if (active) {\n        const ended = active;\n        active = null;\n        // Environment teardown ends everything, preserved layouts included.\n        await endPage(ended);\n      }\n      await application.dispose();\n    },\n  };\n}\n\nexport type { FrontendLifecycle };\nexport { FrontendWorkError };\n"],"mappings":"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","names":[]}

package/dist/frontend/index.cjs

@@ -0,0 +1,52 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var frontend_exports = {};
+__export(frontend_exports, {
+  FrontendLifecycleOwner: () => import_frontend_lifecycle.FrontendLifecycleOwner,
+  FrontendWorkError: () => import_work_registry.FrontendWorkError,
+  PageCatalog: () => import_page_catalog.PageCatalog,
+  PageCatalogError: () => import_page_catalog.PageCatalogError,
+  TrackedTransport: () => import_tracked_transport.TrackedTransport,
+  WorkRegistry: () => import_work_registry.WorkRegistry,
+  createFrontendPage: () => import_frontend_page.createFrontendPage,
+  createFrontendSurface: () => import_frontend_surface.createFrontendSurface,
+  pageIdentity: () => import_page_catalog.pageIdentity,
+  parseViewsSource: () => import_page_catalog.parseViewsSource
+});
+module.exports = __toCommonJS(frontend_exports);
+var import_work_registry = require("./work_registry.cjs");
+var import_frontend_lifecycle = require("./frontend_lifecycle.cjs");
+var import_page_catalog = require("./page_catalog.cjs");
+var import_tracked_transport = require("./tracked_transport.cjs");
+var import_frontend_page = require("./frontend_page.cjs");
+var import_frontend_surface = require("./frontend_surface.cjs");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FrontendLifecycleOwner,
+  FrontendWorkError,
+  PageCatalog,
+  PageCatalogError,
+  TrackedTransport,
+  WorkRegistry,
+  createFrontendPage,
+  createFrontendSurface,
+  pageIdentity,
+  parseViewsSource
+});
+//# sourceMappingURL=index.cjs.map

package/dist/frontend/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/frontend/index.ts"],"sourcesContent":["/**\n * Frontend application slice (spec 18 / 18A) — plain-Node tier.\n *\n * NOTE: keep re-exports single-line — the tsup extension-rewrite plugin\n * only rewrites single-line import/export specifiers.\n */\nexport { WorkRegistry, FrontendWorkError } from './work_registry.cjs';\nexport type { WorkDescriptor, WorkFailure, WorkKind, WorkOptions } from './work_registry.cjs';\nexport { FrontendLifecycleOwner } from './frontend_lifecycle.cjs';\nexport type { FrontendLifecycle } from './frontend_lifecycle.cjs';\nexport { PageCatalog, PageCatalogError, pageIdentity, parseViewsSource } from './page_catalog.cjs';\nexport type { RendererSelection, ViewsSource } from './page_catalog.cjs';\nexport { TrackedTransport } from './tracked_transport.cjs';\nexport { createFrontendPage } from './frontend_page.cjs';\nexport type { FrontendPage, FrontendPageHandle, FrontendLayout, MountedLayout } from './frontend_page.cjs';\nexport { createFrontendSurface } from './frontend_surface.cjs';\nexport type { FrontendApplicationSurface, FrontendOpenOptions, CreateFrontendSurfaceOptions, PageScopeContext } from './frontend_surface.cjs';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,2BAAgD;AAEhD,gCAAuC;AAEvC,0BAA8E;AAE9E,+BAAiC;AACjC,2BAAmC;AAEnC,8BAAsC;","names":[]}

package/dist/frontend/index.d.cts

@@ -0,0 +1,10 @@
+export { FrontendWorkError, WorkDescriptor, WorkFailure, WorkKind, WorkOptions, WorkRegistry } from './work_registry.cjs';
+export { FrontendLifecycle, FrontendLifecycleOwner } from './frontend_lifecycle.cjs';
+export { PageCatalog, PageCatalogError, RendererSelection, ViewsSource, pageIdentity, parseViewsSource } from './page_catalog.cjs';
+export { TrackedTransport } from './tracked_transport.cjs';
+export { FrontendLayout, FrontendPage, FrontendPageHandle, MountedLayout, createFrontendPage } from './frontend_page.cjs';
+export { CreateFrontendSurfaceOptions, FrontendApplicationSurface, FrontendOpenOptions, PageScopeContext, createFrontendSurface } from './frontend_surface.cjs';
+import '../types/views.cjs';
+import '../transport/wood_rpc_transport.cjs';
+import '../navigation/index.cjs';
+import '../navigation/automation_introspection.cjs';

package/dist/frontend/index.d.ts

@@ -0,0 +1,10 @@
+export { FrontendWorkError, WorkDescriptor, WorkFailure, WorkKind, WorkOptions, WorkRegistry } from './work_registry.js';
+export { FrontendLifecycle, FrontendLifecycleOwner } from './frontend_lifecycle.js';
+export { PageCatalog, PageCatalogError, RendererSelection, ViewsSource, pageIdentity, parseViewsSource } from './page_catalog.js';
+export { TrackedTransport } from './tracked_transport.js';
+export { FrontendLayout, FrontendPage, FrontendPageHandle, MountedLayout, createFrontendPage } from './frontend_page.js';
+export { CreateFrontendSurfaceOptions, FrontendApplicationSurface, FrontendOpenOptions, PageScopeContext, createFrontendSurface } from './frontend_surface.js';
+import '../types/views.js';
+import '../transport/wood_rpc_transport.js';
+import '../navigation/index.js';
+import '../navigation/automation_introspection.js';

package/dist/frontend/index.js

@@ -0,0 +1,19 @@
+import { WorkRegistry, FrontendWorkError } from "./work_registry.js";
+import { FrontendLifecycleOwner } from "./frontend_lifecycle.js";
+import { PageCatalog, PageCatalogError, pageIdentity, parseViewsSource } from "./page_catalog.js";
+import { TrackedTransport } from "./tracked_transport.js";
+import { createFrontendPage } from "./frontend_page.js";
+import { createFrontendSurface } from "./frontend_surface.js";
+export {
+  FrontendLifecycleOwner,
+  FrontendWorkError,
+  PageCatalog,
+  PageCatalogError,
+  TrackedTransport,
+  WorkRegistry,
+  createFrontendPage,
+  createFrontendSurface,
+  pageIdentity,
+  parseViewsSource
+};
+//# sourceMappingURL=index.js.map

package/dist/frontend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/frontend/index.ts"],"sourcesContent":["/**\n * Frontend application slice (spec 18 / 18A) — plain-Node tier.\n *\n * NOTE: keep re-exports single-line — the tsup extension-rewrite plugin\n * only rewrites single-line import/export specifiers.\n */\nexport { WorkRegistry, FrontendWorkError } from './work_registry.js';\nexport type { WorkDescriptor, WorkFailure, WorkKind, WorkOptions } from './work_registry.js';\nexport { FrontendLifecycleOwner } from './frontend_lifecycle.js';\nexport type { FrontendLifecycle } from './frontend_lifecycle.js';\nexport { PageCatalog, PageCatalogError, pageIdentity, parseViewsSource } from './page_catalog.js';\nexport type { RendererSelection, ViewsSource } from './page_catalog.js';\nexport { TrackedTransport } from './tracked_transport.js';\nexport { createFrontendPage } from './frontend_page.js';\nexport type { FrontendPage, FrontendPageHandle, FrontendLayout, MountedLayout } from './frontend_page.js';\nexport { createFrontendSurface } from './frontend_surface.js';\nexport type { FrontendApplicationSurface, FrontendOpenOptions, CreateFrontendSurfaceOptions, PageScopeContext } from './frontend_surface.js';\n"],"mappings":"AAMA,SAAS,cAAc,yBAAyB;AAEhD,SAAS,8BAA8B;AAEvC,SAAS,aAAa,kBAAkB,cAAc,wBAAwB;AAE9E,SAAS,wBAAwB;AACjC,SAAS,0BAA0B;AAEnC,SAAS,6BAA6B;","names":[]}

package/dist/frontend/page_catalog.cjs

@@ -0,0 +1,135 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var page_catalog_exports = {};
+__export(page_catalog_exports, {
+  PageCatalog: () => PageCatalog,
+  PageCatalogError: () => PageCatalogError,
+  pageIdentity: () => pageIdentity,
+  parseViewsSource: () => parseViewsSource
+});
+module.exports = __toCommonJS(page_catalog_exports);
+var import_views_parser = require("../parser/views_parser.cjs");
+class PageCatalogError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PageCatalogError";
+  }
+}
+function pageIdentity(view) {
+  return `${view.windowName}.${view.pageName}`;
+}
+function listIdentities(views) {
+  const identities = [...views].map(pageIdentity);
+  if (!identities.length) return "the source defines no views";
+  return `available pages:
+  ${identities.join("\n  ")}`;
+}
+function parseViewsSource(source) {
+  if (Array.isArray(source)) return source;
+  if (typeof source === "string") return (0, import_views_parser.parseViews)(source);
+  throw new PageCatalogError("views must be YAML content or parsed ViewDef[]");
+}
+class PageCatalog {
+  constructor(views) {
+    this.byIdentity = /* @__PURE__ */ new Map();
+    for (const view of views) {
+      const identity = pageIdentity(view);
+      if (this.byIdentity.has(identity)) {
+        throw new PageCatalogError(`duplicate page identity "${identity}" in views source`);
+      }
+      this.byIdentity.set(identity, view);
+    }
+  }
+  get size() {
+    return this.byIdentity.size;
+  }
+  all() {
+    return [...this.byIdentity.values()];
+  }
+  /**
+   * Apply a renderer aperture selection. Exactly one of `window`, `page`,
+   * `pages` must be supplied (they are mutually exclusive in the final
+   * effective selection).
+   */
+  select(selection) {
+    const forms = ["window", "page", "pages"].filter(
+      (key) => selection[key] !== void 0
+    );
+    if (forms.length !== 1) {
+      throw new PageCatalogError(
+        "renderer selection requires exactly one of { window }, { page }, or { pages }" + (forms.length ? `; got: ${forms.join(", ")}` : "")
+      );
+    }
+    if (selection.window !== void 0) {
+      const matched2 = this.all().filter((view) => view.windowName === selection.window);
+      if (!matched2.length) {
+        const windows = [...new Set(this.all().map((view) => view.windowName))];
+        throw new PageCatalogError(
+          `unknown window "${selection.window}"; ` + (windows.length ? `available windows: ${windows.join(", ")}` : "the source defines no views")
+        );
+      }
+      return new PageCatalog(matched2);
+    }
+    const requested = selection.page !== void 0 ? [selection.page] : selection.pages;
+    if (!requested.length) {
+      throw new PageCatalogError("renderer selection { pages } requires at least one page identity");
+    }
+    const matched = requested.map((identity) => {
+      const view = this.byIdentity.get(identity);
+      if (!view) {
+        throw new PageCatalogError(
+          `unknown page "${identity}"; ${listIdentities(this.byIdentity.values())}`
+        );
+      }
+      return view;
+    });
+    return new PageCatalog(matched);
+  }
+  /**
+   * Resolve a page identity for `frontend.open()` or navigation. The
+   * canonical `window.page` identity is always accepted; a short leaf name
+   * is accepted only when exactly one selected page has that leaf.
+   */
+  resolve(page) {
+    const exact = this.byIdentity.get(page);
+    if (exact) return exact;
+    const leafMatches = this.all().filter((view) => view.pageName === page);
+    if (leafMatches.length === 1) return leafMatches[0];
+    if (leafMatches.length > 1) {
+      throw new PageCatalogError(
+        `page "${page}" is ambiguous in the selected aperture; use a fully qualified identity: ` + leafMatches.map(pageIdentity).join(", ")
+      );
+    }
+    throw new PageCatalogError(
+      `page "${page}" is not in the selected aperture; ${listIdentities(this.byIdentity.values())}
+Widen the selection with select({ renderer: { window | pages } }) if this navigation is intentional.`
+    );
+  }
+  has(identity) {
+    return this.byIdentity.has(identity);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PageCatalog,
+  PageCatalogError,
+  pageIdentity,
+  parseViewsSource
+});
+//# sourceMappingURL=page_catalog.cjs.map

package/dist/frontend/page_catalog.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/frontend/page_catalog.ts"],"sourcesContent":["/**\n * Renderer page catalog and aperture selection (18A D-FAS-04).\n *\n * Wood's canonical page identity is the existing `window.page` view key\n * (`main.chat_dom`) — the first segment of the views YAML dot path is the\n * window name, the rest the page name. No renderer \"module\" concept is\n * invented; renderer grouping uses its natural window identity.\n *\n * Selection defines the allowed production page graph. It never chooses\n * the currently open page (`frontend.open` does, explicitly) and it never\n * widens itself: opening or navigating outside the aperture fails with a\n * diagnostic naming the aperture and the fix.\n */\nimport type { ViewDef } from '../types/index.cjs';\nimport { parseViews } from '../parser/views_parser.cjs';\n\nexport interface RendererSelection {\n  /** Every page belonging to one production window catalog. */\n  window?: string;\n  /** Exactly one renderer page (canonical `window.page` identity). */\n  page?: string;\n  /** Explicit pages needed by one flow. */\n  pages?: string[];\n}\n\nexport class PageCatalogError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'PageCatalogError';\n  }\n}\n\nexport function pageIdentity(view: ViewDef): string {\n  return `${view.windowName}.${view.pageName}`;\n}\n\nfunction listIdentities(views: Iterable<ViewDef>): string {\n  const identities = [...views].map(pageIdentity);\n  if (!identities.length) return 'the source defines no views';\n  return `available pages:\\n  ${identities.join('\\n  ')}`;\n}\n\nexport type ViewsSource = string | ViewDef[];\n\nexport function parseViewsSource(source: ViewsSource): ViewDef[] {\n  if (Array.isArray(source)) return source;\n  if (typeof source === 'string') return parseViews(source);\n  throw new PageCatalogError('views must be YAML content or parsed ViewDef[]');\n}\n\n/**\n * The production renderer page catalog: every view keyed by its canonical\n * `window.page` identity, with aperture selection and open/navigation\n * resolution (short leaf names accepted only when unambiguous).\n */\nexport class PageCatalog {\n  private readonly byIdentity = new Map<string, ViewDef>();\n\n  constructor(views: ViewDef[]) {\n    for (const view of views) {\n      const identity = pageIdentity(view);\n      if (this.byIdentity.has(identity)) {\n        throw new PageCatalogError(`duplicate page identity \"${identity}\" in views source`);\n      }\n      this.byIdentity.set(identity, view);\n    }\n  }\n\n  get size(): number {\n    return this.byIdentity.size;\n  }\n\n  all(): ViewDef[] {\n    return [...this.byIdentity.values()];\n  }\n\n  /**\n   * Apply a renderer aperture selection. Exactly one of `window`, `page`,\n   * `pages` must be supplied (they are mutually exclusive in the final\n   * effective selection).\n   */\n  select(selection: RendererSelection): PageCatalog {\n    const forms = (['window', 'page', 'pages'] as const).filter(\n      (key) => selection[key] !== undefined,\n    );\n    if (forms.length !== 1) {\n      throw new PageCatalogError(\n        'renderer selection requires exactly one of { window }, { page }, or { pages }' +\n        (forms.length ? `; got: ${forms.join(', ')}` : ''),\n      );\n    }\n\n    if (selection.window !== undefined) {\n      const matched = this.all().filter((view) => view.windowName === selection.window);\n      if (!matched.length) {\n        const windows = [...new Set(this.all().map((view) => view.windowName))];\n        throw new PageCatalogError(\n          `unknown window \"${selection.window}\"; ` +\n          (windows.length ? `available windows: ${windows.join(', ')}` : 'the source defines no views'),\n        );\n      }\n      return new PageCatalog(matched);\n    }\n\n    const requested = selection.page !== undefined ? [selection.page] : selection.pages!;\n    if (!requested.length) {\n      throw new PageCatalogError('renderer selection { pages } requires at least one page identity');\n    }\n    const matched = requested.map((identity) => {\n      const view = this.byIdentity.get(identity);\n      if (!view) {\n        throw new PageCatalogError(\n          `unknown page \"${identity}\"; ${listIdentities(this.byIdentity.values())}`,\n        );\n      }\n      return view;\n    });\n    return new PageCatalog(matched);\n  }\n\n  /**\n   * Resolve a page identity for `frontend.open()` or navigation. The\n   * canonical `window.page` identity is always accepted; a short leaf name\n   * is accepted only when exactly one selected page has that leaf.\n   */\n  resolve(page: string): ViewDef {\n    const exact = this.byIdentity.get(page);\n    if (exact) return exact;\n\n    const leafMatches = this.all().filter((view) => view.pageName === page);\n    if (leafMatches.length === 1) return leafMatches[0];\n    if (leafMatches.length > 1) {\n      throw new PageCatalogError(\n        `page \"${page}\" is ambiguous in the selected aperture; use a fully qualified identity: ` +\n        leafMatches.map(pageIdentity).join(', '),\n      );\n    }\n\n    throw new PageCatalogError(\n      `page \"${page}\" is not in the selected aperture; ${listIdentities(this.byIdentity.values())}\\n` +\n      'Widen the selection with select({ renderer: { window | pages } }) if this navigation is intentional.',\n    );\n  }\n\n  has(identity: string): boolean {\n    return this.byIdentity.has(identity);\n  }\n}\n"],"mappings":"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","names":["matched"]}