@crouton-kit/capture 1.4.1 → 1.4.10

package/src/har-manager.ts

@@ -391,9 +391,6 @@ function vClocks(v: unknown, source: string, path: string): CaptureClocks {
     if (responseMonotonic < requestMonotonic) {
       fail(source, `${path}.responseMonotonic`, 'must be >= requestMonotonic');
     }
-    if (responseMonotonic > terminalMonotonic) {
-      fail(source, `${path}.responseMonotonic`, 'must be <= terminalMonotonic');
-    }
   }
   return {
     requestWallTime: vFinite(o.requestWallTime, source, `${path}.requestWallTime`),
@@ -768,6 +765,7 @@ function vInvalidClockOrder(
   let violation: Extract<IncompleteLifecycle, { kind: 'invalid_clock_order' }>['violation'];
   if (o.violation === 'response_before_request') violation = 'response_before_request';
   else if (o.violation === 'terminal_before_request') violation = 'terminal_before_request';
+  // Schema-v1 accepts this persisted discriminator.
   else if (o.violation === 'terminal_before_response') violation = 'terminal_before_response';
   else return fail(source, `${path}.violation`, 'must be "response_before_request", "terminal_before_request", or "terminal_before_response"');
 
@@ -828,7 +826,7 @@ function vStoppedDuringBody(
   const requestWallTime = vFinite(cap.requestWallTime, source, `${path}._capture.requestWallTime`);
   const requestMonotonic = vFiniteMin(cap.requestMonotonic, 0, source, `${path}._capture.requestMonotonic`);
   const responseMonotonic = vFiniteMin(cap.responseMonotonic, requestMonotonic, source, `${path}._capture.responseMonotonic`);
-  const terminalMonotonic = vFiniteMin(cap.terminalMonotonic, responseMonotonic, source, `${path}._capture.terminalMonotonic`);
+  const terminalMonotonic = vFiniteMin(cap.terminalMonotonic, requestMonotonic, source, `${path}._capture.terminalMonotonic`);
   const encodedDataLength = vFiniteMin(cap.encodedDataLength, 0, source, `${path}._capture.encodedDataLength`);
 
   assertStartedDateTime(startedDateTime, requestWallTime, source, `${path}._capture.requestWallTime`, `${path}.startedDateTime`);

package/src/interact.ts

@@ -6,7 +6,7 @@
  * (`src/output/selector.ts`'s `parseSelectorInput`) and resolves it against
  * the LIVE page (not collector-stored records), per prefix:
  *
- *   bare string    live CSS query — `DOM.getDocument` + `DOM.querySelectorAll`
+ *   bare string    live CSS query, or an exact accessible-name match when CSS finds none
  *   backend:<id>   identity — the canonical retry key in every resolution failure
  *   ax:<name>      case-insensitive SUBSTRING over live `Accessibility.getFullAXTree` names
  *   axid:<id>      AX node id from the same live fetch
@@ -37,14 +37,14 @@ import { parseSelectorInput, type SelectorInputKind } from './output/selector.js
 
 /**
  * The minimal CDP surface this module drives. `CDPClient` and
- * `RecorderHeldClient` satisfy it structurally; `motion rec --do` adapts
+ * `MotionHeldClient` satisfy it structurally; `motion rec --do` adapts
  * `RecorderSession.handleCdp` onto it.
  */
 export interface LiveClient {
   send(method: string, params?: Record<string, unknown>): Promise<unknown>;
   /**
    * Optional marked dispatch — transports that record labeled input
-   * landmarks (the recorder bridge's `mark` mechanism) expose it so a
+   * landmarks (the motion collector's `mark` mechanism) expose it so a
    * mutating call that is not auto-markable (`Runtime.callFunctionOn` in
    * {@link scrollResolved}) can carry its landmark. When absent, a marked
    * call degrades to a plain `send` (nothing is recording landmarks).
@@ -53,7 +53,7 @@ export interface LiveClient {
   /**
    * Optional recorder hook — suppresses the landmark on the next focus
    * click's initiating edge so a routed `type --into` lands one landmark on
-   * its actual text insertion (see `RecorderHeldClient`).
+   * its actual text insertion (see `MotionHeldClient`).
    */
   suppressNextFocusClickMark?(): void;
 }
@@ -111,17 +111,23 @@ export interface ClickDispatch {
   readonly name: string | null;
   readonly x: number;
   readonly y: number;
+  /** Present when the browser's hit test resolves to another node, or when the caller requests the receiver identity even when it equals the target. */
+  readonly hitTestReceiverBackendNodeId?: number;
 }
 
-/** Facts of a dispatched scroll: resolved identity + where the container landed. */
+/** Facts of a dispatched scroll: resolved identity + the observed range traversal. */
 export interface ScrollDispatch {
   readonly backendNodeId: number;
   readonly role: string | null;
   readonly name: string | null;
   /** The requested destination: `top`, `bottom`, or a pixel offset. */
   readonly to: string;
+  /** The container's `scrollTop` before the dispatch. */
+  readonly scrollTopBefore: number;
   /** The container's `scrollTop` after the dispatch. */
   readonly scrollTop: number;
+  /** The resolved container's maximum vertical scroll offset. */
+  readonly maxScrollTop: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -172,7 +178,7 @@ export async function resolveLiveTarget(
       return settleAxMatches('axid', input, matches);
     }
     case 'css':
-      return resolveLiveCss(client, input, parsed.value);
+      return resolveBareTarget(client, input, parsed.value);
   }
 }
 
@@ -220,6 +226,32 @@ function settleAxMatches(
   };
 }
 
+/**
+ * Bare targets preserve CSS behavior when they select one or many elements;
+ * when CSS selects none (or rejects the string), an exact accessible-name
+ * lookup lets an element name emitted by `page elements` drive directly.
+ * `ax:` remains the explicit case-insensitive substring query.
+ */
+async function resolveBareTarget(
+  client: LiveClient,
+  input: string,
+  selector: string,
+): Promise<ResolvedTarget | ResolutionFailure> {
+  const css = await resolveLiveCss(client, input, selector);
+  if (css.ok || css.code === 'ambiguous') return css;
+
+  const normalized = normalizeAccessibleName(input);
+  if (!normalized) return css;
+  const matches = (await readFullAXTree(client)).filter(
+    (node) =>
+      node.backendDOMNodeId !== undefined &&
+      node.name?.value !== undefined &&
+      normalizeAccessibleName(node.name.value) === normalized,
+  );
+  const ax = settleAxMatches('ax', input, matches);
+  return ax.ok || ax.code === 'ambiguous' ? ax : css;
+}
+
 async function resolveLiveCss(
   client: LiveClient,
   input: string,
@@ -331,7 +363,7 @@ async function axIdentityFor(
 export async function clickResolved(
   client: LiveClient,
   resolved: ResolvedTarget,
-  opts: { mark?: string } = {},
+  opts: { mark?: string; inspectHitTest?: boolean; includeHitTestReceiver?: boolean } = {},
 ): Promise<ClickDispatch> {
   const { backendNodeId } = resolved;
 
@@ -355,20 +387,37 @@ export async function clickResolved(
   const x = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
   const y = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
 
-  const pressParams = { type: 'mousePressed', x, y, button: 'left', clickCount: 1 };
+  const dispatchX = Math.round(x);
+  const dispatchY = Math.round(y);
+  let hitTestReceiverBackendNodeId: number | undefined;
+  if (opts.inspectHitTest) {
+    const hitTest = (await client.send('DOM.getNodeForLocation', { x: dispatchX, y: dispatchY })) as { backendNodeId?: unknown };
+    if (typeof hitTest.backendNodeId !== 'number' || !Number.isSafeInteger(hitTest.backendNodeId) || hitTest.backendNodeId <= 0) {
+      throw captureError(
+        'world',
+        'malformed_protocol',
+        `DOM.getNodeForLocation returned no valid backend node id for the dispatch point of backend:${backendNodeId}.`,
+        { method: 'DOM.getNodeForLocation', response: hitTest },
+      );
+    }
+    if (hitTest.backendNodeId !== backendNodeId || opts.includeHitTestReceiver) hitTestReceiverBackendNodeId = hitTest.backendNodeId;
+  }
+
+  const pressParams = { type: 'mousePressed', x: dispatchX, y: dispatchY, button: 'left', clickCount: 1 };
   if (opts.mark !== undefined && client.sendMarked) {
     await client.sendMarked('Input.dispatchMouseEvent', pressParams, opts.mark);
   } else {
     await client.send('Input.dispatchMouseEvent', pressParams);
   }
-  await client.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 });
+  await client.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: dispatchX, y: dispatchY, button: 'left', clickCount: 1 });
 
   return {
     backendNodeId,
     role: resolved.role,
     name: resolved.name,
-    x: Math.round(x),
-    y: Math.round(y),
+    x: dispatchX,
+    y: dispatchY,
+    ...(hitTestReceiverBackendNodeId === undefined ? {} : { hitTestReceiverBackendNodeId }),
   };
 }
 
@@ -387,9 +436,10 @@ export async function focusAndType(
   client: LiveClient,
   resolved: ResolvedTarget,
   text: string,
+  opts: { inspectHitTest?: boolean; includeHitTestReceiver?: boolean } = {},
 ): Promise<ClickDispatch> {
   client.suppressNextFocusClickMark?.();
-  const dispatch = await clickResolved(client, resolved);
+  const dispatch = await clickResolved(client, resolved, opts);
   // Small delay for focus to settle
   await new Promise((r) => setTimeout(r, 100));
   await typeText(client, text);
@@ -397,18 +447,20 @@ export async function focusAndType(
 }
 
 /**
- * Scrolls a resolved container to `top`, `bottom`, or a pixel offset by
- * assigning its `scrollTop` — `DOM.resolveNode` + `Runtime.callFunctionOn`
- * with the destination passed as data, never concatenated as code. When the
- * caller supplies `opts.mark` and the transport records landmarks
- * ({@link LiveClient.sendMarked}), the one mutating call carries the label —
- * the recorder landmark behavior `motion rec --do scroll:` shares.
+ * Scrolls a resolved container to `top`, `bottom`, or a pixel offset through
+ * an instant or native smooth-scroll dispatch — `DOM.resolveNode` +
+ * `Runtime.callFunctionOn` with the destination passed as data, never
+ * concatenated as code. The call resolves only at `scrollend`, returning the
+ * actual final offset. When the caller supplies `opts.mark` and the transport
+ * records landmarks ({@link LiveClient.sendMarked}), the one mutating call
+ * carries the label — the recorder landmark behavior `motion rec --do scroll:`
+ * shares.
  */
 export async function scrollResolved(
   client: LiveClient,
   resolved: ResolvedTarget,
   to: string,
-  opts: { mark?: string } = {},
+  opts: { mark?: string; behavior?: 'instant' | 'smooth' } = {},
 ): Promise<ScrollDispatch> {
   if (!isScrollDestination(to)) {
     throw captureError(
@@ -441,8 +493,9 @@ export async function scrollResolved(
     const params: Record<string, unknown> = {
       objectId,
       functionDeclaration:
-        'function(to) { const n = to === "top" ? 0 : to === "bottom" ? this.scrollHeight : Number(to); this.scrollTop = n; return this.scrollTop; }',
-      arguments: [{ value: to }],
+        'function(to, behavior) { const root = this === document.documentElement || this === document.body; const container = root ? document.scrollingElement : this; const before = container.scrollTop; const max = Math.max(0, container.scrollHeight - container.clientHeight); const n = to === "top" ? 0 : to === "bottom" ? container.scrollHeight : Number(to); const top = Math.max(0, Math.min(n, max)); const observed = () => ({ scrollTopBefore: before, scrollTopAfter: container.scrollTop, maxScrollTop: max }); if (before === top || behavior === "instant") { if (root) window.scrollTo({ top, behavior: "instant" }); else this.scrollTo({ top, behavior: "instant" }); return observed(); } return new Promise((resolve) => { const eventTarget = root ? document : this; let done = false; const finish = () => { if (done) return; done = true; clearTimeout(timeout); resolve(observed()); }; const timeout = setTimeout(finish, 5000); eventTarget.addEventListener("scrollend", finish, { once: true }); if (root) window.scrollTo({ top, behavior: "smooth" }); else this.scrollTo({ top, behavior: "smooth" }); }); }',
+      arguments: [{ value: to }, { value: opts.behavior ?? 'instant' }],
+      awaitPromise: true,
       returnByValue: true,
     };
     const result = (
@@ -458,15 +511,15 @@ export async function scrollResolved(
         `Scroll dispatch threw in-page: ${result.exceptionDetails.text ?? 'unknown error'}.`,
       );
     }
-    const scrollTop = result?.result?.value;
-    if (typeof scrollTop !== 'number') {
-      throw captureError('world', 'malformed_protocol', 'Scroll did not return a valid scrollTop payload.', {
+    const observed = result?.result?.value as { scrollTopBefore?: unknown; scrollTopAfter?: unknown; maxScrollTop?: unknown } | undefined;
+    if (typeof observed?.scrollTopBefore !== 'number' || typeof observed.scrollTopAfter !== 'number' || typeof observed.maxScrollTop !== 'number') {
+      throw captureError('world', 'malformed_protocol', 'Scroll did not return a valid traversed-range payload.', {
         method: 'Runtime.callFunctionOn',
         response: result,
       });
     }
 
-    return { backendNodeId, role: resolved.role, name: resolved.name, to, scrollTop };
+    return { backendNodeId, role: resolved.role, name: resolved.name, to, scrollTopBefore: observed.scrollTopBefore, scrollTop: observed.scrollTopAfter, maxScrollTop: observed.maxScrollTop };
   } catch (error) {
     primaryFailed = true;
     primaryError = error;

package/src/output/artifact.ts

@@ -26,7 +26,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { assertUnderCaptureRoot, type SnapMeta, type RecMeta } from '../session/artifacts.js';
+import { assertUnderCaptureRoot, readPrivateFile, type SnapMeta, type RecMeta } from '../session/artifacts.js';
 import { getActiveSession } from '../session-context.js';
 
 // ============================================================================
@@ -47,7 +47,16 @@ export interface RecRef {
   readonly dir: string;
 }
 
-export type ArtifactRef = SnapRef | RecRef;
+export interface TraceRef {
+  readonly kind: 'trace';
+  readonly id: string;
+  /** Absolute path to `perf/traces/{id}` (or the oneshot equivalent). */
+  readonly dir: string;
+  readonly completion: 'complete' | 'partial' | 'orphaned' | 'truncated';
+  readonly reason?: string;
+}
+
+export type ArtifactRef = SnapRef | RecRef | TraceRef;
 
 /** What a pluggable URL-snap callback must return. */
 export interface SnapUrlResult {
@@ -107,12 +116,12 @@ export function isUrlRef(ref: string): boolean {
 }
 
 interface RefKindConfig {
-  readonly kind: 'snap' | 'rec';
+  readonly kind: 'snap' | 'rec' | 'trace';
   /** Path segments under a session dir an id resolves through, e.g.
    * `['measure', 'snaps']`. */
   readonly idSegments: readonly [string, string];
   readonly creatingCommand: string;
-  readonly label: 'snapshot' | 'recording';
+  readonly label: 'snapshot' | 'recording' | 'trace';
 }
 
 const SNAP_CONFIG: RefKindConfig = {
@@ -129,6 +138,13 @@ const REC_CONFIG: RefKindConfig = {
   label: 'recording',
 };
 
+const TRACE_CONFIG: RefKindConfig = {
+  kind: 'trace',
+  idSegments: ['perf', 'traces'],
+  creatingCommand: 'capture perf trace',
+  label: 'trace',
+};
+
 function stripTrailingSep(p: string): string {
   return p.length > 1 && (p.endsWith('/') || p.endsWith(path.sep)) ? p.slice(0, -1) : p;
 }
@@ -223,6 +239,33 @@ export function resolveRecRef(ref: string): RecRef {
   return resolveRefFromId(ref, REC_CONFIG) as RecRef;
 }
 
+/** Resolves a finalized performance trace and verifies the host's committed-file inventory. */
+export function resolveTraceRef(ref: string): TraceRef {
+  if (isUrlRef(ref)) {
+    throw new ArtifactResolutionError(ref, [], 'a trace ref cannot be a URL — record one first with `capture perf trace <url>` or `--start`/`--stop`');
+  }
+  const resolved = (path.isAbsolute(ref) ? resolveRefFromPath(ref, TRACE_CONFIG) : (rejectRelativePath(ref), resolveRefFromId(ref, TRACE_CONFIG))) as { kind: 'trace'; id: string; dir: string };
+  let meta: Record<string, unknown>;
+  try { meta = JSON.parse(readPrivateFile(path.join(resolved.dir, 'meta.json')).toString('utf8')) as Record<string, unknown>; }
+  catch (error) { throw new ArtifactResolutionError(ref, [path.join(resolved.dir, 'meta.json')], `could not read trace metadata: ${error instanceof Error ? error.message : String(error)}`, TRACE_CONFIG.creatingCommand); }
+  const completion = meta.completion;
+  if (completion !== 'complete' && completion !== 'partial' && completion !== 'orphaned') {
+    throw new ArtifactResolutionError(ref, [path.join(resolved.dir, 'meta.json')], 'trace metadata has no valid completion state', TRACE_CONFIG.creatingCommand);
+  }
+  const inventory = meta.files;
+  const inventoryMalformed = !Array.isArray(inventory);
+  const inventoryMismatch = !inventoryMalformed && inventory.some((entry) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return true;
+    const item = entry as Record<string, unknown>;
+    const name = item.name;
+    const bytes = item.bytes;
+    if (typeof name !== 'string' || typeof bytes !== 'number' || !Number.isSafeInteger(bytes) || bytes < 0 || name.includes(path.sep)) return true;
+    try { return fs.statSync(path.join(resolved.dir, name)).size !== bytes; } catch { return true; }
+  });
+  const truncatedReason = inventoryMalformed ? 'artifact_inventory_missing_or_malformed' : inventoryMismatch ? 'artifact_inventory_mismatch' : undefined;
+  return { ...resolved, completion: truncatedReason ? 'truncated' : completion, ...(truncatedReason ? { reason: truncatedReason } : typeof meta.reason === 'string' ? { reason: meta.reason } : {}) };
+}
+
 // ============================================================================
 // Readers
 // ============================================================================
@@ -249,6 +292,7 @@ const CREATING_COMMAND_BY_FILE: Record<string, string> = {
   'rects.jsonl': 'capture motion rec',
   'events.jsonl': 'capture motion rec',
   'markers.json': 'capture motion rec',
+  'trace.json': 'capture perf trace',
 };
 
 function creatingCommandFor(filename: string): string | undefined {
@@ -268,7 +312,7 @@ export function artifactPath(ref: ArtifactRef, filename: string, opts: { mustExi
     throw new ArtifactResolutionError(
       ref.id,
       [filePath],
-      `${filename} is not present in ${ref.kind === 'snap' ? 'snapshot' : 'recording'} ${ref.id}`,
+      `${filename} is not present in ${ref.kind === 'snap' ? 'snapshot' : ref.kind === 'rec' ? 'recording' : 'trace'} ${ref.id}`,
       creatingCommandFor(filename),
     );
   }

package/src/output/render.ts

@@ -30,6 +30,7 @@ export const RESULT_TAGS = [
   'diff',
   'census',
   'explain',
+  'text',
   'sweep',
   'focus-map',
   'scroll-map',
@@ -45,6 +46,7 @@ export const RESULT_TAGS = [
   'session-stopped',
   'sessions',
   'session-har',
+  'collectors',
   'log-tail',
   'clicked',
   'typed',
@@ -52,6 +54,11 @@ export const RESULT_TAGS = [
   'navigated',
   'exec-result',
   'elements',
+  'listeners',
+  'cardinality',
+  'frames',
+  'resources',
+  'repeated',
   'screenshot',
   'tabs',
   'tab-opened',
@@ -60,10 +67,20 @@ export const RESULT_TAGS = [
   'browser-launched',
   'browser-quit',
   'network',
+  'mock',
   'cdp-result',
   'libs',
   'lib',
   'ax-map',
+  'trace',
+  'vitals',
+  'insights',
+  'heap-snapshot',
+  'heap-census',
+  'heap-objects',
+  'retainers',
+  'heap-diff',
+  'lighthouse',
 ] as const;
 
 export type ResultTag = (typeof RESULT_TAGS)[number];
@@ -723,7 +740,7 @@ function resolveFactLine(fl: FactLine, mode: 'xml' | 'json'): string {
 // ---------------------------------------------------------------------------
 
 export interface Attestation {
-  readonly kind: 'snapshot' | 'recording';
+  readonly kind: 'snapshot' | 'recording' | 'trace';
   /** Snapshot or recording id, e.g. "snap-a3f2" / "rec-9f31". */
   readonly id: string;
   /** Absolute artifact directory path. */
@@ -738,7 +755,9 @@ export interface Attestation {
 // hands to renderResult()/emitResult().
 // ---------------------------------------------------------------------------
 
-export type ResultAttrs = Record<string, string | number | boolean | undefined>;
+export type ResultAttrs = Record<string, string | number | boolean | Capped | undefined>;
+
+export type JsonValue = string | number | boolean | null | Capped | readonly JsonValue[] | { readonly [key: string]: JsonValue };
 
 export interface RenderableResult {
   /** Trusted block tag — must be one of RESULT_TAGS. */
@@ -753,6 +772,10 @@ export interface RenderableResult {
   readonly attrs?: ResultAttrs;
   /** Snapshot/recording identity + optional method note. */
   readonly attestation?: Attestation;
+  /** Optional structured JSON mirror for artifact names. Prose retains the rendered FactLine artifact list. */
+  readonly jsonArtifacts?: readonly string[];
+  /** Optional structured JSON mirror for sections. Prose retains the rendered FactLine sections. */
+  readonly jsonSections?: readonly JsonValue[];
   /** Lead sentence(s), rendered immediately after the opening tag. */
   readonly summary?: FactLine;
   /** Pre-formatted artifact listing (typically via formatArtifactList),
@@ -764,20 +787,23 @@ export interface RenderableResult {
    * multi-line paragraph/preformatted block that should NOT be blank-line
    * split — e.g. a motion timeline's consecutive `t=...` rows. */
   readonly sections?: readonly FactLine[];
+  /** Structured JSON mirror of sections when rows are records rather than prose. All strings are recursively sanitized by the renderer. */
+  readonly jsonSections?: unknown;
   /** A single follow_up line, built only from trusted command templates via
    * `fact`/`text`/`data` — ids/paths are always embedded as escaped data,
    * never as literal instruction text. */
   readonly followUp?: FactLine;
 }
 
-function renderAttrValue(raw: string | number | boolean): string {
+function renderAttrValue(raw: string | number | boolean | Capped): string {
+  if (isCapped(raw)) return escapeXmlAttr(capLength(neutralizeControl(String(raw.value)), raw.maxLength));
   if (typeof raw === 'number') return sanitizeNumber(raw);
   if (typeof raw === 'boolean') return String(raw);
-  const cleaned = neutralizeControl(raw);
-  return escapeXmlAttr(capLength(cleaned, DEFAULT_ATTR_MAX));
+  return escapeXmlAttr(capLength(neutralizeControl(raw), DEFAULT_ATTR_MAX));
 }
 
-function jsonAttrValue(raw: string | number | boolean): string | number | boolean {
+function jsonAttrValue(raw: string | number | boolean | Capped): string | number | boolean {
+  if (isCapped(raw)) return capLength(neutralizeControl(String(raw.value)), raw.maxLength);
   if (typeof raw !== 'string') return raw;
   return capLength(neutralizeControl(raw), DEFAULT_ATTR_MAX);
 }
@@ -816,7 +842,7 @@ function renderAttrs(attrs: ResultAttrs): string {
  * the prose and --json paths. */
 function mergeAttestationAttrs(attrs: ResultAttrs, attestation?: Attestation): ResultAttrs {
   if (!attestation) return attrs;
-  const idKey = attestation.kind === 'snapshot' ? 'snap' : 'rec';
+  const idKey = attestation.kind === 'snapshot' ? 'snap' : attestation.kind === 'recording' ? 'rec' : 'trace';
   const canonical: ResultAttrs = { path: attestation.path, [idKey]: attestation.id };
 
   for (const [key, canonicalValue] of Object.entries(canonical)) {
@@ -839,6 +865,14 @@ function mergeAttestationAttrs(attrs: ResultAttrs, attestation?: Attestation): R
   return merged;
 }
 
+function jsonValue(value: JsonValue): JsonValue {
+  if (isCapped(value)) return capLength(neutralizeControl(String(value.value)), value.maxLength);
+  if (typeof value === 'string') return capLength(neutralizeControl(value), DEFAULT_DATA_MAX);
+  if (typeof value === 'number' || typeof value === 'boolean' || value === null) return value;
+  if (Array.isArray(value)) return value.map(jsonValue);
+  return Object.fromEntries(Object.entries(value).map(([key, child]) => [capLength(neutralizeControl(key), DEFAULT_DATA_MAX), jsonValue(child)]));
+}
+
 function assembleBody(result: RenderableResult): string {
   const header: string[] = [];
   if (result.attestation?.note) header.push(resolveFactLine(result.attestation.note, 'xml'));
@@ -864,6 +898,22 @@ export function renderResult(result: RenderableResult): string {
   return `${block}\nfollow_up: ${resolveFactLine(result.followUp, 'xml')}`;
 }
 
+function sanitizeJsonValue(value: unknown, seen = new WeakSet<object>()): unknown {
+  if (isCapped(value)) return capLength(neutralizeControl(String(value.value)), value.maxLength);
+  if (typeof value === 'string') return capLength(neutralizeControl(value), DEFAULT_DATA_MAX);
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  if (typeof value === 'boolean' || value === null) return value;
+  if (Array.isArray(value)) return value.map(item => sanitizeJsonValue(item, seen));
+  if (typeof value === 'object') {
+    if (seen.has(value)) throw new Error('render.ts: structured JSON sections cannot contain cycles');
+    seen.add(value);
+    const record = Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, item]) => [capLength(neutralizeControl(key), DEFAULT_ATTR_MAX), sanitizeJsonValue(item, seen)]));
+    seen.delete(value);
+    return record;
+  }
+  return null;
+}
+
 /** Build the plain-object JSON mirror of a result, applying the same
  * length-cap / control-char redaction as the prose renderer (minus XML
  * entity escaping, which JSON.stringify already makes unnecessary). */
@@ -875,7 +925,7 @@ export function toJsonResult(result: RenderableResult): Record<string, unknown>
       .filter(([, v]) => v !== undefined)
       .map(([k, v]) => {
         assertValidAttrKey(k);
-        return [k, jsonAttrValue(v as string | number | boolean)];
+        return [k, jsonAttrValue(v as string | number | boolean | Capped)];
       }),
   );
 
@@ -891,7 +941,8 @@ export function toJsonResult(result: RenderableResult): Record<string, unknown>
   }
   if (result.summary) out.summary = resolveFactLine(result.summary, 'json');
   if (result.artifacts) out.artifacts = resolveFactLine(result.artifacts, 'json');
-  if (result.sections?.length) out.sections = result.sections.map((s) => resolveFactLine(s, 'json'));
+  if (result.jsonSections !== undefined) out.sections = sanitizeJsonValue(result.jsonSections);
+  else if (result.sections?.length) out.sections = result.sections.map((s) => resolveFactLine(s, 'json'));
   if (result.followUp) out.followUp = resolveFactLine(result.followUp, 'json');
 
   return out;

package/src/output/selection.ts

@@ -0,0 +1,6 @@
+import { type ParsedArgs } from '../cdp/types.js';
+
+/** Select the final stdout record set after a leaf has applied its own semantic filters and stable ordering. */
+export function selectRecords<T>(records: readonly T[], parsed: Pick<ParsedArgs, 'limit'>, defaultLimit: number): T[] {
+  return records.slice(0, parsed.limit ?? defaultLimit);
+}