@x12i/catalox 2.1.0 → 2.2.1

package/README.md

@@ -62,6 +62,9 @@ Example `.env` (do not commit secrets):
 ```bash
 MONGO_URI=mongodb://127.0.0.1:27017
 GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+# Or (used by the packaged CLI migration + live integration tests):
+FIREBASE_SERVICE_ACCOUNT_PATH=/path/to/service-account.json
+FIREBASE_PROJECT_ID=your-project-id
 FIRESTORE_LIVE_TESTS=1
 ```
 
@@ -199,6 +202,10 @@ export type CatalogDescriptor = {
   queryCapabilities?: Record<string, unknown>;
   filterSpec?: Record<string, unknown>;
   presentationSpec?: Record<string, unknown>;
+  /**
+   * Optional UI escape hatch: registry components and/or stored snippet refs per role.
+   * See `CatalogCustomRenderer` in the published types (`renderers[]` with `role` + optional `mode`).
+   */
   customRenderer?: Record<string, unknown>;
   identity: CatalogIdentityDescriptor;
   metadata?: Record<string, unknown>;
@@ -211,27 +218,30 @@ Catalog descriptors can include optional UI metadata for generic presentation la
 
 - `filterSpec`: declarative filter configuration (built on `FieldSource`)
 - `presentationSpec`: declarative layout + view/edit semantics (grid/list/cards/form)
-- `customRenderer`: escape hatch that assigns either:
-  - a host-resolved JSX component (by registry key), or
-  - a separately-stored renderer snippet reference (`snippetRef`) (TSX/JSX/HTML)
+- `customRenderer`: escape hatch with a **`renderers[]`** list. Each entry has a **`role`** (`core|list|grid|item|report|dashboard`) and optional **`mode`** (`readonly|editable`, only for `list|grid|item`). An entry may set either:
+  - a host-resolved component (**`component`**: registry key), or
+  - a separately-stored renderer snippet (**`snippetRef`**), plus optional **`syntax`** (`html|jsx|tsx`), **`props`**, and **`receiveMap`** (`full|minimal`).
+
+Use **`role: "core"`** for defaults shared across roles; merge with **`resolveCustomRendererEntry(...)`** (exported from `@x12i/catalox`).
 
 Custom renderer contracts:
 
 - [`docs/catalog-list-render-map.md`](docs/catalog-list-render-map.md)
 - [`docs/catalog-item-render-map.md`](docs/catalog-item-render-map.md)
+- [`docs/custom-renderer-snippets-io.md`](docs/custom-renderer-snippets-io.md) — **snippet default export, `map` I/O, `actions`, roles, and `receiveMap`**
 
 Important: host presentation layers are responsible for resolving `FieldSource` lookups (cross-catalog enums/refs) and populating `resolvedSources` for renderers.
 
-#### Stored JSX/TSX renderer snippets (optional)
-
-In addition to `customRenderer.{list|item}.component`, descriptors may specify:
+#### Stored renderer snippets (optional)
 
-- `customRenderer.renderers[].snippetRef`
+Descriptors reference snippets via **`customRenderer.renderers[].snippetRef`**.
 
-Snippets are stored separately in Firestore:
+Snippet documents (Firestore, default layout) live at:
 
 - `catalogRendererSnippets/{catalogId}:{role}[:{mode}]` where `role` is `core|list|grid|item|report|dashboard` and `mode` is optional (`readonly|editable`)
 
+Snippet record fields include **`rendererSource`** + optional **`syntax`** (`html|jsx|tsx`). Fetch via **`catalox.getCatalogRendererSnippet(ctx, catalogId, role, mode?)`** when `rendererSnippets` is wired on `Catalox`.
+
 This package includes a small set of opt-in helpers for snippet compilation/validation:
 
 - `transpileRendererSourceToModuleSource(...)`: TSX/JSX → ESM module source (string)
@@ -239,6 +249,20 @@ This package includes a small set of opt-in helpers for snippet compilation/vali
 - `unsafeCreateRendererFunction(...)`: **UNSAFE** runtime evaluation of transpiled code
 - `renderRendererToHtml(...)`: best-effort HTML rendering if `react` + `react-dom` are installed
 
+**CLI: migrating legacy snippet/descriptor shapes** (old `surface`/`jsxSource` and `customRenderer.list` / `customRenderer.item`):
+
+```bash
+# Uses FIREBASE_SERVICE_ACCOUNT_PATH + FIREBASE_PROJECT_ID from .env (or env)
+npx catalox migrate renderers --dry-run
+npx catalox migrate renderers --write
+```
+
+Optional **`--app <appId>`** also scans `apps/<appId>/catalogRendererSnippets` and `apps/<appId>/catalogDescriptors`.
+
+Programmatic conversion (no Firestore): import **`convertLegacySnippetRecordToRoleModel`**, **`migrateDescriptorCustomRendererInPlace`**, etc. from `@x12i/catalox`.
+
+**Worked example (catalog viewer + Catalox `map`)**: [`docs/new-feature/USAGE.md`](docs/new-feature/USAGE.md)
+
 ### What you need persisted for “generic consumption”
 
 To let consumers operate *purely* from `appId` with no hardcoded catalog registrations, Catalox relies on these being present in Firestore:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/catalox",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Catalox: Firebase-native catalog metadata + unification package.",
   "license": "MIT",
   "private": false,