@nuasite/notes 0.1.0

package/src/overlay/lib/manifest-fetch.ts

@@ -0,0 +1,35 @@
+/**
+ * Read-only fetchers for `@nuasite/cms`'s public manifest endpoints.
+ *
+ * The overlay uses the per-page manifest to map a `data-cms-id` element back
+ * to its source file + line + snippet at the moment a note is created. We
+ * intentionally do NOT pull from the global `/cms-manifest.json` here — the
+ * per-page file already contains everything we need and is much smaller.
+ */
+
+import type { CmsPageManifest } from '../types'
+
+/**
+ * Build the per-page manifest URL for a page path.
+ *   /                       → /index.json
+ *   /inspekce-nemovitosti   → /inspekce-nemovitosti.json
+ *   /blog/post              → /blog/post.json
+ */
+export function manifestUrlForPage(page: string): string {
+	if (page === '' || page === '/') return '/index.json'
+	const trimmed = page.replace(/^\/+|\/+$/g, '')
+	return `/${trimmed}.json`
+}
+
+export async function fetchPageManifest(page: string): Promise<CmsPageManifest | null> {
+	const url = manifestUrlForPage(page)
+	try {
+		const res = await fetch(url, { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(10_000) })
+		if (!res.ok) return null
+		const data = (await res.json()) as CmsPageManifest
+		return data
+	} catch (err) {
+		console.warn(`[nuasite-notes] Failed to fetch CMS manifest for "${page}":`, err instanceof Error ? err.message : err)
+		return null
+	}
+}

package/src/overlay/lib/notes-fetch.ts

@@ -0,0 +1,121 @@
+/**
+ * Thin wrapper around `/_nua/notes/*` endpoints.
+ *
+ * All methods return parsed JSON. Errors throw with the server-provided
+ * message so the overlay can surface them in a banner.
+ */
+
+import type { NoteItem, NoteRange, NotesPageFile, NoteStatus, NoteType } from '../types'
+
+const BASE = '/_nua/notes'
+const TIMEOUT_MS = 10_000
+
+async function postJson<T>(path: string, body: unknown): Promise<T> {
+	const res = await fetch(`${BASE}${path}`, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify(body),
+		signal: AbortSignal.timeout(TIMEOUT_MS),
+	})
+	const text = await res.text()
+	let parsed: any
+	try {
+		parsed = text ? JSON.parse(text) : {}
+	} catch {
+		throw new Error(`notes: invalid JSON response from ${path}`)
+	}
+	if (!res.ok) {
+		throw new Error(parsed?.error ?? `notes: ${path} failed (${res.status})`)
+	}
+	return parsed as T
+}
+
+export async function listNotes(page: string): Promise<NotesPageFile> {
+	const res = await fetch(`${BASE}/list?page=${encodeURIComponent(page)}`, {
+		headers: { Accept: 'application/json' },
+		signal: AbortSignal.timeout(TIMEOUT_MS),
+	})
+	if (!res.ok) throw new Error(`notes: list failed (${res.status})`)
+	return (await res.json()) as NotesPageFile
+}
+
+export interface CreateInput {
+	page: string
+	type: NoteType
+	targetCmsId: string
+	targetSourcePath?: string
+	targetSourceLine?: number
+	targetSnippet?: string
+	range?: NoteRange | null
+	body: string
+	author: string
+}
+
+export async function createNote(input: CreateInput): Promise<NoteItem> {
+	const res = await postJson<{ item: NoteItem }>('/create', input)
+	return res.item
+}
+
+export async function updateNote(
+	page: string,
+	id: string,
+	patch: Partial<Pick<NoteItem, 'body' | 'status' | 'targetSnippet'>> & { range?: NoteRange | null },
+): Promise<NoteItem> {
+	const res = await postJson<{ item: NoteItem }>('/update', { page, id, patch })
+	return res.item
+}
+
+export async function setNoteStatus(page: string, id: string, status: NoteStatus): Promise<NoteItem> {
+	if (status === 'resolved') {
+		const res = await postJson<{ item: NoteItem }>('/resolve', { page, id })
+		return res.item
+	}
+	if (status === 'open') {
+		const res = await postJson<{ item: NoteItem }>('/reopen', { page, id })
+		return res.item
+	}
+	return updateNote(page, id, { status })
+}
+
+export async function deleteNote(page: string, id: string): Promise<void> {
+	await postJson<{ ok: true }>('/delete', { page, id })
+}
+
+export interface ApplyResponse {
+	item: NoteItem
+	file?: string
+	before?: string
+	after?: string
+	error?: string
+	reason?: string
+}
+
+/**
+ * Apply a suggestion. Returns the updated item plus before/after snippets
+ * on success, or throws with the server error message. The 409 response
+ * (drift) is returned as a normal value because the server already updated
+ * the item to `stale` and the overlay should refresh accordingly.
+ */
+export async function applyNote(page: string, id: string): Promise<ApplyResponse> {
+	const res = await fetch(`${BASE}/apply`, {
+		method: 'POST',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify({ page, id }),
+		signal: AbortSignal.timeout(TIMEOUT_MS),
+	})
+	const text = await res.text()
+	let parsed: any
+	try {
+		parsed = text ? JSON.parse(text) : {}
+	} catch {
+		throw new Error(`notes: invalid JSON response from /apply`)
+	}
+	if (res.status === 409) {
+		// Drift — server already marked as stale
+		return parsed as ApplyResponse
+	}
+	if (!res.ok) {
+		throw new Error(parsed?.error ?? `notes: /apply failed (${res.status})`)
+	}
+	return parsed as ApplyResponse
+}

package/src/overlay/lib/range-anchor.ts

@@ -0,0 +1,87 @@
+/**
+ * Anchor-text re-attachment for range suggestions.
+ *
+ * Suggestions don't store character offsets — they store the original
+ * substring (`anchorText`). On reload we walk the target element's text
+ * nodes and look for that substring. If found, we return a DOM `Range`
+ * the overlay can use to draw highlights or compute coordinates. If not
+ * found, the suggestion is reported as stale so the sidebar can surface
+ * a re-attach CTA.
+ *
+ * The matching is intentionally simple: first exact match, then a
+ * collapsed-whitespace fallback (handles HTML re-flowing). Anything more
+ * sophisticated (fuzzy / Levenshtein) waits for a real-world failure.
+ */
+
+import { collectTextNodes, rangeFromOffsets } from './dom-walker'
+
+export interface AnchorMatch {
+	range: Range
+	rect: DOMRect
+	start: number
+	end: number
+}
+
+function collapseWhitespace(s: string): string {
+	return s.replace(/\s+/g, ' ').trim()
+}
+
+export function findAnchorRange(el: Element, anchorText: string): AnchorMatch | null {
+	if (!anchorText) return null
+	const { joined } = collectTextNodes(el)
+	if (!joined) return null
+
+	// 1. Exact substring match
+	const idx = joined.indexOf(anchorText)
+	if (idx >= 0) {
+		const range = rangeFromOffsets(el, idx, idx + anchorText.length)
+		if (range) return { range, rect: range.getBoundingClientRect(), start: idx, end: idx + anchorText.length }
+	}
+
+	// 2. Whitespace-collapsed fallback. Build a map from collapsed offsets back
+	//    to original offsets so we can still produce a real DOM range.
+	const collapsedAnchor = collapseWhitespace(anchorText)
+	if (!collapsedAnchor) return null
+	const map: number[] = [] // collapsed index → original index
+	let collapsed = ''
+	let prevWs = false
+	for (let i = 0; i < joined.length; i++) {
+		const ch = joined[i]!
+		const isWs = /\s/.test(ch)
+		if (isWs) {
+			if (collapsed.length === 0) continue // leading
+			if (prevWs) continue
+			collapsed += ' '
+			map.push(i)
+			prevWs = true
+		} else {
+			collapsed += ch
+			map.push(i)
+			prevWs = false
+		}
+	}
+	const trimmed = collapsed.replace(/\s+$/, '')
+	const cIdx = trimmed.indexOf(collapsedAnchor)
+	if (cIdx < 0) return null
+	const startOrig = map[cIdx]
+	const endOrigInclusive = map[cIdx + collapsedAnchor.length - 1]
+	if (startOrig == null || endOrigInclusive == null) return null
+	const range = rangeFromOffsets(el, startOrig, endOrigInclusive + 1)
+	if (!range) return null
+	return { range, rect: range.getBoundingClientRect(), start: startOrig, end: endOrigInclusive + 1 }
+}
+
+/**
+ * Compute the substring of an element's joined text inside the user's
+ * current selection. Returns null if the selection is empty or not fully
+ * inside the element.
+ */
+export function selectionInsideElement(el: Element, selection: Selection): { text: string; rect: DOMRect } | null {
+	if (selection.rangeCount === 0) return null
+	const range = selection.getRangeAt(0)
+	if (range.collapsed) return null
+	if (!el.contains(range.startContainer) || !el.contains(range.endContainer)) return null
+	const text = range.toString()
+	if (!text.trim()) return null
+	return { text, rect: range.getBoundingClientRect() }
+}

package/src/overlay/lib/url-mode.ts

@@ -0,0 +1,43 @@
+/**
+ * URL flag + cookie helpers controlling notes review mode.
+ *
+ * Review mode is on when EITHER the URL has the `?<urlFlag>` query param OR
+ * the `nua-notes-mode=1` cookie is set. Visiting a page with the flag the
+ * first time sets the cookie so subsequent navigation stays in review mode.
+ *
+ * The toggle button in the toolbar clears the cookie + reloads, which drops
+ * the user back into the regular CMS view.
+ */
+
+const COOKIE = 'nua-notes-mode'
+
+export function isReviewMode(urlFlag: string): boolean {
+	if (typeof window === 'undefined') return false
+	const url = new URL(window.location.href)
+	if (url.searchParams.has(urlFlag)) return true
+	return document.cookie.split('; ').some(c => c.startsWith(`${COOKIE}=1`))
+}
+
+export function setReviewModeCookie(): void {
+	// Session cookie — cleared when the browser closes. Good enough for v0.1.
+	document.cookie = `${COOKIE}=1; path=/; SameSite=Lax`
+}
+
+export function clearReviewModeCookie(): void {
+	document.cookie = `${COOKIE}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT; SameSite=Lax`
+}
+
+export function exitReviewMode(urlFlag: string): void {
+	clearReviewModeCookie()
+	const url = new URL(window.location.href)
+	url.searchParams.delete(urlFlag)
+	window.location.href = url.pathname + (url.search || '') + url.hash
+}
+
+export function getCurrentPagePath(): string {
+	if (typeof window === 'undefined') return '/'
+	const p = window.location.pathname
+	if (p === '' || p === '/') return '/'
+	// Drop trailing slash for consistency with CMS / notes storage
+	return p.endsWith('/') ? p.slice(0, -1) : p
+}