wenay-react2 1.0.29 → 1.0.31

package/README.md

@@ -4,8 +4,8 @@ Common React UI primitives for wenay apps.
 
 Use the new concise API guide first:
 
-- [wenay-react2.md](./wenay-react2.md) - canonical everyday API.
-- [wenay-react2-rare.md](./wenay-react2-rare.md) - old names, low-level exports, migration notes.
+- [wenay-react2.md](doc/wenay-react2.md) - canonical everyday API.
+- [wenay-react2-rare.md](doc/wenay-react2-rare.md) - old names, low-level exports, migration notes.
 - [agGrid4 README](./src/common/src/grid/agGrid4/README.md) - table buffer/controller details.
 - [agGrid4 wrapper boundary](./src/common/src/grid/agGrid4/WRAPPER.md) - where generic primitives end and app wrappers begin.
 
@@ -55,4 +55,4 @@ The stand source is `src/common/testUseReact/qa.tsx`. Use it for visual checks a
 
 ```sh
 npm run build
-```
+```

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

@@ -1,4 +1,5 @@
 import React, { ReactNode } from "react";
+import { ObservableMap } from "../../utils/observableMap";
 type tPosition = {
     x: number;
     y: number;
@@ -46,7 +47,7 @@ type tDivRndBase = {
     children: React.ReactElement | ((update: number) => React.ReactElement);
     className?: string;
 };
-export declare const ExRNDMap3: Map<string, tRND>;
+export declare const ExRNDMap3: ObservableMap<string, tRND>;
 export declare const DivRnd3: typeof DivRndBase3;
 /**
  * Wrapper component around react-rnd.

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

@@ -2,8 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useEffect, useLayoutEffect, useRef, useState } from "react";
 import { Rnd } from "react-rnd";
 import { renderBy, updateBy } from "../../../updateBy";
-// Map of all popup window sizes
-export const ExRNDMap3 = new Map();
+import { ObservableMap } from "../../utils/observableMap";
+// Map of all popup window sizes; observable - Cash marks itself dirty on its mutations
+export const ExRNDMap3 = new ObservableMap();
 // limit={{x:{min:0}, y:{min:0}}}
 let k = 0;
 const openWindows = { ar: [] };
@@ -97,6 +98,10 @@ export function DivRndBase3({ children, keyForSave: ks, position, size, overflow
             document.removeEventListener("mousemove", mouseMoveHandler);
             lastC.current = null;
             setA(false);
+            // drag end commits geometry mutated in place - invisible to the map, so announce
+            // it; a no-move click also lands here, the save-side diff turns that into a no-op
+            if (ks)
+                ExRNDMap3.touch(ks);
         };
         // Touch
         const touchMoveHandler = (e) => {
@@ -141,6 +146,8 @@ export function DivRndBase3({ children, keyForSave: ks, position, size, overflow
                 document.removeEventListener("touchend", touchEndHandler);
                 document.removeEventListener("touchmove", touchMoveHandler);
                 setB(false);
+                if (ks)
+                    ExRNDMap3.touch(ks);
             }
         };
         // If mouse dragging mode is active
@@ -227,6 +234,8 @@ export function DivRndBase3({ children, keyForSave: ks, position, size, overflow
             setHeight(elementRef.offsetHeight);
             setWidth(elementRef.offsetWidth);
             setUpdate(update + 1);
+            if (ks)
+                ExRNDMap3.touch(ks);
         }, onResize: (e, dir, elementRef, delta, pos) => {
             onUpdate?.({ e, dir, elementRef, delta, position: pos });
         }, position: { x, y }, size: { width, height }, default: {

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

@@ -1,9 +1,10 @@
 import { ResizableProps } from "re-resizable";
+import { ObservableMap } from "../../utils/observableMap";
 type tSaveMap = {
     height?: number | string;
     width?: number | string;
 };
-export declare const mapResiReact: Map<string, tSaveMap>;
+export declare const mapResiReact: ObservableMap<string, tSaveMap>;
 type t3 = Pick<ResizableProps, "style" | "enable" | "onResize" | "children" | "size" | "maxWidth" | "maxHeight" | "minWidth" | "minHeight">;
 export declare function FResizableReact({ style, onResize, enable, children, keyForSave, onResizeStop, size, minWidth, minHeight, maxWidth, maxHeight, moveWith, moveHeight }: t3 & {
     keyForSave?: string;

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

@@ -1,7 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Resizable } from "re-resizable";
-// Memory for all column sizes
-export const mapResiReact = new Map();
+import { ObservableMap } from "../../utils/observableMap";
+// Memory for all column sizes; observable - Cash marks itself dirty on its mutations
+export const mapResiReact = new ObservableMap();
 export function FResizableReact({ style, onResize, enable, children, keyForSave, onResizeStop, size = { height: 50, width: 50 }, minWidth, minHeight, maxWidth = "100%", maxHeight = "100%", moveWith = true, moveHeight = true }) {
     let obj = size;
     if (keyForSave) {
@@ -30,6 +31,9 @@ export function FResizableReact({ style, onResize, enable, children, keyForSave,
                     obj.height = elementRef.style.height;
                 }
             // onResize?.(size)
+            // obj is mutated in place - invisible to the map, so announce it
+            if (keyForSave)
+                mapResiReact.touch(keyForSave);
             onResizeStop?.(obj);
             // this.Refresh()
         }, size: obj, defaultSize: obj, maxWidth: maxWidth, maxHeight: maxHeight, minWidth: minWidth, minHeight: minHeight, children: children });

package/lib/common/src/components/Menu/RightMenu.js

@@ -67,6 +67,7 @@ export function DropdownMenu({ elements, style, position: initialPosition = 'rig
         setPosition(nextPosition);
         setIsTop(toTop);
         if (keyForSave) {
+            // mapRightMenu is observable: set() itself marks the cache dirty
             mapRightMenu.set(keyForSave, {
                 position: nextPosition,
                 position2: toTop ? 'top' : 'bottom',

package/lib/common/src/components/Menu/RightMenuStore.d.ts

@@ -8,4 +8,5 @@ export type MenuRightSavedState = {
         y: number;
     };
 };
-export declare const mapRightMenu: Map<string, MenuRightSavedState>;
+import { ObservableMap } from "../../utils/observableMap";
+export declare const mapRightMenu: ObservableMap<string, MenuRightSavedState>;

package/lib/common/src/components/Menu/RightMenuStore.js

@@ -1 +1,3 @@
-export const mapRightMenu = new Map();
+import { ObservableMap } from "../../utils/observableMap";
+// observable - Cash marks itself dirty on its mutations (drag end re-set()s the state)
+export const mapRightMenu = new ObservableMap();

package/lib/common/src/components/UiSlot/UiSlot.d.ts

@@ -1,7 +1,8 @@
 import React from "react";
 /** One UI block shown in exactly one of several mount points; the point is a persisted setting.
- *  Persistence rides the existing staticProps -> Cash mechanics: the app calls Cash.load()/save()
- *  the same way it does for window state (ExRNDMap3 etc.).
+ *  Persistence rides the existing staticProps -> Cash mechanics: staticProps is observable,
+ *  setPlace announces its in-place mutation (staticMarkDirty), the app decides when to save
+ *  via Cash.onDirty - same as window state (ExRNDMap3 etc.).
  *  Mount points render <Slot place="..."> themselves and decide nothing: the slot compares
  *  the persisted place with its own and renders children only on a match. */
 export declare function createUiSlot<Places extends string>(opts: {

package/lib/common/src/components/UiSlot/UiSlot.js

@@ -1,9 +1,10 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { renderBy, updateBy } from "../../../updateBy";
-import { staticGetAdd } from "../../utils/mapMemory";
+import { staticGetAdd, staticMarkDirty } from "../../utils/mapMemory";
 /** One UI block shown in exactly one of several mount points; the point is a persisted setting.
- *  Persistence rides the existing staticProps -> Cash mechanics: the app calls Cash.load()/save()
- *  the same way it does for window state (ExRNDMap3 etc.).
+ *  Persistence rides the existing staticProps -> Cash mechanics: staticProps is observable,
+ *  setPlace announces its in-place mutation (staticMarkDirty), the app decides when to save
+ *  via Cash.onDirty - same as window state (ExRNDMap3 etc.).
  *  Mount points render <Slot place="..."> themselves and decide nothing: the slot compares
  *  the persisted place with its own and renders children only on a match. */
 export function createUiSlot(opts) {
@@ -16,6 +17,7 @@ export function createUiSlot(opts) {
             return;
         st.place = p;
         renderBy(st);
+        staticMarkDirty(opts.key);
     };
     function Slot(p) {
         updateBy(st);

package/lib/common/src/hooks/index.d.ts

@@ -1,4 +1,5 @@
 export * from './useAddDownAnyKey';
 export * from './useDraggable';
 export * from './useObserveStore';
+export * from './useReplay';
 export * from './useOutside';

package/lib/common/src/hooks/index.js

@@ -1,4 +1,5 @@
 export * from './useAddDownAnyKey';
 export * from './useDraggable';
 export * from './useObserveStore';
+export * from './useReplay';
 export * from './useOutside';

package/lib/common/src/hooks/useReplay.d.ts

@@ -0,0 +1,94 @@
+import { ObserveAll2, Replay } from "wenay-common2";
+type StorePatch = ObserveAll2.StorePatch;
+type ReplayEvent<Z extends any[]> = Replay.ReplayEvent<Z>;
+type ReplayRemote<Z extends any[]> = Replay.ReplayRemote<Z>;
+export type UseReplaySubscribeOptions = {
+    /** Start position for the first subscription: journal tail after this seq; omit = keyframe. */
+    since?: number;
+    /** Keep the last seen seq across resubscribes (remount/restart) and reconnect with the tail. Default true. */
+    keepSeq?: boolean;
+    /** false = do not subscribe (and drop the current subscription). Default true. */
+    enabled?: boolean;
+    onSeq?: (seq: number) => void;
+    onError?: (e: unknown) => void;
+};
+export type ReplaySubscribeController = {
+    /** Keyframe/tail catch-up finished, events are live from here. */
+    readonly ready: boolean;
+    readonly error: unknown;
+    /** Last seen seq (reconnect point). Getter — reading it does not re-render. */
+    seq(): number;
+    /** Drop and re-create the subscription. since omitted = continue by keepSeq rules; a number = explicit position. */
+    restart(since?: number): void;
+};
+/**
+ * Subscribe to a replay line (`Replay.exposeReplay` shape: {line, since, keyframe}).
+ * The delivery contract of the line is preserved as is: cb first receives the snapshot
+ * (keyframe as a normal event), then strictly-newer events, seq-ascending, deduped.
+ * cb goes through a ref — a new cb identity does not resubscribe.
+ */
+export declare function useReplaySubscribe<Z extends any[]>(remote: ReplayRemote<Z> | null | undefined, cb: (...event: Z) => void, options?: UseReplaySubscribeOptions): ReplaySubscribeController;
+export type UseStoreReplaySyncOptions = UseReplaySubscribeOptions;
+export type StoreReplaySyncController = ReplaySubscribeController;
+/**
+ * Sync an existing mirror store from a store replay line (`ObserveAll2.exposeStoreReplay(...).api.replay`).
+ * Thin lifecycle wrapper over `ObserveAll2.syncStoreReplay`: the keyframe (root patch) and the
+ * patch tail are applied to the store by the library; UI subscribes to the store as usual
+ * (useStoreNode/useStoreSelect).
+ */
+export declare function useStoreReplaySync<T extends object>(store: ObserveAll2.Store<T> | null | undefined, remote: ReplayRemote<[StorePatch]> | null | undefined, options?: UseStoreReplaySyncOptions): StoreReplaySyncController;
+export type StoreReplayMirrorController<T extends object> = StoreReplaySyncController & {
+    readonly store: ObserveAll2.Store<T>;
+};
+/**
+ * Convenience: create a local mirror store and keep it synced from a store replay line.
+ * The store lives in a ref — a component remount keeps both the state and the seq,
+ * so reconnect is a journal tail, not a keyframe. A new `remote` recreates the store.
+ */
+export declare function useStoreReplayMirror<T extends object>(remote: ReplayRemote<[StorePatch]> | null | undefined, initial: T, options?: UseStoreReplaySyncOptions): StoreReplayMirrorController<T>;
+export type ReplayHistoryLike<Z extends any[]> = {
+    at(where?: {
+        seq?: number;
+        ts?: number;
+    }): ReplayEvent<Z>[] | undefined;
+    subscribe(cb: (...event: Z) => void, opts?: {
+        since?: number;
+        ts?: number;
+        onSeq?: (seq: number) => void;
+    }): (() => void) & {
+        seq: () => number;
+    };
+};
+export type UseReplayHistoryOptions = {
+    /** Live head seq getter (slider max), e.g. `() => replay.head()`. Without it head = max seen seq. */
+    head?: () => number;
+    /** Called before folding a seek (clear consumer state). Usually not needed: a keyframe fully redefines the state. */
+    reset?: () => void;
+    /** UI position/head refresh period while live, ms. Default 300. */
+    tickMs?: number;
+    /** Follow live on mount. Default true. */
+    autoPlay?: boolean;
+};
+export type ReplayHistoryController = {
+    /** true = following live (archive tail -> live handover), false = paused/seeked. */
+    readonly live: boolean;
+    /** Current playback position (UI state; refreshed every tickMs while live). */
+    readonly seq: number;
+    /** Last known head seq (slider max). */
+    readonly head: number;
+    pause(): void;
+    /** Resume from the current position: journal/archive tail, then live. */
+    play(): void;
+    /** Pause and jump: fold keyframe + events up to the position through `apply`. */
+    seek(where: {
+        seq?: number;
+        ts?: number;
+    }): void;
+};
+/**
+ * Time machine over `Replay.openHistory(storage, live?)`: scrubber/pause/resume for any replay line.
+ * `apply` folds ONE event into the consumer state (draw a frame, apply a store patch, ...) —
+ * the same fold works for live playback and for seeks, snapshot is not a special case.
+ */
+export declare function useReplayHistory<Z extends any[]>(history: ReplayHistoryLike<Z> | null | undefined, apply: (...event: Z) => void, options?: UseReplayHistoryOptions): ReplayHistoryController;
+export {};

package/lib/common/src/hooks/useReplay.js

@@ -0,0 +1,222 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ObserveAll2, Replay } from "wenay-common2";
+/**
+ * React bridge over the Replay stack (snapshot + sequenced delta line) of wenay-common2.
+ *
+ * The lifecycle rules these hooks encapsulate:
+ * - off() on unmount, subscription never outlives the component (StrictMode double-effect safe);
+ * - seq survives resubscribes within a mounted component (StrictMode double-effect, restart(),
+ *   enabled toggling): the resubscribe reconnects with {since: lastSeq} and receives the journal
+ *   tail instead of a full keyframe — as long as the folded state itself lives outside the effect
+ *   (ref/store/canvas). If the consumer state resets on resubscribe, pass {keepSeq: false};
+ * - a FULL unmount loses the hook's refs: to reconnect by tail after a remount, keep the position
+ *   outside via onSeq and pass it back as `since` (see the QA card for the pattern);
+ * - a different `remote` identity always starts from scratch (seq from another line is meaningless).
+ *
+ * Server-side parts of the stack (conflateReplay, archiveReplay) are per-connection/per-process
+ * and intentionally have no hooks here.
+ */
+function useLatestRef(value) {
+    const ref = useRef(value);
+    ref.current = value;
+    return ref;
+}
+/**
+ * Subscribe to a replay line (`Replay.exposeReplay` shape: {line, since, keyframe}).
+ * The delivery contract of the line is preserved as is: cb first receives the snapshot
+ * (keyframe as a normal event), then strictly-newer events, seq-ascending, deduped.
+ * cb goes through a ref — a new cb identity does not resubscribe.
+ */
+export function useReplaySubscribe(remote, cb, options = {}) {
+    const { since, keepSeq = true, enabled = true, onSeq, onError } = options;
+    const cbRef = useLatestRef(cb);
+    const hooksRef = useLatestRef({ onSeq, onError });
+    const seqRef = useRef(since);
+    const subRef = useRef(null);
+    const lastRemoteRef = useRef(undefined);
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState(null);
+    const [epoch, setEpoch] = useState(0);
+    useEffect(() => {
+        if (!remote || !enabled)
+            return;
+        if (lastRemoteRef.current !== undefined && lastRemoteRef.current !== remote)
+            seqRef.current = undefined; // a different line — old seq is meaningless
+        lastRemoteRef.current = remote;
+        let alive = true;
+        setReady(false);
+        setError(null);
+        const off = Replay.replaySubscribe(remote, (...event) => cbRef.current(...event), {
+            since: seqRef.current,
+            onSeq: seq => {
+                seqRef.current = seq;
+                hooksRef.current.onSeq?.(seq);
+            },
+            onError: e => {
+                if (alive)
+                    setError(e);
+                hooksRef.current.onError?.(e);
+            },
+        });
+        subRef.current = off;
+        off.ready.then(() => { if (alive)
+            setReady(true); }, e => { if (alive)
+            setError(e); });
+        return () => {
+            alive = false;
+            subRef.current = null;
+            off();
+            if (!keepSeq)
+                seqRef.current = since;
+        };
+        // keepSeq/since are start-position config, not subscription identity — no resubscribe on change
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [remote, enabled, epoch]);
+    const seq = useCallback(() => subRef.current?.seq() ?? seqRef.current ?? -1, []);
+    const restart = useCallback((at) => {
+        if (at !== undefined)
+            seqRef.current = at;
+        setEpoch(v => v + 1);
+    }, []);
+    return useMemo(() => ({ ready, error, seq, restart }), [ready, error, seq, restart]);
+}
+/**
+ * Sync an existing mirror store from a store replay line (`ObserveAll2.exposeStoreReplay(...).api.replay`).
+ * Thin lifecycle wrapper over `ObserveAll2.syncStoreReplay`: the keyframe (root patch) and the
+ * patch tail are applied to the store by the library; UI subscribes to the store as usual
+ * (useStoreNode/useStoreSelect).
+ */
+export function useStoreReplaySync(store, remote, options = {}) {
+    const { since, keepSeq = true, enabled = true, onSeq, onError } = options;
+    const hooksRef = useLatestRef({ onSeq, onError });
+    const seqRef = useRef(since);
+    const subRef = useRef(null);
+    const lastRemoteRef = useRef(undefined);
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState(null);
+    const [epoch, setEpoch] = useState(0);
+    useEffect(() => {
+        if (!store || !remote || !enabled)
+            return;
+        if (lastRemoteRef.current !== undefined && lastRemoteRef.current !== remote)
+            seqRef.current = undefined;
+        lastRemoteRef.current = remote;
+        let alive = true;
+        setReady(false);
+        setError(null);
+        const off = ObserveAll2.syncStoreReplay(store, remote, {
+            since: seqRef.current,
+            onSeq: seq => {
+                seqRef.current = seq;
+                hooksRef.current.onSeq?.(seq);
+            },
+            onError: e => {
+                if (alive)
+                    setError(e);
+                hooksRef.current.onError?.(e);
+            },
+        });
+        subRef.current = off;
+        off.ready.then(() => { if (alive)
+            setReady(true); }, e => { if (alive)
+            setError(e); });
+        return () => {
+            alive = false;
+            subRef.current = null;
+            off();
+            if (!keepSeq)
+                seqRef.current = since;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [store, remote, enabled, epoch]);
+    const seq = useCallback(() => subRef.current?.seq() ?? seqRef.current ?? -1, []);
+    const restart = useCallback((at) => {
+        if (at !== undefined)
+            seqRef.current = at;
+        setEpoch(v => v + 1);
+    }, []);
+    return useMemo(() => ({ ready, error, seq, restart }), [ready, error, seq, restart]);
+}
+/**
+ * Convenience: create a local mirror store and keep it synced from a store replay line.
+ * The store lives in a ref — a component remount keeps both the state and the seq,
+ * so reconnect is a journal tail, not a keyframe. A new `remote` recreates the store.
+ */
+export function useStoreReplayMirror(remote, initial, options = {}) {
+    const storeRef = useRef(null);
+    if (!storeRef.current || storeRef.current.remote !== remote) {
+        storeRef.current = { remote, store: ObserveAll2.createStore(initial) };
+    }
+    const store = storeRef.current.store;
+    const sync = useStoreReplaySync(store, remote, options);
+    return useMemo(() => ({ ...sync, store }), [sync, store]);
+}
+/**
+ * Time machine over `Replay.openHistory(storage, live?)`: scrubber/pause/resume for any replay line.
+ * `apply` folds ONE event into the consumer state (draw a frame, apply a store patch, ...) —
+ * the same fold works for live playback and for seeks, snapshot is not a special case.
+ */
+export function useReplayHistory(history, apply, options = {}) {
+    const { head: headGetter, reset, tickMs = 300, autoPlay = true } = options;
+    const applyRef = useLatestRef(apply);
+    const resetRef = useLatestRef(reset);
+    const headRef = useLatestRef(headGetter);
+    const posRef = useRef(-1);
+    const killRef = useRef(null);
+    const [live, setLive] = useState(autoPlay);
+    const [pos, setPos] = useState(-1);
+    const [head, setHead] = useState(-1);
+    const readHead = useCallback(() => {
+        const h = headRef.current ? headRef.current() : -1;
+        return Math.max(h, posRef.current);
+    }, [headRef]);
+    useEffect(() => {
+        if (!history || !live)
+            return;
+        const off = history.subscribe((...event) => applyRef.current(...event), {
+            since: posRef.current >= 0 ? posRef.current : undefined,
+            onSeq: seq => { posRef.current = seq; },
+        });
+        let done = false;
+        killRef.current = () => {
+            if (done)
+                return;
+            done = true;
+            off();
+        };
+        const timer = setInterval(() => {
+            setPos(posRef.current);
+            setHead(readHead());
+        }, tickMs);
+        return () => {
+            clearInterval(timer);
+            killRef.current?.();
+            killRef.current = null;
+        };
+    }, [history, live, tickMs, applyRef, readHead]);
+    const pause = useCallback(() => {
+        killRef.current?.(); // stop deliveries immediately, not on the next render
+        killRef.current = null;
+        setLive(false);
+        setPos(posRef.current);
+        setHead(readHead());
+    }, [readHead]);
+    const play = useCallback(() => setLive(true), []);
+    const seek = useCallback((where) => {
+        if (!history)
+            return;
+        killRef.current?.();
+        killRef.current = null;
+        setLive(false);
+        const events = history.at(where);
+        if (events && events.length) {
+            resetRef.current?.();
+            for (const ev of events)
+                applyRef.current(...ev.event);
+            posRef.current = events[events.length - 1].seq;
+        }
+        setPos(posRef.current);
+        setHead(readHead());
+    }, [history, applyRef, resetRef, readHead]);
+    return useMemo(() => ({ live, seq: pos, head, pause, play, seek }), [live, pos, head, pause, play, seek]);
+}

package/lib/common/src/utils/cache.d.ts

@@ -1,3 +1,4 @@
+export type tDirtyListener = (scope?: string, key?: string) => void;
 export interface IServerSaveBasePromise {
     set(key: string, value: object): Promise<boolean>;
     get<T extends (object)>(key: string): Promise<T | null>;
@@ -23,6 +24,12 @@ export declare function CacheFuncMapBase(arr: [k: string, v: Map<string, unknown
     saveDebounced(delay?: number): void;
     flush(): Promise<void>;
     clear(): Promise<void>;
+    /** Manual announcement for state the observable maps cannot see (plain Map entries). */
+    markDirty: (scope?: string, key?: string) => void;
+    /** Subscribe to this instance's dirty events (coalesced, async); returns unsubscribe. */
+    onDirty(cb: tDirtyListener): () => void;
+    /** Cheap hint (e.g. a beforeunload guard); the save diff is the source of truth. */
+    isDirty(): boolean;
     getArr: [k: string, v: Map<string, unknown>][];
 };
 export declare function CacheFuncMap(arr: [k: string, v: Map<string, unknown>][]): {
@@ -31,5 +38,11 @@ export declare function CacheFuncMap(arr: [k: string, v: Map<string, unknown>][]
     saveDebounced(delay?: number): void;
     flush(): Promise<void>;
     clear(): Promise<void>;
+    /** Manual announcement for state the observable maps cannot see (plain Map entries). */
+    markDirty: (scope?: string, key?: string) => void;
+    /** Subscribe to this instance's dirty events (coalesced, async); returns unsubscribe. */
+    onDirty(cb: tDirtyListener): () => void;
+    /** Cheap hint (e.g. a beforeunload guard); the save diff is the source of truth. */
+    isDirty(): boolean;
     getArr: [k: string, v: Map<string, unknown>][];
 };

package/lib/common/src/utils/index.d.ts

@@ -4,4 +4,5 @@ export * from './cache';
 export * from './callbackHub';
 export * from './inputAutoStep';
 export * from './mapMemory';
+export * from './observableMap';
 export * from './pageVisibilityContext';

package/lib/common/src/utils/index.js

@@ -4,4 +4,5 @@ export * from './cache';
 export * from './callbackHub';
 export * from './inputAutoStep';
 export * from './mapMemory';
+export * from './observableMap';
 export * from './pageVisibilityContext';

package/lib/common/src/utils/mapMemory.d.ts

@@ -1,3 +1,4 @@
+import { ObservableMap } from "./observableMap";
 export declare function staticSet(key: any, data: object): void;
 export declare function staticGet(key: any): object | undefined;
 export declare function deepMergeWithMap(target: any, source: any, visited?: Map<any, any>): any;
@@ -6,6 +7,13 @@ export declare function staticGetAdd<T extends object>(key: any, def: T, options
     deepAutoMerge?: boolean;
     reversDeep?: boolean;
 }): T;
+/** Announce a direct in-place mutation of an object taken from staticGetAdd - such
+ *  mutations are invisible to map methods. staticSet/staticGetAdd need no announcement:
+ *  their set() calls are observed by Cash automatically. */
+export declare function staticMarkDirty(key: any): void;
+/** App-facing change of a persisted staticProps entry in one call:
+ *  mutate + rerender subscribers + mark the cache dirty. No-op if the key is absent. */
+export declare function staticUpdate<T extends object>(key: any, mutate: (cur: T) => void): T | undefined;
 export declare function staticGetById<T extends object>(key: any, def: T, id: string | number): T;
 export declare const Cash: {
     load(): Promise<void>;
@@ -13,10 +21,13 @@ export declare const Cash: {
     saveDebounced(delay?: number): void;
     flush(): Promise<void>;
     clear(): Promise<void>;
+    markDirty: (scope?: string, key?: string) => void;
+    onDirty(cb: import("./cache").tDirtyListener): () => void;
+    isDirty(): boolean;
     getArr: [k: string, v: Map<string, unknown>][];
 };
 export declare const MemoryMap: {
-    rnd: Map<string, {
+    rnd: ObservableMap<string, {
         position: {
             x: number;
             y: number;
@@ -26,10 +37,10 @@ export declare const MemoryMap: {
             width: number | string;
         };
     }>;
-    resize: Map<string, {
+    resize: ObservableMap<string, {
         height?: number | string;
         width?: number | string;
     }>;
-    rightMenu: Map<string, import("../components/Menu/RightMenuStore").MenuRightSavedState>;
-    other: Map<string, object>;
+    rightMenu: ObservableMap<string, import("../components/Menu/RightMenuStore").MenuRightSavedState>;
+    other: ObservableMap<string, object>;
 };

package/lib/common/src/utils/mapMemory.js

@@ -1,9 +1,12 @@
 import { deepClone } from "wenay-common2";
+import { renderBy } from "../../updateBy";
 import { ExRNDMap3 } from "../components/Dnd/RNDFunc3";
 import { mapResiReact } from "../components/Dnd/Resizable";
 import { mapRightMenu } from "../components/Menu/RightMenuStore";
 import { CacheFuncMap } from "./cache";
-const staticProps = new Map();
+import { ObservableMap } from "./observableMap";
+// observable - Cash marks itself dirty on its mutations
+const staticProps = new ObservableMap();
 export function staticSet(key, data) {
     if (!staticProps.has(key))
         staticProps.set(key, data);
@@ -52,6 +55,23 @@ export function staticGetAdd(key, def, options = { reversDeep: false }) {
     const t = (staticProps.has(key) ? staticProps.get(key) : staticProps.set(key, def).get(key));
     return t; // Object.assign(def, t) // t //
 }
+/** Announce a direct in-place mutation of an object taken from staticGetAdd - such
+ *  mutations are invisible to map methods. staticSet/staticGetAdd need no announcement:
+ *  their set() calls are observed by Cash automatically. */
+export function staticMarkDirty(key) {
+    staticProps.touch(typeof key == "string" ? key : undefined);
+}
+/** App-facing change of a persisted staticProps entry in one call:
+ *  mutate + rerender subscribers + mark the cache dirty. No-op if the key is absent. */
+export function staticUpdate(key, mutate) {
+    const cur = staticProps.get(key);
+    if (cur === undefined)
+        return undefined;
+    mutate(cur);
+    renderBy(cur);
+    staticMarkDirty(key);
+    return cur;
+}
 export function staticGetById(key, def, id) {
     const stored = staticProps.get(key);
     if (!stored || stored.__id !== id) {

package/lib/common/src/utils/observableMap.d.ts

@@ -0,0 +1,17 @@
+/** Map that announces its own mutations. The persisted-state maps (ExRNDMap3, mapResiReact,
+ *  mapRightMenu, staticProps) are ObservableMap instances, so the dirty signal originates in
+ *  the data layer itself: set/delete/clear emit automatically, touch(key) announces an
+ *  in-place mutation of a stored object (invisible to map methods). CacheFuncMapBase
+ *  subscribes to the maps it owns - mutation sites never talk to the cache directly. */
+export type tMapChangeListener<K> = (key?: K) => void;
+export declare class ObservableMap<K, V> extends Map<K, V> {
+    private listeners?;
+    /** Subscribe to mutations (set/delete/clear/touch); returns unsubscribe. */
+    onChange(cb: tMapChangeListener<K>): () => void;
+    /** Announce an in-place mutation of a stored value. */
+    touch(key?: K): void;
+    private emit;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    clear(): void;
+}

package/lib/common/src/utils/observableMap.js

@@ -0,0 +1,40 @@
+/** Map that announces its own mutations. The persisted-state maps (ExRNDMap3, mapResiReact,
+ *  mapRightMenu, staticProps) are ObservableMap instances, so the dirty signal originates in
+ *  the data layer itself: set/delete/clear emit automatically, touch(key) announces an
+ *  in-place mutation of a stored object (invisible to map methods). CacheFuncMapBase
+ *  subscribes to the maps it owns - mutation sites never talk to the cache directly. */
+export class ObservableMap extends Map {
+    // no initializer: Map's constructor calls this.set() before class fields are assigned
+    listeners;
+    /** Subscribe to mutations (set/delete/clear/touch); returns unsubscribe. */
+    onChange(cb) {
+        (this.listeners ??= new Set()).add(cb);
+        return () => { this.listeners?.delete(cb); };
+    }
+    /** Announce an in-place mutation of a stored value. */
+    touch(key) { this.emit(key); }
+    emit(key) {
+        if (!this.listeners?.size)
+            return;
+        // copy before iterating: an unsubscribe from inside a callback must not skip the rest
+        for (const cb of [...this.listeners])
+            cb(key);
+    }
+    set(key, value) {
+        super.set(key, value);
+        this.emit(key);
+        return this;
+    }
+    delete(key) {
+        const existed = super.delete(key);
+        if (existed)
+            this.emit(key);
+        return existed;
+    }
+    clear() {
+        const hadEntries = this.size > 0;
+        super.clear();
+        if (hadEntries)
+            this.emit();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wenay-react2",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "description": "Common react",
   "strict": true,
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-rnd": "^10.5.3",
-    "wenay-common2": "^1.0.53"
+    "wenay-common2": "^1.0.56"
   },
   "peerDependencies": {
     "react": "^19.2.0",