@reliantlabs/forge-web-runtime 0.3.1 → 0.4.0

package/dist/error-boundary.js.map

@@ -1 +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 (\n      this.state.error &&\n      !shallowEqual(prev.resetKeys, this.props.resetKeys)\n    ) {\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"]}
+{"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\nimport { reportException } from \"./error-reporter.js\";\nimport { userMessage } from \"./errors.js\";\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  /** Extra reporter hook, called after the error is recorded with the browser telemetry SDK. */\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, and record with the browser telemetry SDK (a no-op when\n    // none is running); the app can additionally forward to a sink via onError.\n    console.error(\"[runtime] error boundary caught:\", error, info);\n    reportException(error, {\n      \"react.component_stack\": info.componentStack ?? \"\",\n      \"error.handled_by\": \"RuntimeErrorBoundary\",\n    });\n    this.props.onError?.(error, info);\n  }\n\n  componentDidUpdate(prev: Props): void {\n    if (\n      this.state.error &&\n      !shallowEqual(prev.resetKeys, this.props.resetKeys)\n    ) {\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      {/* userMessage, never error.message — the same display rule as\n          <Resource>'s error rung. */}\n      <p className=\"max-w-md text-sm text-danger-ink\">{userMessage(error)}</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/error-reporter.d.ts

@@ -0,0 +1,27 @@
+/** Span/log attribute values the recorder accepts. */
+export type ExceptionAttributes = Record<string, string | number | boolean>;
+type ExceptionReporter = (error: unknown, attributes?: ExceptionAttributes) => void;
+/**
+ * Install (or clear, with null) the recorder reportException forwards to.
+ * Called by initBrowserTelemetry; an app has no reason to call it directly.
+ */
+export declare function setExceptionReporter(next: ExceptionReporter | null): void;
+/**
+ * reportException hands a caught error to the browser telemetry SDK, if one
+ * is running. Never throws: reporting an error must not become a second
+ * error.
+ *
+ * Returns true when the SDK has the error and false when no SDK is running —
+ * so a caller can fall back to console.error and an error never vanishes:
+ *
+ *     if (!reportException(error)) console.error(error);
+ *
+ * Use it where React or Next catch an error for you (error boundaries,
+ * `error.tsx`). The SDK already records uncaught exceptions, unhandled
+ * rejections and anything passed to console.error, and React logs a
+ * boundary-caught error to console.error itself, so the recorder installed
+ * by `/telemetry` skips an error the SDK has already seen: one failure is
+ * one record, never two.
+ */
+export declare function reportException(error: unknown, attributes?: ExceptionAttributes): boolean;
+export {};

package/dist/error-reporter.js

@@ -0,0 +1,55 @@
+// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// The seam between "something threw" and "somebody recorded it".
+//
+// The error boundary and the Next.js error files live in the barrel, which
+// every frontend imports — including the Vite SPA and React Native ones that
+// never install the HyperDX browser SDK. So the barrel cannot import the SDK.
+// It imports this dependency-free registry instead, and the `/telemetry`
+// subpath (which does import the SDK) installs the real recorder here once the
+// SDK has initialised. Until then — SSR, telemetry off, SDK still loading —
+// reportException is a no-op, which is what makes it safe to call from any
+// catch block unconditionally.
+/**
+ * Reports which recorder is installed, if any. reportException's return
+ * value is "the telemetry SDK has this error" — true both when it was just
+ * recorded and when it had already been recorded by another route.
+ */
+let reporter = null;
+/**
+ * Install (or clear, with null) the recorder reportException forwards to.
+ * Called by initBrowserTelemetry; an app has no reason to call it directly.
+ */
+export function setExceptionReporter(next) {
+    reporter = next;
+}
+/**
+ * reportException hands a caught error to the browser telemetry SDK, if one
+ * is running. Never throws: reporting an error must not become a second
+ * error.
+ *
+ * Returns true when the SDK has the error and false when no SDK is running —
+ * so a caller can fall back to console.error and an error never vanishes:
+ *
+ *     if (!reportException(error)) console.error(error);
+ *
+ * Use it where React or Next catch an error for you (error boundaries,
+ * `error.tsx`). The SDK already records uncaught exceptions, unhandled
+ * rejections and anything passed to console.error, and React logs a
+ * boundary-caught error to console.error itself, so the recorder installed
+ * by `/telemetry` skips an error the SDK has already seen: one failure is
+ * one record, never two.
+ */
+export function reportException(error, attributes) {
+    if (!reporter) {
+        return false;
+    }
+    try {
+        reporter(error, attributes);
+    }
+    catch {
+        // Telemetry must never break the app.
+    }
+    return true;
+}
+//# sourceMappingURL=error-reporter.js.map

package/dist/error-reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-reporter.js","sourceRoot":"","sources":["../src/error-reporter.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,iEAAiE;AACjE,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,8EAA8E;AAC9E,yEAAyE;AACzE,+EAA+E;AAC/E,4EAA4E;AAC5E,2EAA2E;AAC3E,+BAA+B;AAU/B;;;;GAIG;AAEH,IAAI,QAAQ,GAA6B,IAAI,CAAC;AAE9C;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAA8B;IACjE,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAc,EACd,UAAgC;IAEhC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC;QACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,sCAAsC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// The seam between \"something threw\" and \"somebody recorded it\".\n//\n// The error boundary and the Next.js error files live in the barrel, which\n// every frontend imports — including the Vite SPA and React Native ones that\n// never install the HyperDX browser SDK. So the barrel cannot import the SDK.\n// It imports this dependency-free registry instead, and the `/telemetry`\n// subpath (which does import the SDK) installs the real recorder here once the\n// SDK has initialised. Until then — SSR, telemetry off, SDK still loading —\n// reportException is a no-op, which is what makes it safe to call from any\n// catch block unconditionally.\n\n/** Span/log attribute values the recorder accepts. */\nexport type ExceptionAttributes = Record<string, string | number | boolean>;\n\ntype ExceptionReporter = (\n  error: unknown,\n  attributes?: ExceptionAttributes,\n) => void;\n\n/**\n * Reports which recorder is installed, if any. reportException's return\n * value is \"the telemetry SDK has this error\" — true both when it was just\n * recorded and when it had already been recorded by another route.\n */\n\nlet reporter: ExceptionReporter | null = null;\n\n/**\n * Install (or clear, with null) the recorder reportException forwards to.\n * Called by initBrowserTelemetry; an app has no reason to call it directly.\n */\nexport function setExceptionReporter(next: ExceptionReporter | null): void {\n  reporter = next;\n}\n\n/**\n * reportException hands a caught error to the browser telemetry SDK, if one\n * is running. Never throws: reporting an error must not become a second\n * error.\n *\n * Returns true when the SDK has the error and false when no SDK is running —\n * so a caller can fall back to console.error and an error never vanishes:\n *\n *     if (!reportException(error)) console.error(error);\n *\n * Use it where React or Next catch an error for you (error boundaries,\n * `error.tsx`). The SDK already records uncaught exceptions, unhandled\n * rejections and anything passed to console.error, and React logs a\n * boundary-caught error to console.error itself, so the recorder installed\n * by `/telemetry` skips an error the SDK has already seen: one failure is\n * one record, never two.\n */\nexport function reportException(\n  error: unknown,\n  attributes?: ExceptionAttributes,\n): boolean {\n  if (!reporter) {\n    return false;\n  }\n  try {\n    reporter(error, attributes);\n  } catch {\n    // Telemetry must never break the app.\n  }\n  return true;\n}\n"]}

package/dist/index.d.ts

@@ -13,6 +13,15 @@ export { ConnectClientError, FORGE_ERROR_REASON_HEADER, isRetryableCode, normali
  * no imports, so there is no dependency footprint for a subpath to fence off.
  */
 export { createBasePath, joinBasePath, normalizeBasePath, type BasePathHelpers, } from "./basepath.js";
+/**
+ * Money and basis points as integers: format minor units through Intl, and
+ * parse form input back to minor units without rounding.
+ *
+ * The web counterpart of forge/pkg/money — an int64 count of the currency's
+ * minor unit plus an ISO 4217 code, exact past 2^53. Barrel-exported for the
+ * same reason as the base-path helpers: it imports nothing.
+ */
+export { basisPointsToInput, currencyMinorDigits, formatBasisPoints, formatMinorUnits, minorUnitsToInput, parseBasisPoints, parseMinorUnits, type BasisPointsOptions, type MoneyOptions, type ParseBasisPointsOptions, type ParseMoneyOptions, } from "./money.js";
 /** W3C trace-context propagation. */
 export { freshTraceparent, injectTraceContext, setTraceSampled, TRACEPARENT_RE, } from "./trace.js";
 /** Session: the signed-in user, derived from the app's auth state and JWT claims. */
@@ -27,8 +36,12 @@ export { RuntimeToastHost, type RuntimeToast, type RuntimeToastHostProps, type R
 export { RouteGuard, type RouteGuardProps } from "./route-guard.js";
 /** Generic data-table container: the tristate ladder, filter and cursor pagination. */
 export { Resource, type ResourceColumn, type ResourceProps, type ResourceStatus, } from "./resource.js";
-/** Client RUM (opt-in export). */
-export { initClientTelemetry, type TelemetryConfig, type TelemetryEvent, } from "./telemetry.js";
+/**
+ * Record a caught error with the browser telemetry SDK, when one is running.
+ * A no-op otherwise, so it is safe in any catch block. The SDK itself arrives
+ * through the "/telemetry" subpath, never the barrel.
+ */
+export { reportException, setExceptionReporter, type ExceptionAttributes, } from "./error-reporter.js";
 /**
  * Dev-only browser log forwarding: mirrors console output and uncaught errors
  * to the dev server, which prints them into

package/dist/index.js

@@ -31,6 +31,15 @@ export { ConnectClientError, FORGE_ERROR_REASON_HEADER, isRetryableCode, normali
  * no imports, so there is no dependency footprint for a subpath to fence off.
  */
 export { createBasePath, joinBasePath, normalizeBasePath, } from "./basepath.js";
+/**
+ * Money and basis points as integers: format minor units through Intl, and
+ * parse form input back to minor units without rounding.
+ *
+ * The web counterpart of forge/pkg/money — an int64 count of the currency's
+ * minor unit plus an ISO 4217 code, exact past 2^53. Barrel-exported for the
+ * same reason as the base-path helpers: it imports nothing.
+ */
+export { basisPointsToInput, currencyMinorDigits, formatBasisPoints, formatMinorUnits, minorUnitsToInput, parseBasisPoints, parseMinorUnits, } from "./money.js";
 /** W3C trace-context propagation. */
 export { freshTraceparent, injectTraceContext, setTraceSampled, TRACEPARENT_RE, } from "./trace.js";
 /** Session: the signed-in user, derived from the app's auth state and JWT claims. */
@@ -45,8 +54,12 @@ export { RuntimeToastHost, } from "./toast-host.js";
 export { RouteGuard } from "./route-guard.js";
 /** Generic data-table container: the tristate ladder, filter and cursor pagination. */
 export { Resource, } from "./resource.js";
-/** Client RUM (opt-in export). */
-export { initClientTelemetry, } from "./telemetry.js";
+/**
+ * Record a caught error with the browser telemetry SDK, when one is running.
+ * A no-op otherwise, so it is safe in any catch block. The SDK itself arrives
+ * through the "/telemetry" subpath, never the barrel.
+ */
+export { reportException, setExceptionReporter, } from "./error-reporter.js";
 /**
  * Dev-only browser log forwarding: mirrors console output and uncaught errors
  * to the dev server, which prints them into

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,4EAA4E;AAC5E,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,4CAA4C;AAE5C,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,4EAA4E;AAC5E,sEAAsE;AAEtE,mCAAmC;AACnC,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,OAAO,EACL,cAAc,EACd,YAAY,EACZ,iBAAiB,GAElB,MAAM,eAAe,CAAC;AAEvB,qCAAqC;AACrC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,qFAAqF;AACrF,OAAO,EACL,SAAS,EACT,eAAe,EACf,UAAU,GAIX,MAAM,cAAc,CAAC;AAEtB,gFAAgF;AAChF,OAAO,EAAE,YAAY,EAA0B,MAAM,gBAAgB,CAAC;AAEtE,+EAA+E;AAC/E,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,yEAAyE;AACzE,OAAO,EACL,gBAAgB,GAMjB,MAAM,iBAAiB,CAAC;AAEzB,gEAAgE;AAChE,OAAO,EAAE,UAAU,EAAwB,MAAM,kBAAkB,CAAC;AAEpE,uFAAuF;AACvF,OAAO,EACL,QAAQ,GAIT,MAAM,eAAe,CAAC;AAEvB,kCAAkC;AAClC,OAAO,EACL,mBAAmB,GAGpB,MAAM,gBAAgB,CAAC;AAExB;;;;;;GAMG;AACH,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,GAGpB,MAAM,aAAa,CAAC","sourcesContent":["// @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Public barrel. Import batteries from \"@reliantlabs/forge-web-runtime\".\n//\n// Everything here is MECHANISM: the transport interceptor stack, the session,\n// the error boundary, the toast queue, the <Resource> tristate ladder, W3C\n// trace propagation, client RUM. Nothing here reaches into an application —\n// app-shaped values (auth state, event subscriptions, toast markup) arrive as\n// props, so an app can restyle or replace its own files freely.\n//\n// Presentation that a project is meant to own — the component library under\n// src/components/ui, globals.css, nav, layout — deliberately stays in the\n// scaffold and is NOT part of this package.\n\n// The per-group docs below are JSDoc, not `//`, on purpose: TypeScript's\n// declaration emit preserves JSDoc and DROPS line comments, and dist/ is now\n// the whole of what this package publishes. `forge project libraries` reads\n// this inventory out of the published barrel, and a consumer's editor shows\n// it on hover — both would get symbols with no explanation otherwise.\n\n/** Transport interceptor stack. */\nexport {\n  authInterceptor,\n  buildRuntimeInterceptors,\n  errorNormalizeInterceptor,\n  headerInterceptor,\n  retryInterceptor,\n  traceInterceptor,\n  type RuntimeInterceptorConfig,\n} from \"./interceptors.js\";\n\n/**\n * Typed client errors, and the backend-framing strippers every surface that\n * SHOWS an error goes through.\n */\nexport {\n  ConnectClientError,\n  FORGE_ERROR_REASON_HEADER,\n  isRetryableCode,\n  normalizeError,\n  stripServerFraming,\n  userMessage,\n} from \"./errors.js\";\n\n/**\n * Mount-prefix helpers, for the URLs Next.js's router never sees — absolute\n * URLs handed to external systems that round-trip back into the app.\n *\n * Barrel-exported rather than behind a subpath: three string functions with\n * no imports, so there is no dependency footprint for a subpath to fence off.\n */\nexport {\n  createBasePath,\n  joinBasePath,\n  normalizeBasePath,\n  type BasePathHelpers,\n} from \"./basepath.js\";\n\n/** W3C trace-context propagation. */\nexport {\n  freshTraceparent,\n  injectTraceContext,\n  setTraceSampled,\n  TRACEPARENT_RE,\n} from \"./trace.js\";\n\n/** Session: the signed-in user, derived from the app's auth state and JWT claims. */\nexport {\n  decodeJwt,\n  SessionProvider,\n  useSession,\n  type JwtClaims,\n  type Session,\n  type SessionAuth,\n} from \"./session.js\";\n\n/** The app-shell provider set: session + error boundary + toast host in one. */\nexport { RuntimeShell, type RuntimeShellProps } from \"./providers.js\";\n\n/** Error boundary with a designed crash fallback, for a route or a subtree. */\nexport {\n  DefaultErrorFallback,\n  RuntimeErrorBoundary,\n} from \"./error-boundary.js\";\n\n/** The toast queue. The app supplies the event source and the markup. */\nexport {\n  RuntimeToastHost,\n  type RuntimeToast,\n  type RuntimeToastHostProps,\n  type RuntimeToastPayload,\n  type RuntimeToastSink,\n  type RuntimeToastVariant,\n} from \"./toast-host.js\";\n\n/** Route guarding: render a page only to a signed-in caller. */\nexport { RouteGuard, type RouteGuardProps } from \"./route-guard.js\";\n\n/** Generic data-table container: the tristate ladder, filter and cursor pagination. */\nexport {\n  Resource,\n  type ResourceColumn,\n  type ResourceProps,\n  type ResourceStatus,\n} from \"./resource.js\";\n\n/** Client RUM (opt-in export). */\nexport {\n  initClientTelemetry,\n  type TelemetryConfig,\n  type TelemetryEvent,\n} from \"./telemetry.js\";\n\n/**\n * Dev-only browser log forwarding: mirrors console output and uncaught errors\n * to the dev server, which prints them into\n * `.forge/logs/<env>/frontend_<name>.log`. No-ops unless `dev: true`, and the\n * receiving endpoint exists only in a dev server — so a production bundle\n * neither posts nor has anywhere to post to.\n */\nexport {\n  DEV_LOG_ENDPOINT,\n  devLoggingInstalled,\n  installDevLogging,\n  uninstallDevLogging,\n  type DevLoggingOptions,\n  type DevLogPayload,\n} from \"./devlog.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,4EAA4E;AAC5E,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,4CAA4C;AAE5C,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,4EAA4E;AAC5E,sEAAsE;AAEtE,mCAAmC;AACnC,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB;;;;;;GAMG;AACH,OAAO,EACL,cAAc,EACd,YAAY,EACZ,iBAAiB,GAElB,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,GAKhB,MAAM,YAAY,CAAC;AAEpB,qCAAqC;AACrC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,qFAAqF;AACrF,OAAO,EACL,SAAS,EACT,eAAe,EACf,UAAU,GAIX,MAAM,cAAc,CAAC;AAEtB,gFAAgF;AAChF,OAAO,EAAE,YAAY,EAA0B,MAAM,gBAAgB,CAAC;AAEtE,+EAA+E;AAC/E,OAAO,EACL,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,yEAAyE;AACzE,OAAO,EACL,gBAAgB,GAMjB,MAAM,iBAAiB,CAAC;AAEzB,gEAAgE;AAChE,OAAO,EAAE,UAAU,EAAwB,MAAM,kBAAkB,CAAC;AAEpE,uFAAuF;AACvF,OAAO,EACL,QAAQ,GAIT,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,GAErB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,GAGpB,MAAM,aAAa,CAAC","sourcesContent":["// @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Public barrel. Import batteries from \"@reliantlabs/forge-web-runtime\".\n//\n// Everything here is MECHANISM: the transport interceptor stack, the session,\n// the error boundary, the toast queue, the <Resource> tristate ladder, W3C\n// trace propagation, client RUM. Nothing here reaches into an application —\n// app-shaped values (auth state, event subscriptions, toast markup) arrive as\n// props, so an app can restyle or replace its own files freely.\n//\n// Presentation that a project is meant to own — the component library under\n// src/components/ui, globals.css, nav, layout — deliberately stays in the\n// scaffold and is NOT part of this package.\n\n// The per-group docs below are JSDoc, not `//`, on purpose: TypeScript's\n// declaration emit preserves JSDoc and DROPS line comments, and dist/ is now\n// the whole of what this package publishes. `forge project libraries` reads\n// this inventory out of the published barrel, and a consumer's editor shows\n// it on hover — both would get symbols with no explanation otherwise.\n\n/** Transport interceptor stack. */\nexport {\n  authInterceptor,\n  buildRuntimeInterceptors,\n  errorNormalizeInterceptor,\n  headerInterceptor,\n  retryInterceptor,\n  traceInterceptor,\n  type RuntimeInterceptorConfig,\n} from \"./interceptors.js\";\n\n/**\n * Typed client errors, and the backend-framing strippers every surface that\n * SHOWS an error goes through.\n */\nexport {\n  ConnectClientError,\n  FORGE_ERROR_REASON_HEADER,\n  isRetryableCode,\n  normalizeError,\n  stripServerFraming,\n  userMessage,\n} from \"./errors.js\";\n\n/**\n * Mount-prefix helpers, for the URLs Next.js's router never sees — absolute\n * URLs handed to external systems that round-trip back into the app.\n *\n * Barrel-exported rather than behind a subpath: three string functions with\n * no imports, so there is no dependency footprint for a subpath to fence off.\n */\nexport {\n  createBasePath,\n  joinBasePath,\n  normalizeBasePath,\n  type BasePathHelpers,\n} from \"./basepath.js\";\n\n/**\n * Money and basis points as integers: format minor units through Intl, and\n * parse form input back to minor units without rounding.\n *\n * The web counterpart of forge/pkg/money — an int64 count of the currency's\n * minor unit plus an ISO 4217 code, exact past 2^53. Barrel-exported for the\n * same reason as the base-path helpers: it imports nothing.\n */\nexport {\n  basisPointsToInput,\n  currencyMinorDigits,\n  formatBasisPoints,\n  formatMinorUnits,\n  minorUnitsToInput,\n  parseBasisPoints,\n  parseMinorUnits,\n  type BasisPointsOptions,\n  type MoneyOptions,\n  type ParseBasisPointsOptions,\n  type ParseMoneyOptions,\n} from \"./money.js\";\n\n/** W3C trace-context propagation. */\nexport {\n  freshTraceparent,\n  injectTraceContext,\n  setTraceSampled,\n  TRACEPARENT_RE,\n} from \"./trace.js\";\n\n/** Session: the signed-in user, derived from the app's auth state and JWT claims. */\nexport {\n  decodeJwt,\n  SessionProvider,\n  useSession,\n  type JwtClaims,\n  type Session,\n  type SessionAuth,\n} from \"./session.js\";\n\n/** The app-shell provider set: session + error boundary + toast host in one. */\nexport { RuntimeShell, type RuntimeShellProps } from \"./providers.js\";\n\n/** Error boundary with a designed crash fallback, for a route or a subtree. */\nexport {\n  DefaultErrorFallback,\n  RuntimeErrorBoundary,\n} from \"./error-boundary.js\";\n\n/** The toast queue. The app supplies the event source and the markup. */\nexport {\n  RuntimeToastHost,\n  type RuntimeToast,\n  type RuntimeToastHostProps,\n  type RuntimeToastPayload,\n  type RuntimeToastSink,\n  type RuntimeToastVariant,\n} from \"./toast-host.js\";\n\n/** Route guarding: render a page only to a signed-in caller. */\nexport { RouteGuard, type RouteGuardProps } from \"./route-guard.js\";\n\n/** Generic data-table container: the tristate ladder, filter and cursor pagination. */\nexport {\n  Resource,\n  type ResourceColumn,\n  type ResourceProps,\n  type ResourceStatus,\n} from \"./resource.js\";\n\n/**\n * Record a caught error with the browser telemetry SDK, when one is running.\n * A no-op otherwise, so it is safe in any catch block. The SDK itself arrives\n * through the \"/telemetry\" subpath, never the barrel.\n */\nexport {\n  reportException,\n  setExceptionReporter,\n  type ExceptionAttributes,\n} from \"./error-reporter.js\";\n\n/**\n * Dev-only browser log forwarding: mirrors console output and uncaught errors\n * to the dev server, which prints them into\n * `.forge/logs/<env>/frontend_<name>.log`. No-ops unless `dev: true`, and the\n * receiving endpoint exists only in a dev server — so a production bundle\n * neither posts nor has anywhere to post to.\n */\nexport {\n  DEV_LOG_ENDPOINT,\n  devLoggingInstalled,\n  installDevLogging,\n  uninstallDevLogging,\n  type DevLoggingOptions,\n  type DevLogPayload,\n} from \"./devlog.js\";\n"]}

package/dist/mock-transport.d.ts

@@ -20,7 +20,14 @@ export interface MockScenarioRegistry {
     byName(name: string): MockScenario | undefined;
     defaultScenario: MockScenario;
 }
-/** One CRUD arm of an entity's dispatch table. */
+/**
+ * One CRUD arm of an entity's dispatch table.
+ *
+ * The List arm needs nothing beyond these three fields to honour filters,
+ * paging and total_count: the REQUEST schema arrives on every call as the
+ * Connect method's `input`, and the entity schema is the element type of
+ * `itemsField` on `responseSchema`.
+ */
 export interface MockListRpc {
     rpc: string;
     responseSchema: DescMessage;

package/dist/mock-transport.js

@@ -21,12 +21,18 @@
 //   4. Anything else rejects with Code.Unimplemented so callers see a
 //      clear error instead of a silent empty response.
 //
+// A fixture List answers the way the backend's generated CRUD List does
+// (pkg/crud HandleList), so a filtered table, a paged table and a "how many"
+// tile read the same against fixtures as against a server — see
+// `serveList` for the exact contract. Custom (non-CRUD) RPCs are not
+// interpreted at all; they stay hand-written scenario handlers.
+//
 // Imported through the "@reliantlabs/forge-web-runtime/mock-transport" subpath,
 // never the barrel: a production bundle must be able to shake the fixtures
 // and this engine out entirely, which is why the generated `connect.ts`
 // reaches its own shim through a dynamic `require()` gated on the mock-mode
 // env var.
-import { create, } from "@bufbuild/protobuf";
+import { create, ScalarType, } from "@bufbuild/protobuf";
 import { Code, ConnectError, } from "@connectrpc/connect";
 /**
  * Mutable session stores, keyed by descriptor identity.
@@ -117,6 +123,191 @@ function makeUnaryResponse(method, message) {
         trailer: new Headers(),
     };
 }
+// ── List semantics ─────────────────────────────────────────────────────
+//
+// What the backend's generated List does, and therefore what the fixture
+// List does (pkg/crud HandleList + the generated Filters closure):
+//
+//   - Every `optional` request field that is SET filters by equality on the
+//     entity field of the same name. Enums compare by value. A field with
+//     IMPLICIT presence (no `optional`) is never a filter — the backend
+//     generates none for it, so the mock must not invent one.
+//   - `search` matches case-insensitively against the entity's string
+//     fields and enum value names (enum columns are stored as names).
+//   - `order_by` (snake_case column, comma-separated, optional ASC/DESC per
+//     column) plus `descending` sorts; an unknown column is InvalidArgument.
+//   - `page_size` defaults to 50 and is clamped to 100. `total_count` is the
+//     filtered count BEFORE paging. `next_page_token` is minted only for the
+//     default (primary-key) order — an ordered list is single-page on the
+//     backend, and a mock that paged it would hide that.
+//
+// Paging, ordering and search arrive through these request fields, by the
+// names forge's CRUD List requests declare. They are never equality filters.
+const LIST_CONTROL_FIELDS = new Set([
+    "pageSize",
+    "pageToken",
+    "orderBy",
+    "descending",
+    "search",
+]);
+/** pkg/crud ListOp's defaults: 0 means 50, and no page exceeds 100. */
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 100;
+/** FeatureSet_FieldPresence.EXPLICIT — proto3 `optional`, oneofs, messages. */
+const EXPLICIT_PRESENCE = 1;
+/** The entity message a List response repeats, read off its descriptor. */
+function listItemSchema(list) {
+    const items = list.responseSchema.field[list.itemsField];
+    return items?.fieldKind === "list" && items.listKind === "message"
+        ? items.message
+        : undefined;
+}
+/** Scalars and enums compare by value; messages, bytes, lists and maps do not. */
+function isComparable(field) {
+    if (field.fieldKind === "enum")
+        return true;
+    return field.fieldKind === "scalar" && field.scalar !== ScalarType.BYTES;
+}
+function sameValue(a, b) {
+    if (a === b)
+        return true;
+    // A 64-bit field is a bigint — or a string under jstype=JS_STRING — and
+    // the two sides are not guaranteed to agree on which.
+    if (a == null || b == null)
+        return false;
+    return ((typeof a === "bigint" || typeof b === "bigint") && String(a) === String(b));
+}
+function enumName(field, value) {
+    return field.fieldKind === "enum"
+        ? field.enum.values.find((v) => v.number === value)?.name
+        : undefined;
+}
+/** The value a column sorts by, as Postgres would order the stored column. */
+function sortKey(field, value) {
+    if (value == null)
+        return undefined;
+    // Enum columns hold the value NAME, so they sort alphabetically by name.
+    if (field.fieldKind === "enum")
+        return enumName(field, value) ?? "";
+    if (field.fieldKind === "scalar")
+        return value;
+    if (field.fieldKind === "message" &&
+        field.message.typeName === "google.protobuf.Timestamp") {
+        const ts = value;
+        return BigInt(ts.seconds) * 1000000000n + BigInt(ts.nanos);
+    }
+    return undefined;
+}
+/** Postgres's default: NULL sorts after every value ascending. */
+function compareKeys(a, b) {
+    if (a === undefined || b === undefined) {
+        return a === b ? 0 : a === undefined ? 1 : -1;
+    }
+    const x = a;
+    const y = b;
+    return x < y ? -1 : x > y ? 1 : 0;
+}
+function invalidArgument(message) {
+    return new ConnectError(`mock-transport: ${message}`, Code.InvalidArgument);
+}
+/** Parse `order_by` the way orm.ValidateOrderBy reads it. */
+function parseOrderBy(clause, descending, itemSchema) {
+    return clause.split(",").map((part) => {
+        const [column = "", direction] = part.trim().split(/\s+/);
+        const field = itemSchema.fields.find((f) => f.name === column || f.localName === column);
+        if (!field) {
+            throw invalidArgument(`unknown order-by column "${column}"`);
+        }
+        const dir = direction?.toUpperCase();
+        if (dir !== undefined && dir !== "ASC" && dir !== "DESC") {
+            throw invalidArgument(`invalid order-by direction "${direction}"`);
+        }
+        return { field, desc: dir === undefined ? descending : dir === "DESC" };
+    });
+}
+/** A count in whatever JS type the response's total_count field takes. */
+function countValue(field, n) {
+    if (field.fieldKind !== "scalar")
+        return n;
+    switch (field.scalar) {
+        case ScalarType.INT64:
+        case ScalarType.UINT64:
+        case ScalarType.SINT64:
+        case ScalarType.FIXED64:
+        case ScalarType.SFIXED64:
+            return field.longAsString ? String(n) : BigInt(n);
+        default:
+            return n;
+    }
+}
+/**
+ * Answer one List call from the entity's rows. See the List semantics note
+ * above for the contract; the engine's tests pin each clause.
+ */
+function serveList(rows, list, input, requestSchema) {
+    const req = (input ?? {});
+    const itemSchema = listItemSchema(list);
+    let matched = rows;
+    if (itemSchema && requestSchema) {
+        for (const filter of requestSchema.fields) {
+            if (LIST_CONTROL_FIELDS.has(filter.localName))
+                continue;
+            if (filter.presence !== EXPLICIT_PRESENCE || !isComparable(filter)) {
+                continue;
+            }
+            const want = req[filter.localName];
+            if (want == null)
+                continue; // unset: no filter
+            const target = itemSchema.field[filter.localName];
+            if (!target || !isComparable(target))
+                continue;
+            matched = matched.filter((row) => sameValue(row[filter.localName], want));
+        }
+    }
+    const search = typeof req.search === "string" ? req.search.trim().toLowerCase() : "";
+    if (itemSchema && search) {
+        const searchable = itemSchema.fields.filter((f) => f.fieldKind === "enum" ||
+            (f.fieldKind === "scalar" && f.scalar === ScalarType.STRING));
+        matched = matched.filter((row) => searchable.some((f) => {
+            const value = row[f.localName];
+            const text = f.fieldKind === "enum" ? enumName(f, value) : value;
+            return typeof text === "string" && text.toLowerCase().includes(search);
+        }));
+    }
+    const orderBy = typeof req.orderBy === "string" ? req.orderBy.trim() : "";
+    if (itemSchema && orderBy) {
+        const keys = parseOrderBy(orderBy, req.descending === true, itemSchema);
+        matched = [...matched].sort((a, b) => {
+            for (const { field, desc } of keys) {
+                const c = compareKeys(sortKey(field, a[field.localName]), sortKey(field, b[field.localName]));
+                if (c !== 0)
+                    return desc ? -c : c;
+            }
+            return 0;
+        });
+    }
+    const total = matched.length;
+    let offset = 0;
+    const token = typeof req.pageToken === "string" ? req.pageToken : "";
+    if (token) {
+        // The mock's own cursor: an offset into the filtered rows. Opaque to the
+        // client, exactly like the backend's keyset cursor.
+        if (!/^\d+$/.test(token))
+            throw invalidArgument("invalid page token");
+        offset = Number(token);
+    }
+    const requested = Number(req.pageSize ?? 0);
+    const pageSize = requested > 0 ? Math.min(requested, MAX_PAGE_SIZE) : DEFAULT_PAGE_SIZE;
+    const end = offset + pageSize;
+    const init = { [list.itemsField]: matched.slice(offset, end) };
+    const totalField = list.responseSchema.field.totalCount;
+    if (totalField)
+        init.totalCount = countValue(totalField, total);
+    if (list.responseSchema.field.nextPageToken && !orderBy && end < total) {
+        init.nextPageToken = String(end);
+    }
+    return create(list.responseSchema, init);
+}
 /**
  * Compile the entity descriptors into a flat `${service}/${rpc}` → handler
  * map. Building it once per transport keeps per-RPC dispatch to a single
@@ -128,10 +319,8 @@ function buildFixtureTable(entities) {
         const pk = entity.pkField;
         const key = (rpc) => `${entity.service}/${rpc}`;
         if (entity.list) {
-            const { rpc, responseSchema, itemsField } = entity.list;
-            table.set(key(rpc), () => create(responseSchema, {
-                [itemsField]: Array.from(storeFor(entity).values()),
-            }));
+            const list = entity.list;
+            table.set(key(list.rpc), (input, requestSchema) => serveList(Array.from(storeFor(entity).values()), list, input, requestSchema));
         }
         if (entity.get) {
             const { rpc, responseSchema, entityField } = entity.get;
@@ -262,7 +451,10 @@ export function createMockTransport(options) {
             //    (Code.NotFound), never a silent wrong-record fallback.
             const fixture = fixtures.get(key);
             if (fixture) {
-                return makeUnaryResponse(method, fixture(input));
+                // `method.input` is typed as always present, but a hand-built method
+                // object (a test, a custom harness) may omit it.
+                const requestSchema = method.input;
+                return makeUnaryResponse(method, fixture(input, requestSchema));
             }
             // 4) Nothing matched. Surface a clear error instead of hanging.
             return Promise.reject(new ConnectError(`mock-transport: no scenario handler or entity fixture for ${key}`, Code.Unimplemented));