rift-ds 1.4.0 → 1.6.0

package/README.md

@@ -16,7 +16,7 @@ An open source React design system built for AI products and coding agents: comp
 - **One package, zero dependencies.** React is the only required peer dependency; recharts is optional and only for the charts entry. No configuration API, no providers, no build-tool integration: theming is plain CSS custom properties, so it works in any bundler, in any stack, beside anything you already use.
 - **Free, open source, consumed your way.** MIT end to end, no pro tier, no paywalled components. Install the npm package, pull single components as source through the shadcn CLI, or clone the repo and own every line; all three are first-class paths.
 - **A few primitives re-theme everything.** Every semantic token chains to a primitive, so a handful of overrides cascade through every component, the charts, and the ambient background, in both colour modes. Your brand is a short CSS block, not a fork.
-- **The shipped themes prove it.** Each one is the same system under different primitives, saved as a complete look: colour modes, a type pairing with self-hosted fonts, radius, density, motion, elevation, the chart palette. Setting `data-brand` on the root element applies all of it with zero runtime JavaScript, the build holds every theme's action colours to WCAG AA in both modes, and the playground builds yours the same way.
+- **The shipped themes prove it.** Each one is the same system under different primitives, saved as a complete look: colour modes, a type pairing with self-hosted fonts, type weight and tracking, icon weight, radius, density, motion, elevation, the chart palette. Setting `data-brand` on the root element applies all of it with zero runtime JavaScript, the build holds every theme's action colours to WCAG AA in both modes, and the playground builds yours the same way.
 - **The AI product set is in the box.** Composer, streaming chat thread, tool calls, reasoning, thread panel and tabs: the components an assistant UI needs, the same set this repo's own site chat is built from.
 - **Legible to coding agents.** One command installs the agent skill and prints the MCP connect line, and the MCP tools and per-component markdown are generated from the same JSDoc that builds the shipped `.d.ts`: an agent reads the exact contract npm ships, no key, no account.
 - **Docs that cannot lie.** Every count, list, and prop table is generated from source registries and build-validated; CI fails on drift, and every component story ships through an accessibility audit. What the docs say is what ships.
@@ -73,13 +73,13 @@ import 'rift-ds/tokens/presets/presets.css';
 
 ## Components
 
-<!-- component-count -->147<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
+<!-- component-count -->149<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
 
 <details>
 <summary>The full list</summary>
 
 <!-- component-list:start -->
-Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · World map
+Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
 <!-- component-list:end -->
 
 </details>

package/components/AppSidebar/AppSidebar.css

@@ -227,6 +227,12 @@
   flex-shrink: 0;
 }
 
+/* A generated avatar in the icon seat: a block-level sprite, so the seat
+   lays it out as a box rather than on the text baseline. */
+.ds-app-sidebar__btn-icon--avatar {
+  display: inline-flex;
+}
+
 .ds-app-sidebar__btn-label {
   font-family: var(--font-paragraph-emphasis-family);
   font-size: var(--font-paragraph-emphasis-size);

package/components/AppSidebar/AppSidebar.d.ts

@@ -23,8 +23,18 @@ export interface AppSidebarSubItem {
 export interface AppSidebarItem {
     /** Unique key for this item */
     key: string;
-    /** Item icon — Material Symbol name (string) or custom element (ReactNode) */
-    icon: string | React.ReactNode;
+    /** Item icon — Material Symbol name (string) or custom element (ReactNode). Optional only when `pixelAvatar` draws the mark instead */
+    icon?: string | React.ReactNode;
+    /**
+     * Draws a generated PixelAvatar in the icon seat instead of `icon`, for
+     * rows that name a thing rather than a place — projects, workspaces,
+     * accounts. `true` seeds the character from `label`; a string seeds it
+     * from that value, so a renamed item can keep its character by passing a
+     * stable id. The sidebar spreads the inks across all of its avatar rows,
+     * so neighbours differ in colour as well as shape. The character is
+     * decorative: the label beside it is the name
+     */
+    pixelAvatar?: boolean | string;
     /** Display label (shown when expanded) */
     label: string;
     /** Click handler — also fires on a link item, so a consumer can route client-side */

package/components/AppSidebar/AppSidebar.js

@@ -5,9 +5,11 @@ import { useLayer } from "../../behaviors/useLayer.js";
 import { useFocusScope } from "../../behaviors/useFocusScope.js";
 import { useScrollLock } from "../../behaviors/useScrollLock.js";
 import { Avatar } from "../Avatar/Avatar.js";
+import { PixelAvatar } from "../PixelAvatar/PixelAvatar.js";
 import { SidebarPanel } from "../SidebarPanel/SidebarPanel.js";
 import "./AppSidebar.css";
 import "../../fonts/material-symbols.css";
+import { distinctPixelInks } from "../PixelAvatar/pixelInks.js";
 function DefaultLogo() {
   return /* @__PURE__ */ jsxs(
     "svg",
@@ -49,6 +51,14 @@ const AppSidebar = ({
   showMobileTrigger = true
 }) => {
   const baseClass = "ds-app-sidebar";
+  const avatarSeed = (item) => typeof item.pixelAvatar === "string" ? item.pixelAvatar : item.label;
+  const avatarItems = sections.flatMap(
+    (section) => section.items.filter((item) => item.pixelAvatar)
+  );
+  const avatarInks = /* @__PURE__ */ new Map();
+  distinctPixelInks(avatarItems.map(avatarSeed)).forEach((ink, index) => {
+    avatarInks.set(avatarItems[index].key, ink);
+  });
   const [internalExpanded, setInternalExpanded] = useState(defaultExpanded);
   const isExpanded = controlledExpanded ?? internalExpanded;
   const onExpandedChangeRef = useRef(onExpandedChange);
@@ -281,7 +291,7 @@ const AppSidebar = ({
             ].filter(Boolean).join(" ");
             const itemContent = /* @__PURE__ */ jsxs(Fragment, { children: [
               /* @__PURE__ */ jsxs("span", { className: `${baseClass}__btn-left`, children: [
-                /* @__PURE__ */ jsx(
+                item.pixelAvatar ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__btn-icon ${baseClass}__btn-icon--avatar`, children: /* @__PURE__ */ jsx(PixelAvatar, { name: avatarSeed(item), ink: avatarInks.get(item.key) }) }) : /* @__PURE__ */ jsx(
                   "span",
                   {
                     className: `${baseClass}__btn-icon${typeof item.icon === "string" ? " material-symbols-rounded" : ""}`,

package/components/ContextMenu/ContextMenu.css

@@ -114,6 +114,31 @@
   background-color: var(--color-action-passive-bg-hover);
 }
 
+/* States — selected: the current choice of a set. DropdownMenu.css owns
+   the recipe (passive wash held, full-strength text and icon, trailing
+   check); the two menus share the entry model, so they share the look. */
+.ds-context-menu__item--selected {
+  background-color: var(--color-action-passive-bg-hover);
+  color: var(--color-text-primary);
+}
+
+.ds-context-menu__item--selected:hover,
+.ds-context-menu__item--selected.ds-context-menu__item--focused {
+  background-color: var(--color-action-passive-bg-active);
+}
+
+.ds-context-menu__item--selected .ds-context-menu__item-icon {
+  color: var(--color-icon-primary);
+}
+
+.ds-context-menu__check {
+  --icon-size: var(--icon-size-500);
+  color: var(--color-icon-primary);
+  margin-left: auto;
+  flex-shrink: 0;
+  line-height: 1;
+}
+
 /* States — disabled */
 .ds-context-menu__item--disabled {
   opacity: 0.4;

package/components/ContextMenu/ContextMenu.js

@@ -121,14 +121,17 @@ const SubEntry = ({
   const itemClasses = [
     `${baseClass}__item`,
     entry.disabled ? `${baseClass}__item--disabled` : "",
-    entry.destructive ? `${baseClass}__item--destructive` : ""
+    entry.destructive ? `${baseClass}__item--destructive` : "",
+    entry.selected ? `${baseClass}__item--selected` : ""
   ].filter(Boolean).join(" ");
+  const isChoice = entry.selected !== void 0;
   return /* @__PURE__ */ jsxs(
     "li",
     {
       id: itemId,
       className: itemClasses,
-      role: "menuitem",
+      role: isChoice ? "menuitemradio" : "menuitem",
+      "aria-checked": isChoice ? entry.selected : void 0,
       "aria-disabled": entry.disabled || void 0,
       onClick: (e) => {
         e.stopPropagation();
@@ -142,7 +145,8 @@ const SubEntry = ({
           entry.icon && /* @__PURE__ */ jsx("span", { className: `${baseClass}__item-icon material-symbols-rounded`, "aria-hidden": "true", children: entry.icon }),
           entry.label
         ] }),
-        entry.shortcut && /* @__PURE__ */ jsx("span", { className: `${baseClass}__shortcut`, children: entry.shortcut })
+        entry.shortcut && /* @__PURE__ */ jsx("span", { className: `${baseClass}__shortcut`, children: entry.shortcut }),
+        entry.selected && /* @__PURE__ */ jsx("span", { className: `${baseClass}__check material-symbols-rounded`, "aria-hidden": "true", children: "check" })
       ]
     }
   );
@@ -321,14 +325,17 @@ const ContextMenu = React.forwardRef(
         `${baseClass}__item`,
         isFocused ? `${baseClass}__item--focused` : "",
         entry.disabled ? `${baseClass}__item--disabled` : "",
-        entry.destructive ? `${baseClass}__item--destructive` : ""
+        entry.destructive ? `${baseClass}__item--destructive` : "",
+        entry.selected ? `${baseClass}__item--selected` : ""
       ].filter(Boolean).join(" ");
+      const isChoice = entry.selected !== void 0;
       return /* @__PURE__ */ jsxs(
         "li",
         {
           id: `${generatedId}-item-${myIndex}`,
           className: itemClasses,
-          role: "menuitem",
+          role: isChoice ? "menuitemradio" : "menuitem",
+          "aria-checked": isChoice ? entry.selected : void 0,
           "aria-disabled": entry.disabled || void 0,
           onClick: (e) => {
             e.stopPropagation();
@@ -349,7 +356,8 @@ const ContextMenu = React.forwardRef(
               ),
               entry.label
             ] }),
-            entry.shortcut && /* @__PURE__ */ jsx("span", { className: `${baseClass}__shortcut`, children: entry.shortcut })
+            entry.shortcut && /* @__PURE__ */ jsx("span", { className: `${baseClass}__shortcut`, children: entry.shortcut }),
+            entry.selected && /* @__PURE__ */ jsx("span", { className: `${baseClass}__check material-symbols-rounded`, "aria-hidden": "true", children: "check" })
           ]
         },
         `item-${index}`

package/components/DropdownMenu/DropdownMenu.css

@@ -145,6 +145,35 @@
   background-color: var(--color-action-passive-bg-hover);
 }
 
+/* ============================================
+   SELECTED ITEM
+   The current choice of a set: the passive wash held down, text and icon
+   at full strength, and a trailing check — three cues, none of them the
+   action colour, which a menu row has no claim on.
+   ============================================ */
+
+.ds-dropdown-menu__item--selected {
+  background-color: var(--color-action-passive-bg-hover);
+  color: var(--color-text-primary);
+}
+
+.ds-dropdown-menu__item--selected:hover,
+.ds-dropdown-menu__item--selected.ds-dropdown-menu__item--focused {
+  background-color: var(--color-action-passive-bg-active);
+}
+
+.ds-dropdown-menu__item--selected .ds-dropdown-menu__item-icon {
+  color: var(--color-icon-primary);
+}
+
+.ds-dropdown-menu__check {
+  --icon-size: var(--icon-size-500);
+  color: var(--color-icon-primary);
+  margin-left: auto;
+  flex-shrink: 0;
+  line-height: 1;
+}
+
 /* ============================================
    DISABLED ITEM
    ============================================ */

package/components/DropdownMenu/DropdownMenu.d.ts

@@ -11,6 +11,8 @@ export interface DropdownMenuItem {
     disabled?: boolean;
     /** Destructive / danger styling (red text) for delete, remove, etc. */
     destructive?: boolean;
+    /** Marks the item as the current choice of a set: it holds the passive wash and a trailing check, and is announced as a checked radio item. Leave undefined on plain action items; pass `false` on the unchosen members of a set so they are announced as radio items too. Ignored on an item that opens a sub-menu. */
+    selected?: boolean;
     /** Click handler */
     onClick?: () => void;
     /** Nested sub-menu items */

package/components/DropdownMenu/DropdownMenu.js

@@ -120,14 +120,17 @@ const MenuPanel = ({
     const itemClasses = [
       `${baseClass}__item`,
       entry.disabled ? `${baseClass}__item--disabled` : "",
-      entry.destructive ? `${baseClass}__item--destructive` : ""
+      entry.destructive ? `${baseClass}__item--destructive` : "",
+      entry.selected ? `${baseClass}__item--selected` : ""
     ].filter(Boolean).join(" ");
+    const isChoice = entry.selected !== void 0;
     return /* @__PURE__ */ jsxs(
       "li",
       {
         id: entryId,
         className: itemClasses,
-        role: "menuitem",
+        role: isChoice ? "menuitemradio" : "menuitem",
+        "aria-checked": isChoice ? entry.selected : void 0,
         "aria-disabled": entry.disabled || void 0,
         onClick: (e) => {
           e.stopPropagation();
@@ -141,7 +144,8 @@ const MenuPanel = ({
             entry.icon && (typeof entry.icon === "string" ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__item-icon material-symbols-rounded`, "aria-hidden": "true", children: entry.icon }) : /* @__PURE__ */ jsx("span", { className: `${baseClass}__item-icon`, "aria-hidden": "true", children: entry.icon })),
             entry.label
           ] }),
-          entry.shortcut && /* @__PURE__ */ jsx("span", { className: `${baseClass}__shortcut`, children: entry.shortcut })
+          entry.shortcut && /* @__PURE__ */ jsx("span", { className: `${baseClass}__shortcut`, children: entry.shortcut }),
+          entry.selected && /* @__PURE__ */ jsx("span", { className: `${baseClass}__check material-symbols-rounded`, "aria-hidden": "true", children: "check" })
         ]
       },
       `item-${index}`
@@ -253,7 +257,7 @@ const DropdownMenu = ({
   };
   useEffect(() => {
     if (isOpen && focusedIndex >= 0 && panelRef.current) {
-      const allItems = panelRef.current.querySelectorAll(`[role="menuitem"]`);
+      const allItems = panelRef.current.querySelectorAll(`[role="menuitem"], [role="menuitemradio"]`);
       const el = allItems[focusedIndex];
       el?.scrollIntoView({ block: "nearest" });
     }
@@ -291,14 +295,17 @@ const DropdownMenu = ({
       `${baseClass}__item`,
       isFocused ? `${baseClass}__item--focused` : "",
       entry.disabled ? `${baseClass}__item--disabled` : "",
-      entry.destructive ? `${baseClass}__item--destructive` : ""
+      entry.destructive ? `${baseClass}__item--destructive` : "",
+      entry.selected ? `${baseClass}__item--selected` : ""
     ].filter(Boolean).join(" ");
+    const isChoice = entry.selected !== void 0;
     return /* @__PURE__ */ jsxs(
       "li",
       {
         id: `${generatedId}-item-${myIndex}`,
         className: itemClasses,
-        role: "menuitem",
+        role: isChoice ? "menuitemradio" : "menuitem",
+        "aria-checked": isChoice ? entry.selected : void 0,
         "aria-disabled": entry.disabled || void 0,
         onClick: (e) => {
           e.stopPropagation();
@@ -312,7 +319,8 @@ const DropdownMenu = ({
             entry.icon && (typeof entry.icon === "string" ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__item-icon material-symbols-rounded`, "aria-hidden": "true", children: entry.icon }) : /* @__PURE__ */ jsx("span", { className: `${baseClass}__item-icon`, "aria-hidden": "true", children: entry.icon })),
             entry.label
           ] }),
-          entry.shortcut && /* @__PURE__ */ jsx("span", { className: `${baseClass}__shortcut`, children: entry.shortcut })
+          entry.shortcut && /* @__PURE__ */ jsx("span", { className: `${baseClass}__shortcut`, children: entry.shortcut }),
+          entry.selected && /* @__PURE__ */ jsx("span", { className: `${baseClass}__check material-symbols-rounded`, "aria-hidden": "true", children: "check" })
         ]
       },
       `item-${index}`

package/components/PixelAvatar/PixelAvatar.css

@@ -0,0 +1,79 @@
+/* ============================================
+   PIXEL AVATAR COMPONENT
+   A generated character mark, drawn from a name
+   ============================================ */
+
+/* Base — the character rides the icon scale, so it seats wherever an icon
+   does. A host that already sets --icon-size on its icon seat is matched by
+   the size classes below, which set the same variable. */
+
+.ds-pixel-avatar {
+  display: inline-flex;
+  flex-shrink: 0;
+  box-sizing: border-box;
+  width: var(--icon-size);
+  height: var(--icon-size);
+  color: var(--ds-pixel-avatar-ink);
+}
+
+.ds-pixel-avatar__sprite {
+  display: block;
+  width: 100%;
+  height: 100%;
+  fill: currentColor;
+}
+
+/* Sizes */
+
+.ds-pixel-avatar--sm {
+  --icon-size: var(--icon-size-500);
+}
+
+.ds-pixel-avatar--md {
+  --icon-size: var(--icon-size-600);
+}
+
+.ds-pixel-avatar--lg {
+  --icon-size: var(--icon-size-800);
+}
+
+.ds-pixel-avatar--xl {
+  --icon-size: var(--icon-size-1200);
+}
+
+/* Inks — one rule per pixel ink token. The tokens carry a light and a dark
+   value each, so the character holds its contrast in both themes. */
+
+.ds-pixel-avatar--ink-1 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-1);
+}
+
+.ds-pixel-avatar--ink-2 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-2);
+}
+
+.ds-pixel-avatar--ink-3 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-3);
+}
+
+.ds-pixel-avatar--ink-4 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-4);
+}
+
+.ds-pixel-avatar--ink-5 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-5);
+}
+
+.ds-pixel-avatar--ink-6 {
+  --ds-pixel-avatar-ink: var(--color-pixel-ink-6);
+}
+
+/* Variants — the tile is the same sprite on a wash of its own ink. The
+   padding comes from the size, not a percentage, which would resolve against
+   the host's width rather than the tile's. */
+
+.ds-pixel-avatar--tile {
+  padding: calc(var(--icon-size) / 16);
+  border-radius: var(--radius-200);
+  background-color: color-mix(in srgb, var(--ds-pixel-avatar-ink) 16%, transparent);
+}

package/components/PixelAvatar/PixelAvatar.d.ts

@@ -0,0 +1,47 @@
+import { default as React } from 'react';
+import { PixelInk } from './pixelInks';
+export { distinctPixelInks, pixelAvatarInk } from './pixelInks';
+export type { PixelInk } from './pixelInks';
+/** Props owned by PixelAvatar itself — everything else falls through to the root span. */
+type PixelAvatarOwnProps = {
+    /**
+     * The seed. The same name always draws the same character in the same
+     * ink, so a project, workspace or thread has its mark the moment it has a
+     * name, with nothing designed or stored for it.
+     */
+    name: string;
+    /** Rendered size, on the icon scale (`--icon-size-500/600/800/1200` — 20, 24, 32 and 48px), so the character seats wherever an icon does. */
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+    /**
+     * Overrides the ink the name picks (1 to 6, the `--color-pixel-ink-*`
+     * tokens). A name's own ink is one of six, so two neighbours can land on
+     * the same one; a host drawing a list passes each row's entry from
+     * `distinctPixelInks` here to keep them apart. The character's shape still
+     * comes from the name.
+     */
+    ink?: PixelInk;
+    /** `plain` draws the character alone; `tile` seats it on a rounded wash of its own ink, for a larger standalone mark. */
+    variant?: 'plain' | 'tile';
+    /**
+     * Accessible name. Omit it when the mark sits beside the name it was
+     * drawn from, which is the usual case: the character is then decorative
+     * and hidden from assistive technology. Given, the root becomes an image
+     * with this label.
+     */
+    label?: string;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface PixelAvatarProps extends PixelAvatarOwnProps, Omit<React.ComponentPropsWithoutRef<'span'>, keyof PixelAvatarOwnProps> {
+}
+/**
+ * PixelAvatar — a generated character mark. The name is the seed: a small
+ * pixel creature and one of six inks are drawn from it, deterministically,
+ * so the same name is always the same character and nothing has to be
+ * designed, uploaded or stored. For the things that have a name before they
+ * have a logo — projects, workspaces, repositories, agents.
+ *
+ * Pure: no hooks, no random source and no browser API, so the server and the
+ * client draw the same sprite and it renders from a Server Component.
+ */
+export declare const PixelAvatar: React.ForwardRefExoticComponent<PixelAvatarProps & React.RefAttributes<HTMLSpanElement>>;

package/components/PixelAvatar/PixelAvatar.js

@@ -0,0 +1,90 @@
+import { jsx } from "react/jsx-runtime";
+import React from "react";
+import { hashName, pixelAvatarInk } from "./pixelInks.js";
+import { distinctPixelInks } from "./pixelInks.js";
+import "./PixelAvatar.css";
+const GRID = 8;
+const MARGIN = 1;
+const ROW_CHANCES = [
+  [0, 0.3, 0.25, 0.15],
+  // antennae
+  [0.1, 0.75, 1, 1],
+  // crown
+  [0.55, 1, 1, 1],
+  // head
+  [0.75, 1, 1, 1],
+  // eyes (one cell is carved out below)
+  [0.7, 1, 1, 1],
+  // cheeks
+  [0.35, 0.85, 0.9, 0.7],
+  // jaw
+  [0.45, 0.5, 0.45, 0.35],
+  // legs
+  [0.35, 0.3, 0.25, 0.1]
+  // feet
+];
+const EYE_ROW = 3;
+function seeded(seed) {
+  let state = seed;
+  return () => {
+    state = state + 1831565813 | 0;
+    let t = Math.imul(state ^ state >>> 15, 1 | state);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function spriteCells(name) {
+  const next = seeded(hashName(name));
+  const eyeColumn = next() < 0.6 ? 2 : 1;
+  const cells = [];
+  ROW_CHANCES.forEach((chances, row) => {
+    chances.forEach((chance, column) => {
+      if (next() >= chance) return;
+      if (row === EYE_ROW && column === eyeColumn) return;
+      cells.push([column, row], [GRID - 1 - column, row]);
+    });
+  });
+  return cells;
+}
+const PixelAvatar = React.forwardRef(
+  ({ name, size = "md", variant = "plain", ink: inkOverride, label, className = "", ...rest }, ref) => {
+    const baseClass = "ds-pixel-avatar";
+    const ink = inkOverride ?? pixelAvatarInk(name);
+    const classes = [
+      baseClass,
+      `${baseClass}--${size}`,
+      `${baseClass}--${variant}`,
+      `${baseClass}--ink-${ink}`,
+      className
+    ].filter(Boolean).join(" ");
+    const viewBox = `${-MARGIN} ${-MARGIN} ${GRID + MARGIN * 2} ${GRID + MARGIN * 2}`;
+    return /* @__PURE__ */ jsx(
+      "span",
+      {
+        ...rest,
+        ref,
+        className: classes,
+        role: label ? "img" : void 0,
+        "aria-label": label,
+        "aria-hidden": label ? void 0 : true,
+        children: /* @__PURE__ */ jsx(
+          "svg",
+          {
+            className: `${baseClass}__sprite`,
+            viewBox,
+            shapeRendering: "crispEdges",
+            focusable: "false",
+            "aria-hidden": "true",
+            children: spriteCells(name).map(([column, row]) => /* @__PURE__ */ jsx("rect", { x: column, y: row, width: 1, height: 1 }, `${column}-${row}`))
+          }
+        )
+      }
+    );
+  }
+);
+PixelAvatar.displayName = "PixelAvatar";
+export {
+  PixelAvatar,
+  distinctPixelInks,
+  pixelAvatarInk
+};

package/components/PixelAvatar/pixelInks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The ink side of PixelAvatar, kept apart from the component so a host that
+ * lays out a list can compute its inks without rendering anything. The
+ * component re-exports everything here; this module has no subpath of its
+ * own.
+ */
+/** One of the six pixel inks, by token number. */
+export type PixelInk = 1 | 2 | 3 | 4 | 5 | 6;
+/** FNV-1a, 32-bit: a small stable hash of a name. */
+export declare function hashName(name: string): number;
+/** The ink a name picks for itself: stable, and one of six. */
+export declare function pixelAvatarInk(name: string): PixelInk;
+/**
+ * Inks for a list of names shown together, in order, so neighbours are told
+ * apart by colour as well as by shape. Each name keeps the ink it picks for
+ * itself when that ink is still among the least used in the list so far and
+ * sits clear of the row before it; otherwise it takes the next ink round the
+ * set that does. "Clear" means at least two steps away on the hue ring the
+ * inks are numbered round (red, orange, yellow, green, blue, purple), so a
+ * row never follows its own colour or the hue beside it: a muted theme
+ * draws neighbouring hues close together, and two warm tans in a row read
+ * as the same mark. The first six names therefore all differ, and a longer
+ * list repeats as evenly as it can. Deterministic
+ * for a given list, so server and client agree; a name's ink can change when
+ * the list around it does, which is the price of the guarantee.
+ */
+export declare function distinctPixelInks(names: readonly string[]): PixelInk[];

package/components/PixelAvatar/pixelInks.js

@@ -0,0 +1,45 @@
+const INKS = 6;
+function hashName(name) {
+  let hash = 2166136261;
+  for (let i = 0; i < name.length; i += 1) {
+    hash ^= name.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function pixelAvatarInk(name) {
+  return hashName(`${name}:colour`) % INKS + 1;
+}
+function distinctPixelInks(names) {
+  const used = new Array(INKS).fill(0);
+  const inks = [];
+  names.forEach((name) => {
+    const own = pixelAvatarInk(name) - 1;
+    const fewest = Math.min(...used);
+    const previous = inks.length > 0 ? inks[inks.length - 1] - 1 : -1;
+    let clear = -1;
+    let different = -1;
+    let any = -1;
+    for (let step = 0; step < INKS; step += 1) {
+      const candidate = (own + step) % INKS;
+      if (used[candidate] !== fewest) continue;
+      if (any === -1) any = candidate;
+      if (candidate === previous) continue;
+      if (different === -1) different = candidate;
+      const apart = Math.abs(candidate - previous);
+      if (previous === -1 || Math.min(apart, INKS - apart) >= 2) {
+        clear = candidate;
+        break;
+      }
+    }
+    const chosen = clear !== -1 ? clear : different !== -1 ? different : any;
+    used[chosen] += 1;
+    inks.push(chosen + 1);
+  });
+  return inks;
+}
+export {
+  distinctPixelInks,
+  hashName,
+  pixelAvatarInk
+};