@almadar/ui 2.61.1 → 3.0.1

package/dist/components/index.cjs

@@ -33,6 +33,7 @@ var langDiff = require('react-syntax-highlighter/dist/esm/languages/prism/diff.j
 var langToml = require('react-syntax-highlighter/dist/esm/languages/prism/toml.js');
 var langGo = require('react-syntax-highlighter/dist/esm/languages/prism/go.js');
 var langGraphql = require('react-syntax-highlighter/dist/esm/languages/prism/graphql.js');
+var core = require('@almadar/core');
 var context = require('@almadar/ui/context');
 var reactQuery = require('@tanstack/react-query');
 
@@ -8943,9 +8944,9 @@ var init_ScaledDiagram = __esm({
   }
 });
 
-// node_modules/.pnpm/katex@0.16.33/node_modules/katex/dist/katex.min.css
+// node_modules/.pnpm/katex@0.16.45/node_modules/katex/dist/katex.min.css
 var init_katex_min = __esm({
-  "node_modules/.pnpm/katex@0.16.33/node_modules/katex/dist/katex.min.css"() {
+  "node_modules/.pnpm/katex@0.16.45/node_modules/katex/dist/katex.min.css"() {
   }
 });
 exports.MarkdownContent = void 0;
@@ -10994,7 +10995,9 @@ function extractTrait(schema, trait, traitIndex) {
   for (const orbital of schema.orbitals) {
     const traits2 = orbital.traits ?? [];
     if (traitIndex < traits2.length) {
-      return traits2[traitIndex];
+      const traitRef = traits2[traitIndex];
+      if (core.isInlineTrait(traitRef)) return traitRef;
+      return null;
     }
   }
   return null;
@@ -11002,8 +11005,10 @@ function extractTrait(schema, trait, traitIndex) {
 function extractEntityFields(schema) {
   if (!schema?.orbitals?.length) return [];
   const entity = schema.orbitals[0].entity;
-  if (!entity?.fields) return [];
-  return entity.fields.map((f3) => f3.name);
+  if (!entity || typeof entity !== "object" || !("fields" in entity)) return [];
+  const inlineEntity = entity;
+  if (!inlineEntity.fields) return [];
+  return inlineEntity.fields.map((f3) => f3.name);
 }
 function toStateMachineDefinition(sm) {
   return {
@@ -11298,12 +11303,18 @@ var init_ContentRenderer = __esm({
             );
           case "orbital": {
             const parsed = segment.schema;
+            const inlineTrait = {
+              name: "inline",
+              scope: "instance",
+              stateMachine: parsed
+            };
             const schema = Array.isArray(parsed.orbitals) ? parsed : {
+              name: "inline",
               orbitals: [{
-                traits: [{
-                  name: "inline",
-                  stateMachine: parsed
-                }]
+                name: "inline",
+                entity: { name: "inline", fields: [] },
+                traits: [inlineTrait],
+                pages: []
               }]
             };
             return /* @__PURE__ */ jsxRuntime.jsxs(exports.VStack, { gap: "sm", children: [
@@ -37491,19 +37502,15 @@ function SlotContentRenderer({
   patternPath
 }) {
   const entityProp = content.props.entity;
-  const entityType = typeof entityProp === "string" ? entityProp : "";
-  const storeData = providers.useEntityRef(entityType);
-  React110__namespace.default.useEffect(() => {
-    if (!entityType) return;
-    if (typeof process !== "undefined" && process.env && process.env.NODE_ENV === "production") return;
-    if (STRING_ENTITY_WARNED.has(entityType)) return;
-    STRING_ENTITY_WARNED.add(entityType);
-    console.warn(
-      `[UISlotRenderer] String-entity binding '${entityType}' is deprecated. Pass 'items' or 'entity' as a value prop resolved from @payload.data. See docs/Almadar_Entity_V2_Plan.md \xA75.`
-    );
-  }, [entityType]);
+  if (typeof entityProp === "string" && entityProp.length > 0) {
+    if (typeof process !== "undefined" && process.env && process.env.NODE_ENV !== "production") {
+      throw new Error(
+        `[UISlotRenderer] Received string 'entity: "${entityProp}"' at render time. The V2 flow requires pre-resolved data; declare a fetch success listener and pass 'entity: @payload.data'. See docs/Almadar_Entity_V2_Plan.md \xA76.`
+      );
+    }
+  }
   const schemaCtx = useEntitySchemaOptional();
-  const entityDef = entityType && schemaCtx ? schemaCtx.entities.get(entityType) : void 0;
+  const entityDef = typeof entityProp === "string" && entityProp.length > 0 && schemaCtx ? schemaCtx.entities.get(entityProp) : void 0;
   const PatternComponent = getComponentForPattern(content.pattern);
   if (PatternComponent) {
     const childrenConfig = content.props.children;
@@ -37512,12 +37519,7 @@ function SlotContentRenderer({
     const renderedChildren = hasChildren ? renderPatternChildren(childrenConfig, onDismiss, content.id, myPath) : void 0;
     const { children: _childrenConfig, ...restProps } = content.props;
     const renderedProps = renderPatternProps(restProps, onDismiss);
-    let finalProps;
-    if (entityType) {
-      finalProps = { ...renderedProps, entity: storeData };
-    } else {
-      finalProps = renderedProps;
-    }
+    const finalProps = renderedProps;
     const resolvedItems = Array.isArray(
       finalProps.entity
     ) ? finalProps.entity : null;
@@ -37531,9 +37533,6 @@ function SlotContentRenderer({
     const isFormPattern = FORM_PATTERNS.has(content.pattern) || content.pattern.includes("form");
     if (isFormPattern && entityDef && Array.isArray(finalProps.fields)) {
       finalProps.fields = enrichFormFields(finalProps.fields, entityDef);
-      if (finalProps.mode === "edit" && !finalProps.initialData && storeData.length > 0) {
-        finalProps.initialData = storeData[0];
-      }
     }
     const acceptsChildren = PATTERNS_WITH_CHILDREN.has(content.pattern);
     return /* @__PURE__ */ jsxRuntime.jsx(
@@ -37627,7 +37626,7 @@ function UISlotRenderer({
   }
   return wrapped;
 }
-var TRAIT_BINDING_RE, STRING_ENTITY_WARNED, SuspenseConfigContext, SlotContainedContext, SLOT_SKELETON_MAP, FORM_PATTERNS, PATTERNS_WITH_CHILDREN;
+var TRAIT_BINDING_RE, SuspenseConfigContext, SlotContainedContext, SLOT_SKELETON_MAP, FORM_PATTERNS, PATTERNS_WITH_CHILDREN;
 var init_UISlotRenderer = __esm({
   "components/organisms/UISlotRenderer.tsx"() {
     "use client";
@@ -37644,7 +37643,6 @@ var init_UISlotRenderer = __esm({
     init_TraitFrame();
     init_component_registry_generated();
     TRAIT_BINDING_RE = /^@trait\.([A-Z][A-Za-z0-9]*)$/;
-    STRING_ENTITY_WARNED = /* @__PURE__ */ new Set();
     SuspenseConfigContext = React110.createContext({ enabled: false });
     SlotContainedContext = React110.createContext(false);
     SuspenseConfigProvider.displayName = "SuspenseConfigProvider";
@@ -41111,8 +41109,8 @@ var API_BASE_URL = typeof process !== "undefined" && process.env?.VITE_API_URL ?
 var ApiError = class extends Error {
   constructor(status, statusText, message) {
     super(message || `API Error: ${status} ${statusText}`);
-    this.status = status;
-    this.statusText = statusText;
+    __publicField(this, "status", status);
+    __publicField(this, "statusText", statusText);
     this.name = "ApiError";
   }
 };

package/dist/components/index.css

@@ -1,4 +1,4 @@
-/* node_modules/.pnpm/katex@0.16.33/node_modules/katex/dist/katex.min.css */
+/* node_modules/.pnpm/katex@0.16.45/node_modules/katex/dist/katex.min.css */
 @font-face {
   font-display: block;
   font-family: KaTeX_AMS;
@@ -205,6 +205,7 @@
     Times New Roman,
     serif;
   line-height: 1.2;
+  position: relative;
   text-indent: 0;
   text-rendering: auto;
 }
@@ -213,7 +214,7 @@
   border-color: currentColor;
 }
 .katex .katex-version:after {
-  content: "0.16.33";
+  content: "0.16.45";
 }
 .katex .katex-mathml {
   clip: rect(1px, 1px, 1px, 1px);
@@ -389,6 +390,10 @@
 .katex .mspace {
   display: inline-block;
 }
+.katex .smash {
+  display: inline;
+  line-height: 0;
+}
 .katex .clap,
 .katex .llap,
 .katex .rlap {

package/dist/components/index.js

@@ -2,7 +2,7 @@ import { clsx } from 'clsx';
 import { twMerge } from 'tailwind-merge';
 import * as React110 from 'react';
 import React110__default, { createContext, useContext, useRef, useEffect, useCallback, useState, Suspense, useMemo, lazy, useSyncExternalStore, useLayoutEffect, useId } from 'react';
-import { EventBusContext, useEntityRef, SelectionContext } from '@almadar/ui/providers';
+import { EventBusContext, SelectionContext } from '@almadar/ui/providers';
 import * as LucideIcons from 'lucide-react';
 import { Loader2, X, AlertTriangle, Info, AlertCircle, CheckCircle, ChevronDown, List, Printer, ChevronRight, ChevronLeft, XCircle, Wrench, RotateCcw, Send, Code, FileText, WrapText, Check, Copy, Zap, Sword, Move, Heart, Shield, Trash2, Settings, Menu as Menu$1, Search, Bell, LogOut, ChevronUp, MoreHorizontal, Bug, ZoomOut, ZoomIn, Download, Pause, Play, Package, Calendar, Pencil, Eye, Image as Image$1, Upload, ArrowRight, ArrowLeft, Eraser, SkipForward, TrendingUp, TrendingDown, Minus, ArrowUp, ArrowDown, MoreVertical, Circle, Clock, CheckCircle2, HelpCircle, FileQuestion, Inbox, Plus, User, Filter, Star, FileWarning, Tag, DollarSign, Sun, Moon } from 'lucide-react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
@@ -33,6 +33,7 @@ import langDiff from 'react-syntax-highlighter/dist/esm/languages/prism/diff.js'
 import langToml from 'react-syntax-highlighter/dist/esm/languages/prism/toml.js';
 import langGo from 'react-syntax-highlighter/dist/esm/languages/prism/go.js';
 import langGraphql from 'react-syntax-highlighter/dist/esm/languages/prism/graphql.js';
+import { isInlineTrait } from '@almadar/core';
 import { useUISlots } from '@almadar/ui/context';
 import { useQueryClient, useMutation, useQuery } from '@tanstack/react-query';
 
@@ -8898,9 +8899,9 @@ var init_ScaledDiagram = __esm({
   }
 });
 
-// node_modules/.pnpm/katex@0.16.33/node_modules/katex/dist/katex.min.css
+// node_modules/.pnpm/katex@0.16.45/node_modules/katex/dist/katex.min.css
 var init_katex_min = __esm({
-  "node_modules/.pnpm/katex@0.16.33/node_modules/katex/dist/katex.min.css"() {
+  "node_modules/.pnpm/katex@0.16.45/node_modules/katex/dist/katex.min.css"() {
   }
 });
 var MarkdownContent;
@@ -10949,7 +10950,9 @@ function extractTrait(schema, trait, traitIndex) {
   for (const orbital of schema.orbitals) {
     const traits2 = orbital.traits ?? [];
     if (traitIndex < traits2.length) {
-      return traits2[traitIndex];
+      const traitRef = traits2[traitIndex];
+      if (isInlineTrait(traitRef)) return traitRef;
+      return null;
     }
   }
   return null;
@@ -10957,8 +10960,10 @@ function extractTrait(schema, trait, traitIndex) {
 function extractEntityFields(schema) {
   if (!schema?.orbitals?.length) return [];
   const entity = schema.orbitals[0].entity;
-  if (!entity?.fields) return [];
-  return entity.fields.map((f3) => f3.name);
+  if (!entity || typeof entity !== "object" || !("fields" in entity)) return [];
+  const inlineEntity = entity;
+  if (!inlineEntity.fields) return [];
+  return inlineEntity.fields.map((f3) => f3.name);
 }
 function toStateMachineDefinition(sm) {
   return {
@@ -11253,12 +11258,18 @@ var init_ContentRenderer = __esm({
             );
           case "orbital": {
             const parsed = segment.schema;
+            const inlineTrait = {
+              name: "inline",
+              scope: "instance",
+              stateMachine: parsed
+            };
             const schema = Array.isArray(parsed.orbitals) ? parsed : {
+              name: "inline",
               orbitals: [{
-                traits: [{
-                  name: "inline",
-                  stateMachine: parsed
-                }]
+                name: "inline",
+                entity: { name: "inline", fields: [] },
+                traits: [inlineTrait],
+                pages: []
               }]
             };
             return /* @__PURE__ */ jsxs(VStack, { gap: "sm", children: [
@@ -37446,19 +37457,15 @@ function SlotContentRenderer({
   patternPath
 }) {
   const entityProp = content.props.entity;
-  const entityType = typeof entityProp === "string" ? entityProp : "";
-  const storeData = useEntityRef(entityType);
-  React110__default.useEffect(() => {
-    if (!entityType) return;
-    if (typeof process !== "undefined" && process.env && process.env.NODE_ENV === "production") return;
-    if (STRING_ENTITY_WARNED.has(entityType)) return;
-    STRING_ENTITY_WARNED.add(entityType);
-    console.warn(
-      `[UISlotRenderer] String-entity binding '${entityType}' is deprecated. Pass 'items' or 'entity' as a value prop resolved from @payload.data. See docs/Almadar_Entity_V2_Plan.md \xA75.`
-    );
-  }, [entityType]);
+  if (typeof entityProp === "string" && entityProp.length > 0) {
+    if (typeof process !== "undefined" && process.env && process.env.NODE_ENV !== "production") {
+      throw new Error(
+        `[UISlotRenderer] Received string 'entity: "${entityProp}"' at render time. The V2 flow requires pre-resolved data; declare a fetch success listener and pass 'entity: @payload.data'. See docs/Almadar_Entity_V2_Plan.md \xA76.`
+      );
+    }
+  }
   const schemaCtx = useEntitySchemaOptional();
-  const entityDef = entityType && schemaCtx ? schemaCtx.entities.get(entityType) : void 0;
+  const entityDef = typeof entityProp === "string" && entityProp.length > 0 && schemaCtx ? schemaCtx.entities.get(entityProp) : void 0;
   const PatternComponent = getComponentForPattern(content.pattern);
   if (PatternComponent) {
     const childrenConfig = content.props.children;
@@ -37467,12 +37474,7 @@ function SlotContentRenderer({
     const renderedChildren = hasChildren ? renderPatternChildren(childrenConfig, onDismiss, content.id, myPath) : void 0;
     const { children: _childrenConfig, ...restProps } = content.props;
     const renderedProps = renderPatternProps(restProps, onDismiss);
-    let finalProps;
-    if (entityType) {
-      finalProps = { ...renderedProps, entity: storeData };
-    } else {
-      finalProps = renderedProps;
-    }
+    const finalProps = renderedProps;
     const resolvedItems = Array.isArray(
       finalProps.entity
     ) ? finalProps.entity : null;
@@ -37486,9 +37488,6 @@ function SlotContentRenderer({
     const isFormPattern = FORM_PATTERNS.has(content.pattern) || content.pattern.includes("form");
     if (isFormPattern && entityDef && Array.isArray(finalProps.fields)) {
       finalProps.fields = enrichFormFields(finalProps.fields, entityDef);
-      if (finalProps.mode === "edit" && !finalProps.initialData && storeData.length > 0) {
-        finalProps.initialData = storeData[0];
-      }
     }
     const acceptsChildren = PATTERNS_WITH_CHILDREN.has(content.pattern);
     return /* @__PURE__ */ jsx(
@@ -37582,7 +37581,7 @@ function UISlotRenderer({
   }
   return wrapped;
 }
-var TRAIT_BINDING_RE, STRING_ENTITY_WARNED, SuspenseConfigContext, SlotContainedContext, SLOT_SKELETON_MAP, FORM_PATTERNS, PATTERNS_WITH_CHILDREN;
+var TRAIT_BINDING_RE, SuspenseConfigContext, SlotContainedContext, SLOT_SKELETON_MAP, FORM_PATTERNS, PATTERNS_WITH_CHILDREN;
 var init_UISlotRenderer = __esm({
   "components/organisms/UISlotRenderer.tsx"() {
     "use client";
@@ -37599,7 +37598,6 @@ var init_UISlotRenderer = __esm({
     init_TraitFrame();
     init_component_registry_generated();
     TRAIT_BINDING_RE = /^@trait\.([A-Z][A-Za-z0-9]*)$/;
-    STRING_ENTITY_WARNED = /* @__PURE__ */ new Set();
     SuspenseConfigContext = createContext({ enabled: false });
     SlotContainedContext = createContext(false);
     SuspenseConfigProvider.displayName = "SuspenseConfigProvider";
@@ -41066,8 +41064,8 @@ var API_BASE_URL = typeof process !== "undefined" && process.env?.VITE_API_URL ?
 var ApiError = class extends Error {
   constructor(status, statusText, message) {
     super(message || `API Error: ${status} ${statusText}`);
-    this.status = status;
-    this.statusText = statusText;
+    __publicField(this, "status", status);
+    __publicField(this, "statusText", statusText);
     this.name = "ApiError";
   }
 };

package/dist/components/organisms/DataTable.d.ts

@@ -1,6 +1,7 @@
 import React from "react";
 import { LucideIcon } from "lucide-react";
 import { EntityDisplayProps } from "./types";
+import type { EntityRow } from "@almadar/core";
 export interface Column<T> {
     key: keyof T | string;
     header: string;
@@ -20,7 +21,7 @@ export interface RowAction<T> {
     show?: (row: T) => boolean;
     event?: string;
 }
-export interface DataTableProps<T extends {
+export interface DataTableProps<T extends EntityRow & {
     id: string | number;
 }> extends EntityDisplayProps<T> {
     /** Fields to display - accepts string[] or Column[] for unified interface. Alias for columns */
@@ -59,7 +60,7 @@ export interface DataTableProps<T extends {
     /** Show total count in pagination */
     showTotal?: boolean;
 }
-export declare function DataTable<T extends {
+export declare function DataTable<T extends EntityRow & {
     id: string | number;
 }>({ fields, columns, entity, itemActions, isLoading, error, emptyIcon, emptyTitle, emptyDescription, emptyAction, selectable, selectedIds, sortBy, sortDirection, searchable, searchValue, searchPlaceholder, page, pageSize, totalCount, rowActions: externalRowActions, bulkActions, headerActions, showTotal, className, }: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;
 export declare namespace DataTable {

package/dist/components/organisms/JazariStateMachine.d.ts

@@ -8,43 +8,16 @@
  * 4. Renders gear-shaped state nodes via the renderStateNode prop
  */
 import React from 'react';
-import type { EntityDisplayProps } from './types';
-interface SmState {
-    name: string;
-    isInitial?: boolean;
-    isTerminal?: boolean;
-    isFinal?: boolean;
-}
-interface SmTransition {
-    from: string;
-    to: string;
-    event: string;
-    guard?: unknown;
-    effects?: unknown[];
-}
-interface SmStateMachine {
-    states: SmState[];
-    transitions: SmTransition[];
-}
-interface SmTrait {
-    name: string;
-    stateMachine?: SmStateMachine;
-    linkedEntity?: string;
-}
-interface SmEntity {
-    name: string;
-    fields?: Array<{
-        name: string;
-    }>;
-}
-interface SmOrbital {
-    entity?: SmEntity;
-    traits?: SmTrait[];
-}
-interface SmSchema {
-    orbitals?: SmOrbital[];
-}
-export interface JazariStateMachineProps extends EntityDisplayProps<SmSchema> {
+import type { OrbitalSchema, Trait as CoreTrait } from '@almadar/core';
+type SmTrait = CoreTrait;
+type SmSchema = OrbitalSchema;
+export interface JazariStateMachineProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
     /** Full schema — extracts first trait's state machine */
     schema?: SmSchema;
     /** Or pass a single trait directly */

package/dist/components/organisms/MasterDetail.d.ts

@@ -10,9 +10,10 @@
  */
 import React from 'react';
 import type { EntityDisplayProps } from './types';
-export interface MasterDetailProps<T extends {
+import type { EntityRow } from '@almadar/core';
+export interface MasterDetailProps<T extends EntityRow & {
     id: string | number;
-} = {
+} = EntityRow & {
     id: string | number;
 }> extends EntityDisplayProps<T> {
     /** Fields to show in the master list (maps to DataTable columns) */
@@ -22,7 +23,7 @@ export interface MasterDetailProps<T extends {
     /** Loading state (alias for isLoading) */
     loading?: boolean;
 }
-export declare function MasterDetail<T extends {
+export declare function MasterDetail<T extends EntityRow & {
     id: string | number;
 }>({ entity, masterFields, detailFields: _detailFields, // Captured but not used here - detail handled separately
 loading: externalLoading, isLoading: externalIsLoading, error: externalError, className, ...rest }: MasterDetailProps<T>): React.ReactElement;

package/dist/components/organisms/MediaGallery.d.ts

@@ -12,7 +12,8 @@
  */
 import React from "react";
 import type { EntityDisplayProps } from "./types";
-export interface MediaItem {
+import type { EntityRow } from "@almadar/core";
+export type MediaItem = EntityRow & {
     /** Unique identifier */
     id: string;
     /** Media URL */
@@ -27,7 +28,7 @@ export interface MediaItem {
     caption?: string;
     /** File size */
     fileSize?: string;
-}
+};
 export interface MediaGalleryAction {
     label: string;
     event?: string;

package/dist/components/organisms/Sidebar.d.ts

@@ -11,7 +11,6 @@
  */
 import React from 'react';
 import type { LucideIcon } from 'lucide-react';
-import type { EntityDisplayProps } from './types';
 export interface SidebarItem {
     /** Item ID */
     id: string;
@@ -32,7 +31,13 @@ export interface SidebarItem {
     /** Sub-items (for nested navigation) */
     subItems?: SidebarItem[];
 }
-export interface SidebarProps extends EntityDisplayProps<SidebarItem> {
+export interface SidebarProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
     /** Logo/Brand content - can be a ReactNode or logo config */
     logo?: React.ReactNode;
     /** Logo image source */

package/dist/components/organisms/StateMachineView.d.ts

@@ -16,7 +16,6 @@
  */
 import React from 'react';
 import type { DomLayoutData, DomStateNode, DomTransitionLabel, VisualizerConfig } from '../../lib/visualizer/index.js';
-import type { EntityDisplayProps } from './types';
 /** Bundled transitions between same from→to states */
 export interface TransitionBundle {
     id: string;
@@ -26,7 +25,13 @@ export interface TransitionBundle {
     isBidirectional: boolean;
     isReverse: boolean;
 }
-export interface StateMachineViewProps extends EntityDisplayProps<DomLayoutData> {
+export interface StateMachineViewProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
     layoutData: DomLayoutData;
     /** Custom state node renderer — when provided, replaces the default circle nodes */
     renderStateNode?: (state: DomStateNode, config: VisualizerConfig) => React.ReactNode;

package/dist/components/organisms/Table.d.ts

@@ -10,6 +10,7 @@
 import React from "react";
 import { MenuItem } from "../molecules/Menu";
 import type { EntityDisplayProps } from "./types";
+import type { EntityRow } from "@almadar/core";
 export type SortDirection = "asc" | "desc";
 export interface TableColumn<T = any> {
     /**
@@ -34,7 +35,7 @@ export interface TableColumn<T = any> {
      */
     width?: string;
 }
-export interface TableProps<T = Record<string, unknown>> extends EntityDisplayProps<T> {
+export interface TableProps<T extends EntityRow = EntityRow> extends EntityDisplayProps<T> {
     /**
      * Table columns
      */

package/dist/components/organisms/Timeline.d.ts

@@ -11,7 +11,7 @@
  * - className for external styling
  */
 import React from "react";
-import type { EntityDisplayProps } from "./types";
+import type { EntityRow } from "@almadar/core";
 import type { LucideIcon } from "lucide-react";
 export type TimelineItemStatus = "complete" | "active" | "pending" | "error";
 export interface TimelineItem {
@@ -36,7 +36,20 @@ export interface TimelineAction {
     navigatesTo?: string;
     variant?: "primary" | "secondary" | "ghost";
 }
-export interface TimelineProps extends EntityDisplayProps<TimelineItem> {
+export interface TimelineProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /**
+     * Schema entity data typed against @almadar/core's EntityRow. Items from
+     * `entity` are normalised into `items` when `items` is omitted. UI-specific
+     * TimelineItem fields (`icon`, callbacks) cannot round-trip through the
+     * event bus, so decorative stories that need them pass `items` directly.
+     */
+    entity?: EntityRow | readonly EntityRow[];
     /** Timeline title */
     title?: string;
     /** Timeline items */

package/dist/components/organisms/book/BookChapterView.d.ts

@@ -8,9 +8,10 @@
  * - Delegates to ContentRenderer children
  */
 import React from 'react';
-import type { EntityDisplayProps } from '../types';
 import type { BookChapter } from './types';
-export interface BookChapterViewProps extends EntityDisplayProps<BookChapter> {
+export interface BookChapterViewProps {
+    /** Additional CSS classes */
+    className?: string;
     chapter: BookChapter;
     direction?: 'rtl' | 'ltr';
 }

package/dist/components/organisms/book/BookCoverPage.d.ts

@@ -8,9 +8,9 @@
  * - Emits: UI:BOOK_START
  */
 import React from 'react';
-import type { EntityDisplayProps } from '../types';
-import type { BookData } from './types';
-export interface BookCoverPageProps extends EntityDisplayProps<BookData> {
+export interface BookCoverPageProps {
+    /** Additional CSS classes */
+    className?: string;
     title: string;
     subtitle?: string;
     author?: string;

package/dist/components/organisms/book/BookNavBar.d.ts

@@ -8,9 +8,9 @@
  * - Emits: UI:BOOK_PAGE_PREV, UI:BOOK_PAGE_NEXT, UI:BOOK_PRINT, UI:BOOK_SHOW_TOC
  */
 import React from 'react';
-import type { EntityDisplayProps } from '../types';
-import type { BookData } from './types';
-export interface BookNavBarProps extends EntityDisplayProps<BookData> {
+export interface BookNavBarProps {
+    /** Additional CSS classes */
+    className?: string;
     currentPage: number;
     totalPages: number;
     chapterTitle?: string;

package/dist/components/organisms/book/BookTableOfContents.d.ts

@@ -8,9 +8,10 @@
  * - Emits: UI:BOOK_NAVIGATE { chapterId }
  */
 import React from 'react';
-import type { EntityDisplayProps } from '../types';
 import type { BookPart } from './types';
-export interface BookTableOfContentsProps extends EntityDisplayProps<BookPart> {
+export interface BookTableOfContentsProps {
+    /** Additional CSS classes */
+    className?: string;
     parts: BookPart[];
     currentChapterId?: string;
     direction?: 'rtl' | 'ltr';

package/dist/components/organisms/book/BookViewer.d.ts

@@ -18,8 +18,8 @@
  */
 import React from 'react';
 import type { EntityDisplayProps } from '../types';
-import type { BookData, BookFieldMap } from './types';
-export interface BookViewerProps extends EntityDisplayProps<BookData | Record<string, unknown>> {
+import type { BookFieldMap } from './types';
+export interface BookViewerProps extends EntityDisplayProps {
     /** Initial page index (default: 0 = cover) */
     initialPage?: number;
     /** Field name translation map — a BookFieldMap object or locale key ("ar") */

package/dist/components/organisms/book/types.d.ts

@@ -1,10 +1,15 @@
 /**
  * BookViewer shared types
  *
- * Field names are canonical English. When entity data arrives from a
- * schema with non-English field names (e.g. Arabic .orb), a field map
- * translates them before passing to BookViewer. See `mapBookData()`.
+ * `BookData` / `BookPart` / `BookChapter` are rendering-layer content-model
+ * types: they carry a typed `OrbitalSchema` (via `@almadar/core`) for the
+ * embedded orbital-diagram feature, which is richer than `FieldValue` and
+ * therefore cannot satisfy `EntityRow`'s primitive-field constraint. The
+ * BookViewer organism's prop surface IS `EntityRow` — raw schema data bound
+ * from `@payload.data`; `mapBookData()` normalises those records (English or
+ * localised) into the typed `BookData` representation at render time.
  */
+import type { OrbitalSchema } from '@almadar/core';
 export interface BookData {
     title: string;
     subtitle?: string;
@@ -21,7 +26,7 @@ export interface BookChapter {
     id: string;
     title: string;
     content: string;
-    orbitalSchema?: unknown;
+    orbitalSchema?: OrbitalSchema;
 }
 /**
  * Maps raw entity field names to canonical BookData field names.