@north-light/crouter 0.3.197 → 0.3.198

package/dist/pages/elements/options.js

@@ -17,10 +17,22 @@
  * Selection is kept in the agent's authored order, never click order, so the response reads
  * the way the question did. `freetext` is absent rather than empty: the response says whether
  * the user wrote something, not whether the box existed.
+ *
+ * Every styling value this element paints is read through a `--crtr-options-*` component
+ * token, so a host restyles the question without touching crtr. Paint that the bundle shares —
+ * the option controls, the two writing boxes, the focus ring on every button — chains through
+ * the `--crtr-control-*` family behind its element token, which is what keeps a comment box
+ * here identical to one in `<crtr-text>` unless a host deliberately parts them. Each anatomy
+ * part carries its own scope: the option row and the control inside it, the comment trigger
+ * and the box it opens, and the two buttons in that box are five things a person can point at,
+ * so they are five scopes rather than one shared name meaning two different rectangles.
  */
-import { adoptComments, setComment, findComment } from '../comments.js';
+import { adoptComments, canRecordComments, setComment, findComment } from '../comments.js';
+import { controlStyle, focusRingStyle, writingBoxStyle } from '../controls.js';
 import { respond, savedIds, savedResponse } from '../host.js';
+import { applyReadOnly, isReadOnly } from '../readonly.js';
 import { registerElement } from '../register.js';
+import { registerSlotResponse } from '../responses.js';
 import { readSlotConfig, readSlotId } from '../slot-config.js';
 const BUBBLE_PLUS = '<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M2.5 3.5h11v7h-6l-3 2.5v-2.5h-2z"/><path d="M8 5.5v3M6.5 7h3"/></svg>';
 const BUBBLE_TEXT = '<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M2.5 3.5h11v7h-6l-3 2.5v-2.5h-2z"/><path d="M5 6.25h6M5 8.25h4"/></svg>';
@@ -31,84 +43,118 @@ const STYLE = `
 
   [part="container"] {
     display: grid;
-    gap: var(--crtr-space-3);
+    gap: var(--crtr-options-container-gap, var(--crtr-space-3));
+  }
+
+  /* The question reads as the agent's own prose above its control, matching the table's
+     caption rather than shouting over the options it introduces. */
+  [part="label"] {
+    margin: var(--crtr-options-label-margin, 0);
+    color: var(--crtr-options-label-text-color, var(--crtr-color-text-muted));
   }
 
   [part="list"] {
     display: grid;
-    gap: var(--crtr-space-2);
+    gap: var(--crtr-options-list-gap, var(--crtr-space-2));
   }
 
   [part="option"] {
     position: relative;
     display: flex;
     align-items: flex-start;
-    gap: var(--crtr-space-3);
-    padding: var(--crtr-space-2) var(--crtr-space-3);
-    background: var(--crtr-color-surface);
-    border: 1px solid var(--crtr-color-border);
-    border-radius: var(--crtr-radius-medium);
-    transition: background-color 120ms ease, border-color 120ms ease;
+    gap: var(--crtr-options-option-gap, var(--crtr-space-3));
+    padding: var(--crtr-options-option-padding, var(--crtr-space-2) var(--crtr-space-3));
+    background: var(--crtr-options-option-fill, var(--crtr-color-surface));
+    border: var(--crtr-options-option-border-width, 1px)
+      var(--crtr-options-option-border-style, solid)
+      var(--crtr-options-option-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-options-option-radius, var(--crtr-radius-medium));
+    transition: background-color var(--crtr-options-option-transition, 120ms ease),
+      border-color var(--crtr-options-option-transition, 120ms ease);
   }
 
   [part="option"]:hover,
   [part="option"][data-active="true"] {
-    background: var(--crtr-color-surface-hover);
+    background: var(--crtr-options-option-hover-fill, var(--crtr-color-surface-hover));
   }
 
   [part="option"][data-selected="true"] {
-    border-color: var(--crtr-color-accent);
-    background: color-mix(in srgb, var(--crtr-color-accent) 10%, var(--crtr-color-surface));
+    border-color: var(
+      --crtr-options-option-selected-border-color,
+      color-mix(in srgb, var(--crtr-color-accent) 45%, transparent)
+    );
+    background: var(
+      --crtr-options-option-selected-fill,
+      color-mix(in srgb, var(--crtr-color-accent) 10%, transparent)
+    );
+  }
+
+  [part="option"][data-selected="true"]:hover,
+  [part="option"][data-selected="true"][data-active="true"] {
+    background: var(
+      --crtr-options-option-selected-hover-fill,
+      color-mix(in srgb, var(--crtr-color-accent) 14%, transparent)
+    );
+  }
+
+  /* A page that can no longer take an answer keeps its selection legible and drops every
+     affordance that says it could still be changed. */
+  [part="option"]:has([part="option-control"]:disabled) [part="option-label"] {
+    cursor: default;
   }
 
   [part="option-label"] {
     display: flex;
     flex: 1;
     align-items: flex-start;
-    gap: var(--crtr-space-3);
+    gap: var(--crtr-options-option-label-gap, var(--crtr-space-3));
     cursor: pointer;
   }
 
-  [part="option-control"] {
-    margin: 0;
-    margin-top: 0.15em;
-    accent-color: var(--crtr-color-accent);
-  }
+  ${controlStyle({ scope: 'options-option-control' }, '[part="option-control"]')}
 
-  [part="option-control"]:focus-visible {
-    outline: 2px solid var(--crtr-color-focus);
-    outline-offset: 2px;
+  /* Centred on the first line of the label rather than on its box, so a two-line option keeps
+     the control beside the title. Half the difference between a 1.5 line box and the control. */
+  [part="option-control"] {
+    margin-top: var(--crtr-options-option-control-offset, 0.1875em);
   }
 
   [part="option-text"] {
     display: grid;
-    gap: var(--crtr-space-1);
+    gap: var(--crtr-options-option-text-gap, var(--crtr-space-1));
   }
 
   [part="option-title"] {
-    font-weight: 500;
+    font-weight: var(--crtr-options-option-title-font-weight, 500);
   }
 
   [part="option-description"] {
-    color: var(--crtr-color-text-muted);
-    font-size: 0.9em;
+    color: var(--crtr-options-option-description-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-options-option-description-font-size, 0.875em);
   }
 
+  /* The trigger stays in the row's anatomy while quiet, then its state rule below reveals it.
+     A host can choose how quiet and how bright those states are independently; the transition
+     remains one knob because all three properties are one reveal. */
   [part="comment"] {
     display: inline-flex;
     align-items: center;
     justify-content: center;
     flex: none;
-    width: 1.5rem;
-    height: 1.5rem;
-    padding: 0;
-    color: var(--crtr-color-text-muted);
-    background: transparent;
-    border: 1px solid transparent;
-    border-radius: var(--crtr-radius-small);
-    opacity: 0;
+    width: var(--crtr-options-comment-size, 1.5em);
+    height: var(--crtr-options-comment-size, 1.5em);
+    padding: var(--crtr-options-comment-padding, 0);
+    color: var(--crtr-options-comment-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-options-comment-fill, transparent);
+    border: var(--crtr-options-comment-border-width, 1px)
+      var(--crtr-options-comment-border-style, solid)
+      var(--crtr-options-comment-border-color, transparent);
+    border-radius: var(--crtr-options-comment-radius, var(--crtr-radius-small));
+    opacity: var(--crtr-options-comment-opacity, 0);
     cursor: pointer;
-    transition: opacity 120ms ease, color 120ms ease, background-color 120ms ease;
+    transition: opacity var(--crtr-options-comment-transition, var(--crtr-control-transition, 120ms ease)),
+      color var(--crtr-options-comment-transition, var(--crtr-control-transition, 120ms ease)),
+      background-color var(--crtr-options-comment-transition, var(--crtr-control-transition, 120ms ease));
   }
 
   [part="option"]:hover [part="comment"],
@@ -116,158 +162,166 @@ const STYLE = `
   [part="option"]:focus-within [part="comment"],
   [part="comment"][data-state="commented"],
   [part="comment"][aria-expanded="true"] {
-    opacity: 1;
+    opacity: var(--crtr-options-comment-visible-opacity, 1);
   }
 
   [part="comment"]:hover {
-    background: var(--crtr-color-surface-hover);
-    border-color: var(--crtr-color-border);
-  }
-
-  [part="comment"]:focus-visible {
-    outline: 2px solid var(--crtr-color-focus);
-    outline-offset: 1px;
+    background: var(--crtr-options-comment-hover-fill, var(--crtr-color-surface-hover));
+    border-color: var(--crtr-options-comment-hover-border-color, var(--crtr-color-border));
   }
 
+${focusRingStyle({ scope: 'options-comment' }, '[part="comment"]')}
   [part="comment"][data-state="commented"] {
-    color: var(--crtr-color-accent);
+    color: var(--crtr-options-comment-commented-text-color, var(--crtr-color-accent));
   }
 
   [part="comment"] svg {
-    width: 0.9rem;
-    height: 0.9rem;
-    fill: none;
-    stroke: currentColor;
-    stroke-width: 1.25;
-    stroke-linecap: round;
-    stroke-linejoin: round;
+    width: var(--crtr-options-comment-icon-size, 0.875em);
+    height: var(--crtr-options-comment-icon-size, 0.875em);
+    fill: var(--crtr-options-comment-icon-fill, none);
+    stroke: var(--crtr-options-comment-icon-stroke-color, currentColor);
+    stroke-width: var(--crtr-options-comment-icon-stroke-width, 1.25);
+    stroke-linecap: var(--crtr-options-comment-icon-stroke-cap, round);
+    stroke-linejoin: var(--crtr-options-comment-icon-stroke-join, round);
   }
 
   [part="comment-popover"] {
     position: absolute;
-    top: calc(100% + var(--crtr-space-1));
+    top: calc(100% + var(--crtr-options-comment-popover-offset, var(--crtr-space-1)));
     right: 0;
     z-index: 2;
     display: grid;
-    gap: var(--crtr-space-2);
-    width: min(20rem, 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);
+    gap: var(--crtr-options-comment-popover-gap, var(--crtr-space-2));
+    width: var(--crtr-options-comment-popover-width, min(20em, 100%));
+    padding: var(--crtr-options-comment-popover-padding, var(--crtr-space-3));
+    background: var(--crtr-options-comment-popover-fill, var(--crtr-color-background));
+    border: var(--crtr-options-comment-popover-border-width, 1px)
+      var(--crtr-options-comment-popover-border-style, solid)
+      var(--crtr-options-comment-popover-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-options-comment-popover-radius, var(--crtr-radius-medium));
+    box-shadow: var(--crtr-options-comment-popover-shadow, var(--crtr-shadow));
   }
 
   [part="comment-popover"][hidden] {
     display: none;
   }
 
+  /* The popover's own prose, in the page's voice — not a caps-mono field label shouting an
+     option id at someone who just clicked that option. */
   [part="comment-subject"] {
-    margin: 0;
-    color: var(--crtr-color-text-muted);
-    font-family: var(--crtr-font-mono);
-    font-size: 0.75em;
-    letter-spacing: 0.06em;
-    text-transform: uppercase;
-  }
-
-  [part="comment-input"],
-  [part="freetext-input"] {
-    width: 100%;
-    box-sizing: border-box;
-    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;
+    margin: var(--crtr-options-comment-subject-margin, 0);
+    color: var(--crtr-options-comment-subject-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-options-comment-subject-font-size, 0.875em);
   }
 
+  /* Two calls rather than one selector list: a comment box and the freetext box are two things
+     a person can point at, so each takes its own scope. They still share the family layer
+     underneath, so they cannot drift apart unless a host parts them on purpose. */
+${writingBoxStyle({ scope: 'options-comment-input' }, '[part="comment-input"]')}
+${writingBoxStyle({ scope: 'options-freetext-input' }, '[part="freetext-input"]')}
   [part="comment-input"] {
-    min-height: 4.5rem;
+    min-height: var(--crtr-options-comment-input-min-height, 4.5em);
+    resize: vertical;
   }
 
   [part="freetext-input"] {
-    min-height: 4rem;
-  }
-
-  [part="comment-input"]:focus-visible,
-  [part="freetext-input"]:focus-visible {
-    outline: 2px solid var(--crtr-color-focus);
-    outline-offset: -1px;
+    min-height: var(--crtr-options-freetext-input-min-height, 4em);
+    resize: vertical;
   }
 
   [part="comment-actions"] {
     display: flex;
     align-items: center;
     justify-content: space-between;
-    gap: var(--crtr-space-2);
+    gap: var(--crtr-options-comment-actions-gap, var(--crtr-space-2));
   }
 
   [part="comment-hint"] {
-    color: var(--crtr-color-text-muted);
-    font-family: var(--crtr-font-mono);
-    font-size: 0.75em;
-    letter-spacing: 0.06em;
-    text-transform: uppercase;
-  }
-
-  [part="comment-cancel"],
-  [part="comment-save"] {
-    padding: var(--crtr-space-1) var(--crtr-space-2);
-    font: inherit;
-    font-size: 0.9em;
-    border-radius: var(--crtr-radius-small);
-    cursor: pointer;
+    color: var(--crtr-options-comment-hint-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-options-comment-hint-font-size, 0.875em);
   }
 
+  /* The two buttons are one shape drawn twice rather than one rule serving two parts, because
+     a scope that named both would make "the cancel button's fill" unsayable. */
   [part="comment-cancel"] {
-    color: var(--crtr-color-text-muted);
-    background: transparent;
-    border: 1px solid transparent;
+    padding: var(--crtr-options-comment-cancel-padding, var(--crtr-space-1) var(--crtr-space-2));
+    font: var(--crtr-options-comment-cancel-font, inherit);
+    font-size: var(--crtr-options-comment-cancel-font-size, 0.875em);
+    color: var(--crtr-options-comment-cancel-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-options-comment-cancel-fill, transparent);
+    border: var(--crtr-options-comment-cancel-border-width, 1px)
+      var(--crtr-options-comment-cancel-border-style, solid)
+      var(--crtr-options-comment-cancel-border-color, transparent);
+    border-radius: var(--crtr-options-comment-cancel-radius, var(--crtr-radius-small));
+    cursor: pointer;
+    transition: color var(--crtr-options-comment-cancel-transition, var(--crtr-control-transition, 120ms ease)),
+      background-color var(--crtr-options-comment-cancel-transition, var(--crtr-control-transition, 120ms ease)),
+      border-color var(--crtr-options-comment-cancel-transition, var(--crtr-control-transition, 120ms ease));
   }
 
   [part="comment-cancel"]:hover {
-    color: var(--crtr-color-text);
-    background: var(--crtr-color-surface-hover);
+    color: var(--crtr-options-comment-cancel-hover-text-color, var(--crtr-color-text));
+    background: var(--crtr-options-comment-cancel-hover-fill, 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="comment-cancel"]:focus-visible,
-  [part="comment-save"]:focus-visible {
-    outline: 2px solid var(--crtr-color-focus);
-    outline-offset: 1px;
-  }
-
+    padding: var(--crtr-options-comment-save-padding, var(--crtr-space-1) var(--crtr-space-2));
+    font: var(--crtr-options-comment-save-font, inherit);
+    font-size: var(--crtr-options-comment-save-font-size, 0.875em);
+    color: var(--crtr-options-comment-save-text-color, var(--crtr-color-accent-contrast));
+    background: var(--crtr-options-comment-save-fill, var(--crtr-color-accent));
+    border: var(--crtr-options-comment-save-border-width, 1px)
+      var(--crtr-options-comment-save-border-style, solid)
+      var(--crtr-options-comment-save-border-color, var(--crtr-color-accent));
+    border-radius: var(--crtr-options-comment-save-radius, var(--crtr-radius-small));
+    cursor: pointer;
+    transition: color var(--crtr-options-comment-save-transition, var(--crtr-control-transition, 120ms ease)),
+      background-color var(--crtr-options-comment-save-transition, var(--crtr-control-transition, 120ms ease)),
+      border-color var(--crtr-options-comment-save-transition, var(--crtr-control-transition, 120ms ease));
+  }
+
+  /* Mixing the accent toward the text colour darkens on a light token set and lightens on a
+     dark one — a brightness filter moves the wrong way on one of them. */
+  [part="comment-save"]:hover {
+    background: var(
+      --crtr-options-comment-save-hover-fill,
+      color-mix(in srgb, var(--crtr-color-accent) 88%, var(--crtr-color-text))
+    );
+    border-color: var(
+      --crtr-options-comment-save-hover-border-color,
+      color-mix(in srgb, var(--crtr-color-accent) 88%, var(--crtr-color-text))
+    );
+  }
+
+${focusRingStyle({ scope: 'options-comment-cancel' }, '[part="comment-cancel"]')}
+${focusRingStyle({ scope: 'options-comment-save' }, '[part="comment-save"]')}
   [part="freetext"] {
     display: grid;
-    gap: var(--crtr-space-1);
+    gap: var(--crtr-options-freetext-gap, var(--crtr-space-1));
   }
 
   [part="freetext-label"] {
-    color: var(--crtr-color-text-muted);
-    font-size: 0.85em;
+    color: var(--crtr-options-freetext-label-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-options-freetext-label-font-size, 0.875em);
   }
 
   [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);
+    padding: var(--crtr-options-unavailable-padding, var(--crtr-space-3));
+    color: var(--crtr-options-unavailable-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-options-unavailable-fill, var(--crtr-color-surface));
+    border: var(--crtr-options-unavailable-border-width, 1px)
+      var(--crtr-options-unavailable-border-style, solid)
+      var(--crtr-options-unavailable-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-options-unavailable-radius, var(--crtr-radius-medium));
   }
 
   [part="reason"] {
-    color: var(--crtr-color-text);
-    font-family: var(--crtr-font-mono);
+    color: var(--crtr-options-reason-text-color, var(--crtr-color-text));
+    font-family: var(--crtr-options-reason-font-family, var(--crtr-font-mono));
   }
 `;
+/** Ids are scoped to this element's shadow root, so one constant is unique everywhere. */
+const LABEL_ID = 'prompt-label';
 let groupCounter = 0;
 /**
  * Whether a key belongs to something being written in rather than to the list grammar.
@@ -284,6 +338,8 @@ function isTextEntry(target) {
     return target.type !== 'checkbox' && target.type !== 'radio';
 }
 class CrtrOptionsElement extends HTMLElement {
+    /** The host marks a resolved or canceled page `inert`; that is this element's read-only signal. */
+    static observedAttributes = ['inert'];
     #shadow;
     #config;
     #slotId;
@@ -317,12 +373,31 @@ class CrtrOptionsElement extends HTMLElement {
         this.#config = config;
         this.#order = config.options.map((option) => option.id);
         this.#hydrate(config);
+        // Registered whether or not the person ever selects anything: the pager reports every
+        // response-bearing slot at submit, and an empty selection is an answer the host validates
+        // and names, where an absent slot is only a map the host cannot read.
+        if (this.#slotId !== undefined)
+            registerSlotResponse(this, this.#slotId, () => this.#response());
         this.#render(config);
         this.#sync();
     }
     disconnectedCallback() {
         document.removeEventListener('pointerdown', this.#onDocumentPointerDown, true);
     }
+    attributeChangedCallback() {
+        if (this.isConnected)
+            this.#syncReadOnly();
+    }
+    /** Read-only is repainted after every build, because a rebuild replaces the controls. */
+    #syncReadOnly() {
+        const readOnly = isReadOnly(this);
+        applyReadOnly(this.#shadow, readOnly);
+        // A page can go read-only while a box is open — the host sets `inert` on a ticket that
+        // resolves under it. A box that can no longer save is closed rather than left there
+        // taking words nothing will keep.
+        if (readOnly && this.#commentingId !== undefined)
+            this.#closeComment(false);
+    }
     /**
      * Seed local state from the answer the host is already holding, so a reopened page shows
      * what it would submit. Ids that no longer name an option are dropped, and single-select
@@ -362,10 +437,24 @@ class CrtrOptionsElement extends HTMLElement {
         style.textContent = STYLE;
         const container = document.createElement('div');
         container.part.add('container');
+        const labelled = config.label !== undefined && config.label !== '';
+        if (labelled) {
+            const label = document.createElement('p');
+            label.part.add('label');
+            label.id = LABEL_ID;
+            label.textContent = config.label ?? '';
+            container.append(label);
+        }
         const list = document.createElement('div');
         list.part.add('list');
+        // A labelled multi-select is a named group of checkboxes; single-select is already one
+        // control, so the radiogroup role it always carries takes the name instead.
         if (config.mode === 'single')
             list.setAttribute('role', 'radiogroup');
+        else if (labelled)
+            list.setAttribute('role', 'group');
+        if (labelled)
+            list.setAttribute('aria-labelledby', LABEL_ID);
         groupCounter += 1;
         const group = `crtr-options-${groupCounter}`;
         for (const option of config.options)
@@ -404,6 +493,24 @@ class CrtrOptionsElement extends HTMLElement {
             text.append(description);
         }
         label.append(control, text);
+        // No comment affordance where a comment has nowhere to go — see `canRecordComments`.
+        const parts = canRecordComments(this.#slotId) ? this.#buildComment(option) : undefined;
+        root.append(label);
+        if (parts !== undefined)
+            root.append(parts.trigger, parts.popover);
+        root.addEventListener('mouseenter', () => this.#setActive(option.id));
+        root.addEventListener('mouseleave', () => this.#clearActive(option.id));
+        this.#rows.set(option.id, {
+            id: option.id,
+            label: option.label,
+            root,
+            control,
+            ...(parts === undefined ? {} : { comment: parts }),
+        });
+        return root;
+    }
+    /** The trigger and its box, built together because they are only ever used together. */
+    #buildComment(option) {
         const comment = document.createElement('button');
         comment.part.add('comment');
         comment.type = 'button';
@@ -454,11 +561,7 @@ class CrtrOptionsElement extends HTMLElement {
         buttons.append(cancel, save);
         actions.append(hint, buttons);
         popover.append(subject, input, actions);
-        root.append(label, comment, popover);
-        root.addEventListener('mouseenter', () => this.#setActive(option.id));
-        root.addEventListener('mouseleave', () => this.#clearActive(option.id));
-        this.#rows.set(option.id, { id: option.id, label: option.label, root, control, comment, popover, input, hint });
-        return root;
+        return { trigger: comment, popover, input, hint };
     }
     #renderFreetext(config) {
         const wrapper = document.createElement('label');
@@ -522,7 +625,7 @@ class CrtrOptionsElement extends HTMLElement {
         this.#sync();
     }
     #toggle(optionId, selected) {
-        if (this.#config === undefined)
+        if (this.#config === undefined || isReadOnly(this))
             return;
         if (this.#config.mode === 'single') {
             this.#selected = [optionId];
@@ -548,19 +651,21 @@ class CrtrOptionsElement extends HTMLElement {
     #onDocumentPointerDown = (event) => {
         if (this.#commentingId === undefined)
             return;
-        const row = this.#rows.get(this.#commentingId);
-        if (row === undefined)
+        const parts = this.#rows.get(this.#commentingId)?.comment;
+        if (parts === undefined)
             return;
         const path = event.composedPath();
-        if (path.includes(row.popover) || path.includes(row.comment))
+        if (path.includes(parts.popover) || path.includes(parts.trigger))
             return;
         // No focus restore: the press is on its way somewhere else, and pulling focus back to
         // the trigger would fight it.
         this.#closeComment(false);
     };
     #openComment(optionId) {
-        const row = this.#rows.get(optionId);
-        if (row === undefined)
+        const parts = this.#rows.get(optionId)?.comment;
+        // A box opens only where its comment can land: never on a read-only page, whose textareas
+        // are already `readOnly`, so it would take focus and refuse every keystroke.
+        if (parts === undefined || isReadOnly(this))
             return;
         if (this.#commentingId === undefined) {
             document.addEventListener('pointerdown', this.#onDocumentPointerDown, true);
@@ -568,27 +673,27 @@ class CrtrOptionsElement extends HTMLElement {
         this.#commentingId = optionId;
         this.#activeId = optionId;
         // Seeded from the saved comment every time it opens.
-        row.input.value = findComment(this.#comments, anchorFor(optionId))?.text ?? '';
+        parts.input.value = findComment(this.#comments, anchorFor(optionId))?.text ?? '';
         this.#sync();
-        row.input.focus();
+        parts.input.focus();
     }
     #closeComment(restoreFocus = true) {
         if (this.#commentingId === undefined)
             return;
-        const row = this.#rows.get(this.#commentingId);
+        const parts = this.#rows.get(this.#commentingId)?.comment;
         this.#commentingId = undefined;
         document.removeEventListener('pointerdown', this.#onDocumentPointerDown, true);
         this.#sync();
         if (restoreFocus)
-            row?.comment.focus();
+            parts?.trigger.focus();
     }
     #commitComment(optionId) {
-        const row = this.#rows.get(optionId);
-        if (row === undefined)
+        const parts = this.#rows.get(optionId)?.comment;
+        if (parts === undefined || isReadOnly(this))
             return;
         // Clearing the box deletes the comment — `setComment` treats empty text as removal, so
         // there is no separate destructive control.
-        this.#comments = setComment(this.#comments, anchorFor(optionId), row.input.value);
+        this.#comments = setComment(this.#comments, anchorFor(optionId), parts.input.value);
         this.#closeComment();
         this.#emit();
     }
@@ -599,20 +704,22 @@ class CrtrOptionsElement extends HTMLElement {
             row.control.checked = selected;
             row.root.dataset.selected = String(selected);
             row.root.dataset.active = String(this.#activeId === row.id);
+            const parts = row.comment;
+            if (parts === undefined)
+                continue;
             const comment = findComment(this.#comments, anchorFor(row.id));
-            row.comment.dataset.state = comment === undefined ? 'empty' : 'commented';
-            row.comment.innerHTML = comment === undefined ? BUBBLE_PLUS : BUBBLE_TEXT;
-            row.comment.setAttribute('aria-label', comment === undefined ? `Comment on ${row.label}` : `Edit comment on ${row.label}`);
+            parts.trigger.dataset.state = comment === undefined ? 'empty' : 'commented';
+            parts.trigger.innerHTML = comment === undefined ? BUBBLE_PLUS : BUBBLE_TEXT;
+            parts.trigger.setAttribute('aria-label', comment === undefined ? `Comment on ${row.label}` : `Edit comment on ${row.label}`);
             const open = this.#commentingId === row.id;
-            row.comment.setAttribute('aria-expanded', String(open));
-            row.popover.hidden = !open;
-            row.hint.textContent = comment === undefined ? '\u2318\u21b5 to save' : 'empty to delete';
+            parts.trigger.setAttribute('aria-expanded', String(open));
+            parts.popover.hidden = !open;
+            parts.hint.textContent = comment === undefined ? '\u2318\u21b5 to save' : 'empty to delete';
         }
+        this.#syncReadOnly();
     }
-    /** The complete current response, on every user change — never a delta. */
-    #emit() {
-        if (this.#slotId === undefined)
-            return;
+    /** The complete current response — what every change hands `respond()`. */
+    #response() {
         const response = {
             selectedOptionIds: [...this.#selected],
             comments: this.#comments.map((comment) => ({ ...comment })),
@@ -620,7 +727,13 @@ class CrtrOptionsElement extends HTMLElement {
         if (this.#config?.allowFreetext === true && this.#freetext !== undefined) {
             response.freetext = this.#freetext;
         }
-        respond(this.#slotId, response);
+        return response;
+    }
+    /** The complete current response, on every user change — never a delta. */
+    #emit() {
+        if (this.#slotId === undefined)
+            return;
+        respond(this.#slotId, this.#response());
     }
 }
 function anchorFor(optionId) {

package/dist/pages/elements/pages.d.ts

@@ -20,5 +20,11 @@
  *
  * A single-step page renders no pager chrome at all — no progress, no forward/back — just
  * the submit affordance, because there is nothing to flip.
+ *
+ * Both elements paint entirely through `--crtr-page-*` component tokens — the same element
+ * scope `bundle.css` gives `crtr-pages` and `crtr-page`, because a person looking at the page
+ * sees one thing. The pager's buttons are the bundle's ordinary buttons, so their focus ring
+ * and their motion chain through the shared `--crtr-control-*` family before falling back to
+ * the kit default.
  */
 export {};