@erclx/canon 4.5.0 → 4.6.0

package/src/driver/drive.ts

@@ -0,0 +1,184 @@
+import { chromium } from 'playwright-core'
+import type { Browser, Page } from 'playwright-core'
+import { isBrowserMissing, isServerUnreachable } from '@/browser/engine'
+import { probeDetails } from '@/driver/probes/details'
+import {
+  probeDiagramGeometry,
+  probeDiagramStrokes,
+} from '@/driver/probes/diagram'
+import { probeFocus } from '@/driver/probes/focus'
+import { describeViewport } from '@/driver/probes/viewport'
+import type { Viewport } from '@/driver/probes/viewport'
+import { runStep, stepProbes } from '@/driver/steps'
+import type {
+  DriverPlan,
+  Finding,
+  PlacedFinding,
+  ProbeName,
+} from '@/driver/steps'
+
+/**
+ * Walks a page through a caller's interaction sequence and measures each state
+ * it reaches. Every browser reference the driver adds lives here, and
+ * `src/commands/driver.ts` reaches it through a dynamic import so no other
+ * command resolves the engine at startup.
+ *
+ * Like `@/demo/drive` and `@/inventory/walk`, and unlike `@/capture/render`,
+ * this module ships. A command whose whole purpose is measuring someone else's
+ * page cannot stay toolkit-only, and nothing here reaches into `@/capture/`,
+ * which `files` in `package.json` excludes from the published package, so the
+ * two surfaces move independently.
+ *
+ * What separates it from `canon capture` is the axis it adds. A render answers
+ * about a page as it loads, and every defect that exists only after a menu
+ * opens, an answer is chosen, or the page scrolls is invisible to one. Probes
+ * therefore run after a step rather than on arrival, and a run reaches the load
+ * state by opening with a `wait` step of its own. That matters most where
+ * capture does not run, since it is toolkit-only and this command is then the
+ * only thing measuring the page at all.
+ */
+
+/** Each probe keyed by the name a caller writes in the run. */
+const PROBES: Record<ProbeName, (page: Page) => Promise<Finding[]>> = {
+  focus: probeFocus,
+  details: probeDetails,
+  'diagram-geometry': probeDiagramGeometry,
+  'diagram-strokes': probeDiagramStrokes,
+}
+
+export interface DriveOptions {
+  readonly url: string
+  readonly plan: DriverPlan
+}
+
+/** One step measured at one viewport, so a sweep reads as passes rather than a total. */
+export interface PassReading {
+  readonly viewport: string
+  readonly step: string
+  readonly probes: number
+  readonly findings: number
+}
+
+export type DriverRefusal =
+  | 'browser-missing'
+  | 'server-unreachable'
+  | 'drive-failed'
+
+export type DriverResult =
+  | {
+      readonly status: 'driven'
+      readonly findings: readonly PlacedFinding[]
+      readonly passes: readonly PassReading[]
+      readonly durationMs: number
+    }
+  | {
+      readonly status: 'failed'
+      readonly reason: DriverRefusal
+      readonly message: string
+    }
+
+function failed(reason: DriverRefusal, error: unknown): DriverResult {
+  return {
+    status: 'failed',
+    reason,
+    message: error instanceof Error ? error.message : String(error),
+  }
+}
+
+export async function drive(options: DriveOptions): Promise<DriverResult> {
+  const started = Date.now()
+
+  let browser: Browser
+  try {
+    browser = await chromium.launch()
+  } catch (error) {
+    return failed(
+      isBrowserMissing(error) ? 'browser-missing' : 'drive-failed',
+      error,
+    )
+  }
+
+  const findings: PlacedFinding[] = []
+  const passes: PassReading[] = []
+
+  try {
+    for (const viewport of options.plan.viewports) {
+      const pass = await driveViewport(browser, options, viewport)
+      findings.push(...pass.findings)
+      passes.push(...pass.passes)
+    }
+  } catch (error) {
+    return failed(
+      isServerUnreachable(error) ? 'server-unreachable' : 'drive-failed',
+      error,
+    )
+  } finally {
+    // Dropped rather than propagated, because a close that fails beside a drive
+    // that already failed would replace the refusal the caller is about to
+    // receive with a reason about teardown.
+    await browser.close().catch(() => undefined)
+  }
+
+  return {
+    status: 'driven',
+    findings,
+    passes,
+    durationMs: Date.now() - started,
+  }
+}
+
+/**
+ * One full pass of the sequence at one viewport, in a context of its own.
+ *
+ * A fresh context per height rather than a resize of the last one, because a
+ * step already run has left the page in a state the next height would inherit,
+ * and a sweep exists to ask the same question of each rather than to ask a
+ * later one of a page the earlier heights already drove.
+ */
+async function driveViewport(
+  browser: Browser,
+  options: DriveOptions,
+  viewport: Viewport,
+): Promise<{ findings: PlacedFinding[]; passes: PassReading[] }> {
+  const context = await browser.newContext({
+    viewport,
+    // Pointed the opposite way from `@/demo/drive`, which asks for the motion
+    // the interface was designed with. A measurement wants it suppressed, since
+    // geometry read mid-transition is a reading of neither state.
+    reducedMotion: 'reduce',
+  })
+
+  const findings: PlacedFinding[] = []
+  const passes: PassReading[] = []
+  const where = describeViewport(viewport)
+
+  try {
+    const page = await context.newPage()
+    await page.goto(options.url, { waitUntil: 'domcontentloaded' })
+
+    for (const step of options.plan.steps) {
+      await runStep(page, step)
+
+      const names = stepProbes(options.plan, step)
+      let count = 0
+      for (const name of names) {
+        const probe = PROBES[name]
+        for (const finding of await probe(page)) {
+          findings.push({ ...finding, step: step.name, viewport: where })
+          count += 1
+        }
+      }
+
+      passes.push({
+        viewport: where,
+        step: step.name,
+        probes: names.length,
+        findings: count,
+      })
+    }
+  } finally {
+    await context.close().catch(() => undefined)
+  }
+
+  return { findings, passes }
+}

package/src/driver/probes/details.ts

@@ -0,0 +1,116 @@
+import type { Page } from 'playwright-core'
+import type { Finding } from '@/driver/steps'
+
+/**
+ * Measures every `<details>` on the page twice, once shut and once open, and
+ * judges only the open reading.
+ *
+ * Two lessons meet here and they pull opposite ways. A closed `<details>` still
+ * reports a layout box and the box is nonsense: at 390 pixels wide a shut menu
+ * measures 13, so its rows read as 18-pixel tap targets hanging off the
+ * viewport, which is where 134 false findings came from in a single run.
+ * Filtering the closed ones out then opens a blind spot the same size, since
+ * the one real menu defect on that page was an open dropdown sitting 35 pixels
+ * off a phone screen and true only while open. Neither reading alone is enough,
+ * so both are taken and the closed one is carried as context rather than judged.
+ *
+ * Discovery is automatic rather than selector-driven. The real defect was
+ * missed because nobody thought to name that menu, and a probe that takes a
+ * selector reproduces that failure every time the author's attention is the
+ * thing at fault.
+ */
+
+/** The smallest a control may be before a finger cannot reliably hit it. */
+const MIN_TAP_PX = 24
+
+/** Ignores a sub-pixel overhang, which is a rounding artifact rather than a defect. */
+const OVERFLOW_TOLERANCE_PX = 1
+
+export async function probeDetails(page: Page): Promise<Finding[]> {
+  const rows = await page.evaluate(
+    ([minTap, tolerance]: [number, number]) => {
+      const describe = (element: Element): string => {
+        const tag = element.tagName.toLowerCase()
+        if (element.id) return `${tag}#${element.id}`
+        const className = element.getAttribute('class')?.trim().split(/\s+/)[0]
+        return className ? `${tag}.${className}` : tag
+      }
+
+      const box = (element: Element) => {
+        const rect = element.getBoundingClientRect()
+        return {
+          left: rect.left,
+          right: rect.right,
+          width: rect.width,
+          height: rect.height,
+        }
+      }
+
+      const found: {
+        selector: string
+        detail: string
+        measured: string
+      }[] = []
+
+      const width = document.documentElement.clientWidth
+
+      for (const element of Array.from(document.querySelectorAll('details'))) {
+        if (!(element instanceof HTMLDetailsElement)) continue
+
+        // Named for the state it was actually in rather than assumed shut. A
+        // step that clicked the menu open leaves this reading an open one, and
+        // calling it shut would report a number as evidence of the opposite
+        // state to the one it was taken in.
+        const wasOpen = element.open
+        const entry = box(element)
+        const entryState = wasOpen ? 'already open' : 'shut'
+        element.open = true
+
+        const rows = Array.from(
+          element.querySelectorAll('a[href], button, [role="menuitem"], li'),
+        )
+
+        // The panel is routinely out of flow, so the element's own box stops at
+        // the summary and says nothing about where the menu landed. Every part
+        // is measured and the furthest overhang is the finding.
+        let worst: { part: Element; off: number; left: number } | undefined
+        for (const part of [element, ...element.querySelectorAll('*')]) {
+          const partBox = box(part)
+          if (partBox.width === 0 && partBox.height === 0) continue
+          const off = Math.max(partBox.right - width, -partBox.left)
+          if (off <= tolerance) continue
+          if (worst && off <= worst.off) continue
+          worst = { part, off, left: partBox.left }
+        }
+
+        if (worst) {
+          found.push({
+            selector: describe(worst.part),
+            detail: `sits ${Math.round(worst.off)}px outside the viewport once ${describe(element)} is open`,
+            measured: `open at left ${Math.round(worst.left)} in a ${width}px viewport, against an ${entryState} ${describe(element)} box of ${Math.round(entry.width)}x${Math.round(entry.height)} that measures nothing about where the panel lands`,
+          })
+        }
+
+        for (const row of rows) {
+          const item = box(row)
+          if (item.width === 0 && item.height === 0) continue
+          if (item.width >= minTap && item.height >= minTap) continue
+          found.push({
+            selector: `${describe(element)} ${describe(row)}`,
+            detail: `is ${Math.round(item.width)}x${Math.round(item.height)} once open, under the ${minTap}px minimum`,
+            measured: `read in the open state, since the ${entryState} box of ${Math.round(entry.width)}x${Math.round(entry.height)} reports every row inside it wrong`,
+          })
+        }
+
+        // Restored because the probe runs between the caller's own steps, and a
+        // menu this left hanging open is a state no later step asked for.
+        element.open = wasOpen
+      }
+
+      return found
+    },
+    [MIN_TAP_PX, OVERFLOW_TOLERANCE_PX] as [number, number],
+  )
+
+  return rows.map((row) => ({ probe: 'details' as const, ...row }))
+}

package/src/driver/probes/diagram.ts

@@ -0,0 +1,260 @@
+import type { Page } from 'playwright-core'
+import type { Finding } from '@/driver/steps'
+
+/**
+ * Reads SVG label geometry off the rendered page, in two probes that differ by
+ * what they compare a label against.
+ *
+ * Everything here is measured in the browser after `document.fonts.ready` and
+ * never computed from the markup, because a generated page is routinely
+ * authored against one font and rendered in another. A stylesheet restyling
+ * `figure svg text` to a hand face after the coordinates were picked against
+ * monospace moves every label, so a label that cleared a line at its authored
+ * width can overlap it once rendered and the markup still says it does not.
+ *
+ * `clientWidth` is not the reading. Comparing it to `scrollWidth` flags every
+ * label whose string is wider than its element box whether or not anything is
+ * actually cut, which is why both probes are geometry against other geometry.
+ */
+
+/**
+ * Trims the slack a text rect carries above and below the glyphs. Vertical
+ * only: a text rect is loose top and bottom and tight to the glyphs left and
+ * right, and a one-pixel horizontal inset was enough to pass a label overrunning
+ * a panel border by three tenths of a unit. Insetting the vertical band alone
+ * stayed free of false positives across 41 strokes.
+ */
+const VERTICAL_INSET_PX = 2
+
+/**
+ * How far two labels overlap before it counts. An SVG text rect is the full
+ * font box rather than the ink, so two properly spaced lines touch by a pixel
+ * and a zero threshold reports every one of them.
+ */
+const COLLISION_PX = 2
+
+/** Sampling interval along a stroke, in device pixels. */
+const STROKE_SAMPLE_PX = 2
+
+/** Bounds the sampling of one stroke, so a long path cannot stall the pass. */
+const MAX_STROKE_SAMPLES = 600
+
+export async function probeDiagramGeometry(page: Page): Promise<Finding[]> {
+  const rows = await page.evaluate(
+    async ([inset, collision]: [number, number]) => {
+      await document.fonts.ready
+
+      const describe = (element: Element): string => {
+        const owner = element.closest('svg')
+        const label = (element.textContent ?? '').trim().slice(0, 40)
+        const id = owner?.id ? `svg#${owner.id}` : 'svg'
+        return label ? `${id} text "${label}"` : `${id} text`
+      }
+
+      const insetRect = (element: Element) => {
+        const rect = element.getBoundingClientRect()
+        return {
+          left: rect.left,
+          right: rect.right,
+          top: rect.top + inset,
+          bottom: rect.bottom - inset,
+        }
+      }
+
+      const overlap = (
+        a: { left: number; right: number; top: number; bottom: number },
+        b: { left: number; right: number; top: number; bottom: number },
+      ) => ({
+        x: Math.min(a.right, b.right) - Math.max(a.left, b.left),
+        y: Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top),
+      })
+
+      const found: { selector: string; detail: string; measured: string }[] = []
+
+      for (const root of Array.from(document.querySelectorAll('svg'))) {
+        const painted = Array.from(root.querySelectorAll('*'))
+        const labels = Array.from(root.querySelectorAll('text'))
+        const frame = root.getBoundingClientRect()
+
+        for (const label of labels) {
+          const rect = insetRect(label)
+          if (rect.right <= rect.left || rect.bottom <= rect.top) continue
+
+          if (
+            rect.left < frame.left - collision ||
+            rect.right > frame.right + collision ||
+            rect.top < frame.top - collision ||
+            rect.bottom > frame.bottom + collision
+          ) {
+            found.push({
+              selector: describe(label),
+              detail: 'is painted outside its own frame',
+              measured: `label spans ${Math.round(rect.left)}..${Math.round(rect.right)} horizontally and ${Math.round(rect.top)}..${Math.round(rect.bottom)} vertically, against a frame of ${Math.round(frame.left)}..${Math.round(frame.right)} and ${Math.round(frame.top)}..${Math.round(frame.bottom)}, vertical inset ${inset}px`,
+            })
+          }
+
+          const order = painted.indexOf(label)
+          for (const shape of painted) {
+            if (shape === label) continue
+            if (shape.tagName.toLowerCase() === 'text') continue
+            if (getComputedStyle(shape).fill === 'none') continue
+            if (!shape.getBoundingClientRect) continue
+
+            const box = shape.getBoundingClientRect()
+            if (box.width === 0 || box.height === 0) continue
+
+            const hit = overlap(rect, {
+              left: box.left,
+              right: box.right,
+              top: box.top,
+              bottom: box.bottom,
+            })
+            if (hit.x <= collision || hit.y <= collision) continue
+
+            const after = painted.indexOf(shape) > order
+            found.push({
+              selector: describe(label),
+              detail: after
+                ? `is covered by a filled ${shape.tagName.toLowerCase()} painted after it`
+                : `sits over a filled ${shape.tagName.toLowerCase()} with no plate behind the glyphs`,
+              measured: `${Math.round(hit.x)}x${Math.round(hit.y)}px of overlap, vertical inset ${inset}px`,
+            })
+          }
+        }
+
+        for (let first = 0; first < labels.length; first += 1) {
+          for (let second = first + 1; second < labels.length; second += 1) {
+            const a = labels[first]
+            const b = labels[second]
+            if (!a || !b) continue
+
+            const hit = overlap(insetRect(a), insetRect(b))
+            if (hit.x <= collision || hit.y <= collision) continue
+
+            found.push({
+              selector: describe(a),
+              detail: `collides with ${describe(b)}`,
+              measured: `${Math.round(hit.x)}x${Math.round(hit.y)}px of overlap, past the ${collision}px threshold, vertical inset ${inset}px`,
+            })
+          }
+        }
+      }
+
+      return found
+    },
+    [VERTICAL_INSET_PX, COLLISION_PX] as [number, number],
+  )
+
+  return rows.map((row) => ({ probe: 'diagram-geometry' as const, ...row }))
+}
+
+/**
+ * Reports a stroke crossing a label, sampled along the stroke's own geometry.
+ *
+ * A bounding box cannot answer this. The first version of the occlusion probe
+ * counted a shape as occluding only when it carried a fill, which filtered out
+ * every `line` and every `fill="none"` panel border before the comparison ran,
+ * and a label sitting on an arrow passed every run until a person saw it. A
+ * diagonal connector's box also covers most of the diagram while the stroke
+ * itself touches almost none of it, so the box would report the opposite error
+ * once the fill filter came off.
+ *
+ * Both paint orders are findings. A stroke drawn after the label crosses the
+ * glyphs out, and one drawn before it shows through them, since SVG text
+ * carries no background plate of its own.
+ */
+export async function probeDiagramStrokes(page: Page): Promise<Finding[]> {
+  const rows = await page.evaluate(
+    async ([inset, interval, maxSamples]: [number, number, number]) => {
+      await document.fonts.ready
+
+      const describe = (element: Element): string => {
+        const owner = element.closest('svg')
+        const label = (element.textContent ?? '').trim().slice(0, 40)
+        const id = owner?.id ? `svg#${owner.id}` : 'svg'
+        return label ? `${id} text "${label}"` : `${id} text`
+      }
+
+      const insetRect = (element: Element) => {
+        const rect = element.getBoundingClientRect()
+        return {
+          left: rect.left,
+          right: rect.right,
+          top: rect.top + inset,
+          bottom: rect.bottom - inset,
+        }
+      }
+
+      const found: { selector: string; detail: string; measured: string }[] = []
+
+      for (const root of Array.from(document.querySelectorAll('svg'))) {
+        const painted = Array.from(root.querySelectorAll('*'))
+        const labels = Array.from(root.querySelectorAll('text'))
+        if (labels.length === 0) continue
+
+        for (const shape of painted) {
+          if (!(shape instanceof SVGGeometryElement)) continue
+          if (getComputedStyle(shape).stroke === 'none') continue
+
+          // Read off the shape rather than off the root, because
+          // `getPointAtLength` answers in the shape's own user space and a
+          // generated diagram nests almost everything under a transformed `g`.
+          // The root's matrix drops that translation, which puts every sampled
+          // point somewhere the label is not and reports the page clean.
+          const matrix = shape.getScreenCTM()
+          if (!matrix) continue
+
+          let length = 0
+          try {
+            length = shape.getTotalLength()
+          } catch {
+            continue
+          }
+          if (length === 0) continue
+
+          const samples = Math.min(
+            maxSamples,
+            Math.max(2, Math.ceil(length / interval)),
+          )
+          const order = painted.indexOf(shape)
+          const crossed = new Map<Element, number>()
+
+          for (let step = 0; step <= samples; step += 1) {
+            const point = shape.getPointAtLength((length * step) / samples)
+            const screen = new DOMPoint(point.x, point.y).matrixTransform(
+              matrix,
+            )
+
+            for (const label of labels) {
+              const rect = insetRect(label)
+              if (rect.bottom <= rect.top) continue
+              if (screen.x < rect.left || screen.x > rect.right) continue
+              if (screen.y < rect.top || screen.y > rect.bottom) continue
+              crossed.set(label, (crossed.get(label) ?? 0) + 1)
+            }
+          }
+
+          for (const [label, hits] of crossed) {
+            const after = order > painted.indexOf(label)
+            found.push({
+              selector: describe(label),
+              detail: after
+                ? `is crossed out by a ${shape.tagName.toLowerCase()} stroked after it`
+                : `is painted over a ${shape.tagName.toLowerCase()} stroke that shows through the glyphs`,
+              measured: `${hits} of ${samples + 1} points sampled along the stroke land inside the label, vertical inset ${inset}px`,
+            })
+          }
+        }
+      }
+
+      return found
+    },
+    [VERTICAL_INSET_PX, STROKE_SAMPLE_PX, MAX_STROKE_SAMPLES] as [
+      number,
+      number,
+      number,
+    ],
+  )
+
+  return rows.map((row) => ({ probe: 'diagram-strokes' as const, ...row }))
+}

package/src/driver/probes/focus.ts

@@ -0,0 +1,121 @@
+import type { Page } from 'playwright-core'
+import { enterKeyboardModality } from '@/browser/engine'
+import type { Finding } from '@/driver/steps'
+
+/**
+ * Reports every element that takes focus and changes nothing a person can see.
+ *
+ * The lesson is in the first line of the run rather than in the comparison. A
+ * probe that focuses each element and reads its computed outline reports every
+ * correctly styled element as unstyled, because `:focus-visible` does not match
+ * a scripted `.focus()` while the browser is in pointer modality. That version
+ * produced 27 false findings against a page whose rings were all present. One
+ * Tab press ahead of the read puts the page in keyboard modality and the rule
+ * matches for the rest of the pass, which is why `enterKeyboardModality` is a
+ * shared helper rather than a line here.
+ *
+ * The reader below is serialized to source and evaluated by the browser, so
+ * every helper it needs is declared inside its own body. A reference to
+ * anything at module scope typechecks and throws once the page calls it.
+ */
+
+/** The elements a keyboard reaches without the page authoring a tab order. */
+const FOCUSABLE =
+  'a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])'
+
+/** What a ring is allowed to move, read at rest and again under focus. */
+const PROPERTIES = [
+  'outlineStyle',
+  'outlineWidth',
+  'outlineColor',
+  'outlineOffset',
+  'boxShadow',
+  'borderColor',
+  'backgroundColor',
+  'color',
+  'textDecorationLine',
+] as const
+
+export async function probeFocus(page: Page): Promise<Finding[]> {
+  await enterKeyboardModality(page)
+
+  const rows = await page.evaluate(
+    ([query, properties]: [string, readonly string[]]) => {
+      const describe = (element: Element): string => {
+        const tag = element.tagName.toLowerCase()
+        if (element.id) return `${tag}#${element.id}`
+        const className = element.getAttribute('class')?.trim().split(/\s+/)[0]
+        return className ? `${tag}.${className}` : tag
+      }
+
+      const snapshot = (element: Element): string[] => {
+        const computed = getComputedStyle(element)
+        return properties.map(
+          (property) => computed[property as 'color'] as string,
+        )
+      }
+
+      // The modality press left one element focused, and reading its rest state
+      // while it still holds focus reports no difference for whatever ring it
+      // actually draws. Every element starts and ends this pass blurred.
+      const entry = document.activeElement
+      if (entry instanceof HTMLElement) entry.blur()
+
+      const found: { selector: string; visible: boolean; detail: string }[] = []
+
+      for (const element of Array.from(document.querySelectorAll(query))) {
+        if (!(element instanceof HTMLElement)) continue
+        // Tested by whether the element paints a box rather than by
+        // `offsetParent`, which is null for anything positioned `fixed` and
+        // would skip a pinned control that is plainly on screen.
+        if (element.getClientRects().length === 0) continue
+        if (getComputedStyle(element).visibility === 'hidden') continue
+
+        const rest = snapshot(element)
+        element.focus()
+        // An element the browser refuses to focus is skipped rather than
+        // reported. A disabled control has no ring by design, and folding it
+        // into the same row as a control that should have one and does not
+        // gives two findings one remedy.
+        if (document.activeElement !== element) {
+          element.blur()
+          continue
+        }
+
+        const focused = snapshot(element)
+        // An outline that resolves to `none` paints nothing, so a width, a
+        // color, or an offset moving underneath it is a computed difference a
+        // person cannot see. A stylesheet that clears `outline` for one control
+        // while a broader rule still sets `outline-offset` produces exactly
+        // that, and counting it would report the control as correctly ringed.
+        const blind =
+          focused[properties.indexOf('outlineStyle')] === 'none'
+            ? (property: string) => property.startsWith('outline')
+            : () => false
+        const moved = properties.filter(
+          (property, index) =>
+            rest[index] !== focused[index] && !blind(property),
+        )
+        element.blur()
+
+        found.push({
+          selector: describe(element),
+          visible: moved.length > 0,
+          detail: moved.join(', '),
+        })
+      }
+
+      return found
+    },
+    [FOCUSABLE, PROPERTIES] as [string, readonly string[]],
+  )
+
+  return rows
+    .filter((row) => !row.visible)
+    .map((row) => ({
+      probe: 'focus' as const,
+      selector: row.selector,
+      detail: 'takes keyboard focus and changes nothing visible',
+      measured: `no movement across ${PROPERTIES.length} properties under :focus-visible`,
+    }))
+}