@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Card/Card.doc.mjs

@@ -57,8 +57,9 @@ export const docs = {
     {
       name: 'padding',
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
-      description: 'Internal padding using the spacing scale.',
-      default: '4',
+      description:
+        "Internal padding using the spacing scale. Omit it and the card takes the theme's card padding rather than a step, so passing a step is a decision to override the theme, not a way to restate the default.",
+      default: "the theme's card padding (spacing step 4 with no theme)",
     },
     {
       name: 'variant',
@@ -77,7 +78,6 @@ export const docs = {
   ],
   playground: {
     defaults: {
-      padding: 4,
       children: {
         __element: 'VStack',
         props: {gap: 2},
@@ -91,7 +91,7 @@ export const docs = {
   theming: {
     container: true,
     targets: [
-      {className: 'astryx-card', visualProps: ['variant']},
+      {className: 'astryx-card', visualProps: ['variant', 'elevation']},
     ],
     vars: [
       {name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},
@@ -135,16 +135,19 @@ export const docsZh = {
     {name: 'maxWidth', type: 'SizeValue', description: '卡片最大宽度。'},
     {name: 'minHeight', type: 'SizeValue', description: '卡片最小高度。'},
     {name: 'children', type: 'ReactNode', description: '在卡片内部渲染的内容。'},
-    {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: '使用间距比例的内边距。', default: '4'},
+    {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: '使用间距比例的内边距。省略时，卡片采用主题的卡片内边距，而不是某个步进值；传入步进值意味着覆盖主题，而不是复述默认值。', default: "the theme's card padding (spacing step 4 with no theme)"},
+    {name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: '背景颜色变体。`default` 使用标准卡片背景；`transparent` 完全去掉背景；`muted` 使用弱化卡片的柔和背景。非语义变体使用对应的 `--color-background-<name>` 令牌。', default: "'default'"},
     {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。`none` 为扁平；`low`/`med`/`high` 对应阴影令牌比例。', default: "'none'"},
   ],
   theming: {
     container: true,
     targets: [
-      {className: 'astryx-card', visualProps: ['variant']},
+      {className: 'astryx-card', visualProps: ['variant', 'elevation']},
     ],
     vars: [
       {name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},
+      {name: '--_card-elevation', description: 'Resting shadow of the card, set from the elevation prop.', default: '0 0 transparent', private: true},
+      {name: '--_card-ring', description: 'Inset ring drawn in the card box-shadow list.', default: '0 0 transparent', private: true},
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_card-radius']},
@@ -178,7 +181,7 @@ export const docsDense = {
     maxWidth: 'max card width',
     minHeight: 'min card height',
     children: 'content inside card',
-    padding: 'internal padding via spacing scale',
+    padding: "internal padding via spacing scale; omitted = the theme's card padding, NOT a fixed step. Passing a step overrides the theme.",
     variant: 'background color variant; `default` = standard card bg, `transparent` = no background at all, `muted` = muted bg for de-emphasised cards; non-semantic variants use the corresponding `--color-background-<name>` token',
     elevation: 'resting shadow depth: none (flat) | low | med | high (shadow token scale). Raise only to float above content.',
   },

package/src/Card/Card.test.tsx

@@ -1,8 +1,10 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import {createRef} from 'react';
 import {describe, it, expect} from 'vitest';
 import {render} from '@testing-library/react';
 import {Card} from './Card';
+import type {CardVariant} from './Card';
 
 describe('Card', () => {
   it('renders children', () => {
@@ -10,17 +12,52 @@ describe('Card', () => {
     expect(getByText('Hello')).toBeInTheDocument();
   });
 
-  it('renders astryx-* class names for theme targeting', () => {
-    const {container} = render(<Card>Content</Card>);
-    const root = container.firstElementChild!;
+  it('forwards ref to the rendered element', () => {
+    const ref = createRef<HTMLDivElement>();
+    const {container} = render(<Card ref={ref}>C</Card>);
+    expect(ref.current).toBe(container.firstElementChild);
+  });
+
+  it('spreads unknown props onto the same element that carries the theme target', () => {
+    const {getByTestId} = render(
+      <Card data-testid="card" id="promo" aria-label="Promotion">
+        C
+      </Card>,
+    );
+    const root = getByTestId('card');
+    expect(root).toHaveAttribute('id', 'promo');
+    expect(root).toHaveAttribute('aria-label', 'Promotion');
     expect(root.className).toContain('astryx-card');
   });
 
-  it('renders transparent variant with variant class', () => {
-    const {container} = render(<Card variant="transparent">Content</Card>);
+  it('merges a consumer className instead of replacing the theme target', () => {
+    const {container} = render(<Card className="promo">C</Card>);
     const root = container.firstElementChild!;
     expect(root.className).toContain('astryx-card');
-    expect(root.className).toContain('transparent');
+    expect(root.className).toContain('promo');
+  });
+
+  it('reflects variant as a theme data attribute', () => {
+    const {container} = render(<Card variant="muted">C</Card>);
+    expect(container.firstElementChild).toHaveAttribute(
+      'data-variant',
+      'muted',
+    );
+  });
+
+  it('reflects elevation as a theme data attribute', () => {
+    const {container} = render(<Card elevation="high">C</Card>);
+    expect(container.firstElementChild).toHaveAttribute(
+      'data-elevation',
+      'high',
+    );
+  });
+
+  it('defaults to the default variant at rest elevation', () => {
+    const {container} = render(<Card>C</Card>);
+    const root = container.firstElementChild!;
+    expect(root).toHaveAttribute('data-variant', 'default');
+    expect(root).toHaveAttribute('data-elevation', 'none');
   });
 
   it('applies a distinct class for each elevation level', () => {
@@ -28,18 +65,75 @@ describe('Card', () => {
       const {container} = render(<Card elevation={elevation}>C</Card>);
       return container.firstElementChild!.className;
     };
-    const none = classFor('none');
-    const low = classFor('low');
-    const med = classFor('med');
-    const high = classFor('high');
-    expect(new Set([none, low, med, high]).size).toBe(4);
-  });
-
-  it('defaults to flat (elevation none) — same class as explicit none', () => {
-    const {container: defaultContainer} = render(<Card>C</Card>);
-    const {container: noneContainer} = render(<Card elevation="none">C</Card>);
-    expect(defaultContainer.firstElementChild!.className).toBe(
-      noneContainer.firstElementChild!.className,
-    );
+    const classes = (['none', 'low', 'med', 'high'] as const).map(classFor);
+    expect(new Set(classes).size).toBe(4);
+  });
+
+  // Deriving the prop from CardVariantMap must not change which values it
+  // accepts. A key added to or dropped from the map fails to type-check here:
+  // a missing one against Record<CardVariant, true>, an extra one as an excess
+  // property.
+  const builtInVariants: Record<CardVariant, true> = {
+    default: true,
+    transparent: true,
+    muted: true,
+    blue: true,
+    cyan: true,
+    gray: true,
+    green: true,
+    orange: true,
+    pink: true,
+    purple: true,
+    red: true,
+    teal: true,
+    yellow: true,
+  };
+
+  it('accepts exactly the thirteen built-in variants, each reflected', () => {
+    const variants = Object.keys(builtInVariants) as CardVariant[];
+    expect(variants).toHaveLength(13);
+    for (const variant of variants) {
+      const {container} = render(<Card variant={variant}>C</Card>);
+      expect(container.firstElementChild).toHaveAttribute(
+        'data-variant',
+        variant,
+      );
+    }
+  });
+
+  describe('a variant a theme added', () => {
+    // The cast stands in for the module augmentation `astryx theme build`
+    // emits; that the augmentation itself widens the prop is covered by
+    // packages/cli/clients/cli/commands/build-theme.variants.test.mjs.
+    const themeAdded = 'brand' as CardVariant;
+
+    const classesFor = (variant: CardVariant) => {
+      const {container} = render(<Card variant={variant}>C</Card>);
+      return new Set(container.firstElementChild!.className.split(' '));
+    };
+
+    it('renders the selector a theme rule needs', () => {
+      const {container} = render(<Card variant={themeAdded}>C</Card>);
+      const root = container.firstElementChild!;
+      expect(root).toHaveAttribute('data-variant', 'brand');
+      expect(root.className).toContain('astryx-card');
+      expect(root.className).toContain('brand');
+    });
+
+    it('falls through to base styles instead of another variant', () => {
+      const muted = classesFor('muted');
+      const blue = classesFor('blue');
+      const brand = classesFor(themeAdded);
+
+      const variantOwned = [
+        ...[...muted].filter(c => !blue.has(c)),
+        ...[...blue].filter(c => !muted.has(c)),
+      ];
+      const shared = [...muted].filter(c => blue.has(c));
+
+      expect(variantOwned.length).toBeGreaterThan(0);
+      expect(variantOwned.filter(c => brand.has(c))).toEqual([]);
+      expect(shared.filter(c => !brand.has(c))).toEqual([]);
+    });
   });
 });

package/src/Card/Card.tsx

@@ -3,7 +3,7 @@
 /**
  * @file Card.tsx
  * @input Uses container utility, StyleX
- * @output Exports Card component and CardProps
+ * @output Exports Card component, CardProps, CardVariant types
  * @position Core card container component
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -15,6 +15,7 @@
 
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
 import {
   borderVars,
   colorVars,
@@ -23,24 +24,21 @@ import {
 } from '../theme/tokens.stylex';
 import {container} from '../Layout/container.stylex';
 import type {SpacingToken} from '../Layout/container.stylex';
-import {
-  paddingStyles,
-  containerPaddingInlineVarStyles,
-  containerPaddingBlockStartVarStyles,
-  containerPaddingBlockEndVarStyles,
-  spacingStepToToken,
-} from '../Layout/padding.stylex';
+import {spacingStepToToken} from '../Layout/padding.stylex';
 import type {Elevation, SizeValue, SpacingStep} from '../utils/types';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import type {CardVariantMap} from './index';
 
 // =============================================================================
 // Variant type
 // =============================================================================
 
 /**
- * Background color variant for Card.
+ * Background color variant for Card, derived from CardVariantMap.
+ * Extensible via module augmentation of CardVariantMap.
+ *
  * - `default`: standard card background with visible border
  * - `transparent`: no background, no visible border — for grouping content without visual weight
  * - `muted`: subtle muted background for de-emphasised cards
@@ -52,20 +50,7 @@ import {themeProps} from '../utils/themeProps';
  * keeping content geometry faithful to the spacing scale and identical to the
  * borderless variants. Themes can override borderWidth/borderColor.
  */
-export type CardVariant =
-  | 'default'
-  | 'transparent'
-  | 'muted'
-  | 'blue'
-  | 'cyan'
-  | 'gray'
-  | 'green'
-  | 'orange'
-  | 'pink'
-  | 'purple'
-  | 'red'
-  | 'teal'
-  | 'yellow';
+export type CardVariant = keyof CardVariantMap;
 
 // =============================================================================
 // Styles
@@ -102,48 +87,53 @@ const styles = stylex.create({
   },
 });
 
-// Background variant styles — each maps to a design token
-const variantStyles = stylex.create({
-  default: {
-    backgroundColor: colorVars['--color-background-card'],
-  },
-  transparent: {
-    backgroundColor: 'transparent',
-  },
-  muted: {
-    backgroundColor: colorVars['--color-background-muted'],
-  },
-  blue: {
-    backgroundColor: colorVars['--color-background-blue'],
-  },
-  cyan: {
-    backgroundColor: colorVars['--color-background-cyan'],
-  },
-  gray: {
-    backgroundColor: colorVars['--color-background-gray'],
-  },
-  green: {
-    backgroundColor: colorVars['--color-background-green'],
-  },
-  orange: {
-    backgroundColor: colorVars['--color-background-orange'],
-  },
-  pink: {
-    backgroundColor: colorVars['--color-background-pink'],
+// Background variant styles — each maps to a design token. Typed as PARTIAL
+// over CardVariant: a theme can add a variant, and the record deliberately has
+// no entry for it, so the lookup is undefined, StyleX drops it, and the card
+// takes base styles for the theme rule to paint over.
+const variantStyles: Partial<Record<CardVariant, StyleXStyles>> = stylex.create(
+  {
+    default: {
+      backgroundColor: colorVars['--color-background-card'],
+    },
+    transparent: {
+      backgroundColor: 'transparent',
+    },
+    muted: {
+      backgroundColor: colorVars['--color-background-muted'],
+    },
+    blue: {
+      backgroundColor: colorVars['--color-background-blue'],
+    },
+    cyan: {
+      backgroundColor: colorVars['--color-background-cyan'],
+    },
+    gray: {
+      backgroundColor: colorVars['--color-background-gray'],
+    },
+    green: {
+      backgroundColor: colorVars['--color-background-green'],
+    },
+    orange: {
+      backgroundColor: colorVars['--color-background-orange'],
+    },
+    pink: {
+      backgroundColor: colorVars['--color-background-pink'],
+    },
+    purple: {
+      backgroundColor: colorVars['--color-background-purple'],
+    },
+    red: {
+      backgroundColor: colorVars['--color-background-red'],
+    },
+    teal: {
+      backgroundColor: colorVars['--color-background-teal'],
+    },
+    yellow: {
+      backgroundColor: colorVars['--color-background-yellow'],
+    },
   },
-  purple: {
-    backgroundColor: colorVars['--color-background-purple'],
-  },
-  red: {
-    backgroundColor: colorVars['--color-background-red'],
-  },
-  teal: {
-    backgroundColor: colorVars['--color-background-teal'],
-  },
-  yellow: {
-    backgroundColor: colorVars['--color-background-yellow'],
-  },
-});
+);
 
 // Elevation → shadow-token map. Sets the private --_card-elevation variable
 // (not box-shadow directly) so it composes with --_card-ring in the shadow
@@ -176,14 +166,6 @@ export type {SizeValue} from '../utils/types';
 
 export interface CardProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
-  /**
-   * CSS class name(s) appended to the root element.
-   */
-  className?: string;
-  /**
-   * Inline styles to apply to the root element.
-   */
-  style?: React.CSSProperties;
   /**
    * Width of the card.
    * Numbers are treated as pixels, strings are used as-is.
@@ -217,7 +199,12 @@ export interface CardProps extends BaseProps<HTMLDivElement> {
   /**
    * Internal padding of the card using the spacing scale.
    * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
-   * @default 4 (16px)
+   *
+   * Omit it and the card takes the theme's card padding rather than a step, so
+   * passing a step is a decision to override the theme, not a way to restate
+   * the default.
+   *
+   * @default the theme's card padding (spacing step 4 with no theme)
    */
   padding?: SpacingStep;
 
@@ -293,16 +280,19 @@ export function Card({
 
   // When no explicit padding prop, use theme default (set via container tokens)
   const useThemeDefault = padding == null;
-  const effectivePadding = padding ?? 4;
-  const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
+  const paddingToken = useThemeDefault
+    ? undefined
+    : (spacingStepToToken[padding] as SpacingToken);
 
   return (
     <div
       ref={ref}
       {...mergeProps(
-        themeProps('card', {variant}),
+        themeProps('card', {variant, elevation}),
         stylex.props(
           styles.card,
+          // A theme's own variant is not a key here: the lookup is undefined,
+          // StyleX drops it, and the theme rule paints over base styles.
           variantStyles[variant],
           elevationStyles[elevation],
           hasFixedHeight && styles.scrollable,
@@ -313,7 +303,7 @@ export function Card({
             minHeight ?? null,
           ),
           ...container(
-            useThemeDefault
+            paddingToken == null
               ? {useThemeDefault: 'card'}
               : {
                   paddingInnerX: paddingToken,
@@ -322,18 +312,6 @@ export function Card({
                   paddingOuterY: paddingToken,
                 },
           ),
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            paddingStyles[effectivePadding],
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            containerPaddingInlineVarStyles[effectivePadding],
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            containerPaddingBlockStartVarStyles[effectivePadding],
-          !useThemeDefault &&
-            effectivePadding !== 4 &&
-            containerPaddingBlockEndVarStyles[effectivePadding],
           // Applied after the container padding so the border-inset calc wins;
           // it reads the --container-padding-* vars set above.
           variant === 'default' && styles.withBorder,

package/src/Card/index.ts

@@ -3,11 +3,46 @@
 /**
  * @file index.ts
  * @input Imports Card component
- * @output Exports Card component and types
+ * @output Exports Card, CardProps, CardVariant, CardVariantMap
  * @position Entry point for @astryxdesign/core/Card module
  *
  * SYNC: When modified, update /packages/core/src/Card/Card.doc.mjs
  */
 
+/**
+ * Extensible variant map for Card.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Card' {
+ *   interface CardVariantMap {
+ *     'brand': true;
+ *   }
+ * }
+ * ```
+ *
+ * Pair the theme rule's `backgroundColor` with `--selectable-card-ring-color`.
+ * SelectableCard rings an added variant in that var, defaulting to the accent —
+ * no token the component could pick is guaranteed to contrast with a fill it
+ * cannot know, so the theme that supplied the fill picks the ring, in the same
+ * rule.
+ */
+export interface CardVariantMap {
+  default: true;
+  transparent: true;
+  muted: true;
+  blue: true;
+  cyan: true;
+  gray: true;
+  green: true;
+  orange: true;
+  pink: true;
+  purple: true;
+  red: true;
+  teal: true;
+  yellow: true;
+}
+
 export {Card} from './Card';
 export type {CardProps, CardVariant, SizeValue} from './Card';

package/src/Carousel/Carousel.tsx

@@ -46,11 +46,12 @@ import {useLayer} from '../Layer';
 import {useScrollOverflow} from '../hooks/useScrollOverflow';
 import {isRtlElement} from '../hooks/isRtlElement';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs, rtlStyles} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import type {SpacingStep} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 /**
  * Imperative control surface for the Carousel, accessed via the `handleRef`
  * prop. Methods drive the same native-scroll machinery as the built-in
@@ -506,7 +507,7 @@ export function Carousel({
 
   return (
     <div
-      ref={mergeRefs(ref, layer.ref as React.Ref<HTMLDivElement>)}
+      ref={useMergedRefs(ref, layer.ref as React.Ref<HTMLDivElement>)}
       data-testid={testId}
       {...htmlProps}
       {...mergeProps(

package/src/Chat/ChatComposerInput.tsx

@@ -255,6 +255,10 @@ const styles = stylex.create({
     opacity: 0.5,
     pointerEvents: 'none' as const,
   },
+  tokenSpan: {
+    display: 'inline-flex',
+    verticalAlign: 'middle',
+  },
 });
 
 // =============================================================================
@@ -749,7 +753,7 @@ export function ChatComposerTokenElement({token}: {token: ChatComposerToken}) {
       data-astryx-token=""
       data-astryx-token-value={token.value}
       contentEditable={false}
-      style={{display: 'inline-flex', verticalAlign: 'baseline'}}>
+      {...stylex.props(styles.tokenSpan)}>
       {isCustomToken(token) ? (
         token.render()
       ) : (

package/src/Chat/ChatLayout.tsx

@@ -33,7 +33,7 @@ import {type ReactNode, useMemo, useRef} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {useChatStreamScroll} from './useChatStreamScroll';
 import {useChatNewMessages} from './useChatNewMessages';
 import {ChatLayoutScrollButton} from './ChatLayoutScrollButton';
@@ -41,6 +41,7 @@ import {ChatLayoutContext} from './ChatContext';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Types
 // =============================================================================
@@ -343,7 +344,7 @@ export function ChatLayout({
     <ChatLayoutContext value={layoutContext}>
       <div
         {...rest}
-        ref={mergeRefs(ref, rootRef)}
+        ref={useMergedRefs(ref, rootRef)}
         data-testid={testId}
         {...mergeProps(
           themeProps('chat-layout', {density}),

package/src/Chat/ChatMessageList.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Chat',
   displayName: 'Chat Message List',
   isHiddenFromOverview: true,
-  description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full.`,
+  description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full; set align="top" to start messages at the top instead.`,
   props: [
     {
       name: 'children',
@@ -45,6 +45,12 @@ export const docs = {
       type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
       description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.',
     },
+    {
+      name: 'align',
+      type: "'top' | 'bottom'",
+      description: "Vertical alignment when the list is shorter than its container. 'bottom' fills free space with a spacer so short conversations sit above the composer; 'top' omits the spacer so messages start at the top. Only affects a non-full list; overflowing lists scroll identically, preserving auto-scroll-to-bottom.",
+      default: "'bottom'",
+    },
     {
       name: 'isStreaming',
       type: 'boolean',
@@ -65,6 +71,7 @@ export const docsZh = {
     scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
     density: '视觉密度，通过上下文传递给子消息。',
     gap: '顶层消息行之间的间距。默认跟随密度；当 LLM 事件流等独立行需要不同间距时可覆盖。',
+    align: "列表内容不足一屏时的垂直对齐方式。'bottom' 用占位块填满剩余空间，让简短对话贴近输入框；'top' 省略占位块，让消息从顶部开始。仅影响未填满的列表，溢出后两种模式滚动一致，保持自动滚动到底部。",
     isStreaming: '是否有助手消息正在流式输出。标记日志为 aria-busy，让屏幕阅读器等待并在完成后一次性播报，而不是每个 token 都重复播报。',
   },
 };
@@ -80,6 +87,7 @@ export const docsDense = {
     scrollToTopAction: 'async action at scroll top; load older msgs',
     density: 'visual density; flows to children via context',
     gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
+    align: "'top'|'bottom' (def bottom); bottom spacer pushes short lists down, top starts at top; overflow scrolls same either way",
     isStreaming: 'assistant streaming? marks log aria-busy so SR announces the completed msg once',
   },
 };

package/src/Chat/ChatMessageList.test.tsx

@@ -83,4 +83,50 @@ describe('ChatMessageList', () => {
     );
     expect(screen.getByTestId('chat-list')).toBeTruthy();
   });
+
+  // With no scrollToTopAction the spacer is the only aria-hidden element in
+  // the list, so its presence maps 1:1 to the aria-hidden count.
+  it('renders the bottom spacer by default', () => {
+    render(
+      <ChatMessageList data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(
+      screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+    ).toHaveLength(1);
+  });
+
+  it('renders the bottom spacer when align="bottom"', () => {
+    render(
+      <ChatMessageList align="bottom" data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(
+      screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+    ).toHaveLength(1);
+  });
+
+  it('omits the spacer when align="top"', () => {
+    render(
+      <ChatMessageList align="top" data-testid="list">
+        <div>msg</div>
+      </ChatMessageList>,
+    );
+    expect(
+      screen.getByTestId('list').querySelectorAll('[aria-hidden]'),
+    ).toHaveLength(0);
+  });
+
+  it('still renders children when align="top"', () => {
+    render(
+      <ChatMessageList align="top">
+        <ChatMessage sender="assistant">
+          <ChatMessageBubble>Hello</ChatMessageBubble>
+        </ChatMessage>
+      </ChatMessageList>,
+    );
+    expect(screen.getByText('Hello')).toBeTruthy();
+  });
 });