@savvifi/meridian-aion-web 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { renderMeridianEntityView, type RenderMeridianEntityViewInput, type RenderMeridianEntityViewResult, type MeridianDehydratedView, type EntityCaller, } 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";

package/dist/index.js

@@ -0,0 +1,11 @@
+// @savvifi/meridian-aion-web — the aion/web <-> meridian-ux render seam.
+//
+// Server: renderMeridianEntityView (parse route -> load composition -> project ->
+// 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 { MeridianEntityView } from "./render-client.js";
+export { savviSkin } from "./savvi-skin.js";
+export { NotFoundSignal, isNotFoundSignal } from "./not-found.js";
+export { createEntityOpsInvoker } from "@savvifi/meridian-aion-projection";

package/dist/not-found.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Thrown by renderMeridianEntityView when a route is not a valid entity route or
+ * has no installed composition — so the SSR host can catch it and serve a 404
+ * (cleaner than branching on a null node). Pass `notFound: "return"` to get
+ * `{ node: null }` instead of a throw.
+ */
+export declare class NotFoundSignal extends Error {
+    readonly pathname?: string | undefined;
+    /** Discriminant so hosts can detect it across module/realm boundaries. */
+    readonly kind: "meridian-not-found";
+    constructor(pathname?: string | undefined);
+}
+export declare function isNotFoundSignal(error: unknown): error is NotFoundSignal;

package/dist/not-found.js

@@ -0,0 +1,22 @@
+/**
+ * Thrown by renderMeridianEntityView when a route is not a valid entity route or
+ * has no installed composition — so the SSR host can catch it and serve a 404
+ * (cleaner than branching on a null node). Pass `notFound: "return"` to get
+ * `{ node: null }` instead of a throw.
+ */
+export class NotFoundSignal extends Error {
+    pathname;
+    /** Discriminant so hosts can detect it across module/realm boundaries. */
+    kind = "meridian-not-found";
+    constructor(pathname) {
+        super(pathname ? `No meridian entity view for route: ${pathname}` : "No meridian entity view for route");
+        this.pathname = pathname;
+        this.name = "NotFoundSignal";
+    }
+}
+export function isNotFoundSignal(error) {
+    return (error instanceof NotFoundSignal ||
+        (typeof error === "object" &&
+            error !== null &&
+            error.kind === "meridian-not-found"));
+}

package/dist/render-client.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from "react";
+import type { RpcInvoker } from "@savvifi/meridian-schemas/uiview";
+import { type MeridianInitialData } from "@savvifi/meridian-web-react";
+export interface MeridianEntityViewProps {
+    /** The dehydrated ViewDescriptor JSON value (from the server render). */
+    viewJson: unknown;
+    /** The dehydrated page-0 seed (keyed by `${service}.${method}`). */
+    initialData: MeridianInitialData;
+    /** Browser invoker over the app tRPC client (`createEntityOpsInvoker(client.entities.ops)`). */
+    invoker: RpcInvoker;
+    /** Resolved color mode; must match the server render for clean hydration. */
+    mode?: "light" | "dark";
+}
+export declare function MeridianEntityView({ viewJson, initialData, invoker, mode, }: MeridianEntityViewProps): ReactNode;

package/dist/render-client.js

@@ -0,0 +1,15 @@
+// MeridianEntityView — the client hydration counterpart. The host reads the
+// dehydrated `{ viewJson, initialData }` from its boot script, builds a browser
+// invoker over its tRPC client (`createEntityOpsInvoker(client.entities.ops)`),
+// and mounts this — hydrating the SSR-rendered node in place. Subsequent pages
+// and actions flow through the browser invoker.
+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 { MeridianMuiProvider } from "@savvifi/meridian-mui-kit";
+import { savviSkin } from "./savvi-skin.js";
+export function MeridianEntityView({ viewJson, initialData, invoker, mode = "light", }) {
+    const view = fromJson(ViewDescriptorSchema, viewJson);
+    return createElement(MeridianMuiProvider, { invoker, theme: savviSkin, mode }, createElement(ViewRenderer, { view, initialData }));
+}

package/dist/render-server.d.ts

@@ -0,0 +1,35 @@
+import { type ReactNode } from "react";
+import { type EntityOpsRoot } from "@savvifi/meridian-aion-projection";
+import { type MeridianInitialData } from "@savvifi/meridian-web-react";
+import { type CompositionGraphClient } from "@aion/entity-route-runtime/composition/loader.js";
+/** A tRPC caller/client exposing entity ops at `entities.ops[modulePath][proc]`. */
+export interface EntityCaller {
+    entities?: {
+        ops?: EntityOpsRoot;
+    };
+}
+export interface RenderMeridianEntityViewInput {
+    /** The request pathname, e.g. `/entities/products` or `/entities/products/id/123`. */
+    pathname: string;
+    /** Reserved for filter/pagination binding (unused in the first cut). */
+    searchParams?: URLSearchParams | Record<string, string>;
+    /** Session-bound server caller (e.g. `studioAppRouter().createCaller(ctx)`). */
+    caller: EntityCaller;
+    /** The request's graph client (`ctx.graph`) for the composition loader. */
+    graph: CompositionGraphClient;
+    /** Resolved color mode (from the host's theme cookie); default "light". */
+    mode?: "light" | "dark";
+    /** Not-found behavior: "throw" a NotFoundSignal (default) or "return" `{node:null}`. */
+    notFound?: "throw" | "return";
+}
+export interface MeridianDehydratedView {
+    /** The projected ViewDescriptor as a JSON value (embed in the boot script). */
+    viewJson: unknown;
+    /** Pre-fetched page-0 rows keyed by `${service}.${method}` for the client seed. */
+    initialData: MeridianInitialData;
+}
+export interface RenderMeridianEntityViewResult {
+    node: ReactNode | null;
+    dehydrated: MeridianDehydratedView | null;
+}
+export declare function renderMeridianEntityView(input: RenderMeridianEntityViewInput): Promise<RenderMeridianEntityViewResult>;

package/dist/render-server.js

@@ -0,0 +1,74 @@
+// renderMeridianEntityView — the SSR entry. Parses an entity route, loads its
+// installed composition, projects it to a meridian ViewDescriptor, pre-fetches
+// page-0 through the request-scoped caller, and returns a rendered React node +
+// a dehydrated payload for the client to hydrate against.
+//
+// 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 { 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";
+import { MeridianMuiProvider } from "@savvifi/meridian-mui-kit";
+import { parseAndValidateEntityRoute } from "@aion/entity-route-runtime/entity-route/index.js";
+import { loadInstalledEntityDetailCompositions, loadInstalledEntityListCompositions, } from "@aion/entity-route-runtime/composition/loader.js";
+import { savviSkin } from "./savvi-skin.js";
+import { NotFoundSignal } from "./not-found.js";
+/** `/entities/products/id/123` → `["products","id","123"]` (strip the prefix). */
+function routeSegments(pathname) {
+    const parts = pathname.replace(/^\/+|\/+$/g, "").split("/");
+    const at = parts.indexOf("entities");
+    return at >= 0 ? parts.slice(at + 1) : parts;
+}
+/** The first table panel in a projected view (the list/related-items table). */
+function firstTablePanel(view) {
+    for (const slot of view.slots) {
+        const body = slot.panel?.body;
+        if (body?.case === "table")
+            return body.value;
+    }
+    return undefined;
+}
+export async function renderMeridianEntityView(input) {
+    const { caller, graph, mode = "light", notFound = "throw" } = input;
+    const parsed = parseAndValidateEntityRoute(routeSegments(input.pathname));
+    const miss = () => {
+        if (notFound === "return")
+            return { node: null, dehydrated: null };
+        throw new NotFoundSignal(input.pathname);
+    };
+    if (!parsed.success)
+        return miss();
+    const { entityType, entityId } = parsed.parsed;
+    const kind = entityId ? "detail" : "list";
+    const systemGraphFactory = async () => graph;
+    const compositions = kind === "detail"
+        ? await loadInstalledEntityDetailCompositions({ systemGraphFactory })
+        : await loadInstalledEntityListCompositions({ systemGraphFactory });
+    const composition = compositions[entityType];
+    if (!composition)
+        return miss();
+    const view = projectEntityView(composition, { kind });
+    const invoker = createEntityOpsInvoker(caller.entities?.ops);
+    // Pre-fetch page-0 for the table so the SSR HTML carries real rows (and the
+    // client hydrates without an immediate refetch). Non-fatal: on failure we
+    // leave it unseeded and the client fetches on mount.
+    const initialData = {};
+    const table = firstTablePanel(view);
+    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, initialData }));
+    return {
+        node,
+        dehydrated: { viewJson: toJson(ViewDescriptorSchema, view), initialData },
+    };
+}

package/dist/savvi-skin.d.ts

@@ -0,0 +1,8 @@
+import { type Theme } from "@savvifi/meridian-proto-ts/proto/theme_pb.js";
+/**
+ * The savvi brand skin as a meridian Theme proto — seeded from studio's current
+ * MUI palette (light + dark). A convenience default so the meridian render path
+ * matches the existing look immediately; long-term the brand values graduate to
+ * `aion/brand` and hosts pass their own Theme proto to override.
+ */
+export declare const savviSkin: Theme;

package/dist/savvi-skin.js

@@ -0,0 +1,29 @@
+import { create } from "@bufbuild/protobuf";
+import { PaletteSchema, ThemeSchema, } from "@savvifi/meridian-proto-ts/proto/theme_pb.js";
+/**
+ * The savvi brand skin as a meridian Theme proto — seeded from studio's current
+ * MUI palette (light + dark). A convenience default so the meridian render path
+ * matches the existing look immediately; long-term the brand values graduate to
+ * `aion/brand` and hosts pass their own Theme proto to override.
+ */
+export const savviSkin = create(ThemeSchema, {
+    id: "savvi",
+    light: create(PaletteSchema, {
+        bg: "#f5f5f5",
+        surface: "#ffffff",
+        fg: "#333333",
+        muted: "#666666",
+        border: "#e0e0e0",
+        accent: "#1976d2",
+        accentStrong: "#1565c0",
+    }),
+    dark: create(PaletteSchema, {
+        bg: "#121212",
+        surface: "#1e1e1e",
+        fg: "#ffffff",
+        muted: "#b0b0b0",
+        border: "#333333",
+        accent: "#90caf9",
+        accentStrong: "#648dae",
+    }),
+});

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@savvifi/meridian-aion-web",
+  "version": "0.1.0",
+  "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": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meridian-ux/meridian-aion-web.git"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/render-server.d.ts",
+      "default": "./dist/render-server.js"
+    },
+    "./client": {
+      "types": "./dist/render-client.d.ts",
+      "default": "./dist/render-client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "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",
+    "@bufbuild/protobuf": "2.12.1"
+  },
+  "peerDependencies": {
+    "@aion/entity-route-runtime": ">=0.1.1",
+    "@emotion/react": "^11.0.0",
+    "@emotion/styled": "^11.0.0",
+    "@mui/material": "^7.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@aion/entity-route-runtime": "^0.2.1",
+    "@emotion/react": "11.14.0",
+    "@emotion/styled": "11.14.0",
+    "@mui/material": "7.3.7",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "typescript": "5.6.2"
+  }
+}