npm - @nuasite/notes - Versions diffs - 0.1.0 - Mend

@nuasite/notes 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/README.md +211 -0
package/dist/overlay.js +1367 -0
package/package.json +51 -0
package/src/apply/apply-suggestion.ts +157 -0
package/src/dev/api-handlers.ts +215 -0
package/src/dev/middleware.ts +65 -0
package/src/dev/request-utils.ts +71 -0
package/src/index.ts +2 -0
package/src/integration.ts +168 -0
package/src/overlay/App.tsx +434 -0
package/src/overlay/components/CommentPopover.tsx +96 -0
package/src/overlay/components/DiffPreview.tsx +29 -0
package/src/overlay/components/ElementHighlight.tsx +33 -0
package/src/overlay/components/SelectionTooltip.tsx +48 -0
package/src/overlay/components/Sidebar.tsx +70 -0
package/src/overlay/components/SidebarItem.tsx +104 -0
package/src/overlay/components/StaleWarning.tsx +19 -0
package/src/overlay/components/SuggestPopover.tsx +139 -0
package/src/overlay/components/Toolbar.tsx +38 -0
package/src/overlay/env.d.ts +4 -0
package/src/overlay/index.tsx +71 -0
package/src/overlay/lib/cms-bridge.ts +33 -0
package/src/overlay/lib/dom-walker.ts +61 -0
package/src/overlay/lib/manifest-fetch.ts +35 -0
package/src/overlay/lib/notes-fetch.ts +121 -0
package/src/overlay/lib/range-anchor.ts +87 -0
package/src/overlay/lib/url-mode.ts +43 -0
package/src/overlay/styles.css +526 -0
package/src/overlay/types.ts +66 -0
package/src/storage/id-gen.ts +32 -0
package/src/storage/json-store.ts +196 -0
package/src/storage/slug.ts +35 -0
package/src/storage/types.ts +100 -0
package/src/tsconfig.json +6 -0
package/src/types.ts +50 -0

package/src/overlay/components/DiffPreview.tsx ADDED Viewed

@@ -0,0 +1,29 @@
+/** @jsxImportSource preact */
+interface DiffPreviewProps {
+	original: string
+	suggested: string
+}
+/**
+ * Inline strikethrough + insertion diff for the sidebar suggestion card.
+ *
+ * v0.1 keeps it dead simple: original on top with strikethrough, suggested
+ * underneath with an insertion mark. We don't try to highlight character-
+ * level changes — the reviewer already saw the whole substring when they
+ * made the suggestion, and the agency mostly cares about the new wording.
+ */
+export function DiffPreview({ original, suggested }: DiffPreviewProps) {
+	return (
+		<div class="notes-diff">
+			<div class="notes-diff__row notes-diff__row--del">
+				<span class="notes-diff__marker">−</span>
+				<span class="notes-strikethrough">{original}</span>
+			</div>
+			<div class="notes-diff__row notes-diff__row--ins">
+				<span class="notes-diff__marker">+</span>
+				<span>{suggested}</span>
+			</div>
+		</div>
+	)
+}

package/src/overlay/components/ElementHighlight.tsx ADDED Viewed

@@ -0,0 +1,33 @@
+/** @jsxImportSource preact */
+interface Rect {
+	x: number
+	y: number
+	width: number
+	height: number
+}
+interface ElementHighlightProps {
+	rect: Rect | null
+	persistent?: boolean
+}
+/**
+ * A non-interactive ring drawn over a target element. The Preact root sits
+ * inside a shadow DOM mounted to `<body>`, so we use viewport-fixed
+ * positioning to align with the target's `getBoundingClientRect()`.
+ */
+export function ElementHighlight({ rect, persistent }: ElementHighlightProps) {
+	if (!rect) return null
+	return (
+		<div
+			class={`notes-highlight ${persistent ? 'notes-highlight--persistent' : ''}`}
+			style={{
+				left: `${rect.x}px`,
+				top: `${rect.y}px`,
+				width: `${rect.width}px`,
+				height: `${rect.height}px`,
+			}}
+		/>
+	)
+}

package/src/overlay/components/SelectionTooltip.tsx ADDED Viewed

@@ -0,0 +1,48 @@
+/** @jsxImportSource preact */
+interface SelectionTooltipProps {
+	rect: { x: number; y: number; width: number; height: number }
+	onComment: () => void
+	onSuggest: () => void
+}
+/**
+ * Floating tooltip that appears just above the user's text selection.
+ * Two actions: leave a comment on the parent element, or open the
+ * suggest popover with the selection as the range anchor.
+ *
+ * Positioning: centered horizontally over the selection, 36px above its
+ * top edge (or below it if there's no room).
+ */
+export function SelectionTooltip({ rect, onComment, onSuggest }: SelectionTooltipProps) {
+	const tooltipWidth = 220
+	const tooltipHeight = 36
+	const margin = 8
+	let left = rect.x + rect.width / 2 - tooltipWidth / 2
+	left = Math.max(margin, Math.min(left, window.innerWidth - tooltipWidth - margin - 360))
+	let top = rect.y - tooltipHeight - margin
+	if (top < 56) {
+		// Below the selection if there's not enough room above
+		top = rect.y + rect.height + margin
+	}
+	return (
+		<div
+			class="notes-selection-tooltip"
+			style={{ left: `${left}px`, top: `${top}px`, width: `${tooltipWidth}px` }}
+			onMouseDown={(e) => {
+				// Prevent the click from clearing the user's text selection
+				e.preventDefault()
+			}}
+		>
+			<button class="notes-btn notes-btn--ghost" onClick={onComment}>
+				💬 Comment
+			</button>
+			<button class="notes-btn notes-btn--primary" onClick={onSuggest}>
+				✏️ Suggest edit
+			</button>
+		</div>
+	)
+}

package/src/overlay/components/Sidebar.tsx ADDED Viewed

@@ -0,0 +1,70 @@
+/** @jsxImportSource preact */
+import type { NoteItem } from '../types'
+import { SidebarItem } from './SidebarItem'
+interface SidebarProps {
+	page: string
+	items: NoteItem[]
+	activeId: string | null
+	picking: boolean
+	error: string | null
+	staleIds: Set<string>
+	applyingId: string | null
+	onFocus: (id: string) => void
+	onResolve: (id: string) => void
+	onReopen: (id: string) => void
+	onDelete: (id: string) => void
+	onApply: (id: string) => void
+}
+export function Sidebar(
+	{ page, items, activeId, picking, error, staleIds, applyingId, onFocus, onResolve, onReopen, onDelete, onApply }: SidebarProps,
+) {
+	const open = items.filter((i) => i.status !== 'resolved' && i.status !== 'applied')
+	const closed = items.filter((i) => i.status === 'resolved' || i.status === 'applied')
+	const renderItem = (item: NoteItem) => (
+		<SidebarItem
+			key={item.id}
+			item={item}
+			active={item.id === activeId}
+			stale={staleIds.has(item.id)}
+			applying={applyingId === item.id}
+			onFocus={() => onFocus(item.id)}
+			onResolve={() => onResolve(item.id)}
+			onReopen={() => onReopen(item.id)}
+			onDelete={() => onDelete(item.id)}
+			onApply={() => onApply(item.id)}
+		/>
+	)
+	return (
+		<aside class="notes-sidebar">
+			<header class="notes-sidebar__header">
+				<h3 class="notes-sidebar__title">Review notes</h3>
+				<div class="notes-sidebar__meta">
+					{open.length} open · {closed.length} resolved · <code>{page}</code>
+				</div>
+			</header>
+			<div class="notes-sidebar__list">
+				{error ? <div class="notes-banner">{error}</div> : null}
+				{items.length === 0
+					? (
+						<div class="notes-sidebar__empty">
+							{picking
+								? 'Click any text or element on the page to add a comment.'
+								: 'Select text on the page to suggest an edit, or click "Pick element" to comment.'}
+						</div>
+					)
+					: null}
+				{open.map(renderItem)}
+				{closed.length > 0
+					? (
+						<>
+							<div class="notes-sidebar__meta" style={{ marginTop: '4px' }}>Resolved</div>
+							{closed.map(renderItem)}
+						</>
+					)
+					: null}
+			</div>
+		</aside>
+	)
+}

package/src/overlay/components/SidebarItem.tsx ADDED Viewed

@@ -0,0 +1,104 @@
+/** @jsxImportSource preact */
+import type { NoteItem } from '../types'
+import { DiffPreview } from './DiffPreview'
+import { StaleWarning } from './StaleWarning'
+interface SidebarItemProps {
+	item: NoteItem
+	active: boolean
+	stale: boolean
+	applying: boolean
+	onFocus: () => void
+	onResolve: () => void
+	onReopen: () => void
+	onDelete: () => void
+	onApply: () => void
+}
+function formatTime(iso: string): string {
+	try {
+		const d = new Date(iso)
+		const now = new Date()
+		const diffMs = now.getTime() - d.getTime()
+		const diffMin = Math.floor(diffMs / 60000)
+		if (diffMin < 1) return 'just now'
+		if (diffMin < 60) return `${diffMin}m ago`
+		const diffHr = Math.floor(diffMin / 60)
+		if (diffHr < 24) return `${diffHr}h ago`
+		const diffDays = Math.floor(diffHr / 24)
+		if (diffDays < 7) return `${diffDays}d ago`
+		return d.toLocaleDateString()
+	} catch {
+		return iso
+	}
+}
+/**
+ * One note card in the sidebar list. Renders both comment and suggestion
+ * shapes from a unified data model: comments show the body; suggestions
+ * show the inline diff and (if any) a rationale + body.
+ */
+export function SidebarItem({ item, active, stale, applying, onFocus, onResolve, onReopen, onDelete, onApply }: SidebarItemProps) {
+	const isResolved = item.status === 'resolved' || item.status === 'applied'
+	const isApplied = item.status === 'applied'
+	const isSuggestion = item.type === 'suggestion' && item.range
+	const canApply = isSuggestion && !isApplied && !stale
+	return (
+		<div
+			class={`notes-item ${active ? 'notes-item--active' : ''} ${isResolved ? 'notes-item--resolved' : ''}`}
+			onMouseEnter={onFocus}
+		>
+			<div class="notes-item__head">
+				<div>
+					<span class={`notes-item__badge notes-item__badge--${item.type}`}>
+						{item.type}
+					</span>
+					{isResolved
+						? <span class="notes-item__badge notes-item__badge--resolved">{item.status}</span>
+						: null}
+					<span class="notes-item__author">{item.author}</span>
+				</div>
+				<span class="notes-item__time">{formatTime(item.createdAt)}</span>
+			</div>
+			{stale && isSuggestion ? <StaleWarning /> : null}
+			{isSuggestion && item.range
+				? (
+					<>
+						<DiffPreview original={item.range.originalText} suggested={item.range.suggestedText} />
+						{item.range.rationale
+							? (
+								<div class="notes-item__rationale">
+									<span class="notes-item__rationale-label">Why:</span> {item.range.rationale}
+								</div>
+							)
+							: null}
+						{item.body ? <div class="notes-item__body">{item.body}</div> : null}
+					</>
+				)
+				: (
+					<>
+						{item.targetSnippet
+							? <div class="notes-item__snippet">{item.targetSnippet}</div>
+							: null}
+						<div class="notes-item__body">{item.body}</div>
+					</>
+				)}
+			<div class="notes-item__actions">
+				{canApply
+					? (
+						<button class="notes-btn notes-btn--primary" onClick={onApply} disabled={applying}>
+							{applying ? 'Applying...' : 'Apply'}
+						</button>
+					)
+					: null}
+				{isResolved
+					? <button class="notes-btn notes-btn--ghost" onClick={onReopen}>Reopen</button>
+					: <button class="notes-btn" onClick={onResolve}>Resolve</button>}
+				<button class="notes-btn notes-btn--ghost notes-btn--danger" onClick={onDelete}>Delete</button>
+			</div>
+		</div>
+	)
+}

package/src/overlay/components/StaleWarning.tsx ADDED Viewed

@@ -0,0 +1,19 @@
+/** @jsxImportSource preact */
+interface StaleWarningProps {
+	reason?: string
+}
+/**
+ * Small badge shown on suggestion cards whose anchor text no longer
+ * appears inside the target element. Phase 5 will add a "re-attach" CTA;
+ * for v0.1 we just surface the situation so the agency can act on it.
+ */
+export function StaleWarning({ reason }: StaleWarningProps) {
+	return (
+		<div class="notes-stale" title={reason}>
+			<span class="notes-stale__icon">⚠</span>
+			<span>Anchor text not found on this page</span>
+		</div>
+	)
+}

package/src/overlay/components/SuggestPopover.tsx ADDED Viewed

@@ -0,0 +1,139 @@
+/** @jsxImportSource preact */
+import { useEffect, useRef, useState } from 'preact/hooks'
+interface SuggestPopoverProps {
+	rect: { x: number; y: number; width: number; height: number }
+	originalText: string
+	defaultAuthor: string
+	onCancel: () => void
+	onSubmit: (input: { suggestedText: string; rationale: string; body: string; author: string }) => void | Promise<void>
+}
+/**
+ * Google Docs-style suggestion popover. Shows the original text crossed out
+ * (read-only), then a textarea pre-filled with the same text the reviewer
+ * can edit, an optional rationale, and a one-line note. The author input
+ * mirrors CommentPopover so the user only types their name once per session.
+ */
+export function SuggestPopover({ rect, originalText, defaultAuthor, onCancel, onSubmit }: SuggestPopoverProps) {
+	const [suggested, setSuggested] = useState(originalText)
+	const [rationale, setRationale] = useState('')
+	const [body, setBody] = useState('')
+	const [author, setAuthor] = useState(defaultAuthor)
+	const [submitting, setSubmitting] = useState(false)
+	const textareaRef = useRef<HTMLTextAreaElement>(null)
+	useEffect(() => {
+		// Focus the suggested text input and select-all so the reviewer can
+		// just start typing the replacement.
+		const ta = textareaRef.current
+		if (ta) {
+			ta.focus()
+			ta.select()
+		}
+	}, [])
+	const dirty = suggested.trim() !== originalText.trim()
+	const handleSubmit = async () => {
+		if (!dirty || submitting) return
+		setSubmitting(true)
+		try {
+			await onSubmit({
+				suggestedText: suggested,
+				rationale: rationale.trim(),
+				body: body.trim(),
+				author: 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()
+		}
+	}
+	const sidebarWidth = 360
+	const popoverWidth = 360
+	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)
+		if (left < margin) left = margin
+	}
+	const top = Math.max(56, Math.min(rect.y, window.innerHeight - 360))
+	return (
+		<div
+			class="notes-popover notes-popover--suggest"
+			style={{ left: `${left}px`, top: `${top}px`, width: `${popoverWidth}px` }}
+			onClick={(e) => e.stopPropagation()}
+			onMouseDown={(e) => e.stopPropagation()}
+			onKeyDown={handleKey}
+		>
+			<h4 class="notes-popover__title">Suggest edit</h4>
+			<div class="notes-popover__original">
+				<span class="notes-popover__label">Original</span>
+				<span class="notes-strikethrough">{originalText}</span>
+			</div>
+			<div>
+				<label class="notes-popover__label" for="nua-suggest-text">Replacement</label>
+				<textarea
+					ref={textareaRef}
+					id="nua-suggest-text"
+					value={suggested}
+					onInput={(e) => setSuggested((e.target as HTMLTextAreaElement).value)}
+				/>
+			</div>
+			<div>
+				<label class="notes-popover__label" for="nua-suggest-rationale">Why? (optional)</label>
+				<input
+					type="text"
+					id="nua-suggest-rationale"
+					placeholder="Stronger framing, fixes typo, ..."
+					value={rationale}
+					onInput={(e) => setRationale((e.target as HTMLInputElement).value)}
+				/>
+			</div>
+			<div>
+				<label class="notes-popover__label" for="nua-suggest-body">Note (optional)</label>
+				<input
+					type="text"
+					id="nua-suggest-body"
+					placeholder="Anything else for the agency"
+					value={body}
+					onInput={(e) => setBody((e.target as HTMLInputElement).value)}
+				/>
+			</div>
+			<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">{dirty ? '⌘+Enter to save' : 'Edit the replacement to enable 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={!dirty || submitting}
+					>
+						{submitting ? 'Saving...' : 'Save suggestion'}
+					</button>
+				</div>
+			</div>
+		</div>
+	)
+}

package/src/overlay/components/Toolbar.tsx ADDED Viewed

@@ -0,0 +1,38 @@
+/** @jsxImportSource preact */
+interface ToolbarProps {
+	page: string
+	count: number
+	picking: boolean
+	onTogglePick: () => void
+	onExit: () => void
+}
+/**
+ * Top bar for notes review mode. Shows the brand mark, current page path,
+ * note count, a "Pick element" button (to enter the click-to-comment flow),
+ * and an "Exit review" button that drops the cookie + reloads.
+ */
+export function Toolbar({ page, count, picking, onTogglePick, onExit }: ToolbarProps) {
+	return (
+		<div class="notes-toolbar">
+			<div class="notes-toolbar__brand">
+				<span class="notes-toolbar__dot" />
+				<span>Notes</span>
+				<span class="notes-toolbar__page">{page} · {count} {count === 1 ? 'item' : 'items'}</span>
+			</div>
+			<div class="notes-toolbar__actions">
+				<button
+					class={`notes-btn ${picking ? 'notes-btn--primary' : ''}`}
+					onClick={onTogglePick}
+					title="Click any text or element on the page to leave a comment"
+				>
+					{picking ? 'Cancel pick' : 'Pick element'}
+				</button>
+				<button class="notes-btn notes-btn--ghost" onClick={onExit} title="Leave review mode">
+					Exit
+				</button>
+			</div>
+		</div>
+	)
+}

package/src/overlay/env.d.ts ADDED Viewed

@@ -0,0 +1,4 @@
+declare module '*.css?inline' {
+	const css: string
+	export default css
+}

package/src/overlay/index.tsx ADDED Viewed

@@ -0,0 +1,71 @@
+/** @jsxImportSource preact */
+import { render } from 'preact'
+import { App } from './App'
+import { enableCmsBridge } from './lib/cms-bridge'
+import { isReviewMode, setReviewModeCookie } from './lib/url-mode'
+import OVERLAY_STYLES from './styles.css?inline'
+/**
+ * Notes overlay entry. Loaded as a virtual ESM module from the page bundle.
+ *
+ * - If the URL flag is absent and the cookie isn't set, do nothing. CMS works
+ *   as normal and the overlay never mounts.
+ * - Otherwise, persist the cookie so navigation stays in review mode, hide
+ *   the CMS chrome via the bridge stylesheet, and mount the Preact app
+ *   inside a shadow DOM so our CSS doesn't leak into the host page.
+ *
+ * The build-time URL flag is read from `window.__NuaNotesConfig` which the
+ * Astro integration injects in `astro:config:setup` before this module loads.
+ */
+interface NuaNotesConfig {
+	urlFlag?: string
+}
+declare global {
+	interface Window {
+		__NuaNotesConfig?: NuaNotesConfig
+		__nuasiteNotesMounted?: boolean
+	}
+}
+function init(): void {
+	if (window.__nuasiteNotesMounted) return
+	const config = window.__NuaNotesConfig ?? {}
+	const urlFlag = config.urlFlag ?? 'nua-notes'
+	if (!isReviewMode(urlFlag)) return
+	window.__nuasiteNotesMounted = true
+	// Cement the cookie so subsequent navigation keeps review mode without
+	// re-appending `?nua-notes` to every link.
+	setReviewModeCookie()
+	enableCmsBridge()
+	const host = document.createElement('div')
+	host.id = 'nua-notes-host'
+	host.setAttribute('data-nua-notes-host', '')
+	host.style.cssText = 'position:fixed;top:0;left:0;width:0;height:0;z-index:2147483600;'
+	document.body.appendChild(host)
+	const shadow = host.attachShadow({ mode: 'open' })
+	const styleEl = document.createElement('style')
+	styleEl.textContent = OVERLAY_STYLES
+	shadow.appendChild(styleEl)
+	const root = document.createElement('div')
+	root.id = 'nua-notes-root'
+	shadow.appendChild(root)
+	render(<App urlFlag={urlFlag} />, root)
+}
+if (typeof window !== 'undefined') {
+	if (document.readyState === 'loading') {
+		document.addEventListener('DOMContentLoaded', init, { once: true })
+	} else {
+		init()
+	}
+}

package/src/overlay/lib/cms-bridge.ts ADDED Viewed

@@ -0,0 +1,33 @@
+/**
+ * Mode-exclusivity bridge with `@nuasite/cms`.
+ *
+ * When notes review mode is active we hide the CMS editor chrome via a
+ * single injected `<style>` tag in the host document. CMS uses a shadow DOM
+ * mounted on `#cms-app-host`, so hiding that element + suppressing pointer
+ * events on the data-cms-id markers is enough to make the two UIs not
+ * collide. There's no postMessage handshake yet — Phase 5 may add one.
+ *
+ * `enable()` is idempotent. `disable()` removes the style if it was added.
+ */
+const STYLE_ID = 'nua-notes-cms-bridge'
+const HIDE_CMS_CSS = `
+	#cms-app-host { display: none !important; }
+	[data-nuasite-cms] { display: none !important; }
+	/* Allow notes to handle clicks on annotated elements without CMS interfering */
+	[data-cms-id] { cursor: default !important; }
+`
+export function enableCmsBridge(): void {
+	if (document.getElementById(STYLE_ID)) return
+	const style = document.createElement('style')
+	style.id = STYLE_ID
+	style.textContent = HIDE_CMS_CSS
+	document.head.appendChild(style)
+}
+export function disableCmsBridge(): void {
+	const existing = document.getElementById(STYLE_ID)
+	if (existing) existing.remove()
+}

package/src/overlay/lib/dom-walker.ts ADDED Viewed

@@ -0,0 +1,61 @@
+/**
+ * Text-node walker scoped to a single element.
+ *
+ * Used by `range-anchor.ts` to locate suggestion anchors after page reloads
+ * (and Phase 3 selection capture). The walker treats the element's text
+ * content as a single string and remembers offsets back into the underlying
+ * text nodes so we can build a DOM `Range` from a substring match.
+ */
+export interface TextNodeOffset {
+	node: Text
+	start: number
+	end: number
+}
+/**
+ * Collect every text node inside `el` (in document order) along with the
+ * cumulative character offset where each node starts within the joined text.
+ */
+export function collectTextNodes(el: Element): { joined: string; nodes: TextNodeOffset[] } {
+	const nodes: TextNodeOffset[] = []
+	let joined = ''
+	const walker = el.ownerDocument.createTreeWalker(el, NodeFilter.SHOW_TEXT)
+	let cur = walker.nextNode() as Text | null
+	while (cur) {
+		const text = cur.nodeValue ?? ''
+		nodes.push({ node: cur, start: joined.length, end: joined.length + text.length })
+		joined += text
+		cur = walker.nextNode() as Text | null
+	}
+	return { joined, nodes }
+}
+/**
+ * Map an absolute character offset back to a `(node, offsetInNode)` pair.
+ * Returns null if the offset is outside the element.
+ */
+export function offsetToNode(nodes: TextNodeOffset[], offset: number): { node: Text; offset: number } | null {
+	for (const n of nodes) {
+		if (offset >= n.start && offset <= n.end) {
+			return { node: n.node, offset: offset - n.start }
+		}
+	}
+	return null
+}
+/**
+ * Build a DOM `Range` covering `[start, end)` (in joined-text coordinates)
+ * inside the element. Returns null if either endpoint is out of bounds.
+ */
+export function rangeFromOffsets(el: Element, start: number, end: number): Range | null {
+	const { joined, nodes } = collectTextNodes(el)
+	if (start < 0 || end > joined.length || start >= end) return null
+	const startPos = offsetToNode(nodes, start)
+	const endPos = offsetToNode(nodes, end)
+	if (!startPos || !endPos) return null
+	const range = el.ownerDocument.createRange()
+	range.setStart(startPos.node, startPos.offset)
+	range.setEnd(endPos.node, endPos.offset)
+	return range
+}