@reliantlabs/forge-web-runtime 0.3.1 → 0.3.2

package/dist/devlog.d.ts

@@ -1,11 +1,20 @@
 /** Console methods this module mirrors. */
 declare const LEVELS: readonly ["log", "info", "warn", "error", "debug"];
 type Level = (typeof LEVELS)[number];
-/** The wire shape the dev-server endpoint expects. */
+/**
+ * One log line on the wire.
+ *
+ * Also the whole v1 body: a legacy endpoint receives exactly this object, which
+ * is why the shape is unchanged and still exported.
+ */
 export interface DevLogPayload {
     level: Level | "error";
     msg: string;
 }
+/** The v2 body: many lines, one request. */
+export interface DevLogBatch {
+    entries: DevLogPayload[];
+}
 export interface DevLoggingOptions {
     /**
      * Whether to install at all. Pass `import.meta.env.DEV` (Vite) or

package/dist/devlog.js

@@ -8,6 +8,47 @@
 // browser console output to a dev-server endpoint that prints it, so it lands
 // in .forge/logs/<env>/frontend_<name>.log next to the server logs.
 //
+// ── Why this batches (protocol v2) ───────────────────────────────────────
+//
+// The first version sent one fetch POST per console call. Measured in a real
+// app that logs freely, that is ~80 requests/s at light load and 200+/s in a
+// burst, and those requests are not free bystanders: they share the browser's
+// six-connections-per-origin pool and the dev server's single event loop with
+// the app's own RPCs. In the same session, RPC latency averaged 37ms in quiet
+// seconds and 127ms in seconds carrying 200+ log lines. Worse, `keepalive`
+// requests draw on a 64 KiB in-flight browser quota shared across the page, so
+// a burst does not just slow things down — some of it gets rejected, and the
+// original `.catch(() => {})` made that indistinguishable from silence.
+//
+// So entries are buffered and flushed as a batch:
+//
+//   - every FLUSH_INTERVAL_MS, timer armed when an entry lands in an empty
+//     buffer (the common case: a few lines coalesce into one request),
+//   - immediately once buffered output reaches MAX_BATCH_BYTES,
+//   - on a microtask for anything error-level, so a crash never waits 250ms
+//     while a same-tick burst still coalesces,
+//   - synchronously via sendBeacon on pagehide / visibilitychange→hidden,
+//     which is the only way output survives a navigation or a crash-reload.
+//
+// At most ONE request is in flight. Entries logged during it keep buffering and
+// go out when it settles, which is what makes the printed order the log order —
+// six parallel POSTs would interleave on the server.
+//
+// Nothing is ever dropped silently. A full buffer, a rejected request and an
+// over-quota request all increment a counter, and the next batch to leave
+// carries a synthetic warn line saying how many lines were lost and why. The
+// failure this replaces was a dead sink that looked exactly like working code.
+//
+// ── Legacy endpoints ─────────────────────────────────────────────────────
+//
+// The receiving endpoint is a scaffold-once file the PROJECT owns (a Vite
+// plugin / a Next.js route handler), so upgrading this package through npm will
+// routinely meet an endpoint that predates batching. Such an endpoint answers
+// 204 and prints one empty line for the whole batch — total, silent loss. A v2
+// endpoint therefore returns `X-Forge-Devlog: 2`, and a 2xx without it makes
+// this client fall back permanently to one v1 POST per line (plus one warn
+// line telling the developer to update the endpoint).
+//
 // DEV ONLY, and structurally so. The receiving endpoint is a Vite plugin
 // gated `apply: "serve"` / a Next.js route behind a NODE_ENV check, so it does
 // not exist in a production build; installDevLogging() additionally no-ops
@@ -20,61 +61,299 @@
 /** Console methods this module mirrors. */
 const LEVELS = ["log", "info", "warn", "error", "debug"];
 export const DEV_LOG_ENDPOINT = "/__forge/log";
+/** Response header a batching endpoint sets. Its ABSENCE selects v1 fallback. */
+const PROTOCOL_HEADER = "X-Forge-Devlog";
+/** Cap a single line so a runaway loop cannot fill the disk. Matches the endpoints. */
+const MAX_LINE = 8_000;
+/** How long a line may wait for company before it is sent. */
+const FLUSH_INTERVAL_MS = 250;
+/**
+ * Per-request ceiling. Deliberately half of the browser's 64 KiB shared
+ * `keepalive` in-flight quota: with one request in flight, a batch cannot be
+ * the thing that pushes the page over it.
+ */
+const MAX_BATCH_BYTES = 32 * 1024;
+/** Buffer ceiling. Past it entries are dropped and counted, never queued forever. */
+const MAX_BUFFER_ENTRIES = 5_000;
 const original = {};
 let installed = false;
 // Guards against infinite recursion. The forwarder calls fetch(), and anything
 // that logs inside fetch (an interceptor, a polyfill, a devtools extension)
-// would otherwise re-enter the override forever.
+// would otherwise re-enter the override forever. Such a line is still mirrored
+// to the real console — it is only forwarding that is suppressed.
 let forwarding = false;
-/** Render one console argument as a string, keeping Error stacks intact. */
-function render(arg) {
-    if (arg instanceof Error) {
-        return `${arg.name}: ${arg.message}${arg.stack ? `\n${arg.stack}` : ""}`;
+let endpointUrl = DEV_LOG_ENDPOINT;
+let buffer = [];
+let bufferedBytes = 0;
+let flushTimer;
+let requestInFlight = false;
+let errorFlushQueued = false;
+let droppedCount = 0;
+let droppedReason = "";
+/** Set for good once an endpoint is known not to understand batches. */
+let legacyEndpoint = false;
+/**
+ * Render one console argument as a string.
+ *
+ * Circular structures and BigInt are the two cases a plain JSON.stringify
+ * throws on, and the old fallback to String(value) turned both into
+ * "[object Object]" — deleting exactly the shape you were trying to read. The
+ * replacer keeps the object and names the cycle instead.
+ */
+function render(value) {
+    if (typeof value === "string")
+        return value;
+    if (value instanceof Error) {
+        return `${value.name}: ${value.message}${value.stack ? `\n${value.stack}` : ""}`;
     }
-    if (typeof arg === "string")
-        return arg;
     try {
-        return JSON.stringify(arg);
+        const seen = new WeakSet();
+        return (JSON.stringify(value, (_key, val) => {
+            if (typeof val === "bigint")
+                return `${val}n`;
+            if (typeof val === "object" && val !== null) {
+                if (seen.has(val))
+                    return "[Circular]";
+                seen.add(val);
+            }
+            return val;
+        }) ?? String(value));
     }
     catch {
-        // Circular structures, BigInt, DOM nodes — never let logging throw.
-        return String(arg);
+        // DOM nodes, getters that throw — never let logging throw.
+        return String(value);
     }
 }
-function forward(endpoint, level, args) {
+function truncate(msg) {
+    return msg.length > MAX_LINE ? `${msg.slice(0, MAX_LINE)}… (truncated)` : msg;
+}
+function entryBytes(entry) {
+    return JSON.stringify(entry).length;
+}
+/**
+ * Buffer one line and decide whether it can wait.
+ *
+ * Arguments are rendered HERE rather than at flush time: a console argument is
+ * a live object, and by the time a batch leaves 250ms later the array it logged
+ * may have been mutated or emptied. The snapshot is the value at the call.
+ */
+function capture(level, args) {
     if (forwarding)
         return;
+    if (buffer.length >= MAX_BUFFER_ENTRIES) {
+        droppedCount += 1;
+        droppedReason = "buffer full";
+        return;
+    }
+    const entry = { level, msg: truncate(args.map(render).join(" ")) };
+    const wasEmpty = buffer.length === 0;
+    buffer.push(entry);
+    bufferedBytes += entryBytes(entry);
+    if (bufferedBytes >= MAX_BATCH_BYTES) {
+        flush();
+        return;
+    }
+    if (level === "error") {
+        // An error is what someone is waiting for; it must not sit in a timer. The
+        // microtask (rather than a direct flush) lets a same-tick burst — a failing
+        // render logging three times — still leave as one request.
+        if (!errorFlushQueued) {
+            errorFlushQueued = true;
+            queueMicrotask(() => {
+                errorFlushQueued = false;
+                flush();
+            });
+        }
+        return;
+    }
+    if (wasEmpty)
+        armTimer();
+}
+function armTimer() {
+    if (flushTimer !== undefined)
+        return;
+    flushTimer = setTimeout(() => {
+        flushTimer = undefined;
+        flush();
+    }, FLUSH_INTERVAL_MS);
+}
+function clearFlushTimer() {
+    if (flushTimer === undefined)
+        return;
+    clearTimeout(flushTimer);
+    flushTimer = undefined;
+}
+/** Pull entries off the front of the buffer without exceeding MAX_BATCH_BYTES. */
+function takeBatch(limit = MAX_BATCH_BYTES) {
+    const batch = [];
+    let size = '{"entries":[]}'.length;
+    while (buffer.length > 0) {
+        const entry = buffer[0];
+        const cost = entryBytes(entry) + (batch.length > 0 ? 1 : 0);
+        // Always take at least one entry: a single line that somehow exceeds the
+        // limit must still leave, or it stalls every line behind it forever.
+        if (batch.length > 0 && size + cost > limit)
+            break;
+        buffer.shift();
+        bufferedBytes -= entryBytes(entry);
+        batch.push(entry);
+        size += cost;
+    }
+    if (buffer.length === 0)
+        bufferedBytes = 0;
+    return batch;
+}
+/**
+ * Prepend the "we lost lines" notice, if any, so it travels with the next batch
+ * rather than needing a request of its own.
+ */
+function drainDroppedNotice() {
+    if (droppedCount === 0)
+        return;
+    const notice = {
+        level: "warn",
+        msg: `[forge-devlog] dropped ${droppedCount} lines (${droppedReason})`,
+    };
+    buffer.unshift(notice);
+    bufferedBytes += entryBytes(notice);
+    droppedCount = 0;
+    droppedReason = "";
+}
+function post(body) {
+    // The recursion guard must wrap the CALL, not the promise: a fetch polyfill
+    // that logs does so synchronously from inside fetch().
     forwarding = true;
     try {
-        const body = { level, msg: args.map(render).join(" ") };
-        void fetch(endpoint, {
+        return fetch(endpointUrl, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(body),
+            body,
             // A log emitted during unload (the interesting case for a crash on
             // navigation) is cancelled without this.
             keepalive: true,
             // Never let log forwarding trip a credentials or CORS policy.
             credentials: "omit",
-        }).catch(() => {
-            // The dev server going away must not surface as an app error.
         });
     }
     finally {
         forwarding = false;
     }
 }
-function onWindowError(endpoint, event) {
-    forward(endpoint, "error", [
+/**
+ * Send one request's worth of buffered output, if nothing is in flight.
+ *
+ * The single-flight rule is what guarantees the dev server prints lines in the
+ * order they were logged, and it doubles as backpressure: a slow endpoint makes
+ * batches bigger rather than making requests pile up.
+ */
+function flush() {
+    if (requestInFlight)
+        return;
+    drainDroppedNotice();
+    if (buffer.length === 0)
+        return;
+    clearFlushTimer();
+    const batch = legacyEndpoint ? takeBatch(0) : takeBatch();
+    if (batch.length === 0)
+        return;
+    const body = legacyEndpoint
+        ? JSON.stringify(batch[0])
+        : JSON.stringify({ entries: batch });
+    requestInFlight = true;
+    post(body).then((response) => {
+        requestInFlight = false;
+        if (!response.ok) {
+            countDropped(batch.length, `endpoint returned ${response.status}`);
+        }
+        else if (!legacyEndpoint && !response.headers.get(PROTOCOL_HEADER)) {
+            adoptLegacyMode(batch);
+        }
+        if (buffer.length > 0 || droppedCount > 0)
+            flush();
+    }, () => {
+        requestInFlight = false;
+        countDropped(batch.length, "request failed");
+        if (buffer.length > 0)
+            flush();
+    });
+}
+function countDropped(count, reason) {
+    droppedCount += count;
+    droppedReason = reason;
+}
+/**
+ * A 2xx with no protocol header came from an endpoint written before batching.
+ * It parsed `{entries:[...]}` as a v1 body, found no `msg`, and printed one
+ * empty line — so this batch is lost unless it is re-sent one line at a time,
+ * and so is everything after it.
+ */
+function adoptLegacyMode(lost) {
+    legacyEndpoint = true;
+    const notice = {
+        level: "warn",
+        msg: "[forge-devlog] this dev server's /__forge/log endpoint predates batched " +
+            "posts; update it (forge skill: debug) — falling back to one request per line",
+    };
+    buffer.unshift(notice, ...lost);
+    bufferedBytes += [notice, ...lost].reduce((n, e) => n + entryBytes(e), 0);
+}
+/**
+ * Last-chance flush on page teardown.
+ *
+ * fetch — even with keepalive — is not reliable here, and an async flush is
+ * hopeless: the event loop may not run again. sendBeacon hands the bytes to the
+ * browser to deliver after the document is gone, which is precisely the case
+ * where the last few log lines explain what happened.
+ */
+function flushOnUnload() {
+    drainDroppedNotice();
+    if (buffer.length === 0)
+        return;
+    const canBeacon = typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function";
+    if (!canBeacon) {
+        // No beacon: keepalive fetch is the only remaining option, and one request
+        // has a better chance of leaving than a queue of them.
+        flush();
+        return;
+    }
+    forwarding = true;
+    try {
+        while (buffer.length > 0) {
+            const batch = legacyEndpoint ? takeBatch(0) : takeBatch();
+            const body = legacyEndpoint
+                ? JSON.stringify(batch[0])
+                : JSON.stringify({ entries: batch });
+            // text/plain is not a decoration: sendBeacon with application/json is a
+            // non-simple request and would need a CORS preflight it cannot make. The
+            // endpoints parse the body regardless of Content-Type for this reason.
+            const blob = new Blob([body], { type: "text/plain;charset=UTF-8" });
+            if (!navigator.sendBeacon(endpointUrl, blob)) {
+                // The beacon queue is full (64 KiB per origin). Nothing later will fit
+                // either, so stop and account for what is left.
+                countDropped(batch.length + buffer.length, "beacon queue full");
+                buffer = [];
+                bufferedBytes = 0;
+                return;
+            }
+        }
+    }
+    finally {
+        forwarding = false;
+    }
+}
+function onWindowError(event) {
+    capture("error", [
         event.error ??
             `${event.message} @ ${event.filename}:${event.lineno}:${event.colno}`,
     ]);
 }
-function onRejection(endpoint, event) {
-    forward(endpoint, "error", ["unhandled rejection:", event.reason]);
+function onRejection(event) {
+    capture("error", ["unhandled rejection:", event.reason]);
 }
 let errorHandler;
 let rejectionHandler;
+let pageHideHandler;
+let visibilityHandler;
 /**
  * Mirror console output and uncaught errors to the dev server, which prints
  * them into .forge/logs/<env>/frontend_<name>.log.
@@ -100,6 +379,13 @@ export function installDevLogging(options) {
         return; // SSR / prerender pass
     const { endpoint = DEV_LOG_ENDPOINT, mirrorToConsole = true } = options;
     installed = true;
+    endpointUrl = endpoint;
+    buffer = [];
+    bufferedBytes = 0;
+    droppedCount = 0;
+    droppedReason = "";
+    legacyEndpoint = false;
+    requestInFlight = false;
     for (const level of LEVELS) {
         // Keep the ORIGINAL reference, not a bound copy: uninstall must restore
         // console.log to the identical function it replaced, so a second consumer
@@ -109,18 +395,33 @@ export function installDevLogging(options) {
         console[level] = (...args) => {
             if (mirrorToConsole)
                 previous.apply(console, args);
-            forward(endpoint, level, args);
+            capture(level, args);
         };
     }
-    errorHandler = (e) => onWindowError(endpoint, e);
-    rejectionHandler = (e) => onRejection(endpoint, e);
+    errorHandler = (e) => onWindowError(e);
+    rejectionHandler = (e) => onRejection(e);
+    pageHideHandler = () => flushOnUnload();
     window.addEventListener("error", errorHandler);
     window.addEventListener("unhandledrejection", rejectionHandler);
+    window.addEventListener("pagehide", pageHideHandler);
+    if (typeof document !== "undefined") {
+        // visibilitychange→hidden is the only teardown signal mobile Safari
+        // reliably fires; pagehide alone loses the whole buffer there.
+        visibilityHandler = () => {
+            if (document.visibilityState === "hidden")
+                flushOnUnload();
+        };
+        document.addEventListener("visibilitychange", visibilityHandler);
+    }
 }
 /** Restore the original console methods and remove the window listeners. */
 export function uninstallDevLogging() {
     if (!installed)
         return;
+    // Flush before restoring: whatever is buffered was logged while this was
+    // installed, and a teardown is no reason to lose it.
+    clearFlushTimer();
+    flush();
     for (const level of LEVELS) {
         const previous = original[level];
         if (previous)
@@ -131,8 +432,14 @@ export function uninstallDevLogging() {
         window.removeEventListener("error", errorHandler);
     if (rejectionHandler)
         window.removeEventListener("unhandledrejection", rejectionHandler);
+    if (pageHideHandler)
+        window.removeEventListener("pagehide", pageHideHandler);
+    if (visibilityHandler && typeof document !== "undefined")
+        document.removeEventListener("visibilitychange", visibilityHandler);
     errorHandler = undefined;
     rejectionHandler = undefined;
+    pageHideHandler = undefined;
+    visibilityHandler = undefined;
     installed = false;
 }
 /** Whether the console override is currently installed. Exposed for tests. */

package/dist/devlog.js.map

@@ -1 +1 @@
-{"version":3,"file":"devlog.js","sourceRoot":"","sources":["../src/devlog.ts"],"names":[],"mappings":"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","sourcesContent":["// Dev-only browser log forwarding.\n//\n// A browser's console is a dead end: an agent debugging a scaffolded frontend\n// cannot open devtools, so every console line and — worse — every uncaught\n// error is invisible to it. The backend has no such gap (structured slog, the\n// observe ComponentChain, and forge's dev loop already tees each process's\n// stdout to .forge/logs/<env>/). This closes the frontend half by POSTing\n// browser console output to a dev-server endpoint that prints it, so it lands\n// in .forge/logs/<env>/frontend_<name>.log next to the server logs.\n//\n// DEV ONLY, and structurally so. The receiving endpoint is a Vite plugin\n// gated `apply: \"serve\"` / a Next.js route behind a NODE_ENV check, so it does\n// not exist in a production build; installDevLogging() additionally no-ops\n// unless it is handed dev: true. A production bundle therefore has no\n// endpoint to post to AND no code that would post.\n//\n// It is also reversible: uninstallDevLogging() restores the original console\n// methods, and the scaffolded call site is an ordinary line in main.tsx /\n// providers.tsx that a project can delete outright.\n\n/** Console methods this module mirrors. */\nconst LEVELS = [\"log\", \"info\", \"warn\", \"error\", \"debug\"] as const;\n\ntype Level = (typeof LEVELS)[number];\n\n/** The wire shape the dev-server endpoint expects. */\nexport interface DevLogPayload {\n  level: Level | \"error\";\n  msg: string;\n}\n\nexport interface DevLoggingOptions {\n  /**\n   * Whether to install at all. Pass `import.meta.env.DEV` (Vite) or\n   * `process.env.NODE_ENV !== \"production\"` (Next.js). When false this is a\n   * no-op, so the call site needs no conditional of its own.\n   */\n  dev: boolean;\n  /** Endpoint the dev server serves. Defaults to the forge convention. */\n  endpoint?: string;\n  /**\n   * Also keep writing to the real console. Default true — the browser devtools\n   * experience should be unchanged; this feature ADDS a sink, it does not move\n   * one.\n   */\n  mirrorToConsole?: boolean;\n}\n\nexport const DEV_LOG_ENDPOINT = \"/__forge/log\";\n\nconst original: Partial<Record<Level, (...args: unknown[]) => void>> = {};\nlet installed = false;\n\n// Guards against infinite recursion. The forwarder calls fetch(), and anything\n// that logs inside fetch (an interceptor, a polyfill, a devtools extension)\n// would otherwise re-enter the override forever.\nlet forwarding = false;\n\n/** Render one console argument as a string, keeping Error stacks intact. */\nfunction render(arg: unknown): string {\n  if (arg instanceof Error) {\n    return `${arg.name}: ${arg.message}${arg.stack ? `\\n${arg.stack}` : \"\"}`;\n  }\n  if (typeof arg === \"string\") return arg;\n  try {\n    return JSON.stringify(arg);\n  } catch {\n    // Circular structures, BigInt, DOM nodes — never let logging throw.\n    return String(arg);\n  }\n}\n\nfunction forward(\n  endpoint: string,\n  level: DevLogPayload[\"level\"],\n  args: unknown[],\n): void {\n  if (forwarding) return;\n  forwarding = true;\n  try {\n    const body: DevLogPayload = { level, msg: args.map(render).join(\" \") };\n    void fetch(endpoint, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify(body),\n      // A log emitted during unload (the interesting case for a crash on\n      // navigation) is cancelled without this.\n      keepalive: true,\n      // Never let log forwarding trip a credentials or CORS policy.\n      credentials: \"omit\",\n    }).catch(() => {\n      // The dev server going away must not surface as an app error.\n    });\n  } finally {\n    forwarding = false;\n  }\n}\n\nfunction onWindowError(endpoint: string, event: ErrorEvent): void {\n  forward(endpoint, \"error\", [\n    event.error ??\n      `${event.message} @ ${event.filename}:${event.lineno}:${event.colno}`,\n  ]);\n}\n\nfunction onRejection(endpoint: string, event: PromiseRejectionEvent): void {\n  forward(endpoint, \"error\", [\"unhandled rejection:\", event.reason]);\n}\n\nlet errorHandler: ((e: ErrorEvent) => void) | undefined;\nlet rejectionHandler: ((e: PromiseRejectionEvent) => void) | undefined;\n\n/**\n * Mirror console output and uncaught errors to the dev server, which prints\n * them into .forge/logs/<env>/frontend_<name>.log.\n *\n * The window listeners are the point of the feature as much as the console\n * override is: an uncaught TypeError or a rejected promise produces no console\n * call of its own, and those are exactly the failures worth seeing.\n *\n * Safe to call more than once; the second call is a no-op.\n */\nexport function installDevLogging(options: DevLoggingOptions): void {\n  // `dev` is read off `options` rather than destructured with a default, and\n  // checked FIRST. A bundler constant-folds `import.meta.env.DEV` to false at\n  // the CALL SITE and can then drop the argument entirely, leaving a bare\n  // `installDevLogging({})` — with a defaulted `dev` that call would install\n  // the override in a production bundle. `options?.dev !== true` is therefore\n  // fail-closed: absent, undefined, or anything non-true means do nothing.\n  if (options?.dev !== true) return;\n  if (installed) return;\n  if (typeof window === \"undefined\") return; // SSR / prerender pass\n\n  const { endpoint = DEV_LOG_ENDPOINT, mirrorToConsole = true } = options;\n  installed = true;\n\n  for (const level of LEVELS) {\n    // Keep the ORIGINAL reference, not a bound copy: uninstall must restore\n    // console.log to the identical function it replaced, so a second consumer\n    // holding that reference (or a test asserting on it) sees no difference.\n    const previous = console[level] as (...args: unknown[]) => void;\n    original[level] = previous;\n    console[level] = (...args: unknown[]) => {\n      if (mirrorToConsole) previous.apply(console, args);\n      forward(endpoint, level, args);\n    };\n  }\n\n  errorHandler = (e) => onWindowError(endpoint, e);\n  rejectionHandler = (e) => onRejection(endpoint, e);\n  window.addEventListener(\"error\", errorHandler);\n  window.addEventListener(\"unhandledrejection\", rejectionHandler);\n}\n\n/** Restore the original console methods and remove the window listeners. */\nexport function uninstallDevLogging(): void {\n  if (!installed) return;\n  for (const level of LEVELS) {\n    const previous = original[level];\n    if (previous) console[level] = previous;\n    delete original[level];\n  }\n  if (errorHandler) window.removeEventListener(\"error\", errorHandler);\n  if (rejectionHandler)\n    window.removeEventListener(\"unhandledrejection\", rejectionHandler);\n  errorHandler = undefined;\n  rejectionHandler = undefined;\n  installed = false;\n}\n\n/** Whether the console override is currently installed. Exposed for tests. */\nexport function devLoggingInstalled(): boolean {\n  return installed;\n}\n"]}
+{"version":3,"file":"devlog.js","sourceRoot":"","sources":["../src/devlog.ts"],"names":[],"mappings":"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","sourcesContent":["// Dev-only browser log forwarding.\n//\n// A browser's console is a dead end: an agent debugging a scaffolded frontend\n// cannot open devtools, so every console line and — worse — every uncaught\n// error is invisible to it. The backend has no such gap (structured slog, the\n// observe ComponentChain, and forge's dev loop already tees each process's\n// stdout to .forge/logs/<env>/). This closes the frontend half by POSTing\n// browser console output to a dev-server endpoint that prints it, so it lands\n// in .forge/logs/<env>/frontend_<name>.log next to the server logs.\n//\n// ── Why this batches (protocol v2) ───────────────────────────────────────\n//\n// The first version sent one fetch POST per console call. Measured in a real\n// app that logs freely, that is ~80 requests/s at light load and 200+/s in a\n// burst, and those requests are not free bystanders: they share the browser's\n// six-connections-per-origin pool and the dev server's single event loop with\n// the app's own RPCs. In the same session, RPC latency averaged 37ms in quiet\n// seconds and 127ms in seconds carrying 200+ log lines. Worse, `keepalive`\n// requests draw on a 64 KiB in-flight browser quota shared across the page, so\n// a burst does not just slow things down — some of it gets rejected, and the\n// original `.catch(() => {})` made that indistinguishable from silence.\n//\n// So entries are buffered and flushed as a batch:\n//\n//   - every FLUSH_INTERVAL_MS, timer armed when an entry lands in an empty\n//     buffer (the common case: a few lines coalesce into one request),\n//   - immediately once buffered output reaches MAX_BATCH_BYTES,\n//   - on a microtask for anything error-level, so a crash never waits 250ms\n//     while a same-tick burst still coalesces,\n//   - synchronously via sendBeacon on pagehide / visibilitychange→hidden,\n//     which is the only way output survives a navigation or a crash-reload.\n//\n// At most ONE request is in flight. Entries logged during it keep buffering and\n// go out when it settles, which is what makes the printed order the log order —\n// six parallel POSTs would interleave on the server.\n//\n// Nothing is ever dropped silently. A full buffer, a rejected request and an\n// over-quota request all increment a counter, and the next batch to leave\n// carries a synthetic warn line saying how many lines were lost and why. The\n// failure this replaces was a dead sink that looked exactly like working code.\n//\n// ── Legacy endpoints ─────────────────────────────────────────────────────\n//\n// The receiving endpoint is a scaffold-once file the PROJECT owns (a Vite\n// plugin / a Next.js route handler), so upgrading this package through npm will\n// routinely meet an endpoint that predates batching. Such an endpoint answers\n// 204 and prints one empty line for the whole batch — total, silent loss. A v2\n// endpoint therefore returns `X-Forge-Devlog: 2`, and a 2xx without it makes\n// this client fall back permanently to one v1 POST per line (plus one warn\n// line telling the developer to update the endpoint).\n//\n// DEV ONLY, and structurally so. The receiving endpoint is a Vite plugin\n// gated `apply: \"serve\"` / a Next.js route behind a NODE_ENV check, so it does\n// not exist in a production build; installDevLogging() additionally no-ops\n// unless it is handed dev: true. A production bundle therefore has no\n// endpoint to post to AND no code that would post.\n//\n// It is also reversible: uninstallDevLogging() restores the original console\n// methods, and the scaffolded call site is an ordinary line in main.tsx /\n// providers.tsx that a project can delete outright.\n\n/** Console methods this module mirrors. */\nconst LEVELS = [\"log\", \"info\", \"warn\", \"error\", \"debug\"] as const;\n\ntype Level = (typeof LEVELS)[number];\n\n/**\n * One log line on the wire.\n *\n * Also the whole v1 body: a legacy endpoint receives exactly this object, which\n * is why the shape is unchanged and still exported.\n */\nexport interface DevLogPayload {\n  level: Level | \"error\";\n  msg: string;\n}\n\n/** The v2 body: many lines, one request. */\nexport interface DevLogBatch {\n  entries: DevLogPayload[];\n}\n\nexport interface DevLoggingOptions {\n  /**\n   * Whether to install at all. Pass `import.meta.env.DEV` (Vite) or\n   * `process.env.NODE_ENV !== \"production\"` (Next.js). When false this is a\n   * no-op, so the call site needs no conditional of its own.\n   */\n  dev: boolean;\n  /** Endpoint the dev server serves. Defaults to the forge convention. */\n  endpoint?: string;\n  /**\n   * Also keep writing to the real console. Default true — the browser devtools\n   * experience should be unchanged; this feature ADDS a sink, it does not move\n   * one.\n   */\n  mirrorToConsole?: boolean;\n}\n\nexport const DEV_LOG_ENDPOINT = \"/__forge/log\";\n\n/** Response header a batching endpoint sets. Its ABSENCE selects v1 fallback. */\nconst PROTOCOL_HEADER = \"X-Forge-Devlog\";\n\n/** Cap a single line so a runaway loop cannot fill the disk. Matches the endpoints. */\nconst MAX_LINE = 8_000;\n\n/** How long a line may wait for company before it is sent. */\nconst FLUSH_INTERVAL_MS = 250;\n\n/**\n * Per-request ceiling. Deliberately half of the browser's 64 KiB shared\n * `keepalive` in-flight quota: with one request in flight, a batch cannot be\n * the thing that pushes the page over it.\n */\nconst MAX_BATCH_BYTES = 32 * 1024;\n\n/** Buffer ceiling. Past it entries are dropped and counted, never queued forever. */\nconst MAX_BUFFER_ENTRIES = 5_000;\n\nconst original: Partial<Record<Level, (...args: unknown[]) => void>> = {};\nlet installed = false;\n\n// Guards against infinite recursion. The forwarder calls fetch(), and anything\n// that logs inside fetch (an interceptor, a polyfill, a devtools extension)\n// would otherwise re-enter the override forever. Such a line is still mirrored\n// to the real console — it is only forwarding that is suppressed.\nlet forwarding = false;\n\nlet endpointUrl = DEV_LOG_ENDPOINT;\nlet buffer: DevLogPayload[] = [];\nlet bufferedBytes = 0;\nlet flushTimer: ReturnType<typeof setTimeout> | undefined;\nlet requestInFlight = false;\nlet errorFlushQueued = false;\nlet droppedCount = 0;\nlet droppedReason = \"\";\n/** Set for good once an endpoint is known not to understand batches. */\nlet legacyEndpoint = false;\n\n/**\n * Render one console argument as a string.\n *\n * Circular structures and BigInt are the two cases a plain JSON.stringify\n * throws on, and the old fallback to String(value) turned both into\n * \"[object Object]\" — deleting exactly the shape you were trying to read. The\n * replacer keeps the object and names the cycle instead.\n */\nfunction render(value: unknown): string {\n  if (typeof value === \"string\") return value;\n  if (value instanceof Error) {\n    return `${value.name}: ${value.message}${value.stack ? `\\n${value.stack}` : \"\"}`;\n  }\n  try {\n    const seen = new WeakSet<object>();\n    return (\n      JSON.stringify(value, (_key, val: unknown) => {\n        if (typeof val === \"bigint\") return `${val}n`;\n        if (typeof val === \"object\" && val !== null) {\n          if (seen.has(val)) return \"[Circular]\";\n          seen.add(val);\n        }\n        return val;\n      }) ?? String(value)\n    );\n  } catch {\n    // DOM nodes, getters that throw — never let logging throw.\n    return String(value);\n  }\n}\n\nfunction truncate(msg: string): string {\n  return msg.length > MAX_LINE ? `${msg.slice(0, MAX_LINE)}… (truncated)` : msg;\n}\n\nfunction entryBytes(entry: DevLogPayload): number {\n  return JSON.stringify(entry).length;\n}\n\n/**\n * Buffer one line and decide whether it can wait.\n *\n * Arguments are rendered HERE rather than at flush time: a console argument is\n * a live object, and by the time a batch leaves 250ms later the array it logged\n * may have been mutated or emptied. The snapshot is the value at the call.\n */\nfunction capture(level: DevLogPayload[\"level\"], args: unknown[]): void {\n  if (forwarding) return;\n\n  if (buffer.length >= MAX_BUFFER_ENTRIES) {\n    droppedCount += 1;\n    droppedReason = \"buffer full\";\n    return;\n  }\n\n  const entry: DevLogPayload = { level, msg: truncate(args.map(render).join(\" \")) };\n  const wasEmpty = buffer.length === 0;\n  buffer.push(entry);\n  bufferedBytes += entryBytes(entry);\n\n  if (bufferedBytes >= MAX_BATCH_BYTES) {\n    flush();\n    return;\n  }\n\n  if (level === \"error\") {\n    // An error is what someone is waiting for; it must not sit in a timer. The\n    // microtask (rather than a direct flush) lets a same-tick burst — a failing\n    // render logging three times — still leave as one request.\n    if (!errorFlushQueued) {\n      errorFlushQueued = true;\n      queueMicrotask(() => {\n        errorFlushQueued = false;\n        flush();\n      });\n    }\n    return;\n  }\n\n  if (wasEmpty) armTimer();\n}\n\nfunction armTimer(): void {\n  if (flushTimer !== undefined) return;\n  flushTimer = setTimeout(() => {\n    flushTimer = undefined;\n    flush();\n  }, FLUSH_INTERVAL_MS);\n}\n\nfunction clearFlushTimer(): void {\n  if (flushTimer === undefined) return;\n  clearTimeout(flushTimer);\n  flushTimer = undefined;\n}\n\n/** Pull entries off the front of the buffer without exceeding MAX_BATCH_BYTES. */\nfunction takeBatch(limit = MAX_BATCH_BYTES): DevLogPayload[] {\n  const batch: DevLogPayload[] = [];\n  let size = '{\"entries\":[]}'.length;\n  while (buffer.length > 0) {\n    const entry = buffer[0] as DevLogPayload;\n    const cost = entryBytes(entry) + (batch.length > 0 ? 1 : 0);\n    // Always take at least one entry: a single line that somehow exceeds the\n    // limit must still leave, or it stalls every line behind it forever.\n    if (batch.length > 0 && size + cost > limit) break;\n    buffer.shift();\n    bufferedBytes -= entryBytes(entry);\n    batch.push(entry);\n    size += cost;\n  }\n  if (buffer.length === 0) bufferedBytes = 0;\n  return batch;\n}\n\n/**\n * Prepend the \"we lost lines\" notice, if any, so it travels with the next batch\n * rather than needing a request of its own.\n */\nfunction drainDroppedNotice(): void {\n  if (droppedCount === 0) return;\n  const notice: DevLogPayload = {\n    level: \"warn\",\n    msg: `[forge-devlog] dropped ${droppedCount} lines (${droppedReason})`,\n  };\n  buffer.unshift(notice);\n  bufferedBytes += entryBytes(notice);\n  droppedCount = 0;\n  droppedReason = \"\";\n}\n\nfunction post(body: string): Promise<Response> {\n  // The recursion guard must wrap the CALL, not the promise: a fetch polyfill\n  // that logs does so synchronously from inside fetch().\n  forwarding = true;\n  try {\n    return fetch(endpointUrl, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      body,\n      // A log emitted during unload (the interesting case for a crash on\n      // navigation) is cancelled without this.\n      keepalive: true,\n      // Never let log forwarding trip a credentials or CORS policy.\n      credentials: \"omit\",\n    });\n  } finally {\n    forwarding = false;\n  }\n}\n\n/**\n * Send one request's worth of buffered output, if nothing is in flight.\n *\n * The single-flight rule is what guarantees the dev server prints lines in the\n * order they were logged, and it doubles as backpressure: a slow endpoint makes\n * batches bigger rather than making requests pile up.\n */\nfunction flush(): void {\n  if (requestInFlight) return;\n  drainDroppedNotice();\n  if (buffer.length === 0) return;\n  clearFlushTimer();\n\n  const batch = legacyEndpoint ? takeBatch(0) : takeBatch();\n  if (batch.length === 0) return;\n\n  const body = legacyEndpoint\n    ? JSON.stringify(batch[0])\n    : JSON.stringify({ entries: batch } satisfies DevLogBatch);\n\n  requestInFlight = true;\n  post(body).then(\n    (response) => {\n      requestInFlight = false;\n      if (!response.ok) {\n        countDropped(batch.length, `endpoint returned ${response.status}`);\n      } else if (!legacyEndpoint && !response.headers.get(PROTOCOL_HEADER)) {\n        adoptLegacyMode(batch);\n      }\n      if (buffer.length > 0 || droppedCount > 0) flush();\n    },\n    () => {\n      requestInFlight = false;\n      countDropped(batch.length, \"request failed\");\n      if (buffer.length > 0) flush();\n    },\n  );\n}\n\nfunction countDropped(count: number, reason: string): void {\n  droppedCount += count;\n  droppedReason = reason;\n}\n\n/**\n * A 2xx with no protocol header came from an endpoint written before batching.\n * It parsed `{entries:[...]}` as a v1 body, found no `msg`, and printed one\n * empty line — so this batch is lost unless it is re-sent one line at a time,\n * and so is everything after it.\n */\nfunction adoptLegacyMode(lost: DevLogPayload[]): void {\n  legacyEndpoint = true;\n  const notice: DevLogPayload = {\n    level: \"warn\",\n    msg:\n      \"[forge-devlog] this dev server's /__forge/log endpoint predates batched \" +\n      \"posts; update it (forge skill: debug) — falling back to one request per line\",\n  };\n  buffer.unshift(notice, ...lost);\n  bufferedBytes += [notice, ...lost].reduce((n, e) => n + entryBytes(e), 0);\n}\n\n/**\n * Last-chance flush on page teardown.\n *\n * fetch — even with keepalive — is not reliable here, and an async flush is\n * hopeless: the event loop may not run again. sendBeacon hands the bytes to the\n * browser to deliver after the document is gone, which is precisely the case\n * where the last few log lines explain what happened.\n */\nfunction flushOnUnload(): void {\n  drainDroppedNotice();\n  if (buffer.length === 0) return;\n\n  const canBeacon =\n    typeof navigator !== \"undefined\" && typeof navigator.sendBeacon === \"function\";\n  if (!canBeacon) {\n    // No beacon: keepalive fetch is the only remaining option, and one request\n    // has a better chance of leaving than a queue of them.\n    flush();\n    return;\n  }\n\n  forwarding = true;\n  try {\n    while (buffer.length > 0) {\n      const batch = legacyEndpoint ? takeBatch(0) : takeBatch();\n      const body = legacyEndpoint\n        ? JSON.stringify(batch[0])\n        : JSON.stringify({ entries: batch } satisfies DevLogBatch);\n      // text/plain is not a decoration: sendBeacon with application/json is a\n      // non-simple request and would need a CORS preflight it cannot make. The\n      // endpoints parse the body regardless of Content-Type for this reason.\n      const blob = new Blob([body], { type: \"text/plain;charset=UTF-8\" });\n      if (!navigator.sendBeacon(endpointUrl, blob)) {\n        // The beacon queue is full (64 KiB per origin). Nothing later will fit\n        // either, so stop and account for what is left.\n        countDropped(batch.length + buffer.length, \"beacon queue full\");\n        buffer = [];\n        bufferedBytes = 0;\n        return;\n      }\n    }\n  } finally {\n    forwarding = false;\n  }\n}\n\nfunction onWindowError(event: ErrorEvent): void {\n  capture(\"error\", [\n    event.error ??\n      `${event.message} @ ${event.filename}:${event.lineno}:${event.colno}`,\n  ]);\n}\n\nfunction onRejection(event: PromiseRejectionEvent): void {\n  capture(\"error\", [\"unhandled rejection:\", event.reason]);\n}\n\nlet errorHandler: ((e: ErrorEvent) => void) | undefined;\nlet rejectionHandler: ((e: PromiseRejectionEvent) => void) | undefined;\nlet pageHideHandler: (() => void) | undefined;\nlet visibilityHandler: (() => void) | undefined;\n\n/**\n * Mirror console output and uncaught errors to the dev server, which prints\n * them into .forge/logs/<env>/frontend_<name>.log.\n *\n * The window listeners are the point of the feature as much as the console\n * override is: an uncaught TypeError or a rejected promise produces no console\n * call of its own, and those are exactly the failures worth seeing.\n *\n * Safe to call more than once; the second call is a no-op.\n */\nexport function installDevLogging(options: DevLoggingOptions): void {\n  // `dev` is read off `options` rather than destructured with a default, and\n  // checked FIRST. A bundler constant-folds `import.meta.env.DEV` to false at\n  // the CALL SITE and can then drop the argument entirely, leaving a bare\n  // `installDevLogging({})` — with a defaulted `dev` that call would install\n  // the override in a production bundle. `options?.dev !== true` is therefore\n  // fail-closed: absent, undefined, or anything non-true means do nothing.\n  if (options?.dev !== true) return;\n  if (installed) return;\n  if (typeof window === \"undefined\") return; // SSR / prerender pass\n\n  const { endpoint = DEV_LOG_ENDPOINT, mirrorToConsole = true } = options;\n  installed = true;\n  endpointUrl = endpoint;\n  buffer = [];\n  bufferedBytes = 0;\n  droppedCount = 0;\n  droppedReason = \"\";\n  legacyEndpoint = false;\n  requestInFlight = false;\n\n  for (const level of LEVELS) {\n    // Keep the ORIGINAL reference, not a bound copy: uninstall must restore\n    // console.log to the identical function it replaced, so a second consumer\n    // holding that reference (or a test asserting on it) sees no difference.\n    const previous = console[level] as (...args: unknown[]) => void;\n    original[level] = previous;\n    console[level] = (...args: unknown[]) => {\n      if (mirrorToConsole) previous.apply(console, args);\n      capture(level, args);\n    };\n  }\n\n  errorHandler = (e) => onWindowError(e);\n  rejectionHandler = (e) => onRejection(e);\n  pageHideHandler = () => flushOnUnload();\n  window.addEventListener(\"error\", errorHandler);\n  window.addEventListener(\"unhandledrejection\", rejectionHandler);\n  window.addEventListener(\"pagehide\", pageHideHandler);\n\n  if (typeof document !== \"undefined\") {\n    // visibilitychange→hidden is the only teardown signal mobile Safari\n    // reliably fires; pagehide alone loses the whole buffer there.\n    visibilityHandler = () => {\n      if (document.visibilityState === \"hidden\") flushOnUnload();\n    };\n    document.addEventListener(\"visibilitychange\", visibilityHandler);\n  }\n}\n\n/** Restore the original console methods and remove the window listeners. */\nexport function uninstallDevLogging(): void {\n  if (!installed) return;\n\n  // Flush before restoring: whatever is buffered was logged while this was\n  // installed, and a teardown is no reason to lose it.\n  clearFlushTimer();\n  flush();\n\n  for (const level of LEVELS) {\n    const previous = original[level];\n    if (previous) console[level] = previous;\n    delete original[level];\n  }\n  if (errorHandler) window.removeEventListener(\"error\", errorHandler);\n  if (rejectionHandler)\n    window.removeEventListener(\"unhandledrejection\", rejectionHandler);\n  if (pageHideHandler) window.removeEventListener(\"pagehide\", pageHideHandler);\n  if (visibilityHandler && typeof document !== \"undefined\")\n    document.removeEventListener(\"visibilitychange\", visibilityHandler);\n  errorHandler = undefined;\n  rejectionHandler = undefined;\n  pageHideHandler = undefined;\n  visibilityHandler = undefined;\n  installed = false;\n}\n\n/** Whether the console override is currently installed. Exposed for tests. */\nexport function devLoggingInstalled(): boolean {\n  return installed;\n}\n"]}

package/dist/service-hooks.js

@@ -1,5 +1,14 @@
+"use client";
 // Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
 //
+// Every export below is a React hook or builds one, so this module belongs in
+// the CLIENT graph. Without the directive the Next.js App Router compiles it
+// into the SERVER graph, where it binds a SECOND @tanstack/react-query
+// instance and every generated hook throws "No QueryClient set" at runtime —
+// invisible to tsc, eslint AND `next build`. published-surface.test.ts asserts
+// the directive survives into dist/. It is NOT applied package-wide: the
+// ./interceptors subpath exists to be importable without React.
+//
 // The React Query wrapper machinery behind forge's generated per-service hook
 // files (`src/hooks/<svc>-service-hooks_gen.ts`).
 //

package/dist/service-hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"service-hooks.js","sourceRoot":"","sources":["../src/service-hooks.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,8EAA8E;AAC9E,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,qEAAqE;AACrE,qEAAqE;AACrE,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,sEAAsE;AACtE,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,sEAAsE;AACtE,wEAAwE;AACxE,6EAA6E;AAC7E,4EAA4E;AAC5E,mCAAmC;AACnC,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,uDAAuD;AACvD,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,OAAO,EACL,MAAM,EACN,MAAM,GAGP,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,EACX,QAAQ,EACR,cAAc,GAKf,MAAM,uBAAuB,CAAC;AAW/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CACxB,MAAc,EACd,GAA6B;IAE7B,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC;AAoBD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO;QACL,GAAG,EAAE,CAAC,OAAO,CAAU;QACvB,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,CAAU;QAClD,KAAK,EACH,CACE,MAAc,EACd,MAAc,EACd,WAAoB,EACpB,EAAE,CACJ,CAAC,GAA6B,EAAmB,EAAE,CACjD,WAAW,KAAK,SAAS;YACvB,CAAC,CAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW;YACvD,CAAC,CAAE,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW;KAC3E,CAAC;AACJ,CAAC;AAeD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA0D,EAC1D,IAA0D;IAE1D,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CACtB,QAAQ,CAAC;QACP,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;QACrB,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;QACxB,GAAG,OAAO;KACX,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,aAA8B,EAC9B,IAA0D;IAE1D,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;QACrC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAC7C,OAAO,WAAW,CAAC;YACjB,UAAU,EAAE,CAAC,GAA6B,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;YACxD,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE;gBACrB,WAAW,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC3D,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YACvB,CAAC;YACD,GAAG,IAAI;SACR,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// The React Query wrapper machinery behind forge's generated per-service hook\n// files (`src/hooks/<svc>-service-hooks_gen.ts`).\n//\n// WHAT WAS HERE BEFORE. Each generated file re-emitted the same three things\n// per RPC: a query-key entry, a useQuery or useMutation wrapper, and — for\n// mutations — the entity-scoped invalidateQueries plus the onSuccess\n// composition, with the reasoning for each re-inlined as comments. A\n// five-service project rendered five copies of machinery that differed only in\n// RPC names and message types. This module IS that machinery, written once.\n// The generated file keeps exactly what varies per RPC: the name, the request\n// schema, the response type, query-vs-mutation, and the entity scope.\n//\n// WHY A SUBPATH AND NOT THE BARREL. This module imports @tanstack/react-query.\n// Every browser frontend forge scaffolds depends on it — but the barrel is\n// also what a consumer imports for interceptors and errors alone, and\n// anchoring React Query there would make a non-React consumer resolve a\n// package it never installed. Same reasoning as ./mock-transport and ./otel:\n// an engine with its own dependency footprint gets its own entry point, and\n// React Query is an OPTIONAL peer.\n//\n// WHAT IT DELIBERATELY DOES NOT DO. It does not emit error toasts — the\n// app-wide MutationCache in src/lib/query-client.ts is the single error-toast\n// chokepoint, and pages that render errors inline pass\n// `meta: { silenceErrorToast: true }`. It never defaults success-side UX\n// either: \"CreateOrder succeeded\" leaks RPC names into the UI, so the toast /\n// redirect / inline confirmation stays the call site's via options.onSuccess.\nimport {\n  create,\n  toJson,\n  type DescMessage,\n  type MessageInitShape,\n} from \"@bufbuild/protobuf\";\nimport {\n  useMutation,\n  useQuery,\n  useQueryClient,\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n} from \"@tanstack/react-query\";\n\nimport type { ConnectClientError } from \"./errors.js\";\n\n/**\n * A generated query key. The tuple is [service, entity?, method,\n * protojson(req)] for a method key and [service] / [service, entity] for the\n * broader scopes.\n */\nexport type ServiceQueryKey = readonly unknown[];\n\n/**\n * requestKey projects a request init into protojson for use inside a query\n * key. Two reasons this is not the raw request object:\n *\n *   - React Query's default hasher is JSON.stringify, which THROWS on bigint\n *     fields (any proto int64) — the raw message crashes the cache.\n *   - protojson normalizes representations, so { id: 1 } and { id: \"1\" } land\n *     in ONE cache entry instead of silently splitting the cache.\n *\n * Exported because a hand-written hook that wants to share a generated hook's\n * cache entry has to hash its request the identical way.\n */\nexport function requestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: MessageInitShape<Schema>,\n): unknown {\n  return toJson(schema, create(schema, req));\n}\n\n/** The three key-scope builders a generated key factory is assembled from. */\nexport interface ServiceKeyBuilders {\n  /** Every query on this service: [service]. */\n  readonly all: readonly [string];\n  /** Every query for one CRUD entity: [service, entity]. Mutations invalidate this. */\n  entity(name: string): readonly [string, string];\n  /**\n   * One query: [service, entity?, method, protojson(req)]. Returns the\n   * per-request key FUNCTION, which is what both the query hook and any\n   * call-site prefetch/setQueryData use.\n   */\n  query<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): (req: MessageInitShape<Schema>) => ServiceQueryKey;\n}\n\n/**\n * serviceKeys returns the builders for one service's query-key factory.\n *\n * Cache-key semantics are a compatibility contract, not an implementation\n * detail: an existing app's\n * `invalidateQueries({ queryKey: orderServiceKeys.order })` has to keep\n * matching the keys its queries were registered under across a version bump.\n * So the tuple order and contents produced here are fixed, and identical to\n * what forge previously inlined into every generated hook file.\n */\nexport function serviceKeys(service: string): ServiceKeyBuilders {\n  return {\n    all: [service] as const,\n    entity: (name: string) => [service, name] as const,\n    query:\n      <Schema extends DescMessage>(\n        method: string,\n        schema: Schema,\n        entityScope?: string,\n      ) =>\n      (req: MessageInitShape<Schema>): ServiceQueryKey =>\n        entityScope === undefined\n          ? ([service, method, requestKey(schema, req)] as const)\n          : ([service, entityScope, method, requestKey(schema, req)] as const),\n  };\n}\n\n/** A generated query hook: `useGetOrder(req, options?)`. */\nexport type ServiceQueryHook<Schema extends DescMessage, Response> = (\n  req: MessageInitShape<Schema>,\n  options?: Partial<UseQueryOptions<Response, ConnectClientError>>,\n) => UseQueryResult<Response, ConnectClientError>;\n\n/** A generated mutation hook: `useCreateOrder(options?)`. */\nexport type ServiceMutationHook<Schema extends DescMessage, Response> = (\n  options?: Partial<\n    UseMutationOptions<Response, ConnectClientError, MessageInitShape<Schema>>\n  >,\n) => UseMutationResult<Response, ConnectClientError, MessageInitShape<Schema>>;\n\n/**\n * createQueryHook builds one useQuery wrapper.\n *\n * The signature it returns is the one call sites already use — `(req,\n * options?)`, with the error typed as ConnectClientError rather than React\n * Query's default `Error`. That type is declared on the OPTIONS parameter\n * because React Query takes the result's error type from the same TError it\n * reads there, so `query.error` is a ConnectClientError at every call site\n * with nothing to pass. Typing it as `Error` hid `.reason`, `.code`, `.status`\n * and `.retryable`, and left `err.message.includes(...)` as the only\n * expression that compiled — the one thing the error contract forbids.\n */\nexport function createQueryHook<Schema extends DescMessage, Response>(\n  keyFor: (req: MessageInitShape<Schema>) => ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceQueryHook<Schema, Response> {\n  return (req, options) =>\n    useQuery({\n      queryKey: keyFor(req),\n      queryFn: () => call(req),\n      ...options,\n    });\n}\n\n/**\n * createMutationHook builds one useMutation wrapper with scoped invalidation.\n *\n * invalidateKey is the entity scope when the RPC maps to a CRUD entity, and\n * the whole-service scope otherwise — a bespoke mutation may touch anything,\n * so over-invalidating is the safe default there.\n *\n * The invalidation is composed BEFORE the caller's onSuccess and is never\n * replaced by it: onSuccess is destructured out and re-invoked after the\n * invalidate, while the rest of the options object is spread separately. A\n * caller passing onSuccess therefore ADDS behaviour, rather than silently\n * disabling the cache refresh — which is exactly what a plain `...options`\n * spread over a default onSuccess would do.\n */\nexport function createMutationHook<Schema extends DescMessage, Response>(\n  invalidateKey: ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceMutationHook<Schema, Response> {\n  return (options) => {\n    const queryClient = useQueryClient();\n    const { onSuccess, ...rest } = options ?? {};\n    return useMutation({\n      mutationFn: (req: MessageInitShape<Schema>) => call(req),\n      onSuccess: (...args) => {\n        queryClient.invalidateQueries({ queryKey: invalidateKey });\n        onSuccess?.(...args);\n      },\n      ...rest,\n    });\n  };\n}\n"]}
+{"version":3,"file":"service-hooks.js","sourceRoot":"","sources":["../src/service-hooks.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,sEAAsE;AACtE,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,uEAAuE;AACvE,6EAA6E;AAC7E,+EAA+E;AAC/E,yEAAyE;AACzE,gEAAgE;AAChE,EAAE;AACF,8EAA8E;AAC9E,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,qEAAqE;AACrE,qEAAqE;AACrE,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,sEAAsE;AACtE,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,sEAAsE;AACtE,wEAAwE;AACxE,6EAA6E;AAC7E,4EAA4E;AAC5E,mCAAmC;AACnC,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,uDAAuD;AACvD,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,OAAO,EACL,MAAM,EACN,MAAM,GAGP,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,WAAW,EACX,QAAQ,EACR,cAAc,GAKf,MAAM,uBAAuB,CAAC;AAW/B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CACxB,MAAc,EACd,GAA6B;IAE7B,OAAO,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC;AAoBD;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO;QACL,GAAG,EAAE,CAAC,OAAO,CAAU;QACvB,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,CAAU;QAClD,KAAK,EACH,CACE,MAAc,EACd,MAAc,EACd,WAAoB,EACpB,EAAE,CACJ,CAAC,GAA6B,EAAmB,EAAE,CACjD,WAAW,KAAK,SAAS;YACvB,CAAC,CAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW;YACvD,CAAC,CAAE,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAW;KAC3E,CAAC;AACJ,CAAC;AAeD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA0D,EAC1D,IAA0D;IAE1D,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CACtB,QAAQ,CAAC;QACP,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;QACrB,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;QACxB,GAAG,OAAO;KACX,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,aAA8B,EAC9B,IAA0D;IAE1D,OAAO,CAAC,OAAO,EAAE,EAAE;QACjB,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;QACrC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAC7C,OAAO,WAAW,CAAC;YACjB,UAAU,EAAE,CAAC,GAA6B,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;YACxD,SAAS,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE;gBACrB,WAAW,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;gBAC3D,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YACvB,CAAC;YACD,GAAG,IAAI;SACR,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC","sourcesContent":["\"use client\";\n\n// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// Every export below is a React hook or builds one, so this module belongs in\n// the CLIENT graph. Without the directive the Next.js App Router compiles it\n// into the SERVER graph, where it binds a SECOND @tanstack/react-query\n// instance and every generated hook throws \"No QueryClient set\" at runtime —\n// invisible to tsc, eslint AND `next build`. published-surface.test.ts asserts\n// the directive survives into dist/. It is NOT applied package-wide: the\n// ./interceptors subpath exists to be importable without React.\n//\n// The React Query wrapper machinery behind forge's generated per-service hook\n// files (`src/hooks/<svc>-service-hooks_gen.ts`).\n//\n// WHAT WAS HERE BEFORE. Each generated file re-emitted the same three things\n// per RPC: a query-key entry, a useQuery or useMutation wrapper, and — for\n// mutations — the entity-scoped invalidateQueries plus the onSuccess\n// composition, with the reasoning for each re-inlined as comments. A\n// five-service project rendered five copies of machinery that differed only in\n// RPC names and message types. This module IS that machinery, written once.\n// The generated file keeps exactly what varies per RPC: the name, the request\n// schema, the response type, query-vs-mutation, and the entity scope.\n//\n// WHY A SUBPATH AND NOT THE BARREL. This module imports @tanstack/react-query.\n// Every browser frontend forge scaffolds depends on it — but the barrel is\n// also what a consumer imports for interceptors and errors alone, and\n// anchoring React Query there would make a non-React consumer resolve a\n// package it never installed. Same reasoning as ./mock-transport and ./otel:\n// an engine with its own dependency footprint gets its own entry point, and\n// React Query is an OPTIONAL peer.\n//\n// WHAT IT DELIBERATELY DOES NOT DO. It does not emit error toasts — the\n// app-wide MutationCache in src/lib/query-client.ts is the single error-toast\n// chokepoint, and pages that render errors inline pass\n// `meta: { silenceErrorToast: true }`. It never defaults success-side UX\n// either: \"CreateOrder succeeded\" leaks RPC names into the UI, so the toast /\n// redirect / inline confirmation stays the call site's via options.onSuccess.\nimport {\n  create,\n  toJson,\n  type DescMessage,\n  type MessageInitShape,\n} from \"@bufbuild/protobuf\";\nimport {\n  useMutation,\n  useQuery,\n  useQueryClient,\n  type UseMutationOptions,\n  type UseMutationResult,\n  type UseQueryOptions,\n  type UseQueryResult,\n} from \"@tanstack/react-query\";\n\nimport type { ConnectClientError } from \"./errors.js\";\n\n/**\n * A generated query key. The tuple is [service, entity?, method,\n * protojson(req)] for a method key and [service] / [service, entity] for the\n * broader scopes.\n */\nexport type ServiceQueryKey = readonly unknown[];\n\n/**\n * requestKey projects a request init into protojson for use inside a query\n * key. Two reasons this is not the raw request object:\n *\n *   - React Query's default hasher is JSON.stringify, which THROWS on bigint\n *     fields (any proto int64) — the raw message crashes the cache.\n *   - protojson normalizes representations, so { id: 1 } and { id: \"1\" } land\n *     in ONE cache entry instead of silently splitting the cache.\n *\n * Exported because a hand-written hook that wants to share a generated hook's\n * cache entry has to hash its request the identical way.\n */\nexport function requestKey<Schema extends DescMessage>(\n  schema: Schema,\n  req: MessageInitShape<Schema>,\n): unknown {\n  return toJson(schema, create(schema, req));\n}\n\n/** The three key-scope builders a generated key factory is assembled from. */\nexport interface ServiceKeyBuilders {\n  /** Every query on this service: [service]. */\n  readonly all: readonly [string];\n  /** Every query for one CRUD entity: [service, entity]. Mutations invalidate this. */\n  entity(name: string): readonly [string, string];\n  /**\n   * One query: [service, entity?, method, protojson(req)]. Returns the\n   * per-request key FUNCTION, which is what both the query hook and any\n   * call-site prefetch/setQueryData use.\n   */\n  query<Schema extends DescMessage>(\n    method: string,\n    schema: Schema,\n    entityScope?: string,\n  ): (req: MessageInitShape<Schema>) => ServiceQueryKey;\n}\n\n/**\n * serviceKeys returns the builders for one service's query-key factory.\n *\n * Cache-key semantics are a compatibility contract, not an implementation\n * detail: an existing app's\n * `invalidateQueries({ queryKey: orderServiceKeys.order })` has to keep\n * matching the keys its queries were registered under across a version bump.\n * So the tuple order and contents produced here are fixed, and identical to\n * what forge previously inlined into every generated hook file.\n */\nexport function serviceKeys(service: string): ServiceKeyBuilders {\n  return {\n    all: [service] as const,\n    entity: (name: string) => [service, name] as const,\n    query:\n      <Schema extends DescMessage>(\n        method: string,\n        schema: Schema,\n        entityScope?: string,\n      ) =>\n      (req: MessageInitShape<Schema>): ServiceQueryKey =>\n        entityScope === undefined\n          ? ([service, method, requestKey(schema, req)] as const)\n          : ([service, entityScope, method, requestKey(schema, req)] as const),\n  };\n}\n\n/** A generated query hook: `useGetOrder(req, options?)`. */\nexport type ServiceQueryHook<Schema extends DescMessage, Response> = (\n  req: MessageInitShape<Schema>,\n  options?: Partial<UseQueryOptions<Response, ConnectClientError>>,\n) => UseQueryResult<Response, ConnectClientError>;\n\n/** A generated mutation hook: `useCreateOrder(options?)`. */\nexport type ServiceMutationHook<Schema extends DescMessage, Response> = (\n  options?: Partial<\n    UseMutationOptions<Response, ConnectClientError, MessageInitShape<Schema>>\n  >,\n) => UseMutationResult<Response, ConnectClientError, MessageInitShape<Schema>>;\n\n/**\n * createQueryHook builds one useQuery wrapper.\n *\n * The signature it returns is the one call sites already use — `(req,\n * options?)`, with the error typed as ConnectClientError rather than React\n * Query's default `Error`. That type is declared on the OPTIONS parameter\n * because React Query takes the result's error type from the same TError it\n * reads there, so `query.error` is a ConnectClientError at every call site\n * with nothing to pass. Typing it as `Error` hid `.reason`, `.code`, `.status`\n * and `.retryable`, and left `err.message.includes(...)` as the only\n * expression that compiled — the one thing the error contract forbids.\n */\nexport function createQueryHook<Schema extends DescMessage, Response>(\n  keyFor: (req: MessageInitShape<Schema>) => ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceQueryHook<Schema, Response> {\n  return (req, options) =>\n    useQuery({\n      queryKey: keyFor(req),\n      queryFn: () => call(req),\n      ...options,\n    });\n}\n\n/**\n * createMutationHook builds one useMutation wrapper with scoped invalidation.\n *\n * invalidateKey is the entity scope when the RPC maps to a CRUD entity, and\n * the whole-service scope otherwise — a bespoke mutation may touch anything,\n * so over-invalidating is the safe default there.\n *\n * The invalidation is composed BEFORE the caller's onSuccess and is never\n * replaced by it: onSuccess is destructured out and re-invoked after the\n * invalidate, while the rest of the options object is spread separately. A\n * caller passing onSuccess therefore ADDS behaviour, rather than silently\n * disabling the cache refresh — which is exactly what a plain `...options`\n * spread over a default onSuccess would do.\n */\nexport function createMutationHook<Schema extends DescMessage, Response>(\n  invalidateKey: ServiceQueryKey,\n  call: (req: MessageInitShape<Schema>) => Promise<Response>,\n): ServiceMutationHook<Schema, Response> {\n  return (options) => {\n    const queryClient = useQueryClient();\n    const { onSuccess, ...rest } = options ?? {};\n    return useMutation({\n      mutationFn: (req: MessageInitShape<Schema>) => call(req),\n      onSuccess: (...args) => {\n        queryClient.invalidateQueries({ queryKey: invalidateKey });\n        onSuccess?.(...args);\n      },\n      ...rest,\n    });\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reliantlabs/forge-web-runtime",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "The forge frontend runtime: Connect interceptor stack, session, error boundary, toast queue, <Resource> container, W3C trace propagation and client RUM. The web twin of forge/pkg.",
   "license": "BUSL-1.1",
   "//repository note": "REQUIRED for `npm publish --provenance`, not decoration. npm cross-checks this against the repository in the signed provenance statement and rejects the publish with a 422 if they disagree — an absent field reads as \"\" and fails that comparison. `directory` names the subdirectory this package lives in, so the provenance points at the real source. Omitting this is what made the first 0.3.1 publish fail AFTER the tarball had been signed and written to the sigstore transparency log.",
@@ -62,13 +62,13 @@
     "@bufbuild/protobuf": "^2.5.0",
     "@connectrpc/connect": "^2.0.0",
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/auto-instrumentations-web": "^0.54.0",
-    "@opentelemetry/core": "^2.0.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.200.0",
-    "@opentelemetry/instrumentation": "^0.200.0",
-    "@opentelemetry/resources": "^2.0.0",
-    "@opentelemetry/sdk-trace-base": "^2.0.0",
-    "@opentelemetry/sdk-trace-web": "^2.0.0",
+    "@opentelemetry/auto-instrumentations-web": "^0.67.0",
+    "@opentelemetry/core": "^2.8.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
+    "@opentelemetry/instrumentation": "^0.222.0",
+    "@opentelemetry/resources": "^2.8.0",
+    "@opentelemetry/sdk-trace-base": "^2.8.0",
+    "@opentelemetry/sdk-trace-web": "^2.8.0",
     "@opentelemetry/semantic-conventions": "^1.28.0",
     "@tanstack/react-query": "^5.59.0",
     "react": "^18.3.0 || ^19.0.0"
@@ -106,13 +106,13 @@
     "@bufbuild/protobuf": "^2.5.0",
     "@connectrpc/connect": "^2.0.0",
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/auto-instrumentations-web": "^0.54.0",
-    "@opentelemetry/core": "^2.0.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.200.0",
-    "@opentelemetry/instrumentation": "^0.200.0",
-    "@opentelemetry/resources": "^2.0.0",
-    "@opentelemetry/sdk-trace-base": "^2.0.0",
-    "@opentelemetry/sdk-trace-web": "^2.0.0",
+    "@opentelemetry/auto-instrumentations-web": "^0.67.0",
+    "@opentelemetry/core": "^2.8.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
+    "@opentelemetry/instrumentation": "^0.222.0",
+    "@opentelemetry/resources": "^2.8.0",
+    "@opentelemetry/sdk-trace-base": "^2.8.0",
+    "@opentelemetry/sdk-trace-web": "^2.8.0",
     "@opentelemetry/semantic-conventions": "^1.28.0",
     "@tanstack/react-query": "^5.59.0",
     "@types/node": "^22.14.0",
@@ -120,7 +120,7 @@
     "@types/react-18": "npm:@types/react@~18.3.0",
     "react": "^19.1.0",
     "typescript": "^5.8.0",
-    "vitest": "^3.1.0"
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=22"