@openruntime/modern-plugin 0.1.0

package/README.md

@@ -0,0 +1,334 @@
+# @openruntime/modern-plugin
+
+`@openruntime/modern-plugin` lets a Modern.js app expose framework runtime
+state to OpenRuntime. It records information that Modern.js already knows:
+application render state, current route state, SSR state, hydration state, and
+optional business ready state.
+
+The plugin does not decide whether a business page is usable. Framework targets
+only describe framework lifecycle. Business readiness should use the business
+ready helpers described below.
+
+## Usage
+
+Add the plugin in `src/modern.runtime.ts`:
+
+```ts
+import { openRuntimeModernPlugin } from "@openruntime/modern-plugin";
+
+export default openRuntimeModernPlugin({
+  bridge: {
+    port: 17321,
+  },
+});
+```
+
+Then use the OpenRuntime CLI against the page:
+
+```sh
+pnpm exec openruntime targets --url http://localhost:19081/
+pnpm exec openruntime snapshot --url http://localhost:19081/
+pnpm exec openruntime wait-for modern:route ready --url http://localhost:19081/ --where pathname=/orders
+```
+
+## Targets
+
+### `modern:app`
+
+Type: `modern.app`
+
+This is the top-level Modern.js runtime signal for the current page. Use it as
+the quick "is the framework page currently healthy" check.
+
+Statuses:
+
+- `initializing`: the plugin has been installed, but rendering has not started.
+- `rendering`: Modern.js is rendering or route work is still in progress.
+- `ready`: the current framework route is ready and no hydration error is
+  active.
+- `error`: a framework-level failure was observed. The snapshot data points to
+  the failed target, usually `modern:route` or `modern:hydration`.
+
+Common snapshot data:
+
+- `routeCount`: number of known Modern.js routes.
+- `basename`: router basename when Modern.js provides it.
+- `failedTargetId`: failed target id when the app is in `error`.
+- `failedStatus`: failed target status, usually `error`.
+- `reason`: short reason such as `route-loader-error`,
+  `route-component-error`, `route-error`, or hydration fallback reason.
+- `pathname`: current pathname when the failure is route-related.
+- `errorRouteIds`: route ids that currently carry route errors.
+- `hydrationEventType`: hydration event type when hydration failed.
+
+### `modern:route`
+
+Type: `modern.route`
+
+This is the single route target. It represents the current route state and keeps
+the route manifest on the target definition.
+
+Statuses:
+
+- `idle`: no current route match has been observed yet.
+- `loading`: navigation, loader, or redirect work is still in progress.
+- `ready`: the current route match is stable and has no known route error.
+- `error`: a route loader, route module, or router error was observed.
+
+Target data from `targets`:
+
+- `routes`: route manifest for known routes.
+- `routes[].routeId`: stable OpenRuntime route id. When a pathname is known,
+  this is the pathname, such as `/orders`.
+- `routes[].path`: Modern.js route path segment.
+- `routes[].pathname`: resolved pathname when available.
+- `routes[].modernRouteId`: original Modern.js route id.
+- `routes[].parentRouteId`: parent route id for nested routes.
+- `routes[].index`: whether this is an index route.
+- `routes[].hasLoader`: whether the route has a real data loader.
+- `routes[].hasRouteComponent`: whether the route declares a route component or
+  lazy module.
+- `routes[].hasLazyModule`: whether the route uses a lazy module.
+
+Snapshot data from `snapshot`:
+
+- `pathname`: current browser pathname.
+- `navigation`: current router navigation state.
+- `matches`: current matched route chain only. Old route matches are not kept
+  after navigation.
+- `matches[].loader`: real data loader state when known:
+  `loading`, `success`, `redirect`, or `error`.
+- `matches[].routeComponent`: shown only when the route component module failed;
+  the value is `error`.
+- `matches[].error`: route-specific error details.
+- `errorRouteIds`: route ids that currently have errors.
+
+`modern:route` does not create separate loader or route component targets.
+Loader and route component details stay inside the current `matches` array so a
+snapshot describes the current route instead of a history of every visited
+route.
+
+Common waits:
+
+```sh
+pnpm exec openruntime wait-for modern:route ready --where pathname=/orders
+pnpm exec openruntime wait-for modern:route error --where pathname=/broken
+```
+
+## Optional Route Actions
+
+The Modern.js plugin does not register route actions by default. Enable them
+explicitly when the page should expose route list and route navigation actions
+to Agents:
+
+```ts
+openRuntimeModernPlugin({
+  injectRouteListAction: true,
+  injectRouteNavigateAction: true,
+});
+```
+
+### `modern.route.list`
+
+Enabled by `injectRouteListAction`.
+
+This safe action returns the same known route manifest stored on the
+`modern:route` target.
+
+```sh
+pnpm exec openruntime run-action modern.route.list
+```
+
+### `modern.route.navigate`
+
+Enabled by `injectRouteNavigateAction`.
+
+This state-changing action navigates through the Modern.js router. The `to`
+input only accepts routes known by the current `modern:route` route manifest.
+Use input options to read the current candidate route pathnames:
+
+```sh
+pnpm exec openruntime input-options --action modern.route.navigate --input to
+pnpm exec openruntime run-action modern.route.navigate --payload '{"to":"/orders"}'
+pnpm exec openruntime wait-for modern:route ready --where pathname=/orders
+```
+
+### `modern:ssr`
+
+Type: `modern.ssr`
+
+This target is registered only when SSR data exists or SSR work is observed. A
+CSR-only page normally does not have `modern:ssr`.
+
+Statuses:
+
+- `unknown`: SSR target was registered before detailed state was available.
+- `rendering`: the server render has started and has not finished yet.
+- `server-rendered`: server render completed and produced SSR payload.
+- `fallback`: Modern.js fell back to client render.
+- `invalidated`: browser hydration showed the SSR result could not be reused.
+- `error`: SSR output is not usable because the server-rendered route failed.
+
+Common snapshot data:
+
+- `environment`: `server` or `browser`.
+- `runtimeId`: OpenRuntime runtime id injected during SSR.
+- `renderId`: render id injected during SSR.
+- `requestPathname`: pathname for the SSR request when available.
+- `requestUrl`: full SSR request URL when available.
+- `renderMode`: Modern.js render mode, such as `string` or `stream`.
+- `renderLevel`: Modern.js hydration/render level when available.
+- `reason`: fallback or invalidation reason when available.
+- `failedTargetId`: failed target id when SSR becomes `error`.
+- `failedStatus`: failed target status.
+
+Common wait:
+
+```sh
+pnpm exec openruntime wait-for modern:ssr server-rendered --where environment=server
+```
+
+### `modern:hydration`
+
+Type: `modern.hydration`
+
+This target is registered only when Modern.js emits hydration events. A CSR-only
+page normally does not have `modern:hydration`. If SSR failed before hydration,
+the plugin suppresses this target so a failed SSR page is not shown as
+hydration success.
+
+Statuses:
+
+- `running`: client hydration has started.
+- `success`: client hydration completed successfully.
+- `fallback`: Modern.js downgraded to client render.
+- `error`: hydration failed or emitted a recoverable hydration error.
+
+Common snapshot data:
+
+- `type`: Modern.js hydration event type.
+- `renderLevel`: Modern.js render level when available.
+- `renderMode`: Modern.js render mode when available.
+- `reason`: hydration fallback or recoverable-error reason.
+
+When hydration enters `error`, `modern:ssr` becomes `invalidated` and
+`modern:app` becomes `error`. Later hydration success events do not overwrite
+the earlier hydration failure.
+
+## Garfish Targets
+
+The package also exports Garfish helpers for Modern.js / EdenX host
+applications that use Garfish:
+
+- `createOpenRuntimeGarfishReporter`
+- `createOpenRuntimeGarfishPlugin`
+- `createOpenRuntimeGarfishCustomLoader`
+
+Garfish is a singleton in the host page. Register the OpenRuntime Garfish
+plugin in the host application before `Garfish.run()` or before the first
+`Garfish.loadApp()`:
+
+```ts
+import {
+  createOpenRuntimeGarfishCustomLoader,
+  createOpenRuntimeGarfishPlugin,
+  createOpenRuntimeGarfishReporter,
+} from "@openruntime/modern-plugin";
+
+const reporter = createOpenRuntimeGarfishReporter();
+
+export const garfishOptions = {
+  plugins: [createOpenRuntimeGarfishPlugin({ reporter })],
+  customLoader: createOpenRuntimeGarfishCustomLoader({ reporter }),
+};
+```
+
+If the host already has a `customLoader`, pass it through `loader` so
+OpenRuntime can wrap it instead of replacing it.
+
+### `modern:garfish`
+
+Type: `modern.garfish`
+
+Aggregate Garfish sub-application state for the current page.
+
+### `modern:garfish:app:<name>`
+
+Type: `modern.garfish.app`
+
+Per-sub-application state. The target records Garfish lifecycle state and
+whether `provider.render` / `provider.destroy` was called through the
+OpenRuntime custom loader.
+
+Statuses:
+
+- `idle`: no Garfish app has been observed yet.
+- `registered`: the app was registered.
+- `loading`: Garfish started loading the app.
+- `loaded`: Garfish loaded the app instance.
+- `evaluating`: a sub-application script started executing.
+- `evaluated`: a sub-application script executed.
+- `mounting`: Garfish started mounting the app.
+- `rendering`: `provider.render` was called through the OpenRuntime custom
+  loader.
+- `mounted`: Garfish mount completed.
+- `unmounting`: Garfish started unmounting or `provider.destroy` was called.
+- `unmounted`: Garfish unmount completed.
+- `error`: load, script execution, mount, or unmount failed.
+
+Common waits:
+
+```sh
+pnpm exec openruntime wait-for modern:garfish:app:orders mounted
+pnpm exec openruntime events --target-id modern:garfish:app:orders --limit 50
+```
+
+## Business Ready Target
+
+The package also exports helpers for business-owned readiness:
+
+- `registerOpenRuntimeReady`
+- `markOpenRuntimeReady`
+- `markOpenRuntimeReadyError`
+- `unregisterOpenRuntimeReady`
+
+These helpers use target ids shaped as `business:ready:<id>` and type
+`business.ready`.
+
+Statuses:
+
+- `pending`: business target is registered but not ready yet.
+- `ready`: business code marked the target as ready.
+- `error`: business code marked the target as failed.
+
+Business targets are owned by business code. If a route unmounts the business
+component, the component should call `unregisterOpenRuntimeReady` so stale
+business targets do not stay in later route snapshots.
+
+Example:
+
+```ts
+import {
+  markOpenRuntimeReady,
+  registerOpenRuntimeReady,
+  unregisterOpenRuntimeReady,
+} from "@openruntime/modern-plugin";
+import { getOpenRuntimeFromWindow } from "@openruntime/core";
+
+const runtime = getOpenRuntimeFromWindow();
+
+if (runtime) {
+  registerOpenRuntimeReady({
+    runtime,
+    id: "checkout",
+  });
+  markOpenRuntimeReady(runtime, "checkout", {
+    screen: "checkout",
+  });
+}
+
+// When the owning page or component unmounts:
+if (runtime) {
+  unregisterOpenRuntimeReady(runtime, "checkout");
+}
+```

package/dist/business/ready.d.ts

@@ -0,0 +1,13 @@
+import type { OpenRuntimeCore } from "@openruntime/core";
+export interface RegisterOpenRuntimeReadyOptions {
+    runtime: OpenRuntimeCore;
+    id?: string;
+    label?: string;
+    source?: string;
+    data?: unknown;
+}
+export declare function registerOpenRuntimeReady(options: RegisterOpenRuntimeReadyOptions): string;
+export declare function markOpenRuntimeReady(runtime: OpenRuntimeCore, id?: string, data?: unknown): void;
+export declare function markOpenRuntimeReadyError(runtime: OpenRuntimeCore, error: Error | string, id?: string): void;
+export declare function unregisterOpenRuntimeReady(runtime: OpenRuntimeCore, id?: string): void;
+//# sourceMappingURL=ready.d.ts.map

package/dist/business/ready.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ready.d.ts","sourceRoot":"","sources":["../../src/business/ready.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIzD,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,eAAe,CAAC;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,+BAA+B,GAAG,MAAM,CAsBzF;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EACxB,EAAE,CAAC,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,OAAO,GACb,IAAI,CAON;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,KAAK,GAAG,MAAM,EACrB,EAAE,CAAC,EAAE,MAAM,GACV,IAAI,CAUN;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAEtF"}

package/dist/business/ready.js

@@ -0,0 +1,48 @@
+const businessReadyStatuses = ["pending", "ready", "error"];
+export function registerOpenRuntimeReady(options) {
+    const targetId = getBusinessReadyTargetId(options.id);
+    const source = options.source ?? "business";
+    options.runtime.registerTarget({
+        id: targetId,
+        type: "business.ready",
+        source,
+        label: options.label ?? targetId,
+        statuses: [...businessReadyStatuses],
+        ...(options.data === undefined ? {} : { data: options.data })
+    });
+    if (options.runtime.getSnapshot({ id: targetId }).targets[targetId] === undefined) {
+        options.runtime.updateSnapshot({
+            id: targetId,
+            status: "pending",
+            source,
+            ...(options.data === undefined ? {} : { data: options.data })
+        });
+    }
+    return targetId;
+}
+export function markOpenRuntimeReady(runtime, id, data) {
+    runtime.updateSnapshot({
+        id: getBusinessReadyTargetId(id),
+        status: "ready",
+        source: "business",
+        ...(data === undefined ? {} : { data })
+    });
+}
+export function markOpenRuntimeReadyError(runtime, error, id) {
+    runtime.updateSnapshot({
+        id: getBusinessReadyTargetId(id),
+        status: "error",
+        source: "business",
+        error: {
+            message: typeof error === "string" ? error : error.message,
+            ...(typeof error === "string" || error.stack === undefined ? {} : { stack: error.stack })
+        }
+    });
+}
+export function unregisterOpenRuntimeReady(runtime, id) {
+    runtime.unregisterTarget(getBusinessReadyTargetId(id));
+}
+function getBusinessReadyTargetId(id = "app") {
+    return `business:ready:${id}`;
+}
+//# sourceMappingURL=ready.js.map

package/dist/business/ready.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ready.js","sourceRoot":"","sources":["../../src/business/ready.ts"],"names":[],"mappings":"AAEA,MAAM,qBAAqB,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AAUrE,MAAM,UAAU,wBAAwB,CAAC,OAAwC;IAC/E,MAAM,QAAQ,GAAG,wBAAwB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC;IAE5C,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC;QAC7B,EAAE,EAAE,QAAQ;QACZ,IAAI,EAAE,gBAAgB;QACtB,MAAM;QACN,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,QAAQ;QAChC,QAAQ,EAAE,CAAC,GAAG,qBAAqB,CAAC;QACpC,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;KAC9D,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,SAAS,EAAE,CAAC;QAClF,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC;YAC7B,EAAE,EAAE,QAAQ;YACZ,MAAM,EAAE,SAAS;YACjB,MAAM;YACN,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;SAC9D,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,OAAwB,EACxB,EAAW,EACX,IAAc;IAEd,OAAO,CAAC,cAAc,CAAC;QACrB,EAAE,EAAE,wBAAwB,CAAC,EAAE,CAAC;QAChC,MAAM,EAAE,OAAO;QACf,MAAM,EAAE,UAAU;QAClB,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;KACxC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,OAAwB,EACxB,KAAqB,EACrB,EAAW;IAEX,OAAO,CAAC,cAAc,CAAC;QACrB,EAAE,EAAE,wBAAwB,CAAC,EAAE,CAAC;QAChC,MAAM,EAAE,OAAO;QACf,MAAM,EAAE,UAAU;QAClB,KAAK,EAAE;YACL,OAAO,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO;YAC1D,GAAG,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;SAC1F;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,OAAwB,EAAE,EAAW;IAC9E,OAAO,CAAC,gBAAgB,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,wBAAwB,CAAC,EAAE,GAAG,KAAK;IAC1C,OAAO,kBAAkB,EAAE,EAAE,CAAC;AAChC,CAAC"}

package/dist/garfish/plugin.d.ts

@@ -0,0 +1,5 @@
+import type { GarfishCustomLoader, OpenRuntimeGarfishCustomLoaderOptions, OpenRuntimeGarfishPluginFactory, OpenRuntimeGarfishPluginOptions } from "./types.js";
+export declare function createOpenRuntimeGarfishPlugin(options?: OpenRuntimeGarfishPluginOptions): OpenRuntimeGarfishPluginFactory;
+export declare function createOpenRuntimeGarfishCustomLoader(options?: OpenRuntimeGarfishCustomLoaderOptions): GarfishCustomLoader;
+export type { GarfishAppInfoLike, GarfishAppInstanceLike, GarfishCustomLoader, GarfishExecOptionsLike, GarfishLoaderResult, GarfishProviderLike, OpenRuntimeGarfishCustomLoaderOptions, OpenRuntimeGarfishPlugin, OpenRuntimeGarfishPluginFactory, OpenRuntimeGarfishPluginOptions, OpenRuntimeGarfishReporter } from "./types.js";
+//# sourceMappingURL=plugin.d.ts.map

package/dist/garfish/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/garfish/plugin.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,mBAAmB,EAMnB,qCAAqC,EAErC,+BAA+B,EAC/B,+BAA+B,EAEhC,MAAM,YAAY,CAAC;AAEpB,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,+BAAoC,GAC5C,+BAA+B,CAsHjC;AAED,wBAAgB,oCAAoC,CAClD,OAAO,GAAE,qCAA0C,GAClD,mBAAmB,CASrB;AAsED,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,qCAAqC,EACrC,wBAAwB,EACxB,+BAA+B,EAC/B,+BAA+B,EAC/B,0BAA0B,EAC3B,MAAM,YAAY,CAAC"}

package/dist/garfish/plugin.js

@@ -0,0 +1,181 @@
+import { createOpenRuntimeGarfishReporter, resolveRenderPayloadAppInfo, toGarfishRuntimeError } from "./reporter.js";
+export function createOpenRuntimeGarfishPlugin(options = {}) {
+    const reporter = resolveReporter(options);
+    return () => ({
+        name: "@openruntime/garfish-plugin",
+        version: "0.1.0",
+        beforeRegisterApp(appInfo) {
+            for (const info of normalizeAppInfos(appInfo)) {
+                reporter.registerApp(info);
+            }
+        },
+        registerApp(apps) {
+            for (const info of normalizeAppInfos(apps)) {
+                reporter.registerApp(info);
+            }
+        },
+        beforeLoad(appInfo) {
+            reporter.updateApp(appInfo, "loading", {
+                lifecycle: "beforeLoad",
+                phase: "load"
+            });
+        },
+        afterLoad(appInfo, appInstance) {
+            const details = {
+                lifecycle: "afterLoad",
+                phase: "load"
+            };
+            reporter.updateApp(appInfo, "loaded", appInstance === undefined
+                ? details
+                : { ...details, appInstance });
+        },
+        errorLoadApp(error, appInfo) {
+            reporter.updateApp(appInfo, "error", {
+                lifecycle: "errorLoadApp",
+                phase: "load",
+                error: toGarfishRuntimeError(error, "garfish_load_error")
+            });
+        },
+        beforeEval(appInfo, _code, _env, scriptUrl, execOptions) {
+            reporter.updateApp(appInfo, "evaluating", {
+                lifecycle: "beforeEval",
+                phase: "eval",
+                ...(scriptUrl === undefined ? {} : { scriptUrl }),
+                ...(execOptions === undefined ? {} : { execOptions })
+            });
+        },
+        afterEval(appInfo, _code, _env, scriptUrl, execOptions) {
+            reporter.updateApp(appInfo, "evaluated", {
+                lifecycle: "afterEval",
+                phase: "eval",
+                ...(scriptUrl === undefined ? {} : { scriptUrl }),
+                ...(execOptions === undefined ? {} : { execOptions })
+            });
+        },
+        errorExecCode(error, appInfo, _code, _env, scriptUrl, execOptions) {
+            reporter.updateApp(appInfo, "error", {
+                lifecycle: "errorExecCode",
+                phase: "eval",
+                ...(scriptUrl === undefined ? {} : { scriptUrl }),
+                ...(execOptions === undefined ? {} : { execOptions }),
+                error: toGarfishRuntimeError(error, "garfish_exec_error")
+            });
+        },
+        beforeMount(appInfo, appInstance, cacheMode) {
+            const details = {
+                lifecycle: "beforeMount",
+                phase: "mount",
+                payload: { cacheMode }
+            };
+            reporter.updateApp(appInfo, "mounting", appInstance === undefined
+                ? details
+                : { ...details, appInstance });
+        },
+        afterMount(appInfo, appInstance, cacheMode) {
+            const details = {
+                lifecycle: "afterMount",
+                phase: "mount",
+                payload: { cacheMode }
+            };
+            reporter.updateApp(appInfo, "mounted", appInstance === undefined
+                ? details
+                : { ...details, appInstance });
+        },
+        errorMountApp(error, appInfo) {
+            reporter.updateApp(appInfo, "error", {
+                lifecycle: "errorMountApp",
+                phase: "mount",
+                error: toGarfishRuntimeError(error, "garfish_mount_error")
+            });
+        },
+        beforeUnmount(appInfo, appInstance, cacheMode) {
+            const details = {
+                lifecycle: "beforeUnmount",
+                phase: "unmount",
+                payload: { cacheMode }
+            };
+            reporter.updateApp(appInfo, "unmounting", appInstance === undefined
+                ? details
+                : { ...details, appInstance });
+        },
+        afterUnmount(appInfo, appInstance, cacheMode) {
+            const details = {
+                lifecycle: "afterUnmount",
+                phase: "unmount",
+                payload: { cacheMode }
+            };
+            reporter.updateApp(appInfo, "unmounted", appInstance === undefined
+                ? details
+                : { ...details, appInstance });
+        },
+        errorUnmountApp(error, appInfo) {
+            reporter.updateApp(appInfo, "error", {
+                lifecycle: "errorUnmountApp",
+                phase: "unmount",
+                error: toGarfishRuntimeError(error, "garfish_unmount_error")
+            });
+        }
+    });
+}
+export function createOpenRuntimeGarfishCustomLoader(options = {}) {
+    const reporter = resolveReporter(options);
+    return async (provider, appInfo, basename) => {
+        const baseResult = await options.loader?.(provider, appInfo, basename);
+        const targetResult = baseResult ?? createDefaultLoaderResult(provider);
+        return wrapLoaderResult(targetResult, appInfo, reporter);
+    };
+}
+function resolveReporter(options) {
+    return options.reporter ?? createOpenRuntimeGarfishReporter(options);
+}
+function wrapLoaderResult(result, appInfo, reporter) {
+    return {
+        ...(result.mount === undefined
+            ? {}
+            : {
+                mount(payload) {
+                    reporter.markProviderRenderCalled(resolveRenderPayloadAppInfo(appInfo, payload), payload);
+                    return result.mount?.(payload);
+                }
+            }),
+        ...(result.unmount === undefined
+            ? {}
+            : {
+                unmount(payload) {
+                    reporter.markProviderDestroyCalled(resolveRenderPayloadAppInfo(appInfo, payload), payload);
+                    return result.unmount?.(payload);
+                }
+            })
+    };
+}
+function createDefaultLoaderResult(provider) {
+    return {
+        ...(provider.render === undefined
+            ? {}
+            : {
+                mount(payload) {
+                    return provider.render?.(payload);
+                }
+            }),
+        ...(provider.destroy === undefined
+            ? {}
+            : {
+                unmount(payload) {
+                    return provider.destroy?.(payload);
+                }
+            })
+    };
+}
+function normalizeAppInfos(input) {
+    if (Array.isArray(input)) {
+        return input;
+    }
+    if (isAppInfo(input)) {
+        return [input];
+    }
+    return Object.values(input).filter(isAppInfo);
+}
+function isAppInfo(value) {
+    return typeof value === "object" && value !== null && "name" in value;
+}
+//# sourceMappingURL=plugin.js.map

package/dist/garfish/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/garfish/plugin.ts"],"names":[],"mappings":"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"}

package/dist/garfish/reporter.d.ts

@@ -0,0 +1,6 @@
+import type { RuntimeError } from "@openruntime/core";
+import { type GarfishAppInfoLike, type GarfishProviderDestroyPayload, type GarfishProviderRenderPayload, type OpenRuntimeGarfishReporter, type OpenRuntimeGarfishReporterOptions } from "./types.js";
+export declare function createOpenRuntimeGarfishReporter(options?: OpenRuntimeGarfishReporterOptions): OpenRuntimeGarfishReporter;
+export declare function toGarfishRuntimeError(error: unknown, code: string): RuntimeError;
+export declare function resolveRenderPayloadAppInfo(appInfo: GarfishAppInfoLike, payload: GarfishProviderRenderPayload | GarfishProviderDestroyPayload): GarfishAppInfoLike;
+//# sourceMappingURL=reporter.d.ts.map

package/dist/garfish/reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.d.ts","sourceRoot":"","sources":["../../src/garfish/reporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,YAAY,EACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAIL,KAAK,kBAAkB,EAGvB,KAAK,6BAA6B,EAClC,KAAK,4BAA4B,EAEjC,KAAK,0BAA0B,EAC/B,KAAK,iCAAiC,EAEvC,MAAM,YAAY,CAAC;AAkDpB,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE,iCAAsC,GAC9C,0BAA0B,CAE5B;AA8KD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CA4BhF;AAqLD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,4BAA4B,GAAG,6BAA6B,GACpE,kBAAkB,CAEpB"}