@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/contact/ContactMailto.tsx

@@ -0,0 +1,112 @@
+/**
+ * ContactMailto — the shared Cloudflare-safe `mailto:` link, promoted from
+ * the three forks that grew one per app (`apps/digithings-web`,
+ * `apps/digiquant-web`, `apps/digichat`, issues #2220/#2226).
+ *
+ * Cloudflare's Email Address Obfuscation (Scrape Shield) rewrites any
+ * literal `mailto:` href — and any bare visible address — in the HTML it
+ * actually serves, so React's hydration payload disagrees with the real DOM.
+ * This component renders with no literal `mailto:` string or bare address in
+ * the initial HTML at all (no href server-side; the real href — and, for
+ * `showAddress`, the address text — assigned after the hydration-safe client
+ * mount flag flips), giving the edge rewriter nothing to rewrite.
+ *
+ * Real users with JS get a working mailto: link; without JS the link is
+ * inert (dimmed, aria-disabled). `showAddress` callers must still pass
+ * `children` — the server-rendered fallback text and accessible name until
+ * the mount swap. Omitting `children` entirely leaves the link empty until
+ * JS runs: acceptable only on JS-required surfaces (the digichat embed),
+ * never on static marketing pages.
+ *
+ * Utility-classed (pending dim only); consuming apps need an `@source` line
+ * for this directory (MIGRATION.md rule 3).
+ */
+"use client";
+
+import { useCallback, useSyncExternalStore } from "react";
+import type { CSSProperties, MouseEvent, ReactNode } from "react";
+
+import { cx } from "../../lib/cx";
+
+/** Pure so the query-string assembly is unit-testable without rendering. */
+export function buildMailtoHref(email: string, subject?: string): string {
+  const query = subject ? `?subject=${subject}` : "";
+  return `mailto:${email}${query}`;
+}
+
+// Baked into the JSX unconditionally rather than a new app-local CSS class —
+// the frontend canon guard's family census rejects new classes in census
+// app stylesheets; token-backed Tailwind utilities are not scanned.
+const PENDING_CLASSES = ["opacity-50", "cursor-default"] as const;
+
+const emptySubscribe = () => () => {};
+const getMountedSnapshot = () => true;
+const getServerSnapshot = () => false;
+
+export function ContactMailto({
+  email,
+  subject,
+  showAddress = false,
+  className,
+  style,
+  ariaLabel,
+  children,
+}: {
+  /** Appended as `?subject=<subject>` verbatim — callers pass it already
+   *  URL-encoded. */
+  email: string;
+  subject?: string;
+  /** Swap `children` for the address itself once mounted, rather than
+   *  passing the address as `children` directly (which would bake the bare
+   *  address into the server-rendered text node). `children` is still
+   *  required on static pages: the fallback text and accessible name. */
+  showAddress?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  ariaLabel?: string;
+  children?: ReactNode;
+}) {
+  // Server + first client hydration pass: false. After hydration: true.
+  // useSyncExternalStore, not setState-in-effect.
+  const mounted = useSyncExternalStore(
+    emptySubscribe,
+    getMountedSnapshot,
+    getServerSnapshot,
+  );
+
+  if (
+    process.env.NODE_ENV !== "production" &&
+    showAddress &&
+    children == null
+  ) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "ContactMailto with showAddress and no children renders an empty, " +
+        "unlabeled link until JS runs — pass fallback children on static pages.",
+    );
+  }
+
+  const readyHref = mounted ? buildMailtoHref(email, subject) : null;
+  const addressText = mounted && showAddress ? email : null;
+  const pending = !mounted;
+
+  const onClick = useCallback(
+    (e: MouseEvent<HTMLAnchorElement>) => {
+      if (pending) e.preventDefault();
+    },
+    [pending],
+  );
+
+  return (
+    <a
+      {...(readyHref ? { href: readyHref } : {})}
+      className={cx(className, pending && PENDING_CLASSES.join(" "))}
+      style={style}
+      aria-label={ariaLabel}
+      aria-disabled={pending ? true : undefined}
+      onClick={onClick}
+    >
+      {addressText ?? children}
+    </a>
+  );
+}

package/src/components/contact/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Contact family barrel — the Cloudflare-safe mailto link. Re-exported
+ * from the package barrel (src/index.ts).
+ */
+export { ContactMailto, buildMailtoHref } from "./ContactMailto";

package/src/components/conviction/ConvictionMeter.tsx

@@ -0,0 +1,40 @@
+/**
+ * ConvictionMeter — the single canonical UNSIGNED conviction encoding,
+ * promoted from `apps/dashboard/components/shared/conviction-meter.tsx`
+ * (dashboard F6 ruling, preserved verbatim): integer pips (max 3 for
+ * `positions.conviction`, max 4 for pre-scaled `theses.confidence`), filled
+ * pips `--accent`, empty pips `--hair`, accent the only color on its row
+ * (F5). Value is clamped and rounded; the redundant `aria-label` + `sr-only`
+ * pair and `data-filled` attributes are preserved for testability.
+ *
+ * Utility-classed (no family CSS); consuming apps need an `@source` line
+ * for this directory (MIGRATION.md rule 3).
+ */
+export function ConvictionMeter({
+  value,
+  max = 3,
+  srLabel,
+}: {
+  value: number;
+  max?: number;
+  srLabel: string;
+}) {
+  const filled = Math.max(0, Math.min(max, Math.round(value)));
+  return (
+    <span className="inline-flex items-center gap-1" role="img" aria-label={srLabel}>
+      {Array.from({ length: max }).map((_, i) => {
+        const isFilled = i < filled;
+        return (
+          <span
+            key={i}
+            data-filled={isFilled ? "true" : "false"}
+            className={`h-1.5 w-1.5 rounded-full ${
+              isFilled ? "bg-accent" : "bg-hair"
+            }`}
+          />
+        );
+      })}
+      <span className="sr-only">{srLabel}</span>
+    </span>
+  );
+}

package/src/components/conviction/SignedConvictionBadge.tsx

@@ -0,0 +1,26 @@
+/**
+ * SignedConvictionBadge — the SIGNED stance badge, promoted from
+ * `apps/dashboard/components/shared/signed-conviction-badge.tsx`
+ * (dashboard F6 ruling, logic verbatim): `decision_log.conviction`
+ * (−5..+5; maps to `AnalystPayload.conviction_score`, ge=-5 le=5 — render
+ * any signed int, do NOT clamp). Up-toned at zero and above, down-toned
+ * below zero: the strict signed-financial-value semantic (F5), never to be
+ * merged with the unsigned ConvictionMeter even when the two share a row.
+ * One intentional deviation from the dashboard source: `rounded-none` pins
+ * the utilitarian radius rule (visually no-op under preflight).
+ *
+ * Utility-classed (no family CSS); consuming apps need an `@source` line
+ * for this directory (MIGRATION.md rule 3).
+ */
+export function SignedConvictionBadge({ value }: { value: number }) {
+  const sign = value < 0 ? "−" : "+";
+  const tone = value < 0 ? "text-down border-down/35" : "text-up border-up/35";
+  return (
+    <span
+      className={`inline-flex items-center rounded-none border px-1.5 py-0.5 font-mono text-[11px] font-semibold tabular-nums ${tone}`}
+    >
+      {sign}
+      {Math.abs(value)}
+    </span>
+  );
+}

package/src/components/conviction/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Conviction family barrel — the dashboard F6 vocabulary (unsigned meter +
+ * signed badge), promoted verbatim. Re-exported from the package barrel
+ * (src/index.ts).
+ */
+export { ConvictionMeter } from "./ConvictionMeter";
+export { SignedConvictionBadge } from "./SignedConvictionBadge";

package/src/components/data-layout/BentoGrid.tsx

@@ -0,0 +1,52 @@
+import type { ReactNode } from "react";
+
+/**
+ * BentoGrid + BentoCell — the asymmetric bento layout promoted from the design
+ * reference (layout-patterns/bento-grid): a 4-column grid where cell weight
+ * signals hierarchy — `hero` anchors 2×2, `wide` runs two columns, `tall` two
+ * rows, `unit` takes one. Each cell may scope a module livery (`accent-<id>`,
+ * declared in @digithings-ai/design/tokens.css) that tints the ::before hover
+ * hairline and the hero wash (styles/data-layout.css). Content is entirely
+ * children-driven — the cell only owns the frame; a heading inside a hero cell
+ * should carry the `bento-name` class to pick up the hero's larger type.
+ * Collapses to one column below 760px. Server components — no state.
+ *
+ * Wiring (in the consuming app):
+ *   globals.css   @import "@digithings-ai/ui/styles/data-layout.css";
+ *                 @source "<path-to>/packages/ui/src/components/data-layout";
+ */
+export type BentoSpan = "hero" | "wide" | "tall" | "unit";
+
+export function BentoGrid({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}) {
+  return <div className={`bento-grid${className ? ` ${className}` : ""}`}>{children}</div>;
+}
+
+export function BentoCell({
+  span = "unit",
+  livery,
+  className,
+  children,
+}: {
+  /** Cell weight — hero 2×2, wide 2×1, tall 1×2, unit 1×1. */
+  span?: BentoSpan;
+  /** Optional module livery scope — suffix of an `accent-<module>` class. */
+  livery?: string;
+  className?: string;
+  children: ReactNode;
+}) {
+  return (
+    <article
+      className={`bento-cell flex flex-col justify-between rounded-none border border-hair p-[1.1rem] bento-${span}${
+        livery ? ` accent-${livery}` : ""
+      }${className ? ` ${className}` : ""}`}
+    >
+      {children}
+    </article>
+  );
+}

package/src/components/data-layout/CardRail.tsx

@@ -0,0 +1,150 @@
+"use client";
+
+import { Children, useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+import { IconButton } from "../../ui";
+import { cn } from "../../lib/utils";
+import { clamp, nearestIndex } from "../effects-chrome/horizontal-track-core";
+
+/**
+ * CardRail — a horizontal rail of cards on NATIVE scroll-snap: swipe, wheel,
+ * arrow keys, or the prev / next buttons (one card per press). Edge fades read
+ * the strip as continuing past the frame. No pin, no transform, no JS needed to
+ * scroll — the buttons are an enhancement over a fully working native rail.
+ *
+ * Re-authored from the design reference's changelog rail (and the refactor
+ * branch's rail) as a utilities-only part: no CSS sheet, no `.cr-*` classes.
+ * The edge fade is a mask over token stops (alpha only, no raw colour).
+ *
+ * Each child is wrapped in a `role="listitem"` snap target. The wrapper carries
+ * `data-active="true"` on the card at the leading edge (a `group/card`, so a
+ * child can style `group-data-[active=true]/card:border-accent` without the rail
+ * knowing anything about it). The wrapper is not a tab stop — put links and
+ * buttons inside the cards; focusing one scrolls the rail natively. The track
+ * itself is focusable so a keyboard user can scroll it with the arrow keys.
+ *
+ * Reveal-safe: the track carries vertical padding so a `Reveal` child's rise
+ * (translateY) is not clipped by the rail's overflow, and wrappers never
+ * transform. With no JS and under reduced motion every card is reachable.
+ *
+ * Stepping is instant under `prefers-reduced-motion` (CSS `scroll-behavior`
+ * smooth is applied only when motion is allowed).
+ *
+ * Wiring (in the consuming app):
+ *   globals.css   @source "<path-to>/packages/ui/src/components/data-layout";
+ */
+export type CardRailProps = {
+  /** The cards. Each direct child becomes one snap item. */
+  children: ReactNode;
+  /** Accessible name for the scroll region, e.g. "Strategy tearsheets". */
+  ariaLabel: string;
+  /** Left of the prev / next buttons (a title, a count). */
+  header?: ReactNode;
+  /** Classes on each snap-item wrapper (sets the card width). */
+  itemClassName?: string;
+  /** Classes on the outermost element. */
+  className?: string;
+  /** Accessible names for the two buttons. */
+  prevLabel?: string;
+  nextLabel?: string;
+};
+
+// Alpha stops through a token — a mask reads alpha only, so no raw colour.
+const FADE =
+  "[mask-image:linear-gradient(90deg,transparent,var(--ink)_1.5rem,var(--ink)_calc(100%_-_1.5rem),transparent)]";
+
+function offsetsOf(track: HTMLElement): number[] {
+  const kids = Array.from(track.children).filter((c): c is HTMLElement => c instanceof HTMLElement);
+  const base = kids[0]?.offsetLeft ?? 0;
+  return kids.map((k) => k.offsetLeft - base);
+}
+
+export function CardRail({
+  children,
+  ariaLabel,
+  header,
+  itemClassName,
+  className,
+  prevLabel = "Previous card",
+  nextLabel = "Next card",
+}: CardRailProps) {
+  const trackRef = useRef<HTMLDivElement | null>(null);
+  const items = Children.toArray(children);
+  const [active, setActive] = useState(0);
+  const [atStart, setAtStart] = useState(true);
+  const [atEnd, setAtEnd] = useState(false);
+
+  const sync = useCallback(() => {
+    const el = trackRef.current;
+    if (!el) return;
+    setAtStart(el.scrollLeft <= 1);
+    setAtEnd(el.scrollLeft + el.clientWidth >= el.scrollWidth - 1);
+    setActive(nearestIndex(offsetsOf(el), el.scrollLeft));
+  }, []);
+
+  useEffect(() => {
+    const el = trackRef.current;
+    if (!el) return;
+    sync();
+    el.addEventListener("scroll", sync, { passive: true });
+    const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(sync);
+    observer?.observe(el);
+    return () => {
+      el.removeEventListener("scroll", sync);
+      observer?.disconnect();
+    };
+  }, [sync, items.length]);
+
+  const step = (direction: 1 | -1) => {
+    const el = trackRef.current;
+    if (!el) return;
+    const offsets = offsetsOf(el);
+    const next = clamp(active + direction, 0, offsets.length - 1);
+    el.scrollTo({ left: offsets[next] ?? 0 });
+  };
+
+  return (
+    <div className={cn("grid min-w-0 gap-3", className)} data-card-rail="">
+      <div className="flex items-end justify-between gap-4">
+        <div className="min-w-0">{header}</div>
+        <div className="flex shrink-0 gap-[0.4rem]">
+          <IconButton
+            aria-label={prevLabel}
+            onClick={() => step(-1)}
+            disabled={atStart}
+            className="border border-hair"
+          >
+            <span aria-hidden="true">{"←"}</span>
+          </IconButton>
+          <IconButton
+            aria-label={nextLabel}
+            onClick={() => step(1)}
+            disabled={atEnd}
+            className="border border-hair"
+          >
+            <span aria-hidden="true">{"→"}</span>
+          </IconButton>
+        </div>
+      </div>
+      <div className={cn("min-w-0", FADE)}>
+        <div
+          ref={trackRef}
+          role="list"
+          aria-label={ariaLabel}
+          tabIndex={0}
+          className="flex snap-x snap-mandatory gap-4 overflow-x-auto scroll-ps-6 px-6 py-4 outline-none [scrollbar-width:none] motion-safe:scroll-smooth focus-visible:outline focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-accent [&::-webkit-scrollbar]:hidden"
+        >
+          {items.map((child, i) => (
+            <div
+              key={i}
+              role="listitem"
+              data-active={i === active ? "true" : undefined}
+              className={cn("group/card relative flex-none snap-start w-[min(82vw,17rem)]", itemClassName)}
+            >
+              {child}
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/data-layout/DotMatrixStat.tsx

@@ -0,0 +1,65 @@
+/**
+ * DotMatrixStat — a single metric rendered as a hardware-style LED grid,
+ * promoted from the design reference (data/dot-matrix-stat). A cols×rows
+ * field of dots lights the first N to encode a percentage, paired with a
+ * mono label / value / note column. The lit dots wear the module accent
+ * (scope with an `accent-<module>` livery class via className) and glow.
+ * The dot field is pure CSS/DOM — no canvas — and decorative (aria-hidden);
+ * the value is real text. Server component — no state, no effects.
+ *
+ * Wiring (in the consuming app):
+ *   globals.css   @import "@digithings-ai/ui/styles/data-layout.css";
+ *                 @source "<path-to>/packages/ui/src/components/data-layout";
+ */
+export type DotMatrixStatProps = {
+  /** Mono micro-caps label above the value — "Signal confidence". */
+  label: string;
+  /** The figure itself, preformatted — "67%". */
+  value: string;
+  /** Percentage of the field to light, 0–100. */
+  percent: number;
+  /** One quiet sentence under the value. */
+  note?: string;
+  /** Dot columns in the LED field. */
+  cols?: number;
+  /** Dot rows in the LED field. */
+  rows?: number;
+  className?: string;
+};
+
+export function DotMatrixStat({
+  label,
+  value,
+  percent,
+  note,
+  cols = 12,
+  rows = 8,
+  className,
+}: DotMatrixStatProps) {
+  const total = cols * rows;
+  const lit = Math.min(total, Math.max(0, Math.round((percent / 100) * total)));
+  return (
+    <div
+      className={`grid grid-cols-[180px_1fr] gap-[1.1rem] rounded-none border border-hair bg-surface p-[1.1rem] max-[900px]:grid-cols-1${
+        className ? ` ${className}` : ""
+      }`}
+    >
+      <div
+        className="dms-grid"
+        style={{ gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))` }}
+        aria-hidden="true"
+      >
+        {Array.from({ length: total }, (_, i) => (
+          <span key={i} className={i < lit ? "dms-dot on" : "dms-dot"} />
+        ))}
+      </div>
+      <div>
+        <p className="font-mono text-[0.72rem] uppercase tracking-[0.08em] text-ink-mute">
+          {label}
+        </p>
+        <p className="mt-[0.2rem] font-mono text-[clamp(2rem,5vw,2.8rem)]">{value}</p>
+        {note ? <p className="mt-[0.55rem] max-w-[50ch] text-ink-soft">{note}</p> : null}
+      </div>
+    </div>
+  );
+}

package/src/components/data-layout/FeatureCell.tsx

@@ -0,0 +1,80 @@
+import type { ReactNode } from "react";
+
+/**
+ * FeatureCell — the universal feature block promoted from the design reference
+ * (layout-patterns/feature-cell), the structure that repeats across graphite /
+ * cursor / x.ai and every band we ship: eyebrow → a short outcome headline →
+ * one sentence of mechanism → a quiet link → the product visual (children —
+ * typically a <ProductFrame/>). Each cell may scope a module livery
+ * (`accent-<module>`) that tints the eyebrow and link. Stack cells as direct
+ * siblings and even-numbered ones swap copy/visual columns automatically
+ * (`:nth-child(even)` in styles/data-layout.css); everything collapses to one
+ * column below 760px. Server component — no state, no effects.
+ *
+ * Wiring (in the consuming app):
+ *   globals.css   @import "@digithings-ai/ui/styles/data-layout.css";
+ *                 @source "<path-to>/packages/ui/src/components/data-layout";
+ */
+export type FeatureCellProps = {
+  /** Mono micro-caps eyebrow above the headline — "research". */
+  eyebrow: string;
+  /** The outcome headline, 4–8 words. */
+  outcome: string;
+  /** One sentence of mechanism under the headline. */
+  mechanism: string;
+  /** Destination of the quiet link; omit to drop the link. */
+  href?: string;
+  /** Link copy. */
+  linkLabel?: string;
+  /** Overrides the link's accessible name — set this when two cells on the
+   *  same page would otherwise share identical link text (and, as in the
+   *  reference demo, an identical href): screen readers announce links by
+   *  their accessible name, so two indistinguishable "Learn more" links
+   *  read as one ambiguous link repeated. */
+  linkAriaLabel?: string;
+  /** Optional module livery scope — suffix of an `accent-<module>` class. */
+  livery?: string;
+  className?: string;
+  /** The product visual — typically a <ProductFrame/> crop. */
+  children?: ReactNode;
+};
+
+export function FeatureCell({
+  eyebrow,
+  outcome,
+  mechanism,
+  href,
+  linkLabel = "Learn more",
+  linkAriaLabel,
+  livery,
+  className,
+  children,
+}: FeatureCellProps) {
+  return (
+    <article
+      className={`fc-cell grid grid-cols-[minmax(0,1fr)_minmax(0,1.1fr)] items-center gap-[1.6rem] rounded-none border border-hair bg-surface p-[1.6rem] max-[760px]:grid-cols-1${
+        livery ? ` accent-${livery}` : ""
+      }${className ? ` ${className}` : ""}`}
+    >
+      <div className="fc-copy">
+        <p className="font-mono text-[0.62rem] uppercase tracking-[0.12em] text-accent">
+          {eyebrow}
+        </p>
+        <h3 className="mt-[0.5rem] font-display font-normal text-[clamp(1.3rem,2.6vw,1.7rem)] tracking-[-0.013em] leading-[1.12] text-ink">
+          {outcome}
+        </h3>
+        <p className="mt-[0.6rem] max-w-[42ch] text-[0.92rem] text-ink-soft">{mechanism}</p>
+        {href ? (
+          <a
+            className="fc-link mt-[0.9rem] inline-block font-mono text-[0.72rem] text-accent no-underline"
+            href={href}
+            aria-label={linkAriaLabel}
+          >
+            {linkLabel} <span aria-hidden="true">→</span>
+          </a>
+        ) : null}
+      </div>
+      {children}
+    </article>
+  );
+}

package/src/components/data-layout/MediaFrame.tsx

@@ -0,0 +1,125 @@
+import { cn } from "../../lib/utils";
+
+/**
+ * MediaFrame — a 16:9 framed artboard for a recording (video) or a still
+ * (image), wearing the terminal chrome: a title row of bracketed micro-labels,
+ * a REQUIRED honesty `badge`, the media, and a caption row. Props-driven and
+ * honest: it shows only the `src` it is given.
+ *
+ * Without `src` it renders a designed placeholder, not a bare dashed box: the
+ * title bar, a faint hairline grid, viewfinder corner ticks, a disabled play
+ * glyph, and the caller's `placeholderLabel` ("recording to come") centred. A
+ * `--:--:--` timecode stands in for a length it does not know.
+ *
+ * With `src` (kind "video", the default) it renders a native `<video>` with
+ * controls, `muted`, `playsInline`, `preload="none"` and the optional `poster`;
+ * it NEVER autoplays, so reduced motion and data-saver users get a still until
+ * they press play. kind "image" renders an `<img>` (alt = caption) instead.
+ *
+ * Utilities-only server component: no CSS sheet, no keyframes, no state, no
+ * motion. Tokens only (grid lines are `--hair`, wash is `--surface`).
+ *
+ * Wiring (in the consuming app):
+ *   globals.css   @source "<path-to>/packages/ui/src/components/data-layout";
+ */
+export type MediaFrameProps = {
+  /** Video (or image) URL. Omit for the placeholder state. */
+  src?: string;
+  /** Poster still for a video. */
+  poster?: string;
+  /** What the media shows — caption row, accessible name, image alt. */
+  caption: string;
+  /** Centred label of the placeholder state, e.g. "recording to come". */
+  placeholderLabel: string;
+  /** Title-row label, e.g. "dashboard walkthrough". */
+  title: string;
+  /** REQUIRED honesty badge in the chrome, e.g. "Placeholder · no recording yet". */
+  badge: string;
+  /** "video" (default) or "image". */
+  kind?: "video" | "image";
+  className?: string;
+};
+
+const CORNER = "pointer-events-none absolute size-3 border-ink-mute";
+
+export function MediaFrame({
+  src,
+  poster,
+  caption,
+  placeholderLabel,
+  title,
+  badge,
+  kind = "video",
+  className,
+}: MediaFrameProps) {
+  return (
+    <figure
+      data-slot="media-frame"
+      data-state={src ? "media" : "placeholder"}
+      className={cn("m-0 min-w-0 border border-hair bg-surface font-mono", className)}
+    >
+      <div className="flex items-center gap-3 border-b border-hair px-3 py-2 text-[0.68rem] tracking-[0.04em] text-ink-mute">
+        <span aria-hidden="true">{kind === "image" ? "[image]" : "[video]"}</span>
+        <span className="min-w-0 flex-1 truncate text-ink-soft">{title}</span>
+        <span className="shrink-0" aria-hidden="true">
+          {src ? "[ready]" : "[empty]"}
+        </span>
+      </div>
+      <div className="border-b border-hair px-3 py-1.5 text-[0.66rem] text-ink-soft" data-slot="media-frame-badge">
+        {`◇ ${badge}`}
+      </div>
+
+      <div className="relative aspect-video w-full overflow-hidden bg-term-bg">
+        {src ? (
+          kind === "image" ? (
+            // Note: plain <img> is intentional — package part, no next/image dependency.
+            // (No next lint plugin runs on packages, so no disable directive here.)
+            <img src={src} alt={caption} className="absolute inset-0 size-full object-cover" />
+          ) : (
+            <video
+              className="absolute inset-0 size-full object-cover"
+              src={src}
+              poster={poster}
+              controls
+              muted
+              playsInline
+              preload="none"
+              aria-label={caption}
+            />
+          )
+        ) : (
+          <div role="img" aria-label={`${placeholderLabel}: ${caption}`} className="absolute inset-0">
+            <div
+              aria-hidden="true"
+              className="absolute inset-0 opacity-50 [background-image:linear-gradient(var(--hair)_1px,transparent_1px),linear-gradient(90deg,var(--hair)_1px,transparent_1px)] [background-size:2.5rem_2.5rem]"
+            />
+            <span aria-hidden="true" className={cn(CORNER, "start-3 top-3 border-s border-t")} />
+            <span aria-hidden="true" className={cn(CORNER, "end-3 top-3 border-e border-t")} />
+            <span aria-hidden="true" className={cn(CORNER, "bottom-3 start-3 border-b border-s")} />
+            <span aria-hidden="true" className={cn(CORNER, "bottom-3 end-3 border-b border-e")} />
+            <div aria-hidden="true" className="absolute inset-0 grid place-content-center justify-items-center gap-3">
+              <button
+                type="button"
+                disabled
+                tabIndex={-1}
+                className="grid size-12 cursor-not-allowed place-items-center border border-hair bg-surface text-[1rem] text-ink-mute opacity-80"
+              >
+                ▶
+              </button>
+              <span className="border border-hair bg-surface px-3 py-1 text-[0.72rem] tracking-[0.06em] text-ink-soft">
+                {`[ ${placeholderLabel} ]`}
+              </span>
+            </div>
+            <span aria-hidden="true" className="absolute bottom-3 start-8 text-[0.62rem] tracking-[0.08em] text-ink-mute">
+              --:--:--
+            </span>
+          </div>
+        )}
+      </div>
+
+      <figcaption className="border-t border-hair px-3 py-2 text-[0.72rem] leading-[1.5] text-ink-soft">
+        {caption}
+      </figcaption>
+    </figure>
+  );
+}