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

package/dist/index.mjs

@@ -1,13 +1,13 @@
 import { create, createStore, useStore } from 'zustand';
 import { subscribeWithSelector, persist } from 'zustand/middleware';
 import { immer } from 'zustand/middleware/immer';
-import React5, { createContext, useSyncExternalStore, useMemo, useRef, useCallback, useEffect, useState, useContext, useId } from 'react';
+import React6, { createContext, useMemo, useSyncExternalStore, useRef, useCallback, useEffect, useState, useContext, useId } from 'react';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { useShallow } from 'zustand/react/shallow';
 import { useReactTable, getSortedRowModel, getCoreRowModel, flexRender } from '@tanstack/react-table';
 import { Search, X, Loader2, RefreshCw, ChevronLeft, ChevronRight, Pencil, Trash2 } from 'lucide-react';
 import { clsx } from 'clsx';
 import { twMerge } from 'tailwind-merge';
-import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
 // src/graph.ts
 var EMPTY_IDS = [];
@@ -17,6 +17,11 @@ var EMPTY_ENTITY_STATE = {
   error: null,
   stale: false
 };
+var EMPTY_SYNC_METADATA = {
+  synced: true,
+  origin: "server",
+  updatedAt: null
+};
 var EMPTY_LIST_STATE = {
   ids: EMPTY_IDS,
   total: null,
@@ -35,6 +40,9 @@ var EMPTY_LIST_STATE = {
 function defaultEntityState() {
   return { ...EMPTY_ENTITY_STATE };
 }
+function defaultSyncMetadata() {
+  return { ...EMPTY_SYNC_METADATA };
+}
 function defaultListState() {
   return { ...EMPTY_LIST_STATE, ids: [] };
 }
@@ -47,24 +55,33 @@ var useGraphStore = create()(
       entities: {},
       patches: {},
       entityStates: {},
+      syncMetadata: {},
       lists: {},
       upsertEntity: (type, id, data) => set((s) => {
         if (!s.entities[type]) s.entities[type] = {};
         s.entities[type][id] = { ...s.entities[type][id] ?? {}, ...data };
+        const key = ek(type, id);
+        if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
       }),
       upsertEntities: (type, entries) => set((s) => {
         if (!s.entities[type]) s.entities[type] = {};
-        for (const { id, data } of entries)
+        for (const { id, data } of entries) {
           s.entities[type][id] = { ...s.entities[type][id] ?? {}, ...data };
+          const key = ek(type, id);
+          if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
+        }
       }),
       replaceEntity: (type, id, data) => set((s) => {
         if (!s.entities[type]) s.entities[type] = {};
         s.entities[type][id] = data;
+        const key = ek(type, id);
+        if (!s.syncMetadata[key]) s.syncMetadata[key] = defaultSyncMetadata();
       }),
       removeEntity: (type, id) => set((s) => {
         delete s.entities[type]?.[id];
         delete s.patches[type]?.[id];
         delete s.entityStates[ek(type, id)];
+        delete s.syncMetadata[ek(type, id)];
       }),
       patchEntity: (type, id, patch) => set((s) => {
         if (!s.patches[type]) s.patches[type] = {};
@@ -96,12 +113,20 @@ var useGraphStore = create()(
         s.entityStates[k].isFetching = false;
         s.entityStates[k].error = null;
         s.entityStates[k].stale = false;
+        s.syncMetadata[k] = { ...s.syncMetadata[k] ?? defaultSyncMetadata(), synced: true, origin: "server", updatedAt: Date.now() };
       }),
       setEntityStale: (type, id, stale) => set((s) => {
         const k = ek(type, id);
         if (!s.entityStates[k]) s.entityStates[k] = defaultEntityState();
         s.entityStates[k].stale = stale;
       }),
+      setEntitySyncMetadata: (type, id, metadata) => set((s) => {
+        const k = ek(type, id);
+        s.syncMetadata[k] = { ...s.syncMetadata[k] ?? defaultSyncMetadata(), ...metadata };
+      }),
+      clearEntitySyncMetadata: (type, id) => set((s) => {
+        delete s.syncMetadata[ek(type, id)];
+      }),
       setListResult: (key, ids, meta) => set((s) => {
         const ex = s.lists[key] ?? defaultListState();
         s.lists[key] = { ...ex, ...meta, ids, isFetching: false, isFetchingMore: false, error: null, stale: false, lastFetched: Date.now() };
@@ -173,11 +198,717 @@ var useGraphStore = create()(
         if (!base) return null;
         const patch = s.patches[type]?.[id];
         return patch ? { ...base, ...patch } : base;
+      },
+      readEntitySnapshot: (type, id) => {
+        const s = get();
+        const base = s.entities[type]?.[id];
+        if (!base) return null;
+        const patch = s.patches[type]?.[id];
+        const metadata = s.syncMetadata[ek(type, id)] ?? EMPTY_SYNC_METADATA;
+        return {
+          ...patch ? { ...base, ...patch } : base,
+          $synced: metadata.synced,
+          $origin: metadata.origin,
+          $updatedAt: metadata.updatedAt
+        };
       }
     }))
   )
 );
 
+// src/graph-query.ts
+function queryOnce(opts) {
+  const store = useGraphStore.getState();
+  const ids = resolveCandidateIds(store, opts);
+  let rows = ids.map((id) => store.readEntitySnapshot(opts.type, id)).filter((row) => row !== null);
+  if (opts.where) rows = rows.filter(opts.where);
+  if (opts.sort) rows = [...rows].sort(opts.sort);
+  const projected = rows.map((row) => applySelection(projectRow(row, opts.include, store), opts.select));
+  if (opts.id) return projected[0] ?? null;
+  return projected;
+}
+var selectGraph = queryOnce;
+function resolveCandidateIds(store, opts) {
+  if (opts.id) return [opts.id];
+  if (opts.ids) return opts.ids;
+  if (opts.listKey) return store.lists[opts.listKey]?.ids ?? [];
+  return Object.keys(store.entities[opts.type] ?? {});
+}
+function projectRow(row, include, store) {
+  if (!include) return row;
+  const projected = { ...row };
+  for (const [key, relation] of Object.entries(include)) {
+    const related = resolveRelation(row, relation, store);
+    projected[key] = related;
+  }
+  return projected;
+}
+function resolveRelation(entity, relation, store) {
+  const include = relation.include;
+  switch (relation.via.kind) {
+    case "field": {
+      const relatedId = entity[relation.via.field];
+      if (typeof relatedId !== "string") return null;
+      const related = store.readEntitySnapshot(relation.type, relatedId);
+      return related ? projectRow(related, include, store) : null;
+    }
+    case "array": {
+      const ids = entity[relation.via.field];
+      if (!Array.isArray(ids)) return [];
+      return ids.map((id) => typeof id === "string" ? store.readEntitySnapshot(relation.type, id) : null).filter((row) => row !== null).map((row) => projectRow(row, include, store));
+    }
+    case "list": {
+      const key = typeof relation.via.key === "function" ? relation.via.key(entity) : relation.via.key;
+      if (!key) return [];
+      const ids = store.lists[key]?.ids ?? [];
+      return ids.map((id) => store.readEntitySnapshot(relation.type, id)).filter((row) => row !== null).map((row) => projectRow(row, include, store));
+    }
+    case "resolver": {
+      const resolved = relation.via.resolve(entity, store);
+      if (Array.isArray(resolved)) {
+        return resolved.map((id) => store.readEntitySnapshot(relation.type, id)).filter((row) => row !== null).map((row) => projectRow(row, include, store));
+      }
+      if (typeof resolved !== "string") return null;
+      const related = store.readEntitySnapshot(relation.type, resolved);
+      return related ? projectRow(related, include, store) : null;
+    }
+  }
+}
+function applySelection(row, select) {
+  if (!select) return row;
+  if (typeof select === "function") {
+    const result = select(row);
+    return result && typeof result === "object" ? result : { value: result };
+  }
+  const picked = {};
+  for (const key of select) {
+    if (key in row) picked[key] = row[key];
+  }
+  return picked;
+}
+
+// src/graph-actions.ts
+var graphActionListeners = /* @__PURE__ */ new Set();
+var graphActionReplayers = /* @__PURE__ */ new Map();
+function createGraphTransaction() {
+  const baseline = cloneGraphData();
+  let closed = false;
+  const tx = {
+    upsertEntity(type, id, data) {
+      useGraphStore.getState().upsertEntity(type, id, data);
+      return tx;
+    },
+    replaceEntity(type, id, data) {
+      useGraphStore.getState().replaceEntity(type, id, data);
+      return tx;
+    },
+    removeEntity(type, id) {
+      useGraphStore.getState().removeEntity(type, id);
+      return tx;
+    },
+    patchEntity(type, id, patch) {
+      useGraphStore.getState().patchEntity(type, id, patch);
+      return tx;
+    },
+    clearPatch(type, id) {
+      useGraphStore.getState().clearPatch(type, id);
+      return tx;
+    },
+    insertIdInList(key, id, position) {
+      useGraphStore.getState().insertIdInList(key, id, position);
+      return tx;
+    },
+    removeIdFromAllLists(type, id) {
+      useGraphStore.getState().removeIdFromAllLists(type, id);
+      return tx;
+    },
+    setEntitySyncMetadata(type, id, metadata) {
+      useGraphStore.getState().setEntitySyncMetadata(type, id, metadata);
+      return tx;
+    },
+    markEntityPending(type, id, origin = "optimistic") {
+      useGraphStore.getState().setEntitySyncMetadata(type, id, {
+        synced: false,
+        origin,
+        updatedAt: Date.now()
+      });
+      return tx;
+    },
+    markEntitySynced(type, id, origin = "server") {
+      useGraphStore.getState().setEntitySyncMetadata(type, id, {
+        synced: true,
+        origin,
+        updatedAt: Date.now()
+      });
+      return tx;
+    },
+    commit() {
+      closed = true;
+    },
+    rollback() {
+      if (closed) return;
+      useGraphStore.setState(cloneGraphData(baseline));
+      closed = true;
+    },
+    snapshot() {
+      return cloneGraphData();
+    }
+  };
+  return tx;
+}
+function createGraphAction(opts) {
+  if (opts.key) {
+    graphActionReplayers.set(opts.key, async (record) => {
+      const tx = createGraphTransaction();
+      try {
+        const result = await opts.run(tx, record.input);
+        tx.commit();
+        return result;
+      } catch (error) {
+        tx.rollback();
+        throw error;
+      }
+    });
+  }
+  return async (input) => {
+    const tx = createGraphTransaction();
+    const record = opts.key ? {
+      id: `${opts.key}:${Date.now()}`,
+      key: opts.key,
+      input: structuredClone(input),
+      enqueuedAt: (/* @__PURE__ */ new Date()).toISOString()
+    } : null;
+    try {
+      if (record) emitGraphActionEvent({ type: "enqueued", record });
+      opts.optimistic?.(tx, input);
+      const result = await opts.run(tx, input);
+      opts.onSuccess?.(result, input, tx);
+      tx.commit();
+      if (record) emitGraphActionEvent({ type: "settled", record });
+      return result;
+    } catch (error) {
+      tx.rollback();
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      if (record) emitGraphActionEvent({ type: "settled", record });
+      opts.onError?.(normalized, input);
+      throw normalized;
+    }
+  };
+}
+function subscribeGraphActionEvents(listener) {
+  graphActionListeners.add(listener);
+  return () => graphActionListeners.delete(listener);
+}
+async function replayRegisteredGraphAction(record) {
+  const replayer = graphActionReplayers.get(record.key);
+  if (!replayer) throw new Error(`No graph action registered for key "${record.key}"`);
+  return replayer(record);
+}
+function cloneGraphData(source = useGraphStore.getState()) {
+  return {
+    entities: structuredClone(source.entities),
+    patches: structuredClone(source.patches),
+    entityStates: structuredClone(source.entityStates),
+    syncMetadata: structuredClone(source.syncMetadata),
+    lists: structuredClone(source.lists)
+  };
+}
+function emitGraphActionEvent(event) {
+  for (const listener of graphActionListeners) listener(event);
+}
+
+// src/graph-effects.ts
+function createGraphEffect(opts) {
+  const getKey = opts.getKey ?? defaultGetKey;
+  const isEqual = opts.isEqual ?? defaultIsEqual;
+  let initialized = false;
+  let previous = /* @__PURE__ */ new Map();
+  const evaluate = () => {
+    const nextValues = normalizeQueryResult(opts.query());
+    const next = /* @__PURE__ */ new Map();
+    nextValues.forEach((value, index) => {
+      next.set(getKey(value, index), value);
+    });
+    if (!initialized) {
+      initialized = true;
+      previous = next;
+      if (opts.skipInitial) return;
+    }
+    for (const [key, value] of next.entries()) {
+      const previousValue = previous.get(key);
+      if (previousValue === void 0) {
+        opts.onEnter?.({ key, value });
+        continue;
+      }
+      if (!isEqual(previousValue, value)) {
+        opts.onUpdate?.({ key, value, previousValue });
+      }
+    }
+    for (const [key, previousValue] of previous.entries()) {
+      if (!next.has(key)) opts.onExit?.({ key, previousValue });
+    }
+    previous = next;
+  };
+  evaluate();
+  const unsubscribe = useGraphStore.subscribe(() => {
+    evaluate();
+  });
+  return {
+    dispose: () => {
+      unsubscribe();
+    }
+  };
+}
+function normalizeQueryResult(value) {
+  if (value == null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function defaultGetKey(value, index) {
+  if (value && typeof value === "object") {
+    const record = value;
+    if (typeof record.id === "string") return record.id;
+    if (typeof record.$key === "string") return record.$key;
+  }
+  return String(index);
+}
+function defaultIsEqual(previousValue, nextValue) {
+  return JSON.stringify(previousValue) === JSON.stringify(nextValue);
+}
+
+// src/object-path.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getValueAtPath(source, path) {
+  if (!path) return source;
+  const segments = path.split(".").filter(Boolean);
+  let current = source;
+  for (const segment of segments) {
+    if (!isObject(current) && !Array.isArray(current)) return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function setValueAtPath(source, path, value) {
+  const segments = path.split(".").filter(Boolean);
+  if (segments.length === 0) return source;
+  const clone = structuredClone(source);
+  let current = clone;
+  for (let index = 0; index < segments.length - 1; index += 1) {
+    const segment = segments[index];
+    const next = current[segment];
+    if (!isObject(next)) current[segment] = {};
+    current = current[segment];
+  }
+  current[segments[segments.length - 1]] = value;
+  return clone;
+}
+function collectDirtyPaths(current, original, prefix = "", acc = /* @__PURE__ */ new Set()) {
+  if (isObject(current) && isObject(original)) {
+    const keys = /* @__PURE__ */ new Set([...Object.keys(current), ...Object.keys(original)]);
+    for (const key of keys) {
+      const nextPrefix = prefix ? `${prefix}.${key}` : key;
+      collectDirtyPaths(current[key], original[key], nextPrefix, acc);
+    }
+    return acc;
+  }
+  if (JSON.stringify(current) !== JSON.stringify(original) && prefix) acc.add(prefix);
+  return acc;
+}
+var schemaRegistry = /* @__PURE__ */ new Map();
+function registerEntityJsonSchema(config) {
+  const key = registryKey(config.entityType, config.field, config.schemaId);
+  schemaRegistry.set(key, config);
+}
+function registerRuntimeSchema(config) {
+  registerEntityJsonSchema(config);
+}
+function getEntityJsonSchema(opts) {
+  const exact = schemaRegistry.get(registryKey(opts.entityType, opts.field, opts.schemaId));
+  if (exact) return exact;
+  if (opts.field) {
+    const byField = schemaRegistry.get(registryKey(opts.entityType, opts.field));
+    if (byField) return byField;
+  }
+  if (opts.schemaId) {
+    const byId = schemaRegistry.get(registryKey(opts.entityType, void 0, opts.schemaId));
+    if (byId) return byId;
+  }
+  for (const schema of schemaRegistry.values()) {
+    if (schema.entityType !== opts.entityType) continue;
+    if (opts.field && schema.field !== opts.field) continue;
+    return schema;
+  }
+  return null;
+}
+function useSchemaEntityFields(opts) {
+  return useMemo(() => {
+    const schema = opts.schema ?? getEntityJsonSchema(opts)?.schema;
+    if (!schema) return [];
+    return buildEntityFieldsFromSchema({ schema, rootField: opts.rootField ?? opts.field });
+  }, [opts.entityType, opts.field, opts.rootField, opts.schemaId, opts.schema]);
+}
+function buildEntityFieldsFromSchema(opts) {
+  return buildSchemaFields(opts.schema, opts.rootField ?? "", "");
+}
+function exportGraphSnapshotWithSchemas(opts) {
+  return JSON.stringify(
+    {
+      scope: opts.scope,
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      data: opts.data,
+      schemas: opts.schemas.filter(Boolean)
+    },
+    null,
+    opts.pretty === false ? 0 : 2
+  );
+}
+function escapeHtml(input) {
+  return input.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+function renderMarkdownToHtml(value) {
+  const escaped = escapeHtml(value);
+  const blocks = escaped.split(/\n{2,}/).map((block) => block.trim()).filter(Boolean);
+  return blocks.map((block) => renderMarkdownBlock(block)).join("");
+}
+function MarkdownFieldRenderer({ value, className }) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className,
+      dangerouslySetInnerHTML: { __html: renderMarkdownToHtml(value ?? "") }
+    }
+  );
+}
+function MarkdownFieldEditor({
+  value,
+  onChange,
+  placeholder
+}) {
+  return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-2", children: [
+    /* @__PURE__ */ jsx(
+      "textarea",
+      {
+        value,
+        onChange: (event) => onChange(event.target.value),
+        placeholder,
+        className: "w-full min-h-[120px] rounded-md border bg-muted/50 px-3 py-2 text-sm resize-y focus:outline-none focus:ring-1 focus:ring-ring transition-colors"
+      }
+    ),
+    /* @__PURE__ */ jsx("div", { className: "rounded-md border bg-background px-3 py-2", children: /* @__PURE__ */ jsx(MarkdownFieldRenderer, { value, className: "prose prose-sm max-w-none" }) })
+  ] });
+}
+function createMarkdownDetailRenderer(field) {
+  return (value, entity) => /* @__PURE__ */ jsx(MarkdownFieldRenderer, { value: String(value ?? getValueAtPath(entity, field) ?? ""), className: "prose prose-sm max-w-none" });
+}
+function buildSchemaFields(schema, pathPrefix, schemaPathPrefix) {
+  if (schema.type === "object" && schema.properties) {
+    const entries = Object.entries(schema.properties).sort(([, left], [, right]) => {
+      const l = left["x-display-order"] ?? Number.MAX_SAFE_INTEGER;
+      const r = right["x-display-order"] ?? Number.MAX_SAFE_INTEGER;
+      return l - r;
+    });
+    return entries.flatMap(([key, childSchema]) => {
+      if (childSchema["x-hidden"]) return [];
+      const field = pathPrefix ? `${pathPrefix}.${key}` : key;
+      const schemaPath = schemaPathPrefix ? `${schemaPathPrefix}.${key}` : key;
+      if (childSchema.type === "object" && childSchema.properties) {
+        return buildSchemaFields(childSchema, field, schemaPath);
+      }
+      return [schemaField(field, schemaPath, childSchema, schema.required?.includes(key) ?? false)];
+    });
+  }
+  return [];
+}
+function schemaField(field, schemaPath, schema, required) {
+  const type = inferFieldType(schema);
+  const descriptor = {
+    field,
+    label: schema.title ?? humanize(field.split(".").pop() ?? field),
+    type,
+    required,
+    hint: schema.description,
+    schemaPath,
+    schema,
+    componentHint: schema["x-a2ui-component"]
+  };
+  if (schema.enum) {
+    descriptor.options = schema.enum.map((value) => ({
+      value: String(value),
+      label: String(value)
+    }));
+  }
+  if (type === "markdown") {
+    descriptor.render = createMarkdownDetailRenderer(field);
+  }
+  return descriptor;
+}
+function inferFieldType(schema) {
+  const forced = schema["x-field-type"];
+  if (forced === "markdown") return "markdown";
+  if (schema.format === "markdown") return "markdown";
+  if (schema.enum) return "enum";
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  switch (type) {
+    case "boolean":
+      return "boolean";
+    case "integer":
+    case "number":
+      return "number";
+    case "string":
+      if (schema.format === "email") return "email";
+      if (schema.format === "uri" || schema.format === "url") return "url";
+      if (schema.format === "date" || schema.format === "date-time") return "date";
+      return "text";
+    case "array":
+    case "object":
+      return "json";
+    default:
+      return "text";
+  }
+}
+function registryKey(entityType, field, schemaId) {
+  return `${entityType}::${field ?? "*"}::${schemaId ?? "*"}`;
+}
+function humanize(value) {
+  return value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function renderMarkdownBlock(block) {
+  if (block.startsWith("# ")) return `<h1>${renderInlineMarkdown(block.slice(2))}</h1>`;
+  if (block.startsWith("## ")) return `<h2>${renderInlineMarkdown(block.slice(3))}</h2>`;
+  return `<p>${renderInlineMarkdown(block).replaceAll("\n", "<br/>")}</p>`;
+}
+function renderInlineMarkdown(block) {
+  return block.replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>");
+}
+
+// src/ai-interop.ts
+function exportGraphSnapshot(opts) {
+  const payload = {
+    scope: opts.scope,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    data: opts.data
+  };
+  return JSON.stringify(payload, null, opts.pretty === false ? 0 : 2);
+}
+function createGraphTool(handler) {
+  return (input) => handler(input, {
+    store: useGraphStore.getState(),
+    queryOnce,
+    exportGraphSnapshot
+  });
+}
+function createSchemaGraphTool(handler) {
+  return (input) => handler(input, {
+    store: useGraphStore.getState(),
+    queryOnce,
+    exportGraphSnapshot,
+    getEntityJsonSchema,
+    exportGraphSnapshotWithSchemas
+  });
+}
+var DEFAULT_STORAGE_KEY = "prometheus:graph";
+var useGraphSyncStatusStore = create((set) => ({
+  status: {
+    phase: "idle",
+    isOnline: true,
+    isSynced: true,
+    pendingActions: 0,
+    lastHydratedAt: null,
+    lastPersistedAt: null,
+    storageKey: null,
+    error: null
+  },
+  setStatus: (status) => set((state) => ({
+    status: {
+      ...state.status,
+      ...status
+    }
+  }))
+}));
+var pendingActions = /* @__PURE__ */ new Map();
+function useGraphSyncStatus() {
+  return useGraphSyncStatusStore((state) => state.status);
+}
+async function persistGraphToStorage(opts) {
+  const payload = {
+    version: 1,
+    snapshot: cloneGraphSnapshot(),
+    pendingActions: opts.pendingActions ?? Array.from(pendingActions.values())
+  };
+  const json = JSON.stringify(payload);
+  await opts.storage.set(opts.key, json);
+  const persistedAt = (/* @__PURE__ */ new Date()).toISOString();
+  useGraphSyncStatusStore.getState().setStatus({
+    lastPersistedAt: persistedAt,
+    storageKey: opts.key,
+    pendingActions: payload.pendingActions.length
+  });
+  return {
+    ok: true,
+    key: opts.key,
+    bytes: json.length,
+    persistedAt
+  };
+}
+async function hydrateGraphFromStorage(opts) {
+  const raw = await opts.storage.get(opts.key);
+  if (!raw) {
+    return {
+      ok: false,
+      key: opts.key,
+      hydratedAt: null,
+      entityCounts: {},
+      error: "No persisted graph snapshot found"
+    };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    useGraphStore.setState(parsed.snapshot);
+    pendingActions.clear();
+    for (const action of parsed.pendingActions ?? []) pendingActions.set(action.id, action);
+    const hydratedAt = (/* @__PURE__ */ new Date()).toISOString();
+    useGraphSyncStatusStore.getState().setStatus({
+      lastHydratedAt: hydratedAt,
+      storageKey: opts.key,
+      pendingActions: pendingActions.size,
+      error: null
+    });
+    return {
+      ok: true,
+      key: opts.key,
+      hydratedAt,
+      entityCounts: Object.fromEntries(
+        Object.entries(parsed.snapshot.entities).map(([type, entities]) => [type, Object.keys(entities).length])
+      ),
+      pendingActions: Array.from(pendingActions.values())
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    useGraphSyncStatusStore.getState().setStatus({
+      phase: "error",
+      error: message,
+      storageKey: opts.key
+    });
+    return {
+      ok: false,
+      key: opts.key,
+      hydratedAt: null,
+      entityCounts: {},
+      error: message
+    };
+  }
+}
+function startLocalFirstGraph(opts) {
+  const key = opts.key ?? DEFAULT_STORAGE_KEY;
+  const persistDebounceMs = opts.persistDebounceMs ?? 50;
+  const statusStore = useGraphSyncStatusStore.getState();
+  statusStore.setStatus({
+    phase: "hydrating",
+    storageKey: key,
+    isOnline: opts.onlineSource?.getIsOnline() ?? getDefaultOnlineSource().getIsOnline(),
+    isSynced: pendingActions.size === 0,
+    error: null
+  });
+  let persistTimer = null;
+  const schedulePersist = () => {
+    if (persistTimer) clearTimeout(persistTimer);
+    persistTimer = setTimeout(() => {
+      void persistGraphToStorage({ storage: opts.storage, key });
+    }, persistDebounceMs);
+  };
+  const graphUnsub = useGraphStore.subscribe(() => {
+    schedulePersist();
+  });
+  const actionUnsub = subscribeGraphActionEvents((event) => {
+    if (event.type === "enqueued") pendingActions.set(event.record.id, event.record);
+    if (event.type === "settled") pendingActions.delete(event.record.id);
+    useGraphSyncStatusStore.getState().setStatus({
+      pendingActions: pendingActions.size,
+      isSynced: pendingActions.size === 0
+    });
+    schedulePersist();
+  });
+  const onlineSource = opts.onlineSource ?? getDefaultOnlineSource();
+  const onlineUnsub = onlineSource.subscribe((online) => {
+    useGraphSyncStatusStore.getState().setStatus({
+      isOnline: online,
+      phase: online ? "ready" : "offline"
+    });
+  });
+  const ready = (async () => {
+    const hydrated = await hydrateGraphFromStorage({ storage: opts.storage, key });
+    if (opts.replayPendingActions && hydrated.ok && pendingActions.size > 0) {
+      useGraphSyncStatusStore.getState().setStatus({
+        phase: "syncing",
+        isSynced: false
+      });
+      for (const action of Array.from(pendingActions.values())) {
+        await replayRegisteredGraphAction(action);
+        pendingActions.delete(action.id);
+      }
+      await persistGraphToStorage({ storage: opts.storage, key });
+    }
+    const online = onlineSource.getIsOnline();
+    useGraphSyncStatusStore.getState().setStatus({
+      phase: online ? "ready" : "offline",
+      isOnline: online,
+      isSynced: pendingActions.size === 0,
+      pendingActions: pendingActions.size
+    });
+  })();
+  return {
+    ready,
+    dispose() {
+      graphUnsub();
+      actionUnsub();
+      onlineUnsub();
+      if (persistTimer) clearTimeout(persistTimer);
+    },
+    async persistNow() {
+      await persistGraphToStorage({ storage: opts.storage, key });
+    },
+    hydrate() {
+      return hydrateGraphFromStorage({ storage: opts.storage, key });
+    },
+    getStatus() {
+      return useGraphSyncStatusStore.getState().status;
+    }
+  };
+}
+function cloneGraphSnapshot() {
+  const state = useGraphStore.getState();
+  return {
+    entities: structuredClone(state.entities),
+    patches: structuredClone(state.patches),
+    entityStates: structuredClone(state.entityStates),
+    syncMetadata: structuredClone(state.syncMetadata),
+    lists: structuredClone(state.lists)
+  };
+}
+function getDefaultOnlineSource() {
+  if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    return {
+      getIsOnline: () => window.navigator.onLine,
+      subscribe: (listener) => {
+        const onlineHandler = () => listener(true);
+        const offlineHandler = () => listener(false);
+        window.addEventListener("online", onlineHandler);
+        window.addEventListener("offline", offlineHandler);
+        return () => {
+          window.removeEventListener("online", onlineHandler);
+          window.removeEventListener("offline", offlineHandler);
+        };
+      }
+    };
+  }
+  return {
+    getIsOnline: () => true,
+    subscribe: () => () => {
+    }
+  };
+}
+
 // src/engine.ts
 function serializeKey(key) {
   return JSON.stringify(key, (_, v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort()) : v);
@@ -445,10 +1176,7 @@ function useEntity(opts) {
   normalizeRef.current = opts.normalize;
   const data = useStore(useGraphStore, useShallow((state) => {
     if (!id) return null;
-    const base = state.entities[type]?.[id];
-    if (!base) return null;
-    const patch = state.patches[type]?.[id];
-    return patch ? { ...base, ...patch } : base;
+    return state.readEntitySnapshot(type, id);
   }));
   const entityState = useStore(useGraphStore, useCallback(
     (state) => state.entityStates[`${type}:${id}`] ?? EMPTY_ENTITY_STATE,
@@ -486,12 +1214,7 @@ function useEntityList(opts) {
     useGraphStore,
     useShallow((state) => {
       const ids = state.lists[key]?.ids ?? EMPTY_IDS;
-      return ids.map((id) => {
-        const base = state.entities[type]?.[id];
-        if (!base) return null;
-        const patch = state.patches[type]?.[id];
-        return patch ? { ...base, ...patch } : base;
-      }).filter((x) => x !== null);
+      return ids.map((id) => state.readEntitySnapshot(type, id)).filter((x) => x !== null);
     })
   );
   const doFetch = useCallback((params = {}) => {
@@ -528,18 +1251,28 @@ function useEntityMutation(opts) {
         const { id, patch } = opt;
         const store = useGraphStore.getState();
         const previous = { ...store.patches[type]?.[id] };
+        const previousSync = store.syncMetadata[`${type}:${id}`];
         store.patchEntity(type, id, patch);
-        rollback = () => Object.keys(previous).length > 0 ? useGraphStore.getState().patchEntity(type, id, previous) : useGraphStore.getState().clearPatch(type, id);
+        store.setEntitySyncMetadata(type, id, { synced: false, origin: "optimistic", updatedAt: Date.now() });
+        rollback = () => {
+          const currentStore = useGraphStore.getState();
+          if (Object.keys(previous).length > 0) currentStore.patchEntity(type, id, previous);
+          else currentStore.clearPatch(type, id);
+          if (previousSync) currentStore.setEntitySyncMetadata(type, id, previousSync);
+          else currentStore.clearEntitySyncMetadata(type, id);
+        };
       }
     }
     try {
       const result = await apiFn(input);
       if (normalize) {
         const { id, data } = normalize(result, input);
-        useGraphStore.getState().upsertEntity(type, id, data);
+        const store = useGraphStore.getState();
+        store.upsertEntity(type, id, data);
+        store.setEntitySyncMetadata(type, id, { synced: true, origin: "server", updatedAt: Date.now() });
         if (optimistic) {
           const opt = optimistic(input);
-          if (opt) useGraphStore.getState().clearPatch(type, opt.id);
+          if (opt) store.clearPatch(type, opt.id);
         }
       }
       if (invalidateLists) for (const k of invalidateLists) useGraphStore.getState().invalidateLists(k);
@@ -1041,12 +1774,7 @@ function useEntityView(opts) {
     useShallow((state) => {
       const list = state.lists[baseKey] ?? EMPTY_LIST_STATE;
       const sourceIds = completenessMode !== "remote" && remoteResultKey ? state.lists[remoteResultKey]?.ids ?? EMPTY_IDS : list.ids;
-      const getEntity = (id) => {
-        const base = state.entities[type]?.[id];
-        if (!base) return null;
-        const patch = state.patches[type]?.[id];
-        return patch ? { ...base, ...patch } : base;
-      };
+      const getEntity = (id) => state.readEntitySnapshot(type, id);
       return applyView(
         sourceIds,
         getEntity,
@@ -1059,12 +1787,7 @@ function useEntityView(opts) {
   const items = useStore(
     useGraphStore,
     useShallow(
-      (state) => localViewIds.map((id) => {
-        const base = state.entities[type]?.[id];
-        if (!base) return null;
-        const patch = state.patches[type]?.[id];
-        return patch ? { ...base, ...patch } : base;
-      }).filter((item) => item !== null)
+      (state) => localViewIds.map((id) => state.readEntitySnapshot(type, id)).filter((item) => item !== null)
     )
   );
   const fireRemoteFetch = useCallback(async (view, cursor) => {
@@ -1119,17 +1842,11 @@ function useEntityView(opts) {
         const isPresent = id in newEntities;
         if (!isPresent) continue;
         const entity = newEntities[id];
-        const patch = store.patches[type]?.[id];
-        const merged = patch ? { ...entity, ...patch } : entity;
+        const merged = store.readEntitySnapshot(type, id) ?? entity;
         const matches = (!view.filter || matchesFilter(merged, view.filter)) && (!view.search?.query || matchesSearch(merged, view.search.query, view.search.fields));
         if (matches && !list.ids.includes(id)) {
           if (view.sort && view.sort.length > 0) {
-            const idx = findInsertionIndex(merged, list.ids, (eid) => {
-              const b = store.entities[type]?.[eid];
-              if (!b) return null;
-              const p = store.patches[type]?.[eid];
-              return p ? { ...b, ...p } : b;
-            }, view.sort);
+            const idx = findInsertionIndex(merged, list.ids, (eid) => store.readEntitySnapshot(type, eid), view.sort);
             store.insertIdInList(baseKey, id, idx);
           } else store.insertIdInList(baseKey, id, "start");
         }
@@ -1172,15 +1889,15 @@ function useEntityView(opts) {
 }
 
 // src/crud/relations.ts
-var schemaRegistry = /* @__PURE__ */ new Map();
+var schemaRegistry2 = /* @__PURE__ */ new Map();
 function registerSchema(schema) {
-  schemaRegistry.set(schema.type, schema);
+  schemaRegistry2.set(schema.type, schema);
 }
 function getSchema(type) {
-  return schemaRegistry.get(type) ?? null;
+  return schemaRegistry2.get(type) ?? null;
 }
 function cascadeInvalidation(ctx) {
-  const schema = schemaRegistry.get(ctx.type);
+  const schema = schemaRegistry2.get(ctx.type);
   if (!schema) return;
   const store = useGraphStore.getState();
   if (schema.globalListKeys) for (const key of schema.globalListKeys) store.invalidateLists(key);
@@ -1207,7 +1924,7 @@ function cascadeInvalidation(ctx) {
       }
     }
   }
-  for (const [, otherSchema] of schemaRegistry) {
+  for (const [, otherSchema] of schemaRegistry2) {
     if (!otherSchema.relations) continue;
     for (const [, rel] of Object.entries(otherSchema.relations)) {
       if (rel.targetType !== ctx.type) continue;
@@ -1216,7 +1933,7 @@ function cascadeInvalidation(ctx) {
   }
 }
 function readRelations(type, entity) {
-  const schema = schemaRegistry.get(type);
+  const schema = schemaRegistry2.get(type);
   if (!schema?.relations) return {};
   const store = useGraphStore.getState();
   const result = {};
@@ -1277,7 +1994,7 @@ function useEntityCRUD(opts) {
   useEffect(() => {
     if (detail) setEditBuffer({ ...detail });
   }, [selectedId]);
-  const setField = useCallback((field, value) => setEditBuffer((prev) => ({ ...prev, [field]: value })), []);
+  const setField = useCallback((field, value) => setEditBuffer((prev) => setValueAtPath(prev, String(field), value)), []);
   const setFields = useCallback((fields) => setEditBuffer((prev) => ({ ...prev, ...fields })), []);
   const resetBuffer = useCallback(() => {
     const current = selectedId ? useGraphStore.getState().readEntity(type, selectedId) : null;
@@ -1285,10 +2002,7 @@ function useEntityCRUD(opts) {
   }, [type, selectedId]);
   const dirty = useMemo(() => {
     if (!detail) return { changed: /* @__PURE__ */ new Set(), isDirty: false };
-    const changed = /* @__PURE__ */ new Set();
-    for (const key of Object.keys(editBuffer)) {
-      if (JSON.stringify(editBuffer[key]) !== JSON.stringify(detail[key])) changed.add(key);
-    }
+    const changed = collectDirtyPaths(editBuffer, detail);
     return { changed, isDirty: changed.size > 0 };
   }, [editBuffer, detail]);
   const startEdit = useCallback((id) => {
@@ -1307,25 +2021,33 @@ function useEntityCRUD(opts) {
   }, [resetBuffer, selectedId]);
   const applyOptimistic = useCallback(() => {
     if (!selectedId) return;
-    useGraphStore.getState().patchEntity(type, selectedId, editBuffer);
+    const store = useGraphStore.getState();
+    store.patchEntity(type, selectedId, editBuffer);
+    store.setEntitySyncMetadata(type, selectedId, { synced: false, origin: "optimistic", updatedAt: Date.now() });
   }, [type, selectedId, editBuffer]);
   const save = useCallback(async () => {
     if (!selectedId || !onUpdate) return null;
     setIsSaving(true);
     setSaveError(null);
-    const previous = useGraphStore.getState().readEntity(type, selectedId);
-    useGraphStore.getState().upsertEntity(type, selectedId, editBuffer);
+    const store = useGraphStore.getState();
+    const previous = store.readEntity(type, selectedId);
+    const previousSync = store.syncMetadata[`${type}:${selectedId}`];
+    store.upsertEntity(type, selectedId, editBuffer);
+    store.setEntitySyncMetadata(type, selectedId, { synced: false, origin: "optimistic", updatedAt: Date.now() });
     try {
       const result = await onUpdate(selectedId, editBuffer);
       const { id, data } = normalize(result);
-      useGraphStore.getState().replaceEntity(type, id, data);
-      useGraphStore.getState().clearPatch(type, id);
+      store.replaceEntity(type, id, data);
+      store.clearPatch(type, id);
+      store.setEntitySyncMetadata(type, id, { synced: true, origin: "server", updatedAt: Date.now() });
       cascadeInvalidation({ type, id: selectedId, previous, next: data, op: "update" });
       setMode("detail");
       optsRef.current.onUpdateSuccess?.(result);
       return result;
     } catch (err) {
-      if (previous) useGraphStore.getState().replaceEntity(type, selectedId, previous);
+      if (previous) store.replaceEntity(type, selectedId, previous);
+      if (previousSync) store.setEntitySyncMetadata(type, selectedId, previousSync);
+      else store.clearEntitySyncMetadata(type, selectedId);
       const error = err instanceof Error ? err : new Error(String(err));
       setSaveError(error.message);
       optsRef.current.onError?.("update", error);
@@ -1337,7 +2059,7 @@ function useEntityCRUD(opts) {
   const [createBuffer, setCreateBuffer] = useState({ ...createDefaults });
   const [isCreating, setIsCreating] = useState(false);
   const [createError, setCreateError] = useState(null);
-  const setCreateField = useCallback((field, value) => setCreateBuffer((prev) => ({ ...prev, [field]: value })), []);
+  const setCreateField = useCallback((field, value) => setCreateBuffer((prev) => setValueAtPath(prev, String(field), value)), []);
   const setCreateFields = useCallback((fields) => setCreateBuffer((prev) => ({ ...prev, ...fields })), []);
   const resetCreateBuffer = useCallback(() => setCreateBuffer({ ...optsRef.current.createDefaults ?? {} }), []);
   const startCreate = useCallback(() => {
@@ -1350,21 +2072,23 @@ function useEntityCRUD(opts) {
     setMode("list");
     setCreateError(null);
   }, [resetCreateBuffer]);
-  const create2 = useCallback(async () => {
+  const create3 = useCallback(async () => {
     if (!onCreate) return null;
     setIsCreating(true);
     setCreateError(null);
     const tempId = `__temp__${Date.now()}`;
     const optimisticData = { ...createBuffer, id: tempId, _optimistic: true };
-    useGraphStore.getState().upsertEntity(type, tempId, optimisticData);
-    useGraphStore.getState().insertIdInList(serializeKey(listQueryKey), tempId, "start");
+    const store = useGraphStore.getState();
+    store.upsertEntity(type, tempId, optimisticData);
+    store.setEntitySyncMetadata(type, tempId, { synced: false, origin: "optimistic", updatedAt: Date.now() });
+    store.insertIdInList(serializeKey(listQueryKey), tempId, "start");
     try {
       const result = await onCreate(createBuffer);
       const { id: realId, data } = normalize(result);
-      useGraphStore.getState().removeEntity(type, tempId);
-      useGraphStore.getState().upsertEntity(type, realId, data);
-      useGraphStore.getState().setEntityFetched(type, realId);
-      const store = useGraphStore.getState();
+      store.removeEntity(type, tempId);
+      store.upsertEntity(type, realId, data);
+      store.setEntityFetched(type, realId);
+      store.setEntitySyncMetadata(type, realId, { synced: true, origin: "server", updatedAt: Date.now() });
       for (const key of Object.keys(store.lists)) {
         const list2 = store.lists[key];
         const idx = list2.ids.indexOf(tempId);
@@ -1382,8 +2106,8 @@ function useEntityCRUD(opts) {
       optsRef.current.onCreateSuccess?.(result);
       return result;
     } catch (err) {
-      useGraphStore.getState().removeEntity(type, tempId);
-      useGraphStore.getState().removeIdFromAllLists(type, tempId);
+      store.removeEntity(type, tempId);
+      store.removeIdFromAllLists(type, tempId);
       const error = err instanceof Error ? err : new Error(String(err));
       setCreateError(error.message);
       optsRef.current.onError?.("create", error);
@@ -1422,7 +2146,7 @@ function useEntityCRUD(opts) {
       setIsDeleting(false);
     }
   }, [type, selectedId, listQueryKey, clearSelectionAfterDelete]);
-  return { mode, setMode, list, selectedId, select, openDetail, detail: detail ?? null, detailIsLoading, detailError: detailError ?? null, relations, editBuffer, setField, setFields, resetBuffer, dirty, startEdit, cancelEdit, save, isSaving, saveError, applyOptimistic, createBuffer, setCreateField, setCreateFields, resetCreateBuffer, startCreate, cancelCreate, create: create2, isCreating, createError, deleteEntity, isDeleting, deleteError, isEditing: mode === "edit" || mode === "create" };
+  return { mode, setMode, list, selectedId, select, openDetail, detail: detail ?? null, detailIsLoading, detailError: detailError ?? null, relations, editBuffer, setField, setFields, resetBuffer, dirty, startEdit, cancelEdit, save, isSaving, saveError, applyOptimistic, createBuffer, setCreateField, setCreateFields, resetCreateBuffer, startCreate, cancelCreate, create: create3, isCreating, createError, deleteEntity, isDeleting, deleteError, isEditing: mode === "edit" || mode === "create" };
 }
 
 // src/adapters/realtime-manager.ts
@@ -2187,10 +2911,7 @@ function useGQLEntity(opts) {
   optsRef.current = opts;
   const data = useStore(useGraphStore, useShallow((s) => {
     if (!id) return null;
-    const base = s.entities[type]?.[id];
-    if (!base) return null;
-    const patch = s.patches[type]?.[id];
-    return patch ? { ...base, ...patch } : base;
+    return s.readEntitySnapshot(type, id);
   }));
   const entityState = useStore(useGraphStore, useCallback(
     (s) => s.entityStates[`${type}:${id}`] ?? EMPTY_ENTITY_STATE,
@@ -2236,12 +2957,7 @@ function useGQLList(opts) {
     useGraphStore,
     useShallow((s) => {
       const ids = s.lists[key]?.ids ?? EMPTY_IDS;
-      return ids.map((id) => {
-        const base = s.entities[type]?.[id];
-        if (!base) return null;
-        const p = s.patches[type]?.[id];
-        return p ? { ...base, ...p } : base;
-      }).filter((x) => x !== null);
+      return ids.map((id) => s.readEntitySnapshot(type, id)).filter((x) => x !== null);
     })
   );
   const doFetch = useCallback((cursor, append = false) => {
@@ -2478,7 +3194,7 @@ function EntityTable({ viewResult, columns, getRowId = (r) => String(r.id), sele
   ] });
 }
 function Sheet({ open, onClose, title, subtitle, children, footer, width = "w-[480px]" }) {
-  React5.useEffect(() => {
+  React6.useEffect(() => {
     const h = (e) => {
       if (e.key === "Escape") onClose();
     };
@@ -2514,6 +3230,8 @@ function FieldControl({ descriptor, value, onChange, entity, readonly }) {
       return /* @__PURE__ */ jsx("input", { type: "number", value: String(value ?? ""), onChange: (e) => onChange(e.target.valueAsNumber), placeholder: descriptor.placeholder, className: base });
     case "textarea":
       return /* @__PURE__ */ jsx("textarea", { value: String(value ?? ""), onChange: (e) => onChange(e.target.value), placeholder: descriptor.placeholder, className: "w-full min-h-[80px] rounded-md border bg-muted/50 px-3 py-2 text-sm resize-none focus:outline-none focus:ring-1 focus:ring-ring transition-colors" });
+    case "markdown":
+      return /* @__PURE__ */ jsx(MarkdownFieldEditor, { value: String(value ?? ""), onChange: (nextValue) => onChange(nextValue), placeholder: descriptor.placeholder });
     case "date":
       return /* @__PURE__ */ jsx("input", { type: "date", value: value ? new Date(value).toISOString().split("T")[0] : "", onChange: (e) => onChange(e.target.value ? new Date(e.target.value).toISOString() : null), className: base });
     case "boolean":
@@ -2533,12 +3251,35 @@ function FieldControl({ descriptor, value, onChange, entity, readonly }) {
         !value && /* @__PURE__ */ jsx("option", { value: "", children: "Select\u2026" }),
         (descriptor.options ?? []).map((o) => /* @__PURE__ */ jsx("option", { value: o.value, children: o.label }, o.value))
       ] });
+    case "json":
+      return /* @__PURE__ */ jsx(
+        "textarea",
+        {
+          value: value != null ? JSON.stringify(value, null, 2) : "",
+          onChange: (event) => {
+            const nextValue = event.target.value;
+            try {
+              onChange(nextValue ? JSON.parse(nextValue) : null);
+            } catch {
+              onChange(nextValue);
+            }
+          },
+          placeholder: descriptor.placeholder,
+          className: "w-full min-h-[120px] rounded-md border bg-muted/50 px-3 py-2 text-sm font-mono resize-y focus:outline-none focus:ring-1 focus:ring-ring transition-colors"
+        }
+      );
     default:
       return /* @__PURE__ */ jsx("input", { value: String(value ?? ""), onChange: (e) => onChange(e.target.value), className: base });
   }
 }
+function FieldReadonlyValue({ descriptor, value, entity }) {
+  if (descriptor.render) return /* @__PURE__ */ jsx(Fragment, { children: descriptor.render(value, entity) });
+  if (descriptor.type === "markdown") return /* @__PURE__ */ jsx(MarkdownFieldRenderer, { value: String(value ?? ""), className: "prose prose-sm max-w-none py-1" });
+  if (descriptor.type === "json") return /* @__PURE__ */ jsx("pre", { className: "text-xs py-1 whitespace-pre-wrap break-words", children: JSON.stringify(value ?? null, null, 2) });
+  return /* @__PURE__ */ jsx("p", { className: "text-sm py-1", children: value != null && value !== "" ? String(value) : "\u2014" });
+}
 function EntityDetailSheet({ crud, fields, title = "Details", description, children, showEditButton = true, showDeleteButton = true, deleteConfirmMessage = "This action cannot be undone." }) {
-  const [confirmDelete, setConfirmDelete] = React5.useState(false);
+  const [confirmDelete, setConfirmDelete] = React6.useState(false);
   const open = crud.mode === "detail" && !!crud.selectedId;
   const entity = crud.detail;
   const resolvedTitle = entity && typeof title === "function" ? title(entity) : String(title);
@@ -2562,8 +3303,7 @@ function EntityDetailSheet({ crud, fields, title = "Details", description, child
         entity && /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-4", children: [
           fields.map((f) => /* @__PURE__ */ jsxs("div", { children: [
             /* @__PURE__ */ jsx("p", { className: "text-[10px] font-medium text-muted-foreground uppercase tracking-wide mb-1", children: f.label }),
-            /* @__PURE__ */ jsx(FieldControl, { descriptor: f, value: entity[f.field], onChange: () => {
-            }, entity, readonly: true })
+            /* @__PURE__ */ jsx(FieldReadonlyValue, { descriptor: f, value: getValueAtPath(entity, f.field), entity })
           ] }, f.field)),
           children && /* @__PURE__ */ jsxs(Fragment, { children: [
             /* @__PURE__ */ jsx("div", { className: "border-t my-1" }),
@@ -2633,13 +3373,14 @@ function EntityFormSheet({ crud, fields, createTitle = "Create", editTitle = "Ed
         error && /* @__PURE__ */ jsx("div", { className: "px-3 py-2 rounded-md bg-destructive/10 border border-destructive/20 text-xs text-destructive", children: error }),
         visibleFields.map((f) => {
           const isDirty = !isCreate && crud.dirty.changed.has(f.field);
+          const currentValue = getValueAtPath(buf, f.field);
           return /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1.5", children: [
             /* @__PURE__ */ jsxs("label", { className: cn("text-xs font-medium", isDirty ? "text-primary" : "text-muted-foreground"), children: [
               f.label,
               f.required && /* @__PURE__ */ jsx("span", { className: "text-destructive ml-0.5", children: "*" }),
               isDirty && /* @__PURE__ */ jsx("span", { className: "ml-1.5 text-[10px] font-normal opacity-70", children: "modified" })
             ] }),
-            /* @__PURE__ */ jsx(FieldControl, { descriptor: f, value: buf[f.field], onChange: (v) => setField(f.field, v), entity: buf, readonly: f.readonlyOnEdit && isEdit }),
+            /* @__PURE__ */ jsx(FieldControl, { descriptor: f, value: currentValue, onChange: (v) => setField(f.field, v), entity: buf, readonly: f.readonlyOnEdit && isEdit }),
             f.hint && /* @__PURE__ */ jsx("p", { className: "text-[10px] text-muted-foreground", children: f.hint })
           ] }, f.field);
         })
@@ -3840,9 +4581,9 @@ function createSelectionStore() {
 function useSelectionStore(store, selector) {
   return useStore(store, selector);
 }
-var SelectionContext = React5.createContext(null);
+var SelectionContext = React6.createContext(null);
 function useSelectionContext() {
-  const store = React5.useContext(SelectionContext);
+  const store = React6.useContext(SelectionContext);
   if (!store) throw new Error("useSelectionContext must be used within a SelectionContext.Provider");
   return store;
 }
@@ -4757,7 +5498,7 @@ function useTableStorageAdapter() {
 function useTableRealtimeMode() {
   return useContext(TableStorageContext).realtimeMode;
 }
-var Table = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("div", { className: "relative w-full overflow-auto", children: /* @__PURE__ */ jsx(
+var Table = React6.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("div", { className: "relative w-full overflow-auto", children: /* @__PURE__ */ jsx(
   "table",
   {
     ref,
@@ -4766,11 +5507,11 @@ var Table = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */
   }
 ) }));
 Table.displayName = "Table";
-var TableHeader = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("thead", { ref, className: cn("bg-muted/60", className), ...props }));
+var TableHeader = React6.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("thead", { ref, className: cn("bg-muted/60", className), ...props }));
 TableHeader.displayName = "TableHeader";
-var TableBody = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("tbody", { ref, className: cn("bg-background", className), ...props }));
+var TableBody = React6.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("tbody", { ref, className: cn("bg-background", className), ...props }));
 TableBody.displayName = "TableBody";
-var TableFooter = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+var TableFooter = React6.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
   "tfoot",
   {
     ref,
@@ -4779,7 +5520,7 @@ var TableFooter = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE
   }
 ));
 TableFooter.displayName = "TableFooter";
-var TableRow = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+var TableRow = React6.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
   "tr",
   {
     ref,
@@ -4791,7 +5532,7 @@ var TableRow = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__
   }
 ));
 TableRow.displayName = "TableRow";
-var TableHead = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+var TableHead = React6.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
   "th",
   {
     ref,
@@ -4803,7 +5544,7 @@ var TableHead = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__
   }
 ));
 TableHead.displayName = "TableHead";
-var TableCell = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+var TableCell = React6.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
   "td",
   {
     ref,
@@ -4815,7 +5556,7 @@ var TableCell = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__
   }
 ));
 TableCell.displayName = "TableCell";
-var TableCaption = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+var TableCaption = React6.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
   "caption",
   {
     ref,
@@ -6334,7 +7075,7 @@ function ChevronsRightIcon({ className }) {
   ] });
 }
 function EmptyState({ config, isFiltered = false, className }) {
-  if (React5.isValidElement(config)) {
+  if (React6.isValidElement(config)) {
     return /* @__PURE__ */ jsx(Fragment, { children: config });
   }
   const cfg = config ?? {};
@@ -7734,13 +8475,13 @@ function selectionColumn2() {
     enableFiltering: false,
     enableHiding: false,
     enableResizing: false,
-    header: ({ table }) => React5.createElement("input", {
+    header: ({ table }) => React6.createElement("input", {
       type: "checkbox",
       checked: table.getIsAllPageRowsSelected(),
       onChange: table.getToggleAllPageRowsSelectedHandler(),
       className: "h-4 w-4 rounded border-primary text-primary focus:ring-ring"
     }),
-    cell: ({ row }) => React5.createElement("input", {
+    cell: ({ row }) => React6.createElement("input", {
       type: "checkbox",
       checked: row.getIsSelected(),
       onChange: row.getToggleSelectedHandler(),
@@ -7876,7 +8617,7 @@ function enumColumn2(options) {
       const opt = options.options.find((o) => o.value === val);
       if (!opt) return val;
       if (opt.badgeClassName) {
-        return React5.createElement(
+        return React6.createElement(
           "span",
           {
             className: `inline-flex items-center rounded px-1.5 py-0.5 text-[11px] font-medium capitalize ${opt.badgeClassName}`
@@ -7884,7 +8625,7 @@ function enumColumn2(options) {
           opt.label
         );
       }
-      return React5.createElement(
+      return React6.createElement(
         "span",
         {
           className: "inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium",
@@ -7921,6 +8662,6 @@ function actionsColumn2() {
   };
 }
 
-export { ActionButtonRow, ActionDropdown, ColumnPresetDialog, DataTable, DataTableColumnHeader, DataTableFilter, DataTablePagination, DataTableToolbar, ElectricSQLAdapter as ElectricSQLPresetAdapter, EmptyState, EntityDetailSheet, EntityFormSheet, EntityListView, EntityTable, FilterPresetDialog, GQLClient, GalleryView, InlineCellEditor, InlineItemEditor, ListView, MemoryAdapter, MultiSelectBar, PresetPicker, InlineCellEditor2 as PureInlineCellEditor, RealtimeManager, RestApiAdapter, SelectionContext, Sheet, SortHeader, SupabaseRealtimeAdapter as SupabasePresetAdapter, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, TableStorageProvider, ViewModeSwitcher, ZustandPersistAdapter, actionsColumn, applyView, booleanColumn, cascadeInvalidation, checkCompleteness, compareEntities, configureEngine, createConvexAdapter, createElectricAdapter, createGQLClient, createGraphQLSubscriptionAdapter, createPresetStore, createPrismaEntityConfig, createRow, createSelectionStore, createSupabaseRealtimeAdapter, createWebSocketAdapter, dateColumn, dedupe, deleteAction, editAction, enumColumn, executeGQL, fetchEntity, fetchList, flattenClauses, getCoreRowModel2 as getCoreRowModel, getExpandedRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGroupedRowModel, getPaginatedRowModel, getRealtimeManager, getSchema, getSelectedRowModel, getSortedRowModel2 as getSortedRowModel, hasCustomPredicates, matchesFilter, matchesSearch, normalizeGQLResponse, numberColumn, prismaRelationsToSchema, actionsColumn2 as pureActionsColumn, booleanColumn2 as pureBooleanColumn, dateColumn2 as pureDateColumn, enumColumn2 as pureEnumColumn, numberColumn2 as pureNumberColumn, selectionColumn2 as pureSelectionColumn, textColumn2 as pureTextColumn, readRelations, registerSchema, resetRealtimeManager, selectionColumn, serializeKey, startGarbageCollector, stopGarbageCollector, 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 { ActionButtonRow, ActionDropdown, ColumnPresetDialog, DataTable, DataTableColumnHeader, DataTableFilter, DataTablePagination, DataTableToolbar, ElectricSQLAdapter as ElectricSQLPresetAdapter, EmptyState, EntityDetailSheet, EntityFormSheet, EntityListView, EntityTable, FilterPresetDialog, GQLClient, GalleryView, InlineCellEditor, InlineItemEditor, ListView, MarkdownFieldEditor, MarkdownFieldRenderer, MemoryAdapter, MultiSelectBar, PresetPicker, InlineCellEditor2 as PureInlineCellEditor, RealtimeManager, RestApiAdapter, SelectionContext, Sheet, SortHeader, SupabaseRealtimeAdapter as SupabasePresetAdapter, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, TableStorageProvider, ViewModeSwitcher, ZustandPersistAdapter, actionsColumn, applyView, booleanColumn, buildEntityFieldsFromSchema, cascadeInvalidation, checkCompleteness, compareEntities, configureEngine, createConvexAdapter, createElectricAdapter, createGQLClient, createGraphAction, createGraphEffect, createGraphQLSubscriptionAdapter, createGraphTool, createGraphTransaction, createPresetStore, createPrismaEntityConfig, createRow, createSchemaGraphTool, createSelectionStore, createSupabaseRealtimeAdapter, createWebSocketAdapter, dateColumn, dedupe, deleteAction, editAction, enumColumn, executeGQL, exportGraphSnapshot, exportGraphSnapshotWithSchemas, fetchEntity, fetchList, flattenClauses, getCoreRowModel2 as getCoreRowModel, getEntityJsonSchema, getExpandedRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getGroupedRowModel, getPaginatedRowModel, getRealtimeManager, getSchema, getSelectedRowModel, getSortedRowModel2 as getSortedRowModel, hasCustomPredicates, hydrateGraphFromStorage, matchesFilter, matchesSearch, normalizeGQLResponse, numberColumn, persistGraphToStorage, prismaRelationsToSchema, actionsColumn2 as pureActionsColumn, booleanColumn2 as pureBooleanColumn, dateColumn2 as pureDateColumn, enumColumn2 as pureEnumColumn, numberColumn2 as pureNumberColumn, selectionColumn2 as pureSelectionColumn, textColumn2 as pureTextColumn, queryOnce, readRelations, registerEntityJsonSchema, registerRuntimeSchema, registerSchema, renderMarkdownToHtml, resetRealtimeManager, selectGraph, selectionColumn, serializeKey, startGarbageCollector, startLocalFirstGraph, stopGarbageCollector, 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 };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map