@djangocfg/devtools 2.1.567 → 2.1.570

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/devtools",
-  "version": "2.1.567",
+  "version": "2.1.570",
   "description": "Frontend devtools for django-cfg apps: error/console capture with backend ingest, plus a floating debug panel. One package, one event stream.",
   "keywords": [
     "django",
@@ -46,19 +46,21 @@
   ],
   "scripts": {
     "check": "tsc --noEmit",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/ui-core": "^2.1.567",
+    "@djangocfg/ui-core": "^2.1.570",
     "lucide-react": ">=0.400.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zustand": "^5.0.0"
   },
   "devDependencies": {
-    "@djangocfg/eslint-config": "^2.1.567",
-    "@djangocfg/typescript-config": "^2.1.567",
-    "@djangocfg/ui-core": "^2.1.567",
+    "@djangocfg/eslint-config": "^2.1.570",
+    "@djangocfg/typescript-config": "^2.1.570",
+    "@djangocfg/ui-core": "^2.1.570",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",
@@ -66,6 +68,7 @@
     "lucide-react": "^0.545.0",
     "storybook": "^10.5.0",
     "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
     "zustand": "^5.0.14"
   }
 }

package/src/__tests__/formatConsoleArgs.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatConsoleArgs } from '../capture';
+
+/**
+ * What reaches the alert has to say what broke.
+ *
+ * consola styles its tag with `%c`, so one logger call arrives as
+ * ["%capi:auth%c message", "<css>", "", err]. Joined on a space, the
+ * stylesheet became the message and the truncation then cut the sentence that
+ * mattered — the Telegram alert read "background: #c0392b; border-radius…".
+ */
+describe('formatConsoleArgs', () => {
+  describe('the production case', () => {
+    it('drops the stylesheet and keeps the sentence', () => {
+      const css = '\n      background: #c0392b;\n      border-radius: 0.5em;\n      color: white;\n    ';
+      const out = formatConsoleArgs([
+        '%capi:auth:error%c Verify OTP failed:',
+        css,
+        '',
+        new Error('HTTP 401: '),
+      ]);
+      // The trailing space is the Error's own message, not our formatting.
+      expect(out).toBe('api:auth:error Verify OTP failed: HTTP 401: ');
+      expect(out).not.toContain('background');
+      expect(out).not.toContain('%c');
+    });
+  });
+
+  describe('format specifiers', () => {
+    it('substitutes %s', () => {
+      expect(formatConsoleArgs(['hello %s', 'world'])).toBe('hello world');
+    });
+
+    it.each([
+      ['%d', 42.9, '42'],
+      ['%i', 42.9, '42'],
+      ['%f', 1.5, '1.5'],
+    ])('substitutes %s', (spec, input, expected) => {
+      expect(formatConsoleArgs([`n=${spec}`, input])).toBe(`n=${expected}`);
+    });
+
+    it('serialises %o and %j', () => {
+      expect(formatConsoleArgs(['%o', { a: 1 }])).toBe('{"a":1}');
+      expect(formatConsoleArgs(['%j', { a: 1 }])).toBe('{"a":1}');
+    });
+
+    it('treats %% as a literal percent and consumes no argument', () => {
+      expect(formatConsoleArgs(['100%% done %s', 'ok'])).toBe('100% done ok');
+    });
+
+    it('appends arguments the format string does not claim', () => {
+      /* What the browser does with extras — dropping them would lose the
+         error object, which is the only part worth reading. */
+      expect(formatConsoleArgs(['%s:', 'ctx', 'detail', 42])).toBe('ctx: detail 42');
+    });
+
+    it('keeps an unmatched specifier rather than inventing a value', () => {
+      expect(formatConsoleArgs(['a %s b %s', 'one'])).toBe('a one b %s');
+    });
+  });
+
+  describe('when there is nothing to substitute', () => {
+    it('joins plain arguments on a space, as before', () => {
+      expect(formatConsoleArgs(['failed:', 'because'])).toBe('failed: because');
+    });
+
+    it('leaves a non-string first argument alone', () => {
+      expect(formatConsoleArgs([{ a: 1 }, 'tail'])).toBe('{"a":1} tail');
+    });
+
+    it('uses an Error message, not its stringification', () => {
+      expect(formatConsoleArgs(['boom:', new Error('the reason')])).toBe('boom: the reason');
+    });
+
+    it('survives a value JSON cannot serialise', () => {
+      const cyclic: Record<string, unknown> = {};
+      cyclic.self = cyclic;
+      expect(() => formatConsoleArgs(['x', cyclic])).not.toThrow();
+    });
+  });
+
+  describe('edge cases that must not throw', () => {
+    it.each([[[]], [[undefined]], [[null]], [['%c']], [['%c', 'css']]])(
+      'handles %j',
+      (args) => {
+        expect(() => formatConsoleArgs(args as unknown[])).not.toThrow();
+      },
+    );
+
+    it('produces nothing but the tag when the message is only a style', () => {
+      expect(formatConsoleArgs(['%ctag%c', 'css', ''])).toBe('tag');
+    });
+  });
+});

package/src/__tests__/isStreamingRuntimeNoise.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+
+import { isStreamingRuntimeNoise } from '../capture';
+
+/**
+ * React's inline streaming scripts fail only when something outside the app
+ * removed the hidden segment first. The stacks below are verbatim from
+ * carapis.com's monitor log, 2026-09-23.
+ */
+describe('isStreamingRuntimeNoise', () => {
+  it('drops a $RS failure', () => {
+    const stack =
+      "TypeError: Cannot read properties of null (reading 'parentNode')\n" +
+      '    at $RS (https://carapis.com/catalog/genesis/eq900/c2d25771/:2:3330)\n' +
+      '    at https://carapis.com/catalog/genesis/eq900/c2d25771/:3:77605';
+    expect(isStreamingRuntimeNoise(stack)).toBe(true);
+  });
+
+  it('drops a $RC failure', () => {
+    expect(
+      isStreamingRuntimeNoise("TypeError: x\n    at $RC (https://a.test/:2:10)\n    at https://a.test/:9:1"),
+    ).toBe(true);
+  });
+
+  it('keeps an app error whose top frame is the app', () => {
+    const stack =
+      "TypeError: Cannot read properties of null (reading 'parentNode')\n" +
+      '    at Gallery (https://carapis.com/_next/static/chunks/abc.js:1:200)\n' +
+      '    at $RS (https://carapis.com/x/:2:3330)';
+    expect(isStreamingRuntimeNoise(stack)).toBe(false);
+  });
+
+  it('keeps an app function that merely starts with $R', () => {
+    expect(isStreamingRuntimeNoise('Error\n    at $Router (https://a.test/app.js:1:1)')).toBe(false);
+  });
+
+  it('keeps an event with no stack', () => {
+    expect(isStreamingRuntimeNoise(undefined)).toBe(false);
+    expect(isStreamingRuntimeNoise('')).toBe(false);
+  });
+});

package/src/capture.ts

@@ -31,9 +31,31 @@ const LIBRARY_NOISE: RegExp[] = [
   /input-otp could not insert CSS rule/i,
 ]
 
+// React's streaming-SSR runtime: the inline `$RS` (reveal segment), `$RC`
+// (complete boundary) and kin that the server writes into the HTML to move
+// each late chunk from its `<div hidden id="S:n">` into its placeholder.
+// They throw only when that hidden element is already gone — something
+// outside the app rewrote the document before the stream finished (a
+// headless scraper stripping hidden nodes, a reader-mode or translation
+// rewrite). The frame is React's, never the app's, and nothing on the page
+// can fix it. Measured on carapis.com, 2026-09-23: 19,381 events in a day,
+// 99.9% from one fixed "Chrome/145" user agent, each page load failing all
+// 19 of its `$RS` calls at once — while a real browser on the same URL
+// raised none.
+const STREAMING_RUNTIME_FRAME = /^\s*at \$R[A-Z]{1,2} \(/m
+
+export function isStreamingRuntimeNoise(stack?: string): boolean {
+  if (!stack) return false
+  // The TOP frame only: an app error that merely passed through a streamed
+  // chunk still has its own frame first, and must still be reported.
+  const firstFrame = stack.split('\n').find((line) => /^\s*at /.test(line))
+  return firstFrame !== undefined && STREAMING_RUNTIME_FRAME.test(firstFrame)
+}
+
 function isNoise(msg: string, stack?: string): boolean {
   if (HYDRATION_NOISE.some((p) => p.test(msg))) return true
   if (LIBRARY_NOISE.some((p) => p.test(msg))) return true
+  if (isStreamingRuntimeNoise(stack)) return true
   // Our own transport failing must never loop back into capture.
   return INGEST_PATTERN.test(msg) || INGEST_PATTERN.test(stack ?? '')
 }
@@ -92,22 +114,64 @@ export function installJsErrorCapture(): () => void {
 
 // ─── console.warn / console.error ────────────────────────────────────────────
 
+function stringifyOne(a: unknown): string {
+  let s: string
+  if (typeof a === 'string') s = a
+  else if (a instanceof Error) s = a.message
+  else {
+    try {
+      // `JSON.stringify(undefined)` returns undefined, not a string, and a
+      // function or a symbol does the same — `truncate` then throws on
+      // `.length` and the capture swallows the whole event.
+      s = JSON.stringify(a) ?? String(a)
+    } catch {
+      s = String(a)
+    }
+  }
+  return truncate(s, ARG_MAX)
+}
+
+/**
+ * Apply console format specifiers the way the browser does.
+ *
+ * consola styles its tag with `%c`, so a single logger call arrives here as
+ * ["%capi:auth%c Verify OTP failed:", "<css>", "", err]. Joining that on a
+ * space put the stylesheet INTO the message — the Telegram alert read
+ * "background: #c0392b; border-radius: 0.5em; ..." and the sentence that said
+ * what had failed was what the truncation then cut. Every styled log from
+ * consola, and anything else using %c, was unreadable for the same reason.
+ *
+ * Only the specifiers a console actually consumes are handled: `%c` swallows
+ * its argument and contributes nothing, `%s`/`%d`/`%i`/`%f`/`%o`/`%O`/`%j`
+ * substitute theirs. `%%` is a literal percent and consumes nothing. Anything
+ * left over is appended, which is what the browser does with extra arguments.
+ *
+ * Not applied when the first argument is not a string, or carries no
+ * specifier: then there is nothing to substitute and the old join is right.
+ */
+export function formatConsoleArgs(args: unknown[]): string {
+  const [first, ...rest] = args
+  if (typeof first !== 'string' || !/%[csdifoOj%]/.test(first)) {
+    return args.map(stringifyOne).join(' ')
+  }
+
+  let i = 0
+  const out = first.replace(/%([csdifoOj%])/g, (match, spec: string) => {
+    if (spec === '%') return '%'
+    if (i >= rest.length) return match // no argument left: the browser keeps the token
+    const arg = rest[i++]
+    if (spec === 'c') return '' // a style, not content
+    if (spec === 'd' || spec === 'i') return String(Math.trunc(Number(arg)))
+    if (spec === 'f') return String(Number(arg))
+    return stringifyOne(arg)
+  })
+
+  const unused = rest.slice(i).map(stringifyOne)
+  return truncate([out.trim(), ...unused].filter(Boolean).join(' '), ARG_MAX * 4)
+}
+
 function stringifyArgs(args: unknown[]): string {
-  return args
-    .map((a) => {
-      let s: string
-      if (typeof a === 'string') s = a
-      else if (a instanceof Error) s = a.message
-      else {
-        try {
-          s = JSON.stringify(a)
-        } catch {
-          s = String(a)
-        }
-      }
-      return truncate(s, ARG_MAX)
-    })
-    .join(' ')
+  return formatConsoleArgs(args)
 }
 
 export function installConsoleCapture(): () => void {