@pygmalionjs/pygmalion 0.2.17 → 0.2.19

package/README.md

@@ -129,9 +129,17 @@ const { sourceRefs, switchSource, mirror } = usePygmalionProject();
   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.
@@ -146,6 +154,26 @@ 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 }`.
 
+### Screens that never stop moving
+
+A capture waits for the document to hold still. A screen with an elapsed clock, a
+level meter, or a marquee never does, so it fails on `stabilize` no matter how
+long it waits. Declare those regions and their mutations stop counting as churn:
+
+```ts
+captureStoryboardCase({
+  // ...
+  stability: {
+    volatileSelectors: ['[data-testid="elapsed-time"]', '[data-live-meter]'],
+  },
+});
+```
+
+The wait itself samples every 100ms and needs three identical samples, up to a
+4s ceiling — wide enough for a screen that repaints on a one-second beat.
+`attempts`, `requiredStableSamples`, `intervalMs`, and `minimumWaitMs` are
+adjustable for anything slower.
+
 ## Register screens and scenarios
 
 The host owns application-specific routes, fixtures, authentication, mock data,