@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/sync/SyncChannel.d.ts

@@ -0,0 +1,65 @@
+import { Guid } from '../identifiers';
+import { StorageBroker } from '../storage';
+/**
+ * Wraps one posted payload with the metadata the dispatch path needs — who sent it, in what order, and when.
+ * Written to the wire by both real transports so the receiving rules are identical across them.
+ */
+export interface SyncEnvelope<TMessage> {
+    /** Identifies the tab that posted the message; the receiver drops an envelope whose sender is itself. */
+    readonly sender: Guid;
+    /** Counts posts from this sender, starting at 0 — makes each fallback write unique and each delivery de-dupable. */
+    readonly seq: number;
+    /** Records the post time in epoch milliseconds, as read from the channel's clock. */
+    readonly timestamp: number;
+    /** Carries the caller's payload, unvalidated at runtime — see this file's header. */
+    readonly message: TMessage;
+}
+/**
+ * Receives a message from another tab. The payload comes first because it is what nearly every caller wants;
+ * the envelope follows for the rare consumer that needs the sender or the ordering metadata.
+ */
+export type SyncListener<TMessage> = (message: TMessage, envelope: SyncEnvelope<TMessage>) => void;
+/**
+ * Names the delivery mechanisms a channel can sit on. `auto` picks the best one available and is the default;
+ * the explicit values exist for tests and for a consumer that deliberately wants the weaker path.
+ */
+export type SyncTransport = 'auto' | 'broadcast' | 'storage' | 'inert';
+/** Names the transport a channel actually resolved to — `auto` is a request, never an answer. */
+export type ResolvedSyncTransport = Exclude<SyncTransport, 'auto'>;
+/** Defines the options that tune how a sync channel finds its peers. */
+export interface SyncChannelOptions {
+    /**
+     * Selects the delivery mechanism; defaults to `auto` (`broadcast` → `storage` → `inert`). An explicit choice
+     * that is unavailable in this environment degrades to the next one down rather than throwing.
+     */
+    readonly transport?: SyncTransport;
+    /** Supplies the persistence seam the `storage` fallback writes through; defaults to `localStorageStorageBroker`. */
+    readonly broker?: StorageBroker;
+    /** Prefixes the `storage` fallback's key, isolating one app's channels from another's; defaults to `wow-two.sync`. */
+    readonly keyPrefix?: string;
+    /** Pins this endpoint's tab id instead of minting one — for deterministic tie-breaks in tests. */
+    readonly id?: Guid;
+    /** Supplies the clock stamped onto each envelope; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Represents one tab's endpoint on a named cross-tab channel. Every method is total: posting on a closed
+ * channel, subscribing after close, or running with no browser APIs at all are ordinary states that answer
+ * quietly instead of throwing.
+ */
+export interface SyncChannel<TMessage> {
+    /** Names the channel; every endpoint sharing this name on the origin is a peer. */
+    readonly name: string;
+    /** Identifies this endpoint (this tab) — stable for the channel's lifetime. */
+    readonly id: Guid;
+    /** Reports the mechanism this endpoint resolved to; `inert` means no peer will ever be reached. */
+    readonly transport: ResolvedSyncTransport;
+    /** Reports whether `close` has run — a closed channel neither sends nor delivers. */
+    readonly closed: boolean;
+    /** Sends `message` to every OTHER endpoint on the channel; never delivers to this one, and never throws. */
+    post(message: TMessage): void;
+    /** Registers `listener` for messages from other tabs; returns an idempotent disposer that unsubscribes it. */
+    subscribe(listener: SyncListener<TMessage>): () => void;
+    /** Detaches every listener and releases the underlying transport; idempotent. */
+    close(): void;
+}

package/dist/foundation/sync/UseBroadcastState.d.ts

@@ -0,0 +1,31 @@
+import { MaybeRefOrGetter, WritableComputedRef } from 'vue';
+import { SyncChannelOptions } from './SyncChannel';
+/** A setter accepting a next value or an updater fn. */
+export type SetBroadcastState<T> = (next: T | ((previous: T) => T)) => void;
+/** The mirrored-state handle — a writable value plus the explicit setter it delegates to. */
+export interface BroadcastStateControls<T> {
+    /**
+     * The mirrored value. Writable: `value.value = next` runs the same path as `setValue(next)`, so it drops
+     * straight into `v-model`. The updater-fn form is `setValue`'s alone — a `v-model` write is always a value.
+     */
+    readonly value: WritableComputedRef<T>;
+    /** Sets the next value locally and announces it to every peer. Accepts a value or an updater fn. */
+    readonly setValue: SetBroadcastState<T>;
+}
+/**
+ * Manages a piece of reactive state mirrored live across every open tab, without persisting it anywhere.
+ *
+ * Setting the value here sets it in every other tab holding the same `key`; a tab that opens later asks its
+ * peers for the current value on mount. Nothing is written to storage, so the value vanishes when the last tab
+ * closes — read this file's header for the split with `usePersistentState`, which is the durable counterpart.
+ *
+ * SSR-safe: no channel is opened on the server, so the value is simply `initial` and the setter is local.
+ *
+ * @typeParam T - The mirrored value; must survive the transport (JSON-only on the `storage` fallback).
+ * @param key - Identifies the shared value; tabs sharing it on this origin mirror each other. A ref or getter
+ *   re-opens the channel on change.
+ * @param initial - The value before any peer answers, and the value when no other tab is open. Read once.
+ * @param options - Channel configuration, read once when the channel opens.
+ * @returns The writable value and its setter.
+ */
+export declare function useBroadcastState<T>(key: MaybeRefOrGetter<string>, initial: T, options?: SyncChannelOptions): BroadcastStateControls<T>;

package/dist/foundation/sync/UseLeaderElection.d.ts

@@ -0,0 +1,25 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { Guid } from '../identifiers';
+import { LeaderElectionOptions } from './LeaderElection';
+/** Reports this tab's standing in an election, as reactive state. */
+export interface LeaderElectionState {
+    /** Reports whether this tab currently holds leadership; false before mount and under SSR. */
+    readonly isLeader: Readonly<ShallowRef<boolean>>;
+    /** Identifies this participant, or null before the election is joined (pre-mount, SSR). */
+    readonly id: Readonly<ShallowRef<Guid | null>>;
+    /** Surrenders leadership deliberately, handing over to a peer; a no-op when not leading. */
+    readonly release: () => void;
+}
+/**
+ * Joins the named leader election for the lifetime of the scope, updating when this tab gains or loses
+ * leadership.
+ *
+ * Exactly one participating tab leads at a time; a tab that dies is superseded once its lease expires. Use it to
+ * elect the single tab that opens the socket, runs the poll, or shows the notification.
+ *
+ * @param name - Election name; tabs sharing it on this origin compete for one leadership. A ref or getter
+ *   re-joins on change.
+ * @param options - Timing and channel configuration, read once when the election is joined.
+ * @returns The current standing plus `release`.
+ */
+export declare function useLeaderElection(name: MaybeRefOrGetter<string>, options?: LeaderElectionOptions): LeaderElectionState;

package/dist/foundation/sync/UseSyncChannel.d.ts

@@ -0,0 +1,16 @@
+import { MaybeRefOrGetter } from 'vue';
+import { SyncChannelOptions, SyncListener } from './SyncChannel';
+/**
+ * Opens a cross-tab channel for the lifetime of the scope and subscribes `onMessage` to it.
+ *
+ * The returned `post` sends to every OTHER tab on the channel, never back into this one. Before mount and after
+ * disposal — and under SSR, where no channel is ever opened — `post` is a silent no-op, so a handler firing at
+ * an awkward moment needs no guard.
+ *
+ * @typeParam TMessage - The payload shape agreed between tabs.
+ * @param name - Channel name; every tab using it on this origin is a peer. A ref or getter re-opens on change.
+ * @param onMessage - Invoked for each message from another tab.
+ * @param options - Transport and storage configuration, read once when the channel opens.
+ * @returns The `post` function.
+ */
+export declare function useSyncChannel<TMessage>(name: MaybeRefOrGetter<string>, onMessage?: SyncListener<TMessage>, options?: SyncChannelOptions): (message: TMessage) => void;

package/dist/foundation/sync/index.d.ts

@@ -0,0 +1,7 @@
+export type { ResolvedSyncTransport, SyncChannel, SyncChannelOptions, SyncEnvelope, SyncListener, SyncTransport, } from './SyncChannel';
+export { createSyncChannel } from './CreateSyncChannel';
+export { memorySyncHub, type MemorySyncHub } from './MemorySyncHub';
+export { createLeaderElection, type LeaderElection, type LeaderElectionOptions, type LeaderRole, type LeaderSignal, } from './LeaderElection';
+export { useSyncChannel } from './UseSyncChannel';
+export { useLeaderElection, type LeaderElectionState } from './UseLeaderElection';
+export { useBroadcastState, type SetBroadcastState, type BroadcastStateControls } from './UseBroadcastState';

package/dist/foundation/sync/index.js

@@ -0,0 +1,484 @@
+import { Guid } from "../identifiers/index.js";
+import { l as localStorageStorageBroker } from "../../chunks/StorageBroker-COC81ZGB.js";
+import { onMounted, watch, toValue, onScopeDispose, shallowRef, computed } from "vue";
+const DEFAULT_KEY_PREFIX = "wow-two.sync";
+function isEnvelope(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return typeof candidate.sender === "string" && typeof candidate.seq === "number" && typeof candidate.timestamp === "number" && "message" in candidate;
+}
+function readEventKey(event) {
+  const candidate = event.key;
+  return typeof candidate === "string" ? candidate : null;
+}
+function resolveWindow() {
+  if (typeof window === "undefined") return null;
+  try {
+    return typeof window.addEventListener === "function" ? window : null;
+  } catch {
+    return null;
+  }
+}
+function bindBroadcast(name, onEnvelope) {
+  if (typeof BroadcastChannel === "undefined") return null;
+  let channel;
+  try {
+    channel = new BroadcastChannel(name);
+  } catch {
+    return null;
+  }
+  const onMessage = (event) => onEnvelope(event.data);
+  channel.addEventListener("message", onMessage);
+  return {
+    kind: "broadcast",
+    send(envelope) {
+      try {
+        channel.postMessage(envelope);
+      } catch {
+      }
+    },
+    dispose() {
+      try {
+        channel.removeEventListener("message", onMessage);
+        channel.close();
+      } catch {
+      }
+    }
+  };
+}
+function bindStorage(key, broker, onEnvelope) {
+  const view = resolveWindow();
+  if (view === null) return null;
+  const onStorage = (event) => {
+    if (readEventKey(event) !== key) return;
+    onEnvelope(broker.read(key));
+  };
+  view.addEventListener("storage", onStorage);
+  return {
+    kind: "storage",
+    send(envelope) {
+      broker.write(key, envelope);
+    },
+    dispose() {
+      view.removeEventListener("storage", onStorage);
+    }
+  };
+}
+const inertBinding = {
+  kind: "inert",
+  send() {
+  },
+  dispose() {
+  }
+};
+function bind(requested, name, key, broker, onEnvelope) {
+  if (requested === "inert") return inertBinding;
+  if (requested === "storage") return bindStorage(key, broker, onEnvelope) ?? inertBinding;
+  if (requested === "broadcast") return bindBroadcast(name, onEnvelope) ?? inertBinding;
+  return bindBroadcast(name, onEnvelope) ?? bindStorage(key, broker, onEnvelope) ?? inertBinding;
+}
+function createSyncChannel(name, options) {
+  const id = options?.id ?? Guid.createV7();
+  const now = options?.now ?? Date.now;
+  const broker = options?.broker ?? localStorageStorageBroker;
+  const key = `${options?.keyPrefix ?? DEFAULT_KEY_PREFIX}.${name}`;
+  const listeners = /* @__PURE__ */ new Set();
+  let seq = 0;
+  let closed = false;
+  let lastStamp = null;
+  function deliver(raw) {
+    if (closed) return;
+    if (!isEnvelope(raw)) return;
+    if (raw.sender === id) return;
+    const stamp = `${raw.sender}:${raw.seq}`;
+    if (stamp === lastStamp) return;
+    lastStamp = stamp;
+    const envelope = raw;
+    for (const listener of [...listeners]) {
+      try {
+        listener(envelope.message, envelope);
+      } catch {
+      }
+    }
+  }
+  const binding = bind(options?.transport ?? "auto", name, key, broker, deliver);
+  return {
+    name,
+    id,
+    transport: binding.kind,
+    get closed() {
+      return closed;
+    },
+    post(message) {
+      if (closed) return;
+      const envelope = { sender: id, seq: seq++, timestamp: now(), message };
+      binding.send(envelope);
+    },
+    subscribe(listener) {
+      if (closed) return () => void 0;
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      listeners.clear();
+      binding.dispose();
+    }
+  };
+}
+function memorySyncHub() {
+  const endpoints = /* @__PURE__ */ new Set();
+  return {
+    channel(name, id) {
+      const endpointId = id ?? Guid.createV7();
+      const listeners = /* @__PURE__ */ new Set();
+      let seq = 0;
+      let closed = false;
+      function receive(envelope) {
+        if (closed) return;
+        const typed = envelope;
+        for (const listener of [...listeners]) {
+          try {
+            listener(typed.message, typed);
+          } catch {
+          }
+        }
+      }
+      const endpoint = {
+        id: endpointId,
+        name,
+        receive,
+        isClosed: () => closed
+      };
+      endpoints.add(endpoint);
+      return {
+        name,
+        id: endpointId,
+        transport: "broadcast",
+        get closed() {
+          return closed;
+        },
+        post(message) {
+          if (closed) return;
+          const envelope = {
+            sender: endpointId,
+            seq: seq++,
+            timestamp: Date.now(),
+            message
+          };
+          for (const peer of [...endpoints]) {
+            if (peer === endpoint) continue;
+            if (peer.name !== name) continue;
+            if (peer.isClosed()) continue;
+            peer.receive(envelope);
+          }
+        },
+        subscribe(listener) {
+          if (closed) return () => void 0;
+          listeners.add(listener);
+          return () => {
+            listeners.delete(listener);
+          };
+        },
+        close() {
+          if (closed) return;
+          closed = true;
+          listeners.clear();
+          endpoints.delete(endpoint);
+        }
+      };
+    },
+    get openCount() {
+      let open = 0;
+      for (const endpoint of endpoints) if (!endpoint.isClosed()) open += 1;
+      return open;
+    },
+    reset() {
+      endpoints.clear();
+    }
+  };
+}
+const CHANNEL_PREFIX$1 = "leader.";
+const DEFAULT_HEARTBEAT_INTERVAL = 1e3;
+const DEFAULT_TIMEOUT = 3500;
+const DEFAULT_CLAIM_WINDOW = 150;
+function createLeaderElection(name, options) {
+  const heartbeatInterval = options?.heartbeatInterval ?? DEFAULT_HEARTBEAT_INTERVAL;
+  const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+  const claimWindow = options?.claimWindow ?? DEFAULT_CLAIM_WINDOW;
+  const ownsChannel = options?.channel === void 0;
+  const channel = options?.channel ?? createSyncChannel(`${CHANNEL_PREFIX$1}${name}`, options?.channelOptions);
+  const id = channel.id;
+  const becomeListeners = /* @__PURE__ */ new Set();
+  const loseListeners = /* @__PURE__ */ new Set();
+  let role = "follower";
+  let closed = false;
+  let claimTimer;
+  let watchTimer;
+  let heartbeatTimer;
+  let lowestRival = null;
+  let leaderSeenDuringClaim = false;
+  function safeInvoke(listener) {
+    try {
+      listener();
+    } catch {
+    }
+  }
+  function emit(listeners) {
+    for (const listener of [...listeners]) safeInvoke(listener);
+  }
+  function clearWatch() {
+    if (watchTimer !== void 0) clearTimeout(watchTimer);
+    watchTimer = void 0;
+  }
+  function clearClaim() {
+    if (claimTimer !== void 0) clearTimeout(claimTimer);
+    claimTimer = void 0;
+  }
+  function clearHeartbeat() {
+    if (heartbeatTimer !== void 0) clearInterval(heartbeatTimer);
+    heartbeatTimer = void 0;
+  }
+  function armWatch() {
+    clearWatch();
+    if (closed) return;
+    watchTimer = setTimeout(beginClaim, timeout);
+  }
+  function toFollower() {
+    role = "follower";
+    armWatch();
+  }
+  function beginClaim() {
+    if (closed || role === "leader") return;
+    clearWatch();
+    clearClaim();
+    role = "candidate";
+    lowestRival = null;
+    leaderSeenDuringClaim = false;
+    channel.post({ kind: "claim", id });
+    claimTimer = setTimeout(resolveClaim, claimWindow);
+  }
+  function resolveClaim() {
+    claimTimer = void 0;
+    if (closed || role !== "candidate") return;
+    if (leaderSeenDuringClaim) {
+      toFollower();
+      return;
+    }
+    if (lowestRival !== null && Guid.compare(lowestRival, id) < 0) {
+      toFollower();
+      return;
+    }
+    becomeLeader();
+  }
+  function becomeLeader() {
+    if (closed) return;
+    role = "leader";
+    clearWatch();
+    clearClaim();
+    channel.post({ kind: "heartbeat", id });
+    heartbeatTimer = setInterval(() => channel.post({ kind: "heartbeat", id }), heartbeatInterval);
+    emit(becomeListeners);
+  }
+  function stepDown() {
+    clearHeartbeat();
+    role = "follower";
+    armWatch();
+    emit(loseListeners);
+  }
+  channel.subscribe((signal) => {
+    if (closed) return;
+    if (typeof signal !== "object" || signal === null) return;
+    switch (signal.kind) {
+      case "heartbeat": {
+        if (role === "leader") {
+          if (Guid.compare(signal.id, id) < 0) stepDown();
+          else channel.post({ kind: "heartbeat", id });
+          return;
+        }
+        leaderSeenDuringClaim = true;
+        if (role === "candidate") {
+          clearClaim();
+          role = "follower";
+        }
+        armWatch();
+        return;
+      }
+      case "claim": {
+        if (role === "leader") {
+          channel.post({ kind: "heartbeat", id });
+          return;
+        }
+        if (role === "candidate" && (lowestRival === null || Guid.compare(signal.id, lowestRival) < 0)) {
+          lowestRival = signal.id;
+        }
+        return;
+      }
+      case "resign": {
+        if (role !== "leader") beginClaim();
+        return;
+      }
+    }
+  });
+  beginClaim();
+  return {
+    id,
+    get isLeader() {
+      return role === "leader";
+    },
+    get role() {
+      return role;
+    },
+    onBecomeLeader(listener) {
+      if (closed) return () => void 0;
+      becomeListeners.add(listener);
+      if (role === "leader") safeInvoke(listener);
+      return () => {
+        becomeListeners.delete(listener);
+      };
+    },
+    onLoseLeader(listener) {
+      if (closed) return () => void 0;
+      loseListeners.add(listener);
+      return () => {
+        loseListeners.delete(listener);
+      };
+    },
+    release() {
+      if (closed) return;
+      if (role === "leader") {
+        stepDown();
+        channel.post({ kind: "resign", id });
+        return;
+      }
+      clearClaim();
+      toFollower();
+    },
+    close() {
+      if (closed) return;
+      if (role === "leader") channel.post({ kind: "resign", id });
+      closed = true;
+      role = "follower";
+      clearWatch();
+      clearClaim();
+      clearHeartbeat();
+      becomeListeners.clear();
+      loseListeners.clear();
+      if (ownsChannel) channel.close();
+    }
+  };
+}
+function useSyncChannel(name, onMessage, options) {
+  let channel = null;
+  let unsubscribe;
+  function teardown() {
+    unsubscribe?.();
+    unsubscribe = void 0;
+    channel?.close();
+    channel = null;
+  }
+  function open() {
+    teardown();
+    const next = createSyncChannel(toValue(name), options);
+    channel = next;
+    unsubscribe = next.subscribe((message, envelope) => {
+      onMessage?.(message, envelope);
+    });
+  }
+  onMounted(open);
+  watch(() => toValue(name), open);
+  onScopeDispose(teardown);
+  return (message) => {
+    channel?.post(message);
+  };
+}
+function useLeaderElection(name, options) {
+  const isLeader = shallowRef(false);
+  const id = shallowRef(null);
+  let election = null;
+  let offBecome;
+  let offLose;
+  function teardown() {
+    offBecome?.();
+    offLose?.();
+    offBecome = void 0;
+    offLose = void 0;
+    election?.close();
+    election = null;
+    isLeader.value = false;
+    id.value = null;
+  }
+  function join() {
+    teardown();
+    const next = createLeaderElection(toValue(name), options);
+    election = next;
+    isLeader.value = next.isLeader;
+    id.value = next.id;
+    offBecome = next.onBecomeLeader(() => {
+      isLeader.value = true;
+      id.value = next.id;
+    });
+    offLose = next.onLoseLeader(() => {
+      isLeader.value = false;
+      id.value = next.id;
+    });
+  }
+  onMounted(join);
+  watch(() => toValue(name), join);
+  onScopeDispose(teardown);
+  const release = () => {
+    election?.release();
+  };
+  return { isLeader, id, release };
+}
+const CHANNEL_PREFIX = "broadcast-state.";
+function useBroadcastState(key, initial, options) {
+  const current = shallowRef(initial);
+  let channel = null;
+  let unsubscribe;
+  function teardown() {
+    unsubscribe?.();
+    unsubscribe = void 0;
+    channel?.close();
+    channel = null;
+  }
+  function open() {
+    teardown();
+    const next = createSyncChannel(`${CHANNEL_PREFIX}${toValue(key)}`, options);
+    channel = next;
+    unsubscribe = next.subscribe((signal) => {
+      if (typeof signal !== "object" || signal === null) return;
+      if (signal.kind === "announce") {
+        current.value = signal.value;
+        return;
+      }
+      next.post({ kind: "announce", value: current.value });
+    });
+    next.post({ kind: "request" });
+  }
+  onMounted(open);
+  watch(() => toValue(key), open);
+  onScopeDispose(teardown);
+  const setValue = (next) => {
+    const resolved = typeof next === "function" ? next(current.value) : next;
+    current.value = resolved;
+    channel?.post({ kind: "announce", value: resolved });
+  };
+  const value = computed({
+    get: () => current.value,
+    set: setValue
+  });
+  return { value, setValue };
+}
+export {
+  createLeaderElection,
+  createSyncChannel,
+  memorySyncHub,
+  useBroadcastState,
+  useLeaderElection,
+  useSyncChannel
+};
+//# sourceMappingURL=index.js.map