@fabrika/annotations 0.2.0

package/src/annotationMarkdown.ts

@@ -0,0 +1,102 @@
+import { formatSnippetInContext } from './annotationContext'
+import { describeSnippet } from './annotationDom'
+import type { AnnotationAttachment, AnnotationContext } from './runtime'
+
+/**
+ * What rendering one annotation reads off it. Every `Annotation` satisfies this,
+ * and so can a record that is not one: how a single annotation reads as markdown
+ * is the half of feedback that belongs to no particular document format.
+ */
+export interface RenderableAnnotation {
+	snippet: string
+	note: string
+	/** Set when the annotation points into a file. With `context.lineStart` it
+	 *  switches the quote to numbered source lines. */
+	filePath?: string
+	context?: AnnotationContext
+	/** Attached images as bare paths/URLs — what the local editor writes. */
+	images?: string[]
+	/** Attached files carried on the wire — what a shared canvas sends back.
+	 *  A host may populate either field; both are rendered. */
+	attachments?: AnnotationAttachment[]
+}
+
+/**
+ * One annotation as markdown: what was annotated, quoted, then the note and any
+ * attachments under it. Ends on a blank line so entries stack.
+ *
+ * The caller owns everything around it — headings, grouping, ordering.
+ */
+export function renderAnnotation(ann: RenderableAnnotation): string {
+	const lines: string[] = []
+	const snippet = ann.snippet.trim()
+	const ctx = ann.context
+	// A snippet that does not read as text — a drawn region — says what it points
+	// at in words instead, since quoting its encoding tells an agent nothing.
+	const described = describeSnippet(snippet)
+
+	if (described !== snippet) {
+		lines.push(`> ${described}`)
+	} else if (ann.filePath && ctx && ctx.lineStart != null) {
+		// File annotation with line numbers
+		const lineStart = ctx.lineStart
+		const lineEnd = ctx.lineEnd ?? lineStart
+		const snippetLines = snippet.split('\n')
+		const isShort = snippet.length < 30 && lineStart === lineEnd
+
+		if (isShort && (ctx.before || ctx.after)) {
+			// Short snippet on single line — show full line context
+			const expanded = formatSnippetInContext(ann)
+			lines.push(`> L${lineStart}: ${expanded}`)
+		} else if (snippetLines.length <= 6) {
+			for (let i = 0; i < snippetLines.length; i++) {
+				lines.push(`> ${lineStart + i} | ${snippetLines[i]}`)
+			}
+		} else {
+			for (let i = 0; i < 3; i++) {
+				lines.push(`> ${lineStart + i} | ${snippetLines[i]}`)
+			}
+			lines.push(`> ... (${snippetLines.length} lines)`)
+			for (let i = snippetLines.length - 3; i < snippetLines.length; i++) {
+				lines.push(`> ${lineStart + i} | ${snippetLines[i]}`)
+			}
+		}
+	} else {
+		// Plan annotations or file annotations without line info
+		const context = formatSnippetInContext(ann)
+		if (snippet.split('\n').length <= 3) {
+			lines.push(`> ${context.split('\n').join('\n> ')}`)
+		} else {
+			const snippetLines = snippet.split('\n')
+			lines.push(`> ${snippetLines[0]}`)
+			lines.push(`> ... (${snippetLines.length} lines)`)
+			lines.push(`> ${snippetLines[snippetLines.length - 1]}`)
+		}
+	}
+
+	// Comment
+	if (ann.note.trim()) {
+		lines.push('')
+		lines.push(ann.note.trim())
+	}
+
+	// Attached images. Both fields are read: the local editor writes `images`,
+	// a shared canvas's reviewer comes back with `attachments`, and an agent that
+	// sees only one of them is looking at feedback with a hole in it.
+	const attached = [...(ann.images ?? [])]
+	const seen = new Set(attached)
+	for (const attachment of ann.attachments ?? []) {
+		if (seen.has(attachment.url)) continue
+		seen.add(attachment.url)
+		attached.push(attachment.url)
+	}
+	if (attached.length) {
+		lines.push('')
+		for (const url of attached) {
+			lines.push(`![screenshot](${url})`)
+		}
+	}
+
+	lines.push('')
+	return lines.join('\n')
+}

package/src/annotationTarget.ts

@@ -0,0 +1,73 @@
+/**
+ * How a snippet names something on the page.
+ *
+ * `Annotation.snippet` is the only field that ties an annotation to a domain —
+ * everything else (draft persistence, sidebar, popover, notes, attachments,
+ * markdown, submit) works on any annotation whatever it points at. A target is
+ * that one tie, pulled out as a strategy: give the kernel a new target and it
+ * can annotate a new kind of thing without another line changing.
+ */
+
+/** What a target may read off the annotation it resolves — DOM identity, not feedback. */
+export interface TargetAnnotation {
+	id: string
+	snippet: string
+	context?: { before: string; after: string; hierarchy: string[] }
+}
+
+export interface AnnotationTarget<L extends object> {
+	/** Names the strategy. */
+	readonly kind: string
+	/** Read a snippet this target wrote. Null means the snippet is not its own. */
+	parse(snippet: string): L | null
+	/** Write the locator back into the snippet key. The exact inverse of `parse`. */
+	format(locator: L): string
+	/**
+	 * The element the locator names, searched inside `root`. Targets whose
+	 * annotation lives in DOM this target itself drew — an inline mark, an
+	 * overlay box — return null here and are resolved by their annotation id
+	 * instead; see findAnnotationElement.
+	 */
+	find(locator: L, root: ParentNode): HTMLElement | null
+	/**
+	 * Put this annotation's own decoration back into `root`, if it is not there
+	 * already. Called after every render, for every annotation, so it must be
+	 * idempotent and cheap on a snippet it does not own.
+	 */
+	restore?(locator: L, root: HTMLElement, ann: TargetAnnotation): void
+	/** A one-line label a reader (or a coding agent) can act on. */
+	describe?(locator: L): string
+}
+
+/** An AnnotationTarget with its locator type sealed inside, so targets whose
+ *  locators have nothing in common can share one list. */
+export interface SealedAnnotationTarget {
+	readonly kind: string
+	owns(snippet: string): boolean
+	find(snippet: string, root: ParentNode): HTMLElement | null
+	restore(root: HTMLElement, ann: TargetAnnotation): void
+	describe(snippet: string): string | null
+}
+
+/** Close over the locator type, so parse and find can never be called with
+ *  a locator the other one did not produce. */
+export function sealTarget<L extends object>(target: AnnotationTarget<L>): SealedAnnotationTarget {
+	return {
+		kind: target.kind,
+		owns: (snippet) => target.parse(snippet) !== null,
+		find: (snippet, root) => {
+			const locator = target.parse(snippet)
+			return locator === null ? null : target.find(locator, root)
+		},
+		restore: (root, ann) => {
+			const locator = target.parse(ann.snippet)
+			if (locator === null) return
+			target.restore?.(locator, root, ann)
+		},
+		describe: (snippet) => {
+			const locator = target.parse(snippet)
+			if (locator === null || !target.describe) return null
+			return target.describe(locator)
+		},
+	}
+}

package/src/blockTarget.ts

@@ -0,0 +1,127 @@
+import type { AnnotationTarget } from './annotationTarget'
+
+/**
+ * A whole canvas block, identified by the text a reader sees in it.
+ *
+ * The hard-won invariant lives here: the selector that decides where an
+ * annotation may be minted and the selector the lookup scans must be one
+ * selector. An annotation minted on a block the lookup skips can never be
+ * resolved again. Both now come off one table, so they cannot drift: a kind is
+ * annotatable exactly when it can mint a snippet, and `getBlockSnippet` refuses
+ * every block outside that set.
+ */
+interface BlockKind {
+	/** CSS matching this kind, as the component emits it. */
+	selector: string
+	/** The key a block of this kind is annotated under, or null when it is
+	 *  missing the attribute that identifies it. */
+	snippet(block: HTMLElement): string | null
+}
+
+/**
+ * A block's text as a reader sees it. Decorative markup — the callout icon,
+ * anything else marked aria-hidden — is skipped, so the glyph does not ride
+ * along into the sidebar label and into feedback.md.
+ */
+function readableText(block: HTMLElement): string {
+	const walker = document.createTreeWalker(block, NodeFilter.SHOW_TEXT)
+	let text = ''
+	for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+		const hidden = node.parentElement?.closest("[aria-hidden='true']")
+		if (hidden && block.contains(hidden)) continue
+		text += node.textContent ?? ''
+	}
+	return text.trim()
+}
+
+/** A block named by one of its attributes, e.g. `[Item] Ship the beta`. */
+function byAttribute(selector: string, prefix: string, attribute: string): BlockKind {
+	return {
+		selector,
+		snippet: (block) => {
+			const value = block.getAttribute(attribute)
+			return value ? `${prefix} ${value}` : null
+		},
+	}
+}
+
+/** Every block an annotation can be minted on. */
+const ANNOTATABLE_KINDS: BlockKind[] = [
+	byAttribute("[data-md='item']", '[Item]', 'data-md-label'),
+	byAttribute("[data-md='section']", '[Section]', 'data-md-title'),
+	byAttribute("[data-md='checklist-item']", '[Checklist]', 'data-md-label'),
+	byAttribute("[data-md='image']", '[Image]', 'data-md-src'),
+	{
+		selector: "[data-md='callout']",
+		snippet: (block) => {
+			const type = block.getAttribute('data-md-type') || 'info'
+			return `[Callout:${type}] ${readableText(block).slice(0, 60) || 'Callout'}`
+		},
+	},
+	{
+		selector: "[data-md='note']",
+		snippet: (block) => `[Note] ${readableText(block).slice(0, 60) || 'Note'}`,
+	},
+	{
+		// Only rows of a table the canvas emitted: a table inside a markdown block
+		// is not navigable, so a row annotated there could never be reached again.
+		selector: "[data-md='table'] tbody tr",
+		snippet: (block) => {
+			const cells = Array.from(block.querySelectorAll('td')).map((td) => td.textContent?.trim()).filter(Boolean)
+			return cells.length ? `[Row] ${cells.join(' | ')}` : null
+		},
+	},
+]
+
+/** Blocks the arrows walk but no annotation can land on — interactive controls
+ *  carry the reader's answer, not the author's text. */
+const NAVIGABLE_ONLY_SELECTORS = [
+	"[data-md='choice-option']",
+	"[data-md='multichoice-option']",
+	"[data-md='userinput']",
+	"[data-md='rangeinput']",
+]
+
+/**
+ * The blocks that can carry a block annotation — a strict subset of
+ * BLOCK_SELECTOR, since interactive controls are navigable but not annotatable.
+ */
+export const ANNOTATABLE_SELECTOR = ANNOTATABLE_KINDS.map((kind) => kind.selector).join(', ')
+
+/** Every block the keyboard arrows walk through. */
+export const BLOCK_SELECTOR = [
+	...ANNOTATABLE_KINDS.map((kind) => kind.selector),
+	...NAVIGABLE_ONLY_SELECTORS,
+].join(', ')
+
+/** The snippet identifier for a block, or null if nothing can be annotated here. */
+export function getBlockSnippet(block: HTMLElement): string | null {
+	for (const kind of ANNOTATABLE_KINDS) {
+		if (block.matches(kind.selector)) return kind.snippet(block)
+	}
+	return null
+}
+
+/** A block is its own locator: the snippet is the text that identifies it. */
+export interface BlockLocator {
+	snippet: string
+}
+
+export const blockTarget: AnnotationTarget<BlockLocator> = {
+	kind: 'block',
+
+	// Every block snippet opens with its kind in brackets. Text that merely looks
+	// like one is not stranded by claiming it: `find` compares against snippets
+	// blocks actually mint, so a lookalike simply matches nothing.
+	parse: (snippet) => (snippet.startsWith('[') ? { snippet } : null),
+
+	format: (locator) => locator.snippet,
+
+	find: (locator, root) => {
+		for (const el of root.querySelectorAll(ANNOTATABLE_SELECTOR)) {
+			if (!(el instanceof HTMLElement)) continue
+			if (getBlockSnippet(el) === locator.snippet) return el
+		}
+		return null
+	},
+}

package/src/highlightRange.ts

@@ -0,0 +1,262 @@
+/**
+ * Wraps the current browser Range in <mark> elements with the given annotation ID.
+ * Works for multiline / cross-element selections.
+ */
+export function wrapRangeWithMark(range: Range, annotationId: string): HTMLElement[] {
+	const marks: HTMLElement[] = []
+
+	// Collect all text nodes within the range
+	const textNodes = getTextNodesInRange(range)
+
+	for (const tn of textNodes) {
+		const nodeRange = document.createRange()
+		nodeRange.selectNodeContents(tn)
+
+		// Clamp to the actual selection range
+		if (tn === range.startContainer) {
+			nodeRange.setStart(tn, range.startOffset)
+		}
+		if (tn === range.endContainer) {
+			nodeRange.setEnd(tn, range.endOffset)
+		}
+
+		const text = nodeRange.toString()
+		if (!text || !text.trim()) continue
+
+		// Wrap this portion in a <mark>
+		const mark = document.createElement('mark')
+		mark.setAttribute('data-annotation-id', annotationId)
+
+		try {
+			nodeRange.surroundContents(mark)
+		} catch {
+			// surroundContents fails if range crosses element boundaries within a single text node
+			// (shouldn't happen for a single text node, but handle gracefully)
+			const fragment = nodeRange.extractContents()
+			mark.appendChild(fragment)
+			nodeRange.insertNode(mark)
+		}
+
+		marks.push(mark)
+	}
+
+	return marks
+}
+
+/**
+ * Whether the annotation index carries this text. Line-number gutters and text
+ * that already belongs to another annotation are outside it. Everything that
+ * records a snippet or its context is matched back against that index later, so
+ * all of them have to skip exactly the same runs.
+ */
+export function isIndexedText(node: Text): boolean {
+	const parent = node.parentElement
+	if (parent?.classList.contains('select-none')) return false
+	if (parent?.closest('[data-annotation-id]')) return false
+	return true
+}
+
+function getTextNodesInRange(range: Range): Text[] {
+	const nodes: Text[] = []
+	const ancestor = range.commonAncestorContainer
+
+	if (ancestor.nodeType === Node.TEXT_NODE) {
+		nodes.push(ancestor as Text)
+		return nodes
+	}
+
+	const walker = document.createTreeWalker(ancestor, NodeFilter.SHOW_TEXT)
+	let node: Text | null
+	while ((node = walker.nextNode() as Text | null)) {
+		if (!isIndexedText(node)) continue
+		if (range.intersectsNode(node)) {
+			nodes.push(node)
+		}
+	}
+
+	return nodes
+}
+
+/** The part of a text node that falls inside the range. */
+function clampToRange(node: Text, range: Range): string {
+	const nodeRange = document.createRange()
+	nodeRange.selectNodeContents(node)
+	if (node === range.startContainer) nodeRange.setStart(node, range.startOffset)
+	if (node === range.endContainer) nodeRange.setEnd(node, range.endOffset)
+	return nodeRange.toString()
+}
+
+/**
+ * A selection's text as the annotation index will read it back. The raw
+ * selection is not that: it carries the gutter and any text already inside
+ * another annotation, none of which the index holds — so a snippet taken from
+ * it names something that cannot be found again.
+ */
+export function rangeIndexText(range: Range): string {
+	let text = ''
+	for (const node of getTextNodesInRange(range)) {
+		text += clampToRange(node, range)
+	}
+	return text
+}
+
+/**
+ * Update the visual state of marks for a given annotation ID.
+ */
+export function setMarkActive(annotationId: string, active: boolean) {
+	const marks = document.querySelectorAll(`[data-annotation-id="${annotationId}"]`)
+	for (const mark of marks) {
+		;(mark as HTMLElement).classList.toggle('mark-active', active)
+	}
+}
+
+/**
+ * Update active state for annotation marks.
+ * Only touches marks for the previous and current active IDs to avoid full DOM scans.
+ */
+export function updateAllMarkStates(activeId: string | null, prevActiveId?: string | null) {
+	if (prevActiveId != null && prevActiveId !== activeId) {
+		setMarkActive(prevActiveId, false)
+	}
+	if (activeId != null) {
+		setMarkActive(activeId, true)
+	}
+}
+
+/**
+ * Rename annotation ID on existing marks (e.g. temp → real ID).
+ */
+export function renameMarkId(oldId: string, newId: string) {
+	const marks = document.querySelectorAll(`[data-annotation-id="${oldId}"]`)
+	for (const mark of marks) {
+		mark.setAttribute('data-annotation-id', newId)
+	}
+}
+
+/**
+ * Restore marks for persisted annotations by finding their snippet text in the DOM.
+ * Uses before/after context for disambiguation when the same text appears multiple times.
+ */
+export function restoreMarks(
+	container: HTMLElement,
+	annotations: { id: string; snippet: string; filePath?: string; context?: { before: string; after: string; hierarchy: string[] } }[],
+) {
+	for (const ann of annotations) {
+		// A canvas can be rendered more than once (overview, compare, hidden
+		// source panes), so restore decisions must be scoped to this container.
+		if (container.querySelector(`[data-annotation-id="${ann.id}"]`)) continue
+
+		const snippet = ann.snippet
+		if (!snippet) continue
+
+		// Rebuild after every inserted mark. Wrapping text splits and moves text
+		// nodes, so a cached offset map can point at stale DOM after the first hit.
+		const { fullText, textNodes } = buildTextIndex(container)
+
+		// Find all occurrences of the snippet in the full text
+		const occurrences: number[] = []
+		let searchFrom = 0
+		while (true) {
+			const idx = fullText.indexOf(snippet, searchFrom)
+			if (idx === -1) break
+			occurrences.push(idx)
+			searchFrom = idx + 1
+		}
+
+		const [firstOccurrence] = occurrences
+		if (firstOccurrence === undefined) continue
+
+		// Pick the best occurrence using context
+		let bestIdx = firstOccurrence
+		if (occurrences.length > 1 && ann.context) {
+			let bestScore = -1
+			for (const idx of occurrences) {
+				let score = 0
+				if (ann.context.before) {
+					const preceding = fullText.slice(Math.max(0, idx - 80), idx)
+					if (preceding.includes(ann.context.before)) score += 2
+					else if (ann.context.before.length > 10 && preceding.includes(ann.context.before.slice(-10))) score += 1
+				}
+				if (ann.context.after) {
+					const following = fullText.slice(idx + snippet.length, idx + snippet.length + 80)
+					if (following.includes(ann.context.after)) score += 2
+					else if (ann.context.after.length > 10 && following.includes(ann.context.after.slice(0, 10))) score += 1
+				}
+				if (score > bestScore) {
+					bestScore = score
+					bestIdx = idx
+				}
+			}
+		}
+
+		// Map text offsets to DOM positions
+		const startOffset = bestIdx
+		const endOffset = bestIdx + snippet.length
+
+		const startPos = offsetToNode(textNodes, startOffset)
+		const endPos = offsetToNode(textNodes, endOffset)
+		if (!startPos || !endPos) continue
+
+		try {
+			const range = document.createRange()
+			range.setStart(startPos.node, startPos.offset)
+			range.setEnd(endPos.node, endPos.offset)
+			wrapRangeWithMark(range, ann.id)
+		} catch {}
+	}
+}
+
+function buildTextIndex(container: HTMLElement): {
+	fullText: string
+	textNodes: { node: Text; start: number }[]
+} {
+	const textNodes: { node: Text; start: number }[] = []
+	let fullText = ''
+	const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT)
+	let tn: Text | null
+	while ((tn = walker.nextNode() as Text | null)) {
+		if (!isIndexedText(tn)) continue
+		textNodes.push({ node: tn, start: fullText.length })
+		fullText += tn.textContent || ''
+	}
+	return { fullText, textNodes }
+}
+
+function offsetToNode(
+	textNodes: { node: Text; start: number }[],
+	offset: number,
+): { node: Text; offset: number } | null {
+	for (let i = textNodes.length - 1; i >= 0; i--) {
+		const entry = textNodes[i]
+		if (!entry || entry.start > offset) continue
+		const localOffset = offset - entry.start
+		const nodeLen = entry.node.textContent?.length ?? 0
+		if (localOffset <= nodeLen) {
+			return { node: entry.node, offset: localOffset }
+		}
+	}
+	return null
+}
+
+/**
+ * Remove the decoration for a given annotation ID, restoring the original text
+ * nodes an inline mark wrapped.
+ */
+export function unwrapMarks(annotationId: string) {
+	const marks = document.querySelectorAll(`[data-annotation-id="${annotationId}"]`)
+	for (const mark of marks) {
+		const parent = mark.parentNode
+		if (!parent) continue
+		// Decoration that is not an inline mark — a region overlay — wraps no text
+		// and is simply taken out.
+		if (mark.tagName !== 'MARK') {
+			parent.removeChild(mark)
+			continue
+		}
+		while (mark.firstChild) {
+			parent.insertBefore(mark.firstChild, mark)
+		}
+		parent.removeChild(mark)
+		parent.normalize()
+	}
+}

package/src/popoverPosition.ts

@@ -0,0 +1,46 @@
+/** Width assumed when the caller does not say — the narrow popover. */
+const DEFAULT_POPOVER_WIDTH = 280
+
+/**
+ * Read a CSS width the popover will be styled with. Only px is a width this
+ * placement can reason about; anything else falls back to the default rather
+ * than clamping against a number that means something different.
+ */
+export function pxWidth(css: string): number | undefined {
+	const match = /^(\d+(?:\.\d+)?)px$/.exec(css.trim())
+	return match ? Number(match[1]) : undefined
+}
+
+/**
+ * Calculate popover position relative to an anchor element.
+ * Returns absolute position within the scroll container (or body).
+ */
+export function getPopoverPosition(
+	anchor: HTMLElement,
+	scrollContainer?: HTMLElement | null,
+	popoverWidth: number = DEFAULT_POPOVER_WIDTH,
+): { style: Record<string, string>; parent: HTMLElement } {
+	const gap = 8
+	const parent = scrollContainer || document.body
+
+	// Use getBoundingClientRect for both anchor and parent,
+	// then add scroll offsets to get absolute position within parent
+	const anchorRect = anchor.getBoundingClientRect()
+	const parentRect = parent.getBoundingClientRect()
+
+	// Both rects are viewport-relative, so the subtraction has already cancelled
+	// page scroll. Only a scrolling parent adds to that — the body is not what
+	// scrolls a document, and counting window.scrollY here counted it twice.
+	const scrollTop = parent === document.body ? 0 : parent.scrollTop
+	const top = anchorRect.bottom - parentRect.top + scrollTop + gap
+
+	// Horizontal: clamp to parent width
+	const left = Math.max(0, Math.min(anchorRect.left - parentRect.left, parentRect.width - popoverWidth - 12))
+
+	parent.style.position = 'relative'
+
+	return {
+		style: { position: 'absolute', top: `${top}px`, left: `${left}px` },
+		parent,
+	}
+}