semiotic 3.4.2 → 3.5.0

package/dist/test-utils/canvasMock.d.ts

@@ -41,17 +41,46 @@ export interface CanvasOpLog {
 }
 export declare function recordCanvasOps(ctx: CanvasContextMock): CanvasOpLog;
 /**
- * Sets up the canvas getContext mock on HTMLCanvasElement.prototype,
- * mocks requestAnimationFrame to execute callbacks synchronously,
- * and mocks cancelAnimationFrame.
+ * rAF stubbing flavor:
+ *
+ * - `true` — synchronous fire: the rAF callback runs immediately when
+ *   scheduled. Default. Right for most tests that just want a paint
+ *   to happen before assertions, but recurses indefinitely for
+ *   components that re-schedule rAF inside the callback (force
+ *   simulations, continuous render loops).
+ *
+ * - `false` — leave jsdom's default rAF in place (setTimeout-backed,
+ *   ~16ms). Right for tests that exercise the actual rAF cadence and
+ *   use `waitFor` to settle. Pairs with force-simulation specs.
+ *
+ * - `"noop"` — install a stub that returns an id but never fires the
+ *   callback. Right for "observe initial state" regression tests that
+ *   want a single mount-time render and nothing else (the frame
+ *   regression suites that spy on `updateConfig` use this).
+ *
+ * - `"microtask"` — fire the callback on a `Promise.resolve().then(...)`
+ *   microtask. Right for tests where synchronous fire would recurse
+ *   `scheduleRender` but jsdom's setTimeout cadence introduces
+ *   undesirable latency (StrictMode double-mount tests use this).
+ */
+export type StubRafMode = boolean | "noop" | "microtask";
+export interface SetupCanvasMockOptions {
+    stubRaf?: StubRafMode;
+}
+/**
+ * Sets up the canvas getContext mock on HTMLCanvasElement.prototype, the
+ * Path2D global, and (optionally) synchronous rAF/cAF stubs.
  *
  * @returns A cleanup function that restores the mocked globals.
  *
  * @example
  * ```ts
  * let cleanup: () => void
- * beforeEach(() => { cleanup = setupCanvasMock() })
+ * beforeEach(() => { cleanup = setupCanvasMock() })          // sync rAF (default)
+ * beforeEach(() => { cleanup = setupCanvasMock({ stubRaf: false }) })       // jsdom rAF (force-sim specs)
+ * beforeEach(() => { cleanup = setupCanvasMock({ stubRaf: "noop" }) })      // never fires (mount-only regression)
+ * beforeEach(() => { cleanup = setupCanvasMock({ stubRaf: "microtask" }) }) // Promise.resolve fire (StrictMode)
  * afterEach(() => { cleanup() })
  * ```
  */
-export declare function setupCanvasMock(): () => void;
+export declare function setupCanvasMock(options?: SetupCanvasMockOptions): () => void;