@omerdlw/base-framework 1.0.0

package/dist/modules/media/index.js

@@ -0,0 +1,728 @@
+"use client";
+import { createContext, useState, useRef, useMemo, useEffect, useId, useCallback, use, useSyncExternalStore } from 'react';
+import 'clsx';
+import 'tailwind-merge';
+import { jsx } from 'react/jsx-runtime';
+import 'next/navigation';
+
+function useRequiredContext(context, hookName, providerName) {
+  const value = use(context);
+  if (value === null) {
+    throw new Error(`${hookName} must be used within ${providerName}`);
+  }
+  return value;
+}
+function useStore(store, selector = (state) => state, isEqual = Object.is) {
+  const cacheRef = useRef({
+    isEqual: null,
+    selected: void 0,
+    selector: null,
+    snapshot: null
+  });
+  const getSelectedSnapshot = useCallback(() => {
+    const snapshot = store.getSnapshot();
+    const cache = cacheRef.current;
+    if (cache.snapshot === snapshot && cache.selector === selector && cache.isEqual === isEqual) {
+      return cache.selected;
+    }
+    const selected = selector(snapshot);
+    if (cache.snapshot !== null && cache.isEqual === isEqual && isEqual(cache.selected, selected)) {
+      cache.snapshot = snapshot;
+      cache.selector = selector;
+      return cache.selected;
+    }
+    cacheRef.current = {
+      isEqual,
+      selected,
+      selector,
+      snapshot
+    };
+    return selected;
+  }, [isEqual, selector, store]);
+  return useSyncExternalStore(
+    store.subscribe,
+    getSelectedSnapshot,
+    getSelectedSnapshot
+  );
+}
+
+// src/utils/object.ts
+function shallowEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || a === null || typeof b !== "object" || b === null) {
+    return false;
+  }
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (!Object.prototype.hasOwnProperty.call(b, key) || !Object.is(
+      a[key],
+      b[key]
+    )) {
+      return false;
+    }
+  }
+  return true;
+}
+function report(scope, error, level = "error") {
+  if (process.env.NODE_ENV === "production" && typeof window !== "undefined") {
+    return;
+  }
+  console[level](`[${scope}]`, error);
+}
+
+// src/utils/store.ts
+function freezeStoreSnapshot(state) {
+  if (process.env.NODE_ENV === "production" || !state || typeof state !== "object") {
+    return state;
+  }
+  const seen = /* @__PURE__ */ new WeakSet();
+  const freeze = (value) => {
+    if (seen.has(value) || Object.isFrozen(value)) return;
+    seen.add(value);
+    const prototype = Object.getPrototypeOf(value);
+    if (Array.isArray(value) || prototype === Object.prototype || prototype === null) {
+      for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor && "value" in descriptor && descriptor.value !== null) {
+          if (typeof descriptor.value === "object") freeze(descriptor.value);
+        }
+      }
+    }
+    Object.freeze(value);
+  };
+  freeze(state);
+  return state;
+}
+function createStore(initialState, { freezeSnapshots = true } = {}) {
+  const listeners = /* @__PURE__ */ new Set();
+  const prepare = freezeSnapshots ? freezeStoreSnapshot : (state) => state;
+  let snapshot = prepare(initialState);
+  const publish = (nextStateOrUpdater) => {
+    const nextState = typeof nextStateOrUpdater === "function" ? nextStateOrUpdater(snapshot) : nextStateOrUpdater;
+    if (Object.is(snapshot, nextState)) return false;
+    snapshot = prepare(nextState);
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch (error) {
+        report("CoreStore subscriber", error, "warn");
+      }
+    }
+    return true;
+  };
+  const setState = (updater) => {
+    if (typeof updater === "function") {
+      return publish(updater);
+    }
+    if (snapshot && typeof snapshot === "object" && updater && typeof updater === "object") {
+      return publish({ ...snapshot, ...updater });
+    }
+    return publish(updater);
+  };
+  return Object.freeze({
+    getSnapshot() {
+      return snapshot;
+    },
+    publish,
+    setState,
+    subscribe(listener) {
+      if (typeof listener !== "function") return () => {
+      };
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  });
+}
+var EventEmitter = class {
+  events = /* @__PURE__ */ new Map();
+  debounceTimers = /* @__PURE__ */ new Map();
+  subscribe(event, callback) {
+    if (typeof event !== "string" || !event || typeof callback !== "function") {
+      return () => {
+      };
+    }
+    const listeners = this.events.get(event) || /* @__PURE__ */ new Set();
+    listeners.add(callback);
+    this.events.set(event, listeners);
+    return () => {
+      listeners.delete(callback);
+      if (listeners.size === 0) this.events.delete(event);
+    };
+  }
+  emit(event, payload) {
+    const listeners = this.events.get(event);
+    if (!listeners || listeners.size === 0) return;
+    const snapshot = Array.from(listeners);
+    for (const callback of snapshot) {
+      try {
+        callback(payload);
+      } catch (error) {
+        report(`Event listener (${String(event)})`, error);
+      }
+    }
+  }
+  emitDebounced(event, payload, waitMs = 100) {
+    const existing = this.debounceTimers.get(event);
+    if (existing) clearTimeout(existing);
+    const timer = setTimeout(() => {
+      this.debounceTimers.delete(event);
+      this.emit(event, payload);
+    }, waitMs);
+    this.debounceTimers.set(event, timer);
+  }
+  cancelDebounced(event) {
+    if (event) {
+      const timer = this.debounceTimers.get(event);
+      if (timer) {
+        clearTimeout(timer);
+        this.debounceTimers.delete(event);
+      }
+    } else {
+      for (const timer of this.debounceTimers.values()) {
+        clearTimeout(timer);
+      }
+      this.debounceTimers.clear();
+    }
+  }
+  unsubscribeAll(event) {
+    this.cancelDebounced(event);
+    if (event) this.events.delete(event);
+    else this.events.clear();
+  }
+  hasListeners(event) {
+    return Boolean(this.events.get(event)?.size);
+  }
+  getListenerCount(event) {
+    return this.events.get(event)?.size || 0;
+  }
+  getAllEvents() {
+    return [...this.events.keys()];
+  }
+};
+var GLOBAL_EVENTS_KEY = /* @__PURE__ */ Symbol.for("__base_framework_global_events__");
+var _global = globalThis;
+_global[GLOBAL_EVENTS_KEY] ?? (_global[GLOBAL_EVENTS_KEY] = new EventEmitter());
+
+// src/modules/media/constants.ts
+var DEFAULT_MEDIA_STATE = Object.freeze({
+  audibleElement: null,
+  element: null,
+  hasMedia: false,
+  isPlaying: false,
+  kind: null,
+  loop: false,
+  sourceId: null
+});
+var MEDIA_SYNC_DRIFT_SECONDS = 0.3;
+var MEDIA_REGISTRY_KEY = "page-media";
+var PAGE_MEDIA_ID = "page";
+
+// src/modules/media/utils.ts
+var noop = () => {
+};
+function newest(sources) {
+  return sources.reduce((a, b) => b.order > a.order ? b : a);
+}
+function resolveMediaSession(sources) {
+  if (sources.length === 0) return null;
+  const ids = new Set(sources.map((source) => source.id));
+  const wantsFollow = (source) => Boolean(source.follow) && source.follow !== source.id && ids.has(source.follow);
+  const rootIds = new Set(
+    sources.filter((source) => !wantsFollow(source)).map((source) => source.id)
+  );
+  const isFollower = (source) => wantsFollow(source) && rootIds.has(source.follow);
+  const transport = newest(sources.filter((source) => !isFollower(source)));
+  const followers = sources.filter((source) => isFollower(source) && source.follow === transport.id).sort((a, b) => a.order - b.order);
+  const audioFollowers = followers.filter((source) => source.kind === "audio");
+  return {
+    audible: audioFollowers.length > 0 ? newest(audioFollowers) : transport,
+    followers,
+    transport
+  };
+}
+function createMediaState(session) {
+  if (!session) return DEFAULT_MEDIA_STATE;
+  const { audible, transport } = session;
+  return {
+    audibleElement: audible.element,
+    element: transport.element,
+    hasMedia: true,
+    isPlaying: transport.isPlaying,
+    kind: transport.kind,
+    loop: transport.loop,
+    sourceId: transport.id
+  };
+}
+function mediaStatesEqual(a, b) {
+  return shallowEqual(a, b);
+}
+function mergeMediaSource(current, input, order) {
+  return {
+    controls: void 0,
+    element: null,
+    follow: null,
+    isPlaying: false,
+    kind: "audio",
+    loop: false,
+    ...current,
+    ...input,
+    order: current?.order ?? order
+  };
+}
+function toggleElement(element) {
+  if (!element) return;
+  if (element.paused || element.ended) {
+    void Promise.resolve(element.play()).catch(noop);
+  } else {
+    element.pause();
+  }
+}
+function safePlay(element) {
+  try {
+    void Promise.resolve(element.play()).catch(noop);
+  } catch {
+  }
+}
+function bindFollowers(transport, followers) {
+  const ownLoops = followers.map((follower) => follower.loop);
+  const align = (hard) => {
+    const time = Number(transport.currentTime) || 0;
+    for (const follower of followers) {
+      follower.loop = false;
+      if (follower.playbackRate !== transport.playbackRate) {
+        follower.playbackRate = transport.playbackRate;
+      }
+      const drift = Math.abs((Number(follower.currentTime) || 0) - time);
+      if (hard || drift > MEDIA_SYNC_DRIFT_SECONDS) follower.currentTime = time;
+    }
+  };
+  const play = () => {
+    align(false);
+    followers.forEach(safePlay);
+  };
+  const pause = () => followers.forEach((follower) => follower.pause());
+  const hardAlign = () => align(true);
+  const softAlign = () => align(false);
+  const listeners = [
+    ["play", play],
+    ["playing", play],
+    ["pause", pause],
+    ["waiting", pause],
+    ["ended", pause],
+    ["seeking", hardAlign],
+    ["seeked", hardAlign],
+    ["ratechange", softAlign],
+    ["timeupdate", softAlign]
+  ];
+  for (const [type, listener] of listeners) {
+    transport.addEventListener(type, listener);
+  }
+  hardAlign();
+  if (!transport.paused && !transport.ended) play();
+  return () => {
+    for (const [type, listener] of listeners) {
+      transport.removeEventListener(type, listener);
+    }
+    followers.forEach((follower, index) => {
+      follower.loop = ownLoops[index];
+    });
+  };
+}
+function sameElements(a, b) {
+  return a.length === b.length && a.every((element, index) => element === b[index]);
+}
+function selectPageMedia(media) {
+  if (!media) return null;
+  if (typeof media === "string") return { src: media };
+  return media.src ? media : null;
+}
+function findDisplacedAudio(entries, session, newId) {
+  if (!session || session.transport.id !== newId) return [];
+  const followerIds = new Set(session.followers.map((entry) => entry.id));
+  return entries.filter(
+    (entry) => entry.id !== newId && !followerIds.has(entry.id) && entry.kind === "audio" && entry.element !== null && !entry.element.paused
+  );
+}
+function getOrCreateGlobalContext(name, defaultValue) {
+  const sym = /* @__PURE__ */ Symbol.for(`@omerdlw/base-framework/context/${name}`);
+  const store = globalThis;
+  if (!store[sym]) {
+    store[sym] = createContext(defaultValue);
+  }
+  return store[sym];
+}
+var MediaContext = getOrCreateGlobalContext(
+  "MediaContext",
+  null
+);
+function MediaProvider({ children }) {
+  const [store] = useState(
+    () => createStore(DEFAULT_MEDIA_STATE, { freezeSnapshots: false })
+  );
+  const sourcesRef = useRef(/* @__PURE__ */ new Map());
+  const sessionRef = useRef(null);
+  const orderRef = useRef(0);
+  const bindingRef = useRef(null);
+  const actions = useMemo(() => {
+    const unbind = () => {
+      bindingRef.current?.cleanup();
+      bindingRef.current = null;
+    };
+    const rebind = (session) => {
+      const transport = session?.transport.element ?? null;
+      const followers = (session?.followers ?? []).map(
+        (source) => source.element
+      );
+      const current = bindingRef.current;
+      if (current && current.transport === transport && sameElements(current.followers, followers)) {
+        return;
+      }
+      unbind();
+      const live = followers.filter(
+        (element) => element !== null
+      );
+      if (!transport || live.length === 0) return;
+      bindingRef.current = {
+        cleanup: bindFollowers(transport, live),
+        followers,
+        transport
+      };
+    };
+    const commit = () => {
+      const session = resolveMediaSession([...sourcesRef.current.values()]);
+      sessionRef.current = session;
+      rebind(session);
+      const next = createMediaState(session);
+      store.publish((prev) => mediaStatesEqual(prev, next) ? prev : next);
+    };
+    const patch = (id, changes) => {
+      const current = sourcesRef.current.get(id);
+      if (!current) return;
+      sourcesRef.current.set(id, { ...current, ...changes });
+      commit();
+    };
+    return {
+      removeSource: (id) => {
+        if (sourcesRef.current.delete(id)) commit();
+      },
+      setMuted: (muted) => {
+        const audible = sessionRef.current?.audible;
+        if (!audible) return;
+        if (audible.controls?.setMuted) audible.controls.setMuted(muted);
+        else if (audible.element) audible.element.muted = muted;
+      },
+      toggle: () => {
+        const transport = sessionRef.current?.transport;
+        if (!transport) return;
+        if (transport.controls?.toggle) transport.controls.toggle();
+        else toggleElement(transport.element);
+      },
+      toggleLoop: () => {
+        const transport = sessionRef.current?.transport;
+        if (!transport) return;
+        if (transport.controls?.toggleLoop) {
+          transport.controls.toggleLoop();
+          return;
+        }
+        const loop = !transport.loop;
+        if (transport.element) transport.element.loop = loop;
+        patch(transport.id, { loop });
+      },
+      upsertSource: (input) => {
+        const current = sourcesRef.current.get(input.id);
+        if (!current) orderRef.current += 1;
+        sourcesRef.current.set(
+          input.id,
+          mergeMediaSource(current, input, orderRef.current)
+        );
+        commit();
+        if (!current) {
+          findDisplacedAudio(
+            [...sourcesRef.current.values()],
+            sessionRef.current,
+            input.id
+          ).forEach((entry) => entry.element?.pause());
+        }
+      }
+    };
+  }, [store]);
+  useEffect(
+    () => () => {
+      bindingRef.current?.cleanup();
+      bindingRef.current = null;
+    },
+    []
+  );
+  const value = useMemo(
+    () => ({ actions, store }),
+    [actions, store]
+  );
+  return /* @__PURE__ */ jsx(MediaContext, { value, children });
+}
+function useMediaState() {
+  const { store } = useRequiredContext(
+    MediaContext,
+    "useMediaState",
+    "MediaProvider"
+  );
+  return useStore(store);
+}
+function useMediaActions() {
+  return useRequiredContext(MediaContext, "useMediaActions", "MediaProvider").actions;
+}
+function useMedia(options) {
+  const generatedId = useId();
+  const id = options.id ?? `media-${generatedId}`;
+  const { removeSource, upsertSource } = useMediaActions();
+  const audioRef = useRef(null);
+  const optionsRef = useRef(options);
+  const { src, enabled = true } = options;
+  const isEnabled = enabled && Boolean(src);
+  useEffect(() => {
+    optionsRef.current = options;
+  });
+  useEffect(() => {
+    if (!isEnabled || !src) return void 0;
+    const audio = new Audio();
+    audio.preload = "auto";
+    audio.src = src;
+    audioRef.current = audio;
+    const initial = optionsRef.current;
+    audio.loop = Boolean(initial.loop);
+    audio.muted = Boolean(initial.muted);
+    if (typeof initial.volume === "number") {
+      audio.volume = Math.min(1, Math.max(0, initial.volume));
+    }
+    upsertSource({
+      element: audio,
+      follow: initial.follow ?? null,
+      id,
+      isPlaying: false,
+      kind: "audio",
+      loop: audio.loop
+    });
+    const syncPlaying = () => upsertSource({ id, isPlaying: !audio.paused && !audio.ended });
+    const events = ["play", "playing", "pause", "ended"];
+    events.forEach((type) => audio.addEventListener(type, syncPlaying));
+    if (!initial.follow && initial.autoplay !== false) {
+      void Promise.resolve(audio.play()).catch(() => {
+      });
+    }
+    return () => {
+      events.forEach((type) => audio.removeEventListener(type, syncPlaying));
+      audio.pause();
+      audio.removeAttribute("src");
+      audio.load();
+      audioRef.current = null;
+      removeSource(id);
+    };
+  }, [id, isEnabled, removeSource, src, upsertSource]);
+  const { follow = null, loop, muted, volume } = options;
+  useEffect(() => {
+    const audio = audioRef.current;
+    if (!audio) return;
+    if (loop !== void 0 && !follow) audio.loop = loop;
+    if (muted !== void 0) audio.muted = muted;
+    if (volume !== void 0) audio.volume = Math.min(1, Math.max(0, volume));
+    upsertSource({ follow, id, ...follow ? {} : { loop: audio.loop } });
+  }, [follow, id, isEnabled, loop, muted, src, upsertSource, volume]);
+  const play = useCallback(() => {
+    const audio = audioRef.current;
+    if (audio) void Promise.resolve(audio.play()).catch(() => {
+    });
+  }, []);
+  const pause = useCallback(() => audioRef.current?.pause(), []);
+  const toggle = useCallback(() => toggleElement(audioRef.current), []);
+  return useMemo(
+    () => ({ id, pause, play, toggle }),
+    [id, pause, play, toggle]
+  );
+}
+
+// src/kernel/constants.ts
+var REGISTRY_SOURCES = Object.freeze({
+  STATIC: "static",
+  DYNAMIC: "dynamic",
+  USER: "user"
+});
+var REGISTRY_LIFECYCLES = Object.freeze({
+  IMMEDIATE: "immediate",
+  GRACEFUL: "graceful",
+  PERSISTENT: "persistent",
+  ROUTE: "route"
+});
+var REGISTRY_METADATA_KEYS = Object.freeze([
+  "cleanup",
+  "cleanupDelayMs",
+  "instanceId",
+  "lifecycle",
+  "priority",
+  "source",
+  "scope",
+  "validation"
+]);
+Object.freeze({
+  [REGISTRY_SOURCES.STATIC]: 100,
+  [REGISTRY_SOURCES.DYNAMIC]: 200,
+  [REGISTRY_SOURCES.USER]: 300
+});
+Object.freeze({
+  [REGISTRY_SOURCES.STATIC]: 10,
+  [REGISTRY_SOURCES.DYNAMIC]: 20,
+  [REGISTRY_SOURCES.USER]: 30
+});
+new Set(
+  Object.values(REGISTRY_LIFECYCLES)
+);
+new Set(
+  REGISTRY_METADATA_KEYS
+);
+var REGISTRY_SCOPE_KINDS = Object.freeze({
+  APP: "app",
+  SESSION: "session",
+  ROUTE: "route",
+  INSTANCE: "instance",
+  WORKSPACE: "workspace"
+});
+REGISTRY_SCOPE_KINDS.APP;
+function createNoopHandle(status = "rejected", reason = "unknown") {
+  const handle = Object.assign(() => false, {
+    active: false,
+    dispose: () => false,
+    instanceId: null,
+    key: "",
+    priority: 0,
+    reason,
+    source: "",
+    status,
+    type: "",
+    update: () => handle,
+    updatedAt: 0,
+    validation: "warn"
+  });
+  return handle;
+}
+createNoopHandle();
+var RegistryContext = getOrCreateGlobalContext(
+  "RegistryContext",
+  null
+);
+function useRegistrySubscription() {
+  return useRequiredContext(
+    RegistryContext,
+    "useRegistrySubscription",
+    "RegistryProvider"
+  ).subscription;
+}
+function useRegistryValue(type, key) {
+  const { getSnapshot, subscribe } = useRegistrySubscription();
+  const subscribeToKey = useCallback(
+    (listener) => subscribe(type, key, listener),
+    [key, subscribe, type]
+  );
+  const getValue = useCallback(
+    () => getSnapshot(type, key),
+    [getSnapshot, key, type]
+  );
+  return useSyncExternalStore(subscribeToKey, getValue, getValue);
+}
+getOrCreateGlobalContext("ModuleHostContext", null);
+function createPageControllerStore() {
+  const listeners = /* @__PURE__ */ new Set();
+  let stack = [];
+  const notify = () => {
+    listeners.forEach((listener) => {
+      try {
+        listener();
+      } catch (error) {
+        report("Page controller listener", error);
+      }
+    });
+  };
+  return {
+    getSnapshot() {
+      const top = stack[stack.length - 1];
+      return top?.controllerRef?.current || null;
+    },
+    notify,
+    register(id, controllerRef) {
+      stack = stack.filter((item) => item.id !== id);
+      stack.push({ controllerRef, id });
+      notify();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    unregister(id) {
+      stack = stack.filter((item) => item.id !== id);
+      notify();
+    }
+  };
+}
+var fallbackStandaloneStore = createPageControllerStore();
+getOrCreateGlobalContext(
+  "PageControllerContext",
+  null
+);
+getOrCreateGlobalContext(
+  "PageControllerStoreContext",
+  fallbackStandaloneStore
+);
+function defineModule(coreModule) {
+  return Object.freeze({ ...coreModule });
+}
+createStore(void 0);
+
+// src/modules/media/overlay.tsx
+function MediaSource(props) {
+  useMedia(props);
+  return null;
+}
+function MediaOverlay() {
+  const page = useRegistryValue(
+    "media",
+    MEDIA_REGISTRY_KEY
+  );
+  useMedia({ ...page, id: PAGE_MEDIA_ID, src: page?.src });
+  return null;
+}
+
+// src/modules/media/module.tsx
+function useMediaPage(_slice, page) {
+  const actions = useMediaActions();
+  return useMemo(
+    () => ({
+      ...actions,
+      set: (media) => page.set({ media })
+    }),
+    [actions, page]
+  );
+}
+var mediaModule = defineModule({
+  id: "media",
+  context: MediaContext,
+  Provider: MediaProvider,
+  Overlay: MediaOverlay,
+  registry: {
+    cleanupDelayMs: 600,
+    keyPolicy: "singleton",
+    lifecycle: "immediate",
+    singletonKey: MEDIA_REGISTRY_KEY
+  },
+  page: {
+    select: (config) => selectPageMedia(config.media),
+    entries: (slice) => [
+      { key: MEDIA_REGISTRY_KEY, value: slice }
+    ],
+    use: useMediaPage
+  }
+});
+
+export { DEFAULT_MEDIA_STATE, MEDIA_REGISTRY_KEY, MEDIA_SYNC_DRIFT_SECONDS, MediaContext, MediaOverlay, MediaProvider, MediaSource, PAGE_MEDIA_ID, bindFollowers, createMediaState, mediaModule, resolveMediaSession, selectPageMedia, useMedia, useMediaActions, useMediaState };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map