gantry-web 0.3.5 → 0.4.0

package/src/bridge.ts

@@ -1,94 +1,95 @@
-// The native bridge: typed access to the window.<prefix>* functions the
-// Go appshell binds. In a plain browser tab none of them exist, so
-// every method is safe to call anywhere - it just does nothing outside
-// the native window - and `available` tells you which world you are in.
-
-export interface ShellCaps {
-  minimize: boolean;
-  maximize: boolean;
-  close: boolean;
-  alwaysOnTop: boolean;
-  /** "windows" | "linux" - which native host is running. */
-  platform?: string;
-  /** True when the window is frameless (custom chrome active). */
-  frameless?: boolean;
-}
-
-export interface ShellBridge {
-  /** True when running inside a Gantry native window. */
-  available: boolean;
-  close(): void;
-  minimize(): void;
-  /** Start the native window drag loop (call on mousedown). */
-  drag(): void;
-  /** System notification sound + taskbar flash. */
-  attention(): void;
-  maximize(): void;
-  restore(): void;
-  isMaximized(): Promise<boolean>;
-  /** Which window buttons the Go side enabled (all false in a browser). */
-  caps(): Promise<ShellCaps>;
-  /** Widgets and popups: show or hide the native window. */
-  setVisible(show: boolean): void;
-  /** Widgets: resize the native window in place. */
-  resize(width: number, height: number): void;
-  setAlwaysOnTop(on: boolean): void;
-  /** Open a URL in the user's default browser (never in the app). */
-  openExternal(url: string): void;
-  /**
-   * Linux frameless windows: start an interactive resize from an edge
-   * ("n","s","e","w","ne","nw","se","sw"). No-op on Windows, where the
-   * native hit-test handles edges.
-   */
-  resizeEdge(edge: string): void;
-}
-
-type AnyFn = (...args: unknown[]) => unknown;
-
-function fn(prefix: string, name: string): AnyFn | undefined {
-  const w = window as unknown as Record<string, unknown>;
-  const f = w[prefix + name];
-  return typeof f === "function" ? (f as AnyFn) : undefined;
-}
-
-const NO_CAPS: ShellCaps = {
-  minimize: false,
-  maximize: false,
-  close: false,
-  alwaysOnTop: false,
-};
-
-/**
- * getShell returns the bridge for the given binding prefix. The prefix
- * must match the Go side's BindingPrefix; both default to "gantry".
- */
-export function getShell(prefix = "gantry"): ShellBridge {
-  const call = (name: string, ...args: unknown[]) => {
-    const f = fn(prefix, name);
-    if (f) void f(...args);
-  };
-  return {
-    // Minimize is bound on every main window unless disabled, and Close
-    // exists on every window kind, so either marks a native host.
-    available: !!(fn(prefix, "Minimize") ?? fn(prefix, "Close")),
-    close: () => call("Close"),
-    minimize: () => call("Minimize"),
-    drag: () => call("Drag"),
-    attention: () => call("Attention"),
-    maximize: () => call("Maximize"),
-    restore: () => call("Restore"),
-    isMaximized: async () => {
-      const f = fn(prefix, "IsMaximized");
-      return f ? ((await f()) as boolean) : false;
-    },
-    caps: async () => {
-      const f = fn(prefix, "Caps");
-      return f ? ((await f()) as ShellCaps) : NO_CAPS;
-    },
-    setVisible: (show) => call("Visible", show),
-    resize: (w, h) => call("Resize", w, h),
-    setAlwaysOnTop: (on) => call("SetAlwaysOnTop", on),
-    openExternal: (url) => call("OpenExternal", url),
-    resizeEdge: (edge) => call("ResizeEdge", edge),
-  };
-}
+// The native bridge: typed access to the window.<prefix>* functions the
+// Go appshell binds. In a plain browser tab none of them exist, so
+// every method is safe to call anywhere - it just does nothing outside
+// the native window - and `available` tells you which world you are in.
+
+export interface ShellCaps {
+  minimize: boolean;
+  maximize: boolean;
+  close: boolean;
+  alwaysOnTop: boolean;
+  /** "windows" | "linux" - which native host is running. */
+  platform?: string;
+  /** True when the window is frameless (custom chrome active). */
+  frameless?: boolean;
+}
+
+export interface ShellBridge {
+  /** True when running inside a Gantry native window. */
+  available: boolean;
+  close(): void;
+  minimize(): void;
+  /** Start the native window drag loop (call on mousedown). */
+  drag(): void;
+  /** System notification sound + taskbar flash. */
+  attention(): void;
+  maximize(): void;
+  restore(): void;
+  isMaximized(): Promise<boolean>;
+  /** Which window buttons the Go side enabled (all false in a browser). */
+  caps(): Promise<ShellCaps>;
+  /** Widgets and popups: show or hide the native window. */
+  setVisible(show: boolean): void;
+  /** Widgets: resize the native window in place. */
+  resize(width: number, height: number): void;
+  setAlwaysOnTop(on: boolean): void;
+  /** Open a URL in the user's default browser (never in the app). */
+  openExternal(url: string): void;
+  /**
+   * Frameless windows: start an interactive resize from an edge
+   * ("n","s","e","w","ne","nw","se","sw"). Bound on both Windows and
+   * Linux; on Windows it posts WM_NCLBUTTONDOWN (the native hit-test
+   * margin remains only as a backstop).
+   */
+  resizeEdge(edge: string): void;
+}
+
+type AnyFn = (...args: unknown[]) => unknown;
+
+function fn(prefix: string, name: string): AnyFn | undefined {
+  const w = window as unknown as Record<string, unknown>;
+  const f = w[prefix + name];
+  return typeof f === "function" ? (f as AnyFn) : undefined;
+}
+
+const NO_CAPS: ShellCaps = {
+  minimize: false,
+  maximize: false,
+  close: false,
+  alwaysOnTop: false,
+};
+
+/**
+ * getShell returns the bridge for the given binding prefix. The prefix
+ * must match the Go side's BindingPrefix; both default to "gantry".
+ */
+export function getShell(prefix = "gantry"): ShellBridge {
+  const call = (name: string, ...args: unknown[]) => {
+    const f = fn(prefix, name);
+    if (f) void f(...args);
+  };
+  return {
+    // Minimize is bound on every main window unless disabled, and Close
+    // exists on every window kind, so either marks a native host.
+    available: !!(fn(prefix, "Minimize") ?? fn(prefix, "Close")),
+    close: () => call("Close"),
+    minimize: () => call("Minimize"),
+    drag: () => call("Drag"),
+    attention: () => call("Attention"),
+    maximize: () => call("Maximize"),
+    restore: () => call("Restore"),
+    isMaximized: async () => {
+      const f = fn(prefix, "IsMaximized");
+      return f ? ((await f()) as boolean) : false;
+    },
+    caps: async () => {
+      const f = fn(prefix, "Caps");
+      return f ? ((await f()) as ShellCaps) : NO_CAPS;
+    },
+    setVisible: (show) => call("Visible", show),
+    resize: (w, h) => call("Resize", w, h),
+    setAlwaysOnTop: (on) => call("SetAlwaysOnTop", on),
+    openExternal: (url) => call("OpenExternal", url),
+    resizeEdge: (edge) => call("ResizeEdge", edge),
+  };
+}

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

@@ -1,22 +1,32 @@
-export { getShell } from "./bridge";
-export type { ShellBridge, ShellCaps } from "./bridge";
-export { useShell, useShellCaps } from "./hooks";
-export { installZoomGuard } from "./zoom";
-export { TitleBar } from "./TitleBar";
-export type { TitleBarProps } from "./TitleBar";
-export { DragStrip } from "./DragStrip";
-export type { DragStripProps } from "./DragStrip";
-export { ResizeFrame } from "./ResizeFrame";
-export { createApp } from "./app";
-export type { CreateAppOptions, GantryAppModule, GantryPage, GantryPageModule } from "./app";
-export { navigate, redirect, goBack, goForward, useRoute, isActive, Link, ExternalLink } from "./router";
-export type { LinkProps, ExternalLinkProps } from "./router";
-export { usePaired } from "./paired";
-export type { Paired } from "./paired";
-export { service, useService, useCall } from "./service";
-export type { Service, CallResult } from "./service";
-export { useGoState } from "./gostate";
-export { useAppInfo, fetchAppInfo } from "./appinfo";
-export type { AppInfo } from "./appinfo";
-export { TeaView } from "./tea/Runtime";
-export type { TeaComponentProps, ComponentRegistry } from "./tea/Runtime";
+export { getShell } from "./bridge";
+export type { ShellBridge, ShellCaps } from "./bridge";
+export { useShell, useShellCaps } from "./hooks";
+export { installZoomGuard } from "./zoom";
+export { TitleBar } from "./TitleBar";
+export type { TitleBarProps } from "./TitleBar";
+export { DragStrip } from "./DragStrip";
+export type { DragStripProps } from "./DragStrip";
+export { ResizeFrame } from "./ResizeFrame";
+export { createApp } from "./app";
+export type { CreateAppOptions, GantryAppModule, GantryPage, GantryPageModule } from "./app";
+export { navigate, redirect, goBack, goForward, useRoute, isActive, useParams, Link, ExternalLink } from "./router";
+export type { LinkProps, ExternalLinkProps, RouteParams } from "./router";
+export { usePaired } from "./paired";
+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(/^\/+/, "");
+}