@agent-ui-kit/components 0.0.3

package/dist/controls/_base/range-element.d.ts

@@ -0,0 +1,120 @@
+import { UIFormElement, type ReactiveProps } from '../../dom/index.js';
+import type { FormValue } from '../../dom/index.js';
+declare const rangeProps: {
+    min: {
+        reflect: true;
+        type: import("../../index.js").PropType<number | null>;
+        default: number | null;
+        attribute?: string | false;
+    };
+    max: {
+        reflect: true;
+        type: import("../../index.js").PropType<number | null>;
+        default: number | null;
+        attribute?: string | false;
+    };
+    step: {
+        reflect: true;
+        type: import("../../index.js").PropType<number | null>;
+        default: number | null;
+        attribute?: string | false;
+    };
+    value: {
+        reflect: true;
+        type: import("../../index.js").PropType<number | null>;
+        default: number | null;
+        attribute?: string | false;
+    };
+    size: {
+        reflect: true;
+        type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+        default: "sm" | "md" | "lg";
+        attribute?: string | false;
+    };
+    name: {
+        reflect: true;
+        type: import("../../index.js").PropType<string>;
+        default: string;
+        attribute?: string | false;
+    };
+    disabled: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+    required: {
+        reflect: true;
+        type: import("../../index.js").PropType<boolean>;
+        default: boolean;
+        attribute?: string | false;
+    };
+};
+export interface UIRangeElement extends ReactiveProps<typeof rangeProps> {
+}
+export declare class UIRangeElement extends UIFormElement {
+    #private;
+    static props: {
+        min: {
+            reflect: true;
+            type: import("../../index.js").PropType<number | null>;
+            default: number | null;
+            attribute?: string | false;
+        };
+        max: {
+            reflect: true;
+            type: import("../../index.js").PropType<number | null>;
+            default: number | null;
+            attribute?: string | false;
+        };
+        step: {
+            reflect: true;
+            type: import("../../index.js").PropType<number | null>;
+            default: number | null;
+            attribute?: string | false;
+        };
+        value: {
+            reflect: true;
+            type: import("../../index.js").PropType<number | null>;
+            default: number | null;
+            attribute?: string | false;
+        };
+        size: {
+            reflect: true;
+            type: import("../../index.js").PropType<"sm" | "md" | "lg">;
+            default: "sm" | "md" | "lg";
+            attribute?: string | false;
+        };
+        name: {
+            reflect: true;
+            type: import("../../index.js").PropType<string>;
+            default: string;
+            attribute?: string | false;
+        };
+        disabled: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+        required: {
+            reflect: true;
+            type: import("../../index.js").PropType<boolean>;
+            default: boolean;
+            attribute?: string | false;
+        };
+    };
+    /**
+     * LLD-C1: the normalised value serialised as the form-submitted string.
+     * The base normalises before serialising so the form entry always reflects the clamped+snapped value.
+     */
+    protected formValue(): FormValue;
+    /**
+     * LLD-C2: hook for `internals.ariaValueText`. Override to return a locale-formatted value string
+     * (e.g. `"$12.00"`). The base returns `String(value)`. Named `valueText` (not `ariaValueText`) to
+     * avoid shadowing the `ARIAMixin.ariaValueText` DOM property.
+     */
+    protected valueText(value: number): string;
+    protected connected(): void;
+}
+export {};

package/dist/controls/_base/range-element.js

@@ -0,0 +1,158 @@
+// range-element.ts — UIRangeElement, the shared base for the Range class (ui-slider · ui-slider-multi).
+// range-element.lld.md.
+//
+// Owns: the numeric value model with clamping/snapping (LLD-C1), the ARIA slider semantics
+// (LLD-C2), keyboard step handling (LLD-C3), and the geometry seam — the `--value-pct` custom
+// property (LLD-C5). The value-drag controller (LLD-C4) is wired by the leaf subclass from its
+// own `connected()`.
+//
+// Layer: controls/_base/ — imports dom only.
+// Inward-only ✓ (controls ← traits ← dom ← reactive).
+import { UIFormElement, prop } from "../../dom/index.js";
+const rangeProps = {
+    ...UIFormElement.formProps,
+    // LLD-C1: numeric range params. All reflected for attribute-driven construction.
+    // prop.number returns PropConfig<number | null>; defaults (0/100/1) mean values are never null in practice.
+    min: { ...prop.number(0), reflect: true },
+    max: { ...prop.number(100), reflect: true },
+    step: { ...prop.number(1), reflect: true },
+    value: { ...prop.number(0), reflect: true },
+    // ADR-0042 clause-2: the shared widget-box size axis (the track/thumb ride --md-sys-compact-{size}); all
+    // Range controls inherit it — typed here, not per-leaf (the same lesson as UIIndicatorElement's size).
+    size: { ...prop.enum(['sm', 'md', 'lg'], 'md'), reflect: true },
+};
+export class UIRangeElement extends UIFormElement {
+    static props = rangeProps;
+    // LLD-C3: the value at focus — committed baseline for `change` event emission on blur.
+    // Reset at connect so a reconnect without an intervening focus cannot fire a stale `change`.
+    #committed = null;
+    /**
+     * LLD-C1: normalise a raw value against the current min/max/step.
+     * - min > max → zero-length range; pin to min.
+     * - step ≤ 0 → continuous; clamp only, no snap.
+     * - step not dividing (max−min) → last reachable step is ≤ max (snap-down);
+     *   max itself is always reachable exactly (the platform `<input type=range>` End rule).
+     */
+    #normalize(raw) {
+        const min = this.min ?? 0;
+        const max = this.max ?? 100;
+        const step = this.step ?? 1;
+        if (min > max)
+            return min;
+        const clamped = Math.max(min, Math.min(max, raw));
+        if (step <= 0)
+            return clamped;
+        // max is always reachable exactly — End → max, and clamping to max lands here too.
+        if (clamped === max)
+            return max;
+        const steps = Math.round((clamped - min) / step);
+        const snapped = min + steps * step;
+        // snap-down if snapped overshoots max
+        return snapped > max ? min + (steps - 1) * step : snapped;
+    }
+    /** LLD-C5: percentage position of value along [min, max] for the `--value-pct` geometry seam. */
+    #valuePct(value) {
+        const min = this.min ?? 0;
+        const max = this.max ?? 100;
+        if (min >= max)
+            return 0;
+        return ((value - min) / (max - min)) * 100;
+    }
+    /**
+     * LLD-C1: the normalised value serialised as the form-submitted string.
+     * The base normalises before serialising so the form entry always reflects the clamped+snapped value.
+     */
+    formValue() {
+        return String(this.#normalize(this.value ?? 0));
+    }
+    /**
+     * LLD-C2: hook for `internals.ariaValueText`. Override to return a locale-formatted value string
+     * (e.g. `"$12.00"`). The base returns `String(value)`. Named `valueText` (not `ariaValueText`) to
+     * avoid shadowing the `ARIAMixin.ariaValueText` DOM property.
+     */
+    valueText(value) {
+        return String(value);
+    }
+    connected() {
+        // Reset the committed baseline so a reconnect without a focus cannot fire a stale `change`.
+        this.#committed = null;
+        // LLD-C2: role is structural, not data-driven; set once here rather than inside an effect.
+        this.internals.role = 'slider';
+        // LLD-C1: normaliser effect — keeps value clamped + snapped on every change to value/min/max/step.
+        // The kernel's Object.is cutoff means no signal update + no re-run when the value is already normal.
+        this.effect(() => {
+            const raw = this.value ?? 0;
+            const normalized = this.#normalize(raw);
+            if (!Object.is(normalized, raw))
+                this.value = normalized;
+        });
+        // LLD-C2: ARIA effect — publishes ariaValueNow/Min/Max/Text reactively, tracking all four props.
+        this.effect(() => {
+            const value = this.#normalize(this.value ?? 0);
+            this.internals.ariaValueNow = String(value);
+            this.internals.ariaValueMin = String(this.min ?? 0);
+            this.internals.ariaValueMax = String(this.max ?? 100);
+            this.internals.ariaValueText = this.valueText(value);
+        });
+        // LLD-C5: geometry seam — `--value-pct` on the host style so the subclass CSS can paint the fill
+        // and position the thumb without needing to import any JS from this base.
+        this.effect(() => {
+            const value = this.#normalize(this.value ?? 0);
+            this.style.setProperty('--value-pct', String(this.#valuePct(value)));
+        });
+        // LLD-C3: keyboard step — Arrow ±step, PageUp/Down ±largeStep (10×step), Home/End → min/max.
+        // Disabled host is inert (effectiveDisabled covers own + fieldset/form disabled).
+        // Each live step emits `input`; `change` is emitted on blur when value moved (below).
+        this.listen(this, 'keydown', (event) => {
+            if (this.effectiveDisabled())
+                return;
+            const e = event;
+            const min = this.min ?? 0;
+            const max = this.max ?? 100;
+            const step = this.step ?? 1;
+            const largeStep = step * 10;
+            const current = this.#normalize(this.value ?? 0);
+            let next = null;
+            switch (e.key) {
+                case 'ArrowRight':
+                case 'ArrowUp':
+                    next = this.#normalize(current + step);
+                    break;
+                case 'ArrowLeft':
+                case 'ArrowDown':
+                    next = this.#normalize(current - step);
+                    break;
+                case 'PageUp':
+                    next = this.#normalize(current + largeStep);
+                    break;
+                case 'PageDown':
+                    next = this.#normalize(current - largeStep);
+                    break;
+                case 'Home':
+                    next = min;
+                    break;
+                case 'End':
+                    next = max; // End reaches max exactly (platform rule, matches the normaliser's max fast-path)
+                    break;
+                default:
+                    return;
+            }
+            e.preventDefault();
+            if (!Object.is(next, current)) {
+                this.value = next;
+                this.emit('input');
+            }
+        });
+        // LLD-C3: change on commit — track value at focus; emit `change` on blur when value has moved.
+        this.listen(this, 'focus', () => {
+            this.#committed = this.#normalize(this.value ?? 0);
+        });
+        this.listen(this, 'blur', () => {
+            const current = this.#normalize(this.value ?? 0);
+            if (this.#committed !== null && !Object.is(current, this.#committed)) {
+                this.emit('change');
+            }
+            this.#committed = null;
+        });
+    }
+}

package/dist/controls/_surface/container-box.css

@@ -0,0 +1,301 @@
+/* container-box.css — the shared container BOX-MODEL (margin inset + the sticky-region pattern). The second
+ * shared surface layer (after `_surface/container.css` which owns the elevation/brightness PAINT); this one
+ * owns the SPACING + region rhythm every container/panel adopts by marking itself `[data-box]`. Imported by
+ * component-styles.css right after container.css, before any element sheet.
+ *
+ * THE MODEL (ruled with Kim, flow-root + margin-collapse — REVISED 2026-07-04, inset regions):
+ *   • L1 `[data-box]` establishes a BFC (`display: flow-root`) and holds NO inner padding — the children's
+ *     margins provide the inset. A BFC means adjacent children's block margins COLLAPSE to one inset (a
+ *     uniform 6px between siblings) AND the edge margins are preserved (6px from the box edge) — not doubled.
+ *   • L2 direct children get `margin: var(--ui-box-inset)` (6px) by default. A child OVERRIDES its own margin
+ *     to go full-bleed (`margin: 0`) — `hr` and an explicit `[data-full-bleed]` opt-out still do.
+ *   • `[padded]` = a full-bleed child (margin 0) whose CONTENT is inset (`padding: var(--ui-box-inset)`) — e.g.
+ *     a header/row that spans the box edge-to-edge but keeps its text off the edge.
+ *   • Region pattern (REVISED 2026-07-04): `header`/`footer`/content (`main`/`[data-region]`) are now INSET,
+ *     not full-bleed — they carry the SAME `--ui-box-inset` margin as every other child (the BFC collapsing
+ *     above keeps the gutter uniform at 6px, frame↔region and region↔region alike). `header`/`footer` stay
+ *     `position: sticky` + `background: inherit` (the box surface) so scrolled content never shows through —
+ *     trivially overridden (a child that sets its own background wins). `hr` is still a full-bleed divider.
+ *     `main`/content is the scroll region between them (it may itself be another container, or a list).
+ *   • Z-DEPTH SCOPE (ADR-0052): `[data-box]` is also its own stacking context (`isolation: isolate` — the one
+ *     purpose-built property: no containing block, no paint side effects). Every descendant z-index (the sticky
+ *     brackets' `z-index: 1` below, a panel's internal chrome) resolves INSIDE the box and can never fight a
+ *     sibling container or the page — no global z ladder can exist. Overlays are unaffected: popover/dialog
+ *     surfaces ride the native TOP LAYER (ADR-0043/0045), which is immune to stacking contexts by spec.
+ *   • EDGE-AWARE SCROLL FADE (the gutter-exposure fix, same revision): an inset sticky bracket's background no
+ *     longer reaches the frame edge, so scrolled content can peek through the thin gutter around it. The fix
+ *     lives on the CONTENT, not the bracket — `traits/scroll-fade.ts` toggles `data-fade-top`/`data-fade-bottom`
+ *     on the scroll viewport from its live scroll position, and the `[data-fade-top]`/`[data-fade-bottom]`
+ *     rules near the foot of this file mask only the edge that genuinely hides content (never a flat guess).
+ *
+ * Everything is specificity-0 (`:where()`), so an element's own `@scope` block cleanly overrides any of it.
+ * Opt-in only: an element is unaffected until it (or its control) marks the surface `[data-box]`.
+ *
+ * `--ui-box-inset` defaults to 0.375rem (6px at the 16px root) and is themeable per box. */
+
+:where([data-box]) {
+  --ui-box-inset: 0.375rem; /* 6px — the uniform inset/gap unit; a box may repoint it */
+  display: flow-root; /* BFC: child margins collapse to ONE inset between siblings + hold the edge inset */
+  isolation: isolate; /* the box is its own Z-DEPTH SCOPE (ADR-0052): descendant z-indexes (the sticky
+                         brackets below, panel-internal chrome) resolve inside THIS stacking context and
+                         cannot paint over a sibling container — layout BFC + paint scope, one opt-in */
+
+  /* ── Region padding system (header / footer / content wrappers) — ruled with Kim ──
+   * The named regions carry their OWN internal padding + gap, distinct from the inset margin above:
+   *   inline 12px · block 6px · gap 8px.
+   * A NESTED content steps its INLINE padding IN by one inset (6px) per level (12 → 6 → 6…, floored), so a
+   * content-inside-content stays concentric with its parent's ink: parent inline-pad 12 = child inset margin 6
+   * + child inline-pad 6. Block padding + gap stay constant at every level. */
+  --ui-box-pad-inline: 0.75rem; /* 12px — region inline padding */
+  --ui-box-pad-block: 0.375rem; /* 6px — region block padding */
+  --ui-box-gap: 0.5rem; /* 8px — gap between a region's own children */
+
+  /* Edge-aware scroll fade (below) — the depth of the mask band at a faded edge. Density-linked (like the
+     old per-component --ui-card-fade it replaces), NOT the rem-based region padding above (a decorative
+     affordance depth, not a layout spacing law). Any consumer may repoint it locally. The literal 1rem
+     fallback keeps this self-contained even where only this sheet is loaded (e.g. container-box.browser.test.ts,
+     which never imports the dimensional --md-sys-space-* ramp). */
+  --ui-box-fade: var(--md-sys-space-lg, 1rem);
+}
+
+/* Popover-carrier re-assertion (the s13 e2e finding, 2026-07-01): the unconditional `display: flow-root`
+ * above is AUTHOR-origin CSS, and author beats user-agent regardless of specificity — so on a box that is
+ * ALSO a `[popover]` (select/menu/combo-box's panels, ADR-0046), it silently defeats the UA's own
+ * `[popover]:not(:popover-open) { display: none }` hidden-until-shown rule. The bug class: a CLOSED panel
+ * kept participating in layout AND focus (rovingFocus's `tabindex=0` current option stayed real), so Tab
+ * landed inside a closed listbox instead of skipping to the next control. This rule re-asserts the UA
+ * semantics at specificity 0 (`:where`, same as everything else here) — an OPEN popover, or any non-popover
+ * box, keeps `flow-root` from the block above untouched; a component may still deliberately override. */
+:where([data-box][popover]:not(:popover-open)) {
+  display: none;
+}
+
+/* Dialog-carrier re-assertion (the SAME class of bug as the `[popover]` rule above, hit by ui-modal's
+ * `<dialog data-part="dialog" data-box>` part, 2026-07-07): the unconditional `display: flow-root` is
+ * author-origin CSS and defeats the UA's own `dialog:not([open]) { display: none }` rule (author always beats
+ * UA, at ANY specificity) — so a CLOSED dialog kept rendering. Worse than the popover case: the UA's default
+ * `dialog { position: absolute; inset: 0; margin: auto; … }` then CENTRED the still-visible box on the page,
+ * exactly as if `showModal()` had been called (no backdrop, no top layer, no focus trap — just an inert box
+ * sitting on top of the page content). Two such closed dialogs on one page render stacked directly on top of
+ * each other, dead centre. Re-assert the UA semantics at specificity 0; an OPEN dialog (native `[open]`
+ * reflects `showModal()`/`show()`) keeps flow-root from the block above untouched. */
+:where(dialog[data-box]:not([open])) {
+  display: none;
+}
+
+/* header / footer — the region padding + gap. A row of controls sits comfortably: inline 12 / block 6 with an
+   8px gap. `display: flex` makes the gap apply; the element's own @scope may override the direction/alignment.
+   REVISED 2026-07-04: header/footer are no longer full-bleed — they carry the SAME `--ui-box-inset` margin as
+   every other `[data-box]` child (the generic `> *` rule below), so a header/footer divider or background no
+   longer reaches the box edge; it floats inside the frame with a uniform 6px gutter, same as any other region. */
+:where([data-box]) > :where(header, footer, [data-region='header'], [data-region='footer']) {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-box-gap);
+  padding-inline: var(--ui-box-pad-inline);
+  padding-block: var(--ui-box-pad-block);
+}
+
+/* content — the region between the brackets: a column of stacked children with the 8px region gap. The INLINE
+   padding steps IN one inset per NESTING level so a content-inside-content stays concentric with its parent's
+   ink (parent 12 = child inset-margin 6 + child pad 6). Expressed as explicit descendant levels rather than a
+   self-referencing custom property (which CSS treats as a cycle → invalid): L1 12 · L2 6 · L3+ 6 (the block-pad
+   floor — L2 and the floor now coincide, since the inset and the block-pad token are both 6px). Three levels
+   covers real nesting; deeper content stays at the 6px floor. */
+:where([data-region='content'], main) {
+  display: block; /* NOT flex — overflow:auto scrolls a block, and a block child keeps its height (flex would
+                     shrink it and break a scroll viewport). The region gap comes from an adjacent-sibling margin. */
+  padding-inline: var(--ui-box-pad-inline); /* L1 = 12px */
+  padding-block: var(--ui-box-pad-block);
+}
+/* The 8px region rhythm between content children — a gap-without-flex adjacent-sibling margin (scroll-safe);
+   the first child takes no top margin (the block padding provides the inset). */
+:where([data-region='content'], main) > * + * {
+  margin-block-start: var(--ui-box-gap);
+}
+:where([data-region='content'], main) :where([data-region='content'], main) {
+  padding-inline: calc(var(--ui-box-pad-inline) - var(--ui-box-inset)); /* L2 = 6px (12 − 6) */
+}
+:where([data-region='content'], main) :where([data-region='content'], main) :where([data-region='content'], main) {
+  padding-inline: var(--ui-box-pad-block); /* L3+ floor = 6px */
+}
+
+/* Every direct child carries the uniform inset margin (→ 6px from the edges, 6px between siblings) — INCLUDING
+   the region wrappers below (REVISED 2026-07-04: they are no longer full-bleed). The BFC established on
+   `[data-box]` above collapses adjacent children's margins to ONE inset, so this single rule is what gives
+   every gutter (frame↔region, region↔region) the same uniform 6px, never doubled. */
+:where([data-box]) > * {
+  margin: var(--ui-box-inset);
+}
+
+/* Full-bleed children — span the box edge-to-edge. Only a genuine divider (`hr`) or an explicit opt-out
+   (`[data-full-bleed]`) still overrides to full-bleed; the region wrappers (header/content/footer/main/
+   [data-region]) NO LONGER appear here (REVISED 2026-07-04) — they keep the generic inset margin above, so a
+   region floats inside the frame instead of spanning it edge-to-edge. */
+:where([data-box]) > :where(hr, [data-full-bleed]) {
+  margin: 0;
+}
+
+/* `[padded]` — full-bleed box, content inset (margin 0 + inset padding). */
+:where([data-box]) > :where([padded]) {
+  margin: 0;
+  padding: var(--ui-box-inset);
+}
+
+/* Sticky regions — pinned to the box's scroll edges, inheriting the box surface so scrolled content does not
+   bleed through. `background: inherit` copies the parent's resolved background value (a header itself easily
+   overrides by declaring its own background).
+   REVISED 2026-07-04 (a cross-engine finding, both Chromium + WebKit): once a sticky box is actually STUCK, its
+   own margin is NOT honored as extra offset — the resting position is governed purely by the inset value, the
+   margin collapses to nothing (verified in container-box.browser.test.ts; this is NOT a bug in that test, it
+   is real platform behaviour). Since a region now carries a 6px margin at REST (the generic `> *` rule above),
+   an `inset-block-start: 0` would show the correct 6px gutter before scrolling and then SNAP flush (0px) the
+   moment it sticks — a jarring visual jump. The fix: the inset offset itself is `--ui-box-inset` (6px), not 0,
+   so the STUCK resting gap matches the AT-REST margin gap exactly, in both states. */
+:where([data-box]) > :where(header, [data-region='header']) {
+  position: sticky;
+  inset-block-start: var(--ui-box-inset);
+  background: inherit;
+  z-index: 1;
+}
+:where([data-box]) > :where(footer, [data-region='footer']) {
+  position: sticky;
+  inset-block-end: var(--ui-box-inset);
+  background: inherit;
+  z-index: 1;
+}
+
+/* Divider — a full-bleed hairline rule between regions. Zero block-size so it adds no row height beyond the
+   1px rule; the surrounding children's margins provide the breathing room. */
+:where([data-box]) > hr {
+  border: 0;
+  border-block-start: 1px solid var(--md-sys-color-neutral-outline-variant);
+  block-size: 0;
+  margin: 0;
+}
+
+/* forced-colors — the sticky regions must stay opaque as a system colour (a transparent sticky header would
+   let scrolled text show through). The divider maps to a system border. */
+@media (forced-colors: active) {
+  :where([data-box]) > :where(header, footer, [data-region='header'], [data-region='footer']) {
+    background: Canvas;
+  }
+  :where([data-box]) > hr {
+    border-block-start-color: CanvasText;
+  }
+}
+
+/* ── Edge-aware scroll fade ───────────────────────────────────────────────────────────────────────────────
+ * The gutter-exposure fix (the 2026-07-04 z-index + mask revision): once header/footer regions became INSET
+ * (above) rather than full-bleed, a sticky bracket's own `background: inherit` no longer reaches the frame
+ * edge — the thin gutter AROUND the bracket can show scrolled content peeking through. The z-index:1 the
+ * sticky regions already carry (isolated per-box via ADR-0052) fully masks content DIRECTLY under a bracket;
+ * this closes the remaining gap by having the SCROLLING CONTENT fade its own edges before they ever reach
+ * that gutter, so nothing hard shows there regardless.
+ *
+ * `traits/scroll-fade.ts` toggles `data-fade-top`/`data-fade-bottom` on the actual scroll VIEWPORT from its
+ * live scroll position — a flag is present ONLY when content is genuinely hidden past that edge, so a short /
+ * non-scrolling viewport (neither flag) is never faded and an at-an-edge viewport fades only the OTHER edge.
+ * The three combinations below are the whole matrix; no flags at all ⇒ no rule matches ⇒ mask-image stays
+ * `none` (the element's un-masked default). This is a GENERIC, cross-family rule (not scoped to `[data-box]`
+ * — ui-card is the scroll viewport in the box-model but is not itself a `[data-box]`) consumed identically by
+ * ui-card, the modal dialog, and the select/menu/combo-box panels; each opts in by wiring the trait, nothing
+ * more. The gradient recipe itself is the one card.css shipped first (alpha-based — `mask-mode` defaults to
+ * `alpha` for an image source, so ANY opaque colour reads as "visible"; `#000`/`transparent` here are mask
+ * channel values, not a theme paint). The -webkit- prefix is still required (no unprefixed mask-image on
+ * WebKit/Safari).
+ *
+ * PRESENCE-AWARE OFFSET (2026-07-04): the fade must adapt to a sticky header/footer. These sticky brackets DO
+ * keep `background: inherit` (+ `z-index: 1`, above) to occlude content directly beneath them — but the fade
+ * itself is carried by the GRADIENT, not by demanding an opaque bracket edge-to-edge: per Kim (2026-07-04) it
+ * is fine for a bit of the gradient to show THROUGH the bracket zone. So the fade RAMP simply reaches PAST a
+ * present bracket: content emerging under it fades out, while the ramp's transparent end still sits at the true
+ * viewport edge (where the bracket floats). `traits/scroll-fade.ts` publishes each edge's
+ * bracket band as `--ui-box-head` / `--ui-box-foot` — its rendered block-size + inset gutter, measured live
+ * (ResizeObserver), or 0px when that edge has NO bracket. Each ramp's OPAQUE end lands at
+ * `bracket-band + --ui-box-fade`, so a bracketed edge stays faded until content has fully cleared the bracket,
+ * and a bracketless edge (offset 0px) collapses to `--ui-box-fade` — the EXACT pre-offset mask. Absent the
+ * trait, the `, 0px` var-fallbacks reduce every stop back to that original recipe, so the rule is
+ * self-contained. (The precise how-much-through-the-bracket look is a fine-tune of these two knobs.)
+ *
+ * THE HOLD (added for ui-card-content's overlaid, backgroundless brackets — 2026-07-07): a bare
+ * `transparent 0 → opaque at band+fade` ramp lets content RAMP UP continuously across the bracket's own band —
+ * by the time content reaches the band's own far edge it can already be >50% visible, so a crisp bracket TEXT
+ * sitting over it still shows a partially-opaque scrolled line layered underneath (measured, card.browser.test.ts).
+ * `--ui-box-head-hold`/`--ui-box-foot-hold` (both default `0px`) insert an EXTRA same-colour stop immediately
+ * after each edge's `transparent`/`#000` anchor, at the hold depth — two coincident stops (identical position,
+ * identical colour) are a geometric NO-OP (nothing renders between them), so every consumer that never sets
+ * these (modal/select/menu/combo-box — opaque `background: inherit` brackets, unaffected by this at all) gets a
+ * RENDER-IDENTICAL mask — not string-identical: the fallback `var(…, 0px)` still serializes two extra
+ * coincident stops into their computed gradient, it is only the PAINT that is unchanged — proven by this
+ * file's own tests staying green. A consumer that DOES set the hold to its
+ * own bracket band (ui-card-content, card.css) instead holds fully transparent/opaque THROUGH the whole band —
+ * content is genuinely invisible behind bracket text — and the soft running fade lives entirely in the
+ * `--ui-box-fade`-deep strip just past the band, never inside it. */
+:where([data-fade-top][data-fade-bottom]) {
+  /* Both edges hidden: transparent at each viewport edge → opaque once content has cleared that edge's bracket
+     band + the fade depth. Both offsets 0px ⇒ the original symmetric transparent→#000→#000→transparent mask. */
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    transparent var(--ui-box-head-hold, 0px),
+    #000 calc(var(--ui-box-head, 0px) + var(--ui-box-fade, 1rem)),
+    #000 calc(100% - var(--ui-box-foot, 0px) - var(--ui-box-fade, 1rem)),
+    transparent calc(100% - var(--ui-box-foot-hold, 0px)),
+    transparent 100%
+  );
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    transparent var(--ui-box-head-hold, 0px),
+    #000 calc(var(--ui-box-head, 0px) + var(--ui-box-fade, 1rem)),
+    #000 calc(100% - var(--ui-box-foot, 0px) - var(--ui-box-fade, 1rem)),
+    transparent calc(100% - var(--ui-box-foot-hold, 0px)),
+    transparent 100%
+  );
+}
+:where([data-fade-top]):not([data-fade-bottom]) {
+  /* Only the top hides content: fade past a present header, opaque below. Header offset 0px ⇒ the original
+     transparent 0 → #000 --ui-box-fade top fade. */
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    transparent var(--ui-box-head-hold, 0px),
+    #000 calc(var(--ui-box-head, 0px) + var(--ui-box-fade, 1rem)),
+    #000 100%
+  );
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    transparent var(--ui-box-head-hold, 0px),
+    #000 calc(var(--ui-box-head, 0px) + var(--ui-box-fade, 1rem)),
+    #000 100%
+  );
+}
+:where([data-fade-bottom]):not([data-fade-top]) {
+  /* Only the bottom hides content: opaque above, fade past a present footer to the bottom edge. Footer offset
+     0px ⇒ the original #000 → transparent 100% bottom fade. */
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    #000 0,
+    #000 calc(100% - var(--ui-box-foot, 0px) - var(--ui-box-fade, 1rem)),
+    transparent calc(100% - var(--ui-box-foot-hold, 0px)),
+    transparent 100%
+  );
+  mask-image: linear-gradient(
+    to bottom,
+    #000 0,
+    #000 calc(100% - var(--ui-box-foot, 0px) - var(--ui-box-fade, 1rem)),
+    transparent calc(100% - var(--ui-box-foot-hold, 0px)),
+    transparent 100%
+  );
+}
+
+/* forced-colors — a mask over system-rendered text harms legibility; drop it (the sticky-region Canvas
+   background above still keeps the bracket itself opaque). */
+@media (forced-colors: active) {
+  :where([data-fade-top], [data-fade-bottom]) {
+    -webkit-mask-image: none;
+    mask-image: none;
+  }
+}