Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/adr/0014-session-ref-frame-lifetime.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,7 @@ These outputs are partial external publications:
- Snapshot diffs.
- Digests that omit the namespace.
- `find`.
- `audit` finding refs.
- Settled diffs/tails.
- Replay divergence screens.

Expand Down Expand Up @@ -400,7 +401,7 @@ Every other one-target constraint in this decision stays unchanged.

### Partial issuance and MCP

`find`, settled diffs/tails, and replay divergence screens publish only the refs that they actually return.
`find`, `audit`, settled diffs/tails, and replay divergence screens publish only the refs that they actually return.
They must not call a whole-frame "refs issued" marker.

Read-only `find` may partially publish its returned ref.
Expand Down
4 changes: 4 additions & 0 deletions packages/capture-kit/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -270,6 +270,10 @@
"types": "./src/snapshot/scroll-edge-state.ts",
"default": "./src/snapshot/scroll-edge-state.ts"
},
"./snapshot-audit": {
"types": "./src/snapshot/snapshot-audit.ts",
"default": "./src/snapshot/snapshot-audit.ts"
},
"./snapshot-baseline": {
"types": "./src/snapshot-baseline.ts",
"default": "./src/snapshot-baseline.ts"
Expand Down
315 changes: 315 additions & 0 deletions packages/capture-kit/src/snapshot/__tests__/snapshot-audit.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,315 @@
import { describe, expect, test } from 'vitest';
import type { AuditContext, AuditFinding } from '@agent-device/contracts/capture';
import type { SnapshotNode } from '@agent-device/kernel/snapshot';
import { auditSnapshot } from '../snapshot-audit.ts';

const IOS: AuditContext = { platform: 'ios', truncated: false };
const ANDROID: AuditContext = { platform: 'android', pixelDensity: 2, truncated: false };

function node(index: number, fields: Partial<SnapshotNode> = {}): SnapshotNode {
return {
index,
ref: `e${index}`,
type: 'Button',
hittable: true,
rect: { x: 0, y: index * 100, width: 100, height: 60 },
...fields,
};
}

function audit(nodes: SnapshotNode[], context: AuditContext = IOS) {
return auditSnapshot(nodes, context);
}

function summarize(findings: AuditFinding[]): string[] {
return findings.map((finding) => `${finding.kind} ${finding.ref}`);
}

describe('small-target', () => {
test('reports a control below 44pt on iOS with its size and the recommendation', () => {
const { findings } = audit([
node(1, { label: 'Menu', rect: { x: 0, y: 0, width: 30, height: 44 } }),
]);
expect(findings).toEqual([
expect.objectContaining({
kind: 'small-target',
severity: 'warning',
ref: '@e1',
detail: { unit: 'pt', width: 30, height: 44, recommendedSize: 44 },
}),
]);
});

test('accepts a 44pt control that float layout reports as 43.67', () => {
const { findings } = audit([
node(1, { label: 'OK', rect: { x: 0, y: 0, width: 43.67, height: 44 } }),
]);
expect(findings).toEqual([]);
});

test('divides Android pixels by the captured density before comparing with 48dp', () => {
const small = { x: 0, y: 0, width: 80, height: 100 };
expect(summarize(audit([node(1, { label: 'A', rect: small })], ANDROID).findings)).toEqual([
'small-target @e1',
]);
// 100px is 100dp at density 1, so the same rect passes there.
expect(
audit([node(1, { label: 'A', rect: small })], {
platform: 'android',
pixelDensity: 1,
truncated: false,
}).findings,
).toEqual([]);
});

test('skips the check and says why when Android density is unknown', () => {
const result = audit([node(1, { label: 'A', rect: { x: 0, y: 0, width: 10, height: 10 } })], {
platform: 'android',
truncated: false,
});
expect(result.findings).toEqual([]);
expect(result.limitations).toEqual([expect.stringContaining('did not report display density')]);
});

test('skips the check on a TV target', () => {
const result = audit([node(1, { label: 'A', rect: { x: 0, y: 0, width: 10, height: 10 } })], {
platform: 'ios',
target: 'tv',
truncated: false,
});
expect(result.findings).toEqual([]);
expect(result.limitations).toEqual([expect.stringContaining('tv targets')]);
});

test('ignores a disabled control, an offscreen control, and a keyboard key', () => {
const tiny = { x: 0, y: 0, width: 20, height: 20 };
const { findings } = audit([
node(1, { label: 'Off', enabled: false, rect: tiny }),
node(2, { label: 'Away', hittable: false, rect: tiny }),
node(3, { label: 'q', keyboardOwned: true, rect: tiny }),
]);
expect(findings).toEqual([]);
});

test('ignores a link inside a text container, but not a link beside text or at the root', () => {
const tiny = { x: 0, y: 0, width: 60, height: 18 };
const inText = audit([
node(0, { type: 'StaticText', label: 'Read the terms', hittable: false }),
node(1, { parentIndex: 0, type: 'Link', label: 'terms', rect: tiny }),
]);
expect(inText.findings).toEqual([]);

const besideText = audit([
node(0, { type: 'Other', hittable: false }),
node(1, { parentIndex: 0, type: 'StaticText', label: 'Read the' }),
node(2, { parentIndex: 0, type: 'Link', label: 'terms', rect: tiny }),
]);
expect(summarize(besideText.findings)).toEqual(['small-target @e2']);

const atRoot = audit([
node(0, { type: 'StaticText', label: 'Title' }),
node(1, { type: 'Link', label: 'terms', rect: tiny }),
]);
expect(summarize(atRoot.findings)).toEqual(['small-target @e1']);
});
});

describe('missing-name', () => {
test('reports a button whose only text is an identifier or a value', () => {
const { findings } = audit([
node(1, { identifier: 'menu-button' }),
node(2, { value: 'On' }),
node(3, { label: 'com.example:id/menu' }),
]);
expect(summarize(findings)).toEqual([
'missing-name @e1',
'missing-name @e2',
'missing-name @e3',
]);
});

test('accepts a label, an Android content description, or a named descendant', () => {
const { findings } = audit([
node(1, { label: 'Save' }),
node(5, { label: 'Dictate', identifier: 'Dictate' }),
node(2, { contentDescription: 'Close' }),
node(3),
node(4, { parentIndex: 3, type: 'StaticText', label: 'Next' }),
]);
expect(findings).toEqual([]);
});

test('does not treat typed field content as its name, but accepts a placeholder or hint label', () => {
const { findings } = audit([
node(1, { type: 'TextField', label: 'hello', value: 'hello' }),
node(2, { type: 'TextField', value: 'hello', placeholder: 'Email' }),
node(3, { type: 'SearchField', label: 'Search', value: 'Search', placeholder: 'Search' }),
]);
expect(summarize(findings)).toEqual(['missing-name @e1']);
});

test('reports an unnamed image button but not a decorative image', () => {
const { findings } = audit([
node(1, { type: 'android.widget.ImageButton' }),
node(2, { type: 'Image' }),
node(3, { type: 'android.widget.ImageView' }),
]);
expect(summarize(findings)).toEqual(['missing-name @e1']);
});

test('does not read a container class as a control', () => {
const { findings } = audit([
node(1, { type: 'android.widget.RadioGroup' }),
node(2, { type: 'android.widget.TabLayout' }),
]);
expect(findings).toEqual([]);
});
});

describe('duplicate wrappers', () => {
const small = { x: 0, y: 0, width: 20, height: 20 };

test('collapses a control that is the only child of a same-role control that reports the same kinds', () => {
const { findings } = audit([
node(1, { rect: small }),
node(2, { parentIndex: 1, rect: small }),
]);
expect(summarize(findings)).toEqual(['small-target @e1', 'missing-name @e1']);
});

test('keeps the child when the parent has a sibling child or another role', () => {
const withSibling = audit([
node(1, { label: 'A', rect: small }),
node(2, { parentIndex: 1, label: 'B', rect: small }),
node(3, { parentIndex: 1, type: 'StaticText', label: 'x' }),
]);
expect(summarize(withSibling.findings)).toEqual(['small-target @e1', 'small-target @e2']);

const otherRole = audit([
node(1, { label: 'A', rect: small }),
node(2, { parentIndex: 1, type: 'Switch', label: 'B', rect: small }),
]);
expect(summarize(otherRole.findings)).toEqual(['small-target @e1', 'small-target @e2']);
});

test('keeps the child when the parent does not report that kind', () => {
const disabledParent = audit([
node(1, { label: 'A', enabled: false, rect: small }),
node(2, { parentIndex: 1, label: 'B', rect: small }),
]);
expect(summarize(disabledParent.findings)).toEqual(['small-target @e2']);

const largeParent = audit([
node(1, { label: 'A', rect: { x: 0, y: 0, width: 100, height: 100 } }),
node(2, { parentIndex: 1, label: 'B', rect: small }),
]);
expect(summarize(largeParent.findings)).toEqual(['small-target @e2']);

const refLessParent = audit([
node(1, { ref: undefined, label: 'A', rect: small }),
node(2, { parentIndex: 1, label: 'B', rect: small }),
]);
expect(summarize(refLessParent.findings)).toEqual(['small-target @e2']);
});

test('does not collapse unrelated controls that share a rect', () => {
const { findings } = audit([
node(1, { label: 'A', rect: small }),
node(2, { label: 'B', rect: small }),
]);
expect(summarize(findings)).toEqual(['small-target @e1', 'small-target @e2']);
});
});

describe('covered-control', () => {
const covered = { interactionBlocked: 'covered', hittable: false } as const;

test('reports a covered control as an observation', () => {
const { findings } = audit([node(1, { label: 'Pay', ...covered })]);
expect(findings).toEqual([
expect.objectContaining({ kind: 'covered-control', severity: 'observation', ref: '@e1' }),
]);
});

test('ignores covered images and text, which no touch targets', () => {
const { findings } = audit([
node(1, { type: 'Image', label: 'Overlay', ...covered }),
node(2, { type: 'StaticText', label: 'Title', ...covered }),
]);
expect(findings).toEqual([]);
});

test('collapses the only child of a covered row, but keeps a child that has siblings', () => {
const wrapped = audit([
node(1, { type: 'Cell', ...covered }),
node(2, { parentIndex: 1, label: 'Passcode', ...covered }),
]);
expect(summarize(wrapped.findings)).toEqual(['covered-control @e1']);

const withSibling = audit([
node(1, { type: 'Cell', ...covered }),
node(2, { parentIndex: 1, label: 'Passcode', ...covered }),
node(3, { parentIndex: 1, label: 'Info', ...covered }),
]);
expect(summarize(withSibling.findings)).toEqual([
'covered-control @e1',
'covered-control @e2',
'covered-control @e3',
]);
});

test('keeps a covered control under a covered container that is neither control nor row', () => {
const { findings } = audit([
node(1, { type: 'Other', ...covered }),
node(2, { parentIndex: 1, label: 'Pay', ...covered }),
]);
expect(summarize(findings)).toEqual(['covered-control @e2']);
});

test('keeps a covered child whose parent is not covered', () => {
const { findings } = audit([
node(1, { type: 'Cell' }),
node(2, { parentIndex: 1, label: 'A', ...covered }),
]);
expect(summarize(findings)).toEqual(['covered-control @e2']);
});

test('does not run the other checks on a covered control', () => {
const { findings } = audit([
node(1, { ...covered, rect: { x: 0, y: 0, width: 10, height: 10 } }),
]);
expect(summarize(findings)).toEqual(['covered-control @e1']);
});
});

describe('scope', () => {
test('skips system bars and nodes without a ref', () => {
const { findings } = audit([node(1, { systemBar: 'navigation' }), node(2, { ref: undefined })]);
expect(findings).toEqual([]);
});

test('marks a truncated capture partial and says controls past the cut were not audited', () => {
const result = audit([node(1, { label: 'A' })], { ...IOS, truncated: true });
expect(result.checks).toEqual({ snapshot: 'partial' });
expect(result.limitations).toEqual([expect.stringContaining('truncated')]);
});

test('keeps unknown truncation unknown instead of calling the capture complete', () => {
const result = audit([node(1, { label: 'A' })], { platform: 'ios' });
expect(result.checks).toEqual({ snapshot: 'unknown' });
expect(result.limitations).toEqual([expect.stringContaining('cannot report truncation')]);
});

test('audits web ARIA roles for names and coverage but not size', () => {
const result = audit(
[
node(1, { type: 'button' }),
node(2, { type: 'textbox', label: 'Email' }),
node(3, { type: 'link', label: 'Home', interactionBlocked: 'covered', hittable: false }),
],
{ platform: 'web', truncated: false },
);
expect(summarize(result.findings)).toEqual(['missing-name @e1', 'covered-control @e3']);
expect(result.limitations).toEqual([expect.stringContaining('web rects')]);
});
});
Loading
Loading