@codyswann/lisa 4.65.8 → 4.66.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/all/copy-overwrite/scripts/lisa-hooks/worktree-binding-guard.mjs +34 -10
  2. package/dist/core/lisa-owned-hash-ledger.d.ts.map +1 -1
  3. package/dist/core/lisa-owned-hash-ledger.js +8 -0
  4. package/dist/core/lisa-owned-hash-ledger.js.map +1 -1
  5. package/dist/core/nightly-e2e-guard-behavior-certificate.js +2 -2
  6. package/dist/core/upstream-evidence-manifest.d.ts.map +1 -1
  7. package/dist/core/upstream-evidence-manifest.js +16 -7
  8. package/dist/core/upstream-evidence-manifest.js.map +1 -1
  9. package/expo/create-only/.github/workflows/maestro-e2e.yml +6 -0
  10. package/package.json +4 -4
  11. package/plugins/lisa/.claude-plugin/plugin.json +1 -1
  12. package/plugins/lisa/.codex-plugin/plugin.json +1 -1
  13. package/plugins/lisa/hooks/worktree-binding-guard.mjs +34 -10
  14. package/plugins/lisa-agy/plugin.json +1 -1
  15. package/plugins/lisa-cdk/.claude-plugin/plugin.json +1 -1
  16. package/plugins/lisa-cdk/.codex-plugin/plugin.json +1 -1
  17. package/plugins/lisa-cdk-agy/plugin.json +1 -1
  18. package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json +1 -1
  19. package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json +1 -1
  20. package/plugins/lisa-copilot/.claude-plugin/plugin.json +1 -1
  21. package/plugins/lisa-copilot/hooks/worktree-binding-guard.mjs +34 -10
  22. package/plugins/lisa-cursor/.claude-plugin/plugin.json +1 -1
  23. package/plugins/lisa-cursor/hooks/worktree-binding-guard.mjs +34 -10
  24. package/plugins/lisa-expo/.claude-plugin/plugin.json +1 -1
  25. package/plugins/lisa-expo/.codex-plugin/plugin.json +1 -1
  26. package/plugins/lisa-expo/.codex-plugin/skills/expo-router-best-practices/SKILL.md +1 -0
  27. package/plugins/lisa-expo/.codex-plugin/skills/expo-router-best-practices/references/static-export-verification.md +54 -0
  28. package/plugins/lisa-expo/.codex-plugin/skills/expo-tailwind-setup/SKILL.md +7 -0
  29. package/plugins/lisa-expo/.codex-plugin/skills/playwright-selectors/SKILL.md +25 -0
  30. package/plugins/lisa-expo/.codex-plugin/skills/testing-library/references/mocking-patterns.md +22 -0
  31. package/plugins/lisa-expo/skills/expo-router-best-practices/SKILL.md +1 -0
  32. package/plugins/lisa-expo/skills/expo-router-best-practices/references/static-export-verification.md +54 -0
  33. package/plugins/lisa-expo/skills/expo-tailwind-setup/SKILL.md +7 -0
  34. package/plugins/lisa-expo/skills/playwright-selectors/SKILL.md +25 -0
  35. package/plugins/lisa-expo/skills/testing-library/references/mocking-patterns.md +22 -0
  36. package/plugins/lisa-expo-agy/plugin.json +1 -1
  37. package/plugins/lisa-expo-agy/skills/expo-router-best-practices/SKILL.md +1 -0
  38. package/plugins/lisa-expo-agy/skills/expo-router-best-practices/references/static-export-verification.md +54 -0
  39. package/plugins/lisa-expo-agy/skills/expo-tailwind-setup/SKILL.md +7 -0
  40. package/plugins/lisa-expo-agy/skills/playwright-selectors/SKILL.md +25 -0
  41. package/plugins/lisa-expo-agy/skills/testing-library/references/mocking-patterns.md +22 -0
  42. package/plugins/lisa-expo-copilot/.claude-plugin/plugin.json +1 -1
  43. package/plugins/lisa-expo-copilot/skills/expo-router-best-practices/SKILL.md +1 -0
  44. package/plugins/lisa-expo-copilot/skills/expo-router-best-practices/references/static-export-verification.md +54 -0
  45. package/plugins/lisa-expo-copilot/skills/expo-tailwind-setup/SKILL.md +7 -0
  46. package/plugins/lisa-expo-copilot/skills/playwright-selectors/SKILL.md +25 -0
  47. package/plugins/lisa-expo-copilot/skills/testing-library/references/mocking-patterns.md +22 -0
  48. package/plugins/lisa-expo-cursor/.claude-plugin/plugin.json +1 -1
  49. package/plugins/lisa-expo-cursor/skills/expo-router-best-practices/SKILL.md +1 -0
  50. package/plugins/lisa-expo-cursor/skills/expo-router-best-practices/references/static-export-verification.md +54 -0
  51. package/plugins/lisa-expo-cursor/skills/expo-tailwind-setup/SKILL.md +7 -0
  52. package/plugins/lisa-expo-cursor/skills/playwright-selectors/SKILL.md +25 -0
  53. package/plugins/lisa-expo-cursor/skills/testing-library/references/mocking-patterns.md +22 -0
  54. package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json +1 -1
  55. package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json +1 -1
  56. package/plugins/lisa-harper-fabric-agy/plugin.json +1 -1
  57. package/plugins/lisa-harper-fabric-copilot/.claude-plugin/plugin.json +1 -1
  58. package/plugins/lisa-harper-fabric-cursor/.claude-plugin/plugin.json +1 -1
  59. package/plugins/lisa-nestjs/.claude-plugin/plugin.json +1 -1
  60. package/plugins/lisa-nestjs/.codex-plugin/plugin.json +1 -1
  61. package/plugins/lisa-nestjs-agy/plugin.json +1 -1
  62. package/plugins/lisa-nestjs-copilot/.claude-plugin/plugin.json +1 -1
  63. package/plugins/lisa-nestjs-cursor/.claude-plugin/plugin.json +1 -1
  64. package/plugins/lisa-openclaw/.claude-plugin/plugin.json +1 -1
  65. package/plugins/lisa-openclaw/.codex-plugin/plugin.json +1 -1
  66. package/plugins/lisa-openclaw-agy/plugin.json +1 -1
  67. package/plugins/lisa-openclaw-copilot/.claude-plugin/plugin.json +1 -1
  68. package/plugins/lisa-openclaw-cursor/.claude-plugin/plugin.json +1 -1
  69. package/plugins/lisa-phaser/.claude-plugin/plugin.json +1 -1
  70. package/plugins/lisa-phaser/.codex-plugin/plugin.json +1 -1
  71. package/plugins/lisa-phaser-agy/plugin.json +1 -1
  72. package/plugins/lisa-phaser-copilot/.claude-plugin/plugin.json +1 -1
  73. package/plugins/lisa-phaser-cursor/.claude-plugin/plugin.json +1 -1
  74. package/plugins/lisa-rails/.claude-plugin/plugin.json +1 -1
  75. package/plugins/lisa-rails/.codex-plugin/plugin.json +1 -1
  76. package/plugins/lisa-rails-agy/plugin.json +1 -1
  77. package/plugins/lisa-rails-copilot/.claude-plugin/plugin.json +1 -1
  78. package/plugins/lisa-rails-cursor/.claude-plugin/plugin.json +1 -1
  79. package/plugins/lisa-typescript/.claude-plugin/plugin.json +1 -1
  80. package/plugins/lisa-typescript/.codex-plugin/plugin.json +1 -1
  81. package/plugins/lisa-typescript-agy/plugin.json +1 -1
  82. package/plugins/lisa-typescript-copilot/.claude-plugin/plugin.json +1 -1
  83. package/plugins/lisa-typescript-cursor/.claude-plugin/plugin.json +1 -1
  84. package/plugins/lisa-wiki/.claude-plugin/plugin.json +1 -1
  85. package/plugins/lisa-wiki/.codex-plugin/plugin.json +1 -1
  86. package/plugins/lisa-wiki-agy/plugin.json +1 -1
  87. package/plugins/lisa-wiki-copilot/.claude-plugin/plugin.json +1 -1
  88. package/plugins/lisa-wiki-cursor/.claude-plugin/plugin.json +1 -1
  89. package/plugins/src/base/hooks/worktree-binding-guard.mjs +34 -10
  90. package/plugins/src/expo/skills/expo-router-best-practices/SKILL.md +1 -0
  91. package/plugins/src/expo/skills/expo-router-best-practices/references/static-export-verification.md +54 -0
  92. package/plugins/src/expo/skills/expo-tailwind-setup/SKILL.md +7 -0
  93. package/plugins/src/expo/skills/playwright-selectors/SKILL.md +25 -0
  94. package/plugins/src/expo/skills/testing-library/references/mocking-patterns.md +22 -0
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-phaser",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "Phaser 4 game-development rules for TypeScript projects",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-phaser",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "Phaser 4 game-development rules for TypeScript projects",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-phaser",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "Phaser 4 game-development rules for TypeScript projects",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-rails",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-rails",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-rails",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-rails",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-rails",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-typescript",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-typescript",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-typescript",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-typescript",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-typescript",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-wiki",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-wiki",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-wiki",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-wiki",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lisa-wiki",
3
- "version": "4.65.8",
3
+ "version": "4.66.1",
4
4
  "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
5
5
  "author": {
6
6
  "name": "Cody Swann"
@@ -503,9 +503,32 @@ function reachesOut(script, foreign, bound) {
503
503
  ]);
504
504
  }
505
505
 
506
- function stateFile(sessionId) {
506
+ function stateFile(bindingKey) {
507
507
  const home = process.env.LISA_STATE_HOME || join(homedir(), ".lisa");
508
- return join(home, "worktree-binding", `${sessionId}.json`);
508
+ return join(home, "worktree-binding", `${bindingKey}.json`);
509
+ }
510
+
511
+ /**
512
+ * The identity a binding belongs to.
513
+ *
514
+ * Parallel subagents share the session's `session_id`, so keying the binding
515
+ * on it alone made each subagent's guarded call read the binding a sibling
516
+ * recorded — the sibling's worktree then read as "changed underneath it" and
517
+ * its writes were refused, or an acknowledgement rebound the file out from
518
+ * under the sibling (CodySwannGT/lisa#4277). The payload's `agent_id` is what
519
+ * distinguishes a subagent from the main agent, so a caller carrying one gets
520
+ * its own state file. The main agent carries no `agent_id` and keeps the
521
+ * session-scoped key it always had, which is also the fallback for runtimes
522
+ * that never send the field.
523
+ *
524
+ * The key lands in a filename, so the composite is folded into a set that is
525
+ * legal on every filesystem — `:` is not, which rules it out as a separator
526
+ * and as tolerated session_id content on Windows hosts.
527
+ */
528
+ function bindingKey(payload) {
529
+ const agent = payload?.agent_id;
530
+ if (typeof agent !== "string" || !agent) return payload.session_id;
531
+ return `${payload.session_id}--${agent}`.replaceAll(/[^A-Za-z0-9._-]/g, "_");
509
532
  }
510
533
 
511
534
  function readState(sessionId) {
@@ -637,8 +660,8 @@ function recordBaseline(sessionId, observed) {
637
660
  function recordClaim(payload, observed) {
638
661
  const claimed = claimedRoot(payload.tool_input, payload.cwd);
639
662
  if (!claimed || claimed === observed) return;
640
- const previous = readState(payload.session_id);
641
- writeState(payload.session_id, {
663
+ const previous = readState(bindingKey(payload));
664
+ writeState(bindingKey(payload), {
642
665
  boundRoot: previous?.boundRoot ?? observed,
643
666
  claimedRoot: claimed,
644
667
  updatedAt: new Date().toISOString(),
@@ -678,7 +701,7 @@ function handleAcceptance(payload, observed) {
678
701
  acceptanceLine(observed),
679
702
  ]);
680
703
  }
681
- writeState(payload.session_id, {
704
+ writeState(bindingKey(payload), {
682
705
  boundRoot: observed,
683
706
  claimedRoot: null,
684
707
  updatedAt: new Date().toISOString(),
@@ -880,15 +903,16 @@ function evaluate(payload) {
880
903
  say("payload carries no session id or cwd; binding is NOT enforced");
881
904
  return 0;
882
905
  }
906
+ const binding = bindingKey(payload);
883
907
  const observed = worktreeRoot(cwd);
884
908
  if (!observed) return 0;
885
909
 
886
910
  if (payload.hook_event_name === "SessionStart") {
887
- recordBaseline(sessionId, observed);
911
+ recordBaseline(binding, observed);
888
912
  // After the baseline, never before: `recordBaseline` writes a fresh state
889
913
  // for a session it has not seen, and the notice's record has to go on top
890
914
  // of that write rather than under it.
891
- noticeRuntimeDrift(sessionId, process.env);
915
+ noticeRuntimeDrift(binding, process.env);
892
916
  return 0;
893
917
  }
894
918
  if (payload.tool_name === "EnterWorktree") {
@@ -900,7 +924,7 @@ function evaluate(payload) {
900
924
  const accepted = handleAcceptance(payload, observed);
901
925
  if (accepted !== null) return accepted;
902
926
 
903
- const state = readState(sessionId);
927
+ const state = readState(binding);
904
928
  if (!state?.boundRoot) {
905
929
  // No baseline means SessionStart did not run for this session — an older
906
930
  // install, a runtime that fires no such event, a harness that skips it.
@@ -909,7 +933,7 @@ function evaluate(payload) {
909
933
  // refusing. Treating it as a refusal would turn a floor into a wall on
910
934
  // every surface where the event does not fire, and a wall gets switched
911
935
  // off, which costs the whole guard.
912
- writeState(sessionId, {
936
+ writeState(binding, {
913
937
  boundRoot: observed,
914
938
  claimedRoot: null,
915
939
  updatedAt: new Date().toISOString(),
@@ -920,7 +944,7 @@ function evaluate(payload) {
920
944
  return unconfirmedSwitch(state.claimedRoot, observed);
921
945
  }
922
946
  if (state.claimedRoot === observed) {
923
- writeState(sessionId, {
947
+ writeState(binding, {
924
948
  boundRoot: observed,
925
949
  claimedRoot: null,
926
950
  updatedAt: new Date().toISOString(),
@@ -426,6 +426,7 @@ const { width } = useWindowDimensions();
426
426
  For detailed documentation on specific topics, refer to:
427
427
 
428
428
  - `references/official-docs.md` - Condensed official Expo Router documentation
429
+ - `references/static-export-verification.md` - Asserting enumerated routes, per-route titles, and initial HTML after `expo export`
429
430
  - `scripts/generate-route.py` - Route scaffolding script
430
431
 
431
432
  Official Documentation: https://docs.expo.dev/router/introduction/
@@ -0,0 +1,54 @@
1
+ # Static Export Verification
2
+
3
+ When `expo export` runs with static output (`output: "static"` in app.json),
4
+ every route must produce an HTML file with the right title and the expected
5
+ initial markup. `expo export` succeeding only proves the bundle built — a
6
+ missing route, a wrong title, or an empty shell all ship green unless the
7
+ exported output itself is checked.
8
+
9
+ ## Enumerate the dynamic routes
10
+
11
+ Static export prerenders each route it can enumerate. Dynamic segments need
12
+ `generateStaticParams` — an unenumerated `[id]` route produces no page at all.
13
+ After export, enumerate the routes the app *declares* and assert each one has
14
+ a file under `dist/`:
15
+
16
+ ```typescript
17
+ import { existsSync, readdirSync } from "node:fs";
18
+ import path from "node:path";
19
+
20
+ const DIST = path.resolve("dist");
21
+
22
+ // The routes the app owns — keep this in sync with app/, or derive it from
23
+ // the route manifest expo-router emits.
24
+ const EXPECTED_ROUTES = ["index", "settings", "players/[id]"];
25
+
26
+ for (const route of EXPECTED_ROUTES) {
27
+ const html = path.join(DIST, `${route}.html`);
28
+ expect(existsSync(html)).toBe(true);
29
+ }
30
+ ```
31
+
32
+ ## Per-route titles
33
+
34
+ `<Stack.Screen options={{ title: "..." }}>` sets the native header title; the
35
+ web `<title>` comes from `Head` (`expo-router/head`). Assert the title the
36
+ exported HTML actually carries:
37
+
38
+ ```typescript
39
+ const html = readFileSync(path.join(DIST, "settings.html"), "utf8");
40
+ expect(html).toMatch(/<title>[^<]*Settings[^<]*<\/title>/);
41
+ ```
42
+
43
+ ## Expected initial content
44
+
45
+ The exported page should ship its prerendered content, not a bare shell —
46
+ that is what makes static export worth shipping at all. Assert a stable marker
47
+ of the route's expected first paint:
48
+
49
+ ```typescript
50
+ expect(html).toContain("Sign in to continue");
51
+ ```
52
+
53
+ Keep the marker to content that exists in the static HTML, never something
54
+ hydration adds later.
@@ -478,3 +478,10 @@ Add className to component props:
478
478
  ```tsx
479
479
  type Props = React.ComponentProps<typeof RNView> & { className?: string };
480
480
  ```
481
+
482
+ The same rule applies at every styling API boundary — `useCssElement`,
483
+ `cssInterop`, or `styled()`: type the wrapped component's props explicitly
484
+ (`React.ComponentProps<typeof X> & { className?: string }`) and pass props
485
+ through, rather than casting to a wider type. A cast compiles over a
486
+ prop-shape drift that an explicit type would refuse — the boundary is where
487
+ the drift is cheapest to catch.
@@ -394,6 +394,31 @@ Components from third-party libraries (e.g., `react-native-bouncy-checkbox`, `re
394
394
 
395
395
  ---
396
396
 
397
+ ## Reveal-on-Focus Assertions
398
+
399
+ `toBeVisible()` proves the element exists and is not hidden — it does NOT
400
+ prove the element crossed onto the screen. A focused element scrolled off-view
401
+ still reports visible. For any "focus reveals the element" behavior (skip
402
+ links, focus-trapped modals, scroll-into-view containers), assert on layout,
403
+ not just visibility:
404
+
405
+ ```typescript
406
+ // Rejects when the element has no box at all (display: none, detached).
407
+ const box = await page.getByTestId("dialog:panel").boundingBox();
408
+ expect(box).not.toBeNull();
409
+
410
+ // Then prove it is actually inside the viewport — the part toBeVisible()
411
+ // cannot say.
412
+ await expect(page.getByTestId("dialog:panel")).toBeInViewport();
413
+ ```
414
+
415
+ Pair them: `boundingBox()` answers "is there a box" (null means never laid
416
+ out), `toBeInViewport()` answers "did it cross onto the screen". An assertion
417
+ that skips the null check reads a missing layout as a viewport miss, which is
418
+ a different bug.
419
+
420
+ ---
421
+
397
422
  ## Implementation Checklist
398
423
 
399
424
  When adding E2E test coverage to a component:
@@ -588,3 +588,25 @@ afterAll(() => {
588
588
  console.error = originalError;
589
589
  });
590
590
  ```
591
+
592
+ ## Migrating jest.mock Usage
593
+
594
+ When moving a test file onto the managed setup, scope the migration to the
595
+ file under your hand — a suite-wide mock sweep is where subtle behavior
596
+ changes hide.
597
+
598
+ - **Prefer renderer-compatible mocks.** A mock that works in the Node
599
+ environment but reads `window`, native modules, or ESM-only entry points
600
+ fails under the jsdom/renderer the Expo preset provides. Mock the seam your
601
+ component actually imports (`jest.mock("nativewind", ...)`,
602
+ `jest.mock("@/lib/env", ...)`) — never reach around it to mock a transitive
603
+ dependency.
604
+ - **Keep factories stable and hoisted.** Jest hoists `jest.mock` calls above
605
+ imports, so a factory cannot close over outer variables. Everything the
606
+ factory needs must come from `jest.requireActual`, `jest.requireMock`, or a
607
+ `mock`-prefixed name. A factory that silently returns a different shape per
608
+ run is the migration failure that surfaces as unrelated flakes.
609
+ - **Check version compatibility, not history.** A pinned workaround for an
610
+ old jest-expo/Expo SDK issue is not a permanent blocker — verify whether the
611
+ current versions still need it before carrying it forward. Historical Expo
612
+ issues expire; copy them forward only when they reproduce.