placementt-core 1.400.963 → 1.400.964

package/README.md

@@ -6,6 +6,69 @@ Shared code (types, Firebase helpers, utilities, shared UI) used by `placementt-
 
 Normally, `placementt-web` and `placementt-backend` depend on published npm versions of this package (via the `dev`/`prod`/`emu` dist-tags). While you're working on a change here, you don't want to publish to npm just to test it — instead, build it locally and link it into the consuming repo with [yalc](https://github.com/wclr/yalc).
 
+There are two ways to do this: **watch mode**, which rebuilds and relinks automatically as you save (recommended for any real iteration), or a manual **one-off** build/link for a single quick check. Watch mode is documented first below; the one-off flow still works and is documented further down.
+
+## Live watch mode (recommended)
+
+### 1. Watch and publish from placementt-core
+
+```
+yarn watch-local dev    # or: yarn watch-local prod (or -d / -p)
+```
+
+Keeps `tsc --watch` running against your current working tree (including uncommitted changes), swapping in dev/prod config for the whole session the same way `test-local` does. On every successful compile it runs `yalc push`, which republishes to the yalc store **and** pushes the update straight into any repo that's already linked this package — no need to re-run anything on the consumer side after the first link.
+
+Leave this running in its own terminal for as long as you're iterating. Stop it with Ctrl+C when you're done — it restores `package.json`, `src/firebase/firebaseConfig.tsx`, and `src/hooks.tsx` to their committed state and resets `lib/` via `git checkout`, so your working tree is left clean automatically.
+
+**Important:** whichever flavor (`dev`/`prod`) this is running as is what gets pushed to *every* linked consumer, regardless of which flavor they originally linked with — yalc tracks link targets by package name only, not by version. Don't run this in `prod` if you're mid-session testing against dev data elsewhere.
+
+### 2. Run the matching watcher in the consuming repo
+
+First time only, link the package (same command as the one-off flow below):
+
+```
+yarn core dev     # or -d / -p — run in placementt-web or placementt-backend
+```
+
+Then, instead of manually restarting after every change, use one of:
+
+**placementt-web — live reload, no restart (preferred)**
+```
+yarn dev:core-live dev / yarn dev:core-live prod   # or prod / -d / -p
+```
+Runs the dev server through [craco](https://github.com/dilanx/craco) (`craco.config.js`) instead of plain `react-scripts`, which tells webpack to actually watch `node_modules/placementt-core` and force a rebuild via `compiler.watching.invalidate()` whenever it changes — so changes show up through normal Fast Refresh with no server restart. It clears `node_modules/.cache` once, right before boot — skip that and the very first boot can silently serve whatever was last cached by an ordinary `yarn start` (this is what caused the app to boot on the wrong Firebase project despite the `dev` flag).
+
+Caveat: since there's no server restart, if `watch-local`'s flavor changes *while* `dev:core-live` is open in the browser, the page can end up in a mixed state — the old Firebase Auth session from one project, new code pointing at the other. Do a hard refresh after switching flavors mid-session.
+
+**placementt-web — restart-based (fallback)**
+```
+yarn dev:core dev    # or prod / -d / -p
+```
+Watches `node_modules/placementt-core` and, on every change, kills whatever's on port 3000, clears `node_modules/.cache`, and restarts `yarn start`. Slower (a full recompile every time, several seconds) but simple. The cache clear isn't optional — webpack treats `node_modules` packages as version-pinned/immutable for caching purposes, and since the local yalc build always publishes under the same constant sentinel version, a restart alone does *not* pick up the change (confirmed — a stale build kept getting served without it). Use this if `dev:core-live` ever misbehaves.
+
+**placementt-backend**
+```
+yarn dev:core dev    # or prod / -d / -p — from repo root or functions/
+```
+Watches `node_modules/placementt-core` and, on change, rebuilds the functions bundle and restarts `firebase emulators:start --only functions`.
+
+### 3. Clean up when you're done
+
+- Stop `watch-local` in core (Ctrl+C) — it self-restores, nothing to clean up manually.
+- Stop `dev:core` / `dev:core-live` in the consuming repo(s).
+- Unlink and go back to the real published version:
+  ```
+  yalc remove placementt-core
+  yarn install
+  ```
+  This restores `package.json`'s `placementt-core` entry to the real npm version and reinstalls it properly. `.yalc/` and `yalc.lock` are gitignored in the consuming repos, so they won't show up as clutter even while linked.
+
+### Known issues
+
+- **"Invalid hook call" / duplicate React instances in placementt-web:** this package declares `expo` as a hard dependency (unused in `src/`, likely leftover), which pins its own `react@18.x`. When linked locally, yarn can nest a private copy of React inside `node_modules/placementt-core/node_modules` if it can't hoist a single version — placementt-web's `package.json` works around this with a `resolutions` override forcing `react`/`react-dom` to the app's version everywhere. If you see this error after linking, check for a nested `node_modules/placementt-core/node_modules/react` first.
+
+## One-off testing (no watch mode)
+
 ### 1. Publish your local changes to the yalc store
 
 From this repo, run:

package/package.json

@@ -2,7 +2,7 @@
   "private": false,
   "name": "placementt-core",
   "author": "Placementt",
-  "version": "1.400.963",
+  "version": "1.400.964",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {