@pygmalionjs/pygmalion 0.2.15 → 0.2.16

package/README.md

@@ -98,6 +98,34 @@ export default definePygmalionProject({
 });
 ```
 
+## 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,