wenay-react2 1.0.41 → 1.0.42

package/doc/wenay-react2-rare.md

@@ -12,7 +12,7 @@ New code teaches and imports the short canonical surface:
 
 Old names are recorded only in `WENAY_REACT2_RENAMES.md`; do not export new compatibility aliases casually. Existing public APIs should usually remain supported during internal refactors; removals require an explicit migration cut with a separate task, migration notes, changelog, and usage signal. Default style contracts are stricter: do not remove old default classes/styles until the replacement class/token path is shipped and documented.
 Do not add new examples with Get*, FuncJSX, *2/*3, or business-specific helper names.
-If a primitive needs app policy, build a small app wrapper above it.
+If a primitive needs app policy, build a small app wrapper above it.
 If behavior is reusable, expose it first as a headless use*/create* API. The hook/controller may return methods, getters, props/bind helpers, or a small API object; visual components and QA cards should consume that surface instead of becoming the only implementation.
 ```
 
@@ -53,6 +53,14 @@ confirmModal({modal, func, password?})
 
 `inputModal` and `confirmModal` accept either a setter function or the `useModal()` controller.
 
+Internal Overlay (A9, 2026-07-10): `components/Overlay.tsx` is the ONE portal+scrim+outside-click+
+Escape composition; `ModalProvider` and `SettingsDialog` are adapters over it (behavior 1:1,
+SettingsDialog keeps its own two-stage Escape by NOT passing `onEscape`). It is deliberately not
+exported: apps use ModalProvider/useModal/SettingsDialog. The render-slot stores above, the
+LeftModal drawer (gesture-driven, scrim-less), and `ModalWrapper`/Input helpers (backdrop-less,
+hosted inside another modal slot) are NOT overlays and stay separate. This leaf is also where all
+scrim/portal DOM lives - the seam for a future react-native view layer.
+
 Left-side modal/menu helpers:
 ```
 LeftModal({arr, zIndex})
@@ -229,7 +237,7 @@ Semantics that are easy to get wrong:
   (setting columnDefs resets grid order). `setPresentGate(keys|null)` is for stable-schema app modes:
   it marks gated-out buttons disabled and hides those grid columns through applyColumnState without
   mutating persisted `visible`. No loop: applyColumnState never adds/removes columns. Null actual presence
-  and null gate together mean all present; if a gate is set, grid-less consumers still see that gate.
+  and null gate together mean all present; if a gate is set, grid-less consumers still see that gate.
 - `listSource` = the `{order, visible}` slice exposed as a `UiListSource` (Toolbar's
   external-config contract): plug it into `createToolbar({source})` and the toolbar, the icon menu
   and the grid all mirror one config. Its setConfig MERGES visible and re-appends via normalize, so
@@ -244,6 +252,29 @@ Semantics that are easy to get wrong:
   stand: hot-reload recreates a module-level controller while the live grid stays attached to the
   OLD instance, so store->grid needs an F5; in a real app the module runs once.
 
+High-level kit (`createColumnGrid`, `grid/columnState/columnGrid.tsx`):
+```
+createColumnGrid({key, columnDefs?, columns?, data?, getId?, def?, saveMs?, toolbar?, autoSizeOnColumnCountChange?})
+    -> {state, toolbar, api, grid, tableProps, Table, Menu, Dots, Cards, Toolbar, Settings, View}
+useColumnGrid(opts) -> same controller, captured once for component-local setups
+```
+- This is the default convenience layer for ordinary app grids that all need the same column menu.
+  It infers `ColumnMeta` from leaf `ColDef`s (`colId` -> `field`, title from `headerName` -> key)
+  and merges optional `columns` overrides for `fixed`, `short`, `icon`, `defaultVisible`, `cardRole`,
+  and group semantics. Unknown explicit overrides are appended, so grid-less/card-only fields still work.
+- `Table` and `tableProps()` wrap `AgGridTable` and wire `state.grid.attach/detach` automatically.
+  Their default `autoSizeColumns=false` is deliberate: the wrapper is for persisted column layout, so
+  auto-fit must be opt-in. `autoSizeOnColumnCountChange` is a narrower opt-in: it calls
+  `sizeColumnsToFit()` only when `visibleKeys().length` changes after a columnState edit.
+- `View` is a small representation switch (`mode:'table'|'cards'`) with controls
+  (`'menu'|'dots'|'toolbar'|false|'auto'`). `auto` resolves to the built-in dots overlay for both
+  table and card mode; the wrapper sets dot max to the full column count unless overridden. `Dots` is
+  not card-specific; on table mode it edits the same config and the attached grid applies visibility,
+  order, and sort through columnState. `data`/`getId` can live on the controller defaults or be
+  passed per `View` render.
+- Use raw `createColumnState` plus `createToolbar` when the app needs a custom skin like QA card 30,
+  a runtime `presentGate`, special group mode buttons, or nonstandard persistence timing.
+
 Icon menu (ColumnsMenu / MenuStrip, `grid/columnState/ColumnsMenu.tsx`):
 ```
 <MenuStrip items={MenuStripItem[]} onItem? onMove? move? tail? holdMs?=150 compact? />
@@ -284,7 +315,7 @@ Mobile (no ag-grid, no storage - the config alone):
   as dots move), `cardRole:'title'` = the header (else the first visible key), `cardRole:'accent'`
   = a badge, the rest are label+value. It sorts by the sticky `config.sort` itself
   (numeric/locale comparator) even when the sorted column is hidden.
-Styling uses shared classes `.wenayColDots*` / `.wenayCardList*`; runtime geometry remains inline because dot positions and drag transforms are state-derived. QA cards 28 (grid layer + F5 restore), 29 (mobile dots + cards), 30 (toolbar icon menu + grouped sub-column mode button), 31 (Toolbar over columnState.listSource + pseudo-icons).
+Styling uses shared classes `.wenayColDots*` / `.wenayCardList*`; runtime geometry remains inline because dot positions and drag transforms are state-derived. QA cards 28 (grid layer + F5 restore), 29 (mobile dots + cards), 30 (toolbar icon menu + grouped sub-column mode button), 31 (Toolbar over columnState.listSource + pseudo-icons), 32 (createColumnGrid wrapper + dots driving table/cards).
 
 ## Outside / Buttons Compatibility
 ```
@@ -297,6 +328,10 @@ StyleOtherColumn
 
 `Button`, `OutsideButton`, `HoverButton`, and `AbsoluteButton` are still direct components rather than hook controllers.
 
+`Button` persists its open/closed status under `keyForSave` (module-lifetime; same naming as
+FloatingWindow/Resizable/RightMenu); the old `keySave` prop is a deprecated alias (`keyForSave`
+wins when both are set).
+
 ## Drag / Resize Low Level
 ```
 FloatingWindowBase(props)                  // lower-level react-rnd wrapper
@@ -306,8 +341,8 @@ floatingWindowMap                           // persisted RND map (ObservableMap)
 FloatingWindowUpdate
 FloatingWindowProps / FloatingWindowController / FloatingWindowSavedGeometry
 
-DragBox(props)                       // absolute-position movement component
-DragArea(props)                     // low-level movement component
+DragBox(props)                       // delta-drag component; thin adapter over useDraggableApi (A7)
+DragArea(props)                     // @deprecated: unique semantics kept as-is; prefer useDraggableApi/DragBox
 FResizableReact(props)
 mapResiReact                        // persisted resize map (ObservableMap)
 OutlineDragDemo()
@@ -321,6 +356,18 @@ const drag = useDraggableApi(...)
 
 `useDraggable(...)` is kept as the simple hook wrapper; `useDraggableApi(...)` is the controller-style shape.
 
+Drag primitives after the A7 pass (2026-07-10): `DragBox` is a thin adapter over
+`useDraggableApi({holdMs: 0, trackState: false, onMove})` - same observable contract as its old
+bespoke loop (immediate start, per-tick imperative `onX`/`onY` with the delta from the press
+point, no re-render per move tick, `onStop` only after a real gesture, `last` ref shares the live
+position object; pinned by `__test/dragBox.test.tsx`, QA card 35). `DragArea` stays untouched and
+`@deprecated`: no consumers, and its semantics are unique (document.body listeners,
+`stopPropagation` per move tick, ABSOLUTE coords, no preventDefault) - re-basing it would change
+observable behavior; removal only in a breaking version. `useFloatingWindowController`'s header
+loop and `StickerMenu` deliberately keep their own loops: viewport clamp + `e.buttons===1` release
+recovery + persistence/z-stack, and mount-lifetime listeners + click-vs-drag suppression
+respectively, are load-bearing behavior `useDraggableApi` does not model.
+
 Reorder-by-drag (useReorder, `hooks/useReorder.tsx` - extracted from the Toolbar editor, which is
 its first consumer):
 ```
@@ -519,6 +566,10 @@ Semantics that are easy to get wrong:
 - `useReplayHistory.seek` kills the live subscription imperatively (guarded off, double-call safe), folds `history.at(where)` through `apply` (keyframe + tail; a keyframe fully redefines consumer state, so `reset` is rarely needed), and freezes. `play()` resubscribes `{since: pos}` -> archive tail -> live handover.
 - `useStoreReplayEach` composes existing pieces instead of calling `Observe.syncStoreReplayEach` (which builds a FRESH store per call): the mirror lives in a ref (like `useStoreReplayMirror`), `store.each()` is subscribed in an effect declared BEFORE the sync effect (hook-call order guarantees the per-key subscriber exists when the keyframe applies — the expansion is never missed), then `useStoreReplaySync` drives the wire. Consequences: within one mount every resubscribe (StrictMode, `restart()`, `enabled` toggle, `staleMs`/`policy` change) reconnects by tail ON TOP of kept state and the consumer sees only the diff — no snapshot/`initial` dance (the library one-call needs `{since, initial: snapshot}` for that). After a FULL unmount pass `{since: prev.seq(), initial: prev.store.snapshot()}` like the library contract. `drain` is creation-time (it goes to `createStore`); changing it later does nothing. The fold target must live outside React state (ref/Map/grid api) — the hook renders nothing; `controller.store` is a normal store for `useStoreNode`/`useStoreKeys` extras.
 - Server primitives (`conflateReplay` per connection, `archiveReplay`) intentionally have no hooks: they live where the RPC server is built.
+- Route coordinator (common2 1.0.67 `Replay.createRouteCoordinator`): the coordinator owns promotion/fallback/shadow via policy hooks; consumers subscribe on a pair `link`, whose handle matches our route hooks (`ready, seq(), label(), active()`) minus `switchRoute` — the transport switch is invisible by the seq contract. Our route hooks (`useReplayRouteSubscribe` etc.) remain the manual-`switchRoute` wrapper over `replayRouteSubscribe`; they do NOT sit on top of a coordinator. React surface for coordinator links (subscribe hook + route-state/`promoteDirect` controls for ops UI) is a target-backlog item — do not bend the existing route hooks to accept links implicitly.
+- WebRTC direct path (common2 1.0.68): `createWebRtcConnector({port, rtc, ...})` is the coordinator's direct `RouteConnector`; `rtc` is an injected factory and in the browser that injection (`() => new RTCPeerConnection(cfg)`) belongs to the app/React side — common2 stays lib.dom-free. Signaling rides the EXISTING rpc socket (`createSignalHub` port exposed by `createRpcServerAuto`), so no new connection management appears in React; channel death / revoke surfaces as loud `onError` on the line (never silence), which the existing hooks already map to `error`. Nothing here needs a hook by itself — it matters as the direct transport under a future adapter (target backlog).
+- Peer SDK (common2 1.0.69 `Peer` / `wenay-common2/peer`): the one-call layer over rpc + store + replay + route coordinator — `createPeerClient({remote, account, initial, rtc?})` publishes the own store as a patch line and `peer(account)` returns a live mirrored store + route control; relay and direct share the OWNER's seq space (`createPatchRelayJournal`), so hand-offs are plain seq resumes, no keyframe reset. This is the intended React adoption surface (a `usePeer` adapter is the target-backlog item, superseding the raw coordinator-link hook idea): the mirrored store already plugs into `useStoreNode`/`useStoreKeys` as-is. 1.0.70 ships the oracle suites + `demo/` stand in the package — living examples per subsystem (`replay/peer-sdk.test.ts` is the Peer contract).
+- Media capture (common2 1.0.66 `Media` namespace / `wenay-common2/media`): CONSUMPTION needs no new hooks — `Media.createAudioSource` / `Media.createVideoSource` return `[emit, listen] & control`, with `replay:true` the `listen` is a normal replay line, so `useReplaySubscribe` / `useReplayFrame` cover it; frames are one `Uint8Array` (40-byte fixed header + raw payload, `Media.decodeMediaFrame`) and follow the existing fold-outside-React rule (canvas/AudioContext via ref). The capture `control` side (`start()` resolving to `'idle'|'requesting'|'live'|'denied'|'no-device'|'error'`, `stop()`, `setDevice`, `listDevices`, stats) is a permission/device/lifecycle state machine — exactly hook-shaped; a `useMediaSource` capture hook + QA card is a recorded target goal (supersedes the earlier "wrap it app-locally" stance). Backpressure defaults live in common2 (audio = lossless queue, video `replay:true` = keep-latest frame recovery); the client-side knobs are the same `policy`/`hint` as any replay line.
 
 QA cards 23/24/25/26 (`testUseReact/replayVideo.tsx`, all in-proc): synthetic 10fps jpeg-frame producer on `Replay.replayListen({history, current})`; client A = direct `exposeReplay` remote; client B = simulated slow wire (1 envelope per rateMs) behind `conflateReplay({pending: () => buf.length, highWater: 4, lowWater: 1, keyOf: () => "frame"})`; client C = `archiveReplay` + `openHistory` scrubber; client D = freshness (`staleMs: 2000`, `React.memo` + no tick, mounted inside a local `<StrictMode>`; the flat renders counter under growing frames is the no-per-event-render proof; "stall producer" toggles the emit interval, "new client" remounts by key for the stalled-mount case; card 24 has the same via `staleMs: 2500` on the mirror); client E = pull path (`useReplayFrame` over the direct remote with a wrapped counting `frame()`, pace switch 250ms/1s/3s keeps seq). `window.__replayVideoDemo` is exposed for debugging (wire.setRateMs, stats). Node-verified: slow wire delivered 12/36 envelopes yet converged to the last frame with bounded buffer (coalesced tail recovery); `syncStoreReplay` off() freezes the mirror and `{since}` resubscribe catches up by tail. Card 25 = per-key feed (`useStoreReplayEach` over `exposeStoreReplay`): a dict-of-rows store, producer touches ONE random row per tick, the fold target is a plain Map with per-row cb counters — only the mutated row's counter grows, keyframe/`replace` are the only whole-table expansions, delete arrives as `(key, undefined)`. Card 26 = route hand-off (`useReplayRouteSubscribe` over the same video line): one canvas starts on relay, switches direct/relay by `switchRoute`, and failed replacement keeps the previous route alive. Browser QA of throttling-sensitive behavior needs a VISIBLE tab: hidden-tab timer/effect throttling stalls the producer and delays passive effects (known stand caveat).
 
@@ -555,6 +606,18 @@ MainPage()
 
 The context logger is a larger UI surface; the global `logsApi` is still the shorter integration point. `createLogsController` is the headless layer for append/limit/settings state; `useMessageEventLogsController` owns the global notification queue/timers/settings, while `MessageEventLogsView` and `MessageEventLogCard` own rendering. `PageLogs`, `MessageEventLogs`, and `LogsPage` remain compatibility UI wrappers. `useLogsTableController` and `useLogsNotificationsController` expose the provider-local table/notification state while `LogsTable` and `LogsNotifications` keep the visual wrappers. Shared logger chrome lives in `src/common/src/logs/logStyles.ts` and is themed through `--logs-*` tokens.
 
+Full-page table controller (`useLogsPageTable` -> `LogsPageTableController`): the last logs table
+moved to the controller pattern. Semantics that matter: the grid receives a MOUNT-TIME snapshot of
+the accumulated log map once (`useState` initializer) and afterwards lives on
+`applyTransactionAsync` appends from the mini feed - re-renders do not re-feed `rowData`, so row
+identity is per-append copy exactly as before. The importance filter is ONE method
+(`applyImportanceFilter(min?)`: set -> `setFilterModel` greaterThanOrEqual on `var`, unset ->
+`destroyFilter`), used by both the settings subscription and `onGridReady` (which skips the
+destroy branch - a fresh grid has no filter). Both data subscriptions are `updateBy(obj, cb)`
+WITH a callback: they run imperatively on `renderBy` and never re-render the component.
+`gridProps` is one stable memo - spread it into `AgGridTable`; `fit()` is exposed for the legacy
+`update` prop, which `PageLogs` still honors. QA card 9.
+
 ## Cache / Memory / Browser Utilities
 ```
 browserCacheStorage
@@ -577,6 +640,9 @@ memoryUpdate(key, mutate)
 memoryMarkDirty(key)
 createSearchHistory({key, max?})
 deepMergeWithMap(target, source)
+structEqual(a, b)                   // deep equality for plain data trees; JSON.stringify-idiom
+                                    //   tolerances (undefined props absent, NaN==NaN) WITHOUT
+                                    //   its key-order sensitivity; not for Maps/Sets/cycles
 memoryCache
 memoryMaps
 
@@ -584,9 +650,27 @@ ArrayPromise({arr, catchF?, thenF?})
 PageVisibilityProvider
 PageVisibilityContext
 setAutoStepForElement(input, {minStep?, maxStep?})
+
+useCacheMapPersistence(cache: CacheMap, delay?=300) -> {isDirty(), flush(), save(), reload()}
 ```
 
-Cache helpers are process/browser storage utilities, not React state management.
+Layering (2026-07 architecture pass): the persisted maps (`floatingWindowMap`, `mapResiReact`,
+`mapRightMenu`) are DECLARED in the utils leaf `utils/persistedMaps.ts` and re-exported by their
+owning components (FloatingWindow/Resizable/RightMenuStore) - importing `memoryStore`/`memoryCache`
+no longer pulls react-rnd or the Menu tree; only `import type` lines point upward (erased at build).
+Shared order helper `utils/fixedOrder.ts` (`pinFixedOrder`, `movedOrderWithFixed`) is the single
+implementation of the "fixed entries pin to descriptor index" invariant used by columnState,
+ColumnsMenu, and Toolbar (it used to be four inline copies that had to stay byte-identical).
+
+Cache helpers are process/browser storage utilities, not React state management. The one React
+entry here is `useCacheMapPersistence` - the documented app contract (`load()` on mount +
+`onDirty -> saveDebounced(delay)`) as a hook. Scope is deliberately exactly that: the
+pagehide/visibilitychange flush backstops stay app-side (they are page-level policy, not
+per-component). Effect identity is `[cache, delay]`; the returned methods are pass-throughs and
+`reload()` is an alias of `load()` - a repeated load MERGES storage on top of the current maps
+(addDataToMap semantics), it is not a reset. QA cards 20/21/25 share one `memoryCache`, so
+several mounted hooks coexist: load() is idempotent-enough (merge) and extra onDirty
+subscribers just debounce the same save.
 
 Dirty/save contract: the dirty signal originates in the data layer. The persisted maps are
 `ObservableMap`s, so `set/delete/clear` announce themselves; in-place mutations of stored
@@ -612,9 +696,20 @@ CResizeObserver
 setResizeableElement(el)
 removeResizeableElement(el)
 ObserveID
+
+useResizeObserver<T>(onResize) -> {ref, element()}
+useElementSize<T>() -> {ref, element(), width, height, getSize()}
 ```
 
-Use these only when a component must participate in the shared resize observer map.
+Use the class/imperative pair only when a component must participate in the shared resize
+observer map. The hooks are the React-shaped entry over the SAME module singleton (one native
+`ResizeObserver` per app): `useResizeObserver` returns a callback ref (attach/detach re-observes;
+React null-call on unmount unsubscribes) and takes `onResize` through a ref - new identity
+neither resubscribes nor is missed. The native observer fires once right after `observe`, so the
+first measurement arrives without an explicit initial read. `useElementSize` folds that into
+rounded, equality-guarded `{width, height}` state (a no-op resize does not re-render) plus a live
+`getSize()` getter (exact floats, no render wait). `setResizeableElement`'s auto-shrink path is
+untouched and still class-driven (ParamsEditor inputs). QA card 19 drives both hooks.
 
 ## Styles
 ```
@@ -640,9 +735,9 @@ Current tokenized prefixes:
 - `--wnd-*` for `FloatingWindow` chrome.
 - `--dlg-*` for `SettingsDialog` chrome.
 - `--tb-*` for toolbar chrome.
-- `--logs-*` for global/context logger chrome.
-- `--cols-menu-*` for compact `ColumnsMenu/MenuStrip` chrome.
-- `--cols-dots-*` for `ColumnDots` chrome.
+- `--logs-*` for global/context logger chrome.
+- `--cols-menu-*` for compact `ColumnsMenu/MenuStrip` chrome.
+- `--cols-dots-*` for `ColumnDots` chrome.
 - `--cols-card-*` for `CardList` chrome.
 - `--wenay-z-modal` for modal/overlay stacking.
 
@@ -650,11 +745,11 @@ Normalization rule: new shared CSS should first try an existing token. Add a new
 
 Open normalization candidates:
 - `src/style/style.css`: `.msTradeAlt`, `.msTradeActive`, `.newButtonSimple`, `.toIndicatorMenuButton:hover`, submit-button green, and several toolbar row hover/drag literals still use raw colors.
-- `src/common/src/grid/columnState/*`: compact menu/dots/card visuals now use `.wenayColsMenu*`, `.wenayColDots*`, `.wenayCardList*` plus `--cols-menu-*`, `--cols-dots-*`, and `--cols-card-*`; further changes here should be visual QA only, not a new default palette.
+- `src/common/src/grid/columnState/*`: compact menu/dots/card visuals now use `.wenayColumnGrid*`, `.wenayColsMenu*`, `.wenayColDots*`, `.wenayCardList*` plus `--cols-grid-*`, `--cols-menu-*`, `--cols-dots-*`, and `--cols-card-*`; further changes here should be visual QA only, not a new default palette.
 - `src/common/src/components/ParamsEditor.tsx` and `src/common/src/components/Input.tsx`: if these stay public primitives, define default class/token contracts instead of component-owned visual styling.
 - `src/common/src/styles/commentaryStyles.css`: standalone `.commentary` CSS is not imported by the root style bundle; either import/tokenize it if still used, or mark it as a local component concern.
 
-Recently normalized: mouse context-menu item colors through `--menu-*`, `--menu-outline-color` for `OutlineDragDemo`, `--logs-*` for logger chrome, `--dlg-scrim` in `ModalProvider`, compact `ColumnsMenu/MenuStrip` visuals through `.wenayColsMenu*` / `--cols-menu-*`, and card-29 mobile primitives through `--cols-dots-*` / `--cols-card-*`.
+Recently normalized: mouse context-menu item colors through `--menu-*`, `--menu-outline-color` for `OutlineDragDemo`, `--logs-*` for logger chrome, `--dlg-scrim` in `ModalProvider`, compact `ColumnsMenu/MenuStrip` visuals through `.wenayColsMenu*` / `--cols-menu-*`, card-29 mobile primitives through `--cols-dots-*` / `--cols-card-*`, and createColumnGrid overlay through `.wenayColumnGrid*` / `--cols-grid-*`.
 
 ## Cleanup Inventory
 
@@ -668,6 +763,16 @@ Suspicious but still public:
 - `src/common/src/myChart/chartEngine/chartEngine.ts` is a reference copy next to the public React engine. It is not exported from root; treat it as suspicious maintenance debt, not as public API.
 - `StyleCSSHeadGridEdit` and `StyleCSSHeadGrid` mutate `<head>` directly. They are exported and can have consumers, but new grid styling should prefer ag-grid theme params and tokens.
 
+Added by the 2026-07-09 architecture audit (evidence in the audit report / `doc/target/my.md`):
+- `menuR.tsx` (`createRightClickMenu` / `MenuR`) - CONFIRMED dead: no runtime consumer anywhere (the test that supposedly covers it imports `RightMenu.tsx`); re-exported twice from `api.tsx` (`export *` + `kit.menu.rightClick`). Candidate for removal in a deliberate breaking version; its gesture code duplicates `menuMouse.tsx:342-380`.
+- `logsContext.tsx` - a full PARALLEL logs stack (own `LogEntry` shape divergent from `logsController`, raw unguarded `localStorage`, own settings/notifications/table) exported from the barrel next to `logs.tsx`. Decide: deprecate or converge; new code should use `logsApi`/`createLogsController`.
+- `MyChartEngine` - a hardcoded DEMO (random data + setInterval inside `useEffect`, no props but `style`) exported as public API from `chartEngineReact.tsx`; `generateIncrementalData` (Math.random demo util) is public too. Should move to demo namespace or gain a real props contract.
+- ~~`getLogsApi<T>()` shared module state~~ FIXED (A2, v1.0.41): every call now builds its own map/mini/settings (optional `settingsKey` persists per instance); the global `logsApi` explicitly injects the legacy shared state.
+- ~~`FloatingWindow` `onCLickClose` typo~~ ALIASED (A10, v1.0.42): `onClickClose` added, typo prop is a deprecated alias; REMOVAL of the alias still needs a breaking pass.
+- `DragArea` - `@deprecated` (A7, v1.0.42): no consumers; unique semantics kept as-is (see Drag / Resize Low Level). Removal in a deliberate breaking version.
+- `Button` `keySave` prop - deprecated alias of `keyForSave` (A10, v1.0.42); removal in a breaking pass.
+- `contextMenu` raw `map`/legacy-queue path is test-only-live (populated only by `contextMenuStats.test.tsx`); the `bb`/`map.clear()` reopening invariant itself is intentional and stays.
+
 ## Charts
 Canvas chart:
 ```
@@ -699,4 +804,4 @@ removed old grid update names -> applyGridRows / agGrid4
 ```
 
 Do not add new generic utilities with app words in their signature. For example, a column primitive should accept
-`names` and `apply`, while a product wrapper decides group ids, column ids, and labels.
+`names` and `apply`, while a product wrapper decides group ids, column ids, and labels.

package/doc/wenay-react2.md

@@ -21,9 +21,11 @@ Put app-specific layout/build rules in an app wrapper above the primitive.
 ## Render Memory
 ```
 updateBy(obj) / useUpdateBy(obj)                 // subscribe current component to renderBy(obj)
+updateBy(obj, cb)                                // imperative callback instead of a re-render;
+                                                 //   cb goes through a ref - inline identity is fine
 renderBy(obj, ms?)                               // emit render for subscribers
-renderByRevers(obj, ms?, reverse?=true)
-renderByLast(obj, ms?)
+renderByRevers(obj, ms?, reverse?=true)          // reverse/last affect ONLY React subscribers;
+renderByLast(obj, ms?)                           //   updateBy(obj, cb) callbacks always all run first
 
 const state = { count: 0 }
 const api = createUpdateApi(state)
@@ -63,6 +65,13 @@ document.addEventListener("visibilitychange",
 window.addEventListener("pagehide", () => { void memoryCache.flush() })  // backstop: flush is async
 ```
 
+The load + dirty->saveDebounced part of that contract as one hook (React components):
+```
+const persistence = useCacheMapPersistence(memoryCache, delayMs?=300)
+persistence.isDirty(); persistence.flush(); persistence.save(); persistence.reload()  // reload = load() alias
+```
+The pagehide/visibility flush backstops stay app-side (see above) - the hook deliberately does not own them.
+
 ## Outside Click / Buttons
 ```
 const outside = useOutside({onOutside, enabled?})
@@ -73,19 +82,35 @@ outside.contains(event.target)
 
 <OutsideClickArea outsideClick={close} status={open}>...</OutsideClickArea>
 
-<Button button={<button>Open</button>} outClick>{...}</Button>
+<Button button={<button>Open</button>} outClick keyForSave?>{...}</Button>   // keySave = deprecated alias
 <OutsideButton button={...}>{...}</OutsideButton>
 <HoverButton button={...}>{...}</HoverButton>
 <AbsoluteButton button={...}>{...}</AbsoluteButton>
 ```
 
+## Element Size / Resize Observer
+```
+const box = useResizeObserver<HTMLDivElement>(() => onResize())   // shared singleton observer
+<div ref={box.ref} />; box.element()
+
+const size = useElementSize<HTMLDivElement>()    // "want the size -> get the value/method"
+<div ref={size.ref} />
+size.width; size.height                          // state, rounded, no-op resize does not re-render
+size.getSize()                                   // live getter (exact, no render wait)
+
+setResizeableElement(el) / removeResizeableElement(el)   // legacy imperative auto-shrink path, unchanged
+```
+Both hooks ride the same module-level `CResizeObserver` singleton (one native `ResizeObserver` for the whole app). QA card 19.
+
 ## Drag / Floating Windows
 ```
-const drag = useDraggableApi({initialPosition, holdMs?, onDragStart?, onDragEnd?})
+const drag = useDraggableApi({initialPosition, holdMs?, onDragStart?, onDragEnd?, onMove?, trackState?})
 <div {...drag.bind} style={{transform: `translate(${drag.position.x}px, ${drag.position.y}px)`}} />
 drag.setPosition({x, y})
 drag.resetPosition()
 drag.cancelDrag()
+// imperative path: onMove(p) fires per move tick (through a ref); trackState:false stops
+// per-tick re-renders - position lives only in drag.positionRef/onMove (DragBox is this shape)
 
 const r = useReorder({order, commit, move?, canDrag?, preview?, holdMs?})   // mini reorder-by-drag
 <div ref={r.listRef}>{order.map(k => {                                      // children 1:1 with order
@@ -99,7 +124,8 @@ const b = useReorderBoard({columns: [{key, items}], commit,                 // d
 b.over                                                                      // {col, index} | null - live target
 // column gravity is YOUR CSS: justify-content flex-start packs up, flex-end packs down
 
-<FloatingWindow keyForSave="tool" size={{width: 320, height: 240}} header={<div>Tool</div>}>
+<FloatingWindow keyForSave="tool" size={{width: 320, height: 240}} header={<div>Tool</div>}
+                onClickClose={() => setOpen(false)}>   {/* onCLickClose (typo) = deprecated alias */}
     <Panel />
 </FloatingWindow>
 
@@ -156,6 +182,7 @@ tb.api.useConfig() / getConfig() / setConfig(next) / setOrder(order) / show(key,
 tb.api.showSettings(on) / showReset(on)             // pseudo-controls visibility
 tb.api.useItems()            // headless bar: ordered visible [{item, density, content}] - custom markup
 tb.api.onChange.on(cfg => ...) -> off        // fires on every edit
+tb.api.dispose()             // release the external-source subscription (HMR/remounts); persisted config stays
 
 registerToolbarDensity({key, name, renderItem?}) -> unregister   // built-ins: 'icon', 'label'
 toolbarItemIcon(item)        // the item's icon, or its first letters as a text pseudo-icon
@@ -282,7 +309,7 @@ cs.api.show(key, on) / move(order) / setSort({key, dir} | null) / toggleSort(key
 cs.api.visibleKeys()                             // keys to render, in order (group-gated)
 cs.api.onChange.on(cfg => ...) -> off
 cs.api.usePresent() / isPresent(key) / setPresent(keys | null)   // live-grid presence
-cs.api.getPresentGate() / setPresentGate(keys | null)           // app runtime availability gate, not persisted
+cs.api.getPresentGate() / setPresentGate(keys | null)           // app runtime availability gate, not persisted
 cs.api.listSource                                // {order, visible} slice as a Toolbar `source`
 ```
 Config `{v, order, visible, width, sort, filter, groups}` is serializable and persisted like
@@ -317,7 +344,34 @@ Mobile (no ag-grid): dots selector + card rows over the same config:
                                                  //   drag=replace, swipe up=remove, tap dot=select, sort button cycles
 <CardList<Row> state={cs} data={rows} getId? renderValue? />   // visible cols -> card fields; cardRole:'title'/'accent'
 ```
-QA cards 28 (grid layer + F5 restore), 29 (mobile dots + cards), 30 (toolbar icon menu + grouped sub-column mode button), 31 (Toolbar over the same config).
+
+Default wrapper for repeated grid/menu/mobile use:
+```
+const cg = createColumnGrid<Row>({
+    key: "orders.columns",
+    columnDefs: cols,                              // ColumnMeta inferred from colId/field/headerName
+    data: rows,                                    // optional default; View props can override
+    getId: r => r.id,
+    autoSizeOnColumnCountChange: true,             // optional fit when visible column count changes
+    columns: [{key: "name", fixed: true, cardRole: "title"}], // optional overrides
+})
+
+<cg.View mode="table" />                           // default controls="auto" -> dots overlay
+<cg.View mode="cards" data={otherRows} />
+<cg.Table rowData={rows} getRowId={p => p.data.id} />
+<cg.Menu compact />
+<cg.Dots />                                        // no wrapper max; defaults to all columns
+<cg.Toolbar settings />
+<cg.Settings />
+```
+`createColumnGrid` returns `{state, toolbar, api, grid, tableProps, Table, Menu, Dots, Cards, Toolbar, Settings, View, dispose}`; `dispose()` releases factory-lifetime subscriptions (config onChange, toolbar source, pending fit) without touching the persisted config. The columnState BARREL stays ag-grid-free; `createColumnGrid` ships from its own module (both are exported from the package root).
+Its `Table`/`tableProps()` attach/detach the columnState grid adapter automatically and default
+`autoSizeColumns=false` so restored widths are not overwritten. `autoSizeOnColumnCountChange` is
+separate and only calls `sizeColumnsToFit()` when the visible column count changes. `useColumnGrid(opts)`
+is the same controller captured once for component-local setups; keep module-level `createColumnGrid`
+when the controller must survive route/component remounts.
+
+QA cards 28 (grid layer + F5 restore), 29 (mobile dots + cards), 30 (toolbar icon menu + grouped sub-column mode button), 31 (Toolbar over the same config), 32 (createColumnGrid wrapper + dots driving table/cards).
 
 
 ## Observe React Adapter
@@ -416,6 +470,10 @@ const tt = useReplayHistory(history, (frame) => draw(frame), {head: () => replay
 tt.live; tt.seq; tt.head; tt.pause(); tt.play(); tt.seek({seq})
 ```
 
+Route hand-off here is the MANUAL surface (`switchRoute`). common2 1.0.67 `Replay.createRouteCoordinator` moves route decisions (policy, promote/fallback/shadow) out of the consumer; a coordinator `link.subscribe(cb)` handle has the same shape (`ready, seq(), label(), active()`) and survives every route change, so components consuming a coordinator link do not need `switchRoute` at all. common2 1.0.68 supplies the direct transport for it: `createWebRtcConnector` with an app-injected `rtc: () => new RTCPeerConnection(cfg)` factory (the browser — i.e. the React app — owns that injection) and signaling over the existing RPC socket (`createSignalHub`). common2 1.0.69 wraps the whole stack into the `Peer` SDK (`wenay-common2/peer`): `createPeerClient(...).peer(account)` returns a live mirrored store (works with `useStoreNode`/`useStoreKeys` as-is) + route control, surviving relay<->direct hand-offs in one seq space. A dedicated `usePeer` adapter is a target-backlog item, not yet a library surface.
+
+Media lines (common2 1.0.66 `Media.createAudioSource` / `Media.createVideoSource`) are ordinary binary Listen sources; with `replay:true` their `listen` is a replay line, so `useReplaySubscribe` / `useReplayFrame` consume mic/camera frames with no media-specific hook. Each frame is one `Uint8Array` (`Media.decodeMediaFrame`); draw/play it via ref (canvas, AudioContext), never useState — the same rule as any high-frequency line. Without `replay`, the plain `listen` works with the listen hooks above.
+
 Contract: `off()` on unmount, StrictMode-safe; seq survives resubscribes inside one mount (keepSeq, default on) — a resubscribe reconnects with `{since}` and gets the journal tail, not a keyframe. Across a FULL unmount/remount keep the position outside via `onSeq` and pass it back as `since`. `seq()` is a getter — high-frequency lines (video frames, ticks) do not re-render per event; draw to canvas via ref, bypassing VDOM. Freshness: detection lives in wenay-common2 (`staleMs` watchdog); the non-route hooks mirror its edge-triggered `onStale` into `stale`, so a fresh 100 ev/s line causes zero extra renders. Route hand-off is explicit through `switchRoute(nextRemote, {label?, since?, reset?, policy?, hint?})`: old route stays live while the replacement catches up by `seq`, then closes. `useReplayHistory` is archive playback — staleness does not apply. QA cards 23 (video line + conflation + time travel + freshness), 24 (store sync), 25 (per-key feed), and 26 (route hand-off) are the live examples.
 
 ## Logs
@@ -425,7 +483,9 @@ logsApi.addLogs({id: "api", time: new Date(), txt: "done", var: 1})
 <logsApi.React.PageLogs />
 <logsApi.React.Setting />
 
-const customLogs = getLogsApi<MyFields>({limitPer: 500, limit?: 50, varMin?: 0})
+const customLogs = getLogsApi<MyFields>({limitPer: 500, limit?: 50, varMin?: 0, settingsKey?: "myLogs"})
+// each getLogsApi call now owns ISOLATED full/mini/settings state (settingsKey persists the
+// instance settings; omitted = fresh non-persisted). The global logsApi keeps the legacy shared state.
 const headless = createLogsController<MyFields>({options: {limitPer: 500, limit: 50}})
 
 const messageNotifications = useMessageEventLogsController({maxVisible: 4})
@@ -437,9 +497,13 @@ const contextNotifications = useLogsNotificationsController()
 const mini = useMiniLogsTable({data: rows, onClick: e => console.log(e.data)})
 <AgGridTable {...mini.props} />
 <MiniLogsTable data={rows} />
+
+const table = useLogsPageTable()                 // full-page logs grid controller
+<AgGridTable {...table.gridProps} />
+table.fit(); table.applyImportanceFilter(min?); table.appendRow(row); table.getApi()
 ```
 
-Logger notification/tabs chrome uses `--logs-*` CSS variables; apps can theme it without forking logger components. `createLogsController` owns the headless append/limit/settings state for custom integrations. `useMessageEventLogsController` owns the global notification queue/timers/settings, `MessageEventLogsView` draws it, and `MessageEventLogs` / `logsApi.React.Message` remain compatibility wrappers. `MiniLogs` remains the compatibility wrapper; new compact-table code can use `useMiniLogsTable` or `MiniLogsTable`.
+Logger notification/tabs chrome uses `--logs-*` CSS variables; apps can theme it without forking logger components. `createLogsController` owns the headless append/limit/settings state for custom integrations. `useMessageEventLogsController` owns the global notification queue/timers/settings, `MessageEventLogsView` draws it, and `MessageEventLogs` / `logsApi.React.Message` remain compatibility wrappers. `MiniLogs` remains the compatibility wrapper; new compact-table code can use `useMiniLogsTable` or `MiniLogsTable`. `useLogsPageTable` owns the full-page table (mount-time row snapshot, transaction appends from the mini feed, one importance-filter method); `PageLogs` / `logsApi.React.PageLogs` remain the thin compatibility wrappers over it.
 
 ## Styles / Theme
 ```
@@ -455,7 +519,7 @@ useAgGridTheme("dark" | "light")
 colDefCentered / colDefWrap / numericComparator
 ```
 
-Shared CSS variables include `--menu-outline-color`, `--logs-*`, `--dlg-*`, `--wnd-*`, `--tb-*`, `--cols-menu-*`, `--cols-dots-*`, and `--cols-card-*`.
+Shared CSS variables include `--menu-outline-color`, `--logs-*`, `--dlg-*`, `--wnd-*`, `--tb-*`, `--cols-grid-*`, `--cols-menu-*`, `--cols-dots-*`, and `--cols-card-*`.
 
 ## Charts
 ```
@@ -472,4 +536,4 @@ npm run testReact                                // http://localhost:3010/
 
 The stand lives in `src/common/testUseReact/qa.tsx`. Use it for visual checks; agGrid4 overlay/dynamic-column demos are dedicated QA cards.
 Two tabs: Active checks (current work) and Verified archive (`#archive`) - verified/fixed cards move
-there and stay runnable for regression re-checks.
+there and stay runnable for regression re-checks.

package/lib/common/api.d.ts

@@ -18,6 +18,7 @@ export * from "./src/components/Dnd";
 export * from "./src/utils";
 export * from "./src/grid/agGrid4";
 export * from "./src/grid/columnState";
+export * from "./src/grid/columnState/columnGrid";
 export * from "./src/components/Buttons";
 export * from "./src/components/MyResizeObserver";
 export * from "./src/components/Other";

package/lib/common/api.js

@@ -15,17 +15,21 @@ export * from "./src/styles/styleGrid";
 export * from "./src/styles/tokens";
 // 1. BASE LAYER - no internal project dependencies
 export * from "./updateBy";
-// 2. HOOKS - depend only on updateBy
+// 2. HOOKS - depend on updateBy and wenay-common2
 export * from "./src/hooks";
-// 4. DND components - depend on updateBy
+// 4. DND components - depend on updateBy and utils (persistedMaps)
 export * from "./src/components/Dnd";
-// 5. UTILS - now depend on Dnd (memoryStore imports floatingWindowMap, mapResiReact)
+// 5. UTILS - self-contained (persisted maps live in utils/persistedMaps; components import
+// their map from there, so utils no longer reaches into the component layer)
 export * from "./src/utils";
 // 5b. GRID (agGrid4): core buffer + headless hook + AgGridTable.
 export * from "./src/grid/agGrid4";
 // 5c. GRID column state (createColumnState): persisted order/visibility/width/sort/filter,
-// standalone config store + optional two-way ag-grid adapter (attach via onGridReady)
+// standalone config store + optional two-way ag-grid adapter (attach via onGridReady).
+// The columnState barrel is deliberately ag-grid-free; createColumnGrid (ag-grid runtime +
+// Toolbar) ships from its own module so grid-less consumers can import the barrel directly.
 export * from "./src/grid/columnState";
+export * from "./src/grid/columnState/columnGrid";
 // 6. BASE COMPONENTS - depend on hooks
 export * from "./src/components/Buttons";
 export * from "./src/components/MyResizeObserver";

package/lib/common/src/components/Dnd/DragArea.d.ts

@@ -1,3 +1,8 @@
+/** @deprecated No consumers in the library; prefer `useDraggableApi` (delta-based, mouse+touch)
+ *  or `DragBox` for the imperative onX/onY shape. Kept as-is because its semantics are unique
+ *  (document.body listeners, stopPropagation on every move tick, ABSOLUTE x/y coordinates,
+ *  no preventDefault) - re-basing it on useDraggableApi would change observable behavior.
+ *  Candidate for removal in a deliberate breaking version (A7/A3 cleanup inventory). */
 export declare function DragArea({ children, onY, onX, x, y, last, onStart, onStop, }: {
     children: React.JSX.Element;
     onX?: (x: number) => void;

package/lib/common/src/components/Dnd/DragArea.js

@@ -1,6 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
-//
+/** @deprecated No consumers in the library; prefer `useDraggableApi` (delta-based, mouse+touch)
+ *  or `DragBox` for the imperative onX/onY shape. Kept as-is because its semantics are unique
+ *  (document.body listeners, stopPropagation on every move tick, ABSOLUTE x/y coordinates,
+ *  no preventDefault) - re-basing it on useDraggableApi would change observable behavior.
+ *  Candidate for removal in a deliberate breaking version (A7/A3 cleanup inventory). */
 export function DragArea({ children, onY, onX, x = 0, y = 0, last, onStart, onStop, }) {
     const lastC = useRef(null);
     const lastT = useRef(null);

package/lib/common/src/components/Dnd/FloatingWindow.d.ts

@@ -1,6 +1,6 @@
 import React, { ReactNode } from "react";
 import { type RndResizeCallback } from "react-rnd";
-import { ObservableMap } from "../../utils/observableMap";
+import { floatingWindowMap } from "../../utils/persistedMaps";
 export type FloatingWindowPosition = {
     x: number;
     y: number;
@@ -31,6 +31,9 @@ export type FloatingWindowProps = {
     position?: FloatingWindowPosition;
     size?: FloatingWindowSize;
     moveOnlyHeader?: boolean;
+    /** Show the close button and handle its click. */
+    onClickClose?: () => void;
+    /** @deprecated typo alias of {@link onClickClose}; kept for compatibility, `onClickClose` wins when both are set. */
     onCLickClose?: () => void;
     header?: React.ReactElement | boolean;
     overflow?: boolean;
@@ -48,7 +51,7 @@ export type FloatingWindowProps = {
     children: React.ReactElement | ((update: number) => React.ReactElement);
     className?: string;
 };
-export type FloatingWindowControllerOptions = Omit<FloatingWindowProps, "children" | "className" | "header" | "moveOnlyHeader" | "overflow" | "onCLickClose">;
+export type FloatingWindowControllerOptions = Omit<FloatingWindowProps, "children" | "className" | "header" | "moveOnlyHeader" | "overflow" | "onCLickClose" | "onClickClose">;
 export type FloatingWindowController = {
     position: FloatingWindowPosition;
     size: FloatingWindowSize;
@@ -64,14 +67,14 @@ export type FloatingWindowController = {
     onResize: RndResizeCallback;
     onResizeStop: RndResizeCallback;
 };
-export declare const floatingWindowMap: ObservableMap<string, FloatingWindowSavedGeometry>;
+export { floatingWindowMap };
 export declare const FloatingWindow: typeof FloatingWindowBase;
 export declare function useFloatingWindowController({ keyForSave: ks, position, size, zIndex, onUpdate, limit, sizeByWindow }?: FloatingWindowControllerOptions): FloatingWindowController;
 /**
  * Wrapper component around react-rnd.
  * Provides dragging and resizing, an optional header, and a close button.
  */
-export declare function FloatingWindowBase({ children, keyForSave: ks, position, size, overflow, zIndex, onUpdate, disableDragging, className, header, moveOnlyHeader, limit, onCLickClose, sizeByWindow }: FloatingWindowProps): import("react/jsx-runtime").JSX.Element;
+export declare function FloatingWindowBase({ children, keyForSave: ks, position, size, overflow, zIndex, onUpdate, disableDragging, className, header, moveOnlyHeader, limit, onCLickClose, onClickClose, sizeByWindow }: FloatingWindowProps): import("react/jsx-runtime").JSX.Element;
 export type DragBoxProps = {
     /** Child element that should be draggable */
     children: ReactNode;
@@ -106,4 +109,5 @@ export type DragBoxProps = {
  * Function only as a hook for parameter changes during movement, although it has its own component (for offset counting).
  * Returns the distance traveled when moving the child element.
  */
-export declare function DragBox({ children, onX, onY, x, y, right, last, dragging, onStart, onStop }: DragBoxProps): import("react/jsx-runtime").JSX.Element;
+export declare function DragBox({ children, onX, onY, x, y, right, last, dragging: _dragging, // accepted for compatibility, was never read
+onStart, onStop }: DragBoxProps): import("react/jsx-runtime").JSX.Element;