@noego/wood 0.4.9 → 0.5.0

package/dist/frontend/frontend_page.d.cts

@@ -0,0 +1,62 @@
+/**
+ * The public projection of one mounted LAYOUT controller (18A D-FAS-05).
+ *
+ * Layout controllers are production page members — the views YAML binds
+ * them, the renderer mounts them alongside the view controller, and a
+ * `preserve: true` layout outlives page transitions. They therefore expose
+ * the same public `data / input / events` contract as the page controller,
+ * never their instance.
+ */
+interface FrontendLayout<Data = unknown, Input = unknown, Events = unknown> {
+    /** The layout view path as declared in the views source. */
+    readonly path: string;
+    /** The layout controller identity as declared in the views source. */
+    readonly controller: string;
+    /** Whether the views source declares this layout preservable. */
+    readonly preserve: boolean;
+    readonly data: Data;
+    readonly input: Input;
+    readonly events: Events | undefined;
+}
+interface FrontendPage<Data = unknown, Input = unknown, Events = unknown> {
+    /** Canonical `window.page` production identity. */
+    readonly identity: string;
+    readonly data: Data;
+    readonly input: Input;
+    readonly events: Events | undefined;
+    /** Every mounted layout controller of this page, outermost first. */
+    readonly layouts: readonly FrontendLayout[];
+    /**
+     * The page's sole layout controller. Throws when the page declares none,
+     * or more than one — use `layouts` and name the layout explicitly there.
+     */
+    readonly layout: FrontendLayout;
+    close(): Promise<void>;
+}
+interface PageControllerLike {
+    data?: unknown;
+    input?: unknown;
+    events?: unknown;
+}
+interface FrontendPageHandle<Data = unknown, Input = unknown, Events = unknown> {
+    page: FrontendPage<Data, Input, Events>;
+    /** Mark the projection stale without disposing (navigation already disposed the scope). */
+    invalidate: () => void;
+}
+/** One mounted layout controller with the scope its handlers run under. */
+interface MountedLayout {
+    path: string;
+    controller: string;
+    preserve: boolean;
+    instance: PageControllerLike;
+    scope: unknown;
+}
+declare function createFrontendPage<Data, Input, Events>(options: {
+    identity: string;
+    controller: PageControllerLike;
+    scope: unknown;
+    layouts?: readonly MountedLayout[];
+    onClose: () => Promise<void>;
+}): FrontendPageHandle<Data, Input, Events>;
+
+export { type FrontendLayout, type FrontendPage, type FrontendPageHandle, type MountedLayout, createFrontendPage };

package/dist/frontend/frontend_page.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The public projection of one mounted LAYOUT controller (18A D-FAS-05).
+ *
+ * Layout controllers are production page members — the views YAML binds
+ * them, the renderer mounts them alongside the view controller, and a
+ * `preserve: true` layout outlives page transitions. They therefore expose
+ * the same public `data / input / events` contract as the page controller,
+ * never their instance.
+ */
+interface FrontendLayout<Data = unknown, Input = unknown, Events = unknown> {
+    /** The layout view path as declared in the views source. */
+    readonly path: string;
+    /** The layout controller identity as declared in the views source. */
+    readonly controller: string;
+    /** Whether the views source declares this layout preservable. */
+    readonly preserve: boolean;
+    readonly data: Data;
+    readonly input: Input;
+    readonly events: Events | undefined;
+}
+interface FrontendPage<Data = unknown, Input = unknown, Events = unknown> {
+    /** Canonical `window.page` production identity. */
+    readonly identity: string;
+    readonly data: Data;
+    readonly input: Input;
+    readonly events: Events | undefined;
+    /** Every mounted layout controller of this page, outermost first. */
+    readonly layouts: readonly FrontendLayout[];
+    /**
+     * The page's sole layout controller. Throws when the page declares none,
+     * or more than one — use `layouts` and name the layout explicitly there.
+     */
+    readonly layout: FrontendLayout;
+    close(): Promise<void>;
+}
+interface PageControllerLike {
+    data?: unknown;
+    input?: unknown;
+    events?: unknown;
+}
+interface FrontendPageHandle<Data = unknown, Input = unknown, Events = unknown> {
+    page: FrontendPage<Data, Input, Events>;
+    /** Mark the projection stale without disposing (navigation already disposed the scope). */
+    invalidate: () => void;
+}
+/** One mounted layout controller with the scope its handlers run under. */
+interface MountedLayout {
+    path: string;
+    controller: string;
+    preserve: boolean;
+    instance: PageControllerLike;
+    scope: unknown;
+}
+declare function createFrontendPage<Data, Input, Events>(options: {
+    identity: string;
+    controller: PageControllerLike;
+    scope: unknown;
+    layouts?: readonly MountedLayout[];
+    onClose: () => Promise<void>;
+}): FrontendPageHandle<Data, Input, Events>;
+
+export { type FrontendLayout, type FrontendPage, type FrontendPageHandle, type MountedLayout, createFrontendPage };

package/dist/frontend/frontend_page.js

@@ -0,0 +1,98 @@
+import { ExecutionContext } from "@noego/ioc";
+import { FrontendWorkError } from "./work_registry.js";
+function bridgeSurface(surface, scope) {
+  if (!surface || typeof surface !== "object") return surface;
+  const wrapped = /* @__PURE__ */ new WeakMap();
+  return new Proxy(surface, {
+    get(target, property, receiver) {
+      const value = Reflect.get(target, property, receiver === void 0 ? target : target);
+      if (typeof value !== "function") return value;
+      const fn = value;
+      const cached = wrapped.get(fn);
+      if (cached) return cached;
+      const bridged = (...args) => ExecutionContext.current() !== void 0 ? fn.apply(target, args) : ExecutionContext.run(scope, () => fn.apply(target, args));
+      wrapped.set(fn, bridged);
+      return bridged;
+    }
+  });
+}
+function createFrontendPage(options) {
+  const { identity, controller, scope } = options;
+  let closed = false;
+  const bridgedInput = bridgeSurface(controller.input, scope);
+  const bridgedEvents = bridgeSurface(controller.events, scope);
+  const layouts = (options.layouts ?? []).map((mounted) => {
+    const layoutInput = bridgeSurface(mounted.instance.input, mounted.scope);
+    const layoutEvents = bridgeSurface(mounted.instance.events, mounted.scope);
+    return {
+      path: mounted.path,
+      controller: mounted.controller,
+      preserve: mounted.preserve,
+      get data() {
+        guard();
+        return mounted.instance.data;
+      },
+      get input() {
+        guard();
+        return layoutInput;
+      },
+      get events() {
+        guard();
+        return layoutEvents;
+      }
+    };
+  });
+  const guard = () => {
+    if (closed) {
+      throw new FrontendWorkError(
+        `page "${identity}" is closed; a closed/navigated-away page handle must not be used. Re-open the page or use frontend.current().`
+      );
+    }
+  };
+  const page = {
+    identity,
+    get data() {
+      guard();
+      return controller.data;
+    },
+    get input() {
+      guard();
+      return bridgedInput;
+    },
+    get events() {
+      guard();
+      return bridgedEvents;
+    },
+    get layouts() {
+      guard();
+      return layouts;
+    },
+    get layout() {
+      guard();
+      if (layouts.length === 1) return layouts[0];
+      if (!layouts.length) {
+        throw new FrontendWorkError(
+          `page "${identity}" mounts no layout controller; its views entry binds none.`
+        );
+      }
+      throw new FrontendWorkError(
+        `page "${identity}" mounts ${layouts.length} layout controllers (${layouts.map((entry) => entry.controller).join(", ")}); use page.layouts and name the one you mean.`
+      );
+    },
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      await options.onClose();
+    }
+  };
+  return {
+    page,
+    invalidate: () => {
+      closed = true;
+    }
+  };
+}
+export {
+  createFrontendPage
+};
+//# sourceMappingURL=frontend_page.js.map

package/dist/frontend/frontend_page.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/frontend/frontend_page.ts"],"sourcesContent":["/**\n * The public frontend page projection (18A D-FAS-05).\n *\n * `FrontendPage` exposes the production `data / input / events` contract of\n * the selected PageController — never the controller instance itself, never\n * private or IoC-only members. References are not cloned (reactivity is\n * preserved); `input`/`events` handlers are bridged so they execute under\n * the page scope's IoC execution context, exactly as the production\n * renderer runtime invokes them (they are plain data properties holding\n * arrow functions, which would otherwise run context-less from a test).\n */\nimport { ExecutionContext } from '@noego/ioc';\nimport { FrontendWorkError } from './work_registry.js';\n\n/**\n * The public projection of one mounted LAYOUT controller (18A D-FAS-05).\n *\n * Layout controllers are production page members — the views YAML binds\n * them, the renderer mounts them alongside the view controller, and a\n * `preserve: true` layout outlives page transitions. They therefore expose\n * the same public `data / input / events` contract as the page controller,\n * never their instance.\n */\nexport interface FrontendLayout<Data = unknown, Input = unknown, Events = unknown> {\n  /** The layout view path as declared in the views source. */\n  readonly path: string;\n  /** The layout controller identity as declared in the views source. */\n  readonly controller: string;\n  /** Whether the views source declares this layout preservable. */\n  readonly preserve: boolean;\n  readonly data: Data;\n  readonly input: Input;\n  readonly events: Events | undefined;\n}\n\nexport interface FrontendPage<Data = unknown, Input = unknown, Events = unknown> {\n  /** Canonical `window.page` production identity. */\n  readonly identity: string;\n  readonly data: Data;\n  readonly input: Input;\n  readonly events: Events | undefined;\n  /** Every mounted layout controller of this page, outermost first. */\n  readonly layouts: readonly FrontendLayout[];\n  /**\n   * The page's sole layout controller. Throws when the page declares none,\n   * or more than one — use `layouts` and name the layout explicitly there.\n   */\n  readonly layout: FrontendLayout;\n  close(): Promise<void>;\n}\n\ninterface PageControllerLike {\n  data?: unknown;\n  input?: unknown;\n  events?: unknown;\n}\n\nfunction bridgeSurface(surface: unknown, scope: unknown): unknown {\n  if (!surface || typeof surface !== 'object') return surface;\n  // Proxy, not a copy: input/events surfaces are often class instances\n  // (methods on the prototype) or reactive objects (accessor-backed state);\n  // a proxy preserves both while wrapping function reads so handlers run\n  // under the page scope's execution context.\n  const wrapped = new WeakMap<object, unknown>();\n  return new Proxy(surface as object, {\n    get(target, property, receiver) {\n      const value = Reflect.get(target, property, receiver === undefined ? target : target);\n      if (typeof value !== 'function') return value;\n      const fn = value as (...args: unknown[]) => unknown;\n      const cached = wrapped.get(fn);\n      if (cached) return cached;\n      const bridged = (...args: unknown[]) =>\n        ExecutionContext.current() !== undefined\n          ? fn.apply(target, args)\n          : ExecutionContext.run(scope as never, () => fn.apply(target, args));\n      wrapped.set(fn, bridged);\n      return bridged;\n    },\n  });\n}\n\nexport interface FrontendPageHandle<Data = unknown, Input = unknown, Events = unknown> {\n  page: FrontendPage<Data, Input, Events>;\n  /** Mark the projection stale without disposing (navigation already disposed the scope). */\n  invalidate: () => void;\n}\n\n/** One mounted layout controller with the scope its handlers run under. */\nexport interface MountedLayout {\n  path: string;\n  controller: string;\n  preserve: boolean;\n  instance: PageControllerLike;\n  scope: unknown;\n}\n\nexport function createFrontendPage<Data, Input, Events>(options: {\n  identity: string;\n  controller: PageControllerLike;\n  scope: unknown;\n  layouts?: readonly MountedLayout[];\n  onClose: () => Promise<void>;\n}): FrontendPageHandle<Data, Input, Events> {\n  const { identity, controller, scope } = options;\n  let closed = false;\n\n  const bridgedInput = bridgeSurface(controller.input, scope);\n  const bridgedEvents = bridgeSurface(controller.events, scope);\n\n  const layouts: FrontendLayout[] = (options.layouts ?? []).map((mounted) => {\n    const layoutInput = bridgeSurface(mounted.instance.input, mounted.scope);\n    const layoutEvents = bridgeSurface(mounted.instance.events, mounted.scope);\n    return {\n      path: mounted.path,\n      controller: mounted.controller,\n      preserve: mounted.preserve,\n      get data() {\n        guard();\n        return mounted.instance.data;\n      },\n      get input() {\n        guard();\n        return layoutInput;\n      },\n      get events() {\n        guard();\n        return layoutEvents;\n      },\n    };\n  });\n\n  const guard = (): void => {\n    if (closed) {\n      throw new FrontendWorkError(\n        `page \"${identity}\" is closed; a closed/navigated-away page handle must not be used. ` +\n        'Re-open the page or use frontend.current().',\n      );\n    }\n  };\n\n  const page: FrontendPage<Data, Input, Events> = {\n    identity,\n    get data(): Data {\n      guard();\n      return controller.data as Data;\n    },\n    get input(): Input {\n      guard();\n      return bridgedInput as Input;\n    },\n    get events(): Events | undefined {\n      guard();\n      return bridgedEvents as Events | undefined;\n    },\n    get layouts(): readonly FrontendLayout[] {\n      guard();\n      return layouts;\n    },\n    get layout(): FrontendLayout {\n      guard();\n      if (layouts.length === 1) return layouts[0];\n      if (!layouts.length) {\n        throw new FrontendWorkError(\n          `page \"${identity}\" mounts no layout controller; its views entry binds none.`,\n        );\n      }\n      throw new FrontendWorkError(\n        `page \"${identity}\" mounts ${layouts.length} layout controllers ` +\n        `(${layouts.map((entry) => entry.controller).join(', ')}); ` +\n        'use page.layouts and name the one you mean.',\n      );\n    },\n    close: async () => {\n      if (closed) return;\n      closed = true;\n      await options.onClose();\n    },\n  };\n\n  return {\n    page,\n    invalidate: () => {\n      closed = true;\n    },\n  };\n}\n"],"mappings":"AAWA,SAAS,wBAAwB;AACjC,SAAS,yBAAyB;AA6ClC,SAAS,cAAc,SAAkB,OAAyB;AAChE,MAAI,CAAC,WAAW,OAAO,YAAY,SAAU,QAAO;AAKpD,QAAM,UAAU,oBAAI,QAAyB;AAC7C,SAAO,IAAI,MAAM,SAAmB;AAAA,IAClC,IAAI,QAAQ,UAAU,UAAU;AAC9B,YAAM,QAAQ,QAAQ,IAAI,QAAQ,UAAU,aAAa,SAAY,SAAS,MAAM;AACpF,UAAI,OAAO,UAAU,WAAY,QAAO;AACxC,YAAM,KAAK;AACX,YAAM,SAAS,QAAQ,IAAI,EAAE;AAC7B,UAAI,OAAQ,QAAO;AACnB,YAAM,UAAU,IAAI,SAClB,iBAAiB,QAAQ,MAAM,SAC3B,GAAG,MAAM,QAAQ,IAAI,IACrB,iBAAiB,IAAI,OAAgB,MAAM,GAAG,MAAM,QAAQ,IAAI,CAAC;AACvE,cAAQ,IAAI,IAAI,OAAO;AACvB,aAAO;AAAA,IACT;AAAA,EACF,CAAC;AACH;AAiBO,SAAS,mBAAwC,SAMZ;AAC1C,QAAM,EAAE,UAAU,YAAY,MAAM,IAAI;AACxC,MAAI,SAAS;AAEb,QAAM,eAAe,cAAc,WAAW,OAAO,KAAK;AAC1D,QAAM,gBAAgB,cAAc,WAAW,QAAQ,KAAK;AAE5D,QAAM,WAA6B,QAAQ,WAAW,CAAC,GAAG,IAAI,CAAC,YAAY;AACzE,UAAM,cAAc,cAAc,QAAQ,SAAS,OAAO,QAAQ,KAAK;AACvE,UAAM,eAAe,cAAc,QAAQ,SAAS,QAAQ,QAAQ,KAAK;AACzE,WAAO;AAAA,MACL,MAAM,QAAQ;AAAA,MACd,YAAY,QAAQ;AAAA,MACpB,UAAU,QAAQ;AAAA,MAClB,IAAI,OAAO;AACT,cAAM;AACN,eAAO,QAAQ,SAAS;AAAA,MAC1B;AAAA,MACA,IAAI,QAAQ;AACV,cAAM;AACN,eAAO;AAAA,MACT;AAAA,MACA,IAAI,SAAS;AACX,cAAM;AACN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,EACF,CAAC;AAED,QAAM,QAAQ,MAAY;AACxB,QAAI,QAAQ;AACV,YAAM,IAAI;AAAA,QACR,SAAS,QAAQ;AAAA,MAEnB;AAAA,IACF;AAAA,EACF;AAEA,QAAM,OAA0C;AAAA,IAC9C;AAAA,IACA,IAAI,OAAa;AACf,YAAM;AACN,aAAO,WAAW;AAAA,IACpB;AAAA,IACA,IAAI,QAAe;AACjB,YAAM;AACN,aAAO;AAAA,IACT;AAAA,IACA,IAAI,SAA6B;AAC/B,YAAM;AACN,aAAO;AAAA,IACT;AAAA,IACA,IAAI,UAAqC;AACvC,YAAM;AACN,aAAO;AAAA,IACT;AAAA,IACA,IAAI,SAAyB;AAC3B,YAAM;AACN,UAAI,QAAQ,WAAW,EAAG,QAAO,QAAQ,CAAC;AAC1C,UAAI,CAAC,QAAQ,QAAQ;AACnB,cAAM,IAAI;AAAA,UACR,SAAS,QAAQ;AAAA,QACnB;AAAA,MACF;AACA,YAAM,IAAI;AAAA,QACR,SAAS,QAAQ,YAAY,QAAQ,MAAM,wBACvC,QAAQ,IAAI,CAAC,UAAU,MAAM,UAAU,EAAE,KAAK,IAAI,CAAC;AAAA,MAEzD;AAAA,IACF;AAAA,IACA,OAAO,YAAY;AACjB,UAAI,OAAQ;AACZ,eAAS;AACT,YAAM,QAAQ,QAAQ;AAAA,IACxB;AAAA,EACF;AAEA,SAAO;AAAA,IACL;AAAA,IACA,YAAY,MAAM;AAChB,eAAS;AAAA,IACX;AAAA,EACF;AACF;","names":[]}

package/dist/frontend/frontend_surface.cjs

@@ -0,0 +1,249 @@
+"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_surface_exports = {};
+__export(frontend_surface_exports, {
+  FrontendWorkError: () => import_work_registry.FrontendWorkError,
+  createFrontendSurface: () => createFrontendSurface
+});
+module.exports = __toCommonJS(frontend_surface_exports);
+var import_ioc = require("@noego/ioc");
+var import_layout_preservation = require("../navigation/layout_preservation.js");
+var import_controller_lifecycle = require("../controller/controller_lifecycle.js");
+var import_page_catalog = require("./page_catalog.js");
+var import_work_registry = require("./work_registry.js");
+var import_frontend_lifecycle = require("./frontend_lifecycle.js");
+var import_frontend_page = require("./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 import_frontend_lifecycle.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 = (0, import_page_catalog.pageIdentity)(view);
+    if (!view.controller) {
+      throw new import_page_catalog.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 import_frontend_lifecycle.FrontendLifecycleOwner(registry, `page ${identity}`);
+    scope.registerFunction?.(import_frontend_lifecycle.FrontendLifecycleOwner, () => lifecycle, { loadAs: import_ioc.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 import_frontend_lifecycle.FrontendLifecycleOwner(registry, `layout ${layoutIdentity}`) : null;
+      const layoutScope = ownScope ?? scope;
+      if (ownScope) {
+        ownScope.registerFunction?.(import_frontend_lifecycle.FrontendLifecycleOwner, () => ownLifecycle, { loadAs: import_ioc.LoadAs.Scoped });
+        await options.configurePageScope?.(ownScope, view, {
+          kind: "layout",
+          layoutIndex: index,
+          controller: layoutIdentity
+        });
+      }
+      registerControllerUnlessBound(layoutScope, LayoutClass);
+      const instance = await import_ioc.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 import_ioc.ExecutionContext.run(
+      scope,
+      () => scope.get(ControllerClass)
+    );
+    guardControllerLifecycleOnce(controller);
+    if (typeof controller.initialize === "function") {
+      await registry.track(
+        Promise.resolve(
+          import_ioc.ExecutionContext.run(
+            scope,
+            () => controller.initialize({ params, query })
+          )
+        ).then(() => void 0),
+        { label: `initialize ${identity}`, kind: "initialize", owner: `page ${identity}` }
+      );
+    }
+    const handle = (0, import_frontend_page.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 (0, import_controller_lifecycle.disposeControllerLifecycle)(page.controller);
+    for (const layout of page.layouts) {
+      if (layout.index < preservedDepth) continue;
+      await (0, import_controller_lifecycle.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 ? (0, import_layout_preservation.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 import_page_catalog.PageCatalogError("frontend.open() requires an explicit { page } identity");
+      }
+      if (active) {
+        throw new import_page_catalog.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((0, import_page_catalog.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();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FrontendWorkError,
+  createFrontendSurface
+});
+//# sourceMappingURL=frontend_surface.cjs.map

package/dist/frontend/frontend_surface.cjs.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.cjs';\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/frontend_surface.d.cts

@@ -0,0 +1,64 @@
+import { Navigation } from '../navigation/index.cjs';
+import { ViewDef } from '../types/views.cjs';
+import { PageCatalog } from './page_catalog.cjs';
+import { WorkRegistry, WorkFailure } from './work_registry.cjs';
+export { FrontendWorkError } from './work_registry.cjs';
+export { FrontendLifecycle } from './frontend_lifecycle.cjs';
+import { FrontendPage } from './frontend_page.cjs';
+import '../navigation/automation_introspection.cjs';
+
+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 };