@astryxdesign/core 0.2.0 → 0.3.0-canary.0b5a38e

package/src/FileInput/FileInput.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'FileInput',
@@ -170,7 +170,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'FileInput',
   displayName: 'File Input',
@@ -293,7 +293,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'File input w/ input/dropzone modes, validation, label, description, status.',
   usage: {

package/src/FileInput/FileInput.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/FileInput/FileInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/FileInput/index.ts (exports if types change)
  * - /apps/storybook/stories/FileInput.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/FileInput/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/FileInput/ (showcase blocks)
  */
 
 import {

package/src/FormLayout/FormLayout.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'FormLayout',
@@ -52,7 +52,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'FormLayout',
   displayName: 'Form Layout',
@@ -100,7 +100,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Layout container for form fields w/ consistent spacing + direction.',

package/src/FormLayout/FormLayout.tsx

@@ -12,17 +12,14 @@
  * - /packages/core/src/FormLayout/FormLayout.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/FormLayout/index.ts (exports if types change)
  * - /apps/storybook/stories/FormLayout.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/FormLayout/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/FormLayout/ (showcase blocks)
  */
 
 import {useMemo, type ReactNode} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
-import {
-  FormLayoutContext,
-  type FormLayoutDirection,
-} from './FormLayoutContext';
+import {FormLayoutContext, type FormLayoutDirection} from './FormLayoutContext';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 

package/src/Grid/Grid.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Grid',
@@ -33,11 +33,6 @@ export const docs = {
       type: "number | {minWidth: number, max?: number, repeat?: 'fill' | 'fit'}",
       description: 'Column configuration. Use a number for fixed columns (e.g. `columns={3}`). Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.',
     },
-    {
-      name: 'minChildWidth',
-      type: 'number',
-      description: 'Deprecated: use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.',
-    },
     {
       name: 'width',
       type: 'SizeValue',
@@ -101,7 +96,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -117,7 +112,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'CSS Grid-based layout w/ responsive column support.',
   usage: {

package/src/Grid/Grid.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/Grid/Grid.doc.mjs
  * - /packages/core/src/Grid/Grid.test.tsx
  * - /apps/storybook/stories/Grid.stories.tsx
- * - /packages/cli/templates/blocks/components/Grid/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Grid/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';
@@ -63,15 +63,6 @@ export interface GridProps extends BaseProps<HTMLDivElement> {
    */
   columns?: GridColumns;
 
-  /**
-   * Minimum width of each grid item in pixels.
-   * Enables responsive auto-fit behavior.
-   *
-   * @deprecated Use `columns={{minWidth: 280}}` instead.
-   * @default 0 (disabled)
-   */
-  minChildWidth?: number;
-
   /**
    * Width of the grid container.
    * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
@@ -384,7 +375,6 @@ function buildCappedTemplate(
  */
 export function Grid({
   columns,
-  minChildWidth = 0,
   rowHeight,
   width,
   height,
@@ -421,20 +411,6 @@ export function Grid({
     } else {
       gridTemplateColumns = `repeat(${repeatMode}, minmax(${columns.minWidth}px, 1fr))`;
     }
-  } else if (minChildWidth > 0) {
-    // Deprecated path: minChildWidth uses auto-fit for backward compat
-    const numColumns = typeof columns === 'number' ? columns : 0;
-    if (numColumns > 0) {
-      gridTemplateColumns = buildCappedTemplate(
-        minChildWidth,
-        numColumns,
-        'auto-fit',
-        gap,
-        columnGap,
-      );
-    } else {
-      gridTemplateColumns = `repeat(auto-fit, minmax(${minChildWidth}px, 1fr))`;
-    }
   } else if (typeof columns === 'number' && columns > 0) {
     // Fixed columns mode
     gridTemplateColumns = `repeat(${columns}, 1fr)`;

package/src/Grid/GridSpan.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'GridSpan',

package/src/Grid/GridSpan.tsx

@@ -10,7 +10,7 @@
  * - /packages/core/src/Grid/Grid.doc.mjs
  * - /packages/core/src/Grid/Grid.test.tsx
  * - /apps/storybook/stories/Grid.stories.tsx
- * - /packages/cli/templates/blocks/components/Grid/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Grid/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/HStack/HStack.tsx

@@ -9,7 +9,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
  * - /packages/core/src/HStack/HStack.test.tsx
- * - /packages/cli/templates/blocks/components/HStack/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/HStack/ (showcase blocks)
  */
 
 import {Stack, type StackProps} from '../Stack/Stack';

package/src/Heading/Heading.tsx

@@ -13,8 +13,8 @@
  * - /packages/core/src/Heading/Heading.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Text/index.ts (exports if types change)
  * - /apps/storybook/stories/Text.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Heading/ (showcase blocks)
- * - /packages/cli/templates/blocks/components/Text/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Heading/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Text/ (showcase blocks)
  */
 
 import {lazy, Suspense, useRef, type ReactNode} from 'react';
@@ -41,6 +41,7 @@ import {
   truncationTooltipStyles,
 } from '../Text/text.stylex';
 import {useTruncation} from '../Text/useTruncation';
+import {resolveStyleColor} from '../Text/Text';
 import type {LayerPlacement} from '../Layer';
 import {mergeProps, mergeRefs} from '../utils';
 import type {BaseProps} from '../BaseProps';
@@ -251,7 +252,7 @@ export function Heading({
         {...mergeProps(
           themeProps('heading', {level, color, ...(type && {type})}),
           stylex.props(
-            colorStyles[color],
+            colorStyles[resolveStyleColor(color)],
             type ? sizeByTypeStyles[type] : sizeByLevelStyles[level],
             type && defaultWeightByTypeStyles[type],
             // Display: use truncation styles when maxLines > 0

package/src/HoverCard/HoverCard.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'HoverCard',
@@ -125,7 +125,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'HoverCard',
   displayName: 'Hover Card',
@@ -234,7 +234,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Hover/focus triggered overlay for displaying rich, interactive content anchored to trigger element.',

package/src/HoverCard/HoverCard.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/HoverCard/HoverCard.test.tsx
  * - /packages/core/src/HoverCard/index.ts
  * - /apps/storybook/stories/HoverCard.stories.tsx
- * - /packages/cli/templates/blocks/components/HoverCard/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/HoverCard/ (showcase blocks)
  */
 
 import {useCallback, useRef, type ReactElement, type ReactNode} from 'react';

package/src/HoverCard/useHoverCard.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useHoverCard',
   displayName: 'useHoverCard',
@@ -43,7 +43,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
   paramDescriptions: {

package/src/Icon/Icon.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Icon',
@@ -19,7 +19,7 @@ export const docs = {
     {
       name: 'icon',
       type: 'IconName | ComponentType<SVGProps>',
-      description: 'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
+      description: 'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
       required: true,
     },
     {
@@ -55,6 +55,7 @@ export const docs = {
     description: 'Icons are small visual symbols that represent actions, objects, or concepts. They improve scannability and reinforce meaning alongside text. Supports both direct SVG components and semantic icon names that adapt to the active theme.',
     bestPractices: [
       { guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },
+      { guidance: true, description: "Libraries can augment the icon map with their own keys: registerIcons({'richtext:bold': <MyIcon />}) accepts arbitrary extension keys (not just the built-in IconName set). Resolve them with getExtendedIcon(key, fallback), which prefers a theme-registered icon and falls back to a bundled default — the seam that makes library-shipped icons theme-overridable." },
       { guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },
       { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), give it an accessible name via the `label` prop: it sets role="img" + aria-label and unhides the icon.' },
       { guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },
@@ -68,7 +69,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Icon',
   displayName: 'Icon',
@@ -76,7 +77,7 @@ export const docsZh = {
     {
       name: 'icon',
       type: 'IconName | ComponentType<SVGProps>',
-      description: '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
+      description: '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
       required: true,
     },
     {
@@ -124,7 +125,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Renders icons w/ Astryx design system colors + sizes. Supports direct SVG icon components + semantic icon names that adapt to active theme.',
@@ -144,7 +145,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
+    icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
     color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
     label: 'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',

package/src/Icon/Icon.test.tsx

@@ -13,7 +13,11 @@ import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import * as stylex from '@stylexjs/stylex';
 import {TestIcon} from '../__tests__/TestIcon';
+import {Theme} from '../theme/Theme';
+import {defineTheme} from '../theme/defineTheme';
+import {resetThemes} from '../theme/themeRegistry';
 import {Icon} from './Icon';
+import {resetIcons} from './globalIconRegistry';
 
 describe('Icon', () => {
   it('renders the icon component', () => {
@@ -169,6 +173,25 @@ describe('Icon', () => {
     expect(screen.getByTestId('icon')).toHaveAttribute('aria-hidden', 'true');
   });
 
+  it('resolves string-mode icons from the nearest Theme without leaking globally', () => {
+    resetIcons();
+    resetThemes();
+    const outer = defineTheme({name: 'outer', icons: {check: 'outer-check'}});
+    const inner = defineTheme({name: 'inner', icons: {check: 'inner-check'}});
+
+    render(
+      <Theme theme={outer}>
+        <Icon icon="check" data-testid="outer" />
+        <Theme theme={inner}>
+          <Icon icon="check" data-testid="inner" />
+        </Theme>
+      </Theme>,
+    );
+
+    expect(screen.getByTestId('outer')).toHaveTextContent('outer-check');
+    expect(screen.getByTestId('inner')).toHaveTextContent('inner-check');
+  });
+
   it('lets a string-mode icon be made meaningful by overriding aria-hidden', () => {
     render(
       <Icon

package/src/Icon/Icon.tsx

@@ -19,13 +19,14 @@
  * - /packages/core/src/Icon/Icon.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Icon/index.ts (exports if types change)
  * - /apps/storybook/stories/Icon.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Icon/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Icon/ (showcase blocks)
  */
 
 import React, {type ComponentType, type SVGProps} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
+import {useThemeName} from '../theme/useTheme';
 import {getIcon} from './globalIconRegistry';
 import type {IconName} from './globalIconRegistry';
 import {mergeProps} from '../utils';
@@ -379,7 +380,8 @@ function IconFromRegistry({
   xstyle?: StyleXStyles;
   spanProps?: Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'>;
 }) {
-  const resolvedIcon = getIcon(name);
+  const themeName = useThemeName();
+  const resolvedIcon = getIcon(name, themeName);
 
   if (resolvedIcon == null) {
     return null;

package/src/Icon/defaultIcons.tsx

@@ -82,6 +82,20 @@ export const defaultIcons: IconRegistry = {
     </svg>
   ),
 
+  /** « — double left chevron (first / jump to start) */
+  chevronsLeft: (
+    <svg {...svgProps}>
+      <path d="M18 6l-6 6 6 6M11 6l-6 6 6 6" />
+    </svg>
+  ),
+
+  /** » — double right chevron (last / jump to end) */
+  chevronsRight: (
+    <svg {...svgProps}>
+      <path d="M6 6l6 6-6 6M13 6l6 6-6 6" />
+    </svg>
+  ),
+
   /** ✓ — checkmark */
   check: (
     <svg {...svgProps}>

package/src/Icon/globalIconRegistry.test.tsx

@@ -1,17 +1,28 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, beforeEach} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {defineTheme} from '../theme/defineTheme';
+import {resetThemes} from '../theme/themeRegistry';
+import {__resetDevWarnings} from '../utils/devWarning';
 import {defaultIcons} from './defaultIcons';
 import {
   registerIcons,
   getIconRegistry,
   getIcon,
+  getExtendedIcon,
   resetIcons,
 } from './globalIconRegistry';
 
 describe('iconRegistry (global, RSC-compatible)', () => {
   beforeEach(() => {
     resetIcons();
+    resetThemes();
+    __resetDevWarnings();
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
   });
 
   it('returns a default icon registry snapshot', () => {
@@ -28,6 +39,18 @@ describe('iconRegistry (global, RSC-compatible)', () => {
     expect(icon).not.toBeNull();
   });
 
+  it('warns once that registerIcons applies global overrides', () => {
+    const warnSpy = vi.mocked(console.warn);
+
+    registerIcons({close: 'custom-close'});
+    registerIcons({check: 'custom-check'});
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]?.[0]).toContain(
+      '`registerIcons()` applies icon overrides globally',
+    );
+  });
+
   it('returns registered icons over defaults', () => {
     const customClose = 'custom-close-icon';
     registerIcons({close: customClose});
@@ -65,6 +88,35 @@ describe('iconRegistry (global, RSC-compatible)', () => {
     expect(getIcon('close')).toBe('close-v2');
   });
 
+  it('resolves icons from an explicit theme object over global registrations', () => {
+    registerIcons({close: 'global-close'});
+    const theme = defineTheme({
+      name: 'brand',
+      icons: {close: 'theme-close'},
+    });
+
+    expect(getIcon('close', theme)).toBe('theme-close');
+    expect(getIconRegistry(theme).close).toBe('theme-close');
+  });
+
+  it('resolves icons from a registered theme name for SSR-friendly lookups', () => {
+    defineTheme({
+      name: 'brand',
+      icons: {close: 'theme-close'},
+    });
+
+    expect(getIcon('close', 'brand')).toBe('theme-close');
+    expect(getIconRegistry('brand').close).toBe('theme-close');
+  });
+
+  it('falls back through global registrations when a theme omits a name', () => {
+    registerIcons({close: 'global-close'});
+    const theme = defineTheme({name: 'brand', icons: {check: 'theme-check'}});
+
+    expect(getIcon('close', theme)).toBe('global-close');
+    expect(getIcon('check', theme)).toBe('theme-check');
+  });
+
   it('resetIcons clears the global registry', () => {
     registerIcons({close: 'custom'});
     expect(getIcon('close')).toBe('custom');
@@ -72,4 +124,38 @@ describe('iconRegistry (global, RSC-compatible)', () => {
     // Should fall back to default
     expect(getIcon('close')).not.toBe('custom');
   });
+
+  describe('extension keys', () => {
+    it('registers and resolves library-contributed keys', () => {
+      registerIcons({'richtext:bold': 'my-bold'});
+      expect(getIcon('richtext:bold')).toBe('my-bold');
+      expect(getExtendedIcon('richtext:bold')).toBe('my-bold');
+    });
+
+    it('getExtendedIcon returns the caller fallback when unregistered', () => {
+      expect(getExtendedIcon('richtext:bold', 'inline-svg')).toBe('inline-svg');
+    });
+
+    it('getExtendedIcon prefers a registered icon over the fallback', () => {
+      registerIcons({'richtext:bold': 'theme-bold'});
+      expect(getExtendedIcon('richtext:bold', 'inline-svg')).toBe('theme-bold');
+    });
+
+    it('getExtendedIcon still resolves built-in defaults', () => {
+      expect(getExtendedIcon('close', 'fallback')).toBe(defaultIcons.close);
+    });
+
+    it('extension keys do not leak into the built-in registry snapshot', () => {
+      registerIcons({'richtext:bold': 'my-bold'});
+      // getIconRegistry() is the built-in IconName snapshot; extension keys
+      // are resolved via getIcon/getExtendedIcon, not surfaced here.
+      expect(Object.keys(getIconRegistry())).toEqual(Object.keys(defaultIcons));
+    });
+
+    it('extension keys are cleared by resetIcons', () => {
+      registerIcons({'richtext:bold': 'my-bold'});
+      resetIcons();
+      expect(getExtendedIcon('richtext:bold', 'fallback')).toBe('fallback');
+    });
+  });
 });