@prometheus-ags/prometheus-entity-management 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -398,11 +398,25 @@ interface GraphTransaction {
     snapshot: () => GraphDataSnapshot;
 }
 interface GraphActionOptions<TInput, TResult> {
+    key?: string;
     optimistic?: (tx: GraphTransaction, input: TInput) => void;
     run: (tx: GraphTransaction, input: TInput) => Promise<TResult> | TResult;
     onSuccess?: (result: TResult, input: TInput, tx: GraphTransaction) => void;
     onError?: (error: Error, input: TInput) => void;
 }
+interface GraphActionRecord$1 {
+    id: string;
+    key: string;
+    input: unknown;
+    enqueuedAt: string;
+}
+type GraphActionEvent = {
+    type: "enqueued";
+    record: GraphActionRecord$1;
+} | {
+    type: "settled";
+    record: GraphActionRecord$1;
+};
 declare function createGraphTransaction(): GraphTransaction;
 declare function createGraphAction<TInput, TResult>(opts: GraphActionOptions<TInput, TResult>): (input: TInput) => Promise<TResult>;
 
@@ -431,18 +445,96 @@ interface GraphEffectHandle {
 }
 declare function createGraphEffect<T>(opts: GraphEffectOptions<T>): GraphEffectHandle;
 
-interface GraphSnapshotExportOptions {
-    scope: string;
-    data: unknown;
-    pretty?: boolean;
+/**
+ * Compiles a {@link FilterSpec} into a Prisma `where` object (plain JSON-serializable shape).
+ *
+ * Operator mapping matches common Prisma filter APIs: `eq` → `equals`, string ops use `mode: "insensitive"`,
+ * `nin` → `notIn`, `arrayContains` → `has`, `isNull` uses `null` / `{ not: null }` per `value`, and `isNotNull` → `{ not: null }`.
+ * Unsupported ops (`between`, `arrayOverlaps`, `matches`, `custom`) are omitted from the result.
+ *
+ * Top-level clause arrays are combined with `AND`. {@link FilterGroup} uses `AND` / `OR` to match `group.logic`.
+ */
+declare function toPrismaWhere(filter: FilterSpec): Record<string, unknown>;
+/**
+ * Compiles a {@link SortSpec} into Prisma `orderBy` form: `[{ fieldName: "asc" | "desc" }, …]`.
+ * `nulls` and `comparator` on {@link SortClause} are ignored (local-only); extend callers if your Prisma version supports null ordering.
+ */
+declare function toPrismaOrderBy(sort: SortSpec): Record<string, string>[];
+
+/**
+ * Transport-agnostic comparison operators. Same spec can compile to REST, SQL, GraphQL, or local JS (`evaluator`).
+ * `custom` opts out of automatic serialization — use for predicates only the client can evaluate.
+ */
+type FilterOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "contains" | "startsWith" | "endsWith" | "isNull" | "isNotNull" | "between" | "arrayContains" | "arrayOverlaps" | "matches" | "custom";
+/** Atomic filter: field path, operator, optional value, and optional JS predicate for `custom`. */
+interface FilterClause {
+    field: string;
+    op: FilterOperator;
+    value?: unknown;
+    predicate?: (fieldValue: unknown, entity: Record<string, unknown>) => boolean;
 }
-interface GraphToolContext {
-    store: ReturnType<typeof useGraphStore.getState>;
-    queryOnce: typeof queryOnce;
-    exportGraphSnapshot: typeof exportGraphSnapshot;
+type FilterLogic = "and" | "or";
+/** Nested boolean group so you can express `(A AND B) OR C` without losing structure when compiling to backends. */
+interface FilterGroup {
+    logic: FilterLogic;
+    clauses: Array<FilterClause | FilterGroup>;
 }
-declare function exportGraphSnapshot(opts: GraphSnapshotExportOptions): string;
-declare function createGraphTool<TInput, TResult>(handler: (input: TInput, ctx: GraphToolContext) => Promise<TResult> | TResult): (input: TInput) => TResult | Promise<TResult>;
+/** Top-level filter: flat AND list of clauses, or a recursive `FilterGroup`. */
+type FilterSpec = FilterGroup | FilterClause[];
+type SortDirection = "asc" | "desc";
+/** Single sort key with optional null ordering and custom comparator for local sort parity with remote semantics. */
+interface SortClause {
+    field: string;
+    direction: SortDirection;
+    nulls?: "first" | "last";
+    comparator?: (a: unknown, b: unknown) => number;
+}
+/** Ordered multi-key sort (stable application in `compareEntities`). */
+type SortSpec = SortClause[];
+/**
+ * Everything `useEntityView` needs to describe a virtualized collection: filters, sorts, and simple multi-field search.
+ * One descriptor can drive local evaluation, remote query compilation, or hybrid mode.
+ */
+interface ViewDescriptor {
+    filter?: FilterSpec;
+    sort?: SortSpec;
+    search?: {
+        query: string;
+        fields: string[];
+        minChars?: number;
+    };
+}
+/**
+ * How complete local graph data is relative to the view: **local** (all in memory), **remote** (server must filter/sort), **hybrid** (show local fast + remote reconcile).
+ */
+type CompletenessMode = "local" | "remote" | "hybrid";
+/**
+ * Compile a view to flat REST query params (`sort`, `q`, and `field[op]=value` keys). Skips `custom` clauses — those cannot be expressed as strings.
+ */
+declare function toRestParams(view: ViewDescriptor): Record<string, string>;
+/**
+ * Compile a view to parameterized SQL fragments for server-side filtering/sorting. Unknown ops become `TRUE` — validate or restrict ops at the edge.
+ */
+declare function toSQLClauses(view: ViewDescriptor): {
+    where: string;
+    orderBy: string;
+    params: unknown[];
+};
+/**
+ * Produce a GraphQL-variable-shaped object from a view (Hasura/Postgraphile-style `_op` maps). Intended as a starting point — wire to your actual schema.
+ */
+declare function toGraphQLVariables(view: ViewDescriptor): {
+    where?: Record<string, unknown>;
+    orderBy?: Array<Record<string, unknown>>;
+    search?: string;
+};
+
+/**
+ * Normalize nested `FilterGroup` trees to a flat clause list for compilers that only understand atomic predicates.
+ */
+declare function flattenClauses(filter: FilterSpec): FilterClause[];
+/** True if any clause requires client-side `predicate` logic — forces local/hybrid evaluation paths that cannot be pushed to generic REST/SQL. */
+declare function hasCustomPredicates(filter: FilterSpec): boolean;
 
 /**
  * Process-wide defaults for stale times, retries, and background revalidation.
@@ -549,360 +641,562 @@ declare function fetchEntity<TRaw, TEntity extends Record<string, unknown>>(opts
 declare function fetchList<TRaw, TEntity extends Record<string, unknown>>(opts: ListQueryOptions<TRaw, TEntity>, params: ListFetchParams, engineOpts: Required<EngineOptions>, isLoadMore?: boolean): Promise<void>;
 
 /**
- * Debug-time snapshot of entity graph health: counts, list queries, patches, staleness,
- * in-flight fetches, and engine subscriber ref-counts.
- *
- * Mount inside a DevTools panel or debug route; subscriber totals update via
- * `useSyncExternalStore` when hooks register/unregister interest, and graph fields
- * update through the Zustand store.
- */
-declare function useGraphDevTools(): {
-    subscriberCount: number;
-    entityCounts: Record<string, number>;
-    totalEntities: number;
-    listCount: number;
-    patchedEntities: {
-        type: string;
-        id: string;
-    }[];
-    staleEntities: {
-        type: string;
-        id: string;
-    }[];
-    fetchingEntities: {
-        type: string;
-        id: string;
-    }[];
-    lists: {
-        key: string;
-        idCount: number;
-        isFetching: boolean;
-        isStale: boolean;
-    }[];
-};
-
-/**
- * View-model for one entity row: merged canonical + patch data plus fetch lifecycle flags.
- * `isLoading` is true only when there is no data yet; `isFetching` includes background refreshes.
+ * Precompiled transport payloads for one view snapshot — pass to REST, GraphQL, or SQL backends without re-deriving from `ViewDescriptor`.
  */
-interface UseEntityResult<T> {
-    data: T | null;
-    isLoading: boolean;
-    isFetching: boolean;
-    error: string | null;
-    isStale: boolean;
-    refetch: () => void;
+interface ViewFetchParams {
+    rest: Record<string, string>;
+    graphql: ReturnType<typeof toGraphQLVariables>;
+    sql: ReturnType<typeof toSQLClauses>;
+    view: ViewDescriptor;
 }
 /**
- * Subscribe to a single normalized entity: populates the graph via `fetch`/`normalize`, dedupes in-flight work, and revalidates when stale.
- * Solves “query-owned silos” by keeping **one** canonical record every list/detail reads through.
- *
- * @param opts - Entity query instruction (`EntityQueryOptions`): `type`, `id`, `fetch`, `normalize`, optional `staleTime` / `enabled`
- * @returns Merged entity (`entities` + `patches`), loading/error/stale flags, and `refetch`
- *
- * @example
- * ```tsx
- * const { data, isLoading, refetch } = useEntity({
- *   type: "Project",
- *   id: projectId,
- *   fetch: (id) => api.getProject(id),
- *   normalize: (raw) => ({ ...raw, id: String(raw.id) }),
- * });
- * ```
+ * Configure a **live view** over a base list: filter/sort/search in JS when data is complete, or compile the same spec to remote params when not.
+ * `baseQueryKey` identifies the underlying id list in the graph; the hook may create additional keys for remote result sets.
  */
-declare function useEntity<TRaw, TEntity extends Record<string, unknown>>(opts: EntityQueryOptions<TRaw, TEntity>): UseEntityResult<TEntity>;
+interface UseEntityViewOptions<TEntity extends Record<string, unknown>> {
+    type: EntityType;
+    baseQueryKey: unknown[];
+    view: ViewDescriptor;
+    mode?: CompletenessMode;
+    remoteFetch?: (params: ViewFetchParams) => Promise<ListResponse<TEntity>>;
+    normalize?: (raw: TEntity) => {
+        id: EntityId;
+        data: Record<string, unknown>;
+    };
+    remoteDebounce?: number;
+    staleTime?: number;
+    enabled?: boolean;
+    /** SSR-seeded ids written once into `lists[baseKey]` to avoid empty-state flash before hydration fetch. */
+    initialIds?: EntityId[];
+    /** SSR-seeded total for completeness heuristics when ids are preloaded. */
+    initialTotal?: number;
+}
 /**
- * Resolved rows for a list query: **`items` joins `ids` to the graph** at render time so shared entities update everywhere.
+ * Rich list UI state: projected `items`/`viewIds`, completeness mode, remote vs local fetching flags, and imperative view updaters.
+ * `isShowingLocalPending` signals hybrid mode where stale local rows are visible while a remote round-trip runs.
  */
-interface UseEntityListResult<TEntity> {
+interface UseEntityViewResult<TEntity> {
     items: TEntity[];
-    ids: EntityId[];
+    viewIds: EntityId[];
+    viewTotal: number | null;
     isLoading: boolean;
     isFetching: boolean;
-    isFetchingMore: boolean;
+    isRemoteFetching: boolean;
+    isShowingLocalPending: boolean;
     error: string | null;
     hasNextPage: boolean;
-    hasPrevPage: boolean;
-    total: number | null;
-    currentPage: number | null;
     fetchNextPage: () => void;
+    isLocallyComplete: boolean;
+    completenessMode: CompletenessMode;
+    setView: (v: Partial<ViewDescriptor>) => void;
+    setFilter: (f: FilterSpec | null) => void;
+    setSort: (s: SortSpec | null) => void;
+    setSearch: (q: string) => void;
+    clearView: () => void;
     refetch: () => void;
+    isFetchingMore: boolean;
 }
 /**
- * Subscribe to a collection: stores **ordered ids** under a serialized `queryKey`, upserts each row into `entities`, and supports pagination.
- * Use when you need a table or feed backed by the shared graph (not an isolated query cache).
+ * Higher-level list hook: combines **graph-backed id lists**, declarative `ViewDescriptor`, local `applyView`, optional remote fetch, and realtime sorted insertion.
+ * Solves “filters tied to one query cache” by deriving the visible id order from the shared graph whenever possible.
  *
- * @param opts - List query instruction (`ListQueryOptions`)
- * @returns Hydrated `items`, raw `ids`, pagination helpers, and fetch flags
+ * @param opts - Base type/key, initial view, optional `remoteFetch` + `normalize`, SSR seeds, forced `mode`
+ * @returns Projected entities, view metadata, completeness, and setters for interactive toolbars
  *
  * @example
  * ```tsx
- * const { items, fetchNextPage, hasNextPage } = useEntityList({
+ * const view = useEntityView({
  *   type: "Task",
- *   queryKey: ["tasks", { projectId }],
- *   fetch: (p) => api.listTasks({ ...p, projectId }),
+ *   baseQueryKey: ["tasks", projectId],
+ *   view: { filter: [{ field: "status", op: "eq", value: "open" }], sort: [{ field: "dueAt", direction: "asc" }] },
+ *   remoteFetch: (p) => api.tasksQuery(p.rest),
  *   normalize: (raw) => ({ id: raw.id, data: raw }),
- *   mode: "append",
  * });
  * ```
  */
-declare function useEntityList<TRaw, TEntity extends Record<string, unknown>>(opts: ListQueryOptions<TRaw, TEntity>): UseEntityListResult<TEntity>;
+declare function useEntityView<TEntity extends Record<string, unknown>>(opts: UseEntityViewOptions<TEntity>): UseEntityViewResult<TEntity>;
+
+/** UI mode for a single CRUD surface: drives which panels/forms are active without scattering boolean flags. */
+type CRUDMode = "list" | "detail" | "edit" | "create";
 /**
- * Options for graph-aware mutations: API call + optional normalization into `entities`, optimistic patches, and targeted invalidation.
- * Prefer `invalidateLists` prefixes / `invalidateEntities` over ad-hoc store calls so list UIs stay coherent.
+ * Wire one entity type into list+detail+forms: remote list via `useEntityView`, optional detail fetch, and create/update/delete callbacks.
+ * Mutations call `cascadeInvalidation` on success so related lists/entities refresh per registered schemas.
  */
-interface MutationOptions<TInput, TRaw, TEntity extends Record<string, unknown>> {
+interface CRUDOptions<TEntity extends Record<string, unknown>> {
     type: EntityType;
-    mutate: (input: TInput) => Promise<TRaw>;
-    normalize?: (raw: TRaw, input: TInput) => {
+    listQueryKey: unknown[];
+    listFetch: (params: ViewFetchParams) => Promise<ListResponse<TEntity>>;
+    normalize: (raw: TEntity) => {
         id: EntityId;
         data: TEntity;
     };
-    optimistic?: (input: TInput) => {
-        id: EntityId;
-        patch: Partial<TEntity>;
-    } | null;
-    invalidateLists?: string[];
-    invalidateEntities?: Array<{
-        type: EntityType;
-        id: EntityId;
-    }>;
-    onSuccess?: (result: TRaw, input: TInput) => void;
-    onError?: (error: Error, input: TInput) => void;
-}
-/** Imperative mutation handle plus explicit async `state` for UI pending/error/success. */
-interface UseMutationResult<TInput, TRaw> {
-    mutate: (input: TInput) => Promise<TRaw | null>;
-    trigger: (input: TInput) => void;
-    reset: () => void;
-    state: {
-        isPending: boolean;
-        isSuccess: boolean;
-        isError: boolean;
-        error: string | null;
-    };
+    detailFetch?: (id: EntityId) => Promise<TEntity>;
+    onCreate?: (data: Partial<TEntity>) => Promise<TEntity>;
+    onUpdate?: (id: EntityId, patch: Partial<TEntity>) => Promise<TEntity>;
+    onDelete?: (id: EntityId) => Promise<void>;
+    createDefaults?: Partial<TEntity>;
+    initialView?: ViewDescriptor;
+    onCreateSuccess?: (entity: TEntity) => void;
+    onUpdateSuccess?: (entity: TEntity) => void;
+    onDeleteSuccess?: (id: EntityId) => void;
+    onError?: (op: "create" | "update" | "delete", error: Error) => void;
+    selectAfterCreate?: boolean;
+    clearSelectionAfterDelete?: boolean;
+}
+/** Public field input for CRUD setters: supports classic `keyof T` calls and dotted nested paths for JSON-backed forms. */
+type EntityFieldPath<TEntity extends Record<string, unknown>> = keyof TEntity | string;
+/** Tracks which fields diverge from loaded detail — edit buffer stays in React state so other views keep showing canonical graph data until save. */
+interface DirtyFields<TEntity extends Record<string, unknown>> {
+    changed: ReadonlySet<EntityFieldPath<TEntity>>;
+    isDirty: boolean;
 }
 /**
- * Perform writes through your API while keeping the entity graph authoritative: optional optimistic `patchEntity`, commit via `upsertEntity`, rollback on failure.
- * Use when `useEntity`/`useEntityList` describe reads and you need a consistent mutation story without a second client cache.
- *
- * @example
- * ```tsx
- * const { mutate, state } = useEntityMutation({
- *   type: "Task",
- *   mutate: (input) => api.updateTask(input.id, input.patch),
- *   normalize: (raw) => ({ id: raw.id, data: raw }),
- * });
- * ```
- */
-declare function useEntityMutation<TInput, TRaw, TEntity extends Record<string, unknown>>(opts: MutationOptions<TInput, TRaw, TEntity>): UseMutationResult<TInput, TRaw>;
-/**
- * Read/write **UI-only** fields for one entity (`patches` layer) so selection, hover, or transient state is visible in every view that reads that id.
- * Does not replace `useEntityCRUD`’s edit buffer for form drafts — patches are for shared, non-persisted overlays.
- *
- * @param type - Entity kind
- * @param id - Entity id (no-ops when null/undefined)
- * @returns Current patch slice and helpers `augment` / `unaugment` / `clear`
- */
-declare function useEntityAugment<TEntity extends Record<string, unknown>>(type: EntityType, id: EntityId | null | undefined): {
-    patch: Partial<TEntity> | null;
-    augment: (fields: Partial<TEntity>) => void;
-    unaugment: (keys: (keyof TEntity)[]) => void;
-    clear: () => void;
-};
-/**
- * Suspense-compatible version of `useEntity`. Throws a promise while the entity
- * is loading, allowing React Suspense boundaries to show fallback UI.
- * Once data is available, returns the entity data directly (never null).
- *
- * @param opts - Same as `useEntity` (`EntityQueryOptions`)
- * @returns `data` plus `isFetching`, `isStale`, and `refetch`
- * @throws Promise while loading (caught by the nearest Suspense boundary)
- * @throws Error if the fetch fails with no data, if `id` is missing when required, or if the entity never resolves
- */
-declare function useSuspenseEntity<TRaw, TEntity extends Record<string, unknown>>(opts: EntityQueryOptions<TRaw, TEntity>): {
-    data: TEntity;
-    isFetching: boolean;
-    isStale: boolean;
-    refetch: () => void;
-};
-/**
- * Suspense-compatible version of `useEntityList`. Throws a promise during
- * initial load, allowing Suspense boundaries to handle loading state.
- *
- * @param opts - Same as `useEntityList` (`ListQueryOptions`)
- * @returns Same shape as `useEntityList` except `isLoading` is omitted (always false when not suspended)
- * @throws Promise while initially loading (caught by the nearest Suspense boundary)
- * @throws Error if the fetch fails while the list is still empty
+ * Everything a CRUD screen needs: composed `list` view, selection, detail subscription, relation joins, edit/create buffers, and mutating actions.
+ * `applyOptimistic` is the escape hatch to mirror the buffer into `patches` for instant sliders/toggles without committing `save` yet.
  */
-declare function useSuspenseEntityList<TRaw, TEntity extends Record<string, unknown>>(opts: ListQueryOptions<TRaw, TEntity>): Omit<UseEntityListResult<TEntity>, "isLoading">;
-
+interface CRUDState<TEntity extends Record<string, unknown>> {
+    mode: CRUDMode;
+    setMode: (mode: CRUDMode) => void;
+    list: UseEntityViewResult<TEntity>;
+    selectedId: EntityId | null;
+    select: (id: EntityId | null) => void;
+    openDetail: (id: EntityId) => void;
+    detail: TEntity | null;
+    detailIsLoading: boolean;
+    detailError: string | null;
+    relations: Record<string, unknown>;
+    editBuffer: Partial<TEntity>;
+    setField: (field: EntityFieldPath<TEntity>, value: unknown) => void;
+    setFields: (fields: Partial<TEntity>) => void;
+    resetBuffer: () => void;
+    dirty: DirtyFields<TEntity>;
+    startEdit: (id?: EntityId) => void;
+    cancelEdit: () => void;
+    save: () => Promise<TEntity | null>;
+    isSaving: boolean;
+    saveError: string | null;
+    applyOptimistic: () => void;
+    createBuffer: Partial<TEntity>;
+    setCreateField: (field: EntityFieldPath<TEntity>, value: unknown) => void;
+    setCreateFields: (fields: Partial<TEntity>) => void;
+    resetCreateBuffer: () => void;
+    startCreate: () => void;
+    cancelCreate: () => void;
+    create: () => Promise<TEntity | null>;
+    isCreating: boolean;
+    createError: string | null;
+    deleteEntity: (id?: EntityId) => Promise<void>;
+    isDeleting: boolean;
+    deleteError: string | null;
+    isEditing: boolean;
+}
 /**
- * Compiles a {@link FilterSpec} into a Prisma `where` object (plain JSON-serializable shape).
- *
- * Operator mapping matches common Prisma filter APIs: `eq` → `equals`, string ops use `mode: "insensitive"`,
- * `nin` → `notIn`, `arrayContains` → `has`, `isNull` uses `null` / `{ not: null }` per `value`, and `isNotNull` → `{ not: null }`.
- * Unsupported ops (`between`, `arrayOverlaps`, `matches`, `custom`) are omitted from the result.
+ * Batteries-included CRUD orchestration over the entity graph: list filtering/sorting, detail fetch, isolated edit buffer, optimistic create row, and transactional save/delete with rollback.
+ * Prefer this over ad-hoc `useEntity` wiring when building admin-style tables + side panels + forms for one resource.
  *
- * Top-level clause arrays are combined with `AND`. {@link FilterGroup} uses `AND` / `OR` to match `group.logic`.
- */
-declare function toPrismaWhere(filter: FilterSpec): Record<string, unknown>;
-/**
- * Compiles a {@link SortSpec} into Prisma `orderBy` form: `[{ fieldName: "asc" | "desc" }, …]`.
- * `nulls` and `comparator` on {@link SortClause} are ignored (local-only); extend callers if your Prisma version supports null ordering.
+ * @param opts - `CRUDOptions` for type, list key/fetch, normalization, lifecycle callbacks
+ * @returns `CRUDState` with list/detail/edit/create controls
  */
-declare function toPrismaOrderBy(sort: SortSpec): Record<string, string>[];
+declare function useEntityCRUD<TEntity extends Record<string, unknown>>(opts: CRUDOptions<TEntity>): CRUDState<TEntity>;
 
-/**
- * Transport-agnostic comparison operators. Same spec can compile to REST, SQL, GraphQL, or local JS (`evaluator`).
- * `custom` opts out of automatic serialization — use for predicates only the client can evaluate.
- */
-type FilterOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "contains" | "startsWith" | "endsWith" | "isNull" | "isNotNull" | "between" | "arrayContains" | "arrayOverlaps" | "matches" | "custom";
-/** Atomic filter: field path, operator, optional value, and optional JS predicate for `custom`. */
-interface FilterClause {
+type FieldType = "text" | "textarea" | "number" | "email" | "url" | "date" | "boolean" | "enum" | "json" | "markdown" | "custom";
+interface FieldDescriptor<TEntity> {
     field: string;
-    op: FilterOperator;
-    value?: unknown;
-    predicate?: (fieldValue: unknown, entity: Record<string, unknown>) => boolean;
+    label: string;
+    type: FieldType;
+    required?: boolean;
+    placeholder?: string;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    hint?: string;
+    render?: (value: unknown, entity: TEntity) => React$1.ReactNode;
+    editControl?: (value: unknown, onChange: (v: unknown) => void, entity: Partial<TEntity>) => React$1.ReactNode;
+    hideOnCreate?: boolean;
+    hideOnEdit?: boolean;
+    readonlyOnEdit?: boolean;
 }
-type FilterLogic = "and" | "or";
-/** Nested boolean group so you can express `(A AND B) OR C` without losing structure when compiling to backends. */
-interface FilterGroup {
-    logic: FilterLogic;
-    clauses: Array<FilterClause | FilterGroup>;
+declare function Sheet({ open, onClose, title, subtitle, children, footer, width }: {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    subtitle?: string;
+    children: React$1.ReactNode;
+    footer?: React$1.ReactNode;
+    width?: string;
+}): react_jsx_runtime.JSX.Element;
+declare function EntityDetailSheet<TEntity extends Record<string, unknown>>({ crud, fields, title, description, children, showEditButton, showDeleteButton, deleteConfirmMessage }: {
+    crud: CRUDState<TEntity>;
+    fields: FieldDescriptor<TEntity>[];
+    title?: string | ((e: TEntity) => string);
+    description?: string | ((e: TEntity) => string);
+    children?: (entity: TEntity, crud: CRUDState<TEntity>) => React$1.ReactNode;
+    showEditButton?: boolean;
+    showDeleteButton?: boolean;
+    deleteConfirmMessage?: string;
+}): react_jsx_runtime.JSX.Element;
+declare function EntityFormSheet<TEntity extends Record<string, unknown>>({ crud, fields, createTitle, editTitle }: {
+    crud: CRUDState<TEntity>;
+    fields: FieldDescriptor<TEntity>[];
+    createTitle?: string;
+    editTitle?: string | ((e: TEntity) => string);
+}): react_jsx_runtime.JSX.Element;
+
+interface JsonSchemaObject {
+    $id?: string;
+    title?: string;
+    description?: string;
+    type?: string | string[];
+    format?: string;
+    enum?: unknown[];
+    default?: unknown;
+    properties?: Record<string, JsonSchemaObject>;
+    items?: JsonSchemaObject;
+    required?: string[];
+    ["x-a2ui-component"]?: string;
+    ["x-display-order"]?: number;
+    ["x-field-type"]?: string;
+    ["x-hidden"]?: boolean;
+}
+interface EntityJsonSchemaConfig {
+    entityType: string;
+    schemaId?: string;
+    field?: string;
+    version?: string;
+    source?: "static" | "runtime" | "ai";
+    schema: JsonSchemaObject;
+}
+interface GetEntityJsonSchemaOptions {
+    entityType: string;
+    schemaId?: string;
+    field?: string;
+}
+interface SchemaFieldDescriptor<TEntity extends Record<string, unknown> = Record<string, unknown>> extends FieldDescriptor<TEntity> {
+    schemaPath: string;
+    schema: JsonSchemaObject;
+    componentHint?: string;
+}
+interface BuildEntityFieldsFromSchemaOptions {
+    schema: JsonSchemaObject;
+    rootField?: string;
+}
+interface GraphSnapshotWithSchemasOptions {
+    scope: string;
+    data: unknown;
+    schemas: Array<EntityJsonSchemaConfig | null | undefined>;
+    pretty?: boolean;
 }
-/** Top-level filter: flat AND list of clauses, or a recursive `FilterGroup`. */
-type FilterSpec = FilterGroup | FilterClause[];
-type SortDirection = "asc" | "desc";
-/** Single sort key with optional null ordering and custom comparator for local sort parity with remote semantics. */
-interface SortClause {
-    field: string;
-    direction: SortDirection;
-    nulls?: "first" | "last";
-    comparator?: (a: unknown, b: unknown) => number;
+declare function registerEntityJsonSchema(config: EntityJsonSchemaConfig): void;
+declare function registerRuntimeSchema(config: EntityJsonSchemaConfig): void;
+declare function getEntityJsonSchema(opts: GetEntityJsonSchemaOptions): EntityJsonSchemaConfig | null;
+declare function useSchemaEntityFields<TEntity extends Record<string, unknown> = Record<string, unknown>>(opts: GetEntityJsonSchemaOptions & {
+    schema?: JsonSchemaObject;
+    rootField?: string;
+}): SchemaFieldDescriptor<TEntity>[];
+declare function buildEntityFieldsFromSchema<TEntity extends Record<string, unknown> = Record<string, unknown>>(opts: BuildEntityFieldsFromSchemaOptions): SchemaFieldDescriptor<TEntity>[];
+declare function exportGraphSnapshotWithSchemas(opts: GraphSnapshotWithSchemasOptions): string;
+declare function renderMarkdownToHtml(value: string): string;
+declare function MarkdownFieldRenderer({ value, className }: {
+    value: string;
+    className?: string;
+}): react_jsx_runtime.JSX.Element;
+declare function MarkdownFieldEditor({ value, onChange, placeholder, }: {
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+}): react_jsx_runtime.JSX.Element;
+
+interface GraphSnapshotExportOptions {
+    scope: string;
+    data: unknown;
+    pretty?: boolean;
 }
-/** Ordered multi-key sort (stable application in `compareEntities`). */
-type SortSpec = SortClause[];
-/**
- * Everything `useEntityView` needs to describe a virtualized collection: filters, sorts, and simple multi-field search.
- * One descriptor can drive local evaluation, remote query compilation, or hybrid mode.
- */
-interface ViewDescriptor {
-    filter?: FilterSpec;
-    sort?: SortSpec;
-    search?: {
-        query: string;
-        fields: string[];
-        minChars?: number;
+interface GraphToolContext {
+    store: ReturnType<typeof useGraphStore.getState>;
+    queryOnce: typeof queryOnce;
+    exportGraphSnapshot: typeof exportGraphSnapshot;
+}
+interface SchemaGraphToolContext extends GraphToolContext {
+    getEntityJsonSchema: typeof getEntityJsonSchema;
+    exportGraphSnapshotWithSchemas: typeof exportGraphSnapshotWithSchemas;
+}
+declare function exportGraphSnapshot(opts: GraphSnapshotExportOptions): string;
+declare function createGraphTool<TInput, TResult>(handler: (input: TInput, ctx: GraphToolContext) => Promise<TResult> | TResult): (input: TInput) => TResult | Promise<TResult>;
+declare function createSchemaGraphTool<TInput, TResult>(handler: (input: TInput, ctx: SchemaGraphToolContext) => Promise<TResult> | TResult): (input: TInput) => TResult | Promise<TResult>;
+
+interface GraphPersistenceAdapter {
+    get: (key: string) => Promise<string | null> | string | null;
+    set: (key: string, value: string) => Promise<void> | void;
+    remove?: (key: string) => Promise<void> | void;
+}
+interface GraphActionRecord {
+    id: string;
+    key: string;
+    input: unknown;
+    enqueuedAt: string;
+}
+interface GraphSyncStatus {
+    phase: "idle" | "hydrating" | "syncing" | "ready" | "offline" | "error";
+    isOnline: boolean;
+    isSynced: boolean;
+    pendingActions: number;
+    lastHydratedAt: string | null;
+    lastPersistedAt: string | null;
+    storageKey: string | null;
+    error: string | null;
+}
+interface GraphSnapshotPayload {
+    version: 1;
+    snapshot: {
+        entities: ReturnType<typeof useGraphStore.getState>["entities"];
+        patches: ReturnType<typeof useGraphStore.getState>["patches"];
+        entityStates: ReturnType<typeof useGraphStore.getState>["entityStates"];
+        syncMetadata: ReturnType<typeof useGraphStore.getState>["syncMetadata"];
+        lists: ReturnType<typeof useGraphStore.getState>["lists"];
     };
+    pendingActions: GraphActionRecord[];
 }
-/**
- * How complete local graph data is relative to the view: **local** (all in memory), **remote** (server must filter/sort), **hybrid** (show local fast + remote reconcile).
- */
-type CompletenessMode = "local" | "remote" | "hybrid";
-/**
- * Compile a view to flat REST query params (`sort`, `q`, and `field[op]=value` keys). Skips `custom` clauses — those cannot be expressed as strings.
- */
-declare function toRestParams(view: ViewDescriptor): Record<string, string>;
-/**
- * Compile a view to parameterized SQL fragments for server-side filtering/sorting. Unknown ops become `TRUE` — validate or restrict ops at the edge.
- */
-declare function toSQLClauses(view: ViewDescriptor): {
-    where: string;
-    orderBy: string;
-    params: unknown[];
-};
-/**
- * Produce a GraphQL-variable-shaped object from a view (Hasura/Postgraphile-style `_op` maps). Intended as a starting point — wire to your actual schema.
- */
-declare function toGraphQLVariables(view: ViewDescriptor): {
-    where?: Record<string, unknown>;
-    orderBy?: Array<Record<string, unknown>>;
-    search?: string;
-};
+interface PersistGraphToStorageOptions {
+    storage: GraphPersistenceAdapter;
+    key: string;
+    pendingActions?: GraphActionRecord[];
+}
+interface HydrateGraphFromStorageOptions {
+    storage: GraphPersistenceAdapter;
+    key: string;
+}
+interface StartLocalFirstGraphOptions {
+    storage: GraphPersistenceAdapter;
+    key?: string;
+    replayPendingActions?: boolean;
+    onlineSource?: {
+        getIsOnline: () => boolean;
+        subscribe: (listener: (online: boolean) => void) => () => void;
+    };
+    persistDebounceMs?: number;
+}
+interface LocalFirstGraphRuntime {
+    ready: Promise<void>;
+    dispose: () => void;
+    persistNow: () => Promise<void>;
+    hydrate: () => Promise<Awaited<ReturnType<typeof hydrateGraphFromStorage>>>;
+    getStatus: () => GraphSyncStatus;
+}
+declare function useGraphSyncStatus(): GraphSyncStatus;
+declare function persistGraphToStorage(opts: PersistGraphToStorageOptions): Promise<{
+    ok: true;
+    key: string;
+    bytes: number;
+    persistedAt: string;
+}>;
+declare function hydrateGraphFromStorage(opts: HydrateGraphFromStorageOptions): Promise<{
+    ok: false;
+    key: string;
+    hydratedAt: null;
+    entityCounts: {};
+    error: string;
+    pendingActions?: undefined;
+} | {
+    ok: true;
+    key: string;
+    hydratedAt: string;
+    entityCounts: {
+        [k: string]: number;
+    };
+    pendingActions: GraphActionRecord[];
+    error?: undefined;
+}>;
+declare function startLocalFirstGraph(opts: StartLocalFirstGraphOptions): LocalFirstGraphRuntime;
 
 /**
- * Normalize nested `FilterGroup` trees to a flat clause list for compilers that only understand atomic predicates.
+ * Debug-time snapshot of entity graph health: counts, list queries, patches, staleness,
+ * in-flight fetches, and engine subscriber ref-counts.
+ *
+ * Mount inside a DevTools panel or debug route; subscriber totals update via
+ * `useSyncExternalStore` when hooks register/unregister interest, and graph fields
+ * update through the Zustand store.
  */
-declare function flattenClauses(filter: FilterSpec): FilterClause[];
-/** True if any clause requires client-side `predicate` logic — forces local/hybrid evaluation paths that cannot be pushed to generic REST/SQL. */
-declare function hasCustomPredicates(filter: FilterSpec): boolean;
+declare function useGraphDevTools(): {
+    subscriberCount: number;
+    entityCounts: Record<string, number>;
+    totalEntities: number;
+    listCount: number;
+    patchedEntities: {
+        type: string;
+        id: string;
+    }[];
+    staleEntities: {
+        type: string;
+        id: string;
+    }[];
+    fetchingEntities: {
+        type: string;
+        id: string;
+    }[];
+    lists: {
+        key: string;
+        idCount: number;
+        isFetching: boolean;
+        isStale: boolean;
+    }[];
+};
 
 /**
- * Precompiled transport payloads for one view snapshot — pass to REST, GraphQL, or SQL backends without re-deriving from `ViewDescriptor`.
+ * View-model for one entity row: merged canonical + patch data plus fetch lifecycle flags.
+ * `isLoading` is true only when there is no data yet; `isFetching` includes background refreshes.
  */
-interface ViewFetchParams {
-    rest: Record<string, string>;
-    graphql: ReturnType<typeof toGraphQLVariables>;
-    sql: ReturnType<typeof toSQLClauses>;
-    view: ViewDescriptor;
+interface UseEntityResult<T> {
+    data: T | null;
+    isLoading: boolean;
+    isFetching: boolean;
+    error: string | null;
+    isStale: boolean;
+    refetch: () => void;
 }
 /**
- * Configure a **live view** over a base list: filter/sort/search in JS when data is complete, or compile the same spec to remote params when not.
- * `baseQueryKey` identifies the underlying id list in the graph; the hook may create additional keys for remote result sets.
- */
-interface UseEntityViewOptions<TEntity extends Record<string, unknown>> {
-    type: EntityType;
-    baseQueryKey: unknown[];
-    view: ViewDescriptor;
-    mode?: CompletenessMode;
-    remoteFetch?: (params: ViewFetchParams) => Promise<ListResponse<TEntity>>;
-    normalize?: (raw: TEntity) => {
-        id: EntityId;
-        data: Record<string, unknown>;
-    };
-    remoteDebounce?: number;
-    staleTime?: number;
-    enabled?: boolean;
-    /** SSR-seeded ids written once into `lists[baseKey]` to avoid empty-state flash before hydration fetch. */
-    initialIds?: EntityId[];
-    /** SSR-seeded total for completeness heuristics when ids are preloaded. */
-    initialTotal?: number;
-}
+ * Subscribe to a single normalized entity: populates the graph via `fetch`/`normalize`, dedupes in-flight work, and revalidates when stale.
+ * Solves “query-owned silos” by keeping **one** canonical record every list/detail reads through.
+ *
+ * @param opts - Entity query instruction (`EntityQueryOptions`): `type`, `id`, `fetch`, `normalize`, optional `staleTime` / `enabled`
+ * @returns Merged entity (`entities` + `patches`), loading/error/stale flags, and `refetch`
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, refetch } = useEntity({
+ *   type: "Project",
+ *   id: projectId,
+ *   fetch: (id) => api.getProject(id),
+ *   normalize: (raw) => ({ ...raw, id: String(raw.id) }),
+ * });
+ * ```
+ */
+declare function useEntity<TRaw, TEntity extends Record<string, unknown>>(opts: EntityQueryOptions<TRaw, TEntity>): UseEntityResult<TEntity>;
 /**
- * Rich list UI state: projected `items`/`viewIds`, completeness mode, remote vs local fetching flags, and imperative view updaters.
- * `isShowingLocalPending` signals hybrid mode where stale local rows are visible while a remote round-trip runs.
+ * Resolved rows for a list query: **`items` joins `ids` to the graph** at render time so shared entities update everywhere.
  */
-interface UseEntityViewResult<TEntity> {
+interface UseEntityListResult<TEntity> {
     items: TEntity[];
-    viewIds: EntityId[];
-    viewTotal: number | null;
+    ids: EntityId[];
     isLoading: boolean;
     isFetching: boolean;
-    isRemoteFetching: boolean;
-    isShowingLocalPending: boolean;
+    isFetchingMore: boolean;
     error: string | null;
     hasNextPage: boolean;
+    hasPrevPage: boolean;
+    total: number | null;
+    currentPage: number | null;
     fetchNextPage: () => void;
-    isLocallyComplete: boolean;
-    completenessMode: CompletenessMode;
-    setView: (v: Partial<ViewDescriptor>) => void;
-    setFilter: (f: FilterSpec | null) => void;
-    setSort: (s: SortSpec | null) => void;
-    setSearch: (q: string) => void;
-    clearView: () => void;
     refetch: () => void;
-    isFetchingMore: boolean;
 }
 /**
- * Higher-level list hook: combines **graph-backed id lists**, declarative `ViewDescriptor`, local `applyView`, optional remote fetch, and realtime sorted insertion.
- * Solves “filters tied to one query cache” by deriving the visible id order from the shared graph whenever possible.
+ * Subscribe to a collection: stores **ordered ids** under a serialized `queryKey`, upserts each row into `entities`, and supports pagination.
+ * Use when you need a table or feed backed by the shared graph (not an isolated query cache).
  *
- * @param opts - Base type/key, initial view, optional `remoteFetch` + `normalize`, SSR seeds, forced `mode`
- * @returns Projected entities, view metadata, completeness, and setters for interactive toolbars
+ * @param opts - List query instruction (`ListQueryOptions`)
+ * @returns Hydrated `items`, raw `ids`, pagination helpers, and fetch flags
  *
  * @example
  * ```tsx
- * const view = useEntityView({
+ * const { items, fetchNextPage, hasNextPage } = useEntityList({
  *   type: "Task",
- *   baseQueryKey: ["tasks", projectId],
- *   view: { filter: [{ field: "status", op: "eq", value: "open" }], sort: [{ field: "dueAt", direction: "asc" }] },
- *   remoteFetch: (p) => api.tasksQuery(p.rest),
+ *   queryKey: ["tasks", { projectId }],
+ *   fetch: (p) => api.listTasks({ ...p, projectId }),
  *   normalize: (raw) => ({ id: raw.id, data: raw }),
+ *   mode: "append",
  * });
  * ```
  */
-declare function useEntityView<TEntity extends Record<string, unknown>>(opts: UseEntityViewOptions<TEntity>): UseEntityViewResult<TEntity>;
+declare function useEntityList<TRaw, TEntity extends Record<string, unknown>>(opts: ListQueryOptions<TRaw, TEntity>): UseEntityListResult<TEntity>;
+/**
+ * Options for graph-aware mutations: API call + optional normalization into `entities`, optimistic patches, and targeted invalidation.
+ * Prefer `invalidateLists` prefixes / `invalidateEntities` over ad-hoc store calls so list UIs stay coherent.
+ */
+interface MutationOptions<TInput, TRaw, TEntity extends Record<string, unknown>> {
+    type: EntityType;
+    mutate: (input: TInput) => Promise<TRaw>;
+    normalize?: (raw: TRaw, input: TInput) => {
+        id: EntityId;
+        data: TEntity;
+    };
+    optimistic?: (input: TInput) => {
+        id: EntityId;
+        patch: Partial<TEntity>;
+    } | null;
+    invalidateLists?: string[];
+    invalidateEntities?: Array<{
+        type: EntityType;
+        id: EntityId;
+    }>;
+    onSuccess?: (result: TRaw, input: TInput) => void;
+    onError?: (error: Error, input: TInput) => void;
+}
+/** Imperative mutation handle plus explicit async `state` for UI pending/error/success. */
+interface UseMutationResult<TInput, TRaw> {
+    mutate: (input: TInput) => Promise<TRaw | null>;
+    trigger: (input: TInput) => void;
+    reset: () => void;
+    state: {
+        isPending: boolean;
+        isSuccess: boolean;
+        isError: boolean;
+        error: string | null;
+    };
+}
+/**
+ * Perform writes through your API while keeping the entity graph authoritative: optional optimistic `patchEntity`, commit via `upsertEntity`, rollback on failure.
+ * Use when `useEntity`/`useEntityList` describe reads and you need a consistent mutation story without a second client cache.
+ *
+ * @example
+ * ```tsx
+ * const { mutate, state } = useEntityMutation({
+ *   type: "Task",
+ *   mutate: (input) => api.updateTask(input.id, input.patch),
+ *   normalize: (raw) => ({ id: raw.id, data: raw }),
+ * });
+ * ```
+ */
+declare function useEntityMutation<TInput, TRaw, TEntity extends Record<string, unknown>>(opts: MutationOptions<TInput, TRaw, TEntity>): UseMutationResult<TInput, TRaw>;
+/**
+ * Read/write **UI-only** fields for one entity (`patches` layer) so selection, hover, or transient state is visible in every view that reads that id.
+ * Does not replace `useEntityCRUD`’s edit buffer for form drafts — patches are for shared, non-persisted overlays.
+ *
+ * @param type - Entity kind
+ * @param id - Entity id (no-ops when null/undefined)
+ * @returns Current patch slice and helpers `augment` / `unaugment` / `clear`
+ */
+declare function useEntityAugment<TEntity extends Record<string, unknown>>(type: EntityType, id: EntityId | null | undefined): {
+    patch: Partial<TEntity> | null;
+    augment: (fields: Partial<TEntity>) => void;
+    unaugment: (keys: (keyof TEntity)[]) => void;
+    clear: () => void;
+};
+/**
+ * Suspense-compatible version of `useEntity`. Throws a promise while the entity
+ * is loading, allowing React Suspense boundaries to show fallback UI.
+ * Once data is available, returns the entity data directly (never null).
+ *
+ * @param opts - Same as `useEntity` (`EntityQueryOptions`)
+ * @returns `data` plus `isFetching`, `isStale`, and `refetch`
+ * @throws Promise while loading (caught by the nearest Suspense boundary)
+ * @throws Error if the fetch fails with no data, if `id` is missing when required, or if the entity never resolves
+ */
+declare function useSuspenseEntity<TRaw, TEntity extends Record<string, unknown>>(opts: EntityQueryOptions<TRaw, TEntity>): {
+    data: TEntity;
+    isFetching: boolean;
+    isStale: boolean;
+    refetch: () => void;
+};
+/**
+ * Suspense-compatible version of `useEntityList`. Throws a promise during
+ * initial load, allowing Suspense boundaries to handle loading state.
+ *
+ * @param opts - Same as `useEntityList` (`ListQueryOptions`)
+ * @returns Same shape as `useEntityList` except `isLoading` is omitted (always false when not suspended)
+ * @throws Promise while initially loading (caught by the nearest Suspense boundary)
+ * @throws Error if the fetch fails while the list is still empty
+ */
+declare function useSuspenseEntityList<TRaw, TEntity extends Record<string, unknown>>(opts: ListQueryOptions<TRaw, TEntity>): Omit<UseEntityListResult<TEntity>, "isLoading">;
 
 /**
  * Evaluate `FilterSpec` against one in-memory entity — mirrors remote semantics as closely as plain JS allows.
@@ -936,87 +1230,6 @@ declare function checkCompleteness(loadedCount: number, total: number | null, ha
     reason: string;
 };
 
-/** UI mode for a single CRUD surface: drives which panels/forms are active without scattering boolean flags. */
-type CRUDMode = "list" | "detail" | "edit" | "create";
-/**
- * Wire one entity type into list+detail+forms: remote list via `useEntityView`, optional detail fetch, and create/update/delete callbacks.
- * Mutations call `cascadeInvalidation` on success so related lists/entities refresh per registered schemas.
- */
-interface CRUDOptions<TEntity extends Record<string, unknown>> {
-    type: EntityType;
-    listQueryKey: unknown[];
-    listFetch: (params: ViewFetchParams) => Promise<ListResponse<TEntity>>;
-    normalize: (raw: TEntity) => {
-        id: EntityId;
-        data: TEntity;
-    };
-    detailFetch?: (id: EntityId) => Promise<TEntity>;
-    onCreate?: (data: Partial<TEntity>) => Promise<TEntity>;
-    onUpdate?: (id: EntityId, patch: Partial<TEntity>) => Promise<TEntity>;
-    onDelete?: (id: EntityId) => Promise<void>;
-    createDefaults?: Partial<TEntity>;
-    initialView?: ViewDescriptor;
-    onCreateSuccess?: (entity: TEntity) => void;
-    onUpdateSuccess?: (entity: TEntity) => void;
-    onDeleteSuccess?: (id: EntityId) => void;
-    onError?: (op: "create" | "update" | "delete", error: Error) => void;
-    selectAfterCreate?: boolean;
-    clearSelectionAfterDelete?: boolean;
-}
-/** Tracks which fields diverge from loaded detail — edit buffer stays in React state so other views keep showing canonical graph data until save. */
-interface DirtyFields<TEntity> {
-    changed: Set<keyof TEntity>;
-    isDirty: boolean;
-}
-/**
- * Everything a CRUD screen needs: composed `list` view, selection, detail subscription, relation joins, edit/create buffers, and mutating actions.
- * `applyOptimistic` is the escape hatch to mirror the buffer into `patches` for instant sliders/toggles without committing `save` yet.
- */
-interface CRUDState<TEntity extends Record<string, unknown>> {
-    mode: CRUDMode;
-    setMode: (mode: CRUDMode) => void;
-    list: UseEntityViewResult<TEntity>;
-    selectedId: EntityId | null;
-    select: (id: EntityId | null) => void;
-    openDetail: (id: EntityId) => void;
-    detail: TEntity | null;
-    detailIsLoading: boolean;
-    detailError: string | null;
-    relations: Record<string, unknown>;
-    editBuffer: Partial<TEntity>;
-    setField: <K extends keyof TEntity>(field: K, value: TEntity[K]) => void;
-    setFields: (fields: Partial<TEntity>) => void;
-    resetBuffer: () => void;
-    dirty: DirtyFields<TEntity>;
-    startEdit: (id?: EntityId) => void;
-    cancelEdit: () => void;
-    save: () => Promise<TEntity | null>;
-    isSaving: boolean;
-    saveError: string | null;
-    applyOptimistic: () => void;
-    createBuffer: Partial<TEntity>;
-    setCreateField: <K extends keyof TEntity>(field: K, value: TEntity[K]) => void;
-    setCreateFields: (fields: Partial<TEntity>) => void;
-    resetCreateBuffer: () => void;
-    startCreate: () => void;
-    cancelCreate: () => void;
-    create: () => Promise<TEntity | null>;
-    isCreating: boolean;
-    createError: string | null;
-    deleteEntity: (id?: EntityId) => Promise<void>;
-    isDeleting: boolean;
-    deleteError: string | null;
-    isEditing: boolean;
-}
-/**
- * Batteries-included CRUD orchestration over the entity graph: list filtering/sorting, detail fetch, isolated edit buffer, optimistic create row, and transactional save/delete with rollback.
- * Prefer this over ad-hoc `useEntity` wiring when building admin-style tables + side panels + forms for one resource.
- *
- * @param opts - `CRUDOptions` for type, list key/fetch, normalization, lifecycle callbacks
- * @returns `CRUDState` with list/detail/edit/create controls
- */
-declare function useEntityCRUD<TEntity extends Record<string, unknown>>(opts: CRUDOptions<TEntity>): CRUDState<TEntity>;
-
 /**
  * FK edge: this entity points at one parent row. Used to invalidate parent aggregates and optional list keys when the FK changes.
  */
@@ -1528,50 +1741,6 @@ interface EntityTableProps<T extends Record<string, unknown>> {
 }
 declare function EntityTable<T extends Record<string, unknown>>({ viewResult, columns, getRowId, selectedId, onRowClick, onCellEdit, onBulkAction, paginationMode, pageSize, searchPlaceholder, searchFields, toolbarChildren, showToolbar, emptyState, className }: EntityTableProps<T>): react_jsx_runtime.JSX.Element;
 
-type FieldType = "text" | "textarea" | "number" | "email" | "url" | "date" | "boolean" | "enum" | "custom";
-interface FieldDescriptor<TEntity> {
-    field: keyof TEntity & string;
-    label: string;
-    type: FieldType;
-    required?: boolean;
-    placeholder?: string;
-    options?: Array<{
-        value: string;
-        label: string;
-    }>;
-    hint?: string;
-    render?: (value: unknown, entity: TEntity) => React$1.ReactNode;
-    editControl?: (value: unknown, onChange: (v: unknown) => void, entity: Partial<TEntity>) => React$1.ReactNode;
-    hideOnCreate?: boolean;
-    hideOnEdit?: boolean;
-    readonlyOnEdit?: boolean;
-}
-declare function Sheet({ open, onClose, title, subtitle, children, footer, width }: {
-    open: boolean;
-    onClose: () => void;
-    title: string;
-    subtitle?: string;
-    children: React$1.ReactNode;
-    footer?: React$1.ReactNode;
-    width?: string;
-}): react_jsx_runtime.JSX.Element;
-declare function EntityDetailSheet<TEntity extends Record<string, unknown>>({ crud, fields, title, description, children, showEditButton, showDeleteButton, deleteConfirmMessage }: {
-    crud: CRUDState<TEntity>;
-    fields: FieldDescriptor<TEntity>[];
-    title?: string | ((e: TEntity) => string);
-    description?: string | ((e: TEntity) => string);
-    children?: (entity: TEntity, crud: CRUDState<TEntity>) => React$1.ReactNode;
-    showEditButton?: boolean;
-    showDeleteButton?: boolean;
-    deleteConfirmMessage?: string;
-}): react_jsx_runtime.JSX.Element;
-declare function EntityFormSheet<TEntity extends Record<string, unknown>>({ crud, fields, createTitle, editTitle }: {
-    crud: CRUDState<TEntity>;
-    fields: FieldDescriptor<TEntity>[];
-    createTitle?: string;
-    editTitle?: string | ((e: TEntity) => string);
-}): react_jsx_runtime.JSX.Element;
-
 type ColumnFilterType = "text" | "number" | "date" | "dateRange" | "boolean" | "enum" | "relation" | "none";
 interface EntityColumnMeta<TEntity> {
     field: keyof TEntity;
@@ -2766,4 +2935,4 @@ declare const TableHead: React$1.ForwardRefExoticComponent<React$1.ThHTMLAttribu
 declare const TableCell: React$1.ForwardRefExoticComponent<React$1.TdHTMLAttributes<HTMLTableCellElement> & React$1.RefAttributes<HTMLTableCellElement>>;
 declare const TableCaption: React$1.ForwardRefExoticComponent<React$1.HTMLAttributes<HTMLTableCaptionElement> & React$1.RefAttributes<HTMLTableCaptionElement>>;
 
-export { type AccessorFn, ActionButtonRow, type ActionDef, ActionDropdown, type ActionItem, type ActivePresets, type AdapterStatus, type AggregationFn, type BatchActionDef, type BelongsToRelation, type CRUDMode, type CRUDOptions, type CRUDState, type CascadeContext, type Cell, type CellContext, type CellRenderer, type ChangeOperation, type ChangeSet, type ChannelConfig, type Column, type ColumnFilterType, type ColumnFiltersState, type ColumnOrderState, type ColumnPinningState, type ColumnPreset, ColumnPresetDialog, type ColumnPresetEntry, type ColumnSizingState, type ColumnVisibilityState, type CompletenessMode, DataTable, DataTableColumnHeader, DataTableFilter, DataTablePagination, DataTableToolbar, type DirtyFields, type ElectricAdapterOptions, ElectricSQLAdapter as ElectricSQLPresetAdapter, type ElectricSQLAdapterOptions as ElectricSQLPresetAdapterOptions, type ElectricTableConfig, EmptyState, type EmptyStateConfig, type EngineOptions, type EntityChange, type EntityColumnMeta, type EntityDescriptor, EntityDetailSheet, EntityFormSheet, type EntityId, EntityListView, type EntityListViewProps, type EntityQueryOptions, type EntitySchema, type EntitySnapshot, type EntityState, type EntitySyncMetadata, EntityTable, type EntityType, type ExpandedState, type FieldDescriptor, type FieldType, type FilterClause, type FilterFn, type FilterGroup, type FilterOperator, type FilterPreset, FilterPresetDialog, type FilterSpec, GQLClient, type GQLClientConfig, type GQLEntityOptions, type GQLError, type GQLListOptions, type GQLResponse, type GalleryColumns, GalleryView, type GraphActionOptions, type GraphEffectEvent, type GraphEffectHandle, type GraphEffectOptions, type GraphIncludeMap, type GraphIncludeRelation, type GraphQueryOptions, type GraphSnapshotExportOptions, type GraphState, type GraphToolContext, type GraphTransaction, type GroupingState, type HasManyRelation, type Header, type HeaderContext, type HeaderGroup, type HeaderRenderer, InlineCellEditor$1 as InlineCellEditor, InlineItemEditor, type ItemDescriptor, type ItemDescriptorBadge, type ItemDescriptorMeta, type ItemRenderContext, type ListFetchParams, type ListQueryOptions, type ListResponse, type ListState, ListView, type ManagerOptions, type ManyToManyRelation, MemoryAdapter, MultiSelectBar, type PaginationState, type PresetChangeEvent, type PresetChangeOperation, PresetPicker, type PresetStoreState, type UnsubscribeFn as PresetUnsubscribeFn, type PrismaEntityConfigOptions, type ColumnDef as PureColumnDef, type ColumnMeta as PureColumnMeta, InlineCellEditor as PureInlineCellEditor, type QueryKey, type RealtimeAdapter, RealtimeManager, type RelationDescriptor, type RestAdapterOptions, RestApiAdapter, type Row, type RowModel, type RowSelectionState, SelectionContext, type SelectionStoreState, Sheet, type SortClause, type SortDirection, SortHeader, type SortSpec, type SortingFn, type SortingState, type SubscriptionConfig, type SupabaseAdapterOptions$1 as SupabaseAdapterOptions, SupabaseRealtimeAdapter as SupabasePresetAdapter, type SupabaseAdapterOptions as SupabasePresetAdapterOptions, type SyncAdapter, type SyncOrigin, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, type TableInstance, type TableOptions, type TablePresetSlice, TableRow, type TableState, type TableStorageAdapter, TableStorageProvider, type TableStorageProviderProps, type UnsubscribeFn$1 as UnsubscribeFn, type Updater, type UseEntityViewOptions, type UseEntityViewResult, type UseLocalFirstResult, type UseTablePresetsOptions, type UseTablePresetsResult, type ViewDescriptor, type ViewFetchParams, type ViewMode, ViewModeSwitcher, type WebSocketAdapterOptions, type ZustandAdapterOptions, ZustandPersistAdapter, actionsColumn$1 as actionsColumn, applyView, booleanColumn$1 as booleanColumn, cascadeInvalidation, checkCompleteness, compareEntities, configureEngine, createConvexAdapter, createElectricAdapter, createGQLClient, createGraphAction, createGraphEffect, createGraphQLSubscriptionAdapter, createGraphTool, createGraphTransaction, createPresetStore, createPrismaEntityConfig, createRow, createSelectionStore, createSupabaseRealtimeAdapter, createWebSocketAdapter, dateColumn$1 as dateColumn, dedupe, deleteAction, editAction, enumColumn$1 as enumColumn, executeGQL, exportGraphSnapshot, fetchEntity, fetchList, flattenClauses, getCoreRowModel, getExpandedRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGroupedRowModel, getPaginatedRowModel, getRealtimeManager, getSchema, getSelectedRowModel, getSortedRowModel, hasCustomPredicates, matchesFilter, matchesSearch, normalizeGQLResponse, numberColumn$1 as numberColumn, prismaRelationsToSchema, actionsColumn as pureActionsColumn, booleanColumn as pureBooleanColumn, dateColumn as pureDateColumn, enumColumn as pureEnumColumn, numberColumn as pureNumberColumn, selectionColumn as pureSelectionColumn, textColumn as pureTextColumn, queryOnce, readRelations, registerSchema, resetRealtimeManager, selectGraph, selectionColumn$1 as selectionColumn, serializeKey, startGarbageCollector, stopGarbageCollector, textColumn$1 as textColumn, toGraphQLVariables, toPrismaInclude, toPrismaOrderBy, toPrismaWhere, toRestParams, toSQLClauses, useEntity, useEntityAugment, useEntityCRUD, useEntityList, useEntityMutation, useEntityView, useGQLEntity, useGQLList, useGQLMutation, useGQLSubscription, useGraphDevTools, useGraphStore, useLocalFirst, usePGliteQuery, useSelectionContext, useSelectionStore, useSuspenseEntity, useSuspenseEntityList, useTable, useTablePresets, useTableRealtimeMode, useTableStorageAdapter, viewAction };
+export { type AccessorFn, ActionButtonRow, type ActionDef, ActionDropdown, type ActionItem, type ActivePresets, type AdapterStatus, type AggregationFn, type BatchActionDef, type BelongsToRelation, type BuildEntityFieldsFromSchemaOptions, type CRUDMode, type CRUDOptions, type CRUDState, type CascadeContext, type Cell, type CellContext, type CellRenderer, type ChangeOperation, type ChangeSet, type ChannelConfig, type Column, type ColumnFilterType, type ColumnFiltersState, type ColumnOrderState, type ColumnPinningState, type ColumnPreset, ColumnPresetDialog, type ColumnPresetEntry, type ColumnSizingState, type ColumnVisibilityState, type CompletenessMode, DataTable, DataTableColumnHeader, DataTableFilter, DataTablePagination, DataTableToolbar, type DirtyFields, type ElectricAdapterOptions, ElectricSQLAdapter as ElectricSQLPresetAdapter, type ElectricSQLAdapterOptions as ElectricSQLPresetAdapterOptions, type ElectricTableConfig, EmptyState, type EmptyStateConfig, type EngineOptions, type EntityChange, type EntityColumnMeta, type EntityDescriptor, EntityDetailSheet, EntityFormSheet, type EntityId, type EntityJsonSchemaConfig, EntityListView, type EntityListViewProps, type EntityQueryOptions, type EntitySchema, type EntitySnapshot, type EntityState, type EntitySyncMetadata, EntityTable, type EntityType, type ExpandedState, type FieldDescriptor, type FieldType, type FilterClause, type FilterFn, type FilterGroup, type FilterOperator, type FilterPreset, FilterPresetDialog, type FilterSpec, GQLClient, type GQLClientConfig, type GQLEntityOptions, type GQLError, type GQLListOptions, type GQLResponse, type GalleryColumns, GalleryView, type GraphActionEvent, type GraphActionOptions, type GraphActionRecord$1 as GraphActionRecord, type GraphEffectEvent, type GraphEffectHandle, type GraphEffectOptions, type GraphIncludeMap, type GraphIncludeRelation, type GraphPersistenceAdapter, type GraphQueryOptions, type GraphSnapshotExportOptions, type GraphSnapshotPayload, type GraphSnapshotWithSchemasOptions, type GraphState, type GraphSyncStatus, type GraphToolContext, type GraphTransaction, type GroupingState, type HasManyRelation, type Header, type HeaderContext, type HeaderGroup, type HeaderRenderer, InlineCellEditor$1 as InlineCellEditor, InlineItemEditor, type ItemDescriptor, type ItemDescriptorBadge, type ItemDescriptorMeta, type ItemRenderContext, type JsonSchemaObject, type ListFetchParams, type ListQueryOptions, type ListResponse, type ListState, ListView, type LocalFirstGraphRuntime, type ManagerOptions, type ManyToManyRelation, MarkdownFieldEditor, MarkdownFieldRenderer, MemoryAdapter, MultiSelectBar, type PaginationState, type GraphActionRecord as PersistedGraphActionRecord, type PresetChangeEvent, type PresetChangeOperation, PresetPicker, type PresetStoreState, type UnsubscribeFn as PresetUnsubscribeFn, type PrismaEntityConfigOptions, type ColumnDef as PureColumnDef, type ColumnMeta as PureColumnMeta, InlineCellEditor as PureInlineCellEditor, type QueryKey, type RealtimeAdapter, RealtimeManager, type RelationDescriptor, type RestAdapterOptions, RestApiAdapter, type Row, type RowModel, type RowSelectionState, type SchemaFieldDescriptor, type SchemaGraphToolContext, SelectionContext, type SelectionStoreState, Sheet, type SortClause, type SortDirection, SortHeader, type SortSpec, type SortingFn, type SortingState, type StartLocalFirstGraphOptions, type SubscriptionConfig, type SupabaseAdapterOptions$1 as SupabaseAdapterOptions, SupabaseRealtimeAdapter as SupabasePresetAdapter, type SupabaseAdapterOptions as SupabasePresetAdapterOptions, type SyncAdapter, type SyncOrigin, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, type TableInstance, type TableOptions, type TablePresetSlice, TableRow, type TableState, type TableStorageAdapter, TableStorageProvider, type TableStorageProviderProps, type UnsubscribeFn$1 as UnsubscribeFn, type Updater, type UseEntityViewOptions, type UseEntityViewResult, type UseLocalFirstResult, type UseTablePresetsOptions, type UseTablePresetsResult, type ViewDescriptor, type ViewFetchParams, type ViewMode, ViewModeSwitcher, type WebSocketAdapterOptions, type ZustandAdapterOptions, ZustandPersistAdapter, actionsColumn$1 as actionsColumn, applyView, booleanColumn$1 as booleanColumn, buildEntityFieldsFromSchema, cascadeInvalidation, checkCompleteness, compareEntities, configureEngine, createConvexAdapter, createElectricAdapter, createGQLClient, createGraphAction, createGraphEffect, createGraphQLSubscriptionAdapter, createGraphTool, createGraphTransaction, createPresetStore, createPrismaEntityConfig, createRow, createSchemaGraphTool, createSelectionStore, createSupabaseRealtimeAdapter, createWebSocketAdapter, dateColumn$1 as dateColumn, dedupe, deleteAction, editAction, enumColumn$1 as enumColumn, executeGQL, exportGraphSnapshot, exportGraphSnapshotWithSchemas, fetchEntity, fetchList, flattenClauses, getCoreRowModel, getEntityJsonSchema, getExpandedRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGroupedRowModel, getPaginatedRowModel, getRealtimeManager, getSchema, getSelectedRowModel, getSortedRowModel, hasCustomPredicates, hydrateGraphFromStorage, matchesFilter, matchesSearch, normalizeGQLResponse, numberColumn$1 as numberColumn, persistGraphToStorage, prismaRelationsToSchema, actionsColumn as pureActionsColumn, booleanColumn as pureBooleanColumn, dateColumn as pureDateColumn, enumColumn as pureEnumColumn, numberColumn as pureNumberColumn, selectionColumn as pureSelectionColumn, textColumn as pureTextColumn, queryOnce, readRelations, registerEntityJsonSchema, registerRuntimeSchema, registerSchema, renderMarkdownToHtml, resetRealtimeManager, selectGraph, selectionColumn$1 as selectionColumn, serializeKey, startGarbageCollector, startLocalFirstGraph, stopGarbageCollector, textColumn$1 as textColumn, toGraphQLVariables, toPrismaInclude, toPrismaOrderBy, toPrismaWhere, toRestParams, toSQLClauses, useEntity, useEntityAugment, useEntityCRUD, useEntityList, useEntityMutation, useEntityView, useGQLEntity, useGQLList, useGQLMutation, useGQLSubscription, useGraphDevTools, useGraphStore, useGraphSyncStatus, useLocalFirst, usePGliteQuery, useSchemaEntityFields, useSelectionContext, useSelectionStore, useSuspenseEntity, useSuspenseEntityList, useTable, useTablePresets, useTableRealtimeMode, useTableStorageAdapter, viewAction };