@almadar/ui 3.9.1 → 4.0.1

package/dist/runtime/ui/SlotsContext.d.ts

@@ -2,50 +2,88 @@
  * SlotsContext - React state-based UI slot management
  *
  * Replaces the UIEnvironment observable store with plain React state.
- * No stacking logic, no priority system, no source tracking for arbitration.
+ * No stacking logic, no priority system.
  *
- * A transition's effects produce the COMPLETE content for each slot.
- * The runtime collects all render-ui effects from a transition, groups by slot,
- * and sets each slot's patterns array in one atomic operation.
+ * A transition's effects produce the COMPLETE content for each slot
+ * from the POV of the trait that fired. The runtime collects all render-ui
+ * effects from a transition, groups by slot, and calls
+ * `setSlotPatterns(slot, patterns, source)` once per slot.
+ *
+ * Multi-trait parity with the compiled path (2026-04-24):
+ * State is keyed by (slot, sourceTraitName). When ProbeCreate renders to
+ * "main" and ProbePersistor also renders to "main", both entries coexist —
+ * each source owns its own sub-entry. Consumers see them as a list in
+ * insertion order. Prior model was single-entry per slot (last-writer-wins),
+ * which diverged from the compiled path's VStack-of-trait-views layout.
  *
  * @packageDocumentation
  */
 import React from 'react';
-import type { PatternConfig } from '@almadar/core';
-import type { ResolvedTrait } from '@almadar/core';
+import type { PatternConfig, EventSource, ResolvedTrait } from '@almadar/core';
 /** A single pattern entry in a slot */
 export interface SlotPatternEntry {
     pattern: PatternConfig;
     props: Record<string, unknown>;
 }
 /**
- * Source metadata for a rendered slot.
- * Used by the Slot Inspector to show debug info.
+ * Source metadata for a rendered slot. Extends `@almadar/core`'s
+ * `EventSource` (which owns the `{ trait, transition?, tick? }` shape
+ * shared with the event bus) with UI-only debug fields used by the Slot
+ * Inspector. Keeping the core subset aligned means the slot machinery
+ * can round-trip with event bus metadata without re-coercion.
  */
-export interface SlotSource {
-    trait: string;
+export interface SlotSource extends EventSource {
+    /** Source trait's current state at the moment of render. */
     state: string;
-    transition: string;
+    /** Raw effects block that produced this render, for inspector display. */
     effects?: unknown[];
     /** Full trait definition for inspector */
     traitDefinition?: ResolvedTrait;
 }
-/** Full state of a single slot */
-export interface SlotState {
+/**
+ * One source's contribution to a slot. The same slot can receive
+ * contributions from multiple source traits (e.g. a page-level layout
+ * where ProbeCreate and ProbePersistor both render to "main").
+ */
+export interface SlotEntry {
     patterns: SlotPatternEntry[];
     source?: SlotSource;
 }
+/**
+ * All source contributions to a single slot, keyed by the source trait's
+ * name. The sentinel `'__default__'` key is used when `setSlotPatterns`
+ * is called without a source (legacy / unscoped callers).
+ *
+ * Iteration order reflects insertion order — the first trait to write to
+ * the slot renders first, which matches the compiled-path VStack order
+ * set by the .lolo's `page ... -> Trait1, Trait2, ...` declaration.
+ */
+export type SlotState = Record<string, SlotEntry>;
 /** All slots state */
 export type SlotsState = Record<string, SlotState>;
 /** Mutation functions for slots (stable references, won't trigger re-renders) */
 export interface SlotsActions {
-    /** Set all patterns for a slot atomically (replaces previous content) */
+    /**
+     * Set this source's contribution to a slot atomically. Replaces any
+     * prior content FROM THE SAME SOURCE only; other sources' entries in
+     * the slot are untouched.
+     */
     setSlotPatterns: (slot: string, patterns: SlotPatternEntry[], source?: SlotSource) => void;
-    /** Clear a single slot */
+    /**
+     * Clear a slot entirely. Wipes all source entries; consumers see an
+     * empty slot (no patterns from any source).
+     */
     clearSlot: (slot: string) => void;
+    /** Remove a single source's contribution from a slot, keeping others. */
+    clearSlotForSource: (slot: string, sourceTrait: string) => void;
     /** Clear all slots */
     clearAllSlots: () => void;
 }
+/** Entries in render order for a slot (insertion order, empty-filtered). */
+export declare function slotEntriesInOrder(slot: SlotState | null | undefined): Array<{
+    sourceKey: string;
+    entry: SlotEntry;
+}>;
 export interface SlotsProviderProps {
     children: React.ReactNode;
 }
@@ -53,7 +91,7 @@ export interface SlotsProviderProps {
  * SlotsProvider - Manages UI slot state via React useState.
  *
  * Replaces UIEnvironmentProvider. No observable store, no stacking logic.
- * Slots are set atomically per transition — React diffs and re-renders.
+ * Slots are set atomically per (transition, source) — React diffs and re-renders.
  */
 export declare function SlotsProvider({ children }: SlotsProviderProps): React.ReactElement;
 /**
@@ -62,7 +100,9 @@ export declare function SlotsProvider({ children }: SlotsProviderProps): React.R
  */
 export declare function useSlots(): SlotsState;
 /**
- * Get content for a specific slot. Returns null if slot is empty.
+ * Get the per-source state map for a specific slot. Returns null if
+ * nothing has written to this slot yet. To iterate sources in render
+ * order, use `slotEntriesInOrder(useSlotContent(name))`.
  */
 export declare function useSlotContent(slotName: string): SlotState | null;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "3.9.1",
+  "version": "4.0.1",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "main": "./dist/components/index.js",

package/dist/hooks/useEntityData.d.ts

@@ -1,155 +0,0 @@
-import type { ReactNode } from "react";
-import React from "react";
-export interface EntityDataAdapter {
-    /** Get all records for an entity */
-    getData: (entity: string) => Record<string, unknown>[];
-    /** Get a single record by entity name and ID */
-    getById: (entity: string, id: string) => Record<string, unknown> | undefined;
-    /** Whether data is currently loading */
-    isLoading: boolean;
-    /** Current error */
-    error: string | null;
-}
-/**
- * Provider that bridges a host app's data source to useEntityList/useEntity hooks.
- *
- * @example
- * ```tsx
- * // In builder runtime
- * const fetchedData = useFetchedData();
- * const adapter = {
- *   getData: fetchedData.getData,
- *   getById: fetchedData.getById,
- *   isLoading: fetchedData.loading,
- *   error: fetchedData.error,
- * };
- * <EntityDataProvider adapter={adapter}>
- *   {children}
- * </EntityDataProvider>
- * ```
- */
-export declare function EntityDataProvider({ adapter, children, }: {
-    adapter: EntityDataAdapter;
-    children: ReactNode;
-}): React.FunctionComponentElement<React.ProviderProps<EntityDataAdapter | null>>;
-/**
- * Access the entity data adapter (null if no provider).
- */
-export declare function useEntityDataAdapter(): EntityDataAdapter | null;
-export declare const entityDataKeys: {
-    all: readonly ["entities"];
-    lists: () => readonly ["entities", "list"];
-    list: (entity: string, filters?: Record<string, unknown>) => readonly ["entities", "list", string, Record<string, unknown> | undefined];
-    details: () => readonly ["entities", "detail"];
-    detail: (entity: string, id: string) => readonly ["entities", "detail", string, string];
-};
-export type EntityDataRecord = Record<string, unknown>;
-export interface UseEntityListOptions {
-    /** Skip fetching */
-    skip?: boolean;
-}
-export interface UseEntityListResult<T = Record<string, unknown>> {
-    data: T[];
-    isLoading: boolean;
-    error: Error | null;
-    refetch: () => void;
-}
-export interface UseEntityDetailResult<T = Record<string, unknown>> {
-    data: T | null;
-    isLoading: boolean;
-    error: Error | null;
-    refetch: () => void;
-}
-export interface PaginationParams {
-    page: number;
-    pageSize: number;
-    search?: string;
-    sortBy?: string;
-    sortDirection?: "asc" | "desc";
-    filters?: Record<string, unknown>;
-}
-export interface UsePaginatedEntityListResult<T = Record<string, unknown>> {
-    data: T[];
-    isLoading: boolean;
-    error: Error | null;
-    totalCount: number;
-    totalPages: number;
-    hasNextPage: boolean;
-    hasPreviousPage: boolean;
-    refetch: () => void;
-}
-/**
- * Hook for fetching entity list data.
- * Uses EntityDataContext if available, otherwise falls back to stub.
- */
-export declare function useEntityList<T = Record<string, unknown>>(entity: string | undefined, options?: UseEntityListOptions): UseEntityListResult<T>;
-/**
- * Hook for fetching a single entity by ID.
- * Uses EntityDataContext if available, otherwise falls back to stub.
- */
-export declare function useEntity<T = Record<string, unknown>>(entity: string | undefined, id: string | undefined): {
-    data: T | null;
-    isLoading: boolean;
-    error: Error | null;
-};
-/**
- * Hook for fetching entity detail by ID (alias for useEntity with refetch).
- * Uses EntityDataContext if available, otherwise falls back to stub.
- */
-export declare function useEntityDetail<T = Record<string, unknown>>(entity: string | undefined, id: string | undefined): UseEntityDetailResult<T>;
-/**
- * Hook for fetching paginated entity list data.
- * Uses EntityDataContext if available (client-side pagination), otherwise falls back to stub.
- */
-export declare function usePaginatedEntityList<T = Record<string, unknown>>(entity: string | undefined, params: PaginationParams, options?: UseEntityListOptions): UsePaginatedEntityListResult<T>;
-/**
- * Suspense-compatible hook for fetching entity list data.
- *
- * Instead of returning `isLoading`/`error`, this hook **suspends** (throws a Promise)
- * when data is not ready. Use inside a `<Suspense>` boundary.
- *
- * Falls back to the adapter when available; otherwise suspends briefly for stub data.
- *
- * @example
- * ```tsx
- * <Suspense fallback={<Skeleton variant="table" />}>
- *   <ErrorBoundary>
- *     <TaskList entity="Task" />
- *   </ErrorBoundary>
- * </Suspense>
- *
- * function TaskList({ entity }: { entity: string }) {
- *   const { data } = useEntityListSuspense<Task>(entity);
- *   // No loading check needed — Suspense handles it
- *   return <DataTable data={data} ... />;
- * }
- * ```
- */
-export declare function useEntityListSuspense<T = Record<string, unknown>>(entity: string): {
-    data: T[];
-    refetch: () => void;
-};
-/**
- * Suspense-compatible hook for fetching a single entity by ID.
- *
- * Suspends when data is not ready. Use inside a `<Suspense>` boundary.
- *
- * @example
- * ```tsx
- * <Suspense fallback={<Skeleton variant="form" />}>
- *   <ErrorBoundary>
- *     <TaskDetail entity="Task" id={taskId} />
- *   </ErrorBoundary>
- * </Suspense>
- *
- * function TaskDetail({ entity, id }: { entity: string; id: string }) {
- *   const { data } = useEntitySuspense<Task>(entity, id);
- *   return <DetailPanel data={data} ... />;
- * }
- * ```
- */
-export declare function useEntitySuspense<T = Record<string, unknown>>(entity: string, id: string): {
-    data: T | null;
-    refetch: () => void;
-};
-export default useEntityList;

package/dist/hooks/useEntityMutations.d.ts

@@ -1,80 +0,0 @@
-/**
- * useEntityMutations - Entity CRUD mutation hooks
- *
- * Provides create, update, and delete mutations for entities.
- * Used by trait hooks for persist_data effects.
- *
- * @deprecated For new code, prefer useOrbitalMutations which sends mutations
- * through the orbital events route. This ensures all mutations go through
- * trait state machines and enforce guards/effects.
- *
- * Migration:
- * ```tsx
- * // Old (deprecated):
- * const { createEntity } = useEntityMutations('Task');
- *
- * // New (recommended):
- * const { createEntity } = useOrbitalMutations('Task', 'TaskManager');
- * ```
- *
- * @see useOrbitalMutations
- */
-import { type OrbitalEventResponse } from './useOrbitalMutations';
-export interface EntityMutationResult {
-    id: string;
-    [key: string]: unknown;
-}
-/**
- * Hook for creating entities
- */
-export declare function useCreateEntity(entityName: string): import("@tanstack/react-query").UseMutationResult<EntityMutationResult, Error, Record<string, unknown>, unknown>;
-/**
- * Hook for updating entities
- */
-export declare function useUpdateEntity(entityName: string): import("@tanstack/react-query").UseMutationResult<EntityMutationResult, Error, {
-    id: string;
-    data: Record<string, unknown>;
-}, unknown>;
-/**
- * Hook for deleting entities
- */
-export declare function useDeleteEntity(entityName: string): import("@tanstack/react-query").UseMutationResult<{
-    id: string;
-}, Error, string, unknown>;
-export interface UseEntityMutationsOptions {
-    /**
-     * If provided, mutations go through orbital events route instead of direct CRUD.
-     * This is the recommended approach for Phase 7+ compliance.
-     */
-    orbitalName?: string;
-    /**
-     * Custom event names when using orbital-based mutations
-     */
-    events?: {
-        create?: string;
-        update?: string;
-        delete?: string;
-    };
-}
-/**
- * Combined hook that provides all entity mutations
- * Used by trait hooks for persist_data effects
- *
- * @param entityName - The entity type name
- * @param options - Optional configuration including orbital-based mutations
- *
- * @deprecated For new code, prefer useOrbitalMutations directly
- */
-export declare function useEntityMutations(entityName: string, options?: UseEntityMutationsOptions): {
-    createEntity: (entityOrData: string | Record<string, unknown>, data?: Record<string, unknown>) => Promise<OrbitalEventResponse | EntityMutationResult | undefined>;
-    updateEntity: (id: string | undefined, data: Record<string, unknown>) => Promise<OrbitalEventResponse | EntityMutationResult | undefined>;
-    deleteEntity: (id: string | undefined) => Promise<OrbitalEventResponse | {
-        id: string;
-    } | undefined>;
-    isCreating: boolean;
-    isUpdating: boolean;
-    isDeleting: boolean;
-    createError: Error | null;
-    updateError: Error | null;
-    deleteError: Error | null;
-};

package/dist/hooks/useOrbitalMutations.d.ts

@@ -1,95 +0,0 @@
-/**
- * useOrbitalMutations - Event-based entity mutations via orbital events route
- *
- * This hook provides entity mutations that go through the orbital events route
- * instead of direct CRUD API calls. This ensures all mutations:
- * 1. Go through trait state machines
- * 2. Enforce guards
- * 3. Execute all trait effects (including persist)
- *
- * This is the Phase 7 replacement for direct CRUD mutations.
- *
- * @example
- * ```tsx
- * const { createEntity, updateEntity, deleteEntity } = useOrbitalMutations('Task', 'TaskManager');
- *
- * // Create - sends ENTITY_CREATE event to orbital
- * await createEntity({ title: 'New Task', status: 'pending' });
- *
- * // Update - sends ENTITY_UPDATE event to orbital
- * await updateEntity(taskId, { status: 'completed' });
- *
- * // Delete - sends ENTITY_DELETE event to orbital
- * await deleteEntity(taskId);
- * ```
- *
- * @packageDocumentation
- */
-/**
- * Standard events for entity mutations
- * These are handled by orbitals with CRUD-capable traits
- */
-export declare const ENTITY_EVENTS: {
-    readonly CREATE: "ENTITY_CREATE";
-    readonly UPDATE: "ENTITY_UPDATE";
-    readonly DELETE: "ENTITY_DELETE";
-};
-export interface OrbitalEventPayload {
-    event: string;
-    payload?: Record<string, unknown>;
-    entityId?: string;
-}
-export interface OrbitalEventResponse {
-    success: boolean;
-    transitioned: boolean;
-    states: Record<string, string>;
-    emittedEvents: Array<{
-        event: string;
-        payload?: unknown;
-    }>;
-    error?: string;
-}
-/**
- * Hook for event-based entity mutations via orbital events route
- *
- * @param entityName - The entity type name (for cache invalidation)
- * @param orbitalName - The orbital to send events to
- * @param options - Optional configuration
- */
-export declare function useOrbitalMutations(entityName: string, orbitalName: string, options?: {
-    /** Custom event names for create/update/delete */
-    events?: {
-        create?: string;
-        update?: string;
-        delete?: string;
-    };
-    /** Enable debug logging */
-    debug?: boolean;
-}): {
-    createEntity: (data: Record<string, unknown>) => Promise<OrbitalEventResponse>;
-    updateEntity: (id: string | undefined, data: Record<string, unknown>) => Promise<OrbitalEventResponse | undefined>;
-    deleteEntity: (id: string | undefined) => Promise<OrbitalEventResponse | undefined>;
-    createMutation: import("@tanstack/react-query").UseMutationResult<OrbitalEventResponse, Error, Record<string, unknown>, unknown>;
-    updateMutation: import("@tanstack/react-query").UseMutationResult<OrbitalEventResponse, Error, {
-        id: string;
-        data: Record<string, unknown>;
-    }, unknown>;
-    deleteMutation: import("@tanstack/react-query").UseMutationResult<OrbitalEventResponse, Error, string, unknown>;
-    isCreating: boolean;
-    isUpdating: boolean;
-    isDeleting: boolean;
-    isMutating: boolean;
-    createError: Error | null;
-    updateError: Error | null;
-    deleteError: Error | null;
-};
-/**
- * Send a custom event to an orbital
- * For non-CRUD operations that go through trait state machines
- */
-export declare function useSendOrbitalEvent(orbitalName: string): {
-    sendEvent: (event: string, payload?: Record<string, unknown>, entityId?: string) => Promise<OrbitalEventResponse>;
-    isPending: boolean;
-    error: Error | null;
-    data: OrbitalEventResponse | undefined;
-};

package/dist/hooks/useResolvedEntity.d.ts

@@ -1,32 +0,0 @@
-export interface ResolvedEntity<T> {
-    /** Resolved data array */
-    data: T[];
-    /** True when data was provided directly via props (not fetched) */
-    isLocal: boolean;
-    /** Loading state — always false for local data */
-    isLoading: boolean;
-    /** Error state — always null for local data */
-    error: Error | null;
-}
-/**
- * Resolves entity data from either a direct `data` prop or an `entity` string.
- *
- * When `data` is provided, it is used directly (isLocal: true).
- * When only `entity` (string) is provided, data is fetched via useEntityList.
- * Direct `data` always takes precedence over auto-fetch.
- *
- * @param entity - Entity name string for auto-fetch, or undefined
- * @param data - Direct data array from trait render-ui, or undefined
- * @returns Normalized { data, isLocal, isLoading, error }
- *
- * @example
- * ```tsx
- * function MyOrganism({ entity, data, isLoading, error }: MyProps) {
- *   const resolved = useResolvedEntity<Item>(entity, data);
- *   // resolved.data is always T[] regardless of source
- *   // resolved.isLocal tells you if data came from props
- * }
- * ```
- */
-export declare function useResolvedEntity<T = Record<string, unknown>>(entity: string | undefined, data: readonly T[] | T[] | undefined): ResolvedEntity<T>;
-export default useResolvedEntity;

package/dist/providers/FetchedDataProvider.d.ts

@@ -1,105 +0,0 @@
-/**
- * FetchedDataProvider
- *
- * Provides server-fetched entity data to the client runtime.
- * This context stores data returned from compiled event handlers
- * via the `data` field in EventResponse.
- *
- * Data Flow:
- * 1. Client sends event to server
- * 2. Server executes compiled handler with fetch effects
- * 3. Server returns { data: { EntityName: [...records] }, clientEffects: [...] }
- * 4. Provider stores data in this context
- * 5. Pattern components access data via useFetchedData hook
- *
- * Used by both Builder preview and compiled shell.
- *
- * @packageDocumentation
- */
-import React from 'react';
-export interface EntityRecord {
-    id: string;
-    [key: string]: unknown;
-}
-export interface FetchedDataState {
-    /** Entity data by entity name (e.g., { Task: [...], User: [...] }) */
-    data: Record<string, EntityRecord[]>;
-    /** Timestamp of last fetch per entity */
-    fetchedAt: Record<string, number>;
-    /** Whether data is currently being fetched */
-    loading: boolean;
-    /** Last error message */
-    error: string | null;
-}
-export interface FetchedDataContextValue {
-    /** Get all records for an entity */
-    getData: (entityName: string) => EntityRecord[];
-    /** Get a single record by ID */
-    getById: (entityName: string, id: string) => EntityRecord | undefined;
-    /** Check if entity data exists */
-    hasData: (entityName: string) => boolean;
-    /** Get fetch timestamp for entity */
-    getFetchedAt: (entityName: string) => number | undefined;
-    /** Update data from server response */
-    setData: (data: Record<string, unknown[]>) => void;
-    /** Clear all fetched data */
-    clearData: () => void;
-    /** Clear data for specific entity */
-    clearEntity: (entityName: string) => void;
-    /** Current loading state */
-    loading: boolean;
-    /** Set loading state */
-    setLoading: (loading: boolean) => void;
-    /** Current error */
-    error: string | null;
-    /** Set error */
-    setError: (error: string | null) => void;
-}
-export declare const FetchedDataContext: React.Context<FetchedDataContextValue | null>;
-export interface FetchedDataProviderProps {
-    /** Initial data (optional) */
-    initialData?: Record<string, unknown[]>;
-    /** Children */
-    children: React.ReactNode;
-}
-/**
- * FetchedDataProvider - Provides server-fetched entity data
- *
- * @example
- * ```tsx
- * <FetchedDataProvider>
- *   <OrbitalProvider>
- *     <App />
- *   </OrbitalProvider>
- * </FetchedDataProvider>
- * ```
- */
-export declare function FetchedDataProvider({ initialData, children, }: FetchedDataProviderProps): React.ReactElement;
-/**
- * Access the fetched data context.
- * Returns null if not within a FetchedDataProvider.
- */
-export declare function useFetchedDataContext(): FetchedDataContextValue | null;
-/**
- * Access fetched data with fallback behavior.
- * If not in a provider, returns empty data.
- */
-export declare function useFetchedData(): FetchedDataContextValue;
-/**
- * Access fetched data for a specific entity.
- * Provides a convenient API for entity-specific operations.
- */
-export declare function useFetchedEntity(entityName: string): {
-    /** All fetched records for this entity */
-    records: EntityRecord[];
-    /** Get a record by ID */
-    getById: (id: string) => EntityRecord | undefined;
-    /** Whether data has been fetched for this entity */
-    hasData: boolean;
-    /** When data was last fetched */
-    fetchedAt: number | undefined;
-    /** Whether data is loading */
-    loading: boolean;
-    /** Current error */
-    error: string | null;
-};