wenay-react2 1.0.40 → 1.0.42

package/doc/wenay-react2.md

@@ -0,0 +1,539 @@
+# wenay-react2 - BRIEF cheat sheet (canonical UI/controller API)
+
+> Root import: `import { ... } from "wenay-react2"`.
+> Notation: `name(args) -> ret`. JSX examples show the intended public path, not every prop.
+> Short controller-style names are canonical. Removed names are recorded in
+> **WENAY_REACT2_RENAMES.md** for migration only; old aliases are not exported.
+
+## Standard
+```
+Hooks that own lifecycle/state return a small controller:
+  api.props / api.bind              // props to spread on an element
+  api.open() / close() / set()      // modal/menu-like state
+  api.update() / remove() / clean() // data buffers
+  api.fit() / flush() / sync()      // ag-grid lifecycle
+
+Components receive controllers when state must outlive the component.
+Library primitives never know app-specific terms, domain objects, or group policy.
+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)          // 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)
+api.use()                                        // hook subscription
+api.emit(ms?)                                    // renderBy(state)
+api.on(obj => {}) -> off
+
+const api2 = useUpdateByApi(state)               // hook + controller in one call
+```
+
+Persistent process memory:
+```
+memoryGetOrCreate(key, def, {abs?, deepAutoMerge?, reversDeep?}) -> def-or-stored
+memoryGetById(key, def, id) -> stored only while id is the same
+memorySet(key, data)
+memoryGet(key)
+memoryUpdate(key, mutate) -> cur?               // mutate + rerender + announce in one call
+memoryMarkDirty(key)                            // announce an in-place mutation of a memoryGetOrCreate object
+createSearchHistory({key, max?})                 // reusable small persisted search history controller
+memoryMaps                                       // rnd / resize / other maps
+```
+
+Persistence contract (memoryCache): the library NEVER writes storage by itself. The persisted maps
+(floatingWindowMap, mapResiReact, mapRightMenu, memoryProps) are `ObservableMap`s - set/delete/clear
+announce themselves, in-place mutations are announced at the commit points (drag/resize stop,
+menu drag end, setPlace). memoryCache observes the maps it owns; the app owns the write policy:
+```
+memoryCache.load()                                      // once on start; remembers the saved snapshot
+memoryCache.onDirty((scope?, key?) => ...) -> off       // dirty channel (coalesced, async)
+memoryCache.saveDebounced(ms?) / save() / flush()       // write only payloads that differ from the snapshot
+memoryCache.isDirty()                                   // cheap hint, e.g. a beforeunload guard
+
+memoryCache.load()
+const off = memoryCache.onDirty(() => memoryCache.saveDebounced(800))
+document.addEventListener("visibilitychange",
+    () => { if (document.visibilityState == "hidden") void memoryCache.flush() })
+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?})
+<div {...outside.props} />
+outside.enable()
+outside.disable()
+outside.contains(event.target)
+
+<OutsideClickArea outsideClick={close} status={open}>...</OutsideClickArea>
+
+<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?, 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
+    const it = r.item(k)                                                    // it.dragging / it.active
+    return <div key={k} {...it.props} style={{...own, ...it.style}} />      // ONE commit(next) on drop
+})}</div>
+
+const b = useReorderBoard({columns: [{key, items}], commit,                 // drag between vertical columns
+    canDrag?, holdMs?, onDragStart?, onDragMove?, onOverChange?, onDragEnd?})
+<div ref={b.columnRef('todo')}>{items.map(k => ...b.item(k)...)}</div>      // one div per column, any count
+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>}
+                onClickClose={() => setOpen(false)}>   {/* onCLickClose (typo) = deprecated alias */}
+    <Panel />
+</FloatingWindow>
+
+const wnd = useFloatingWindowController({keyForSave: "custom-tool", size: {width: 320, height: 240}})
+wnd.position                 // {x,y}; bind wnd.onHeaderMouseDown/onHeaderTouchStart for custom chrome
+```
+
+## Modal / Input
+```
+<ModalProvider>
+    <App />
+</ModalProvider>
+
+const modal = useModal()
+modal.open(<Dialog />)
+modal.set(<Dialog />)
+modal.close()
+modal(null)                                      // callable shortcut for clearing
+```
+
+Input helpers:
+```
+const text = useTextInputPanel({callback: txt => {}, txt: ""})  // headless value + submit API
+const file = useFileInputPanel({callback: file => {}})          // headless file + submit API
+<TextInputPanel callback={txt => {}} name="Name" txt="" />     // thin visual wrapper over hook
+<FileInputPanel callback={file => {}} name="File" />            // thin visual wrapper over hook
+<TextInputModal callback={...} outClick={modal.close} />
+<FileInputModal callback={...} outClick={modal.close} />
+<FreeModal outClick={modal.close} size={{width: 400, height: 260}}>...</FreeModal>
+```
+
+## Settings Dialog
+```
+<SettingsDialog trigger={<span>settings</span>} sections={[{key, name, render, children?, parentKey?, searchText?, keywords?}]} defaultSection? /> // searchable tree + persisted search history; history closes when search focus leaves
+const settings = useSettingsDialogController({sections, defaultSection?}) // open/search/tree/history/resize actions for custom chrome
+registerSettingsSection({key, name, render, parentKey?, searchText?, keywords?}) -> unregister
+```
+
+## UI Slot
+```
+const slot = createUiSlot({key, places: {top: "Top bar", side: "Sidebar"}, def: "top"})
+
+<slot.Slot place="top">{content}</slot.Slot>     // each mount point decides by itself
+<slot.PlacementSetting />                        // segmented place switcher; setPlace marks memoryCache dirty
+```
+
+## Toolbar
+```
+const tb = createToolbar({key, items: [{key, title, icon?, short?, render?, onClick?, defaultVisible?, fixed?}], def?, settingsItem?, resetItem?, source?, sourceMode?})
+
+<tb.Bar settings reset? />   // the live bar; settings adds a gear; reset is hidden by default; item moves animate
+<tb.Settings />              // the PURE config editor - same element drops into a settings section
+tb.api.useConfig() / getConfig() / setConfig(next) / setOrder(order) / show(key,on) / setDensity(key) / reset()
+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
+```
+Config `{order, visible, density}` is serializable and persisted like createUiSlot
+(memoryGetOrCreate -> memoryCache, the app owns the write policy). Items added in an app update are merged
+into a stale persisted config (appended, default-visible), removed ones are ignored. `icon` is
+optional: in icon density an icon-less item renders the first letters of its short/title.
+The gear and reset button are pseudo-items: `settingsItem: {title?, icon?}` and `resetItem` re-skin them,
+and the editor has separated toggle rows for them (`visible['__settings']` / `visible['__reset']`, no order slots - they always sit at the bar edge). Settings is visible by default; reset is hidden by default unless `resetItem.defaultVisible: true` or `api.showReset(true)` enables it. `resetItem: false` removes the reset feature.
+
+`source?` makes the toolbar a VIEW over an external `UiListSource`. Default `sourceMode:"orderVisible"`
+means the source owns item order and item visibility, so one config can drive a grid, its icon menu
+AND the toolbar together (`columnState.api.listSource`, QA card 31). `sourceMode:"order"` shares only
+the source-key order; item membership, density, pseudo-controls, and extra non-source item positions
+stay in the toolbar store (QA card 30). Without `source` the toolbar keeps its own store (standalone mode).
+
+## Callback Hub
+```
+const hub = createCallbackHub<[Args]>(emit => api.onX(emit))  // one slot -> many subscribers
+hub.on(cb) -> off
+```
+
+## Params
+```
+<ParamsEditor
+    params={params}
+    onChange={next => setParams(next)}
+    onExpand={next => setParams(next)}
+    expandStatus?
+    expandStatusLvl?
+/>
+
+const controller = useParamsEditorController({params, onChange, onExpand?})
+
+<ParamsEdit params={params} onSave={next => save(next)} />
+<ParamRow name="Name">...</ParamRow>
+```
+
+## Menu
+```
+type MenuItem = { name, actionKey?, onClick?, next?, func?, status? } | false | null | undefined
+
+<Menu data={items} coordinate={{x: 0, y: 0}} />
+
+<contextMenu.Layer>{children}</contextMenu.Layer>
+contextMenu.openAt(event, [{name: "Copy", actionKey: "grid.copy", onClick: copy}], {source: "grid"})
+contextMenu.stats.getSnapshot()   // local counters: opens, source/layer usage, actionTotals, keyed actions
+contextMenu.close()
+```
+
+Use `contextMenu.openAt(e, items, {source?})` for new right-click integrations. `contextMenu.map` still exists as a legacy Layer queue, but it is not the recommended path for new code. `contextMenu.stats` is an in-memory diagnostics API; it never persists data, never reports over the network, and records per-action counters only for explicit `actionKey` values. Unkeyed items are counted in aggregate totals without storing labels.
+
+`Menu` keeps the hovered/open item in internal React state. `status` is only an initial open hint and a compatibility field passed to custom renderers; menu objects are not mutated.
+
+Floating right menu:
+```
+<DropdownMenu elements={items} trigger={iconOrRender} classNames={...} styles={...} />
+const menu = useRightMenuController({elements, keyForSave?})
+```
+
+`DropdownMenu` is a floating action menu with caller-owned trigger/content styling, not the main context-menu primitive. `useRightMenuController` exposes the same open/fixed/select/submenu/drag state for custom views; `DropdownMenu` remains the compatible visual wrapper.
+
+## agGrid4
+Plain declarative rows:
+```
+<AgGridTable<Row> rowData={rows} columnDefs={cols} />
+```
+
+Buffered mirror table:
+```
+const grid = useAgGrid<Row>({getId: row => row.id})
+<AgGridTable<Row> controller={grid} columnDefs={cols} />
+
+grid.update({newData: rows})
+grid.remove([{id}])
+grid.clean()
+grid.fit()
+grid.flush()
+```
+
+Shared module store:
+```
+export const mainTable = createGridBuffer<Row>({getId, externalBuffer})
+
+const grid = useAgGrid({core: mainTable})
+<AgGridTable<Row> controller={grid} columnDefs={cols} />
+```
+
+Overlay patches over React-owned `rowData`:
+```
+const core = createGridBuffer<Row>({getId, mode: "overlay", pushDefaults: {add: false}})
+const grid = useAgGrid({core})
+
+<AgGridTable<Row> controller={grid} rowData={rows} columnDefs={cols} getRowId={p => getId(p.data)} />
+```
+
+Dynamic columns are pure names + lifecycle replay:
+```
+const columns = createColumnBuffer<Row>()
+
+columns.api.setNames(["a", "b"])
+columns.control.attach(api, {
+    apply: ({api, names}) => api.setGridOption("columnDefs", buildColumnDefs(names)),
+})
+columns.api.apply()
+columns.control.detach()
+```
+
+`createColumnBuffer()` knows nothing about groups, `columnDefs`, business names, or where columns live.
+
+
+## columnState
+A persisted column layer over a keyed column set - order / visibility / width / sort / filter in a
+standalone config store, with an OPTIONAL two-way ag-grid adapter. Mobile card views consume the
+SAME config with no ag-grid at all. agGrid4 wrappers are never modified: this is the app-level
+column wrapper `WRAPPER.md` postulates, packaged as a primitive.
+```
+const cs = createColumnState({key, columns: [{key, title, short?, icon?, group?, fixed?, defaultVisible?, cardRole?}], def?, saveMs?})
+
+cs.columns                                       // the descriptors (UI renders from these + config)
+cs.api.useConfig() / getConfig() / setConfig(next) / reset()
+cs.api.show(key, on) / move(order) / setSort({key, dir} | null) / toggleSort(key)   // asc->desc->off
+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.listSource                                // {order, visible} slice as a Toolbar `source`
+```
+Config `{v, order, visible, width, sort, filter, groups}` is serializable and persisted like
+createToolbar (memoryGetOrCreate(key) -> memoryCache, the app owns the write policy); a stale config migrates
+softly (unknown keys dropped, new columns appended default-visible, `fixed` pinned). `sort` is
+STICKY: independent of visibility/selection, may point at a hidden or grid-absent column, changes
+only by an explicit toggle/header click.
+
+Two-way ag-grid adapter (opt-in, agGrid4 untouched):
+```
+<AgGridTable columnDefs={cols} autoSizeColumns={false}
+    onGridReady={e => cs.grid.attach(e.api)}          // restore saved layout, then watch the grid
+    onGridPreDestroyed={() => cs.grid.detach()} />     // config survives remounts
+```
+Grid drag/resize/hide/sort/filter fold back into the config; UI edits apply to the grid; a column
+removed from the live grid (dynamic defs) keeps its config entry and reads `isPresent==false`.
+
+Icon menu - a 1:1 grid mirror (reorder in the grid <-> reorder the buttons):
+```
+<ColumnsMenu state={cs} compact? marks? tail? onItem? onTail? reorder? />      // default click = toggle visibility
+<MenuStrip items={[{key, title, state:'on'|'off'|'disabled', marks?, fixed?}]} onItem? onMove? tail? compact? />
+```
+`ColumnsMenu` binds `MenuStrip` - a presentation-only layer that reports clicks/drags but never
+interprets them - to the config. `compact` = icon-only buttons; an item with no icon shows its
+first letters. `tail` = trailing non-column buttons (a table-standards cycler etc.). For new
+settings-integrated toolbar/grid surfaces prefer `createToolbar({source: cs.api.listSource})`;
+keep `ColumnsMenu` for compact button strips or custom presentation-only menus.
+
+Mobile (no ag-grid): dots selector + card rows over the same config:
+```
+<ColumnDots state={cs} max?=8 />                 // track of marks; dots = shown columns; tap empty=add,
+                                                 //   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'
+```
+
+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
+`wenay-common2` owns the store/listen/RPC primitives. `wenay-react2` owns React lifecycle hooks around them.
+
+```ts
+import { Observe } from "wenay-common2"
+import { useStoreMirror, useStoreNode, useStoreKeys, useStoreSelect, useStoreChangedPaths, useListenEffect, useListenValue } from "wenay-react2"
+```
+
+Node subscription:
+```
+const price = useStoreNode(store.node.data.BTC)
+price.value
+price.exists
+price.replace(123)
+price.refresh()
+```
+
+Selection subscription:
+```
+const sel = useStoreSelect(store.update({data: {BTC: true}, meta: {status: true}}))
+sel.value
+sel.get()
+```
+
+Network mirror is explicit:
+```
+const mirror = useStoreMirror(remoteStore, {data: {}, meta: {}}, {
+    mask: {data: {BTC: true}, meta: {status: true}},
+    current: true,
+    drain: 250,
+})
+
+mirror.value
+mirror.ready
+mirror.sync()
+mirror.stop()
+```
+
+Per-key feed (`store.each()` of common2 — one cb per CHANGED top-level key):
+```
+useStoreEach(store, (key, value, ctx) => {
+    value === undefined ? removeRow(key) : upsertRow(key, value)
+}, {enabled?})
+```
+`undefined` = key deleted; a root replace (store.replace / mirror keyframe) expands into one call per key. The fold target should live outside React state (ref/Map/grid api) — the hook renders nothing itself. The wire counterpart is `useStoreReplayEach` below.
+
+Listen helpers:
+```
+useListenEffect(listen, (...args) => {})
+const value = useListenValue(listen, {initial})
+const args = useListenArgs(listen)
+```
+
+The hook does not choose transport. `remoteStore` needs `{ get(mask?), changed }` and may also provide `changedPaths`; apps may implement it with RPC, WebSocket, SSE, or test HTTP. `changedPaths` is used as a transport optimization: mirror pulls `mask ∩ paths` instead of the whole mask. `initial` is only the local mirror seed; changing it does not reset an existing mirror. `mask` is treated as a small declarative StoreMask, so structurally equal inline masks do not resubscribe. For add/delete keys, subscribe to the parent object node with `useStoreKeys(node)`; this also covers deep objects. If a state key conflicts with StoreNode methods such as `count`, use `store.node.at("count")`.
+
+## Replay React Adapter
+Client-side hooks over the wenay-common2 Replay stack (snapshot + sequenced delta line). Server parts (`conflateReplay`, `archiveReplay`, `createRpcServerAuto` replayOpts) are per-connection and stay hook-free by design.
+
+```ts
+import { useReplaySubscribe, useReplayRouteSubscribe, useStoreReplaySync, useStoreReplayMirror, useStoreReplayRouteSync, useStoreReplayRouteMirror, useStoreReplayEach, useReplayFrame, useReplayHistory } from "wenay-react2"
+
+// any replay line ({line, since, keyframe, frame?, frameLine?} remote)
+const sub = useReplaySubscribe(remote, (frame) => draw(frame), {onSeq?, onError?, since?, enabled?, staleMs?, onStale?, policy?, hint?})
+sub.ready; sub.error; sub.seq(); sub.restart()
+sub.stale; sub.lastTs()   // freshness (needs staleMs): stale re-renders on fresh<->stale transitions ONLY; lastTs() is a getter like seq()
+// policy: 'queue' (default, nothing skipped) | 'frame' (rides the server frameLine when present: on lag the
+// server drops and recovers with a mini-frame; old servers/in-proc degrade to 'queue'). hint -> the line's frame condenser.
+
+// explicit route hand-off over the same logical replay line (relay <-> direct, etc.)
+const routed = useReplayRouteSubscribe(relayRemote, (frame) => draw(frame), {label: "relay", onRoute?})
+await routed.switchRoute(directRemote, {label: "direct"})
+routed.ready; routed.switching; routed.route; routed.seq(); routed.label(); routed.active()
+// route hooks do not expose stale/lastTs yet; use non-route hooks when freshness is required.
+// store patch line (Observe.exposeStoreReplay(...).api.replay)
+const mirror = useStoreReplayMirror(remote, initial, {enabled?})   // creates the mirror store; same staleMs/stale/policy surface
+mirror.store; mirror.ready; mirror.seq(); mirror.restart()
+const sync = useStoreReplaySync(existingStore, remote)              // same, store supplied by the app
+const routedSync = useStoreReplayRouteSync(existingStore, relayRemote, {label: "relay"})   // same store, switchRoute() replaces the route after catch-up
+const routedMirror = useStoreReplayRouteMirror(relayRemote, initial, {label: "relay"}) // mirror store + route hand-off controller
+
+// per-key fold over the same line (Observe.syncStoreReplayEach counterpart): cb per CHANGED top-level key,
+// first delivery = keyframe expanded per key, (key, undefined) = deleted — grid rows without special cases
+const feed = useStoreReplayEach<Rows>(remote, (key, row) => row === undefined ? removeRow(key) : upsertRow(key, row), {drain?, initial?})
+feed.store; feed.ready; feed.stale; feed.seq(); feed.restart()      // same controller surface as the mirror
+// the mirror store lives in a ref: in-mount resubscribes (StrictMode/restart/enabled) reconnect by tail ON TOP of
+// kept state — the consumer sees only the diff. After a full unmount: {since: prev.seq(), initial: prev.store.snapshot()}
+
+// pull at YOUR pace (frame model): timer around remote.frame(seq, hint) — server condenses, no backlog, no live socket sub
+const pf = useReplayFrame(remote, (quote) => apply(quote), {intervalMs: 500, hint?})
+pf.ready; pf.error; pf.seq(); pf.pull(); pf.restart()               // error (e.g. sacred line evicted) STOPS pulling until restart()
+
+// time machine over Replay.openHistory(storage, live?)
+const tt = useReplayHistory(history, (frame) => draw(frame), {head: () => replay.head()})
+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
+```
+logsApi.addLogs({id: "api", time: new Date(), txt: "done", var: 1})
+<logsApi.React.Message />
+<logsApi.React.PageLogs />
+<logsApi.React.Setting />
+
+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})
+<MessageEventLogsView controller={messageNotifications} zIndex={80} />
+
+const contextTable = useLogsTableController()
+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`. `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
+```
+tokens.color.bgDark
+tokens.menu.outlineColor
+tokens.logs.notificationAccent
+tokens.zIndex.modal
+
+GridStyleDefault()                               // inject legacy grid CSS vars/classes
+StyleGridDefault                                 // common ag-grid style object
+buildAgTheme("dark" | "light")
+useAgGridTheme("dark" | "light")
+colDefCentered / colDefWrap / numericComparator
+```
+
+Shared CSS variables include `--menu-outline-color`, `--logs-*`, `--dlg-*`, `--wnd-*`, `--tb-*`, `--cols-grid-*`, `--cols-menu-*`, `--cols-dots-*`, and `--cols-card-*`.
+
+## Charts
+```
+<MyChartEngine style={{height: 400}} />
+createChartCanvas(config) -> canvas controller
+```
+
+The chart engine surface is still mostly low-level. Keep product-specific chart wrappers in the app.
+
+## QA Stand
+```
+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.

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;