@savvifi/meridian-aion-web 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,71 @@
+# @savvifi/meridian-aion-web
+
+The **aion/web ↔ meridian-ux render seam**. Lets an SSR host (e.g. `aion/web` on
+Hono + Vite classic SSR) render aion **entity routes** through meridian-ux —
+`ViewDescriptor → muiKit` — instead of the legacy React entity-page path, behind a
+per-entity feature flag so parity can be proven before switching.
+
+Meridian owns everything from the composition down (project → render → paginate);
+the host keeps the SSR harness, the app shell, navigation, providers, and the
+session-bound tRPC caller.
+
+## Install
+
+```sh
+pnpm add @savvifi/meridian-aion-web
+```
+
+Peers the host provides: `react` `react-dom` (19), `@mui/material` (7),
+`@emotion/react` `@emotion/styled` (11), and `@aion/entity-route-runtime` (the
+composition loader + route parser — the host's version wins).
+
+## Server (SSR)
+
+```ts
+import { renderMeridianEntityView, NotFoundSignal } from "@savvifi/meridian-aion-web/server";
+
+const { node, dehydrated } = await renderMeridianEntityView({
+  pathname,          // "/entities/products" | "/entities/products/id/123"
+  caller,            // session-bound createCaller -> caller.entities.ops
+  graph,             // ctx.graph -> composition loader's systemGraphFactory
+  mode,              // "light" | "dark" (default "light")
+  // notFound: "throw" (default) throws NotFoundSignal; "return" -> { node: null }
+});
+// stream `node` as the page content; embed `dehydrated` = { viewJson, initialData }
+// in your boot script for the client.
+```
+
+`renderMeridianEntityView` parses the route, loads the installed composition,
+projects it to a `ViewDescriptor`, **pre-fetches page-0** through the caller (so the
+SSR HTML carries real rows), renders it through `muiKit` + the `savviSkin` theme,
+and returns the node plus the dehydrated payload.
+
+## Client (hydration)
+
+```tsx
+import { MeridianEntityView } from "@savvifi/meridian-aion-web/client";
+import { createEntityOpsInvoker } from "@savvifi/meridian-aion-web";
+
+// invoker over the app's browser tRPC client:
+const invoker = createEntityOpsInvoker(client.entities.ops);
+
+<MeridianEntityView
+  viewJson={dehydrated.viewJson}     // a JSON value, not a string
+  initialData={dehydrated.initialData}
+  invoker={invoker}
+  mode={mode}
+/>
+```
+
+`usePagedRows` (in `@savvifi/meridian-web-react`) seeds page-0 from `initialData`
+and skips the initial refetch, so hydration matches the server render with no flash.
+
+## Exports
+
+- `@savvifi/meridian-aion-web/server` — `renderMeridianEntityView`, `NotFoundSignal`, `isNotFoundSignal`, `savviSkin`
+- `@savvifi/meridian-aion-web/client` — `MeridianEntityView`, `savviSkin`
+- root — all of the above + `createEntityOpsInvoker`
+
+## License
+
+UNLICENSED — © savvifi.

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { renderMeridianEntityView, type RenderMeridianEntityViewInput, type RenderMeridianEntityViewResult, type MeridianDehydratedView, type EntityCaller, } from "./render-server.js";
+export { renderMeridianEntityView, renderCrdLayout, type RenderMeridianEntityViewInput, type RenderMeridianEntityViewResult, type MeridianDehydratedView, type EntityCaller, type RenderCrdLayoutInput, type LayoutFetcher, type CrdRpcInvoker, } from "./render-server.js";
 export { MeridianEntityView, type MeridianEntityViewProps } from "./render-client.js";
 export { savviSkin } from "./savvi-skin.js";
 export { NotFoundSignal, isNotFoundSignal } from "./not-found.js";
 export { createEntityOpsInvoker } from "@savvifi/meridian-aion-projection";
+export type { MeridianActionHandler } from "@savvifi/meridian-web-react";

package/dist/index.js

@@ -4,7 +4,7 @@
 // pre-fetch page-0 -> render + dehydrate). Client: MeridianEntityView (hydrate).
 // Plus savviSkin (the brand Theme proto) and createEntityOpsInvoker (build a
 // meridian RpcInvoker over a tRPC caller/client's entities.ops).
-export { renderMeridianEntityView, } from "./render-server.js";
+export { renderMeridianEntityView, renderCrdLayout, } from "./render-server.js";
 export { MeridianEntityView } from "./render-client.js";
 export { savviSkin } from "./savvi-skin.js";
 export { NotFoundSignal, isNotFoundSignal } from "./not-found.js";

package/dist/render-client.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from "react";
 import type { RpcInvoker } from "@savvifi/meridian-schemas/uiview";
-import { type MeridianInitialData } from "@savvifi/meridian-web-react";
+import { type MeridianActionHandler, type MeridianInitialData } from "@savvifi/meridian-web-react";
 export interface MeridianEntityViewProps {
     /** The dehydrated ViewDescriptor JSON value (from the server render). */
     viewJson: unknown;
@@ -10,5 +10,11 @@ export interface MeridianEntityViewProps {
     invoker: RpcInvoker;
     /** Resolved color mode; must match the server render for clean hydration. */
     mode?: "light" | "dark";
+    /**
+     * Host handler for no-call actions (view_details / edit / create …). The host
+     * wires this to its router — e.g. `(actionId, entityType, entityId) => nav(...)`.
+     * Client-only (SSR renders the same markup; onClick handlers aren't serialized).
+     */
+    onAction?: MeridianActionHandler;
 }
-export declare function MeridianEntityView({ viewJson, initialData, invoker, mode, }: MeridianEntityViewProps): ReactNode;
+export declare function MeridianEntityView({ viewJson, initialData, invoker, mode, onAction, }: MeridianEntityViewProps): ReactNode;

package/dist/render-client.js

@@ -6,10 +6,10 @@
 import { createElement } from "react";
 import { fromJson } from "@bufbuild/protobuf";
 import { ViewDescriptorSchema } from "@savvifi/meridian-proto-ts/proto/view_pb.js";
-import { ViewRenderer } from "@savvifi/meridian-web-react";
+import { ViewRenderer, } from "@savvifi/meridian-web-react";
 import { MeridianMuiProvider } from "@savvifi/meridian-mui-kit";
 import { savviSkin } from "./savvi-skin.js";
-export function MeridianEntityView({ viewJson, initialData, invoker, mode = "light", }) {
+export function MeridianEntityView({ viewJson, initialData, invoker, mode = "light", onAction, }) {
     const view = fromJson(ViewDescriptorSchema, viewJson);
-    return createElement(MeridianMuiProvider, { invoker, theme: savviSkin, mode }, createElement(ViewRenderer, { view, initialData }));
+    return createElement(MeridianMuiProvider, { invoker, theme: savviSkin, mode, onAction }, createElement(ViewRenderer, { view, initialData }));
 }

package/dist/render-server.d.ts

@@ -33,3 +33,28 @@ export interface RenderMeridianEntityViewResult {
     dehydrated: MeridianDehydratedView | null;
 }
 export declare function renderMeridianEntityView(input: RenderMeridianEntityViewInput): Promise<RenderMeridianEntityViewResult>;
+/** The host-supplied transport that fetches a Layout's ViewDescriptor as proto-JSON.
+ *  Abstracted so the gRPC client (Connect / grpc-js) is a host adapter, not a dep of
+ *  this package — it calls `LayoutService.GetLayout({ name })` and returns
+ *  `toJson(ViewDescriptorSchema, layout.viewDescriptor)`. */
+export type LayoutFetcher = (name: string) => Promise<unknown>;
+/** An RpcInvoker (one method) that dispatches a panel's RpcCall. For CRD layouts the
+ *  RpcCalls target `meridian.k8s.backend.Kubernetes`, so this must reach the K8s API
+ *  (or the meridian-k8s backend) rather than the tRPC entity-ops root. */
+export interface CrdRpcInvoker {
+    invoke(service: string, method: string, request: object): Promise<object>;
+}
+export interface RenderCrdLayoutInput {
+    /** CRD kind id (the CRD name), e.g. `instances.aion.savvifi.com`. */
+    kind: string;
+    /** Which layout to render. Default "detail". */
+    view?: "list" | "detail";
+    /** Fetches the ViewDescriptor proto-JSON from the meridian-k8s LayoutService. */
+    fetchLayout: LayoutFetcher;
+    /** Dispatches the layout's RpcCalls (meridian-k8s / K8s backend). */
+    invoker: CrdRpcInvoker;
+    /** Resolved color mode; default "light". */
+    mode?: "light" | "dark";
+}
+/** Fetch a meridian-k8s Layout and render it exactly like a projected entity view. */
+export declare function renderCrdLayout(input: RenderCrdLayoutInput): Promise<RenderMeridianEntityViewResult>;

package/dist/render-server.js

@@ -6,7 +6,7 @@
 // The host owns the SSR harness (renderToPipeableStream), the session-bound
 // caller, and the graph; meridian owns everything from the composition down.
 import { createElement } from "react";
-import { toJson } from "@bufbuild/protobuf";
+import { fromJson, toJson } from "@bufbuild/protobuf";
 import { ViewDescriptorSchema } from "@savvifi/meridian-proto-ts/proto/view_pb.js";
 import { createEntityOpsInvoker, projectEntityView, } from "@savvifi/meridian-aion-projection";
 import { buildPageRequest, readPage, ViewRenderer, } from "@savvifi/meridian-web-react";
@@ -72,3 +72,30 @@ export async function renderMeridianEntityView(input) {
         dehydrated: { viewJson: toJson(ViewDescriptorSchema, view), initialData },
     };
 }
+/** Fetch a meridian-k8s Layout and render it exactly like a projected entity view. */
+export async function renderCrdLayout(input) {
+    const { kind, view = "detail", fetchLayout, invoker, mode = "light" } = input;
+    const name = `kinds/${kind}/layouts/${view}`;
+    const viewJson = await fetchLayout(name);
+    // Normalize through the canonical schema — the same message ViewRenderer consumes,
+    // whether it was projected (renderMeridianEntityView) or fetched (here).
+    const descriptor = fromJson(ViewDescriptorSchema, viewJson);
+    // Pre-fetch page-0 for the first table (non-fatal), identical to the entity path.
+    const initialData = {};
+    const table = firstTablePanel(descriptor);
+    if (table?.populate) {
+        try {
+            const request = buildPageRequest(table.pagination, { page: 0 });
+            const response = await invoker.invoke(table.populate.service, table.populate.method, request);
+            initialData[`${table.populate.service}.${table.populate.method}`] = readPage(table.pagination, response, table.rowsField);
+        }
+        catch {
+            // leave unseeded
+        }
+    }
+    const node = createElement(MeridianMuiProvider, { invoker, theme: savviSkin, mode }, createElement(ViewRenderer, { view: descriptor, initialData }));
+    return {
+        node,
+        dehydrated: { viewJson: toJson(ViewDescriptorSchema, descriptor), initialData },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@savvifi/meridian-aion-web",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "The aion/web <-> meridian-ux render seam: renderMeridianEntityView (server — parse route, load composition, project to a ViewDescriptor, pre-fetch page-0, render + dehydrate) + MeridianEntityView (client hydration) + savviSkin. Lets an SSR host (e.g. aion/web on Hono+Vite) render entity routes through meridian instead of the legacy React path.",
   "publishConfig": {
@@ -37,10 +37,10 @@
   },
   "dependencies": {
     "@savvifi/meridian-aion-projection": "^0.2.2",
-    "@savvifi/meridian-mui-kit": "^0.1.0",
-    "@savvifi/meridian-proto-ts": "^0.3.0",
-    "@savvifi/meridian-schemas": "^0.3.0",
-    "@savvifi/meridian-web-react": "^0.3.3",
+    "@savvifi/meridian-mui-kit": "^0.2.0",
+    "@savvifi/meridian-proto-ts": "^0.5.0",
+    "@savvifi/meridian-schemas": "^0.5.0",
+    "@savvifi/meridian-web-react": "^0.4.0",
     "@bufbuild/protobuf": "2.12.1"
   },
   "peerDependencies": {