@crouton-kit/capture 1.3.7 → 1.3.9

package/src/output/selector.ts

@@ -0,0 +1,185 @@
+/**
+ * Selector helpers — map a query leaf's `--selector`/`--element` input
+ * string to the stored per-element records a snapshot's collector files
+ * carry. Pure lookups over an already-read array; this module never reads
+ * an artifact file itself (see `src/output/artifact.ts` for that).
+ *
+ * Contract this module fixes for upstream collector writers: any collector
+ * file that indexes elements (`geometry.json` first and foremost — see the
+ * contract note at the top of `artifact.ts`) should shape each element's
+ * record to satisfy {@link ElementRecord} — a stable `id`, and whichever of
+ * `selector`/`backendNodeId`/`axId`/`axName`/`text` it has facts for — so a
+ * query leaf's selector lookup works the same way regardless of which
+ * collector file it pulled the array from.
+ */
+
+// ============================================================================
+// Element records
+// ============================================================================
+
+export interface ElementRecord {
+  /** Stable per-snapshot element id (e.g. `el-14`) collectors key off of. */
+  readonly id: string;
+  /** The collector-computed CSS-ish selector string for this element
+   * (e.g. `.message-card:nth-child(4)`), when known. */
+  readonly selector?: string;
+  readonly backendNodeId?: number;
+  /** Accessibility node id, when the element has a non-ignored AX node. */
+  readonly axId?: string;
+  /** Accessibility computed name, when known. */
+  readonly axName?: string;
+  /** Text content associated with the element, when known. */
+  readonly text?: string;
+  readonly [key: string]: unknown;
+}
+
+// ============================================================================
+// Direct lookups
+// ============================================================================
+
+/** Elements whose stored `selector` exactly equals `selector`. */
+export function findBySelector(elements: readonly ElementRecord[], selector: string): ElementRecord[] {
+  return elements.filter((e) => e.selector === selector);
+}
+
+/** The element with this `backendNodeId`, if any. */
+export function findByBackendNodeId(elements: readonly ElementRecord[], backendNodeId: number): ElementRecord | undefined {
+  return elements.find((e) => e.backendNodeId === backendNodeId);
+}
+
+/** The element with this exact `axId`, if any. */
+export function findByAxId(elements: readonly ElementRecord[], axId: string): ElementRecord | undefined {
+  return elements.find((e) => e.axId === axId);
+}
+
+/** Elements whose `axName` matches `name` — exact (case-insensitive) by
+ * default, or a case-insensitive substring match with `{ exact: false }`. */
+export function findByAxName(
+  elements: readonly ElementRecord[],
+  name: string,
+  opts: { exact?: boolean } = {},
+): ElementRecord[] {
+  const exact = opts.exact ?? true;
+  const needle = name.toLowerCase();
+  return elements.filter((e) => {
+    if (e.axName === undefined) return false;
+    const hay = e.axName.toLowerCase();
+    return exact ? hay === needle : hay.includes(needle);
+  });
+}
+
+/** Elements whose `text` matches `needle` — case-insensitive substring by
+ * default, or an exact (case-insensitive) match with `{ exact: true }`. */
+export function findByText(
+  elements: readonly ElementRecord[],
+  needle: string,
+  opts: { exact?: boolean } = {},
+): ElementRecord[] {
+  const exact = opts.exact ?? false;
+  const target = needle.toLowerCase();
+  return elements.filter((e) => {
+    if (e.text === undefined) return false;
+    const hay = e.text.toLowerCase();
+    return exact ? hay === target : hay.includes(target);
+  });
+}
+
+// ============================================================================
+// Selector-input grammar
+// ============================================================================
+
+export type SelectorInputKind = 'backend' | 'axid' | 'ax' | 'text' | 'css';
+
+export interface ParsedSelectorInput {
+  readonly kind: SelectorInputKind;
+  readonly value: string;
+}
+
+/**
+ * Parses a `--selector`/`--element` input string into its lookup kind:
+ *  - `backend:1234` — backend node id
+ *  - `axid:<id>`    — accessibility node id
+ *  - `ax:<name>`    — accessibility name (substring)
+ *  - `text:<needle>`— text content (substring)
+ *  - anything else  — a CSS-ish selector, matched exactly against the
+ *    collector's stored `selector` string (the form every design sample
+ *    uses, e.g. `--selector ".toast-container"`)
+ */
+export function parseSelectorInput(input: string): ParsedSelectorInput {
+  const prefixes: Array<[string, SelectorInputKind]> = [
+    ['backend:', 'backend'],
+    ['axid:', 'axid'],
+    ['ax:', 'ax'],
+    ['text:', 'text'],
+  ];
+  for (const [prefix, kind] of prefixes) {
+    if (input.startsWith(prefix)) {
+      return { kind, value: input.slice(prefix.length) };
+    }
+  }
+  return { kind: 'css', value: input };
+}
+
+/**
+ * Resolves a `--selector`/`--element` input string to every matching
+ * element record, dispatching on {@link parseSelectorInput}'s grammar. This
+ * is the one entry point query leaves should call for user-supplied
+ * selector input rather than picking a `findBy*` helper themselves.
+ */
+export function resolveSelectorInput(elements: readonly ElementRecord[], input: string): ElementRecord[] {
+  const parsed = parseSelectorInput(input);
+  switch (parsed.kind) {
+    case 'backend': {
+      const id = Number(parsed.value);
+      if (!Number.isFinite(id)) return [];
+      const found = findByBackendNodeId(elements, id);
+      return found ? [found] : [];
+    }
+    case 'axid': {
+      const found = findByAxId(elements, parsed.value);
+      return found ? [found] : [];
+    }
+    case 'ax':
+      return findByAxName(elements, parsed.value, { exact: false });
+    case 'text':
+      return findByText(elements, parsed.value, { exact: false });
+    case 'css':
+      return findBySelector(elements, parsed.value);
+  }
+}
+
+// ============================================================================
+// Recovery hints
+// ============================================================================
+
+export interface SelectorHints {
+  readonly selectors: readonly string[];
+  readonly axNames: readonly string[];
+  readonly texts: readonly string[];
+}
+
+function uniqueTruncated(values: readonly (string | undefined)[], limit: number): string[] {
+  const seen = new Set<string>();
+  for (const v of values) {
+    if (v === undefined) continue;
+    seen.add(v);
+    if (seen.size >= limit) break;
+  }
+  return [...seen];
+}
+
+/**
+ * Example selector/AX-name/text values present in `elements`, for a query
+ * leaf to embed in a "missing selector" structured recovery error (per the
+ * design: "missing selector returns a structured recovery error listing
+ * available selector forms"). This module only gathers the raw examples —
+ * the calling leaf renders them through `src/output/render.ts`'s `data()`
+ * so untrusted DOM/AX/text content is escaped before it reaches output.
+ */
+export function selectorHints(elements: readonly ElementRecord[], limit = 10): SelectorHints {
+  return {
+    selectors: uniqueTruncated(elements.map((e) => e.selector), limit),
+    axNames: uniqueTruncated(elements.map((e) => e.axName), limit),
+    texts: uniqueTruncated(elements.map((e) => e.text), limit),
+  };
+}

package/src/output/structured.ts

@@ -0,0 +1,211 @@
+/**
+ * Unreachable structured-output owner for the hard cut. Leaves give this
+ * module one semantic projection builder and two canonical encoders; this
+ * module alone decides which optional records are admitted.
+ */
+import { MAX_BOUNDED_BYTES, utf8ByteLength } from '../contracts/primitives.js';
+
+export type OutputEncoding = 'prose' | 'json';
+
+export interface CollectionOmittedBy {
+  readonly count_limit: number;
+  readonly byte_budget: number;
+}
+
+export interface DisplayedCollection<T> {
+  readonly retained_total: number;
+  readonly displayed: number;
+  readonly omitted: number;
+  readonly limit: number;
+  readonly omitted_by: CollectionOmittedBy;
+  readonly records: readonly T[];
+}
+
+export interface ProjectionCandidate<T> {
+  /** Stable ID used by both encoders and later artifact lookup. */
+  readonly id: string;
+  /** Canonical per-collection display order, independent of admission priority. */
+  readonly displayOrder: number;
+  readonly record: T;
+}
+
+export interface ProjectionCollection<T> {
+  readonly name: string;
+  readonly retainedTotal: number;
+  readonly limit: number;
+  /** Eligible candidates in this collection's canonical record order. */
+  readonly candidates: readonly ProjectionCandidate<T>[];
+}
+
+export type DisplayedCollections<T> = Readonly<Record<string, DisplayedCollection<T>>>;
+
+export interface CanonicalStructuredEncoders<S> {
+  readonly prose: (semantic: S) => string;
+  readonly json: (semantic: S) => string;
+}
+
+export interface AllocateStructuredProjection<S, T> {
+  readonly collections: readonly ProjectionCollection<T>[];
+  /**
+   * Every eligible candidate exactly once, in the leaf's declared global
+   * consideration order. This represents priority groups and cross-collection
+   * round robin without letting the allocator invent command semantics.
+   */
+  readonly candidateOrder: readonly { readonly collection: string; readonly candidate: ProjectionCandidate<T> }[];
+  /** Builds the one semantic input shared by the two encoders. */
+  readonly build: (collections: DisplayedCollections<T>) => S;
+  readonly encoders: CanonicalStructuredEncoders<S>;
+  readonly maxBytes?: number;
+}
+
+export interface AllocatedStructuredProjection<S, T> {
+  readonly semantic: S;
+  readonly collections: DisplayedCollections<T>;
+  readonly prose: string;
+  readonly json: string;
+  readonly bytes: Readonly<Record<OutputEncoding, number>>;
+}
+
+interface MutableCollection<T> {
+  readonly definition: ProjectionCollection<T>;
+  readonly eligible: readonly ProjectionCandidate<T>[];
+  readonly displayed: ProjectionCandidate<T>[];
+  byteBudget: number;
+}
+
+function assertSafeUint(value: number, field: string): void {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${field} must be a nonnegative safe integer`);
+}
+
+function verifyDefinitions<T>(collections: readonly ProjectionCollection<T>[]): void {
+  const names = new Set<string>();
+  const ids = new Set<string>();
+  for (const collection of collections) {
+    if (!collection.name) throw new Error('collection name must not be empty');
+    if (names.has(collection.name)) throw new Error(`duplicate collection name: ${collection.name}`);
+    names.add(collection.name);
+    assertSafeUint(collection.retainedTotal, `${collection.name}.retainedTotal`);
+    assertSafeUint(collection.limit, `${collection.name}.limit`);
+    if (collection.candidates.length > collection.retainedTotal) throw new Error(`${collection.name} has more candidates than retainedTotal`);
+    const eligible = Math.min(collection.retainedTotal, collection.limit);
+    if (collection.candidates.length !== eligible) throw new Error(`${collection.name} candidates must contain exactly min(retainedTotal, limit) records`);
+    const displayOrders = new Set<number>();
+    for (const candidate of collection.candidates) {
+      if (!candidate.id) throw new Error(`${collection.name} candidate has empty stable id`);
+      assertSafeUint(candidate.displayOrder, `${collection.name}.${candidate.id}.displayOrder`);
+      if (displayOrders.has(candidate.displayOrder)) throw new Error(`${collection.name} repeats displayOrder ${candidate.displayOrder}`);
+      displayOrders.add(candidate.displayOrder);
+      if (ids.has(candidate.id)) throw new Error(`duplicate stable candidate id: ${candidate.id}`);
+      ids.add(candidate.id);
+    }
+  }
+}
+
+function displayedCollections<T>(states: readonly MutableCollection<T>[]): DisplayedCollections<T> {
+  return Object.fromEntries(states.map((state) => {
+    const { retainedTotal, limit, name } = state.definition;
+    const displayed = state.displayed.length;
+    const countLimit = Math.max(0, retainedTotal - limit);
+    const omitted = retainedTotal - displayed;
+    const byteBudget = Math.min(retainedTotal, limit) - displayed;
+    if (byteBudget !== state.byteBudget) throw new Error(`allocator corruption for ${name}`);
+    return [name, {
+      retained_total: retainedTotal,
+      displayed,
+      omitted,
+      limit,
+      omitted_by: { count_limit: countLimit, byte_budget: byteBudget },
+      records: [...state.displayed]
+        .sort((left, right) => left.displayOrder - right.displayOrder)
+        .map((candidate) => candidate.record),
+    } satisfies DisplayedCollection<T>];
+  }));
+}
+
+function encode<S, T>(states: readonly MutableCollection<T>, build: (collections: DisplayedCollections<T>) => S, encoders: CanonicalStructuredEncoders<S>): AllocatedStructuredProjection<S, T> {
+  const collections = displayedCollections(states);
+  const semantic = build(collections);
+  const prose = encoders.prose(semantic);
+  const json = encoders.json(semantic);
+  return { semantic, collections, prose, json, bytes: { prose: utf8ByteLength(prose), json: utf8ByteLength(json) } };
+}
+
+function fits<S, T>(projection: AllocatedStructuredProjection<S, T>, maxBytes: number): boolean {
+  return projection.bytes.prose <= maxBytes && projection.bytes.json <= maxBytes;
+}
+
+/**
+ * Allocate whole records once for both encodings. A candidate is tested against
+ * the projection with every not-yet-considered eligible record counted as a
+ * byte-budget omission; this makes the final omission metadata part of every
+ * admission decision. A record that does not fit never blocks later records.
+ */
+export function allocateStructuredProjection<S, T>(input: AllocateStructuredProjection<S, T>): AllocatedStructuredProjection<S, T> {
+  const maxBytes = input.maxBytes ?? MAX_BOUNDED_BYTES;
+  assertSafeUint(maxBytes, 'maxBytes');
+  if (maxBytes > MAX_BOUNDED_BYTES) throw new Error(`maxBytes must not exceed ${MAX_BOUNDED_BYTES}`);
+  verifyDefinitions(input.collections);
+  const states = input.collections.map<MutableCollection<T>>((definition) => ({
+    definition,
+    eligible: definition.candidates,
+    displayed: [],
+    byteBudget: definition.candidates.length,
+  }));
+  const stateByName = new Map(states.map((state) => [state.definition.name, state]));
+  const expectedCandidates = new Map(states.flatMap((state) => state.eligible.map((candidate) => [candidate.id, { state, candidate }] as const)));
+  const orderedIds = new Set<string>();
+  for (const entry of input.candidateOrder) {
+    const expected = expectedCandidates.get(entry.candidate.id);
+    if (!expected || expected.state !== stateByName.get(entry.collection) || expected.candidate !== entry.candidate) {
+      throw new Error(`candidateOrder contains an unknown or mismatched candidate: ${entry.candidate.id}`);
+    }
+    if (orderedIds.has(entry.candidate.id)) throw new Error(`candidateOrder repeats candidate: ${entry.candidate.id}`);
+    orderedIds.add(entry.candidate.id);
+  }
+  if (orderedIds.size !== expectedCandidates.size) throw new Error('candidateOrder must contain every eligible candidate exactly once');
+
+  for (const { collection, candidate } of input.candidateOrder) {
+    const state = stateByName.get(collection)!;
+    state.displayed.push(candidate);
+    state.byteBudget--;
+    if (!fits(encode(states, input.build, input.encoders), maxBytes)) {
+      state.displayed.pop();
+      state.byteBudget++;
+    }
+  }
+
+  let projection = encode(states, input.build, input.encoders);
+  // Decimal omission metadata can grow after later candidates are rejected.
+  // Remove whole records (never encoded prefixes) until the final semantic
+  // projection itself satisfies both independent caps.
+  while (!fits(projection, maxBytes)) {
+    const state = [...states].reverse().find((candidate) => candidate.displayed.length > 0);
+    if (!state) throw new Error(`mandatory structured projection exceeds ${maxBytes} bytes`);
+    state.displayed.pop();
+    state.byteBudget++;
+    projection = encode(states, input.build, input.encoders);
+  }
+  return projection;
+}
+
+/** Cap a UTF-8 string at a code-point boundary and report exact byte omission arithmetic. */
+export function capUtf8(value: string, maxBytes: number): { readonly value: string; readonly bytes_omitted: number } {
+  assertSafeUint(maxBytes, 'maxBytes');
+  const sourceBytes = utf8ByteLength(value);
+  if (sourceBytes <= maxBytes) return { value, bytes_omitted: 0 };
+  let end = 0;
+  let bytes = 0;
+  for (const codePoint of value) {
+    const next = utf8ByteLength(codePoint);
+    if (bytes + next > maxBytes) break;
+    bytes += next;
+    end += codePoint.length;
+  }
+  return { value: value.slice(0, end), bytes_omitted: sourceBytes - bytes };
+}
+
+/** Exact scalar and collection exhaustion calculation shared by both encoders. */
+export function projectionExhaustive<T>(collections: DisplayedCollections<T>, scalarBytesOmittedTotal: number): boolean {
+  assertSafeUint(scalarBytesOmittedTotal, 'scalarBytesOmittedTotal');
+  return scalarBytesOmittedTotal === 0 && Object.values(collections).every((collection) => collection.omitted === 0);
+}