@cosxai/ui 1.0.0-alpha.10 → 1.0.0-alpha.12

package/CHANGELOG.md

@@ -1,3 +1,37 @@
+## 1.0.0-alpha.12 (2026-10-04)
+
+From the Metaroom app (Motion & Native Feel §04, Account):
+
+- BottomSheet: rises in 280ms and now leaves in 220ms instead of vanishing
+  (it stays mounted for its exit; the scrim fades with it and carries
+  `data-leaving` while it goes). `detents="two"`: half (60%) and full —
+  typing in it, scrolling its list or dragging up lifts it to full,
+  dragging down from full goes back to half; dragging above its top gives
+  way at 0.3×. `action` (the title row's button) and `footer` (pinned below
+  the list). The rise starts when Radix puts the content on the page, so it
+  always plays. Buttons and fields in the title row don't start a drag.
+- Avatar: size 64 (Account's profile photo), initials at 20px.
+
+## 1.0.0-alpha.11 (2026-10-01)
+
+App shell for the Agent module (Metaroom Agent, desktop and phone):
+
+- Popover, PopoverTrigger, PopoverContent, PopoverAnchor, PopoverClose: a
+  small non-modal panel on Radix Popover — portal, flips to fit, Esc and
+  outside click close, focus returns. `inline` keeps it out of the portal.
+- Avatar: a person's photo or initials, sizes 20–52, tone chrome / brand,
+  optional ring; decorative unless `label` is given.
+- BottomSheet: the phone's sheet on Radix Dialog — drag handle, title, drag
+  or flick down to close, scrim, 20px top corners, safe-area padding, a
+  screen-reader close button.
+- BottomTabs: the phone tab bar — 48×28 pill in the brand field for the
+  current tab, counts, avatar tab, disabled tabs at 40% (aria-disabled,
+  `onDisabledSelect`).
+- AppRail + AppRailSlot: the 60px desktop rail — workspace slot, 40×38
+  module buttons (brand field when current), counts and dots, disabled
+  modules with the caller's tooltip, account slot. A nav of buttons with
+  aria-current.
+
 ## 1.0.0-alpha.10 (2026-09-30)
 
 - BrandLoader: the COSX loop as a loading indicator (Claude Design, COSX

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosxai/ui",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.12",
   "description": "COSX Design System 3.0 \u2014 tokens, Tailwind v4 theme and React components",
   "license": "UNLICENSED",
   "type": "module",

package/src/components/AppRail.tsx

@@ -0,0 +1,141 @@
+import type { LucideIcon } from 'lucide-react';
+import { forwardRef, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { formatCount } from './Button';
+import { Icon } from './Icon';
+import { Tooltip } from './Tooltip';
+
+export type AppRailItem = {
+  key: string;
+  icon: LucideIcon;
+  /** The module's name: accessible name and tooltip. */
+  label: string;
+  /** A count on the corner; hidden at zero (and on a disabled item), 99+ above 99. */
+  count?: number | undefined;
+  /** A dot on the corner — something new, no number. A count wins. */
+  dot?: boolean | undefined;
+  /** Not available yet: 40% opacity, aria-disabled (still focusable); a press calls `onDisabledSelect`. */
+  disabled?: boolean | undefined;
+  /** The tooltip while disabled ("My tasks · Coming soon"); the caller words it. @default label */
+  disabledHint?: string | undefined;
+};
+
+export type AppRailProps = Omit<ComponentProps<'nav'>, 'onChange' | 'children'> & {
+  items: AppRailItem[];
+  /** The current module's key. */
+  value: string;
+  onChange: (key: string) => void;
+  /** A disabled item was pressed — say why (a toast: "Coming soon"). */
+  onDisabledSelect?: ((key: string) => void) | undefined;
+  /** The landmark's accessible name ("Modules"). */
+  label: string;
+  /** Top slot: the workspace, usually an AppRailSlot holding a 36px WorkspaceMark. */
+  workspace?: ReactNode;
+  /** Bottom slot: the account, usually an AppRailSlot shape="round" holding a 32px Avatar. */
+  account?: ReactNode;
+};
+
+/**
+ * AppRail — the 60px desktop module rail (Metaroom Agent): the workspace at
+ * the top, one 40×38 icon button per module, a flexible gap, the account at
+ * the bottom. The current module takes the workspace's field colour
+ * (--brand-field); modules not built yet stay visible at 40% with a tooltip
+ * that says so. Counts and dots use --brand-mark.
+ *
+ * Compose with: AppRailSlot + WorkspaceMark / Avatar for the slots, each
+ * usually a PopoverTrigger (workspace switcher, account card); BottomTabs is
+ * the same navigation on phones.
+ *
+ * A nav landmark of buttons; the current one has aria-current="page".
+ * Forwards ref to the <nav>; spreads `...rest` onto it.
+ */
+export const AppRail = forwardRef<HTMLElement, AppRailProps>(function AppRail(
+  { items, value, onChange, onDisabledSelect, label, workspace, account, className, ...rest },
+  ref,
+) {
+  return (
+    <nav
+      ref={ref}
+      aria-label={label}
+      className={cn('flex w-[60px] shrink-0 flex-col items-center gap-1 border-r border-rule bg-sunk py-3.5 font-sans text-fg', className)}
+      {...rest}
+    >
+      {workspace && <div className="mb-3 flex">{workspace}</div>}
+      {items.map((it) => {
+        const on = it.key === value;
+        const count = it.disabled || it.count === undefined ? null : formatCount(it.count);
+        return (
+          <Tooltip key={it.key} side="right" content={it.disabled ? (it.disabledHint ?? it.label) : it.label}>
+            <button
+              type="button"
+              aria-label={count ? `${it.label} (${count})` : it.label}
+              aria-current={on ? 'page' : undefined}
+              aria-disabled={it.disabled || undefined}
+              onClick={() => (it.disabled ? onDisabledSelect?.(it.key) : onChange(it.key))}
+              className={cn(
+                'relative grid h-[38px] w-10 shrink-0 cursor-pointer place-items-center rounded-md border-0 p-0 outline-none',
+                'transition-colors duration-[120ms] ease-standard focus-visible:shadow-(--focus-ring)',
+                on ? 'bg-brand-field text-ink' : 'bg-transparent text-fg',
+                !on && !it.disabled && 'hover:bg-hover',
+                it.disabled && 'cursor-not-allowed opacity-40',
+              )}
+            >
+              <Icon icon={it.icon} size={17} />
+              {count ? (
+                <span
+                  aria-hidden
+                  className="absolute top-1 right-[5px] h-3.5 min-w-3.5 rounded-pill bg-brand-mark px-[3px] text-center text-[9px] leading-[14px] font-bold text-ink tabular-nums"
+                >
+                  {count}
+                </span>
+              ) : (
+                it.dot && !it.disabled && <span aria-hidden data-dot="" className="absolute top-[7px] right-[9px] size-[7px] rounded-pill bg-brand-mark" />
+              )}
+            </button>
+          </Tooltip>
+        );
+      })}
+      <div className="flex-1" />
+      {account && <div className="flex">{account}</div>}
+    </nav>
+  );
+});
+
+export type AppRailSlotProps = Omit<ComponentProps<'button'>, 'aria-label'> & {
+  /** Accessible name ("Switch workspace", "Account"). */
+  label: string;
+  /** tile (the workspace, 9px corners) · round (the account). @default "tile" */
+  shape?: 'tile' | 'round' | undefined;
+  /** Its popover is open: an ink ring with a gap. Set from the popover's open state. */
+  active?: boolean | undefined;
+};
+
+/**
+ * AppRailSlot — the bare button around the rail's workspace mark or account
+ * avatar: no fill of its own, the focus ring, and the ink ring while its
+ * popover is open. Works as `PopoverTrigger asChild` (forwards ref and
+ * props).
+ */
+export const AppRailSlot = forwardRef<HTMLButtonElement, AppRailSlotProps>(function AppRailSlot(
+  { label, shape = 'tile', active = false, className, children, ...rest },
+  ref,
+) {
+  return (
+    <button
+      ref={ref}
+      type="button"
+      aria-label={label}
+      title={label}
+      className={cn(
+        'inline-flex shrink-0 cursor-pointer border-0 bg-transparent p-0 outline-none focus-visible:shadow-(--focus-ring) disabled:cursor-default',
+        shape === 'round' ? 'rounded-pill' : 'rounded-[9px]',
+        active && 'shadow-[0_0_0_2px_var(--bg-sunk),0_0_0_4px_var(--text-primary)]',
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </button>
+  );
+});

package/src/components/Avatar.tsx

@@ -0,0 +1,75 @@
+import { forwardRef, useEffect, useRef, useState, type ComponentProps } from 'react';
+
+import { cn } from '../lib/cn';
+import { initialsOf } from './ActivityTimeline';
+
+export type AvatarSize = 20 | 24 | 28 | 32 | 36 | 40 | 52 | 64;
+
+// Initials size per avatar size (Metaroom Agent / Account: 22→9, 28→10,
+// 32→11, 40→13, 52→16, Account's profile photo 64→20).
+const TYPE: Record<AvatarSize, number> = { 20: 9, 24: 9, 28: 10, 32: 11, 36: 12, 40: 13, 52: 16, 64: 20 };
+
+export type AvatarProps = Omit<ComponentProps<'span'>, 'children'> & {
+  /** The person's name: gives the initials (two Latin initials, or the first hanzi). */
+  name: string;
+  /** Their photo; the initials show while it is unset or when it fails to load. */
+  src?: string | undefined;
+  /** Initials to use instead of ones taken from `name`. */
+  initials?: string | undefined;
+  /** px. @default 32 */
+  size?: AvatarSize | undefined;
+  /** chrome (a grey disc) · brand (the workspace's field colour, for "you"). @default "chrome" */
+  tone?: 'chrome' | 'brand' | undefined;
+  /** An ink ring with a gap — the avatar's menu is open, or it is the current tab.
+   *  The gap takes `--avatar-ring-gap` (default the page colour); set it to the ground behind. */
+  ring?: boolean | undefined;
+  /** Accessible name. Without it the avatar is decorative: the name sits beside it. */
+  label?: string | undefined;
+};
+
+/**
+ * Avatar — a person: their photo, or their initials on a round disc. Sizes
+ * 20–64 as the Metaroom app uses them (rail account 32, phone tab 24, lists
+ * 28–40, Me card 52, Account's profile photo 64). For the Agent use MetaAvatar (@cosxai/chat); for a
+ * workspace, WorkspaceMark.
+ *
+ * Compose with: AppRail `account` slot (inside a button), BottomTabs item
+ * `avatar`, list rows beside the person's name (decorative there).
+ *
+ * Forwards ref to the root <span>; spreads `...rest` onto it.
+ */
+export const Avatar = forwardRef<HTMLSpanElement, AvatarProps>(function Avatar(
+  { name, src, initials, size = 32, tone = 'chrome', ring = false, label, className, style, ...rest },
+  ref,
+) {
+  const [failed, setFailed] = useState(false);
+  const img = useRef<HTMLImageElement>(null);
+  useEffect(() => setFailed(false), [src]);
+  // A server-rendered page can fail the image before React is listening.
+  useEffect(() => {
+    const el = img.current;
+    if (el?.complete && el.naturalWidth === 0) setFailed(true);
+  }, [src]);
+  const photo = Boolean(src) && !failed;
+  return (
+    <span
+      ref={ref}
+      {...(label ? { role: 'img', 'aria-label': label } : { 'aria-hidden': true })}
+      data-tone={tone}
+      className={cn(
+        'inline-grid shrink-0 place-items-center overflow-hidden rounded-pill font-sans leading-none font-semibold select-none',
+        tone === 'brand' ? 'bg-brand-field text-ink' : 'bg-chrome text-fg',
+        ring && 'shadow-[0_0_0_2px_var(--avatar-ring-gap,var(--bg-page)),0_0_0_4px_var(--text-primary)]',
+        className,
+      )}
+      style={{ width: size, height: size, fontSize: TYPE[size] ?? Math.round(size * 0.32), ...style }}
+      {...rest}
+    >
+      {photo ? (
+        <img ref={img} src={src} alt="" className="size-full object-cover" onError={() => setFailed(true)} />
+      ) : (
+        (initials ?? initialsOf(name))
+      )}
+    </span>
+  );
+});

package/src/components/BottomSheet.tsx

@@ -0,0 +1,253 @@
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type ComponentProps, type PointerEvent as ReactPointerEvent, type ReactElement, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { useReducedMotion } from './status-motion';
+
+export type BottomSheetProps = Omit<ComponentProps<typeof DialogPrimitive.Content>, 'title' | 'children' | 'ref'> & {
+  /** Says what the sheet is for ("Switch workspace", "Language"). Labels the dialog. */
+  title: ReactNode;
+  /** Keep the title for screen readers only. @default false */
+  hideTitle?: boolean | undefined;
+  /** A line under the title, read out with it. */
+  description?: ReactNode;
+  /** The main button, at the end of the title row (seen at half height too). */
+  action?: ReactNode;
+  /** Pinned below the scrolling content, above the home indicator (a Done or Add button). */
+  footer?: ReactNode;
+  /**
+   * "content": as tall as what it holds, up to half the screen — menus and
+   * confirmations. "two": half (60%) and full — browsing and picking;
+   * typing in it, scrolling its list or dragging it up lifts it to full,
+   * dragging down from full goes back to half. @default "content"
+   */
+  detents?: 'content' | 'two' | undefined;
+  children?: ReactNode;
+  open?: boolean | undefined;
+  defaultOpen?: boolean | undefined;
+  onOpenChange?: ((open: boolean) => void) | undefined;
+  /** The element that opens it (rendered asChild). Or control `open`. */
+  trigger?: ReactElement | undefined;
+  /** Accessible name of the screen-reader close button (touch readers have no Esc). @default "Close" */
+  closeLabel?: string | undefined;
+};
+
+// Motion & Native Feel §04: rises in 280ms, leaves in 220ms (a quarter faster).
+const ENTER_MS = 280;
+const EXIT_MS = 220;
+const ENTER = 'cubic-bezier(.16,1,.3,1)';
+const EXIT = 'cubic-bezier(.4,0,1,1)';
+const RELEASE = 'cubic-bezier(.2,.8,.2,1)';
+// A drag past this share of the sheet's height (at most CLOSE_MAX), or a flick, closes it.
+const CLOSE_SHARE = 0.25;
+const CLOSE_MAX = 120;
+const FLICK = 0.6; // px per ms
+// Dragged above its top, the sheet gives way at this rate.
+const OVERSHOOT = 0.3;
+const HALF = 0.6;
+
+const currentY = (el: HTMLElement) => {
+  try {
+    return new DOMMatrixReadOnly(getComputedStyle(el).transform).m42 || 0;
+  } catch {
+    return 0;
+  }
+};
+
+/**
+ * BottomSheet — the phone's sheet: a page-coloured sheet rising from the
+ * bottom with a drag handle and a title (Metaroom Agent phone: switch
+ * workspace, language, an object's menu; link files, with two heights).
+ * 20px top corners over the scrim; the bottom padding clears the home
+ * indicator (safe area). Rises in 280ms and leaves in 220ms. Drag the
+ * handle or the title row down, or flick, to close (from full height: back
+ * to half); Esc, a tap on the scrim and the screen-reader close button
+ * close it too. Built on Radix Dialog: focus moves in, is trapped and
+ * returns to the opener.
+ *
+ * Compose with: BottomTabs (the Me tab opens it), rows of 48–56px buttons
+ * inside. On desktop use Popover or DialogContent instead.
+ */
+export function BottomSheet({
+  title,
+  hideTitle = false,
+  description,
+  action,
+  footer,
+  detents = 'content',
+  children,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  trigger,
+  closeLabel = 'Close',
+  className,
+  style,
+  onOpenAutoFocus,
+  onFocusCapture,
+  ...rest
+}: BottomSheetProps) {
+  const [openState, setOpenState] = useState(defaultOpen);
+  const open = openProp ?? openState;
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (openProp === undefined) setOpenState(next);
+      onOpenChange?.(next);
+    },
+    [openProp, onOpenChange],
+  );
+
+  const reduce = useReducedMotion();
+  // Mounted while open and while leaving (the exit plays before it goes)
+  const [mounted, setMounted] = useState(open);
+  const [full, setFull] = useState(false);
+  const sheet = useRef<HTMLDivElement | null>(null);
+  const scrim = useRef<HTMLDivElement | null>(null);
+  const drag = useRef<{ y0: number; t0: number } | null>(null);
+  const entering = useRef(open);
+
+  useLayoutEffect(() => {
+    if (open) {
+      entering.current = true;
+      setMounted(true);
+      setFull(false);
+      return;
+    }
+    if (!mounted) return;
+    const el = sheet.current;
+    if (!el || reduce || typeof el.animate !== 'function') {
+      setMounted(false);
+      return;
+    }
+    // The scrim's leaving is a CSS animation: listeners (a status bar
+    // following the page) hear it start, as with Dialog's
+    scrim.current?.setAttribute('data-leaving', '');
+    const from = currentY(el) || parseFloat(el.style.transform.replace(/[^\d.-]/g, '')) || 0;
+    el.style.transform = '';
+    el.animate([{ transform: `translateY(${from}px)` }, { transform: 'translateY(100%)' }], { duration: EXIT_MS, easing: EXIT, fill: 'forwards' }).onfinish = () => setMounted(false);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open]);
+
+  // Radix puts the content on the page a render after ours: the rise starts when it arrives
+  const setSheet = (el: HTMLDivElement | null) => {
+    sheet.current = el;
+    if (!el || !entering.current) return;
+    entering.current = false;
+    if (reduce || typeof el.animate !== 'function') return;
+    el.animate([{ transform: 'translateY(100%)' }, { transform: 'translateY(0)' }], { duration: ENTER_MS, easing: ENTER });
+  };
+
+  useEffect(() => () => void (drag.current = null), []);
+
+  const height = () => sheet.current?.offsetHeight ?? 0;
+  const settle = () => {
+    const el = sheet.current;
+    if (!el) return;
+    const from = el.style.transform;
+    el.style.transform = '';
+    if (from && !reduce && typeof el.animate === 'function') {
+      el.animate([{ transform: from }, { transform: 'translateY(0)' }], { duration: 200, easing: RELEASE });
+    }
+  };
+  const onDown = (e: ReactPointerEvent<HTMLDivElement>) => {
+    if (e.button !== 0) return;
+    if ((e.target as HTMLElement).closest('button, a, input, textarea, select')) return;
+    drag.current = { y0: e.clientY, t0: performance.now() };
+    e.currentTarget.setPointerCapture?.(e.pointerId);
+  };
+  const onMove = (e: ReactPointerEvent<HTMLDivElement>) => {
+    const d = drag.current;
+    if (!d || !sheet.current) return;
+    const raw = e.clientY - d.y0;
+    const dy = raw < 0 ? raw * OVERSHOOT : raw;
+    sheet.current.style.transform = `translateY(${dy}px)`;
+  };
+  const onUp = (e: ReactPointerEvent<HTMLDivElement>) => {
+    const d = drag.current;
+    drag.current = null;
+    if (!d) return;
+    const dist = e.clientY - d.y0;
+    const speed = dist / Math.max(1, performance.now() - d.t0);
+    const h = height();
+    const limit = h > 0 ? Math.min(CLOSE_MAX, h * CLOSE_SHARE) : CLOSE_MAX;
+    const down = dist > limit || (dist > 8 && speed > FLICK);
+    if (down && detents === 'two' && full) {
+      setFull(false);
+      settle();
+    } else if (down) {
+      setOpen(false);
+    } else {
+      if (detents === 'two' && !full && (dist < -24 || speed < -FLICK)) setFull(true);
+      settle();
+    }
+  };
+
+  const two = detents === 'two';
+  return (
+    // Open while shown, leaving included; the trigger stays the same element throughout
+    <DialogPrimitive.Root open={mounted} onOpenChange={(o) => (o ? setOpen(true) : open && setOpen(false))}>
+      {trigger && <DialogPrimitive.Trigger asChild>{trigger}</DialogPrimitive.Trigger>}
+      {mounted && (
+      <DialogPrimitive.Portal>
+        <DialogPrimitive.Overlay ref={scrim} className="cosx-sheet-scrim fixed inset-0 z-50 bg-scrim" />
+        <DialogPrimitive.Content
+          ref={setSheet}
+          {...(description ? {} : { 'aria-describedby': undefined })}
+          onOpenAutoFocus={(e) => {
+            onOpenAutoFocus?.(e);
+            if (e.defaultPrevented) return;
+            // The sheet itself takes focus (read out by its title), not the first row.
+            e.preventDefault();
+            (e.currentTarget as HTMLElement | null)?.focus();
+          }}
+          // Typing lifts a two-height sheet to full (the keyboard needs the room)
+          onFocusCapture={(e) => {
+            onFocusCapture?.(e);
+            if (two && (e.target as HTMLElement).matches('input, textarea')) setFull(true);
+          }}
+          className={cn(
+            'fixed inset-x-0 bottom-0 z-50 flex flex-col rounded-t-[20px] bg-page px-4 pt-2 font-sans text-fg outline-none',
+            two ? 'transition-[height] duration-300 ease-[cubic-bezier(.2,0,0,1)]' : 'max-h-[90dvh]',
+            className,
+          )}
+          style={{
+            paddingBottom: footer ? 'max(16px, calc(env(safe-area-inset-bottom, 0px) + 8px))' : 'max(30px, calc(env(safe-area-inset-bottom, 0px) + 12px))',
+            ...(two ? { height: full ? 'calc(100dvh - env(safe-area-inset-top, 0px) - 8px)' : `${HALF * 100}dvh` } : {}),
+            ...style,
+          }}
+          {...rest}
+        >
+          <div
+            data-sheet-drag=""
+            className="flex shrink-0 cursor-grab touch-none flex-col select-none active:cursor-grabbing"
+            onPointerDown={onDown}
+            onPointerMove={onMove}
+            onPointerUp={onUp}
+            onPointerCancel={() => {
+              drag.current = null;
+              settle();
+            }}
+          >
+            <span aria-hidden className="mb-2.5 h-1 w-9 self-center rounded-pill bg-rule" />
+            <div className="flex items-center gap-3">
+              <DialogPrimitive.Title className={cn('m-0 min-w-0 flex-1 truncate px-1 pb-2 text-[17px] leading-[1.3] font-medium', hideTitle && 'sr-only')}>{title}</DialogPrimitive.Title>
+              {action && <div className="shrink-0 pb-2">{action}</div>}
+            </div>
+            {description && <DialogPrimitive.Description className="m-0 px-1 pb-2 text-small text-fg-secondary">{description}</DialogPrimitive.Description>}
+          </div>
+          <div
+            className={cn('flex min-h-0 flex-1 flex-col gap-0.5', two && !full ? 'overflow-hidden' : 'overflow-y-auto overscroll-contain')}
+            // At half height, a pull up on the list lifts the sheet first
+            onWheel={(e) => two && !full && e.deltaY > 0 && setFull(true)}
+            onTouchMove={() => two && !full && setFull(true)}
+          >
+            {children}
+          </div>
+          {footer && <div className="shrink-0 border-t border-rule-soft pt-2.5">{footer}</div>}
+          <DialogPrimitive.Close className="sr-only">{closeLabel}</DialogPrimitive.Close>
+        </DialogPrimitive.Content>
+      </DialogPrimitive.Portal>
+      )}
+    </DialogPrimitive.Root>
+  );
+}

package/src/components/BottomTabs.tsx

@@ -0,0 +1,102 @@
+import type { LucideIcon } from 'lucide-react';
+import { forwardRef, type ComponentProps, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn';
+import { formatCount } from './Button';
+import { Icon } from './Icon';
+
+export type BottomTabItem = {
+  key: string;
+  /** A Lucide icon. Ignored when `avatar` is set. */
+  icon?: LucideIcon | undefined;
+  label: string;
+  /** A count on the corner; hidden at zero (and on a disabled tab), 99+ above 99. */
+  count?: number | undefined;
+  /** Not available yet: 40% opacity, aria-disabled; a press calls `onDisabledSelect`. */
+  disabled?: boolean | undefined;
+  /** Shown in place of the icon — the person's Avatar (size 24) on the Me tab. */
+  avatar?: ReactNode;
+};
+
+export type BottomTabsProps = Omit<ComponentProps<'nav'>, 'onChange' | 'children'> & {
+  items: BottomTabItem[];
+  /** The current tab's key. */
+  value: string;
+  onChange: (key: string) => void;
+  /** A disabled tab was pressed — say why (a toast: "Coming soon"). */
+  onDisabledSelect?: ((key: string) => void) | undefined;
+  /** The landmark's accessible name ("Modules"). */
+  label: string;
+};
+
+/**
+ * BottomTabs — the phone's tab bar (Metaroom Agent phone): an icon in a
+ * 48×28 pill over an 11px label; the current tab's pill takes the
+ * workspace's field colour (--brand-field), a person's avatar gets an ink
+ * ring. Tabs not built yet stay visible at 40% opacity (aria-disabled, still
+ * focusable, so a press can explain). The bottom padding clears the home
+ * indicator.
+ *
+ * Compose with: Avatar (size 24) for the Me tab, BottomSheet opened from
+ * it; AppRail is the same navigation on desktop.
+ *
+ * A nav landmark of buttons; the current one has aria-current="page".
+ * Forwards ref to the <nav>; spreads `...rest` onto it.
+ */
+export const BottomTabs = forwardRef<HTMLElement, BottomTabsProps>(function BottomTabs(
+  { items, value, onChange, onDisabledSelect, label, className, style, ...rest },
+  ref,
+) {
+  return (
+    <nav
+      ref={ref}
+      aria-label={label}
+      className={cn('flex shrink-0 border-t border-rule bg-page px-2 pt-1.5 font-sans text-fg', className)}
+      style={{ paddingBottom: 'max(22px, env(safe-area-inset-bottom, 0px))', ...style }}
+      {...rest}
+    >
+      {items.map((it) => {
+        const on = it.key === value;
+        const count = it.disabled || it.count === undefined ? null : formatCount(it.count);
+        return (
+          <button
+            key={it.key}
+            type="button"
+            aria-current={on ? 'page' : undefined}
+            aria-disabled={it.disabled || undefined}
+            aria-label={count ? `${it.label} (${count})` : undefined}
+            onClick={() => (it.disabled ? onDisabledSelect?.(it.key) : onChange(it.key))}
+            className={cn(
+              'relative flex min-h-12 flex-1 cursor-pointer flex-col items-center justify-center gap-[3px] rounded-md border-0 bg-transparent p-0 text-fg outline-none focus-visible:shadow-(--focus-ring)',
+              it.disabled && 'cursor-not-allowed opacity-40',
+            )}
+          >
+            <span
+              className={cn(
+                'grid h-7 w-12 place-items-center rounded-pill transition-colors duration-[120ms] ease-standard',
+                on && 'bg-brand-field text-ink',
+              )}
+            >
+              {it.avatar ? (
+                <span aria-hidden className={cn('inline-flex rounded-pill', on && 'shadow-[0_0_0_1.5px_var(--text-primary)]')}>
+                  {it.avatar}
+                </span>
+              ) : (
+                it.icon && <Icon icon={it.icon} size={18} />
+              )}
+            </span>
+            <span className="text-[11px] leading-none font-medium">{it.label}</span>
+            {count && (
+              <span
+                aria-hidden
+                className="absolute top-0.5 left-1/2 ml-2 h-3.5 min-w-3.5 rounded-pill bg-brand-mark px-[3px] text-center text-[9px] leading-[14px] font-bold text-ink tabular-nums"
+              >
+                {count}
+              </span>
+            )}
+          </button>
+        );
+      })}
+    </nav>
+  );
+});

package/src/components/Popover.tsx

@@ -0,0 +1,46 @@
+import * as PopoverPrimitive from '@radix-ui/react-popover';
+import type { ComponentProps } from 'react';
+
+import { cn } from '../lib/cn';
+
+/** Popover root: `open` / `onOpenChange`, or uncontrolled with PopoverTrigger. */
+export const Popover = PopoverPrimitive.Root;
+/** The element that opens it (asChild onto a Button or IconButton). Focus returns here on close. */
+export const PopoverTrigger = PopoverPrimitive.Trigger;
+/** Positions the content against something other than the trigger (a row, a caret). */
+export const PopoverAnchor = PopoverPrimitive.Anchor;
+/** Closes the popover (asChild onto a Done button). */
+export const PopoverClose = PopoverPrimitive.Close;
+
+export type PopoverContentProps = ComponentProps<typeof PopoverPrimitive.Content> & {
+  /** Keep it in the tree without a portal (inside a dialog that must contain it). @default false */
+  inline?: boolean | undefined;
+};
+
+/**
+ * PopoverContent — a small non-modal panel next to its trigger: the files of
+ * a conversation, a workspace switcher, the account card (Metaroom Agent).
+ * Page colour, 14px corners, a hairline edge; no shadow (3.0 has none).
+ * Renders in a portal and flips to stay in view (placement auto, Radix
+ * Popover); Esc and an outside click close it and focus returns to the
+ * trigger.
+ *
+ * Compose with: PopoverTrigger asChild onto an IconButton / AppRail slot;
+ * Menu for a list of actions instead (it brings arrow-key navigation).
+ */
+export function PopoverContent({ className, sideOffset = 6, collisionPadding = 8, align = 'start', inline = false, ...rest }: PopoverContentProps) {
+  const content = (
+    <PopoverPrimitive.Content
+      sideOffset={sideOffset}
+      collisionPadding={collisionPadding}
+      align={align}
+      className={cn(
+        'z-[60] w-[320px] max-w-[calc(100vw-16px)] overflow-y-auto rounded-[14px] border border-rule bg-page p-2 font-sans text-ui text-fg outline-none',
+        'max-h-(--radix-popover-content-available-height)',
+        className,
+      )}
+      {...rest}
+    />
+  );
+  return inline ? content : <PopoverPrimitive.Portal>{content}</PopoverPrimitive.Portal>;
+}

package/src/components.css

@@ -0,0 +1,10 @@
+/* Component motion that has to be CSS (listeners hear animationstart):
+   BottomSheet's scrim fades in with the sheet (280ms) and out as it
+   leaves (220ms, data-leaving) — Motion & Native Feel §04. */
+@keyframes cosx-sheet-scrim-in { from { opacity: 0; } }
+@keyframes cosx-sheet-scrim-out { to { opacity: 0; } }
+.cosx-sheet-scrim { animation: cosx-sheet-scrim-in 280ms cubic-bezier(.16,1,.3,1); }
+.cosx-sheet-scrim[data-leaving] { animation: cosx-sheet-scrim-out 220ms cubic-bezier(.4,0,1,1) forwards; }
+@media (prefers-reduced-motion: reduce) {
+  .cosx-sheet-scrim, .cosx-sheet-scrim[data-leaving] { animation: none; }
+}

package/src/index.ts

@@ -77,3 +77,10 @@ export { WindowDrop, useWindowDrop, type WindowDropProps } from './components/Wi
 export { AuthIconTile, AuthLayout, AuthPanel, AuthStepHead, type AuthIconTileProps, type AuthLayoutProps, type AuthPanelProps, type AuthStepHeadProps } from './components/AuthLayout';
 export { ThemeSwitch, type ThemeSwitchLabels, type ThemeSwitchProps } from './components/ThemeSwitch';
 export { WorkspaceMark, WorkspaceRow, type WorkspaceMarkProps, type WorkspaceRowProps } from './components/WorkspaceRow';
+
+// Stage 4 — app shell (Metaroom Agent)
+export { AppRail, AppRailSlot, type AppRailItem, type AppRailProps, type AppRailSlotProps } from './components/AppRail';
+export { Avatar, type AvatarProps, type AvatarSize } from './components/Avatar';
+export { BottomSheet, type BottomSheetProps } from './components/BottomSheet';
+export { BottomTabs, type BottomTabItem, type BottomTabsProps } from './components/BottomTabs';
+export { Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverTrigger, type PopoverContentProps } from './components/Popover';

package/src/styles.css

@@ -17,3 +17,4 @@
 @import "./brand.css";
 @import "./modes.css";
 @import "./fonts.css";
+@import "./components.css";