@pygmalionjs/pygmalion 0.6.31 → 0.6.33

package/README.md

@@ -58,6 +58,7 @@ export default definePygmalionProject({
       "src/generated/design-registry.ts",
       "src/generated/design-inventory.ts",
     ],
+    runtimeInputs: [".env.local"],
   },
   inspect: {
     normalizeValue(property, value) {
@@ -68,8 +69,13 @@ export default definePygmalionProject({
 ```
 
 `inventory.outputs` lists generator-owned paths relative to the application root. Pygmalion
-restores only these paths in its dedicated mirror before switching revisions, while any other
-mirror change still stops synchronization.
+restores these paths in its dedicated mirror before switching revisions and checks again after
+generation; any change outside the declared outputs stops synchronization.
+Git does not report ignored files, so list ignored runtime or configuration
+files a generator could affect in `inventory.runtimeInputs`. Each entry is one
+file relative to the application root, with at most 64 files and 16 MiB total.
+Pygmalion compares their content directly before and after generation; it does
+not recursively scan `.git`, `node_modules`, or other unrelated directories.
 
 Add the integration plugins to the host Vite configuration:
 
@@ -132,6 +138,73 @@ mirror.sourceRef; // what it is tracking now
 to a throwaway commit, leaving your branch, HEAD, and index untouched. It covers
 tracked changes only; untracked files raise a warning on the returned status.
 
+### Bind screen declarations to the selected revision
+
+An editor host is normally built once, while its mirror can switch among many
+checkouts. Bundling routed pages into the host therefore lets a new preview run
+under an old screen catalog. Generate a JSON catalog inside every mirror
+checkout and let the exact-source endpoint serve it under a read lease:
+
+```ts
+export default definePygmalionProject({
+  // ...
+  inventory: {
+    script: './scripts/generate-pygmalion-inventory.mjs',
+    outputs: ['artifacts/pygmalion-revision-catalog.json'],
+  },
+  preview: {
+    catalog: { file: 'artifacts/pygmalion-revision-catalog.json' },
+  },
+});
+```
+
+With the default `inventory.script` invocation, Pygmalion passes
+`--source-root <path> --out-root <path> --commit <sha>`. A custom
+`inventory.args(context)` receives the same exact `context.commit` when the
+generator uses another CLI shape.
+
+The generated file uses the versioned, JSON-only contract exported as
+`PygmalionRevisionCatalog`. Stamp `sourceRevision` from the inventory
+generator's `commit` context and include routed `screens.pages`,
+`screens.assets`, `tokens`, and every screen declaration that can differ by
+revision. Put serializable registry metadata in `componentRegistry`; the editor
+binds it by name to the React implementations already bundled by the host and
+rejects a catalog whose implementation is unavailable. This keeps props,
+defaults, adoption, and code-generation metadata revision-bound without putting
+functions in JSON.
+Repository-owned generated-code intent belongs in `codegenProject` so its
+frame contracts and prompt provenance switch with the same catalog.
+Then opt the editor into the endpoint:
+
+```tsx
+const { appOrigin, previewRevision } = usePygmalionProject();
+
+<PygmalionEditor
+  previewCacheNamespace="my-product"
+  previewRevision={previewRevision}
+  appOrigin={appOrigin ?? undefined}
+  previewCatalogEndpoint="/__pygmalion-route-preview/artifact/catalog"
+/>
+```
+
+Pass the runtime's full `previewRevision`; the editor derives its source SHA
+for the catalog request while retaining the session mutation counter for screen
+cache invalidation.
+
+The editor validates both namespace and source revision before installation.
+While another checkout is preparing, it keeps the last complete catalog,
+preview origin, and interaction declarations together. A late response from an
+older dev → qa → dev request cannot overwrite the current selection.
+Invalid, permanently unavailable, or catalogs that produce no installable page
+fail closed on a dedicated error surface; the editor never relabels the
+previous canvas as the requested revision. A catalog with no routed screens
+remains installable when the host contributes non-screen library pages.
+
+When `onDesignChange` is connected, each payload carries the exact
+`sourceRevision` that owned the edited batch. Its non-enumerable `signal` is
+aborted when that catalog is retired, allowing an in-process host adapter to
+cancel work without changing an existing JSON request body.
+
 To offer a choice instead of asking for a ref string, list the revisions and
 render the shipped control in your toolbar: