@noego/wood 0.4.10 → 0.5.0

package/dist/frontend/frontend_lifecycle.js

@@ -0,0 +1,50 @@
+import { FrontendWorkError } from "./work_registry.js";
+class FrontendLifecycleOwner {
+  constructor(registry, owner) {
+    this.registry = registry;
+    this.owner = owner;
+    this.abortController = new AbortController();
+    this.resources = [];
+    this.disposed = false;
+  }
+  get signal() {
+    return this.abortController.signal;
+  }
+  track(work, options) {
+    if (this.disposed) {
+      throw new FrontendWorkError(
+        `cannot track "${options.label}": lifecycle "${this.owner}" is disposed. Work started after a page/environment ended is a product lifecycle bug.`
+      );
+    }
+    return this.registry.track(work, {
+      label: options.label,
+      kind: options.kind ?? "tracked",
+      owner: this.owner
+    });
+  }
+  own(resource) {
+    if (this.disposed) {
+      throw new FrontendWorkError(
+        `cannot own a resource: lifecycle "${this.owner}" is disposed.`
+      );
+    }
+    this.resources.push(resource);
+  }
+  get isDisposed() {
+    return this.disposed;
+  }
+  /** Abort owned work and dispose owned resources in reverse order. */
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.abortController.abort();
+    for (const resource of this.resources.reverse()) {
+      await resource.dispose();
+    }
+    this.resources.length = 0;
+  }
+}
+export {
+  FrontendLifecycleOwner
+};
+//# sourceMappingURL=frontend_lifecycle.js.map

package/dist/frontend/frontend_lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/frontend/frontend_lifecycle.ts"],"sourcesContent":["/**\n * Production lifecycle owners for deliberately detached frontend work\n * (18A D-FAS-01 §2.2). Two natural owners exist per environment:\n *\n *   page lifecycle         — default for PageController work; aborted and\n *                            disposed when that page ends\n *   application lifecycle  — explicit for work that intentionally survives\n *                            page navigation; disposed with the environment\n *\n * PageControllers/client services register their own deliberately detached\n * finite work through their injected lifecycle owner — tests do not repair\n * unowned product code by wrapping it in track() from the outside.\n */\nimport { WorkRegistry, FrontendWorkError } from './work_registry.js';\n\nexport interface FrontendLifecycle {\n  readonly signal: AbortSignal;\n\n  track<T>(\n    work: Promise<T>,\n    options: {\n      label: string;\n      kind?: string;\n    },\n  ): Promise<T>;\n\n  own(resource: { dispose(): void | Promise<void> }): void;\n}\n\nexport class FrontendLifecycleOwner implements FrontendLifecycle {\n  private readonly abortController = new AbortController();\n  private readonly resources: Array<{ dispose(): void | Promise<void> }> = [];\n  private disposed = false;\n\n  constructor(\n    private readonly registry: WorkRegistry,\n    /** Diagnostic owner identity, e.g. `page main.chat_dom` or `application`. */\n    readonly owner: string,\n  ) {}\n\n  get signal(): AbortSignal {\n    return this.abortController.signal;\n  }\n\n  track<T>(work: Promise<T>, options: { label: string; kind?: string }): Promise<T> {\n    if (this.disposed) {\n      throw new FrontendWorkError(\n        `cannot track \"${options.label}\": lifecycle \"${this.owner}\" is disposed. ` +\n        'Work started after a page/environment ended is a product lifecycle bug.',\n      );\n    }\n    return this.registry.track(work, {\n      label: options.label,\n      kind: options.kind ?? 'tracked',\n      owner: this.owner,\n    });\n  }\n\n  own(resource: { dispose(): void | Promise<void> }): void {\n    if (this.disposed) {\n      throw new FrontendWorkError(\n        `cannot own a resource: lifecycle \"${this.owner}\" is disposed.`,\n      );\n    }\n    this.resources.push(resource);\n  }\n\n  get isDisposed(): boolean {\n    return this.disposed;\n  }\n\n  /** Abort owned work and dispose owned resources in reverse order. */\n  async dispose(): Promise<void> {\n    if (this.disposed) return;\n    this.disposed = true;\n    this.abortController.abort();\n    for (const resource of this.resources.reverse()) {\n      await resource.dispose();\n    }\n    this.resources.length = 0;\n  }\n}\n"],"mappings":"AAaA,SAAuB,yBAAyB;AAgBzC,MAAM,uBAAoD;AAAA,EAK/D,YACmB,UAER,OACT;AAHiB;AAER;AAPX,SAAiB,kBAAkB,IAAI,gBAAgB;AACvD,SAAiB,YAAwD,CAAC;AAC1E,SAAQ,WAAW;AAAA,EAMhB;AAAA,EAEH,IAAI,SAAsB;AACxB,WAAO,KAAK,gBAAgB;AAAA,EAC9B;AAAA,EAEA,MAAS,MAAkB,SAAuD;AAChF,QAAI,KAAK,UAAU;AACjB,YAAM,IAAI;AAAA,QACR,iBAAiB,QAAQ,KAAK,iBAAiB,KAAK,KAAK;AAAA,MAE3D;AAAA,IACF;AACA,WAAO,KAAK,SAAS,MAAM,MAAM;AAAA,MAC/B,OAAO,QAAQ;AAAA,MACf,MAAM,QAAQ,QAAQ;AAAA,MACtB,OAAO,KAAK;AAAA,IACd,CAAC;AAAA,EACH;AAAA,EAEA,IAAI,UAAqD;AACvD,QAAI,KAAK,UAAU;AACjB,YAAM,IAAI;AAAA,QACR,qCAAqC,KAAK,KAAK;AAAA,MACjD;AAAA,IACF;AACA,SAAK,UAAU,KAAK,QAAQ;AAAA,EAC9B;AAAA,EAEA,IAAI,aAAsB;AACxB,WAAO,KAAK;AAAA,EACd;AAAA;AAAA,EAGA,MAAM,UAAyB;AAC7B,QAAI,KAAK,SAAU;AACnB,SAAK,WAAW;AAChB,SAAK,gBAAgB,MAAM;AAC3B,eAAW,YAAY,KAAK,UAAU,QAAQ,GAAG;AAC/C,YAAM,SAAS,QAAQ;AAAA,IACzB;AACA,SAAK,UAAU,SAAS;AAAA,EAC1B;AACF;","names":[]}

package/dist/frontend/frontend_page.cjs

@@ -0,0 +1,122 @@
+"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_page_exports = {};
+__export(frontend_page_exports, {
+  createFrontendPage: () => createFrontendPage
+});
+module.exports = __toCommonJS(frontend_page_exports);
+var import_ioc = require("@noego/ioc");
+var import_work_registry = require("./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) => import_ioc.ExecutionContext.current() !== void 0 ? fn.apply(target, args) : import_ioc.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 import_work_registry.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 import_work_registry.FrontendWorkError(
+          `page "${identity}" mounts no layout controller; its views entry binds none.`
+        );
+      }
+      throw new import_work_registry.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;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createFrontendPage
+});
+//# sourceMappingURL=frontend_page.cjs.map

package/dist/frontend/frontend_page.cjs.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":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,iBAAiC;AACjC,2BAAkC;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,4BAAiB,QAAQ,MAAM,SAC3B,GAAG,MAAM,QAAQ,IAAI,IACrB,4BAAiB,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_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":[]}