@reddb-io/ui-kit 0.3.4 → 0.3.5

package/vendor/ds/kits/base/src/indicator.variants.ts

@@ -0,0 +1,35 @@
+import { tv, type VariantProps } from "tailwind-variants";
+
+export const INDICATOR_POSITIONS = [
+  "top-start",
+  "top-center",
+  "top-end",
+  "middle-start",
+  "middle-end",
+  "bottom-start",
+  "bottom-center",
+  "bottom-end",
+] as const;
+export type IndicatorPosition = (typeof INDICATOR_POSITIONS)[number];
+
+const POSITION: Record<IndicatorPosition, { marker: string }> = {
+  "top-start": { marker: "start-0 top-0 -translate-x-1/2 -translate-y-1/2" },
+  "top-center": { marker: "start-1/2 top-0 -translate-x-1/2 -translate-y-1/2" },
+  "top-end": { marker: "end-0 top-0 translate-x-1/2 -translate-y-1/2" },
+  "middle-start": { marker: "start-0 top-1/2 -translate-x-1/2 -translate-y-1/2" },
+  "middle-end": { marker: "end-0 top-1/2 translate-x-1/2 -translate-y-1/2" },
+  "bottom-start": { marker: "bottom-0 start-0 -translate-x-1/2 translate-y-1/2" },
+  "bottom-center": { marker: "bottom-0 start-1/2 -translate-x-1/2 translate-y-1/2" },
+  "bottom-end": { marker: "bottom-0 end-0 translate-x-1/2 translate-y-1/2" },
+};
+
+export const indicator = tv({
+  slots: {
+    root: "relative inline-flex",
+    marker: "absolute z-10 inline-flex",
+  },
+  variants: { position: POSITION },
+  defaultVariants: { position: "top-end" },
+});
+
+export type IndicatorVariants = VariantProps<typeof indicator>;

package/vendor/ds/kits/base/src/inline-edit.variants.ts

@@ -0,0 +1,33 @@
+import { tv } from "tailwind-variants";
+import { typeRoleMerge } from "./type-roles";
+
+export const inlineEdit = tv({
+  slots: {
+    root: "group/inline-edit flex min-w-0 flex-col gap-[var(--reddb-spatial-gap-sm)] text-foreground",
+    label: "text-caption text-ink-muted",
+    row: "flex min-w-0 flex-wrap items-center gap-[var(--reddb-spatial-gap-sm)]",
+    value: "min-w-0 break-words",
+    field: "relative min-w-0 flex-1 basis-[12ch]",
+    input: "min-w-0 w-full",
+    icon: "pointer-events-none inline-flex shrink-0 items-center text-ink-muted",
+    inputIcon: "pointer-events-none absolute inset-y-0 start-0 inline-flex w-[var(--reddb-spatial-control-height-md)] items-center justify-center text-ink-muted",
+    readText: "min-w-0 select-text break-words [overflow-wrap:anywhere]",
+    status: "m-0 break-words text-caption text-ink-muted",
+    edit: "shrink-0",
+    error: "m-0 text-caption text-feedback-danger-foreground",
+  },
+  variants: {
+    presentation: {
+      text: { value: "inline-flex items-center gap-[var(--reddb-spatial-gap-sm)] text-body font-medium" },
+      input: { value: "flex min-h-[var(--reddb-spatial-control-height-md)] flex-1 basis-[12ch] items-center gap-[var(--reddb-spatial-gap-sm)] text-editable-md" },
+    },
+    withIcon: {
+      true: { input: "ps-[var(--reddb-spatial-control-height-md)]" },
+    },
+    editVisibility: {
+      always: { edit: "" },
+      hover: { edit: "[@media(hover:hover)_and_(pointer:fine)]:opacity-0 group-hover/inline-edit:opacity-100 group-focus-within/inline-edit:opacity-100" },
+    },
+  },
+  defaultVariants: { editVisibility: "always", presentation: "text" },
+}, typeRoleMerge);

package/vendor/ds/kits/base/src/input.variants.ts

@@ -0,0 +1,33 @@
+// Input's public appearance seam. Input itself owns only the native element
+// and forwarding behavior; this function is where a consumer composes or
+// extends the canonical appearance without copying that behavior.
+
+import { tv, type VariantProps } from "tailwind-variants";
+import { typeRoleMerge } from "./type-roles";
+
+export const input = tv({
+  base: [
+    "flex w-full",
+    "rounded-md border border-control-edge bg-background",
+    "text-foreground",
+    "placeholder:text-ink-muted",
+    "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus",
+    "aria-invalid:border-feedback-danger-border",
+    "disabled:cursor-not-allowed disabled:opacity-50",
+  ].join(" "),
+  variants: {
+    // The same three steps as Button, so a field and the action beside it
+    // share one control height at every Density stop. Named `controlSize` on
+    // the component: the native `size` attribute is still spread through.
+    size: {
+      sm: "h-[var(--reddb-spatial-control-height-sm)] px-[var(--reddb-spatial-inset-sm)] text-editable-sm",
+      md: "h-[var(--reddb-spatial-control-height-md)] px-[var(--reddb-spatial-inset-md)] text-editable-md",
+      lg: "h-[var(--reddb-spatial-control-height-lg)] px-[var(--reddb-spatial-inset-lg)] text-editable-lg",
+    },
+  },
+  defaultVariants: { size: "md" },
+}, typeRoleMerge);
+
+export type InputVariants = VariantProps<typeof input>;
+export type InputSize = NonNullable<InputVariants["size"]>;
+export const INPUT_SIZES = ["sm", "md", "lg"] as const satisfies readonly InputSize[];

package/vendor/ds/kits/base/src/interaction.ts

@@ -0,0 +1,3 @@
+// Portable integration seams. Importing them never loads a renderer.
+export { isEventFromModal } from "./core/modal";
+export { warnA11y, hasAccessibleName } from "./core/a11y";

package/vendor/ds/kits/base/src/kbd.variants.ts

@@ -0,0 +1,25 @@
+import { tv, type VariantProps } from "tailwind-variants";
+
+const SIZE = {
+  sm: "h-4 min-w-4 px-1 text-xs",
+  md: "h-5 min-w-5 px-1.5 text-xs",
+} as const;
+
+/** Key-cap size follows its surrounding typography, not page Density. */
+export const kbd = tv({
+  base: "inline-flex items-center justify-center rounded-sm border border-muted bg-transparent font-mono leading-tight text-foreground whitespace-nowrap",
+  variants: { size: SIZE },
+  defaultVariants: { size: "md" },
+});
+
+/** A multi-key chord; only the inter-cap gap routes through Density. */
+export const kbdChord = tv({
+  slots: {
+    root: "inline-flex items-center gap-[var(--reddb-spatial-gap-sm)] whitespace-nowrap",
+    separator: "text-ink-muted text-xs",
+  },
+});
+
+export type KbdVariants = VariantProps<typeof kbd>;
+export type KbdSize = NonNullable<KbdVariants["size"]>;
+export const KBD_SIZES = Object.keys(SIZE) as readonly KbdSize[];

package/vendor/ds/kits/base/src/label.variants.ts

@@ -0,0 +1,8 @@
+// Label's token-only appearance seam. Association stays native through `for`.
+import { tv, type VariantProps } from "tailwind-variants";
+
+export const label = tv({
+  base: "text-sm font-medium text-foreground",
+});
+
+export type LabelVariants = VariantProps<typeof label>;

package/vendor/ds/kits/base/src/link-preview.variants.ts

@@ -0,0 +1,10 @@
+import { tv, type VariantProps } from "tailwind-variants";
+import { popover } from "./popover.variants";
+
+/** Link previews reuse the canonical anchored surface instead of restating it. */
+export const linkPreview = tv({
+  extend: popover,
+  base: "select-text",
+});
+
+export type LinkPreviewVariants = VariantProps<typeof linkPreview>;

package/vendor/ds/kits/base/src/link.variants.ts

@@ -0,0 +1,20 @@
+import { tv, type VariantProps } from "tailwind-variants";
+import { typeRoleMerge } from "./type-roles";
+
+/**
+ * Native-link appearance with a persistent non-colour affordance.
+ *
+ * A link is ink, not accent: foreground text carrying the underline, which
+ * thickens on hover. The Brand red is reserved for the primary action — and in
+ * the light scheme it is the same red as danger, so a red link would read as an
+ * error (DESIGN.md, "Interactive states").
+ */
+export const link = tv({
+  base: [
+    "text-foreground underline decoration-current underline-offset-[var(--reddb-spatial-gap-sm)]",
+    "hover:decoration-2",
+    "focus-visible:rounded-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus",
+  ].join(" "),
+}, typeRoleMerge);
+
+export type LinkVariants = VariantProps<typeof link>;

package/vendor/ds/kits/base/src/list.variants.ts

@@ -0,0 +1,17 @@
+import { tv, type VariantProps } from "tailwind-variants";
+
+const GAP = {
+  sm: "gap-[var(--reddb-spatial-gap-sm)]",
+  md: "gap-[var(--reddb-spatial-gap-md)]",
+  lg: "gap-[var(--reddb-spatial-gap-lg)]",
+} as const;
+
+export const list = tv({
+  base: "flex flex-col",
+  variants: { gap: GAP },
+  defaultVariants: { gap: "md" },
+});
+
+export type ListVariants = VariantProps<typeof list>;
+export type ListGap = NonNullable<ListVariants["gap"]>;
+export const LIST_GAPS = Object.keys(GAP) as readonly ListGap[];

package/vendor/ds/kits/base/src/loading-indicator.variants.ts

@@ -0,0 +1,31 @@
+import { tv, type VariantProps } from "tailwind-variants";
+
+// The spinner is a glyph, so it takes the Icon's Density-responsive size role
+// of the same name: it tightens with the stop instead of holding a fixed step.
+const SIZE = {
+  sm: { spinner: "size-[var(--reddb-spatial-icon-size-sm)]", label: "text-xs" },
+  md: { spinner: "size-[var(--reddb-spatial-icon-size-md)]", label: "text-sm" },
+  lg: { spinner: "size-[var(--reddb-spatial-icon-size-lg)]", label: "text-base" },
+} as const;
+
+export const loadingIndicator = tv({
+  slots: {
+    root: "inline-flex items-center justify-center gap-[var(--reddb-spatial-gap-md)] text-ink-muted",
+    spinner: "motion-safe:animate-spin motion-reduce:animate-pulse text-primary-text",
+    track: "fill-none stroke-current opacity-25 motion-reduce:opacity-50",
+    head: "fill-none stroke-current",
+    label: "leading-tight",
+  },
+  variants: {
+    size: SIZE,
+    labelHidden: {
+      true: { label: "sr-only" },
+      false: { label: "" },
+    },
+  },
+  defaultVariants: { size: "md", labelHidden: false },
+});
+
+export type LoadingIndicatorVariants = VariantProps<typeof loadingIndicator>;
+export type LoadingIndicatorSize = NonNullable<LoadingIndicatorVariants["size"]>;
+export const LOADING_INDICATOR_SIZES = Object.keys(SIZE) as readonly LoadingIndicatorSize[];

package/vendor/ds/kits/base/src/logo.box.ts

@@ -0,0 +1,128 @@
+// The Logo's physics: clearspace and minimum size, as arithmetic.
+//
+// ADR 0004 settled that these are the component's physics and not its
+// documentation — "the Logo's box includes the clearspace intrinsically and
+// below-minimum is a dev error. No opt-out prop; a legitimate exception must
+// be written by the Brand first." That has one mechanical consequence, and it
+// is the whole of this module: the box a caller lays out is mark + clearspace,
+// so a caller cannot place something inside the clearspace by accident, and
+// cannot ask for the mark without it at all.
+//
+// Everything is measured against the SYMBOL — the red glyph — because the
+// symbol is the same drawing in every layout. Clearspace is 25% of its height;
+// the minimum is a floor under its height. One rule, three layouts, and no
+// per-layout numbers to keep in step: the stacked Mark's minimum is taller
+// than the horizontal one's only because its symbol is a smaller share of it.
+//
+// These are lengths in CSS pixels rather than tokens, and deliberately so. A
+// Theme reassigns colour; a density stop reassigns the space a component holds
+// inside itself (ADR 0003). Clearspace is neither — it is a proportion of the
+// Brand's drawing, fixed by the licence, and a stop that shrank it would be
+// shrinking the Brand's own margin.
+
+import type { Mark } from "./logo.marks";
+
+/** Clearspace is 25% of the symbol's height (ADR 0004). */
+export const CLEARSPACE_RATIO = 0.25;
+
+/**
+ * The floor under the symbol, in CSS pixels. Below it the wordmark's counters
+ * close up and the notch in the symbol stops reading, so it is an error rather
+ * than a smaller Logo.
+ */
+export const MINIMUM_SYMBOL_PX = 16;
+
+/** What `size` means when a caller does not say: comfortable, not minimal. */
+export const DEFAULT_SYMBOL_PX = 32;
+
+/** The Logo's laid-out geometry, in CSS pixels. */
+export interface LogoBox {
+  /** The symbol's height — the size the caller asked for. */
+  symbol: number;
+  /** Clearspace on every side. */
+  clearspace: number;
+  /** The Mark itself, inside the clearspace. */
+  markWidth: number;
+  markHeight: number;
+  /** The component's own box: the Mark plus clearspace on all four sides. */
+  width: number;
+  height: number;
+}
+
+/**
+ * The refusal for a Logo asked to render below the minimum.
+ *
+ * ADR 0004 calls it a dev error, and an error is what it is: a Logo that
+ * renders illegibly is worse than a page with a hole in it, because nobody
+ * files the second one as a bug against the DS.
+ */
+export class LogoTooSmallError extends Error {
+  /** The symbol height that was asked for, in CSS pixels. */
+  readonly size: number;
+  /** The floor it fell under. */
+  readonly minimum: number;
+
+  constructor(size: number, minimum: number = MINIMUM_SYMBOL_PX) {
+    super(
+      `Logo: size=${size} would render the symbol at ${size}px, below the ${minimum}px minimum.\n` +
+        "Minimum size is the component's physics, not its documentation (ADR 0004): there is no " +
+        "opt-out prop, because a legitimate exception has to be written by the Brand first.\n" +
+        `Ask for size=${minimum} or larger, or use a layout whose symbol carries at this size.`,
+    );
+    this.name = "LogoTooSmallError";
+    this.size = size;
+    this.minimum = minimum;
+  }
+}
+
+/**
+ * The box `mark` occupies when its symbol is `size` pixels tall.
+ *
+ * Throws rather than clamping when `size` is below the minimum or is not a
+ * usable length: clamping would render a Logo nobody asked for, and silence is
+ * how a below-minimum Logo ships.
+ */
+export function logoBox(mark: Mark, size: number = DEFAULT_SYMBOL_PX): LogoBox {
+  if (!Number.isFinite(size) || size <= 0) {
+    throw new LogoTooSmallError(size);
+  }
+  if (size < MINIMUM_SYMBOL_PX) {
+    throw new LogoTooSmallError(size);
+  }
+
+  // The symbol is a share of the drawing's height, so the drawing scales by
+  // the ratio between them — which is what keeps one `size` meaning the same
+  // thing across layouts whose proportions differ.
+  const scale = size / mark.symbolHeight;
+  const markWidth = mark.width * scale;
+  const markHeight = mark.height * scale;
+  const clearspace = size * CLEARSPACE_RATIO;
+
+  return {
+    symbol: size,
+    clearspace,
+    markWidth,
+    markHeight,
+    width: markWidth + clearspace * 2,
+    height: markHeight + clearspace * 2,
+  };
+}
+
+/**
+ * The smallest `size` a Mark may be placed at. One number for every Mark,
+ * because the floor is under the symbol and the symbol is shared.
+ */
+export function minimumSize(): number {
+  return MINIMUM_SYMBOL_PX;
+}
+
+/**
+ * A length as CSS, rounded to a resolution finer than a device pixel.
+ *
+ * The Marks' viewBoxes carry three decimals, so the arithmetic above produces
+ * numbers like 120.62144 — real, and not worth the bytes. Rounding here rather
+ * than in `logoBox` keeps the box exact for anyone computing with it.
+ */
+export function px(length: number): string {
+  return `${Math.round(length * 1000) / 1000}px`;
+}

package/vendor/ds/kits/base/src/logo.marks.ts

@@ -0,0 +1,248 @@
+// The Marks the Logo may place, and the refusal when it may not.
+//
+// The Brand owns the drawing; the DS owns only the placement (ADR 0004). So
+// this module enumerates what the pinned Assets release ships and nothing
+// else: five layouts, two surfaces, and one hole where the release ships no
+// Mark. It never composes, recolors or substitutes a Mark — the asset licence
+// binds that literally, and a variant that does not exist upstream is a Brand
+// proposal, not a local file.
+//
+// A Mark is reached by importing the file, so it stays opaque bytes the whole
+// way through: the bundler emits the SVG as an asset and hands back its URL,
+// which is what the Logo renders as an <img>. Nothing here parses the drawing,
+// and no code path can alter it — "reproduced unaltered" is therefore a
+// property of how the Logo works rather than a rule someone has to follow.
+//
+// `on` names the SURFACE behind the Mark, never the Theme: a dark hero on a
+// light marketing page takes `on="dark"` under the light Color Scheme, which is
+// exactly the case ADR 0004 fixed the prop for.
+
+import horizontalColor from "./marks/reddb-horizontal-color.svg";
+import horizontalInverse from "./marks/reddb-horizontal-inverse.svg";
+import iconColor from "./marks/reddb-icon-color.svg";
+import stackedColor from "./marks/reddb-stacked-color.svg";
+import stackedInverse from "./marks/reddb-stacked-inverse.svg";
+import symbolBlack from "./marks/reddb-symbol-black.svg";
+import symbolColor from "./marks/reddb-symbol-color.svg";
+import symbolKnockout from "./marks/reddb-symbol-knockout.svg";
+import symbolWhite from "./marks/reddb-symbol-white.svg";
+import wordmarkBlack from "./marks/reddb-wordmark-black.svg";
+import wordmarkWhite from "./marks/reddb-wordmark-white.svg";
+
+/**
+ * The pinned Brand Assets release these Marks came from
+ * (`vendor/brand/brand.lock.json`).
+ *
+ * Written here as a literal because a Kit is vendorable source with no build
+ * step and no lock to read at runtime — and kept honest rather than
+ * remembered: `test/marks.test.ts` fails when it drifts from the lock, which
+ * is the same edit re-vendoring makes anyway.
+ */
+export const BRAND_RELEASE = "2026.10";
+
+/** How the Mark is laid out. */
+export const LOGO_LAYOUTS = ["horizontal", "stacked", "icon", "symbol", "wordmark"] as const;
+export type LogoLayout = (typeof LOGO_LAYOUTS)[number];
+
+/**
+ * The surface the Mark sits on — the local background, not the global Theme.
+ * `light` takes the color Mark, `dark` takes the inverse one.
+ */
+export const LOGO_SURFACES = ["light", "dark"] as const;
+export type LogoSurface = (typeof LOGO_SURFACES)[number];
+
+/** One Mark as the release published it. */
+export interface Mark {
+  /** File name, exactly as the release names it. */
+  file: string;
+  /** The URL the bundler emitted for the file. */
+  src: string;
+  /** The drawing's own width, from its viewBox. */
+  width: number;
+  /** The drawing's own height, from its viewBox. */
+  height: number;
+  /**
+   * How much of that height the SYMBOL — the red glyph — occupies.
+   *
+   * The symbol is the same drawing in every layout, which is what makes it the
+   * thing to measure: clearspace is 25% of symbol height (ADR 0004), and one
+   * minimum on the symbol gives every lockup a minimum without several numbers
+   * anyone has to keep in step. In the horizontal, icon and symbol Marks the
+   * symbol spans the full height; in the stacked one it sits above the
+   * wordmark and occupies 100 of the drawing's 154.423 units. The standalone
+   * wordmark has no symbol, so its own 71.4-unit ink box is the sizing
+   * reference.
+   */
+  symbolHeight: number;
+}
+
+/**
+ * Every Mark the pinned release ships, by layout and surface.
+ *
+ * The hole is the point: `icon` has no `dark` entry because the release
+ * publishes no `reddb-icon-inverse.svg`. It is left absent rather than filled
+ * with the color Mark, so the gap is a fact the type system and the refusal
+ * both read off one place.
+ */
+export const MARKS: Readonly<Record<LogoLayout, Partial<Record<LogoSurface, Mark>>>> = {
+  horizontal: {
+    light: {
+      file: "reddb-horizontal-color.svg",
+      src: horizontalColor,
+      width: 397.712,
+      height: 100,
+      symbolHeight: 100,
+    },
+    dark: {
+      file: "reddb-horizontal-inverse.svg",
+      src: horizontalInverse,
+      width: 397.712,
+      height: 100,
+      symbolHeight: 100,
+    },
+  },
+  stacked: {
+    light: {
+      file: "reddb-stacked-color.svg",
+      src: stackedColor,
+      width: 140,
+      height: 154.423,
+      symbolHeight: 100,
+    },
+    dark: {
+      file: "reddb-stacked-inverse.svg",
+      src: stackedInverse,
+      width: 140,
+      height: 154.423,
+      symbolHeight: 100,
+    },
+  },
+  icon: {
+    light: {
+      file: "reddb-icon-color.svg",
+      src: iconColor,
+      width: 100,
+      height: 100,
+      symbolHeight: 100,
+    },
+    // No `dark`: the pinned release ships no icon inverse. The chatbot avatar
+    // on a dark surface is blocked here until the Brand ships one (ADR 0004).
+  },
+  symbol: {
+    // The Brand names these two single-colour variants by their intended
+    // grounds: black for light, white for dark. `color` is the primary
+    // treatment and `knockout` describes transparency, not a third kind of
+    // surface, so neither distorts the `on` vocabulary.
+    light: {
+      file: "reddb-symbol-black.svg",
+      src: symbolBlack,
+      width: 100,
+      height: 100,
+      symbolHeight: 100,
+    },
+    dark: {
+      file: "reddb-symbol-white.svg",
+      src: symbolWhite,
+      width: 100,
+      height: 100,
+      symbolHeight: 100,
+    },
+  },
+  wordmark: {
+    light: {
+      file: "reddb-wordmark-black.svg",
+      src: wordmarkBlack,
+      width: 308.3,
+      height: 71.4,
+      symbolHeight: 71.4,
+    },
+    dark: {
+      file: "reddb-wordmark-white.svg",
+      src: wordmarkWhite,
+      width: 308.3,
+      height: 71.4,
+      symbolHeight: 71.4,
+    },
+  },
+};
+
+/**
+ * Every SVG drawing the pinned release publishes.
+ *
+ * Most are selected by layout and surface through `MARKS`. The color symbol
+ * and knockout symbol are treatments rather than surfaces: they belong in the
+ * catalogue and ship byte-identically with the Kit, but do not invent a third
+ * `on` value or silently displace the Brand's explicit black/light and
+ * white/dark mapping.
+ */
+export const MARK_CATALOGUE: readonly Mark[] = [
+  ...LOGO_LAYOUTS.flatMap((layout) =>
+    LOGO_SURFACES.map((on) => MARKS[layout][on]).filter(
+      (mark): mark is Mark => mark !== undefined,
+    ),
+  ),
+  {
+    file: "reddb-symbol-color.svg",
+    src: symbolColor,
+    width: 100,
+    height: 100,
+    symbolHeight: 100,
+  },
+  {
+    file: "reddb-symbol-knockout.svg",
+    src: symbolKnockout,
+    width: 100,
+    height: 100,
+    symbolHeight: 100,
+  },
+];
+
+/**
+ * The refusal: the Logo was asked for a Mark the pinned release does not ship.
+ *
+ * It names the gap and the release, because those are the two things whoever
+ * hits it needs — what is missing, and which release it is missing from — and
+ * because the fix is upstream: the message is the first draft of the Brand
+ * proposal.
+ */
+export class MarkNotShippedError extends Error {
+  /** The layout that was asked for. */
+  readonly layout: LogoLayout;
+  /** The surface it was asked for. */
+  readonly on: LogoSurface;
+  /** The Assets release that ships no such Mark. */
+  readonly release: string;
+
+  constructor(layout: LogoLayout, on: LogoSurface, release: string = BRAND_RELEASE) {
+    const alternatives = LOGO_LAYOUTS.filter((other) => MARKS[other][on] !== undefined);
+    super(
+      `Logo: the pinned Brand Assets release ${release} ships no ${layout} Mark for a ${on} surface.\n` +
+        "The Logo refuses rather than falling back to the other surface's Mark or recoloring one: " +
+        "the Brand owns the drawing and the DS owns only its placement (ADR 0004), so a variant " +
+        "that does not exist upstream is a Brand proposal, not a local file.\n" +
+        `Until the Brand ships it, place the ${layout} Mark on the surface it has ` +
+        `(on="${on === "dark" ? "light" : "dark"}"), or use ` +
+        `${alternatives.map((other) => `layout="${other}"`).join(" or ")} on a ${on} surface.`,
+    );
+    this.name = "MarkNotShippedError";
+    this.layout = layout;
+    this.on = on;
+    this.release = release;
+  }
+}
+
+/**
+ * The Mark for one layout on one surface, or a loud refusal when the release
+ * ships none. Never falls back, never invents: those are the two failures the
+ * licence forbids, so neither has a code path here.
+ */
+export function selectMark(layout: LogoLayout, on: LogoSurface): Mark {
+  const mark = MARKS[layout][on];
+  if (mark === undefined) throw new MarkNotShippedError(layout, on);
+  return mark;
+}
+
+/** Does the pinned release ship a Mark for this layout on this surface? */
+export function shipsMark(layout: LogoLayout, on: LogoSurface): boolean {
+  return MARKS[layout][on] !== undefined;
+}

package/vendor/ds/kits/base/src/logo.surface.ts

@@ -0,0 +1,45 @@
+// Which surface the Logo sits on when the caller does not say.
+//
+// ADR 0004's `on="light" | "dark"` names the surface behind the Mark. The
+// Color Scheme, not the directional Theme, is the document-level signal that
+// answers that contrast question. A local surface still uses `on` explicitly.
+
+import { LOGO_SURFACES, type LogoSurface } from "./logo.marks";
+
+/** The attribute the Color Scheme selectors key on. */
+export const COLOR_SCHEME_ATTRIBUTE = "data-color-scheme";
+
+/** The surface a Color Scheme implies. Anything unrecognised is light. */
+export function surfaceOfColorScheme(scheme: string | null | undefined): LogoSurface {
+  return scheme === "dark" ? "dark" : "light";
+}
+
+/** The surface implied by the active Color Scheme on `doc`. */
+export function activeSurface(doc: Document | null | undefined = globalThis.document): LogoSurface {
+  if (!doc) return "light";
+  return surfaceOfColorScheme(doc.documentElement.getAttribute(COLOR_SCHEME_ATTRIBUTE));
+}
+
+/**
+ * Observe root Color Scheme changes and report their implied Logo surface.
+ * Returns a cleanup function; without a browser it reports once and is inert.
+ */
+export function observeActiveSurface(
+  report: (surface: LogoSurface) => void,
+  doc: Document | null | undefined = globalThis.document,
+): () => void {
+  report(activeSurface(doc));
+  const Observer = doc?.defaultView?.MutationObserver;
+  if (!doc || !Observer) return () => {};
+  const observer = new Observer(() => report(activeSurface(doc)));
+  observer.observe(doc.documentElement, {
+    attributes: true,
+    attributeFilter: [COLOR_SCHEME_ATTRIBUTE],
+  });
+  return () => observer.disconnect();
+}
+
+/** Is `value` a surface the Logo knows? */
+export function isLogoSurface(value: unknown): value is LogoSurface {
+  return typeof value === "string" && (LOGO_SURFACES as readonly string[]).includes(value);
+}