@pygmalionjs/pygmalion 0.2.15 → 0.2.17

package/README.md

@@ -98,6 +98,54 @@ 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.
+
+To offer a choice instead of asking for a ref string, list the revisions and
+render the shipped control in your toolbar:
+
+```tsx
+const { sourceRefs, switchSource, mirror } = usePygmalionProject();
+
+<SourceRefControl
+  value={mirror.sourceRef}
+  refs={sourceRefs.refs}
+  defaultRef={sourceRefs.defaultRef}
+  worktreeRef={sourceRefs.worktreeRef}
+  busy={mirror.state === 'syncing'}
+  onChange={(ref) => void switchSource(ref)}
+/>;
+```
+
+`GET /__pygmalion-dev-control/refs` backs this list with local branches, remote
+tracking branches, the default revision, and the worktree ref. `loadSourceRefs()`
+reloads it after branches change.
+
+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,