gantry-web 0.3.5 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gantry-web",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Frontend half of the Gantry desktop app framework: window chrome, native bridge, Tea runtime, Vite plugin",
   "license": "MIT",
   "repository": {

package/src/Await.tsx

@@ -0,0 +1,85 @@
+// Loading states for Go calls. useCall() already exposes { loading,
+// error, data }; Await is the declarative wrapper: show a developer-
+// defined fallback (a spinner, <Skeleton/>, anything) while the call
+// is in flight, an error card with retry when it fails, and the
+// children once data is there.
+//
+//	const users = useCall<User[]>("api", "listUsers");
+//	return (
+//	  <Await call={users} fallback={<Skeleton lines={4} />}>
+//	    {(list) => <ul>{list.map(...)}</ul>}
+//	  </Await>
+//	);
+
+import type { CSSProperties, ReactNode } from "react";
+import type { CallResult } from "./service";
+
+export interface AwaitProps<T> {
+  /** The in-flight call (from useCall, or anything CallResult-shaped). */
+  call: CallResult<T>;
+  /** What to show while loading: a spinner, <Skeleton/>, custom JSX.
+   * Default: <Skeleton lines={3}/>. */
+  fallback?: ReactNode;
+  /** Custom error rendering; default is a small card with a Retry
+   * button. */
+  renderError?: (error: string, code: string | null, reload: () => void) => ReactNode;
+  /** Renders the loaded data. */
+  children: (data: T) => ReactNode;
+}
+
+export function Await<T>({ call, fallback, renderError, children }: AwaitProps<T>) {
+  if (call.loading) {
+    return <>{fallback ?? <Skeleton lines={3} />}</>;
+  }
+  if (call.error !== null) {
+    if (renderError) return <>{renderError(call.error, call.code, call.reload)}</>;
+    return (
+      <div className="gantry-await-error">
+        <span className="gantry-await-error-message">{call.error}</span>
+        {call.code && <span className="gantry-await-error-code">{call.code}</span>}
+        <button className="gantry-await-retry" onClick={call.reload}>
+          Retry
+        </button>
+      </div>
+    );
+  }
+  return <>{children(call.data as T)}</>;
+}
+
+export interface SkeletonProps {
+  /** Placeholder text lines (the last one renders shorter). */
+  lines?: number;
+  /** Explicit size for a single block (a chart area, an avatar). */
+  width?: number | string;
+  height?: number | string;
+  /** Round the block fully (avatars). */
+  circle?: boolean;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * Skeleton renders shimmering placeholder blocks sized like the
+ * content they stand in for: <Skeleton lines={4}/> for text,
+ * <Skeleton width={240} height={120}/> for a block, circle for
+ * avatars.
+ */
+export function Skeleton({ lines, width, height, circle, className, style }: SkeletonProps) {
+  if (lines === undefined && (width !== undefined || height !== undefined || circle)) {
+    const s: CSSProperties = {
+      width: width ?? (circle ? 40 : "100%"),
+      height: height ?? (circle ? 40 : 16),
+      borderRadius: circle ? "50%" : undefined,
+      ...style,
+    };
+    return <div className={"gantry-skeleton" + (className ? " " + className : "")} style={s} />;
+  }
+  const n = Math.max(1, lines ?? 3);
+  return (
+    <div className={"gantry-skeleton-lines" + (className ? " " + className : "")} style={style}>
+      {Array.from({ length: n }, (_, i) => (
+        <div key={i} className="gantry-skeleton" style={{ width: i === n - 1 && n > 1 ? "60%" : "100%" }} />
+      ))}
+    </div>
+  );
+}

package/src/ErrorScreen.tsx

@@ -0,0 +1,98 @@
+// The built-in error UI: a full-screen overlay for fatal render
+// crashes and dismissible banners for non-fatal errors (Go panics,
+// unhandled rejections). Development shows the full story - message,
+// stack, the page, and the "what led here" action trail; production
+// shows a friendly minimal card. Replace it per app via
+// createApp({ errors: { screen: MyScreen } }).
+
+import type { FC } from "react";
+import type { GantryCrumb, GantryErrorInfo } from "./errors";
+
+export interface ErrorScreenProps {
+  error: GantryErrorInfo;
+  /** Resolved app mode; null while unknown (treated as development). */
+  mode: "development" | "production" | null;
+  /** "fatal" = render crash overlay, "notice" = dismissible banner. */
+  variant: "fatal" | "notice";
+  onDismiss: () => void;
+}
+
+function ago(iso: string, now: number): string {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return "";
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 1) return "now";
+  if (s < 60) return `${s}s ago`;
+  return `${Math.floor(s / 60)}m${s % 60 ? ` ${s % 60}s` : ""} ago`;
+}
+
+function Trail({ trail }: { trail: GantryCrumb[] }) {
+  const now = Date.now();
+  return (
+    <div className="gantry-error-trail">
+      <div className="gantry-error-heading">What led here</div>
+      {trail.map((c, i) => (
+        <div key={i} className={"gantry-error-crumb" + (c.ok ? "" : " gantry-error-crumb-failed")}>
+          <span className="gantry-error-crumb-time">{ago(c.time, now)}</span>
+          <span className="gantry-error-crumb-type">{c.type}</span>
+          <span className="gantry-error-crumb-detail">{c.detail}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function Detail({ error }: { error: GantryErrorInfo }) {
+  return (
+    <>
+      <div className="gantry-error-meta">
+        <span className="gantry-error-kind">{error.kind}</span>
+        {error.code && <span className="gantry-error-code">{error.code}</span>}
+        {error.page && <span className="gantry-error-page">on {error.page}</span>}
+        {error.source && <span className="gantry-error-source">{error.source}</span>}
+        <span className="gantry-error-origin">{error.origin === "go" ? "Go" : "JS"}</span>
+      </div>
+      {error.stack && <pre className="gantry-error-stack">{error.stack}</pre>}
+      {error.componentStack && (
+        <>
+          <div className="gantry-error-heading">Component stack</div>
+          <pre className="gantry-error-stack">{error.componentStack}</pre>
+        </>
+      )}
+      {error.trail && error.trail.length > 0 && <Trail trail={error.trail} />}
+    </>
+  );
+}
+
+export const ErrorScreen: FC<ErrorScreenProps> = ({ error, mode, variant, onDismiss }) => {
+  const dev = mode !== "production";
+  if (variant === "fatal") {
+    return (
+      <div className="gantry-error-overlay">
+        <div className="gantry-error-card">
+          <div className="gantry-error-title">{dev ? "The page crashed" : "Something went wrong"}</div>
+          {dev ? <div className="gantry-error-message">{error.message}</div> : <div className="gantry-error-message">The app hit an unexpected error. Reloading usually fixes it.</div>}
+          {dev && <Detail error={error} />}
+          <div className="gantry-error-actions">
+            <button className="gantry-error-button" onClick={() => location.reload()}>
+              Reload
+            </button>
+          </div>
+        </div>
+      </div>
+    );
+  }
+  return (
+    <div className="gantry-error-banner">
+      <div className="gantry-error-banner-head">
+        <span className="gantry-error-banner-title">
+          {error.origin === "go" ? "Go error" : "Error"}: {error.message}
+        </span>
+        <button className="gantry-error-dismiss" onClick={onDismiss} aria-label="Dismiss">
+          ×
+        </button>
+      </div>
+      {dev && <Detail error={error} />}
+    </div>
+  );
+};

package/src/app.tsx

@@ -1,12 +1,15 @@
 /// <reference path="../types/index.d.ts" />
-import { StrictMode, useEffect, type FC, type ReactNode } from "react";
+import { Component, StrictMode, useEffect, type ErrorInfo as ReactErrorInfo, type FC, type ReactNode } from "react";
 import { createRoot } from "react-dom/client";
 import { TitleBar, type TitleBarProps } from "./TitleBar";
 import { ResizeFrame } from "./ResizeFrame";
 import { installZoomGuard } from "./zoom";
-import { connect, ready } from "./socket";
+import { connect, ready, callGo } from "./socket";
 import { useRoute, redirect } from "./router";
 import { setRegistry, type ComponentRegistry, type TeaComponentProps } from "./tea/Runtime";
+import { installErrorHandlers, reportError, useGantryErrors, dismissNotice, clearFatal, setDevMode, type ErrorHandlingOptions, type GantryErrorInfo } from "./errors";
+import { ErrorScreen, type ErrorScreenProps } from "./ErrorScreen";
+import { fetchEnv, useMode } from "./env";
 
 /** The shape of a page module (a pages/<name>/<name>.tsx file). */
 export interface GantryPageModule {
@@ -72,6 +75,14 @@ export interface CreateAppOptions {
   socketURL?: string;
   /** Hide the TitleBar on every page (pages can also export chrome = false). */
   chrome?: boolean;
+  /**
+   * Crash detection and interception - on by default. A React render
+   * crash shows a full-screen error (full detail in development, a
+   * friendly card in production) instead of a white screen; Go panics
+   * and unhandled JS errors show dismissible notices in development.
+   * Replace the UI (screen), intercept (onError), or turn it off.
+   */
+  errors?: ErrorHandlingOptions & { screen?: FC<ErrorScreenProps> };
 }
 
 function keyClass(key: string): string {
@@ -134,6 +145,51 @@ function layoutsFor(page: GantryPage, chrome: boolean): FC<{ children?: ReactNod
   return out;
 }
 
+// ErrorBoundary catches render crashes below it. It wraps the page
+// content only - ResizeFrame and TitleBar stay outside, so a crashed
+// page keeps its drag and close controls.
+class ErrorBoundary extends Component<{ children: ReactNode }, { crashed: boolean }> {
+  state = { crashed: false };
+  static getDerivedStateFromError() {
+    return { crashed: true };
+  }
+  componentDidCatch(error: Error, info: ReactErrorInfo) {
+    reportError({
+      kind: "react-render",
+      code: "react.render",
+      message: error.message,
+      stack: error.stack,
+      componentStack: info.componentStack ?? undefined,
+      time: new Date().toISOString(),
+      origin: "js",
+    });
+  }
+  render() {
+    // The fatal overlay renders from the store (ErrorHost); the crashed
+    // subtree just goes away.
+    return this.state.crashed ? null : this.props.children;
+  }
+}
+
+// ErrorHost renders the (default or custom) error UI from the store:
+// the fatal overlay and the notice banners.
+function ErrorHost({ options }: { options: CreateAppOptions }) {
+  const { fatal, notices } = useGantryErrors();
+  const mode = useMode();
+  if (options.errors?.enabled === false) return null;
+  const Screen = options.errors?.screen ?? ErrorScreen;
+  return (
+    <>
+      {fatal && <Screen error={fatal} mode={mode} variant="fatal" onDismiss={clearFatal} />}
+      {notices.map((e, i) => (
+        // Newest first: the CSS shows only the first banner, dismissing
+        // it reveals the next.
+        <Screen key={i} error={e} mode={mode} variant="notice" onDismiss={() => dismissNotice(i)} />
+      )).reverse()}
+    </>
+  );
+}
+
 function AppRoot({ options }: { options: CreateAppOptions }) {
   const path = useRoute();
   const page = match(path);
@@ -155,11 +211,15 @@ function AppRoot({ options }: { options: CreateAppOptions }) {
   for (const Layout of layoutsFor(page, chrome).reverse()) {
     content = <Layout>{content}</Layout>;
   }
+  // The boundary wraps the page and layouts only: a render crash takes
+  // the content down, never the window chrome - the error overlay
+  // appears and the TitleBar keeps drag/close working.
   return (
     <div className="gantry-app">
       <ResizeFrame prefix={options.prefix} />
       {chrome && <TitleBar title={options.title} prefix={options.prefix} {...options.titleBar} />}
-      {content}
+      <ErrorBoundary>{content}</ErrorBoundary>
+      <ErrorHost options={options} />
     </div>
   );
 }
@@ -180,7 +240,22 @@ export function createApp(app: GantryAppModule, options: CreateAppOptions = {}):
     options = { ...options, ...reg.appConfig.default };
   }
   installZoomGuard();
+  installErrorHandlers(options.errors ?? {});
   connect(options.socketURL);
+  // Resolve the mode for the error UI (dev shows full detail), and
+  // surface a crash from the previous run if Go recorded one.
+  if (options.errors?.enabled !== false) {
+    fetchEnv()
+      .then((env) => setDevMode(env.mode === "development"))
+      .catch(() => {});
+    callGo("gantry", "errors")
+      .then((list) => {
+        const errs = (list ?? []) as (Omit<GantryErrorInfo, "origin"> & { kind: string })[];
+        const crash = errs.filter((e) => e.kind === "process-crash").at(-1);
+        if (crash) reportError({ ...crash, origin: "go" });
+      })
+      .catch(() => {});
+  }
 
   const registry: ComponentRegistry = {};
   for (const [key, mod] of Object.entries(reg.components)) {

package/src/env.ts

@@ -0,0 +1,71 @@
+// The app's mode and declared args, served by the built-in "gantry"
+// service the Go side registers in gantry.Run. Mode is "development"
+// under gantry dev and "production" in a built binary; args are the
+// gantry.json "args" declarations resolved from their environment
+// variables. Use them to gate pages and features.
+
+import { useEffect, useState } from "react";
+import { callGo } from "./socket";
+
+export type AppMode = "development" | "production";
+
+export interface AppEnv {
+  /** "development" under gantry dev, "production" in a built binary. */
+  mode: AppMode;
+  /** Every declared arg (gantry.json "args"), resolved: env > default. */
+  args: Record<string, string | number | boolean>;
+}
+
+let cached: AppEnv | null = null;
+let pending: Promise<AppEnv> | null = null;
+
+/** fetchEnv resolves the mode and declared args once and caches them -
+ * the values cannot change while the app runs. */
+export function fetchEnv(): Promise<AppEnv> {
+  if (cached) return Promise.resolve(cached);
+  pending ??= callGo("gantry", "env")
+    .then((v) => (cached = v as AppEnv))
+    .catch((err) => {
+      pending = null; // retry on the next call
+      throw err;
+    });
+  return pending;
+}
+
+/**
+ * useEnv returns { mode, args } - null until the first fetch resolves.
+ *
+ *	const env = useEnv();
+ *	if (env?.args["mock-data"]) ...
+ */
+export function useEnv(): AppEnv | null {
+  const [env, setEnv] = useState(cached);
+  useEffect(() => {
+    if (env) return;
+    let alive = true;
+    fetchEnv()
+      .then((v) => {
+        if (alive) setEnv(v);
+      })
+      .catch(() => {});
+    return () => {
+      alive = false;
+    };
+  }, [env]);
+  return env;
+}
+
+/** useMode returns the app mode - null until the first fetch resolves. */
+export function useMode(): AppMode | null {
+  return useEnv()?.mode ?? null;
+}
+
+/**
+ * useArg returns one declared arg's value - undefined until the first
+ * fetch resolves (and for undeclared names).
+ *
+ *	const host = useArg<string>("api-host");
+ */
+export function useArg<T extends string | number | boolean = string | number | boolean>(name: string): T | undefined {
+  return useEnv()?.args[name] as T | undefined;
+}

package/src/errors.ts

@@ -0,0 +1,214 @@
+// The frontend half of Gantry's error pipeline. createApp installs the
+// window-level handlers and the ErrorBoundary reports render crashes
+// here; Go-side errors arrive over the websocket as {"t":"error"}
+// frames. Every error lands in one store that drives the (default or
+// custom) error UI, and JS-side errors are reported back to Go so the
+// gantry dev terminal, the ring buffer and the app's OnError hook see
+// them too.
+
+import { useSyncExternalStore } from "react";
+import { callGo, onServerError } from "./socket";
+
+/** One breadcrumb in an error's trail (recorded by the Go server). */
+export interface GantryCrumb {
+  time: string;
+  type: "navigate" | "event" | "call" | "state" | "custom";
+  detail: string;
+  ok: boolean;
+}
+
+/** One captured error, from either side of the app. */
+export interface GantryErrorInfo {
+  /** "react-render" | "js-error" | "js-rejection" | the Go kinds
+   * ("call-panic", "process-crash", ...). */
+  kind: string;
+  /** gerr code: "panic.call", "js.error", ... */
+  code?: string;
+  /** Where it happened: "pages/index.increment", a component stack head. */
+  source?: string;
+  message: string;
+  stack?: string;
+  /** React component stack, for render crashes. */
+  componentStack?: string;
+  time: string;
+  /** Active page when it fired. */
+  page?: string;
+  /** Recent user actions leading up to it, oldest first. */
+  trail?: GantryCrumb[];
+  /** Which side captured it. */
+  origin: "go" | "js";
+}
+
+export interface ErrorHandlingOptions {
+  /** false turns the whole frontend pipeline off (default true). */
+  enabled?: boolean;
+  /** Replace the built-in error screen (see ErrorScreenProps). */
+  screen?: unknown; // typed as FC<ErrorScreenProps> in app.tsx to avoid a cycle
+  /** Intercept every error; return false to suppress the default UI. */
+  onError?: (e: GantryErrorInfo) => boolean | void;
+  /** Report JS-side errors to Go (terminal log, ring buffer, OnError
+   * hook). Default true. */
+  reportToGo?: boolean;
+  /** Show Go-side errors (panics) as dismissible notices: true, false,
+   * or only in development mode (the default). */
+  showGoErrors?: boolean | "development";
+}
+
+interface ErrorStore {
+  /** A render crash: the page is down, the overlay owns the screen. */
+  fatal: GantryErrorInfo | null;
+  /** Non-fatal errors (Go panics, unhandled rejections): banners. */
+  notices: GantryErrorInfo[];
+}
+
+let store: ErrorStore = { fatal: null, notices: [] };
+const listeners = new Set<() => void>();
+let opts: ErrorHandlingOptions = {};
+let installed = false;
+let devMode: boolean | null = null; // resolved from the env service
+
+// StrictMode and error bubbling can fire the same error twice within a
+// tick; dedupe by message+stack in a short window.
+let lastSig = "";
+let lastSigAt = 0;
+
+function emit(): void {
+  listeners.forEach((fn) => fn());
+}
+
+function setStore(next: ErrorStore): void {
+  store = next;
+  emit();
+}
+
+/** setDevMode feeds the resolved mode in (createApp does this); the
+ * default UI shows full detail only in development. */
+export function setDevMode(dev: boolean): void {
+  devMode = dev;
+  emit();
+}
+
+export function isDevMode(): boolean | null {
+  return devMode;
+}
+
+function shouldShowGoError(): boolean {
+  const pref = opts.showGoErrors ?? "development";
+  if (pref === "development") return devMode !== false; // unknown mode: show
+  return pref;
+}
+
+/**
+ * reportError feeds one error into the pipeline: dedupe, the app's
+ * onError hook, the store (driving the error UI), and - for JS-side
+ * errors - a best-effort report to Go.
+ */
+export function reportError(e: GantryErrorInfo): void {
+  if (opts.enabled === false) return;
+  const sig = e.message + "\n" + (e.stack ?? "");
+  const now = Date.now();
+  if (sig === lastSig && now - lastSigAt < 500) return;
+  lastSig = sig;
+  lastSigAt = now;
+
+  if (!e.page && e.origin === "js") e.page = location.pathname;
+  if (!e.time) e.time = new Date().toISOString();
+
+  if (e.origin === "js" && opts.reportToGo !== false) {
+    // Best-effort: the socket may be down; the console always has it.
+    callGo("gantry", "reportError", e).catch(() => {});
+  }
+
+  const suppress = opts.onError?.(e) === false;
+  if (suppress) return;
+
+  if (e.kind === "react-render") {
+    setStore({ ...store, fatal: e });
+    return;
+  }
+  if (e.origin === "go" && !shouldShowGoError()) {
+    console.warn(`gantry: go error [${e.kind}] ${e.source ?? ""}: ${e.message}`);
+    return;
+  }
+  if (e.origin === "js" && devMode === false) {
+    // Production: non-fatal JS errors stay in the console.
+    console.warn(`gantry: error [${e.kind}]: ${e.message}`);
+    return;
+  }
+  setStore({ ...store, notices: [...store.notices, e] });
+}
+
+/** dismissNotice removes one banner (or all, with no index). */
+export function dismissNotice(index?: number): void {
+  if (index === undefined) {
+    setStore({ ...store, notices: [] });
+  } else {
+    setStore({ ...store, notices: store.notices.filter((_, i) => i !== index) });
+  }
+}
+
+/** clearFatal drops the fatal overlay (the Reload button uses a real
+ * reload instead; this is for custom screens that can recover). */
+export function clearFatal(): void {
+  setStore({ ...store, fatal: null });
+}
+
+/** useGantryErrors subscribes the error UI to the store. */
+export function useGantryErrors(): ErrorStore {
+  return useSyncExternalStore(
+    (fn) => {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    () => store,
+  );
+}
+
+/**
+ * addBreadcrumb records an app-specific action in the Go-side error
+ * trail ("sync started"), alongside the automatic navigate/event/call
+ * crumbs. Fire-and-forget.
+ */
+export function addBreadcrumb(detail: string): void {
+  callGo("gantry", "breadcrumb", { detail }).catch(() => {});
+}
+
+/**
+ * installErrorHandlers wires the window-level capture: uncaught JS
+ * errors and unhandled promise rejections. createApp calls this once.
+ */
+export function installErrorHandlers(options: ErrorHandlingOptions): void {
+  opts = options;
+  if (installed || options.enabled === false) return;
+  installed = true;
+
+  // Go-side errors (panics, last-run crashes) arrive as {"t":"error"}
+  // frames.
+  onServerError((p) => {
+    const e = p as Omit<GantryErrorInfo, "origin">;
+    if (e && e.message) reportError({ ...e, origin: "go" });
+  });
+
+  window.addEventListener("error", (ev) => {
+    reportError({
+      kind: "js-error",
+      code: "js.error",
+      message: ev.message || String(ev.error ?? "unknown error"),
+      stack: ev.error instanceof Error ? ev.error.stack : undefined,
+      source: ev.filename ? `${ev.filename}:${ev.lineno}` : undefined,
+      time: new Date().toISOString(),
+      origin: "js",
+    });
+  });
+  window.addEventListener("unhandledrejection", (ev) => {
+    const reason = ev.reason;
+    reportError({
+      kind: "js-rejection",
+      code: "js.rejection",
+      message: reason instanceof Error ? reason.message : String(reason),
+      stack: reason instanceof Error ? reason.stack : undefined,
+      time: new Date().toISOString(),
+      origin: "js",
+    });
+  });
+}

package/src/index.ts

@@ -16,7 +16,17 @@ export type { Paired } from "./paired";
 export { service, useService, useCall } from "./service";
 export type { Service, CallResult } from "./service";
 export { useGoState } from "./gostate";
+export { resourceURL } from "./resources";
 export { useAppInfo, fetchAppInfo } from "./appinfo";
 export type { AppInfo } from "./appinfo";
+export { useEnv, useMode, useArg, fetchEnv } from "./env";
+export type { AppEnv, AppMode } from "./env";
+export { reportError, addBreadcrumb, useGantryErrors, dismissNotice, clearFatal } from "./errors";
+export type { GantryErrorInfo, GantryCrumb, ErrorHandlingOptions } from "./errors";
+export { ErrorScreen } from "./ErrorScreen";
+export type { ErrorScreenProps } from "./ErrorScreen";
+export { GantryCallError } from "./socket";
+export { Await, Skeleton } from "./Await";
+export type { AwaitProps, SkeletonProps } from "./Await";
 export { TeaView } from "./tea/Runtime";
 export type { TeaComponentProps, ComponentRegistry } from "./tea/Runtime";

package/src/resources.ts

@@ -0,0 +1,17 @@
+// Embedded app resources. Files placed in the app's resources/ directory
+// are embedded into the binary once and served by the Go side at
+// /resources/<path> (in gantry dev, the Vite plugin serves the same
+// folder live off disk). Reference them by URL:
+//
+//   import { resourceURL } from "gantry-web";
+//   <img src={resourceURL("img/logo.png")} />
+//   const cfg = await fetch(resourceURL("cfg.json")).then((r) => r.json());
+//   // fonts: `url(${resourceURL("fonts/inter.woff2")})`
+//
+// The same file is reachable from the paired .go code via
+// gantry.Resource("img/logo.png") / gantry.Resources().
+
+/** URL of an embedded resource, e.g. resourceURL("img/logo.png") -> "/resources/img/logo.png". */
+export function resourceURL(name: string): string {
+  return "/resources/" + String(name).replace(/^\/+/, "");
+}

package/src/service.ts

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { callGo, connect } from "./socket";
+import { callGo, connect, GantryCallError } from "./socket";
 
 export interface Service {
   /** call awaits a Go function registered on this service (ui.Calls). */
@@ -35,6 +35,8 @@ export function useService(name: string): Service {
 export interface CallResult<T> {
   data: T | undefined;
   error: string | null;
+  /** The gerr code of a failed call ("panic.call", "auth.expired", ...). */
+  code: string | null;
   loading: boolean;
   /** reload re-runs the call. */
   reload: () => void;
@@ -48,6 +50,7 @@ export interface CallResult<T> {
 export function useCall<T = unknown>(key: string, name: string, payload?: unknown): CallResult<T> {
   const [data, setData] = useState<T | undefined>(undefined);
   const [error, setError] = useState<string | null>(null);
+  const [code, setCode] = useState<string | null>(null);
   const [loading, setLoading] = useState(true);
   const [tick, setTick] = useState(0);
   const alive = useRef(true);
@@ -57,6 +60,7 @@ export function useCall<T = unknown>(key: string, name: string, payload?: unknow
     alive.current = true;
     setLoading(true);
     setError(null);
+    setCode(null);
     callGo(key, name, payload)
       .then((v) => {
         if (alive.current) {
@@ -67,6 +71,7 @@ export function useCall<T = unknown>(key: string, name: string, payload?: unknow
       .catch((e: Error) => {
         if (alive.current) {
           setError(e.message);
+          if (e instanceof GantryCallError && e.code) setCode(e.code);
           setLoading(false);
         }
       });
@@ -78,5 +83,5 @@ export function useCall<T = unknown>(key: string, name: string, payload?: unknow
   }, [key, name, payloadKey, tick]);
 
   const reload = useCallback(() => setTick((t) => t + 1), []);
-  return { data, error, loading, reload };
+  return { data, error, code, loading, reload };
 }

package/src/socket.ts

@@ -3,6 +3,25 @@
 // backoff (webview reloads, dev server restarts, HMR) and re-announces
 // the active page on every connect so the server always re-renders.
 
+/** GantryCallError rejects a failed callGo with the gerr code the Go
+ * side attached ("panic.call", or the code of the returned error), so
+ * callers can switch on it. */
+export class GantryCallError extends Error {
+  code?: string;
+  constructor(message: string, code?: string) {
+    super(message);
+    this.name = "GantryCallError";
+    this.code = code;
+  }
+}
+
+/** The (single) consumer of server {"t":"error"} frames; errors.ts
+ * subscribes. Registered lazily to keep this module UI-free. */
+let errorListener: ((p: unknown) => void) | null = null;
+export function onServerError(fn: (p: unknown) => void): void {
+  errorListener = fn;
+}
+
 export type WireNode = {
   type: string;
   key?: string;
@@ -63,6 +82,7 @@ function open(): void {
       id?: string;
       ok?: boolean;
       err?: string;
+      code?: string;
     };
     try {
       msg = JSON.parse(e.data as string);
@@ -79,11 +99,13 @@ function open(): void {
         pending.delete(msg.id);
         clearTimeout(p.timer);
         if (msg.ok) p.resolve(msg.p);
-        else p.reject(new Error(msg.err ?? "call failed"));
+        else p.reject(new GantryCallError(msg.err ?? "call failed", msg.code));
       }
     } else if (msg.t === "state" && msg.key) {
       stateValues.set(msg.key, msg.p);
       stateListeners.get(msg.key)?.forEach((fn) => fn());
+    } else if (msg.t === "error") {
+      errorListener?.(msg.p);
     }
   };
   sock.onclose = () => {

package/src/styles.css

@@ -307,3 +307,250 @@
   min-height: 0;
   overflow: auto;
 }
+
+/* ---- error UI (ErrorScreen.tsx) ---- */
+
+.gantry-error-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 9998;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  background: color-mix(in srgb, var(--gantry-bg) 82%, black);
+}
+
+.gantry-error-card {
+  max-width: 720px;
+  max-height: 80vh;
+  overflow: auto;
+  padding: 20px 24px;
+  border: 1px solid color-mix(in srgb, var(--gantry-fg) 15%, transparent);
+  border-radius: 10px;
+  background: var(--gantry-bg);
+  color: var(--gantry-fg);
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.35);
+}
+
+.gantry-error-title {
+  font-size: 17px;
+  font-weight: 600;
+  color: #e5484d;
+  margin-bottom: 8px;
+}
+
+.gantry-error-message {
+  font-size: 14px;
+  margin-bottom: 12px;
+  word-break: break-word;
+}
+
+.gantry-error-meta {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-bottom: 10px;
+  font-size: 11px;
+}
+
+.gantry-error-meta > span {
+  padding: 2px 7px;
+  border-radius: 99px;
+  background: color-mix(in srgb, var(--gantry-fg) 8%, transparent);
+  opacity: 0.85;
+}
+
+.gantry-error-code {
+  font-family: var(--gantry-mono, ui-monospace, monospace);
+}
+
+.gantry-error-heading {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  opacity: 0.6;
+  margin: 12px 0 6px;
+}
+
+.gantry-error-stack {
+  margin: 0;
+  padding: 10px 12px;
+  border-radius: 6px;
+  background: color-mix(in srgb, var(--gantry-fg) 6%, transparent);
+  font-family: var(--gantry-mono, ui-monospace, monospace);
+  font-size: 11.5px;
+  line-height: 1.5;
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 260px;
+  overflow: auto;
+}
+
+.gantry-error-trail {
+  margin-top: 4px;
+}
+
+.gantry-error-crumb {
+  display: flex;
+  gap: 8px;
+  align-items: baseline;
+  padding: 2px 0;
+  font-size: 12px;
+}
+
+.gantry-error-crumb-failed .gantry-error-crumb-detail,
+.gantry-error-crumb-failed .gantry-error-crumb-type {
+  color: #e5484d;
+}
+
+.gantry-error-crumb-time {
+  min-width: 64px;
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+  opacity: 0.5;
+  font-size: 11px;
+}
+
+.gantry-error-crumb-type {
+  min-width: 62px;
+  font-size: 11px;
+  opacity: 0.65;
+}
+
+.gantry-error-crumb-detail {
+  font-family: var(--gantry-mono, ui-monospace, monospace);
+  word-break: break-word;
+}
+
+.gantry-error-actions {
+  margin-top: 16px;
+  display: flex;
+  gap: 8px;
+}
+
+.gantry-error-button {
+  padding: 6px 16px;
+  border: 1px solid color-mix(in srgb, var(--gantry-fg) 20%, transparent);
+  border-radius: 6px;
+  background: var(--gantry-accent);
+  color: white;
+  font-size: 13px;
+  cursor: pointer;
+}
+
+.gantry-error-banner {
+  position: fixed;
+  right: 16px;
+  bottom: 16px;
+  z-index: 9999;
+  width: min(520px, calc(100vw - 32px));
+  max-height: 45vh;
+  overflow: auto;
+  padding: 12px 14px;
+  border: 1px solid #e5484d;
+  border-radius: 8px;
+  background: var(--gantry-bg);
+  color: var(--gantry-fg);
+  box-shadow: 0 8px 28px rgba(0, 0, 0, 0.3);
+}
+
+.gantry-error-banner + .gantry-error-banner {
+  display: none; /* stacked banners: newest wins, dismiss reveals the next */
+}
+
+.gantry-error-banner-head {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  justify-content: space-between;
+}
+
+.gantry-error-banner-title {
+  font-size: 13px;
+  font-weight: 500;
+  word-break: break-word;
+}
+
+.gantry-error-dismiss {
+  border: none;
+  background: none;
+  color: var(--gantry-fg);
+  opacity: 0.6;
+  font-size: 16px;
+  line-height: 1;
+  cursor: pointer;
+  padding: 0 2px;
+}
+
+.gantry-error-dismiss:hover {
+  opacity: 1;
+}
+
+/* ---- loading states (Await.tsx) ---- */
+
+.gantry-skeleton {
+  height: 14px;
+  border-radius: 4px;
+  background: linear-gradient(
+    90deg,
+    color-mix(in srgb, var(--gantry-fg) 7%, transparent) 25%,
+    color-mix(in srgb, var(--gantry-fg) 13%, transparent) 50%,
+    color-mix(in srgb, var(--gantry-fg) 7%, transparent) 75%
+  );
+  background-size: 200% 100%;
+  animation: gantry-skeleton-shimmer 1.4s ease-in-out infinite;
+}
+
+.gantry-skeleton-lines {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+@keyframes gantry-skeleton-shimmer {
+  0% {
+    background-position: 200% 0;
+  }
+  100% {
+    background-position: -200% 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .gantry-skeleton {
+    animation: none;
+  }
+}
+
+.gantry-await-error {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 12px;
+  border: 1px solid color-mix(in srgb, #e5484d 40%, transparent);
+  border-radius: 6px;
+  font-size: 13px;
+}
+
+.gantry-await-error-code {
+  font-family: var(--gantry-mono, ui-monospace, monospace);
+  font-size: 11px;
+  opacity: 0.6;
+}
+
+.gantry-await-retry {
+  margin-left: auto;
+  padding: 3px 12px;
+  border: 1px solid color-mix(in srgb, var(--gantry-fg) 20%, transparent);
+  border-radius: 5px;
+  background: none;
+  color: var(--gantry-fg);
+  font-size: 12px;
+  cursor: pointer;
+}
+
+.gantry-await-retry:hover {
+  border-color: var(--gantry-accent);
+}

package/src/vite/index.js

@@ -19,6 +19,36 @@ import path from "node:path";
 const VIRTUAL_ID = "virtual:gantry-app";
 const RESOLVED_ID = "\0" + VIRTUAL_ID;
 
+// Content types for the dev /resources/ middleware. Keep in rough sync
+// with the extensions developers drop in resources/ (images, fonts,
+// data). Unknown types fall back to a generic binary stream.
+const RESOURCE_MIME = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".avif": "image/avif",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".json": "application/json",
+  ".txt": "text/plain; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".wasm": "application/wasm",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".pdf": "application/pdf",
+};
+
+function resourceMime(file) {
+  return RESOURCE_MIME[path.extname(file).toLowerCase()] || "application/octet-stream";
+}
+
 /**
  * @param {{ appRoot?: string, goPort?: number }} [opts]
  * @returns {import("vite").Plugin}
@@ -218,6 +248,33 @@ export function gantry(opts = {}) {
     },
 
     configureServer(server) {
+      // Serve /resources/<path> live off <appRoot>/resources during dev,
+      // the same tree the Go side embeds and serves in production. Kept
+      // off the Go server (no proxy) so edits appear without a rebuild.
+      const resourcesDir = path.join(appRoot, "resources");
+      server.middlewares.use((req, res, next) => {
+        const url = (req.url || "").split("?")[0];
+        if (!url.startsWith("/resources/")) return next();
+        const rel = decodeURIComponent(url.slice("/resources/".length));
+        const abs = path.join(resourcesDir, rel);
+        // Contain the request inside resources/ (reject ../ traversal).
+        const rootPrefix = resourcesDir + path.sep;
+        if (abs !== resourcesDir && !abs.startsWith(rootPrefix)) {
+          res.statusCode = 403;
+          return res.end("Forbidden");
+        }
+        let stat;
+        try {
+          stat = fs.statSync(abs);
+        } catch {
+          return next();
+        }
+        if (!stat.isFile()) return next();
+        res.setHeader("Content-Type", resourceMime(abs));
+        res.setHeader("Content-Length", stat.size);
+        fs.createReadStream(abs).pipe(res);
+      });
+
       server.watcher.add(appRoot);
       const refresh = (file) => {
         const f = file.split(path.sep).join("/");