agent-canvas 0.2.1 → 0.6.0

package/daemon/langMap.ts

@@ -1,8 +1,26 @@
 /** File extension → highlight.js language name mapping. */
 export const LANG_MAP: Record<string, string> = {
-  ts: "typescript", tsx: "typescript", js: "javascript", jsx: "javascript",
-  py: "python", rs: "rust", go: "go", rb: "ruby", java: "java",
-  json: "json", yaml: "yaml", yml: "yaml", md: "markdown",
-  css: "css", html: "html", sh: "bash", bash: "bash", toml: "toml",
-  sql: "sql", xml: "xml", c: "c", cpp: "cpp", h: "c",
-};
+	ts: 'typescript',
+	tsx: 'typescript',
+	js: 'javascript',
+	jsx: 'javascript',
+	py: 'python',
+	rs: 'rust',
+	go: 'go',
+	rb: 'ruby',
+	java: 'java',
+	json: 'json',
+	yaml: 'yaml',
+	yml: 'yaml',
+	md: 'markdown',
+	css: 'css',
+	html: 'html',
+	sh: 'bash',
+	bash: 'bash',
+	toml: 'toml',
+	sql: 'sql',
+	xml: 'xml',
+	c: 'c',
+	cpp: 'cpp',
+	h: 'c',
+}

package/daemon/review-widget/anchor.ts

@@ -0,0 +1,187 @@
+import type { ReviewAnchor } from '../src/review/model'
+import { contextOf, htmlOf } from './markup'
+
+const MAX_TEXT = 120
+const QUOTE_CONTEXT = 40
+const MAX_COMPONENTS = 8
+
+function shorten(text: string, max = MAX_TEXT): string {
+	const collapsed = text.replace(/\s+/g, ' ').trim()
+	return collapsed.length > max ? `${collapsed.slice(0, max - 1)}…` : collapsed
+}
+
+const IMPLICIT_ROLES: Record<string, string> = {
+	button: 'button',
+	select: 'combobox',
+	textarea: 'textbox',
+	h1: 'heading',
+	h2: 'heading',
+	h3: 'heading',
+	h4: 'heading',
+	h5: 'heading',
+	h6: 'heading',
+	img: 'img',
+	nav: 'navigation',
+	main: 'main',
+	dialog: 'dialog',
+	table: 'table',
+	tr: 'row',
+	th: 'columnheader',
+	td: 'cell',
+	li: 'listitem',
+	ul: 'list',
+	ol: 'list',
+	form: 'form',
+}
+
+const INPUT_ROLES: Record<string, string> = { checkbox: 'checkbox', radio: 'radio', button: 'button', submit: 'button', range: 'slider' }
+
+export function roleOf(element: Element): string | undefined {
+	const explicit = element.getAttribute('role')
+	if (explicit !== null && explicit !== '') return explicit.split(' ')[0]
+	const tag = element.tagName.toLowerCase()
+	if (tag === 'a') return element.hasAttribute('href') ? 'link' : undefined
+	if (tag === 'input') return INPUT_ROLES[element.getAttribute('type') ?? 'text'] ?? 'textbox'
+	return IMPLICIT_ROLES[tag]
+}
+
+/** The accessible name, approximated: the sources a reviewer's element usually has, in the order the spec reads them. */
+export function nameOf(element: Element): string | undefined {
+	const label = element.getAttribute('aria-label')
+	if (label !== null && label.trim() !== '') return shorten(label)
+	const labelledBy = element.getAttribute('aria-labelledby')
+	if (labelledBy !== null) {
+		const text = labelledBy.split(/\s+/).map((id) => element.ownerDocument.getElementById(id)?.textContent ?? '').join(' ')
+		if (text.trim() !== '') return shorten(text)
+	}
+	if (element.id !== '') {
+		const forLabel = element.ownerDocument.querySelector(`label[for="${CSS.escape(element.id)}"]`)
+		if (forLabel?.textContent != null && forLabel.textContent.trim() !== '') return shorten(forLabel.textContent)
+	}
+	for (const attribute of ['alt', 'title', 'placeholder']) {
+		const value = element.getAttribute(attribute)
+		if (value !== null && value.trim() !== '') return shorten(value)
+	}
+	const role = roleOf(element)
+	const namedByContent = role === 'button' || role === 'link' || role === 'heading' || role === 'cell' || role === 'columnheader' || role === 'tab'
+		|| role === 'menuitem' || role === 'option'
+	if (namedByContent && element.textContent !== null && element.textContent.trim() !== '') return shorten(element.textContent)
+	return undefined
+}
+
+/** A CSS path from the nearest ancestor with an id, or from `body`, using `:nth-of-type` only where siblings share a tag. */
+export function selectorOf(element: Element): string {
+	const parts: string[] = []
+	let current: Element | null = element
+	while (current !== null && current.tagName.toLowerCase() !== 'body' && current.tagName.toLowerCase() !== 'html') {
+		if (current.id !== '' && current.ownerDocument.querySelectorAll(`#${CSS.escape(current.id)}`).length === 1) {
+			parts.unshift(`#${CSS.escape(current.id)}`)
+			return parts.join(' > ')
+		}
+		const tag = current.tagName.toLowerCase()
+		const parent: Element | null = current.parentElement
+		const sameTag = parent === null ? [] : [...parent.children].filter((child) => child.tagName === current?.tagName)
+		parts.unshift(sameTag.length > 1 ? `${tag}:nth-of-type(${sameTag.indexOf(current) + 1})` : tag)
+		current = parent
+	}
+	parts.unshift('body')
+	return parts.join(' > ')
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null
+}
+
+function componentName(type: unknown): string | undefined {
+	if (typeof type === 'function') {
+		const displayName: unknown = Reflect.get(type, 'displayName')
+		if (typeof displayName === 'string' && displayName !== '') return displayName
+		return type.name === '' ? undefined : type.name
+	}
+	if (isRecord(type)) {
+		// memo() wraps the component in `type`, forwardRef() in `render`.
+		return componentName(type['type']) ?? componentName(type['render'])
+	}
+	return undefined
+}
+
+/** Owner components of a React development build, outermost first; empty for other renderers and production builds. */
+export function componentsOf(element: Element): string[] {
+	const fiberKey = Object.keys(element).find((key) => key.startsWith('__reactFiber$'))
+	if (fiberKey === undefined) return []
+	const names: string[] = []
+	let fiber: unknown = Reflect.get(element, fiberKey)
+	while (isRecord(fiber) && names.length < 40) {
+		// Bundlers suffix a name that collides in their scope (`Card` → `Card13`); the source still says `Card`.
+		const name = componentName(fiber['type'])?.replace(/(?<=[a-z])\d+$/, '')
+		// Context providers wrap whole apps and say nothing about where the element is.
+		if (name !== undefined && /^[A-Z]/.test(name) && !name.endsWith('Provider') && names[0] !== name) names.unshift(name)
+		fiber = fiber['return']
+	}
+	return names.slice(-MAX_COMPONENTS)
+}
+
+function quoteOf(element: Element, range: Range): ReviewAnchor['quote'] {
+	const exact = range.toString().trim()
+	if (exact === '') return undefined
+	const before = element.ownerDocument.createRange()
+	before.selectNodeContents(element)
+	before.setEnd(range.startContainer, range.startOffset)
+	const after = element.ownerDocument.createRange()
+	after.selectNodeContents(element)
+	after.setStart(range.endContainer, range.endOffset)
+	return {
+		exact: exact.slice(0, 2000),
+		before: before.toString().replace(/\s+/g, ' ').slice(-QUOTE_CONTEXT),
+		after: after.toString().replace(/\s+/g, ' ').slice(0, QUOTE_CONTEXT),
+	}
+}
+
+/**
+ * Describes the element, or the selection inside it, so the agent can find it in code and the widget in the page.
+ * Source positions need the page's source maps, so the caller resolves them separately.
+ */
+export function describe(element: Element, url: string, range?: Range): ReviewAnchor {
+	const role = roleOf(element)
+	const name = nameOf(element)
+	const text = element.textContent === null ? '' : shorten(element.textContent)
+	const components = componentsOf(element)
+	const quote = range === undefined ? undefined : quoteOf(element, range)
+	const context = contextOf(element)
+	return {
+		url,
+		selector: selectorOf(element),
+		...(role === undefined ? {} : { role }),
+		...(name === undefined ? {} : { name }),
+		...(text === '' ? {} : { text }),
+		...(components.length === 0 ? {} : { components }),
+		...(quote === undefined ? {} : { quote }),
+		...(context === undefined ? {} : { context }),
+		html: htmlOf(element),
+	}
+}
+
+function matches(element: Element, anchor: ReviewAnchor): boolean {
+	if (anchor.role !== undefined && roleOf(element) !== anchor.role) return false
+	if (anchor.name !== undefined && nameOf(element) !== anchor.name) return false
+	return true
+}
+
+/**
+ * Re-finds the anchored element after the page re-rendered: the CSS path when it still points at an element with the
+ * same role and name, otherwise the only element with that role and name.
+ */
+export function find(document: Document, anchor: ReviewAnchor): Element | null {
+	let bySelector: Element | null = null
+	try {
+		bySelector = document.querySelector(anchor.selector)
+	} catch {
+		bySelector = null
+	}
+	if (bySelector !== null && matches(bySelector, anchor)) return bySelector
+	if (anchor.role !== undefined && anchor.name !== undefined) {
+		const candidates = [...document.body.querySelectorAll('*')].filter((element) => matches(element, anchor))
+		if (candidates.length === 1) return candidates[0] ?? null
+	}
+	return bySelector
+}

package/daemon/review-widget/client.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod'
+import { type ReviewAnchor, type ReviewBrowserFrame, type ReviewThread, reviewThreadSchema } from '../src/review/model'
+
+const threadListSchema = z.object({ threads: z.array(reviewThreadSchema) })
+
+export interface ReviewEvents {
+	threads(threads: readonly ReviewThread[]): void
+	agentWatching(watching: boolean): void
+	connected(connected: boolean): void
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** The daemon only ever sends these frames; anything else is ignored rather than trusted. */
+function readFrame(data: unknown): ReviewBrowserFrame | undefined {
+	if (typeof data !== 'string') return undefined
+	let frame: unknown
+	try {
+		frame = JSON.parse(data)
+	} catch {
+		return undefined
+	}
+	if (!isRecord(frame)) return undefined
+	if (frame['type'] === 'agent-status' && typeof frame['watching'] === 'boolean') return { type: 'agent-status', watching: frame['watching'] }
+	if (frame['type'] !== 'threads') return undefined
+	const parsed = threadListSchema.safeParse(frame)
+	return parsed.success ? { type: 'threads', threads: parsed.data.threads } : undefined
+}
+
+/** The widget's side of the daemon: thread mutations over HTTP, the thread list and agent presence over a WebSocket. */
+export class ReviewClient {
+	private socket: WebSocket | null = null
+	private closed = false
+
+	constructor(private readonly daemonOrigin: string, private readonly project: string) {}
+
+	connect(events: ReviewEvents): void {
+		const url = `${this.daemonOrigin.replace(/^http/, 'ws')}/ws/review/${encodeURIComponent(this.project)}`
+		const socket = new WebSocket(url)
+		this.socket = socket
+		socket.onopen = () => {
+			events.connected(true)
+			void this.request('GET', '/threads').then((body) => {
+				const parsed = threadListSchema.safeParse(body)
+				if (parsed.success) events.threads(parsed.data.threads)
+			})
+		}
+		socket.onmessage = (event) => {
+			const frame = readFrame(event.data)
+			if (frame?.type === 'threads') events.threads(frame.threads)
+			if (frame?.type === 'agent-status') events.agentWatching(frame.watching)
+		}
+		socket.onclose = () => {
+			events.connected(false)
+			if (!this.closed) setTimeout(() => this.connect(events), 2000)
+		}
+	}
+
+	close(): void {
+		this.closed = true
+		this.socket?.close()
+	}
+
+	createThread(anchor: ReviewAnchor, body: string, send: boolean, screenshot?: string): Promise<unknown> {
+		return this.request('POST', '/threads', { anchor, body, send, ...(screenshot === undefined ? {} : { screenshot }) })
+	}
+
+	comment(threadId: string, body: string, send: boolean): Promise<unknown> {
+		return this.request('POST', `/threads/${threadId}/comments`, { body, send })
+	}
+
+	send(threadId: string): Promise<unknown> {
+		return this.request('POST', `/threads/${threadId}/send`)
+	}
+
+	setResolved(threadId: string, resolved: boolean): Promise<unknown> {
+		return this.request('POST', `/threads/${threadId}/${resolved ? 'resolve' : 'reopen'}`)
+	}
+
+	delete(threadId: string): Promise<unknown> {
+		return this.request('DELETE', `/threads/${threadId}`)
+	}
+
+	private async request(method: string, path: string, body?: unknown): Promise<unknown> {
+		const response = await fetch(`${this.daemonOrigin}/api/review/${encodeURIComponent(this.project)}${path}`, {
+			method,
+			...(body === undefined ? {} : { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }),
+		})
+		const result: unknown = await response.json()
+		if (!response.ok) throw new Error(isRecord(result) && typeof result['error'] === 'string' ? result['error'] : `Request failed (${response.status})`)
+		return result
+	}
+}

package/daemon/review-widget/index.tsx

@@ -0,0 +1,36 @@
+import { render } from 'preact'
+import { PROJECT_RE } from '../src/review/model'
+import { ReviewClient } from './client'
+import styles from './styles.css' with { type: 'text' }
+import { ReviewWidget } from './widget'
+
+const HOST_TAG = 'agent-canvas-review'
+
+/**
+ * `<script src="http://localhost:19400/assets/review.js" data-project="my-app"></script>` in the application under
+ * review mounts the widget. Its own origin is the daemon's.
+ */
+function mount(script: HTMLScriptElement): void {
+	const project = script.dataset['project'] ?? ''
+	if (!PROJECT_RE.test(project)) {
+		console.error(`agent-canvas review: data-project must match ${PROJECT_RE}, got "${project}"`)
+		return
+	}
+	if (document.querySelector(HOST_TAG) !== null) return
+
+	const pageStyle = document.createElement('style')
+	pageStyle.textContent = 'html.agent-canvas-review-picking, html.agent-canvas-review-picking * { cursor: crosshair !important; }'
+	document.head.append(pageStyle)
+
+	const host = document.createElement(HOST_TAG)
+	document.documentElement.append(host)
+	const root = host.attachShadow({ mode: 'open' })
+	const style = document.createElement('style')
+	style.textContent = styles
+	root.append(style)
+	render(<ReviewWidget client={new ReviewClient(new URL(script.src).origin, project)} host={host} />, root)
+}
+
+const script = document.currentScript
+if (script instanceof HTMLScriptElement) mount(script)
+else console.error('agent-canvas review: load review.js with a classic <script> tag')

package/daemon/review-widget/markup.ts

@@ -0,0 +1,71 @@
+import { MAX_HTML } from '../src/review/model'
+
+const MAX_CHILDREN = 8
+const MAX_TEXT = 80
+const DROPPED_TAGS = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE'])
+
+function trimTree(node: Element, depth: number): void {
+	if (node.tagName.toLowerCase() === 'svg') {
+		node.replaceChildren()
+		return
+	}
+	let elements = 0
+	for (const child of [...node.childNodes]) {
+		if (child.nodeType === Node.TEXT_NODE) {
+			const text = child.textContent ?? ''
+			if (text.trim() === '') child.remove()
+			else if (text.length > MAX_TEXT) child.textContent = `${text.slice(0, MAX_TEXT)}…`
+			continue
+		}
+		if (!(child instanceof Element) || DROPPED_TAGS.has(child.tagName)) {
+			child.remove()
+			continue
+		}
+		elements++
+		if (depth === 0 || elements > MAX_CHILDREN) child.remove()
+		else trimTree(child, depth - 1)
+	}
+	if (depth === 0 && elements > 0) node.append(node.ownerDocument.createComment(` ${elements} child elements cut `))
+	else if (elements > MAX_CHILDREN) node.append(node.ownerDocument.createComment(` ${elements - MAX_CHILDREN} more `))
+}
+
+/** The element's markup, shallower until it fits: the agent sees structure, classes and attributes, not whole subtrees. */
+export function htmlOf(element: Element): string {
+	for (let depth = 5; depth >= 0; depth--) {
+		const clone = element.cloneNode(true)
+		if (!(clone instanceof Element)) return ''
+		trimTree(clone, depth)
+		const html = clone.outerHTML
+		if (html.length <= MAX_HTML) return html
+	}
+	const shallow = element.cloneNode(false)
+	return shallow instanceof Element ? shallow.outerHTML.slice(0, MAX_HTML) : ''
+}
+
+function headingIn(container: Element): string | undefined {
+	const label = container.getAttribute('aria-label')
+	if (label !== null && label.trim() !== '') return label.trim()
+	const labelledBy = container.getAttribute('aria-labelledby')
+	const labelElement = labelledBy === null ? null : container.ownerDocument.getElementById(labelledBy.split(/\s+/)[0] ?? '')
+	const heading = labelElement ?? container.querySelector('h1, h2, h3, h4, legend, [role="heading"]')
+	const text = heading?.textContent?.replace(/\s+/g, ' ').trim()
+	return text === undefined || text === '' ? undefined : text.slice(0, 80)
+}
+
+const LANDMARKS: readonly { selector: string; kind: string }[] = [
+	{ selector: 'dialog, [role="dialog"], [role="alertdialog"], [aria-modal="true"]', kind: 'Dialog' },
+	{ selector: 'section, article, fieldset, form, [role="region"], [role="tabpanel"]', kind: 'Section' },
+]
+
+/** The page heading and the nearest section and dialog around the element, outermost first. */
+export function contextOf(element: Element): string | undefined {
+	const parts: string[] = []
+	const pageHeading = element.ownerDocument.querySelector('h1')?.textContent?.replace(/\s+/g, ' ').trim()
+	if (pageHeading !== undefined && pageHeading !== '') parts.push(`Page "${pageHeading.slice(0, 80)}"`)
+	for (const landmark of LANDMARKS) {
+		const container = element.closest(landmark.selector)
+		const heading = container === null ? undefined : headingIn(container)
+		if (heading !== undefined && !parts.includes(`Page "${heading}"`)) parts.push(`${landmark.kind} "${heading}"`)
+	}
+	return parts.length === 0 ? undefined : parts.join(' › ')
+}

package/daemon/review-widget/screenshot.ts

@@ -0,0 +1,91 @@
+/** The smallest surroundings worth showing around a picked element, and the tallest an ancestor may be to count as them. */
+const MIN_CONTEXT = { width: 480, height: 160 }
+const MAX_CONTEXT_HEIGHT = 900
+const OUTLINE = '#e11d48'
+
+/** The nearest ancestor large enough to show where the element sits, but not a whole scrolling page. */
+function surroundingsOf(element: Element): Element {
+	let context = element
+	for (let parent = element.parentElement; parent !== null && parent !== element.ownerDocument.body; parent = parent.parentElement) {
+		const box = context.getBoundingClientRect()
+		if (box.width >= MIN_CONTEXT.width && box.height >= MIN_CONTEXT.height) break
+		if (parent.getBoundingClientRect().height > MAX_CONTEXT_HEIGHT) break
+		context = parent
+	}
+	return context
+}
+
+/** Resolves once the stream has delivered `count` new frames, so the frame drawn shows the page after our changes. */
+function streamFrames(video: HTMLVideoElement, count: number): Promise<void> {
+	return new Promise((resolve) => {
+		const fallback = setTimeout(resolve, 1000)
+		const wait = (left: number) => {
+			if (left === 0) {
+				clearTimeout(fallback)
+				resolve()
+				return
+			}
+			video.requestVideoFrameCallback(() => wait(left - 1))
+		}
+		wait(count)
+	})
+}
+
+function clip(box: DOMRect): { left: number; top: number; width: number; height: number } {
+	const left = Math.max(0, box.left)
+	const top = Math.max(0, box.top)
+	return { left, top, width: Math.min(innerWidth, box.right) - left, height: Math.min(innerHeight, box.bottom) - top }
+}
+
+/**
+ * Real pixels of the element in its surroundings, the element outlined, the widget hidden: the browser asks the
+ * reviewer to share this tab for one frame. Rendering the DOM into a picture instead gets fonts and text wrapping
+ * wrong, which is exactly what a visual comment is about.
+ *
+ * Call it straight from the click handler: the browser lets a page ask for the tab only during a user gesture.
+ */
+export async function captureElement(element: Element, widgetHost: HTMLElement): Promise<string> {
+	// Hidden before the stream starts: its first frames already lack the widget, later ones can lag behind the page.
+	const previousVisibility = widgetHost.style.visibility
+	widgetHost.style.visibility = 'hidden'
+	element.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+	let stream: MediaStream
+	try {
+		stream = await navigator.mediaDevices.getDisplayMedia({
+			video: { displaySurface: 'browser', width: { ideal: innerWidth * devicePixelRatio }, height: { ideal: innerHeight * devicePixelRatio } },
+			audio: false,
+			// Chrome's options for sharing the page's own tab without a picker; other browsers ignore them.
+			...{ preferCurrentTab: true, selfBrowserSurface: 'include' },
+		})
+	} catch (error) {
+		widgetHost.style.visibility = previousVisibility
+		throw error
+	}
+	try {
+		const [track] = stream.getVideoTracks()
+		if (track === undefined || track.getSettings().displaySurface !== 'browser') throw new Error('Share this tab to attach a screenshot')
+		const video = document.createElement('video')
+		video.muted = true
+		video.srcObject = stream
+		await video.play()
+		await streamFrames(video, 2)
+
+		const context = clip(surroundingsOf(element).getBoundingClientRect())
+		const target = element.getBoundingClientRect()
+		// The captured frame is the tab's viewport at the device's pixel density.
+		const ratio = video.videoWidth / innerWidth
+		const canvas = document.createElement('canvas')
+		canvas.width = Math.round(context.width * ratio)
+		canvas.height = Math.round(context.height * ratio)
+		const drawing = canvas.getContext('2d')
+		if (drawing === null) throw new Error('Canvas is not available')
+		drawing.drawImage(video, context.left * ratio, context.top * ratio, canvas.width, canvas.height, 0, 0, canvas.width, canvas.height)
+		drawing.strokeStyle = OUTLINE
+		drawing.lineWidth = 3 * ratio
+		drawing.strokeRect((target.left - context.left) * ratio, (target.top - context.top) * ratio, target.width * ratio, target.height * ratio)
+		return canvas.toDataURL('image/png')
+	} finally {
+		widgetHost.style.visibility = previousVisibility
+		for (const track of stream.getTracks()) track.stop()
+	}
+}

package/daemon/review-widget/source.ts

@@ -0,0 +1,103 @@
+import { originalPositionFor, TraceMap } from '@jridgewell/trace-mapping'
+import type { ReviewSource } from '../src/review/model'
+
+/** A frame of a development stack, still in the bundle the page loaded. */
+export interface BundleFrame {
+	label: string
+	url: string
+	line: number
+	column: number
+}
+
+const MAX_SOURCES = 6
+const RESOLVE_TIMEOUT_MS = 3000
+/** Frames inside React's element factory and scheduler, which every stack starts with. */
+const REACT_INTERNAL =
+	/\bat (?:[\w$]+\.)*(?:jsxDEV|jsxs?|createElement|react_stack_bottom_frame)\b|\/node_modules\/(?:\.vite\/deps\/)?react(?:-dom)?[/_]/
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null
+}
+
+function nameOf(type: unknown): string | undefined {
+	if (typeof type === 'string') return type
+	if (typeof type === 'function') return type.name === '' ? undefined : type.name.replace(/(?<=[a-z])\d+$/, '')
+	if (isRecord(type)) return nameOf(type['type']) ?? nameOf(type['render'])
+	return undefined
+}
+
+/** The first application frame of a stack: where the JSX was written. */
+function creationFrame(stack: string): Omit<BundleFrame, 'label'> | undefined {
+	for (const line of stack.split('\n').slice(1)) {
+		if (REACT_INTERNAL.test(line)) continue
+		const match = line.match(/\(?((?:https?|file):\/\/[^\s)]+):(\d+):(\d+)\)?\s*$/)
+		if (match?.[1] !== undefined && match[2] !== undefined && match[3] !== undefined) {
+			return { url: match[1], line: Number(match[2]), column: Number(match[3]) }
+		}
+	}
+	return undefined
+}
+
+/**
+ * Where the element and its nearest components were created, read off React 19 development fibers (`_debugStack`).
+ * Empty for other renderers and production builds.
+ */
+export function bundleFrames(element: Element): BundleFrame[] {
+	const fiberKey = Object.keys(element).find((key) => key.startsWith('__reactFiber$'))
+	if (fiberKey === undefined) return []
+	const frames: BundleFrame[] = []
+	let fiber: unknown = Reflect.get(element, fiberKey)
+	for (let depth = 0; isRecord(fiber) && frames.length < MAX_SOURCES && depth < 60; depth++, fiber = fiber['return']) {
+		const name = nameOf(fiber['type'])
+		// Host elements other than the picked one, and components without a name, say nothing new.
+		if (name === undefined || (frames.length > 0 && typeof fiber['type'] === 'string')) continue
+		const stack = isRecord(fiber['_debugStack']) ? fiber['_debugStack']['stack'] : undefined
+		if (typeof stack !== 'string') continue
+		const frame = creationFrame(stack)
+		if (frame === undefined) continue
+		const owner = isRecord(fiber['_debugOwner']) ? nameOf(fiber['_debugOwner']['type']) : undefined
+		frames.push({ label: owner === undefined ? `<${name}>` : `<${name}> in ${owner}`, ...frame })
+	}
+	return frames
+}
+
+const traceMaps = new Map<string, Promise<TraceMap | null>>()
+
+async function loadTraceMap(scriptUrl: string): Promise<TraceMap | null> {
+	const script = await fetch(scriptUrl).then((response) => response.text())
+	const reference = [...script.matchAll(/\/\/[#@] sourceMappingURL=(\S+)/g)].at(-1)?.[1]
+	if (reference === undefined) return null
+	const mapUrl = new URL(reference, scriptUrl).href
+	const map: unknown = await fetch(mapUrl).then((response) => response.json())
+	if (!isRecord(map) || map['version'] !== 3) return null
+	return new TraceMap(JSON.stringify(map), mapUrl)
+}
+
+function traceMapFor(scriptUrl: string): Promise<TraceMap | null> {
+	let map = traceMaps.get(scriptUrl)
+	if (map === undefined) {
+		map = loadTraceMap(scriptUrl).catch(() => null)
+		traceMaps.set(scriptUrl, map)
+	}
+	return map
+}
+
+function sourcePath(source: string): string {
+	return source.startsWith('file://') ? decodeURIComponent(new URL(source).pathname) : source
+}
+
+async function resolveFrame(frame: BundleFrame): Promise<ReviewSource | null> {
+	const map = await traceMapFor(frame.url)
+	if (map === null) return null
+	// Stack columns count from 1, source map columns from 0.
+	const position = originalPositionFor(map, { line: frame.line, column: frame.column - 1 })
+	if (position.source === null || position.line === null) return null
+	return { label: frame.label, file: sourcePath(position.source), line: position.line, column: position.column + 1 }
+}
+
+/** Source positions of the frames, through the bundles' source maps; frames a map does not cover are left out. */
+export async function resolveSources(frames: readonly BundleFrame[]): Promise<ReviewSource[]> {
+	const timeout = new Promise<null>((resolve) => setTimeout(() => resolve(null), RESOLVE_TIMEOUT_MS))
+	const resolved = await Promise.race([Promise.all(frames.map((frame) => resolveFrame(frame).catch(() => null))), timeout])
+	return resolved === null ? [] : resolved.filter((source) => source !== null)
+}