@weasel-js/labkit 1.4.3 → 1.5.0

package/dist/chunk-RWNDDKOH.js

@@ -0,0 +1,682 @@
+import { TrialIdContext } from './chunk-2YILQ7Y5.js';
+import { createContext, useRef, useState, useEffect, useContext, useCallback, useSyncExternalStore } from 'react';
+import { jsx, Fragment } from 'react/jsx-runtime';
+
+// src/state/helpers.ts
+function labStorageKey(storageKey, bucket) {
+  return `lk:${storageKey}:${bucket}`;
+}
+function encodeUrlHash(value) {
+  return btoa(encodeURIComponent(value));
+}
+function decodeUrlHash(hash) {
+  if (!hash) return null;
+  try {
+    return decodeURIComponent(atob(hash));
+  } catch {
+    return null;
+  }
+}
+var idCounter = 0;
+function newId() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  return `lk-${Date.now().toString(36)}-${idCounter++}`;
+}
+function emptyUndoStack() {
+  return { past: [], future: [] };
+}
+function serializeTrials(trials, serializers) {
+  return trials.map(({ undoStack: _undo, ...w }) => {
+    const s = serializers[w.instrumentName];
+    return { ...w, state: s?.serialize ? s.serialize(w.state) : w.state };
+  });
+}
+function deserializeTrials(records, deserializers) {
+  if (!Array.isArray(records)) {
+    console.warn("[labkit] deserializeTrials: not an array, returning empty list");
+    return [];
+  }
+  return records.map((r) => {
+    const d = deserializers[r.instrumentName];
+    return {
+      ...r,
+      state: d?.deserialize ? d.deserialize(r.state, r.config) : r.state,
+      undoStack: emptyUndoStack()
+    };
+  });
+}
+
+// src/state/adapters.ts
+function parse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+function isJsonSafe(value, seen = /* @__PURE__ */ new Set()) {
+  if (value === null) return true;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return true;
+    case "number":
+      return Number.isFinite(value);
+    case "object": {
+      if (seen.has(value)) return false;
+      seen.add(value);
+      const proto = Object.getPrototypeOf(value);
+      const ok = Array.isArray(value) ? value.every((v) => isJsonSafe(v, seen)) : (proto === Object.prototype || proto === null) && Object.values(value).every((v) => v === void 0 || isJsonSafe(v, seen));
+      seen.delete(value);
+      return ok;
+    }
+    default:
+      return false;
+  }
+}
+function webStorageAdapter(area, name, crossTab) {
+  const warned = /* @__PURE__ */ new Set();
+  const adapter = {
+    get: async (key) => {
+      const raw = area().getItem(key);
+      return raw === null ? void 0 : parse(raw);
+    },
+    list: async (prefix) => {
+      const store = area();
+      const out = [];
+      for (let i = 0; i < store.length; i++) {
+        const key = store.key(i);
+        if (key === null || !key.startsWith(prefix)) continue;
+        const raw = store.getItem(key);
+        if (raw !== null) out.push([key, parse(raw)]);
+      }
+      return out;
+    },
+    set: async (key, value) => {
+      if (!warned.has(key) && !isJsonSafe(value)) {
+        warned.add(key);
+        console.warn(
+          `[labkit] "${key}" holds a value JSON cannot keep exactly; ${name} stores what JSON keeps. Use IndexedDB for binary or non-JSON state.`
+        );
+      }
+      area().setItem(key, JSON.stringify(value));
+    },
+    delete: async (key) => {
+      area().removeItem(key);
+    }
+  };
+  if (crossTab) {
+    adapter.subscribe = (prefix, on) => {
+      if (typeof window === "undefined") return () => {
+      };
+      const handler = (e) => {
+        if (e.key === null || !e.key.startsWith(prefix)) return;
+        if (e.storageArea !== area()) return;
+        on([[e.key, e.newValue === null ? void 0 : parse(e.newValue)]]);
+      };
+      window.addEventListener("storage", handler);
+      return () => window.removeEventListener("storage", handler);
+    };
+  }
+  return adapter;
+}
+var localStorageAdapter = webStorageAdapter(
+  () => localStorage,
+  "localStorage",
+  true
+);
+var sessionStorageAdapter = webStorageAdapter(
+  () => sessionStorage,
+  "sessionStorage",
+  false
+);
+var URL_HASH_GUARD = typeof window !== "undefined";
+function readHashMap() {
+  if (!URL_HASH_GUARD) return {};
+  const raw = decodeUrlHash(window.location.hash.replace(/^#/, ""));
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+var hashSubscribers = /* @__PURE__ */ new Set();
+function writeHashMap(map) {
+  if (!URL_HASH_GUARD) return;
+  const encoded = encodeUrlHash(JSON.stringify(map));
+  window.history.replaceState(null, "", `#${encoded}`);
+  for (const sub of hashSubscribers) sub.last = { ...map };
+}
+var urlHashAdapter = {
+  get: async (key) => {
+    const raw = readHashMap()[key];
+    return raw === void 0 ? void 0 : parse(raw);
+  },
+  list: async (prefix) => Object.entries(readHashMap()).filter(([key]) => key.startsWith(prefix)).map(([key, raw]) => [key, parse(raw)]),
+  set: async (key, value) => {
+    const map = readHashMap();
+    map[key] = JSON.stringify(value);
+    writeHashMap(map);
+  },
+  delete: async (key) => {
+    const map = readHashMap();
+    delete map[key];
+    writeHashMap(map);
+  },
+  subscribe: (prefix, on) => {
+    if (!URL_HASH_GUARD) return () => {
+    };
+    const sub = { last: readHashMap() };
+    hashSubscribers.add(sub);
+    const handler = () => {
+      const next = readHashMap();
+      const changes = [];
+      for (const key of /* @__PURE__ */ new Set([...Object.keys(sub.last), ...Object.keys(next)])) {
+        if (!key.startsWith(prefix) || sub.last[key] === next[key]) continue;
+        const raw = next[key];
+        changes.push([key, raw === void 0 ? void 0 : parse(raw)]);
+      }
+      sub.last = next;
+      if (changes.length > 0) on(changes);
+    };
+    window.addEventListener("hashchange", handler);
+    return () => {
+      hashSubscribers.delete(sub);
+      window.removeEventListener("hashchange", handler);
+    };
+  }
+};
+var memorySubscribers = /* @__PURE__ */ new WeakMap();
+function createMemoryAdapter(backing = /* @__PURE__ */ new Map()) {
+  let subscribers = memorySubscribers.get(backing);
+  if (!subscribers) {
+    subscribers = /* @__PURE__ */ new Set();
+    memorySubscribers.set(backing, subscribers);
+  }
+  const peers = subscribers;
+  const notify = (key, value) => {
+    for (const sub of peers) {
+      if (sub.owner === adapter || !key.startsWith(sub.prefix)) continue;
+      const copy = value === void 0 ? void 0 : structuredClone(value);
+      queueMicrotask(() => sub.on([[key, copy]]));
+    }
+  };
+  const adapter = {
+    get: async (key) => backing.has(key) ? structuredClone(backing.get(key)) : void 0,
+    list: async (prefix) => [...backing].filter(([key]) => key.startsWith(prefix)).map(([key, value]) => [key, structuredClone(value)]),
+    set: async (key, value) => {
+      const copy = structuredClone(value);
+      backing.set(key, copy);
+      notify(key, copy);
+    },
+    delete: async (key) => {
+      backing.delete(key);
+      notify(key, void 0);
+    },
+    subscribe: (prefix, on) => {
+      const sub = { owner: adapter, prefix, on };
+      peers.add(sub);
+      return () => {
+        peers.delete(sub);
+      };
+    }
+  };
+  return adapter;
+}
+var noneAdapter = {
+  get: async () => void 0,
+  list: async () => [],
+  set: async () => {
+  },
+  delete: async () => {
+  }
+};
+function createIndexedDbAdapter({
+  database = "labkit",
+  store = "records"
+} = {}) {
+  let opened = null;
+  const open = () => {
+    opened ??= new Promise((resolve, reject) => {
+      if (typeof indexedDB === "undefined") {
+        reject(new Error("[labkit] IndexedDB is not available here"));
+        return;
+      }
+      const request = indexedDB.open(database, 1);
+      request.onupgradeneeded = () => {
+        if (!request.result.objectStoreNames.contains(store)) {
+          request.result.createObjectStore(store);
+        }
+      };
+      request.onsuccess = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(store)) {
+          reject(new Error(`[labkit] IndexedDB database "${database}" has no store "${store}"`));
+          return;
+        }
+        resolve(db);
+      };
+      request.onerror = () => reject(request.error);
+      request.onblocked = () => reject(new Error(`[labkit] IndexedDB "${database}" is blocked`));
+    });
+    return opened;
+  };
+  const run = (mode, body) => open().then(
+    (db) => new Promise((resolve, reject) => {
+      const tx = db.transaction(store, mode);
+      const result = body(tx.objectStore(store));
+      tx.oncomplete = () => resolve(result());
+      tx.onerror = () => reject(tx.error);
+      tx.onabort = () => reject(tx.error);
+    })
+  );
+  let channel = null;
+  const getChannel = () => {
+    if (typeof BroadcastChannel === "undefined") return null;
+    if (!channel) {
+      channel = new BroadcastChannel(`labkit:${database}:${store}`);
+      channel.unref?.();
+    }
+    return channel;
+  };
+  const announce = (changes) => {
+    getChannel()?.postMessage(changes);
+  };
+  const adapter = {
+    get: (key) => run("readonly", (s) => {
+      const request = s.get(key);
+      return () => request.result;
+    }),
+    list: (prefix) => run("readonly", (s) => {
+      const range = IDBKeyRange.bound(prefix, `${prefix}\uFFFF`);
+      const keys = s.getAllKeys(range);
+      const values = s.getAll(range);
+      return () => keys.result.map((key, i) => [String(key), values.result[i]]);
+    }),
+    set: async (key, value) => {
+      await run("readwrite", (s) => {
+        s.put(value, key);
+        return () => void 0;
+      });
+      announce([[key, value]]);
+    },
+    delete: async (key) => {
+      await run("readwrite", (s) => {
+        s.delete(key);
+        return () => void 0;
+      });
+      announce([[key, void 0]]);
+    }
+  };
+  if (typeof BroadcastChannel !== "undefined") {
+    adapter.subscribe = (prefix, on) => {
+      const ch = getChannel();
+      if (!ch) return () => {
+      };
+      const handler = (e) => {
+        const mine = e.data.filter(([key]) => key.startsWith(prefix));
+        if (mine.length > 0) on(mine);
+      };
+      ch.addEventListener("message", handler);
+      return () => ch.removeEventListener("message", handler);
+    };
+  }
+  return adapter;
+}
+var indexedDbAdapter = createIndexedDbAdapter();
+var resolvedDefault = null;
+function defaultStorage() {
+  resolvedDefault ??= indexedDbAdapter.list("\0").then(
+    () => indexedDbAdapter,
+    (error) => {
+      console.warn("[labkit] IndexedDB would not open; persisting to localStorage instead", error);
+      return localStorageAdapter;
+    }
+  );
+  return resolvedDefault;
+}
+
+// src/state/labRecords.ts
+function labPrefix(storageKey) {
+  return `lk:${encodeURIComponent(storageKey)}:`;
+}
+var META_RECORD = "meta";
+var LAYOUT_RECORD = "layout";
+var UNDOCK_RECORD = "undock";
+function trialRecord(id) {
+  return `trial:${encodeURIComponent(id)}`;
+}
+function saveRecord(id) {
+  return `save:${encodeURIComponent(id)}`;
+}
+function trialValuesPrefix(trialId) {
+  return `value:trial:${encodeURIComponent(trialId)}:`;
+}
+function valueRecord(trialId, name) {
+  const encoded = encodeURIComponent(name);
+  return trialId === null ? `value:lab:${encoded}` : `${trialValuesPrefix(trialId)}${encoded}`;
+}
+function parseRecordName(name) {
+  const parts = name.split(":");
+  try {
+    switch (parts[0]) {
+      case "meta":
+      case "layout":
+      case "undock":
+        return parts.length === 1 ? { kind: parts[0] } : null;
+      case "trial":
+      case "save":
+        return parts.length === 2 && parts[1] ? { kind: parts[0], id: decodeURIComponent(parts[1]) } : null;
+      case "value":
+        return parts[1] === "lab" && parts.length === 3 || parts[1] === "trial" && parts.length === 4 ? { kind: "value" } : null;
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function recordsOfDocument(doc) {
+  return [
+    ...doc.trials.map((t, order) => [trialRecord(t.id), { ...t, order }]),
+    ...doc.saves.map((s) => [saveRecord(s.id), s]),
+    [LAYOUT_RECORD, doc.layout],
+    [UNDOCK_RECORD, doc.undockedPanels],
+    [META_RECORD, { version: doc.version, mode: doc.mode }]
+  ];
+}
+function documentOfRecords(entries) {
+  let meta;
+  let layout;
+  let undock;
+  const trials = [];
+  const saves = [];
+  for (const [name, value] of entries) {
+    const parsed = parseRecordName(name);
+    if (!parsed) continue;
+    switch (parsed.kind) {
+      case "meta":
+        meta = value;
+        break;
+      case "layout":
+        layout = value;
+        break;
+      case "undock":
+        undock = value;
+        break;
+      case "trial":
+        if (isObject(value)) {
+          const { order, ...rest } = value;
+          trials.push({
+            trial: { ...rest, id: parsed.id },
+            order: typeof order === "number" && Number.isFinite(order) ? order : Infinity
+          });
+        }
+        break;
+      case "save":
+        if (isObject(value)) saves.push({ ...value, id: parsed.id });
+        break;
+    }
+  }
+  if (!isObject(meta)) return null;
+  trials.sort(compareTrialOrder);
+  const orders = /* @__PURE__ */ new Map();
+  let next = 0;
+  for (const { trial, order } of trials) {
+    const at = Number.isFinite(order) ? order : next;
+    orders.set(trial.id, at);
+    next = Math.max(next, at + 1);
+  }
+  saves.sort((a, b) => a.savedAt - b.savedAt);
+  return {
+    doc: {
+      version: meta.version,
+      mode: meta.mode,
+      trials: trials.map((t) => t.trial),
+      saves,
+      layout,
+      undockedPanels: undock
+    },
+    orders
+  };
+}
+function compareTrialOrder(a, b) {
+  if (a.order !== b.order) return a.order < b.order ? -1 : 1;
+  return a.trial.id < b.trial.id ? -1 : a.trial.id > b.trial.id ? 1 : 0;
+}
+
+// src/state/records.ts
+var DELETED = /* @__PURE__ */ Symbol("deleted");
+function createRecordCache(options) {
+  const { storage, prefix } = options;
+  const debounceMs = options.debounceMs ?? 300;
+  const maxWaitMs = options.maxWaitMs ?? 1e3;
+  const values = new Map(options.initial ?? []);
+  const queued = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  let writable = options.writable ?? true;
+  let closed = false;
+  let timer = null;
+  let firstQueuedAt = null;
+  const emit = (changes) => {
+    for (const listener of [...listeners]) listener(changes);
+  };
+  const schedule = () => {
+    if (!writable || closed) return;
+    const now = Date.now();
+    firstQueuedAt ??= now;
+    if (timer) clearTimeout(timer);
+    const wait = Math.max(0, Math.min(debounceMs, firstQueuedAt + maxWaitMs - now));
+    timer = setTimeout(() => {
+      timer = null;
+      void flush();
+    }, wait);
+  };
+  async function flush() {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    firstQueuedAt = null;
+    if (!writable || queued.size === 0) return;
+    const batch = [...queued];
+    queued.clear();
+    await Promise.all(
+      batch.map(async ([name, value]) => {
+        const key = prefix + name;
+        try {
+          if (value === DELETED) await storage.delete(key);
+          else await storage.set(key, value);
+        } catch (error) {
+          console.warn(`[labkit] could not write "${key}"; keeping it in memory`, error);
+        }
+      })
+    );
+  }
+  const applyRemote = (changes) => {
+    const applied = [];
+    for (const [key, value] of changes) {
+      if (!key.startsWith(prefix)) continue;
+      const name = key.slice(prefix.length);
+      if (queued.has(name)) continue;
+      if (value === void 0) {
+        if (!values.has(name)) continue;
+        values.delete(name);
+      } else {
+        values.set(name, value);
+      }
+      applied.push({ name, value, origin: "remote" });
+    }
+    if (applied.length > 0) emit(applied);
+  };
+  const unsubscribe = writable ? storage.subscribe?.(prefix, applyRemote) : void 0;
+  const onPageHide = () => {
+    void flush();
+  };
+  const onVisibility = () => {
+    if (document.visibilityState === "hidden") void flush();
+  };
+  if (typeof window !== "undefined") {
+    window.addEventListener("pagehide", onPageHide);
+    document.addEventListener("visibilitychange", onVisibility);
+  }
+  const cache = {
+    prefix,
+    get writable() {
+      return writable;
+    },
+    has: (name) => values.has(name),
+    get: (name) => values.get(name),
+    entries: (namePrefix = "") => [...values].filter(([name]) => name.startsWith(namePrefix)),
+    set: (name, value) => {
+      values.set(name, value);
+      queued.set(name, value);
+      emit([{ name, value, origin: "local" }]);
+      schedule();
+    },
+    delete: (name) => {
+      if (!values.has(name) && !queued.has(name)) return;
+      values.delete(name);
+      queued.set(name, DELETED);
+      emit([{ name, value: void 0, origin: "local" }]);
+      schedule();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    flush,
+    close: async () => {
+      if (closed) return;
+      await flush();
+      closed = true;
+      unsubscribe?.();
+      if (typeof window !== "undefined") {
+        window.removeEventListener("pagehide", onPageHide);
+        document.removeEventListener("visibilitychange", onVisibility);
+      }
+    },
+    seed: (entries) => {
+      for (const [name, value] of entries) values.set(name, value);
+    },
+    stopWriting: () => {
+      writable = false;
+      queued.clear();
+      if (timer) clearTimeout(timer);
+      timer = null;
+      unsubscribe?.();
+    },
+    applyRemote
+  };
+  return cache;
+}
+async function openRecords(options) {
+  const early = [];
+  const stopEarly = options.storage.subscribe?.(options.prefix, (c) => early.push(...c));
+  let listed;
+  try {
+    listed = await options.storage.list(options.prefix);
+  } catch (error) {
+    stopEarly?.();
+    console.warn(
+      `[labkit] could not read "${options.prefix}"; opening empty and not persisting`,
+      error
+    );
+    return createRecordCache({ ...options, writable: false });
+  }
+  const cache = createRecordCache({
+    ...options,
+    initial: listed.map(([key, value]) => [
+      key.slice(options.prefix.length),
+      value
+    ])
+  });
+  stopEarly?.();
+  cache.applyRemote(early);
+  return cache;
+}
+function useOpenOnce(open) {
+  const entry = useRef(null);
+  if (entry.current === null) {
+    const result = open();
+    entry.current = result instanceof Promise ? { value: null, pending: result, mounts: 0 } : { value: result, pending: null, mounts: 0 };
+  }
+  const [value, setValue] = useState(entry.current.value);
+  useEffect(() => {
+    const e = entry.current;
+    e.mounts += 1;
+    let live = true;
+    void e.pending?.then((opened) => {
+      e.value = opened;
+      if (live) setValue(opened);
+    });
+    return () => {
+      live = false;
+      e.mounts -= 1;
+      queueMicrotask(() => {
+        if (e.mounts > 0) return;
+        if (e.value) void e.value.close();
+        else
+          void e.pending?.then((opened) => {
+            if (e.mounts === 0) void opened.close();
+          });
+      });
+    };
+  }, []);
+  return value;
+}
+function useWarnIgnoredChange(component, props) {
+  const first = useRef(props);
+  const warned = useRef(false);
+  if (process.env.NODE_ENV === "production" || warned.current) return;
+  for (const key of Object.keys(props)) {
+    if (Object.is(first.current[key], props[key])) continue;
+    warned.current = true;
+    console.warn(
+      `[labkit] ${component} reads \`${key}\` once, at mount; a later change is ignored`
+    );
+    return;
+  }
+}
+var PersistenceContext = createContext(null);
+function Persistence({ storageKey, storage, fallback = null, children }) {
+  useWarnIgnoredChange("<Persistence>", { storageKey, storage });
+  const records = useOpenOnce(
+    async () => openRecords({ storage: storage ?? await defaultStorage(), prefix: labPrefix(storageKey) })
+  );
+  if (!records) return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+  return /* @__PURE__ */ jsx(PersistenceContext.Provider, { value: records, children });
+}
+function usePersistedState(name, initial, options = {}) {
+  const records = useContext(PersistenceContext);
+  const trialId = useContext(TrialIdContext);
+  const [local, setLocal] = useState(initial);
+  const record = records && name != null ? valueRecord(options.scope === "lab" ? null : trialId, name) : null;
+  const subscribe = useCallback(
+    (notify) => records && record ? records.subscribe((changes) => {
+      if (changes.some((c) => c.name === record)) notify();
+    }) : () => {
+    },
+    [records, record]
+  );
+  const read = () => records && record && records.has(record) ? records.get(record) : local;
+  const persisted = useSyncExternalStore(subscribe, read, read);
+  const setPersisted = useCallback(
+    (next) => {
+      if (!records || !record) return;
+      const prev = records.has(record) ? records.get(record) : local;
+      records.set(record, typeof next === "function" ? next(prev) : next);
+    },
+    [records, record, local]
+  );
+  return records && record ? [persisted, setPersisted] : [local, setLocal];
+}
+
+export { LAYOUT_RECORD, META_RECORD, Persistence, PersistenceContext, UNDOCK_RECORD, compareTrialOrder, createIndexedDbAdapter, createMemoryAdapter, createRecordCache, decodeUrlHash, defaultStorage, deserializeTrials, documentOfRecords, emptyUndoStack, encodeUrlHash, indexedDbAdapter, labPrefix, labStorageKey, localStorageAdapter, newId, noneAdapter, openRecords, parseRecordName, recordsOfDocument, saveRecord, serializeTrials, sessionStorageAdapter, trialRecord, trialValuesPrefix, urlHashAdapter, useOpenOnce, usePersistedState, useWarnIgnoredChange };
+//# sourceMappingURL=chunk-RWNDDKOH.js.map
+//# sourceMappingURL=chunk-RWNDDKOH.js.map