@xenide-io/the-old-ui-theme 0.4.4 → 0.4.8

package/dist/suite.d.mts

@@ -1,9 +1,13 @@
 import * as react from 'react';
-import { ReactNode, ComponentType, ButtonHTMLAttributes, CSSProperties, ElementType, PointerEvent } from 'react';
+import { ReactNode, ComponentType, ButtonHTMLAttributes, CSSProperties, PointerEvent, ElementType } from 'react';
 import { ClassValue } from 'clsx';
 export { m } from 'motion/react';
 
-/** Full-bleed theme wash + soft clouds; uses ph-* tokens from each app's theme. */
+/**
+ * Today page content wrapper with soft atmosphere.
+ * Does not own scrolling — `#main-content` is the scrollport so sticky headers work.
+ * Glow/clouds are absolute and do not create a nested scrollport.
+ */
 declare function TodayPageFrame({ children }: {
     children: ReactNode;
 }): react.JSX.Element;
@@ -50,8 +54,56 @@ declare function getTodayGreeting(user?: {
     overdueCount?: number;
     hours?: number;
 }): string;
-declare function TodayHero({ message, }: {
+declare function TodayHero({ message, brief, briefMeta, }: {
     message?: ReactNode;
+    /** AI / local focus brief under the greeting. */
+    brief?: ReactNode;
+    briefMeta?: ReactNode;
+}): react.JSX.Element;
+type TodayPrimaryAccent = 'tides' | 'turtletime' | 'kraken' | 'shellstack' | 'neutral';
+/**
+ * Compact primary CTA for Today — one action per app.
+ * Colours live in suite-skin (.today-primary-action); no idle animation.
+ */
+declare function TodayPrimaryAction({ label, description, icon, accent, onClick, href, loading, active, className, dataTest, }: {
+    label: string;
+    description?: string;
+    icon?: ReactNode;
+    accent?: TodayPrimaryAccent;
+    onClick?: () => void;
+    href?: string;
+    loading?: boolean;
+    /** e.g. timer already running */
+    active?: boolean;
+    className?: string;
+    dataTest?: string;
+}): react.JSX.Element;
+declare function TodayEmptyAction({ title, description, actionLabel, href, onClick, dataTest, }: {
+    title: string;
+    description?: string;
+    actionLabel?: string;
+    href?: string;
+    onClick?: () => void;
+    dataTest?: string;
+}): react.JSX.Element;
+/** Desktop Today shell: main column + sticky Ask AI / brief aside. */
+declare function TodayLayout({ primary, main, aside, className, }: {
+    primary?: ReactNode;
+    main: ReactNode;
+    aside?: ReactNode;
+    className?: string;
+}): react.JSX.Element;
+/**
+ * Today Ask AI CTA — opens the suite assistant (not Kraken Deep Research).
+ * Prefer onClick → openSuiteAskAi(); href is a fallback only.
+ */
+declare function TodayAskAiCard({ title, description, cta, className, onClick, href, }: {
+    title?: string;
+    description?: string;
+    cta?: string;
+    className?: string;
+    onClick?: () => void;
+    href?: string;
 }): react.JSX.Element;
 declare function TodaySection({ icon: Icon, iconClassName, title, description, action, testId, children, }: {
     icon: LucideIcon;
@@ -192,14 +244,16 @@ declare function DeferredChrome({ children }: {
  * close, body scroll-lock and focus hand-off while open. Nav content stays
  * app-side via `children`.
  */
-declare function SuiteMobileDrawer({ open, onClose, children, side, showCloseButton, closeLabel, backdropLabel, dialogLabel, durationMs, dataTest, panelDataTest, panelClassName, }: {
+declare function SuiteMobileDrawer({ open, onClose, children, side, showCloseButton, title, closeLabel, backdropLabel, dialogLabel, durationMs, dataTest, panelDataTest, panelClassName, }: {
     open: boolean;
     onClose: () => void;
     children: ReactNode;
     /** Edge the panel slides in from. */
-    side?: 'left' | 'right';
+    side?: "left" | "right";
     /** Standard close row (h-14, trailing X button) above the content. */
     showCloseButton?: boolean;
+    /** Optional label in the standard close row. */
+    title?: ReactNode;
     closeLabel?: string;
     backdropLabel?: string;
     /** Accessible name for the dialog panel. */
@@ -237,6 +291,25 @@ declare function SuiteMobileHeader({ onMenuClick, menuIcon: MenuIcon, title, act
     className?: string;
 }): react.JSX.Element;
 
+interface SuiteSettingsLayoutProps {
+    children: ReactNode;
+    sidebar: ReactNode;
+    mobileNav?: ReactNode;
+    loading?: ReactNode;
+    title?: ReactNode;
+    description?: ReactNode;
+    header?: ReactNode;
+    dataTest?: string;
+    headerDataTest?: string;
+    className?: string;
+    contentClassName?: string;
+}
+/**
+ * Canonical settings geometry for every suite app.
+ * Apps own nav data and content; the suite owns spacing, scrolling and breakpoints.
+ */
+declare function SuiteSettingsLayout({ children, sidebar, mobileNav, loading, title, description, header, dataTest, headerDataTest, className, contentClassName, }: SuiteSettingsLayoutProps): react.JSX.Element;
+
 interface SuiteUserMenuProps {
     name?: string | null;
     email?: string | null;
@@ -308,18 +381,24 @@ declare const SUITE_APPS: readonly SuiteAppDefinition[];
 declare const SUITE_APP_MAP: Readonly<Record<SuiteAppSlug, SuiteAppDefinition>>;
 /** Resolve an app's base URL: env var first, dev fallback second. */
 declare function suiteAppBaseUrl(slug: SuiteAppSlug): string;
+/**
+ * Suite notification links are often stored as `/dashboard/...` relative to the
+ * *source* app. Resolving them with the current product origin opens the wrong
+ * app — prefix with that app's base URL instead.
+ */
+declare function resolveSuiteNotificationHref(href: string | null | undefined, sourceApp: string | null | undefined): string;
 
 /**
  * Today-page loading/empty calibrating state. Apps inject their branded
- * AppSpinner; `variant` picks the ornamentation style:
- * - `ring` — large spinner ring + ping behind the sun (TurtleTime/ShellStack)
- * - `pulse` — pulsing sun only (Tides/Kraken)
+ * AppSpinner. Kept deliberately quiet — single soft fade + one spinner,
+ * no ping/pulse stacks that compete with OAuth/launch handoffs.
  */
-declare function TodayCalibrating({ onRetry, retrying, className, spinner: Spinner, variant, retrySpinnerClassName, }: {
+declare function TodayCalibrating({ onRetry, retrying, className, spinner: Spinner, variant: _variant, retrySpinnerClassName, }: {
     onRetry?: () => void;
     retrying?: boolean;
     className?: string;
     spinner: SuiteSpinnerComponent;
+    /** @deprecated Kept for call-site compat; ornamentation is always calm. */
     variant?: 'ring' | 'pulse';
     retrySpinnerClassName?: string;
 }): react.JSX.Element;
@@ -367,36 +446,50 @@ declare function SuiteThemeProvider({ config, children, }: {
 }): react.JSX.Element;
 declare function useSuiteTheme(): SuiteThemeContextValue;
 
+declare const SUITE_OPEN_ASK_AI_EVENT = "shellstack:open-ask-ai";
+type SuiteAskAiOpenDetail = {
+    prompt?: string;
+};
+/** Open the suite Ask AI panel from anywhere (Today card, command palette, …). */
+declare function openSuiteAskAi(detail?: SuiteAskAiOpenDetail): void;
 interface SuiteAiPreset {
     label: string;
     prompt: string;
 }
+interface SuiteAiChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    created_at?: string;
+}
 /**
- * Thin ShellStack AI slide-over shared by suite apps.
+ * Suite-wide Ask AI slide-over — Notion-style continuous chat.
  *
- * One-shot completions via the shared `/api/ai/complete` endpoint. Apps
- * inject their API helpers, preset prompts, brand icon and spinner. Renders
- * its own floating launcher so it can be mounted once in the authenticated
- * app shell.
+ * One thread per workspace (persisted via injected fetch/send/clear helpers).
+ * Not Kraken Deep Research. Apps mount this once in the authenticated shell.
  */
-declare function SuiteAiPanel({ presets, emptyState, fetchStatus, complete, brandIcon: BrandIcon, spinner: Spinner, }: {
-    presets: SuiteAiPreset[];
-    /** Idle-state hint copy shown before the first request. */
-    emptyState: ReactNode;
-    fetchStatus: () => Promise<{
+declare function SuiteAiPanel({ presets, emptyState, title, fetchChat, sendMessage, clearChat, brandIcon: BrandIcon, spinner: Spinner, hideLauncher, }: {
+    presets?: SuiteAiPreset[];
+    emptyState?: ReactNode;
+    title?: string;
+    fetchChat: () => Promise<{
+        messages: SuiteAiChatMessage[];
         configured: boolean;
     }>;
-    complete: (params: {
+    sendMessage: (params: {
         prompt: string;
     }) => Promise<{
-        text: string;
+        messages: SuiteAiChatMessage[];
+        reply: string;
     }>;
-    brandIcon: ComponentType<{
+    clearChat: () => Promise<void>;
+    brandIcon?: ComponentType<{
         className?: string;
     }>;
     spinner: ComponentType<{
         className?: string;
     }>;
+    /** When true, only Today / events open the panel (no floating button). */
+    hideLauncher?: boolean;
 }): react.JSX.Element;
 
 /**
@@ -516,6 +609,23 @@ declare function SuiteAppIcon({ app, size, label, className, style, }: SuiteAppI
 /** Mount non-critical chrome after the browser is idle (or a short timeout). */
 declare function useIdleMount(timeoutMs?: number): boolean;
 
+declare const SIDEBAR_RAIL_WIDTH = 56;
+declare const SIDEBAR_COLLAPSE_THRESHOLD = 80;
+declare const SIDEBAR_MIN_EXPANDED_WIDTH = 180;
+declare const SIDEBAR_MAX_WIDTH = 320;
+declare const SIDEBAR_DEFAULT_WIDTH = 320;
+/**
+ * Shared suite sidebar resizing: drag below the threshold to collapse,
+ * drag the rail edge out to expand, and double-click to reset.
+ */
+declare function useSidebarWidth(storageKey: string): {
+    width: number;
+    collapsed: boolean;
+    setCollapsed: (value: boolean) => void;
+    resetWidth: () => void;
+    startResize: (event: PointerEvent<HTMLDivElement>) => void;
+};
+
 declare function cn(...inputs: ClassValue[]): string;
 
 /**
@@ -570,13 +680,8 @@ declare const SUITE_SPRINGS: {
 };
 type SuiteSpringName = keyof typeof SUITE_SPRINGS;
 
-declare const WIDTHS: {
-    readonly full: "max-w-none";
-    readonly wide: "max-w-7xl";
-    readonly content: "max-w-6xl";
-    readonly narrow: "max-w-4xl";
-};
-type SuitePageWidth = keyof typeof WIDTHS;
+/** Width tokens — applied as data-width; CSS in suite-skin.css owns max-width. */
+type SuitePageWidth = 'full' | 'wide' | 'content' | 'narrow' | 'reading';
 interface SuiteBreadcrumbsProps {
     items: {
         label: ReactNode;
@@ -605,7 +710,9 @@ todayIcon, todayIconClassName,
 /** Small badge/pill next to the title (e.g. "Beta", org name). */
 badge, 
 /** Breadcrumb line rendered above the title. */
-breadcrumb, }: {
+breadcrumb, 
+/** Stick to the top of the scrollport (desktop page titles). */
+sticky, }: {
     title: ReactNode;
     description?: ReactNode;
     eyebrow?: ReactNode;
@@ -618,6 +725,7 @@ breadcrumb, }: {
     todayIconClassName?: string;
     badge?: ReactNode;
     breadcrumb?: ReactNode;
+    sticky?: boolean;
 }): react.JSX.Element;
 declare function SuiteToolbar({ children, className, label, dataTest, }: {
     children: ReactNode;
@@ -676,10 +784,7 @@ declare function SuiteEmptyState({ icon, title, description, action, className,
 interface SuiteSettingsNavItem {
     label: string;
     href: string;
-    icon: ComponentType<{
-        className?: string;
-        'aria-hidden'?: boolean;
-    }> | ReactNode;
+    icon: ElementType | ReactNode;
     testId?: string;
 }
 interface SuiteSettingsMobileNavProps {
@@ -687,6 +792,8 @@ interface SuiteSettingsMobileNavProps {
     activeHref: string;
     onSelect: (href: string) => void;
     dataTest?: string;
+    ariaLabel?: string;
+    className?: string;
 }
 /**
  * Horizontal scrollable settings nav for mobile.
@@ -694,7 +801,7 @@ interface SuiteSettingsMobileNavProps {
  * meet 44px touch targets, and preserve visual hierarchy (Law of UX: Hick's Law,
  * Recognition over Recall).
  */
-declare function SuiteSettingsMobileNav({ items, activeHref, onSelect, dataTest, }: SuiteSettingsMobileNavProps): react.JSX.Element;
+declare function SuiteSettingsMobileNav({ items, activeHref, onSelect, dataTest, ariaLabel, className, }: SuiteSettingsMobileNavProps): react.JSX.Element;
 
 type CollapsedNode = ReactNode | ((collapsed: boolean) => ReactNode);
 interface SuiteSidebarNavItem {
@@ -743,6 +850,11 @@ interface SuiteAppLayoutProps {
     sidebarWidth?: number;
     /** True when the sidebar is collapsed to the icon rail. */
     collapsed?: boolean;
+    /**
+     * When true, `#main-content` does not scroll — the page owns an internal
+     * scrollport (e.g. Deep Research: fixed header + composer, chat scrolls).
+     */
+    lockMainScroll?: boolean;
     /** Drag this to resize the sidebar. */
     onStartResize?: (e: PointerEvent<HTMLDivElement>) => void;
     /** Double-click to reset sidebar width. */
@@ -750,11 +862,10 @@ interface SuiteAppLayoutProps {
     className?: string;
 }
 /**
- * Responsive ShellStack app shell. Desktop: resizable fixed sidebar +
- * scrollable content with an optional drag handle. Mobile/tablet: mobile
- * header + content + bottom nav. This is the single layout primitive every
- * app should use.
+ * Responsive ShellStack app shell. One content tree (no duplicate children),
+ * one `#main-content` landmark. Desktop: fixed sidebar + scrollable main.
+ * Mobile: header + main + bottom nav.
  */
-declare function SuiteAppLayout({ sidebar, children, mobileHeader, bottomNav, sidebarWidth, collapsed, onStartResize, onResetWidth, className, }: SuiteAppLayoutProps): react.JSX.Element;
+declare function SuiteAppLayout({ sidebar, children, mobileHeader, bottomNav, sidebarWidth, collapsed, lockMainScroll, onStartResize, onResetWidth, className, }: SuiteAppLayoutProps): react.JSX.Element;
 
-export { APP_ACCENTS, APP_GLYPHS, AnimatedMoon, AnimatedSun, AppSwitcher, AppSwitcherChevron, AppSwitcherMark, CommandPaletteHost, DeferredChrome, SUITE_APPS, SUITE_APP_MAP, SUITE_GLYPHS, SUITE_ICON_NAMES, SUITE_SPRINGS, SourceAppGlyph, type SuiteAccentSlug, SuiteAiPanel, type SuiteAiPreset, type SuiteAppAccent, type SuiteAppDefinition, type SuiteAppEntry, SuiteAppIcon, type SuiteAppIconProps, SuiteAppLayout, type SuiteAppLayoutProps, type SuiteAppSlug, SuiteAppStrip, SuiteBottomNav, type SuiteBottomNavItem, SuiteBreadcrumbs, type SuiteBreadcrumbsProps, type SuiteCommandItem, type SuiteCommandPaletteComponent, type SuiteDropdownItemComponent, type SuiteDropdownMenuComponent, type SuiteDropdownMenuProps, SuiteEmptyState, type SuiteGlyph, type SuiteGlyphElement, SuiteIcon, type SuiteIconName, type SuiteIconProps, SuiteMobileDrawer, SuiteMobileHeader, SuiteMotionProvider, type SuiteNotification, SuiteNotificationBell, type SuiteNotificationsResponse, SuitePage, SuitePageHeader, type SuitePageWidth, type SuiteResolvedTheme, SuiteSectionHeader, SuiteSettingsMobileNav, type SuiteSettingsNavItem, SuiteSidebar, type SuiteSidebarNavItem, SuiteSkeleton, SuiteSkeletonCard, SuiteSkeletonList, type SuiteSpinnerComponent, type SuiteSpringName, SuiteTabList, type SuiteTheme, type SuiteThemeConfig, type SuiteThemeContextValue, SuiteThemeProvider, SuiteToolbar, SuiteUserMenu, type SuiteUserMenuProps, TodayCalibrating, TodayEmptyState, TodayHero, TodayPageFrame, TodayPanel, TodaySection, TodayTimeIcon, TodayTopBar, appSwitcherMarkClass, appSwitcherMenuItemClass, appSwitcherTriggerClass, cn, getTodayGreeting, sourceToSuiteApp, suiteAppBaseUrl, suiteAppLabel, useIdleMount, useSuiteTheme };
+export { APP_ACCENTS, APP_GLYPHS, AnimatedMoon, AnimatedSun, AppSwitcher, AppSwitcherChevron, AppSwitcherMark, CommandPaletteHost, DeferredChrome, SIDEBAR_COLLAPSE_THRESHOLD, SIDEBAR_DEFAULT_WIDTH, SIDEBAR_MAX_WIDTH, SIDEBAR_MIN_EXPANDED_WIDTH, SIDEBAR_RAIL_WIDTH, SUITE_APPS, SUITE_APP_MAP, SUITE_GLYPHS, SUITE_ICON_NAMES, SUITE_OPEN_ASK_AI_EVENT, SUITE_SPRINGS, SourceAppGlyph, type SuiteAccentSlug, type SuiteAiChatMessage, SuiteAiPanel, type SuiteAiPreset, type SuiteAppAccent, type SuiteAppDefinition, type SuiteAppEntry, SuiteAppIcon, type SuiteAppIconProps, SuiteAppLayout, type SuiteAppLayoutProps, type SuiteAppSlug, SuiteAppStrip, type SuiteAskAiOpenDetail, SuiteBottomNav, type SuiteBottomNavItem, SuiteBreadcrumbs, type SuiteBreadcrumbsProps, type SuiteCommandItem, type SuiteCommandPaletteComponent, type SuiteDropdownItemComponent, type SuiteDropdownMenuComponent, type SuiteDropdownMenuProps, SuiteEmptyState, type SuiteGlyph, type SuiteGlyphElement, SuiteIcon, type SuiteIconName, type SuiteIconProps, SuiteMobileDrawer, SuiteMobileHeader, SuiteMotionProvider, type SuiteNotification, SuiteNotificationBell, type SuiteNotificationsResponse, SuitePage, SuitePageHeader, type SuitePageWidth, type SuiteResolvedTheme, SuiteSectionHeader, SuiteSettingsLayout, type SuiteSettingsLayoutProps, SuiteSettingsMobileNav, type SuiteSettingsNavItem, SuiteSidebar, type SuiteSidebarNavItem, SuiteSkeleton, SuiteSkeletonCard, SuiteSkeletonList, type SuiteSpinnerComponent, type SuiteSpringName, SuiteTabList, type SuiteTheme, type SuiteThemeConfig, type SuiteThemeContextValue, SuiteThemeProvider, SuiteToolbar, SuiteUserMenu, type SuiteUserMenuProps, TodayAskAiCard, TodayCalibrating, TodayEmptyAction, TodayEmptyState, TodayHero, TodayLayout, TodayPageFrame, TodayPanel, type TodayPrimaryAccent, TodayPrimaryAction, TodaySection, TodayTimeIcon, TodayTopBar, appSwitcherMarkClass, appSwitcherMenuItemClass, appSwitcherTriggerClass, cn, getTodayGreeting, openSuiteAskAi, resolveSuiteNotificationHref, sourceToSuiteApp, suiteAppBaseUrl, suiteAppLabel, useIdleMount, useSidebarWidth, useSuiteTheme };

package/dist/suite.d.ts

@@ -1,9 +1,13 @@
 import * as react from 'react';
-import { ReactNode, ComponentType, ButtonHTMLAttributes, CSSProperties, ElementType, PointerEvent } from 'react';
+import { ReactNode, ComponentType, ButtonHTMLAttributes, CSSProperties, PointerEvent, ElementType } from 'react';
 import { ClassValue } from 'clsx';
 export { m } from 'motion/react';
 
-/** Full-bleed theme wash + soft clouds; uses ph-* tokens from each app's theme. */
+/**
+ * Today page content wrapper with soft atmosphere.
+ * Does not own scrolling — `#main-content` is the scrollport so sticky headers work.
+ * Glow/clouds are absolute and do not create a nested scrollport.
+ */
 declare function TodayPageFrame({ children }: {
     children: ReactNode;
 }): react.JSX.Element;
@@ -50,8 +54,56 @@ declare function getTodayGreeting(user?: {
     overdueCount?: number;
     hours?: number;
 }): string;
-declare function TodayHero({ message, }: {
+declare function TodayHero({ message, brief, briefMeta, }: {
     message?: ReactNode;
+    /** AI / local focus brief under the greeting. */
+    brief?: ReactNode;
+    briefMeta?: ReactNode;
+}): react.JSX.Element;
+type TodayPrimaryAccent = 'tides' | 'turtletime' | 'kraken' | 'shellstack' | 'neutral';
+/**
+ * Compact primary CTA for Today — one action per app.
+ * Colours live in suite-skin (.today-primary-action); no idle animation.
+ */
+declare function TodayPrimaryAction({ label, description, icon, accent, onClick, href, loading, active, className, dataTest, }: {
+    label: string;
+    description?: string;
+    icon?: ReactNode;
+    accent?: TodayPrimaryAccent;
+    onClick?: () => void;
+    href?: string;
+    loading?: boolean;
+    /** e.g. timer already running */
+    active?: boolean;
+    className?: string;
+    dataTest?: string;
+}): react.JSX.Element;
+declare function TodayEmptyAction({ title, description, actionLabel, href, onClick, dataTest, }: {
+    title: string;
+    description?: string;
+    actionLabel?: string;
+    href?: string;
+    onClick?: () => void;
+    dataTest?: string;
+}): react.JSX.Element;
+/** Desktop Today shell: main column + sticky Ask AI / brief aside. */
+declare function TodayLayout({ primary, main, aside, className, }: {
+    primary?: ReactNode;
+    main: ReactNode;
+    aside?: ReactNode;
+    className?: string;
+}): react.JSX.Element;
+/**
+ * Today Ask AI CTA — opens the suite assistant (not Kraken Deep Research).
+ * Prefer onClick → openSuiteAskAi(); href is a fallback only.
+ */
+declare function TodayAskAiCard({ title, description, cta, className, onClick, href, }: {
+    title?: string;
+    description?: string;
+    cta?: string;
+    className?: string;
+    onClick?: () => void;
+    href?: string;
 }): react.JSX.Element;
 declare function TodaySection({ icon: Icon, iconClassName, title, description, action, testId, children, }: {
     icon: LucideIcon;
@@ -192,14 +244,16 @@ declare function DeferredChrome({ children }: {
  * close, body scroll-lock and focus hand-off while open. Nav content stays
  * app-side via `children`.
  */
-declare function SuiteMobileDrawer({ open, onClose, children, side, showCloseButton, closeLabel, backdropLabel, dialogLabel, durationMs, dataTest, panelDataTest, panelClassName, }: {
+declare function SuiteMobileDrawer({ open, onClose, children, side, showCloseButton, title, closeLabel, backdropLabel, dialogLabel, durationMs, dataTest, panelDataTest, panelClassName, }: {
     open: boolean;
     onClose: () => void;
     children: ReactNode;
     /** Edge the panel slides in from. */
-    side?: 'left' | 'right';
+    side?: "left" | "right";
     /** Standard close row (h-14, trailing X button) above the content. */
     showCloseButton?: boolean;
+    /** Optional label in the standard close row. */
+    title?: ReactNode;
     closeLabel?: string;
     backdropLabel?: string;
     /** Accessible name for the dialog panel. */
@@ -237,6 +291,25 @@ declare function SuiteMobileHeader({ onMenuClick, menuIcon: MenuIcon, title, act
     className?: string;
 }): react.JSX.Element;
 
+interface SuiteSettingsLayoutProps {
+    children: ReactNode;
+    sidebar: ReactNode;
+    mobileNav?: ReactNode;
+    loading?: ReactNode;
+    title?: ReactNode;
+    description?: ReactNode;
+    header?: ReactNode;
+    dataTest?: string;
+    headerDataTest?: string;
+    className?: string;
+    contentClassName?: string;
+}
+/**
+ * Canonical settings geometry for every suite app.
+ * Apps own nav data and content; the suite owns spacing, scrolling and breakpoints.
+ */
+declare function SuiteSettingsLayout({ children, sidebar, mobileNav, loading, title, description, header, dataTest, headerDataTest, className, contentClassName, }: SuiteSettingsLayoutProps): react.JSX.Element;
+
 interface SuiteUserMenuProps {
     name?: string | null;
     email?: string | null;
@@ -308,18 +381,24 @@ declare const SUITE_APPS: readonly SuiteAppDefinition[];
 declare const SUITE_APP_MAP: Readonly<Record<SuiteAppSlug, SuiteAppDefinition>>;
 /** Resolve an app's base URL: env var first, dev fallback second. */
 declare function suiteAppBaseUrl(slug: SuiteAppSlug): string;
+/**
+ * Suite notification links are often stored as `/dashboard/...` relative to the
+ * *source* app. Resolving them with the current product origin opens the wrong
+ * app — prefix with that app's base URL instead.
+ */
+declare function resolveSuiteNotificationHref(href: string | null | undefined, sourceApp: string | null | undefined): string;
 
 /**
  * Today-page loading/empty calibrating state. Apps inject their branded
- * AppSpinner; `variant` picks the ornamentation style:
- * - `ring` — large spinner ring + ping behind the sun (TurtleTime/ShellStack)
- * - `pulse` — pulsing sun only (Tides/Kraken)
+ * AppSpinner. Kept deliberately quiet — single soft fade + one spinner,
+ * no ping/pulse stacks that compete with OAuth/launch handoffs.
  */
-declare function TodayCalibrating({ onRetry, retrying, className, spinner: Spinner, variant, retrySpinnerClassName, }: {
+declare function TodayCalibrating({ onRetry, retrying, className, spinner: Spinner, variant: _variant, retrySpinnerClassName, }: {
     onRetry?: () => void;
     retrying?: boolean;
     className?: string;
     spinner: SuiteSpinnerComponent;
+    /** @deprecated Kept for call-site compat; ornamentation is always calm. */
     variant?: 'ring' | 'pulse';
     retrySpinnerClassName?: string;
 }): react.JSX.Element;
@@ -367,36 +446,50 @@ declare function SuiteThemeProvider({ config, children, }: {
 }): react.JSX.Element;
 declare function useSuiteTheme(): SuiteThemeContextValue;
 
+declare const SUITE_OPEN_ASK_AI_EVENT = "shellstack:open-ask-ai";
+type SuiteAskAiOpenDetail = {
+    prompt?: string;
+};
+/** Open the suite Ask AI panel from anywhere (Today card, command palette, …). */
+declare function openSuiteAskAi(detail?: SuiteAskAiOpenDetail): void;
 interface SuiteAiPreset {
     label: string;
     prompt: string;
 }
+interface SuiteAiChatMessage {
+    role: 'user' | 'assistant';
+    content: string;
+    created_at?: string;
+}
 /**
- * Thin ShellStack AI slide-over shared by suite apps.
+ * Suite-wide Ask AI slide-over — Notion-style continuous chat.
  *
- * One-shot completions via the shared `/api/ai/complete` endpoint. Apps
- * inject their API helpers, preset prompts, brand icon and spinner. Renders
- * its own floating launcher so it can be mounted once in the authenticated
- * app shell.
+ * One thread per workspace (persisted via injected fetch/send/clear helpers).
+ * Not Kraken Deep Research. Apps mount this once in the authenticated shell.
  */
-declare function SuiteAiPanel({ presets, emptyState, fetchStatus, complete, brandIcon: BrandIcon, spinner: Spinner, }: {
-    presets: SuiteAiPreset[];
-    /** Idle-state hint copy shown before the first request. */
-    emptyState: ReactNode;
-    fetchStatus: () => Promise<{
+declare function SuiteAiPanel({ presets, emptyState, title, fetchChat, sendMessage, clearChat, brandIcon: BrandIcon, spinner: Spinner, hideLauncher, }: {
+    presets?: SuiteAiPreset[];
+    emptyState?: ReactNode;
+    title?: string;
+    fetchChat: () => Promise<{
+        messages: SuiteAiChatMessage[];
         configured: boolean;
     }>;
-    complete: (params: {
+    sendMessage: (params: {
         prompt: string;
     }) => Promise<{
-        text: string;
+        messages: SuiteAiChatMessage[];
+        reply: string;
     }>;
-    brandIcon: ComponentType<{
+    clearChat: () => Promise<void>;
+    brandIcon?: ComponentType<{
         className?: string;
     }>;
     spinner: ComponentType<{
         className?: string;
     }>;
+    /** When true, only Today / events open the panel (no floating button). */
+    hideLauncher?: boolean;
 }): react.JSX.Element;
 
 /**
@@ -516,6 +609,23 @@ declare function SuiteAppIcon({ app, size, label, className, style, }: SuiteAppI
 /** Mount non-critical chrome after the browser is idle (or a short timeout). */
 declare function useIdleMount(timeoutMs?: number): boolean;
 
+declare const SIDEBAR_RAIL_WIDTH = 56;
+declare const SIDEBAR_COLLAPSE_THRESHOLD = 80;
+declare const SIDEBAR_MIN_EXPANDED_WIDTH = 180;
+declare const SIDEBAR_MAX_WIDTH = 320;
+declare const SIDEBAR_DEFAULT_WIDTH = 320;
+/**
+ * Shared suite sidebar resizing: drag below the threshold to collapse,
+ * drag the rail edge out to expand, and double-click to reset.
+ */
+declare function useSidebarWidth(storageKey: string): {
+    width: number;
+    collapsed: boolean;
+    setCollapsed: (value: boolean) => void;
+    resetWidth: () => void;
+    startResize: (event: PointerEvent<HTMLDivElement>) => void;
+};
+
 declare function cn(...inputs: ClassValue[]): string;
 
 /**
@@ -570,13 +680,8 @@ declare const SUITE_SPRINGS: {
 };
 type SuiteSpringName = keyof typeof SUITE_SPRINGS;
 
-declare const WIDTHS: {
-    readonly full: "max-w-none";
-    readonly wide: "max-w-7xl";
-    readonly content: "max-w-6xl";
-    readonly narrow: "max-w-4xl";
-};
-type SuitePageWidth = keyof typeof WIDTHS;
+/** Width tokens — applied as data-width; CSS in suite-skin.css owns max-width. */
+type SuitePageWidth = 'full' | 'wide' | 'content' | 'narrow' | 'reading';
 interface SuiteBreadcrumbsProps {
     items: {
         label: ReactNode;
@@ -605,7 +710,9 @@ todayIcon, todayIconClassName,
 /** Small badge/pill next to the title (e.g. "Beta", org name). */
 badge, 
 /** Breadcrumb line rendered above the title. */
-breadcrumb, }: {
+breadcrumb, 
+/** Stick to the top of the scrollport (desktop page titles). */
+sticky, }: {
     title: ReactNode;
     description?: ReactNode;
     eyebrow?: ReactNode;
@@ -618,6 +725,7 @@ breadcrumb, }: {
     todayIconClassName?: string;
     badge?: ReactNode;
     breadcrumb?: ReactNode;
+    sticky?: boolean;
 }): react.JSX.Element;
 declare function SuiteToolbar({ children, className, label, dataTest, }: {
     children: ReactNode;
@@ -676,10 +784,7 @@ declare function SuiteEmptyState({ icon, title, description, action, className,
 interface SuiteSettingsNavItem {
     label: string;
     href: string;
-    icon: ComponentType<{
-        className?: string;
-        'aria-hidden'?: boolean;
-    }> | ReactNode;
+    icon: ElementType | ReactNode;
     testId?: string;
 }
 interface SuiteSettingsMobileNavProps {
@@ -687,6 +792,8 @@ interface SuiteSettingsMobileNavProps {
     activeHref: string;
     onSelect: (href: string) => void;
     dataTest?: string;
+    ariaLabel?: string;
+    className?: string;
 }
 /**
  * Horizontal scrollable settings nav for mobile.
@@ -694,7 +801,7 @@ interface SuiteSettingsMobileNavProps {
  * meet 44px touch targets, and preserve visual hierarchy (Law of UX: Hick's Law,
  * Recognition over Recall).
  */
-declare function SuiteSettingsMobileNav({ items, activeHref, onSelect, dataTest, }: SuiteSettingsMobileNavProps): react.JSX.Element;
+declare function SuiteSettingsMobileNav({ items, activeHref, onSelect, dataTest, ariaLabel, className, }: SuiteSettingsMobileNavProps): react.JSX.Element;
 
 type CollapsedNode = ReactNode | ((collapsed: boolean) => ReactNode);
 interface SuiteSidebarNavItem {
@@ -743,6 +850,11 @@ interface SuiteAppLayoutProps {
     sidebarWidth?: number;
     /** True when the sidebar is collapsed to the icon rail. */
     collapsed?: boolean;
+    /**
+     * When true, `#main-content` does not scroll — the page owns an internal
+     * scrollport (e.g. Deep Research: fixed header + composer, chat scrolls).
+     */
+    lockMainScroll?: boolean;
     /** Drag this to resize the sidebar. */
     onStartResize?: (e: PointerEvent<HTMLDivElement>) => void;
     /** Double-click to reset sidebar width. */
@@ -750,11 +862,10 @@ interface SuiteAppLayoutProps {
     className?: string;
 }
 /**
- * Responsive ShellStack app shell. Desktop: resizable fixed sidebar +
- * scrollable content with an optional drag handle. Mobile/tablet: mobile
- * header + content + bottom nav. This is the single layout primitive every
- * app should use.
+ * Responsive ShellStack app shell. One content tree (no duplicate children),
+ * one `#main-content` landmark. Desktop: fixed sidebar + scrollable main.
+ * Mobile: header + main + bottom nav.
  */
-declare function SuiteAppLayout({ sidebar, children, mobileHeader, bottomNav, sidebarWidth, collapsed, onStartResize, onResetWidth, className, }: SuiteAppLayoutProps): react.JSX.Element;
+declare function SuiteAppLayout({ sidebar, children, mobileHeader, bottomNav, sidebarWidth, collapsed, lockMainScroll, onStartResize, onResetWidth, className, }: SuiteAppLayoutProps): react.JSX.Element;
 
-export { APP_ACCENTS, APP_GLYPHS, AnimatedMoon, AnimatedSun, AppSwitcher, AppSwitcherChevron, AppSwitcherMark, CommandPaletteHost, DeferredChrome, SUITE_APPS, SUITE_APP_MAP, SUITE_GLYPHS, SUITE_ICON_NAMES, SUITE_SPRINGS, SourceAppGlyph, type SuiteAccentSlug, SuiteAiPanel, type SuiteAiPreset, type SuiteAppAccent, type SuiteAppDefinition, type SuiteAppEntry, SuiteAppIcon, type SuiteAppIconProps, SuiteAppLayout, type SuiteAppLayoutProps, type SuiteAppSlug, SuiteAppStrip, SuiteBottomNav, type SuiteBottomNavItem, SuiteBreadcrumbs, type SuiteBreadcrumbsProps, type SuiteCommandItem, type SuiteCommandPaletteComponent, type SuiteDropdownItemComponent, type SuiteDropdownMenuComponent, type SuiteDropdownMenuProps, SuiteEmptyState, type SuiteGlyph, type SuiteGlyphElement, SuiteIcon, type SuiteIconName, type SuiteIconProps, SuiteMobileDrawer, SuiteMobileHeader, SuiteMotionProvider, type SuiteNotification, SuiteNotificationBell, type SuiteNotificationsResponse, SuitePage, SuitePageHeader, type SuitePageWidth, type SuiteResolvedTheme, SuiteSectionHeader, SuiteSettingsMobileNav, type SuiteSettingsNavItem, SuiteSidebar, type SuiteSidebarNavItem, SuiteSkeleton, SuiteSkeletonCard, SuiteSkeletonList, type SuiteSpinnerComponent, type SuiteSpringName, SuiteTabList, type SuiteTheme, type SuiteThemeConfig, type SuiteThemeContextValue, SuiteThemeProvider, SuiteToolbar, SuiteUserMenu, type SuiteUserMenuProps, TodayCalibrating, TodayEmptyState, TodayHero, TodayPageFrame, TodayPanel, TodaySection, TodayTimeIcon, TodayTopBar, appSwitcherMarkClass, appSwitcherMenuItemClass, appSwitcherTriggerClass, cn, getTodayGreeting, sourceToSuiteApp, suiteAppBaseUrl, suiteAppLabel, useIdleMount, useSuiteTheme };
+export { APP_ACCENTS, APP_GLYPHS, AnimatedMoon, AnimatedSun, AppSwitcher, AppSwitcherChevron, AppSwitcherMark, CommandPaletteHost, DeferredChrome, SIDEBAR_COLLAPSE_THRESHOLD, SIDEBAR_DEFAULT_WIDTH, SIDEBAR_MAX_WIDTH, SIDEBAR_MIN_EXPANDED_WIDTH, SIDEBAR_RAIL_WIDTH, SUITE_APPS, SUITE_APP_MAP, SUITE_GLYPHS, SUITE_ICON_NAMES, SUITE_OPEN_ASK_AI_EVENT, SUITE_SPRINGS, SourceAppGlyph, type SuiteAccentSlug, type SuiteAiChatMessage, SuiteAiPanel, type SuiteAiPreset, type SuiteAppAccent, type SuiteAppDefinition, type SuiteAppEntry, SuiteAppIcon, type SuiteAppIconProps, SuiteAppLayout, type SuiteAppLayoutProps, type SuiteAppSlug, SuiteAppStrip, type SuiteAskAiOpenDetail, SuiteBottomNav, type SuiteBottomNavItem, SuiteBreadcrumbs, type SuiteBreadcrumbsProps, type SuiteCommandItem, type SuiteCommandPaletteComponent, type SuiteDropdownItemComponent, type SuiteDropdownMenuComponent, type SuiteDropdownMenuProps, SuiteEmptyState, type SuiteGlyph, type SuiteGlyphElement, SuiteIcon, type SuiteIconName, type SuiteIconProps, SuiteMobileDrawer, SuiteMobileHeader, SuiteMotionProvider, type SuiteNotification, SuiteNotificationBell, type SuiteNotificationsResponse, SuitePage, SuitePageHeader, type SuitePageWidth, type SuiteResolvedTheme, SuiteSectionHeader, SuiteSettingsLayout, type SuiteSettingsLayoutProps, SuiteSettingsMobileNav, type SuiteSettingsNavItem, SuiteSidebar, type SuiteSidebarNavItem, SuiteSkeleton, SuiteSkeletonCard, SuiteSkeletonList, type SuiteSpinnerComponent, type SuiteSpringName, SuiteTabList, type SuiteTheme, type SuiteThemeConfig, type SuiteThemeContextValue, SuiteThemeProvider, SuiteToolbar, SuiteUserMenu, type SuiteUserMenuProps, TodayAskAiCard, TodayCalibrating, TodayEmptyAction, TodayEmptyState, TodayHero, TodayLayout, TodayPageFrame, TodayPanel, type TodayPrimaryAccent, TodayPrimaryAction, TodaySection, TodayTimeIcon, TodayTopBar, appSwitcherMarkClass, appSwitcherMenuItemClass, appSwitcherTriggerClass, cn, getTodayGreeting, openSuiteAskAi, resolveSuiteNotificationHref, sourceToSuiteApp, suiteAppBaseUrl, suiteAppLabel, useIdleMount, useSidebarWidth, useSuiteTheme };