@segnavia/capture 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 modstudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/geometry.d.ts

@@ -0,0 +1,17 @@
+import { Annotation, Box, TextDirection } from "@segnavia/format";
+//#region src/geometry.d.ts
+export declare const SIDES: readonly ["left", "right", "top", "bottom"];
+export type Side = (typeof SIDES)[number];
+export interface AnnotationSpec {
+  number?: number;
+  arrow?: Side | 'auto';
+  label?: string;
+  highlight?: boolean;
+}
+export interface Viewport {
+  width: number;
+  height: number;
+}
+export declare function chooseArrowSide(box: Box, viewport: Viewport, preferred?: Side | 'auto', direction?: TextDirection): Side;
+export declare function layoutAnnotation(box: Box, spec: AnnotationSpec, viewport: Viewport, direction?: TextDirection): Annotation;
+//#endregion

package/dist/geometry.js

@@ -0,0 +1,118 @@
+//#region src/geometry.ts
+const SIDES = [
+	"left",
+	"right",
+	"top",
+	"bottom"
+];
+const RING_PADDING = 6;
+const ARROW_LENGTH = 96;
+const ARROW_GAP = 10;
+const BADGE_OFFSET = 4;
+const EDGE_MARGIN = 8;
+function padBox(box, padding = RING_PADDING) {
+	return {
+		x: box.x - padding,
+		y: box.y - padding,
+		width: box.width + padding * 2,
+		height: box.height + padding * 2
+	};
+}
+function roomAround(box, viewport) {
+	return {
+		left: box.x,
+		right: viewport.width - (box.x + box.width),
+		top: box.y,
+		bottom: viewport.height - (box.y + box.height)
+	};
+}
+function chooseArrowSide(box, viewport, preferred = "auto", direction = "ltr") {
+	const room = roomAround(box, viewport);
+	if (preferred !== "auto") {
+		if (room[preferred] < 72) throw new Error(`There is ${Math.round(room[preferred])}px of room on the ${preferred}; an arrow needs 72px.`);
+		return preferred;
+	}
+	const order = direction === "rtl" ? [
+		"right",
+		"left",
+		"top",
+		"bottom"
+	] : SIDES;
+	return order.reduce((best, side) => room[side] > room[best] ? side : best, order[0]);
+}
+function arrowGeometry(ring, side, viewport) {
+	const center = {
+		x: ring.x + ring.width / 2,
+		y: ring.y + ring.height / 2
+	};
+	const room = roomAround(ring, viewport);
+	const span = Math.max(24, Math.min(ARROW_LENGTH, room[side] - ARROW_GAP - EDGE_MARGIN));
+	const left = ring.x - ARROW_GAP;
+	const right = ring.x + ring.width + ARROW_GAP;
+	const top = ring.y - ARROW_GAP;
+	const bottom = ring.y + ring.height + ARROW_GAP;
+	switch (side) {
+		case "left": return {
+			head: {
+				x: left,
+				y: center.y
+			},
+			tail: {
+				x: left - span,
+				y: center.y
+			}
+		};
+		case "right": return {
+			head: {
+				x: right,
+				y: center.y
+			},
+			tail: {
+				x: right + span,
+				y: center.y
+			}
+		};
+		case "top": return {
+			head: {
+				x: center.x,
+				y: top
+			},
+			tail: {
+				x: center.x,
+				y: top - span
+			}
+		};
+		case "bottom": return {
+			head: {
+				x: center.x,
+				y: bottom
+			},
+			tail: {
+				x: center.x,
+				y: bottom + span
+			}
+		};
+	}
+}
+function layoutAnnotation(box, spec, viewport, direction = "ltr") {
+	const ring = padBox(box);
+	const arrow = spec.arrow !== void 0 || spec.label !== void 0 ? {
+		...arrowGeometry(ring, chooseArrowSide(ring, viewport, spec.arrow ?? "auto", direction), viewport),
+		label: spec.label ?? null
+	} : null;
+	const badgeX = direction === "rtl" ? ring.x + BADGE_OFFSET : ring.x + ring.width - BADGE_OFFSET;
+	const badge = spec.number === void 0 ? null : {
+		center: {
+			x: badgeX,
+			y: ring.y + BADGE_OFFSET
+		},
+		number: spec.number
+	};
+	return {
+		ring: spec.highlight === false ? null : ring,
+		badge,
+		arrow
+	};
+}
+//#endregion
+export { SIDES, arrowGeometry, chooseArrowSide, layoutAnnotation, padBox, roomAround };

package/dist/host.d.ts

@@ -0,0 +1,24 @@
+import { ShotSpec } from "./shot.js";
+import { Browser, BrowserContextOptions, Page, Response } from "playwright-core";
+//#region src/host.d.ts
+export interface FlowIdentity {
+  name: string;
+  session?: string;
+}
+export interface HostSession<Extras> {
+  context?: BrowserContextOptions;
+  contextFor?(flow: FlowIdentity): BrowserContextOptions | Promise<BrowserContextOptions>;
+  injectCss?: string;
+  extras?(page: Page, flow: FlowIdentity): Extras | Promise<Extras>;
+  beforeNavigate?(url: string): Promise<void>;
+  observe?(response: Response, flow: FlowIdentity): void;
+  refuseShot?(shot: ShotSpec, flow: FlowIdentity): string | null;
+  close?(): Promise<void>;
+}
+export interface Host<Extras = Record<string, never>> {
+  open(env: {
+    browser: Browser;
+    baseUrl: string;
+  }): Promise<HostSession<Extras>>;
+}
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import { chooseArrowSide, layoutAnnotation } from "./geometry.js";
+import { ImageOutput, ShotSpec, Target } from "./shot.js";
+import { FlowIdentity, Host, HostSession } from "./host.js";
+import { Manifest, Shot } from "@segnavia/format";
+import { BrowserContextOptions, Page } from "playwright-core";
+//#region src/index.d.ts
+export interface FlowContext<Extras> {
+  flow: string;
+  page: Page;
+  extras: Extras;
+  log(message: string): void;
+  currentStep(): string;
+  step<T>(name: string, body: () => Promise<T>): Promise<T>;
+  goto(url: string): Promise<void>;
+  until(predicate: string | ((arg: unknown) => unknown), what: string, options?: {
+    arg?: unknown;
+    timeout?: number;
+  }): Promise<void>;
+  viewport(size?: {
+    width: number;
+    height: number;
+  }): Promise<void>;
+  setLocalStorage(entries: Record<string, string | number | boolean>): Promise<void>;
+  shot(spec: ShotSpec): Promise<Shot>;
+}
+export interface Flow<Extras> extends FlowIdentity {
+  run(flow: FlowContext<Extras>): Promise<void>;
+}
+export interface CaptureConfig {
+  baseUrl: string;
+  outputDirectory: string;
+  executablePath: string;
+  launchArgs?: string[];
+  viewport?: {
+    width: number;
+    height: number;
+  };
+  scale?: number;
+  context?: BrowserContextOptions;
+  output?: ImageOutput;
+  flows?: string[];
+  meta?: Record<string, unknown>;
+  log?: (message: string) => void;
+}
+export interface FlowResult {
+  name: string;
+  ok: boolean;
+  error?: string;
+  failureScreenshot?: string;
+  shots: Shot[];
+}
+export interface CaptureRun {
+  results: FlowResult[];
+  manifest: Manifest;
+  ok: boolean;
+}
+export declare function selectFlows<F extends {
+  name: string;
+}>(flows: F[], requested?: string[]): F[];
+export declare function capture<Extras>(host: Host<Extras>, flows: Flow<Extras>[], config: CaptureConfig): Promise<CaptureRun>;
+//#endregion
+export { type FlowIdentity, type Host, type HostSession, type ImageOutput, type ShotSpec, type Target, chooseArrowSide, layoutAnnotation };

package/dist/index.js

@@ -0,0 +1,206 @@
+import { chooseArrowSide, layoutAnnotation } from "./geometry.js";
+import { takeShot } from "./shot.js";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { Manifest } from "@segnavia/format";
+import { chromium } from "playwright-core";
+//#region src/index.ts
+const DEFAULTS = {
+	viewport: {
+		width: 1280,
+		height: 720
+	},
+	scale: 2,
+	output: { format: "png" }
+};
+function selectFlows(flows, requested) {
+	if (!requested || requested.length === 0) return flows;
+	const matches = (flow, name) => flow.name === name || flow.name.startsWith(`${name}.`);
+	const unknown = requested.filter((name) => !flows.some((flow) => matches(flow, name)));
+	if (unknown.length > 0) throw new Error(`No flow is named ${unknown.join(", ")}. Flows: ${flows.map((flow) => flow.name).join(", ")}`);
+	return flows.filter((flow) => requested.some((name) => matches(flow, name)));
+}
+function injectStyle(css) {
+	const apply = () => {
+		const style = document.createElement("style");
+		style.textContent = css;
+		document.documentElement.appendChild(style);
+	};
+	if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", apply);
+	else apply();
+}
+async function runFlow(flow, browser, session, config) {
+	const staging = path.join(config.outputDirectory, ".staging", flow.name);
+	rmSync(staging, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(staging, { recursive: true });
+	const identity = {
+		name: flow.name,
+		session: flow.session
+	};
+	const shots = [];
+	const state = {
+		step: "setting up",
+		number: 0
+	};
+	const context = await browser.newContext({
+		baseURL: config.baseUrl,
+		viewport: config.viewport,
+		deviceScaleFactor: config.scale,
+		colorScheme: "light",
+		reducedMotion: "reduce",
+		...config.context,
+		...session.context,
+		...session.contextFor ? await session.contextFor(identity) : {}
+	});
+	if (session.injectCss) await context.addInitScript(injectStyle, session.injectCss);
+	const page = await context.newPage();
+	try {
+		if (session.observe) page.on("response", (response) => session.observe?.(response, identity));
+		const flowContext = {
+			flow: flow.name,
+			page,
+			extras: session.extras ? await session.extras(page, identity) : {},
+			log: (message) => config.log(`    ${message}`),
+			currentStep: () => state.step,
+			async step(name, body) {
+				state.step = name;
+				state.number += 1;
+				config.log(`  ${flow.name} › ${name}`);
+				return body();
+			},
+			async goto(url) {
+				await session.beforeNavigate?.(url);
+				await page.goto(url);
+			},
+			async until(predicate, what, options = {}) {
+				const timeout = options.timeout ?? 3e4;
+				try {
+					await page.waitForFunction(predicate, options.arg, { timeout });
+				} catch {
+					throw new Error(`waited ${timeout / 1e3}s for ${what}`);
+				}
+			},
+			async viewport(size) {
+				await page.setViewportSize(size ?? config.viewport);
+			},
+			async setLocalStorage(entries) {
+				if (!page.url().startsWith(config.baseUrl)) await flowContext.goto("/");
+				await page.evaluate((pairs) => {
+					for (const [key, value] of Object.entries(pairs)) localStorage.setItem(key, String(value));
+				}, entries);
+			},
+			async shot(spec) {
+				const refusal = session.refuseShot?.(spec, identity);
+				if (refusal) throw new Error(`Step "${state.step}": ${refusal}`);
+				if (shots.some((shot) => shot.key === spec.key)) throw new Error(`Shot key ${spec.key} is taken twice in ${flow.name}.`);
+				const shot = await takeShot(page, spec, {
+					step: state.step,
+					directory: staging,
+					scale: config.scale,
+					output: config.output
+				});
+				const recorded = {
+					...shot,
+					meta: {
+						...config.meta,
+						...shot.meta,
+						flow: flow.name,
+						step: Math.max(state.number, 1),
+						stepName: state.step
+					}
+				};
+				shots.push(recorded);
+				config.log(`    captured ${spec.key}`);
+				return recorded;
+			}
+		};
+		await flow.run(flowContext);
+		for (const shot of shots) for (const file of [shot.file, shot.annotatedFile]) if (file) renameSync(path.join(staging, file), path.join(config.outputDirectory, file));
+		return {
+			name: flow.name,
+			ok: true,
+			shots
+		};
+	} catch (error) {
+		const failureScreenshot = path.join(config.outputDirectory, ".failures", `${flow.name}.png`);
+		mkdirSync(path.dirname(failureScreenshot), { recursive: true });
+		await page.screenshot({ path: failureScreenshot }).catch(() => {});
+		const message = error.message.split("\n")[0] ?? "";
+		return {
+			name: flow.name,
+			ok: false,
+			error: message.startsWith("Step \"") ? message : `Step "${state.step}": ${message}`,
+			failureScreenshot,
+			shots: []
+		};
+	} finally {
+		await context.close();
+		rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+function writeManifest(directory, results) {
+	const file = path.join(directory, "manifest.json");
+	const manifest = existsSync(file) ? Manifest.parse(JSON.parse(readFileSync(file, "utf8"))) : {
+		shots: {},
+		updatedAt: ""
+	};
+	for (const shot of results.flatMap((result) => result.shots)) manifest.shots[shot.key] = shot;
+	manifest.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+	writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+	return manifest;
+}
+async function capture(host, flows, config) {
+	const resolved = {
+		...DEFAULTS,
+		...config,
+		log: config.log ?? (() => {})
+	};
+	const selected = selectFlows(flows, config.flows);
+	mkdirSync(resolved.outputDirectory, { recursive: true });
+	const browser = await chromium.launch({
+		executablePath: resolved.executablePath,
+		args: [
+			"--hide-scrollbars",
+			"--force-color-profile=srgb",
+			"--font-render-hinting=none",
+			...config.launchArgs ?? []
+		]
+	});
+	const results = [];
+	try {
+		const session = await host.open({
+			browser,
+			baseUrl: resolved.baseUrl
+		});
+		try {
+			for (const flow of selected) {
+				resolved.log(`flow ${flow.name}`);
+				const result = await runFlow(flow, browser, session, resolved);
+				resolved.log(result.ok ? `  ok: ${result.shots.length} shots` : `  FAILED: ${result.error}`);
+				results.push(result);
+			}
+		} finally {
+			await session.close?.();
+		}
+	} finally {
+		await browser.close();
+	}
+	const manifest = writeManifest(resolved.outputDirectory, results);
+	writeFileSync(path.join(resolved.outputDirectory, "report.json"), `${JSON.stringify({
+		meta: config.meta ?? {},
+		flows: results
+	}, null, 2)}\n`);
+	return {
+		results,
+		manifest,
+		ok: results.every((result) => result.ok)
+	};
+}
+//#endregion
+export { capture, chooseArrowSide, layoutAnnotation, selectFlows };

package/dist/shot.d.ts

@@ -0,0 +1,36 @@
+import { AnnotationSpec } from "./geometry.js";
+import { Shot } from "@segnavia/format";
+import { Page } from "playwright-core";
+//#region src/shot.d.ts
+export type Target = ({
+  role: Parameters<Page['getByRole']>[0];
+  name?: string | RegExp;
+} | {
+  label: string | RegExp;
+} | {
+  text: string | RegExp;
+} | {
+  css: string;
+}) & {
+  exact?: boolean;
+  within?: Target;
+};
+export interface ShotSpec {
+  key: string;
+  title: string;
+  description?: string;
+  tags?: string[];
+  annotate?: Array<AnnotationSpec & {
+    target: Target;
+  }>;
+  settleMs?: number;
+  meta?: Record<string, unknown>;
+}
+export interface ImageOutput {
+  format: 'png' | 'webp' | 'jpeg';
+  quality?: number[];
+  maxBytes?: number;
+  annotated?: boolean;
+  color?: string;
+}
+//#endregion

package/dist/shot.js

@@ -0,0 +1,114 @@
+import { layoutAnnotation } from "./geometry.js";
+import { writeFileSync } from "node:fs";
+import path from "node:path";
+import { SHOT_KEY } from "@segnavia/format";
+import { annotationSvg } from "@segnavia/frame/svg";
+import { captureImage } from "@segnavia/render";
+//#region src/shot.ts
+function describeTarget(target) {
+	const scope = target.within ? `${describeTarget(target.within)}.` : "";
+	if ("role" in target) return `${scope}getByRole(${JSON.stringify(target.role)}${target.name === void 0 ? "" : `, { name: ${String(target.name)} }`})`;
+	if ("label" in target) return `${scope}getByLabel(${String(target.label)})`;
+	if ("text" in target) return `${scope}getByText(${String(target.text)})`;
+	return `${scope}locator(${JSON.stringify(target.css)})`;
+}
+function locate(page, target) {
+	const root = target.within ? locate(page, target.within) : page;
+	const exact = target.exact ?? true;
+	if ("role" in target) return root.getByRole(target.role, target.name === void 0 ? {} : {
+		name: target.name,
+		exact
+	});
+	if ("label" in target) return root.getByLabel(target.label, { exact });
+	if ("text" in target) return root.getByText(target.text, { exact });
+	return root.locator(target.css);
+}
+async function resolveOne(page, target, step) {
+	const locator = locate(page, target).filter({ visible: true });
+	const count = await locator.count();
+	if (count !== 1) throw new Error(`Step "${step}": ${describeTarget(target)} matched ${count} visible elements; expected exactly one.`);
+	return locator;
+}
+async function settle(page, ms = 400) {
+	const viewport = page.viewportSize();
+	if (viewport) await page.mouse.move(viewport.width - 1, viewport.height - 1);
+	await page.waitForLoadState("networkidle", { timeout: 15e3 }).catch(() => {});
+	await page.evaluate(() => document.fonts.ready.then(() => true));
+	await page.waitForFunction(() => [...document.images].every((image) => image.complete), null, { timeout: 15e3 }).catch(() => {});
+	await page.waitForTimeout(ms);
+}
+async function measure(page, spec, step, direction) {
+	const viewport = page.viewportSize();
+	if (!viewport) throw new Error(`Step "${step}": the page has no fixed viewport to measure against.`);
+	const annotations = [];
+	for (const [index, annotation] of (spec.annotate ?? []).entries()) {
+		const locator = await resolveOne(page, annotation.target, step);
+		if (index === 0) await locator.scrollIntoViewIfNeeded();
+		const box = await locator.boundingBox();
+		const inside = box && box.x >= -1 && box.y >= -1 && box.x + box.width <= viewport.width + 1 && box.y + box.height <= viewport.height + 1;
+		if (!box || !inside) throw new Error(`Step "${step}": ${describeTarget(annotation.target)} is not fully inside the ${viewport.width}x${viewport.height} viewport.`);
+		try {
+			annotations.push(layoutAnnotation(box, annotation, viewport, direction));
+		} catch (error) {
+			throw new Error(`Step "${step}": ${error.message}`);
+		}
+	}
+	return annotations;
+}
+const OVERLAY_ID = "__segnavia-annotations";
+function drawOverlay({ id, svg }) {
+	const overlay = document.createElement("div");
+	overlay.id = id;
+	overlay.style.cssText = "position:fixed;inset:0;z-index:2147483647;pointer-events:none";
+	overlay.innerHTML = svg;
+	for (const group of overlay.querySelectorAll("g")) group.setAttribute("style", "opacity:1");
+	document.documentElement.appendChild(overlay);
+}
+function removeOverlay(id) {
+	document.getElementById(id)?.remove();
+}
+async function takeShot(page, spec, options) {
+	if (!SHOT_KEY.test(spec.key)) throw new Error(`Shot key "${spec.key}" must be lowercase words joined by dots or dashes.`);
+	if (!spec.title) throw new Error(`Shot ${spec.key} needs a title.`);
+	await settle(page, spec.settleMs);
+	const direction = await page.evaluate(() => getComputedStyle(document.documentElement).direction === "rtl" ? "rtl" : "ltr");
+	const annotations = await measure(page, spec, options.step, direction);
+	const viewport = page.viewportSize();
+	const extension = options.output.format === "jpeg" ? "jpg" : options.output.format;
+	const encode = () => captureImage(page, {
+		format: options.output.format,
+		quality: options.output.quality,
+		limits: { maxBytes: options.output.maxBytes }
+	}, false);
+	const file = `${spec.key}.${extension}`;
+	writeFileSync(path.join(options.directory, file), await encode());
+	let annotatedFile = null;
+	if (options.output.annotated && annotations.length > 0) {
+		annotatedFile = `${spec.key}.annotated.${extension}`;
+		await page.evaluate(drawOverlay, {
+			id: OVERLAY_ID,
+			svg: annotationSvg(viewport, annotations, options.output.color)
+		});
+		try {
+			writeFileSync(path.join(options.directory, annotatedFile), await encode());
+		} finally {
+			await page.evaluate(removeOverlay, OVERLAY_ID).catch(() => {});
+		}
+	}
+	return {
+		key: spec.key,
+		title: spec.title,
+		description: spec.description ?? null,
+		tags: spec.tags ?? [],
+		file,
+		annotatedFile,
+		size: viewport,
+		scale: options.scale,
+		dir: direction,
+		annotations,
+		capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		meta: spec.meta ?? {}
+	};
+}
+//#endregion
+export { describeTarget, locate, resolveOne, settle, takeShot };

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@segnavia/capture",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modstudio/segnavia.git",
+    "directory": "packages/capture"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "@segnavia/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@segnavia/format": "0.2.0",
+    "playwright-core": "1.55.1",
+    "@segnavia/frame": "0.2.0",
+    "@segnavia/render": "0.2.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.