@north-light/crouter 0.3.196 → 0.3.198

package/dist/pages/elements/cards.js

@@ -9,14 +9,28 @@
  * (`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.
+ * Data arrives inline as `cards`. The element never touches the network: a page source file
+ * is read and embedded once at submit, before this element renders.
+ *
+ * ## Every value here is a `--crtr-cards-*` token
+ *
+ * The card surface, its heading, its tag, the comment affordance and the three notice states
+ * are all painted through `var(--crtr-cards-<part>-<knob>, <kit default>)`, so a host restyles
+ * this element by setting properties on the document root — custom properties inherit into
+ * shadow roots, which is the whole mechanism. The shared control, writing-box and focus
+ * recipes carry their own element layer through the `{ scope }` each call passes, so the
+ * card's radio reads `--crtr-cards-control-*` over the family's `--crtr-control-box-*`.
+ *
+ * Defaults stay inline at the rule that spends them and no `--crtr-cards-*` token is ever
+ * declared: an unset token is what carries the kit default down the chain, which is why an
+ * unstyled page renders exactly as it did before any of this existed.
  */
-import { adoptComments, findComment, setComment } from '../comments.js';
-import { artifactData, respond, savedIds, savedResponse } from '../host.js';
+import { adoptComments, canRecordComments, findComment, setComment } 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 STYLE = `
   :host {
@@ -29,13 +43,23 @@ const STYLE = `
   [part~="container"] {
     display: flex;
     flex-direction: column;
-    gap: var(--crtr-space-1);
+    gap: var(--crtr-cards-container-gap, var(--crtr-space-1));
   }
 
+  /* The question reads as the agent's own prose above its control, matching the table's
+     caption rather than shouting over the cards it introduces. The container's gap is a
+     hairline, so the breathing room under the prompt is the prompt's own. */
+  [part~="label"] {
+    margin: 0 0 var(--crtr-cards-label-gap, var(--crtr-space-2));
+    color: var(--crtr-cards-label-text-color, var(--crtr-color-text-muted));
+  }
+
+  /* The column count is anatomy rather than paint — a container query cannot read a custom
+     property, so the breakpoint below stays a literal. */
   [part~="grid"] {
     display: grid;
     grid-template-columns: minmax(0, 1fr);
-    gap: var(--crtr-space-3);
+    gap: var(--crtr-cards-grid-gap, var(--crtr-space-3));
   }
 
   @container (min-width: 30rem) {
@@ -51,35 +75,44 @@ const STYLE = `
   [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;
+    gap: var(--crtr-cards-card-gap, var(--crtr-space-2));
+    padding: var(--crtr-cards-card-padding, var(--crtr-space-3));
+    color: var(--crtr-cards-card-text-color, var(--crtr-color-text));
+    background: var(--crtr-cards-card-fill, var(--crtr-color-surface));
+    border: var(--crtr-cards-card-border-width, 1px)
+      var(--crtr-cards-card-border-style, solid)
+      var(--crtr-cards-card-border-color, color-mix(in srgb, var(--crtr-color-border) 60%, transparent));
+    border-radius: var(--crtr-cards-card-radius, var(--crtr-radius-medium));
+    /* The whole card is the target, not just its heading — see the click handler. */
+    cursor: pointer;
+    transition: background-color var(--crtr-cards-card-transition, 120ms ease),
+      border-color var(--crtr-cards-card-transition, 120ms ease);
+  }
+
+  [part~="card"]:has([part~="control"]:disabled) {
+    cursor: default;
   }
 
   [part~="card"]:hover,
   [part~="card"][part~="active"] {
-    background: var(--crtr-color-surface-hover);
-    border-color: var(--crtr-color-border);
+    background: var(--crtr-cards-card-hover-fill, var(--crtr-color-surface-hover));
+    border-color: var(--crtr-cards-card-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);
+    background: var(--crtr-cards-card-selected-fill, color-mix(in srgb, var(--crtr-color-accent) 10%, transparent));
+    border-color: var(--crtr-cards-card-selected-border-color, color-mix(in srgb, var(--crtr-color-accent) 45%, transparent));
   }
 
   [part~="card"][part~="selected"]:hover,
   [part~="card"][part~="selected"][part~="active"] {
-    background: color-mix(in srgb, var(--crtr-color-accent) 12%, transparent);
+    background: var(--crtr-cards-card-selected-hover-fill, color-mix(in srgb, var(--crtr-color-accent) 14%, transparent));
   }
 
   [part~="card-header"] {
     display: flex;
     align-items: flex-start;
-    gap: var(--crtr-space-2);
+    gap: var(--crtr-cards-card-header-gap, var(--crtr-space-2));
   }
 
   /* The label carries the click target, so the whole heading toggles the native control
@@ -88,62 +121,61 @@ const STYLE = `
     display: flex;
     flex: 1;
     align-items: flex-start;
-    gap: var(--crtr-space-2);
+    gap: var(--crtr-cards-card-label-gap, var(--crtr-space-2));
     min-width: 0;
-    font: inherit;
+    font: var(--crtr-cards-card-label-font, inherit);
     cursor: pointer;
   }
 
-  [part~="control"] {
-    flex: none;
-    margin: 0;
-    margin-top: 0.2em;
-    accent-color: var(--crtr-color-accent);
-  }
+  ${controlStyle({ scope: 'cards-control' }, '[part~="control"]')}
 
-  [part~="control"]:focus-visible {
-    outline: 2px solid var(--crtr-color-focus);
-    outline-offset: 2px;
+  /* Centred on the card's title line, which sets its own tighter line-height. The box size
+     is read back through --control-box, the local the recipe above resolves it into, so a
+     host that resizes the control keeps it centred without touching this offset. */
+  [part~="control"] {
+    margin-top: var(--crtr-cards-control-offset, calc((1.35em - var(--control-box)) / 2));
   }
 
   [part~="card-heading"] {
     display: grid;
     flex: 1;
-    gap: calc(var(--crtr-space-1) / 2);
+    gap: var(--crtr-cards-card-heading-gap, calc(var(--crtr-space-1) / 2));
     min-width: 0;
   }
 
   [part~="card-title"] {
-    font-weight: 500;
-    line-height: 1.35;
+    font-weight: var(--crtr-cards-card-title-font-weight, 500);
+    line-height: var(--crtr-cards-card-title-line-height, 1.35);
   }
 
   [part~="card-subtitle"] {
-    color: var(--crtr-color-text-muted);
-    font-size: calc(var(--crtr-font-size) * 0.85);
+    color: var(--crtr-cards-card-subtitle-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-cards-card-subtitle-font-size, 0.875em);
   }
 
   [part~="card-body"] {
-    margin: 0;
-    color: var(--crtr-color-text-muted);
-    font-size: calc(var(--crtr-font-size) * 0.85);
-    line-height: 1.6;
+    margin: var(--crtr-cards-card-body-margin, 0);
+    color: var(--crtr-cards-card-body-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-cards-card-body-font-size, 0.875em);
+    line-height: var(--crtr-cards-card-body-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);
+    padding: var(--crtr-cards-tag-padding, 0 var(--crtr-space-1));
+    color: var(--crtr-cards-tag-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-cards-tag-font-size, 0.75em);
+    line-height: var(--crtr-cards-tag-line-height, 1.7);
+    border: var(--crtr-cards-tag-border-width, 1px)
+      var(--crtr-cards-tag-border-style, solid)
+      var(--crtr-cards-tag-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-cards-tag-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);
+    color: var(--crtr-cards-tag-selected-text-color, var(--crtr-color-accent));
+    background: var(--crtr-cards-tag-selected-fill, color-mix(in srgb, var(--crtr-color-accent) 10%, transparent));
+    border-color: var(--crtr-cards-tag-selected-border-color, color-mix(in srgb, var(--crtr-color-accent) 45%, transparent));
   }
 
   /* The affordance is quiet until you reach for it, and stays visible once a note lives
@@ -153,139 +185,185 @@ const STYLE = `
     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);
+    /* One knob: the affordance is a square, so its width and height are the same value. */
+    width: var(--crtr-cards-comment-button-size, 1.5em);
+    height: var(--crtr-cards-comment-button-size, 1.5em);
+    padding: var(--crtr-cards-comment-button-padding, 0);
+    color: var(--crtr-cards-comment-button-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-cards-comment-button-fill, none);
+    border: var(--crtr-cards-comment-button-border-width, 1px)
+      var(--crtr-cards-comment-button-border-style, solid)
+      var(--crtr-cards-comment-button-border-color, transparent);
+    border-radius: var(--crtr-cards-comment-button-radius, var(--crtr-radius-small));
     cursor: pointer;
-    opacity: 0;
-    transition: opacity 120ms ease, color 120ms ease, background-color 120ms ease;
+    opacity: var(--crtr-cards-comment-button-resting-opacity, 0);
+    transition: opacity var(--crtr-cards-comment-button-transition, var(--crtr-control-transition, 120ms ease)),
+      color var(--crtr-cards-comment-button-transition, var(--crtr-control-transition, 120ms ease)),
+      background-color var(--crtr-cards-comment-button-transition, var(--crtr-control-transition, 120ms ease));
   }
 
   [part~="comment-button"] svg {
-    width: calc(var(--crtr-font-size) * 0.95);
-    height: calc(var(--crtr-font-size) * 0.95);
+    width: var(--crtr-cards-comment-button-icon-size, 0.875em);
+    height: var(--crtr-cards-comment-button-icon-size, 0.875em);
+    fill: var(--crtr-cards-comment-button-icon-fill, none);
+    stroke: var(--crtr-cards-comment-button-icon-stroke-color, currentColor);
+    stroke-width: var(--crtr-cards-comment-button-icon-stroke-width, 2);
+    stroke-linecap: var(--crtr-cards-comment-button-icon-line-cap, round);
+    stroke-linejoin: var(--crtr-cards-comment-button-icon-line-join, round);
     /* 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);
+    color: var(--crtr-cards-comment-button-hover-text-color, var(--crtr-color-text));
+    background: var(--crtr-cards-comment-button-hover-fill, var(--crtr-color-surface-hover));
   }
 
   [part~="comment-button"][part~="has-comment"] {
-    color: var(--crtr-color-accent);
+    color: var(--crtr-cards-comment-button-noted-text-color, var(--crtr-color-accent));
   }
 
+${focusRingStyle({ scope: 'cards-comment-button' }, '[part~="comment-button"]')}
   [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;
+    opacity: var(--crtr-cards-comment-button-revealed-opacity, 1);
   }
 
   [part~="comment-editor"] {
     display: grid;
-    gap: var(--crtr-space-2);
+    gap: var(--crtr-cards-comment-editor-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);
+    padding: var(--crtr-cards-comment-editor-padding, var(--crtr-space-2));
+    text-align: var(--crtr-cards-comment-editor-text-align, left);
+    background: var(--crtr-cards-comment-editor-fill, var(--crtr-color-background));
+    border: var(--crtr-cards-comment-editor-border-width, 1px)
+      var(--crtr-cards-comment-editor-border-style, solid)
+      var(--crtr-cards-comment-editor-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-cards-comment-editor-radius, var(--crtr-radius-small));
     cursor: auto;
   }
 
-  [part~="comment-subject"],
+  /* The editor's own prose, in the page's voice — not a caps-mono field label shouting a
+     card id at someone who just clicked that card. */
+  [part~="comment-subject"] {
+    color: var(--crtr-cards-comment-subject-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-cards-comment-subject-font-size, 0.875em);
+  }
+
   [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;
+    color: var(--crtr-cards-comment-hint-text-color, var(--crtr-color-text-muted));
+    font-size: var(--crtr-cards-comment-hint-font-size, 0.875em);
   }
 
+${writingBoxStyle({ scope: 'cards-comment-input' }, '[part~="comment-input"]')}
   [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);
+    min-height: var(--crtr-cards-comment-input-min-height, 4.5em);
     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);
+    gap: var(--crtr-cards-comment-actions-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;
+    gap: var(--crtr-cards-comment-buttons-gap, var(--crtr-space-1));
   }
 
   [part~="comment-cancel"] {
-    color: var(--crtr-color-text-muted);
-    background: none;
-    border: 1px solid transparent;
+    padding: var(--crtr-cards-comment-cancel-padding, var(--crtr-space-1) var(--crtr-space-2));
+    color: var(--crtr-cards-comment-cancel-text-color, var(--crtr-color-text-muted));
+    font: var(--crtr-cards-comment-cancel-font, inherit);
+    font-size: var(--crtr-cards-comment-cancel-font-size, 0.875em);
+    background: var(--crtr-cards-comment-cancel-fill, none);
+    border: var(--crtr-cards-comment-cancel-border-width, 1px)
+      var(--crtr-cards-comment-cancel-border-style, solid)
+      var(--crtr-cards-comment-cancel-border-color, transparent);
+    border-radius: var(--crtr-cards-comment-cancel-radius, var(--crtr-radius-small));
+    cursor: pointer;
+    transition: color var(--crtr-cards-comment-cancel-transition, var(--crtr-control-transition, 120ms ease)),
+      background-color var(--crtr-cards-comment-cancel-transition, var(--crtr-control-transition, 120ms ease)),
+      border-color var(--crtr-cards-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-cards-comment-cancel-hover-text-color, var(--crtr-color-text));
+    background: var(--crtr-cards-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);
+    padding: var(--crtr-cards-comment-save-padding, var(--crtr-space-1) var(--crtr-space-2));
+    color: var(--crtr-cards-comment-save-text-color, var(--crtr-color-accent-contrast));
+    font: var(--crtr-cards-comment-save-font, inherit);
+    font-size: var(--crtr-cards-comment-save-font-size, 0.875em);
+    background: var(--crtr-cards-comment-save-fill, var(--crtr-color-accent));
+    border: var(--crtr-cards-comment-save-border-width, 1px)
+      var(--crtr-cards-comment-save-border-style, solid)
+      var(--crtr-cards-comment-save-border-color, var(--crtr-color-accent));
+    border-radius: var(--crtr-cards-comment-save-radius, var(--crtr-radius-small));
+    cursor: pointer;
+    transition: color var(--crtr-cards-comment-save-transition, var(--crtr-control-transition, 120ms ease)),
+      background-color var(--crtr-cards-comment-save-transition, var(--crtr-control-transition, 120ms ease)),
+      border-color var(--crtr-cards-comment-save-transition, var(--crtr-control-transition, 120ms ease));
+  }
+
+  /* Mixing 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-cards-comment-save-hover-fill, color-mix(in srgb, var(--crtr-color-accent) 88%, var(--crtr-color-text)));
+    border-color: var(--crtr-cards-comment-save-hover-border-color, color-mix(in srgb, var(--crtr-color-accent) 88%, var(--crtr-color-text)));
+  }
+
+${focusRingStyle({ scope: 'cards-comment-cancel' }, '[part~="comment-cancel"]')}
+${focusRingStyle({ scope: 'cards-comment-save' }, '[part~="comment-save"]')}
+  /* These sit in the flow of the page rather than above it, so they carry no elevation —
+     a shadow in this bundle means floating (a popover, an editor). Each state keeps its own
+     scope even though their kit defaults match: one scope never names two different parts. */
+  [part~="unavailable"] {
+    padding: var(--crtr-cards-unavailable-padding, var(--crtr-space-3));
+    color: var(--crtr-cards-unavailable-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-cards-unavailable-fill, var(--crtr-color-surface));
+    border: var(--crtr-cards-unavailable-border-width, 1px)
+      var(--crtr-cards-unavailable-border-style, solid)
+      var(--crtr-cards-unavailable-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-cards-unavailable-radius, var(--crtr-radius-medium));
+  }
+
+  [part~="empty"] {
+    padding: var(--crtr-cards-empty-padding, var(--crtr-space-3));
+    color: var(--crtr-cards-empty-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-cards-empty-fill, var(--crtr-color-surface));
+    border: var(--crtr-cards-empty-border-width, 1px)
+      var(--crtr-cards-empty-border-style, solid)
+      var(--crtr-cards-empty-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-cards-empty-radius, var(--crtr-radius-medium));
   }
 
-  [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);
+    padding: var(--crtr-cards-loading-padding, var(--crtr-space-3));
+    color: var(--crtr-cards-loading-text-color, var(--crtr-color-text-muted));
+    background: var(--crtr-cards-loading-fill, var(--crtr-color-surface));
+    border: var(--crtr-cards-loading-border-width, 1px)
+      var(--crtr-cards-loading-border-style, solid)
+      var(--crtr-cards-loading-border-color, var(--crtr-color-border));
+    border-radius: var(--crtr-cards-loading-radius, var(--crtr-radius-medium));
   }
 
   [part~="kind"] {
-    color: var(--crtr-color-text);
-    font-family: var(--crtr-font-mono);
+    color: var(--crtr-cards-kind-text-color, var(--crtr-color-text));
+    font-family: var(--crtr-cards-kind-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);
+    margin-top: var(--crtr-cards-reason-gap, var(--crtr-space-1));
+    font-size: var(--crtr-cards-reason-font-size, 0.875em);
   }
 `;
 /**
@@ -333,35 +411,36 @@ function normalizeCards(raw) {
     }
     return cards;
 }
-const CONFIG_KEYS = new Set(['cards', 'source', 'mode', 'columns']);
+const CONFIG_KEYS = new Set(['label', 'cards', 'mode', 'columns']);
+/** Ids are scoped to this element's shadow root, so one constant is unique everywhere. */
+const LABEL_ID = 'prompt-label';
 /** 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 label = raw.label;
+    if (label !== undefined && typeof label !== 'string')
+        return { status: 'invalid', reason: 'label must be a string' };
     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 } };
+    return {
+        status: 'ok',
+        config: { label: label, cards, mode, columns },
+    };
 }
 /**
  * Typing in the comment box is ordinary writing — the list grammar keeps out of it. A card's
@@ -381,11 +460,6 @@ const SVG_NS = 'http://www.w3.org/2000/svg';
 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');
@@ -409,12 +483,26 @@ function commentIcon(hasComment) {
     }
     return svg;
 }
+/** The prompt above the grid, or nothing when the agent asked its question elsewhere. */
+function buildLabel(text) {
+    if (text === undefined || text === '')
+        return null;
+    const label = document.createElement('p');
+    label.part.add('label');
+    label.id = LABEL_ID;
+    label.textContent = text;
+    return label;
+}
 /** Radio groups are keyed by name, so every element on a page needs its own. */
 let groupCounter = 0;
 class CrtrCardsElement extends HTMLElement {
+    /** The host marks a resolved or canceled page `inert`; that is this element's read-only signal. */
+    static observedAttributes = ['inert'];
     #container = document.createElement('div');
     #group;
     #config = null;
+    /** The rendered prompt, kept across repaints because every render replaces the container. */
+    #label = null;
     #cards = [];
     #slotId;
     // Response state. Authoritative for rendering; `respond()` only asks the host to save it.
@@ -424,8 +512,6 @@ class CrtrCardsElement extends HTMLElement {
     #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;
@@ -438,8 +524,6 @@ class CrtrCardsElement extends HTMLElement {
         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);
@@ -452,37 +536,26 @@ class CrtrCardsElement extends HTMLElement {
         }
         this.#config = normalized.config;
         this.#slotId = readSlotId(this);
-        const source = normalized.config.source;
-        if (source === undefined) {
-            this.#cards = normalized.config.cards ?? [];
-            this.#hydrate();
-            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;
+        // Registered before render: the pager reports every response-bearing slot
+        // at submit, whether or not the person ever selected a card.
+        if (this.#slotId !== undefined)
+            registerSlotResponse(this, this.#slotId, () => this.#response());
+        this.#label = buildLabel(normalized.config.label);
+        this.#cards = normalized.config.cards ?? [];
         this.#hydrate();
         this.#build();
     }
+    attributeChangedCallback() {
+        if (this.isConnected)
+            this.#syncReadOnly();
+    }
+    /** Repainted after every build, because a rebuild replaces the controls. */
+    #syncReadOnly() {
+        const readOnly = isReadOnly(this);
+        applyReadOnly(this.#container, readOnly);
+        if (readOnly && this.#open !== null)
+            this.#closeEditor(false);
+    }
     /**
      * Seed local state from the answer the host is already holding, so a reopened page shows
      * the cards that were picked. `#build` is what drops ids the current data no longer has,
@@ -513,14 +586,21 @@ class CrtrCardsElement extends HTMLElement {
         detail.part.add('reason');
         detail.textContent = reason;
         box.append('Component unavailable: ', kind, detail);
-        this.#container.replaceChildren(box);
+        this.#setContent(box);
     }
     #renderStatus(part, text) {
         const box = document.createElement('div');
         box.part.add(part);
         box.setAttribute('role', 'status');
         box.textContent = text;
-        this.#container.replaceChildren(box);
+        this.#setContent(box);
+    }
+    /** Every repaint replaces the container's children, so the prompt is re-laid each time. */
+    #setContent(content) {
+        if (this.#label === null)
+            this.#container.replaceChildren(content);
+        else
+            this.#container.replaceChildren(this.#label, content);
     }
     /** Builds the grid once per data load; every later change repaints in place. */
     #build() {
@@ -543,8 +623,13 @@ class CrtrCardsElement extends HTMLElement {
         grid.part.add('grid');
         if (config.columns === 3)
             grid.dataset.columns = '3';
+        if (this.#label !== null) {
+            // A named group of choices: single-select is a radio group, multi a plain group.
+            grid.setAttribute('role', config.mode === 'single' ? 'radiogroup' : 'group');
+            grid.setAttribute('aria-labelledby', LABEL_ID);
+        }
         grid.append(...this.#cards.map((card) => this.#buildCard(card, config.mode, this.#group)));
-        this.#container.replaceChildren(grid);
+        this.#setContent(grid);
         this.#paint();
     }
     #buildCard(card, mode, group) {
@@ -576,16 +661,21 @@ class CrtrCardsElement extends HTMLElement {
             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);
-        });
+        let commentButton;
+        if (canRecordComments(this.#slotId)) {
+            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);
+        header.append(label);
+        if (commentButton !== undefined)
+            header.append(commentButton);
         root.append(header);
         if (card.body !== undefined && card.body !== '') {
             const body = document.createElement('p');
@@ -606,7 +696,28 @@ class CrtrCardsElement extends HTMLElement {
                 this.#setActive(null, false);
         });
         root.addEventListener('focusin', () => this.#setActive(card.id, false));
-        this.#nodes.set(card.id, { root, control, commentButton, tag });
+        // The whole card is the choice, not just its heading: a click on the body, the tag, or
+        // the padding around them picks the card. A click that went through the label is left
+        // alone — the native control has already toggled from it, and toggling again here would
+        // undo the user's own click. The comment button and the editor stop propagation, so a
+        // press on either never reaches this. A press that ends a text selection is someone
+        // reading the card, not choosing it.
+        root.addEventListener('click', (event) => {
+            if (control.disabled)
+                return;
+            if (event.composedPath().includes(label))
+                return;
+            if (document.getSelection()?.isCollapsed === false)
+                return;
+            this.#setActive(card.id, false);
+            this.#toggle(card.id, !this.#selected.includes(card.id));
+        });
+        this.#nodes.set(card.id, {
+            root,
+            control,
+            ...(commentButton === undefined ? {} : { commentButton }),
+            tag,
+        });
         return root;
     }
     /** Repaints selection, activity and comment presence without rebuilding the grid. */
@@ -624,8 +735,10 @@ class CrtrCardsElement extends HTMLElement {
             // 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);
+            if (node.commentButton !== undefined)
+                this.#paintCommentButton(node.commentButton, comment, card.title);
         }
+        this.#syncReadOnly();
     }
     #paintCommentButton(button, comment, target) {
         const has = comment !== undefined;
@@ -651,7 +764,7 @@ class CrtrCardsElement extends HTMLElement {
             this.#nodes.get(id)?.control.focus();
     }
     #toggle(cardId, selected) {
-        if (this.#config === null)
+        if (this.#config === null || isReadOnly(this))
             return;
         if (this.#config.mode === 'single') {
             // Radio semantics: choosing a card replaces the answer, and re-choosing keeps it.
@@ -695,7 +808,7 @@ class CrtrCardsElement extends HTMLElement {
             event.preventDefault();
             const card = this.#cards.find((entry) => entry.id === currentId);
             const node = this.#nodes.get(currentId);
-            if (card === undefined || node === undefined)
+            if (card === undefined || node?.commentButton === undefined)
                 return;
             this.#setActive(currentId, false);
             this.#toggleEditor({ kind: 'card', cardId: card.id }, card.title, node.root, null);
@@ -706,7 +819,7 @@ class CrtrCardsElement extends HTMLElement {
     // ----------------------------------------------------------------- comments
     /** Opens the editor for `anchor`, or closes it when it is already the open one. */
     #toggleEditor(anchor, target, mount, after) {
-        if (mount === null)
+        if (mount === null || !canRecordComments(this.#slotId) || isReadOnly(this))
             return;
         const openAnchor = this.#open?.anchor;
         const sameAnchor = openAnchor !== undefined &&
@@ -781,7 +894,7 @@ class CrtrCardsElement extends HTMLElement {
     }
     #commitComment(text) {
         const open = this.#open;
-        if (open === null)
+        if (open === null || isReadOnly(this))
             return;
         this.#comments = setComment(this.#comments, open.anchor, text);
         this.#closeEditor(true);