@reliantlabs/forge-web-runtime 0.3.0

package/README.md

@@ -0,0 +1,192 @@
+# @reliantlabs/forge-web-runtime
+
+The forge frontend runtime — the web twin of `forge/pkg`. Framework-agnostic
+React/TypeScript mechanism shared by every frontend forge scaffolds (Next.js
+App Router and Vite SPA alike).
+
+```ts
+import {
+  buildRuntimeInterceptors, // Connect transport stack
+  ConnectClientError,       // typed client errors
+  RuntimeShell,             // session + error boundary + toast host
+  useSession,               // the signed-in user
+  RouteGuard,               // signed-in render gate
+  Resource,                 // the list tristate + cursor pagination
+  initClientTelemetry,      // opt-in client RUM
+} from "@reliantlabs/forge-web-runtime";
+```
+
+## What is in here, and what is deliberately not
+
+**In:** mechanism. The interceptor stack (auth, brand headers, W3C
+traceparent, error normalization, idempotency-gated retry), the session
+derived from JWT claims, the error boundary, the toast queue, the
+`<Resource>` tristate/pagination container, trace-context propagation, and
+client RUM.
+
+**Out:** presentation a project is meant to own. The component library under
+`src/components/ui`, `globals.css`, the nav and the app layout all stay in the
+scaffold, because forking them is the point.
+
+The dependency runs one way. Nothing here imports application code — auth
+state, event subscriptions and toast markup all arrive as **props**, so an app
+can rename, restyle or delete its own files without breaking the runtime.
+
+## What this package publishes
+
+`dist/` — compiled ESM plus `.d.ts` — and nothing else. `src/` is not in the
+tarball.
+
+That is a contract, not a packaging detail. This package used to publish its
+TypeScript sources: `types` pointed at `src/index.ts`, so **every consumer
+typechecked this package's internals against its own React**. A React 18 app
+(Expo SDK 52 pins 18.3) compiling sources written against `@types/react` 19
+failed on files it never rendered —
+
+```
+providers.tsx: 'RuntimeErrorBoundary' cannot be used as a JSX component
+resource.tsx:  Type '0n' is not assignable to type 'ReactNode'
+```
+
+— and no amount of version pinning fixes the shape of that: a package that
+ships sources makes its own dependency versions its consumers' problem,
+forever, for every consumer. Publishing declarations ends it. A consumer
+typechecks against the `.d.ts`, which `skipLibCheck` does not re-check, and
+whose `react` references resolve in the consumer's own program.
+
+`src/published-surface.test.ts` is the gate: it fails if any entry point
+points back into `src/`, or if `src` reappears in `files`.
+
+### One `.d.ts` for React 18 and 19
+
+`peerDependencies` declares `react: "^18.3.0 || ^19.0.0"`, and both halves are
+real: forge's Next.js and Vite scaffolds are on 19, its Expo scaffold on 18.3.
+
+The two `@types/react` majors disagree about where `JSX.Element` lives — 19
+declares it inside the `react` module, 18.3 declares it globally and
+re-exports it from `react/jsx-runtime`. An **inferred** component return type
+is therefore emitted as `import("react").JSX.Element` when compiled against 19
+and `import("react/jsx-runtime").JSX.Element` when compiled against 18, so the
+published `.d.ts` would silently depend on whichever major happened to be
+installed at build time.
+
+So every exported component **declares `: ReactElement`**, a name both majors
+export from `react`. With that, the emitted `.d.ts` is byte-for-byte identical
+under either — the peer range is a fact about the artifact rather than a hope.
+`src/published-surface.test.ts` fails on any `JSX.Element` reaching `dist/`,
+and `npm run typecheck` compiles the package against **both** majors
+(`tsconfig.react18.json` redirects `react` at an aliased `@types/react-18`).
+
+### Peer dependencies
+
+`react`, `@connectrpc/connect`, `@bufbuild/protobuf` and `@opentelemetry/api`
+are peers, resolved from the consuming app. `next` deliberately is **not** — a
+Vite SPA consumes this package identically.
+
+Next.js consumers keep `transpilePackages: ["@reliantlabs/forge-web-runtime"]`
+(forge's generated `next.config.ts` sets it). The reason changed with the
+build — it is no longer "these are `.tsx` files" but "these modules carry
+`"use client"` and Next has to process them rather than treat the package as
+an opaque external."
+
+## The DOM-free interceptors entry point
+
+```ts
+import {
+  buildRuntimeInterceptors, // the Connect transport stack
+  ConnectClientError,       // what the stack throws
+  setTraceSampled,          // traceInterceptor's knob
+} from "@reliantlabs/forge-web-runtime/interceptors";
+```
+
+The `./interceptors` subpath is the transport layer on its own: `src/errors.ts`
+and `src/trace.ts` are the only modules it reaches. It imports **no React and
+no `@types/react`**, so a consumer never typechecks components it does not
+render.
+
+That is what keeps the package honest on React Native. A mobile app renders
+none of the components here — they emit `<table>`, `<input>`, `<div>` — so
+reaching them would drag a bundle's worth of dead code and a React binding
+onto a platform whose renderer is not react-dom. The subpath skips them
+entirely. `src/interceptors.ts` is guarded by
+`src/interceptors-entry.test.ts`, which walks the entry point's real import
+graph and fails if React ever appears in it.
+
+(This subpath was *also* the workaround for React 18 vs 19 type skew, back
+when the package published its sources. That is no longer why it exists — see
+"One `.d.ts` for React 18 and 19" above; the barrel typechecks fine from Expo
+now. It stays because dead components in a mobile bundle is a separate and
+still-real cost.)
+
+React Native resolvers predate `exports`: Expo SDK 52 / React Native 0.76 runs
+Metro with `unstable_enablePackageExports` off, and `expo/tsconfig.base` sets
+`moduleResolution: node10`. Neither reads the `exports` map. The
+`interceptors/package.json` directory shim is what they resolve instead — same
+build output, reached the old way. Delete it and mobile breaks while web keeps
+working.
+
+## The `--color-*` contract
+
+Several components render semantic Tailwind utilities. They are part of this
+package's public contract: the consuming app's stylesheet MUST declare these
+custom properties in its `@theme` block, and Tailwind v4 must be told to scan
+this package — **it does not scan `node_modules`**:
+
+```css
+/* frontends/<name>/src/app/globals.css (Next.js) */
+@source "../../node_modules/@reliantlabs/forge-web-runtime";
+
+/* frontends/<name>/src/index.css (Vite SPA) */
+@source "../node_modules/@reliantlabs/forge-web-runtime";
+```
+
+Without that directive every utility only this package uses is dropped from
+the built CSS and the components render unstyled.
+
+Required tokens:
+
+| Token | Used for |
+| --- | --- |
+| `--color-surface` | table / panel background |
+| `--color-surface-muted` | table head, row hover |
+| `--color-border` | table and panel rules |
+| `--color-ink` | primary text |
+| `--color-ink-muted` | secondary text, empty states |
+| `--color-ink-subtle` | placeholders, disabled controls |
+| `--color-accent` | focus ring, active filter border |
+| `--color-danger` | error text, destructive fill |
+| `--color-danger-hover` | destructive fill hover |
+| `--color-danger-surface` | error panel background |
+| `--color-danger-border` | error panel border |
+| `--color-danger-ink` | error text on a danger surface |
+| `--color-on-danger` | text on a danger fill |
+
+## Local development
+
+A dev forge build writes an npm `file:` dependency on this directory into a
+generated frontend's `package.json`, so npm creates and maintains the link
+itself and edits here are picked up with nothing published. The path is
+written relative or home-anchored, never absolute. A release build writes an
+ordinary version range instead.
+
+`forge project libraries` prints where the package resolved to and what every
+module exports — read it instead of searching the disk.
+
+### The live-edit loop
+
+The bridge resolves `dist/`, so **run `npm run dev` here while you edit** —
+`tsc --watch`, a few hundred milliseconds per incremental build. The linked
+app's bundler is already watching this directory (Metro via `watchFolders`,
+Next via `transpilePackages`, Vite because a linked dep is treated as source),
+so a save still lands in the running app; it just arrives one compile later.
+
+You do not have to remember to build before the *first* install. `prepare`
+(`scripts/build.mjs`) runs when npm materialises the `file:` link and again
+before `npm publish` — the two moments a consumable `dist/` has to exist. On a
+checkout that has never been developed it installs this package's own
+devDependencies once so `tsc` is there at all, because npm does not install a
+link target's devDependencies and forge's CI never runs `npm install` here.
+The script never runs for a registry install: the tarball already has `dist/`.
+
+`npm test` builds first (`pretest`), so `src/published-surface.test.ts` always
+asserts against a current artifact rather than whatever was last on disk.

package/dist/basepath.d.ts

@@ -0,0 +1,57 @@
+/**
+ * normalizeBasePath canonicalises a raw base-path value: ensure a leading
+ * "/", drop any trailing "/". "" and "/" both mean "served from the host
+ * root" and both normalise to "".
+ *
+ *   normalizeBasePath("admin")   -> "/admin"
+ *   normalizeBasePath("/admin/") -> "/admin"
+ *   normalizeBasePath("/")       -> ""
+ */
+export declare function normalizeBasePath(raw: string): string;
+/**
+ * joinBasePath prefixes an app-internal path with an ALREADY-NORMALISED base
+ * path (see normalizeBasePath).
+ *
+ * Contract:
+ *   - Idempotent: a path already under basePath is returned unchanged, so
+ *     double-wrapping never double-prefixes.
+ *   - Absolute http(s) URLs pass through untouched.
+ *   - Accepts paths with or without a leading "/".
+ *
+ * Examples (basePath "/admin"):
+ *   joinBasePath("/admin", "/billing/success") -> "/admin/billing/success"
+ *   joinBasePath("/admin", "billing/success")  -> "/admin/billing/success"
+ *   joinBasePath("/admin", "/admin/billing")   -> "/admin/billing"  (idempotent)
+ *   joinBasePath("/admin", "/")                -> "/admin"
+ *   joinBasePath("/admin", "https://x.test/y") -> "https://x.test/y"
+ *
+ * Most callers want the bound one-argument form from createBasePath() rather
+ * than repeating the prefix at every call site.
+ */
+export declare function joinBasePath(basePath: string, path: string): string;
+/** What createBasePath() hands back: the normalised prefix and a joiner bound to it. */
+export interface BasePathHelpers {
+    /**
+     * The effective mount prefix, normalised. "" means the frontend is served
+     * from the host root.
+     */
+    BASE_PATH: string;
+    /** joinBasePath, bound to BASE_PATH — the one-argument form apps call. */
+    joinBasePath: (path: string) => string;
+}
+/**
+ * createBasePath binds the prefix once, at module scope, and returns the pair
+ * an app actually imports.
+ *
+ * This is the seam forge's generated `src/lib/basepath_gen.ts` is reduced to:
+ *
+ *   export const { BASE_PATH, joinBasePath } = createBasePath(
+ *     process.env.NEXT_PUBLIC_BASE_PATH ?? "/admin",
+ *   );
+ *
+ * The `process.env.NEXT_PUBLIC_*` read STAYS in project code and cannot move
+ * here: Next.js inlines those literals by substituting them into the sources
+ * it compiles, so a library reading process.env at runtime finds nothing in a
+ * browser bundle. The value is the project's; the behaviour is this package's.
+ */
+export declare function createBasePath(raw: string): BasePathHelpers;

package/dist/basepath.js

@@ -0,0 +1,102 @@
+// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// The mount-prefix primitives: normalising a raw `base_path` value, and
+// prefixing an app-internal path with it.
+//
+// WHY THIS IS A LIBRARY AND NOT A GENERATED FILE. The prefix ITSELF is
+// project-specific — it comes from forge.yaml's `frontends[].base_path`, with
+// NEXT_PUBLIC_BASE_PATH as the build-time override. The RULES for handling it
+// are not: leading slash, no trailing slash, idempotent joins, absolute URLs
+// untouched. Those rules are identical in every project, and every one of the
+// edge cases below is one somebody has shipped a broken deploy over. So the
+// project keeps the value and this module keeps the behaviour.
+//
+// WHEN AN APP NEEDS THIS AT ALL. Next.js prepends the configured basePath to
+// `<Link href>` and `useRouter().push()` on its own — keep passing
+// app-relative paths there. This is for the URLs Next.js never sees:
+//
+//   - window.location-built absolute URLs handed to external systems that
+//     round-trip back into the app: payment-provider redirect / return URLs
+//     (Stripe success_url / cancel_url), OAuth redirect_uri, share links,
+//     magic-link emails;
+//   - raw fetch() / EventSource / <a> / <img> paths built by string
+//     concatenation rather than rendered through Next's router.
+//
+// The anti-pattern this exists to kill is the hand-baked prefix literal
+// (`"/admin" + path`) and the bare `/route` string in a hand-built URL — they
+// bypass the prefix, or double it, the day the mount point moves.
+//
+// This module is in the BARREL, not behind a subpath: it is three string
+// functions with no imports at all, so there is no optional dependency for a
+// subpath to fence off and nothing for a bundler to fail to shake out.
+/**
+ * normalizeBasePath canonicalises a raw base-path value: ensure a leading
+ * "/", drop any trailing "/". "" and "/" both mean "served from the host
+ * root" and both normalise to "".
+ *
+ *   normalizeBasePath("admin")   -> "/admin"
+ *   normalizeBasePath("/admin/") -> "/admin"
+ *   normalizeBasePath("/")       -> ""
+ */
+export function normalizeBasePath(raw) {
+    if (!raw || raw === "/")
+        return "";
+    const withLeading = raw.startsWith("/") ? raw : `/${raw}`;
+    return withLeading.endsWith("/") ? withLeading.slice(0, -1) : withLeading;
+}
+/**
+ * joinBasePath prefixes an app-internal path with an ALREADY-NORMALISED base
+ * path (see normalizeBasePath).
+ *
+ * Contract:
+ *   - Idempotent: a path already under basePath is returned unchanged, so
+ *     double-wrapping never double-prefixes.
+ *   - Absolute http(s) URLs pass through untouched.
+ *   - Accepts paths with or without a leading "/".
+ *
+ * Examples (basePath "/admin"):
+ *   joinBasePath("/admin", "/billing/success") -> "/admin/billing/success"
+ *   joinBasePath("/admin", "billing/success")  -> "/admin/billing/success"
+ *   joinBasePath("/admin", "/admin/billing")   -> "/admin/billing"  (idempotent)
+ *   joinBasePath("/admin", "/")                -> "/admin"
+ *   joinBasePath("/admin", "https://x.test/y") -> "https://x.test/y"
+ *
+ * Most callers want the bound one-argument form from createBasePath() rather
+ * than repeating the prefix at every call site.
+ */
+export function joinBasePath(basePath, path) {
+    if (/^https?:\/\//i.test(path))
+        return path;
+    const withLeading = path.startsWith("/") ? path : `/${path}`;
+    if (!basePath)
+        return withLeading;
+    if (withLeading === basePath || withLeading.startsWith(`${basePath}/`)) {
+        return withLeading;
+    }
+    if (withLeading === "/")
+        return basePath;
+    return `${basePath}${withLeading}`;
+}
+/**
+ * createBasePath binds the prefix once, at module scope, and returns the pair
+ * an app actually imports.
+ *
+ * This is the seam forge's generated `src/lib/basepath_gen.ts` is reduced to:
+ *
+ *   export const { BASE_PATH, joinBasePath } = createBasePath(
+ *     process.env.NEXT_PUBLIC_BASE_PATH ?? "/admin",
+ *   );
+ *
+ * The `process.env.NEXT_PUBLIC_*` read STAYS in project code and cannot move
+ * here: Next.js inlines those literals by substituting them into the sources
+ * it compiles, so a library reading process.env at runtime finds nothing in a
+ * browser bundle. The value is the project's; the behaviour is this package's.
+ */
+export function createBasePath(raw) {
+    const BASE_PATH = normalizeBasePath(raw);
+    return {
+        BASE_PATH,
+        joinBasePath: (path) => joinBasePath(BASE_PATH, path),
+    };
+}
+//# sourceMappingURL=basepath.js.map

package/dist/basepath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"basepath.js","sourceRoot":"","sources":["../src/basepath.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,wEAAwE;AACxE,0CAA0C;AAC1C,EAAE;AACF,uEAAuE;AACvE,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,+DAA+D;AAC/D,EAAE;AACF,6EAA6E;AAC7E,mEAAmE;AACnE,qEAAqE;AACrE,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,0EAA0E;AAC1E,yBAAyB;AACzB,oEAAoE;AACpE,gEAAgE;AAChE,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,kEAAkE;AAClE,EAAE;AACF,yEAAyE;AACzE,6EAA6E;AAC7E,uEAAuE;AAEvE;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,WAAW,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;IAC1D,OAAO,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC;AAC5E,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,IAAY;IACzD,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;IAC7D,IAAI,CAAC,QAAQ;QAAE,OAAO,WAAW,CAAC;IAClC,IAAI,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,CAAC,EAAE,CAAC;QACvE,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,IAAI,WAAW,KAAK,GAAG;QAAE,OAAO,QAAQ,CAAC;IACzC,OAAO,GAAG,QAAQ,GAAG,WAAW,EAAE,CAAC;AACrC,CAAC;AAaD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,SAAS,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACzC,OAAO;QACL,SAAS;QACT,YAAY,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC;KAC9D,CAAC;AACJ,CAAC","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// The mount-prefix primitives: normalising a raw `base_path` value, and\n// prefixing an app-internal path with it.\n//\n// WHY THIS IS A LIBRARY AND NOT A GENERATED FILE. The prefix ITSELF is\n// project-specific — it comes from forge.yaml's `frontends[].base_path`, with\n// NEXT_PUBLIC_BASE_PATH as the build-time override. The RULES for handling it\n// are not: leading slash, no trailing slash, idempotent joins, absolute URLs\n// untouched. Those rules are identical in every project, and every one of the\n// edge cases below is one somebody has shipped a broken deploy over. So the\n// project keeps the value and this module keeps the behaviour.\n//\n// WHEN AN APP NEEDS THIS AT ALL. Next.js prepends the configured basePath to\n// `<Link href>` and `useRouter().push()` on its own — keep passing\n// app-relative paths there. This is for the URLs Next.js never sees:\n//\n//   - window.location-built absolute URLs handed to external systems that\n//     round-trip back into the app: payment-provider redirect / return URLs\n//     (Stripe success_url / cancel_url), OAuth redirect_uri, share links,\n//     magic-link emails;\n//   - raw fetch() / EventSource / <a> / <img> paths built by string\n//     concatenation rather than rendered through Next's router.\n//\n// The anti-pattern this exists to kill is the hand-baked prefix literal\n// (`\"/admin\" + path`) and the bare `/route` string in a hand-built URL — they\n// bypass the prefix, or double it, the day the mount point moves.\n//\n// This module is in the BARREL, not behind a subpath: it is three string\n// functions with no imports at all, so there is no optional dependency for a\n// subpath to fence off and nothing for a bundler to fail to shake out.\n\n/**\n * normalizeBasePath canonicalises a raw base-path value: ensure a leading\n * \"/\", drop any trailing \"/\". \"\" and \"/\" both mean \"served from the host\n * root\" and both normalise to \"\".\n *\n *   normalizeBasePath(\"admin\")   -> \"/admin\"\n *   normalizeBasePath(\"/admin/\") -> \"/admin\"\n *   normalizeBasePath(\"/\")       -> \"\"\n */\nexport function normalizeBasePath(raw: string): string {\n  if (!raw || raw === \"/\") return \"\";\n  const withLeading = raw.startsWith(\"/\") ? raw : `/${raw}`;\n  return withLeading.endsWith(\"/\") ? withLeading.slice(0, -1) : withLeading;\n}\n\n/**\n * joinBasePath prefixes an app-internal path with an ALREADY-NORMALISED base\n * path (see normalizeBasePath).\n *\n * Contract:\n *   - Idempotent: a path already under basePath is returned unchanged, so\n *     double-wrapping never double-prefixes.\n *   - Absolute http(s) URLs pass through untouched.\n *   - Accepts paths with or without a leading \"/\".\n *\n * Examples (basePath \"/admin\"):\n *   joinBasePath(\"/admin\", \"/billing/success\") -> \"/admin/billing/success\"\n *   joinBasePath(\"/admin\", \"billing/success\")  -> \"/admin/billing/success\"\n *   joinBasePath(\"/admin\", \"/admin/billing\")   -> \"/admin/billing\"  (idempotent)\n *   joinBasePath(\"/admin\", \"/\")                -> \"/admin\"\n *   joinBasePath(\"/admin\", \"https://x.test/y\") -> \"https://x.test/y\"\n *\n * Most callers want the bound one-argument form from createBasePath() rather\n * than repeating the prefix at every call site.\n */\nexport function joinBasePath(basePath: string, path: string): string {\n  if (/^https?:\\/\\//i.test(path)) return path;\n  const withLeading = path.startsWith(\"/\") ? path : `/${path}`;\n  if (!basePath) return withLeading;\n  if (withLeading === basePath || withLeading.startsWith(`${basePath}/`)) {\n    return withLeading;\n  }\n  if (withLeading === \"/\") return basePath;\n  return `${basePath}${withLeading}`;\n}\n\n/** What createBasePath() hands back: the normalised prefix and a joiner bound to it. */\nexport interface BasePathHelpers {\n  /**\n   * The effective mount prefix, normalised. \"\" means the frontend is served\n   * from the host root.\n   */\n  BASE_PATH: string;\n  /** joinBasePath, bound to BASE_PATH — the one-argument form apps call. */\n  joinBasePath: (path: string) => string;\n}\n\n/**\n * createBasePath binds the prefix once, at module scope, and returns the pair\n * an app actually imports.\n *\n * This is the seam forge's generated `src/lib/basepath_gen.ts` is reduced to:\n *\n *   export const { BASE_PATH, joinBasePath } = createBasePath(\n *     process.env.NEXT_PUBLIC_BASE_PATH ?? \"/admin\",\n *   );\n *\n * The `process.env.NEXT_PUBLIC_*` read STAYS in project code and cannot move\n * here: Next.js inlines those literals by substituting them into the sources\n * it compiles, so a library reading process.env at runtime finds nothing in a\n * browser bundle. The value is the project's; the behaviour is this package's.\n */\nexport function createBasePath(raw: string): BasePathHelpers {\n  const BASE_PATH = normalizeBasePath(raw);\n  return {\n    BASE_PATH,\n    joinBasePath: (path: string) => joinBasePath(BASE_PATH, path),\n  };\n}\n"]}

package/dist/error-boundary.d.ts

@@ -0,0 +1,31 @@
+import { Component, type ErrorInfo, type ReactElement, type ReactNode } from "react";
+interface FallbackProps {
+    error: Error;
+    reset: () => void;
+}
+interface Props {
+    children: ReactNode;
+    /** Custom fallback UI. Defaults to DefaultErrorFallback. */
+    fallback?: (props: FallbackProps) => ReactNode;
+    /** Reporter hook — wire to telemetry (initClientTelemetry) or Sentry. */
+    onError?: (error: Error, info: ErrorInfo) => void;
+    /** When any value in this array changes, the boundary resets. */
+    resetKeys?: unknown[];
+    /** Compact single-line fallback (for small subtrees). */
+    compact?: boolean;
+}
+interface State {
+    error: Error | null;
+}
+export declare class RuntimeErrorBoundary extends Component<Props, State> {
+    constructor(props: Props);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    componentDidUpdate(prev: Props): void;
+    reset: () => void;
+    render(): ReactNode;
+}
+export declare function DefaultErrorFallback({ error, reset, compact, }: FallbackProps & {
+    compact?: boolean;
+}): ReactElement;
+export {};

package/dist/error-boundary.js

@@ -0,0 +1,62 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// A React error boundary with a designed fallback. Next.js file-convention
+// boundaries (app/error.tsx, app/global-error.tsx) catch route render
+// crashes; this component boundary lets you ALSO isolate a subtree — a
+// dashboard widget, a <Resource> table — so one crashing panel degrades to a
+// small fallback instead of taking the whole route (or the app) white.
+import { Component, } from "react";
+export class RuntimeErrorBoundary extends Component {
+    constructor(props) {
+        super(props);
+        this.state = { error: null };
+    }
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    componentDidCatch(error, info) {
+        // Always log; the app can additionally forward to a sink via onError.
+        console.error("[runtime] error boundary caught:", error, info);
+        this.props.onError?.(error, info);
+    }
+    componentDidUpdate(prev) {
+        if (this.state.error && !shallowEqual(prev.resetKeys, this.props.resetKeys)) {
+            this.reset();
+        }
+    }
+    reset = () => {
+        this.setState({ error: null });
+    };
+    render() {
+        const { error } = this.state;
+        if (!error) {
+            return this.props.children;
+        }
+        if (this.props.fallback) {
+            return this.props.fallback({ error, reset: this.reset });
+        }
+        return (_jsx(DefaultErrorFallback, { error: error, reset: this.reset, compact: this.props.compact }));
+    }
+}
+function shallowEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (!a || !b || a.length !== b.length) {
+        return false;
+    }
+    return a.every((v, i) => Object.is(v, b[i]));
+}
+// The `: ReactElement` here and on every other exported component is
+// load-bearing, not decoration — see README, "One .d.ts for React 18 and 19".
+// Inferring it makes the published declaration name a type whose SPELLING
+// differs between the two @types/react majors this package supports.
+export function DefaultErrorFallback({ error, reset, compact, }) {
+    if (compact) {
+        return (_jsxs("div", { role: "alert", className: "flex items-center justify-between gap-3 rounded-md border border-danger-border bg-danger-surface px-3 py-2 text-sm text-danger-ink", children: [_jsx("span", { className: "truncate", children: "Couldn't load this section." }), _jsx("button", { type: "button", onClick: reset, className: "shrink-0 font-medium text-danger underline hover:text-danger-hover", children: "Retry" })] }));
+    }
+    return (_jsxs("div", { role: "alert", className: "flex min-h-[12rem] flex-col items-center justify-center gap-3 rounded-lg border border-danger-border bg-danger-surface p-8 text-center", children: [_jsx("h2", { className: "text-lg font-semibold text-danger-ink", children: "Something went wrong" }), _jsx("p", { className: "max-w-md text-sm text-danger-ink", children: "This section ran into an unexpected error. You can try again \u2014 the rest of the app is still working." }), _jsx("p", { className: "max-w-md font-mono text-xs text-danger", children: error.message }), _jsx("button", { type: "button", onClick: reset, className: "mt-1 rounded-md bg-danger px-4 py-2 text-sm font-medium text-on-danger hover:bg-danger-hover", children: "Try again" })] }));
+}
+//# sourceMappingURL=error-boundary.js.map

package/dist/error-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-boundary.js","sourceRoot":"","sources":["../src/error-boundary.tsx"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\n// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// A React error boundary with a designed fallback. Next.js file-convention\n// boundaries (app/error.tsx, app/global-error.tsx) catch route render\n// crashes; this component boundary lets you ALSO isolate a subtree — a\n// dashboard widget, a <Resource> table — so one crashing panel degrades to a\n// small fallback instead of taking the whole route (or the app) white.\nimport {\n  Component,\n  type ErrorInfo,\n  type ReactElement,\n  type ReactNode,\n} from \"react\";\n\ninterface FallbackProps {\n  error: Error;\n  reset: () => void;\n}\n\ninterface Props {\n  children: ReactNode;\n  /** Custom fallback UI. Defaults to DefaultErrorFallback. */\n  fallback?: (props: FallbackProps) => ReactNode;\n  /** Reporter hook — wire to telemetry (initClientTelemetry) or Sentry. */\n  onError?: (error: Error, info: ErrorInfo) => void;\n  /** When any value in this array changes, the boundary resets. */\n  resetKeys?: unknown[];\n  /** Compact single-line fallback (for small subtrees). */\n  compact?: boolean;\n}\n\ninterface State {\n  error: Error | null;\n}\n\nexport class RuntimeErrorBoundary extends Component<Props, State> {\n  constructor(props: Props) {\n    super(props);\n    this.state = { error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): State {\n    return { error };\n  }\n\n  componentDidCatch(error: Error, info: ErrorInfo): void {\n    // Always log; the app can additionally forward to a sink via onError.\n    console.error(\"[runtime] error boundary caught:\", error, info);\n    this.props.onError?.(error, info);\n  }\n\n  componentDidUpdate(prev: Props): void {\n    if (this.state.error && !shallowEqual(prev.resetKeys, this.props.resetKeys)) {\n      this.reset();\n    }\n  }\n\n  reset = (): void => {\n    this.setState({ error: null });\n  };\n\n  render(): ReactNode {\n    const { error } = this.state;\n    if (!error) {\n      return this.props.children;\n    }\n    if (this.props.fallback) {\n      return this.props.fallback({ error, reset: this.reset });\n    }\n    return (\n      <DefaultErrorFallback\n        error={error}\n        reset={this.reset}\n        compact={this.props.compact}\n      />\n    );\n  }\n}\n\nfunction shallowEqual(a?: unknown[], b?: unknown[]): boolean {\n  if (a === b) {\n    return true;\n  }\n  if (!a || !b || a.length !== b.length) {\n    return false;\n  }\n  return a.every((v, i) => Object.is(v, b[i]));\n}\n\n// The `: ReactElement` here and on every other exported component is\n// load-bearing, not decoration — see README, \"One .d.ts for React 18 and 19\".\n// Inferring it makes the published declaration name a type whose SPELLING\n// differs between the two @types/react majors this package supports.\nexport function DefaultErrorFallback({\n  error,\n  reset,\n  compact,\n}: FallbackProps & { compact?: boolean }): ReactElement {\n  if (compact) {\n    return (\n      <div\n        role=\"alert\"\n        className=\"flex items-center justify-between gap-3 rounded-md border border-danger-border bg-danger-surface px-3 py-2 text-sm text-danger-ink\"\n      >\n        <span className=\"truncate\">Couldn&apos;t load this section.</span>\n        <button\n          type=\"button\"\n          onClick={reset}\n          className=\"shrink-0 font-medium text-danger underline hover:text-danger-hover\"\n        >\n          Retry\n        </button>\n      </div>\n    );\n  }\n  return (\n    <div\n      role=\"alert\"\n      className=\"flex min-h-[12rem] flex-col items-center justify-center gap-3 rounded-lg border border-danger-border bg-danger-surface p-8 text-center\"\n    >\n      <h2 className=\"text-lg font-semibold text-danger-ink\">\n        Something went wrong\n      </h2>\n      <p className=\"max-w-md text-sm text-danger-ink\">\n        This section ran into an unexpected error. You can try again — the rest\n        of the app is still working.\n      </p>\n      <p className=\"max-w-md font-mono text-xs text-danger\">{error.message}</p>\n      <button\n        type=\"button\"\n        onClick={reset}\n        className=\"mt-1 rounded-md bg-danger px-4 py-2 text-sm font-medium text-on-danger hover:bg-danger-hover\"\n      >\n        Try again\n      </button>\n    </div>\n  );\n}\n"]}

package/dist/errors.d.ts

@@ -0,0 +1,90 @@
+import { Code } from "@connectrpc/connect";
+/**
+ * FORGE_ERROR_REASON_HEADER is the Connect trailer/metadata key carrying a
+ * stable, machine-readable reason code (snake_case) the backend sets for
+ * every error. UI/routing keys off `error.reason` instead of matching
+ * human-readable message strings — the message text is display-only and
+ * may change. The backend owns the setter; the frontend only reads it.
+ */
+export declare const FORGE_ERROR_REASON_HEADER = "x-forge-error-reason";
+/**
+ * stripServerFraming removes the transport framing that must never surface
+ * to a user: the leading "[code] " gRPC-code prefix connect-es puts on
+ * `ConnectError.message`. What survives is the message the server wrote,
+ * which is exactly what a user should read.
+ *
+ * This is the SINGLE implementation — a project never wants a different
+ * answer here, and a copy frozen into a scaffold could never be corrected
+ * once shipped. Idempotent: framing that has already been stripped strips
+ * to itself.
+ */
+export declare function stripServerFraming(message: string): string;
+/**
+ * userMessage — turn any thrown value into copy fit for end users.
+ *
+ * `ConnectError.message` prefixes the gRPC code ("[not_found] no such task");
+ * `rawMessage` is the server's human-readable text without that framing, and
+ * stripServerFraming drops the prefix from whichever of the two is available.
+ * Use this everywhere an error is SHOWN (banners, toasts) instead of
+ * `err.message`.
+ *
+ * Pass `fallback` to override the default copy for a surface that wants its
+ * own wording.
+ */
+export declare function userMessage(err: unknown, fallback?: string): string;
+/**
+ * ConnectClientError is the single typed error shape the app catches. It is
+ * a plain Error subclass so it works with React Query, error boundaries, and
+ * `instanceof` alike.
+ */
+export declare class ConnectClientError extends Error {
+    /** Canonical Connect code name, e.g. "unavailable", "not_found". */
+    readonly code: string;
+    /** Numeric Connect code (Code enum), or undefined for non-Connect errors. */
+    readonly connectCode?: Code;
+    /** Approximate HTTP status, for telemetry and generic UI. */
+    readonly status: number;
+    /** True when a transparent retry is reasonable (transient failures). */
+    readonly retryable: boolean;
+    /**
+     * Stable machine-readable reason code from the backend
+     * (x-forge-error-reason metadata), or null. Key UI/routing off THIS,
+     * never off `message` — message text is display-only.
+     */
+    readonly reason: string | null;
+    constructor(args: {
+        message: string;
+        code: string;
+        connectCode?: Code;
+        status: number;
+        retryable: boolean;
+        reason?: string | null;
+        cause?: unknown;
+    });
+    /**
+     * `instanceof` matches on SHAPE, not on class identity — so every check
+     * spelled `err instanceof ConnectClientError`, here and in app code, keeps
+     * working when two copies of this package end up in one bundle (see
+     * {@link isConnectClientErrorShape}). Without it, normalizeError's
+     * pass-through guard misses an already-normalized error from the other
+     * copy; that error's `name` is "ConnectClientError" rather than
+     * "ConnectError", so it misses the ConnectError branch too and is re-wrapped
+     * through the generic Error branch — silently downgrading every error in the
+     * app to code "unknown", status 500, no connectCode and no reason.
+     * @connectrpc/connect does the same on ConnectError, for the same reason.
+     */
+    static [Symbol.hasInstance](v: unknown): boolean;
+}
+/** isRetryable reports whether a Connect code merits a transport retry. */
+export declare function isRetryableCode(code: Code): boolean;
+/**
+ * normalizeError coerces any thrown value into a ConnectClientError. Already-
+ * normalized errors pass through unchanged so the interceptor chain never
+ * double-wraps.
+ *
+ * Both `instanceof` checks below match on SHAPE rather than class identity —
+ * ours via ConnectClientError's Symbol.hasInstance, ConnectError's via the one
+ * @connectrpc/connect ships — so neither branch is missed when a second copy
+ * of either package lands in the bundle.
+ */
+export declare function normalizeError(err: unknown): ConnectClientError;