@north-light/crouter 0.3.196 → 0.3.198

package/dist/pages/comments.d.ts

@@ -12,6 +12,19 @@
  * `respond()`.
  */
 import type { Comment, CommentAnchor } from './types.js';
+/**
+ * Whether this slot can record a comment at all.
+ *
+ * Comments ride the slot's response: `respond(slotId, …)` is the only way one leaves the
+ * frame, so a slot with no `slot-id` has nowhere to put it. That is a real page shape — a
+ * table with no row or column selection is display-only and the renderer gives it no id
+ * (`isResponseBearingSlot`), and a hand-authored html page can omit the attribute on any
+ * element — and it used to render the full comment affordance anyway: the trigger opened, the
+ * box took the words, Save closed it, and the comment was dropped on the floor. An affordance
+ * that cannot keep what it accepts should not be drawn, so the elements build no comment UI
+ * when this is false.
+ */
+export declare function canRecordComments(slotId: string | undefined): boolean;
 /** A stable string identity for an anchor, used to find and key comments. */
 export declare function anchorKey(anchor: CommentAnchor): string;
 /** The comment on `anchor`, if the user has left one. */
@@ -39,5 +52,21 @@ export declare function adoptComments(value: unknown): Comment[];
  * legible in a response the human reads.
  */
 export declare function newCommentId(): string;
+/**
+ * The quoted region as a composer shows it back: what you selected, at a glance, in about two
+ * lines however much you selected.
+ *
+ * A range anchor carries the selection verbatim, and a selection is as long as the person made
+ * it — a whole paragraph is a normal thing to comment on. Rendered verbatim that quote pushed
+ * the box and the save button off the bottom of the popover, so the thing being written could
+ * not be seen while writing it. The preview keeps both ends — the beginning says what was
+ * selected and the end says where it stopped, which is exactly what a person checks — and
+ * elides the middle. Line breaks collapse, because a preview is one run of text and a quote
+ * that keeps its paragraph shape is the blowout again in another form.
+ *
+ * The comment itself is still anchored to the full range: this is what is shown, never what is
+ * stored.
+ */
+export declare function quotePreview(quote: string): string;
 /** A short, human label for what a comment is attached to. */
 export declare function anchorLabel(anchor: CommentAnchor): string;

package/dist/pages/comments.js

@@ -11,6 +11,21 @@
  * list in local state, replace it with the returned one, and hand the whole response to
  * `respond()`.
  */
+/**
+ * Whether this slot can record a comment at all.
+ *
+ * Comments ride the slot's response: `respond(slotId, …)` is the only way one leaves the
+ * frame, so a slot with no `slot-id` has nowhere to put it. That is a real page shape — a
+ * table with no row or column selection is display-only and the renderer gives it no id
+ * (`isResponseBearingSlot`), and a hand-authored html page can omit the attribute on any
+ * element — and it used to render the full comment affordance anyway: the trigger opened, the
+ * box took the words, Save closed it, and the comment was dropped on the floor. An affordance
+ * that cannot keep what it accepts should not be drawn, so the elements build no comment UI
+ * when this is false.
+ */
+export function canRecordComments(slotId) {
+    return slotId !== undefined;
+}
 /** A stable string identity for an anchor, used to find and key comments. */
 export function anchorKey(anchor) {
     switch (anchor.kind) {
@@ -112,6 +127,42 @@ export function newCommentId() {
     counter += 1;
     return `c${counter}`;
 }
+/** How much of a quoted region a preview shows before it is worth eliding. Two lines in a
+ *  20em popover at the quote's own size, which is the whole budget the composer can spare. */
+const QUOTE_BUDGET = 84;
+const QUOTE_HEAD = 48;
+const QUOTE_TAIL = 30;
+/** Drop a trailing part-word, so a head cut lands between words rather than inside one. */
+function headWords(text) {
+    const cut = text.lastIndexOf(' ');
+    return (cut > 0 && cut >= text.length - 12 ? text.slice(0, cut) : text).trimEnd();
+}
+/** Drop a leading part-word, the same way, at the other end of the elision. */
+function tailWords(text) {
+    const cut = text.indexOf(' ');
+    return (cut !== -1 && cut < 12 ? text.slice(cut + 1) : text).trimStart();
+}
+/**
+ * The quoted region as a composer shows it back: what you selected, at a glance, in about two
+ * lines however much you selected.
+ *
+ * A range anchor carries the selection verbatim, and a selection is as long as the person made
+ * it — a whole paragraph is a normal thing to comment on. Rendered verbatim that quote pushed
+ * the box and the save button off the bottom of the popover, so the thing being written could
+ * not be seen while writing it. The preview keeps both ends — the beginning says what was
+ * selected and the end says where it stopped, which is exactly what a person checks — and
+ * elides the middle. Line breaks collapse, because a preview is one run of text and a quote
+ * that keeps its paragraph shape is the blowout again in another form.
+ *
+ * The comment itself is still anchored to the full range: this is what is shown, never what is
+ * stored.
+ */
+export function quotePreview(quote) {
+    const flat = quote.replace(/\s+/gu, ' ').trim();
+    if (flat.length <= QUOTE_BUDGET)
+        return flat;
+    return `${headWords(flat.slice(0, QUOTE_HEAD))} \u2026 ${tailWords(flat.slice(-QUOTE_TAIL))}`;
+}
 /** A short, human label for what a comment is attached to. */
 export function anchorLabel(anchor) {
     switch (anchor.kind) {

package/dist/pages/controls.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The shared control paint: the one focus treatment every focusable thing in the page bundle
+ * wears, the one radio and checkbox recipe every element draws with, and the one writing-box
+ * recipe every textarea and text field wears.
+ *
+ * All three exist for the same reason — a control that differs element to element reads as
+ * foreign, and the host's kit draws each of them exactly one way.
+ *
+ * A page frame is a bare document rendered beside a host's own UI, and the host's controls are
+ * drawn ones — a bordered box with an accent fill and a tick, a ring with a dot. A native UA
+ * control cannot be made to look like that: `accent-color` only tints the UA's own drawing, so
+ * the frame's radios kept the platform's shape, size, checked treatment and focus ring while
+ * everything around them wore the host's. They read as foreign, because they were.
+ *
+ * So the controls are drawn here instead, out of the same `--crtr-*` tokens the rest of the
+ * bundle spends. They stay real `<input type="radio">` / `<input type="checkbox">` elements —
+ * the label association, the arrow-key behaviour of a native radio group, Space, the `change`
+ * event and every `target.type` check keep working exactly as before. Only the paint moved.
+ *
+ * The mark is a `::before` on the input, which is why `display: inline-grid` is on the control:
+ * an `appearance: none` input has no UA-drawn glyph left and no content of its own, so the grid
+ * exists purely to centre the one pseudo-element in it.
+ *
+ * ## This module is the `--crtr-control-*` family
+ *
+ * Every value these three recipes paint with is read through a named component token, so a
+ * host restyles the bundle's controls without touching crtr — custom properties inherit
+ * through shadow roots, which is the whole mechanism. The short version of the layering rule
+ * is:
+ *
+ *     var(--crtr-<element>-<knob>, var(--crtr-control-<part>-<knob>, <kit default>))
+ *
+ * The element layer is the optional `{ scope }` first argument each function takes. A call
+ * that passes `{ scope: 'text-editor' }` gets `--crtr-text-editor-padding` laid over the
+ * family's `--crtr-control-writing-padding`; a call that passes no scope reads the family
+ * token alone. Every default stays inline here — the family tokens are deliberately NOT
+ * declared in `bundle.css`, because an undeclared token is what lets the fallback chain carry
+ * the kit default all the way down.
+ *
+ * The innermost fallback of each chain is a theme token read with a CSS system colour behind
+ * it, because these rules live in the element's own shadow root and therefore apply even when
+ * `bundle.css` — where the whole `--crtr-*` theme map is declared — never loaded. That way an
+ * unstyled frame still shows a control with a visible box, a visible mark and a visible focus
+ * ring rather than a blank square.
+ */
+/**
+ * The element-level token layer a call site lays over the shared family.
+ *
+ * `scope` is the `--crtr-`-suffix an element claims for these particular controls, so
+ * `{ scope: 'text-editor' }` mints `--crtr-text-editor-<knob>`. It is the element's name plus
+ * the anatomy part it is styling, and it is the element's to choose: the family part name
+ * (`writing`, `box`, `radio`, `checkbox`, `focus`, `mark`) describes the shared recipe, while
+ * the scope describes the thing on the page a person is looking at.
+ */
+export interface TokenScope {
+    readonly scope: string;
+}
+/**
+ * The focus treatment bound to the selectors of things that are neither a writing box nor a
+ * drawn control — every button in the bundle. `writingBoxStyle` and `controlStyle` already
+ * carry it, so they do not need this.
+ *
+ * The ring is outset paint, so a button close enough to the edge of the page frame to have the
+ * ring clipped needs a gutter around it, the way `<crtr-text>`'s writing surface does.
+ */
+export declare function focusRingStyle(...selectors: readonly string[]): string;
+export declare function focusRingStyle(scope: TokenScope, ...selectors: readonly string[]): string;
+/**
+ * The one writing-box recipe — every `<textarea>` and single-line `<input type="text">` the
+ * bundle puts in front of a person paints with this.
+ *
+ * It is the host kit's own field, translated token for token from
+ * `apps/gateway/components/ui/textarea.tsx` — which the kit's `input.tsx` matches declaration
+ * for declaration, because in the kit a one-line field and a writing surface are the same
+ * control at two heights: text at the body size and body weight (`font: inherit`, which against
+ * `--crtr-font-size` is the kit's `md:text-sm`), `px-3 py-2`, a hairline border at the small
+ * radius, the faintest fill against the page, `shadow-xs`, and the shared focus ring.
+ *
+ * Before this existed each element wrote its own comment box, and they had drifted: three
+ * different paddings, two different fills, and an `outline` focus ring where the kit uses a
+ * border-plus-ring. A comment box has to read as the same thing wherever a person meets it, so
+ * the recipe is shared rather than repeated — and `<crtr-text>`'s one-line field and its
+ * textarea are one call with two selectors, so they cannot drift apart again.
+ *
+ * Sizing that belongs to one box — how tall it starts, whether it may be dragged taller — stays
+ * in the element's own rule, which follows this block and wins at equal specificity.
+ */
+export declare function writingBoxStyle(...selectors: readonly string[]): string;
+export declare function writingBoxStyle(scope: TokenScope, ...selectors: readonly string[]): string;
+/**
+ * The recipe, bound to the `part` selectors an element gives its controls.
+ *
+ * The result is interpolated into that element's shadow-root stylesheet. Anything an element
+ * owns rather than shares — where the control sits against its label — stays in the element's
+ * own rule, which follows this block and therefore wins at equal specificity.
+ */
+export declare function controlStyle(...selectors: readonly string[]): string;
+export declare function controlStyle(scope: TokenScope, ...selectors: readonly string[]): string;

package/dist/pages/controls.js

@@ -0,0 +1,261 @@
+/**
+ * The shared control paint: the one focus treatment every focusable thing in the page bundle
+ * wears, the one radio and checkbox recipe every element draws with, and the one writing-box
+ * recipe every textarea and text field wears.
+ *
+ * All three exist for the same reason — a control that differs element to element reads as
+ * foreign, and the host's kit draws each of them exactly one way.
+ *
+ * A page frame is a bare document rendered beside a host's own UI, and the host's controls are
+ * drawn ones — a bordered box with an accent fill and a tick, a ring with a dot. A native UA
+ * control cannot be made to look like that: `accent-color` only tints the UA's own drawing, so
+ * the frame's radios kept the platform's shape, size, checked treatment and focus ring while
+ * everything around them wore the host's. They read as foreign, because they were.
+ *
+ * So the controls are drawn here instead, out of the same `--crtr-*` tokens the rest of the
+ * bundle spends. They stay real `<input type="radio">` / `<input type="checkbox">` elements —
+ * the label association, the arrow-key behaviour of a native radio group, Space, the `change`
+ * event and every `target.type` check keep working exactly as before. Only the paint moved.
+ *
+ * The mark is a `::before` on the input, which is why `display: inline-grid` is on the control:
+ * an `appearance: none` input has no UA-drawn glyph left and no content of its own, so the grid
+ * exists purely to centre the one pseudo-element in it.
+ *
+ * ## This module is the `--crtr-control-*` family
+ *
+ * Every value these three recipes paint with is read through a named component token, so a
+ * host restyles the bundle's controls without touching crtr — custom properties inherit
+ * through shadow roots, which is the whole mechanism. The short version of the layering rule
+ * is:
+ *
+ *     var(--crtr-<element>-<knob>, var(--crtr-control-<part>-<knob>, <kit default>))
+ *
+ * The element layer is the optional `{ scope }` first argument each function takes. A call
+ * that passes `{ scope: 'text-editor' }` gets `--crtr-text-editor-padding` laid over the
+ * family's `--crtr-control-writing-padding`; a call that passes no scope reads the family
+ * token alone. Every default stays inline here — the family tokens are deliberately NOT
+ * declared in `bundle.css`, because an undeclared token is what lets the fallback chain carry
+ * the kit default all the way down.
+ *
+ * The innermost fallback of each chain is a theme token read with a CSS system colour behind
+ * it, because these rules live in the element's own shadow root and therefore apply even when
+ * `bundle.css` — where the whole `--crtr-*` theme map is declared — never loaded. That way an
+ * unstyled frame still shows a control with a visible box, a visible mark and a visible focus
+ * ring rather than a blank square.
+ */
+/** Lucide's `check`, as a mask. Colour comes from the pseudo-element, so the paint is opaque
+ *  black and the geometry — including the 2-unit round-capped stroke — is the kit's own. */
+const CHECK_MASK = "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'/%3E%3C/svg%3E\")";
+/** Lucide's `minus` — the glyph a partial selection wears, so "some" cannot read as "none". */
+const MINUS_MASK = "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12h14'/%3E%3C/svg%3E\")";
+/** The selector list, each entry suffixed and joined the way a CSS rule wants it. */
+function each(selectors, suffix = '') {
+    return selectors.map((selector) => `${selector}${suffix}`).join(',\n  ');
+}
+/**
+ * Splits the optional leading scope off a variadic selector list.
+ *
+ * The scope is a leading argument rather than a trailing options object because the selector
+ * list is variadic and reads as one thought; an element file's call stays a single line either
+ * way.
+ */
+function split(args) {
+    const first = args[0];
+    if (typeof first === 'object')
+        return [first.scope, args.slice(1)];
+    return [null, args];
+}
+/**
+ * A chain builder for one family part: given a knob name and the kit's current value for it,
+ * it returns the `var()` chain a declaration is written through.
+ *
+ * `elementPart` is what the element layer prefixes the knob with. It is empty only for the one
+ * family per call that owns the plain knob names, and set on every other family sharing that
+ * call — two families that both spend `fill` or `mark-color` would otherwise collapse onto a
+ * single element token, and overriding the box's fill would repaint the mark inside it.
+ */
+function chain(scope, familyPrefix, elementPart) {
+    return (name, fallback) => {
+        const family = `var(--crtr-${familyPrefix}-${name}, ${fallback})`;
+        if (scope === null)
+            return family;
+        const element = elementPart === '' ? `${scope}-${name}` : `${scope}-${elementPart}-${name}`;
+        return `var(--crtr-${element}, ${family})`;
+    };
+}
+/**
+ * The one focus treatment, and the only one the bundle draws.
+ *
+ * It is the kit's, verbatim: the border takes the focus colour and a soft ring sits just
+ * outside it — `focus-visible:border-aurora-cyan/60 focus-visible:ring-aurora-cyan/25
+ * focus-visible:ring-[3px]`, which `apps/gateway/components/ui/{input,textarea,button,
+ * checkbox}.tsx` all carry identically. A UA `outline` is never it; every element in this
+ * bundle wrote its own `outline: 2px solid` before this existed, so a focused button and the
+ * focused field under it drew two visibly different rings.
+ *
+ * It is one declaration block rather than a ring plus a resting elevation, so a missing shadow
+ * token can never take the ring down with it.
+ *
+ * The ring width is a flat three pixels on every focusable thing the kit draws — a button, a
+ * field, a checkbox — so its default is in `rem` rather than `em`: an `em` ring would come out
+ * a different thickness on a button set at `0.875em` than on the field beside it, which is the
+ * drift this module exists to remove.
+ *
+ * A focusable region that is not a control — a scrolling thread, a table body, a prose block —
+ * is deliberately NOT in this family. Those run the full width of the frame the host gives the
+ * page, so a ring painted outside them is clipped and draws three sides of a rectangle; they
+ * keep an inset `outline` and say so at the rule.
+ */
+function focusRing(scope) {
+    const focus = chain(scope, 'control-focus', 'focus');
+    const width = focus('ring-width', '0.1875rem');
+    const color = focus('ring-color', 'color-mix(in srgb, var(--crtr-color-focus, CanvasText) 25%, transparent)');
+    return `
+    outline: ${focus('outline', 'none')};
+    border-color: ${focus('border-color', 'color-mix(in srgb, var(--crtr-color-focus, CanvasText) 60%, transparent)')};
+    box-shadow: ${focus('ring', `0 0 0 ${width}\n      ${color}`)};`;
+}
+export function focusRingStyle(...args) {
+    const [scope, selectors] = split(args);
+    return `
+  ${each(selectors, ':focus-visible')} {${focusRing(scope)}
+  }
+`;
+}
+export function writingBoxStyle(...args) {
+    const [scope, selectors] = split(args);
+    const box = chain(scope, 'control-writing', '');
+    const any = chain(scope, 'control', '');
+    const motion = any('transition', '120ms ease');
+    return `
+  ${each(selectors)} {
+    /* Block, not the UA's inline-block: a full-width field on its own line would otherwise sit
+       in a line box and carry a descender's worth of dead space under it. */
+    display: block;
+    box-sizing: border-box;
+    width: 100%;
+    padding: ${box('padding', 'var(--crtr-space-2) var(--crtr-space-3)')};
+    color: ${box('text-color', 'var(--crtr-color-text, CanvasText)')};
+    font: ${box('font', 'inherit')};
+    line-height: ${box('line-height', 'var(--crtr-line-height, 1.5)')};
+    background: ${box('fill', 'color-mix(in srgb, var(--crtr-color-text, CanvasText) 2%, var(--crtr-color-background, Canvas))')};
+    border: ${box('border-width', '1px')} ${box('border-style', 'solid')} ${box('border-color', 'var(--crtr-color-border, CanvasText)')};
+    border-radius: ${box('radius', 'var(--crtr-radius-small)')};
+    box-shadow: ${box('shadow', 'var(--crtr-shadow)')};
+    transition: border-color ${motion}, box-shadow ${motion};
+  }
+
+  ${each(selectors, '::placeholder')} {
+    color: ${box('placeholder-color', 'var(--crtr-color-text-muted, GrayText)')};
+  }
+
+  ${each(selectors, ':focus-visible')} {${focusRing(scope)}
+  }
+
+  /* A page that can no longer take an answer keeps its text selectable and copyable, and drops
+     the affordances that say it could still be rewritten. */
+  ${each(selectors, ':read-only')} {
+    background: ${box('readonly-fill', 'var(--crtr-color-surface, Canvas)')};
+    box-shadow: ${box('readonly-shadow', 'none')};
+    resize: none;
+  }
+`;
+}
+export function controlStyle(...args) {
+    const [scope, selectors] = split(args);
+    const box = chain(scope, 'control-box', '');
+    const mark = chain(scope, 'control-mark', 'mark');
+    const radio = chain(scope, 'control-radio', 'radio');
+    const check = chain(scope, 'control-checkbox', 'checkbox');
+    const any = chain(scope, 'control', '');
+    const motion = any('transition', '120ms ease');
+    return `
+  ${each(selectors)} {
+    /* The box tracks the host's font token like every other size in the bundle. The kit's
+       control is 16px against 14px text; these ratios are that pair, kept proportional. */
+    --control-box: ${box('size', '1.125em')};
+    appearance: none;
+    -webkit-appearance: none;
+    box-sizing: border-box;
+    display: inline-grid;
+    place-content: center;
+    flex: none;
+    width: var(--control-box);
+    height: var(--control-box);
+    margin: 0;
+    padding: 0;
+    vertical-align: middle;
+    /* Transparent rather than the background token, so an empty control on a selected row
+       carries that row's tint the way the kit's does. */
+    background: ${box('fill', 'transparent')};
+    border: ${box('border-width', '1px')} ${box('border-style', 'solid')} ${box('border-color', 'var(--crtr-color-border, CanvasText)')};
+    border-radius: ${box('radius', 'calc(var(--control-box) * 0.25)')};
+    box-shadow: ${box('shadow', 'var(--crtr-shadow)')};
+    cursor: pointer;
+    transition: background-color ${motion}, border-color ${motion}, box-shadow ${motion};
+  }
+
+  ${each(selectors, '[type="radio"]')} {
+    border-radius: ${radio('radius', '50%')};
+  }
+
+  /* The mark. It is always present and always centred; selecting scales it in, which is the
+     state change the kit animates too. */
+  ${each(selectors, '::before')} {
+    content: "";
+    background: ${mark('fill', 'currentColor')};
+    transform: scale(0);
+    transition: transform ${motion};
+  }
+
+  ${each(selectors, ':checked::before')},
+  ${each(selectors, ':indeterminate::before')} {
+    transform: scale(1);
+  }
+
+  /* A radio keeps its own surface and marks itself with a dot in the accent; a checkbox fills
+     with the accent and carries the tick in the accent's contrast colour. */
+  ${each(selectors, '[type="radio"]::before')} {
+    width: ${radio('mark-size', 'calc(var(--control-box) * 0.5)')};
+    height: ${radio('mark-size', 'calc(var(--control-box) * 0.5)')};
+    border-radius: ${radio('mark-radius', '50%')};
+    color: ${radio('mark-color', 'var(--crtr-color-accent, CanvasText)')};
+  }
+
+  ${each(selectors, '[type="radio"]:checked')} {
+    border-color: ${radio('checked-border-color', 'var(--crtr-color-accent, CanvasText)')};
+  }
+
+  ${each(selectors, '[type="checkbox"]::before')} {
+    width: ${check('mark-size', 'calc(var(--control-box) * 0.875)')};
+    height: ${check('mark-size', 'calc(var(--control-box) * 0.875)')};
+    color: ${check('mark-color', 'var(--crtr-color-accent-contrast, Canvas)')};
+    -webkit-mask: ${check('mark-image', CHECK_MASK)} ${check('mark-layout', 'center / contain no-repeat')};
+    mask: ${check('mark-image', CHECK_MASK)} ${check('mark-layout', 'center / contain no-repeat')};
+  }
+
+  ${each(selectors, '[type="checkbox"]:indeterminate::before')} {
+    -webkit-mask-image: ${check('indeterminate-mark-image', MINUS_MASK)};
+    mask-image: ${check('indeterminate-mark-image', MINUS_MASK)};
+  }
+
+  ${each(selectors, '[type="checkbox"]:checked')},
+  ${each(selectors, '[type="checkbox"]:indeterminate')} {
+    background: ${check('checked-fill', 'var(--crtr-color-accent, CanvasText)')};
+    border-color: ${check('checked-border-color', 'var(--crtr-color-accent, CanvasText)')};
+  }
+
+  /* The bundle's one focus treatment. The box scales with the font token, but the ring does
+     not: the kit's is a flat three pixels on a checkbox and on the field beside it alike. */
+  ${each(selectors, '[type]:focus-visible')} {${focusRing(scope)}
+  }
+
+  /* A page that can no longer take an answer keeps its selection legible — the mark stays the
+     accent, only dimmed — and drops every affordance that says it could still be changed. */
+  ${each(selectors, ':disabled')} {
+    opacity: ${any('disabled-opacity', '0.5')};
+    box-shadow: ${any('disabled-shadow', 'none')};
+    cursor: default;
+  }
+`;
+}

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

@@ -9,9 +9,20 @@
  * (`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.
  */
 export {};