@nuasite/notes 0.1.0

package/src/integration.ts

@@ -0,0 +1,168 @@
+import type { AstroIntegration } from 'astro'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createNotesDevMiddleware } from './dev/middleware'
+import { NotesJsonStore } from './storage/json-store'
+import type { NuaNotesOptions } from './types'
+
+/**
+ * `@nuasite/notes` Astro integration.
+ *
+ * Adds a Pastel-style comment overlay (Phase 2) and a Google Docs-style
+ * suggestion overlay (Phase 3+) alongside `@nuasite/cms`. Activated by
+ * visiting any page with the `?nua-notes` query flag (or with the
+ * `nua-notes-mode=1` cookie set).
+ *
+ * What ships in each phase:
+ *   Phase 0: marker script proves the integration mounts
+ *   Phase 1: dev API + JSON storage at /_nua/notes/*
+ *   Phase 2: Preact overlay v1 — sidebar, comment popover, mode toggle
+ *   Phase 3: range suggestions with diff preview
+ *   Phase 4: apply flow (peer-imports @nuasite/cms source-finder)
+ *   Phase 5: proxy support, replies, agency inbox
+ */
+
+const VIRTUAL_OVERLAY_PATH = '/@nuasite/notes-overlay.js'
+
+export default function nuaNotes(options: NuaNotesOptions = {}): AstroIntegration {
+	const {
+		enabled = true,
+		urlFlag = 'nua-notes',
+		notesDir = 'data/notes',
+	} = options
+
+	// Lazily constructed in `astro:config:setup` once we know the project root.
+	let store: NotesJsonStore | null = null
+	let projectRoot: string | null = null
+
+	return {
+		name: '@nuasite/notes',
+		hooks: {
+			'astro:config:setup': ({ command, config, injectScript, updateConfig, logger }) => {
+				// Notes is dev-only, mirroring @nuasite/cms.
+				if (command !== 'dev') return
+				if (!enabled) {
+					logger.info('@nuasite/notes is disabled via options.enabled')
+					return
+				}
+
+				// Astro provides the project root as a file:// URL on `config.root`.
+				projectRoot = fileURLToPath(config.root)
+				store = new NotesJsonStore({ projectRoot, notesDir })
+
+				// Two delivery modes for the overlay (mirrors @nuasite/cms):
+				//
+				//  1. NPM install case: a pre-built `dist/overlay.js` ships with
+				//     the package and is served as the virtual module. The bundle
+				//     has preact, the overlay sources, and the inlined CSS — the
+				//     consumer needs zero peer dependencies.
+				//
+				//  2. Monorepo dev case (this repo's playground): no pre-built
+				//     bundle exists, so we resolve the virtual module to the
+				//     source `overlay/index.tsx` and let Vite compile it on the
+				//     fly using the JSX-pragma transform plugin below. preact is
+				//     resolved through the workspace devDependency.
+				const notesDirAbs = dirname(fileURLToPath(import.meta.url))
+				const overlayBundlePath = join(notesDirAbs, '../dist/overlay.js')
+				const hasPrebuiltBundle = existsSync(overlayBundlePath)
+				const overlayEntry = join(notesDirAbs, 'overlay/index.tsx')
+
+				// Inject a small loader on every page. It writes the runtime config
+				// (window.__NuaNotesConfig) and adds the overlay script tag once.
+				// The overlay itself decides at runtime whether to mount based on
+				// the URL flag / cookie, so the cost on non-review pages is a tiny
+				// idempotent script tag.
+				injectScript(
+					'page',
+					`
+					(function () {
+						if (window.__nuasiteNotesAlive) return;
+						window.__nuasiteNotesAlive = true;
+						window.__NuaNotesConfig = ${JSON.stringify({ urlFlag })};
+						if (!document.querySelector('script[data-nuasite-notes]')) {
+							const s = document.createElement('script');
+							s.type = 'module';
+							s.src = ${JSON.stringify(VIRTUAL_OVERLAY_PATH)};
+							s.dataset.nuasiteNotes = '';
+							document.head.appendChild(s);
+						}
+					})();
+					`,
+				)
+
+				// Vite plugins:
+				//   - In bundle mode: serve the pre-built overlay.js as the
+				//     virtual module via a load() hook. No source compilation
+				//     needed and the consumer doesn't need preact installed.
+				//   - In source mode (monorepo dev): resolve the virtual path to
+				//     the real .tsx file AND prepend the @jsxImportSource pragma
+				//     so Vite's esbuild compiles JSX with Preact's `h` instead
+				//     of React (which the host project may use).
+				const vitePlugins: any[] = []
+
+				if (hasPrebuiltBundle) {
+					const bundleContent = readFileSync(overlayBundlePath, 'utf-8')
+					vitePlugins.push({
+						name: 'nuasite-notes-overlay-bundle',
+						resolveId(id: string) {
+							if (id === VIRTUAL_OVERLAY_PATH) return VIRTUAL_OVERLAY_PATH
+						},
+						load(id: string) {
+							if (id === VIRTUAL_OVERLAY_PATH) return bundleContent
+						},
+					})
+				} else {
+					vitePlugins.push(
+						{
+							name: 'nuasite-notes-overlay-resolver',
+							resolveId(id: string) {
+								if (id === VIRTUAL_OVERLAY_PATH) return overlayEntry
+							},
+						},
+						{
+							name: 'nuasite-notes-preact-jsx',
+							transform(code: string, id: string) {
+								if (id.includes('/notes/src/overlay/') && id.endsWith('.tsx') && !code.includes('@jsxImportSource')) {
+									return `/** @jsxImportSource preact */\n${code}`
+								}
+							},
+						},
+					)
+				}
+
+				// Only force the react→preact alias in source mode. In bundle
+				// mode, preact is already inlined in the bundle and the alias
+				// could conflict with consumer apps that legitimately use React.
+				updateConfig({
+					vite: {
+						plugins: vitePlugins,
+						resolve: hasPrebuiltBundle ? undefined : {
+							alias: {
+								'react': 'preact/compat',
+								'react-dom': 'preact/compat',
+								'react/jsx-runtime': 'preact/jsx-runtime',
+							},
+						},
+					},
+				})
+
+				logger.info(
+					`@nuasite/notes injected (notesDir: ${notesDir}, ${hasPrebuiltBundle ? 'pre-built overlay' : 'source overlay'})`,
+				)
+			},
+
+			'astro:server:setup': ({ server, logger }) => {
+				if (!enabled) return
+				if (!store || !projectRoot) {
+					logger.warn('@nuasite/notes server:setup ran before config:setup; skipping')
+					return
+				}
+				createNotesDevMiddleware(server, store, projectRoot)
+				logger.info('@nuasite/notes API enabled at /_nua/notes/')
+			},
+		},
+	}
+}
+
+export { nuaNotes }

package/src/overlay/App.tsx

@@ -0,0 +1,434 @@
+/** @jsxImportSource preact */
+import { useCallback, useEffect, useMemo, useState } from 'preact/hooks'
+import { CommentPopover } from './components/CommentPopover'
+import { ElementHighlight } from './components/ElementHighlight'
+import { SelectionTooltip } from './components/SelectionTooltip'
+import { Sidebar } from './components/Sidebar'
+import { SuggestPopover } from './components/SuggestPopover'
+import { Toolbar } from './components/Toolbar'
+import { fetchPageManifest } from './lib/manifest-fetch'
+import { applyNote, createNote, deleteNote, listNotes, setNoteStatus } from './lib/notes-fetch'
+import { findAnchorRange, selectionInsideElement } from './lib/range-anchor'
+import { exitReviewMode, getCurrentPagePath } from './lib/url-mode'
+import type { CmsPageManifest, NoteItem } from './types'
+
+interface AppProps {
+	urlFlag: string
+}
+
+interface PickState {
+	cmsId: string
+	rect: { x: number; y: number; width: number; height: number }
+	snippet?: string
+}
+
+interface SelectionState {
+	cmsId: string
+	anchorText: string
+	rect: { x: number; y: number; width: number; height: number }
+	elementRect: { x: number; y: number; width: number; height: number }
+	elementSnippet?: string
+}
+
+const AUTHOR_KEY = 'nua-notes-author'
+
+function loadAuthor(): string {
+	try {
+		return localStorage.getItem(AUTHOR_KEY) || ''
+	} catch {
+		return ''
+	}
+}
+
+function saveAuthor(name: string): void {
+	try {
+		localStorage.setItem(AUTHOR_KEY, name)
+	} catch {
+		// ignore
+	}
+}
+
+function getRect(el: Element): { x: number; y: number; width: number; height: number } {
+	const r = el.getBoundingClientRect()
+	return { x: r.x, y: r.y, width: r.width, height: r.height }
+}
+
+function rectFromDom(r: DOMRect): { x: number; y: number; width: number; height: number } {
+	return { x: r.x, y: r.y, width: r.width, height: r.height }
+}
+
+function findCmsAncestor(target: EventTarget | null): Element | null {
+	let el = target as Element | null
+	while (el && el.nodeType === 1) {
+		if (el.hasAttribute?.('data-cms-id')) return el
+		el = el.parentElement
+	}
+	return null
+}
+
+export function App({ urlFlag }: AppProps) {
+	const page = useMemo(() => getCurrentPagePath(), [])
+	const [items, setItems] = useState<NoteItem[]>([])
+	const [manifest, setManifest] = useState<CmsPageManifest | null>(null)
+	const [picking, setPicking] = useState(false)
+	const [hoverRect, setHoverRect] = useState<PickState | null>(null)
+	const [pendingPick, setPendingPick] = useState<PickState | null>(null)
+	const [pendingSuggest, setPendingSuggest] = useState<SelectionState | null>(null)
+	const [pendingSelection, setPendingSelection] = useState<SelectionState | null>(null)
+	const [activeId, setActiveId] = useState<string | null>(null)
+	const [activeRect, setActiveRect] = useState<{ x: number; y: number; width: number; height: number } | null>(null)
+	const [error, setError] = useState<string | null>(null)
+	const [author, setAuthor] = useState<string>(() => loadAuthor())
+	const [staleIds, setStaleIds] = useState<Set<string>>(new Set())
+	const [applyingId, setApplyingId] = useState<string | null>(null)
+
+	// Load notes + manifest on mount
+	useEffect(() => {
+		let alive = true
+		Promise.all([listNotes(page), fetchPageManifest(page)])
+			.then(([file, mf]) => {
+				if (!alive) return
+				setItems(file.items)
+				setManifest(mf)
+			})
+			.catch((err) => {
+				if (!alive) return
+				setError(err instanceof Error ? err.message : String(err))
+			})
+		return () => {
+			alive = false
+		}
+	}, [page])
+
+	// Re-attach suggestion anchors after items load. A suggestion is "stale"
+	// if its anchorText can't be found inside its target element anymore
+	// (e.g. the source file changed). Run on items change so HMR-driven
+	// edits update the warning live.
+	useEffect(() => {
+		const stale = new Set<string>()
+		for (const item of items) {
+			if (item.type !== 'suggestion' || !item.range) continue
+			const el = document.querySelector(`[data-cms-id="${item.targetCmsId}"]`)
+			if (!el) {
+				stale.add(item.id)
+				continue
+			}
+			const match = findAnchorRange(el, item.range.anchorText)
+			if (!match) stale.add(item.id)
+		}
+		setStaleIds(stale)
+	}, [items])
+
+	// Reposition the active highlight when the page scrolls or resizes.
+	// For suggestion items, prefer the anchor range rect over the element rect.
+	useEffect(() => {
+		if (!activeId) {
+			setActiveRect(null)
+			return
+		}
+		const item = items.find((i) => i.id === activeId)
+		if (!item) return
+		const el = document.querySelector(`[data-cms-id="${item.targetCmsId}"]`)
+		if (!el) {
+			setActiveRect(null)
+			return
+		}
+		const updateRect = () => {
+			if (item.type === 'suggestion' && item.range) {
+				const match = findAnchorRange(el, item.range.anchorText)
+				if (match) {
+					setActiveRect(rectFromDom(match.rect))
+					return
+				}
+			}
+			setActiveRect(getRect(el))
+		}
+		updateRect()
+		window.addEventListener('scroll', updateRect, true)
+		window.addEventListener('resize', updateRect)
+		return () => {
+			window.removeEventListener('scroll', updateRect, true)
+			window.removeEventListener('resize', updateRect)
+		}
+	}, [activeId, items])
+
+	// Picking-mode hover and click handlers
+	useEffect(() => {
+		if (!picking) {
+			setHoverRect(null)
+			return
+		}
+		const onMove = (e: MouseEvent) => {
+			const el = findCmsAncestor(e.target)
+			if (!el) {
+				setHoverRect(null)
+				return
+			}
+			const cmsId = el.getAttribute('data-cms-id')!
+			setHoverRect({ cmsId, rect: getRect(el) })
+		}
+		const onClick = (e: MouseEvent) => {
+			const el = findCmsAncestor(e.target)
+			if (!el) return
+			e.preventDefault()
+			e.stopPropagation()
+			const cmsId = el.getAttribute('data-cms-id')!
+			const text = (el.textContent || '').trim().slice(0, 200)
+			setPendingPick({ cmsId, rect: getRect(el), snippet: text })
+			setPicking(false)
+		}
+		document.addEventListener('mousemove', onMove, true)
+		document.addEventListener('click', onClick, true)
+		return () => {
+			document.removeEventListener('mousemove', onMove, true)
+			document.removeEventListener('click', onClick, true)
+		}
+	}, [picking])
+
+	// Text selection capture (for the suggestion flow). Only active when not
+	// in pick mode and no popover is open. Listens for selectionchange and
+	// translates the current Selection into a SelectionState if it lands
+	// inside a single data-cms-id element.
+	useEffect(() => {
+		if (picking || pendingPick || pendingSuggest) {
+			setPendingSelection(null)
+			return
+		}
+		const onSelectionChange = () => {
+			const sel = document.getSelection()
+			if (!sel || sel.rangeCount === 0 || sel.isCollapsed) {
+				setPendingSelection(null)
+				return
+			}
+			const range = sel.getRangeAt(0)
+			const startEl = range.startContainer.nodeType === 3
+				? range.startContainer.parentElement
+				: range.startContainer as Element
+			if (!startEl) return
+			const cmsEl = findCmsAncestor(startEl)
+			if (!cmsEl) {
+				setPendingSelection(null)
+				return
+			}
+			// Selection must stay inside the same data-cms-id element
+			if (!cmsEl.contains(range.endContainer)) {
+				setPendingSelection(null)
+				return
+			}
+			const inside = selectionInsideElement(cmsEl, sel)
+			if (!inside) {
+				setPendingSelection(null)
+				return
+			}
+			const cmsId = cmsEl.getAttribute('data-cms-id')!
+			const elementSnippet = (cmsEl.textContent || '').trim().slice(0, 200)
+			setPendingSelection({
+				cmsId,
+				anchorText: inside.text,
+				rect: rectFromDom(inside.rect),
+				elementRect: getRect(cmsEl),
+				elementSnippet,
+			})
+		}
+		document.addEventListener('selectionchange', onSelectionChange)
+		return () => document.removeEventListener('selectionchange', onSelectionChange)
+	}, [picking, pendingPick, pendingSuggest])
+
+	const handleCreateComment = useCallback(
+		async (body: string, authorName: string) => {
+			if (!pendingPick) return
+			saveAuthor(authorName)
+			setAuthor(authorName)
+			const entry = manifest?.entries?.[pendingPick.cmsId]
+			try {
+				const item = await createNote({
+					page,
+					type: 'comment',
+					targetCmsId: pendingPick.cmsId,
+					targetSourcePath: entry?.sourcePath,
+					targetSourceLine: entry?.sourceLine,
+					targetSnippet: entry?.sourceSnippet ?? pendingPick.snippet,
+					body,
+					author: authorName,
+				})
+				setItems((prev) => [...prev, item])
+				setActiveId(item.id)
+				setPendingPick(null)
+				setError(null)
+			} catch (err) {
+				setError(err instanceof Error ? err.message : String(err))
+			}
+		},
+		[page, pendingPick, manifest],
+	)
+
+	const handleCreateSuggestion = useCallback(
+		async (input: { suggestedText: string; rationale: string; body: string; author: string }) => {
+			if (!pendingSuggest) return
+			saveAuthor(input.author)
+			setAuthor(input.author)
+			const entry = manifest?.entries?.[pendingSuggest.cmsId]
+			try {
+				const item = await createNote({
+					page,
+					type: 'suggestion',
+					targetCmsId: pendingSuggest.cmsId,
+					targetSourcePath: entry?.sourcePath,
+					targetSourceLine: entry?.sourceLine,
+					targetSnippet: entry?.sourceSnippet ?? pendingSuggest.elementSnippet,
+					range: {
+						anchorText: pendingSuggest.anchorText,
+						originalText: pendingSuggest.anchorText,
+						suggestedText: input.suggestedText,
+						rationale: input.rationale || undefined,
+					},
+					body: input.body,
+					author: input.author,
+				})
+				setItems((prev) => [...prev, item])
+				setActiveId(item.id)
+				setPendingSuggest(null)
+				setPendingSelection(null)
+				// Clear the page selection so the tooltip doesn't reopen
+				try {
+					document.getSelection()?.removeAllRanges()
+				} catch {}
+				setError(null)
+			} catch (err) {
+				setError(err instanceof Error ? err.message : String(err))
+			}
+		},
+		[page, pendingSuggest, manifest],
+	)
+
+	const handleResolve = useCallback(async (id: string) => {
+		try {
+			const item = await setNoteStatus(page, id, 'resolved')
+			setItems((prev) => prev.map((i) => (i.id === id ? item : i)))
+		} catch (err) {
+			setError(err instanceof Error ? err.message : String(err))
+		}
+	}, [page])
+
+	const handleReopen = useCallback(async (id: string) => {
+		try {
+			const item = await setNoteStatus(page, id, 'open')
+			setItems((prev) => prev.map((i) => (i.id === id ? item : i)))
+		} catch (err) {
+			setError(err instanceof Error ? err.message : String(err))
+		}
+	}, [page])
+
+	const handleDelete = useCallback(async (id: string) => {
+		try {
+			await deleteNote(page, id)
+			setItems((prev) => prev.filter((i) => i.id !== id))
+			if (activeId === id) setActiveId(null)
+		} catch (err) {
+			setError(err instanceof Error ? err.message : String(err))
+		}
+	}, [page, activeId])
+
+	const handleApply = useCallback(async (id: string) => {
+		setApplyingId(id)
+		try {
+			const result = await applyNote(page, id)
+			// On both success and 409 the server returns an updated item
+			setItems((prev) => prev.map((i) => (i.id === id ? result.item : i)))
+			if (result.error) {
+				setError(result.error)
+			} else {
+				setError(null)
+			}
+		} catch (err) {
+			setError(err instanceof Error ? err.message : String(err))
+		} finally {
+			setApplyingId(null)
+		}
+	}, [page])
+
+	const handleSelectionComment = useCallback(() => {
+		if (!pendingSelection) return
+		// Convert the selection into a comment on the parent element
+		setPendingPick({
+			cmsId: pendingSelection.cmsId,
+			rect: pendingSelection.elementRect,
+			snippet: pendingSelection.anchorText,
+		})
+		setPendingSelection(null)
+	}, [pendingSelection])
+
+	const handleSelectionSuggest = useCallback(() => {
+		if (!pendingSelection) return
+		setPendingSuggest(pendingSelection)
+		setPendingSelection(null)
+	}, [pendingSelection])
+
+	return (
+		<div class="notes-root">
+			<Toolbar
+				page={page}
+				count={items.length}
+				picking={picking}
+				onTogglePick={() => {
+					setPicking((p) => !p)
+					setPendingPick(null)
+					setPendingSuggest(null)
+				}}
+				onExit={() => exitReviewMode(urlFlag)}
+			/>
+			<Sidebar
+				page={page}
+				items={items}
+				activeId={activeId}
+				picking={picking}
+				error={error}
+				staleIds={staleIds}
+				applyingId={applyingId}
+				onFocus={setActiveId}
+				onResolve={handleResolve}
+				onReopen={handleReopen}
+				onDelete={handleDelete}
+				onApply={handleApply}
+			/>
+			{picking && hoverRect ? <ElementHighlight rect={hoverRect.rect} /> : null}
+			{activeRect ? <ElementHighlight rect={activeRect} persistent /> : null}
+			{pendingSelection && !pendingPick && !pendingSuggest
+				? (
+					<SelectionTooltip
+						rect={pendingSelection.rect}
+						onComment={handleSelectionComment}
+						onSuggest={handleSelectionSuggest}
+					/>
+				)
+				: null}
+			{pendingPick
+				? (
+					<CommentPopover
+						rect={pendingPick.rect}
+						snippet={pendingPick.snippet}
+						defaultAuthor={author}
+						onCancel={() => setPendingPick(null)}
+						onSubmit={handleCreateComment}
+					/>
+				)
+				: null}
+			{pendingSuggest
+				? (
+					<SuggestPopover
+						rect={pendingSuggest.rect}
+						originalText={pendingSuggest.anchorText}
+						defaultAuthor={author}
+						onCancel={() => {
+							setPendingSuggest(null)
+							try {
+								document.getSelection()?.removeAllRanges()
+							} catch {}
+						}}
+						onSubmit={handleCreateSuggestion}
+					/>
+				)
+				: null}
+		</div>
+	)
+}

package/src/overlay/components/CommentPopover.tsx

@@ -0,0 +1,96 @@
+/** @jsxImportSource preact */
+import { useEffect, useRef, useState } from 'preact/hooks'
+
+interface CommentPopoverProps {
+	rect: { x: number; y: number; width: number; height: number }
+	snippet?: string
+	defaultAuthor: string
+	onCancel: () => void
+	onSubmit: (body: string, author: string) => void | Promise<void>
+}
+
+/**
+ * Popover anchored to the right of the picked element. Submits a free-form
+ * comment body with an author name (persisted in localStorage by the App).
+ *
+ * Stops propagation on its own clicks so the App's outside-click handler
+ * doesn't immediately close it.
+ */
+export function CommentPopover({ rect, snippet, defaultAuthor, onCancel, onSubmit }: CommentPopoverProps) {
+	const [body, setBody] = useState('')
+	const [author, setAuthor] = useState(defaultAuthor)
+	const [submitting, setSubmitting] = useState(false)
+	const textareaRef = useRef<HTMLTextAreaElement>(null)
+
+	useEffect(() => {
+		textareaRef.current?.focus()
+	}, [])
+
+	const handleSubmit = async () => {
+		if (!body.trim() || submitting) return
+		setSubmitting(true)
+		try {
+			await onSubmit(body.trim(), author.trim() || 'Anonymous')
+		} finally {
+			setSubmitting(false)
+		}
+	}
+
+	const handleKey = (e: KeyboardEvent) => {
+		if (e.key === 'Escape') {
+			e.preventDefault()
+			onCancel()
+		} else if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+			e.preventDefault()
+			handleSubmit()
+		}
+	}
+
+	// Position to the right of the element when there's room, otherwise left.
+	const sidebarWidth = 360
+	const popoverWidth = 320
+	const margin = 12
+	const viewportW = window.innerWidth - sidebarWidth
+	let left = rect.x + rect.width + margin
+	if (left + popoverWidth > viewportW) {
+		left = Math.max(margin, rect.x - popoverWidth - margin)
+	}
+	const top = Math.max(56, Math.min(rect.y, window.innerHeight - 260))
+
+	return (
+		<div
+			class="notes-popover"
+			style={{ left: `${left}px`, top: `${top}px` }}
+			onClick={(e) => e.stopPropagation()}
+			onKeyDown={handleKey}
+		>
+			<h4 class="notes-popover__title">Add comment</h4>
+			{snippet
+				? <div class="notes-popover__snippet">{snippet}</div>
+				: null}
+			<textarea
+				ref={textareaRef}
+				placeholder="Leave a note for the agency..."
+				value={body}
+				onInput={(e) => setBody((e.target as HTMLTextAreaElement).value)}
+			/>
+			<input
+				type="text"
+				placeholder="Your name"
+				value={author}
+				onInput={(e) => setAuthor((e.target as HTMLInputElement).value)}
+			/>
+			<div class="notes-popover__row">
+				<span class="notes-sidebar__hint">⌘+Enter to save</span>
+				<div style={{ display: 'flex', gap: '6px' }}>
+					<button class="notes-btn notes-btn--ghost" onClick={onCancel} disabled={submitting}>
+						Cancel
+					</button>
+					<button class="notes-btn notes-btn--primary" onClick={handleSubmit} disabled={!body.trim() || submitting}>
+						{submitting ? 'Saving...' : 'Save'}
+					</button>
+				</div>
+			</div>
+		</div>
+	)
+}