@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui-runtime/dev-landing-entry.tsx

@@ -0,0 +1,258 @@
+// Browser entry for `realm-sdk dev`'s landing page. Mounts the shared
+// `DevShell` (Home-style sidebar) around one of three views, picked from
+// the URL pathname the server rendered:
+//
+//   - /            → Home: router tiles + widget iframes in a mixed
+//                    grid (mirrors platform/home/src/routes/(authed)/index.tsx).
+//   - /pages/<key> → page iframe for that surface.
+//
+// The island also owns two bridges:
+//
+//   - postMessage bridge: forward `ui-call` from sandboxed iframes to
+//     `POST /loader/<kind>/<key>/<name>`. The iframes run in an opaque
+//     origin (no allow-same-origin) so they can't fetch directly.
+//
+//   - SSE: subscribe to `/events` and bump an iframe `key` so any visible
+//     iframe remounts on realm.ts edits.
+//
+// Routing is server-driven: clicking a sidebar entry triggers a full
+// navigation; the dev server returns this same HTML for / and
+// /pages/<key>, just with a different `pathname` baked in.
+
+import { render } from "preact";
+import { useEffect, useMemo, useState } from "preact/hooks";
+import type { WidgetManifest } from "../resolve.ts";
+import { CubeIcon } from "../ui/components/icons.tsx";
+import { DevShell, type DevShellState } from "../ui/dev/dev-shell.tsx";
+import { HomeGrid, type RouterTile, type WidgetTile } from "../ui/home/home-grid.tsx";
+
+// Wire shapes the dev server serializes into the page; the HomeGrid
+// component takes its own (different) tile shape, so the landing maps
+// these → tiles before rendering.
+interface WireRouter {
+  serviceId: string;
+  name: string;
+  iconSrc?: string;
+  publicDomain?: string;
+}
+
+type WireWidget = Pick<WidgetManifest, "title" | "icon" | "cols" | "rows"> & { key: string };
+
+interface LandingState extends DevShellState {
+  pathname: string;
+  routers: WireRouter[];
+  widgets: WireWidget[];
+  sidebarOpen: boolean;
+}
+
+function readState(): LandingState {
+  const el = document.getElementById("dev-state");
+  if (!el || el.tagName !== "SCRIPT") throw new Error("dev-state script tag missing");
+  return JSON.parse(el.textContent ?? "{}") as LandingState;
+}
+
+const KEY_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+function useUiCallBridge() {
+  useEffect(() => {
+    function findIframeWindow(source: EventTarget | null): HTMLIFrameElement | null {
+      if (!source) return null;
+      for (const f of document.querySelectorAll("iframe")) {
+        if (f.contentWindow === source) return f;
+      }
+      return null;
+    }
+    // `/iframe/<kind>/<key>` is where this landing page mounted the surface,
+    // so the src is the authentic record of which one it is.
+    function surfaceFromIframe(
+      iframe: HTMLIFrameElement,
+    ): { kind: "page" | "widget"; key: string } | null {
+      let path: string;
+      try {
+        path = new URL(iframe.src, globalThis.location.href).pathname;
+      } catch {
+        return null;
+      }
+      const m = path.match(/^\/iframe\/(page|widget)\/([^/]+)$/);
+      if (!m) return null;
+      let key: string;
+      try {
+        key = decodeURIComponent(m[2]!);
+      } catch {
+        return null;
+      }
+      if (!KEY_RE.test(key)) return null;
+      return { kind: m[1] as "page" | "widget", key };
+    }
+    function reply(
+      target: Window,
+      id: number,
+      payload: { data: unknown } | { error: string; code?: string },
+    ): void {
+      target.postMessage({ realm: "ui-response", id, ...payload }, "*");
+    }
+    async function onMessage(ev: MessageEvent): Promise<void> {
+      const v = ev.data as {
+        realm?: string;
+        id?: number;
+        endpoint?: string;
+        name?: string;
+        request?: unknown;
+      } | null;
+      if (!v || v.realm !== "ui-call" || typeof v.id !== "number") return;
+      if (typeof v.name !== "string" || !KEY_RE.test(v.name)) return;
+      if (v.endpoint !== "loader" && v.endpoint !== "action") return;
+      const source = ev.source as Window | null;
+      if (!source) return;
+      const iframe = findIframeWindow(source);
+      if (!iframe) return;
+      // The surface's identity comes off the element we mounted, never off
+      // the message — same rule Home's UiBridge enforces, so the dev loop
+      // can't accept a call shape the real parent would reject.
+      const surface = surfaceFromIframe(iframe);
+      if (!surface) return;
+      try {
+        const res = await fetch(
+          `/${v.endpoint}/${surface.kind}/${encodeURIComponent(surface.key)}/${encodeURIComponent(
+            v.name,
+          )}`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ request: v.request }),
+          },
+        );
+        const body = (await res.json().catch(() => null)) as unknown;
+        if (!res.ok) {
+          const errMsg =
+            body && typeof body === "object" && "error" in body
+              ? String((body as { error: unknown }).error)
+              : `HTTP ${res.status}`;
+          const code =
+            body && typeof body === "object" && "code" in body
+              ? String((body as { code: unknown }).code)
+              : undefined;
+          reply(source, v.id, { error: errMsg, code });
+          return;
+        }
+        reply(source, v.id, { data: body });
+      } catch (err) {
+        reply(source, v.id, { error: (err as Error)?.message ?? String(err) });
+      }
+    }
+    globalThis.addEventListener("message", onMessage);
+    return () => globalThis.removeEventListener("message", onMessage);
+  }, []);
+}
+
+function useSseReload(onReload: () => void) {
+  useEffect(() => {
+    const es = new EventSource("/events");
+    const handler = () => onReload();
+    es.addEventListener("reload", handler);
+    return () => {
+      es.removeEventListener("reload", handler);
+      es.close();
+    };
+  }, [onReload]);
+}
+
+function HomeView({
+  routers,
+  widgets,
+  bump,
+}: {
+  routers: WireRouter[];
+  widgets: WireWidget[];
+  bump: number;
+}) {
+  const routerTiles: RouterTile[] = routers.map((r) => ({
+    key: r.serviceId,
+    label: r.name,
+    ...(r.publicDomain ? { href: `https://${r.publicDomain}`, external: true } : {}),
+    ...(r.iconSrc ? { iconSrc: r.iconSrc } : {}),
+  }));
+  const widgetTiles: WidgetTile[] = widgets.map((w) => ({
+    key: w.key,
+    title: w.title,
+    icon: w.icon,
+    cols: w.cols,
+    rows: w.rows,
+    iframeSrc: `/iframe/widget/${encodeURIComponent(w.key)}`,
+  }));
+  return (
+    <HomeGrid
+      routers={routerTiles}
+      widgets={widgetTiles}
+      reloadNonce={bump}
+      emptyState={
+        <div class="rounded-2xl border border-dashed border-border bg-card/50 p-10 flex flex-col items-center gap-3 text-center">
+          <CubeIcon className="size-8 text-muted-foreground" />
+          <p class="text-sm text-muted-foreground max-w-sm">
+            This app declares no routed services or widgets. Add a{" "}
+            <code class="font-mono">router</code> to a service or a{" "}
+            <code class="font-mono">ui.widget</code> to see tiles here.
+          </p>
+        </div>
+      }
+    />
+  );
+}
+
+function PageView({ pageKey, bump }: { pageKey: string; bump: number }) {
+  return (
+    <iframe
+      key={`page:${pageKey}:${bump}`}
+      sandbox="allow-scripts allow-forms"
+      src={`/iframe/page/${encodeURIComponent(pageKey)}`}
+      class="flex-1 w-full border-0 bg-card"
+    />
+  );
+}
+
+function pageKeyFromPath(pathname: string): string | null {
+  const m = pathname.match(/^\/pages\/([^/]+)$/);
+  if (!m) return null;
+  try {
+    return decodeURIComponent(m[1]!);
+  } catch {
+    return null;
+  }
+}
+
+function DevLanding({ state }: { state: LandingState }) {
+  const [bump, setBump] = useState(0);
+  useUiCallBridge();
+  useSseReload(useMemo(() => () => setBump((n) => n + 1), []));
+
+  const pageKey = pageKeyFromPath(state.pathname);
+  const activePage = pageKey ? state.pages.find((p) => p.key === pageKey) : null;
+
+  const titleProps =
+    activePage !== null && activePage !== undefined
+      ? { title: activePage.title, titleIcon: activePage.icon }
+      : { title: "Home", titleIcon: "HouseIcon" };
+
+  return (
+    <DevShell
+      state={state}
+      pathname={state.pathname}
+      sidebarOpen={state.sidebarOpen}
+      {...titleProps}
+    >
+      {activePage ? (
+        <PageView pageKey={activePage.key} bump={bump} />
+      ) : pageKey ? (
+        <div class="p-6 text-xs text-muted-foreground">
+          Page <code class="font-mono">{pageKey}</code> not declared.
+        </div>
+      ) : (
+        <HomeView routers={state.routers} widgets={state.widgets} bump={bump} />
+      )}
+    </DevShell>
+  );
+}
+
+const root = document.getElementById("root");
+if (!root) throw new Error("#root missing");
+render(<DevLanding state={readState()} />, root);

package/src/ui-runtime/index.ts

@@ -0,0 +1,83 @@
+// Iframe runtime barrel. esbuild bundles this into one file
+// (runtime.js) and the iframe importmap maps every external the
+// surface bundle declares — `@yourrealm/sdk`, `@yourrealm/sdk/ui`,
+// `@yourrealm/sdk/preact`, `@yourrealm/sdk/jsx-runtime`,
+// `@yourrealm/sdk/services`, `zod` — to that one URL. The browser
+// dedupes by URL, so every import shares one runtime instance.
+
+export { Fragment, h, render } from "preact";
+export type { ComponentChildren, JSX, VNode } from "preact";
+
+export { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "preact/hooks";
+
+// JSX automatic runtime. Surface bundles compiled with
+// --jsx=automatic --jsx-import-source=@yourrealm/sdk emit
+// `import { jsx, jsxs, Fragment } from "@yourrealm/sdk/jsx-runtime"`
+// for every JSX element, and the importmap routes that specifier here.
+// `Fragment` is the same identity as preact's (exported above) so it's
+// reachable through both specifiers without a duplicate binding.
+export { jsx, jsxs, jsxDEV } from "preact/jsx-runtime";
+
+// Identity helpers from @yourrealm/sdk/ui — they exist for TS inference
+// at authoring time, but the bundled surface calls them at module load,
+// so the importmap-resolved runtime needs them as real functions too.
+// Re-exported from ui-surface so typed and runtime versions can't drift.
+export { action, loader, page, widget } from "../ui-surface.ts";
+
+// Components — must mirror the type-only contract in
+// `packages/sdk/src/ui/index.ts` (the surface bundle resolves names
+// from that type list against this module's exports).
+export * from "../ui/components/badge.tsx";
+export * from "../ui/components/button.tsx";
+export * from "../ui/components/card.tsx";
+export * from "../ui/components/checkbox.tsx";
+export * from "../ui/components/combobox.tsx";
+export * from "../ui/components/dialog.tsx";
+export * from "../ui/components/empty-state.tsx";
+export * from "../ui/components/icons.tsx";
+export * from "../ui/components/input.tsx";
+export * from "../ui/components/label.tsx";
+export * from "../ui/components/line-chart.tsx";
+export * from "../ui/components/page.tsx";
+export * from "../ui/components/pie-chart.tsx";
+export * from "../ui/components/separator.tsx";
+export * from "../ui/components/sheet.tsx";
+export * from "../ui/components/skeleton.tsx";
+export * from "../ui/components/switch.tsx";
+export * from "../ui/components/table.tsx";
+export * from "../ui/components/timeago.tsx";
+export * from "../ui/components/tooltip.tsx";
+
+// SDK + zod re-exports. Surface bundles externalize `@yourrealm/sdk`
+// (`createApp`, `r`, `z`, `apply`, `interpolate`, `ref`) and `zod`
+// (`z`, schemas) so a per-surface bundle is single-digit KB instead
+// of ~414 KB. Both modules are browser-safe: plain authoring JS, with
+// nothing that touches Deno or node.
+export * from "../index.ts";
+export * from "zod";
+
+// `@yourrealm/sdk/docker` (registry-gate helpers) is referenced by
+// realm.ts files at module load — `verifyAnonymousRequest` closes over
+// `checkDockerBasic` / `dockerChallenge` even though only Home's gate
+// sandbox calls them. The iframe never runs the gate, but the surface
+// bundle imports the names at module load, so the importmap-resolved
+// runtime must provide them. They're pure JS (no Deno/atob/Web Crypto —
+// see docker.ts), so re-export the real fns.
+export { checkDockerBasic, dockerChallenge } from "../docker.ts";
+
+// `@yourrealm/sdk/services` (Postgres, Valkey, etc.) is referenced by
+// realm.ts files at module load — `getDesiredState` closes over the
+// classes even though only Home eval calls it. The iframe never
+// instantiates these, so the runtime needs *names* but not behavior:
+// a single empty class re-exported as every Service satisfies ESM
+// resolution, and constructing one yields a no-op object.
+class _IframeServiceStub {}
+export {
+  _IframeServiceStub as Postgres,
+  _IframeServiceStub as MySQL,
+  _IframeServiceStub as Valkey,
+  _IframeServiceStub as Redis,
+  _IframeServiceStub as Garage,
+};
+
+export { mount, mountNeedsConfig } from "./mount.ts";

package/src/ui-runtime/install-entry.tsx

@@ -0,0 +1,119 @@
+// Browser entry for `realm-sdk dev`'s `/install` route. Mounts the shared
+// `DevShell` (Home-style sidebar) around the install panel so the page
+// matches the rest of the dev product chrome bit-for-bit. esbuild
+// bundles this into `install-panel.js`; the dev server's HTML shell
+// loads it and reads two JSON script tags (the dev shell state +
+// the install config).
+//
+// The panel doesn't talk to the dev server directly — it goes through
+// an InstallAdapter that POSTs to `/install/api/preview` and
+// `/install/api/install`. On failure those endpoints respond with the
+// same wire shape Home uses (`{error, violations?}`), so the same
+// `parseInstallError` helper rehydrates an InstallErrorShape for the
+// panel to render.
+
+import { render } from "preact";
+import InstallAppPanel from "../ui/install/install-app-panel.tsx";
+import { parseInstallError } from "../ui/install/install-error.tsx";
+import {
+  InstallAdapterError,
+  type InstallAdapter,
+  type InstallPayload,
+  type PreviewResult,
+} from "../ui/install/adapter.ts";
+import { WORKER_CAPABILITIES } from "../permissions.ts";
+import { DevShell, type DevShellState } from "../ui/dev/dev-shell.tsx";
+
+// realm-sdk dev runs every service via docker compose on the operator's
+// host, so the local environment effectively satisfies every host
+// capability. Advertise the full set under a synthetic worker so the
+// install panel doesn't flag every `host.*` grant as unsupported.
+const DEV_WORKER = {
+  id: "dev",
+  slug: "dev",
+  name: "realm-sdk dev (local)",
+  capabilities: [...WORKER_CAPABILITIES],
+};
+
+interface InstallConfig {
+  initialSource: string;
+  hideDeployTargets: boolean;
+}
+
+interface InstallShellState extends DevShellState {
+  pathname: string;
+  sidebarOpen: boolean;
+}
+
+function readConfig(): InstallConfig {
+  const el = document.getElementById("install-config");
+  if (!el || el.tagName !== "SCRIPT") throw new Error("install-config script tag missing");
+  const parsed = JSON.parse(el.textContent ?? "{}") as Partial<InstallConfig>;
+  return {
+    initialSource: parsed.initialSource ?? "",
+    hideDeployTargets: parsed.hideDeployTargets ?? true,
+  };
+}
+
+function readShellState(): InstallShellState {
+  const el = document.getElementById("dev-state");
+  if (!el || el.tagName !== "SCRIPT") throw new Error("dev-state script tag missing");
+  return JSON.parse(el.textContent ?? "{}") as InstallShellState;
+}
+
+async function postJson(path: string, body: unknown): Promise<unknown> {
+  const res = await fetch(path, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json().catch(() => null);
+  if (!res.ok) {
+    throw new InstallAdapterError(parseInstallError(res.status, data));
+  }
+  return data;
+}
+
+const devInstallAdapter: InstallAdapter = {
+  async preview(source: string): Promise<PreviewResult> {
+    return (await postJson("/install/api/preview", { source })) as PreviewResult;
+  },
+  async install(payload: InstallPayload): Promise<{ id: string }> {
+    const data = await postJson("/install/api/install", payload);
+    return { id: (data as { id?: string } | null)?.id ?? "" };
+  },
+  // No listSilos / createSilo: a Silo is a Home record on a named worker and
+  // dev has neither. Leaving them off is how the panel knows to skip the picker
+  // and its install gate, so a silo app reaches the dev compiler's own "no Silo
+  // in the fixture" error instead of a permanently disabled button.
+  // Dev mounts the app's own UI in place, so the id the panel passes on install
+  // is ignored and the redirect lands on the dev home.
+  onInstalled(): void {
+    globalThis.location.href = "/";
+  },
+};
+
+function InstallPage() {
+  const config = readConfig();
+  const shell = readShellState();
+  return (
+    <DevShell
+      state={shell}
+      pathname={shell.pathname}
+      sidebarOpen={shell.sidebarOpen}
+      title="Install"
+      titleIcon="DownloadSimpleIcon"
+    >
+      <InstallAppPanel
+        workers={[DEV_WORKER]}
+        plumbing={devInstallAdapter}
+        initialSource={config.initialSource}
+        hideDeployTargets={config.hideDeployTargets}
+      />
+    </DevShell>
+  );
+}
+
+const root = document.getElementById("root");
+if (!root) throw new Error("#root missing");
+render(<InstallPage />, root);