bgrozev
diff --git a/‎.claude/skills/add-persisted-field/SKILL.md‎
Lines changed: 75 additions & 0 deletions b/‎.claude/skills/add-persisted-field/SKILL.md‎
Lines changed: 75 additions & 0 deletions
diff --git a/‎.claude/skills/verify-flip/SKILL.md‎
Lines changed: 65 additions & 0 deletions b/‎.claude/skills/verify-flip/SKILL.md‎
Lines changed: 65 additions & 0 deletions
diff --git a/‎.env.example‎
Lines changed: 1 addition & 1 deletion b/‎.env.example‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.eslintrc.js‎
Lines changed: 71 additions & 9 deletions b/‎.eslintrc.js‎
Lines changed: 71 additions & 9 deletions
diff --git a/‎.github/workflows/static.yml‎
Lines changed: 6 additions & 4 deletions b/‎.github/workflows/static.yml‎
Lines changed: 6 additions & 4 deletions
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 0 deletions b/‎.gitignore‎
Lines changed: 3 additions & 0 deletions
@@ -0,0 +1,75 @@
+---
+name: add-persisted-field
+description: Add a field to a persisted FliP document (Settings, FlockingParams, PatternParams, a new store, ...) through the versioned-codec pipeline. Use when adding any user-facing option that must survive a reload.
+---
+
+# Add a persisted field to FliP
+
+Every persisted document goes through a **versioned codec**
+(`util/storage.ts createVersionedCodec`) whose `migrate*` loader lives in
+`core/model.ts` and **must never throw** — old/corrupt localStorage has to
+degrade gracefully. Skipping any step below breaks a test; do them all.
+
+## Adding a field to an EXISTING document (the common case)
+
+1. **Type** — add the field to the interface in `core/` (e.g.
+   `FlockingParams` in `core/flocking.ts`, `Settings`/`UnitPreferences`,
+   `PatternParams`).
+2. **Default** — add it to the `DEFAULT_*` constant in `core/model.ts`.
+   Distances persist in **statute miles**; express nm/km defaults via
+   `displayToMiles(x, 'nm')`, not a magic number.
+3. **Migration** — add the field to the matching `migrate*` in
+   `core/model.ts`, using the existing helpers so garbage never throws:
+   - number in a range → `limitedNumber(r.x, d.x, LIMITS.xxx)`
+   - free number → `finiteNumber` / `normalizeDirection`
+   - enum/string set → `oneOf(r.x, ALLOWED, d.x)`
+   - boolean → `booleanOr(r.x, d.x)`
+   - string → `stringOr(r.x, '')`
+   - nested/array → a dedicated `migrateX` that filters bad entries.
+4. **Limits** — if it needs bounds, add a `LIMITS.xxx` entry in
+   `core/validation.ts`.
+5. **Tests** — in `core/model.test.ts`:
+   - the garbage cases already assert `migrateX(g).toEqual(DEFAULT_X)`;
+   - the **"keeps valid params"** test does `.toEqual(fullObject)` — you
+     MUST add your field to that fixture or it fails;
+   - add a case: valid value kept, out-of-range clamped, missing → default.
+6. **Wire the UI** — thread it: `App.tsx` → component props → the control
+   (usually `NumberInput`/`Switch`/`ToggleButton`). Direction fields use
+   `NumberInput`'s `wrap={360}`; ring/offset fields round with
+   `roundDist(.., unit, 2)`.
+
+## Adding a WHOLE NEW persisted store
+
+Also do, in `hooks/useAppState.tsx`:
+
+7. `const [storedX, setStoredX] = useLocalStorageState<X>('flip.x', DEFAULT_X,
+   { codec: createVersionedCodec(SCHEMA_VERSION, migrateX) });`
+   then `const x = storedX ?? DEFAULT_X;` (wrap in `useMemo` if it's an
+   object/array read by a `useCallback`, or lint flags the dep).
+8. Add `x` + its setter to the context **interface**, the value **memo**
+   (both the object and its dependency array), and clear it in `resetAll`.
+9. If the codec's stored type includes `null` (a "never set yet" state),
+   widen the codec generic — and if a parenthesized `keyof` generic trips
+   the `indent` lint rule, hoist it to a `type` alias first.
+
+## Gotchas seen repeatedly
+
+- Adding to the type but not the default/migration → a `tsc` "missing
+  property" error or a failing `.toEqual` test. Add all three together.
+- `SCHEMA_VERSION` does not change for an additive field — the migration
+  fills the default for old envelopes.
+- A field only relevant to one mode still persists in the one shared
+  document; gate its *use*, not its storage (e.g. flocking corridors).
+
+## Verify
+
+`npm test`, `npm run lint` (0 errors, ≤ 50 warnings), `npm run build` all
+green before committing. Commit the slice immediately (per the branch's
+working agreement).
+
+### Regenerating golden values
+
+If a core-math change shifts pinned test numbers (as the `addWind` fix
+did), don't hand-edit them: write a throwaway `*.test.ts` that runs the
+pipeline and `console.log`s the new values, paste them in, delete the
+scratch test. Same trick works for any large pinned fixture.
@@ -0,0 +1,65 @@
+---
+name: verify-flip
+description: Verify a FliP change actually works, given this repo's real browser-automation limits. Use before committing anything with a runtime surface, especially map/flocking UI.
+---
+
+# Verify a FliP change
+
+The always-run gate: `npm test`, `npm run lint` (0 errors, ≤ 50 known
+warnings), `npm run build` — green before every commit.
+
+Beyond that, **prefer a unit or hook test of the actual contract over a
+browser check.** The pure core (`core/`) and the derive hooks
+(`useFlockingPath`, `usePresets`, `useAppState`) are directly testable
+with Vitest + RTL `renderHook`; a targeted test proves more, faster, than
+driving the UI.
+
+## The falsifiability rule (the important one)
+
+**When an automated check passes, ask: would it have FAILED before the
+change?** If not, it proved nothing.
+
+To find out: stash the change, re-run the exact same check on the
+pre-change code. Identical behavior ⇒ the check is worthless, and a
+"pass" is a false positive. This session, a browser check appeared to
+confirm a click-to-move fix; the old code behaved identically, because
+automated map clicks never reach the handler at all. It was re-verified
+with a unit test of the contract (`map/layers/TargetEditLayer.test.tsx` —
+note the `vi.mock('..')` that stubs the provider-bound primitives).
+
+## Browser automation limits here (measured, not guessed)
+
+Reliable: DOM queries, `javascript_tool`, screenshots, reading
+`localStorage` to confirm a state write, `read_page` refs for clicking
+real DOM buttons.
+
+Unreliable / broken:
+- Coordinate clicks frequently do **not** reach the Google Maps click
+  handler (so "clicked the map, nothing moved" proves nothing).
+- Synthetic drags do **not** drive the map drag handles.
+- Wheel-zoom can hang the tooling.
+- `read_page` sometimes reports a 0x0 viewport on panel routes.
+- Reading an input's value synchronously after dispatching an `input`
+  event shows the pre-React value — `await` a tick first.
+
+Testing UI state via localStorage: seed `flip.mode`, `flip.winds`,
+`flip.flocking.params` etc. as `{schemaVersion:1, doc:{...}}` envelopes,
+`location.href='/flocking'`, then read the panel via `data-testid`
+(`flocking-spot`, `flocking-miss`, `flocking-deviation`) or
+`input[aria-label=...]`, and read the params back out of localStorage to
+confirm writes.
+
+## Never yet exercised by a real pointer
+
+These pass by unit test + DOM inspection but no automated drag can drive
+them — flag for the owner rather than claim verified:
+
+- Flocking free mode: the jumprun 2-D **move** handle, the **rotate**
+  handle, the canopy-rotate handle at the flight's end.
+- The **Spot Reference** drag (dragging pins it).
+- The flocking target drag (click-to-move is deliberately off there).
+
+## PWA
+
+The service worker only exists in a production build — verify offline/PWA
+behavior with `npm run build && npm run preview`, not the dev server.
@@ -1 +1 @@
-REACT_APP_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
+VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
@@ -1,4 +1,5 @@
 module.exports = {
+    "root": true,
     "env": {
         "browser": true,
         "es2021": true
@@ -8,28 +9,89 @@ module.exports = {
         "plugin:react/recommended",
         "@jitsi/eslint-config"
     ],
-    "overrides": [
-    ],
-    "parser": "@babel/eslint-parser",
+    "parser": "@typescript-eslint/parser",
     "parserOptions": {
         "ecmaVersion": "latest",
         "sourceType": "module",
-        "requireConfigFile": false,
         "ecmaFeatures": {
             "jsx": true
-        },
-        "babelOptions": {
-            "presets": ["@babel/preset-react"]
         }
     },
     "plugins": [
-        "react"
+        "react",
+        "react-hooks",
+        "@typescript-eslint"
+    ],
+    "overrides": [
+        {
+            "files": ["*.ts", "*.tsx"],
+            "extends": [
+                "plugin:@typescript-eslint/eslint-recommended",
+                "plugin:@typescript-eslint/recommended"
+            ],
+            "rules": {
+                // Warn-only for now; tighten during Phase 1 refactors
+                "@typescript-eslint/no-explicit-any": 1,
+                "prefer-const": 1,
+                "react-hooks/exhaustive-deps": 1
+            }
+        },
+        {
+            "files": ["*.test.ts", "*.test.tsx"],
+            "env": {
+                "node": true
+            }
+        }
     ],
     "rules": {
         "require-jsdoc": 0,
         "max-params": 0,
         "react/prop-types": 0,
-        "object-property-newline": 0
+        "object-property-newline": 0,
+
+        // Match the existing 2-space code style instead of reformatting the
+        // whole codebase (@jitsi config assumes 4-space).
+        "indent": ["error", 2, { "SwitchCase": 1 }],
+
+        // Stylistic rules from @jitsi/eslint-config that the existing code
+        // doesn't follow; disabled to keep lint useful without a mass reformat.
+        "array-bracket-spacing": 0,
+        "padding-line-between-statements": 0,
+        "no-multi-spaces": 0,
+        "curly": 0,
+        "max-len": 0,
+        "lines-around-comment": 0,
+        "no-extra-parens": 0,
+        "import/order": 0,
+        "operator-linebreak": 0,
+        "brace-style": 0,
+        "no-negated-condition": 0,
+        "arrow-body-style": 0,
+        "max-statements-per-line": 0,
+        "sort-imports": 0,
+        "key-spacing": 0,
+        "comma-dangle": 0,
+        "quotes": 0,
+        "no-continue": 0,
+        "no-confusing-arrow": 0,
+        "newline-per-chained-call": 0,
+        "no-mixed-operators": 0,
+        "no-bitwise": 0,
+
+        // Substantive rules the current code violates: warn for now, clean up
+        // in Phase 1 refactors (auto-fixing e.g. eqeqeq can change behavior).
+        "eqeqeq": 1,
+        "no-eq-null": 1,
+        "no-shadow": 1,
+        "no-implicit-coercion": 1,
+        "dot-notation": 1,
+        "prefer-const": 1,
+        "prefer-template": 1,
+        "no-extra-boolean-cast": 1,
+        "import/no-duplicates": 1,
+        "@typescript-eslint/no-explicit-any": 1,
+        "react-hooks/rules-of-hooks": 2,
+        "react-hooks/exhaustive-deps": 1
     },
     "settings": {
         "react": {
 
@@ -33,18 +33,20 @@ jobs:
         uses: actions/checkout@v4
       - name: Setup Pages
         uses: actions/configure-pages@v5
-      - name: Use Node.js 
-        uses: actions/setup-node@v3
+      - name: Use Node.js
+        uses: actions/setup-node@v4
         with:
+          node-version: 24
           cache: 'npm'
       - run: npm install
-      - run: npm test -- --watchAll=false
+      - run: npm run lint
+      - run: npm test
       - run: node scripts/inject-ga.js
         env:
           GA_ID: ${{ secrets.GA_ID }}
       - run: npm run build --if-present
         env:
-          REACT_APP_GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
+          VITE_GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
 
@@ -28,3 +28,6 @@ yarn-error.log*
 *iml
 .idea
 *.swp
+
+# vite-plugin-pwa dev output
+dev-dist
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-REACT_APP_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here`
	`1`	`+VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here`