@goliapkg/smix 0.1.0

package/src/Locator.ts

@@ -0,0 +1,190 @@
+// v7.5 c3 — Locator poll loop, mirror Kotlin v7.4 c3 + Swift v7.1 c3.
+//
+// 250ms tick over a millisecond deadline. On timeout, throws
+// ExpectationFailure with the last tree's first-20 visible elements
+// populated for AI agent diagnosis.
+
+import { findById, flatten, type A11yNode } from './A11yNode.js'
+import type { App } from './App.js'
+import { ExpectationFailure } from './ExpectationFailure.js'
+import {
+  encodeSelectorJson,
+  type Selector,
+} from './Selector.js'
+
+const POLL_INTERVAL_MS = 250
+const DEFAULT_TIMEOUT_MS = 5_000
+
+export class Locator {
+  constructor(
+    public readonly app: App,
+    public readonly selector: Selector,
+  ) {}
+
+  /**
+   * Resolve [selector] until at least one match exists AND that match
+   * is `visible=true`. Polls every 250ms until [timeoutMs] expires.
+   */
+  async toBeVisible(opts: { timeoutMs?: number } = {}): Promise<void> {
+    return this.pollUntil({
+      timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      wrongStatePredicate: node => node !== null && node.visible !== true,
+      successPredicate: node => node !== null && node.visible === true,
+      timeoutMessage: 'element never became visible',
+    })
+  }
+
+  /**
+   * Resolve [selector] until a match exists AND `text.includes(needle)`
+   * on label/title/text fields.
+   */
+  async toContainText(text: string, opts: { timeoutMs?: number } = {}): Promise<void> {
+    return this.pollUntil({
+      timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      wrongStatePredicate: () => false,
+      successPredicate: node =>
+        node !== null && (
+          node.label?.includes(text) === true ||
+          node.title?.includes(text) === true ||
+          node.text?.includes(text) === true
+        ),
+      timeoutMessage: `element text never contained "${text}"`,
+    })
+  }
+
+  /**
+   * v7.6 c1 — Resolve [selector] until at least one match exists AND
+   * that match's label equals [label]. Polls via standard resolver +
+   * findById path (label is on the snapshot node, not on FFI's labels
+   * resolver which is more useful for count-based assertions).
+   */
+  async toHaveLabel(label: string, opts: { timeoutMs?: number } = {}): Promise<void> {
+    return this.pollUntil({
+      timeoutMs: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      wrongStatePredicate: () => false,
+      successPredicate: node => node !== null && node.label === label,
+      timeoutMessage: `element label never equaled "${label}"`,
+    })
+  }
+
+  /**
+   * v7.6 c1 — Resolve [selector] until the labels resolver returns
+   * exactly [n] matches. Uses dedicated `app.labelsResolver` (wraps
+   * Rust `resolve_selector_labels`) so count semantics skip index
+   * modifier per Playwright "match all" behavior.
+   */
+  async toHaveCount(n: number, opts: { timeoutMs?: number } = {}): Promise<void> {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    const deadline = Date.now() + timeoutMs
+    let lastCount = 0
+    let lastTree: A11yNode | null = null
+    const selectorJson = encodeSelectorJson(this.selector)
+    while (true) {
+      const tree = await this.app.runtime.snapshotTree()
+      lastTree = tree
+      let labels: readonly string[]
+      try {
+        labels = await this.app.labelsResolver(JSON.stringify(tree), selectorJson)
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e)
+        throw new ExpectationFailure({
+          code: 'unknown',
+          message: `FFI resolveSelectorLabels raised during poll: ${msg}`,
+          selectorJson,
+        })
+      }
+      lastCount = labels.length
+      if (lastCount === n) return
+      if (Date.now() >= deadline) break
+      await delay(POLL_INTERVAL_MS)
+    }
+    throw new ExpectationFailure({
+      code: 'wrongState',
+      message: `expected ${n} matches, last poll saw ${lastCount}`,
+      selectorJson,
+      visibleElements: lastTree !== null ? flatten(lastTree).slice(0, 20) : [],
+      suggestions: [
+        'verify the selector matches the expected count in the current tree',
+        'consider extending the timeout if render is slow',
+      ],
+    })
+  }
+
+  /**
+   * Generic 250ms poll loop. On each tick, resolve [selector] via the
+   * app's runtime + resolver, then check predicates.
+   *
+   * - [successPredicate] returns true → return immediately
+   * - [wrongStatePredicate] returns true → throw wrongState
+   * - Otherwise, continue polling.
+   *
+   * On timeout, throws timeout with the last tree's first-20 nodes.
+   */
+  private async pollUntil(opts: {
+    timeoutMs: number
+    wrongStatePredicate: (node: A11yNode | null) => boolean
+    successPredicate: (node: A11yNode | null) => boolean
+    timeoutMessage: string
+  }): Promise<void> {
+    const deadline = Date.now() + opts.timeoutMs
+    let lastTree: A11yNode | null = null
+
+    while (true) {
+      const tree = await this.app.runtime.snapshotTree()
+      lastTree = tree
+      const selectorJson = encodeSelectorJson(this.selector)
+      let matches: readonly string[]
+      try {
+        matches = await this.app.resolver(JSON.stringify(tree), selectorJson)
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e)
+        throw new ExpectationFailure({
+          code: 'unknown',
+          message: `FFI resolveSelector raised during poll: ${msg}`,
+          selectorJson,
+        })
+      }
+      const firstId = matches[0]
+      const node = firstId !== undefined ? findById(tree, firstId) : null
+
+      if (opts.wrongStatePredicate(node)) {
+        throw new ExpectationFailure({
+          code: 'wrongState',
+          message: 'element matched but predicate failed (e.g. not visible)',
+          selectorJson,
+          visibleElements: node !== null ? [node, ...flatten(tree).slice(0, 19)] : flatten(tree).slice(0, 20),
+        })
+      }
+      if (opts.successPredicate(node)) return
+
+      if (Date.now() >= deadline) break
+      await delay(POLL_INTERVAL_MS)
+    }
+
+    throw new ExpectationFailure({
+      code: 'timeout',
+      message: opts.timeoutMessage,
+      selectorJson: encodeSelectorJson(this.selector),
+      visibleElements: lastTree !== null ? flatten(lastTree).slice(0, 20) : [],
+      suggestions: [
+        'consider extending the timeout if the UI takes longer to settle',
+        'verify the selector matches when manually inspected (use app.tree())',
+      ],
+    })
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+/**
+ * Compile-time-known unimplemented surface (distinct from
+ * ExpectationFailure which is runtime resolution failure).
+ */
+export class SmixNotImplementedError extends Error {
+  constructor(public readonly stage: string, public readonly api: string) {
+    super(`${api} not implemented yet (lands ${stage})`)
+    this.name = 'SmixNotImplementedError'
+  }
+}

package/src/Pattern.ts

@@ -0,0 +1,51 @@
+// v7.5 c1 — Pattern (literal vs regex) mirror Swift v7.2 c3 + Kotlin v7.4 c4
+// + Rust smix-selector `#[serde(untagged)] enum Pattern`.
+//
+// Wire JSON forms (untagged):
+//   Literal: bare string                   e.g. "hello"
+//   Regex:   {"regex":"...","flags":"i"}    (flags default "i")
+
+export type Pattern =
+  | { kind: 'literal'; value: string }
+  | { kind: 'regex'; regex: string; flags: string }
+
+export function literal(value: string): Pattern {
+  return { kind: 'literal', value }
+}
+
+export function regex(pat: string, flags = 'i'): Pattern {
+  return { kind: 'regex', regex: pat, flags }
+}
+
+/**
+ * Encode a Pattern to its Rust-compatible untagged JSON form
+ * (bare string for literal / `{regex, flags}` object for regex).
+ * Returns a JSON-encodable value (not a JSON string).
+ */
+export function patternToJson(p: Pattern): unknown {
+  switch (p.kind) {
+    case 'literal':
+      return p.value
+    case 'regex':
+      return { regex: p.regex, flags: p.flags }
+  }
+}
+
+/**
+ * Decode a JSON value into a Pattern. Throws on unrecognized shape.
+ */
+export function patternFromJson(value: unknown): Pattern {
+  if (typeof value === 'string') {
+    return { kind: 'literal', value }
+  }
+  if (typeof value === 'object' && value !== null && 'regex' in value) {
+    const obj = value as Record<string, unknown>
+    const rx = obj.regex
+    if (typeof rx !== 'string') {
+      throw new Error(`Pattern.regex must be string, got: ${typeof rx}`)
+    }
+    const flags = typeof obj.flags === 'string' ? obj.flags : 'i'
+    return { kind: 'regex', regex: rx, flags }
+  }
+  throw new Error(`Pattern must be string or {regex, flags?} object, got: ${JSON.stringify(value)}`)
+}

package/src/Selector.ts

@@ -0,0 +1,296 @@
+// v7.5 c1 — Selector full 7-case + Modifiers flatten + Pattern + fluent.
+//
+// Mirror Swift v7.2 c3 + Kotlin v7.4 c4 + Rust smix-selector
+// `#[serde(untagged)] enum Selector` with full `Modifiers` flatten on
+// Text/Id/Label/Role/LocalizedText bases. Focused has no modifiers.
+// Anchor uses AnchorBox + IndexModifiers.
+//
+// Class-based API (mirrors Kotlin sealed interface 1:1):
+//   sel.id('btn-login')
+//     .below(sel.text(literal('Sign In')))
+//     .nth(0)
+//
+// Each fluent method returns a NEW Selector (immutable copy semantics).
+
+import { type Pattern, patternFromJson, patternToJson } from './Pattern.js'
+
+/** All-optional modifier set stacked onto a base Selector. */
+export interface Modifiers {
+  near?: Selector | undefined
+  below?: Selector | undefined
+  above?: Selector | undefined
+  leftOf?: Selector | undefined
+  rightOf?: Selector | undefined
+  inside?: Selector | undefined
+  ancestor?: Selector | undefined
+  nth?: number | undefined
+  first?: boolean | undefined
+  last?: boolean | undefined
+}
+
+/** Spatial-only anchor box (no index, no base). Used by `anchor()`. */
+export interface AnchorBox {
+  near?: Selector | undefined
+  below?: Selector | undefined
+  above?: Selector | undefined
+  leftOf?: Selector | undefined
+  rightOf?: Selector | undefined
+  inside?: Selector | undefined
+  ancestor?: Selector | undefined
+}
+
+/** Index-only modifier subset used by `anchor()`. */
+export interface IndexModifiers {
+  nth?: number | undefined
+  first?: boolean | undefined
+  last?: boolean | undefined
+}
+
+export type SelectorKind =
+  | 'id' | 'text' | 'label' | 'role'
+  | 'focused' | 'anchor' | 'localizedText'
+
+/** Discriminated union (kind tag for narrowing; wire-shape is untagged). */
+export type SelectorData =
+  | { kind: 'id'; id: string; modifiers: Modifiers }
+  | { kind: 'text'; text: Pattern; modifiers: Modifiers }
+  | { kind: 'label'; label: string; modifiers: Modifiers }
+  | { kind: 'role'; role: string; name?: Pattern | undefined; modifiers: Modifiers }
+  | { kind: 'focused' }
+  | { kind: 'anchor'; box: AnchorBox; index: IndexModifiers }
+  | { kind: 'localizedText'; map: Readonly<Record<string, string>>; modifiers: Modifiers }
+
+/**
+ * A11y selector — identifies a node in the tree.
+ *
+ * Wire JSON shape matches Rust smix-selector `#[serde(untagged)]`:
+ * discriminator is which key is present. Modifiers are flattened
+ * into the same JSON body. Implemented via [selectorToJson].
+ */
+export class Selector {
+  constructor(public readonly data: SelectorData) {}
+
+  // ---- Constructors -----------------------------------------------------
+
+  static id(value: string): Selector {
+    return new Selector({ kind: 'id', id: value, modifiers: {} })
+  }
+  static text(p: Pattern): Selector {
+    return new Selector({ kind: 'text', text: p, modifiers: {} })
+  }
+  static label(value: string): Selector {
+    return new Selector({ kind: 'label', label: value, modifiers: {} })
+  }
+  static role(value: string, name?: Pattern): Selector {
+    return new Selector({
+      kind: 'role',
+      role: value,
+      ...(name !== undefined ? { name } : {}),
+      modifiers: {},
+    })
+  }
+  static focused(): Selector {
+    return new Selector({ kind: 'focused' })
+  }
+  static anchor(box: AnchorBox, index: IndexModifiers = {}): Selector {
+    return new Selector({ kind: 'anchor', box, index })
+  }
+  static localizedText(map: Record<string, string>): Selector {
+    return new Selector({ kind: 'localizedText', map, modifiers: {} })
+  }
+
+  // ---- Fluent chaining --------------------------------------------------
+
+  below(anchor: Selector): Selector { return this.withMods(m => ({ ...m, below: anchor })) }
+  above(anchor: Selector): Selector { return this.withMods(m => ({ ...m, above: anchor })) }
+  leftOf(anchor: Selector): Selector { return this.withMods(m => ({ ...m, leftOf: anchor })) }
+  rightOf(anchor: Selector): Selector { return this.withMods(m => ({ ...m, rightOf: anchor })) }
+  near(anchor: Selector): Selector { return this.withMods(m => ({ ...m, near: anchor })) }
+  inside(anchor: Selector): Selector { return this.withMods(m => ({ ...m, inside: anchor })) }
+  ancestor(anchor: Selector): Selector { return this.withMods(m => ({ ...m, ancestor: anchor })) }
+  nth(i: number): Selector { return this.withMods(m => ({ ...m, nth: i })) }
+  first(): Selector { return this.withMods(m => ({ ...m, first: true })) }
+  last(): Selector { return this.withMods(m => ({ ...m, last: true })) }
+
+  private withMods(mutate: (m: Modifiers) => Modifiers): Selector {
+    const d = this.data
+    switch (d.kind) {
+      case 'id':
+        return new Selector({ ...d, modifiers: mutate(d.modifiers) })
+      case 'text':
+        return new Selector({ ...d, modifiers: mutate(d.modifiers) })
+      case 'label':
+        return new Selector({ ...d, modifiers: mutate(d.modifiers) })
+      case 'role':
+        return new Selector({ ...d, modifiers: mutate(d.modifiers) })
+      case 'localizedText':
+        return new Selector({ ...d, modifiers: mutate(d.modifiers) })
+      case 'focused':
+        return this  // no modifiers — no-op
+      case 'anchor': {
+        const proxy = mutate({})
+        const newIdx: IndexModifiers = {
+          ...(proxy.nth !== undefined ? { nth: proxy.nth } : d.index.nth !== undefined ? { nth: d.index.nth } : {}),
+          ...(proxy.first !== undefined ? { first: proxy.first } : d.index.first !== undefined ? { first: d.index.first } : {}),
+          ...(proxy.last !== undefined ? { last: proxy.last } : d.index.last !== undefined ? { last: d.index.last } : {}),
+        }
+        return new Selector({ ...d, index: newIdx })
+      }
+    }
+  }
+}
+
+// ---- JSON encoding (Rust-compatible untagged + flatten) -----------------
+
+function addModifiers(out: Record<string, unknown>, m: Modifiers): void {
+  if (m.near !== undefined) out.near = selectorToJsonValue(m.near)
+  if (m.below !== undefined) out.below = selectorToJsonValue(m.below)
+  if (m.above !== undefined) out.above = selectorToJsonValue(m.above)
+  if (m.leftOf !== undefined) out.leftOf = selectorToJsonValue(m.leftOf)
+  if (m.rightOf !== undefined) out.rightOf = selectorToJsonValue(m.rightOf)
+  if (m.inside !== undefined) out.inside = selectorToJsonValue(m.inside)
+  if (m.ancestor !== undefined) out.ancestor = selectorToJsonValue(m.ancestor)
+  if (m.nth !== undefined) out.nth = m.nth
+  if (m.first !== undefined) out.first = m.first
+  if (m.last !== undefined) out.last = m.last
+}
+
+function addAnchorBox(out: Record<string, unknown>, b: AnchorBox): void {
+  if (b.near !== undefined) out.near = selectorToJsonValue(b.near)
+  if (b.below !== undefined) out.below = selectorToJsonValue(b.below)
+  if (b.above !== undefined) out.above = selectorToJsonValue(b.above)
+  if (b.leftOf !== undefined) out.leftOf = selectorToJsonValue(b.leftOf)
+  if (b.rightOf !== undefined) out.rightOf = selectorToJsonValue(b.rightOf)
+  if (b.inside !== undefined) out.inside = selectorToJsonValue(b.inside)
+  if (b.ancestor !== undefined) out.ancestor = selectorToJsonValue(b.ancestor)
+}
+
+function addIndex(out: Record<string, unknown>, i: IndexModifiers): void {
+  if (i.nth !== undefined) out.nth = i.nth
+  if (i.first !== undefined) out.first = i.first
+  if (i.last !== undefined) out.last = i.last
+}
+
+/** Encode a Selector to its Rust-compatible untagged JSON value. */
+export function selectorToJsonValue(s: Selector): unknown {
+  const out: Record<string, unknown> = {}
+  const d = s.data
+  switch (d.kind) {
+    case 'id':
+      out.id = d.id
+      addModifiers(out, d.modifiers)
+      break
+    case 'text':
+      out.text = patternToJson(d.text)
+      addModifiers(out, d.modifiers)
+      break
+    case 'label':
+      out.label = d.label
+      addModifiers(out, d.modifiers)
+      break
+    case 'role':
+      out.role = d.role
+      if (d.name !== undefined) out.name = patternToJson(d.name)
+      addModifiers(out, d.modifiers)
+      break
+    case 'focused':
+      out.focused = true
+      break
+    case 'anchor': {
+      const box: Record<string, unknown> = {}
+      addAnchorBox(box, d.box)
+      out.anchor = box
+      addIndex(out, d.index)
+      break
+    }
+    case 'localizedText':
+      out.localizedText = d.map
+      addModifiers(out, d.modifiers)
+      break
+  }
+  return out
+}
+
+/** Encode a Selector to its Rust-compatible untagged JSON string. */
+export function encodeSelectorJson(s: Selector): string {
+  return JSON.stringify(selectorToJsonValue(s))
+}
+
+/** Decode a Rust-compatible untagged JSON value into a Selector. */
+export function selectorFromJsonValue(value: unknown): Selector {
+  if (typeof value !== 'object' || value === null) {
+    throw new Error(`Selector must be a JSON object, got: ${JSON.stringify(value)}`)
+  }
+  const obj = value as Record<string, unknown>
+
+  // Focused: explicit boolean field, highest-priority discriminator.
+  if (obj.focused === true) return Selector.focused()
+
+  // Anchor: nested box discriminator.
+  if (obj.anchor !== undefined && typeof obj.anchor === 'object' && obj.anchor !== null) {
+    const box = decodeAnchorBox(obj.anchor as Record<string, unknown>)
+    return Selector.anchor(box, decodeIndex(obj))
+  }
+
+  if (typeof obj.id === 'string') {
+    return new Selector({ kind: 'id', id: obj.id, modifiers: decodeModifiers(obj) })
+  }
+  if (obj.text !== undefined) {
+    return new Selector({ kind: 'text', text: patternFromJson(obj.text), modifiers: decodeModifiers(obj) })
+  }
+  if (typeof obj.label === 'string') {
+    return new Selector({ kind: 'label', label: obj.label, modifiers: decodeModifiers(obj) })
+  }
+  if (typeof obj.role === 'string') {
+    const name = obj.name !== undefined ? patternFromJson(obj.name) : undefined
+    return new Selector({
+      kind: 'role',
+      role: obj.role,
+      ...(name !== undefined ? { name } : {}),
+      modifiers: decodeModifiers(obj),
+    })
+  }
+  if (obj.localizedText !== undefined && typeof obj.localizedText === 'object' && obj.localizedText !== null) {
+    return new Selector({
+      kind: 'localizedText',
+      map: obj.localizedText as Record<string, string>,
+      modifiers: decodeModifiers(obj),
+    })
+  }
+  throw new Error(`Selector JSON missing recognized discriminator: ${JSON.stringify(obj)}`)
+}
+
+function decodeModifiers(obj: Record<string, unknown>): Modifiers {
+  const m: Modifiers = {}
+  if (obj.near !== undefined) m.near = selectorFromJsonValue(obj.near)
+  if (obj.below !== undefined) m.below = selectorFromJsonValue(obj.below)
+  if (obj.above !== undefined) m.above = selectorFromJsonValue(obj.above)
+  if (obj.leftOf !== undefined) m.leftOf = selectorFromJsonValue(obj.leftOf)
+  if (obj.rightOf !== undefined) m.rightOf = selectorFromJsonValue(obj.rightOf)
+  if (obj.inside !== undefined) m.inside = selectorFromJsonValue(obj.inside)
+  if (obj.ancestor !== undefined) m.ancestor = selectorFromJsonValue(obj.ancestor)
+  if (typeof obj.nth === 'number') m.nth = obj.nth
+  if (typeof obj.first === 'boolean') m.first = obj.first
+  if (typeof obj.last === 'boolean') m.last = obj.last
+  return m
+}
+
+function decodeAnchorBox(obj: Record<string, unknown>): AnchorBox {
+  const b: AnchorBox = {}
+  if (obj.near !== undefined) b.near = selectorFromJsonValue(obj.near)
+  if (obj.below !== undefined) b.below = selectorFromJsonValue(obj.below)
+  if (obj.above !== undefined) b.above = selectorFromJsonValue(obj.above)
+  if (obj.leftOf !== undefined) b.leftOf = selectorFromJsonValue(obj.leftOf)
+  if (obj.rightOf !== undefined) b.rightOf = selectorFromJsonValue(obj.rightOf)
+  if (obj.inside !== undefined) b.inside = selectorFromJsonValue(obj.inside)
+  if (obj.ancestor !== undefined) b.ancestor = selectorFromJsonValue(obj.ancestor)
+  return b
+}
+
+function decodeIndex(obj: Record<string, unknown>): IndexModifiers {
+  const i: IndexModifiers = {}
+  if (typeof obj.nth === 'number') i.nth = obj.nth
+  if (typeof obj.first === 'boolean') i.first = obj.first
+  if (typeof obj.last === 'boolean') i.last = obj.last
+  return i
+}

package/src/SelectorResolver.ts

@@ -0,0 +1,76 @@
+// v7.5 c1 — SelectorResolver injection boundary.
+//
+// Mirror Kotlin v7.4 c2 R-Kotlin-A: real impl wraps Rust FFI core
+// (in TS via HTTP runner or future ffi-napi binding); mock impl for
+// vitest. Lambda-style fn interface keeps the abstraction minimal.
+
+export type SelectorResolver = (
+  treeJson: string,
+  selectorJson: string,
+) => Promise<readonly string[]>
+
+/**
+ * v7.6 c1 — labels resolver wrapping Rust `resolve_selector_labels`
+ * (each match's `.label`; empty string when None). Used by
+ * Locator.toHaveCount + Locator.toHaveLabel.
+ */
+export type LabelsResolver = (
+  treeJson: string,
+  selectorJson: string,
+) => Promise<readonly string[]>
+
+/**
+ * Mock resolver for vitest unit tests. Pre-registered selectorJson →
+ * id list mappings; falls back to empty list for unknown selectors.
+ * Mirrors Kotlin MockSelectorResolver from v7.4 c2.
+ */
+export class MockSelectorResolver {
+  readonly returnMap = new Map<string, readonly string[]>()
+  throwOnNext: Error | null = null
+  readonly calls: { treeJson: string; selectorJson: string }[] = []
+
+  resolve: SelectorResolver = async (treeJson, selectorJson) => {
+    this.calls.push({ treeJson, selectorJson })
+    const t = this.throwOnNext
+    if (t !== null) {
+      this.throwOnNext = null
+      throw t
+    }
+    return this.returnMap.get(selectorJson) ?? []
+  }
+
+  /** Register a single-hit response for the given selector JSON key. */
+  registerHit(selectorJson: string, id: string): void {
+    this.returnMap.set(selectorJson, [id])
+  }
+
+  /** Register a multi-hit response. */
+  registerHits(selectorJson: string, ids: readonly string[]): void {
+    this.returnMap.set(selectorJson, ids)
+  }
+}
+
+/**
+ * v7.6 c1 — Mock labels resolver for vitest tests. Pre-registered
+ * selectorJson → label list mappings. Mirrors Kotlin MockLabelsResolver.
+ */
+export class MockLabelsResolver {
+  readonly returnMap = new Map<string, readonly string[]>()
+  throwOnNext: Error | null = null
+  readonly calls: { treeJson: string; selectorJson: string }[] = []
+
+  resolve: LabelsResolver = async (treeJson, selectorJson) => {
+    this.calls.push({ treeJson, selectorJson })
+    const t = this.throwOnNext
+    if (t !== null) {
+      this.throwOnNext = null
+      throw t
+    }
+    return this.returnMap.get(selectorJson) ?? []
+  }
+
+  /** Register the matched-labels list for a selector. */
+  registerLabels(selectorJson: string, labels: readonly string[]): void {
+    this.returnMap.set(selectorJson, labels)
+  }
+}