@almadar/shell-web 0.0.0-stage → 1.0.0

package/dist/core.d.ts

@@ -0,0 +1,2599 @@
+import * as React$1 from 'react';
+import React__default, { RefObject } from 'react';
+import { A11yProps, AssetUrl, EventKey, TextureAtlas, Tilesheet, SpriteSheetAtlas, EventPayload, EventEmit, FieldValue, SExpr, Asset, OrbitalSchema, OrbitalPage, NavStackEntry, IconFamily as IconFamily$1, JsonValue, SurfaceMode } from '@almadar/core';
+export { BusEvent, BusEventListener, BusEventSource, BusEventListener as EventListener, SurfaceMode, Unsubscribe, comparePathSpecificity, matchPath, matchPathAmong } from '@almadar/core';
+import { I as IconInput } from './fx-CmQjnHmT.js';
+export { B as Badge, b as BadgeColor, c as BadgeProps, d as BadgeSize, e as BadgeVariant, C as CONFETTI_BURST_KEYFRAMES, f as CONFETTI_COLORS, g as ColorToken, h as ConfettiParticle, D as DisplayField, i as DisplayFieldFormat, j as DisplayFieldVariant, F as FxItem, k as FxLifecycle, l as FxOverlayItem, m as FxOverlayKind, a as FxPreset, n as FxProceduralShape, o as FxSpace, p as FxView, q as Icon, r as IconAnimation, s as IconProps, t as IconSize, u as ImageSource, L as LinkAction, P as Point, R as Rect, U as UiError, v as createConfettiParticles, w as fxHash01, x as fxLifecycle, y as resolveFxView, z as resolveIcon } from './fx-CmQjnHmT.js';
+export { B as Button, a as ButtonProps, b as ButtonSize, c as ButtonVariant, I as Input, d as InputProps, P as PatternTile, e as PatternTileProps, f as PatternVariant, S as Select, g as SelectOption, h as SelectOptionGroup, i as SelectProps, j as getTileDimensions } from './Select-B-iDdnvE.js';
+export { E as EventBusContext, a as EventBusContextType, b as EventBusContextTypeExtended, c as EventBusProvider, V as VideoEmbed, d as VideoEmbedProps, e as VideoErrorPayload, f as VideoPlayPayload, g as VideoReadyPayload, h as getGlobalEventBus, s as setGlobalEventBus, u as useEmitEvent, i as useEventBus, j as useEventListener, k as useEventSubscription, l as useRootEventBus } from './EventBusProvider-BFFHfN4O.js';
+import { ClassValue } from 'clsx';
+import { LucideIcon } from 'lucide-react';
+import { EvalContextWire, TraitSurface } from '@almadar/core/kernel-wire';
+import { U as UIThemeDefinition } from './ThemeContext-DJmO59xd.js';
+export { C as ColorMode, D as DesignTheme, R as ResolvedMode, a as ResolvedTheme, b as Theme, c as ThemeProvider, T as ThemeProviderProps, d as ThemeScope, e as ThemeScopeContext, k as keyInViewerMode, r as registryKeyMode, f as registryKeyTheme, t as themeHasMode, u as useScopedMode, g as useTheme, h as useThemeScope } from './ThemeContext-DJmO59xd.js';
+
+type GraphicAnimation = 'draw' | 'fill' | 'pulse' | 'morph';
+/** @accessibleName alt */
+interface AnimatedGraphicProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>, keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** URL to an SVG file. Fetched and inlined to enable stroke/fill animations. */
+    src?: AssetUrl;
+    /** Inline SVG string. Takes precedence over src if both provided. */
+    svgContent?: string;
+    /** Animation type applied to SVG paths/shapes */
+    animation?: GraphicAnimation;
+    /** Whether to run the animation (default: false). Controlled externally or via AnimatedReveal. */
+    animate?: boolean;
+    /** Animation duration in ms (default: 1200) */
+    duration?: number;
+    /** Delay before animation starts in ms (default: 0) */
+    delay?: number;
+    /** Easing function (default: cubic-bezier(0.16, 1, 0.3, 1)) */
+    easing?: string;
+    /** Width of the graphic container */
+    width?: string | number;
+    /** Height of the graphic container */
+    height?: string | number;
+    /** Stroke color override for SVG paths */
+    strokeColor?: string;
+    /** Fill color for the 'fill' animation end state */
+    fillColor?: string;
+    /** Alt text for accessibility */
+    alt?: string;
+}
+declare const AnimatedGraphic: React__default.ForwardRefExoticComponent<AnimatedGraphicProps & React__default.RefAttributes<HTMLDivElement>>;
+
+type RevealTrigger = 'scroll' | 'hover' | 'manual';
+type RevealAnimation = 'fade-up' | 'fade-down' | 'fade-in' | 'fade-left' | 'fade-right' | 'scale' | 'scale-up' | 'none';
+interface AnimatedRevealProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>, 'children' | keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** What triggers the animation */
+    trigger?: RevealTrigger;
+    /** Built-in animation preset */
+    animation?: RevealAnimation;
+    /** Animation duration in ms (default: 600) */
+    duration?: number;
+    /** Delay before animation starts in ms (default: 0) */
+    delay?: number;
+    /** How much of the element must be visible before triggering, 0-1 (default: 0.15) */
+    threshold?: number;
+    /**
+     * scroll trigger: event emitted once (as UI:{revealEvent}) the first time the element scrolls into view; never under reduced motion
+     * @notification
+     */
+    revealEvent?: EventKey;
+    /**
+     * scroll trigger: event emitted (as UI:{enterEvent}) every time the element enters the view
+     * @notification
+     */
+    enterEvent?: EventKey;
+    /**
+     * scroll trigger: event emitted (as UI:{leaveEvent}) every time the element leaves the view after having entered it
+     * @notification
+     */
+    leaveEvent?: EventKey;
+    /** Animate only the first time the element enters the viewport (default: true) */
+    once?: boolean;
+    /** Manual control: when trigger='manual', set this to true to animate */
+    animate?: boolean;
+    /** Easing function (default: cubic-bezier(0.16, 1, 0.3, 1)) */
+    easing?: string;
+    /** Children: ReactNode or render function receiving animated state */
+    children: React__default.ReactNode | ((animated: boolean) => React__default.ReactNode);
+}
+declare const AnimatedReveal: React__default.ForwardRefExoticComponent<AnimatedRevealProps & React__default.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Aside Atom Component
+ *
+ * Semantic wrapper for the native `<aside>` landmark. Owns raw HTML so
+ * molecules (SidePanel, navigation rails, callouts) can compose the
+ * semantic-aside primitive without falling back to a raw element.
+ */
+
+/**
+ * Aside — a secondary side panel that hosts navigation links or supplementary
+ * content alongside a main content area.
+ *
+ * @capabilities settings navigation sidebar, preferences menu panel, account settings nav, secondary panel, side navigation rail
+ */
+interface AsideProps extends Omit<React__default.HTMLAttributes<HTMLElement>, keyof A11yProps>, A11yProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Aside contents */
+    children?: React__default.ReactNode;
+}
+declare const Aside: React__default.ForwardRefExoticComponent<AsideProps & React__default.RefAttributes<HTMLElement>>;
+
+/**
+ * atlasSlice — the ONLY place a packed sheet is cut at runtime.
+ *
+ * An `Asset` may carry `{ url: <sheet.png>, atlas: <atlas.json>, sprite: <name|index> }`. This
+ * module fetches + caches the atlas JSON (a `TextureAtlas` of named sub-rects or a uniform
+ * `Tilesheet`) and resolves the source rectangle for a `sprite`, so the canvas can `drawImage`
+ * exactly that sub-region of the sheet. Coexists with the whole-PNG path (an Asset with no
+ * `atlas`/`sprite` draws the whole image) and the `useUnitSpriteAtlas` animation path.
+ *
+ * See `docs/Almadar_Std_Assets.md` §2, §7.
+ *
+ * @packageDocumentation
+ */
+
+/** The minimal draw-relevant projection of an `Asset` — a sheet URL plus an optional atlas
+ *  sub-texture reference. A full `@almadar/core` `Asset` is structurally assignable. */
+interface SpriteRef {
+    url?: string;
+    atlas?: string;
+    sprite?: string;
+}
+type ParsedAtlas = TextureAtlas | Tilesheet | SpriteSheetAtlas;
+/** True for an animated sprite-sheet manifest (frame grid + animation rows). */
+declare function isSpriteSheetAtlas(a: ParsedAtlas): a is SpriteSheetAtlas;
+/**
+ * Get a parsed atlas by URL, fetching+caching on first request. Returns undefined until loaded;
+ * `onReady` fires once when the fetch resolves so the caller can trigger a re-render.
+ */
+declare function getAtlas(url: string, onReady: () => void): ParsedAtlas | undefined;
+/** True when the atlas fetch for `url` has failed (cached null). `getAtlas`
+ *  collapses in-flight and failed to `undefined`; this distinguishes them. */
+declare function atlasFailed(url: string): boolean;
+interface SubRect {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+}
+/**
+ * Resolve the source rect for `sprite` in `atlas`.
+ * - `TextureAtlas`: `sprite` is a SubTexture name (e.g. `"blockBrown.png"`).
+ * - `Tilesheet`: `sprite` is `"col,row"` or a flat index into the row-major grid.
+ * Returns null if the name/index doesn't resolve.
+ */
+declare function subRectFor(atlas: ParsedAtlas, sprite: string): SubRect | null;
+/** True when the asset points into a sheet (needs slicing) rather than being a whole PNG. */
+/** The asset's atlas manifest URL; an empty string means no atlas. */
+declare function atlasUrlOf(asset: SpriteRef | undefined | null): string | undefined;
+declare function isAtlasAsset(asset: SpriteRef | undefined | null): boolean;
+interface AssetSource {
+    img: HTMLImageElement;
+    /** Sub-rect to blit; null = draw the whole image. */
+    rect: SubRect | null;
+    /** Source aspect ratio (width/height) — sub-rect for a slice, natural otherwise. */
+    aspect: number;
+}
+/**
+ * Resolve what to draw for `asset` given its loaded sheet `img`. Returns null when the asset is
+ * an atlas ref whose JSON isn't loaded yet (or whose sprite name doesn't resolve) — `onReady`
+ * will trigger a re-render once the fetch lands. Callers use `.aspect` to size, then `blit`.
+ */
+declare function resolveAssetSource(img: HTMLImageElement, asset: SpriteRef | undefined | null, onReady: () => void): AssetSource | null;
+/** Draw a resolved source at `(dx,dy,dw,dh)` — sliced sub-rect or whole image. */
+declare function blit(ctx: CanvasRenderingContext2D, src: AssetSource, dx: number, dy: number, dw: number, dh: number): void;
+
+/** Asset-compatible input: sheet url + optional atlas sub-texture reference. */
+interface AtlasImageAsset extends SpriteRef {
+    name?: string;
+    category?: string;
+}
+/** @accessibleName alt */
+interface AtlasImageProps extends Omit<A11yProps, 'aria-hidden'> {
+    asset?: AtlasImageAsset;
+    /** Square pixel size (icon usage). Ignored when `fill`. */
+    size?: number;
+    width?: number;
+    height?: number;
+    /** Absolutely fill the nearest positioned ancestor (background usage). */
+    fill?: boolean;
+    fit?: 'contain' | 'cover' | 'fill';
+    alt?: string;
+    className?: string;
+    style?: React$1.CSSProperties;
+    'aria-hidden'?: boolean;
+}
+/**
+ * Resolve an atlas slice to a standalone dataURL (extracted once, cached) so CSS can 9-slice or
+ * tile it — `border-image`/`background-repeat` can't crop a packed sheet. Returns undefined until
+ * the sheet + atlas are loaded; `onReady` re-fires the caller when they land.
+ */
+declare function useAtlasSliceDataUrl(asset: AtlasImageAsset | undefined): string | undefined;
+interface AtlasPanelProps extends Omit<A11yProps, 'aria-hidden'> {
+    asset?: AtlasImageAsset;
+    /** Border thickness (source pixels) for the 9-slice cut. */
+    borderSlice?: number;
+    /** Rendered border width in CSS px. */
+    borderWidth?: number;
+    /** 'nineSlice' scales edges crisp (panels/buttons); 'repeat' tiles the slice (pattern fills). */
+    mode?: 'nineSlice' | 'repeat';
+    className?: string;
+    style?: React$1.CSSProperties;
+    children?: React$1.ReactNode;
+    'aria-hidden'?: boolean;
+}
+/**
+ * A container skinned by an atlas slice: 9-sliced panel chrome or a tiled pattern. The pack sheet
+ * is cropped once to a dataURL; CSS border-image / background-repeat does the scaling. Falls back
+ * to a plain container while the sheet/atlas load.
+ */
+declare function AtlasPanel({ asset, borderSlice, borderWidth, mode, className, style, children, 'aria-hidden': ariaHidden, ...rest }: AtlasPanelProps): React$1.JSX.Element;
+declare namespace AtlasPanel {
+    var displayName: string;
+}
+/**
+ * The one chrome-side renderer for `Asset` images. With `atlas`+`sprite` it draws EXACTLY that
+ * sub-rect of the packed sheet into a canvas (never the whole sheet); otherwise it renders the
+ * plain `<img>` path. `fill` + `fit` cover background/panel usage (GameShell, card frames).
+ */
+declare function AtlasImage({ asset, size, width, height, fill, fit, alt, className, style, 'aria-hidden': ariaHidden, ...rest }: AtlasImageProps): React$1.JSX.Element | null;
+declare namespace AtlasImage {
+    var displayName: string;
+}
+
+type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+type AvatarStatus = "online" | "offline" | "away" | "busy";
+/**
+ * @accessibleName alt name
+ * @role img
+ * @tokens --color-muted --color-border --color-foreground
+ * @contrast foreground muted
+ * @motion css
+ */
+interface AvatarProps extends A11yProps {
+    /**
+     * Image source URL
+     */
+    src?: AssetUrl;
+    /**
+     * Alt text for the image
+     */
+    alt?: string;
+    /**
+     * Full name - initials will be generated automatically
+     */
+    name?: string;
+    /**
+     * Initials to display (e.g., "JD" for John Doe)
+     * If not provided but name is, initials will be auto-generated
+     */
+    initials?: string;
+    /**
+     * Icon to display when no image or initials. Accepts a Lucide component
+     * directly, or a canonical kebab-case icon name string (resolved via
+     * `resolveIcon`) so trait/factory authors can pass an icon by name.
+     */
+    icon?: IconInput;
+    /**
+     * Size of the avatar
+     * @default 'md'
+     */
+    size?: AvatarSize;
+    /**
+     * Status indicator
+     */
+    status?: AvatarStatus;
+    /**
+     * Badge content (e.g., notification count)
+     */
+    badge?: string | number;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Click handler
+     */
+    onClick?: () => void;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: EventKey;
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
+    actionPayload?: EventPayload;
+}
+declare const Avatar: React__default.FC<AvatarProps>;
+
+type BandEdge = 'none' | 'curve' | 'wave' | 'arc' | 'tilt' | 'step' | 'scallop';
+type BandEdgeColor = 'background' | 'muted' | 'surface' | 'gradient' | 'inverse';
+declare const BAND_SHAPES: Record<Exclude<BandEdge, 'none' | 'curve'>, string>;
+declare const BAND_ACCENT_FALLBACK = "linear-gradient(180deg, color-mix(in oklab, var(--color-primary) 12%, var(--color-background)), var(--color-background))";
+declare const BAND_EDGE_FILL: Record<BandEdgeColor, string>;
+declare function bandEdgeMask(edge: Exclude<BandEdge, 'none'>): string;
+declare function bandEdgeHeight(edge: Exclude<BandEdge, 'none'>): string;
+interface BandEdgeLayerStyle {
+    height: string;
+    background: string;
+    maskImage: string;
+    WebkitMaskImage: string;
+    transform?: string;
+    backgroundSize?: string;
+    backgroundAttachment?: string;
+}
+declare function bandEdgeLayerStyle(edge: Exclude<BandEdge, 'none'>, side: 'top' | 'bottom', flip: boolean, color: BandEdgeColor): BandEdgeLayerStyle;
+declare function bandPadding(basePad: string, edge: BandEdge): string | undefined;
+
+/**
+ * Box Component
+ *
+ * A versatile layout primitive that provides spacing, background, border, and shadow controls.
+ * Think of it as a styled div with consistent design tokens.
+ */
+
+type BoxPadding = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+type BoxMargin = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "auto";
+type BoxBg = "transparent" | "primary" | "secondary" | "muted" | "accent" | "surface" | "overlay" | "gradient" | "inverse";
+type BoxRounded = "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+type BoxShadow = "none" | "sm" | "md" | "lg" | "xl";
+interface BoxProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>, keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** Inline styles applied to the root element. */
+    style?: React__default.CSSProperties;
+    /** Data-theme attribute applied to the root element for CSS theme scoping (e.g. almadar-website-dark). */
+    'data-theme'?: string;
+    /**
+     * Padding on all sides
+     * @example md
+     */
+    padding?: BoxPadding;
+    /** Horizontal padding (overrides padding for x-axis) */
+    paddingX?: BoxPadding;
+    /** Vertical padding (overrides padding for y-axis) */
+    paddingY?: BoxPadding;
+    /** Margin on all sides */
+    margin?: BoxMargin;
+    /** Horizontal margin */
+    marginX?: BoxMargin;
+    /** Vertical margin */
+    marginY?: BoxMargin;
+    /** Background color */
+    bg?: BoxBg;
+    /**
+     * Show border
+     * @example true
+     */
+    border?: boolean;
+    /** Border radius */
+    rounded?: BoxRounded;
+    /** Box shadow */
+    shadow?: BoxShadow;
+    /** Display type */
+    display?: "block" | "inline" | "inline-block" | "flex" | "inline-flex" | "grid";
+    /** Fill available width */
+    fullWidth?: boolean;
+    /** Fill available height */
+    fullHeight?: boolean;
+    /** Overflow behavior */
+    overflow?: "auto" | "hidden" | "visible" | "scroll";
+    /** Position */
+    position?: "relative" | "absolute" | "fixed" | "sticky";
+    /** HTML element to render as */
+    as?: React__default.ElementType;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: EventKey;
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
+    actionPayload?: EventPayload;
+    /**
+     * Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave
+     * @notification
+     */
+    hoverEvent?: EventEmit<{
+        hovered: boolean;
+    }>;
+    /** When true (default), a touch/pen tap also fires `hoverEvent` (toggling hovered) so hover-only reveals work on touch. */
+    tapReveal?: boolean;
+    /** Maximum width (CSS value, e.g., "550px", "80rem") */
+    maxWidth?: string;
+    /** Shape cut into the top edge of a full-width band; "curve" uses the theme's shape */
+    edgeTop?: BandEdge;
+    /** Shape cut into the bottom edge of a full-width band; "curve" uses the theme's shape */
+    edgeBottom?: BandEdge;
+    /** Surface of the neighbouring band, which fills the cut */
+    edgeColor?: BandEdgeColor;
+    /** Mirror the edge shapes horizontally */
+    edgeFlip?: boolean;
+    /** Lay the theme's texture over the band */
+    texture?: boolean;
+    /** Content that appears or changes inside the box eases in instead of switching in one frame (new rows, swapped views, changed text), played in presentation motion (the theme's dramatic duration, standard easing) so it can be watched. Off under reduced motion. */
+    animateChanges?: boolean;
+    /** Scene behind the band's content (photo, illustration, pattern); never takes clicks */
+    backdrop?: React__default.ReactNode;
+    /** Children elements */
+    children?: React__default.ReactNode;
+}
+/**
+ * Box - Versatile container component with design tokens
+ */
+declare const Box: React__default.ForwardRefExoticComponent<BoxProps & React__default.RefAttributes<HTMLDivElement>>;
+
+type CardShadow = "none" | "sm" | "md" | "lg";
+/**
+ * Layer 2 visual treatment for the card pattern — orthogonal to the semantic
+ * `variant` (which conveys role / state).
+ */
+type CardLook = "elevated" | "flat-bordered" | "borderless-divider" | "ticket" | "invoice" | "chip" | "tile-image-first";
+interface CardProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>, keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    variant?: "default" | "bordered" | "elevated" | "interactive";
+    padding?: "none" | "sm" | "md" | "lg";
+    /** Card title - renders in header if provided */
+    title?: string;
+    /** Card subtitle - renders below title */
+    subtitle?: string;
+    /** Shadow size override */
+    shadow?: CardShadow;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
+    look?: CardLook;
+    /** Card content */
+    children?: React__default.ReactNode;
+    /** Declarative event key emitted on click for trait dispatch */
+    action?: EventKey;
+    /** Shows a skeleton/spinner overlay while true. */
+    loading?: boolean;
+}
+declare const Card: React__default.ForwardRefExoticComponent<CardProps & React__default.RefAttributes<HTMLDivElement>>;
+declare const CardHeader: React__default.ForwardRefExoticComponent<React__default.HTMLAttributes<HTMLDivElement> & React__default.RefAttributes<HTMLDivElement>>;
+declare const CardTitle: React__default.ForwardRefExoticComponent<React__default.HTMLAttributes<HTMLHeadingElement> & React__default.RefAttributes<HTMLHeadingElement>>;
+declare const CardContent: React__default.ForwardRefExoticComponent<React__default.HTMLAttributes<HTMLDivElement> & React__default.RefAttributes<HTMLDivElement>>;
+declare const CardBody: React__default.ForwardRefExoticComponent<React__default.HTMLAttributes<HTMLDivElement> & React__default.RefAttributes<HTMLDivElement>>;
+declare const CardFooter: React__default.ForwardRefExoticComponent<React__default.HTMLAttributes<HTMLDivElement> & React__default.RefAttributes<HTMLDivElement>>;
+
+interface CenterProps extends A11yProps {
+    /** Center inline (width fits content) vs block (full width) */
+    inline?: boolean;
+    /** Center only horizontally */
+    horizontal?: boolean;
+    /** Center only vertically */
+    vertical?: boolean;
+    /** Minimum height (useful for vertical centering) */
+    minHeight?: string | number;
+    /** Fill available height */
+    fullHeight?: boolean;
+    /** Fill available width */
+    fullWidth?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Inline styles */
+    style?: React__default.CSSProperties;
+    /** Children elements */
+    children: React__default.ReactNode;
+    /** HTML element to render as */
+    as?: React__default.ElementType;
+}
+/**
+ * Center - Centers content horizontally and/or vertically
+ */
+declare const Center: React__default.FC<CenterProps>;
+
+/**
+ * @accessibleName label
+ * @role checkbox
+ * @tokens --color-primary --color-border --color-card --color-foreground
+ * @contrast foreground card
+ * @motion none
+ */
+interface CheckboxProps extends Omit<React__default.InputHTMLAttributes<HTMLInputElement>, "type" | "onChange" | keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** Whether the checkbox is checked */
+    checked?: boolean;
+    /** Default checked state (uncontrolled) */
+    defaultChecked?: boolean;
+    label?: string;
+    /** Error message */
+    error?: string;
+    /** onChange handler or declarative event key for trait dispatch */
+    onChange?: React__default.ChangeEventHandler<HTMLInputElement> | EventEmit<{
+        checked: boolean;
+    }>;
+}
+declare const Checkbox: React__default.ForwardRefExoticComponent<CheckboxProps & React__default.RefAttributes<HTMLInputElement>>;
+
+/**
+ * ConditionalWrapper Atom Component
+ *
+ * A wrapper component that conditionally renders its children based on
+ * S-expression evaluation. Used for dynamic field visibility in inspection forms.
+ */
+
+/**
+ * Context for conditional evaluation
+ */
+type ConditionalContext = {
+    formValues: Record<string, FieldValue>;
+    globalVariables: Record<string, FieldValue>;
+    localVariables?: Record<string, FieldValue>;
+    entity?: Record<string, FieldValue>;
+};
+interface ConditionalWrapperProps {
+    /** The S-expression condition to evaluate */
+    condition?: SExpr;
+    /** Context for evaluating the condition */
+    context: ConditionalContext;
+    /** Children to render when condition is true (or when no condition is provided) */
+    children: React__default.ReactNode;
+    /** Optional fallback to render when condition is false */
+    fallback?: React__default.ReactNode;
+    /** Whether to animate the transition (uses CSS transitions) */
+    animate?: boolean;
+}
+/**
+ * ConditionalWrapper conditionally renders children based on S-expression evaluation.
+ *
+ * Supported bindings:
+ * - @entity.formValues.fieldId - Access form field values
+ * - @entity.globalVariables.HG_VAR - Access global inspection variables
+ * - @entity.localVariables.H_VAR - Access document-local variables
+ * - @state - Current state machine state
+ * - @now - Current timestamp
+ *
+ * @example
+ * // Simple condition - show field when another field equals a value
+ * <ConditionalWrapper
+ *   condition={["=", "@entity.formValues.vehicleType", "commercial"]}
+ *   context={{ formValues: { vehicleType: "commercial" }, globalVariables: {} }}
+ * >
+ *   <Input name="commercialLicenseNumber" />
+ * </ConditionalWrapper>
+ *
+ * @example
+ * // With fallback - show message when condition not met
+ * <ConditionalWrapper
+ *   condition={[">=", "@entity.formValues.loadWeight", 3500]}
+ *   context={formContext}
+ *   fallback={<Typography variant="small">Load weight must be at least 3500kg</Typography>}
+ * >
+ *   <HeavyVehicleFields />
+ * </ConditionalWrapper>
+ *
+ * @example
+ * // Using global variables for cross-form conditions
+ * <ConditionalWrapper
+ *   condition={["=", "@entity.globalVariables.HG_POTROSNIKI", "DA"]}
+ *   context={{ formValues: {}, globalVariables: { HG_POTROSNIKI: "DA" } }}
+ * >
+ *   <PriceMarkingSection />
+ * </ConditionalWrapper>
+ */
+declare const ConditionalWrapper: React__default.FC<ConditionalWrapperProps>;
+
+interface ConfettiEffectProps extends A11yProps {
+    /** When this changes from false to true, a burst of particles is spawned */
+    trigger: boolean;
+    /** How long the animation lasts in milliseconds */
+    duration?: number;
+    /** Number of particles to spawn */
+    particleCount?: number;
+    /** Additional class names */
+    className?: string;
+}
+declare const ConfettiEffect: React__default.FC<ConfettiEffectProps>;
+
+interface DayCellProps extends A11yProps {
+    /** The date this cell represents. Optional at the dynamic render edge: an
+     *  unbound `@config.date` arrives as `undefined`, so the cell falls back to today. */
+    date?: Date;
+    /** Whether this date is today */
+    isToday?: boolean;
+    /** Called when the day is clicked */
+    onClick?: (date: Date) => void;
+    /** Additional CSS classes */
+    className?: string;
+}
+declare function DayCell({ date, isToday, onClick, className, ...rest }: DayCellProps): React__default.JSX.Element;
+declare namespace DayCell {
+    var displayName: string;
+}
+
+/**
+ * Dialog Atom Component
+ *
+ * Semantic wrapper for the native `<dialog>` element. Owns the raw
+ * HTML rendering so molecules (Modal, ConfirmDialog, etc.) can compose
+ * the dialog primitive without dropping back to raw HTML.
+ *
+ * Defaults `role="dialog"` and `aria-modal="true"`; both overridable
+ * for non-modal use cases.
+ */
+
+interface DialogProps extends Omit<React__default.DialogHTMLAttributes<HTMLDialogElement>, keyof A11yProps>, A11yProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Dialog contents */
+    children?: React__default.ReactNode;
+}
+declare const Dialog: React__default.ForwardRefExoticComponent<DialogProps & React__default.RefAttributes<HTMLDialogElement>>;
+
+/**
+ * Divider Atom Component
+ *
+ * A divider component for separating content sections.
+ */
+
+type DividerOrientation = "horizontal" | "vertical";
+type DividerVariant = "solid" | "dashed" | "dotted";
+/**
+ * @role separator
+ * @tokens --color-border
+ * @motion none
+ */
+interface DividerProps extends A11yProps {
+    /**
+     * Orientation of the divider
+     * @default 'horizontal'
+     */
+    orientation?: DividerOrientation;
+    /**
+     * Text label to display in the divider
+     */
+    label?: string;
+    /**
+     * Line style variant
+     * @default 'solid'
+     */
+    variant?: DividerVariant;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+declare const Divider: React__default.FC<DividerProps>;
+
+type FilterPillVariant = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "info" | "neutral";
+type FilterPillSize = "sm" | "md" | "lg";
+interface FilterPillProps extends Omit<React__default.HTMLAttributes<HTMLSpanElement>, "onClick" | keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    variant?: FilterPillVariant;
+    size?: FilterPillSize;
+    /** Pill label text (alternative to children for schema-driven rendering). */
+    label?: string | number;
+    /** Lucide icon component or canonical kebab-case icon name string */
+    icon?: IconInput;
+    /** Called when the user clicks the remove (×) button
+     *  @offByDefault */
+    onRemove?: () => void;
+    /** Disable the remove button (renders without × control) */
+    removable?: boolean;
+    /** Pressed state of the pill body (filter toggle), exposed as aria-pressed */
+    selected?: boolean;
+    /** Click handler for the body of the pill (filter toggle) */
+    onClick?: () => void;
+    /** Event name dispatched via event bus when the pill body is clicked. Payload: { label } */
+    clickEvent?: EventEmit<{
+        label: string | number | undefined;
+    }>;
+    /** Event name dispatched via event bus when the remove (×) button is clicked. Payload: { label }
+     *  @offByDefault */
+    removeEvent?: EventEmit<{
+        label: string | number | undefined;
+    }>;
+}
+declare const FilterPill: React__default.ForwardRefExoticComponent<FilterPillProps & React__default.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * FlipContainer — CSS 3D perspective atom (distinct from FlipCard molecule).
+ * Owns perspective/preserve-3d/rotateY only. Children are the raw face elements.
+ * Use FlipCard when you need standard card chrome; use FlipContainer when you
+ * need the flip mechanic around custom face content.
+ */
+
+interface FlipContainerProps extends A11yProps {
+    /** Whether the container is flipped (rotateY 180deg) */
+    flipped: boolean;
+    /** Optional className for the outer wrapper */
+    className?: string;
+    /** The two face elements (front and back) */
+    children: React__default.ReactNode;
+    /** Click handler on the outer wrapper */
+    onClick?: () => void;
+}
+declare const FlipContainer: {
+    ({ flipped, className, children, onClick, ...rest }: FlipContainerProps): React__default.JSX.Element;
+    displayName: string;
+};
+
+/** @accessibleName alt */
+interface GameIconProps extends A11yProps {
+    /** Asset — when url is present, renders an img (Asset-primary). */
+    assetUrl?: Asset;
+    /** Lucide component or kebab-case icon name (fallback when no assetUrl). */
+    icon: IconInput;
+    /** Pixel size or named variant. */
+    size?: number | 'sm' | 'md' | 'lg';
+    /** Alt text for the img (defaults to assetUrl.category). */
+    alt?: string;
+    /** Additional CSS classes. */
+    className?: string;
+}
+declare function GameIcon({ assetUrl, icon, size, alt, className, ...rest }: GameIconProps): React$1.JSX.Element;
+declare namespace GameIcon {
+    var displayName: string;
+}
+
+type ImageFit = 'cover' | 'contain' | 'fill' | 'none';
+type ImageAspect = 'auto' | '1/1' | '4/3' | '3/2' | '16/9' | '21/9';
+type ImageRounded = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+type ImagePosition = 'center' | 'top' | 'bottom' | 'left' | 'right';
+/**
+ * @accessibleName alt
+ * @role img
+ * @tokens --color-border
+ * @motion none
+ */
+interface ImageProps extends A11yProps {
+    /** Image source URL */
+    src: AssetUrl;
+    /** Alternative text; empty string marks the image decorative */
+    alt: string;
+    /** How the image fills its box */
+    fit?: ImageFit;
+    /** Fixed aspect ratio of the box; "auto" keeps the image's own */
+    aspect?: ImageAspect;
+    /** Corner rounding */
+    rounded?: ImageRounded;
+    /** Draw a subtle border around the image */
+    bordered?: boolean;
+    /** "lazy" defers off-screen images; "eager" for above-the-fold media */
+    loading?: 'lazy' | 'eager';
+    /** Which part of the image stays visible when it is cropped */
+    position?: ImagePosition;
+    /** Candidate sources at different widths (the HTML `srcset`) */
+    srcSet?: string;
+    /** Rendered widths at each breakpoint (the HTML `sizes`) */
+    sizes?: string;
+    /** The page's main image: load it first */
+    priority?: boolean;
+    /** Additional class names */
+    className?: string;
+}
+declare const Image: React__default.FC<ImageProps>;
+
+interface InfiniteScrollSentinelProps extends A11yProps {
+    /** Event name to emit when load-more is triggered (emitted as UI:{loadMoreEvent}) */
+    loadMoreEvent: EventKey;
+    /** Optional payload to include with the load-more event
+     *  @payloadFor loadMoreEvent
+     */
+    loadMorePayload?: EventPayload;
+    /** Whether a load operation is currently in progress */
+    isLoading?: boolean;
+    /** Whether there are more items to load */
+    hasMore?: boolean;
+    /** IntersectionObserver rootMargin for early trigger */
+    threshold?: string;
+    /** Additional class names */
+    className?: string;
+}
+declare const InfiniteScrollSentinel: React__default.FC<InfiniteScrollSentinelProps>;
+
+interface LabelProps extends Omit<React__default.LabelHTMLAttributes<HTMLLabelElement>, keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** Label text content */
+    text?: string;
+    /** Associated input element ID */
+    htmlFor?: string;
+    /** Show required indicator (decorative; the field itself carries aria-required) */
+    required?: boolean;
+}
+declare const Label: React__default.ForwardRefExoticComponent<LabelProps & React__default.RefAttributes<HTMLLabelElement>>;
+
+/**
+ * LawReferenceTooltip Atom Component
+ *
+ * A specialized tooltip for displaying law references in inspection forms.
+ * Shows law name, article number, and relevant clause text.
+ */
+
+/**
+ * Law reference definition
+ */
+type LawReference = {
+    /** Law identifier (e.g., "VVO", "TPED") */
+    law: string;
+    /** Full name of the law */
+    lawName?: string;
+    /** Article number (e.g., "§8", "Artikel 5") */
+    article: string;
+    /** Clause or paragraph text */
+    clause?: string;
+    /** Optional link to full law text */
+    link?: string;
+};
+interface LawReferenceTooltipProps extends A11yProps {
+    /** The law reference to display */
+    reference: LawReference;
+    /** Children element that triggers the tooltip */
+    children: React__default.ReactNode;
+    /** Tooltip position */
+    position?: "top" | "bottom" | "left" | "right";
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * LawReferenceTooltip displays legal references with structured formatting.
+ *
+ * @example
+ * <LawReferenceTooltip
+ *   reference={{
+ *     law: "VVO",
+ *     lawName: "Verkehrsverordnung",
+ *     article: "§8 Abs. 3",
+ *     clause: "Die zulässige Gesamtmasse darf 3500 kg nicht überschreiten."
+ *   }}
+ * >
+ *   <Typography variant="small" className="text-blue-600 underline cursor-help">VVO §8</Typography>
+ * </LawReferenceTooltip>
+ */
+declare const LawReferenceTooltip: React__default.FC<LawReferenceTooltipProps>;
+
+interface OverlayProps extends A11yProps {
+    isVisible?: boolean;
+    onClick?: (e: React__default.MouseEvent) => void;
+    className?: string;
+    blur?: boolean;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: EventKey;
+}
+declare const Overlay: React__default.FC<OverlayProps>;
+
+/**
+ * Presence Atom — the single enter/leave animation mechanism.
+ *
+ * React unmounts children synchronously, so an exit animation is impossible
+ * unless a wrapper keeps the child mounted for one more frame. `usePresence`
+ * extracts Modal's `closing` + `onAnimationEnd` pattern into one reusable
+ * hook; the `<Presence>` component is a thin wrapper for the arbitrary case.
+ *
+ * Every animated surface converges on this: Overlay/Drawer/SidePanel/Popover/
+ * Toast call `usePresence` and spread the result onto their own element (no
+ * extra wrapper div — important for fixed/absolute positioning). Token-driven:
+ * the `animation` prop maps to the `animate-<name>-in/out` utilities, which
+ * read `--motion-*` / `--duration-*` / `--easing-*`. Toggle off per-instance
+ * (`animate={false}`), globally (`--motion-enable: off`), or via the OS
+ * (`prefers-reduced-motion`, collapsed in `_base.css`).
+ *
+ * @packageDocumentation
+ */
+
+type PresenceAnimation = "modal" | "overlay" | "slide-up" | "drawer" | "popover" | "toast" | "fade" | "page";
+/** Whether token-driven motion is on (`--motion-enable` is not `off`). */
+declare function isMotionEnabled(): boolean;
+interface UsePresenceOptions {
+    /** Which motion preset to use (maps to `animate-<name>-in/out`). */
+    animation: PresenceAnimation;
+    /** Per-instance opt-out. Global opt-out is `--motion-enable` / reduced-motion. @default true */
+    animate?: boolean;
+    /**
+     * Fired after the exit animation completes (before unmount).
+     * @notification
+     */
+    onExited?: () => void;
+}
+interface PresenceResult {
+    /** Whether the element should be in the tree (enter or exit phase). */
+    mounted: boolean;
+    /** True during the exit animation. */
+    exiting: boolean;
+    /** Class to merge onto the animated element: `animate-<name>-in` or `-out` (empty if disabled). */
+    className: string;
+    /** Attach to the animated element's `onAnimationEnd`. */
+    onAnimationEnd: (e: React__default.AnimationEvent) => void;
+}
+/**
+ * The single enter/leave mechanism. Call from a molecule, spread `className`
+ * (via `cn`) and `onAnimationEnd` onto the element that carries the animation.
+ */
+declare function usePresence(show: boolean, opts: UsePresenceOptions): PresenceResult;
+interface PresenceProps extends UsePresenceOptions, A11yProps {
+    /** When false, the exit animation runs, then children unmount. */
+    show: boolean;
+    className?: string;
+    children: React__default.ReactNode;
+}
+/**
+ * Wrapper form of `usePresence` for arbitrary content that doesn't already
+ * own its animated element. Renders a `<div>` carrying the animation class.
+ */
+declare const Presence: React__default.FC<PresenceProps>;
+
+/**
+ * ProgressBar Atom Component
+ *
+ * A progress bar component with linear, circular, and stepped variants.
+ */
+
+type ProgressBarType = "linear" | "circular" | "stepped";
+type ProgressBarVariant = "default" | "primary" | "success" | "warning" | "error" | "danger";
+type ProgressBarColor = ProgressBarVariant;
+/**
+ * @role progressbar
+ * @tokens --color-primary --color-muted --color-error --color-warning --color-foreground
+ * @motion css
+ */
+interface ProgressBarProps extends A11yProps {
+    /**
+     * Progress value (0-100)
+     */
+    value: number;
+    /**
+     * Maximum value (for calculating percentage)
+     * @default 100
+     */
+    max?: number;
+    /**
+     * Type of the progress bar (linear, circular, stepped)
+     * @default 'linear'
+     */
+    progressType?: ProgressBarType;
+    /**
+     * Variant/color of the progress bar
+     * @default 'primary'
+     */
+    variant?: ProgressBarVariant;
+    /**
+     * Color variant (alias for variant; `variant` applies when omitted)
+     */
+    color?: ProgressBarColor;
+    /**
+     * Show percentage text
+     * @default false
+     */
+    showPercentage?: boolean;
+    /**
+     * Alias for showPercentage (pattern compatibility)
+     */
+    showLabel?: boolean;
+    /**
+     * Label text
+     */
+    label?: string;
+    /**
+     * Size (for circular variant)
+     * @default 'md'
+     */
+    size?: "sm" | "md" | "lg";
+    /**
+     * Number of steps (for stepped variant)
+     * @default 5
+     */
+    steps?: number;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+declare const ProgressBar: React__default.FC<ProgressBarProps>;
+
+/**
+ * Radio Atom Component
+ *
+ * A radio button component with label support and accessibility.
+ */
+
+/**
+ * @accessibleName label
+ * @role radio
+ * @tokens --color-primary --color-border --color-foreground
+ * @motion css
+ */
+interface RadioProps extends Omit<React__default.InputHTMLAttributes<HTMLInputElement>, "type" | "size" | keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** Radio options (string array or SelectOption array) */
+    options?: string[];
+    /** Current selected value */
+    value?: string;
+    /** Declarative event name for trait dispatch */
+    action?: EventEmit<{
+        value: string;
+    }>;
+    /**
+     * Label text displayed next to the radio button
+     */
+    label?: string;
+    /**
+     * Helper text displayed below the radio button
+     */
+    helperText?: string;
+    /**
+     * Error message displayed below the radio button
+     */
+    error?: string;
+    /**
+     * Size of the radio button
+     * @default 'md'
+     */
+    size?: "sm" | "md" | "lg";
+}
+declare const Radio: React__default.ForwardRefExoticComponent<RadioProps & React__default.RefAttributes<HTMLInputElement>>;
+
+type RangeSliderSize = "sm" | "md" | "lg";
+interface RangeSliderProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>, "onChange" | keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Current value */
+    value?: number;
+    /** Step increment */
+    step?: number;
+    /** Show tooltip with current value on drag */
+    showTooltip?: boolean;
+    /** Show tick marks at step intervals */
+    showTicks?: boolean;
+    /** Buffered range (0-100), for media seek bars */
+    buffered?: number;
+    /** Slider size */
+    size?: RangeSliderSize;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Declarative event name for value changes */
+    action?: EventEmit<{
+        value: number;
+    }>;
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
+    actionPayload?: EventPayload;
+    /** Direct onChange callback */
+    onChange?: (value: number) => void;
+    /** Format function for tooltip display */
+    formatValue?: (value: number) => string;
+}
+declare const RangeSlider: React__default.ForwardRefExoticComponent<RangeSliderProps & React__default.RefAttributes<HTMLDivElement>>;
+
+interface SectionHeaderProps extends A11yProps {
+    /** Section title text */
+    title: string;
+    /** Optional subtitle text */
+    subtitle?: string;
+    /** Text alignment */
+    align?: "center" | "left" | "right";
+    /** Heading level (1, 2, or 3) */
+    level?: 1 | 2 | 3;
+    /** Additional class names */
+    className?: string;
+}
+declare const SectionHeader: React__default.FC<SectionHeaderProps>;
+
+/**
+ * Spacer Component
+ *
+ * A flexible spacer that expands to fill available space in a flex container.
+ * Useful for pushing elements apart or creating consistent spacing.
+ */
+
+type SpacerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'auto';
+interface SpacerProps extends A11yProps {
+    /** Fixed size (auto = flex grow) */
+    size?: SpacerSize;
+    /** Orientation (for fixed sizes) */
+    axis?: 'horizontal' | 'vertical';
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Spacer - Flexible spacing element for flex layouts
+ *
+ * Usage:
+ * - size="auto" (default): Expands to fill available space (flex: 1)
+ * - size="md": Fixed size spacing
+ */
+declare const Spacer: React__default.FC<SpacerProps>;
+
+/**
+ * Sparkline Atom Component
+ *
+ * Minimal inline trend chart. Pure SVG polyline over a numeric series.
+ * Extracted from StatCard's sparkline path so any KPI or list row can
+ * include a trend visualization without compositing the whole card.
+ */
+
+type SparklineColor = "auto" | "primary" | "success" | "warning" | "error" | "info" | "muted";
+interface SparklineProps extends A11yProps {
+    /** Numeric series to plot. Length < 2 renders nothing. */
+    data: readonly number[];
+    /**
+     * Stroke color.
+     * `auto` (default): success when the series trends up (last ≥ first),
+     * error when it trends down.
+     */
+    color?: SparklineColor;
+    /** SVG width in px. Default 80. */
+    width?: number;
+    /** SVG height in px. Default 32. */
+    height?: number;
+    /** Stroke width in px. Default 2. */
+    strokeWidth?: number;
+    /** Fill the area under the line with the stroke color at low opacity. */
+    fill?: boolean;
+    /** Additional CSS classes. */
+    className?: string;
+}
+declare const Sparkline: React__default.FC<SparklineProps>;
+
+type SpinnerSize = "xs" | "sm" | "md" | "lg";
+/**
+ * @role status
+ * @tokens --color-foreground
+ * @motion css
+ */
+interface SpinnerProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>, keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    size?: SpinnerSize;
+    /** Renders a centered overlay backdrop instead of inline. */
+    overlay?: boolean;
+}
+declare const Spinner: React__default.ForwardRefExoticComponent<SpinnerProps & React__default.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Stack Component
+ *
+ * A layout primitive for arranging children in a vertical or horizontal stack with consistent spacing.
+ * Includes convenience exports VStack and HStack for common use cases.
+ */
+
+type StackDirection = "horizontal" | "vertical";
+type StackGap = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
+type StackJustify = "start" | "center" | "end" | "between" | "around" | "evenly";
+interface StackProps extends Omit<React__default.AriaAttributes, keyof A11yProps>, A11yProps {
+    /** Stack direction */
+    direction?: StackDirection;
+    /** Gap between children */
+    gap?: StackGap;
+    /** Align items on the cross axis */
+    align?: StackAlign;
+    /** Justify items on the main axis */
+    justify?: StackJustify;
+    /** Allow items to wrap */
+    wrap?: boolean;
+    /** Reverse the order of children */
+    reverse?: boolean;
+    /** Fill available space (flex: 1) */
+    flex?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Inline styles */
+    style?: React__default.CSSProperties;
+    /** Children elements */
+    children?: React__default.ReactNode;
+    /** HTML element to render as */
+    as?: React__default.ElementType;
+    /** Click handler */
+    onClick?: (e: React__default.MouseEvent) => void;
+    /**
+     * Keyboard handler
+     * @notification
+     */
+    onKeyDown?: (e: React__default.KeyboardEvent) => void;
+    /** Element id */
+    id?: string;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: EventKey;
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
+    actionPayload?: EventPayload;
+    /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
+    responsive?: boolean;
+}
+/**
+ * Stack - Flexible layout component for arranging children
+ */
+declare const Stack: React__default.FC<StackProps>;
+/**
+ * VStack - Vertical stack shorthand
+ */
+interface VStackProps extends Omit<StackProps, "direction"> {
+}
+declare const VStack: React__default.FC<VStackProps>;
+/**
+ * HStack - Horizontal stack shorthand
+ */
+interface HStackProps extends Omit<StackProps, "direction"> {
+}
+declare const HStack: React__default.FC<HStackProps>;
+
+type StatusDotStatus = "online" | "offline" | "away" | "busy" | "warning" | "critical";
+type StatusDotSize = "sm" | "md" | "lg";
+/**
+ * @role status
+ * @tokens --color-success --color-warning --color-error --color-muted-foreground
+ * @motion css
+ */
+interface StatusDotProps extends Omit<React__default.HTMLAttributes<HTMLSpanElement>, keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** Status determines the dot color */
+    status?: StatusDotStatus;
+    /** Enable pulse animation for active/critical states */
+    pulse?: boolean;
+    /** Dot size */
+    size?: StatusDotSize;
+    /** Accessible label (rendered as sr-only text) */
+    label?: string;
+}
+declare const StatusDot: React__default.ForwardRefExoticComponent<StatusDotProps & React__default.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * @accessibleName label
+ * @role switch
+ * @tokens --color-primary --color-muted --color-background
+ * @motion css
+ */
+interface SwitchProps extends A11yProps {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+    /** Declarative event name — emits UI:{action} with `actionPayload` and the new `checked` value on toggle */
+    action?: EventKey;
+    /** Payload to include with the action event (the new `checked` is added to it)
+     *  @payloadFor action
+     */
+    actionPayload?: EventPayload;
+    disabled?: boolean;
+    label?: string;
+    id?: string;
+    name?: string;
+    className?: string;
+}
+declare const Switch: React$1.ForwardRefExoticComponent<SwitchProps & React$1.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * TextHighlight Atom Component
+ *
+ * A styled span component for highlighting text with annotations (questions or notes).
+ * Uses different colors for different annotation types:
+ * - Questions: Blue highlight
+ * - Notes: Yellow highlight
+ */
+
+type HighlightType = "question" | "note";
+interface TextHighlightProps extends A11yProps {
+    /**
+     * Type of highlight (determines color)
+     */
+    highlightType: HighlightType;
+    /**
+     * Whether the highlight is currently active/focused
+     * @default false
+     */
+    isActive?: boolean;
+    /**
+     * Callback when highlight is clicked
+     */
+    onClick?: () => void;
+    /**
+     * Callback when highlight is hovered
+     * @notification
+     */
+    onMouseEnter?: () => void;
+    /**
+     * Callback when hover ends
+     * @notification
+     */
+    onMouseLeave?: () => void;
+    /**
+     * Unique ID for the annotation
+     */
+    annotationId?: string;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+    /**
+     * Highlighted text content
+     */
+    children: React__default.ReactNode;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: EventEmit<{
+        annotationId?: string;
+    }>;
+    /**
+     * Declarative hover event — emits UI:{hoverEvent} with { hovered, annotationId }
+     * @notification
+     */
+    hoverEvent?: EventEmit<{
+        hovered: boolean;
+        annotationId?: string;
+    }>;
+}
+/**
+ * TextHighlight component for rendering highlighted text annotations
+ */
+declare const TextHighlight: React__default.FC<TextHighlightProps>;
+
+/**
+ * @accessibleName label
+ * @role textbox
+ * @tokens --color-card --color-border --color-foreground --color-muted-foreground
+ * @contrast foreground card
+ * @motion none
+ */
+interface TextareaProps extends Omit<React__default.TextareaHTMLAttributes<HTMLTextAreaElement>, 'onChange' | keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** Visible label naming the field. */
+    label?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Number of visible rows */
+    rows?: number;
+    /** Controlled value, for a field the program fills or clears. */
+    value?: string;
+    /** Declarative event: fires on ⌘/Ctrl+Enter with `{ value }`. */
+    action?: EventEmit<{
+        value: string;
+    }>;
+    /** Helper text describing the field. */
+    helperText?: string;
+    /** Error message */
+    error?: string;
+    /** onChange handler or declarative event key for trait dispatch */
+    onChange?: React__default.ChangeEventHandler<HTMLTextAreaElement> | EventEmit<{
+        value: string;
+    }>;
+}
+declare const Textarea: React__default.ForwardRefExoticComponent<TextareaProps & React__default.RefAttributes<HTMLTextAreaElement>>;
+
+/**
+ * ThemeToggle Atom Component
+ *
+ * A button that toggles between light and dark themes.
+ * Uses Sun and Moon icons to indicate current/target theme.
+ *
+ * @packageDocumentation
+ */
+
+interface ThemeToggleProps extends A11yProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Size variant */
+    size?: "sm" | "md" | "lg";
+    /** Show label text */
+    showLabel?: boolean;
+    /** Accessible action label when the current mode is dark. */
+    switchToLightLabel?: string;
+    /** Accessible action label when the current mode is light. */
+    switchToDarkLabel?: string;
+    /** Visible light mode label. */
+    lightLabel?: string;
+    /** Visible dark mode label. */
+    darkLabel?: string;
+}
+/**
+ * ThemeToggle component for switching between light and dark modes
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <ThemeToggle />
+ *
+ * // With label
+ * <ThemeToggle showLabel />
+ *
+ * // Custom size
+ * <ThemeToggle size="lg" />
+ * ```
+ */
+declare const ThemeToggle: React__default.FC<ThemeToggleProps>;
+
+/**
+ * TimeSlotCell
+ *
+ * Calendar time slot atom. Renders a clickable container for a single
+ * time slot that can hold event content via children.
+ */
+
+interface TimeSlotCellProps extends A11yProps {
+    /** Time label for this slot (e.g. "09:00") */
+    time: string;
+    /** Called when the slot is clicked */
+    onClick?: (time: string) => void;
+    /** Additional CSS classes */
+    className?: string;
+    /** Event content placed inside the slot */
+    children?: React__default.ReactNode;
+    /** Whether this slot contains an event */
+    isOccupied?: boolean;
+    onPointerDown?: React__default.PointerEventHandler<HTMLDivElement>;
+    onPointerUp?: React__default.PointerEventHandler<HTMLDivElement>;
+    onPointerCancel?: React__default.PointerEventHandler<HTMLDivElement>;
+    /** @notification */
+    onPointerLeave?: React__default.PointerEventHandler<HTMLDivElement>;
+    "data-testid"?: string;
+}
+declare function TimeSlotCell({ time, onClick, className, children, isOccupied, onPointerDown, onPointerUp, onPointerCancel, onPointerLeave, "data-testid": testId, ...rest }: TimeSlotCellProps): React__default.JSX.Element;
+declare namespace TimeSlotCell {
+    var displayName: string;
+}
+
+type TrendDirection = "up" | "down" | "flat";
+type TrendIndicatorSize = "sm" | "md" | "lg";
+/**
+ * @role status
+ * @tokens --color-success --color-error --color-muted-foreground
+ * @motion none
+ */
+interface TrendIndicatorProps extends Omit<React__default.HTMLAttributes<HTMLSpanElement>, keyof A11yProps>, A11yProps {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** Numeric value to display (e.g., 12.5 for +12.5%) */
+    value?: number;
+    /** Override automatic direction detection (positive=up, negative=down, zero=flat) */
+    direction?: TrendDirection;
+    /** Show the formatted value text next to the arrow */
+    showValue?: boolean;
+    /** Invert color logic (for metrics where down is good, e.g., error rate, bounce rate) */
+    invert?: boolean;
+    /** Accessible label override */
+    label?: string;
+    /** Size of the indicator */
+    size?: TrendIndicatorSize;
+}
+declare const TrendIndicator: React__default.ForwardRefExoticComponent<TrendIndicatorProps & React__default.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * TypewriterText Atom Component
+ *
+ * Reveals text character-by-character with a blinking cursor
+ * that disappears after the full text has been typed out.
+ */
+
+interface TypewriterTextProps extends A11yProps {
+    /** The full text to reveal */
+    text: string;
+    /** Milliseconds per character */
+    speed?: number;
+    /** Delay before typing starts (ms) */
+    startDelay?: number;
+    /** Additional class names */
+    className?: string;
+    /**
+     * Event emitted (as UI:{onComplete}) when the entire text has been revealed; empty = none
+     * @notification
+     */
+    onComplete?: EventKey;
+}
+declare const TypewriterText: React__default.FC<TypewriterTextProps>;
+
+/**
+ * Typography Atom Component
+ *
+ * Text elements following the KFlow design system with theme-aware styling.
+ */
+
+type TypographyVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "heading" | "subheading" | "body1" | "body2" | "body" | "caption" | "overline" | "small" | "large" | "label";
+/** `none` = no size override — the variant's baked size applies. */
+type TypographySize = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+interface TypographyProps extends Omit<React__default.AriaAttributes, keyof A11yProps>, A11yProps {
+    /** Typography variant */
+    variant?: TypographyVariant;
+    /** Heading level (1-6) - alternative to variant for headings */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Text color */
+    color?: "primary" | "secondary" | "muted" | "error" | "success" | "warning" | "inherit";
+    /** Text alignment */
+    align?: "left" | "center" | "right";
+    /** Font weight override — `none` = no override, the variant's baked weight applies */
+    weight?: "none" | "light" | "normal" | "medium" | "semibold" | "bold";
+    /** Font size override */
+    size?: TypographySize;
+    /** Truncate with ellipsis (single line) */
+    truncate?: boolean;
+    /** Overflow handling mode */
+    overflow?: "visible" | "hidden" | "wrap" | "clamp-2" | "clamp-3";
+    /** Custom HTML element */
+    as?: keyof React__default.JSX.IntrinsicElements;
+    /** HTML id attribute */
+    id?: string;
+    /** Additional class names */
+    className?: string;
+    /** Inline style */
+    style?: React__default.CSSProperties;
+    /**
+     * Value formatting applied to string/number/Date content — `none` (the
+     * default) renders content as-is. Covers the raw-ISO-date class: a bound
+     * datetime renders human-readable via `format="date"|"time"|"datetime"`.
+     */
+    format?: "none" | "date" | "time" | "datetime" | "number" | "currency" | "percent";
+    /** Text content (alternative to children) */
+    content?: React__default.ReactNode;
+    /** Children elements */
+    children?: React__default.ReactNode;
+}
+declare const Typography: React__default.FC<TypographyProps>;
+
+interface SvgBranchProps extends A11yProps {
+    x?: number;
+    y?: number;
+    variant?: 'fork' | 'merge' | 'diamond';
+    branches?: number;
+    size?: number;
+    color?: string;
+    opacity?: number;
+    className?: string;
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgBranch: React__default.FC<SvgBranchProps>;
+
+interface SvgConnectionProps extends A11yProps {
+    x1?: number;
+    y1?: number;
+    x2?: number;
+    y2?: number;
+    variant?: 'solid' | 'dashed' | 'animated';
+    color?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    className?: string;
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgConnection: React__default.FC<SvgConnectionProps>;
+
+interface SvgFlowProps extends A11yProps {
+    points?: Array<[number, number]>;
+    color?: string;
+    strokeWidth?: number;
+    animated?: boolean;
+    opacity?: number;
+    className?: string;
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgFlow: React__default.FC<SvgFlowProps>;
+
+interface SvgGridProps extends A11yProps {
+    x?: number;
+    y?: number;
+    cols?: number;
+    rows?: number;
+    spacing?: number;
+    nodeRadius?: number;
+    color?: string;
+    opacity?: number;
+    className?: string;
+    highlights?: number[];
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgGrid: React__default.FC<SvgGridProps>;
+
+interface SvgLobeProps extends A11yProps {
+    cx?: number;
+    cy?: number;
+    rx?: number;
+    ry?: number;
+    rotation?: number;
+    shells?: number;
+    color?: string;
+    opacity?: number;
+    className?: string;
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgLobe: React__default.FC<SvgLobeProps>;
+
+interface SvgMeshProps extends A11yProps {
+    cx?: number;
+    cy?: number;
+    nodes?: number;
+    radius?: number;
+    color?: string;
+    connectionDensity?: number;
+    opacity?: number;
+    className?: string;
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgMesh: React__default.FC<SvgMeshProps>;
+
+interface SvgMorphProps extends A11yProps {
+    x?: number;
+    y?: number;
+    size?: number;
+    variant?: 'text-to-code' | 'code-to-app' | 'generic';
+    color?: string;
+    opacity?: number;
+    className?: string;
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgMorph: React__default.FC<SvgMorphProps>;
+
+interface SvgNodeProps extends A11yProps {
+    x?: number;
+    y?: number;
+    r?: number;
+    variant?: 'filled' | 'stroked' | 'pulse';
+    color?: string;
+    opacity?: number;
+    className?: string;
+    label?: string;
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgNode: React__default.FC<SvgNodeProps>;
+
+interface SvgPulseProps extends A11yProps {
+    cx?: number;
+    cy?: number;
+    rings?: number;
+    maxRadius?: number;
+    color?: string;
+    animated?: boolean;
+    opacity?: number;
+    className?: string;
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgPulse: React__default.FC<SvgPulseProps>;
+
+interface SvgRingProps extends A11yProps {
+    cx?: number;
+    cy?: number;
+    r?: number;
+    variant?: 'solid' | 'dashed' | 'glow';
+    color?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    className?: string;
+    label?: string;
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgRing: React__default.FC<SvgRingProps>;
+
+interface SvgShieldProps extends A11yProps {
+    x?: number;
+    y?: number;
+    size?: number;
+    variant?: 'outline' | 'filled' | 'check';
+    color?: string;
+    opacity?: number;
+    className?: string;
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    width?: number;
+    height?: number;
+}
+declare const SvgShield: React__default.FC<SvgShieldProps>;
+
+interface SvgStackProps extends A11yProps {
+    x?: number;
+    y?: number;
+    layers?: number;
+    width?: number;
+    height?: number;
+    color?: string;
+    opacity?: number;
+    className?: string;
+    labels?: string[];
+    /** When true (default), wraps in a standalone <svg> so the shape is visible without a parent SVG context. */
+    asRoot?: boolean;
+    svgWidth?: number;
+    svgHeight?: number;
+}
+declare const SvgStack: React__default.FC<SvgStackProps>;
+
+/**
+ * useDialogBehavior — the one owner of modal-dialog keyboard behavior
+ * (WAI-ARIA APG dialog pattern), shared by Modal and Drawer:
+ *
+ * - focus moves into the dialog on open and returns to the opener on close;
+ * - Tab / Shift+Tab wrap inside the dialog (focus trap);
+ * - Escape reaches only the top-most open dialog, so stacked overlays close
+ *   one at a time.
+ *
+ * A non-modal dialog (`modal: false`, e.g. Popover) joins the Escape stack
+ * but neither takes focus on open nor traps Tab.
+ */
+
+interface DialogBehaviorOptions {
+    open: boolean;
+    containerRef: RefObject<HTMLElement | null>;
+    onEscape: () => void;
+    closeOnEscape?: boolean;
+    modal?: boolean;
+    /** Where focus returns on close; defaults to whatever had focus at open
+     *  (a click does not focus a button in every browser, so triggers pass it). */
+    returnFocusRef?: RefObject<HTMLElement | null>;
+}
+declare function useDialogBehavior({ open, containerRef, onEscape, closeOnEscape, modal, returnFocusRef }: DialogBehaviorOptions): void;
+
+interface InfiniteScrollOptions {
+    /** Root margin for IntersectionObserver (default: "200px") */
+    rootMargin?: string;
+    /** Whether more items are available to load */
+    hasMore?: boolean;
+    /** Whether a load is currently in progress */
+    isLoading?: boolean;
+}
+interface InfiniteScrollResult {
+    /** Ref to attach to the sentinel element */
+    sentinelRef: React.RefCallback<HTMLElement>;
+}
+declare function useInfiniteScroll(onLoadMore: () => void, options?: InfiniteScrollOptions): InfiniteScrollResult;
+
+/**
+ * Reactively track a CSS media query (e.g. `'(pointer: coarse)'`).
+ *
+ * Components whose LAYOUT MATH depends on a media feature (a JS-computed
+ * grid track, an inline-action budget) can't express it in CSS alone —
+ * this hook is the one owner for that. `false` on the server and wherever
+ * there is no `matchMedia`.
+ */
+declare function useMediaQuery(query: string): boolean;
+
+/** Whether the OS asks for reduced motion — the one gate for JS/rAF/camera animations (CSS ones collapse in `_base.css`). */
+declare function usePrefersReducedMotion(): boolean;
+
+/**
+ * Hover-only reveals (tooltips, hover-popovers, submenus, `Box.hoverEvent`) have no hover on
+ * touch, so they're invisible/unreachable. This adds the tap-to-reveal fallback: on a touch/pen
+ * tap the surface reveals and fires the SAME event the hover path fires; a tap outside dismisses.
+ * Mouse is left to the component's existing hover handlers (`pointerType === 'mouse'` is ignored),
+ * so this is purely additive — no behavior change on desktop.
+ */
+interface TapRevealOptions {
+    /** Fired when a tap reveals — reuse to emit the component's existing hover event. */
+    onReveal?: () => void;
+    /** Fired when an outside tap (or a second trigger tap) dismisses. */
+    onDismiss?: () => void;
+    /**
+     * Elements considered "inside" for outside-tap detection. Pass the trigger and the surface
+     * (the surface may be portaled, so it isn't a DOM descendant of the trigger). A tap whose
+     * target is inside none of these dismisses.
+     */
+    refs?: ReadonlyArray<React.RefObject<HTMLElement | null>>;
+    /** When false, taps are ignored (hover-only). Default true. */
+    enabled?: boolean;
+}
+interface TapRevealResult {
+    /** Whether the surface is currently revealed via a tap. OR this with the hover state. */
+    revealed: boolean;
+    /** Spread on the trigger; toggles reveal on a touch/pen tap (ignores mouse). */
+    triggerProps: {
+        onPointerDown: (e: React.PointerEvent) => void;
+    };
+    reveal: () => void;
+    dismiss: () => void;
+}
+declare function useTapReveal(options?: TapRevealOptions): TapRevealResult;
+
+/**
+ * Shared value formatting — the single owner of the locale-aware format
+ * vocabulary used by every data display. Labels are never derived from names:
+ * a display shows the declared label, or the name/value as stored.
+ */
+
+type ValueFormat = 'none' | 'date' | 'time' | 'datetime' | 'number' | 'currency' | 'percent' | 'boolean';
+/**
+ * A `YYYY-MM-DD` value is a calendar day with no time zone. `new Date(s)`
+ * reads it as UTC midnight, which shows the previous day west of UTC; this
+ * parses it as local midnight instead. Returns null for any other shape.
+ */
+declare function parseCalendarDate(value: string): Date | null;
+/** A field value, or the `Date` a local calendar helper builds; a `Date` is never a stored field value (that is its ISO text). */
+type DateLike = FieldValue | Date;
+/** Value for an `<input type="date">`: the LOCAL calendar day. */
+declare function toDateInputValue(value: DateLike | undefined): string;
+/** Value for an `<input type="datetime-local">`: LOCAL wall-clock time. */
+declare function toDateTimeInputValue(value: DateLike | undefined): string;
+declare function formatDate(value: FieldValue | undefined, locale?: string): string;
+declare function formatTime(value: FieldValue | undefined, locale?: string): string;
+declare function formatDateTime(value: FieldValue | undefined, locale?: string): string;
+/** Translated boolean words, resolved by the caller (`t('common.yes')` / `t('common.no')`). */
+interface BooleanLabels {
+    yes: string;
+    no: string;
+}
+/** The app's formatting settings (see `useFormatContext`). */
+interface FormatContext {
+    /** BCP 47 locale; omitted, the runtime default */
+    locale?: string;
+    /** ISO 4217 currency for `currency` values */
+    currency?: string;
+    /** Translated Yes/No */
+    booleanLabels?: BooleanLabels;
+}
+/** Money is USD unless the host declares the app's currency (I18nContext `currency`). */
+declare const DEFAULT_CURRENCY = "USD";
+/**
+ * Format a field value for display. Booleans always render Yes/No regardless
+ * of the declared format (a raw `true`/`false` cell is never intended output).
+ */
+declare function formatValue(value: FieldValue | undefined, format?: string, fmt?: FormatContext): string;
+/** Sort direction for {@link sortRows}. */
+type SortDirection = 'asc' | 'desc';
+/**
+ * Order two cell values by their own type, never by what the field is called.
+ *
+ * Numbers compare numerically, date-like strings chronologically, everything
+ * else by locale string order. `null`/`undefined` sort last in both directions
+ * so empty cells never displace real data at the top of a list.
+ */
+declare function compareCellValues(a: FieldValue | undefined, b: FieldValue | undefined): number;
+/**
+ * Return a new array ordered by `field`. Non-mutating, and a no-op without a
+ * field so callers can pass the prop through unconditionally.
+ *
+ * NOTE: this orders only the rows already fetched. A collection larger than its
+ * `limit` still needs ordering at the data layer — see `L-NO-COLLECTION-ORDERING`.
+ */
+declare function sortRows<T extends Record<string, FieldValue | undefined>>(rows: readonly T[], field?: string, direction?: SortDirection): readonly T[];
+
+/**
+ * useTranslate — i18n hook for Almadar UI components.
+ *
+ * Provides locale-aware string translation via React context.
+ * No provider = passthrough: t('key') returns 'key' as-is (never crashes).
+ *
+ * Usage in organisms:
+ *   const { t, locale, direction } = useTranslate();
+ *   <Button>{t('common.save')}</Button>
+ *   <Typography>{t('table.showing', { count: 5, total: 20 })}</Typography>
+ *
+ * Templates MUST NOT use this hook (flattener rule). They receive
+ * translated strings via entity props from the organism above.
+ */
+
+type TranslateFunction = (key: string, params?: Record<string, string | number>) => string;
+interface I18nContextValue {
+    /** Current locale code (e.g. 'en', 'ar', 'sl') */
+    locale: string;
+    /** Text direction for the current locale */
+    direction: 'ltr' | 'rtl';
+    /** Translate a key, with optional interpolation params */
+    t: TranslateFunction;
+    /** The active locale's program catalog (qualified `<behavior>:<key>` → message): the runtime evaluates `i18n/t` against it. */
+    messages?: Readonly<Record<string, string>>;
+    /** ISO 4217 currency of the app's money values, declared by the host with the locale (e.g. `SAR` for an ar-SA app) */
+    currency?: string;
+}
+/**
+ * Provider component — wrap your app or Storybook decorator with this.
+ *
+ * ```tsx
+ * <I18nProvider value={{ locale: 'ar', direction: 'rtl', t: createTranslate(arMessages) }}>
+ *   <App />
+ * </I18nProvider>
+ * ```
+ */
+interface I18nProviderProps {
+    value: I18nContextValue;
+    children?: React__default.ReactNode;
+    /** The app's root provider: mirrors locale + direction onto `<html lang dir>`.
+     *  Embedded previews omit it so they never rewrite their host document. */
+    documentRoot?: boolean;
+}
+declare function I18nProvider({ value, children, documentRoot }: I18nProviderProps): React__default.ReactElement;
+/**
+ * Hook to access the current locale and translate function.
+ * Safe to call without a provider — returns passthrough t().
+ */
+declare function useTranslate(): I18nContextValue;
+/** The viewer's locale and its catalog, for `i18n/t` / `@locale` evaluated in the browser. */
+interface RenderI18n {
+    locale: string;
+    messages: Readonly<Record<string, string>>;
+}
+/** The provider's locale + catalog as one identity-stable value; undefined when the host supplied no catalog. */
+declare function useRenderI18n(): RenderI18n | undefined;
+/** The app's formatting settings for `formatValue`: its locale, currency and translated Yes/No. */
+declare function useFormatContext(): FormatContext;
+/**
+ * Create a translate function from a flat messages object.
+ *
+ * ```ts
+ * const t = createTranslate({ 'common.save': 'Save', 'table.showing': 'Showing {{count}} of {{total}}' });
+ * t('common.save') // → 'Save'
+ * t('table.showing', { count: 5, total: 20 }) // → 'Showing 5 of 20'
+ * t('missing.key') // → 'missing.key' (fallback)
+ * ```
+ *
+ * Pass `locale` so built-in component labels the app catalog doesn't carry
+ * come from the UI's own catalog for that locale before English.
+ */
+declare function createTranslate(messages: Record<string, string>, locale?: string): TranslateFunction;
+
+/**
+ * Changes inside a container ease in instead of switching in one frame: an
+ * element that appears fades and rises in, text that changes in place fades
+ * in on its element, blocks the change pushed glide to their new place, and the
+ * container's own height eases to fit its new content. Rows with their own motion (item glides, entrance classes) are left alone. Timing is the theme's `--duration-normal` /
+ * `--easing-emphasized`; off under reduced motion.
+ */
+
+declare function useAnimateChanges(ref: RefObject<HTMLElement | null>, enabled: boolean): void;
+
+/**
+ * Utility function to merge Tailwind CSS classes
+ * Combines clsx for conditional classes with tailwind-merge to handle conflicts
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * The attribute namespaces a layout/text primitive forwards to its element:
+ * `aria-*`, `data-*`, `role`, `id`, `lang`, `dir` and `tabIndex` (HTML's own
+ * global-attribute contract; @almadar/core A11yProps).
+ * The runtime renderer spreads schema props onto components, so anything else
+ * stays off the DOM.
+ */
+type DomPassthrough = Record<string, string | number | boolean | undefined>;
+declare function domPassthrough(props: object): DomPassthrough;
+
+/**
+ * NavigationContext - Schema-Driven Navigation for Orbital Runtime
+ *
+ * Provides navigation within the orbital schema without react-router dependency.
+ * Navigation works by:
+ * 1. Matching path to a page in the schema
+ * 2. Extracting route params (e.g., /inspection/:id → { id: "123" })
+ * 3. Switching active page
+ * 4. Triggering INIT with merged payload
+ *
+ * This approach works whether OrbitalRuntime is standalone or embedded in another app.
+ *
+ * Used by both:
+ * - Builder runtime (interpreted execution)
+ * - Compiled shells (generated applications)
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extract route params from a path given its pattern.
+ * Wrapper around matchPath for explicit use.
+ */
+declare function extractRouteParams(pattern: string, path: string): Record<string, string>;
+/**
+ * Check if a path matches a pattern.
+ */
+declare function pathMatches(pattern: string, path: string): boolean;
+/**
+ * Find a page in the schema by matching its path pattern against a concrete path.
+ * Returns the page and extracted route params.
+ */
+declare function findPageByPath(schema: OrbitalSchema, path: string): {
+    page: OrbitalPage;
+    params: Record<string, string>;
+    orbitalName: string;
+} | null;
+/**
+ * Find a page by name.
+ */
+declare function findPageByName(schema: OrbitalSchema, pageName: string): {
+    page: OrbitalPage;
+    orbitalName: string;
+} | null;
+/**
+ * Get the first page in the schema (default page).
+ */
+declare function getDefaultPage(schema: OrbitalSchema): {
+    page: OrbitalPage;
+    orbitalName: string;
+} | null;
+/**
+ * Get all pages from the schema.
+ */
+declare function getAllPages(schema: OrbitalSchema): Array<{
+    page: OrbitalPage;
+    orbitalName: string;
+}>;
+interface NavigationState {
+    /** Current active page name */
+    activePage: string;
+    /** Current path (for URL sync) */
+    currentPath: string;
+    /** Payload to pass to INIT when page loads */
+    initPayload: Record<string, FieldValue>;
+    /** Navigation counter (increments on each navigation) */
+    navigationId: number;
+}
+interface NavigationContextValue {
+    /** Current navigation state */
+    state: NavigationState;
+    /** Navigate to a path with optional payload */
+    navigateTo: (path: string, payload?: Record<string, FieldValue>) => void;
+    /** Navigate to a page by name with optional payload */
+    navigateToPage: (pageName: string, payload?: Record<string, FieldValue>) => void;
+    /** The schema being navigated */
+    schema: OrbitalSchema;
+    /** Whether navigation is ready (schema loaded) */
+    isReady: boolean;
+}
+interface NavigationProviderProps {
+    /** The schema to navigate within */
+    schema: OrbitalSchema;
+    /** Initial page name (optional, defaults to the page marked initial, else the first) */
+    initialPage?: string;
+    /** Whether to update browser URL on navigation (default: true) */
+    updateUrl?: boolean;
+    /** Callback when navigation occurs */
+    onNavigate?: (pageName: string, path: string, payload: Record<string, FieldValue>) => void;
+    /** Children */
+    children: React__default.ReactNode;
+}
+/**
+ * NavigationProvider - Provides schema-driven navigation context
+ *
+ * @example
+ * ```tsx
+ * <NavigationProvider schema={mySchema}>
+ *   <OrbitalRuntimeContent />
+ * </NavigationProvider>
+ * ```
+ */
+declare function NavigationProvider({ schema, initialPage, updateUrl, onNavigate, children, }: NavigationProviderProps): React__default.ReactElement;
+/**
+ * Hook to access navigation context.
+ * Returns null if not within NavigationProvider.
+ */
+declare function useNavigation(): NavigationContextValue | null;
+/**
+ * Hook to get the navigateTo function.
+ * Returns a no-op function if not within NavigationProvider.
+ */
+declare function useNavigateTo(): (path: string, payload?: Record<string, FieldValue>) => void;
+/**
+ * Hook to get current navigation state.
+ */
+declare function useNavigationState(): NavigationState | null;
+/**
+ * Hook to get the current INIT payload (for passing to trait INIT events).
+ */
+declare function useInitPayload(): Record<string, FieldValue>;
+/**
+ * Hook to get current active page name.
+ */
+declare function useActivePage(): string | null;
+/**
+ * Hook to get navigation ID (changes on each navigation, useful for triggering effects).
+ */
+declare function useNavigationId(): number;
+
+/**
+ * Navigation-stack core — the pure logic behind the orbital-scoped
+ * client-session navigation stack both execution paths share.
+ *
+ * The stack is what detail-page breadcrumb bands and the `navigate-back`
+ * effect read. It lives client-side only (per browser tab): the runtime
+ * path's OrbPreview and the compiled app's App.tsx both mount
+ * `NavStackProvider` (providers/NavStackContext.tsx), which drives this
+ * module on every route change.
+ *
+ * Semantics (deterministic):
+ * - One stack per ORBITAL, keyed by the orbital owning the current page.
+ * - On route change: an entry with the same href already in the stack
+ *   truncates back to it (revisit); otherwise the new entry is pushed.
+ * - Cold load (deep link): the stack seeds from the declared page-path
+ *   hierarchy — every declared page whose pattern matches a strict prefix
+ *   of the concrete path becomes an ancestor entry — so the trail is never
+ *   empty and back always has a target on nested paths.
+ * - Entry label = the `crumb` carried by the navigate effect when one was
+ *   staged for this href, else the page's declared label, else its name as written.
+ */
+
+/** One declared page as the nav stack needs it: path pattern + name + owning orbital + declared label. */
+interface NavPageDecl {
+    path: string;
+    name: string;
+    orbital: string;
+    /** Declared nav label (`@label`); absent = the page name as written. */
+    label?: string;
+}
+/** Per-orbital stacks. */
+type NavStackState = Record<string, NavStackEntry[]>;
+/** Crumb staged by a `(navigate … { crumb })` effect, consumed by the next sync. */
+interface PendingCrumb {
+    href: string;
+    crumb: string;
+}
+/** A page's entry label: its declared label, else the declared navItem label for it, else its name as written (never derived). */
+declare function pageEntryLabel(page: NavPageDecl, navLabels?: NavItemLabels): string;
+/** Declared navItem labels keyed by the page path each item's href resolves to. */
+type NavItemLabels = Readonly<Record<string, string>>;
+/** A declared navigation item (the app shell's `navItems`), children included. */
+interface NavItemDecl {
+    href: string;
+    label: string;
+    children?: readonly NavItemDecl[];
+}
+/** Map every navItem (children too) to the declared page its href resolves to; hrefs matching no page are skipped. */
+declare function navLabelsFromItems(pages: readonly NavPageDecl[], items: readonly NavItemDecl[]): Record<string, string>;
+/**
+ * Entries whose label is still their page's own fallback (declared label or
+ * name) take the page's navItem label; a staged record crumb is left alone.
+ */
+declare function resolveEntryLabels(entries: readonly NavStackEntry[], pages: readonly NavPageDecl[], navLabels: NavItemLabels): readonly NavStackEntry[];
+/** The page a concrete path resolves to (specificity-ranked), or null. */
+declare function matchNavPage(pages: readonly NavPageDecl[], path: string): NavPageDecl | null;
+/**
+ * Fold a route change into the stack state. Returns the next state plus the
+ * orbital owning the current path (`null` when no declared page matches —
+ * e.g. /login — in which case the state is returned unchanged).
+ */
+declare function syncNavStack(state: NavStackState, pages: readonly NavPageDecl[], path: string, pending: PendingCrumb | null): {
+    state: NavStackState;
+    orbital: string | null;
+};
+/**
+ * Relabel the entry for the current path — the loaded record's real title
+ * replacing the page-name fallback (`Contract Detail` → the contract's
+ * title). Fed by DetailPanel when it renders a resolved record in the
+ * routed main slot, so cold loads and refreshes read like in-app pushes.
+ * Returns the same state object when nothing changes (no page match, or
+ * the label already equals `label`) so callers can skip re-renders.
+ */
+declare function relabelCurrent(state: NavStackState, pages: readonly NavPageDecl[], path: string, label: string): NavStackState;
+/**
+ * The previous entry for the current path's orbital — the `navigate-back`
+ * target — or null when the stack holds no earlier entry (top-level page).
+ */
+declare function previousEntry(state: NavStackState, pages: readonly NavPageDecl[], path: string): NavStackEntry | null;
+/** Entries for the current path's orbital (empty when no page matches). */
+declare function entriesFor(state: NavStackState, pages: readonly NavPageDecl[], path: string): readonly NavStackEntry[];
+
+/**
+ * NavStackProvider — the orbital-scoped client-session navigation stack.
+ *
+ * One provider instance per app host. Both execution paths mount it:
+ * - Runtime path: OrbPreview supplies `currentPath` + `navigate` explicitly.
+ * - Compiled path: the emitted App.tsx mounts `NavStackRouterBridge`, which
+ *   reads react-router's location/navigate and renders this provider.
+ *
+ * Pure stack semantics live in lib/navStack.ts (one owner for both paths).
+ * State persists to sessionStorage (per-tab) so a compiled app's full page
+ * reload keeps the trail; every storage access is guarded with an in-memory
+ * fallback.
+ */
+
+interface NavStackApi {
+    /** Stack of the current page's orbital, root-first (empty when no declared page matches). */
+    entries: readonly NavStackEntry[];
+    /** True when a previous entry exists for the current page's orbital. */
+    canGoBack: boolean;
+    /** Stage the crumb label for the entry the target page will record, then call navigate yourself. */
+    beginNavigate: (href: string, crumb?: string) => void;
+    /** Pop the current orbital's stack: navigate to the previous entry (no-op without one). */
+    back: () => void;
+    /** Navigate to an arbitrary stack entry (breadcrumb click). */
+    goTo: (href: string) => void;
+    /** Relabel the current page's stack entry with the loaded record's title
+     *  (idempotent; no-op when the label already matches). DetailPanel calls
+     *  this from the routed main slot so cold-loaded crumbs read like pushes. */
+    setCurrentLabel: (label: string) => void;
+    /** The app shell's declared navItems: a page reached by one shows that item's label in the trail. */
+    registerNavItems: (items: readonly NavItemDecl[]) => void;
+}
+/** True when no NavStackProvider is mounted above (plain React / SSR hosts). */
+declare function isInertNavStack(api: NavStackApi): boolean;
+declare function useNavStack(): NavStackApi;
+interface NavStackProviderProps {
+    pages: readonly NavPageDecl[];
+    /** Concrete current path (route params substituted), e.g. /contracts/42. */
+    currentPath: string;
+    /** Host navigation function (SPA route change). */
+    navigate: (path: string) => void;
+    /** sessionStorage key; omit to keep the stack in memory only. */
+    storageKey?: string;
+    children: React__default.ReactNode;
+}
+declare const NavStackProvider: React__default.FC<NavStackProviderProps>;
+interface NavStackRouterBridgeProps {
+    pages: readonly NavPageDecl[];
+    storageKey?: string;
+    children: React__default.ReactNode;
+}
+/**
+ * Compiled-path host: binds NavStackProvider to react-router. Must render
+ * inside a Router (the emitted App.tsx mounts it directly under
+ * BrowserRouter).
+ */
+declare const NavStackRouterBridge: React__default.FC<NavStackRouterBridgeProps>;
+
+/** True for an absolute URL (`https:`, `mailto:`, …) that must load outside the app. */
+declare function isAbsoluteHref(href: string): boolean;
+/** Follow an href: an in-page `#anchor` scrolls to it, an absolute URL loads, a path goes through the nav stack (or loads when there is none). */
+declare function followHref(href: string, navStack: NavStackApi): void;
+
+/**
+ * Icon family runtime resolver (Layer 1 Iconography axis).
+ *
+ * Reads the active `--icon-family` CSS variable from the document element and
+ * dispatches a canonical icon name (kebab-case, matching lucide's vocabulary)
+ * to the equivalent lucide component. Subscribes to data-theme attribute changes
+ * via MutationObserver so a theme switch re-renders icons without a page reload.
+ *
+ * Non-lucide families (phosphor, tabler, fontawesome) are temporarily disabled
+ * to keep them out of client bundles. They can be re-enabled later behind an
+ * async chunk boundary once the workspace/publish dust settles.
+ *
+ * See `docs/Almadar_Std_Variations.md` §2 and `themes/_contract.md`.
+ */
+
+type IconFamily = IconFamily$1;
+/** Adapter props that EVERY family-specific icon component accepts at this layer. */
+interface RenderedIconProps {
+    className?: string;
+    strokeWidth?: number;
+    size?: number;
+    style?: React__default.CSSProperties;
+}
+/** Read --icon-family from <html> at runtime. Returns 'lucide' on SSR. */
+declare function getCurrentIconFamily(): IconFamily;
+/** React hook: whether the theme's `--icon-stroke-width` applies to the rendered icons. */
+declare function useThemeIconStrokeApplies(ref: React__default.RefObject<Element | null>): boolean;
+/** React hook: returns the active icon family, re-renders on theme switch. */
+declare function useIconFamily(): IconFamily;
+type RenderedIcon = React__default.ForwardRefExoticComponent<RenderedIconProps & React__default.RefAttributes<SVGSVGElement>>;
+/**
+ * Dispatch a canonical icon name to the active family component.
+ * Non-lucide families are currently disabled and fall back to lucide.
+ */
+declare function resolveIconForFamily(name: string, _family: IconFamily): RenderedIcon;
+/**
+ * Resolve a canonical icon name to a family-aware component. The returned
+ * component re-renders the icon into the active family's library on theme
+ * switch (via useIconFamily's MutationObserver subscription).
+ */
+declare function useResolvedIcon(name: string): RenderedIcon;
+
+/**
+ * The attribute a component puts on the element that shows one of its text
+ * props (value: the prop name), so an editor can edit that text in place and
+ * write it back to exactly that prop.
+ */
+declare const INLINE_TEXT_ATTR = "data-inline-text";
+
+/** Kebab-case to PascalCase: 'shopping-cart' -> 'ShoppingCart', 'trash-2' -> 'Trash2'. */
+declare function kebabToPascal(name: string): string;
+/** The lucide module key for a kebab-case or PascalCase icon name; undefined when lucide has no such icon. */
+declare function lucideIconKey(name: string): string | undefined;
+/**
+ * Resolve an icon name to a lucide component, sync. Aliases and the help glyph are bundled; every other icon
+ * is its own on-demand module, so a client downloads only the icons its program names.
+ */
+declare function resolveLucideByName(name: string): LucideIcon;
+
+/** A CSS `<time>` (`400ms`, `.4s`) in milliseconds; NaN when it is not one. */
+declare function cssTimeMs(value: string): number;
+/**
+ * Duration + easing from the named tokens as they resolve at `scope` (default: the page root),
+ * or undefined when motion is off (theme, OS reduced motion, or tokens absent).
+ */
+declare function motionTiming(durationToken: string, easingToken: string, scope?: Element): {
+    duration: number;
+    easing: string;
+} | undefined;
+/**
+ * How much `el` is scaled on screen by transforms above it (a desktop-size demo scaled to fit):
+ * its on-screen width over its layout width; 1 when it is not laid out. Script-driven motion
+ * measures on screen and animates in layout pixels, so it divides by this.
+ */
+declare function layoutScale(el: Element): number;
+
+/** A fresh key for one activation of a control. */
+declare function newPendingKey(): string;
+/** A dispatch carrying `key` started. */
+declare function beginPending(key: string): void;
+/** A dispatch carrying `key` settled. */
+declare function endPending(key: string): void;
+declare function isPending(key: string): boolean;
+declare function subscribePending(key: string, cb: () => void): () => void;
+/**
+ * A region (a modal) that holds still while an action started inside it is in
+ * flight: its confirm button stays busy and the dialog does not leave before
+ * the action settles.
+ */
+interface PendingScopeValue {
+    track: (key: string) => void;
+    hasPending: () => boolean;
+    subscribe: (cb: () => void) => () => void;
+}
+declare const PendingScopeContext: React$1.Context<PendingScopeValue | null>;
+/** Builds the value a `PendingScopeContext.Provider` carries. */
+declare function usePendingScopeValue(): PendingScopeValue;
+/** Whether the nearest pending scope (or the given one) has an action in flight. */
+declare function useScopeHasPending(scope: PendingScopeValue | null): boolean;
+/**
+ * One control's busy state. `activate(emit)` hands `emit` a fresh key to stamp
+ * on the event it sends; `pending` is true until every dispatch that event
+ * started has settled.
+ */
+declare function usePendingAction(): {
+    pending: boolean;
+    activate: (emit: (pendingKey: string) => void) => void;
+};
+/**
+ * Busy state per row of a collection: a row action marks ITS row pending while
+ * the dispatches it started are in flight.
+ */
+declare function usePendingRows(): {
+    isRowPending: (rowId: string) => boolean;
+    activateRow: (rowId: string, emit: (pendingKey: string) => void) => void;
+};
+
+/**
+ * pressableProps — props that make a non-button surface (a card, a row, a cell)
+ * an operable control: `role="button"`, a tab stop, and Enter/Space activation
+ * (WAI-ARIA APG button). Without a handler it returns nothing, so a surface is
+ * only ever a control when it declares an action. A plain function, not a
+ * hook, so row loops can call it. Enter/Space dispatch a real
+ * click, so the surface's `onClick` receives the same MouseEvent either way.
+ */
+
+interface PressableProps<T extends Element = HTMLElement> {
+    role?: 'button';
+    tabIndex?: number;
+    'aria-disabled'?: true;
+    onClick?: (e: React__default.MouseEvent<T>) => void;
+    onKeyDown?: (e: React__default.KeyboardEvent<T>) => void;
+}
+declare function pressableProps<T extends Element = HTMLElement>(onPress: ((e: React__default.MouseEvent<T>) => void) | undefined, options?: {
+    disabled?: boolean;
+}): PressableProps<T>;
+interface RowActivationProps<T extends Element = HTMLElement> {
+    tabIndex?: number;
+    onClick?: (e: React__default.MouseEvent<T>) => void;
+    onKeyDown?: (e: React__default.KeyboardEvent<T>) => void;
+}
+/**
+ * A clickable table/list row keeps its own role (`row`), so it cannot become a
+ * button; it gets a tab stop and Enter activation instead, dispatching the
+ * same click.
+ */
+declare function rowActivationProps<T extends Element = HTMLElement>(onActivate: ((e: React__default.MouseEvent<T>) => void) | undefined): RowActivationProps<T>;
+/**
+ * The keyboard/AT half of a clickable row: the row container owns the plain
+ * `onClick` (no role, no tab stop), and ONE element inside it — the title, or
+ * an overlay for custom-rendered rows — is the named `role="button"` tab stop.
+ * Enter/Space dispatch a real click that bubbles to the row, so activation runs
+ * through the one handler and row-action buttons stay siblings instead of
+ * buttons nested inside a button. Action clusters must stop propagation.
+ */
+declare function rowOpenControlProps<T extends Element = HTMLElement>(enabled: boolean): {
+    role?: 'button';
+    tabIndex?: number;
+    onKeyDown?: (e: React__default.KeyboardEvent<T>) => void;
+};
+/** Focus ring for a row-open control, painted over its whole row via `::after` (row needs `relative`). */
+declare const STRETCHED_CONTROL = "after:absolute after:inset-0 after:content-[''] after:rounded-[inherit] focus-visible:outline-none focus-visible:after:ring-2 focus-visible:after:ring-primary focus-visible:after:ring-inset";
+/** Lifts interactive row content (action clusters, checkboxes) above a STRETCHED_CONTROL's ::after. */
+declare const STRETCHED_ABOVE = "relative z-[1]";
+
+/**
+ * Render-time expression evaluation on the kernel's one evaluator.
+ *
+ * A render binds many expressions against one context (a form's conditional fields and sections, a list's
+ * row actions). Each helper here takes the whole batch and crosses into the kernel once; a caller with no
+ * expression never touches the kernel. The module that loads the kernel installs the evaluator
+ * (`KernelEngineProvider`), and there is no other evaluator to fall back on.
+ *
+ * @packageDocumentation
+ */
+
+/** The value of each expression against `context`, in one crossing; throws `KernelEvalError` on the first that fails. */
+declare function evaluateBindings(context: EvalContextWire, expressions: readonly SExpr[]): JsonValue[];
+/** The value of one expression against `context`; throws `KernelEvalError` when it fails. */
+declare function evaluateBinding(context: EvalContextWire, expression: SExpr): JsonValue;
+/** Whether each guard holds against `context` (the kernel's truthiness), in one crossing; throws on the first that fails. */
+declare function guardsHold(context: EvalContextWire, guards: readonly SExpr[]): boolean[];
+
+declare const SVG_MOTION_CLASSES: {
+    readonly flowDash: "almadar-svg-flow-dash";
+    readonly pulseRing: "almadar-svg-pulse-ring";
+    readonly pulseExpand: "almadar-svg-pulse-expand";
+};
+type SvgMotion = keyof typeof SVG_MOTION_CLASSES;
+/** The class for `motion` when the element animates and theme motion is on. */
+declare function svgMotionClass(motion: SvgMotion, animated: boolean): string | undefined;
+
+/**
+ * The custom scale keys `tailwind-preset.cjs` adds on top of Tailwind's stock
+ * scales, by theme group. `cn` registers them with tailwind-merge so a caller's
+ * class replaces a component's default of the same group; `cn.test.ts` fails
+ * when the preset gains a key that is missing here.
+ */
+declare const THEME_SCALE_KEYS: {
+    readonly height: readonly ["button-sm", "button-md", "button-lg", "input-sm", "input-md", "input-lg", "row-compact", "row-normal", "row-spacious", "icon-default"];
+    readonly minHeight: readonly ["button-sm", "button-md", "button-lg", "input-sm", "input-md", "input-lg", "row-compact", "row-normal", "row-spacious"];
+    readonly width: readonly ["icon-default"];
+    readonly fontSize: readonly ["display-1", "display-2"];
+    readonly borderRadius: readonly ["container", "interactive", "pill"];
+    readonly boxShadow: readonly ["elevation-card", "elevation-popover", "elevation-dialog", "elevation-toast", "elevation-interactive", "elevation-pressed"];
+    readonly spacing: readonly ["card-sm", "card-md", "card-lg", "dialog", "section"];
+};
+
+/**
+ * Which traits have rendered output on screen — what a `[visible]` tick asks
+ * before it fires (LOLO §11). A trait is `absent` when nothing it renders is
+ * mounted, `on-screen` when any of its output is near the viewport in a
+ * visible tab, and `off-screen` otherwise.
+ *
+ * Only watched traits are tracked: `TraitScopeProvider` wraps a trait's output
+ * in a layout-neutral `display: contents` element only while some tick runner
+ * watches that trait, so programs without `[visible]` ticks render unchanged.
+ */
+
+type TraitPresenceState = 'absent' | 'on-screen' | 'off-screen';
+interface TraitPresence {
+    /** Ask for these traits' output to be tracked; returns the release. */
+    watch(traits: readonly string[]): () => void;
+    isWatched(trait: string): boolean;
+    /** Notified when the watched set changes. */
+    subscribe(listener: () => void): () => void;
+    /** Track `wrapper`'s rendered boxes as `trait`'s output; returns the detach. */
+    attach(trait: string, wrapper: Element): () => void;
+    /** The presence of a group: on screen when any member is, absent when no member renders. */
+    state(traits: readonly string[]): TraitPresenceState;
+}
+/** The element boxes a wrapper renders, looking through `display: contents` layers. */
+declare function boxesOf(el: Element): Element[];
+declare function createTraitPresence(): TraitPresence;
+/** The one presence registry for this document. */
+declare function getTraitPresence(): TraitPresence;
+/** The traits whose output decides `traitName`'s presence: itself, or every trait sharing its `[shared]` entity's frame (LOLO §11). */
+declare function presenceGroup(traitIndex: {
+    byName: ReadonlyMap<string, Pick<TraitSurface, 'shared' | 'frameKey'>>;
+}, traitName: string): string[];
+
+/**
+ * Content surfaces: the background box behind a content block (table,
+ * calendar, list, chart …). Every block paints the theme-owned `.surface-content`
+ * by default, so a patterned page never shows through one block and not the
+ * next; the THEME decides what that surface looks like via `--surface-content-*`.
+ *
+ * Anything that already is a surface (a Card, a dialog, a panel, or a block that
+ * painted one) marks its subtree, and a block inside that subtree stays flat —
+ * declared ancestry, so a surface never nests inside another.
+ */
+
+/** Marks its subtree as already sitting on a surface. */
+declare function SurfaceBoundary({ children }: {
+    children?: React__default.ReactNode;
+}): React__default.ReactElement;
+interface ContentSurface {
+    /** `surface-content` when this block paints the surface, otherwise undefined. */
+    className: string | undefined;
+    /** Wraps the block's content so nested blocks know they already sit on a surface. */
+    provide: (node: React__default.ReactNode) => React__default.ReactElement;
+}
+declare function useContentSurface(surface?: SurfaceMode): ContentSurface;
+/** True when an ancestor already painted a surface. */
+declare function useOnSurface(): boolean;
+
+/**
+ * GENERATED — do not edit by hand. One entry per @almadar/core theme preset
+ * (packages/almadar-core/themes/*.json). Regenerate: almadar-sync themes.
+ */
+
+declare const BUILT_IN_THEMES: UIThemeDefinition[];
+
+/**
+ * TraitScopeProvider
+ *
+ * Wraps a trait's rendered subtree with its owning `{ orbital, trait }`
+ * pair. Pure components inside the subtree (Button, Form, etc.) keep
+ * calling `useEventBus().emit('UI:X', ...)` exactly as today; the
+ * scoped wrapper that `useEventBus` returns inside this provider
+ * rewrites bare `UI:X` keys into the qualified
+ * `UI:Orbital.Trait.X` form that `useTraitStateMachine` (and the rest
+ * of the post-Phase 4 subscriber side) listens on.
+ *
+ * Producer-side fix for the gap where Button-emitted bare keys never
+ * reached the trait state machine in the runtime path. The compiled
+ * path's codegen wraps each trait view with the same provider so both
+ * paths share the qualification contract.
+ *
+ * ## Embedded-trait emit bubbling (R-EMBEDDED-EMIT-BUBBLE)
+ *
+ * Providers NEST: when a trait's `render-ui` embeds another trait
+ * (`@trait.X` / inline `<External.Trait …/>`), the embedded view is
+ * rendered inside the host's subtree AND wraps itself in its own
+ * provider. The context therefore carries the full scope CHAIN
+ * (innermost-first), not a single scope. `useEventBus` fans every
+ * `UI:*` emit out to each scope on the chain so the host trait's
+ * subscribers hear emits from the embedded trait — a button authored
+ * as `<UiButton.traits.ButtonRender action={CREATE}/>` inside a host
+ * dispatches on the host's qualified key, not only the hoisted atom's.
+ *
+ * @packageDocumentation
+ */
+
+interface TraitScope {
+    /** Owning orbital name (e.g. `"ContactOrbital"`). */
+    orbital: string;
+    /** Trait name within the orbital (e.g. `"ContactBrowse"`). */
+    trait: string;
+}
+/**
+ * Scope chain, innermost-first. `chain[0]` is the trait whose subtree
+ * the caller renders inside; `chain[1..]` are its host ancestors (the
+ * traits whose `render-ui` embedded it, outermost last). An empty
+ * chain means the caller is outside any `TraitScopeProvider`.
+ */
+type TraitScopeChain = readonly TraitScope[];
+interface TraitScopeProviderProps {
+    orbital: string;
+    trait: string;
+    children?: React__default.ReactNode;
+}
+/**
+ * Wrap a trait's rendered subtree to qualify bare `UI:*` emits with the
+ * trait's scope. Mount this at the slot-content boundary in runtime
+ * mode (UISlotRenderer) and at each generated trait view's outermost
+ * element in compiled mode (orbital-shell-typescript codegen). Nesting
+ * is preserved: a provider prepends itself to the parent chain so
+ * embedded-trait emits can bubble to their host.
+ */
+declare function TraitScopeProvider({ orbital, trait, children, }: TraitScopeProviderProps): React__default.ReactElement;
+/**
+ * Read the full trait-scope chain, innermost-first. Empty when called
+ * outside any `TraitScopeProvider` (e.g. Storybook, design-system
+ * catalog). `useEventBus` uses this to fan embedded-trait emits out to
+ * every host ancestor.
+ */
+declare function useTraitScopeChain(): TraitScopeChain;
+/**
+ * Read the innermost (nearest) trait scope. Returns `null` when called
+ * outside any `TraitScopeProvider`. Kept for callers that only need the
+ * immediate scope.
+ */
+declare function useTraitScope(): TraitScope | null;
+
+/**
+ * Core locale loader for @almadar/ui.
+ *
+ * Exports message maps for en/ar/sl and a helper to merge
+ * project-specific messages on top of core.
+ */
+type SupportedLocale = 'en' | 'ar' | 'sl';
+interface LocaleMeta {
+    locale: string;
+    direction: 'ltr' | 'rtl';
+}
+/** Core messages keyed by locale */
+declare const coreMessages: Record<SupportedLocale, Record<string, string>>;
+/** Locale metadata */
+declare const localeMeta: Record<SupportedLocale, LocaleMeta>;
+/**
+ * Merge core messages with project-specific messages.
+ * Project keys override core keys.
+ */
+declare function mergeMessages(locale: SupportedLocale, projectMessages: Record<string, string>): Record<string, string>;
+
+export { AnimatedGraphic, AnimatedReveal, Aside, AtlasImage, AtlasPanel, Avatar, BAND_ACCENT_FALLBACK, BAND_EDGE_FILL, BAND_SHAPES, BUILT_IN_THEMES, Box, Card, CardBody, CardContent, CardFooter, CardHeader, CardTitle, Center, Checkbox, ConditionalWrapper, ConfettiEffect, DEFAULT_CURRENCY, DayCell, Dialog, Divider, FilterPill, FlipContainer, GameIcon, HStack, I18nProvider, INLINE_TEXT_ATTR, IconInput, Image, InfiniteScrollSentinel, Label, LawReferenceTooltip, NavStackProvider, NavStackRouterBridge, NavigationProvider, Overlay, PendingScopeContext, Presence, ProgressBar, Radio, RangeSlider, STRETCHED_ABOVE, STRETCHED_CONTROL, SVG_MOTION_CLASSES, SectionHeader, Spacer, Sparkline, Spinner, Stack, StatusDot, SurfaceBoundary, SvgBranch, SvgConnection, SvgFlow, SvgGrid, SvgLobe, SvgMesh, SvgMorph, SvgNode, SvgPulse, SvgRing, SvgShield, SvgStack, Switch, THEME_SCALE_KEYS, TextHighlight, Textarea, ThemeToggle, TimeSlotCell, TraitScopeProvider, TrendIndicator, TypewriterText, Typography, UIThemeDefinition, VStack, atlasFailed, atlasUrlOf, bandEdgeHeight, bandEdgeLayerStyle, bandEdgeMask, bandPadding, beginPending, blit, boxesOf, cn, compareCellValues, coreMessages, createTraitPresence, createTranslate, cssTimeMs, domPassthrough, endPending, entriesFor, evaluateBinding, evaluateBindings, extractRouteParams, findPageByName, findPageByPath, followHref, formatDate, formatDateTime, formatTime, formatValue, getAllPages, getAtlas, getCurrentIconFamily, getDefaultPage, getTraitPresence, guardsHold, isAbsoluteHref, isAtlasAsset, isInertNavStack, isMotionEnabled, isPending, isSpriteSheetAtlas, kebabToPascal, layoutScale, localeMeta, lucideIconKey, matchNavPage, mergeMessages, motionTiming, navLabelsFromItems, newPendingKey, pageEntryLabel, parseCalendarDate, pathMatches, presenceGroup, pressableProps, previousEntry, relabelCurrent, resolveAssetSource, resolveEntryLabels, resolveIconForFamily, resolveLucideByName, rowActivationProps, rowOpenControlProps, sortRows, subRectFor, subscribePending, svgMotionClass, syncNavStack, toDateInputValue, toDateTimeInputValue, useActivePage, useAnimateChanges, useAtlasSliceDataUrl, useContentSurface, useDialogBehavior, useFormatContext, useIconFamily, useInfiniteScroll, useInitPayload, useMediaQuery, useNavStack, useNavigateTo, useNavigation, useNavigationId, useNavigationState, useOnSurface, usePendingAction, usePendingRows, usePendingScopeValue, usePrefersReducedMotion, usePresence, useRenderI18n, useResolvedIcon, useScopeHasPending, useTapReveal, useThemeIconStrokeApplies, useTraitScope, useTraitScopeChain, useTranslate };
+export type { AnimatedGraphicProps, AnimatedRevealProps, AsideProps, AssetSource, AtlasImageAsset, AtlasImageProps, AtlasPanelProps, AvatarProps, AvatarSize, AvatarStatus, BandEdge, BandEdgeColor, BandEdgeLayerStyle, BooleanLabels, BoxBg, BoxMargin, BoxPadding, BoxProps, BoxRounded, BoxShadow, CardLook, CardProps, CardShadow, CenterProps, CheckboxProps, ConditionalContext, ConditionalWrapperProps, ConfettiEffectProps, ContentSurface, DayCellProps, DialogBehaviorOptions, DialogProps, DividerOrientation, DividerProps, DividerVariant, DomPassthrough, FilterPillProps, FilterPillSize, FilterPillVariant, FlipContainerProps, FormatContext, GameIconProps, GraphicAnimation, HStackProps, HighlightType, I18nContextValue, I18nProviderProps, IconFamily, ImageAspect, ImageFit, ImagePosition, ImageProps, ImageRounded, InfiniteScrollOptions, InfiniteScrollResult, InfiniteScrollSentinelProps, LabelProps, LawReference, LawReferenceTooltipProps, LocaleMeta, NavItemDecl, NavItemLabels, NavPageDecl, NavStackApi, NavStackProviderProps, NavStackRouterBridgeProps, NavStackState, NavigationContextValue, NavigationProviderProps, NavigationState, OverlayProps, PendingCrumb, PendingScopeValue, PresenceAnimation, PresenceProps, PresenceResult, PressableProps, ProgressBarColor, ProgressBarProps, ProgressBarType, ProgressBarVariant, RadioProps, RangeSliderProps, RangeSliderSize, RenderI18n, RenderedIcon, RenderedIconProps, RevealAnimation, RevealTrigger, RowActivationProps, SectionHeaderProps, SortDirection, SpacerProps, SpacerSize, SparklineColor, SparklineProps, SpinnerProps, SpinnerSize, SpriteRef, StackAlign, StackDirection, StackGap, StackJustify, StackProps, StatusDotProps, StatusDotSize, StatusDotStatus, SubRect, SupportedLocale, SvgBranchProps, SvgConnectionProps, SvgFlowProps, SvgGridProps, SvgLobeProps, SvgMeshProps, SvgMorphProps, SvgMotion, SvgNodeProps, SvgPulseProps, SvgRingProps, SvgShieldProps, SvgStackProps, SwitchProps, TapRevealOptions, TapRevealResult, TextHighlightProps, TextareaProps, ThemeToggleProps, TimeSlotCellProps, TraitPresence, TraitPresenceState, TraitScope, TraitScopeProviderProps, TranslateFunction, TrendDirection, TrendIndicatorProps, TrendIndicatorSize, TypewriterTextProps, TypographyProps, TypographySize, TypographyVariant, UsePresenceOptions, VStackProps, ValueFormat };