Skip to content

Commit 6c1c562

Browse files
committed
refactor(capture-kit): share glyph drawing and recording script lookup
1 parent a798792 commit 6c1c562

9 files changed

Lines changed: 315 additions & 117 deletions

File tree

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
import { describe, expect, test } from 'vitest';
2+
import { BLACK, solidPng, WHITE } from './png-pixels.fixtures.ts';
3+
import { PNG } from './png.ts';
4+
import {
5+
drawPngGlyphText,
6+
measurePngGlyphText,
7+
measurePngGlyphTextAdvance,
8+
measurePngGlyphTextHeight,
9+
} from './png-glyph-text.ts';
10+
11+
function countPixels(png: PNG, color: readonly number[]): number {
12+
let count = 0;
13+
for (let offset = 0; offset < png.data.length; offset += 4) {
14+
if (
15+
png.data[offset] === color[0] &&
16+
png.data[offset + 1] === color[1] &&
17+
png.data[offset + 2] === color[2] &&
18+
png.data[offset + 3] === color[3]
19+
) {
20+
count += 1;
21+
}
22+
}
23+
return count;
24+
}
25+
26+
describe('png glyph text', () => {
27+
test('measures the advance the painter actually uses', () => {
28+
expect(measurePngGlyphText('12')).toBe(11);
29+
expect(measurePngGlyphText('')).toBe(0);
30+
expect(measurePngGlyphText('12', 2)).toBe(22);
31+
expect(measurePngGlyphTextHeight()).toBe(7);
32+
expect(measurePngGlyphTextHeight(2)).toBe(14);
33+
});
34+
35+
test('paints the timestamp characters a contact sheet prints', () => {
36+
for (const text of ['0', '9', ':', '.', '00:00:01.234']) {
37+
const png = solidPng(140, 12, BLACK);
38+
drawPngGlyphText(png, { x: 2, y: 2, text, color: WHITE });
39+
expect(countPixels(png, WHITE), text).toBeGreaterThan(0);
40+
}
41+
});
42+
43+
test('scales a glyph to whole blocks so a label stays crisp', () => {
44+
const single = solidPng(40, 12, BLACK);
45+
drawPngGlyphText(single, { x: 2, y: 2, text: '1', color: WHITE });
46+
const doubled = solidPng(40, 20, BLACK);
47+
drawPngGlyphText(doubled, { x: 2, y: 2, text: '1', color: WHITE, scale: 2 });
48+
49+
expect(countPixels(doubled, WHITE)).toBe(countPixels(single, WHITE) * 4);
50+
});
51+
52+
test('advances past a character the table does not cover', () => {
53+
const blank = solidPng(40, 12, BLACK);
54+
drawPngGlyphText(blank, { x: 2, y: 2, text: 'z', color: WHITE });
55+
expect(countPixels(blank, WHITE)).toBe(0);
56+
57+
const shifted = solidPng(40, 12, BLACK);
58+
drawPngGlyphText(shifted, { x: 2, y: 2, text: 'z1', color: WHITE });
59+
const aligned = solidPng(40, 12, BLACK);
60+
drawPngGlyphText(aligned, {
61+
x: 2 + measurePngGlyphTextAdvance('z'),
62+
y: 2,
63+
text: '1',
64+
color: WHITE,
65+
});
66+
67+
expect(shifted.data.equals(aligned.data)).toBe(true);
68+
});
69+
70+
test('clips at the image edge instead of writing past it', () => {
71+
const png = solidPng(4, 4, BLACK);
72+
expect(() =>
73+
drawPngGlyphText(png, { x: -3, y: -3, text: '00:00', color: WHITE, scale: 2 }),
74+
).not.toThrow();
75+
expect(png.data.length).toBe(4 * 4 * 4);
76+
});
77+
});
Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
import type { PNG } from './png.ts';
2+
3+
/**
4+
* The bitmap glyph table both capture annotators paint with: the `eN` badges the screenshot ref
5+
* overlay prints, and the elapsed-time labels a contact sheet prints. It covers the characters
6+
* those labels are built from — digits, the separator and decimal point of a timestamp, and the
7+
* `e` ref prefix — and nothing else, so an unsupported character paints as blank rather than
8+
* inventing a shape nobody reviewed.
9+
*/
10+
export type PngGlyphColor = readonly [number, number, number, number];
11+
12+
const GLYPH_WIDTH = 5;
13+
const GLYPH_HEIGHT = 7;
14+
const GLYPH_SPACING = 1;
15+
const GLYPH_WIDTH_PITCH = GLYPH_WIDTH + GLYPH_SPACING;
16+
17+
const FONT: Record<string, readonly string[]> = {
18+
e: ['01110', '10000', '11110', '10000', '10000', '10001', '01110'],
19+
'0': ['01110', '10001', '10011', '10101', '11001', '10001', '01110'],
20+
'1': ['00100', '01100', '00100', '00100', '00100', '00100', '01110'],
21+
'2': ['01110', '10001', '00001', '00010', '00100', '01000', '11111'],
22+
'3': ['11110', '00001', '00001', '01110', '00001', '00001', '11110'],
23+
'4': ['00010', '00110', '01010', '10010', '11111', '00010', '00010'],
24+
'5': ['11111', '10000', '10000', '11110', '00001', '00001', '11110'],
25+
'6': ['01110', '10000', '10000', '11110', '10001', '10001', '01110'],
26+
'7': ['11111', '00001', '00010', '00100', '01000', '01000', '01000'],
27+
'8': ['01110', '10001', '10001', '01110', '10001', '10001', '01110'],
28+
'9': ['01110', '10001', '10001', '01111', '00001', '00001', '01110'],
29+
':': ['00000', '00100', '00100', '00000', '00100', '00100', '00000'],
30+
'.': ['00000', '00000', '00000', '00000', '00000', '00110', '00110'],
31+
} as const;
32+
33+
/** Width the painted text actually occupies, with no trailing inter-character gap. */
34+
export function measurePngGlyphText(text: string, scale = 1): number {
35+
if (text === '') return 0;
36+
return measurePngGlyphTextAdvance(text, scale) - GLYPH_SPACING * scale;
37+
}
38+
39+
/** Distance the cursor moves, including the gap after the final character. */
40+
export function measurePngGlyphTextAdvance(text: string, scale = 1): number {
41+
return text.length * GLYPH_WIDTH_PITCH * scale;
42+
}
43+
44+
export function measurePngGlyphTextHeight(scale = 1): number {
45+
return GLYPH_HEIGHT * scale;
46+
}
47+
48+
/**
49+
* Paints `text` at `x, y` at the given integer scale, clipping at the image edge. A character the
50+
* table does not cover still advances the cursor, so a partially supported label keeps its layout.
51+
*/
52+
export function drawPngGlyphText(
53+
png: PNG,
54+
input: Readonly<{
55+
x: number;
56+
y: number;
57+
text: string;
58+
color: PngGlyphColor;
59+
scale?: number;
60+
}>,
61+
): void {
62+
const scale = input.scale ?? 1;
63+
let cursorX = input.x;
64+
for (const character of input.text.toLowerCase()) {
65+
const glyph = FONT[character];
66+
if (glyph) {
67+
for (let row = 0; row < glyph.length; row += 1) {
68+
for (let column = 0; column < glyph[row]!.length; column += 1) {
69+
if (glyph[row]![column] !== '1') continue;
70+
fillGlyphPixel(png, cursorX + column * scale, input.y + row * scale, scale, input.color);
71+
}
72+
}
73+
}
74+
cursorX += GLYPH_WIDTH_PITCH * scale;
75+
}
76+
}
77+
78+
function fillGlyphPixel(png: PNG, x: number, y: number, scale: number, color: PngGlyphColor): void {
79+
for (let row = 0; row < scale; row += 1) {
80+
for (let column = 0; column < scale; column += 1) {
81+
setPngPixel(png, x + column, y + row, color);
82+
}
83+
}
84+
}
85+
86+
export function setPngPixel(png: PNG, x: number, y: number, color: PngGlyphColor): void {
87+
if (x < 0 || y < 0 || x >= png.width || y >= png.height) return;
88+
const index = (png.width * y + x) * 4;
89+
png.data[index] = color[0];
90+
png.data[index + 1] = color[1];
91+
png.data[index + 2] = color[2];
92+
png.data[index + 3] = color[3];
93+
}
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import { PNG } from './png.ts';
2+
3+
/**
4+
* Decoded-frame builders for tests that reason about pixels: solid fills and one painted
5+
* rectangle, which is enough to name exactly what a test claims changed between two frames.
6+
*/
7+
8+
export type Rgba = readonly [number, number, number, number];
9+
export type Rectangle = Readonly<{ x: number; y: number; width: number; height: number }>;
10+
11+
export const BLACK: Rgba = [0, 0, 0, 255];
12+
export const WHITE: Rgba = [255, 255, 255, 255];
13+
export const RED: Rgba = [255, 0, 0, 255];
14+
15+
export function solidPng(width: number, height: number, color: Rgba = BLACK): PNG {
16+
const png = new PNG({ width, height });
17+
for (let offset = 0; offset < png.data.length; offset += 4) {
18+
png.data[offset] = color[0];
19+
png.data[offset + 1] = color[1];
20+
png.data[offset + 2] = color[2];
21+
png.data[offset + 3] = color[3];
22+
}
23+
return png;
24+
}
25+
26+
/** Paints one rectangle of `color` onto a copy of `source`, leaving the source untouched. */
27+
export function paintPng(source: PNG, rectangle: Rectangle, color: Rgba): PNG {
28+
const png = solidPng(source.width, source.height);
29+
source.data.copy(png.data);
30+
for (let row = rectangle.y; row < rectangle.y + rectangle.height; row += 1) {
31+
for (let column = rectangle.x; column < rectangle.x + rectangle.width; column += 1) {
32+
if (column < 0 || row < 0 || column >= png.width || row >= png.height) continue;
33+
const offset = (row * png.width + column) * 4;
34+
png.data[offset] = color[0];
35+
png.data[offset + 1] = color[1];
36+
png.data[offset + 2] = color[2];
37+
png.data[offset + 3] = color[3];
38+
}
39+
}
40+
return png;
41+
}
42+
43+
/** Fraction of the frame a rectangle covers, for tests that assert a ratio rather than a count. */
44+
export function rectangleShare(rectangle: Rectangle, width: number, height: number): number {
45+
return (rectangle.width * rectangle.height) / (width * height);
46+
}

‎packages/capture-kit/src/png-resize.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ export async function resizePngFile(
3939
await fs.writeFile(filePath, await encodePngAsync(resizePngBox(source, width, height)));
4040
}
4141

42-
function resizePngBox(source: PNG, width: number, height: number): PNG {
42+
export function resizePngBox(source: PNG, width: number, height: number): PNG {
4343
const output = new PNG({ width, height });
4444
for (let y = 0; y < height; y += 1) {
4545
const sourceTop = (y * source.height) / height;

‎packages/capture-kit/src/recording/__tests__/overlay.test.ts‎

Lines changed: 1 addition & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ vi.mock('../video.ts', () => ({
2828
waitForPlayableVideo: vi.fn(async () => {}),
2929
}));
3030

31-
import { buildRecordingScriptPathCandidates, overlayRecordingTouches } from '../overlay.ts';
31+
import { overlayRecordingTouches } from '../overlay.ts';
3232
import { AppError } from '@agent-device/kernel/errors';
3333
import { runCmd } from '@agent-device/host-kit/command';
3434

@@ -130,23 +130,3 @@ test('overlay forwards the requested high export preset', async () => {
130130
expect.arrayContaining(['--events', telemetryPath, '--quality', 'high']),
131131
);
132132
});
133-
134-
test('recording script candidates include packaged dist apple-runner source', () => {
135-
const packageRoot = path.join(tmpDir, 'package');
136-
const scriptPath = path.join(
137-
packageRoot,
138-
'dist/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift',
139-
);
140-
fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
141-
fs.writeFileSync(scriptPath, 'print("overlay")\n');
142-
143-
const candidates = buildRecordingScriptPathCandidates(
144-
'recording-overlay.swift',
145-
path.join(packageRoot, 'dist/src'),
146-
packageRoot,
147-
tmpDir,
148-
);
149-
const firstExisting = candidates.find((candidate) => fs.existsSync(candidate));
150-
151-
expect(firstExisting).toBe(scriptPath);
152-
});

‎packages/capture-kit/src/recording/overlay.ts‎

Lines changed: 8 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,18 @@
11
import fs from 'node:fs';
22
import path from 'node:path';
3-
import { fileURLToPath } from 'node:url';
43
import { runCmd } from '@agent-device/host-kit/command';
54
import { AppError } from '@agent-device/kernel/errors';
6-
import { buildSwiftToolEnv, compileSwiftSourceFile } from './swift-cache.ts';
7-
import { findProjectRoot } from '@agent-device/host-kit/version';
5+
import {
6+
buildSwiftToolEnv,
7+
compileSwiftSourceFile,
8+
resolveRecordingScriptPath,
9+
} from './swift-cache.ts';
810
import { waitForPlayableVideo, waitForStableFile } from './video.ts';
911
import {
1012
DEFAULT_RECORDING_EXPORT_QUALITY,
1113
type RecordingExportQuality,
1214
} from '@agent-device/contracts/recording';
1315

14-
export function buildRecordingScriptPathCandidates(
15-
scriptName: string,
16-
moduleDir: string,
17-
projectRoot: string,
18-
cwd: string,
19-
): string[] {
20-
const sourceScriptPath = `apple/runner/AgentDeviceRunner/RecordingScripts/${scriptName}`;
21-
const packagedScriptPath = `dist/${sourceScriptPath}`;
22-
return [
23-
path.resolve(moduleDir, scriptName),
24-
path.resolve(projectRoot, sourceScriptPath),
25-
path.resolve(moduleDir, `../${sourceScriptPath}`),
26-
path.resolve(moduleDir, `../../${sourceScriptPath}`),
27-
path.resolve(moduleDir, `../../../${sourceScriptPath}`),
28-
path.resolve(projectRoot, packagedScriptPath),
29-
path.resolve(cwd, sourceScriptPath),
30-
];
31-
}
32-
33-
function resolveRecordingScriptPath(scriptName: string): string {
34-
const moduleDir = path.dirname(fileURLToPath(import.meta.url));
35-
const scriptCandidates = buildRecordingScriptPathCandidates(
36-
scriptName,
37-
moduleDir,
38-
findProjectRoot(),
39-
process.cwd(),
40-
);
41-
42-
for (const candidate of scriptCandidates) {
43-
if (fs.existsSync(candidate)) {
44-
return candidate;
45-
}
46-
}
47-
48-
throw new AppError('COMMAND_FAILED', `Missing recording helper script: ${scriptName}`, {
49-
hint: 'Ensure apple/runner/AgentDeviceRunner/RecordingScripts is present in this checkout or bundled under dist/apple/runner in the package.',
50-
scriptName,
51-
searchedPaths: scriptCandidates,
52-
});
53-
}
54-
55-
let overlayScriptPath: string | undefined;
56-
let exportSupportScriptPath: string | undefined;
57-
5816
export function getRecordingOverlaySupportWarning(
5917
hostPlatform: NodeJS.Platform = process.platform,
6018
): string | undefined {
@@ -64,6 +22,9 @@ export function getRecordingOverlaySupportWarning(
6422
return 'touch overlay burn-in is only available on macOS hosts; returning raw video plus gesture telemetry';
6523
}
6624

25+
let overlayScriptPath: string | undefined;
26+
let exportSupportScriptPath: string | undefined;
27+
6728
function getOverlayScriptPath(): string {
6829
overlayScriptPath ??= resolveRecordingScriptPath('recording-overlay.swift');
6930
return overlayScriptPath;

‎packages/capture-kit/src/recording/swift-cache.test.ts‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,11 @@ vi.mock(import('@agent-device/host-kit/command'), async (importOriginal) => ({
1414
}));
1515

1616
import { runCmd } from '@agent-device/host-kit/command';
17-
import { compileSwiftSourceFile, compileSwiftSourceText } from './swift-cache.ts';
17+
import {
18+
buildRecordingScriptPathCandidates,
19+
compileSwiftSourceFile,
20+
compileSwiftSourceText,
21+
} from './swift-cache.ts';
1822

1923
const mockRunCmd = vi.mocked(runCmd);
2024

@@ -246,3 +250,23 @@ async function expectConcurrentCacheReuse(compile: () => Promise<string>): Promi
246250
expect(fs.readFileSync(firstExecutable, 'utf8')).toBe('compiled once');
247251
expect(mockRunCmd).toHaveBeenCalledTimes(1);
248252
}
253+
254+
test('recording script candidates include packaged dist apple-runner source', () => {
255+
const packageRoot = path.join(tmpDir, 'package');
256+
const scriptPath = path.join(
257+
packageRoot,
258+
'dist/apple/runner/AgentDeviceRunner/RecordingScripts/recording-overlay.swift',
259+
);
260+
fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
261+
fs.writeFileSync(scriptPath, 'print("overlay")\n');
262+
263+
const candidates = buildRecordingScriptPathCandidates(
264+
'recording-overlay.swift',
265+
path.join(packageRoot, 'dist/src'),
266+
packageRoot,
267+
tmpDir,
268+
);
269+
const firstExisting = candidates.find((candidate) => fs.existsSync(candidate));
270+
271+
expect(firstExisting).toBe(scriptPath);
272+
});

0 commit comments

Comments
 (0)