@almadar/ui 5.79.1 → 5.80.0

package/dist/components/core/molecules/WizardNavigation.d.ts

@@ -0,0 +1,61 @@
+/**
+ * WizardNavigation Component
+ *
+ * Navigation buttons for multi-step wizards.
+ * Includes Back, Next, and Complete buttons with proper state handling.
+ *
+ * Emits events via useEventBus for trait integration.
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React from "react";
+import type { EventEmit } from "@almadar/core";
+export interface WizardNavigationProps {
+    /** Current step index (0-based) */
+    currentStep: number;
+    /** Total number of steps */
+    totalSteps: number;
+    /** Whether the current step is valid (enables Next/Complete) */
+    isValid?: boolean;
+    /** Show the Back button */
+    showBack?: boolean;
+    /** Show the Next button */
+    showNext?: boolean;
+    /** Show the Complete button (on last step) */
+    showComplete?: boolean;
+    /** Custom label for Back button */
+    backLabel?: string;
+    /** Custom label for Next button */
+    nextLabel?: string;
+    /** Custom label for Complete button */
+    completeLabel?: string;
+    /** Event to emit on Back click — emits UI:{onBack} with { currentStep, totalSteps } */
+    onBack?: EventEmit<{
+        currentStep: number;
+        totalSteps: number;
+    }>;
+    /** Event to emit on Next click — emits UI:{onNext} with { currentStep, totalSteps } */
+    onNext?: EventEmit<{
+        currentStep: number;
+        totalSteps: number;
+    }>;
+    /** Event to emit on Complete click — emits UI:{onComplete} with { currentStep, totalSteps } */
+    onComplete?: EventEmit<{
+        currentStep: number;
+        totalSteps: number;
+    }>;
+    /** Direct callback for Back (alternative to event) */
+    onBackClick?: () => void;
+    /** Direct callback for Next (alternative to event) */
+    onNextClick?: () => void;
+    /** Direct callback for Complete (alternative to event) */
+    onCompleteClick?: () => void;
+    /** Compact mode (smaller padding) */
+    compact?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+/**
+ * WizardNavigation - Wizard navigation buttons
+ */
+export declare const WizardNavigation: React.FC<WizardNavigationProps>;
+export default WizardNavigation;

package/dist/components/core/molecules/WizardProgress.d.ts

@@ -0,0 +1,45 @@
+/**
+ * WizardProgress Component
+ *
+ * Step progress indicator for multi-step wizards.
+ * Shows current step, completed steps, and allows navigation to completed steps.
+ *
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React from "react";
+import type { EventEmit } from "@almadar/core";
+/**
+ * Step info needed by WizardProgress.
+ * Compatible with WizardContainer's WizardStep (subset of fields).
+ */
+export interface WizardProgressStep {
+    /** Step identifier */
+    id: string;
+    /** Step title */
+    title: string;
+    /** Step description (optional) */
+    description?: string;
+}
+export interface WizardProgressProps {
+    /** Step definitions (compatible with WizardContainer's WizardStep). A string is shorthand for `{ id: str, title: str }`. */
+    steps?: (WizardProgressStep | string)[];
+    /** Current step index (0-based) */
+    currentStep: number;
+    /** Callback when a completed step is clicked */
+    onStepClick?: (stepIndex: number) => void;
+    /** Allow clicking on completed steps to navigate back */
+    allowNavigation?: boolean;
+    /** Compact mode (smaller, no titles) */
+    compact?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Declarative step click event — emits UI:{stepClickEvent} with { stepIndex } */
+    stepClickEvent?: EventEmit<{
+        stepIndex: number;
+    }>;
+}
+/**
+ * WizardProgress - Step progress indicator
+ */
+export declare const WizardProgress: React.FC<WizardProgressProps>;
+export default WizardProgress;

package/dist/components/core/molecules/index.d.ts

@@ -0,0 +1,137 @@
+export { ErrorBoundary, type ErrorBoundaryProps } from './ErrorBoundary';
+export { JsonTreeEditor, type JsonTreeEditorProps } from './JsonTreeEditor';
+export { NodeSlotEditor, type NodeSlotEditorProps } from './NodeSlotEditor';
+export { FileTree, type FileTreeProps, type FileTreeNode } from './FileTree';
+export { FormField, type FormFieldProps } from './FormField';
+export { EmptyState, type EmptyStateProps } from './EmptyState';
+export { LoadingState, type LoadingStateProps } from './LoadingState';
+export { ErrorState, type ErrorStateProps } from './ErrorState';
+export { Skeleton, type SkeletonProps, type SkeletonVariant } from './Skeleton';
+export { Accordion, type AccordionProps, type AccordionItem } from './Accordion';
+export { Alert, type AlertProps, type AlertVariant } from './Alert';
+export { Breadcrumb, type BreadcrumbProps, type BreadcrumbItem } from './Breadcrumb';
+export { ButtonGroup, type ButtonGroupProps } from './ButtonGroup';
+export { FilterGroup, type FilterGroupProps, type FilterDefinition } from './FilterGroup';
+export { Card as ActionCard, type CardProps as ActionCardProps, type CardAction } from './Card';
+export { Container, type ContainerProps } from './Container';
+export { Flex, type FlexProps } from './Flex';
+export { FloatingActionButton, type FloatingActionButtonProps, type FloatingAction } from './FloatingActionButton';
+export { Grid, type GridProps } from './Grid';
+export { InputGroup, type InputGroupProps } from './InputGroup';
+export { Menu, type MenuProps, type MenuItem } from './Menu';
+export { Modal, type ModalProps, type ModalSize } from './Modal';
+export { Pagination, type PaginationProps } from './Pagination';
+export { Popover, type PopoverProps } from './Popover';
+export { Coachmark, useAnchorRect, type CoachmarkProps, type CoachmarkPlacement, type CoachmarkAnchor, } from './Coachmark';
+export { OnboardingSpotlight, type OnboardingSpotlightProps, type SpotlightStep, } from './OnboardingSpotlight';
+export { RelationSelect, type RelationSelectProps, type RelationOption } from './RelationSelect';
+export { SearchInput, type SearchInputProps } from './SearchInput';
+export { SidePanel, type SidePanelProps } from './SidePanel';
+export { SimpleGrid, type SimpleGridProps } from './SimpleGrid';
+export { Tabs, type TabsProps, type TabItem } from './Tabs';
+export { Toast, type ToastProps, type ToastVariant } from './Toast';
+export { Tooltip, type TooltipProps } from './Tooltip';
+export { Drawer, type DrawerProps, type DrawerPosition, type DrawerSize } from './Drawer';
+export { WizardProgress, type WizardProgressProps, type WizardProgressStep } from './WizardProgress';
+export { WizardNavigation, type WizardNavigationProps } from './WizardNavigation';
+export { MarkdownContent, type MarkdownContentProps } from './markdown/MarkdownContent';
+export { CodeBlock, type CodeBlockProps, type CodeLanguage, type CodeViewerMode, type DiffLine, type CodeViewerFile, type CodeViewerAction, toCodeLanguage, } from './markdown/CodeBlock';
+export { QuizBlock, type QuizBlockProps } from './QuizBlock';
+export { ScaledDiagram, type ScaledDiagramProps } from './ScaledDiagram';
+export { CalendarGrid, type CalendarGridProps } from './CalendarGrid';
+export { RepeatableFormSection, type RepeatableFormSectionProps, type RepeatableItem } from './RepeatableFormSection';
+export { ViolationAlert, type ViolationAlertProps, type ViolationRecord } from './ViolationAlert';
+export { FormSectionHeader, type FormSectionHeaderProps } from './FormSectionHeader';
+export { FlipCard, type FlipCardProps } from './FlipCard';
+export { GridPicker, type GridPickerProps, type PickerItem, type GridPickerCellSize, } from './GridPicker';
+export { AssetPicker, type AssetPickerProps } from './AssetPicker';
+export { IconPicker, type IconPickerProps } from './IconPicker';
+export { DateRangePicker, type DateRangePickerProps, type DateRangePickerPreset } from './DateRangePicker';
+export { DateRangeSelector, type DateRangeSelectorProps, type DateRangeSelectorOption } from './DateRangeSelector';
+export { ChartLegend, type ChartLegendProps, type ChartLegendItem } from './ChartLegend';
+export { LineChart, type LineChartProps, type ChartDataPoint } from './LineChart';
+export { ProgressDots, type ProgressDotsProps, type DotState, type DotSize } from './ProgressDots';
+export * from '../../game/2d/molecules/index';
+export { MathCanvas, type MathCanvasProps, type MathCurve, type MathPoint, type MathVector, } from '../../learning/molecules/MathCanvas';
+export { PhysicsCanvas, type PhysicsCanvasProps, type LearningPhysicsBody, type LearningPhysicsConstraint, } from '../../learning/molecules/PhysicsCanvas';
+export { BiologyCanvas, type BiologyCanvasProps, type BiologyNode, type BiologyEdge, } from '../../learning/molecules/BiologyCanvas';
+export { ChemistryCanvas, type ChemistryCanvasProps, type ChemistryAtom, type ChemistryBond, type ChemistryArrow, } from '../../learning/molecules/ChemistryCanvas';
+export { GraphView, type GraphViewProps, type GraphViewNode, type GraphViewEdge } from './GraphView';
+export { MapView, type MapViewProps, type MapMarkerData, type MapRouteData, type MapRouteWaypoint } from './MapView';
+export { NumberStepper, type NumberStepperProps, type NumberStepperSize } from './NumberStepper';
+export { StarRating, type StarRatingProps, type StarRatingSize, type StarRatingPrecision } from './StarRating';
+export { UploadDropZone, type UploadDropZoneProps } from './UploadDropZone';
+export { Lightbox, type LightboxProps, type LightboxImage } from './Lightbox';
+export { DataGrid, type DataGridProps, type DataGridField, type DataGridItemAction } from './DataGrid';
+export { DataList, type DataListProps, type DataListField, type DataListItemAction } from './DataList';
+export { TableView, type TableViewProps, type TableViewColumn } from './TableView';
+export { StatDisplay, type StatDisplayProps } from './StatDisplay';
+export { Meter, type MeterProps, type MeterVariant, type MeterThreshold, type MeterAction } from './Meter';
+export { SwipeableRow, type SwipeableRowProps, type SwipeAction } from './SwipeableRow';
+export { SortableList, type SortableListProps } from './SortableList';
+export { Carousel, type CarouselProps } from './Carousel';
+export { PullToRefresh, type PullToRefreshProps } from './PullToRefresh';
+export { InstallBox, type InstallBoxProps } from '../../marketing/molecules/InstallBox';
+export { FeatureCard, type FeatureCardProps } from '../../marketing/molecules/FeatureCard';
+export { FeatureGrid, type FeatureGridProps } from './FeatureGrid';
+export { CTABanner, type CTABannerProps, type CTABannerBackground } from '../../marketing/molecules/CTABanner';
+export { HeroSection, type HeroSectionProps } from '../../marketing/molecules/HeroSection';
+export { PricingCard, type PricingCardProps } from '../../marketing/molecules/PricingCard';
+export { PricingGrid, type PricingGridProps } from '../../marketing/molecules/PricingGrid';
+export { StatsGrid, type StatsGridProps } from '../../marketing/molecules/StatsGrid';
+export { ServiceCatalog, type ServiceCatalogProps, type ServiceCatalogItem } from '../../marketing/molecules/ServiceCatalog';
+export { CaseStudyCard, type CaseStudyCardProps } from '../../marketing/molecules/CaseStudyCard';
+export { ArticleSection, type ArticleSectionProps } from '../../marketing/molecules/ArticleSection';
+export { SocialProof, type SocialProofProps, type SocialProofItem } from './SocialProof';
+export { StepFlow, type StepFlowProps, type StepItemProps } from '../../marketing/molecules/StepFlow';
+export { SplitSection, type SplitSectionProps } from '../../marketing/molecules/SplitSection';
+export { TagCloud, type TagCloudProps, type TagCloudItem } from '../../marketing/molecules/TagCloud';
+export { TagInput, type TagInputProps } from './TagInput';
+export { CommunityLinks, type CommunityLinksProps } from '../../marketing/molecules/CommunityLinks';
+export { TeamCard, type TeamCardProps } from '../../marketing/molecules/TeamCard';
+export { ShowcaseCard, type ShowcaseCardProps } from '../../marketing/molecules/ShowcaseCard';
+export { GeometricPattern, type GeometricPatternProps } from '../../marketing/molecules/GeometricPattern';
+export { EdgeDecoration, type EdgeDecorationProps, type EdgeVariant, type EdgeSide } from './EdgeDecoration';
+export { VoteStack, type VoteStackProps } from './VoteStack';
+export { LikertScale, type LikertScaleProps, type LikertOption, DEFAULT_LIKERT_OPTIONS } from './LikertScale';
+export { MatrixQuestion, type MatrixQuestionProps, type MatrixRow, type MatrixColumn, DEFAULT_MATRIX_COLUMNS } from './MatrixQuestion';
+export { QrScanner, type QrScannerProps, type QrScanResult } from './QrScanner';
+export { OptionConstraintGroup, type OptionConstraintGroupProps, type OptionConstraintOption, type OptionConstraint } from './OptionConstraintGroup';
+export { PositionedCanvas, type PositionedCanvasProps, type CanvasItemStatus, type CanvasItemShape } from './PositionedCanvas';
+export { RichBlockEditor, type RichBlockEditorProps, type RichBlock, type BlockType } from './RichBlockEditor';
+export { ReplyTree, type ReplyTreeProps } from './ReplyTree';
+export { BranchingLogicBuilder, type BranchingLogicBuilderProps, type BranchingQuestion, type BranchingRule } from './BranchingLogicBuilder';
+export { VersionDiff, type VersionDiffProps, type DiffRevision, type DiffLine as VersionDiffLine, type DiffLineType } from './VersionDiff';
+export { DocBreadcrumb, type DocBreadcrumbProps, type DocBreadcrumbItem } from './DocBreadcrumb';
+export { DocPagination, type DocPaginationProps, type DocPaginationLink } from './DocPagination';
+export { DocSearch, type DocSearchProps, type DocSearchResult } from './DocSearch';
+export { DocSidebar, type DocSidebarProps, type DocSidebarItem } from './DocSidebar';
+export { DocTOC, type DocTOCProps, type DocTOCItem } from './DocTOC';
+export { GradientDivider, type GradientDividerProps } from './GradientDivider';
+export { MarketingFooter, type MarketingFooterProps, type FooterLinkColumn, type FooterLinkItem } from '../../marketing/molecules/MarketingFooter';
+export { PullQuote, type PullQuoteProps } from '../../marketing/molecules/PullQuote';
+export { BehaviorView, type BehaviorViewProps } from '../../avl/molecules/BehaviorView';
+export { ModuleCard, type ModuleCardProps } from '../../avl/molecules/ModuleCard';
+export { PageHeader, type PageHeaderProps, type PageBreadcrumb, } from "./PageHeader";
+export { FormSection, FormLayout, FormActions, type FormSectionProps, type FormLayoutProps, type FormActionsProps, } from "./FormSection";
+export { PropertyInspector, type PropertyInspectorProps } from "./PropertyInspector";
+export { Header, type HeaderProps } from "./Header";
+export { Navigation, type NavigationProps, type NavigationItem, } from "./Navigation";
+export { Section, type SectionProps } from "./Section";
+export { Sidebar, type SidebarProps, type SidebarItem } from "./Sidebar";
+export { Split, type SplitProps } from "./Split";
+export { ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogVariant, } from "./ConfirmDialog";
+export { WizardContainer, type WizardContainerProps, type WizardStep, } from "./WizardContainer";
+export { OrbitalVisualization, type OrbitalVisualizationProps, } from "./OrbitalVisualization";
+export { JazariStateMachine, type JazariStateMachineProps, } from "./JazariStateMachine";
+export { ContentRenderer, type ContentRendererProps, } from "./ContentRenderer";
+export { Chart, type ChartProps, type ChartType, type ChartSeries, } from "./Chart";
+export { SignaturePad, type SignaturePadProps, } from "./SignaturePad";
+export { DocumentViewer, type DocumentViewerProps, type DocumentType, } from "./DocumentViewer";
+export { GraphCanvas, type GraphCanvasProps, type GraphNode, type GraphEdge, } from "./GraphCanvas";
+export { ActivationBlock, type ActivationBlockProps } from './ActivationBlock';
+export { ReflectionBlock, type ReflectionBlockProps } from './ReflectionBlock';
+export { ConnectionBlock, type ConnectionBlockProps } from './ConnectionBlock';
+export { BloomQuizBlock, type BloomQuizBlockProps, type BloomLevel } from './BloomQuizBlock';
+export { parseLessonSegments, type LessonSegment, type LessonUserProgress } from './parseLessonSegments';
+export { parseMarkdownWithCodeBlocks, type MixedSegment } from './lessonSegmentUtils';

package/dist/components/core/molecules/lessonSegmentUtils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Utility for lesson-segment parsing: splits a markdown string into alternating
+ * markdown and fenced-code-block segments. Exported so SegmentRenderer and
+ * BloomQuizBlock can reuse without circular imports.
+ */
+export type MarkdownSegment = {
+    type: 'markdown';
+    content: string;
+};
+export type CodeSegment = {
+    type: 'code';
+    language: string;
+    content: string;
+    runnable?: boolean;
+};
+export type MixedSegment = MarkdownSegment | CodeSegment;
+/** Splits markdown content into markdown and fenced-code-block segments. */
+export declare function parseMarkdownWithCodeBlocks(content: string): MixedSegment[];

package/dist/components/core/molecules/markdown/CodeBlock.d.ts

@@ -0,0 +1,108 @@
+/**
+ * CodeBlock Molecule Component
+ *
+ * A syntax-highlighted code block with copy-to-clipboard functionality.
+ * Preserves scroll position during re-renders.
+ *
+ * Event Contract:
+ * - Emits: UI:COPY_CODE { language, success }
+ */
+import React from 'react';
+import type { UiError } from '../../atoms/types';
+/**
+ * The set of languages with a registered PrismLight grammar (above) plus the
+ * `.orb`/`.lolo` grammars from `@almadar/syntax`. Authoritative: an unregistered
+ * value renders as plain text, so this union mirrors the `registerLanguage`
+ * calls exactly.
+ */
+export declare const CODE_LANGUAGES: readonly ["text", "json", "javascript", "js", "typescript", "ts", "jsx", "tsx", "css", "markdown", "md", "bash", "shell", "sh", "yaml", "yml", "rust", "python", "py", "sql", "diff", "toml", "go", "graphql", "html", "xml", "orb", "lolo"];
+export type CodeLanguage = (typeof CODE_LANGUAGES)[number];
+/**
+ * Narrow an arbitrary string (e.g. a markdown fence info-string) to a
+ * `CodeLanguage`, falling back to `'text'` for any value without a registered
+ * grammar — matching the highlighter's own plain-text fallback.
+ */
+export declare function toCodeLanguage(value: string | undefined): CodeLanguage;
+export type CodeViewerMode = 'code' | 'diff';
+export interface DiffLine {
+    type: 'add' | 'added' | 'remove' | 'removed' | 'context' | 'unchanged';
+    content: string;
+    lineNumber?: number;
+}
+export interface CodeViewerAction {
+    label: string;
+    event?: string;
+    navigatesTo?: string;
+    variant?: 'primary' | 'secondary' | 'ghost';
+}
+export interface CodeViewerFile {
+    label: string;
+    code: string;
+    language?: CodeLanguage;
+}
+export interface CodeBlockProps {
+    /** The code content to display */
+    code?: string;
+    /** Programming language for syntax highlighting */
+    language?: CodeLanguage;
+    /** Show the copy button */
+    showCopyButton?: boolean;
+    /** Show the language badge */
+    showLanguageBadge?: boolean;
+    /** Maximum height before scrolling */
+    maxHeight?: string | number;
+    /** Enable brace-based code folding of multi-line `{}`/`[]` blocks (default: true). */
+    foldable?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /**
+     * When true, render an editable surface that composes a transparent `Textarea`
+     * over a Prism-highlighted overlay. The overlay re-tokenizes on each keystroke
+     * (driven from a local mirror of the textarea value), so users see syntax-highlighted
+     * code while still being able to type. Folding is skipped in editable mode.
+     *
+     * History: GAP-51 first-cut shipped plain (no-highlighting) editable text;
+     * GAP-77 (2026-04-12) added the Prism overlay layer.
+     *
+     * Default: false (existing read-only behavior unchanged).
+     */
+    editable?: boolean;
+    /**
+     * GAP-51: called with the new code on every keystroke when `editable === true`.
+     * Consumers should debounce + parse downstream — `CodeBlock` does not.
+     */
+    onChange?: (code: string) => void;
+    /**
+     * GAP-80: line-level error/warning highlights for editable mode.
+     * Map of 1-based line number → severity. The overlay paints a colored
+     * background on each line: error = red, warning = yellow. Pass undefined
+     * (default) to disable. The consumer is responsible for computing the
+     * path → line map from the schema + validation results.
+     */
+    errorLines?: Map<number, 'error' | 'warning'>;
+    /** Title shown in the toolbar */
+    title?: string;
+    /** Diff or plain-code display mode */
+    mode?: CodeViewerMode;
+    /** Pre-computed diff lines */
+    diff?: readonly DiffLine[];
+    /** Old source text — generates diff when combined with newValue */
+    oldValue?: string;
+    /** New source text — generates diff when combined with oldValue */
+    newValue?: string;
+    /** Show line numbers in code / diff mode */
+    showLineNumbers?: boolean;
+    /** Enable word-wrap in code / diff mode */
+    wordWrap?: boolean;
+    /** Multiple files shown as tabs */
+    files?: readonly CodeViewerFile[];
+    /** Action badges in the toolbar */
+    actions?: readonly CodeViewerAction[];
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: UiError | null;
+    /** Show copy button (viewer alias for showCopyButton) */
+    showCopy?: boolean;
+}
+export declare const CodeBlock: React.NamedExoticComponent<CodeBlockProps>;

package/dist/components/core/molecules/markdown/MarkdownContent.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MarkdownContent Molecule Component
+ *
+ * Renders markdown content with support for GFM (GitHub Flavored Markdown)
+ * and math equations (KaTeX). Handles inline code only — fenced code blocks
+ * should be parsed out and rendered with CodeBlock component.
+ *
+ * Event Contract:
+ * - No events emitted (display-only component)
+ * - entityAware: false
+ *
+ * NOTE: react-markdown's `components` override API requires native HTML
+ * elements — this is the same library-boundary exception as `<iframe>` in
+ * DocumentViewer and `<svg>` in JazariStateMachine/StateMachineView.
+ */
+import React from 'react';
+import 'katex/dist/katex.min.css';
+export interface MarkdownContentProps {
+    /** The markdown content to render */
+    content: string;
+    /** Text direction (defaults to ltr; `ltr` is first so the generated config seeds it) */
+    direction?: 'ltr' | 'rtl';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const MarkdownContent: React.NamedExoticComponent<MarkdownContentProps>;

package/dist/components/core/molecules/markdown/index.d.ts

@@ -0,0 +1,2 @@
+export { MarkdownContent, type MarkdownContentProps } from './MarkdownContent';
+export { CodeBlock, type CodeBlockProps, type CodeLanguage } from './CodeBlock';

package/dist/components/core/molecules/parseLessonSegments.d.ts

@@ -0,0 +1,44 @@
+/**
+ * parseLessonSegments — parses lesson markdown with embedded learning-science
+ * XML-style tags into a typed Segment array.
+ *
+ * Supported tags: <activate>, <connect>, <reflect>, <bloom level="...">,
+ * <question>/<answer>, <visualize type="..." description="..." />.
+ *
+ * Tags may be open (unclosed) — the parser falls back to consuming content
+ * until the next recognised tag, a section heading (`\n\n#`), or end-of-input.
+ */
+import type { BloomLevel } from './BloomQuizBlock';
+import { type MixedSegment } from './lessonSegmentUtils';
+export type InteractiveOrbitalType = 'chart' | 'simulation' | 'math' | 'physics' | 'biology' | 'chemistry' | 'probability';
+export type LessonSegment = MixedSegment | {
+    type: 'quiz';
+    question: string;
+    answer: string;
+} | {
+    type: 'activate';
+    question: string;
+} | {
+    type: 'connect';
+    content: string;
+} | {
+    type: 'reflect';
+    prompt: string;
+} | {
+    type: 'bloom';
+    level: BloomLevel;
+    question: string;
+    answer: string;
+} | {
+    type: 'visualization';
+    visualizationType: InteractiveOrbitalType;
+    description: string;
+};
+/** User progress state passed into SegmentRenderer. */
+export interface LessonUserProgress {
+    activationResponse?: string;
+    reflectionNotes?: string[];
+    bloomAnswered?: Record<number, boolean>;
+}
+/** Parse a lesson string into typed segments. Returns `[]` when input is empty. */
+export declare function parseLessonSegments(lesson: string | undefined): LessonSegment[];

package/dist/components/core/molecules/useDataDnd.d.ts

@@ -0,0 +1,63 @@
+/**
+ * useDataDnd — shared drag-drop machinery for DataList + DataGrid.
+ *
+ * Both primitives expose six identical drag-drop props:
+ *   - dragGroup?:      string   items in this container announce this group when picked up
+ *   - accepts?:        string   this container accepts drops whose dragGroup matches (or "*" for any)
+ *   - sortable?:       boolean  enable in-container reorder
+ *   - dropEvent?:      EventKey bus event on cross-container drop: { id, sourceGroup, targetGroup, newIndex }
+ *   - reorderEvent?:   EventKey bus event on in-container reorder: { id, oldIndex, newIndex }
+ *   - dndItemIdField?: string   row field used as the @dnd-kit draggable id (default "id")
+ *
+ * Architecture
+ *   - A container that opts in via any dnd prop becomes a "zone".
+ *   - The first ancestor zone in the tree creates the DndContext (the "root").
+ *   - Inner zones detect the root via React context and skip creating their own.
+ *   - The root's onDragEnd reads source + target zone metadata off the dragged
+ *     item and the drop target, dispatches to the bus accordingly.
+ */
+import React from 'react';
+import { type UniqueIdentifier } from '@dnd-kit/core';
+import type { EntityRow, EventKey } from '@almadar/core';
+export interface DataDndProps {
+    /**
+     * Event emitted N times per drop (one per item in each affected zone) so
+     * the trait can persist new positions for every item — not just the moved
+     * one. Required for stable sort-by-position because setting only the
+     * dragged item's position creates collisions with the (unchanged) others.
+     * Payload: { id : string, position : number }.
+     */
+    positionEvent?: EventKey;
+    dragGroup?: string;
+    accepts?: string;
+    sortable?: boolean;
+    dropEvent?: EventKey;
+    reorderEvent?: EventKey;
+    dndItemIdField?: string;
+    /**
+     * Mark this container as the DnD root for its subtree. Use on an outer
+     * container (e.g. a data-grid hosting inner data-lists) when the container
+     * itself is NOT a drop target or sortable, but descendant zones need to
+     * share one DndContext so items can be dragged between them. Inner zones
+     * with `accepts` / `dragGroup` / `sortable` detect this root and skip
+     * creating their own DndContext.
+     */
+    dndRoot?: boolean;
+}
+interface UseDataDndArgs extends DataDndProps {
+    items: readonly EntityRow[];
+    layout: 'list' | 'grid';
+}
+interface UseDataDndResult {
+    enabled: boolean;
+    /** True when this container is a sortable zone (own items are draggable). False in dndRoot-only mode. */
+    isZone: boolean;
+    wrapContainer: (children: React.ReactNode) => React.ReactNode;
+    SortableItem: React.FC<{
+        id: UniqueIdentifier;
+        children: React.ReactNode;
+    }>;
+    orderedItems: readonly EntityRow[];
+}
+export declare function useDataDnd(args: UseDataDndArgs): UseDataDndResult;
+export {};

package/dist/components/core/organisms/CardGrid.d.ts

@@ -0,0 +1,84 @@
+/**
+ * CardGrid Component
+ *
+ * A dumb, responsive grid specifically designed for card layouts.
+ * Uses CSS Grid auto-fit for automatic responsive columns.
+ *
+ * Data comes exclusively from the `entity` prop (injected by the runtime).
+ * All user interactions emit events via useEventBus. Never manages internal state
+ * for pagination, filtering, or search. All state is owned by the trait state machine.
+ */
+import React from 'react';
+import type { EventKey, EventPayload } from "@almadar/core";
+import type { DisplayStateProps } from './types';
+import type { EntityRow } from '@almadar/core';
+export type CardGridGap = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Action configuration for card items (schema-driven)
+ */
+export interface CardItemAction {
+    /** Action button label */
+    label: string;
+    /** Event to dispatch on click (schema metadata) */
+    event?: EventKey;
+    /** Navigation URL - supports template interpolation like "/products/{{row.id}}" */
+    navigatesTo?: string;
+    /** Callback on click */
+    onClick?: (item: EventPayload) => void;
+    /** Action used by generated code - alternative to event */
+    action?: EventKey;
+    /** Action placement - accepts string for compatibility with generated code */
+    placement?: 'card' | 'footer' | 'row' | string;
+    /** Button variant - accepts string for compatibility with generated code */
+    variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | string;
+}
+/**
+ * Field definition - can be a simple string or object with key/header or name/label
+ */
+export type FieldDef = string | {
+    key?: string;
+    header?: string;
+    name?: string;
+    label?: string;
+};
+export interface CardGridProps extends DisplayStateProps {
+    /** Entity data (single record or collection). */
+    entity?: EntityRow | readonly EntityRow[];
+    /** Minimum width of each card (default: 280px) */
+    minCardWidth?: number;
+    /** Maximum number of columns */
+    maxCols?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Gap between cards */
+    gap?: CardGridGap;
+    /** Align cards vertically in their cells */
+    alignItems?: 'start' | 'center' | 'end' | 'stretch';
+    /** Children elements (cards) - optional when using entity prop */
+    children?: React.ReactNode;
+    /** Fields to display - required for schema-driven rendering */
+    fields: readonly FieldDef[];
+    /** Alias for fields - backwards compatibility */
+    fieldNames?: readonly string[];
+    /** Alias for fields - backwards compatibility */
+    columns?: readonly FieldDef[];
+    /** Actions for each card item (schema-driven) */
+    itemActions?: readonly CardItemAction[];
+    /** Show total count in pagination */
+    showTotal?: boolean;
+    /** Show avatar/image field on cards */
+    showAvatar?: boolean;
+    /** Visual variant for the card grid */
+    variant?: string;
+    /** Entity field name containing an image URL to display as card thumbnail */
+    imageField?: string;
+}
+/**
+ * CardGrid - Responsive card collection layout
+ *
+ * Can be used in two ways:
+ * 1. With children: <CardGrid><Card>...</Card></CardGrid>
+ * 2. With entity data: <CardGrid entity={tasks} fields={['title', 'status']} />
+ *
+ * All data comes from the `entity` prop. Pagination display hints come from
+ * `page`, `pageSize`, and `totalCount` props (set by the trait via render-ui).
+ */
+export declare const CardGrid: React.FC<CardGridProps>;

package/dist/components/core/organisms/ChatBar.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ChatBar Organism
+ *
+ * The always-visible bottom chat bar. A single-row input surface for talking
+ * to the agent: status icon, optional context badge, text input, and a
+ * status-driven action button (Send / Pause+Stop / Resume / Retry).
+ *
+ * The agent's activity stream lives in the dedicated Trace tab (see
+ * SubagentTracePanel). ChatBar emits generic EventBus events
+ * (`UI:CHAT_SEND`, `UI:ELEMENT_SELECTED`, plus the declarative `UI:*` actions
+ * the Button atom raises) — it owns no app-specific state.
+ */
+import React from 'react';
+import type { DisplayStateProps } from './types';
+export type ChatBarStatus = 'idle' | 'running' | 'paused' | 'complete' | 'error';
+export interface ChatBarProps extends DisplayStateProps {
+    /** Pipeline status */
+    status?: ChatBarStatus;
+    /** Currently active gate label, e.g. "Gate 2: State machines" */
+    activeGate?: string;
+    /** JEPA validity probability 0-1 */
+    jepaValidity?: number;
+    /** Input placeholder text */
+    placeholder?: string;
+    /** Agent context description */
+    context?: string;
+}
+export declare function ChatBar({ status, activeGate, jepaValidity, placeholder, context, className, }: ChatBarProps): React.ReactElement;
+export declare namespace ChatBar {
+    var displayName: string;
+}