@pygmalionjs/pygmalion 0.2.16 → 0.2.18

package/README.md

@@ -116,6 +116,34 @@ 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.
 
+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)}
+>
+  {/* Optional: your own trigger, so the control reads as part of the toolbar. */}
+  <span>{mirror.sourceRef ?? 'dev'}@{mirror.shortCommit}</span>
+</SourceRefControl>;
+```
+
+The menu is a native select layered over that trigger, so keyboard access,
+mobile behavior, and placement stay with the platform while the painted trigger
+stays yours. `[data-pygmalion-source-ref]` and `[data-busy]` are available for
+styling.
+
+`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