@north-light/crouter 0.3.191 → 0.3.193

package/dist/pages/elements/cards.js

@@ -0,0 +1,785 @@
+/**
+ * `<crtr-cards>` — the choice `options` makes, when each candidate has enough body to
+ * deserve its own surface: a meeting slot, a vendor, a search result.
+ *
+ * This is a port of the agent interaction kit's `cards` component, not a new design. The
+ * selection treatment is the kit's selectable-surface recipe — a hairline surface that
+ * answers the pointer and goes accent-toned once chosen — carrying the kit's selection
+ * control and the kit's comment affordance. Navigation is the kit's classic list grammar
+ * (`j`/`k` move, `x` selects, `c` comments), so a card grid, an option list and a table
+ * are all driven the same way.
+ *
+ * Data arrives one of two ways: inline `cards`, or a `source` the host resolves through
+ * `artifactData()`. The element never touches the network, and anything it cannot render —
+ * a malformed config, an unreachable source, source data that is not a card list — becomes
+ * a named unavailable state rather than an exception.
+ */
+import { findComment, setComment } from '../comments.js';
+import { artifactData, respond } from '../host.js';
+import { registerElement } from '../register.js';
+import { readSlotConfig, readSlotId } from '../slot-config.js';
+const STYLE = `
+  :host {
+    display: block;
+    /* Column count answers the element's own width, not the viewport: a slot can sit in
+       a narrow rail on a wide screen. */
+    container-type: inline-size;
+  }
+
+  [part~="container"] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--crtr-space-1);
+  }
+
+  [part~="grid"] {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: var(--crtr-space-3);
+  }
+
+  @container (min-width: 30rem) {
+    [part~="grid"] {
+      grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+
+    [part~="grid"][data-columns="3"] {
+      grid-template-columns: repeat(3, minmax(0, 1fr));
+    }
+  }
+
+  [part~="card"] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--crtr-space-2);
+    padding: var(--crtr-space-3);
+    color: var(--crtr-color-text);
+    background: var(--crtr-color-surface);
+    border: 1px solid color-mix(in srgb, var(--crtr-color-border) 60%, transparent);
+    border-radius: var(--crtr-radius-medium);
+    transition: background-color 120ms ease, border-color 120ms ease;
+  }
+
+  [part~="card"]:hover,
+  [part~="card"][part~="active"] {
+    background: var(--crtr-color-surface-hover);
+    border-color: var(--crtr-color-border);
+  }
+
+  [part~="card"][part~="selected"] {
+    background: color-mix(in srgb, var(--crtr-color-accent) 7%, transparent);
+    border-color: color-mix(in srgb, var(--crtr-color-accent) 40%, transparent);
+  }
+
+  [part~="card"][part~="selected"]:hover,
+  [part~="card"][part~="selected"][part~="active"] {
+    background: color-mix(in srgb, var(--crtr-color-accent) 12%, transparent);
+  }
+
+  [part~="card-header"] {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--crtr-space-2);
+  }
+
+  /* The label carries the click target, so the whole heading toggles the native control
+     the way the kit's Label does — and the comment button stays its own control. */
+  [part~="card-label"] {
+    display: flex;
+    flex: 1;
+    align-items: flex-start;
+    gap: var(--crtr-space-2);
+    min-width: 0;
+    font: inherit;
+    cursor: pointer;
+  }
+
+  [part~="control"] {
+    flex: none;
+    margin: 0;
+    margin-top: 0.2em;
+    accent-color: var(--crtr-color-accent);
+  }
+
+  [part~="control"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 2px;
+  }
+
+  [part~="card-heading"] {
+    display: grid;
+    flex: 1;
+    gap: calc(var(--crtr-space-1) / 2);
+    min-width: 0;
+  }
+
+  [part~="card-title"] {
+    font-weight: 500;
+    line-height: 1.35;
+  }
+
+  [part~="card-subtitle"] {
+    color: var(--crtr-color-text-muted);
+    font-size: calc(var(--crtr-font-size) * 0.85);
+  }
+
+  [part~="card-body"] {
+    margin: 0;
+    color: var(--crtr-color-text-muted);
+    font-size: calc(var(--crtr-font-size) * 0.85);
+    line-height: 1.6;
+  }
+
+  [part~="tag"] {
+    align-self: flex-start;
+    padding: 0 var(--crtr-space-1);
+    color: var(--crtr-color-text-muted);
+    font-size: calc(var(--crtr-font-size) * 0.78);
+    line-height: 1.7;
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-small);
+  }
+
+  [part~="card"][part~="selected"] [part~="tag"] {
+    color: var(--crtr-color-accent);
+    background: color-mix(in srgb, var(--crtr-color-accent) 10%, transparent);
+    border-color: color-mix(in srgb, var(--crtr-color-accent) 40%, transparent);
+  }
+
+  /* The affordance is quiet until you reach for it, and stays visible once a note lives
+     there — that presence is the whole "there is a comment here" signal. */
+  [part~="comment-button"] {
+    flex: none;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: calc(var(--crtr-font-size) * 1.6);
+    height: calc(var(--crtr-font-size) * 1.6);
+    padding: 0;
+    color: var(--crtr-color-text-muted);
+    background: none;
+    border: none;
+    border-radius: var(--crtr-radius-small);
+    cursor: pointer;
+    opacity: 0;
+    transition: opacity 120ms ease, color 120ms ease, background-color 120ms ease;
+  }
+
+  [part~="comment-button"] svg {
+    width: calc(var(--crtr-font-size) * 0.95);
+    height: calc(var(--crtr-font-size) * 0.95);
+    /* The glyph is never the event target: a repaint that swaps it mid-press would
+       otherwise leave mousedown and mouseup on different nodes and eat the click. */
+    pointer-events: none;
+  }
+
+  [part~="comment-button"]:hover {
+    color: var(--crtr-color-text);
+    background: var(--crtr-color-surface-hover);
+  }
+
+  [part~="comment-button"][part~="has-comment"] {
+    color: var(--crtr-color-accent);
+  }
+
+  [part~="card"]:hover [part~="comment-button"],
+  [part~="card"]:focus-within [part~="comment-button"],
+  [part~="comment-button"]:focus-visible,
+  [part~="comment-button"][part~="has-comment"] {
+    opacity: 1;
+  }
+
+  [part~="comment-editor"] {
+    display: grid;
+    gap: var(--crtr-space-2);
+    width: 100%;
+    padding: var(--crtr-space-2);
+    text-align: left;
+    background: var(--crtr-color-background);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-small);
+    cursor: auto;
+  }
+
+  [part~="comment-subject"],
+  [part~="comment-hint"] {
+    color: var(--crtr-color-text-muted);
+    font-family: var(--crtr-font-mono);
+    font-size: calc(var(--crtr-font-size) * 0.72);
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+  }
+
+  [part~="comment-input"] {
+    box-sizing: border-box;
+    width: 100%;
+    min-height: 4.5em;
+    padding: var(--crtr-space-1) var(--crtr-space-2);
+    color: var(--crtr-color-text);
+    font: inherit;
+    background: var(--crtr-color-background);
+    border: 1px solid var(--crtr-color-border);
+    border-radius: var(--crtr-radius-small);
+    resize: vertical;
+  }
+
+  [part~="comment-input"]:focus-visible {
+    outline: 2px solid var(--crtr-color-focus);
+    outline-offset: 1px;
+  }
+
+  [part~="comment-actions"] {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--crtr-space-2);
+  }
+
+  [part~="comment-buttons"] {
+    display: flex;
+    gap: var(--crtr-space-1);
+  }
+
+  [part~="comment-cancel"],
+  [part~="comment-save"] {
+    padding: var(--crtr-space-1) var(--crtr-space-2);
+    font: inherit;
+    font-size: calc(var(--crtr-font-size) * 0.9);
+    border-radius: var(--crtr-radius-small);
+    cursor: pointer;
+  }
+
+  [part~="comment-cancel"] {
+    color: var(--crtr-color-text-muted);
+    background: none;
+    border: 1px solid transparent;
+  }
+
+  [part~="comment-cancel"]:hover {
+    color: var(--crtr-color-text);
+    background: var(--crtr-color-surface-hover);
+  }
+
+  [part~="comment-save"] {
+    color: var(--crtr-color-accent-contrast);
+    background: var(--crtr-color-accent);
+    border: 1px solid var(--crtr-color-accent);
+  }
+
+  [part~="unavailable"],
+  [part~="empty"],
+  [part~="loading"] {
+    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~="kind"] {
+    color: var(--crtr-color-text);
+    font-family: var(--crtr-font-mono);
+  }
+
+  [part~="reason"] {
+    display: block;
+    margin-top: var(--crtr-space-1);
+    font-size: calc(var(--crtr-font-size) * 0.85);
+  }
+`;
+/**
+ * A card is a plain `{ id, title }` record; everything else is optional prose. This mirrors
+ * `cardSchema`, which is strict — an unknown key means the data is not a card, so a typo
+ * surfaces as an unavailable state rather than a silently dropped field.
+ */
+const CARD_KEYS = new Set(['id', 'title', 'subtitle', 'body', 'tag']);
+function normalizeCard(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const value = raw;
+    if (typeof value.id !== 'string' || value.id === '')
+        return null;
+    if (typeof value.title !== 'string' || value.title === '')
+        return null;
+    for (const key of ['subtitle', 'body', 'tag']) {
+        if (value[key] !== undefined && typeof value[key] !== 'string')
+            return null;
+    }
+    for (const key of Object.keys(value)) {
+        if (!CARD_KEYS.has(key))
+            return null;
+    }
+    return {
+        id: value.id,
+        title: value.title,
+        subtitle: value.subtitle,
+        body: value.body,
+        tag: value.tag,
+    };
+}
+/** A card list, or `null` when the data is not one. Ids must be unique — selection keys off them. */
+function normalizeCards(raw) {
+    if (!Array.isArray(raw))
+        return null;
+    const cards = [];
+    const seen = new Set();
+    for (const entry of raw) {
+        const card = normalizeCard(entry);
+        if (card === null || seen.has(card.id))
+            return null;
+        seen.add(card.id);
+        cards.push(card);
+    }
+    return cards;
+}
+const CONFIG_KEYS = new Set(['cards', 'source', 'mode', 'columns']);
+/** Mirrors strict `cardsConfigSchema`, so this element accepts exactly what the agent may send. */
+function normalizeConfig(raw) {
+    for (const key of Object.keys(raw)) {
+        if (!CONFIG_KEYS.has(key))
+            return { status: 'invalid', reason: `unknown config property "${key}"` };
+    }
+    const mode = raw.mode;
+    if (mode !== 'single' && mode !== 'multi')
+        return { status: 'invalid', reason: 'mode must be "single" or "multi"' };
+    // The source string is opaque to this element — the host is the only thing that reads it.
+    const source = raw.source;
+    if (source !== undefined && typeof source !== 'string') {
+        return { status: 'invalid', reason: 'source must be a string' };
+    }
+    const columns = raw.columns;
+    if (columns !== undefined && columns !== 2 && columns !== 3) {
+        return { status: 'invalid', reason: 'columns must be 2 or 3' };
+    }
+    let cards;
+    if (raw.cards !== undefined) {
+        if (source !== undefined)
+            return { status: 'invalid', reason: 'cards and source are mutually exclusive' };
+        const parsed = normalizeCards(raw.cards);
+        if (parsed === null)
+            return { status: 'invalid', reason: 'cards must be a list of uniquely identified cards' };
+        cards = parsed;
+    }
+    return { status: 'ok', config: { cards, source: source, mode, columns } };
+}
+/**
+ * Typing in the comment box is ordinary writing — the list grammar keeps out of it. A card's
+ * own radio or checkbox is not prose, so `j`/`k`/`x`/`c` still reach the grid from there.
+ */
+function isTextEntry(target) {
+    if (target instanceof HTMLTextAreaElement)
+        return true;
+    if (target instanceof HTMLElement && target.isContentEditable)
+        return true;
+    if (!(target instanceof HTMLInputElement))
+        return false;
+    return target.type !== 'checkbox' && target.type !== 'radio';
+}
+const SVG_NS = 'http://www.w3.org/2000/svg';
+/** The comment glyph: a speech square, gaining a line of text once a note lives there. */
+function commentIcon(hasComment) {
+    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');
+    const bubble = document.createElementNS(SVG_NS, 'path');
+    bubble.setAttribute('d', 'M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z');
+    svg.append(bubble);
+    const marks = hasComment
+        ? [
+            ['7', '9', '17', '9'],
+            ['7', '13', '13', '13'],
+        ]
+        : [
+            ['12', '7', '12', '13'],
+            ['9', '10', '15', '10'],
+        ];
+    for (const [x1, y1, x2, y2] of marks) {
+        const line = document.createElementNS(SVG_NS, 'line');
+        line.setAttribute('x1', x1 ?? '0');
+        line.setAttribute('y1', y1 ?? '0');
+        line.setAttribute('x2', x2 ?? '0');
+        line.setAttribute('y2', y2 ?? '0');
+        svg.append(line);
+    }
+    return svg;
+}
+/** Radio groups are keyed by name, so every element on a page needs its own. */
+let groupCounter = 0;
+class CrtrCardsElement extends HTMLElement {
+    #container = document.createElement('div');
+    #group;
+    #config = null;
+    #cards = [];
+    #slotId;
+    // Response state. Authoritative for rendering; `respond()` only asks the host to save it.
+    #selected = [];
+    #comments = [];
+    #activeId = null;
+    #nodes = new Map();
+    #open = null;
+    #editor = null;
+    /** Bumped on every (dis)connect so a late source read cannot paint a stale grid. */
+    #generation = 0;
+    constructor() {
+        super();
+        groupCounter += 1;
+        this.#group = `crtr-cards-${groupCounter}`;
+        const root = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent = STYLE;
+        this.#container.part.add('container');
+        this.#container.addEventListener('keydown', (event) => this.#onKeyDown(event));
+        root.append(style, this.#container);
+    }
+    connectedCallback() {
+        this.#generation += 1;
+        const generation = this.#generation;
+        const read = readSlotConfig(this);
+        if (read.status !== 'ok') {
+            this.#renderUnavailable(read.reason);
+            return;
+        }
+        const normalized = normalizeConfig(read.config);
+        if (normalized.status !== 'ok') {
+            this.#renderUnavailable(normalized.reason);
+            return;
+        }
+        this.#config = normalized.config;
+        this.#slotId = readSlotId(this);
+        const source = normalized.config.source;
+        if (source === undefined) {
+            this.#cards = normalized.config.cards ?? [];
+            this.#build();
+            return;
+        }
+        this.#renderStatus('loading', 'Loading cards…');
+        void this.#resolveSource(source, generation);
+    }
+    disconnectedCallback() {
+        this.#generation += 1;
+    }
+    /** The host resolves `source`; this element never touches the network. */
+    async #resolveSource(source, generation) {
+        const read = await artifactData(source);
+        if (generation !== this.#generation)
+            return;
+        if (read.status !== 'ok') {
+            this.#renderUnavailable(read.reason);
+            return;
+        }
+        const cards = normalizeCards(read.data);
+        if (cards === null) {
+            this.#renderUnavailable(`source "${source}" is not a list of cards`);
+            return;
+        }
+        this.#cards = cards;
+        this.#build();
+    }
+    // ---------------------------------------------------------------- rendering
+    #renderUnavailable(reason) {
+        this.#nodes.clear();
+        this.#open = null;
+        this.#editor = null;
+        const box = document.createElement('div');
+        box.part.add('unavailable');
+        box.setAttribute('role', 'status');
+        const kind = document.createElement('span');
+        kind.part.add('kind');
+        kind.textContent = 'cards';
+        const detail = document.createElement('span');
+        detail.part.add('reason');
+        detail.textContent = reason;
+        box.append('Component unavailable: ', kind, detail);
+        this.#container.replaceChildren(box);
+    }
+    #renderStatus(part, text) {
+        const box = document.createElement('div');
+        box.part.add(part);
+        box.setAttribute('role', 'status');
+        box.textContent = text;
+        this.#container.replaceChildren(box);
+    }
+    /** Builds the grid once per data load; every later change repaints in place. */
+    #build() {
+        const config = this.#config;
+        if (config === null)
+            return;
+        this.#nodes.clear();
+        this.#open = null;
+        this.#editor = null;
+        // A selection or comment carried over from a previous data load can only name a card
+        // that is still here — true even when the new load has no cards at all.
+        const ids = new Set(this.#cards.map((card) => card.id));
+        this.#selected = this.#selected.filter((id) => ids.has(id));
+        this.#comments = this.#comments.filter((comment) => comment.anchor.kind !== 'card' || ids.has(comment.anchor.cardId));
+        if (this.#cards.length === 0) {
+            this.#renderStatus('empty', 'No cards to choose from.');
+            return;
+        }
+        const grid = document.createElement('div');
+        grid.part.add('grid');
+        if (config.columns === 3)
+            grid.dataset.columns = '3';
+        grid.append(...this.#cards.map((card) => this.#buildCard(card, config.mode, this.#group)));
+        this.#container.replaceChildren(grid);
+        this.#paint();
+    }
+    #buildCard(card, mode, group) {
+        const root = document.createElement('div');
+        root.part.add('card');
+        root.dataset.cardId = card.id;
+        const header = document.createElement('div');
+        header.part.add('card-header');
+        // The surface is presentational; the real radio / checkbox is the control, so a
+        // native radio group's arrow keys, Enter and Space all behave as they always do.
+        const label = document.createElement('label');
+        label.part.add('card-label');
+        const control = document.createElement('input');
+        control.part.add('control');
+        control.type = mode === 'single' ? 'radio' : 'checkbox';
+        control.name = group;
+        control.value = card.id;
+        control.addEventListener('change', () => this.#toggle(card.id, control.checked));
+        control.addEventListener('focus', () => this.#setActive(card.id, false));
+        const heading = document.createElement('span');
+        heading.part.add('card-heading');
+        const title = document.createElement('span');
+        title.part.add('card-title');
+        title.textContent = card.title;
+        heading.append(title);
+        if (card.subtitle !== undefined && card.subtitle !== '') {
+            const subtitle = document.createElement('span');
+            subtitle.part.add('card-subtitle');
+            subtitle.textContent = card.subtitle;
+            heading.append(subtitle);
+        }
+        const commentButton = document.createElement('button');
+        commentButton.type = 'button';
+        commentButton.part.add('comment-button');
+        commentButton.addEventListener('click', (event) => {
+            event.stopPropagation();
+            this.#setActive(card.id, false);
+            this.#toggleEditor({ kind: 'card', cardId: card.id }, card.title, root, null);
+        });
+        label.append(control, heading);
+        header.append(label, commentButton);
+        root.append(header);
+        if (card.body !== undefined && card.body !== '') {
+            const body = document.createElement('p');
+            body.part.add('card-body');
+            body.textContent = card.body;
+            root.append(body);
+        }
+        let tag = null;
+        if (card.tag !== undefined && card.tag !== '') {
+            tag = document.createElement('span');
+            tag.part.add('tag');
+            tag.textContent = card.tag;
+            root.append(tag);
+        }
+        root.addEventListener('mouseenter', () => this.#setActive(card.id, false));
+        root.addEventListener('mouseleave', () => {
+            if (this.#activeId === card.id)
+                this.#setActive(null, false);
+        });
+        root.addEventListener('focusin', () => this.#setActive(card.id, false));
+        this.#nodes.set(card.id, { root, control, commentButton, tag });
+        return root;
+    }
+    /** Repaints selection, activity and comment presence without rebuilding the grid. */
+    #paint() {
+        const mode = this.#config?.mode ?? 'multi';
+        const tabbableId = mode === 'single' ? (this.#selected[0] ?? this.#cards[0]?.id) : undefined;
+        for (const card of this.#cards) {
+            const node = this.#nodes.get(card.id);
+            if (node === undefined)
+                continue;
+            const selected = this.#selected.includes(card.id);
+            node.root.part.toggle('selected', selected);
+            node.root.part.toggle('active', this.#activeId === card.id);
+            node.control.checked = selected;
+            // A radio group holds one tab stop; an unselected group still needs an entry point.
+            node.control.tabIndex = mode === 'single' && card.id !== tabbableId ? -1 : 0;
+            const comment = findComment(this.#comments, { kind: 'card', cardId: card.id });
+            this.#paintCommentButton(node.commentButton, comment, card.title);
+        }
+    }
+    #paintCommentButton(button, comment, target) {
+        const has = comment !== undefined;
+        const glyphChanged = button.part.contains('has-comment') !== has;
+        button.part.toggle('has-comment', has);
+        button.setAttribute('aria-label', has ? `Edit comment on ${target}` : `Comment on ${target}`);
+        // The saved note reads on hover, so a comment is legible without opening its editor.
+        if (has)
+            button.title = comment.text;
+        else
+            button.removeAttribute('title');
+        // Paint runs on every hover and focus change; only a real change touches the DOM.
+        if (glyphChanged || button.childElementCount === 0)
+            button.replaceChildren(commentIcon(has));
+    }
+    // ------------------------------------------------------------- interaction
+    #setActive(id, focus) {
+        if (this.#activeId === id && !focus)
+            return;
+        this.#activeId = id;
+        this.#paint();
+        if (focus && id !== null)
+            this.#nodes.get(id)?.control.focus();
+    }
+    #toggle(cardId, selected) {
+        if (this.#config === null)
+            return;
+        if (this.#config.mode === 'single') {
+            // Radio semantics: choosing a card replaces the answer, and re-choosing keeps it.
+            this.#selected = [cardId];
+        }
+        else {
+            const next = selected
+                ? [...this.#selected, cardId]
+                : this.#selected.filter((id) => id !== cardId);
+            // Selection reads back in the order the agent authored the cards, not click order.
+            this.#selected = this.#cards.map((card) => card.id).filter((id) => next.includes(id));
+        }
+        this.#paint();
+        this.#emit();
+    }
+    #onKeyDown(event) {
+        if (event.metaKey || event.ctrlKey || event.altKey)
+            return;
+        if (isTextEntry(event.target))
+            return;
+        const ids = this.#cards.map((card) => card.id);
+        if (ids.length === 0)
+            return;
+        const key = event.key.toLowerCase();
+        const currentId = this.#activeId ?? this.#selected[this.#selected.length - 1] ?? ids[0] ?? '';
+        if (key === 'j' || key === 'k') {
+            event.preventDefault();
+            const index = Math.max(0, ids.indexOf(currentId));
+            const step = key === 'j' ? 1 : -1;
+            const nextId = ids[(index + step + ids.length) % ids.length];
+            if (nextId !== undefined)
+                this.#setActive(nextId, true);
+            return;
+        }
+        if (key === 'x') {
+            event.preventDefault();
+            this.#toggle(currentId, this.#config?.mode === 'single' ? true : !this.#selected.includes(currentId));
+            return;
+        }
+        if (key === 'c') {
+            event.preventDefault();
+            const card = this.#cards.find((entry) => entry.id === currentId);
+            const node = this.#nodes.get(currentId);
+            if (card === undefined || node === undefined)
+                return;
+            this.#setActive(currentId, false);
+            this.#toggleEditor({ kind: 'card', cardId: card.id }, card.title, node.root, null);
+        }
+        // Enter, Space and the arrow keys are left to the native radio / checkbox, exactly as
+        // the kit leaves them — this handler only adds the list grammar on top.
+    }
+    // ----------------------------------------------------------------- comments
+    /** Opens the editor for `anchor`, or closes it when it is already the open one. */
+    #toggleEditor(anchor, target, mount, after) {
+        if (mount === null)
+            return;
+        const openAnchor = this.#open?.anchor;
+        const sameAnchor = openAnchor !== undefined &&
+            openAnchor.kind === anchor.kind &&
+            (anchor.kind !== 'card' || (openAnchor.kind === 'card' && openAnchor.cardId === anchor.cardId));
+        this.#closeEditor(false);
+        if (sameAnchor)
+            return;
+        this.#openEditor({ anchor, target, mount, after });
+    }
+    #openEditor(open) {
+        const editor = document.createElement('div');
+        editor.part.add('comment-editor');
+        // The editor lives inside the card it comments on; a click in it is not a card click.
+        editor.addEventListener('click', (event) => event.stopPropagation());
+        const subject = document.createElement('p');
+        subject.part.add('comment-subject');
+        subject.textContent = `Comment on ${open.target}`;
+        const input = document.createElement('textarea');
+        input.part.add('comment-input');
+        input.placeholder = 'What should the agent know about this?';
+        // Seeded from the saved comment every time it opens, so an abandoned edit never leaks.
+        input.value = findComment(this.#comments, open.anchor)?.text ?? '';
+        const actions = document.createElement('div');
+        actions.part.add('comment-actions');
+        const hint = document.createElement('span');
+        hint.part.add('comment-hint');
+        hint.textContent = findComment(this.#comments, open.anchor) !== undefined ? 'empty to delete' : '⌘↵ to save';
+        const buttons = document.createElement('div');
+        buttons.part.add('comment-buttons');
+        const cancel = document.createElement('button');
+        cancel.type = 'button';
+        cancel.part.add('comment-cancel');
+        cancel.textContent = 'Cancel';
+        cancel.addEventListener('click', () => this.#closeEditor(true));
+        const save = document.createElement('button');
+        save.type = 'button';
+        save.part.add('comment-save');
+        save.textContent = 'Save';
+        save.addEventListener('click', () => this.#commitComment(input.value));
+        buttons.append(cancel, save);
+        actions.append(hint, buttons);
+        input.addEventListener('keydown', (event) => {
+            if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+                event.preventDefault();
+                this.#commitComment(input.value);
+                return;
+            }
+            if (event.key === 'Escape') {
+                event.preventDefault();
+                this.#closeEditor(true);
+            }
+        });
+        editor.append(subject, input, actions);
+        if (open.after !== null)
+            open.after.after(editor);
+        else
+            open.mount.append(editor);
+        this.#open = open;
+        this.#editor = editor;
+        input.focus();
+    }
+    #closeEditor(restoreFocus) {
+        const open = this.#open;
+        this.#editor?.remove();
+        this.#editor = null;
+        this.#open = null;
+        if (!restoreFocus || open === null)
+            return;
+        if (open.anchor.kind === 'card')
+            this.#nodes.get(open.anchor.cardId)?.control.focus();
+    }
+    #commitComment(text) {
+        const open = this.#open;
+        if (open === null)
+            return;
+        this.#comments = setComment(this.#comments, open.anchor, text);
+        this.#closeEditor(true);
+        this.#paint();
+        this.#emit();
+    }
+    // ----------------------------------------------------------------- response
+    #response() {
+        return { selectedCardIds: [...this.#selected], comments: this.#comments.map((comment) => ({ ...comment })) };
+    }
+    /** Every user change hands the host this slot's complete current response, never a delta. */
+    #emit() {
+        if (this.#slotId === undefined)
+            return;
+        respond(this.#slotId, this.#response());
+    }
+}
+registerElement('crtr-cards', CrtrCardsElement);