@teamblind-chorus/ui 1.0.1 → 1.2.0

package/dist/index.d.cts

@@ -32,12 +32,22 @@ export type BadgeProps =
 // ── Banner (banner/banner) ──
 interface BannerPropsOwn {
   appearance?: "default" | "accent" | "destructive";
+  /** Paints a `sys.borderWidth.hairline` (1) inset stroke around the container, toned to the appearance's color family and kept deliberately faint so it reads as a soft edge of the same tint, not a frame — the subtle gray hairline (`sys.color.outlineVariant`) on `default`'s gray-tinted fill, `primary` at 40% (`color-mix(sys.color.primary, 40%)`) on `accent`'s blue-tinted fill, `error` at 40% on `destructive`. Rendered as an inset box-shadow, never a real border, so toggling it cannot change the banner's footprint (see DESIGN.md → Border & Stroke). Reach for it when the tinted fill alone doesn't separate the banner from its host surface. */
+  outlined?: boolean;
+  /** On `accent`, paints the title + body in the neutral default foreground (`sys.color.onSurface`) and steps the action to `sys.color.primary` — i.e. the **Default appearance's** foreground treatment laid over the accent fill, decoupling the background tone from the text tone. Reach for it when the `primaryContainer` tint should still pull the eye but the copy should read as quiet, high-legibility body text rather than tonal `onPrimaryContainer` primary-family text (long-form explainers, dense asides). No effect on `default` (already `onSurface`) or `destructive` (the warning tone must carry through the copy). */
+  neutralBody?: boolean;
+  /** Optional heading line above the body. label.md (14 / Semibold 600) in the container's foreground, separated from the body by `sys.layout.stack.2xs` (4). Reach for it when the aside needs a scannable lead-in; omit for single-thought asides where the body carries itself. */
+  title?: React.ReactNode;
   /** A 16 × 16 (`sys.icon.md`) glyph at the container's leading edge. Inherits the banner's foreground (`currentColor`) so the mark reads as part of the body copy. The slot occupies the body.sm line-box height so the glyph centers on the **first line** of the body — multi-line bodies keep the icon anchored to the first-line cap, not the block center. Ignored when `thumbnail` is also passed. */
   icon?: React.ReactNode;
+  /** A 16 × 16 (`sys.icon.md`) glyph at the container's trailing edge, vertically centered against the whole block (`align-self: center`). Paints in `currentColor`. Reach for it when the banner leads somewhere — a forward affordance such as `ForwardCircleFillIcon` signaling the whole aside opens a destination. */
+  trailingIcon?: React.ReactNode;
   /** A leading visual rendered by [Thumbnail](../thumbnail/thumbnail.md) — used when the aside is anchored to a channel, author, or sub-brand image rather than to a glyph. Takes precedence over `icon`. */
   thumbnail?: React.ReactNode;
   /** { label, href? , onClick? } — a follow-through link rendered as a block child below the body. */
   action?: Record<string, unknown>;
+  /** A [Text Button](../button/text.md) (`<Button variant="text">`) rendered at the container's trailing edge, vertically centered against the whole block (`align-self: center`). Distinct from `action` (a follow-through link below the body): `trailingAction` is a compact inline commit that sits beside the copy — Dismiss, Enable, Undo. The button keeps full control of its own `size` and `appearance` per the button/text spec; **by default pick the appearance whose color family matches the banner fill** so the commit reads as part of the tinted block — `accent` banner → `appearance="accent"`, `default` banner → `appearance="default"`, `destructive` banner → the Text Button `destructive` flavor. Override only when a denser rung (`size="small"` / `"xsmall"`) or a different emphasis is deliberately wanted. The button also keeps its own `leadingIcon` / `trailingIcon` slots, so the commit can carry an in-button glyph (e.g. a trailing `ChevronRightIcon` on an *Enable* / *Continue* commit). Takes precedence over the banner-level `trailingIcon` when both are passed. */
+  trailingAction?: React.ReactNode;
   /** Body text — the explanation copy. */
   children: React.ReactNode;
 }
@@ -152,6 +162,14 @@ export type ButtonProps =
   | ButtonToggleProps
   | ButtonToolbarProps;
 
+// ── ButtonGroup (button/group) ──
+interface ButtonGroupPropsOwn {
+  variant?: "inline" | "docked";
+  orientation?: "horizontal" | "vertical";
+  label?: React.ReactNode;
+}
+export interface ButtonGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof ButtonGroupPropsOwn>, ButtonGroupPropsOwn {}
+
 // ── Fab (button/fab) ──
 interface FabPropsOwn {
   variant?: "fab";
@@ -249,6 +267,19 @@ interface DirectoryListPropsOwn {
 }
 export interface DirectoryListProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof DirectoryListPropsOwn>, DirectoryListPropsOwn {}
 
+// ── EmptyState (empty-state/empty-state) ──
+interface EmptyStatePropsOwn {
+  /** Optional leading glyph or illustration, centered above the headline. Sized to a `ref.space.600` (48) box — larger than `sys.icon.lg` (24), realizing DESIGN.md's `icon.xl` or larger intent (no `icon.xl` icon-size rung exists; the icon scale stops at `lg`). Painted in `sys.color.onSurfaceVariant` via `currentColor` so it reads as quiet, monochrome chrome — illustrations stay monochrome unless they carry deliberate brand-moment intent. Separated from the headline by `sys.layout.stack.sm` (12). */
+  illustration?: React.ReactNode;
+  /** The required lead line. `sys.typo.heading.sm` in `sys.color.onSurface`. Names what the surface is for / why it is empty in one short line (e.g. 'No posts yet'). */
+  headline: React.ReactNode;
+  /** Optional supporting line below the headline. `sys.typo.body.sm` in `sys.color.onSurfaceVariant`, separated from the headline by `sys.layout.stack.2xs` (4). One sentence — the second of the three lines (e.g. 'Conversations you start or join will appear here'). */
+  body?: React.ReactNode;
+  /** { label, href?, onClick? } — the primary CTA. Renders a default-size primary `Button` (the surface's primary action — the one thing that fills the empty surface). Placed below the body with a `sys.layout.stack.md` (16) gap. There is NO `cta` slot to fill with a custom button; pass the action object so the primary Button is composed for you. */
+  action?: Record<string, unknown>;
+}
+export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof EmptyStatePropsOwn>, EmptyStatePropsOwn {}
+
 // ── Feed (feed/post) ──
 interface FeedPropsOwn {
   /** Editorial label — 'HOT', 'NEW', 'PINNED'. Opt-in; most posts render without one. */
@@ -491,9 +522,11 @@ export interface MetadataStandardProps extends Omit<React.HTMLAttributes<HTMLDiv
 
 interface MetadataCompactPropsOwn {
   variant: "compact";
+  /** Leading [Thumbnail](../thumbnail/thumbnail.md) at `size={32}` — same prop and rung as the [Standard](standard.md) head. Forwards every Thumbnail prop verbatim (`{ src, alt }`). When omitted, the Thumbnail renders its image-area fallback over `surfaceContainerHigh`. */
+  avatar?: Record<string, unknown>;
   /** Array of independently-linked identity items — canonical fill is `[company name, nickname]`, the nickname canonically last, displayed bare (no @ prefix). Each entry is either a string (renders as a stub-href link) or a `{ label, href, badge }` object — `badge` is an optional SINGLE presentational mark node rendered AFTER the item's link, outside the <a> (canonical fill: Badge variant="role" on the trailing nickname item). Items separate by middot. Same grammar as the standard sub's `meta`; here it is the whole cluster, so it is required. */
   meta: React.ReactNode;
-  /** Posting time at the line's trailing edge — plain text (never a link), preceded by a middot, in `label.sm` / `sys.color.outline` so it recedes behind the identity links. Required: the timestamp is what distinguishes a compact attribution from a bare identity row. */
+  /** Posting time at the line's trailing edge — plain text (never a link), in `label.sm` / `sys.color.outline` so it recedes behind the identity links. NOT preceded by a middot: the time is separated from the identity cluster by an `inline.md` (8) gap so it reads as a distinct trailing element rather than another identity item (mirrors the Standard head's name↔time treatment). Required: the timestamp is what distinguishes a compact attribution from a bare identity row. */
   timestamp: string;
 }
 export interface MetadataCompactProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof MetadataCompactPropsOwn>, MetadataCompactPropsOwn {}
@@ -594,6 +627,30 @@ export type NavigationBarProps =
   | NavigationBarSubProps
   | NavigationBarSearchProps;
 
+// ── PageShell (page-shell/page-shell) ──
+interface PageShellPropsOwn {
+  /** Rendered in flow at the top — a `NavigationBar`. Pays its own `safe-area-inset-top`; the shell does NOT re-pay it. Pinned by the flex column, never by `position: sticky` / `fixed`. */
+  nav?: React.ReactNode;
+  /** Rendered in flow at the bottom — a `TabBar`. Pays its own `safe-area-inset-bottom`; the shell does NOT re-pay it. Pinned by the flex column, never by `position: sticky` / `fixed`. */
+  tabBar?: React.ReactNode;
+  /** The scrolling body content — the sole scroll region. Rendered inside `<main class="chorus-page-shell__body">`. */
+  children: React.ReactNode;
+  /** Spread onto `<main>` — use to add a page gutter (`style={{ paddingInline: 'var(--sys-layout-page-md)' }}`) when the screen carries inline (non-full-bleed) content. `className` composes with `chorus-page-shell__body`; the rest spread as-is. Do NOT use it to re-pay a bar's safe-area inset. */
+  bodyProps?: Record<string, unknown>;
+  /** Composes with the shell root's own `chorus-page-shell` class. Use for placement only; never to override the pin/scroll mechanics. */
+  className?: string;
+}
+export interface PageShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof PageShellPropsOwn>, PageShellPropsOwn {}
+
+// ── Pagination (pagination/pagination) ──
+interface PaginationPropsOwn {
+  /** Total number of pages — one dot renders per page. Below 2 the component renders nothing. */
+  count?: number;
+  /** Zero-based index of the active page. Clamped to `0..count-1`. Owned by the host pager (e.g. updated from an IntersectionObserver on its scroll-snap targets). */
+  activeIndex?: number;
+}
+export interface PaginationProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof PaginationPropsOwn>, PaginationPropsOwn {}
+
 // ── ProfileHeader (profile-header/profile-header) ──
 interface ProfileHeaderPropsOwn {
   /** Entity name — channel topic, person, or company. Renders as the page-level `<h1>` at `sys.typo.heading.lg` / Semibold / `onSurface`. Single line; truncates with ellipsis at narrow widths. */
@@ -688,6 +745,17 @@ interface SkeletonPropsOwn {
 }
 export interface SkeletonProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof SkeletonPropsOwn>, SkeletonPropsOwn {}
 
+// ── Spinner (spinner/spinner) ──
+interface SpinnerPropsOwn {
+  /** Selects the arc diameter off the `icon.*` ladder. `medium` paints at `sys.icon.lg` (24px); `small` at `sys.icon.md` (16px). */
+  size?: "medium" | "small";
+  /** Optional loading copy rendered beside the arc in `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. When present it also supplies the accessible name, so `aria-label` is not required. */
+  label?: React.ReactNode;
+  /** Accessible label announced by screen readers. Defaults to `'Loading'`. Supply a more specific name (e.g. `'Signing in'`) when the wait scope is meaningful. Redundant when a visible `label` is passed. */
+  "aria-label"?: string;
+}
+export interface SpinnerProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof SpinnerPropsOwn>, SpinnerPropsOwn {}
+
 // ── StatusTag (status-tag/status-tag) ──
 interface StatusTagPropsOwn {
   /** Tonal fill / foreground pair. `neutral` is the quiet informational default; `error` is the rejection / blocked / failed state. */
@@ -813,7 +881,6 @@ export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
 export interface TabProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
 export interface FeedGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
 export interface FormFieldGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
-export interface PageShellProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
 export interface NavCardGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
 export interface CarouselProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
 export interface SideSheetGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
@@ -825,6 +892,7 @@ export const Banner: React.ForwardRefExoticComponent<BannerProps & React.RefAttr
 export const BottomSheet: React.ForwardRefExoticComponent<BottomSheetProps & React.RefAttributes<HTMLDivElement>>;
 export const Bubble: React.ForwardRefExoticComponent<BubbleProps & React.RefAttributes<HTMLDivElement>>;
 export const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export const ButtonGroup: React.ForwardRefExoticComponent<ButtonGroupProps & React.RefAttributes<HTMLDivElement>>;
 export const Fab: React.ForwardRefExoticComponent<FabProps & React.RefAttributes<HTMLButtonElement>>;
 export const SuggestionList: React.ForwardRefExoticComponent<SuggestionListProps & React.RefAttributes<HTMLDivElement>>;
 export const AvatarRail: React.ForwardRefExoticComponent<AvatarRailProps & React.RefAttributes<HTMLDivElement>>;
@@ -832,6 +900,7 @@ export const Chip: React.ForwardRefExoticComponent<ChipProps & React.RefAttribut
 export const Dialog: React.ForwardRefExoticComponent<DialogProps & React.RefAttributes<HTMLDivElement>>;
 export const Divider: React.ForwardRefExoticComponent<DividerProps & React.RefAttributes<HTMLElement>>;
 export const DirectoryList: React.ForwardRefExoticComponent<DirectoryListProps & React.RefAttributes<HTMLElement>>;
+export const EmptyState: React.ForwardRefExoticComponent<EmptyStateProps & React.RefAttributes<HTMLDivElement>>;
 export const Feed: React.ForwardRefExoticComponent<FeedProps & React.RefAttributes<HTMLElement>>;
 export const FeedAd: React.ForwardRefExoticComponent<FeedAdProps & React.RefAttributes<HTMLElement>>;
 export const FormField: React.ForwardRefExoticComponent<FormFieldProps & React.RefAttributes<HTMLElement>>;
@@ -842,12 +911,15 @@ export const Metadata: React.ForwardRefExoticComponent<MetadataProps & React.Ref
 export const NavCard: React.ForwardRefExoticComponent<NavCardProps & React.RefAttributes<HTMLButtonElement>>;
 export const NavList: React.ForwardRefExoticComponent<NavListProps & React.RefAttributes<HTMLElement>>;
 export const NavigationBar: React.ForwardRefExoticComponent<NavigationBarProps & React.RefAttributes<HTMLElement>>;
+export const PageShell: React.ForwardRefExoticComponent<PageShellProps & React.RefAttributes<HTMLDivElement>>;
+export const Pagination: React.ForwardRefExoticComponent<PaginationProps & React.RefAttributes<HTMLSpanElement>>;
 export const ProfileHeader: React.ForwardRefExoticComponent<ProfileHeaderProps & React.RefAttributes<HTMLElement>>;
 export const Progress: React.ForwardRefExoticComponent<ProgressProps & React.RefAttributes<HTMLDivElement>>;
 export const PostCarousel: React.ForwardRefExoticComponent<PostCarouselProps & React.RefAttributes<HTMLDivElement>>;
 export const ProfileCarousel: React.ForwardRefExoticComponent<ProfileCarouselProps & React.RefAttributes<HTMLDivElement>>;
 export const SideSheet: React.ForwardRefExoticComponent<SideSheetProps & React.RefAttributes<HTMLElement>>;
 export const Skeleton: React.ForwardRefExoticComponent<SkeletonProps & React.RefAttributes<HTMLSpanElement>>;
+export const Spinner: React.ForwardRefExoticComponent<SpinnerProps & React.RefAttributes<HTMLSpanElement>>;
 export const StatusTag: React.ForwardRefExoticComponent<StatusTagProps & React.RefAttributes<HTMLSpanElement>>;
 export const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;
 export const TabBar: React.ForwardRefExoticComponent<TabBarProps & React.RefAttributes<HTMLElement>>;
@@ -858,7 +930,6 @@ export const Tooltip: React.ForwardRefExoticComponent<TooltipProps & React.RefAt
 export const Tab: React.ForwardRefExoticComponent<TabProps & React.RefAttributes<HTMLElement>>;
 export const FeedGroup: React.ForwardRefExoticComponent<FeedGroupProps & React.RefAttributes<HTMLElement>>;
 export const FormFieldGroup: React.ForwardRefExoticComponent<FormFieldGroupProps & React.RefAttributes<HTMLElement>>;
-export const PageShell: React.ForwardRefExoticComponent<PageShellProps & React.RefAttributes<HTMLElement>>;
 export const NavCardGroup: React.ForwardRefExoticComponent<NavCardGroupProps & React.RefAttributes<HTMLElement>>;
 export const Carousel: React.ForwardRefExoticComponent<CarouselProps & React.RefAttributes<HTMLElement>>;
 export const SideSheetGroup: React.ForwardRefExoticComponent<SideSheetGroupProps & React.RefAttributes<HTMLElement>>;

package/dist/index.d.ts

@@ -32,12 +32,22 @@ export type BadgeProps =
 // ── Banner (banner/banner) ──
 interface BannerPropsOwn {
   appearance?: "default" | "accent" | "destructive";
+  /** Paints a `sys.borderWidth.hairline` (1) inset stroke around the container, toned to the appearance's color family and kept deliberately faint so it reads as a soft edge of the same tint, not a frame — the subtle gray hairline (`sys.color.outlineVariant`) on `default`'s gray-tinted fill, `primary` at 40% (`color-mix(sys.color.primary, 40%)`) on `accent`'s blue-tinted fill, `error` at 40% on `destructive`. Rendered as an inset box-shadow, never a real border, so toggling it cannot change the banner's footprint (see DESIGN.md → Border & Stroke). Reach for it when the tinted fill alone doesn't separate the banner from its host surface. */
+  outlined?: boolean;
+  /** On `accent`, paints the title + body in the neutral default foreground (`sys.color.onSurface`) and steps the action to `sys.color.primary` — i.e. the **Default appearance's** foreground treatment laid over the accent fill, decoupling the background tone from the text tone. Reach for it when the `primaryContainer` tint should still pull the eye but the copy should read as quiet, high-legibility body text rather than tonal `onPrimaryContainer` primary-family text (long-form explainers, dense asides). No effect on `default` (already `onSurface`) or `destructive` (the warning tone must carry through the copy). */
+  neutralBody?: boolean;
+  /** Optional heading line above the body. label.md (14 / Semibold 600) in the container's foreground, separated from the body by `sys.layout.stack.2xs` (4). Reach for it when the aside needs a scannable lead-in; omit for single-thought asides where the body carries itself. */
+  title?: React.ReactNode;
   /** A 16 × 16 (`sys.icon.md`) glyph at the container's leading edge. Inherits the banner's foreground (`currentColor`) so the mark reads as part of the body copy. The slot occupies the body.sm line-box height so the glyph centers on the **first line** of the body — multi-line bodies keep the icon anchored to the first-line cap, not the block center. Ignored when `thumbnail` is also passed. */
   icon?: React.ReactNode;
+  /** A 16 × 16 (`sys.icon.md`) glyph at the container's trailing edge, vertically centered against the whole block (`align-self: center`). Paints in `currentColor`. Reach for it when the banner leads somewhere — a forward affordance such as `ForwardCircleFillIcon` signaling the whole aside opens a destination. */
+  trailingIcon?: React.ReactNode;
   /** A leading visual rendered by [Thumbnail](../thumbnail/thumbnail.md) — used when the aside is anchored to a channel, author, or sub-brand image rather than to a glyph. Takes precedence over `icon`. */
   thumbnail?: React.ReactNode;
   /** { label, href? , onClick? } — a follow-through link rendered as a block child below the body. */
   action?: Record<string, unknown>;
+  /** A [Text Button](../button/text.md) (`<Button variant="text">`) rendered at the container's trailing edge, vertically centered against the whole block (`align-self: center`). Distinct from `action` (a follow-through link below the body): `trailingAction` is a compact inline commit that sits beside the copy — Dismiss, Enable, Undo. The button keeps full control of its own `size` and `appearance` per the button/text spec; **by default pick the appearance whose color family matches the banner fill** so the commit reads as part of the tinted block — `accent` banner → `appearance="accent"`, `default` banner → `appearance="default"`, `destructive` banner → the Text Button `destructive` flavor. Override only when a denser rung (`size="small"` / `"xsmall"`) or a different emphasis is deliberately wanted. The button also keeps its own `leadingIcon` / `trailingIcon` slots, so the commit can carry an in-button glyph (e.g. a trailing `ChevronRightIcon` on an *Enable* / *Continue* commit). Takes precedence over the banner-level `trailingIcon` when both are passed. */
+  trailingAction?: React.ReactNode;
   /** Body text — the explanation copy. */
   children: React.ReactNode;
 }
@@ -152,6 +162,14 @@ export type ButtonProps =
   | ButtonToggleProps
   | ButtonToolbarProps;
 
+// ── ButtonGroup (button/group) ──
+interface ButtonGroupPropsOwn {
+  variant?: "inline" | "docked";
+  orientation?: "horizontal" | "vertical";
+  label?: React.ReactNode;
+}
+export interface ButtonGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof ButtonGroupPropsOwn>, ButtonGroupPropsOwn {}
+
 // ── Fab (button/fab) ──
 interface FabPropsOwn {
   variant?: "fab";
@@ -249,6 +267,19 @@ interface DirectoryListPropsOwn {
 }
 export interface DirectoryListProps extends Omit<React.HTMLAttributes<HTMLElement>, keyof DirectoryListPropsOwn>, DirectoryListPropsOwn {}
 
+// ── EmptyState (empty-state/empty-state) ──
+interface EmptyStatePropsOwn {
+  /** Optional leading glyph or illustration, centered above the headline. Sized to a `ref.space.600` (48) box — larger than `sys.icon.lg` (24), realizing DESIGN.md's `icon.xl` or larger intent (no `icon.xl` icon-size rung exists; the icon scale stops at `lg`). Painted in `sys.color.onSurfaceVariant` via `currentColor` so it reads as quiet, monochrome chrome — illustrations stay monochrome unless they carry deliberate brand-moment intent. Separated from the headline by `sys.layout.stack.sm` (12). */
+  illustration?: React.ReactNode;
+  /** The required lead line. `sys.typo.heading.sm` in `sys.color.onSurface`. Names what the surface is for / why it is empty in one short line (e.g. 'No posts yet'). */
+  headline: React.ReactNode;
+  /** Optional supporting line below the headline. `sys.typo.body.sm` in `sys.color.onSurfaceVariant`, separated from the headline by `sys.layout.stack.2xs` (4). One sentence — the second of the three lines (e.g. 'Conversations you start or join will appear here'). */
+  body?: React.ReactNode;
+  /** { label, href?, onClick? } — the primary CTA. Renders a default-size primary `Button` (the surface's primary action — the one thing that fills the empty surface). Placed below the body with a `sys.layout.stack.md` (16) gap. There is NO `cta` slot to fill with a custom button; pass the action object so the primary Button is composed for you. */
+  action?: Record<string, unknown>;
+}
+export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof EmptyStatePropsOwn>, EmptyStatePropsOwn {}
+
 // ── Feed (feed/post) ──
 interface FeedPropsOwn {
   /** Editorial label — 'HOT', 'NEW', 'PINNED'. Opt-in; most posts render without one. */
@@ -491,9 +522,11 @@ export interface MetadataStandardProps extends Omit<React.HTMLAttributes<HTMLDiv
 
 interface MetadataCompactPropsOwn {
   variant: "compact";
+  /** Leading [Thumbnail](../thumbnail/thumbnail.md) at `size={32}` — same prop and rung as the [Standard](standard.md) head. Forwards every Thumbnail prop verbatim (`{ src, alt }`). When omitted, the Thumbnail renders its image-area fallback over `surfaceContainerHigh`. */
+  avatar?: Record<string, unknown>;
   /** Array of independently-linked identity items — canonical fill is `[company name, nickname]`, the nickname canonically last, displayed bare (no @ prefix). Each entry is either a string (renders as a stub-href link) or a `{ label, href, badge }` object — `badge` is an optional SINGLE presentational mark node rendered AFTER the item's link, outside the <a> (canonical fill: Badge variant="role" on the trailing nickname item). Items separate by middot. Same grammar as the standard sub's `meta`; here it is the whole cluster, so it is required. */
   meta: React.ReactNode;
-  /** Posting time at the line's trailing edge — plain text (never a link), preceded by a middot, in `label.sm` / `sys.color.outline` so it recedes behind the identity links. Required: the timestamp is what distinguishes a compact attribution from a bare identity row. */
+  /** Posting time at the line's trailing edge — plain text (never a link), in `label.sm` / `sys.color.outline` so it recedes behind the identity links. NOT preceded by a middot: the time is separated from the identity cluster by an `inline.md` (8) gap so it reads as a distinct trailing element rather than another identity item (mirrors the Standard head's name↔time treatment). Required: the timestamp is what distinguishes a compact attribution from a bare identity row. */
   timestamp: string;
 }
 export interface MetadataCompactProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof MetadataCompactPropsOwn>, MetadataCompactPropsOwn {}
@@ -594,6 +627,30 @@ export type NavigationBarProps =
   | NavigationBarSubProps
   | NavigationBarSearchProps;
 
+// ── PageShell (page-shell/page-shell) ──
+interface PageShellPropsOwn {
+  /** Rendered in flow at the top — a `NavigationBar`. Pays its own `safe-area-inset-top`; the shell does NOT re-pay it. Pinned by the flex column, never by `position: sticky` / `fixed`. */
+  nav?: React.ReactNode;
+  /** Rendered in flow at the bottom — a `TabBar`. Pays its own `safe-area-inset-bottom`; the shell does NOT re-pay it. Pinned by the flex column, never by `position: sticky` / `fixed`. */
+  tabBar?: React.ReactNode;
+  /** The scrolling body content — the sole scroll region. Rendered inside `<main class="chorus-page-shell__body">`. */
+  children: React.ReactNode;
+  /** Spread onto `<main>` — use to add a page gutter (`style={{ paddingInline: 'var(--sys-layout-page-md)' }}`) when the screen carries inline (non-full-bleed) content. `className` composes with `chorus-page-shell__body`; the rest spread as-is. Do NOT use it to re-pay a bar's safe-area inset. */
+  bodyProps?: Record<string, unknown>;
+  /** Composes with the shell root's own `chorus-page-shell` class. Use for placement only; never to override the pin/scroll mechanics. */
+  className?: string;
+}
+export interface PageShellProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof PageShellPropsOwn>, PageShellPropsOwn {}
+
+// ── Pagination (pagination/pagination) ──
+interface PaginationPropsOwn {
+  /** Total number of pages — one dot renders per page. Below 2 the component renders nothing. */
+  count?: number;
+  /** Zero-based index of the active page. Clamped to `0..count-1`. Owned by the host pager (e.g. updated from an IntersectionObserver on its scroll-snap targets). */
+  activeIndex?: number;
+}
+export interface PaginationProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof PaginationPropsOwn>, PaginationPropsOwn {}
+
 // ── ProfileHeader (profile-header/profile-header) ──
 interface ProfileHeaderPropsOwn {
   /** Entity name — channel topic, person, or company. Renders as the page-level `<h1>` at `sys.typo.heading.lg` / Semibold / `onSurface`. Single line; truncates with ellipsis at narrow widths. */
@@ -688,6 +745,17 @@ interface SkeletonPropsOwn {
 }
 export interface SkeletonProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof SkeletonPropsOwn>, SkeletonPropsOwn {}
 
+// ── Spinner (spinner/spinner) ──
+interface SpinnerPropsOwn {
+  /** Selects the arc diameter off the `icon.*` ladder. `medium` paints at `sys.icon.lg` (24px); `small` at `sys.icon.md` (16px). */
+  size?: "medium" | "small";
+  /** Optional loading copy rendered beside the arc in `sys.typo.body.sm` / `sys.color.onSurfaceVariant`. When present it also supplies the accessible name, so `aria-label` is not required. */
+  label?: React.ReactNode;
+  /** Accessible label announced by screen readers. Defaults to `'Loading'`. Supply a more specific name (e.g. `'Signing in'`) when the wait scope is meaningful. Redundant when a visible `label` is passed. */
+  "aria-label"?: string;
+}
+export interface SpinnerProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, keyof SpinnerPropsOwn>, SpinnerPropsOwn {}
+
 // ── StatusTag (status-tag/status-tag) ──
 interface StatusTagPropsOwn {
   /** Tonal fill / foreground pair. `neutral` is the quiet informational default; `error` is the rejection / blocked / failed state. */
@@ -813,7 +881,6 @@ export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
 export interface TabProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
 export interface FeedGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
 export interface FormFieldGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
-export interface PageShellProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
 export interface NavCardGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
 export interface CarouselProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
 export interface SideSheetGroupProps extends React.HTMLAttributes<HTMLElement> { children?: React.ReactNode; [key: string]: unknown; }
@@ -825,6 +892,7 @@ export const Banner: React.ForwardRefExoticComponent<BannerProps & React.RefAttr
 export const BottomSheet: React.ForwardRefExoticComponent<BottomSheetProps & React.RefAttributes<HTMLDivElement>>;
 export const Bubble: React.ForwardRefExoticComponent<BubbleProps & React.RefAttributes<HTMLDivElement>>;
 export const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export const ButtonGroup: React.ForwardRefExoticComponent<ButtonGroupProps & React.RefAttributes<HTMLDivElement>>;
 export const Fab: React.ForwardRefExoticComponent<FabProps & React.RefAttributes<HTMLButtonElement>>;
 export const SuggestionList: React.ForwardRefExoticComponent<SuggestionListProps & React.RefAttributes<HTMLDivElement>>;
 export const AvatarRail: React.ForwardRefExoticComponent<AvatarRailProps & React.RefAttributes<HTMLDivElement>>;
@@ -832,6 +900,7 @@ export const Chip: React.ForwardRefExoticComponent<ChipProps & React.RefAttribut
 export const Dialog: React.ForwardRefExoticComponent<DialogProps & React.RefAttributes<HTMLDivElement>>;
 export const Divider: React.ForwardRefExoticComponent<DividerProps & React.RefAttributes<HTMLElement>>;
 export const DirectoryList: React.ForwardRefExoticComponent<DirectoryListProps & React.RefAttributes<HTMLElement>>;
+export const EmptyState: React.ForwardRefExoticComponent<EmptyStateProps & React.RefAttributes<HTMLDivElement>>;
 export const Feed: React.ForwardRefExoticComponent<FeedProps & React.RefAttributes<HTMLElement>>;
 export const FeedAd: React.ForwardRefExoticComponent<FeedAdProps & React.RefAttributes<HTMLElement>>;
 export const FormField: React.ForwardRefExoticComponent<FormFieldProps & React.RefAttributes<HTMLElement>>;
@@ -842,12 +911,15 @@ export const Metadata: React.ForwardRefExoticComponent<MetadataProps & React.Ref
 export const NavCard: React.ForwardRefExoticComponent<NavCardProps & React.RefAttributes<HTMLButtonElement>>;
 export const NavList: React.ForwardRefExoticComponent<NavListProps & React.RefAttributes<HTMLElement>>;
 export const NavigationBar: React.ForwardRefExoticComponent<NavigationBarProps & React.RefAttributes<HTMLElement>>;
+export const PageShell: React.ForwardRefExoticComponent<PageShellProps & React.RefAttributes<HTMLDivElement>>;
+export const Pagination: React.ForwardRefExoticComponent<PaginationProps & React.RefAttributes<HTMLSpanElement>>;
 export const ProfileHeader: React.ForwardRefExoticComponent<ProfileHeaderProps & React.RefAttributes<HTMLElement>>;
 export const Progress: React.ForwardRefExoticComponent<ProgressProps & React.RefAttributes<HTMLDivElement>>;
 export const PostCarousel: React.ForwardRefExoticComponent<PostCarouselProps & React.RefAttributes<HTMLDivElement>>;
 export const ProfileCarousel: React.ForwardRefExoticComponent<ProfileCarouselProps & React.RefAttributes<HTMLDivElement>>;
 export const SideSheet: React.ForwardRefExoticComponent<SideSheetProps & React.RefAttributes<HTMLElement>>;
 export const Skeleton: React.ForwardRefExoticComponent<SkeletonProps & React.RefAttributes<HTMLSpanElement>>;
+export const Spinner: React.ForwardRefExoticComponent<SpinnerProps & React.RefAttributes<HTMLSpanElement>>;
 export const StatusTag: React.ForwardRefExoticComponent<StatusTagProps & React.RefAttributes<HTMLSpanElement>>;
 export const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;
 export const TabBar: React.ForwardRefExoticComponent<TabBarProps & React.RefAttributes<HTMLElement>>;
@@ -858,7 +930,6 @@ export const Tooltip: React.ForwardRefExoticComponent<TooltipProps & React.RefAt
 export const Tab: React.ForwardRefExoticComponent<TabProps & React.RefAttributes<HTMLElement>>;
 export const FeedGroup: React.ForwardRefExoticComponent<FeedGroupProps & React.RefAttributes<HTMLElement>>;
 export const FormFieldGroup: React.ForwardRefExoticComponent<FormFieldGroupProps & React.RefAttributes<HTMLElement>>;
-export const PageShell: React.ForwardRefExoticComponent<PageShellProps & React.RefAttributes<HTMLElement>>;
 export const NavCardGroup: React.ForwardRefExoticComponent<NavCardGroupProps & React.RefAttributes<HTMLElement>>;
 export const Carousel: React.ForwardRefExoticComponent<CarouselProps & React.RefAttributes<HTMLElement>>;
 export const SideSheetGroup: React.ForwardRefExoticComponent<SideSheetGroupProps & React.RefAttributes<HTMLElement>>;