@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui-runtime/mount.ts

@@ -0,0 +1,367 @@
+// Iframe runtime — mount one surface and proxy its loader/action calls
+// to the parent window over postMessage. The iframe runs in an opaque
+// origin (sandbox="allow-scripts allow-forms" without allow-same-origin)
+// and never fetches Home directly; the parent makes authenticated
+// requests on its behalf and posts results back.
+//
+// State is owned by tanstack-query: each mount() gets its own
+// QueryClient. The render fn receives prebuilt handles — `loaders.X`
+// (a UseQueryResult) and `actions.Y` (a UseMutationResult) — instead of
+// calling hooks itself, plus the widget's own `state`/`setState`/`reset`
+// and resolved `config`. A loader's bundled `request(state, config)`
+// builds the call (or returns `null` for idle/lazy); Home prefills the
+// eager ones and inlines the results as `initialData`, so those handles
+// carry `data` on first paint.
+
+import { type ComponentChildren, h, render } from "preact";
+import { useState } from "preact/hooks";
+import {
+  QueryClient,
+  QueryClientProvider,
+  useMutation,
+  type UseMutationResult,
+  useQuery,
+  type UseQueryResult,
+} from "@tanstack/react-query";
+import type { LoaderQueryOptions, RequestShape } from "../ui-surface.ts";
+import {
+  isTransientUiError,
+  readUiFailure,
+  type UiErrorCode,
+  uiErrorFromFailure,
+} from "../ui-error.ts";
+
+interface SurfaceLoader {
+  // The bundled surface object retains the author's runtime `merge`
+  // callback (closured over the original surface). Home's manifest only
+  // sees `merge: true` and decides to fan out; the iframe still has the
+  // function and applies it to the `{ results: [...] }` envelope.
+  // deno-lint-ignore no-explicit-any
+  merge?: (results: any[]) => any;
+  // The bundled stitch fn: builds the call from the widget's state +
+  // config, or returns `null` when the state isn't ready (→ idle/lazy).
+  // Rides the bundle (never crosses QuickJS) so it keeps its closure.
+  request: (state: unknown, config: unknown) => RequestShape | null;
+  // Ships on the loader definition (rides the bundle like `merge`) so a
+  // *function* interval (e.g. `(q) => building ? 2000 : false`) survives
+  // — a function can't cross the JSON manifest / QuickJS boundary.
+  refetchInterval?: LoaderQueryOptions["refetchInterval"];
+}
+
+interface SurfaceAction {
+  // Builds the call from the caller's `mutate(input)` argument + config.
+  request: (input: unknown, config: unknown) => RequestShape;
+}
+
+interface RenderApi {
+  loaders: Record<string, UseQueryResult<unknown, Error>>;
+  actions: Record<string, UseMutationResult<unknown, Error, unknown>>;
+  // The widget's live UI state (read-only here; mutate via setState).
+  state: unknown;
+  setState: (patch: Record<string, unknown>) => void;
+  reset: () => void;
+  // The surface's resolved config (settings set outside the widget).
+  config: unknown;
+  queryClient: QueryClient;
+}
+
+interface SurfaceLike {
+  title: string;
+  // The live state schema rides the bundle; its `{}`-parse seeds the
+  // widget's initial state.
+  stateSchema?: { safeParse(v: unknown): { success: boolean; data?: unknown } };
+  loaders?: Record<string, SurfaceLoader>;
+  actions?: Record<string, SurfaceAction>;
+  render: (api: RenderApi) => ComponentChildren;
+}
+
+// No appId/kind/key: the parent stamped all three on this iframe's src and
+// reads them back from there. A sandboxed surface can only send what
+// genuinely originates inside it, so there is nothing here to forge.
+interface MountOpts {
+  surface: SurfaceLike;
+  container: Element;
+  // The surface's resolved config, inlined by Home. A loader/action's
+  // `request(state, config)` reads it. Absent → `{}`.
+  config?: unknown;
+  // Server-prefilled loader results, keyed by loader name. Present for
+  // eager loaders Home could run (their `request` returned a shape at the
+  // default state); missing entries degrade to fetch-on-mount. Same shape
+  // as the loader's queryFn output *before* merge, so the runtime applies
+  // merge to it too — see `applyMerge`.
+  initialData?: Record<string, unknown>;
+}
+
+interface PendingHandler {
+  resolve: (data: unknown) => void;
+  reject: (err: Error) => void;
+}
+
+let nextCallId = 1;
+const pending = new Map<number, PendingHandler>();
+let listenerAttached = false;
+
+function attachListener(): void {
+  if (listenerAttached) return;
+  listenerAttached = true;
+  globalThis.addEventListener("message", (ev: MessageEvent) => {
+    // Only the parent brokers ui-responses. Sibling iframes (and browser
+    // extensions injecting into them) can postMessage to us via
+    // `parent.frames[i]`, so without this check a forged response with
+    // a guessed `id` would resolve a pending loader with attacker data.
+    if (ev.source !== globalThis.parent) return;
+    const m = ev.data as {
+      realm?: string;
+      id?: number;
+      data?: unknown;
+      error?: string;
+      code?: UiErrorCode;
+    } | null;
+    if (!m || m.realm !== "ui-response" || typeof m.id !== "number") return;
+    const handler = pending.get(m.id);
+    if (!handler) return;
+    pending.delete(m.id);
+    if (typeof m.error === "string") {
+      // A coded failure rejects with a UiError so the surface (and the
+      // initial-load gate below) can branch on `code` — e.g. tell a
+      // transient boot window from a crashed container. `readUiFailure`
+      // validates the code against the known set rather than trusting the
+      // parent frame's string; an uncoded or unrecognized failure stays a
+      // plain Error and falls through to the author's branch.
+      const failure = readUiFailure({ error: m.error, code: m.code });
+      handler.reject(failure ? uiErrorFromFailure(failure) : new Error(m.error));
+    } else {
+      handler.resolve(m.data);
+    }
+  });
+}
+
+// Self-evict orphaned pending entries. Worker has a 30s upstream cap,
+// Home→Worker has 35s, so a real reply always arrives within ~35s. Set
+// the iframe-side timeout slightly higher so a slow round-trip wins
+// over our local fallback when both fire close together.
+const PENDING_TIMEOUT_MS = 40_000;
+
+type Endpoint = "loader" | "action";
+
+// Send the built request shape to the parent, which makes the
+// authenticated call to Home and posts the result back. `request` is the
+// `{ method, path, query, body }` a loader/action's stitch fn produced —
+// Home layers on `service`/`port`/headers (the grant boundary + secrets)
+// from the manifest and forwards to the worker.
+function callParent(endpoint: Endpoint, name: string, request: RequestShape): Promise<unknown> {
+  const id = nextCallId++;
+  return new Promise<unknown>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      if (pending.delete(id)) {
+        reject(
+          new Error(`ui-runtime: ${endpoint} "${name}" timed out after ${PENDING_TIMEOUT_MS}ms`),
+        );
+      }
+    }, PENDING_TIMEOUT_MS);
+    // Wrap the resolvers to clear the timer when a real reply arrives.
+    pending.set(id, {
+      resolve: (data) => {
+        clearTimeout(timer);
+        resolve(data);
+      },
+      reject: (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    });
+    const message = {
+      realm: "ui-call",
+      id,
+      endpoint,
+      name,
+      request,
+    };
+    // Parent's message listener validates `event.source` against the
+    // iframe's contentWindow so a "*" target here is fine — only the
+    // intended parent will accept the message.
+    (globalThis as unknown as { parent: Window }).parent.postMessage(message, "*");
+  });
+}
+
+// merge loaders return `{ results: [...] }` — one `{ data, workerId }` per
+// worker that answered; the author's merge() reduces them to the declared
+// output shape. Applied in both the queryFn (live fetch) and over
+// `initialData` (server prefill) so the cached value is the same shape either
+// way. Non-merge loaders and non-envelope values pass through untouched.
+function applyMerge(loader: SurfaceLoader, raw: unknown): unknown {
+  if (raw && typeof raw === "object" && "results" in raw && typeof loader.merge === "function") {
+    return loader.merge((raw as { results: unknown[] }).results);
+  }
+  return raw;
+}
+
+export function mount(opts: MountOpts): void {
+  attachListener();
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        // The iframe is sandboxed and never visibly refocuses on its
+        // own; turn off focus refetch so behavior stays predictable
+        // regardless of how the host page swaps tabs.
+        refetchOnWindowFocus: false,
+        retry: false,
+      },
+    },
+  });
+
+  // The widget's config (resolved by Home) and initial state (the live
+  // stateSchema's `{}`-parse). `seedState` is a stable reference so
+  // `initialData` applies only while the widget is still at its seed: that
+  // gates the prefill to the query key Home actually ran to produce it
+  // (`request(seedState, config)`), so a re-keyed loader can't inherit it.
+  const config = opts.config ?? {};
+  const seedParse = opts.surface.stateSchema?.safeParse({});
+  const seedState: unknown = seedParse?.success ? seedParse.data : {};
+
+  // Capture the loader/action name sets ONCE, before the component
+  // renders. The render loop calls one useQuery per loader and one
+  // useMutation per action in this fixed order every render —
+  // rules-of-hooks safe precisely because the set never changes for a
+  // given mount. Never filter these lists conditionally.
+  const loaderSetup = Object.entries(opts.surface.loaders ?? {});
+  const actionSetup = Object.entries(opts.surface.actions ?? {});
+
+  function SurfaceRoot() {
+    // ONE state object for the whole widget — shared across its loaders.
+    const [state, setState] = useState<unknown>(seedState);
+
+    const loaders: Record<string, UseQueryResult<unknown, Error>> = {};
+    for (const [name, loader] of loaderSetup) {
+      // Build this loader's call from the current state + config. `null`
+      // → not ready (idle/lazy); a shape → run it, keyed on the shape so
+      // it re-fetches only when its own request changes. A throwing
+      // request() counts as idle — mirrors the server prefill (stitchSnippet
+      // catches → lazy), so one broken loader can't blank the mount.
+      let request: RequestShape | null;
+      try {
+        request = loader.request(state, config);
+      } catch (err) {
+        console.error(`[realm] loader "${name}" request() threw; treating as idle`, err);
+        request = null;
+      }
+      // Server-prefilled seed data is fresh — Home just ran this loader while
+      // building the shell — so staleTime Infinity keeps the query from
+      // re-fetching on mount and churning the result. A setState re-keys to a
+      // new query with no initialData (staleTime 0 → fetches normally);
+      // refetchInterval and an explicit .refetch() still override staleTime.
+      const prefilled =
+        state === seedState ? applyMerge(loader, opts.initialData?.[name]) : undefined;
+      loaders[name] = useQuery({
+        queryKey: ["loader", name, request],
+        enabled: request !== null,
+        initialData: prefilled,
+        staleTime: prefilled !== undefined ? Infinity : 0,
+        queryFn: async () =>
+          applyMerge(loader, await callParent("loader", name, request as RequestShape)),
+        refetchInterval: loader.refetchInterval,
+      });
+    }
+
+    const actions: Record<string, UseMutationResult<unknown, Error, unknown>> = {};
+    for (const [name, action] of actionSetup) {
+      // No queryKey for mutations — invalidation is the author's job (via
+      // a loader handle's `.refetch()` or `queryClient.invalidateQueries`).
+      // The stitch fn builds the call from the mutate argument + config.
+      actions[name] = useMutation({
+        mutationFn: (input: unknown) => callParent("action", name, action.request(input, config)),
+      });
+    }
+
+    // Initial-load boot state: while an eager loader has produced no data,
+    // render a centered boot state in place of the surface rather than let
+    // the author's render fn paint a half-empty tile (success branch with
+    // `data === undefined`) or a raw error string. `data === undefined` is
+    // what keeps this to the *initial* load — once a loader has succeeded its
+    // data stays set, so a later background refetch shows stale data rather
+    // than flipping back to a spinner. Two flavors:
+    //   - first fetch in flight (`isFetching`, no data, no error) → "Loading…"
+    //   - first fetch failed with a transient UiError (CONTAINER_STARTING) →
+    //     "Container starting…"
+    // Hard codes (CONTAINER_CRASHED, UPSTREAM_*, …) and plain Errors fall
+    // through to the author's own error branch.
+    //
+    // `isFetching`, not `isPending`: `isPending` is true for ANY query with no
+    // cached data, including a disabled lazy loader that has never fetched, so
+    // gating on it would pin a lazy widget on "Loading…" forever.
+    //
+    // The `polls` guard is the "does it ever clear" condition for the ERROR
+    // case: a transient-error spinner clears only when the loader's poll timer
+    // re-fires and the tick that returns data re-renders the live surface. A
+    // loader with no active poll falls through to the author's branch instead
+    // of promising a recovery nothing delivers. (The in-flight case clears on
+    // the in-flight fetch itself, so it needs no poll.)
+    for (const [name, def] of loaderSetup) {
+      const loader = loaders[name]!;
+      if (loader.data !== undefined) continue;
+      const polls = def.refetchInterval !== undefined && def.refetchInterval !== false;
+      const inFlight = loader.isFetching;
+      const booting = polls && isTransientUiError(loader.error);
+      if (inFlight || booting) {
+        return h(
+          "div",
+          { class: "flex h-full flex-col items-center justify-center gap-2 p-3 bg-sidebar" },
+          h("span", { class: "realm-boot-spinner", "aria-hidden": "true" }),
+          h(
+            "p",
+            { class: "text-sm text-muted-foreground" },
+            booting ? "Container starting…" : "Loading…",
+          ),
+        );
+      }
+    }
+
+    return opts.surface.render({
+      loaders,
+      actions,
+      state,
+      setState: (patch: Record<string, unknown>) =>
+        setState((prev: unknown) => ({ ...(prev as Record<string, unknown>), ...patch })),
+      reset: () => setState(seedState),
+      config,
+      queryClient,
+    });
+  }
+
+  render(h(QueryClientProvider, { client: queryClient }, h(SurfaceRoot, null)), opts.container);
+}
+
+// Rendered in a widget iframe in place of the surface when its resolved config
+// doesn't satisfy the widget's declared configSchema (a required field left
+// unset, with no prefill). The author's render/loaders never run — their
+// `config` is typed non-optional. The operator gets a Configure button that
+// asks the parent to open this tile's config dialog; the parent maps the
+// pid → placement.
+export function mountNeedsConfig(opts: { container: Element; title: string; pid: string }): void {
+  function configure() {
+    (globalThis as unknown as { parent: Window }).parent.postMessage(
+      { realm: "ui-configure", pid: opts.pid },
+      "*",
+    );
+  }
+  render(
+    h(
+      "div",
+      {
+        class: "flex h-full flex-col items-center justify-center gap-2 bg-sidebar p-3 text-center",
+      },
+      h("p", { class: "text-xs text-muted-foreground" }, `${opts.title} needs setup`),
+      h(
+        "button",
+        {
+          type: "button",
+          onClick: configure,
+          class:
+            "cursor-pointer rounded-lg bg-primary px-3 py-1.5 text-xs font-medium text-primary-foreground hover:bg-primary/90",
+        },
+        "Configure",
+      ),
+    ),
+    opts.container,
+  );
+}

package/src/ui-runtime/runtime.css

@@ -0,0 +1,56 @@
+/*
+ * Iframe runtime CSS. Built by `realm-sdk build-runtime` via the
+ * tailwindcss CLI. Carries chrome only — clay tokens (from
+ * `@yourrealm/sdk/ui/tokens.css`), the SDK UI base layer, and every
+ * utility class a `src/ui/` component might emit (so the
+ * runtime ships <Button>/<Card>/<Dialog>/etc styled out-of-the-box).
+ *
+ * Per-surface utility classes live in a separate CSS file generated by
+ * `bundleUiSurfaces` and served at `/api/ui-bundles/<hash>.css`. The
+ * iframe shell loads runtime.css first, then the per-surface CSS — so
+ * the runtime stays small + cache-shared while each surface's own
+ * `class="..."` strings get whatever utilities they actually use,
+ * scoped to that surface alone.
+ */
+
+@import "tailwindcss";
+@import "@yourrealm/sdk/ui/tokens.css";
+
+@source "../ui";
+
+/* Iframe base: make html/body/#root fill the iframe viewport so surface
+   content can use `h-full` to vertically center inside its widget card.
+   Without this, the body sizes to content and any h-full child collapses
+   to zero, pinning content to the top-left of the iframe. */
+html,
+body,
+#root {
+  height: 100%;
+}
+body {
+  margin: 0;
+  /* Match Home's _app.tsx body styling so the dev landing + install panel
+     share the same clay-theme background as the production dashboard. */
+  background: var(--background);
+  color: var(--foreground);
+}
+
+/* Boot-state spinner for the runtime's initial-load gate (mount.ts): a
+   container in its boot window renders a centered spinner instead of the
+   surface. Plain CSS so it needs no icon component and no per-surface
+   utility generation — the gate's markup lives in mount.ts, not a
+   bundled surface. */
+.realm-boot-spinner {
+  width: 1.25rem;
+  height: 1.25rem;
+  border-radius: 9999px;
+  border: 2px solid var(--muted-foreground);
+  border-top-color: transparent;
+  opacity: 0.7;
+  animation: realm-boot-spin 0.7s linear infinite;
+}
+@keyframes realm-boot-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}