@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui/tokens.css

@@ -0,0 +1,279 @@
+/*
+ * Realm UI tokens — claymorphism theme.
+ *
+ * Clay shadow technique based on https://github.com/codeAdrian/clay.css/
+ *
+ * Color palette:
+ *   Background:     #f0edff (lavender)
+ *   Primary:        #7c5cfc (purple)
+ *   Dark:           #2d2456 (headings, dark cards)
+ *   Text:           #534ab7 (body text on light)
+ *   Muted:          #9b8fd4 (labels, secondary text)
+ *   Light muted:    #b8aee0 (placeholders)
+ *   Surface:        #ffffff (cards)
+ *   Surface tinted: #f8f6ff (slightly purple cards)
+ *   Surface light:  #f4f2ff (inputs, code backgrounds)
+ *   Blue (trust):   #185fa5 / #3b82f6 / #eef4ff
+ *   Amber (perms):  #a07830 / #fef8f0
+ *   Red (danger):   #dc2626 / #fef2f2
+ *   Green (ok):     #16a34a / #22c55e / #ecfdf5
+ */
+
+@source ".";
+
+@layer base {
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-border);
+  }
+
+  /* Soft dimensional wash behind the content area so raised clay
+     surfaces have something to lift off of. The sidebar-inset already
+     paints `bg-background`; this layers a faint corner glow on top. */
+  [data-slot="sidebar-inset"] {
+    background-image:
+      radial-gradient(1100px circle at 100% -10%, rgba(155, 125, 255, 0.18), transparent 45%),
+      radial-gradient(900px circle at -10% 110%, rgba(124, 92, 252, 0.12), transparent 50%);
+  }
+
+  .dark [data-slot="sidebar-inset"] {
+    background-image:
+      radial-gradient(1100px circle at 100% -10%, rgba(124, 92, 252, 0.22), transparent 45%),
+      radial-gradient(900px circle at -10% 110%, rgba(80, 50, 200, 0.18), transparent 50%);
+  }
+}
+
+:root {
+  --background: #f0edff;
+  --foreground: #2d2456;
+  --card: #ffffff;
+  --card-foreground: #2d2456;
+  --popover: #ffffff;
+  --popover-foreground: #2d2456;
+  --primary: #7c5cfc;
+  --primary-foreground: #ffffff;
+  --secondary: #f4f2ff;
+  --secondary-foreground: #534ab7;
+  --muted: #f4f2ff;
+  --muted-foreground: #9b8fd4;
+  --accent: #f4f2ff;
+  --accent-foreground: #534ab7;
+  --destructive: #dc2626;
+  --destructive-foreground: #ffffff;
+  --border: #d4d0e8;
+  --input: #e8e4ff;
+  --ring: #7c5cfc;
+  --chart-1: #7c5cfc;
+  --chart-2: #534ab7;
+  --chart-3: #9b8fd4;
+  --chart-4: #b8aee0;
+  --chart-5: #d4d0e8;
+  --chart-6: #6d7ce0;
+  --chart-7: #a774c9;
+  --chart-8: #6f6a99;
+  --sidebar: #f8f6ff;
+  --sidebar-foreground: #2d2456;
+  --sidebar-primary: #7c5cfc;
+  --sidebar-primary-foreground: #ffffff;
+  --sidebar-accent: #f0edff;
+  --sidebar-accent-foreground: #534ab7;
+  --sidebar-border: #d4d0e8;
+  --sidebar-ring: #7c5cfc;
+  --radius: 1rem;
+  /* Aside/callout grounds. Plain variables rather than `@theme inline`
+     literals, because `inline` bakes the value into the utility and a
+     `.dark` override of the theme key would never reach it. */
+  --trust-bg: #eef4ff;
+  --perm-bg: #fef8f0;
+  --danger-bg: #fef2f2;
+}
+
+.dark {
+  --background: #1a1433;
+  --foreground: #e8e4ff;
+  --card: #241e45;
+  --card-foreground: #e8e4ff;
+  --popover: #241e45;
+  --popover-foreground: #e8e4ff;
+  --primary: #9b7dff;
+  --primary-foreground: #ffffff;
+  --secondary: #2d2456;
+  --secondary-foreground: #d4d0e8;
+  --muted: #2d2456;
+  --muted-foreground: #9b8fd4;
+  --accent: #2d2456;
+  --accent-foreground: #d4d0e8;
+  --destructive: #f87171;
+  --destructive-foreground: #1a1433;
+  --border: #3d3566;
+  --input: #3d3566;
+  --ring: #9b7dff;
+  --chart-1: #9b7dff;
+  --chart-2: #7c5cfc;
+  --chart-3: #b8aee0;
+  --chart-4: #534ab7;
+  --chart-5: #3d3566;
+  --chart-6: #8b93ea;
+  --chart-7: #c294dd;
+  --chart-8: #8681b5;
+  --sidebar: #1e1838;
+  --sidebar-foreground: #e8e4ff;
+  --sidebar-primary: #9b7dff;
+  --sidebar-primary-foreground: #ffffff;
+  --sidebar-accent: #2d2456;
+  --sidebar-accent-foreground: #e8e4ff;
+  --sidebar-border: #3d3566;
+  --sidebar-ring: #9b7dff;
+  --trust-bg: #1c2f4d;
+  --perm-bg: #3a2e14;
+  --danger-bg: #3f1d1d;
+}
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+@theme inline {
+  --font-sans: var(--font-nunito, system-ui, sans-serif);
+
+  /* Extra small breakpoint below Tailwind's `sm` (640px), for phone-portrait
+     layouts. Enables `xs:` / `max-xs:` variants. */
+  --breakpoint-xs: 30rem;
+
+  /* ── Clay shadows (light) ──
+     Puffy/inflated look: a soft diagonal drop shadow (slightly more y
+     than x so surfaces read as lifted), a dark bottom-right inset, and
+     a bright top-left inset highlight. The highlight is what sells the
+     "soft clay" feel — keep it near-white and generous. */
+  --shadow-clay-sm:
+    4px 6px 12px 0 rgba(100, 80, 180, 0.16), inset -2px -2px 5px 0 rgba(100, 80, 180, 0.1),
+    inset 2px 3px 6px 0 rgba(255, 255, 255, 0.9);
+  --shadow-clay:
+    8px 12px 24px 0 rgba(100, 80, 180, 0.2), inset -4px -4px 10px 0 rgba(100, 80, 180, 0.1),
+    inset 3px 5px 14px 0 rgba(255, 255, 255, 1);
+  --shadow-clay-lg:
+    14px 18px 38px 0 rgba(100, 80, 180, 0.24), inset -5px -5px 12px 0 rgba(100, 80, 180, 0.1),
+    inset 4px 7px 18px 0 rgba(255, 255, 255, 1);
+  --shadow-clay-primary:
+    6px 9px 18px 0 rgba(124, 92, 252, 0.45), inset -3px -3px 8px 0 rgba(80, 50, 200, 0.4),
+    inset 3px 4px 8px 0 rgba(255, 255, 255, 0.4);
+
+  /* ── Clay shadows (dark) ── */
+  --shadow-clay-dark-sm:
+    4px 6px 12px 0 rgba(10, 5, 30, 0.4), inset -2px -2px 5px 0 rgba(10, 5, 30, 0.3),
+    inset 2px 3px 6px 0 rgba(255, 255, 255, 0.05);
+  --shadow-clay-dark:
+    8px 12px 24px 0 rgba(10, 5, 30, 0.45), inset -4px -4px 10px 0 rgba(10, 5, 30, 0.35),
+    inset 3px 5px 14px 0 rgba(255, 255, 255, 0.06);
+  --shadow-clay-dark-lg:
+    14px 18px 38px 0 rgba(10, 5, 30, 0.5), inset -5px -5px 12px 0 rgba(10, 5, 30, 0.4),
+    inset 4px 7px 18px 0 rgba(255, 255, 255, 0.06);
+  --shadow-clay-dark-primary:
+    6px 9px 18px 0 rgba(155, 125, 255, 0.3), inset -3px -3px 8px 0 rgba(40, 20, 120, 0.4),
+    inset 3px 4px 8px 0 rgba(255, 255, 255, 0.08);
+
+  /* ── Semantic clay shadows ── */
+  --shadow-clay-blue:
+    8px 12px 24px 0 rgba(24, 95, 165, 0.16), inset -4px -4px 10px 0 rgba(24, 95, 165, 0.08),
+    inset 3px 5px 14px 0 rgba(255, 255, 255, 0.9);
+  --shadow-clay-amber:
+    8px 12px 24px 0 rgba(186, 117, 23, 0.16), inset -4px -4px 10px 0 rgba(186, 117, 23, 0.08),
+    inset 3px 5px 14px 0 rgba(255, 255, 255, 0.9);
+  --shadow-clay-danger:
+    8px 12px 24px 0 rgba(220, 38, 38, 0.18), inset -4px -4px 10px 0 rgba(220, 38, 38, 0.09),
+    inset 3px 5px 14px 0 rgba(255, 255, 255, 0.9);
+  --shadow-clay-ok:
+    8px 12px 24px 0 rgba(22, 163, 74, 0.16), inset -4px -4px 10px 0 rgba(22, 163, 74, 0.08),
+    inset 3px 5px 14px 0 rgba(255, 255, 255, 0.9);
+  --shadow-clay-roadmap:
+    8px 12px 24px 0 rgba(13, 148, 136, 0.16), inset -4px -4px 10px 0 rgba(13, 148, 136, 0.08),
+    inset 3px 5px 14px 0 rgba(255, 255, 255, 0.9);
+
+  /* ── Map standard shadow scale to clay ── */
+  --shadow-2xs: 0 0 0 0 transparent;
+  --shadow-xs: 0 0 0 0 transparent;
+  --shadow-sm: var(--shadow-clay-sm);
+  --shadow: var(--shadow-clay);
+  --shadow-md: var(--shadow-clay);
+  --shadow-lg: var(--shadow-clay-lg);
+  --shadow-xl: var(--shadow-clay-lg);
+  --shadow-2xl: var(--shadow-clay-lg);
+
+  /* ── Semantic colors ── */
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-chart-6: var(--chart-6);
+  --color-chart-7: var(--chart-7);
+  --color-chart-8: var(--chart-8);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  /* ── Extra surface/text tokens ── */
+  --color-surface-tinted: #f8f6ff;
+  --color-surface-light: #f4f2ff;
+  --color-text-body: #534ab7;
+  --color-text-muted: #9b8fd4;
+  --color-text-faint: #b8aee0;
+  --color-text-dark: #2d2456;
+  --color-purple-light: #e8e4ff;
+  --color-purple-wash: #f0edff;
+
+  /* Trust (blue) */
+  --color-trust: #3b82f6;
+  --color-trust-bg: var(--trust-bg);
+  --color-trust-deep: #185fa5;
+  --color-trust-surface: #d0e2ff;
+  --color-trust-text: #1a2a4a;
+  --color-trust-muted: #6b8ab8;
+
+  /* Permissions (amber) */
+  --color-perm: #a07830;
+  --color-perm-bg: var(--perm-bg);
+
+  /* Danger (red) */
+  --color-danger: #dc2626;
+  --color-danger-bg: var(--danger-bg);
+  --color-danger-deep: #991b1b;
+
+  /* Success (green) */
+  --color-success: #22c55e;
+  --color-success-bg: #ecfdf5;
+  --color-success-text: #16a34a;
+
+  /* Roadmap (teal) - planned-but-not-built callouts */
+  --color-roadmap: #0d9488;
+  --color-roadmap-bg: #f0fdfa;
+}

package/src/ui/utils.ts

@@ -0,0 +1,78 @@
+import { cloneElement, type ComponentChildren, isValidElement, type JSX, type VNode } from "preact";
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+/**
+ * Props for a wrapper over a DOM element, minus `class`.
+ *
+ * Preact takes either `class` or `className` on an element, so `class` is the
+ * idiom everywhere else in this repo. It does NOT work on these wrappers: they
+ * pull `className` out, feed it through {@link cn}, and spread the rest onto
+ * the element - which hands preact/compat's vnode normalizer both keys at
+ * once. It resolves that collision by letting `className` win outright:
+ *
+ *     if (props.class && !props.className) { ...keep class... }
+ *     else if (props.className) { normalizedProps.class = normalizedProps.className = props.className }
+ *
+ * A wrapper's `className` is always set (it's `cn(...)` of its own base
+ * classes), so the second branch always runs and a caller's `class` is
+ * discarded. Silently: `ComponentProps<"div">` permits both keys, so it
+ * typechecks and then evaporates at runtime.
+ *
+ * Omitting `class` here turns that into a compile error at the call site.
+ * Wrappers over an Ark primitive don't need this - their props come from
+ * Ark's React types, which only have `className`.
+ */
+export type ElementProps<T extends keyof JSX.IntrinsicElements> = Omit<
+  JSX.IntrinsicElements[T],
+  "class"
+>;
+
+type AnyProps = Record<string, unknown>;
+
+export function mergeProps<T extends keyof JSX.IntrinsicElements = "div">(
+  ...sources: (Partial<JSX.IntrinsicElements[T]> | undefined | null)[]
+): JSX.IntrinsicElements[T] {
+  const result: Record<string, unknown> = {};
+  for (const source of sources) {
+    if (!source) continue;
+    for (const key of Object.keys(source)) {
+      const a = result[key];
+      const b = (source as AnyProps)[key];
+      if (key === "className" || key === "class") {
+        result[key] = cn(a as ClassValue, b as ClassValue);
+      } else if (key === "style") {
+        result[key] = { ...(a as object), ...(b as object) };
+      } else if (/^on[A-Z]/.test(key) && typeof a === "function" && typeof b === "function") {
+        result[key] = (...args: unknown[]) => {
+          (a as (...args: unknown[]) => unknown)(...args);
+          (b as (...args: unknown[]) => unknown)(...args);
+        };
+      } else {
+        result[key] = b;
+      }
+    }
+  }
+  return result as JSX.IntrinsicElements[T];
+}
+
+// Clones a single-element child, merging wrapper props onto it. Implements
+// the shadcn/Ark `asChild` pattern: caller supplies the host element as
+// children, wrapper contributes className/state/events. className, style,
+// and on* handlers merge; everything else goes child-wins-over-wrapper so
+// href/type/etc. survive.
+export function Slot({
+  children,
+  ...props
+}: { children?: ComponentChildren } & Record<string, unknown>): VNode {
+  if (!isValidElement(children)) {
+    throw new Error("Slot requires a single element as children.");
+  }
+  const child = children as VNode<AnyProps>;
+  const childProps = (child.props ?? {}) as AnyProps;
+  return cloneElement(child, mergeProps(props as never, childProps as never) as never);
+}

package/src/ui-error.ts

@@ -0,0 +1,139 @@
+// The typed error contract for ui loader/action calls.
+//
+// A loader (or action) failure is a *typed* value across all four hops
+// (worker ui-proxy → Home run-loader → UiBridge postMessage → iframe
+// mount): the worker emits `{ error, code }`, each relay hop preserves
+// `code`, and the iframe runtime rejects the loader's promise with a
+// `UiError` (an `Error` subclass carrying `code`). A widget — or, for the
+// transient boot codes, the runtime's initial-load gate — branches on
+// `error.code`, which the message alone can't carry: a booting container
+// and a crashed one both read "no running container matches …".
+//
+// This file is imported from both sides of the wire: the worker
+// (`@yourrealm/sdk/worker`) emits it, the iframe runtime (`mount.ts`)
+// consumes it, and it's re-exported from `@yourrealm/sdk/ui` so surface
+// authors can name the codes. It must stay free of any runtime-global
+// (Deno, window) at module load — the SDK barrel is bundled into QuickJS.
+
+/** The stable set of codes a ui loader/action failure can carry. */
+export type UiErrorCode =
+  // The service has no container created at all (never deployed, or the
+  // app isn't pinned yet). Distinct from STARTING: there's nothing that
+  // will come up on its own, so this is not a spinner-forever state.
+  | "NO_CONTAINER"
+  // A container exists but isn't serving yet: created, restarting, or
+  // running-without-an-ip-yet. Transient — the loader's refetchInterval
+  // clears it once the container answers. This is the boot-window code the
+  // runtime's initial-load gate turns into a centered spinner.
+  | "CONTAINER_STARTING"
+  // A container exists but exited, died, or is paused. Real failure —
+  // surfaced to the author, never auto-retried into a spinner.
+  | "CONTAINER_CRASHED"
+  // The container was found but didn't answer within the upstream cap.
+  | "UPSTREAM_TIMEOUT"
+  // The container answered with a non-2xx, or returned a body the proxy
+  // couldn't pass through (non-JSON where JSON was required, oversize).
+  | "UPSTREAM_ERROR"
+  // Anything else: bad request shape, transport failure reaching the
+  // worker, an exception the proxy didn't anticipate.
+  | "INTERNAL";
+
+/** Codes that mean "not up yet, but expected to come up on its own." */
+export const TRANSIENT_UI_ERROR_CODES: ReadonlySet<UiErrorCode> = new Set(["CONTAINER_STARTING"]);
+
+/** An `Error` that also carries a `UiErrorCode`. */
+export class UiError extends Error {
+  readonly code: UiErrorCode;
+  constructor(code: UiErrorCode, message: string) {
+    super(message);
+    this.name = "UiError";
+    this.code = code;
+  }
+}
+
+/** Type guard: is this value a `UiError` (vs a plain `Error`)? */
+export function isUiError(value: unknown): value is UiError {
+  return value instanceof UiError;
+}
+
+/** True when `err` is a UiError whose code is transient (boot window). */
+export function isTransientUiError(err: unknown): boolean {
+  return isUiError(err) && TRANSIENT_UI_ERROR_CODES.has(err.code);
+}
+
+// --- Wire shape -------------------------------------------------------------
+// The body a coded failure takes on the wire: `{ error, code }`. Plain
+// helpers rather than zod so the worker's hot path pays no schema parse per
+// proxy response; two fields, validated by construction at the emit site and
+// by a membership check at the consume site.
+
+const UI_ERROR_CODES: ReadonlySet<string> = new Set([
+  "NO_CONTAINER",
+  "CONTAINER_STARTING",
+  "CONTAINER_CRASHED",
+  "UPSTREAM_TIMEOUT",
+  "UPSTREAM_ERROR",
+  "INTERNAL",
+]);
+
+/** Build the `{ error, code }` body a proxy route returns for `code`. */
+export function uiErrorBody(
+  code: UiErrorCode,
+  message: string,
+): {
+  error: string;
+  code: UiErrorCode;
+} {
+  return { error: message, code };
+}
+
+/**
+ * Read a `UiErrorCode` off an already-parsed response body, if one is
+ * present and recognized. Returns `undefined` for absent / unknown codes,
+ * so callers degrade to string-only behavior against an out-of-date peer.
+ */
+export function readUiErrorCode(body: unknown): UiErrorCode | undefined {
+  if (!body || typeof body !== "object") return undefined;
+  const code = (body as { code?: unknown }).code;
+  return typeof code === "string" && UI_ERROR_CODES.has(code) ? (code as UiErrorCode) : undefined;
+}
+
+/** Read the human message off an error body, with a fallback. */
+export function readUiErrorMessage(body: unknown, fallback: string): string {
+  if (body && typeof body === "object") {
+    const err = (body as { error?: unknown }).error;
+    if (typeof err === "string" && err.length > 0) return err;
+  }
+  return fallback;
+}
+
+// --- The canonical failure value ---------------------------------------------
+// A ui failure IS this object, born on the worker and carried — not
+// re-encoded into a string and re-parsed — through Home, the postMessage
+// bridge, and the iframe. Downstream code branches on `.code`; the message
+// is for humans. One shape end to end makes a fan-out of N failures a plain
+// list of these, with no hop re-deciding the contract.
+
+/** The typed failure a ui loader/action call can produce. */
+export interface UiFailure {
+  code: UiErrorCode;
+  message: string;
+}
+
+/**
+ * Parse an already-read response/postMessage body into a `UiFailure`, or
+ * `undefined` if it isn't one (absent/unknown code, or no message). This is
+ * the single place the wire shape is validated; every consumer keys off the
+ * returned object instead of re-reading `error`/`code` ad hoc.
+ */
+export function readUiFailure(body: unknown): UiFailure | undefined {
+  const code = readUiErrorCode(body);
+  if (code === undefined) return undefined;
+  const message = readUiErrorMessage(body, "");
+  return { code, message };
+}
+
+/** Build the `UiError` an iframe-side promise rejects with, from a failure. */
+export function uiErrorFromFailure(f: UiFailure): UiError {
+  return new UiError(f.code, f.message);
+}