@forgeax/interface 0.4.1

package/dist/package/browser/lib/browser-prefs-sync.js

@@ -0,0 +1,151 @@
+/** Persist + restore browser localStorage UI prefs via `/api/prefs/browser-localStorage`.
+ *  Snapshot lands in `.forgeax/prefs/browser-localStorage.json` for export-instance. */
+import { installStorageObservation } from '@forgeax/app-shell/react';
+import { STORAGE_KEYS } from './storageKeys';
+const SYNC_DEBOUNCE_MS = 1500;
+const SYNC_INTERVAL_MS = 30_000;
+const KEY_PREFIXES = ['forgeax.', 'forgeax:project:'];
+// First-run onboarding is a per-browser-profile gate, NOT a portable UI pref.
+// Mirroring it through the server snapshot re-seeds a stale phase back into
+// localStorage on every load (and races the async restore against first paint),
+// which silently kills / replays the wizard and makes a local reset impossible.
+// Keep onboarding purely local: excluding here blocks BOTH push and restore
+// (restoreBrowserLocalStorage also gates on shouldSyncKey), so any pre-existing
+// snapshot entries become inert. Trade-off: an imported instance re-runs the
+// first-run flow once — acceptable, and safer than silently skipping it.
+const KEY_EXCLUDE = new Set([
+    STORAGE_KEYS.onboarding,
+    STORAGE_KEYS.onboardingSeenLegacy,
+]);
+function shouldSyncKey(key) {
+    if (KEY_EXCLUDE.has(key))
+        return false;
+    return KEY_PREFIXES.some((p) => key.startsWith(p));
+}
+export function captureBrowserLocalStorage() {
+    if (typeof window === 'undefined')
+        return {};
+    const entries = {};
+    try {
+        for (let i = 0; i < window.localStorage.length; i++) {
+            const key = window.localStorage.key(i);
+            if (!key || !shouldSyncKey(key))
+                continue;
+            const val = window.localStorage.getItem(key);
+            if (val !== null)
+                entries[key] = val;
+        }
+    }
+    catch {
+        /* private mode */
+    }
+    return entries;
+}
+export function restoreBrowserLocalStorage(entries) {
+    if (typeof window === 'undefined')
+        return 0;
+    let n = 0;
+    try {
+        for (const [key, val] of Object.entries(entries)) {
+            if (!shouldSyncKey(key) || typeof val !== 'string')
+                continue;
+            // Non-destructive: never overwrite a value that already exists locally.
+            // localStorage survives reloads natively, so a fresh same-tab change
+            // (e.g. resetting the dock layout) must win over the periodically-pushed
+            // server snapshot — which is only refreshed on the 30s interval /
+            // unreliable beforeunload. Only fill genuinely-missing keys (fresh
+            // browser, cleared storage, or import into a fresh profile).
+            if (window.localStorage.getItem(key) !== null)
+                continue;
+            window.localStorage.setItem(key, val);
+            n += 1;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return n;
+}
+async function pushBrowserPrefs() {
+    const entries = captureBrowserLocalStorage();
+    if (Object.keys(entries).length === 0)
+        return;
+    try {
+        await fetch('/api/prefs/browser-localStorage', {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                v: 1,
+                exportedAt: new Date().toISOString(),
+                origin: window.location.origin,
+                entries,
+            }),
+        });
+    }
+    catch {
+        /* server may be down during boot */
+    }
+}
+/** Push the current localStorage snapshot to the server immediately (no debounce).
+ *  Call after a same-tab pref change that must survive a quick reload — the
+ *  `storage` event only fires in OTHER tabs, so same-tab writes are otherwise
+ *  only flushed on the 30s interval / beforeunload (unreliable). */
+export function flushBrowserPrefs() {
+    void pushBrowserPrefs();
+}
+/** Pull server snapshot into localStorage. Non-destructive: the snapshot only
+ *  fills keys that are MISSING locally (fresh browser / cleared storage / import
+ *  into a fresh profile). On a normal reload the local value always wins, so a
+ *  same-tab change (e.g. layout reset) is never clobbered by a stale snapshot. */
+export async function syncBrowserPrefsFromServer() {
+    try {
+        const res = await fetch('/api/prefs/browser-localStorage');
+        if (!res.ok)
+            return 0;
+        // Standalone (no backend) serves the SPA index.html for unknown /api
+        // routes — a 200 with text/html. Guard against parsing that as JSON.
+        if (!res.headers.get('content-type')?.includes('application/json'))
+            return 0;
+        const snap = (await res.json());
+        if (!snap.entries || Object.keys(snap.entries).length === 0)
+            return 0;
+        return restoreBrowserLocalStorage(snap.entries);
+    }
+    catch {
+        return 0;
+    }
+}
+let debounceTimer;
+let started = false;
+function schedulePush() {
+    if (debounceTimer)
+        clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+        debounceTimer = undefined;
+        void pushBrowserPrefs();
+    }, SYNC_DEBOUNCE_MS);
+}
+/** Start periodic + event-driven sync to server (call once from main.tsx). */
+export function startBrowserPrefsSync() {
+    if (started || typeof window === 'undefined')
+        return;
+    started = true;
+    const onBrowserPreferenceStorage = (e) => {
+        if (e.key && shouldSyncKey(e.key))
+            schedulePush();
+    };
+    void installStorageObservation({ target: window, onStorage: onBrowserPreferenceStorage });
+    window.addEventListener('beforeunload', () => {
+        void pushBrowserPrefs();
+    });
+    const interval = window.setInterval(() => {
+        void pushBrowserPrefs();
+    }, SYNC_INTERVAL_MS);
+    window.addEventListener('beforeunload', () => {
+        window.clearInterval(interval);
+    });
+    // Initial push after UI settles (captures keys written during boot).
+    window.setTimeout(() => {
+        void pushBrowserPrefs();
+    }, 4000);
+}

package/dist/package/browser/lib/builtin-actions.d.ts

@@ -0,0 +1,2 @@
+/** bootUiBridge 调用一次(幂等)。 */
+export declare function registerBuiltinActions(): void;