@cueplusplus/ui 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @cueplusplus/ui
 
+## 0.23.0
+
+### Minor Changes
+
+- dae9dec: **A field's edge can reach 3:1: `data-field-edge="contrast"`** (cue-ui-60). Every shipped theme's
+  `--cue-border` measured 1.07:1 to 2.02:1 against `surface-1`, under WCAG 1.4.11's 3:1 for the line
+  that marks out where to type. The border stays as it is, because it is a box edge and a quiet one on
+  purpose, and a field's edge becomes a role of its own.
+
+  - **`--cue-field-edge`** is each block's border moved toward its ink until it clears 3:1 on its
+    `surface-1`, written per block as a literal. Every theme package, `theme-base`'s own palette and
+    `createTheme()` write it, and the contrast report holds it to 3:1 as the required pair
+    `field-edge/surface-1`.
+  - **Opt in with `data-field-edge="contrast"`** on any element, `<html>` included. Every recessed
+    control inside then draws its resting edge in `--cue-field-edge`, disabled ones too, and over a
+    paint pack's stroke. Hover, focus and invalid edges keep their own colours. Outside the attribute,
+    nothing changes.
+  - **`edgeToContrast(edge, ground, toward, minimum = 3)`** is the arithmetic, exported from
+    `@cueplusplus/theme-base/contrast` and `@cueplusplus/ui/theming`.
+  - `@cueplusplus/tokens` publishes `field-edge` as a derived name, with `var(--cue-border)` as its
+    template. A stylesheet built before this release falls back to the plain border.
+
+  **For a theme package of your own:** `theme-tools` now writes one more line per block. Run
+  `generate` once after upgrading; until then `check` reports the stylesheet out of date.
+
+- 39884b3: **`MarkdownText` renders GitHub tables** (cue-ui-58). An agent's table used to arrive as one
+  paragraph of pipes: the parser read CommonMark only, and the sanitizer allowed no table elements.
+  Tables are now the one part of GFM the parser reads. Each column is aligned as its delimiter row
+  says, header cells sit on `surface-2`, and the table scrolls sideways inside a named,
+  keyboard-reachable region rather than widening the turn. Task lists, footnotes and autolink literals
+  stay out, and raw HTML is still refused: a cell's markup is text, and alignment is the only style a
+  cell carries.
+
+  **`remarkPlugins`** adds parser plugins after the table syntax. It is a seam for the parser, not
+  for the page: whatever a plugin puts in the tree passes the same sanitizer, so it can change what
+  the markdown means but cannot widen what renders.
+
+  ### Migrating
+  - **`@cueplusplus/ui/elements/markdown` has two more optional peers**, the table half of GFM:
+    `pnpm add micromark-extension-gfm-table mdast-util-gfm-table`. Like `react-markdown` and
+    `rehype-sanitize`, they are needed only where this subpath is imported. A build that imports it
+    without them fails to resolve the module, and names it.
+
+### Patch Changes
+
+- Updated dependencies [dae9dec]
+  - @cueplusplus/tokens@0.23.0
+  - @cueplusplus/theme-base@1.4.0
+
+## 0.22.0
+
+### Minor Changes
+
+- bdc8a32: A field's fill is a name now: `--cue-style-field-fill`. Every recessed control — Input, NumberField, SearchInput, Select, Combobox, Autocomplete, MultiSelect, TagsInput, Textarea, OtpField, ScrubInput, InputGroup, ColorField, ColorPicker, the date fields and MusicalTimeInput — fills with it before `--cue-sunken`, and a disabled one follows it unless `--cue-style-disabled-fill` is set. Nothing sets it by default, so nothing changes until a style set or a subtree does: `style={{ "--cue-style-field-fill": "var(--cue-surface-2)" }}` on any wrapper fills every field inside it. In the manifest, Button, Checkbox, CheckboxGroup, Switch and Toggle no longer list three stroke tokens they never painted.
+
+  The studio's generated tables carry the new catalogue identity, so a scene validates against the vocabulary that now includes a field's fill.
+
+- 1962b97: Fields can take their fill from the ground they stand on. Put `data-field-ground="relative"` on any element — `<html>` included — and every recessed control inside it fills one step off its nearest container, toward its text colour: lighter on a dark card, deeper on a light one. `--cue-style-field-step` sets the distance (6% by default) and `--cue-style-field-toward` the direction (`black` inline is always deeper). Containers painted with `bg-bg`, `bg-sunken`, `bg-surface-1/2/3`, a Card or an overlay say what they painted as `--cue-ground` (an overlay's is its `--cue-style-overlay-ground` when a Look sets one, so its fields follow the overlay the Look drew); anything painted another way sets `--cue-ground` itself. `--cue-style-field-fill` still wins, a disabled field follows, and nothing changes outside the attribute. The derivation is a `field-ground` utility in `@cueplusplus/ui/styles.css`, so a field of your own can wear it too.
+
+  The studio's generated tables carry the new catalogue identity, so a scene validates against the vocabulary that now includes the relative fill's two names.
+
+### Patch Changes
+
+- Updated dependencies [bdc8a32]
+- Updated dependencies [1962b97]
+  - @cueplusplus/tokens@0.22.0
+
 ## 0.21.0
 
 ### Minor Changes

package/README.md

@@ -105,7 +105,7 @@ their own, so importing a button never pulls a charting library into your bundle
 | `@cueplusplus/ui/chat` | the multi-agent transcript: messages, composer, HITL questions, agent colour |
 | `@cueplusplus/ui/agent-runtime` | the streaming layer under Chat; needs `@assistant-ui/react` |
 | `@cueplusplus/ui/elements` | the agent's own surface, vendored from assistant-ui and repainted onto the tokens; needs `lucide-react` and `heat-graph` (+ `./elements.css`) |
-| `@cueplusplus/ui/elements/markdown` | `MarkdownText`; needs `react-markdown`, `rehype-sanitize` |
+| `@cueplusplus/ui/elements/markdown` | `MarkdownText`; needs `react-markdown`, `rehype-sanitize`, `micromark-extension-gfm-table`, `mdast-util-gfm-table` |
 | `@cueplusplus/ui/elements/generative` | the generative-UI renderer and its spec (+ `./elements/generative.css`) |
 | `@cueplusplus/ui/elements/replay` | the scripted session-replay frame |
 | `@cueplusplus/ui/dmx` | 512 bytes at wire rate: the bar, the strip, the patch bar, the channel grid |

package/dist/elements/markdown.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import Markdown from "react-markdown";
 //#region src/elements/markdown.d.ts
 /** A fenced block, handed to a highlighter that was opted into. */
 interface MarkdownCodeBlock {
@@ -50,6 +51,16 @@ interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">,
    * behaviour they inherited.
    */
   renderCodeBlock?: (block: MarkdownCodeBlock) => React.ReactNode;
+  /**
+   * More remark plugins, run after the component's own table syntax.
+   *
+   * A seam for the parser, not for the page: whatever a plugin adds to the
+   * tree still passes the same sanitizer, so a plugin can change what the
+   * markdown *means* — a mention syntax, a glossary link — but cannot widen
+   * what renders. An element outside the subset is dropped, and an attribute
+   * the schema does not name never arrives.
+   */
+  remarkPlugins?: React.ComponentProps<typeof Markdown>["remarkPlugins"];
 }
 /**
  * Model output, rendered.
@@ -84,9 +95,11 @@ interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">,
  * - **Attributes are enumerated, not filtered.** An element that is not in the
  *   schema renders nothing; an element that is renders only the attributes
  *   named beside it — `href`/`title` on a link, `src`/`alt`/`title` on an
- *   image, `language-…` on a `code`. No element in the subset accepts `id`,
+ *   image, `language-…` on a `code`, and `align` on a table cell, held to
+ *   `left`, `center` or `right`. No element in the subset accepts `id`,
  *   `style`, `srcset`, `formaction` or any `on*` handler, so none of them has
- *   an attribute to arrive on.
+ *   an attribute to arrive on; the one inline style anything carries is a
+ *   cell's `text-align`, which the renderer writes from that `align`.
  * - **URLs are allow-listed twice.** `http`, `https` and `mailto` on both
  *   `href` and `src`; a relative URL stays relative; everything else — a
  *   `javascript:` link, a `data:text/html` image, `vbscript:`, `blob:`,
@@ -98,10 +111,14 @@ interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">,
  *
  * **The subset.** Paragraphs, ATX and setext headings, bullet and ordered
  * lists, block quotes, thematic breaks, fenced and indented code, inline code,
- * emphasis, strong, strikethrough, links, images, and hard breaks. No GFM
- * plugin is enabled, so no tables, task lists, footnotes or autolink literals —
- * an explicit `<https://…>` autolink still works. Fenced blocks are plain text
- * unless {@link MarkdownTextProps.renderCodeBlock} is given.
+ * emphasis, strong, strikethrough, links, images, hard breaks, and GitHub
+ * tables. Tables are the one part of GFM the parser reads, each column aligned
+ * as its delimiter row says and wrapped in a named region that scrolls
+ * sideways; task lists, footnotes and autolink literals stay out — an explicit
+ * `<https://…>` autolink still works. Fenced blocks are plain text unless
+ * {@link MarkdownTextProps.renderCodeBlock} is given, and
+ * {@link MarkdownTextProps.remarkPlugins} adds parser plugins without widening
+ * the subset.
  *
  * **Streaming.** Pass `streaming` while the turn is arriving and the token the
  * model is halfway through typing is hidden rather than rendered as
@@ -110,10 +127,11 @@ interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">,
  * words appear as they arrive; only their formatting waits for the closing
  * token.
  *
- * `react-markdown` and `rehype-sanitize` are optional peers of this subpath
- * alone, which is why this component is not re-exported from
+ * `react-markdown`, `rehype-sanitize` and GFM's table pair
+ * (`micromark-extension-gfm-table`, `mdast-util-gfm-table`) are optional peers
+ * of this subpath alone, which is why this component is not re-exported from
  * `@cueplusplus/ui/elements`: a console that renders a transcript without
- * markdown should install neither.
+ * markdown should install none of them.
  *
  * @example
  * <Message agent="researcher">
@@ -125,6 +143,8 @@ interface MarkdownTextProps extends Omit<React.ComponentPropsWithoutRef<"div">,
  * <MarkdownText renderCodeBlock={({ language, code }) => <Highlight lang={language} code={code} />}>
  *   {answer}
  * </MarkdownText>
+ * @example
+ * <MarkdownText remarkPlugins={[remarkMentions]}>{turn.text}</MarkdownText>
  */
 declare const MarkdownText: React.ForwardRefExoticComponent<MarkdownTextProps & React.RefAttributes<HTMLDivElement>>;
 //#endregion

package/dist/elements/markdown.js

@@ -4,6 +4,8 @@ import { FOCUS_RING } from "../system/_focus-ring.js";
 import { codeScroll, codeSurface, field, mono } from "./surfaces.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
+import { gfmTableFromMarkdown } from "mdast-util-gfm-table";
+import { gfmTable } from "micromark-extension-gfm-table";
 import Markdown from "react-markdown";
 import rehypeSanitize from "rehype-sanitize";
 //#region src/elements/markdown.tsx
@@ -19,9 +21,13 @@ import rehypeSanitize from "rehype-sanitize";
 * `MarkdownText`'s JSDoc quotes it, and a test asserts nothing outside it
 * survives.
 *
+* The six table elements are here because GFM's table syntax is the one part
+* of GFM the parser reads (see {@link remarkTables}): a table is inert, and it
+* is how an agent presents a comparison.
+*
 * Deliberately absent, and each for a reason: `input` (GFM task lists would
-* put a control inside a transcript), `table` and friends (no GFM plugin is
-* enabled, so the parser never produces them), `svg`/`math` (an untrusted
+* put a control inside a transcript), `sup`/`section` (footnotes, which a
+* reply does not need), `svg`/`math` (an untrusted
 * vector is a script host in several browsers' history), `details`/`summary`
 * (disclosure is a component, not a token stream), and every sectioning or
 * embedding tag — `iframe`, `object`, `embed`, `script`, `style`, `form`.
@@ -46,6 +52,12 @@ const ALLOWED_TAGS = [
 	"p",
 	"pre",
 	"strong",
+	"table",
+	"tbody",
+	"td",
+	"th",
+	"thead",
+	"tr",
 	"ul"
 ];
 /**
@@ -72,6 +84,9 @@ const ALLOWED_PROTOCOLS = [
 * handler unreachable by construction instead of by deny-list. `code` may
 * carry a `className`, and only one matching `language-…`, because that is how
 * a fenced block's info string reaches {@link MarkdownTextProps.renderCodeBlock}.
+* A table cell may carry `align`, and only one of the three values the
+* delimiter row can write; the renderer turns it into `text-align`, which is
+* the one inline style anything in this surface ever carries.
 */
 const SCHEMA = {
 	tagNames: [...ALLOWED_TAGS],
@@ -84,6 +99,18 @@ const SCHEMA = {
 		],
 		code: [["className", /^language-[\w+#.-]+$/]],
 		ol: ["start"],
+		th: [[
+			"align",
+			"left",
+			"center",
+			"right"
+		]],
+		td: [[
+			"align",
+			"left",
+			"center",
+			"right"
+		]],
 		"*": []
 	},
 	protocols: {
@@ -304,6 +331,20 @@ function sealStream(source) {
 	for (let index = 0; index < tail.length; index += 1) if (!erase.has(index)) sealed += tail[index];
 	return head + sealed;
 }
+/**
+* GitHub's table syntax, as a remark plugin, and nothing else from GFM.
+*
+* `remark-gfm` would bring task lists (a checkbox in a transcript), footnotes
+* and autolink literals along with tables. This registers the table tokenizer
+* and its tree handlers alone, which is what `remark-gfm` itself does for each
+* of its five extensions, one at a time. The sanitizer still decides what a
+* table may render as: the six elements and a cell's `align`.
+*/
+function remarkTables() {
+	const data = this.data();
+	(data.micromarkExtensions ??= []).push(gfmTable());
+	(data.fromMarkdownExtensions ??= []).push(gfmTableFromMarkdown());
+}
 /** The text and info string of a fenced block, read off its hast node. */
 function readCodeBlock(node) {
 	const code = node?.children?.find((child) => child.tagName === "code");
@@ -347,9 +388,11 @@ function readCodeBlock(node) {
 * - **Attributes are enumerated, not filtered.** An element that is not in the
 *   schema renders nothing; an element that is renders only the attributes
 *   named beside it — `href`/`title` on a link, `src`/`alt`/`title` on an
-*   image, `language-…` on a `code`. No element in the subset accepts `id`,
+*   image, `language-…` on a `code`, and `align` on a table cell, held to
+*   `left`, `center` or `right`. No element in the subset accepts `id`,
 *   `style`, `srcset`, `formaction` or any `on*` handler, so none of them has
-*   an attribute to arrive on.
+*   an attribute to arrive on; the one inline style anything carries is a
+*   cell's `text-align`, which the renderer writes from that `align`.
 * - **URLs are allow-listed twice.** `http`, `https` and `mailto` on both
 *   `href` and `src`; a relative URL stays relative; everything else — a
 *   `javascript:` link, a `data:text/html` image, `vbscript:`, `blob:`,
@@ -361,10 +404,14 @@ function readCodeBlock(node) {
 *
 * **The subset.** Paragraphs, ATX and setext headings, bullet and ordered
 * lists, block quotes, thematic breaks, fenced and indented code, inline code,
-* emphasis, strong, strikethrough, links, images, and hard breaks. No GFM
-* plugin is enabled, so no tables, task lists, footnotes or autolink literals —
-* an explicit `<https://…>` autolink still works. Fenced blocks are plain text
-* unless {@link MarkdownTextProps.renderCodeBlock} is given.
+* emphasis, strong, strikethrough, links, images, hard breaks, and GitHub
+* tables. Tables are the one part of GFM the parser reads, each column aligned
+* as its delimiter row says and wrapped in a named region that scrolls
+* sideways; task lists, footnotes and autolink literals stay out — an explicit
+* `<https://…>` autolink still works. Fenced blocks are plain text unless
+* {@link MarkdownTextProps.renderCodeBlock} is given, and
+* {@link MarkdownTextProps.remarkPlugins} adds parser plugins without widening
+* the subset.
 *
 * **Streaming.** Pass `streaming` while the turn is arriving and the token the
 * model is halfway through typing is hidden rather than rendered as
@@ -373,10 +420,11 @@ function readCodeBlock(node) {
 * words appear as they arrive; only their formatting waits for the closing
 * token.
 *
-* `react-markdown` and `rehype-sanitize` are optional peers of this subpath
-* alone, which is why this component is not re-exported from
+* `react-markdown`, `rehype-sanitize` and GFM's table pair
+* (`micromark-extension-gfm-table`, `mdast-util-gfm-table`) are optional peers
+* of this subpath alone, which is why this component is not re-exported from
 * `@cueplusplus/ui/elements`: a console that renders a transcript without
-* markdown should install neither.
+* markdown should install none of them.
 *
 * @example
 * <Message agent="researcher">
@@ -388,8 +436,10 @@ function readCodeBlock(node) {
 * <MarkdownText renderCodeBlock={({ language, code }) => <Highlight lang={language} code={code} />}>
 *   {answer}
 * </MarkdownText>
+* @example
+* <MarkdownText remarkPlugins={[remarkMentions]}>{turn.text}</MarkdownText>
 */
-const MarkdownText = React.forwardRef(function MarkdownText({ className, children, streaming = false, target = "_blank", headingLevel = 2, renderCodeBlock, ...elementProps }, ref) {
+const MarkdownText = React.forwardRef(function MarkdownText({ className, children, streaming = false, target = "_blank", headingLevel = 2, renderCodeBlock, remarkPlugins, ...elementProps }, ref) {
 	const source = streaming ? sealStream(children) : children;
 	const components = React.useMemo(() => markdownComponents({
 		target,
@@ -408,6 +458,7 @@ const MarkdownText = React.forwardRef(function MarkdownText({ className, childre
 		...elementProps,
 		children: /* @__PURE__ */ jsx(Markdown, {
 			components,
+			remarkPlugins: [remarkTables, ...remarkPlugins ?? []],
 			rehypePlugins: [[rehypeSanitize, SCHEMA]],
 			skipHtml: true,
 			urlTransform: safeUrl,
@@ -522,7 +573,45 @@ function markdownComponents(options) {
 					children: renderCodeBlock(block)
 				})
 			});
-		}
+		},
+		table: ({ children }) => /* @__PURE__ */ jsx("div", {
+			role: "region",
+			"aria-label": "Table",
+			tabIndex: 0,
+			"data-slot": "markdown-table-scroll",
+			className: cn("rounded-control border border-border outline-none", codeScroll, FOCUS_RING),
+			children: /* @__PURE__ */ jsx("table", {
+				"data-slot": "markdown-table",
+				className: "w-full border-collapse text-(length:--cue-text-ui)",
+				children
+			})
+		}),
+		thead: ({ children }) => /* @__PURE__ */ jsx("thead", {
+			"data-slot": "markdown-table-head",
+			className: "bg-surface-2",
+			children
+		}),
+		tbody: ({ children }) => /* @__PURE__ */ jsx("tbody", {
+			"data-slot": "markdown-table-body",
+			children
+		}),
+		tr: ({ children }) => /* @__PURE__ */ jsx("tr", {
+			"data-slot": "markdown-table-row",
+			className: "border-b border-border last:border-b-0",
+			children
+		}),
+		th: ({ children, style }) => /* @__PURE__ */ jsx("th", {
+			"data-slot": "markdown-table-header",
+			style,
+			className: "px-(--cue-space-3) py-(--cue-space-2) text-start align-bottom font-medium text-fg",
+			children
+		}),
+		td: ({ children, style }) => /* @__PURE__ */ jsx("td", {
+			"data-slot": "markdown-table-cell",
+			style,
+			className: "px-(--cue-space-3) py-(--cue-space-2) align-top text-fg",
+			children
+		})
 	};
 }
 //#endregion

package/dist/forms/_chassis.d.ts

@@ -102,6 +102,14 @@ import { FormControlSize } from "./_chassis-size.js";
  * set (a hex colour code, a DMX value) restates `font-mono` on top, as
  * `color-picker.tsx`'s hex field does.
  *
+ * **`field-ground`** is `styles.css`'s opt-in relative fill (spec
+ * 2026-10-08-field-ground R3): inside `[data-field-ground="relative"]` it
+ * re-declares this field's own `--cue-sunken` one step off the ground it stands
+ * on; anywhere else it compiles to nothing that applies. The same hook carries
+ * the contrast edge (cue-ui-60): inside `[data-field-edge="contrast"]` this
+ * field's resting stroke reads `--cue-field-edge`, its theme's border moved to
+ * 3:1 on `surface-1`.
+ *
  * **The resting shade** ({@link REST_SHADE_CLASS}, spec §3.10) is the one
  * shadow this recipe draws: the stroke paints a border and a ground and no
  * shadow, so the shade is added as a utility of its own rather than composed
@@ -110,7 +118,7 @@ import { FormControlSize } from "./_chassis-size.js";
  * own `shadow-` utility replaces it through `twMerge`, as it would have
  * replaced nothing before.
  */
-declare const controlSurface = "w-full rounded-[var(--cue-style-field-radius,calc(var(--cue-style-control-radius,var(--cue-radius-control))*var(--cue-radius-scale)))] border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-sunken),var(--cue-sunken)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] bg-origin-border [background-clip:padding-box,border-box] shadow-[shadow:0_calc(2px*var(--cue-paint-shadow-scale))_calc(4px*var(--cue-paint-shadow-scale))_var(--cue-paint-rest-shade,transparent)] font-[family-name:var(--cue-style-input-face,var(--cue-font-mono))] font-[number:var(--cue-style-body-weight,inherit)] text-fg placeholder:text-fg-subtle outline-none hover:border-[color:var(--cue-style-field-hover-edge,transparent)] focus:border-[color:var(--cue-style-focus-edge,var(--cue-border-strong))] focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-(--cue-focus) focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)] disabled:opacity-[var(--cue-style-disabled-opacity,0.4)] data-[disabled]:opacity-[var(--cue-style-disabled-opacity,0.4)] disabled:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-sunken)),var(--cue-style-disabled-fill,var(--cue-sunken))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] data-[disabled]:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-sunken)),var(--cue-style-disabled-fill,var(--cue-sunken))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] data-[invalid]:border-danger data-[invalid]:focus-visible:outline-danger";
+declare const controlSurface = "w-full field-ground rounded-[var(--cue-style-field-radius,calc(var(--cue-style-control-radius,var(--cue-radius-control))*var(--cue-radius-scale)))] border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-style-field-fill,var(--cue-sunken)),var(--cue-style-field-fill,var(--cue-sunken))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] bg-origin-border [background-clip:padding-box,border-box] shadow-[shadow:0_calc(2px*var(--cue-paint-shadow-scale))_calc(4px*var(--cue-paint-shadow-scale))_var(--cue-paint-rest-shade,transparent)] font-[family-name:var(--cue-style-input-face,var(--cue-font-mono))] font-[number:var(--cue-style-body-weight,inherit)] text-fg placeholder:text-fg-subtle outline-none hover:border-[color:var(--cue-style-field-hover-edge,transparent)] focus:border-[color:var(--cue-style-focus-edge,var(--cue-border-strong))] focus-visible:outline-solid focus-visible:outline-[length:var(--cue-style-focus-width,var(--cue-focus-ring))] focus-visible:outline-(--cue-focus) focus-visible:outline-offset-[var(--cue-style-field-focus-offset,-1px)] disabled:opacity-[var(--cue-style-disabled-opacity,0.4)] data-[disabled]:opacity-[var(--cue-style-disabled-opacity,0.4)] disabled:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken))),var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken)))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] data-[disabled]:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken))),var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken)))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] data-[invalid]:border-danger data-[invalid]:focus-visible:outline-danger";
 /**
  * The full recessed-control recipe, one variant per rung of the control ladder.
  *

package/dist/forms/_chassis.js

@@ -1,9 +1,9 @@
 import { REST_SHADE_CLASS } from "../system/_paint-rest-shade.js";
-import { DATA_DISABLED_OPACITY, DISABLED_OPACITY, FIELD_DISABLED_FILL } from "../system/_style-disabled.js";
+import { DATA_DISABLED_OPACITY, DISABLED_OPACITY } from "../system/_style-disabled.js";
 import { cva } from "../lib/cva.js";
 import { FOCUS_RING_FIELD, FOCUS_RING_GROUP_FIELD } from "../system/_focus-ring-field.js";
 import { CONTROL_STEP_SIZE_BODY, CONTROL_STEP_SIZE_SM } from "../system/_style-control-step.js";
-import { STROKE_SUNKEN } from "../system/_paint-stroke-sunken.js";
+import { FIELD_DISABLED_FILL, STROKE_SUNKEN } from "../system/_paint-stroke-sunken.js";
 import { BODY_WEIGHT } from "../system/_style-body-weight.js";
 import { FIELD_HOVER_EDGE, FIELD_PAD_LG, FIELD_PAD_MD, FIELD_PAD_SM, FIELD_RADIUS, INVALID_EDGE } from "../system/_style-field-chassis.js";
 import { INPUT_FACE } from "../system/_style-input-face.js";
@@ -109,6 +109,14 @@ import { INPUT_FACE } from "../system/_style-input-face.js";
 * set (a hex colour code, a DMX value) restates `font-mono` on top, as
 * `color-picker.tsx`'s hex field does.
 *
+* **`field-ground`** is `styles.css`'s opt-in relative fill (spec
+* 2026-10-08-field-ground R3): inside `[data-field-ground="relative"]` it
+* re-declares this field's own `--cue-sunken` one step off the ground it stands
+* on; anywhere else it compiles to nothing that applies. The same hook carries
+* the contrast edge (cue-ui-60): inside `[data-field-edge="contrast"]` this
+* field's resting stroke reads `--cue-field-edge`, its theme's border moved to
+* 3:1 on `surface-1`.
+*
 * **The resting shade** ({@link REST_SHADE_CLASS}, spec §3.10) is the one
 * shadow this recipe draws: the stroke paints a border and a ground and no
 * shadow, so the shade is added as a utility of its own rather than composed
@@ -117,7 +125,7 @@ import { INPUT_FACE } from "../system/_style-input-face.js";
 * own `shadow-` utility replaces it through `twMerge`, as it would have
 * replaced nothing before.
 */
-const controlSurface = `w-full ${FIELD_RADIUS} ${STROKE_SUNKEN} ${REST_SHADE_CLASS} ${INPUT_FACE} ${BODY_WEIGHT} text-fg placeholder:text-fg-subtle outline-none ${FIELD_HOVER_EDGE} focus:border-[color:var(--cue-style-focus-edge,var(--cue-border-strong))] ${FOCUS_RING_FIELD} ${DISABLED_OPACITY} ${DATA_DISABLED_OPACITY} ${FIELD_DISABLED_FILL} ${INVALID_EDGE} data-[invalid]:focus-visible:outline-danger`;
+const controlSurface = `w-full field-ground ${FIELD_RADIUS} ${STROKE_SUNKEN} ${REST_SHADE_CLASS} ${INPUT_FACE} ${BODY_WEIGHT} text-fg placeholder:text-fg-subtle outline-none ${FIELD_HOVER_EDGE} focus:border-[color:var(--cue-style-focus-edge,var(--cue-border-strong))] ${FOCUS_RING_FIELD} ${DISABLED_OPACITY} ${DATA_DISABLED_OPACITY} ${FIELD_DISABLED_FILL} ${INVALID_EDGE} data-[invalid]:focus-visible:outline-danger`;
 /**
 * The full recessed-control recipe, one variant per rung of the control ladder.
 *

package/dist/overlays/_surface.d.ts

@@ -18,7 +18,7 @@
  * @example
  * <Popover.Popup className={cn(overlaySurfaceClasses, className)} />
  */
-declare const overlaySurfaceClasses = "rounded-overlay border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-style-overlay-ground,var(--cue-surface-2)),var(--cue-style-overlay-ground,var(--cue-surface-2))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-overlay-from,var(--cue-border-overlay)),var(--cue-paint-stroke-overlay-to,var(--cue-border-overlay)))] bg-origin-border [background-clip:padding-box,border-box] shadow-[0_0_0_var(--cue-paint-rim-width)_var(--cue-paint-shade-hairline,transparent),0_calc(2px*var(--cue-paint-shadow-scale))_calc(6px*var(--cue-paint-shadow-scale))_var(--cue-paint-shadow-spread)_var(--cue-paint-shade-near,transparent),0_calc(8px*var(--cue-paint-shadow-scale))_calc(24px*var(--cue-paint-shadow-scale))_var(--cue-paint-shadow-spread)_var(--cue-paint-shade-far,rgba(0,0,0,0.4)),inset_0_1px_0_0_var(--cue-paint-sheen-ink,transparent)]";
+declare const overlaySurfaceClasses = "rounded-overlay border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-style-overlay-ground,var(--cue-surface-2)),var(--cue-style-overlay-ground,var(--cue-surface-2))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-overlay-from,var(--cue-border-overlay)),var(--cue-paint-stroke-overlay-to,var(--cue-border-overlay)))] bg-origin-border [background-clip:padding-box,border-box] [--cue-ground:var(--cue-style-overlay-ground,var(--cue-surface-2))] shadow-[0_0_0_var(--cue-paint-rim-width)_var(--cue-paint-shade-hairline,transparent),0_calc(2px*var(--cue-paint-shadow-scale))_calc(6px*var(--cue-paint-shadow-scale))_var(--cue-paint-shadow-spread)_var(--cue-paint-shade-near,transparent),0_calc(8px*var(--cue-paint-shadow-scale))_calc(24px*var(--cue-paint-shadow-scale))_var(--cue-paint-shadow-spread)_var(--cue-paint-shade-far,rgba(0,0,0,0.4)),inset_0_1px_0_0_var(--cue-paint-sheen-ink,transparent)]";
 /**
  * The full-viewport dim behind a modal surface. `--cue-scrim` is theme-owned —
  * dusk and hivehub tune their own — so the value is never hard-coded here.

package/dist/styles.css

@@ -133,3 +133,72 @@
     clip-path: none;
   }
 }
+
+/* A container's ground, for the relative field fill (spec 2026-10-08-field-ground R3).
+ *
+ * Every fill utility a container can paint with says what it painted, as
+ * `--cue-ground`, and a control inside `[data-field-ground="relative"]` mixes
+ * its fill from the nearest one (`system/_field-ground.ts`). Declaring it is
+ * free: nothing outside the opt-in reads it. In `base` so a consumer's own
+ * utility or inline `--cue-ground` wins; a container painted any other way — a
+ * gradient, an image, a translucent fill — sets `--cue-ground` itself. */
+@layer base {
+  .bg-bg {
+    --cue-ground: var(--cue-bg);
+  }
+  .bg-sunken {
+    --cue-ground: var(--cue-sunken);
+  }
+  .bg-surface-1 {
+    --cue-ground: var(--cue-surface-1);
+  }
+  .bg-surface-2 {
+    --cue-ground: var(--cue-surface-2);
+  }
+  .bg-surface-3 {
+    --cue-ground: var(--cue-surface-3);
+  }
+}
+
+/* The relative field fill (spec 2026-10-08-field-ground R3), and opt-in.
+ *
+ * Nothing happens until an ancestor carries `data-field-ground="relative"`.
+ * Inside one, a field that wears `field-ground` — every control the recessed
+ * chassis draws does — re-declares its OWN `--cue-sunken` one step off the
+ * nearest container's `--cue-ground` (declared above, and by the raised and
+ * overlay strokes), toward its text colour: lighter on a dark ground, deeper on
+ * a light one, 6% unless `--cue-style-field-step` says otherwise.
+ * `--cue-style-field-toward` changes the direction.
+ *
+ * On the field, never on the ancestor: a custom property resolves its `var()`s
+ * where it is declared, so declared on the opt-in element it would freeze at
+ * that element's ground and every field below — in a card, in a popover —
+ * would fill as if it stood on the page.
+ *
+ * Re-declaring `sunken` rather than adding a term to the field's fill keeps
+ * the chain the stroke already reads, `var(--cue-style-field-fill,
+ * var(--cue-sunken))`: a named fill still wins, a disabled field follows, and
+ * no field's class grows by more than this utility's name. A consumer's own
+ * field can wear `field-ground` too.
+ *
+ * The contrast edge (cue-ui-60), and opt-in too. A theme's `--cue-border` is a
+ * box edge, quiet on purpose, and against `surface-1` it measured 1.07:1 to
+ * 2.02:1 in every shipped theme: under WCAG 1.4.11's 3:1 for the line that
+ * marks out where to type. `--cue-field-edge` is that border moved toward the
+ * ink until it clears 3:1 (each theme writes it per block, as a literal), and
+ * inside an ancestor carrying `data-field-edge="contrast"` a field's resting
+ * stroke reads it. Declared on the field for the reason the fill is: resolved
+ * here, it is the theme the field stands in, island or not. It sets both ends
+ * of the stroke, so it wins over a paint pack's gradient edge — the opt-in is
+ * a reader's need, and a pack is a look. The hover, focus and invalid edges are
+ * their own colours and do not move. Same hook as the relative fill, so no
+ * field's class grows for it. */
+@utility field-ground {
+  :where([data-field-ground="relative"]) & {
+    --cue-sunken: color-mix(in oklab, var(--cue-ground, var(--cue-bg)), var(--cue-style-field-toward, var(--cue-fg)) var(--cue-style-field-step, 6%));
+  }
+  :where([data-field-edge="contrast"]) & {
+    --cue-paint-stroke-from: var(--cue-field-edge, var(--cue-border));
+    --cue-paint-stroke-to: var(--cue-field-edge, var(--cue-border));
+  }
+}

package/dist/system/_paint-stroke-sunken.js

@@ -12,8 +12,28 @@
 * The recipe itself, and why its off state is a flat gradient rather than
 * `none`, is documented once in `./_paint`.
 *
+* **The fill is a name first** (spec 2026-10-08-field-ground R2):
+* `--cue-style-field-fill`, declared on no `:root` for the reason
+* `_style-input-face.ts` gives, so with nothing set this resolves to exactly
+* the `--cue-sunken` it always painted. A style set, or any subtree, names it.
+*
 * @internal Not part of the public API.
 */
-const STROKE_SUNKEN = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-sunken),var(--cue-sunken)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] bg-origin-border [background-clip:padding-box,border-box]";
+const STROKE_SUNKEN = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-style-field-fill,var(--cue-sunken)),var(--cue-style-field-fill,var(--cue-sunken))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] bg-origin-border [background-clip:padding-box,border-box]";
+/**
+* The same two layers when the field is disabled: the fill read through
+* `style-disabled-fill`, then the field's own fill, then `sunken`, on
+* `:disabled` and on `[data-disabled]`.
+*
+* **Here, beside the resting recipe, and not in `_style-disabled.ts`** with the
+* other disabled recipes (spec 2026-10-08-field-ground R2). Docgen credits every
+* `--cue-*` in a module to each component that imports it, and the button, the
+* checkbox and the switch import that module for their own disabled recipes:
+* left there, all of them would claim a field's fill they never paint. This
+* module is imported by the field chassis alone, so the credit is exact, and
+* the library ships one file per module, so a module of its own would have
+* cost every page that draws a field one more request.
+*/
+const FIELD_DISABLED_FILL = "disabled:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken))),var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken)))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] data-[disabled]:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken))),var(--cue-style-disabled-fill,var(--cue-style-field-fill,var(--cue-sunken)))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))]";
 //#endregion
-export { STROKE_SUNKEN };
+export { FIELD_DISABLED_FILL, STROKE_SUNKEN };

package/dist/system/_paint-stroke-surface-1.js

@@ -12,8 +12,12 @@
 * The recipe itself, and why its off state is a flat gradient rather than
 * `none`, is documented once in `./_paint`.
 *
+* It also says what it painted, as `--cue-ground`, for the relative field fill
+* (spec 2026-10-08-field-ground R3): a field inside `[data-field-ground="relative"]`
+* takes its fill one step off the nearest container's ground.
+*
 * @internal Not part of the public API.
 */
-const STROKE_SURFACE_1 = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-surface-1),var(--cue-surface-1)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-raised-from,var(--cue-paint-stroke-from,var(--cue-border))),var(--cue-paint-stroke-raised-to,var(--cue-paint-stroke-to,var(--cue-border))))] bg-origin-border [background-clip:padding-box,border-box]";
+const STROKE_SURFACE_1 = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-surface-1),var(--cue-surface-1)),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-raised-from,var(--cue-paint-stroke-from,var(--cue-border))),var(--cue-paint-stroke-raised-to,var(--cue-paint-stroke-to,var(--cue-border))))] bg-origin-border [background-clip:padding-box,border-box] [--cue-ground:var(--cue-surface-1)]";
 //#endregion
 export { STROKE_SURFACE_1 };

package/dist/system/_paint-stroke-surface-2.js

@@ -33,8 +33,12 @@
 * The recipe itself, and why its off state is a flat gradient rather than
 * `none`, is documented once in `./_paint`.
 *
+* It also says what it painted, as `--cue-ground`, for the relative field fill
+* (spec 2026-10-08-field-ground R3): a field inside `[data-field-ground="relative"]`
+* takes its fill one step off the nearest container's ground.
+*
 * @internal Not part of the public API.
 */
-const STROKE_SURFACE_2 = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-style-overlay-ground,var(--cue-surface-2)),var(--cue-style-overlay-ground,var(--cue-surface-2))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-overlay-from,var(--cue-border-overlay)),var(--cue-paint-stroke-overlay-to,var(--cue-border-overlay)))] bg-origin-border [background-clip:padding-box,border-box]";
+const STROKE_SURFACE_2 = "border-transparent border-(length:--cue-paint-stroke-width) bg-[linear-gradient(var(--cue-style-overlay-ground,var(--cue-surface-2)),var(--cue-style-overlay-ground,var(--cue-surface-2))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-overlay-from,var(--cue-border-overlay)),var(--cue-paint-stroke-overlay-to,var(--cue-border-overlay)))] bg-origin-border [background-clip:padding-box,border-box] [--cue-ground:var(--cue-style-overlay-ground,var(--cue-surface-2))]";
 //#endregion
 export { STROKE_SURFACE_2 };

package/dist/system/_style-disabled.js

@@ -33,12 +33,6 @@ const LABEL_DISABLED_OPACITY = "has-[[data-disabled]]:opacity-[var(--cue-style-d
 /** A disabled control label's ink, falling back to the label ink it drew (`LABEL_INK`). */
 const LABEL_DISABLED_INK = "has-[[data-disabled]]:text-[color:var(--cue-style-disabled-ink,var(--cue-style-label-ink,var(--cue-fg-muted)))]";
 /**
-* The field chassis's fill when disabled: its own two layers (`STROKE_SUNKEN`),
-* with the fill layer's `sunken` read through `style-disabled-fill`, on
-* `:disabled` and on `[data-disabled]`.
-*/
-const FIELD_DISABLED_FILL = "disabled:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-sunken)),var(--cue-style-disabled-fill,var(--cue-sunken))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))] data-[disabled]:bg-[linear-gradient(var(--cue-style-disabled-fill,var(--cue-sunken)),var(--cue-style-disabled-fill,var(--cue-sunken))),linear-gradient(var(--cue-paint-stroke-angle),var(--cue-paint-stroke-from,var(--cue-border)),var(--cue-paint-stroke-to,var(--cue-border)))]";
-/**
 * The button tones' fill and ink when disabled, each falling back to the tone's own resting fill and ink.
 * The two transparent tones keep their ground and take an edge instead (`style-disabled-edge`, falling
 * back to the edge each drew): stripe.com's disabled icon button stays on its ground and draws a 1px rim
@@ -67,4 +61,4 @@ const CHECK_DISABLED = "data-[disabled]:bg-[color:var(--cue-style-disabled-fill,
 /** The switch's track when disabled, unchecked and checked, each state keeping its own fallback. */
 const SWITCH_DISABLED_TRACK = "data-[disabled]:bg-[color:var(--cue-style-disabled-fill,var(--cue-surface-3))] data-[disabled]:data-[checked]:bg-[color:var(--cue-style-disabled-fill,var(--cue-accent))]";
 //#endregion
-export { CHECK_DISABLED, DATA_DISABLED_OPACITY, DISABLED_OPACITY, DISABLED_TONES, FIELD_DISABLED_FILL, LABEL_DISABLED_INK, LABEL_DISABLED_OPACITY, SWITCH_DISABLED_TRACK };
+export { CHECK_DISABLED, DATA_DISABLED_OPACITY, DISABLED_OPACITY, DISABLED_TONES, LABEL_DISABLED_INK, LABEL_DISABLED_OPACITY, SWITCH_DISABLED_TRACK };

package/dist/theming/contrast.d.ts

@@ -1,2 +1,2 @@
-import { CONTRAST_REQUIREMENTS, ContrastCheck, ContrastInput, ContrastReport, ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport as contrastReport$1, relativeLuminance } from "@cueplusplus/theme-base/contrast";
-export { CONTRAST_REQUIREMENTS, type ContrastCheck, type ContrastInput, type ContrastReport, type ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport$1 as contrastReport, relativeLuminance };
+import { CONTRAST_REQUIREMENTS, ContrastCheck, ContrastInput, ContrastReport, ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport as contrastReport$1, edgeToContrast, relativeLuminance } from "@cueplusplus/theme-base/contrast";
+export { CONTRAST_REQUIREMENTS, type ContrastCheck, type ContrastInput, type ContrastReport, type ContrastRequirement, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport$1 as contrastReport, edgeToContrast, relativeLuminance };

package/dist/theming/contrast.js

@@ -1,2 +1,2 @@
-import { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport as contrastReport$1, relativeLuminance } from "@cueplusplus/theme-base/contrast";
-export { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport$1 as contrastReport, relativeLuminance };
+import { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport as contrastReport$1, edgeToContrast, relativeLuminance } from "@cueplusplus/theme-base/contrast";
+export { CONTRAST_REQUIREMENTS, WCAG_AAA_TEXT, WCAG_AA_NON_TEXT, WCAG_AA_TEXT, contrastRatio, contrastReport$1 as contrastReport, edgeToContrast, relativeLuminance };