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

package/CHANGELOG.md

@@ -5,6 +5,46 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ---
 
+## [1.2.0] — 2026-04-05
+
+PWA/local-first and schema-driven entity release focused on dynamic JSON-column UI, markdown-aware rendering, and IPC-safe graph persistence.
+
+### Added
+
+- Local-first runtime helpers: `startLocalFirstGraph(...)`, `hydrateGraphFromStorage(...)`, `persistGraphToStorage(...)`, and `useGraphSyncStatus()`.
+- Serializable pending graph action records and replay hooks for persisted optimistic workflows.
+- JSON Schema registry APIs: `registerEntityJsonSchema(...)`, `registerRuntimeSchema(...)`, `getEntityJsonSchema(...)`, `buildEntityFieldsFromSchema(...)`, and `useSchemaEntityFields(...)`.
+- Built-in markdown support with `MarkdownFieldRenderer`, `MarkdownFieldEditor`, and schema-driven `format: "markdown"` field generation.
+- Schema-aware AI helpers: `createSchemaGraphTool(...)` and `exportGraphSnapshotWithSchemas(...)`.
+- Vitest coverage for persisted graph hydration, pending action replay, schema-driven field generation, runtime schema replacement, and safe markdown rendering.
+
+### Changed
+
+- `EntityFormSheet` and related CRUD state now support dotted field paths for nested JSON-column editing.
+- `FieldType` now includes `json` and `markdown`.
+- Public docs and API references now describe the local-first runtime and schema/A2UI-oriented dynamic entity surface.
+
+## [1.1.0] — 2026-04-05
+
+Graph-runtime expansion release focused on TanStack DB comparison gaps without changing the library’s core React entity-graph architecture.
+
+### Added
+
+- Graph runtime snapshot helpers: `queryOnce(...)` and `selectGraph(...)`.
+- Nested graph projection support via graph-native `include` definitions.
+- Explicit optimistic write primitives: `createGraphTransaction(...)` and `createGraphAction(...)`.
+- Graph workflow/effect helper: `createGraphEffect(...)`.
+- Per-entity sync/provenance metadata exposed through snapshot reads: `$synced`, `$origin`, `$updatedAt`.
+- AI interoperability helpers: `createGraphTool(...)` and `exportGraphSnapshot(...)`.
+- Vitest coverage for graph runtime querying, actions, rollback, effects, and AI helpers.
+- New comparison documentation: `docs/tanstack-comparison.md`.
+
+### Changed
+
+- Core read paths now resolve sync-aware snapshots rather than base-entity-plus-patch merges alone.
+- Optimistic mutation and CRUD flows now track sync metadata and restore it correctly on rollback.
+- Top-level docs now describe the graph runtime surface and the library’s positioning relative to TanStack DB, Query, Table, AI, and Intent.
+
 ## [1.0.0] — 2026-04-04
 
 Production-ready semantic version with CI, tests, documentation, and skills export verification.

package/README.md

@@ -9,6 +9,7 @@ Update a post in one screen and every list row, detail panel, and badge that rea
 | Doc | Purpose |
 |-----|---------|
 | [docs/tanstack-query-and-table.md](docs/tanstack-query-and-table.md) | How this library fits with TanStack Query and TanStack Table |
+| [docs/tanstack-comparison.md](docs/tanstack-comparison.md) | Detailed comparison against TanStack DB, Query, Table, AI, and Intent |
 | [docs/advanced.md](docs/advanced.md) | Engine, GC, Suspense, DevTools, SSR, testing |
 | [RELEASING.md](RELEASING.md) | Versioning, `prepublishOnly`, npm publish |
 | [CHANGELOG.md](CHANGELOG.md) | Release history |
@@ -20,10 +21,10 @@ Update a post in one screen and every list row, detail panel, and badge that rea
 ### 1. Install
 
 ```bash
-npm install @prometheus-ags/prometheus-entity-management zustand immer
+pnpm add @prometheus-ags/prometheus-entity-management zustand immer
 ```
 
-(`pnpm` and `yarn` work the same way for app dependencies.)
+(`npm install` works for consumers too; this repository itself is `pnpm`-only.)
 
 ### 2. Define an entity type
 
@@ -98,6 +99,24 @@ Data flows **up** into the graph; UI reads **down** through hooks (see [Architec
 
 ---
 
+## New in v1.2
+
+The graph runtime now exposes a focused set of non-hook helpers for loaders, workflows, and orchestration:
+
+- `queryOnce(...)` / `selectGraph(...)` for one-shot graph snapshots without a live subscription
+- nested `include` projections over normalized graph data
+- `createGraphTransaction(...)` / `createGraphAction(...)` for explicit optimistic graph writes with rollback
+- sync-aware snapshot metadata: `$synced`, `$origin`, `$updatedAt`
+- `createGraphEffect(...)` for enter/update/exit reactions over graph query results
+- `createGraphTool(...)` / `exportGraphSnapshot(...)` for AI interoperability without bundling an AI runtime
+- `startLocalFirstGraph(...)`, `hydrateGraphFromStorage(...)`, and `persistGraphToStorage(...)` for PWA/PGlite-friendly graph persistence and replay
+- schema-driven entity rendering via `registerEntityJsonSchema(...)`, `buildEntityFieldsFromSchema(...)`, and `useSchemaEntityFields(...)`
+- built-in markdown-aware schema fields plus schema-aware graph export helpers for A2UI/runtime-generated entity models
+
+These additions are intentionally graph-native. They extend the entity graph for orchestration use cases without changing the core `Components → Hooks → Stores → APIs/Realtime` architecture.
+
+---
+
 ## Feature comparison
 
 | Feature | `@prometheus-ags/prometheus-entity-management` | TanStack Query | Apollo Client | SWR |
@@ -147,6 +166,38 @@ Compare against peers only when measurement methodology matches (minified vs unm
 | `dedupe` | Process-global in-flight promise deduplication helper. |
 | `startGarbageCollector` / `stopGarbageCollector` | Periodic eviction of unsubscribed, stale entities (also started via `configureEngine`). |
 
+### Graph runtime
+
+| Export | Description |
+|--------|-------------|
+| `queryOnce` / `selectGraph` | One-shot graph snapshot queries with local filtering, sorting, and nested includes. |
+| `createGraphTransaction` | Explicit graph write transaction with commit / rollback. |
+| `createGraphAction` | Higher-level optimistic action wrapper around graph transactions. |
+| `createGraphEffect` | Subscribe to graph query results with `onEnter`, `onUpdate`, and `onExit`. |
+| `createGraphTool` | Typed graph-backed helper for AI or workflow integrations. |
+| `createSchemaGraphTool` | Schema-aware graph tool helper for AI workflows built around dynamic entity schemas. |
+| `exportGraphSnapshot` | Serialize graph data for prompts, exports, and non-React workflows. |
+
+### Schema-driven entities
+
+| Export | Description |
+|--------|-------------|
+| `registerEntityJsonSchema` / `registerRuntimeSchema` | Register static or runtime-generated JSON Schemas for an entity type or JSON column. |
+| `getEntityJsonSchema` | Resolve the active schema by entity type, schema id, or field. |
+| `buildEntityFieldsFromSchema` | Generate entity field descriptors from JSON Schema for dynamic forms and detail views. |
+| `useSchemaEntityFields` | Hook that resolves a registered schema and returns generated field descriptors. |
+| `MarkdownFieldRenderer` / `MarkdownFieldEditor` | Built-in markdown-aware schema field renderer and editor. |
+| `exportGraphSnapshotWithSchemas` | Serialize graph data together with resolved entity schemas. |
+
+### Local-first runtime
+
+| Export | Description |
+|--------|-------------|
+| `startLocalFirstGraph` | Starts a higher-level local-first runtime for graph hydration, persistence, action replay, and sync status. |
+| `hydrateGraphFromStorage` | Restore graph state from a storage adapter using a JSON-serializable snapshot payload. |
+| `persistGraphToStorage` | Persist graph state and pending action metadata through a storage adapter. |
+| `useGraphSyncStatus` | Hook exposing online/offline/hydrating/syncing/ready state for PWAs and IPC-safe hosts. |
+
 ### Hooks (REST-oriented)
 
 | Export | Description |
@@ -232,7 +283,7 @@ Compare against peers only when measurement methodology matches (minified vs unm
 
 ### Types (high level)
 
-`GraphState`, `EntityState`, `ListState`, `EntityType`, `EntityId`, `EngineOptions`, `EntityQueryOptions`, `ListQueryOptions`, `ViewDescriptor`, `EntitySchema`, `RelationDescriptor`, realtime adapter types, GraphQL types, CRUD types, column meta types — all exported from the package entry.
+`GraphState`, `EntityState`, `ListState`, `EntityType`, `EntityId`, `EntitySyncMetadata`, `EntitySnapshot`, `EngineOptions`, `EntityQueryOptions`, `ListQueryOptions`, `ViewDescriptor`, `EntitySchema`, `RelationDescriptor`, realtime adapter types, GraphQL types, CRUD types, and column meta types are all exported from the package entry.
 
 ---
 
@@ -475,6 +526,7 @@ pnpm run dev:next   # http://localhost:3000
 1. **`entities`** — Canonical server-shaped records per `(type, id)`.
 2. **`patches`** — Local-only overlays (`_selected`, `_loading`, …) merged at read time.
 3. **`lists`** — Ordered `ids[]`, pagination, and fetch flags — **not** duplicated row payloads.
+4. **`syncMetadata`** — Per-entity sync/provenance state layered into snapshot reads as `$synced`, `$origin`, and `$updatedAt`.
 
 ### Engine (`src/engine.ts`)