@north-light/crouter 0.3.192 → 0.3.194

package/dist/pages/elements/text.js

@@ -0,0 +1,951 @@
+/**
+ * `<crtr-text>` — the universal primitive: prose the agent puts in front of the user, which
+ * the user can rewrite, annotate, or both.
+ *
+ * The three shapes in the catalog are all this one element:
+ *
+ *  - a **draft** the user edits in place — `editable`, pre-filled;
+ *  - **read** text the user leaves anchored comments on, review-style — select a range and
+ *    the comment affordance appears at the selection;
+ *  - an **empty input** — `editable` with no starting text, which opens already editing.
+ *
+ * Text is always commentable; that is not a capability switch, and edit and comment coexist.
+ * Reading is the resting state, because that is where anchored commenting lives; the edit
+ * toggle swaps the block for a plain textarea. Comments survive the switch, but a range
+ * anchor written before an edit can end up pointing at moved text — which is why every range
+ * carries the `quote` it was written against.
+ *
+ * `edited` means *differs*, not *was touched*: returning the text to what the agent wrote
+ * un-sets the flag.
+ *
+ * Ported from the reviewed interaction kit (`apps/gateway/components/agent-ui/agent-text.tsx`
+ * and `comment-affordance.tsx` @ `3705fe9e2`), framework-free and styled only through the
+ * bundle's `--crtr-*` tokens.
+ */
+import { registerElement } from '../register.js';
+import { readSlotConfig, readSlotId } from '../slot-config.js';
+import { respond } from '../host.js';
+import { findComment, setComment } from '../comments.js';
+const WHOLE = { kind: 'whole' };
+const WHOLE_TARGET = 'the whole passage';
+const RANGE_TARGET = 'the selected text';
+const POPOVER_GAP = 6;
+const POPOVER_ID = 'comment-popover';
+const STYLE = `
+  :host {
+    display: block;
+  }
+
+  [part="container"] {
+    position: relative;
+    display: grid;
+    gap: var(--crtr-space-2);
+  }
+
+  [part="toolbar"] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: flex-end;
+    gap: var(--crtr-space-2);
+  }
+
+  [part="edited"] {
+    padding: 0 var(--crtr-space-2);
+    color: var(--crtr-color-accent);
+    background: color-mix(in srgb, var(--crtr-color-accent) 14%, transparent);
+    border-radius: var(--crtr-radius-small);
+    font-family: var(--crtr-font-mono);
+    font-size: 0.6875rem;
+    letter-spacing: 0.06em;
+    line-height: 1.7;
+    text-transform: uppercase;
+  }
+
+  button {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--crtr-space-1);
+    max-width: 100%;
+    padding: var(--crtr-space-1) var(--crtr-space-2);
+    color: var(--crtr-color-text-muted);
+    font: inherit;
+    background: transparent;
+    border: 1px solid transparent;
+    border-radius: var(--crtr-radius-small);
+    cursor: pointer;
+  }
+
+  button:hover {
+    color: var(--crtr-color-text);
+    background: var(--crtr-color-surface-hover);
+  }
+
+  button:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 2px;
+  }
+
+  button[data-state="on"] {
+    color: var(--crtr-color-accent);
+  }
+
+  svg {
+    width: 0.875rem;
+    height: 0.875rem;
+    flex: none;
+  }
+
+  [part="editor"] {
+    display: block;
+    box-sizing: border-box;
+    width: 100%;
+    min-height: 10rem;
+    padding: var(--crtr-space-3) var(--crtr-space-4);
+    color: var(--crtr-color-text);
+    font: inherit;
+    line-height: var(--crtr-line-height);
+    background: var(--crtr-color-background);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+    resize: vertical;
+  }
+
+  [part="editor"]:focus-visible,
+  [part="popover-input"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: -1px;
+  }
+
+  [part="body"] {
+    position: relative;
+    padding: var(--crtr-space-3) var(--crtr-space-4);
+    background: var(--crtr-color-surface);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+  }
+
+  [part="body"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 2px;
+  }
+
+  [part="prose"] {
+    display: grid;
+    gap: var(--crtr-space-3);
+  }
+
+  [part="prose"] p {
+    margin: 0;
+    white-space: pre-wrap;
+  }
+
+  [part="placeholder"] {
+    color: var(--crtr-color-text-muted);
+  }
+
+  [part~="commented"] {
+    position: relative;
+    border-radius: var(--crtr-radius-small);
+    background: color-mix(in srgb, var(--crtr-color-accent) 18%, transparent);
+    text-decoration: underline dotted;
+    text-decoration-color: var(--crtr-color-accent);
+    text-underline-offset: 4px;
+    cursor: help;
+    outline: none;
+  }
+
+  [part~="commented"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 2px;
+  }
+
+  [part="comment-bubble"] {
+    position: absolute;
+    bottom: calc(100% + var(--crtr-space-1));
+    left: 0;
+    z-index: 2;
+    display: grid;
+    gap: var(--crtr-space-1);
+    width: max-content;
+    max-width: 18rem;
+    padding: var(--crtr-space-2) var(--crtr-space-3);
+    color: var(--crtr-color-text);
+    background: var(--crtr-color-background);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+    box-shadow: var(--crtr-shadow);
+    text-decoration: none;
+    white-space: normal;
+    user-select: none;
+    opacity: 0;
+    visibility: hidden;
+    transition: opacity 120ms ease 120ms, visibility 0s linear 240ms;
+  }
+
+  [part~="commented"]:hover > [part="comment-bubble"],
+  [part~="commented"]:focus > [part="comment-bubble"] {
+    opacity: 1;
+    visibility: visible;
+    transition: opacity 120ms ease 220ms, visibility 0s linear 220ms;
+  }
+
+  [part="bubble-label"],
+  [part="comment-count"],
+  [part="popover-subject"],
+  [part="popover-hint"] {
+    color: var(--crtr-color-text-muted);
+    font-family: var(--crtr-font-mono);
+    font-size: 0.6875rem;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+  }
+
+  [part="bubble-label"] {
+    color: var(--crtr-color-accent);
+  }
+
+  [part~="selection-comment"] {
+    position: absolute;
+    z-index: 3;
+    color: var(--crtr-color-accent);
+    background: var(--crtr-color-background);
+    border-color: color-mix(in srgb, var(--crtr-color-accent) 40%, transparent);
+    box-shadow: var(--crtr-shadow);
+  }
+
+  [part="comment-rail"] {
+    display: grid;
+    gap: var(--crtr-space-1);
+  }
+
+  [part="comment-chips"] {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--crtr-space-2);
+  }
+
+  [part~="comment-chip"] {
+    color: var(--crtr-color-text);
+    border-color: var(--crtr-color-border);
+    text-align: left;
+  }
+
+  [part~="comment-chip"] > span {
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  [part="popover"] {
+    position: absolute;
+    z-index: 5;
+    box-sizing: border-box;
+    display: grid;
+    gap: var(--crtr-space-2);
+    width: 20rem;
+    max-width: 100%;
+    padding: var(--crtr-space-3);
+    background: var(--crtr-color-background);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+    box-shadow: var(--crtr-shadow);
+  }
+
+  [part="popover"][hidden],
+  [part="edited"][hidden],
+  [part="comment-rail"][hidden],
+  [part~="selection-comment"][hidden],
+  [part="popover-quote"][hidden],
+  [part="edit-toggle"][hidden] {
+    display: none;
+  }
+
+  [part="popover-subject"],
+  [part="popover-quote"] {
+    margin: 0;
+  }
+
+  [part="popover-quote"] {
+    padding: var(--crtr-space-1) var(--crtr-space-2);
+    color: var(--crtr-color-text-muted);
+    background: color-mix(in srgb, var(--crtr-color-accent) 8%, transparent);
+    border-left: 2px solid color-mix(in srgb, var(--crtr-color-accent) 40%, transparent);
+    white-space: pre-wrap;
+  }
+
+  [part="popover-input"] {
+    box-sizing: border-box;
+    width: 100%;
+    min-height: 5rem;
+    padding: var(--crtr-space-2);
+    color: var(--crtr-color-text);
+    font: inherit;
+    background: var(--crtr-color-surface);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-small);
+    resize: vertical;
+  }
+
+  [part="popover-actions"] {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--crtr-space-2);
+  }
+
+  [part="popover-buttons"] {
+    display: flex;
+    gap: var(--crtr-space-2);
+  }
+
+  [part="popover-save"] {
+    color: var(--crtr-color-accent-contrast);
+    background: var(--crtr-color-accent);
+  }
+
+  [part="popover-save"]:hover {
+    color: var(--crtr-color-accent-contrast);
+    background: var(--crtr-color-accent);
+    opacity: 0.9;
+  }
+
+  [part="popover-cancel"] {
+    border-color: var(--crtr-color-border);
+  }
+
+  [part="unavailable"] {
+    padding: var(--crtr-space-3);
+    color: var(--crtr-color-text-muted);
+    background: var(--crtr-color-surface);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-medium);
+    box-shadow: var(--crtr-shadow);
+  }
+
+  [part="reason"] {
+    color: var(--crtr-color-text);
+    font-family: var(--crtr-font-mono);
+  }
+`;
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const BUBBLE = 'M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z';
+const ICON_COMMENT_ADD = [BUBBLE, 'M12 7v6', 'M9 10h6'];
+const ICON_COMMENT = [BUBBLE, 'M13 8H7', 'M17 12H7'];
+const ICON_EDIT = [
+    'M12 20h9',
+    'M16.376 3.622a1 1 0 0 1 3.002 3.002L7.368 18.635a2 2 0 0 1-.855.506l-2.872.838a.5.5 0 0 1-.62-.62l.838-2.872a2 2 0 0 1 .506-.854z',
+    'm15 5 3 3',
+];
+const ICON_DONE = ['M20 6 9 17l-5-5'];
+function icon(paths) {
+    const svg = document.createElementNS(SVG_NS, 'svg');
+    svg.setAttribute('viewBox', '0 0 24 24');
+    svg.setAttribute('fill', 'none');
+    svg.setAttribute('stroke', 'currentColor');
+    svg.setAttribute('stroke-width', '2');
+    svg.setAttribute('stroke-linecap', 'round');
+    svg.setAttribute('stroke-linejoin', 'round');
+    svg.setAttribute('aria-hidden', 'true');
+    for (const d of paths) {
+        const path = document.createElementNS(SVG_NS, 'path');
+        path.setAttribute('d', d);
+        svg.append(path);
+    }
+    return svg;
+}
+/** Paragraphs with their character offsets into the whole text preserved. */
+function splitParagraphs(text) {
+    const out = [];
+    const separator = /\n{2,}/g;
+    let cursor = 0;
+    let match;
+    while ((match = separator.exec(text)) !== null) {
+        out.push({ start: cursor, text: text.slice(cursor, match.index) });
+        cursor = match.index + match[0].length;
+    }
+    out.push({ start: cursor, text: text.slice(cursor) });
+    return out.filter((paragraph) => paragraph.text.trim().length > 0);
+}
+/** Splits one paragraph at its commented ranges so they can be painted. */
+function segmentParagraph(paragraph, comments) {
+    const anchored = comments
+        .filter((comment) => comment.anchor.kind === 'range')
+        .filter((comment) => comment.anchor.end > paragraph.start && comment.anchor.start < paragraph.start + paragraph.text.length)
+        .sort((a, b) => a.anchor.start - b.anchor.start);
+    const segments = [];
+    let cursor = 0;
+    for (const comment of anchored) {
+        const start = Math.max(cursor, comment.anchor.start - paragraph.start);
+        const end = Math.min(paragraph.text.length, comment.anchor.end - paragraph.start);
+        if (end <= start)
+            continue; // fully overlapped by an earlier comment
+        if (start > cursor)
+            segments.push({ text: paragraph.text.slice(cursor, start) });
+        segments.push({ text: paragraph.text.slice(start, end), comment });
+        cursor = end;
+    }
+    if (cursor < paragraph.text.length)
+        segments.push({ text: paragraph.text.slice(cursor) });
+    return segments;
+}
+function closestParagraph(node) {
+    const element = node.nodeType === Node.ELEMENT_NODE ? node : node.parentElement;
+    return element?.closest('[data-paragraph]') ?? null;
+}
+/**
+ * Characters of `root` that precede the (node, offset) boundary. Comment bubbles live inside
+ * their highlighted range for positioning, but are UI rather than passage text, so cloned
+ * bubble nodes are removed before measuring. This keeps later anchors aligned to `value.text`
+ * after an earlier range has already been commented.
+ */
+function offsetWithin(root, node, offset) {
+    const range = document.createRange();
+    range.selectNodeContents(root);
+    range.setEnd(node, offset);
+    const contents = range.cloneContents();
+    for (const bubble of contents.querySelectorAll('[part="comment-bubble"]'))
+        bubble.remove();
+    return contents.textContent?.length ?? 0;
+}
+function passageLength(root) {
+    const contents = root.cloneNode(true);
+    for (const bubble of contents.querySelectorAll('[part="comment-bubble"]'))
+        bubble.remove();
+    return contents.textContent?.length ?? 0;
+}
+/**
+ * Normalizes a browser Selection boundary to one of the rendered paragraph text ranges.
+ * A whole-paragraph selection commonly ends at character 0 of the NEXT `<p>` (or at the next
+ * child boundary of their shared wrapper), despite selecting no text there. For an end
+ * boundary, that belongs to the previous paragraph.
+ */
+function paragraphBoundary(body, node, offset, edge) {
+    const paragraphs = Array.from(body.querySelectorAll('[data-paragraph]'));
+    const direct = closestParagraph(node);
+    if (direct) {
+        if (edge === 'end' && offset === 0) {
+            const index = paragraphs.indexOf(direct);
+            const previous = paragraphs[index - 1];
+            if (previous)
+                return { paragraph: previous, offset: passageLength(previous) };
+        }
+        return { paragraph: direct, offset: offsetWithin(direct, node, offset) };
+    }
+    // The range can also land on the wrapper between paragraph elements. Locate the first
+    // paragraph at/after that caret for a start, or the last paragraph before it for an end.
+    const boundary = document.createRange();
+    boundary.setStart(node, offset);
+    boundary.collapse(true);
+    const ordered = edge === 'start' ? paragraphs : [...paragraphs].reverse();
+    for (const paragraph of ordered) {
+        const contents = document.createRange();
+        contents.selectNodeContents(paragraph);
+        const relation = boundary.compareBoundaryPoints(edge === 'start' ? Range.START_TO_START : Range.START_TO_END, contents);
+        if ((edge === 'start' && relation <= 0) || (edge === 'end' && relation >= 0)) {
+            return { paragraph, offset: edge === 'start' ? 0 : passageLength(paragraph) };
+        }
+    }
+    return null;
+}
+/**
+ * The live selection that covers this element's prose. A selection made inside a shadow root
+ * is reported by `ShadowRoot.getSelection()` where that exists and by the document selection
+ * elsewhere, so both are consulted and the containment check decides.
+ */
+function selectionRange(root, body) {
+    const scoped = root;
+    const candidates = [
+        typeof scoped.getSelection === 'function' ? scoped.getSelection() : null,
+        document.getSelection(),
+    ];
+    for (const selection of candidates) {
+        if (!selection || selection.isCollapsed || selection.rangeCount === 0)
+            continue;
+        const range = selection.getRangeAt(0);
+        if (body.contains(range.startContainer) && body.contains(range.endContainer))
+            return range;
+    }
+    return null;
+}
+/**
+ * Every node that opens the comment popover carries the popover's own semantics: the kit's
+ * Radix trigger supplied these, and a port that drops them leaves a dialog no assistive
+ * technology can find from the control that opens it.
+ */
+function markTrigger(element) {
+    element.setAttribute('aria-haspopup', 'dialog');
+    element.setAttribute('aria-controls', POPOVER_ID);
+    element.setAttribute('aria-expanded', 'false');
+}
+class CrtrTextElement extends HTMLElement {
+    #root;
+    #container = document.createElement('div');
+    #toolbar = document.createElement('div');
+    #editedBadge = document.createElement('span');
+    #wholeComment = document.createElement('button');
+    #editToggle = document.createElement('button');
+    #editLabel = document.createElement('span');
+    #surface = document.createElement('div');
+    #editor = document.createElement('textarea');
+    #body = document.createElement('div');
+    #prose = document.createElement('div');
+    #selectionComment = document.createElement('button');
+    #rail = document.createElement('div');
+    #railCount = document.createElement('span');
+    #railChips = document.createElement('div');
+    #popover = document.createElement('div');
+    #popoverSubject = document.createElement('p');
+    #popoverQuote = document.createElement('blockquote');
+    #popoverInput = document.createElement('textarea');
+    #popoverHint = document.createElement('span');
+    #popoverSave = document.createElement('button');
+    #popoverCancel = document.createElement('button');
+    #config = { initialText: '' };
+    #slotId;
+    #text = '';
+    #comments = [];
+    #editing = false;
+    #live = false;
+    #draft = null;
+    #open = null;
+    constructor() {
+        super();
+        this.#root = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent = STYLE;
+        this.#container.part.add('container');
+        this.#toolbar.part.add('toolbar');
+        this.#editedBadge.part.add('edited');
+        this.#editedBadge.textContent = 'edited';
+        this.#editedBadge.hidden = true;
+        this.#wholeComment.type = 'button';
+        this.#wholeComment.part.add('comment-trigger');
+        this.#wholeComment.part.add('whole-comment');
+        markTrigger(this.#wholeComment);
+        this.#wholeComment.addEventListener('click', () => {
+            this.#openComment(WHOLE, WHOLE_TARGET, this.#wholeComment, 'end');
+        });
+        this.#editToggle.type = 'button';
+        this.#editToggle.part.add('edit-toggle');
+        this.#editToggle.hidden = true;
+        this.#editToggle.append(this.#editLabel);
+        this.#editToggle.addEventListener('click', () => {
+            this.#editing = !this.#editing;
+            this.#clearDraft();
+            this.#renderSurface();
+            this.#renderToolbar();
+            if (this.#editing)
+                this.#editor.focus();
+            else
+                this.#body.focus();
+        });
+        this.#toolbar.append(this.#editedBadge, this.#wholeComment, this.#editToggle);
+        this.#surface.part.add('surface');
+        this.#editor.part.add('editor');
+        this.#editor.addEventListener('input', () => {
+            this.#text = this.#editor.value;
+            this.#renderToolbar();
+            this.#emit();
+        });
+        this.#body.part.add('body');
+        this.#body.tabIndex = 0;
+        this.#prose.part.add('prose');
+        this.#selectionComment.type = 'button';
+        this.#selectionComment.part.add('comment-trigger');
+        this.#selectionComment.part.add('selection-comment');
+        this.#selectionComment.hidden = true;
+        markTrigger(this.#selectionComment);
+        this.#selectionComment.append(icon(ICON_COMMENT_ADD), document.createTextNode('Comment'));
+        this.#selectionComment.addEventListener('mousedown', (event) => event.preventDefault());
+        this.#selectionComment.addEventListener('click', () => {
+            const draft = this.#draft;
+            if (draft === null)
+                return;
+            this.#openComment(draft.anchor, RANGE_TARGET, this.#selectionComment, 'start', draft.anchor.quote);
+        });
+        this.#body.append(this.#prose, this.#selectionComment);
+        this.#body.addEventListener('mouseup', () => this.#captureSelection());
+        this.#rail.part.add('comment-rail');
+        this.#rail.hidden = true;
+        this.#railCount.part.add('comment-count');
+        this.#railChips.part.add('comment-chips');
+        this.#rail.append(this.#railCount, this.#railChips);
+        this.#popover.part.add('popover');
+        this.#popover.hidden = true;
+        this.#popover.id = POPOVER_ID;
+        this.#popover.setAttribute('role', 'dialog');
+        this.#popoverSubject.part.add('popover-subject');
+        this.#popoverQuote.part.add('popover-quote');
+        this.#popoverQuote.hidden = true;
+        this.#popoverInput.part.add('popover-input');
+        this.#popoverInput.placeholder = 'What should the agent know about this?';
+        this.#popoverInput.addEventListener('keydown', (event) => {
+            if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+                event.preventDefault();
+                this.#commitComment();
+            }
+        });
+        this.#popoverHint.part.add('popover-hint');
+        this.#popoverCancel.type = 'button';
+        this.#popoverCancel.part.add('popover-cancel');
+        this.#popoverCancel.textContent = 'Cancel';
+        this.#popoverCancel.addEventListener('click', () => this.#closeComment());
+        this.#popoverSave.type = 'button';
+        this.#popoverSave.part.add('popover-save');
+        this.#popoverSave.textContent = 'Save';
+        this.#popoverSave.addEventListener('click', () => this.#commitComment());
+        const actions = document.createElement('div');
+        actions.part.add('popover-actions');
+        const buttons = document.createElement('div');
+        buttons.part.add('popover-buttons');
+        buttons.append(this.#popoverCancel, this.#popoverSave);
+        actions.append(this.#popoverHint, buttons);
+        this.#popover.append(this.#popoverSubject, this.#popoverQuote, this.#popoverInput, actions);
+        this.#container.append(this.#toolbar, this.#surface, this.#rail, this.#popover);
+        this.#root.append(style, this.#container);
+        this.addEventListener('keydown', this.#onKeyDown);
+    }
+    connectedCallback() {
+        if (this.#live)
+            return;
+        const read = readSlotConfig(this);
+        if (read.status !== 'ok') {
+            this.#renderUnavailable(read.reason);
+            return;
+        }
+        if (typeof read.config.initialText !== 'string') {
+            this.#renderUnavailable('text config has no initialText string');
+            return;
+        }
+        this.#live = true;
+        this.#config = read.config;
+        this.#slotId = readSlotId(this);
+        this.#text = read.config.initialText;
+        this.#editing = read.config.editable === true && this.#text.length === 0;
+        this.#renderToolbar();
+        this.#renderSurface();
+        this.#renderRail();
+    }
+    disconnectedCallback() {
+        document.removeEventListener('pointerdown', this.#onDocumentPointerDown, true);
+    }
+    /** The complete current response — what every change hands `respond()`. */
+    #response() {
+        return { text: this.#text, edited: this.#text !== this.#config.initialText, comments: this.#comments };
+    }
+    #emit() {
+        if (this.#slotId === undefined)
+            return;
+        respond(this.#slotId, this.#response());
+    }
+    // — rendering —————————————————————————————————————————————————————————————
+    #renderUnavailable(reason) {
+        const box = document.createElement('div');
+        box.part.add('unavailable');
+        box.setAttribute('role', 'status');
+        const detail = document.createElement('span');
+        detail.part.add('reason');
+        detail.textContent = reason;
+        box.append('Text unavailable: ', detail);
+        this.#container.replaceChildren(box);
+    }
+    #renderToolbar() {
+        this.#editedBadge.hidden = this.#text === this.#config.initialText;
+        const whole = findComment(this.#comments, WHOLE);
+        this.#wholeComment.replaceChildren(icon(whole ? ICON_COMMENT : ICON_COMMENT_ADD));
+        this.#wholeComment.dataset.state = whole ? 'on' : 'off';
+        this.#wholeComment.setAttribute('aria-label', `${whole ? 'Edit comment on' : 'Comment on'} ${WHOLE_TARGET}`);
+        this.#editToggle.hidden = this.#config.editable !== true;
+        this.#editToggle.dataset.state = this.#editing ? 'on' : 'off';
+        this.#editLabel.textContent = this.#editing ? 'Done' : 'Edit';
+        this.#editToggle.replaceChildren(icon(this.#editing ? ICON_DONE : ICON_EDIT), this.#editLabel);
+    }
+    #renderSurface() {
+        if (this.#editing) {
+            if (this.#editor.value !== this.#text)
+                this.#editor.value = this.#text;
+            this.#editor.placeholder = this.#config.placeholder ?? 'Write your answer\u2026';
+            if (this.#surface.firstChild !== this.#editor)
+                this.#surface.replaceChildren(this.#editor);
+            return;
+        }
+        if (this.#surface.firstChild !== this.#body)
+            this.#surface.replaceChildren(this.#body);
+        this.#renderProse();
+    }
+    #renderProse() {
+        const paragraphs = splitParagraphs(this.#text);
+        if (paragraphs.length === 0) {
+            const empty = document.createElement('p');
+            empty.part.add('placeholder');
+            empty.textContent = this.#config.placeholder ?? 'Nothing yet.';
+            this.#prose.replaceChildren(empty);
+            return;
+        }
+        const rendered = paragraphs.map((paragraph) => {
+            const element = document.createElement('p');
+            element.dataset.paragraph = '';
+            element.dataset.start = String(paragraph.start);
+            for (const segment of segmentParagraph(paragraph, this.#comments)) {
+                element.append(segment.comment ? this.#renderCommented(segment.text, segment.comment) : segment.text);
+            }
+            return element;
+        });
+        this.#prose.replaceChildren(...rendered);
+    }
+    /**
+     * A saved range comment in place. The highlight is both the durable anchor and the hover
+     * target: the comment opens over the words it refers to, while the chip rail below remains
+     * the editing path.
+     */
+    #renderCommented(text, comment) {
+        const span = document.createElement('span');
+        span.part.add('commented');
+        span.tabIndex = 0;
+        span.dataset.commentId = comment.id;
+        markTrigger(span);
+        const bubble = document.createElement('span');
+        bubble.part.add('comment-bubble');
+        bubble.setAttribute('role', 'note');
+        const label = document.createElement('span');
+        label.part.add('bubble-label');
+        label.textContent = 'Comment';
+        const body = document.createElement('span');
+        body.textContent = comment.text;
+        bubble.append(label, body);
+        span.append(text, bubble);
+        return span;
+    }
+    #renderRail() {
+        const count = this.#comments.length;
+        this.#rail.hidden = count === 0;
+        if (count === 0) {
+            this.#railChips.replaceChildren();
+            return;
+        }
+        this.#railCount.textContent = `${count} comment${count === 1 ? '' : 's'}`;
+        const chips = this.#comments.map((comment) => {
+            const chip = document.createElement('button');
+            chip.type = 'button';
+            chip.part.add('comment-trigger');
+            chip.part.add('comment-chip');
+            chip.dataset.commentId = comment.id;
+            markTrigger(chip);
+            const label = document.createElement('span');
+            label.textContent = comment.text;
+            chip.append(icon(ICON_COMMENT), label);
+            const range = comment.anchor.kind === 'range' ? comment.anchor : undefined;
+            chip.setAttribute('aria-label', `Edit comment on ${range ? RANGE_TARGET : WHOLE_TARGET}`);
+            chip.addEventListener('click', () => {
+                this.#openComment(comment.anchor, range ? RANGE_TARGET : WHOLE_TARGET, chip, 'start', range?.quote);
+            });
+            return chip;
+        });
+        this.#railChips.replaceChildren(...chips);
+    }
+    // — selection ——————————————————————————————————————————————————————————————
+    /**
+     * Reads the live selection as a range anchor. One anchor is one paragraph: a comment
+     * spanning a paragraph break has no readable quote, and the review UIs worth copying all
+     * draw the same line. The boundary resolver deliberately treats an end at offset 0 of the
+     * next paragraph as the end of the previous one — that is the DOM range browsers produce
+     * for a normal whole-paragraph selection.
+     */
+    #readSelection() {
+        const range = selectionRange(this.#root, this.#body);
+        if (range === null)
+            return null;
+        const start = paragraphBoundary(this.#body, range.startContainer, range.startOffset, 'start');
+        const end = paragraphBoundary(this.#body, range.endContainer, range.endOffset, 'end');
+        if (start === null || end === null || start.paragraph !== end.paragraph)
+            return null;
+        const paragraphStart = Number(start.paragraph.dataset.start ?? '0');
+        const from = paragraphStart + start.offset;
+        const to = paragraphStart + end.offset;
+        if (to <= from)
+            return null;
+        const rect = range.getBoundingClientRect();
+        const bounds = this.#body.getBoundingClientRect();
+        return {
+            anchor: { kind: 'range', start: from, end: to, quote: this.#text.slice(from, to) },
+            left: rect.left - bounds.left,
+            top: rect.bottom - bounds.top + 4,
+        };
+    }
+    /**
+     * The affordance is anchored to the selection rather than to a toolbar, so commenting
+     * starts where the user is looking.
+     */
+    #captureSelection() {
+        if (this.#editing || this.#open !== null)
+            return;
+        const draft = this.#readSelection();
+        if (draft === null) {
+            this.#clearDraft();
+            return;
+        }
+        this.#draft = draft;
+        this.#selectionComment.hidden = false;
+        this.#selectionComment.style.left = `${draft.left}px`;
+        this.#selectionComment.style.top = `${draft.top}px`;
+    }
+    #clearDraft() {
+        this.#draft = null;
+        this.#selectionComment.hidden = true;
+    }
+    // — the comment popover ————————————————————————————————————————————————————
+    #openComment(anchor, target, trigger, align, quote) {
+        // Invoking the trigger of the open popover closes it, and moving to another trigger
+        // hands the open state over — the popover is one dialog, and exactly one control at a
+        // time reports itself as expanded.
+        const previous = this.#open;
+        if (previous !== null) {
+            if (previous.trigger === trigger) {
+                this.#closeComment();
+                return;
+            }
+            previous.trigger.setAttribute('aria-expanded', 'false');
+        }
+        const existing = findComment(this.#comments, anchor);
+        this.#open = { anchor, trigger };
+        trigger.setAttribute('aria-expanded', 'true');
+        this.#popoverSubject.textContent = `Comment on ${target}`;
+        this.#popover.setAttribute('aria-label', `Comment on ${target}`);
+        this.#popoverQuote.hidden = quote === undefined || quote === '';
+        this.#popoverQuote.textContent = quote ?? '';
+        // The box is seeded from the saved comment every time it opens, so an abandoned edit
+        // never leaks into the next one.
+        this.#popoverInput.value = existing?.text ?? '';
+        this.#popoverHint.textContent = existing ? 'empty to delete' : '\u2318\u21b5 to save';
+        this.#popover.hidden = false;
+        this.#positionPopover(trigger, align);
+        this.#popoverInput.focus();
+        document.addEventListener('pointerdown', this.#onDocumentPointerDown, true);
+    }
+    #positionPopover(trigger, align) {
+        const bounds = this.#container.getBoundingClientRect();
+        const rect = trigger.getBoundingClientRect();
+        const width = this.#popover.offsetWidth;
+        const raw = align === 'end' ? rect.right - bounds.left - width : rect.left - bounds.left;
+        const left = Math.min(Math.max(raw, 0), Math.max(0, bounds.width - width));
+        this.#popover.style.left = `${left}px`;
+        this.#popover.style.top = `${rect.bottom - bounds.top + POPOVER_GAP}px`;
+    }
+    #closeComment(restoreFocus = true) {
+        const open = this.#open;
+        this.#open = null;
+        this.#popover.hidden = true;
+        open?.trigger.setAttribute('aria-expanded', 'false');
+        document.removeEventListener('pointerdown', this.#onDocumentPointerDown, true);
+        const returnFocus = open !== null && open.trigger !== this.#selectionComment ? open.trigger : this.#body;
+        this.#clearDraft();
+        if (restoreFocus && this.#root.contains(returnFocus))
+            returnFocus.focus();
+    }
+    /** Clearing the box and saving deletes the comment; `setComment` is where that lives. */
+    #commitComment() {
+        const open = this.#open;
+        if (open === null)
+            return;
+        // Saving replaces every highlight and every chip, so a trigger living in either is
+        // about to be detached: close without restoring focus to that doomed node, then hand
+        // focus to the node that now stands for the same anchor so j/k/c keep working.
+        const anchored = this.#prose.contains(open.trigger) || this.#railChips.contains(open.trigger);
+        this.#comments = setComment(this.#comments, open.anchor, this.#popoverInput.value);
+        this.#closeComment(!anchored);
+        this.#renderToolbar();
+        if (!this.#editing)
+            this.#renderProse();
+        this.#renderRail();
+        if (anchored)
+            this.#refocusAnchor(open.anchor);
+        this.#emit();
+    }
+    /** Focus the freshly rendered highlight or chip for an anchor; the body when it is gone. */
+    #refocusAnchor(anchor) {
+        const id = findComment(this.#comments, anchor)?.id;
+        const selector = id === undefined ? null : `[data-comment-id="${CSS.escape(id)}"]`;
+        const replacement = selector === null
+            ? null
+            : (this.#prose.querySelector(selector) ??
+                this.#railChips.querySelector(selector));
+        const target = replacement ?? this.#body;
+        if (this.#root.contains(target))
+            target.focus();
+    }
+    #onDocumentPointerDown = (event) => {
+        if (this.#open === null)
+            return;
+        const path = event.composedPath();
+        if (path.includes(this.#popover) || path.includes(this.#open.trigger))
+            return;
+        this.#closeComment();
+    };
+    // — the kit's keyboard grammar ——————————————————————————————————————————————
+    #onKeyDown = (event) => {
+        if (event.defaultPrevented)
+            return;
+        if (event.key === 'Escape' && this.#open !== null) {
+            event.preventDefault();
+            this.#closeComment();
+            return;
+        }
+        if (this.#open !== null || this.#editing)
+            return;
+        const focus = event.composedPath()[0];
+        if (focus instanceof HTMLElement && (focus.tagName === 'TEXTAREA' || focus.tagName === 'INPUT'))
+            return;
+        if (event.metaKey || event.ctrlKey || event.altKey)
+            return;
+        if (event.key === 'j' || event.key === 'k') {
+            event.preventDefault();
+            this.#moveHighlight(event.key === 'j' ? 1 : -1);
+            return;
+        }
+        if (event.key === 'c') {
+            event.preventDefault();
+            this.#commentFocusedAnchor();
+        }
+    };
+    #highlights() {
+        return Array.from(this.#prose.querySelectorAll('[part~="commented"]'));
+    }
+    #moveHighlight(delta) {
+        const spans = this.#highlights();
+        if (spans.length === 0)
+            return;
+        const active = this.#root.activeElement;
+        const current = active instanceof HTMLElement ? spans.indexOf(active) : -1;
+        const next = current === -1 ? (delta > 0 ? 0 : spans.length - 1) : current + delta;
+        const target = spans[Math.min(Math.max(next, 0), spans.length - 1)];
+        target?.focus();
+    }
+    /**
+     * `c` comments what the user is on: a live selection first, then a focused highlight, and
+     * the whole passage when neither says otherwise.
+     */
+    #commentFocusedAnchor() {
+        const draft = this.#draft ?? this.#readSelection();
+        if (draft !== null) {
+            this.#draft = draft;
+            this.#selectionComment.hidden = false;
+            this.#selectionComment.style.left = `${draft.left}px`;
+            this.#selectionComment.style.top = `${draft.top}px`;
+            this.#openComment(draft.anchor, RANGE_TARGET, this.#selectionComment, 'start', draft.anchor.quote);
+            return;
+        }
+        const active = this.#root.activeElement;
+        if (active instanceof HTMLElement && active.dataset.commentId !== undefined) {
+            const comment = this.#comments.find((entry) => entry.id === active.dataset.commentId);
+            if (comment !== undefined) {
+                const range = comment.anchor.kind === 'range' ? comment.anchor : undefined;
+                const target = range === undefined ? WHOLE_TARGET : RANGE_TARGET;
+                this.#openComment(comment.anchor, target, active, 'start', range?.quote);
+                return;
+            }
+        }
+        this.#openComment(WHOLE, WHOLE_TARGET, this.#wholeComment, 'end');
+    }
+}
+registerElement('crtr-text', CrtrTextElement);