Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(ok): scroll + outline telemetry in bundles (PRD-8074, PRD-8192) (#3900)
Andrew Mikofalvy1298445d8ca8
diff --git a/.changeset/bug-report-doc-names-detailed-tier.md b/.changeset/bug-report-doc-names-detailed-tier.mdnew file mode 100644index 000000000..fb06caca5--- /dev/null+++ b/.changeset/bug-report-doc-names-detailed-tier.md@@ -0,0 +1,7 @@+---+"@inkeep/open-knowledge": patch+---++Document names are now replaced with a short fingerprint in the basic bug report. The app's diagnostics gained a record of scrolling and outline clicks, which is what makes a "the page jumped" report diagnosable at all, but each of those records named the document it happened in, and several routine log lines already did the same. That turned a report from an ordinary session into a readable list of the files you had open, sent under a notice that mentions logs and system info and says nothing about documents. The support team can still tell which records belong to the same document and follow what happened in it; they no longer receive the list of names. Detailed diagnostics, which you opt into separately and which does say it includes document names, is unchanged.++To be straight about how strong this is: the fingerprint is not reversible in bulk, but it is not a secret either. Someone who already suspects a specific filename can check that guess against a fingerprint. It removes the list, not the possibility of confirming a name someone has reason to try.diff --git a/.changeset/scroll-and-outline-nav-diagnostics.md b/.changeset/scroll-and-outline-nav-diagnostics.mdnew file mode 100644index 000000000..f4c05e744--- /dev/null+++ b/.changeset/scroll-and-outline-nav-diagnostics.md@@ -0,0 +1,11 @@+---+"@inkeep/open-knowledge": patch+---++Bug reports about scrolling and about the outline panel now carry the numbers needed to diagnose them. Two related blind spots.++The editor already measured a lot about restoring your scroll position when you return to a document, but those measurements only ever existed inside the running app and were never written down, so they went with the window when it closed and three separate scroll bugs were investigated without a single scroll measurement between them. Those measurements now also go to the app log a report collects, and each one identifies the document it belongs to along with how far down the document was scrolled, how tall it was, and how much of it was on screen — enough to tell "the editor scrolled past the end of the document" apart from "the content had not finished drawing yet", which previously took a purpose-built reproduction to establish.++Clicking a heading in the outline panel recorded nothing at all. If it took you to the wrong section, or appeared to do nothing, a report could not say which row was clicked, which heading answered, or whether the editor scrolled. It now records all three, in both the visual and the source editor, including the case where something else was already controlling the scroll position and the click was correctly declined — which looks identical to a broken click from the outside. It also records where the clicked heading actually sits in the document, so an outline whose rows have drifted out of step with the page reports the size of the drift directly instead of presenting as an unreproducible complaint.++Headings are user-written text and no report has ever included document prose, so none of this records the heading text itself — the positions alone answer the question.diff --git a/packages/app/src/components/EditorActivityPool.scroll-suppression.dom.test.tsx b/packages/app/src/components/EditorActivityPool.scroll-suppression.dom.test.tsxindex 14490b492..a09cf718f 100644--- a/packages/app/src/components/EditorActivityPool.scroll-suppression.dom.test.tsx+++ b/packages/app/src/components/EditorActivityPool.scroll-suppression.dom.test.tsx@@ -18,7 +18,8 @@*/import { cleanup, render } from '@testing-library/react';-import { afterEach, beforeEach, describe, expect, test } from 'vitest';+import type { RefObject } from 'react';+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import {__resetScrollRestoreCoordination,acquireScrollRestoreSuppression,@@ -27,6 +28,7 @@ import {import type { EditorModeValue } from '@/editor/use-editor-mode';import { getCollector } from '@/lib/perf/collector';import { ScrollPreservingContainer } from './EditorActivityPool';+import { RESTORE_BACKSTOP_MS } from './scroll-restore';const scrollTops = new WeakMap<HTMLElement, number>();let stubScrollHeight = 5000;@@ -57,7 +59,13 @@ beforeEach(() => {return scrollTops.get(this) ?? 0;},set(this: HTMLElement, value: number) {- scrollTops.set(this, value);+ // Clamped like a real scroller rather than accepting any number: a+ // browser refuses a scrollTop outside [0, scrollHeight - clientHeight],+ // so a restore aiming past the rendered runway comes to rest SHORT of+ // its target. An unclamped stub makes every write land, which is the one+ // behaviour that would hide the failures these marks exist to report.+ const maxScroll = Math.max(0, stubScrollHeight - stubClientHeight);+ scrollTops.set(this, Math.min(Math.max(0, value), maxScroll));},});Object.defineProperty(HTMLElement.prototype, 'scrollHeight', {@@ -88,22 +96,53 @@ function scrollerOf(container: HTMLElement): HTMLDivElement {return el;}+/**+ * Re-apply the scroller's current offset so the stub clamps it against the+ * height that just changed — what a browser does on its own the moment content+ * shrinks under a scrolled viewport.+ */+function reclampToCurrentHeight(el: HTMLElement) {+ const current = el.scrollTop;+ el.scrollTop = current;+}+function crossModeMark(): { properties?: Record<string, unknown> } | undefined {return getCollector()?.marks.toArray().find((m) => m.name === 'ok/scroll-restore/cross-mode');}+/**+ * The diagnostic breadcrumbs a `console.info` spy captured, in emission order.+ * Both log transports agree on one wire shape — a lone `console.info` whose+ * only argument is `JSON.stringify({ event, ...props })` — so parsing the+ * argument back is what a bundle reader would see, non-JSON noise dropped.+ */+function breadcrumbLines(info: { mock: { calls: unknown[][] } }): Array<Record<string, unknown>> {+ return info.mock.calls.flatMap(([first]) => {+ if (typeof first !== 'string') return [];+ try {+ return [JSON.parse(first) as Record<string, unknown>];+ } catch {+ return [];+ }+ });+}+function Harness({active,docName,mode = 'wysiwyg',initialScrollTop = 500,+ anchorRef,}: {active: boolean;docName: string;mode?: EditorModeValue;initialScrollTop?: number;+ /** Optional body-top anchor. Omitted, the restore sees no anchor at all and+ * falls back to the raw saved scrollTop. */+ anchorRef?: RefObject<HTMLElement | null>;}) {return (<ScrollPreservingContainer@@ -111,6 +150,7 @@ function Harness({docName={docName}mode={mode}initialScrollTop={initialScrollTop}+ bodyAnchorRef={anchorRef}><div>body content</div></ScrollPreservingContainer>@@ -123,6 +163,37 @@ describe('ScrollPreservingContainer scroll-restore suppression', () => {expect(scrollerOf(container).scrollTop).toBe(500);});+ test('the ordinary restore reports the document and the geometry, not just a target', () => {+ // The whole point of routing these marks: a bundle without `docName` cannot+ // attribute the numbers, and one without the geometry cannot separate a+ // landing past real content from content that had not painted. Both were+ // absent from this mark before, which is why three scroll tickets shipped+ // with no scroll number on disk.+ const info = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ try {+ render(<Harness active docName="doc-geo" />);+ const lines = breadcrumbLines(info);+ // Matched exactly, not by containment: the risk this guards is a field+ // being DROPPED from the payload, which any objectContaining would wave+ // through. `contentBottom` is absent here because jsdom lays nothing out,+ // so the extent probe finds none — its presence on a real restore is what+ // the assertion's exactness protects for the day layout exists.+ expect(lines).toEqual([+ {+ event: 'ok/scroll-restore/phase1-success',+ docName: 'doc-geo',+ target: 500,+ elapsedMs: expect.any(Number),+ scrollTop: 500,+ scrollHeight: 5000,+ clientHeight: 0,+ },+ ]);+ } finally {+ info.mockRestore();+ }+ });+test('stands down and writes no scroll position while a landing holds suppression', () => {acquireScrollRestoreSuppression('doc-b', 'landing');const { container } = render(<Harness active docName="doc-b" />);@@ -165,6 +236,40 @@ describe('ScrollPreservingContainer cross-mode re-activation floor', () => {expect(m?.properties?.applied).toBe(true);});+ test('the same mark reaches the renderer log, where a bundle can carry it', () => {+ // The end of the route, exercised through the real restore rather than+ // through `mark()` directly: the collector this mark also lands in is+ // compiled out of production and `performance.measure` needs DevTools+ // attached, so the log line is the only one of the three a user can send us.+ // Three scroll tickets shipped without a single scroll number on disk.+ const info = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ try {+ rememberDocScrollState('doc-x', { offset: 4321, mode: 'source', fraction: 0.4 });+ render(<Harness active docName="doc-x" mode="wysiwyg" initialScrollTop={0} />);+ const lines = breadcrumbLines(info);+ expect(lines).toEqual([+ // `docName` correlates the numbers to a document, and the geometry+ // triple is what separates "landed past the content" from "content had+ // not painted yet" — the question that previously took an instrumented+ // reproduction to answer. Matched exactly so a dropped field fails.+ {+ event: 'ok/scroll-restore/cross-mode',+ docName: 'doc-x',+ savedMode: 'source',+ mode: 'wysiwyg',+ fraction: 0.4,+ target: 2000,+ applied: true,+ scrollTop: 2000,+ scrollHeight: 5000,+ clientHeight: 0,+ },+ ]);+ } finally {+ info.mockRestore();+ }+ });+test('a same-mode re-activation is unaffected — no floor, no cross-mode mark', () => {// Same mode → the cross-mode branch is skipped and the normal restore drives// the saved position (raw target 777, since this harness renders no body@@ -191,3 +296,204 @@ describe('ScrollPreservingContainer cross-mode re-activation floor', () => {expect(crossModeMark()?.properties?.applied).toBe(false);});});++/**+ * The three `yielded` reasons and the `abandoned` backstop only fire on a+ * restore that is still in flight when something else claims the scroll, so+ * they need the rAF poll to actually run — faked here and driven a frame at a+ * time, rather than left to jsdom's real clock where the test would end first.+ */+describe('ScrollPreservingContainer restore-outcome marks', () => {+ /** One faked animation frame, plus margin: the fake clock schedules the+ * callback on the next 16ms boundary rather than exactly 16ms out. */+ const ONE_FRAME_MS = 20;++ beforeEach(() => {+ vi.useFakeTimers({+ toFake: ['requestAnimationFrame', 'cancelAnimationFrame', 'setTimeout', 'clearTimeout'],+ });+ });++ afterEach(() => {+ // Unmount under the fake clock so the loop's teardown runs against the same+ // timer implementation that scheduled it.+ cleanup();+ vi.useRealTimers();+ });++ /**+ * A restore that can never land: a saved body offset makes the target+ * anchor-relative, and an anchor that generates no layout boxes (detached+ * here; a Suspense fallback window in production) yields no measurement, so+ * every frame holds instead of writing. That is the state all three+ * `yielded` reasons require — the mark exists precisely to make a restore+ * that never landed visible instead of silent.+ */+ function renderNeverLandingRestore(docName: string) {+ rememberDocScrollState(docName, { offset: 300, mode: 'wysiwyg', fraction: 0.1 });+ const anchorRef: RefObject<HTMLElement | null> = { current: document.createElement('div') };+ const { container } = render(<Harness active docName={docName} anchorRef={anchorRef} />);+ const scroller = scrollerOf(container);+ expect(scroller.scrollTop).toBe(0); // held: no valid evidence to write through+ return scroller;+ }++ test('a user scroll during a restore that never landed is reported, with geometry', () => {+ const info = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ try {+ const scroller = renderNeverLandingRestore('doc-yield-user');+ scroller.dispatchEvent(new WheelEvent('wheel'));+ // Exact match, not containment: a dropped field is the failure this+ // guards. `contentBottom` is deliberately absent — the loop passes no+ // extent to the yielded marks.+ expect(breadcrumbLines(info)).toEqual([+ {+ event: 'ok/scroll-restore/yielded',+ docName: 'doc-yield-user',+ reason: 'user',+ elapsedMs: expect.any(Number),+ scrollTop: 0,+ scrollHeight: 5000,+ clientHeight: 0,+ },+ ]);+ } finally {+ info.mockRestore();+ }+ });++ test('a landing taking over mid-restore is reported as its own reason', () => {+ const info = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ try {+ renderNeverLandingRestore('doc-yield-landing');+ // Acquired AFTER mount: acquiring first makes the layout effect stand+ // down at setup, and there is then no restore to take over.+ acquireScrollRestoreSuppression('doc-yield-landing', 'landing');+ vi.advanceTimersByTime(ONE_FRAME_MS);+ // Two lines, not one: a takeover that finds a holder reports WHO has the+ // scroller now (`superseded`) as well as that this restore never landed+ // (`yielded`). Both reach a bundle, so both are asserted whole — a+ // `superseded` line that stopped naming its document would otherwise pass+ // here unread.+ expect(breadcrumbLines(info)).toEqual([+ {+ event: 'ok/scroll-restore/superseded',+ docName: 'doc-yield-landing',+ holder: 'landing',+ elapsedMs: expect.any(Number),+ finalScrollTop: 0,+ },+ {+ event: 'ok/scroll-restore/yielded',+ docName: 'doc-yield-landing',+ reason: 'landing',+ elapsedMs: expect.any(Number),+ scrollTop: 0,+ scrollHeight: 5000,+ clientHeight: 0,+ },+ ]);+ } finally {+ info.mockRestore();+ }+ });++ test('an upward scroll we did not write is reported as an external takeover', () => {+ const info = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ try {+ const scroller = renderNeverLandingRestore('doc-yield-external');+ // What an outline click or find-in-doc does: moves the scroller UP from+ // where the loop left it, between two of its frames.+ scroller.scrollTop = 300;+ vi.advanceTimersByTime(ONE_FRAME_MS);+ expect(breadcrumbLines(info)).toEqual([+ {+ event: 'ok/scroll-restore/yielded',+ docName: 'doc-yield-external',+ reason: 'external',+ elapsedMs: expect.any(Number),+ scrollTop: 300,+ scrollHeight: 5000,+ clientHeight: 0,+ },+ ]);+ } finally {+ info.mockRestore();+ }+ });++ test('a restore the layout can never satisfy is reported at the backstop', () => {+ const info = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ try {+ // Runway enough to keep trying (scrollHeight reaches past the target) but+ // never enough to arrive: the scroller clamps every write to 200 while+ // the target stays 500, so the loop re-applies until the backstop and+ // this mark is the only record that the position was never reached.+ stubScrollHeight = 1000;+ stubClientHeight = 800;+ const { container } = render(<Harness active docName="doc-abandon" />);+ expect(scrollerOf(container).scrollTop).toBe(200);+ vi.advanceTimersByTime(RESTORE_BACKSTOP_MS);+ expect(breadcrumbLines(info)).toEqual([+ {+ event: 'ok/scroll-restore/abandoned',+ docName: 'doc-abandon',+ target: 500,+ anchorMeasurable: true,+ elapsedMs: expect.any(Number),+ scrollTop: 200,+ scrollHeight: 1000,+ clientHeight: 800,+ },+ ]);+ } finally {+ info.mockRestore();+ }+ });++ test('a re-apply after the height collapses and regrows is reported as phase 2', () => {+ const info = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ try {+ const { container } = render(<Harness active docName="doc-phase2" />);+ const scroller = scrollerOf(container);+ expect(scroller.scrollTop).toBe(500); // phase 1 landed++ // The warm-fallback -> real-editor swap: content height collapses, which+ // re-clamps the scroller downward — a shrink-clamp, not a takeover...+ stubScrollHeight = 100;+ reclampToCurrentHeight(scroller);+ expect(scroller.scrollTop).toBe(100);+ vi.advanceTimersByTime(ONE_FRAME_MS); // no runway below the target: hold+ expect(scroller.scrollTop).toBe(100);++ // ...and regrows once the real editor hydrates, which is the frame the+ // poll exists for.+ stubScrollHeight = 5000;+ vi.advanceTimersByTime(ONE_FRAME_MS);+ expect(scroller.scrollTop).toBe(500);++ expect(breadcrumbLines(info)).toEqual([+ {+ event: 'ok/scroll-restore/phase1-success',+ docName: 'doc-phase2',+ target: 500,+ elapsedMs: expect.any(Number),+ scrollTop: 500,+ scrollHeight: 5000,+ clientHeight: 0,+ },+ {+ event: 'ok/scroll-restore/phase2-success',+ docName: 'doc-phase2',+ target: 500,+ elapsedMs: expect.any(Number),+ scrollTop: 500,+ scrollHeight: 5000,+ clientHeight: 0,+ },+ ]);+ } finally {+ info.mockRestore();+ }+ });+});diff --git a/packages/app/src/components/EditorActivityPool.tsx b/packages/app/src/components/EditorActivityPool.tsxindex 5d49d49f0..c54b738a2 100644--- a/packages/app/src/components/EditorActivityPool.tsx+++ b/packages/app/src/components/EditorActivityPool.tsx@@ -597,6 +597,30 @@ interface ActivityEntryProps {serverRestartRecovery: ServerRestartRecoveryState;}+/**+ * The scroller's measurements at the instant a restore mark fires. Every mark in+ * the `ok/scroll-restore` family carries them, because the family is routed into+ * diagnostic bundles and re-deriving them after the fact is precisely what a+ * bundle cannot do.+ *+ * How they are READ differs by outcome — by enough that no summary of it is+ * safe. The `yielded` sites pass `contentBottom: null` unconditionally, so an+ * absent value there means "not measured" rather than "not measurable" and+ * inverts the reading that holds elsewhere; `abandoned` splits again on+ * `anchorMeasurable`. The triage playbook in the bug-triage skill is the single+ * statement of all of it, kept there rather than restated here so the two+ * cannot drift — a short version lived here for several revisions and was+ * wrong about `yielded` for all of them.+ */+function geometry(el: HTMLElement, contentBottom: number | null) {+ return {+ scrollTop: el.scrollTop,+ scrollHeight: el.scrollHeight,+ clientHeight: el.clientHeight,+ ...(contentBottom !== null ? { contentBottom } : {}),+ };+}+/*** Owns one imperative host for a document Activity. Moving that host between* pane mounts reparents DOM without changing the ActivityEntry's React key,@@ -854,6 +878,11 @@ export function ScrollPreservingContainer({fraction: Number(saved.fraction.toFixed(4)),target,applied: applicable && el.scrollTop === target,+ // Measured here rather than passed null: this branch lands on a+ // fraction of the OTHER mode's geometry, which makes it the restore+ // most likely to come to rest past where the document actually+ // reaches — the one case where the content extent is the whole answer.+ ...geometry(el, measureContentExtent(el)),});return;}@@ -929,8 +958,10 @@ export function ScrollPreservingContainer({) {hasLandedOnce = true;mark('ok/scroll-restore/phase1-success', {+ docName,target: frame.target,elapsedMs: performance.now() - startTs,+ ...geometry(el, frame.contentBottom),});}}@@ -965,9 +996,10 @@ export function ScrollPreservingContainer({// invisible (no phase1/phase2-success, no abandoned) — surface it so// operators can distinguish "user took over" from "never ran".mark('ok/scroll-restore/yielded', {+ docName,reason: 'user',elapsedMs: performance.now() - startTs,- finalScrollTop: el.scrollTop,+ ...geometry(el, null),});}finish();@@ -1011,15 +1043,20 @@ export function ScrollPreservingContainer({const holder = scrollSuppressionHolder(docName);if (holder) {mark('ok/scroll-restore/superseded', {+ // Carried for the same reason as every other mark on this track: this+ // one reaches a diagnostic bundle now, and a line there that names no+ // document cannot be tied to the restore it describes.+ docName,holder,elapsedMs: performance.now() - startTs,finalScrollTop: el.scrollTop,});if (!hasLandedOnce) {mark('ok/scroll-restore/yielded', {+ docName,reason: holder,elapsedMs: performance.now() - startTs,- finalScrollTop: el.scrollTop,+ ...geometry(el, null),});}finish();@@ -1034,9 +1071,10 @@ export function ScrollPreservingContainer({if (isExternalScroll(prevScrollTop, el.scrollTop)) {if (!hasLandedOnce) {mark('ok/scroll-restore/yielded', {+ docName,reason: 'external',elapsedMs: performance.now() - startTs,- finalScrollTop: el.scrollTop,+ ...geometry(el, null),});}finish();@@ -1058,8 +1096,10 @@ export function ScrollPreservingContainer({// At-most-once per restore session: phase2-success fires on the// first re-apply that lands, not every frame thereafter.mark('ok/scroll-restore/phase2-success', {+ docName,target: frame.target,elapsedMs: performance.now() - startTs,+ ...geometry(el, frame.contentBottom),});phase2Marked = true;hasLandedOnce = true;@@ -1092,11 +1132,11 @@ export function ScrollPreservingContainer({// the unmeasurable-anchor case is carried by `anchorMeasurable`// with `target` omitted.mark('ok/scroll-restore/abandoned', {+ docName,...(finalTarget !== null ? { target: finalTarget } : {}),anchorMeasurable: finalTarget !== null,elapsedMs: performance.now() - startTs,- scrollHeight: el.scrollHeight,- finalScrollTop: el.scrollTop,+ ...geometry(el, final.contentBottom),});}finish();@@ -1109,7 +1149,7 @@ export function ScrollPreservingContainer({<divref={ref}data-testid="editor-scroll-container"- // Toolbar exclusion zone = 3.5rem (EditorToolbar's rendered height). Six+ // Toolbar exclusion zone = 3.5rem (EditorToolbar's rendered height). Seven// load-bearing constants must move together if the toolbar height changes:// - `pt-14` (here): initial-paint content reserve so doc content doesn't// start behind the absolute-positioned EditorToolbar overlay.@@ -1133,6 +1173,12 @@ export function ScrollPreservingContainer({// - editorToolbarOverlapPx in editor/utils/editor-visible-region.ts: the// top inset of the region selection-anchored floating surfaces clip// and clamp against, so the toolbar band counts as occluded.+ // - the outline-click section of the bug-triage skill's+ // references/bundle-forensics.md: a healthy `block: 'start'` landing+ // rests AT this inset, so the playbook states it as the value+ // `targetTopAfter` is read against. The only entry outside the app,+ // and the only one nothing here would fail on — it goes stale silently+ // and a triager measures against the wrong number.// The toolbar itself: components/EditorToolbar.tsx.className={cn('editor-doc-scroll subtle-scrollbar h-full overflow-y-auto',diff --git a/packages/app/src/components/OutlinePanel.dispatch.dom.test.tsx b/packages/app/src/components/OutlinePanel.dispatch.dom.test.tsxnew file mode 100644index 000000000..fd32221ac--- /dev/null+++ b/packages/app/src/components/OutlinePanel.dispatch.dom.test.tsx@@ -0,0 +1,171 @@+// @vitest-environment jsdom+/**+ * The click as the panel dispatched it.+ *+ * Both consumers guard on document, mode and mount state with bare returns, so+ * a click that reaches neither of them leaves no trace anywhere. This line is+ * what makes "the outline row did nothing" a readable finding instead of an+ * absence: a dispatch with no consumer line following it says the event fired+ * and nobody answered.+ */++import * as actualLinguiMacro from '@lingui/react/macro';+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';+import { act, cleanup, render, screen } from '@testing-library/react';+import userEvent from '@testing-library/user-event';+import type { ReactNode } from 'react';+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';+import { renderLinguiTemplate } from '@/test-utils/lingui-mock';++const DOC_NAME = 'notes/outline-dispatch';+// Levels differ so the emitted `headingLevel` is answered by the clicked row+// rather than satisfied by whatever constant the fixture happens to share.+const HEADINGS = [+ { level: 1, text: 'Alpha', slug: 'alpha' },+ { level: 3, text: 'Beta', slug: 'beta' },+ { level: 2, text: 'Gamma', slug: 'gamma' },+];++vi.doMock('@lingui/core/macro', () => ({+ ...actualLinguiMacro,+ t: renderLinguiTemplate,+ msg: renderLinguiTemplate,+}));+vi.doMock('@lingui/react/macro', () => ({+ ...actualLinguiMacro,+ Trans: ({ children }: { children: ReactNode }) => <>{children}</>,+ useLingui: () => ({ t: renderLinguiTemplate }),+}));+vi.doMock('@/components/PageListContext', () => ({+ usePageList: () => ({ loading: false, pages: new Set<string>([DOC_NAME]) }),+}));+vi.doMock('@/editor/DocumentContext', () => ({+ useDocumentContext: () => ({ activeProvider: null, activeDocName: DOC_NAME }),+}));+vi.doMock('@/hooks/useActiveHeading', () => ({+ useActiveHeading: () => activeSlug,+}));++const { OUTLINE_NAV_BREADCRUMB, OUTLINE_NAV_DISPATCH_BREADCRUMB, OUTLINE_NAV_EVENT, OutlinePanel } =+ await import('./OutlinePanel');++let activeSlug: string | null = null;+let originalFetch: typeof fetch;++describe('outline dispatch breadcrumb', () => {+ let infoSpy: ReturnType<typeof vi.spyOn>;++ beforeEach(() => {+ activeSlug = null;+ originalFetch = globalThis.fetch;+ globalThis.fetch = vi.fn(async (input: RequestInfo | URL) => {+ if (String(input).startsWith('/api/page-headings')) {+ return Response.json({ docName: DOC_NAME, headings: HEADINGS });+ }+ return Response.json({}, { status: 404 });+ }) as unknown as typeof fetch;+ infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ });++ afterEach(() => {+ cleanup();+ globalThis.fetch = originalFetch;+ vi.restoreAllMocks();+ });++ function breadcrumbs(event: string): Array<Record<string, unknown>> {+ return infoSpy.mock.calls.flatMap(([first]) => {+ if (typeof first !== 'string') return [];+ let parsed: Record<string, unknown>;+ try {+ parsed = JSON.parse(first) as Record<string, unknown>;+ } catch {+ return [];+ }+ return parsed.event === event ? [parsed] : [];+ });+ }++ async function renderPanel(isSourceMode = false): Promise<void> {+ const client = new QueryClient({+ defaultOptions: { queries: { retry: false, gcTime: 0 } },+ });+ await act(async () => {+ render(+ <QueryClientProvider client={client}>+ <OutlinePanel docName={DOC_NAME} isSourceMode={isSourceMode} />+ </QueryClientProvider>,+ );+ });+ await screen.findByRole('button', { name: 'Gamma' });+ }++ test('a click records the ordinal, the list it indexed, and the mode', async () => {+ await renderPanel();+ await userEvent.click(screen.getByRole('button', { name: 'Gamma' }));+ expect(breadcrumbs(OUTLINE_NAV_DISPATCH_BREADCRUMB)).toEqual([+ expect.objectContaining({+ docName: DOC_NAME,+ index: 2,+ mode: 'wysiwyg',+ outlineCount: 3,+ headingLevel: 2,+ activeIndex: -1,+ }),+ ]);+ });++ test('the dispatch is recorded even when no consumer answers it', async () => {+ // Nothing here mounts an editor, which is the point: the event fires into+ // an empty room and the click is still on the record.+ await renderPanel();+ await userEvent.click(screen.getByRole('button', { name: 'Alpha' }));+ expect(breadcrumbs(OUTLINE_NAV_DISPATCH_BREADCRUMB)).toHaveLength(1);+ expect(breadcrumbs(OUTLINE_NAV_BREADCRUMB)).toEqual([]);+ });++ test('source mode is recorded as such, so a silent consumer is attributable', async () => {+ await renderPanel(true);+ await userEvent.click(screen.getByRole('button', { name: 'Beta' }));+ expect(breadcrumbs(OUTLINE_NAV_DISPATCH_BREADCRUMB)).toEqual([+ expect.objectContaining({ index: 1, mode: 'source', headingLevel: 3 }),+ ]);+ });++ test('the heading depth reaches the line rather than being eaten as a reserved key', async () => {+ // The emitter drops anything named after a key the logger owns, so a+ // regression to `level` would not show up as a corrupted record here — it+ // would show up as the depth going missing. Asserting the absence of+ // `droppedReservedFields` is the form that can actually fail; the+ // corruption itself is pinned in the emitter's own suite.+ await renderPanel();+ await userEvent.click(screen.getByRole('button', { name: 'Gamma' }));+ const [line] = breadcrumbs(OUTLINE_NAV_DISPATCH_BREADCRUMB);+ expect(line.headingLevel).toBe(2);+ expect('droppedReservedFields' in line).toBe(false);+ });++ test('the marker position rides along, so the panel disagreeing with itself is visible', async () => {+ // The marker resolves by slug and the click by ordinal. Recording both+ // makes a disagreement between the two readable off one line.+ activeSlug = 'gamma';+ await renderPanel();+ await userEvent.click(screen.getByRole('button', { name: 'Alpha' }));+ expect(breadcrumbs(OUTLINE_NAV_DISPATCH_BREADCRUMB)).toEqual([+ expect.objectContaining({ index: 0, activeIndex: 2 }),+ ]);+ });++ test('the dispatched event still carries the detail the consumers read', async () => {+ const seen: unknown[] = [];+ const listener = (e: Event) => seen.push((e as CustomEvent).detail);+ window.addEventListener(OUTLINE_NAV_EVENT, listener);+ try {+ await renderPanel();+ await userEvent.click(screen.getByRole('button', { name: 'Beta' }));+ } finally {+ window.removeEventListener(OUTLINE_NAV_EVENT, listener);+ }+ expect(seen).toEqual([{ docName: DOC_NAME, index: 1, slug: 'beta', mode: 'wysiwyg' }]);+ });+});diff --git a/packages/app/src/components/OutlinePanel.tsx b/packages/app/src/components/OutlinePanel.tsxindex c180fe463..f8e3477d1 100644--- a/packages/app/src/components/OutlinePanel.tsx+++ b/packages/app/src/components/OutlinePanel.tsx@@ -24,6 +24,7 @@ import { useDocumentContext } from '@/editor/DocumentContext';import { HttpResponseParseError } from '@/editor/http-client';import { rememberPendingSourceNavigation } from '@/editor/source-editor-navigation';import { useActiveHeading } from '@/hooks/useActiveHeading';+import { emitDiagnosticBreadcrumb } from '@/lib/diagnostic-breadcrumb';import { ProfilerBoundary } from '@/lib/perf';import { cn } from '@/lib/utils';@@ -80,6 +81,20 @@ export interface OutlineNavDetail {export const OUTLINE_NAV_EVENT = 'open-knowledge:outline-nav';+/**+ * Event name the two outline-nav consumers report under, so one grep over a+ * diagnostic bundle finds every click regardless of which editor answered it.+ * Lives beside the event it traces rather than in either consumer, because+ * neither consumer is the one both of them share.+ */+export const OUTLINE_NAV_BREADCRUMB = 'ok-outline-nav';++/** The click as the panel dispatched it, before any consumer has seen it. */+export const OUTLINE_NAV_DISPATCH_BREADCRUMB = 'ok-outline-nav-dispatch';++/** Where the scroll came to rest, once the smooth animation has finished. */+export const OUTLINE_NAV_SETTLED_BREADCRUMB = 'ok-outline-nav-settled';+export function OutlinePanel(props: {docName: string;isSourceMode: boolean;@@ -162,6 +177,31 @@ function OutlinePanelInner({if (detail.mode === 'source') {rememberPendingSourceNavigation(docName, { kind: 'outline', detail });}+ // Emitted here, at the dispatch, and not left to the consumers. Every+ // consumer guard is a bare return — wrong document, wrong mode, view not+ // mounted — so without this line a click that reaches no consumer is+ // indistinguishable from a click that never happened, and "the row did+ // nothing" is exactly the report this instrumentation has to answer.+ // A consumer line that never follows this one is itself the finding.+ emitDiagnosticBreadcrumb(OUTLINE_NAV_DISPATCH_BREADCRUMB, {+ docName,+ index,+ mode: detail.mode,+ // Named for the enumeration it counted, not generically: each consumer+ // reports the count of ITS OWN list under its own name, and the three+ // disagreeing is the drift this instrumentation exists to expose. A+ // shared `headingCount` would hide that behind one word.+ outlineCount: headings.length,+ // NOT `level`: that name belongs to the log record's own producer, so the+ // emitter and the capture chokepoint both drop it. Using it would cost+ // the heading depth entirely rather than corrupt anything — the field+ // would simply never reach the line.+ headingLevel: headings[index]?.level,+ // What the panel's own marker believed was current, resolved by slug+ // rather than by ordinal. The two disagreeing is the panel disagreeing+ // with itself about the same document.+ activeIndex,+ });window.dispatchEvent(new CustomEvent(OUTLINE_NAV_EVENT, { detail }));}diff --git a/packages/app/src/editor/SourceEditor.dom.test.tsx b/packages/app/src/editor/SourceEditor.dom.test.tsxindex c22dc26b3..f3a63c589 100644--- a/packages/app/src/editor/SourceEditor.dom.test.tsx+++ b/packages/app/src/editor/SourceEditor.dom.test.tsx@@ -7,7 +7,11 @@ import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';import { Awareness } from 'y-protocols/awareness';import * as Y from 'yjs';import { subscribeToOpenAskAiComposer } from '@/components/ask-ai-composer-events';-import { OUTLINE_NAV_EVENT, type OutlineNavDetail } from '@/components/OutlinePanel';+import {+ OUTLINE_NAV_BREADCRUMB,+ OUTLINE_NAV_EVENT,+ type OutlineNavDetail,+} from '@/components/OutlinePanel';import { LINT_NAV_EVENT, type LintNavDetail } from '@/components/ProblemsPanel';import { ConfigContext, type ConfigContextValue } from '@/lib/config-context';import { evictCmEditor } from './editor-cache';@@ -367,6 +371,77 @@ describe('SourceEditor outline navigation', () => {expect(headingLine.text).toBe('## Second');expect(view.state.selection.main.head).toBe(headingLine.from);});++ describe('breadcrumb', () => {+ // Only one of the two outline consumers ever answers a given click, so a+ // bundle that instruments the WYSIWYG side alone cannot separate "the user+ // was in source mode" from "the event never fired".+ let infoSpy: ReturnType<typeof vi.spyOn>;++ beforeEach(() => {+ __resetScrollRestoreCoordination();+ infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ });++ afterEach(() => {+ __resetScrollRestoreCoordination();+ vi.restoreAllMocks();+ });++ function breadcrumbs(): Array<Record<string, unknown>> {+ return infoSpy.mock.calls.flatMap(([first]) => {+ if (typeof first !== 'string') return [];+ let parsed: Record<string, unknown>;+ try {+ parsed = JSON.parse(first) as Record<string, unknown>;+ } catch {+ return [];+ }+ return parsed.event === OUTLINE_NAV_BREADCRUMB ? [parsed] : [];+ });+ }++ async function mountSource(docName: string, content: string): Promise<void> {+ const { provider, ytext } = makeProvider(docName, content);+ const { container } = render(<Harness provider={provider} ytext={ytext} wordWrap={true} />);+ await findCmContent(container);+ }++ test('a jump reports the line it landed on', async () => {+ await mountSource('source-outline-crumb', '# First\n\n## Second\n\n## Third');+ await dispatchOutlineNav('source-outline-crumb', 2, 'third');+ expect(breadcrumbs()).toEqual([+ expect.objectContaining({+ docName: 'source-outline-crumb',+ mode: 'source',+ index: 2,+ sourceHeadingCount: 3,+ outcome: 'scrolled',+ targetLine: 5,+ }),+ ]);+ });++ test('a declined claim is recorded rather than read as a completed jump', async () => {+ await mountSource('source-outline-crumb-declined', '# First\n\n## Second');+ registerLandingScrollOwner('source-outline-crumb-declined', {+ yieldsToNavigation: false,+ supersede: () => {},+ });+ await dispatchOutlineNav('source-outline-crumb-declined', 1, 'second');+ expect(breadcrumbs()).toEqual([+ expect.objectContaining({ mode: 'source', index: 1, outcome: 'declined' }),+ ]);+ });++ test('an out-of-range ordinal reports the count that made it out of range', async () => {+ await mountSource('source-outline-crumb-range', '# Only');+ await dispatchOutlineNav('source-outline-crumb-range', 7, 'nowhere');+ expect(breadcrumbs()).toEqual([+ expect.objectContaining({ index: 7, sourceHeadingCount: 1, outcome: 'no-target' }),+ ]);+ });+ });});describe('SourceEditor raw-MDX replay mode re-check', () => {diff --git a/packages/app/src/editor/SourceEditor.tsx b/packages/app/src/editor/SourceEditor.tsxindex 680473a14..641f79b89 100644--- a/packages/app/src/editor/SourceEditor.tsx+++ b/packages/app/src/editor/SourceEditor.tsx@@ -12,7 +12,11 @@ import { useTheme } from 'next-themes';import { useEffect, useRef, useState } from 'react';import { yCollab, yUndoManagerKeymap } from 'y-codemirror.next';import type * as Y from 'yjs';-import { OUTLINE_NAV_EVENT, type OutlineNavDetail } from '@/components/OutlinePanel';+import {+ OUTLINE_NAV_BREADCRUMB,+ OUTLINE_NAV_EVENT,+ type OutlineNavDetail,+} from '@/components/OutlinePanel';import { LINT_NAV_EVENT, type LintNavDetail } from '@/components/ProblemsPanel';import {createNestedCMExtensions,@@ -21,6 +25,7 @@ import {} from '@/editor/extensions/nested-cm-extensions';import type { RawMdxNavDetail } from '@/editor/extensions/raw-mdx-nav-event';import { useConfigContext } from '@/lib/config-provider';+import { emitDiagnosticBreadcrumb } from '@/lib/diagnostic-breadcrumb';import { editorToolbarOverlapPx } from '@/lib/editor-toolbar-overlap';import { claimNoteWindowInitialFocus } from '@/lib/note-window-focus';import { registerSourceView, unregisterSourceView } from './active-source-view';@@ -73,19 +78,48 @@ interface SourceEditorProps {isSourceModeActive: boolean;}+/**+ * Both outcomes report themselves under the same event the WYSIWYG consumer+ * uses, distinguished by `mode`. A bundle has to answer "the outline click did+ * nothing" whichever surface the user was looking at, and only one of the two+ * consumers ever sees a given click — so instrumenting one of them leaves half+ * the reports as silent as before.+ */function applyOutlineNavigation(view: EditorView, detail: OutlineNavDetail, docName: string): void {// The outline row's index maps 1:1 onto this enumeration, which shares its// line-admission rules with the server producer that emitted the row.- const heading = sourceHeadingLines(view.state.doc)[detail.index];- if (!heading) return;+ const lines = sourceHeadingLines(view.state.doc);+ const heading = lines[detail.index];+ const trace = {+ docName,+ mode: 'source',+ index: detail.index,+ // Named for the enumeration it counted. This scan shares its line-admission+ // rules with the server producer, so it should equal the dispatch line's+ // `outlineCount`; the WYSIWYG DOM is a third enumeration that need not.+ sourceHeadingCount: lines.length,+ };+ if (!heading) {+ emitDiagnosticBreadcrumb(OUTLINE_NAV_BREADCRUMB, { ...trace, outcome: 'no-target' });+ return;+ }- runScrollNavigation(docName, 'outline', () => {+ const claimed = runScrollNavigation(docName, 'outline', () => {view.dispatch({selection: EditorSelection.cursor(heading.from),effects: EditorView.scrollIntoView(heading.from, { y: 'start' }),});view.focus();});+ emitDiagnosticBreadcrumb(OUTLINE_NAV_BREADCRUMB, {+ ...trace,+ outcome: claimed ? 'scrolled' : 'declined',+ // Where the caret was sent, as a line number. Unlike the WYSIWYG side there+ // is no pixel geometry to read — CodeMirror owns its own scroller and the+ // effect is queued — and a line number is the coordinate a triager can+ // check against the document without converting anything.+ targetLine: view.state.doc.lineAt(heading.from).number,+ });}export function applyRawMdxNavigation(@@ -103,6 +137,10 @@ export function applyRawMdxNavigation(// Clamp offset to doc length (offset may exceed doc length if content// differs between Y.Text and originalSpan).const pos = Math.min(detail.offset, doc.length);+ // The only jump here that still discards the claim result: the outline+ // path captures it and the problems-row jump returns it, so a navigation a+ // landing declined leaves no trace on this one alone. Known gap, not the+ // pattern: the outline click is what carries a reported bug today.runScrollNavigation(docName, 'raw-mdx', () => {view.dispatch({selection: EditorSelection.cursor(pos),@@ -531,7 +569,15 @@ export function SourceEditor({if (!detail || detail.docName !== docName || detail.mode !== 'source' || !isSourceModeActive)return;const view = viewRef.current;- if (!view) return;+ if (!view) {+ emitDiagnosticBreadcrumb(OUTLINE_NAV_BREADCRUMB, {+ docName,+ mode: 'source',+ index: detail.index,+ outcome: 'no-view',+ });+ return;+ }applyOutlineNavigation(view, detail, docName);clearPendingSourceNavigation(docName);}diff --git a/packages/app/src/editor/TiptapEditor.outline-nav-breadcrumb.dom.test.tsx b/packages/app/src/editor/TiptapEditor.outline-nav-breadcrumb.dom.test.tsxnew file mode 100644index 000000000..bcde9bf3e--- /dev/null+++ b/packages/app/src/editor/TiptapEditor.outline-nav-breadcrumb.dom.test.tsx@@ -0,0 +1,565 @@+// @vitest-environment jsdom+/**+ * What an outline click leaves behind in a diagnostic bundle.+ *+ * A user reported outline rows navigating to the wrong section and the bundle+ * could not say which row was clicked, which heading answered, or whether the+ * scroll happened — the path wrote nothing anywhere. These tests pin the+ * breadcrumb that closes that, and in particular the numbers that make the+ * class self-diagnosing: the outline's rows come from a server scan of the+ * markdown, this consumer resolves them against the headings ProseMirror+ * painted, and the two enumerations are joined by ordinal alone. `slugFoundAt`+ * reports where the clicked row's slug sits in the DOM, so `slugFoundAt - index`+ * is the shift whenever the slug resolves at all; `domHeadingCount` against the+ * dispatch line's `outlineCount` says the same thing without needing it to.+ *+ * The real component runs against a genuine TipTap view (so HeadingAnchors+ * assigns the real slug ids); the surrounding chrome is stubbed to markers, as+ * in the hash-ladder harness next door.+ */++import type { HocuspocusProvider } from '@hocuspocus/provider';+import { act, cleanup, render } from '@testing-library/react';+import { Editor } from '@tiptap/core';+import { Suspense } from 'react';+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';+import { Awareness } from 'y-protocols/awareness';+import * as Y from 'yjs';+import {+ OUTLINE_NAV_BREADCRUMB,+ OUTLINE_NAV_EVENT,+ OUTLINE_NAV_SETTLED_BREADCRUMB,+ type OutlineNavDetail,+} from '@/components/OutlinePanel';+import { sharedExtensions } from './extensions/shared';+import {+ __resetScrollRestoreCoordination,+ registerLandingScrollOwner,+} from './scroll-restore-coordination';++const DOC_NAME = 'outline-nav-doc';+const HEADINGS = [+ { text: 'Alpha', level: 1 },+ { text: 'Beta', level: 3 },+ { text: 'Gamma', level: 2 },+] as const;++let editorEntry: {+ editor: Editor;+ ydoc: Y.Doc;+ ytext: Y.Text;+ provider: HocuspocusProvider;+} | null = null;++vi.doMock('./DocumentContext', () => ({+ useDocumentContext: () => ({+ principal: null,+ activeDocName: DOC_NAME,+ recycleDocument: () => {},+ openTarget: () => {},+ }),+}));+vi.doMock('../presence/identity', () => ({+ useIdentity: () => ({ name: 'Tester', color: '#336699' }),+}));+vi.doMock('./mount-promise', () => ({+ mountTiptapEditorPromise: () => Promise.resolve(editorEntry),+}));+// Only the parking surface is stubbed. `editorScrollContainerOf` stays REAL so+// these tests exercise the actual ancestor walk — the thing that has to pick+// this editor's scroller rather than whichever one happens to be painted.+vi.doMock('./editor-cache', async (importOriginal) => ({+ ...(await importOriginal<typeof import('./editor-cache')>()),+ parkTiptapEditor: () => {},+ peekRenameSnapshot: () => null,+ clearRenameSnapshot: () => {},+}));+// Toggle for the pre-mount / recycle race, which jsdom cannot hold open.+// Delegates to the real accessor otherwise.+vi.doMock('./utils/get-editor-view', async (importOriginal) => {+ const actual = await importOriginal<typeof import('./utils/get-editor-view')>();+ return {+ ...actual,+ getEditorView: (editor: Parameters<typeof actual.getEditorView>[0]) =>+ viewUnavailable ? undefined : actual.getEditorView(editor),+ };+});+vi.doMock('./bubble-menu/BubbleMenuBar', () => ({ BubbleMenuBar: () => <div /> }));+vi.doMock('./table-controls/TableCellHandles', () => ({ TableCellHandles: () => <div /> }));+vi.doMock('@/components/editor/SelectionAnnouncer', () => ({+ SelectionAnnouncer: () => <div />,+}));+vi.doMock('./interaction-layer', () => ({ InteractionLayerView: () => <div /> }));+vi.doMock('@tiptap/react', () => ({ EditorContent: () => <div data-testid="editor-content" /> }));++const { TiptapEditor } = await import('./TiptapEditor');++let scroller: HTMLDivElement | null = null;+let viewUnavailable = false;++function makeProvider(ydoc: Y.Doc): HocuspocusProvider {+ return {+ document: ydoc,+ awareness: new Awareness(ydoc),+ configuration: { name: DOC_NAME },+ on: () => {},+ off: () => {},+ } as unknown as HocuspocusProvider;+}++describe('outline click breadcrumb', () => {+ let host: HTMLElement;+ let portalTarget: HTMLElement;+ let infoSpy: ReturnType<typeof vi.spyOn>;++ beforeEach(() => {+ __resetScrollRestoreCoordination();+ // The real ancestor walk resolves this, so the editor DOM has to live+ // inside a genuine scroll container rather than beside a stand-in.+ scroller = document.createElement('div');+ scroller.setAttribute('data-testid', 'editor-scroll-container');+ document.body.appendChild(scroller);+ scroller.scrollTop = 250;+ host = document.createElement('div');+ scroller.appendChild(host);+ portalTarget = document.createElement('div');+ document.body.appendChild(portalTarget);++ const ydoc = new Y.Doc();+ const ytext = ydoc.getText('source');+ const editor = new Editor({+ element: host,+ extensions: sharedExtensions,+ content: {+ type: 'doc',+ // Levels deliberately differ so `resolvedLevel` is answered by the+ // element rather than satisfied by a constant.+ content: HEADINGS.map(({ text, level }) => ({+ type: 'heading',+ attrs: { level },+ content: [{ type: 'text', text }],+ })),+ },+ });+ editorEntry = { editor, ydoc, ytext, provider: makeProvider(ydoc) };++ Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {+ value: vi.fn(),+ configurable: true,+ writable: true,+ });+ infoSpy = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ });++ afterEach(() => {+ cleanup();+ editorEntry?.editor.destroy();+ editorEntry = null;+ host.remove();+ portalTarget.remove();+ scroller?.remove();+ scroller = null;+ __resetScrollRestoreCoordination();+ vi.restoreAllMocks();+ Reflect.deleteProperty(HTMLElement.prototype, 'scrollIntoView');+ });++ /** Breadcrumbs emitted so far under the outline-nav event, in order. */+ function breadcrumbs(event = OUTLINE_NAV_BREADCRUMB): Array<Record<string, unknown>> {+ return infoSpy.mock.calls.flatMap(([first]) => {+ if (typeof first !== 'string') return [];+ let parsed: Record<string, unknown>;+ try {+ parsed = JSON.parse(first) as Record<string, unknown>;+ } catch {+ return [];+ }+ return parsed.event === event ? [parsed] : [];+ });+ }++ function tree(isSourceMode: boolean) {+ const entry = editorEntry;+ if (!entry) throw new Error('editor entry not prepared');+ return (+ <Suspense fallback={null}>+ <TiptapEditor+ provider={entry.provider}+ isSourceMode={isSourceMode}+ portalTarget={portalTarget}+ />+ </Suspense>+ );+ }++ async function mountEditor(): Promise<ReturnType<typeof render>> {+ let result: ReturnType<typeof render> | undefined;+ await act(async () => {+ result = render(tree(false));+ });+ if (!result) throw new Error('render did not commit');+ return result;+ }++ async function clickOutlineRow(detail: Partial<OutlineNavDetail>): Promise<void> {+ const full: OutlineNavDetail = {+ docName: DOC_NAME,+ index: 0,+ slug: 'alpha',+ mode: 'wysiwyg',+ ...detail,+ };+ await act(async () => {+ window.dispatchEvent(new CustomEvent(OUTLINE_NAV_EVENT, { detail: full }));+ });+ }++ test('HeadingAnchors assigns the slug ids the drift check reads', async () => {+ await mountEditor();+ const ids = Array.from(+ editorEntry?.editor.view.dom.querySelectorAll('h1, h2, h3, h4, h5, h6') ?? [],+ ).map((h) => h.id);+ expect(ids).toEqual(['alpha', 'beta', 'gamma']);+ });++ test('a click that resolves the row it asked for reports no drift', async () => {+ await mountEditor();+ await clickOutlineRow({ index: 2, slug: 'gamma' });+ expect(breadcrumbs()).toEqual([+ expect.objectContaining({+ docName: DOC_NAME,+ mode: 'wysiwyg',+ index: 2,+ domHeadingCount: 3,+ slugFoundAt: 2,+ outcome: 'scrolled',+ resolvedLevel: 2,+ scrollTopBefore: 250,+ scrollHeightBefore: 0,+ }),+ ]);+ });++ test('an ordinal that lands on the wrong heading reports the exact shift', async () => {+ // The outline believes row 1 is "Gamma"; the painted DOM has "Gamma" third.+ // This is the shape a skipped-by-the-scanner heading produces, and the pair+ // of numbers is what a bundle needs to say so without a reproduction.+ await mountEditor();+ await clickOutlineRow({ index: 1, slug: 'gamma' });+ const [line] = breadcrumbs();+ expect(line).toMatchObject({+ index: 1,+ slugFoundAt: 2,+ domHeadingCount: 3,+ outcome: 'scrolled',+ });+ expect((line.slugFoundAt as number) - (line.index as number)).toBe(1);+ });++ test('an out-of-range ordinal reports the count that made it out of range', async () => {+ await mountEditor();+ await clickOutlineRow({ index: 9, slug: 'nowhere' });+ expect(breadcrumbs()).toEqual([+ expect.objectContaining({+ index: 9,+ domHeadingCount: 3,+ slugFoundAt: -1,+ outcome: 'no-target',+ }),+ ]);+ });++ test('a declined claim is recorded rather than read as a completed scroll', async () => {+ // A landing that does not yield owns the scroller, so the click does+ // nothing at all. The user sees a dead row; before this line, so did triage.+ await mountEditor();+ registerLandingScrollOwner(DOC_NAME, {+ yieldsToNavigation: false,+ supersede: () => {},+ });+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ expect(breadcrumbs()).toEqual([+ expect.objectContaining({ index: 0, outcome: 'declined', slugFoundAt: 0 }),+ ]);+ });++ test('a click arriving before the view mounts is reported, not swallowed', async () => {+ // `getEditorView` returns undefined during the recycle/remount race — the+ // window in which a click is otherwise lost with no trace anywhere. The+ // accessor is forced here because that race cannot be held open in jsdom.+ await mountEditor();+ viewUnavailable = true;+ try {+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ } finally {+ viewUnavailable = false;+ }+ expect(breadcrumbs()).toEqual([+ expect.objectContaining({ docName: DOC_NAME, index: 0, outcome: 'no-view' }),+ ]);+ });++ test('the scroller is this editor own, not whichever pane happens to be painted', async () => {+ // A second pane's container, EARLIER in the document than this editor's, is+ // what a painted-container lookup would return. Every position on the line+ // would then describe a document nobody clicked in.+ const otherPane = document.createElement('div');+ otherPane.setAttribute('data-testid', 'editor-scroll-container');+ otherPane.scrollTop = 8888;+ document.body.insertBefore(otherPane, document.body.firstChild);+ try {+ await mountEditor();+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ expect(breadcrumbs()).toEqual([+ expect.objectContaining({ scrollTopBefore: 250, outcome: 'scrolled' }),+ ]);+ } finally {+ otherPane.remove();+ }+ });++ test('a click for another document is not this editor to report', async () => {+ await mountEditor();+ await clickOutlineRow({ docName: 'some/other-doc', index: 0, slug: 'alpha' });+ expect(breadcrumbs()).toEqual([]);+ });++ test('a source-mode click is not this consumer to report', async () => {+ await mountEditor();+ await clickOutlineRow({ index: 0, slug: 'alpha', mode: 'source' });+ expect(breadcrumbs()).toEqual([]);+ });++ test('where the scroller came to rest arrives after the smooth scroll settles', async () => {+ vi.useFakeTimers();+ try {+ await mountEditor();+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ expect(breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB)).toEqual([]);+ if (scroller) scroller.scrollTop = 40;+ await act(async () => {+ vi.runAllTimers();+ });+ expect(breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB)).toEqual([+ expect.objectContaining({+ docName: DOC_NAME,+ index: 0,+ scrollTopAfter: 40,+ targetTopAfter: 0,+ scrollHeightAfter: 0,+ }),+ ]);+ } finally {+ vi.useRealTimers();+ }+ });++ test('the settle read re-measures the target, not just where the scroller stopped', async () => {+ // Content above the target carries an estimated intrinsic height until it+ // paints. It materializes at its real height as the scroll passes through,+ // which moves the target out from under the landing — the scroller reports+ // a clean arrival while the user is looking at the wrong section. The+ // target's own position after settling is the observable that says so, and+ // the growth in scrollHeight is what names the cause.+ vi.useFakeTimers();+ try {+ await mountEditor();+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ const target = editorEntry?.editor.view.dom.querySelector('h1');+ if (!target || !scroller) throw new Error('fixture not prepared');+ // The document grew underneath the landing and pushed the target down.+ target.getBoundingClientRect = () => ({ top: 17_000 }) as DOMRect;+ Object.defineProperty(scroller, 'scrollHeight', { value: 26_000, configurable: true });+ await act(async () => {+ vi.runAllTimers();+ });+ expect(breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB)).toEqual([+ expect.objectContaining({ targetTopAfter: 17_000, scrollHeightAfter: 26_000 }),+ ]);+ } finally {+ vi.useRealTimers();+ }+ });++ test('a heading replaced mid-animation reports its absence, not a zero-rect position', async () => {+ // A detached node answers `getBoundingClientRect` with a zero rect rather+ // than refusing, so an unguarded re-measure would report `-scrollerTop` —+ // indistinguishable from a real position. A remote edit inside the 600 ms+ // window is enough to reach this.+ vi.useFakeTimers();+ try {+ await mountEditor();+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ editorEntry?.editor.view.dom.querySelector('h1')?.remove();+ await act(async () => {+ vi.runAllTimers();+ });+ const [line] = breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB);+ expect(line).toMatchObject({ targetDetached: true, scrollerDetached: false });+ expect('targetTopAfter' in line).toBe(false);+ // The scroller is still live, so its own numbers are still reportable.+ expect(line.scrollTopAfter).toBe(250);+ } finally {+ vi.useRealTimers();+ }+ });++ test('the before-scroll height is read before the scroll, not after it', async () => {+ // `scrollIntoView` is smooth, so a late read usually returns the same+ // number — usually is not what a field called `before` should rest on, and+ // this one is half of the pair that measures the document growing.+ await mountEditor();+ if (!scroller) throw new Error('fixture not prepared');+ // Keyed on the scroll HAVING HAPPENED, not on read ordinal. A read counter+ // would pass whether the statement sat before or after the scroll call —+ // nothing else reads the height in between — so it would pin "this is the+ // handler's first height read", which is true either way.+ Object.defineProperty(scroller, 'scrollHeight', {+ get: () =>+ vi.mocked(HTMLElement.prototype.scrollIntoView).mock.calls.length > 0 ? 99_999 : 1234,+ configurable: true,+ });+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ expect(breadcrumbs()).toEqual([+ expect.objectContaining({ scrollHeightBefore: 1234, outcome: 'scrolled' }),+ ]);+ });++ test('unmounting cancels the pending settle read rather than firing it late', async () => {+ vi.useFakeTimers();+ try {+ await mountEditor();+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ cleanup();+ await act(async () => {+ vi.runAllTimers();+ });+ expect(breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB)).toEqual([]);+ } finally {+ vi.useRealTimers();+ }+ });++ test('flipping to source mode cancels the settle instead of measuring the other pane', async () => {+ // A mode flip is a CSS swap, so this editor stays mounted and both+ // connectedness guards keep passing — while the shared scroller now+ // describes the source view and the hidden pane's `content-visibility`+ // makes the heading answer with a zero rect. The line would land looking+ // like a clean arrival, which is the one outcome worse than no line.+ vi.useFakeTimers();+ try {+ const result = await mountEditor();+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ await act(async () => {+ result.rerender(tree(true));+ });+ await act(async () => {+ vi.runAllTimers();+ });+ expect(breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB)).toEqual([]);+ } finally {+ vi.useRealTimers();+ }+ });++ test('the settled line names its surface, like both of its siblings', async () => {+ vi.useFakeTimers();+ try {+ await mountEditor();+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ await act(async () => {+ vi.runAllTimers();+ });+ expect(breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB)).toEqual([+ expect.objectContaining({ mode: 'wysiwyg' }),+ ]);+ } finally {+ vi.useRealTimers();+ }+ });++ test('rapid clicking settles once, on the landing that survived', async () => {+ vi.useFakeTimers();+ try {+ await mountEditor();+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ await clickOutlineRow({ index: 2, slug: 'gamma' });+ await act(async () => {+ vi.runAllTimers();+ });+ expect(breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB)).toEqual([+ expect.objectContaining({ index: 2 }),+ ]);+ } finally {+ vi.useRealTimers();+ }+ });++ test('the settle read measures the scroller the click measured, not the visible one', async () => {+ // `visibleEditorScrollContainer` answers with whichever scroller is+ // painted, not this document's. A tab switch inside the settle window would+ // otherwise file another document's position under this `docName`, and a+ // confidently wrong number is worse to triage against than a missing one.+ vi.useFakeTimers();+ try {+ await mountEditor();+ const clicked = scroller;+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ if (clicked) clicked.scrollTop = 77;++ // Tagged and painted, and EARLIER in the document than this editor's own,+ // so a settle-time painted-container lookup would answer with it. Without+ // the attribute and the client rect the competitor is inert and the test+ // proves nothing.+ const otherDoc = document.createElement('div');+ otherDoc.setAttribute('data-testid', 'editor-scroll-container');+ otherDoc.getClientRects = (() => [{}]) as unknown as Element['getClientRects'];+ document.body.insertBefore(otherDoc, document.body.firstChild);+ otherDoc.scrollTop = 9999;+ scroller = otherDoc;++ await act(async () => {+ vi.runAllTimers();+ });+ expect(breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB)).toEqual([+ expect.objectContaining({ scrollTopAfter: 77, scrollerDetached: false }),+ ]);+ otherDoc.remove();+ scroller = clicked;+ } finally {+ vi.useRealTimers();+ }+ });++ test('a scroller torn down before the settle reports the teardown, not a zero', async () => {+ vi.useFakeTimers();+ try {+ await mountEditor();+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ scroller?.remove();+ await act(async () => {+ vi.runAllTimers();+ });+ const [line] = breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB);+ expect(line).toMatchObject({ scrollerDetached: true });+ expect('scrollTopAfter' in line).toBe(false);+ } finally {+ vi.useRealTimers();+ }+ });++ test('a declined click schedules no settle read, having moved nothing', async () => {+ vi.useFakeTimers();+ try {+ await mountEditor();+ registerLandingScrollOwner(DOC_NAME, { yieldsToNavigation: false, supersede: () => {} });+ await clickOutlineRow({ index: 0, slug: 'alpha' });+ await act(async () => {+ vi.runAllTimers();+ });+ expect(breadcrumbs(OUTLINE_NAV_SETTLED_BREADCRUMB)).toEqual([]);+ } finally {+ vi.useRealTimers();+ }+ });+});diff --git a/packages/app/src/editor/TiptapEditor.outline-nav.dom.test.tsx b/packages/app/src/editor/TiptapEditor.outline-nav.dom.test.tsxindex 7fbcd7513..640e8afdc 100644--- a/packages/app/src/editor/TiptapEditor.outline-nav.dom.test.tsx+++ b/packages/app/src/editor/TiptapEditor.outline-nav.dom.test.tsx@@ -62,7 +62,12 @@ vi.doMock('../presence/identity', () => ({vi.doMock('./mount-promise', () => ({mountTiptapEditorPromise: () => Promise.resolve(editorEntry),}));-vi.doMock('./editor-cache', () => ({+// Spread the original rather than listing exports: the editor also reads+// `editorScrollContainerOf` from here, and a hand-listed mock silently drops+// whatever it does not name — which surfaces as an unrelated assertion failing+// on an empty array, not as a missing export.+vi.doMock('./editor-cache', async (importOriginal) => ({+ ...(await importOriginal<typeof import('./editor-cache')>()),parkTiptapEditor: () => {},peekRenameSnapshot: () => null,clearRenameSnapshot: () => {},diff --git a/packages/app/src/editor/TiptapEditor.tsx b/packages/app/src/editor/TiptapEditor.tsxindex c1dae8114..0683a3fda 100644--- a/packages/app/src/editor/TiptapEditor.tsx+++ b/packages/app/src/editor/TiptapEditor.tsx@@ -19,7 +19,12 @@ import { initProseMirrorDoc, yCursorPlugin, ySyncPluginKey } from '@tiptap/y-tipimport { type FC, use, useEffect, useLayoutEffect, useRef, useState } from 'react';import { createPortal } from 'react-dom';import { SelectionAnnouncer } from '@/components/editor/SelectionAnnouncer';-import { clearRenameSnapshot, parkTiptapEditor, peekRenameSnapshot } from './editor-cache';+import {+ clearRenameSnapshot,+ editorScrollContainerOf,+ parkTiptapEditor,+ peekRenameSnapshot,+} from './editor-cache';import { InteractionLayerView } from './interaction-layer';import { getInteractionLayer } from './interaction-layer-host';@@ -36,7 +41,13 @@ import { CommentMarginRail } from '@/comments/CommentMarginRail';import { CommentSelectionAffordance } from '@/comments/CommentSelectionAffordance';import { CommentsBoundary } from '@/comments/CommentsBoundary';import { loadFollowFilePref } from '@/components/acp/follow-file';-import { OUTLINE_NAV_EVENT, type OutlineNavDetail } from '@/components/OutlinePanel';+import {+ OUTLINE_NAV_BREADCRUMB,+ OUTLINE_NAV_EVENT,+ OUTLINE_NAV_SETTLED_BREADCRUMB,+ type OutlineNavDetail,+} from '@/components/OutlinePanel';+import { emitDiagnosticBreadcrumb } from '@/lib/diagnostic-breadcrumb';import { anchorFromHash } from '@/lib/doc-hash';import { claimNoteWindowInitialFocus } from '@/lib/note-window-focus';import { mark } from '@/lib/perf';@@ -167,6 +178,14 @@ const ANCHOR_SCROLL_RETRY_MS = 100;const ANCHOR_SCROLL_FOLLOW_UP_ATTEMPTS = 3;const ANCHOR_SCROLL_FOLLOW_UP_MS = 250;+/**+ * How long to let a smooth `scrollIntoView` run before reading where it landed.+ * Long enough to outlast the animation on a slow frame, short enough that a+ * second click supersedes the first (each click clears the pending timer, so+ * rapid outline clicking reports only the landing that survived).+ */+const OUTLINE_NAV_SETTLE_MS = 600;+interface TiptapEditorProps {provider: HocuspocusProvider;placeholder?: string;@@ -1648,26 +1667,151 @@ const TiptapEditorChrome: FC<TiptapEditorChromeProps> = ({// Outline panel click → scroll the Nth heading in the WYSIWYG DOM into view.// Using index (not slug) keeps this robust to duplicate heading texts without// re-implementing HeadingAnchors' dedup logic on the outline side.+ //+ // That ordinal join is also the path's one failure mode, and the reason every+ // branch below reports itself. The outline's rows come from the server, which+ // scans the markdown for ATX headings only; this list is every heading node+ // ProseMirror painted. The two enumerations agree on ordinary documents and+ // diverge on anything the scanner skips but the editor renders, and a single+ // divergence shifts every row after it. `slugFoundAt` measures that drift+ // directly: it is where the clicked row's slug actually sits in the DOM, so+ // `slugFoundAt - index` is the shift, and a report of "the outline jumps to+ // the wrong section" stops needing a reproduction to classify.+ //+ // The slug itself is deliberately NOT logged. It is heading text the user+ // wrote, and no bundle carries document prose today; the ordinals answer the+ // question without opening that door.useEffect(() => {+ // Stood down at the effect body, as the two sibling effects in this file+ // do, rather than inside the handler — where it could never be the branch+ // that returns, because the same `isSourceMode` that gates this stamps the+ // event's own `mode`, and the check below would reject it first. An+ // unreachable guard is one cleanup away from deletion, and deleting it+ // would take the dependency with it and silently restore the bug this+ // arrangement exists to prevent.+ if (isSourceMode) return;+ let settleTimer: ReturnType<typeof setTimeout> | undefined;+function onNav(e: Event) {const detail = (e as CustomEvent<OutlineNavDetail>).detail;if (!detail || detail.docName !== docName || detail.mode !== 'wysiwyg' || editor.isDestroyed)return;+ const trace = { docName, mode: 'wysiwyg', index: detail.index };// `getEditorView` is the non-throwing accessor for the underlying// ProseMirror EditorView (see utils/get-editor-view.ts). Returns// undefined pre-mount, never throws on the recycle/remount race.const realView = getEditorView(editor);- if (!realView) return;+ if (!realView) {+ emitDiagnosticBreadcrumb(OUTLINE_NAV_BREADCRUMB, { ...trace, outcome: 'no-view' });+ return;+ }+ // Resolved from this editor's own DOM, not from whichever container is+ // painted: with two panes open both are, so the painted-container+ // accessor can hand back the other document's scroller and every+ // position below would describe a document nobody clicked in.+ const scroller = editorScrollContainerOf(realView.dom);const headings = realView.dom.querySelectorAll<HTMLElement>('h1, h2, h3, h4, h5, h6');+ const resolved = {+ ...trace,+ scrollTopBefore: scroller?.scrollTop,+ domHeadingCount: headings.length,+ // Where the clicked row's slug actually sits in this list. Compare it+ // to `index` for the shift — but read a -1 as inconclusive, not as a+ // large drift: the outline's slug is derived from the raw markdown+ // line and this id from the heading's rendered text, so a heading+ // containing a link or image slugs differently on the two sides and+ // can never match. `outlineCount` on the dispatch line versus+ // `domHeadingCount` here is the drift signal that does not depend on+ // slugs agreeing.+ slugFoundAt: Array.from(headings).findIndex((h) => h.id === detail.slug),+ };const target = headings[detail.index];- if (!target) return;- runScrollNavigation(docName, 'outline', () => {+ if (!target) {+ emitDiagnosticBreadcrumb(OUTLINE_NAV_BREADCRUMB, { ...resolved, outcome: 'no-target' });+ return;+ }+ // Undefined unless BOTH elements are still in the document. A detached+ // node answers `getBoundingClientRect` with a zero rect rather than+ // refusing, so re-measuring a heading ProseMirror replaced mid-animation+ // would yield `-scrollerTop` — a number that looks like a position.+ const targetTop = () =>+ scroller === null || !scroller.isConnected || !target.isConnected+ ? undefined+ : Math.round(target.getBoundingClientRect().top - scroller.getBoundingClientRect().top);+ // Both "before" numbers are read before the scroll is even claimed. The+ // scroll is smooth, so a read taken after it usually still returns the+ // pre-scroll value — usually is not what a field called `before` should+ // rest on, least of all `scrollHeight`, whose growth is the whole point+ // of bracketing it against the settle reading.+ const targetTopBefore = targetTop();+ const scrollHeightBefore = scroller?.scrollHeight;+ const claimed = runScrollNavigation(docName, 'outline', () => {target.scrollIntoView({ behavior: 'smooth', block: 'start' });});+ emitDiagnosticBreadcrumb(OUTLINE_NAV_BREADCRUMB, {+ ...resolved,+ // A declined claim means a landing owns the scroller and this click did+ // nothing. The user sees a dead row; before this line, so did triage.+ outcome: claimed ? 'scrolled' : 'declined',+ resolvedLevel: Number(target.tagName.slice(1)),+ // Measured from the scroller's top EDGE, which `scroll-padding-top`+ // does not move — so a settled `block: 'start'` scroll rests AT that+ // padding, not at zero: the toolbar inset in a main window, zero only+ // in a note window. That inset is what the settled reading is judged+ // against; this one is taken before the scroll is claimed, so it is+ // the heading's arbitrary starting offset and the two differing says+ // nothing. An absolute offset would need the scroller's own frame to+ // interpret; this reads as "how far off the top it is".+ targetTopBefore,+ scrollHeightBefore,+ });+ if (!claimed) return;+ // `scrollIntoView` is smooth, so the numbers that matter do not exist+ // yet, and one of them is not the scroller's. Content above the target+ // carries `content-visibility: auto` with an estimated intrinsic height;+ // it materializes at its real height as the scroll passes through, which+ // moves the target out from under the landing. Re-measuring only where+ // the scroller stopped would report that as a clean arrival — the target+ // is the observable that says otherwise, and the growth in `scrollHeight`+ // is what names the cause.+ clearTimeout(settleTimer);+ settleTimer = setTimeout(() => {+ emitDiagnosticBreadcrumb(OUTLINE_NAV_SETTLED_BREADCRUMB, {+ docName,+ // Carried even though only this consumer schedules a settle: reading+ // the line's absence for source mode would otherwise take knowledge+ // that lives in this file, not in the bundle.+ mode: 'wysiwyg',+ index: detail.index,+ // The same element measured at click time, never a fresh lookup: a+ // tab switch inside the settle window would otherwise file another+ // document's position under this `docName`, and a confidently wrong+ // number is worse to triage against than a missing one.+ scrollTopAfter: scroller?.isConnected === true ? scroller.scrollTop : undefined,+ scrollHeightAfter: scroller?.isConnected === true ? scroller.scrollHeight : undefined,+ // `targetTop` carries its own connectedness guard, covering the+ // heading as well as the scroller: a remote edit can replace the+ // node inside the settle window while the scroller lives on.+ targetTopAfter: targetTop(),+ scrollerDetached: scroller !== null && !scroller.isConnected,+ targetDetached: !target.isConnected,+ });+ }, OUTLINE_NAV_SETTLE_MS);}window.addEventListener(OUTLINE_NAV_EVENT, onNav);- return () => window.removeEventListener(OUTLINE_NAV_EVENT, onNav);- }, [editor, docName]);+ return () => {+ window.removeEventListener(OUTLINE_NAV_EVENT, onNav);+ clearTimeout(settleTimer);+ };+ // `isSourceMode` earns its place in this list twice over: the handler reads+ // it, and re-registering on a flip is what cancels a settle still pending+ // across one. A flip is a CSS swap — this editor stays mounted — so both+ // connectedness guards keep passing, while the hidden pane's+ // `content-visibility` makes the heading answer with a zero rect and the+ // shared scroller now describes the source view. The settle would land as a+ // confident, wrong, clean-looking arrival. Losing the line is the better+ // trade.+ }, [editor, docName, isSourceMode]);// Publish (or clear) this tab's awareness for the doc this editor binds to.//diff --git a/packages/app/src/editor/editor-cache.ts b/packages/app/src/editor/editor-cache.tsindex 2cefae258..3dddc22c0 100644--- a/packages/app/src/editor/editor-cache.ts+++ b/packages/app/src/editor/editor-cache.ts@@ -449,15 +449,38 @@ export function __resetRenameSnapshotStore(): void {*/export function visibleEditorScrollContainer(): HTMLDivElement | null {if (typeof document === 'undefined') return null;- const containers = document.querySelectorAll<HTMLDivElement>(- '[data-testid="editor-scroll-container"]',- );+ const containers = document.querySelectorAll<HTMLDivElement>(EDITOR_SCROLL_CONTAINER_SELECTOR);for (const el of containers) {if (el.getClientRects().length > 0) return el;}return null;}+const EDITOR_SCROLL_CONTAINER_SELECTOR = '[data-testid="editor-scroll-container"]';++/**+ * The scroll container a given element actually sits in — the one a+ * `scrollIntoView` on it would move.+ *+ * Reach for this over {@link visibleEditorScrollContainer} when the answer has+ * to be a SPECIFIC document's scroller. That accessor answers "which container+ * is painted", a different question with a different answer as soon as two+ * panes are open: both are painted, and it returns whichever comes first in the+ * DOM. Reading a position off the wrong pane is worse than reading none,+ * because the number still looks answerable.+ *+ * The painted-container form stays correct where the caller genuinely means+ * whichever document is on screen, which the mode-switch landing does. The+ * rename snapshot does not: `readActiveScrollTop` takes no document, so one+ * painted-container read is stored against every entry of a rename batch, and a+ * backgrounded doc ends up holding another pane's position. Fixing that wants+ * the snapshotted editor's own container and is a behaviour change with its own+ * blast radius, so it is named here rather than smuggled in.+ */+export function editorScrollContainerOf(el: Element): HTMLDivElement | null {+ return el.closest<HTMLDivElement>(EDITOR_SCROLL_CONTAINER_SELECTOR);+}+/*** Best-effort live scrollTop read from the painted editor scroll container.*/diff --git a/packages/app/src/lib/diagnostic-breadcrumb.test.ts b/packages/app/src/lib/diagnostic-breadcrumb.test.tsnew file mode 100644index 000000000..d6ab30af1--- /dev/null+++ b/packages/app/src/lib/diagnostic-breadcrumb.test.ts@@ -0,0 +1,207 @@+import { RENDERER_LOG_MAX_MESSAGE_BYTES } from '@inkeep/open-knowledge-core';+import { afterEach, describe, expect, test, vi } from 'vitest';+import { emitDiagnosticBreadcrumb, MAX_BREADCRUMB_CHARS } from './diagnostic-breadcrumb';++function captureInfo() {+ return vi.spyOn(console, 'info').mockImplementation(() => undefined);+}++function soleParsedCall(spy: ReturnType<typeof captureInfo>): Record<string, unknown> {+ expect(spy.mock.calls).toHaveLength(1);+ const [first, ...rest] = spy.mock.calls[0];+ // The capture sites only parse a message whose FIRST argument is a lone JSON+ // object; a second argument would be joined into the message text on the web+ // transport and dropped entirely on the Electron one.+ expect(rest).toEqual([]);+ expect(typeof first).toBe('string');+ return JSON.parse(first as string) as Record<string, unknown>;+}++afterEach(() => {+ vi.restoreAllMocks();+});++describe('emitDiagnosticBreadcrumb', () => {+ test('emits one console.info carrying a single JSON object argument', () => {+ const spy = captureInfo();+ emitDiagnosticBreadcrumb('ok-test-event', { docName: 'notes/a', index: 3, claimed: true });+ expect(soleParsedCall(spy)).toEqual({+ event: 'ok-test-event',+ docName: 'notes/a',+ index: 3,+ claimed: true,+ });+ });++ test('emits at info, the only level both capture transports keep', () => {+ // `mapConsoleLevel` maps 'debug' to null and the web forwarder never patches+ // `console.debug`, so a debug breadcrumb reaches no log file on either+ // distribution. warn/error survive but misreport routine diagnostics.+ const info = captureInfo();+ const debug = vi.spyOn(console, 'debug').mockImplementation(() => undefined);+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);+ const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);+ emitDiagnosticBreadcrumb('ok-test-event');+ expect(info).toHaveBeenCalledTimes(1);+ expect(debug).not.toHaveBeenCalled();+ expect(warn).not.toHaveBeenCalled();+ expect(error).not.toHaveBeenCalled();+ });++ test('omits undefined fields rather than serializing them', () => {+ const spy = captureInfo();+ emitDiagnosticBreadcrumb('ok-test-event', { present: 0, absent: undefined });+ const parsed = soleParsedCall(spy);+ expect(parsed).toEqual({ event: 'ok-test-event', present: 0 });+ expect('absent' in parsed).toBe(false);+ });++ test('keeps a false or zero field, which an undefined check must not swallow', () => {+ const spy = captureInfo();+ emitDiagnosticBreadcrumb('ok-test-event', { claimed: false, scrollTop: 0, found: -1 });+ expect(soleParsedCall(spy)).toEqual({+ event: 'ok-test-event',+ claimed: false,+ scrollTop: 0,+ found: -1,+ });+ });++ test('a payload cannot rename its own event and hide from a grep', () => {+ const spy = captureInfo();+ emitDiagnosticBreadcrumb('ok-real-event', { event: 'ok-impostor', docName: 'notes/a' });+ expect(soleParsedCall(spy)).toEqual({ event: 'ok-real-event', docName: 'notes/a' });+ });++ test('drops a nested field and counts it rather than shipping unredactable depth', () => {+ // Pino's keyed redact reaches one level, so a nested object cannot be+ // masked; a cyclic one would additionally throw on serialize.+ const spy = captureInfo();+ const cyclic: Record<string, unknown> = {};+ cyclic.self = cyclic;+ expect(() =>+ emitDiagnosticBreadcrumb('ok-test-event', { cyclic, nested: { a: 1 }, index: 2 }),+ ).not.toThrow();+ expect(soleParsedCall(spy)).toEqual({+ event: 'ok-test-event',+ index: 2,+ droppedNonScalarFields: 2,+ });+ });++ test('a field named after a pino key is dropped, not left to corrupt the record', () => {+ // pino appends these fields to its own without deduping, so a collision+ // reaches the file as a repeated key that whichever parser reads it next+ // has to arbitrate. Enforced at the boundary because `mark()` forwards the+ // props of marks that do not exist yet.+ const spy = captureInfo();+ emitDiagnosticBreadcrumb('ok-test-event', {+ level: 2,+ time: 1,+ pid: 2,+ hostname: 'h',+ msg: 'no',+ // Base bindings and the desktop logger's own key. `subsystem` is the+ // worst of them: that logger merges as `{ subsystem, ...data }`, so a+ // field of this name wins in plain JS before pino runs and silently+ // re-files the record under another subsystem.+ name: 'nope',+ runtime: 'nope',+ subsystem: 'nope',+ // The server logger's OTel mixin keys, which pino resolves in the merge+ // object's favour — so one of these would re-file the line against a+ // trace that does not contain it.+ trace_id: 'nope',+ span_id: 'nope',+ trace_flags: 'nope',+ headingLevel: 2,+ });+ expect(soleParsedCall(spy)).toEqual({+ event: 'ok-test-event',+ headingLevel: 2,+ droppedReservedFields: 11,+ });+ });++ test('a BigInt costs one field, not the whole line', () => {+ // `JSON.stringify` throws on a BigInt, and a denylist keyed on `typeof+ // 'object'` would let it through to the outer catch — which discards the+ // breadcrumb, event name included. `mark()` forwards props verbatim from+ // marks that do not exist yet, so the value type cannot be assumed.+ const spy = captureInfo();+ expect(() => emitDiagnosticBreadcrumb('ok-test-event', { big: 10n, index: 3 })).not.toThrow();+ expect(soleParsedCall(spy)).toEqual({+ event: 'ok-test-event',+ index: 3,+ droppedNonScalarFields: 1,+ });+ });++ test('a symbol or function is dropped the same way', () => {+ const spy = captureInfo();+ emitDiagnosticBreadcrumb('ok-test-event', {+ sym: Symbol('x'),+ fn: () => undefined,+ index: 1,+ });+ expect(soleParsedCall(spy)).toEqual({+ event: 'ok-test-event',+ index: 1,+ droppedNonScalarFields: 2,+ });+ });++ test('a dropped field is counted, so the gap is visible rather than silent', () => {+ const spy = captureInfo();+ emitDiagnosticBreadcrumb('ok-test-event', { level: 2, nested: { a: 1 }, index: 7 });+ expect(soleParsedCall(spy)).toEqual({+ event: 'ok-test-event',+ index: 7,+ droppedNonScalarFields: 1,+ droppedReservedFields: 1,+ });+ });++ test('null survives — it is a value, not a missing field', () => {+ const spy = captureInfo();+ emitDiagnosticBreadcrumb('ok-test-event', { resolved: null });+ expect(soleParsedCall(spy)).toEqual({ event: 'ok-test-event', resolved: null });+ });++ test('an oversized payload degrades to a parseable line instead of an unparseable one', () => {+ // The Electron capture site truncates BEFORE parsing and the parse is+ // all-or-nothing, so a line over the transport cap arrives there with no+ // event name and no fields at all. Degrade deliberately instead, which also+ // makes the two transports agree on what an oversized payload looks like.+ const spy = captureInfo();+ emitDiagnosticBreadcrumb('ok-test-event', {+ docName: 'x'.repeat(MAX_BREADCRUMB_CHARS),+ index: 4,+ });+ const parsed = soleParsedCall(spy);+ expect(parsed).toEqual({ event: 'ok-test-event', oversized: true, fieldCount: 2 });+ expect(JSON.stringify(parsed).length).toBeLessThan(MAX_BREADCRUMB_CHARS);+ });++ test('the cap keeps the documented headroom under the 8192 transport limit', () => {+ // Pinned against the transport's own constant rather than left to drift:+ // the headroom is what absorbs UTF-16-length-versus-UTF-8-bytes on a+ // multibyte payload, and raising the cap to the transport limit would+ // spend it silently.+ expect(MAX_BREADCRUMB_CHARS).toBeLessThanOrEqual(RENDERER_LOG_MAX_MESSAGE_BYTES / 2);+ });++ test('a payload sized exactly to the cap keeps every field', () => {+ const spy = captureInfo();+ // Exactly at the cap, which the comparison admits — the boundary is where a+ // one-off in either direction shows up, and any lower cap degrades this and+ // fails the assertion.+ const room =+ MAX_BREADCRUMB_CHARS -+ JSON.stringify({ event: 'ok-test-event', docName: '', index: 4 }).length;+ emitDiagnosticBreadcrumb('ok-test-event', { docName: 'x'.repeat(room), index: 4 });+ const parsed = soleParsedCall(spy);+ expect(parsed.index).toBe(4);+ expect(parsed.oversized).toBeUndefined();+ });+});diff --git a/packages/app/src/lib/diagnostic-breadcrumb.ts b/packages/app/src/lib/diagnostic-breadcrumb.tsnew file mode 100644index 000000000..5c4af881c--- /dev/null+++ b/packages/app/src/lib/diagnostic-breadcrumb.ts@@ -0,0 +1,128 @@+/**+ * `emitDiagnosticBreadcrumb(event, fields)` — write one structured renderer+ * event into the on-disk log a diagnostic bundle collects.+ *+ * The renderer runs sandboxed and cannot call pino. Both distributions capture+ * its console instead, and both agree on one wire shape: a single `console.info`+ * whose only argument is `JSON.stringify({ event, ...fields })`.+ *+ * - Electron — main's `console-message` listener+ * (`packages/desktop/src/main/renderer-console-capture.ts`) lifts the parsed+ * object into pino fields and writes `~/.ok/logs/desktop.<date>.log`.+ * - web / `ok ui` — the client-log forwarder+ * (`./install-client-log-forwarder.ts`) batches the same text to+ * `POST /api/client-logs`, which writes the server's `renderer` subsystem log.+ *+ * Either way `fields` land as top-level pino keys and `event` becomes the+ * message, so a breadcrumb is greppable by name and its numbers are queryable+ * without parsing free text. `report-bundle` collects both sinks.+ *+ * **`debug` is the one level that reaches no log file**, dropped twice over:+ * `mapConsoleLevel` maps it to null before pino sees it, and the web forwarder+ * never patches `console.debug` at all. `warn` and `error` do reach disk, but+ * they file routine diagnostics as faults, which is why this helper is fixed at+ * `info`.+ *+ * Field names must avoid pino's own keys, which this drops rather than leaves to+ * convention — see {@link PINO_RESERVED_KEYS}.+ *+ * Fields must be flat scalars, which this enforces rather than trusts. Pino's+ * keyed `redact` reaches one level of nesting, so a nested blob is both+ * unredactable and the shape that pushes a line over the cap below.+ */++import { LOGGER_OWNED_FIELDS } from '@inkeep/open-knowledge-core';++/**+ * Ceiling on a serialized line, at half the 8192-code-unit cap both transports+ * apply to one message. The headroom is for the multibyte case: the cap is a+ * UTF-16 length while the wire budget it protects is bytes.+ *+ * On the Electron path, overshooting does not cost the tail — it costs+ * everything. That capture site truncates BEFORE parsing and the parse is+ * all-or-nothing on `JSON.parse`, so a payload one character over arrives as an+ * unparsed string with no event name and no fields. (The web forwarder parses+ * the untruncated argument and so keeps the event, dropping only oversized+ * fields; the degradation below is what makes the two agree.) Every payload+ * here runs a few hundred bytes, but `docName` has no length bound.+ */+export const MAX_BREADCRUMB_CHARS = 4096;++/**+ * Names the log record's own producer owns. The authority is+ * `LOGGER_OWNED_FIELDS`, which strips them at the chokepoint both capture+ * transports call — that is what makes the rule hold for emitters that never+ * found this helper. IMPORTED rather than restated: a second hand-maintained+ * copy would drift silently, since both copies would keep passing their own+ * tests while one of them stopped matching the loggers.+ *+ * Dropping them here as well is not redundant. It is what lets the count below+ * report the loss, so a caller sees that a field of theirs went missing instead+ * of wondering where it went.+ */+const PINO_RESERVED_KEYS: ReadonlySet<string> = new Set(LOGGER_OWNED_FIELDS);++/**+ * What may be written as a field value.+ *+ * Stated as an allowlist rather than as "not an object", because the values that+ * break serialization are not all objects: a BigInt is a scalar by every other+ * measure and makes `JSON.stringify` throw, and a symbol or function serializes+ * to nothing. Under a denylist those reach the outer catch, which discards the+ * whole breadcrumb — event name included. An allowlist folds them into the+ * counted-drop path instead, so one bad field costs one field.+ */+function isLoggableScalar(value: unknown): value is string | number | boolean | null {+ return (+ value === null ||+ typeof value === 'string' ||+ typeof value === 'number' ||+ typeof value === 'boolean'+ );+}++/**+ * Emit one breadcrumb. Never throws: a diagnostic must not break the path it+ * observes, and every caller sits on a user-facing interaction.+ *+ * A `fields.event` is ignored so a payload cannot rename its own event and hide+ * from a grep.+ */+export function emitDiagnosticBreadcrumb(+ event: string,+ fields?: Readonly<Record<string, unknown>>,+): void {+ try {+ const payload: Record<string, unknown> = { event };+ let droppedNonScalarFields = 0;+ let droppedReservedFields = 0;+ if (fields) {+ for (const [key, value] of Object.entries(fields)) {+ if (key === 'event' || value === undefined) continue;+ if (PINO_RESERVED_KEYS.has(key)) {+ droppedReservedFields += 1;+ continue;+ }+ if (!isLoggableScalar(value)) {+ droppedNonScalarFields += 1;+ continue;+ }+ payload[key] = value;+ }+ }+ // Counted rather than silently swallowed: a dropped field is a gap in the+ // record, and a gap nobody can see reads as "the code did not do that".+ if (droppedNonScalarFields > 0) payload.droppedNonScalarFields = droppedNonScalarFields;+ if (droppedReservedFields > 0) payload.droppedReservedFields = droppedReservedFields;+ const line = JSON.stringify(payload);+ console.info(+ line.length <= MAX_BREADCRUMB_CHARS+ ? line+ : // Report the event and the shape of what was lost. A line that says+ // "this happened, oversized" is still evidence; an unparsed one is not.+ JSON.stringify({ event, oversized: true, fieldCount: Object.keys(payload).length - 1 }),+ );+ } catch {+ // A non-serializable scalar (BigInt) must not take the caller down.+ }+}diff --git a/packages/app/src/lib/install-client-log-forwarder.test.ts b/packages/app/src/lib/install-client-log-forwarder.test.tsindex eb1f807d7..79a520c35 100644--- a/packages/app/src/lib/install-client-log-forwarder.test.ts+++ b/packages/app/src/lib/install-client-log-forwarder.test.ts@@ -149,6 +149,23 @@ describe('installClientLogForwarder', () => {expect(entries[0]?.message).toContain('[REDACTED-GH-PAT]');});+ test('scrubs credentials out of the LIFTED FIELDS too, which no later layer masks', () => {+ // The message and the fields are parsed from different strings, so scrubbing+ // the message alone leaves the fields raw — and the ingest handler spreads+ // them straight into pino, whose keyed redact covers a fixed denylist this+ // key is not on. The scrub-coverage guard cannot catch the gap either: it+ // asks whether the file scrubs anywhere, and it does, on the message path.+ const fetchSpy = makeFetchSpy();+ const { con } = install(fetchSpy);+ const secret = 'ghp_0123456789abcdefghijklmnopqrstuvwxyz';+ con.warn(JSON.stringify({ event: 'ok-pool-recycle-all', detail: `token ${secret}` }));+ handle?.flushNow();+ const { entries } = bodyOf(fetchSpy);+ const fields = entries[0]?.fields as Record<string, unknown>;+ expect(fields?.detail).not.toContain(secret);+ expect(fields?.detail).toContain('[REDACTED-GH-PAT]');+ });+test('keeps the 8192-byte message cap after scrubbing', () => {const fetchSpy = makeFetchSpy();const { con } = install(fetchSpy);diff --git a/packages/app/src/lib/install-client-log-forwarder.ts b/packages/app/src/lib/install-client-log-forwarder.tsindex 414c50bf6..6840a4fe1 100644--- a/packages/app/src/lib/install-client-log-forwarder.ts+++ b/packages/app/src/lib/install-client-log-forwarder.ts@@ -248,6 +248,8 @@ export function installClientLogForwarder(typeof firstArg === 'string' && firstArg.length <= RENDERER_LOG_MAX_BATCH_BYTES? firstArg: undefined;+ // The parser scrubs its own input, so the lifted fields are masked the+ // same way `message` is — this path does not need its own scrub call.const structured = firstString ? parseStructuredConsoleMessage(firstString) : null;// Bound the lifted fields so a single oversized structured entry can't// blow past the batch byte budget (and the keepalive limit). Drop fieldsdiff --git a/packages/app/src/lib/perf/mark-bundled-tracks.test.ts b/packages/app/src/lib/perf/mark-bundled-tracks.test.tsnew file mode 100644index 000000000..1aabfefa1--- /dev/null+++ b/packages/app/src/lib/perf/mark-bundled-tracks.test.ts@@ -0,0 +1,130 @@+/**+ * The route from a perf mark to a diagnostic bundle.+ *+ * `mark`'s two original sinks are both unreachable after the fact —+ * `performance.measure` needs DevTools attached at the time, and the collector+ * ring is compiled out of production. A track on `BUNDLED_TRACKS` additionally+ * writes a renderer breadcrumb, which is the only one of the three that survives+ * into a log file a user can upload.+ */++import { afterEach, describe, expect, test, vi } from 'vitest';+import { getCollector } from './collector';+import { BUNDLED_TRACKS, mark } from './mark';++function captureBreadcrumbs() {+ const spy = vi.spyOn(console, 'info').mockImplementation(() => undefined);+ return {+ parsed(): Array<Record<string, unknown>> {+ return spy.mock.calls.flatMap(([first]) => {+ if (typeof first !== 'string') return [];+ try {+ return [JSON.parse(first) as Record<string, unknown>];+ } catch {+ return [];+ }+ });+ },+ spy,+ };+}++afterEach(() => {+ vi.restoreAllMocks();+ getCollector()?.reset();+});++describe('marks routed into diagnostic bundles', () => {+ test('a scroll-restore mark writes a breadcrumb keyed by the mark name', () => {+ const { parsed } = captureBreadcrumbs();+ mark('ok/scroll-restore/abandoned', {+ docName: 'notes/tall',+ target: 4200,+ scrollTop: 120,+ scrollHeight: 4800,+ clientHeight: 900,+ anchorMeasurable: true,+ });+ // The event IS the mark name, so one string finds the mark in a DevTools+ // trace and the line in a bundle.+ expect(parsed()).toEqual([+ {+ event: 'ok/scroll-restore/abandoned',+ docName: 'notes/tall',+ target: 4200,+ scrollTop: 120,+ scrollHeight: 4800,+ clientHeight: 900,+ anchorMeasurable: true,+ },+ ]);+ });++ test('a mark with no props still reaches the log', () => {+ const { parsed } = captureBreadcrumbs();+ mark('ok/scroll-restore/phase1-success');+ expect(parsed()).toEqual([{ event: 'ok/scroll-restore/phase1-success' }]);+ });++ test('an unlisted track writes no breadcrumb', () => {+ const { spy } = captureBreadcrumbs();+ mark('ok/nav/hash-change', { docName: 'notes/a' });+ mark('ok/sync/resolve', { docName: 'notes/a' });+ expect(spy).not.toHaveBeenCalled();+ });++ test('every mark still reaches the collector, listed or not', () => {+ captureBreadcrumbs();+ mark('ok/scroll-restore/cross-mode', { docName: 'notes/a' });+ mark('ok/nav/hash-change', { docName: 'notes/a' });+ const names = getCollector()+ ?.marks.toArray()+ .map((m) => m.name);+ expect(names).toContain('ok/scroll-restore/cross-mode');+ expect(names).toContain('ok/nav/hash-change');+ });++ test('the allowlist holds exactly the one family that is safe to write per emission', () => {+ // Locked deliberately, not descriptively. A breadcrumb is one log line per+ // emission with no sampling or cap, so a track only belongs here when every+ // mark under it is at-most-once per session. `ok/scroll-restore` is: its+ // five events fire once per restore, guarded by `phase2Marked` /+ // `hasLandedOnce` / a single backstop timer.+ //+ // The tracks one careless edit away are not: `ok/cold` wraps a ProseMirror+ // `decorations` prop, so it emits per transaction — per keystroke — and+ // would age the 45 MB log-directory cap out from under the very session+ // being diagnosed. `ok/vitals` and `ok/cold` also build their names+ // dynamically, so nothing here could enumerate them anyway.+ expect([...BUNDLED_TRACKS]).toEqual(['ok/scroll-restore']);+ });++ test('membership is by whole track, so a lookalike prefix does not opt in', () => {+ const { spy } = captureBreadcrumbs();+ mark('ok/scroll/restore-ish', { docName: 'notes/a' });+ expect(spy).not.toHaveBeenCalled();+ });++ test('the breadcrumb does not depend on the DevTools measure API existing', () => {+ // The breadcrumb is the only sink here that survives to a file a user can+ // send us. Ordering it behind the `performance.measure` guard would rebuild+ // the dependency on DevTools that routing these marks to disk exists to+ // break — and the guard is exactly what a hardened or headless embedder+ // trips.+ const { parsed } = captureBreadcrumbs();+ // `measure` lives on Performance.prototype, so there is no own descriptor to+ // save and restore — shadow it with an own property, then delete that to+ // uncover the prototype's. Restoring by descriptor would silently no-op and+ // leave `performance.measure` undefined for every later test in the file.+ Object.defineProperty(performance, 'measure', { value: undefined, configurable: true });+ try {+ mark('ok/scroll-restore/phase2-success', { docName: 'notes/a', target: 100 });+ } finally {+ Reflect.deleteProperty(performance, 'measure');+ }+ expect(typeof performance.measure).toBe('function');+ expect(parsed()).toEqual([+ { event: 'ok/scroll-restore/phase2-success', docName: 'notes/a', target: 100 },+ ]);+ });+});diff --git a/packages/app/src/lib/perf/mark.ts b/packages/app/src/lib/perf/mark.tsindex b4b7fe1b2..7832dd4ad 100644--- a/packages/app/src/lib/perf/mark.ts+++ b/packages/app/src/lib/perf/mark.ts@@ -12,15 +12,42 @@* `validatePerfMarkName` is a dev-only lint of the shape; it `console.warn`s in* dev and returns silently so emission is always best-effort.*- * Production cost is one `performance.measure` call. The collector push is- * `no-op` in non-DEV builds (see `collector.ts`).+ * Production cost is one `performance.measure` call for most marks; the+ * collector push is `no-op` in non-DEV builds (see `collector.ts`). A mark on a+ * `BUNDLED_TRACKS` track additionally writes one line to the renderer log — see+ * that constant for what a track must satisfy to earn it.*/+import { emitDiagnosticBreadcrumb } from '../diagnostic-breadcrumb';import { recordCounter, recordHistogram, recordMark } from './collector';import type { DevToolsTrackEntry, PerfMarkDetail } from './types';const NAME_RE = /^ok\/[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/;+/**+ * Tracks whose marks are ALSO written to the renderer log, so their numbers+ * survive into a user-uploaded diagnostic bundle.+ *+ * Both of `mark`'s own sinks are unreachable after the fact: a+ * `performance.measure` entry lives in the page's own timeline, readable only+ * from inside that page while it is still alive — this repo's e2e substrate does+ * read them back, but nothing writes them anywhere, so they go with the window —+ * and the collector ring is compiled out of production entirely. A scroll bug+ * therefore reached triage three times running with rich marks defined and not+ * one scroll number anywhere on disk.+ *+ * This is the egress boundary, so keep it deliberate on two axes:+ * - **Sensitivity.** Every prop of an allowlisted mark ships to whoever reads+ * the bundle. Scroll geometry plus a `docName` matches what the pool's+ * `ok-pool-*` breadcrumbs already carry; anything richer wants its own call.+ * - **Volume.** A line per emission, uncapped. Every mark under+ * `ok/scroll-restore` is at-most-once per restore session, which is what+ * makes always-on safe here. A per-frame or per-keystroke mark added to an+ * allowlisted track would flood the log and age the 45 MB dir cap out from+ * under the very session being diagnosed.+ */+export const BUNDLED_TRACKS: ReadonlySet<string> = new Set(['ok/scroll-restore']);+export function validatePerfMarkName(name: string): boolean {return NAME_RE.test(name);}@@ -83,9 +110,18 @@ function markImpl(name: string, props?: Record<string, unknown>, opts?: MarkOpticonsole.warn(`[perf] mark name "${name}" does not match ok/<subsystem>/<event>`);}+ const track = deriveTrack(name);+ // Emitted BEFORE the `performance.measure` guard below. The breadcrumb is the+ // only one of this function's three sinks that survives to a file a user can+ // send us, and gating it on a DevTools tracing API being present would+ // rebuild, one layer down, exactly the dependency this route exists to break.+ //+ // The full mark name is the event, so one string finds the mark in a trace+ // and the line in a bundle.+ if (BUNDLED_TRACKS.has(track)) emitDiagnosticBreadcrumb(name, props);+if (typeof performance === 'undefined' || !performance.measure) return;- const track = deriveTrack(name);const properties = propsToDevToolsTuples(props);const devtools: DevToolsTrackEntry = {dataType: 'track-entry',diff --git a/packages/cli/src/commands/bug-report-bundle.test.ts b/packages/cli/src/commands/bug-report-bundle.test.tsindex 80579f6c3..aeba5250d 100644--- a/packages/cli/src/commands/bug-report-bundle.test.ts+++ b/packages/cli/src/commands/bug-report-bundle.test.ts@@ -888,3 +888,168 @@ describe('defaultBugReportZipPath', () => {expect(okBugReportsDir()).toBe(join(homedir(), '.ok', 'bug-reports'));});});++describe('collectStandardBundle — document names are a Detailed-diagnostics field', () => {+ // One renderer breadcrumb per document activation, in the wire shape both+ // capture transports produce: `docName` lifted to a top-level pino key.+ const scrollLog = [+ '{"level":30,"msg":"ok-outline-nav-dispatch","docName":"notes/salary-negotiation.md","index":3}',+ '{"level":30,"msg":"ok-scroll-restore","docName":"notes/salary-negotiation.md","top":120}',+ '{"level":30,"msg":"ok-outline-nav","docName":"private/board-deck.md","index":0}',+ ].join('\n');++ test('replaces every docName with a digest that still groups one document', async () => {+ const userLogsDir = makeTmpDir();+ writeAt(userLogsDir, 'desktop.2026-08-27.log', `${scrollLog}\n`);+ const outputPath = join(makeTmpDir(), 'report.zip');++ await collectStandardBundle({ redact: true, outputPath, userLogsDir });++ const staged = readZipEntry(outputPath, 'logs/desktop.2026-08-27.log');++ // The names are gone — checked as substrings, so a partial replacement that+ // left a stem behind cannot pass.+ expect(staged).not.toContain('salary-negotiation');+ expect(staged).not.toContain('board-deck');+ expect(staged).not.toContain('notes/');+ expect(staged).not.toContain('private/');++ // Every record still parses and still carries the field, because triage+ // reads these as JSON.+ const records = staged+ .trim()+ .split('\n')+ .map(+ (line) =>+ JSON.parse(line) as { msg: string; docName: string; index?: number; top?: number },+ );+ expect(records).toHaveLength(3);+ expect(records.every((r) => /^doc#[0-9a-f]{12}$/.test(r.docName))).toBe(true);++ // The correlation the outline-click playbook needs survives: two marks on+ // one document share a digest, and a different document gets a different one.+ expect(records[0].docName).toBe(records[1].docName);+ expect(records[0].docName).not.toBe(records[2].docName);++ // Sibling keys are intact — a body that ran past the closing quote would+ // have eaten them.+ expect(records[0].index).toBe(3);+ expect(records[1].top).toBe(120);+ });++ test('holds when the caller turns the secret scrub off — this is a tier rule, not a redaction rule', async () => {+ const userLogsDir = makeTmpDir();+ writeAt(userLogsDir, 'desktop.2026-08-27.log', `${scrollLog}\n`);+ const outputPath = join(makeTmpDir(), 'report.zip');++ await collectStandardBundle({ redact: false, outputPath, userLogsDir });++ const staged = readZipEntry(outputPath, 'logs/desktop.2026-08-27.log');+ expect(staged).not.toContain('salary-negotiation');+ expect(staged).toContain('doc#');+ });++ test('a name carrying an escaped quote is replaced whole, not up to the escape', async () => {+ const userLogsDir = makeTmpDir();+ // `notes/she said "hi".md` as it appears on the wire.+ writeAt(+ userLogsDir,+ 'desktop.2026-08-27.log',+ '{"level":30,"msg":"ok-scroll-restore","docName":"notes/she said \\"hi\\".md","top":9}\n',+ );+ const outputPath = join(makeTmpDir(), 'report.zip');++ await collectStandardBundle({ redact: true, outputPath, userLogsDir });++ const staged = readZipEntry(outputPath, 'logs/desktop.2026-08-27.log');+ expect(staged).not.toContain('she said');+ const record = JSON.parse(staged.trim()) as { docName: string; top: number };+ expect(record.docName).toMatch(/^doc#[0-9a-f]{12}$/);+ expect(record.top).toBe(9);+ });+ test('revealDocNames ships the names as written — the Detailed-diagnostics tier', async () => {+ const userLogsDir = makeTmpDir();+ writeAt(userLogsDir, 'desktop.2026-08-27.log', `${scrollLog}\n`);+ const outputPath = join(makeTmpDir(), 'report.zip');++ await collectStandardBundle({ redact: true, outputPath, userLogsDir, revealDocNames: true });++ const staged = readZipEntry(outputPath, 'logs/desktop.2026-08-27.log');+ expect(staged).toContain('notes/salary-negotiation.md');+ expect(staged).not.toContain('doc#');+ });+ test('masks the same name where it is interpolated into a message body', async () => {+ const userLogsDir = makeTmpDir();+ // The renderer's success-path line, which fires on EVERY document open, next+ // to the breadcrumb that fields the same name. Before the sweep, the field+ // was digested and this line shipped the name in full.+ writeAt(+ userLogsDir,+ 'desktop.2026-08-27.log',+ `${[+ '{"level":30,"msg":"ok-scroll-restore","docName":"notes/salary-negotiation.md","top":1}',+ '{"level":30,"msg":"[syncPromise] notes/salary-negotiation.md resolved synchronously (warm provider)"}',+ ].join('\n')}\n`,+ );+ const outputPath = join(makeTmpDir(), 'report.zip');++ await collectStandardBundle({ redact: true, outputPath, userLogsDir });++ const staged = readZipEntry(outputPath, 'logs/desktop.2026-08-27.log');+ expect(staged).not.toContain('salary-negotiation');+ const records = staged+ .trim()+ .split('\n')+ .map((line) => JSON.parse(line) as { msg: string; docName?: string });+ // Same digest in both shapes, so a triager can still join the message to the+ // breadcrumb that names the document.+ const digest = records[0].docName as string;+ expect(digest).toMatch(/^doc#[0-9a-f]{12}$/);+ expect(records[1].msg).toBe(`[syncPromise] ${digest} resolved synchronously (warm provider)`);+ });++ test('masks documentName, which does not contain the literal docName', async () => {+ const userLogsDir = makeTmpDir();+ writeAt(+ userLogsDir,+ 'desktop.2026-08-27.log',+ '{"level":50,"documentName":"private/board-deck.md","msg":"[persistence] Failed to save private/board-deck.md"}\n',+ );+ const outputPath = join(makeTmpDir(), 'report.zip');++ await collectStandardBundle({ redact: true, outputPath, userLogsDir });++ const staged = readZipEntry(outputPath, 'logs/desktop.2026-08-27.log');+ expect(staged).not.toContain('board-deck');+ const record = JSON.parse(staged.trim()) as { documentName: string; msg: string };+ expect(record.documentName).toMatch(/^doc#[0-9a-f]{12}$/);+ expect(record.msg).toBe(`[persistence] Failed to save ${record.documentName}`);+ });++ test('a name that is a prefix of another does not corrupt the longer one', async () => {+ const userLogsDir = makeTmpDir();+ writeAt(+ userLogsDir,+ 'desktop.2026-08-27.log',+ `${[+ '{"level":30,"docName":"notes/plan","msg":"opened notes/plan"}',+ '{"level":30,"docName":"notes/plan-b","msg":"opened notes/plan-b"}',+ ].join('\n')}\n`,+ );+ const outputPath = join(makeTmpDir(), 'report.zip');++ await collectStandardBundle({ redact: true, outputPath, userLogsDir });++ const staged = readZipEntry(outputPath, 'logs/desktop.2026-08-27.log');+ expect(staged).not.toContain('notes/plan');+ // Longest-first: had the shorter name been swept first, the longer line would+ // read `doc#<short>-b` and leak the suffix.+ expect(staged).not.toContain('-b"');+ const records = staged+ .trim()+ .split('\n')+ .map((line) => JSON.parse(line) as { docName: string; msg: string });+ expect(records[0].docName).not.toBe(records[1].docName);+ expect(records[1].msg).toBe(`opened ${records[1].docName}`);+ });+});diff --git a/packages/cli/src/commands/bug-report-bundle.ts b/packages/cli/src/commands/bug-report-bundle.tsindex 630fd7cb1..3ffd6ecbc 100644--- a/packages/cli/src/commands/bug-report-bundle.ts+++ b/packages/cli/src/commands/bug-report-bundle.ts@@ -79,6 +79,19 @@ export interface CollectStandardBundleOptions {projectDir?: string;/** Apply the secret-pattern scrub to every bundled file. */redact: boolean;+ /**+ * Ship document names as written instead of as digests. Defaults to false,+ * because this collector's tier discloses logs and system info and says+ * nothing about which documents a session opened.+ *+ * Set only for a `full` bundle, whose consent covers them. That level+ * normally uses its own staging path and never reaches here — except when it+ * runs with no `projectDir`, where every full-only artifact is+ * project-scoped and the two levels collapse onto this collector. Passing the+ * level explicitly is what keeps the consented case consented there, rather+ * than leaving it to that coincidence.+ */+ revealDocNames?: boolean;/** Zip destination; parent directories are created as needed. */outputPath: string;/** Override the user-level logs directory (defaults to `~/.ok/logs`). */@@ -419,23 +432,108 @@ function collectLocalSinkLogs(cwd: string): { files: string[] } {return { files: found };}+/**+ * Document names are a Detailed-diagnostics-tier field. This tier's consent+ * copy names "app & system info, recent app logs, and project server logs" and+ * says nothing about the documents a session opened, so this replaces every+ * `docName` / `doc.name` value with a digest before the bytes reach the zip.+ *+ * A digest rather than a fixed marker, following `contentDir` in the manifest,+ * which masks `absolutePath` while keeping `pathSha256` "a stable correlation+ * identifier for the recipient". Triage of the scroll and outline breadcrumbs+ * needs to group a document's marks and read its before/after sequence; it does+ * not need the title. Equal digests mean the same document, here and across+ * bundles.+ *+ * BE PRECISE ABOUT WHAT THIS BUYS, because the tempting sentence is wrong. It is+ * not that the name cannot be recovered. The digest is an unsalted SHA-256 over a+ * short, relative, highly guessable path, truncated to 48 bits, and the party+ * holding it is the one the name is being kept from — so confirming a GUESSED name+ * costs one hash, and a candidate list built once works on every bundle forever.+ * No salt fixes that: one the recipient can see is no obstacle to the recipient,+ * and a secret per-bundle salt would destroy the cross-bundle grouping above. What+ * this delivers is that a bundle no longer HANDS OVER the list — bulk readability+ * is gone, targeted confirmation is not. The stronger property has only one lever,+ * which is not sending the field at this tier at all.+ *+ * NOT gated on `redact`: that flag chooses whether to hunt for secrets in+ * content the user has agreed to send. This is a question of which tier the+ * field belongs to, and the answer does not change when a caller passes+ * `--no-redact`.+ *+ * TWO PASSES, because a document name reaches this tier in more than one shape.+ * The first is key-anchored and authoritative: it finds the field, and its body+ * pattern is the JSON string production — `(?:[^"\\]|\\.)*` consumes an escaped+ * pair whole and so cannot stop on an escaped quote or run past the real+ * terminator. Overshooting would eat the next field; undershooting would ship the+ * tail of the very name this is removing.+ *+ * The second sweeps the names the first pass LEARNED through the rest of the text,+ * because the same name also arrives interpolated into a message body — the+ * renderer's `[syncPromise] <name> resolved...` fires on every successful open,+ * and the server's `[reconcile] delete: <name>` and its siblings reach this tier+ * through `local-logs/`. Both duplicate a name they already pass as a field, which+ * is what makes the sweep sufficient and why fixing it here rather than at ten+ * emit sites loses a triager nothing.+ *+ * Its BOUND, stated rather than hoped: it can only mask a name that appears at+ * least once as a field IN THE SAME FILE. That holds for both sinks today because+ * every one of those call sites passes the name as a field too. A future emitter+ * that interpolates a name it never fields would slip through, and nothing here+ * would notice — which is the argument for eventually dropping the interpolations.+ *+ * Longest-first, so a name that is a prefix of another cannot be rewritten inside+ * it and leave the longer one's tail exposed.+ */+function pseudonymizeDocNames(content: string): { text: string; count: number } {+ let count = 0;+ const digests = new Map<string, string>();+ let text = content.replace(+ /("(?:docName|doc\.name|documentName)"\s*:\s*")((?:[^"\\]|\\.)*)"/g,+ (_match, prefix: string, value: string) => {+ count += 1;+ let digest = digests.get(value);+ if (digest === undefined) {+ digest = `doc#${createHash('sha256').update(value).digest('hex').slice(0, 12)}`;+ digests.set(value, digest);+ }+ return `${prefix}${digest}"`;+ },+ );++ for (const [value, digest] of [...digests].sort(([a], [b]) => b.length - a.length)) {+ // `split`/`join` rather than a built regex: a document name is arbitrary user+ // text and may carry regex metacharacters. An empty value is skipped because+ // splitting on '' would wedge a digest between every character.+ if (value.length === 0 || !text.includes(value)) continue;+ const parts = text.split(value);+ count += parts.length - 1;+ text = parts.join(digest);+ }++ return { text, count };+}+function addTextEntry(args: {zipfile: ZipFile;name: string;content: string;redact: boolean;+ revealDocNames?: boolean;bundleFiles: string[];redactions: BundleRedaction[];}): void {+ // Tier gate first, so it applies on both arms — see `pseudonymizeDocNames`.+ const content = args.revealDocNames ? args.content : pseudonymizeDocNames(args.content).text;if (args.redact) {- const { redacted, patterns, lineCount } = redactContent(args.content);+ const { redacted, patterns, lineCount } = redactContent(content);args.zipfile.addBuffer(Buffer.from(redacted, 'utf8'), args.name);args.bundleFiles.push(args.name);if (patterns.length > 0) {args.redactions.push({ file: args.name, lineCount, patterns });}} else {- args.zipfile.addBuffer(Buffer.from(args.content, 'utf8'), args.name);+ args.zipfile.addBuffer(Buffer.from(content, 'utf8'), args.name);args.bundleFiles.push(args.name);}}@@ -445,6 +543,7 @@ function addContentFiles(args: {files: string[];prefix: string;redact: boolean;+ revealDocNames?: boolean;bundleFiles: string[];redactions: BundleRedaction[];logger?: BundleLogger;@@ -456,6 +555,7 @@ function addContentFiles(args: {name: `${args.prefix}/${basename(file)}`,content: readFileSync(file, 'utf8'),redact: args.redact,+ revealDocNames: args.revealDocNames,bundleFiles: args.bundleFiles,redactions: args.redactions,});@@ -477,6 +577,7 @@ export async function collectStandardBundle(opts: CollectStandardBundleOptions,): Promise<StandardBundleResult> {const { redact, outputPath, logger } = opts;+ const revealDocNames = opts.revealDocNames ?? false;const userLogsDir = opts.userLogsDir ?? join(homedir(), '.ok', 'logs');const projectSlug = opts.projectDir ? resolveProjectSlug(opts.projectDir, logger) : null;@@ -528,6 +629,7 @@ export async function collectStandardBundle(files: [...logFiles, ...shipItFiles],prefix: 'logs',redact,+ revealDocNames,bundleFiles,redactions,logger,@@ -537,6 +639,7 @@ export async function collectStandardBundle(files: lockFiles,prefix: 'lockdir',redact,+ revealDocNames,bundleFiles,redactions,logger,@@ -546,6 +649,7 @@ export async function collectStandardBundle(files: localSinkFiles,prefix: 'local-logs',redact,+ revealDocNames,bundleFiles,redactions,logger,@@ -558,6 +662,7 @@ export async function collectStandardBundle(files: opts.bugReportLedgerFiles ?? [],prefix: REPORT_SIDECAR_BUNDLE_DIR,redact,+ revealDocNames,bundleFiles,redactions,logger,@@ -588,6 +693,7 @@ export async function collectStandardBundle(name: 'note.txt',content: opts.note,redact,+ revealDocNames,bundleFiles,redactions,});diff --git a/packages/cli/src/diagnose/bundle.test.ts b/packages/cli/src/diagnose/bundle.test.tsindex 7f89a4b31..82266f6ef 100644--- a/packages/cli/src/diagnose/bundle.test.ts+++ b/packages/cli/src/diagnose/bundle.test.ts@@ -670,6 +670,44 @@ describe('collectBundle — summary', () => {collected.cleanup();});+ test('docNameCount also counts the renderer-log spelling, in the log files', async () => {+ // The number this feeds is printed to a user deciding whether to share the+ // bundle. Frontend spans are opt-in and off by default, so a scan that saw+ // only the span attribute in only `telemetry/` reported zero over a zip+ // carrying a document path per activation.+ const contentDir = makeTmpDir();+ writeAt(+ contentDir,+ '.ok/local/logs/server-current.jsonl',+ '{"source":"renderer-console","event":"ok-outline-nav","docName":"notes/a"}\n' ++ '{"source":"renderer-console","event":"ok/scroll-restore/abandoned","docName":"notes/b"}\n',+ );+ const collected = await collectBundle({ contentDir, deps: makeDeterministicDeps() });+ expect(collected.summary.docNameCount).toBe(2);+ collected.cleanup();+ });++ test('docNameCount sees the `.log` sink, which is the only one the desktop build writes', async () => {+ // Everything staged under `logs/` is `.log`, and on desktop the web+ // forwarder is switched off — so `desktop.<date>.log` carries every+ // breadcrumb and a `.jsonl`-only scan reports zero over all of them.+ const contentDir = makeTmpDir();+ const userLogsDir = makeTmpDir();+ writeAt(+ userLogsDir,+ 'desktop.2026-08-25.log',+ '{"subsystem":"renderer","event":"ok-outline-nav","docName":"notes/a"}\n' ++ '{"subsystem":"renderer","event":"ok-outline-nav-settled","docName":"notes/a"}\n',+ );+ const collected = await collectBundle({+ contentDir,+ userLogFiles: [join(userLogsDir, 'desktop.2026-08-25.log')],+ deps: makeDeterministicDeps(),+ });+ expect(collected.summary.docNameCount).toBe(2);+ collected.cleanup();+ });+test('contentDirVisible flips true when path appears in any staged file', async () => {const contentDir = makeTmpDir();// A log line referencing the content-dir path verbatim.diff --git a/packages/cli/src/diagnose/bundle.ts b/packages/cli/src/diagnose/bundle.tsindex cd31cda6b..81399c353 100644--- a/packages/cli/src/diagnose/bundle.ts+++ b/packages/cli/src/diagnose/bundle.ts@@ -638,14 +638,25 @@ function countLines(filePath: string): number {return count;}+/**+ * Both spellings a document path is filed under, because the number this feeds+ * is read by a user deciding whether to share the bundle. `doc.name` is the OTel+ * span attribute; `docName` is the renderer-log field, and since frontend OTel+ * is opt-in and off by default, the log spelling is the one most bundles+ * actually carry. Counting only the span attribute reported zero over a zip full+ * of document paths.+ */+const DOC_NAME_MARKERS = ['"doc.name"', '"docName"'] as const;+function countDocNameOccurrences(filePath: string): number {const content = readFileSync(filePath, 'utf-8');- const marker = '"doc.name"';let count = 0;- let idx = content.indexOf(marker);- while (idx !== -1) {- count++;- idx = content.indexOf(marker, idx + marker.length);+ for (const marker of DOC_NAME_MARKERS) {+ let idx = content.indexOf(marker);+ while (idx !== -1) {+ count++;+ idx = content.indexOf(marker, idx + marker.length);+ }}return count;}@@ -955,7 +966,14 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedBconst lines = shouldCountLines(relPath) ? countLines(absPath) : 0;files.push({ path: relPath, bytes, lines });totalBytes += bytes;- if (relPath.startsWith('telemetry/') && shouldCountLines(relPath)) {+ // `logs/` as well as `telemetry/`, and NOT gated on `shouldCountLines`:+ // that predicate admits only `.jsonl`, while everything staged under+ // `logs/` is `.log` — including `desktop.<date>.log`, which on the+ // desktop build is the ONLY sink these breadcrumbs reach, the web+ // forwarder being switched off there. Scoping the scan to spans, or to+ // line-countable files, both leave the consent prompt reporting zero over+ // a bundle carrying a document path per activation.+ if (relPath.startsWith('telemetry/') || relPath.startsWith('logs/')) {docNameCount += countDocNameOccurrences(absPath);}}diff --git a/packages/cli/src/report-bundle.ts b/packages/cli/src/report-bundle.tsindex 743248af9..7d529a7c3 100644--- a/packages/cli/src/report-bundle.ts+++ b/packages/cli/src/report-bundle.ts@@ -187,8 +187,21 @@ async function collectFullBundle(* levels produce the same system-wide bundle.** With `redact` on, the secret-pattern scrub applies at both levels; the full- * level additionally masks the content-dir path. Doc names ship raw under the- * user's explicit Detailed-diagnostics consent.+ * level additionally masks the content-dir path.+ *+ * Doc names ship raw only at `full`, under the user's explicit+ * Detailed-diagnostics consent. At `standard` a name is replaced by a digest+ * before staging, because that level's consent copy names logs and system info+ * and says nothing about which documents a session opened. The digest still+ * groups a document's marks for triage.+ *+ * Scope, precisely, because the mechanism is field-anchored: it digests the+ * `docName` / `doc.name` / `documentName` FIELD, then sweeps the names it+ * learned through the rest of that same file, which is what also covers a name+ * interpolated into a message body. A name that never appears as a field in the+ * file carrying it is not reached. See `pseudonymizeDocNames` for that bound and+ * for what a digest does and does not buy against a recipient who can hash+ * guesses.*/export async function collectReportBundle(opts: CollectReportBundleOptions,@@ -202,6 +215,9 @@ export async function collectReportBundle(const { zipPath, summary } = await collectStandardBundle({projectDir,redact: opts.redact,+ // Reached at `full` only when there is no `projectDir` — see the option's+ // docblock. At `standard` this is the tier gate.+ revealDocNames: opts.level === 'full',outputPath: opts.outputPath,userLogsDir: opts.userLogsDir,shipItLogFiles: collectShipItLogFiles(opts.cachesDir ?? join(homedir(), 'Library', 'Caches')),diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 763aeaa2b..14f14a982 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -79,6 +79,7 @@ export {// and the web renderer forwarder, plus the server `/api/client-logs` ingest// that receives what the forwarder captured.export {+ LOGGER_OWNED_FIELDS,mapConsoleLevel,parseStructuredConsoleMessage,prepareCapturedConsoleMessage,diff --git a/packages/core/src/logging/qa-secret-pattern-canary.test.ts b/packages/core/src/logging/qa-secret-pattern-canary.test.tsindex 2011bcacc..77e57304e 100644--- a/packages/core/src/logging/qa-secret-pattern-canary.test.ts+++ b/packages/core/src/logging/qa-secret-pattern-canary.test.ts@@ -47,8 +47,14 @@ const PLANTED: Record<string, { input: string; secret: string; marker: string }>marker: '[REDACTED-OPENAI]',},'bearer-token': {- input: 'Authorization: Bearer abcdefghijklmnopqrstuvwxyz0123456789',- secret: 'abcdefghijklmnopqrstuvwxyz0123456789',+ // The `:` is what does the work: it sits outside BOTH `[A-Za-z0-9]` and RFC+ // 6750's `b64token` alphabet, so either narrowing ends the match there and+ // ships the rest. The `/` is inside `b64token` and outside `[A-Za-z0-9]`,+ // and being later in the token it is inert against both narrowings named+ // here — it is carried for the narrowing that admits `:` but not `/`. A+ // pure-alphanumeric fixture survives all of them and reports nothing.+ input: 'Authorization: Bearer abcdef:ghijkl/mnopqrstuvwxyz0123456789',+ secret: 'abcdef:ghijkl/mnopqrstuvwxyz0123456789',marker: '[REDACTED',},jwt: {@@ -68,13 +74,13 @@ const PLANTED: Record<string, { input: string; secret: string; marker: string }>marker: '[REDACTED-GH-PAT]',},'openai-key-modern': {- input: 'key=sk-proj-abcdefghijklmnopqrstuvwxyz0123456789ABCD',- secret: 'sk-proj-abcdefghijklmnopqrstuvwxyz0123456789ABCD',+ input: 'key=sk-proj-abcdefghijklmnopqrstuvwxyz0123456789ABCDEF',+ secret: 'sk-proj-abcdefghijklmnopqrstuvwxyz0123456789ABCDEF',marker: '[REDACTED-OPENAI]',},'slack-token': {- input: 'slack xoxb-24209812345-67890abcdefXYZ token',- secret: 'xoxb-24209812345-67890abcdefXYZ',+ input: 'slack xoxb-24209812345-67890abcdefXYZABC token',+ secret: 'xoxb-24209812345-67890abcdefXYZABC',marker: '[REDACTED-SLACK]',},'google-api-key': {@@ -88,24 +94,56 @@ const PLANTED: Record<string, { input: string; secret: string; marker: string }>marker: '[REDACTED-STRIPE]',},'gitlab-pat': {- input: 'gitlab glpat-abcdefghij0123456789XYZ done',- secret: 'glpat-abcdefghij0123456789XYZ',+ input: 'gitlab glpat-abcdefghij0123456789XYZABC done',+ secret: 'glpat-abcdefghij0123456789XYZABC',marker: '[REDACTED-GITLAB]',},'bearer-token-json': {- input: '{"authorization":"Bearer opaqueBearerToken1234567890abcXYZ","k":1}',- secret: 'opaqueBearerToken1234567890abcXYZ',+ input: '{"authorization":"Bearer opaque:Tokenv1/1234567890abcXYZ","k":1}',+ secret: 'opaque:Tokenv1/1234567890abcXYZ',marker: '[REDACTED',},};+// Long enough that no fixture's surviving context collides with a window by+// accident, short enough to catch the tail a mid-run narrowing ships.+//+// This is an OBLIGATION ON EACH FIXTURE, not a property of the loop: it catches+// any surviving run of six or more, so a fixture must keep its+// class-distinguishing characters at least this far from its end. Park them+// closer and a narrowing that still clears the pattern's quantifier floor ships+// a tail too short for any window, and every assertion here stays green — the+// head is gone, so `not.toContain(secret)` passes, and the pattern still fired,+// so the attribution check passes too.+//+// Raising this value is the same trap from the other side, which is why the+// completeness check below pins it against the fixture set rather than leaving+// it free.+const FRAGMENT_WINDOW = 6;++/** A fixture already in serialized form, which the wrapping loop skips. */+const isSerializedPayload = (value: string): boolean => value.trimStart().startsWith('{');+describe('secret-pattern canary', () => {it('plants a canary for every named pattern (adding a pattern without one fails here)', () => {expect([...SECRET_PATTERN_NAMES].sort()).toEqual(Object.keys(PLANTED).sort());});+ it('keeps every planted secret long enough for the fragment loop to run on it', () => {+ // Pins `FRAGMENT_WINDOW` upward. A lower value fails loudly (windows start+ // colliding with surrounding context), but a higher one fails SILENTLY: a+ // secret shorter than the window yields no windows at all, so the fixture+ // drops out of the fragment check while its test stays green. Raising the+ // window to 8, 13 or 26 each drops a different slice of the set.+ const tooShort = Object.entries(PLANTED)+ .filter(([, { secret }]) => secret.length < FRAGMENT_WINDOW)+ .map(([name]) => name);+ expect(tooShort).toEqual([]);+ });+for (const [name, { input, secret, marker }] of Object.entries(PLANTED)) {- it(`scrubs a planted ${name}`, () => {+ const survivalSuffix = isSerializedPayload(input) ? ' without breaking the record' : '';+ it(`scrubs a planted ${name}${survivalSuffix}`, () => {// Planted-positive control: the raw token really is present pre-scrub, so// a canary that silently stopped containing its own secret can't pass.expect(input).toContain(secret);@@ -114,11 +152,59 @@ describe('secret-pattern canary', () => {expect(scrubbed).not.toContain(secret);expect(scrubbed).toContain(marker);+ // No 6-character run of the token survives either. `not.toContain(secret)`+ // alone passes on a partial redaction — a narrowed character class stops+ // at the first character outside it, ships the tail, and still reports the+ // pattern as having fired, which is worse than a clean miss. Slid rather+ // than split on non-alphanumerics: a narrowing that stops PART WAY through+ // a run leaves a tail that every whole-run check still passes, and the+ // home-path secrets have no alphanumeric run this long to split out at all.+ for (let i = 0; i + FRAGMENT_WINDOW <= secret.length; i++) {+ expect(scrubbed).not.toContain(secret.slice(i, i + FRAGMENT_WINDOW));+ }++ // A fixture that is ALREADY a serialized payload never reaches the wrapping+ // loop below, so it gets the record-survives property here instead. Without+ // this, `bearer-token-json` — the one pattern named for JSON — is the only+ // planted secret `JSON.parse` is never called on anywhere in this file.+ if (isSerializedPayload(input)) {+ expect(Object.keys(JSON.parse(scrubbed))).toEqual(Object.keys(JSON.parse(input)));+ }+// The line-wise redactor must attribute the hit to this pattern by name.expect(redactSecrets(input).patterns).toContain(name);});}+ for (const [name, { input, secret }] of Object.entries(PLANTED)) {+ // A fixture that is already a serialized payload gets its parse assertion in+ // the loop above instead. Wrapping it again would model a JSON document+ // nested inside a JSON string value, where the inner quotes arrive escaped+ // and no key-anchored pattern can see them — a real but separate limitation,+ // and not what this loop is for.+ if (isSerializedPayload(input)) continue;++ it(`scrubs a planted ${name} inside serialized JSON without breaking the record`, () => {+ // The renderer-log chokepoint scrubs a serialized console payload BEFORE+ // parsing it, so every pattern runs against JSON as well as free text.+ // Both halves matter and neither is implied by the free-text case above:+ // the secret must go, AND the surrounding record must survive — a body+ // that can cross a `"` runs out of the value it matched and either+ // deletes the next field or leaves nothing parseable at all.+ const payload = JSON.stringify({ event: 'ok-canary', detail: input, docName: 'notes/a' });+ // Planted-positive control, as in the loop above and for a sharper reason+ // here: `JSON.stringify` ESCAPES a `\"` or `\\`, so a future fixture+ // carrying either survives serialization in a form the raw secret no+ // longer matches. Both assertions below would then pass without the scrub+ // having done anything. Every fixture is escape-free ASCII today, which is+ // exactly why nothing would notice when one stops being.+ expect(payload).toContain(secret);+ const scrubbed = scrubSecrets(payload);+ expect(scrubbed).not.toContain(secret);+ expect(Object.keys(JSON.parse(scrubbed))).toEqual(['event', 'detail', 'docName']);+ });+ }+it('scrubs every planted secret when they arrive together in one blob', () => {const blob = Object.values(PLANTED).map((p) => p.input)diff --git a/packages/core/src/logging/renderer-log.test.ts b/packages/core/src/logging/renderer-log.test.tsindex c3cc139af..9a0482857 100644--- a/packages/core/src/logging/renderer-log.test.ts+++ b/packages/core/src/logging/renderer-log.test.ts@@ -52,6 +52,120 @@ describe('parseStructuredConsoleMessage', () => {expect(parseStructuredConsoleMessage('')).toBeNull();expect(parseStructuredConsoleMessage('{not json')).toBeNull();});++ test('strips the fields the log record producer owns', () => {+ // Both capture sites spread these into the object pino serializes. pino+ // writes `level`/`time` and its base bindings BEFORE that merge and `msg`+ // after it, so either way a collision reaches the file as a repeated key,+ // and the bundle redactor round-trips every line through `JSON.parse`,+ // which is last-key-wins. `subsystem` never even gets that far: the desktop+ // logger merges as `{ subsystem, ...data }`, so a renderer field of that+ // name wins outright and re-files the record under a subsystem nobody wrote.+ const out = parseStructuredConsoleMessage(+ JSON.stringify({+ event: 'ok-outline-nav',+ level: 2,+ time: 1,+ pid: 3,+ hostname: 'h',+ msg: 'hijack',+ name: 'nope',+ runtime: 'nope',+ subsystem: 'nope',+ // The OTel mixin's keys. Pino resolves a mixin key in the merge+ // object's favour, so a breadcrumb of this name wins outright and+ // re-files the line against a trace that does not contain it.+ trace_id: 'nope',+ span_id: 'nope',+ trace_flags: 'nope',+ docName: 'notes/a',+ index: 4,+ }),+ );+ expect(out?.event).toBe('ok-outline-nav');+ expect(out?.fields).toEqual({ event: 'ok-outline-nav', docName: 'notes/a', index: 4 });+ });++ test('masks the JSON wire form of an authorization header, key and value apart', () => {+ // The pattern for this shape anchors on the delimiters, so it can only fire+ // while the payload is still serialized. Parsing first separates the key+ // from the value and leaves nothing for either bearer pattern to match.+ const out = parseStructuredConsoleMessage(+ JSON.stringify({ event: 'ok-provider-auth-failed', authorization: 'Bearer s3cret' }),+ );+ expect(out?.event).toBe('ok-provider-auth-failed');+ expect(JSON.stringify(out?.fields)).not.toContain('s3cret');+ });++ test('the event name is masked too, being what both sinks use as the message', () => {+ const out = parseStructuredConsoleMessage(+ JSON.stringify({ event: 'ghp_0123456789abcdefghijklmnopqrstuvwxyz' }),+ );+ expect(out?.event).not.toContain('ghp_0123456789');+ });++ test('scrubs strings nested inside objects and arrays, not just top-level ones', () => {+ // Pino's keyed redact reaches one level, so nothing downstream masks a+ // credential any deeper than that either.+ const secret = 'ghp_0123456789abcdefghijklmnopqrstuvwxyz';+ const out = parseStructuredConsoleMessage(+ JSON.stringify({+ event: 'ok-pool-recycle-all',+ nested: { inner: `token ${secret}` },+ list: [`token ${secret}`],+ }),+ );+ expect(JSON.stringify(out?.fields)).not.toContain(secret);+ expect(JSON.stringify(out?.fields)).toContain('[REDACTED-GH-PAT]');+ // Structure preserved, not flattened or dropped.+ expect((out?.fields.nested as Record<string, unknown>).inner).toBeTypeOf('string');+ expect(Array.isArray(out?.fields.list)).toBe(true);+ });++ test('scrubs each string leaf, so a credential in a field is masked', () => {+ const out = parseStructuredConsoleMessage(+ JSON.stringify({+ event: 'ok-provider-token-refresh',+ token: 'ghp_0123456789abcdefghijklmnopqrstuvwxyz',+ index: 4,+ }),+ );+ expect(out?.fields.token).not.toContain('ghp_0123456789');+ expect(out?.fields.token).toContain('[REDACTED-GH-PAT]');+ expect(out?.fields.index).toBe(4);+ });++ test('scrubbing per leaf keeps a payload that a whole-line scrub would destroy', () => {+ // `scrubSecrets` is a line-level regex pass and its bearer pattern ends at+ // whitespace, which `JSON.stringify` output does not contain — so applied to+ // the whole line it would run to the end and leave nothing parseable, losing+ // the event and every field. Applied per value it masks and stops.+ const out = parseStructuredConsoleMessage(+ JSON.stringify({+ event: 'ok-pool-recycle-all',+ detail: 'authorization: Bearer abc123',+ docName: 'notes/a',+ }),+ );+ expect(out?.event).toBe('ok-pool-recycle-all');+ expect(out?.fields.docName).toBe('notes/a');+ expect(out?.fields.detail).not.toContain('abc123');+ });++ test('the strip does not disturb the provenance markers the capture sites set', () => {+ // Those are already defended by spread order at both sites; stripping them+ // here would break the capture-time overwrite rather than protect anything.+ const out = parseStructuredConsoleMessage(+ JSON.stringify({ source: 's', transport: 't', sourceId: 'i', lineNumber: 1, clientTs: 2 }),+ );+ expect(out?.fields).toEqual({+ source: 's',+ transport: 't',+ sourceId: 'i',+ lineNumber: 1,+ clientTs: 2,+ });+ });});describe('truncateLogMessage', () => {diff --git a/packages/core/src/logging/renderer-log.ts b/packages/core/src/logging/renderer-log.tsindex b345dd186..2b88e71e2 100644--- a/packages/core/src/logging/renderer-log.ts+++ b/packages/core/src/logging/renderer-log.ts@@ -66,21 +66,90 @@ export function mapConsoleLevel(level: string): RendererLogLevel | null {}}+/**+ * Field names the log record's own producer owns, stripped from a renderer+ * payload before it is lifted.+ *+ * Both capture sites already spread renderer fields first so their provenance+ * markers win. These are the names that defence cannot reach, because they are+ * not added by the capture site at all:+ * - `level`, `time`, `pid`, `hostname`, `name`, `runtime` — pino writes the+ * first two at serialize time and the rest as child bindings, all BEFORE+ * the merge object. A collision reaches the file as a repeated key,+ * harmless until something parses the line — and the bundle redactor+ * round-trips every line through `JSON.parse`, which is last-key-wins, so+ * the renderer's value silently becomes the permanent one. pino orders it+ * this way deliberately, so that a logged object can take precedence.+ * - `msg` — the mirror image, and the reason this list is not simply "pino's+ * keys": pino appends it LAST, so last-key-wins keeps pino's message and+ * the renderer's field is the one that vanishes. Stripped anyway, because a+ * duplicate key that never wins is still a duplicate key, and a first-wins+ * parser reading the same file would resolve it the other way.+ * - `subsystem` — worse. The desktop logger merges as `{ subsystem, ...data }`,+ * so a renderer field of that name wins in plain JS before pino runs: no+ * duplicate key at all, just a record silently re-filed under another+ * subsystem, which is the field triage greps on first.+ *+ * Stripped HERE, at the one chokepoint both transports call, rather than at each+ * emitter: a producer-side denylist has to be kept in sync by hand with two+ * logger configs it cannot see, and nothing would fail when one of them adds a+ * binding. Emitters may still filter for a clearer local contract, but this is+ * what makes the guarantee hold for a bare `console.info(JSON.stringify(...))`+ * written by someone who never finds the helper.+ *+ * Sources of truth for the list: `packages/desktop/src/main/desktop-logger.ts`+ * and `packages/server/src/logger.ts`.+ */+export const LOGGER_OWNED_FIELDS = [+ 'level',+ 'time',+ 'pid',+ 'hostname',+ 'msg',+ 'name',+ 'runtime',+ 'subsystem',+ // The server logger's OTel mixin. Pino resolves a mixin key in the merge+ // object's favour, so these behave like `subsystem` rather than like `level`:+ // the renderer's value wins outright. Their whole job is to let a triager+ // jump from a log line to the trace that produced it, so a breadcrumb+ // carrying one would re-file the line against a trace that does not contain+ // it — a wrong pointer, which is worse than a missing one.+ 'trace_id',+ 'span_id',+ 'trace_flags',+] as const;+/*** Best-effort unwrap of a structured console message. The renderer emits many* events as `console.warn(JSON.stringify({ event, ...fields }))` (e.g.* provider-pool's `ok-provider-*` events). Lifting those into pino object* fields makes them greppable and lets pino's path-based `redact` mask the- * denylisted keys it covers (top-level + one level of nesting). Call this on a- * message already run through {@link prepareCapturedConsoleMessage}: pino's- * keyed `redact` only masks the fixed denylist at depth <= 1, so a credential- * in any other field (or in a plain non-JSON string) is only removed by the- * capture-time scrub. Returns `null` when the message is not a JSON object.+ * denylisted keys it covers (top-level + one level of nesting).+ *+ * Scrubs its own input, so a caller may pass the raw message. Truncate first if+ * the payload needs bounding; scrubbing twice is a no-op, every replacement+ * token being a fixed point.+ *+ * Returns `null` when the message is not a JSON object.*/export function parseStructuredConsoleMessage(message: string,): { event: string | undefined; fields: Record<string, unknown> } | null {- const trimmed = message.trim();+ // Scrubbed over the SERIALIZED text, before the parse. That reaches strings at+ // every depth and object keys as well, and it is the only point at which the+ // patterns anchored on the JSON wire form can fire: `"authorization":"Bearer …"`+ // is recognizable only while the delimiters are still there, and once parsed+ // the key and the value are separate objects no pattern can relate.+ //+ // This order is safe on one condition, which `secret-scrub.ts` has to keep: NO+ // PATTERN BODY MAY CROSS A `"`. Every structural delimiter in+ // `JSON.stringify` output is separated from string content by a quote, so a+ // body that cannot cross one cannot leave the value it matched in. A body that+ // can is not a leaked credential but a mangled record — either a field+ // silently deleted from a line that still parses, or nothing parseable at all,+ // costing the event name and every field.+ const trimmed = scrubSecrets(message).trim();if (trimmed.length === 0 || trimmed[0] !== '{') return null;let parsed: unknown;try {@@ -90,6 +159,7 @@ export function parseStructuredConsoleMessage(}if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;const fields = parsed as Record<string, unknown>;+ for (const key of LOGGER_OWNED_FIELDS) delete fields[key];return { event: typeof fields.event === 'string' ? fields.event : undefined, fields };}diff --git a/packages/core/src/logging/secret-scrub.test.ts b/packages/core/src/logging/secret-scrub.test.tsindex 80d631cae..34a8f2295 100644--- a/packages/core/src/logging/secret-scrub.test.ts+++ b/packages/core/src/logging/secret-scrub.test.ts@@ -1,6 +1,130 @@import { describe, expect, it } from 'vitest';import { redactSecrets, SECRET_PATTERN_NAMES, scrubSecrets } from './secret-scrub.ts';+describe('scrubbing a serialized JSON payload', () => {+ // The renderer-log chokepoint scrubs a serialized console payload BEFORE+ // parsing it, which is the only order in which the patterns anchored on the+ // JSON wire form can fire. That order rests on one property of this list, so+ // the property is asserted here rather than left to each pattern's author: a+ // body that can cross a `"` runs out of the value it matched, and the cost is+ // a mangled record — a field silently deleted from a line that still parses,+ // or a line that no longer parses at all.+ it('every replacement leaves the payload parseable with its other fields intact', () => {+ const payloads: Record<string, unknown>[] = [+ { event: 'ok-fs-error', reason: 'EACCES on /Users/alice', docName: 'notes/a' },+ { home: '/Users/bob', db: 'postgres://u:p@h/x' },+ { event: 'ok-x', detail: 'authorization: Bearer abc123', docName: 'notes/b' },+ { event: 'ok-x', authorization: 'Bearer abc123', docName: 'notes/c' },+ { a: '/home/alice', b: { c: 'x/y' } },+ { token: 'ghp_0123456789abcdefghijklmnopqrstuvwxyz', docName: 'notes/d' },+ ];+ for (const payload of payloads) {+ const parsed = JSON.parse(scrubSecrets(JSON.stringify(payload))) as Record<string, unknown>;+ expect(Object.keys(parsed)).toEqual(Object.keys(payload));+ }+ });++ it('masks a bearer token however it is quoted, without breaking the line', () => {+ // A class that excludes the quote cannot START on one, so a quoted token was+ // not matched at all; and against an escaped quote it took the backslash,+ // producing a line that neither parsed nor redacted. Both shapes reach this+ // through arbitrary renderer console JSON.+ const shapes = [+ 'Authorization: Bearer abc123',+ 'Authorization: Bearer "abc123"',+ JSON.stringify({ detail: 'authorization: Bearer "abc123"', d: 1 }),+ JSON.stringify({ detail: 'authorization: Bearer abc123', d: 1 }),+ JSON.stringify({ authorization: 'Bearer "abc123"', d: 1 }),+ ];+ for (const shape of shapes) {+ const scrubbed = scrubSecrets(shape);+ expect(scrubbed).not.toContain('abc123');+ if (shape.startsWith('{')) expect(() => JSON.parse(scrubbed)).not.toThrow();+ }+ });++ it('masks a home directory whose account name contains a space or a backslash', () => {+ // Both are legal in an account name, and these are the file's only privacy+ // patterns — excluding either from the body stops the name being masked.+ expect(scrubSecrets('/Users/Jane Doe/notes/plan.md')).not.toContain('Jane Doe');+ expect(scrubSecrets('/Users/al\\ice/x')).not.toContain('al\\ice');+ expect(scrubSecrets('/home/Jane Doe/notes')).not.toContain('Jane Doe');+ });++ it('redacts a bearer token whole when it carries a character outside token68', () => {+ // A body spelling out what a token may BE ends at the first character+ // outside that set, so the tail ships — while the audit still records the+ // pattern as having fired over that line. A fragment reported as redacted+ // is worse than a clean miss. Opaque vendor tokens and URL-encoded copies+ // are the exposed class; JWTs and the prefixed vendor formats are not.+ for (const token of ['abc:123', 'ab%2Fcd', 'a=b/c+d']) {+ expect(scrubSecrets(`Authorization: Bearer ${token}`)).toBe(+ 'Authorization: Bearer [REDACTED]',+ );+ const json = JSON.stringify({ authorization: `Bearer ${token}`, d: 1 });+ const scrubbed = scrubSecrets(json);+ expect(scrubbed).not.toContain(token);+ expect(Object.keys(JSON.parse(scrubbed))).toEqual(['authorization', 'd']);+ }+ });++ it('an escaped-quoted bearer value is redacted and still leaves the line parseable', () => {+ // The lone backslash of an escaped quote used to be taken as the token's+ // first character, producing a line that neither parsed nor redacted.+ const json = JSON.stringify({ authorization: 'Bearer "abc:123"', d: 1 });+ const scrubbed = scrubSecrets(json);+ expect(scrubbed).not.toContain('abc:123');+ expect(Object.keys(JSON.parse(scrubbed))).toEqual(['authorization', 'd']);+ });++ it('a bearer prefix at the end of a value does not run into the next key', () => {+ // The quoted branch's opening `"` can bind a value's CLOSING delimiter. With+ // a permissive body it would then consume the comma and swallow the key+ // after it, which is why that one branch stays narrow.+ const json = JSON.stringify({ detail: 'authorization: Bearer ', d: 1 });+ expect(Object.keys(JSON.parse(scrubSecrets(json)))).toEqual(['detail', 'd']);+ });++ it('a bearer value containing a quote keeps the record parseable', () => {+ // The bare branch must not contain a backslash ANYWHERE, not merely start+ // on one: taking the `\` of a `\"` escape leaves the value's closing quote+ // exposed and the line stops parsing. The shape to worry about in a real+ // log is a quoted header inside a value, which this now handles whole.+ const curl = JSON.stringify({ cmd: 'curl -H "authorization: Bearer TOK" https://x' });+ const scrubbedCurl = scrubSecrets(curl);+ expect(scrubbedCurl).not.toContain('TOK');+ expect(Object.keys(JSON.parse(scrubbedCurl))).toEqual(['cmd']);++ // A token carrying a quote or a backslash of its own is not a real+ // credential shape — `b64token` excludes both — and bounding on them is+ // what buys parse safety everywhere else. So the tail after one survives,+ // which is accepted: the record stays intact and readable, where an+ // unbounded body destroyed it.+ for (const value of ['Bearer abc"def', 'Bearer abc\\def']) {+ const scrubbed = scrubSecrets(JSON.stringify({ authorization: value, d: 1 }));+ expect(scrubbed).not.toContain('abc');+ expect(Object.keys(JSON.parse(scrubbed))).toEqual(['authorization', 'd']);+ }+ });++ it('stopping at a backslash is the right boundary when it begins an escape', () => {+ // The same bound that costs a tail on a malformed token is correct here:+ // the escape starts content that is not the token, so the match ends where+ // the token does.+ const scrubbed = scrubSecrets(JSON.stringify({ detail: 'authorization: Bearer TOK\nafter' }));+ expect(scrubbed).not.toContain('TOK');+ expect(JSON.parse(scrubbed).detail).toContain('after');+ });++ it('a home-path collapse cannot consume the URL a credential pattern anchors on', () => {+ // The cosmetic path patterns run last for this reason: greedy, an unbounded+ // home-path body reached across the `://` and left the URL-credential+ // pattern nothing to match, shipping the credential verbatim.+ const scrubbed = scrubSecrets(JSON.stringify({ home: '/Users/bob', db: 'postgres://u:p@h/x' }));+ expect(scrubbed).not.toContain('u:p@h');+ });+});+describe('scrubSecrets', () => {it('leaves credential-free text unchanged', () => {const clean = 'bridge drain settled: 3 docs converged';diff --git a/packages/core/src/logging/secret-scrub.ts b/packages/core/src/logging/secret-scrub.tsindex 16b9210d1..8416a3753 100644--- a/packages/core/src/logging/secret-scrub.ts+++ b/packages/core/src/logging/secret-scrub.ts@@ -26,8 +26,6 @@ interface SecretPattern {}const SECRET_PATTERNS: readonly SecretPattern[] = [- { name: 'macos-home-path', regex: /\/Users\/[^/]+\//g, replacement: '~/' },- { name: 'linux-home-path', regex: /\/home\/[^/]+\//g, replacement: '~/' },{name: 'github-pat',regex: /\b(ghp_|gho_|ghu_|ghs_|ghr_)[A-Za-z0-9]{36,}\b/g,@@ -46,7 +44,32 @@ const SECRET_PATTERNS: readonly SecretPattern[] = [{ name: 'openai-key', regex: /\bsk-[A-Za-z0-9]{20,}\b/g, replacement: '[REDACTED-OPENAI]' },{name: 'bearer-token',- regex: /([Aa]uthorization:\s*[Bb]earer\s+)\S+/g,+ // Three alternatives, ordered, so the token's own quoting is matched as part+ // of the token: escaped-quoted, quoted, bare. What a bare token may not+ // contain is the bound — NOT a spelling of what it may be. RFC 6750's+ // `b64token` looked like the safer statement and is not: the first character+ // outside it ends the match, so `Bearer abc:123` redacted `abc` and shipped+ // `:123`, with the audit still naming the pattern as having fired. A+ // surviving fragment recorded as redacted is worse than a clean miss —+ // where the character ending the match is one a real credential can hold.+ //+ // Two constraints on the shape. The bare branch must not contain a+ // backslash ANYWHERE — not merely start on one. Taking the `\` of a `\"`+ // escape leaves the value's closing quote exposed, which breaks the line+ // whether the backslash was the first character or the fourth.+ //+ // That bound has the same shape as the cost above and is accepted on the+ // narrower ground: a value carrying a backslash truncates there, tail+ // shipped and pattern still named. `b64token` excludes the backslash, so no+ // conformant bearer credential contains one — unlike `:` or `%`, which real+ // composite and URL-encoded tokens do. And in serialized JSON the backslash+ // is usually the start of an escape, where stopping IS the right boundary:+ // `Bearer TOK\nnext line` truncates at the newline that ends the token.+ // And the QUOTED branch keeps the narrow class deliberately: its opening `"`+ // can bind a value's closing delimiter, and with a permissive body it would+ // then run through the comma into the next key.+ regex:+ /([Aa]uthorization:\s*[Bb]earer\s+)(?:\\"[^\s"\\]+\\"|"[A-Za-z0-9\-._~+/=]+"|[^\s"\\]+)/g,replacement: '$1[REDACTED]',},// JWTs (header.payload.signature; header + payload are base64url of `{`) and@@ -61,7 +84,11 @@ const SECRET_PATTERNS: readonly SecretPattern[] = [},{name: 'url-credentials',- regex: /:\/\/[^/\s:@]+:[^/\s:@]+@/g,+ // The classes also exclude `"`, so the match cannot run across a JSON+ // delimiter and swallow the key after it. ONLY the quote is added: RFC 3986+ // permits sub-delims such as `,` in userinfo, and excluding those would+ // narrow what this recognises on a security path.+ regex: /:\/\/[^/\s:@"]+:[^/\s:@"]+@/g,replacement: '://[REDACTED]@',},// Current-default provider formats the classic prefixes above miss: GitHub@@ -91,10 +118,39 @@ const SECRET_PATTERNS: readonly SecretPattern[] = [{name: 'bearer-token-json',// JSON-serialized wire form: `"authorization":"Bearer <opaque>"`, which the- // colon-anchored `bearer-token` pattern above cannot see.- regex: /("[Aa]uthorization"\s*:\s*"[Bb]earer\s+)[^"]+/g,+ // colon-anchored `bearer-token` pattern above cannot see. Same quote-and-+ // backslash bound as that one, and for the same reason — an unescaped quote+ // inside a JSON string value can only be that value's own terminator, but a+ // backslash can still be the escape that precedes one, and a body admitting+ // it closes the string early.+ //+ // TWO deliberate divergences from the sibling, neither of which TypeScript+ // can catch when one side is edited alone. This body does NOT exclude `\s`:+ // it already sits inside a quoted value, where whitespace is token material+ // rather than the terminator it is in free text. And there are two branches+ // rather than three — no plain-quoted branch, because an opening quote can+ // never appear mid-value, so that branch could not fire.+ regex: /("[Aa]uthorization"\s*:\s*"[Bb]earer\s+)(?:\\"[^"\\]+\\"|[^"\\]+)/g,replacement: '$1[REDACTED]',},+ // Cosmetic, and LAST on purpose. These collapse a home directory to `~/`,+ // which is lossy in a way a credential pattern is not: the match consumes the+ // segment it replaces. Run ahead of the credential patterns, they could eat+ // text one of those still needs to recognise its own match — a `/Users/<name>/`+ // run reaching across a `://` leaves no `://` for the URL-credential pattern to+ // anchor on, and the credential then ships verbatim.+ //+ // The bodies exclude the quote and NOTHING else. A space or a backslash is a+ // legal part of an account name — `/Users/Jane Doe/` is the macOS shape this+ // repo's own fixtures use — and excluding either silently stopped those from+ // being masked at all, which on the file's only two privacy patterns is the+ // wrong direction to be wrong in.+ //+ // A home path at the very end of a JSON string value is left alone, having no+ // trailing slash inside its own value to match: reaching it would mean running+ // through the closing quote, which is what deleted the following field.+ { name: 'macos-home-path', regex: /\/Users\/[^/"]+\//g, replacement: '~/' },+ { name: 'linux-home-path', regex: /\/home\/[^/"]+\//g, replacement: '~/' },];/** Names of the redaction patterns, for a bundle's privacy summary. */diff --git a/packages/desktop/src/main/renderer-console-capture.test.ts b/packages/desktop/src/main/renderer-console-capture.test.tsindex 2780cdb6c..58cf8a4cb 100644--- a/packages/desktop/src/main/renderer-console-capture.test.ts+++ b/packages/desktop/src/main/renderer-console-capture.test.ts@@ -170,6 +170,32 @@ describe('attachRendererConsoleCapture', () => {expect(JSON.stringify(call.data)).not.toContain(secret);});+ test('a bearer credential is masked without taking the record with it', () => {+ // The pattern class the AWS-key case above cannot reach. `bearer-token`+ // ends at whitespace and serialized JSON has none, so a scrub applied to+ // the line before parsing runs to its end and `JSON.parse` then throws —+ // costing the event name and every field. Parsing first and masking the+ // values keeps both the record and the redaction.+ const wc = makeFakeWebContents();+ const spy = makeSpyLogger();+ attachRendererConsoleCapture(wc, { getLogger: spy.getLogger });++ wc.emit({+ level: 'warning',+ message: JSON.stringify({+ event: 'ok-provider-auth-failed',+ detail: 'authorization: Bearer abc123secret',+ docName: 'notes/plan',+ }),+ });++ const call = spy.calls[0];+ if (!call) throw new Error('expected exactly one log call');+ expect(call.msg).toBe('ok-provider-auth-failed');+ expect(call.data.docName).toBe('notes/plan');+ expect(JSON.stringify(call.data)).not.toContain('abc123secret');+ });+test('scrubs before truncating so a secret straddling the cap cannot survive', () => {const wc = makeFakeWebContents();const spy = makeSpyLogger();