@pygmalionjs/pygmalion 0.2.14 → 0.2.16

package/README.md

@@ -86,6 +86,46 @@ When the mirror preview reloads the host Vite configuration,
 `PYGMALION_PREVIEW_MODE=1` prevents the integration plugins from starting
 recursively.
 
+Mirror and session previews run as their own Vite processes, so the mode you
+pass to the editor does not reach them. Set `preview.mode` when a screen only
+exists under a specific env file — a feature flag that has to be off, a mock
+profile a recipe depends on:
+
+```ts
+export default definePygmalionProject({
+  // ...
+  preview: { mode: "e2e" },
+});
+```
+
+## Switch what the mirror renders
+
+The mirror follows `source.branch` unless `source.ref` pins it. Either can be
+repointed at runtime, so comparing two revisions no longer means restarting the
+dev server:
+
+```ts
+const { switchSource, mirror } = usePygmalionProject();
+
+await switchSource("origin/dev");
+await switchSource(PYGMALION_WORKTREE_SOURCE_REF); // uncommitted work
+mirror.sourceRef; // what it is tracking now
+```
+
+`PYGMALION_WORKTREE_SOURCE_REF` renders the current working tree by resolving it
+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.
+
+Preview artifacts are cached per source SHA, so switching invalidates that cache
+and the next capture runs again from scratch. A capture already running for the
+previous revision is discarded instead of published, so it cannot overwrite the
+artifact the editor moved to.
+
+A design session's worktree is branched from one source SHA. Once it holds
+unapplied edits, `switchSource` refuses rather than leave the canvas on a
+revision those edits were never written against — apply or revert them first, or
+pass `{ discardEdits: true }`.
+
 ## Register screens and scenarios
 
 The host owns application-specific routes, fixtures, authentication, mock data,