@urk/adapters 0.1.3 → 0.1.4

package/src/audio.ts

@@ -1,458 +0,0 @@
-/**
- * Company: EonHive Inc.
- * Title: Audio Adapter
- * Purpose: Provide a small browser-native audio transport capability for URK.
- * Author: Stan Nesi
- * Created: 2026-04-23
- * Updated: 2026-04-23
- * Notes: Vibe coded with Codex.
- */
-
-import type { AdapterRegistration } from '@urk/core';
-
-export interface AudioTrackDefinition {
-  id: string;
-  src: string;
-  label: string;
-  loop?: boolean;
-  volume?: number;
-}
-
-export type AudioPlaybackStatus = 'idle' | 'loading' | 'ready' | 'playing' | 'paused' | 'error';
-
-export interface AudioTransportSnapshot {
-  activeTrackId: string | null;
-  status: AudioPlaybackStatus;
-  muted: boolean;
-  volume: number;
-  loadedTrackIds: string[];
-  errorMessage?: string;
-}
-
-export type AudioListener = (snapshot: AudioTransportSnapshot) => void;
-
-export interface AudioAdapterApi {
-  registerTrack(track: AudioTrackDefinition): void;
-  preload(trackId: string): Promise<void>;
-  play(trackId?: string): Promise<void>;
-  pause(): void;
-  stop(): void;
-  setMuted(next: boolean): void;
-  setVolume(next: number): void;
-  getSnapshot(): AudioTransportSnapshot;
-  subscribe(listener: AudioListener): () => void;
-}
-
-type RegisteredTrack = {
-  definition: AudioTrackDefinition;
-  element: HTMLAudioElement;
-  onEnded: () => void;
-  onError: () => void;
-};
-
-function clampVolume(value: number): number {
-  return Math.max(0, Math.min(value, 1));
-}
-
-function cloneSnapshot(snapshot: AudioTransportSnapshot): AudioTransportSnapshot {
-  return {
-    ...snapshot,
-    loadedTrackIds: [...snapshot.loadedTrackIds],
-  };
-}
-
-function createEmptySnapshot(): AudioTransportSnapshot {
-  return {
-    activeTrackId: null,
-    status: 'idle',
-    muted: false,
-    volume: 1,
-    loadedTrackIds: [],
-  };
-}
-
-function formatTrackError(track: AudioTrackDefinition, action: 'preload' | 'playback'): string {
-  return `Failed ${action} for audio track: ${track.label}`;
-}
-
-export function createAudioAdapter(
-  id = 'audio-adapter',
-): AdapterRegistration<AudioAdapterApi> {
-  let teardown: (() => void) | null = null;
-
-  return {
-    id,
-    capability: 'audio',
-    isSupported() {
-      return typeof window !== 'undefined' && typeof Audio !== 'undefined';
-    },
-    setup(ctx) {
-      const tracks = new Map<string, RegisteredTrack>();
-      const loadedTrackIds = new Set<string>();
-      const listeners = new Set<AudioListener>();
-      let snapshot = createEmptySnapshot();
-
-      const publish = (
-        partial: Partial<AudioTransportSnapshot> = {},
-        extraEvent?:
-          | {
-              type: 'audio:ended' | 'audio:error';
-              payload: unknown;
-            }
-          | undefined,
-      ): AudioTransportSnapshot => {
-        snapshot = {
-          ...snapshot,
-          ...partial,
-          loadedTrackIds: [...loadedTrackIds],
-        };
-
-        const next = cloneSnapshot(snapshot);
-
-        ctx.events.emit({
-          type: 'audio:changed',
-          source: id,
-          payload: next,
-          timestamp: Date.now(),
-        });
-
-        if (extraEvent) {
-          ctx.events.emit({
-            type: extraEvent.type,
-            source: id,
-            payload: extraEvent.payload,
-            timestamp: Date.now(),
-          });
-        }
-
-        for (const listener of [...listeners]) {
-          listener(next);
-        }
-
-        return next;
-      };
-
-      const requireTrack = (trackId: string): RegisteredTrack => {
-        const record = tracks.get(trackId);
-
-        if (!record) {
-          throw new Error(`Unknown audio track: ${trackId}`);
-        }
-
-        return record;
-      };
-
-      const applyElementSettings = (record: RegisteredTrack): void => {
-        record.element.loop = record.definition.loop ?? false;
-        record.element.muted = snapshot.muted;
-        record.element.volume = clampVolume(snapshot.volume * (record.definition.volume ?? 1));
-      };
-
-      const stopElement = (record: RegisteredTrack): void => {
-        record.element.pause();
-
-        try {
-          record.element.currentTime = 0;
-        } catch {
-          // Some browsers can reject currentTime writes if metadata is unavailable.
-        }
-      };
-
-      const preloadElement = async (record: RegisteredTrack): Promise<void> => {
-        if (loadedTrackIds.has(record.definition.id) || record.element.readyState >= 3) {
-          loadedTrackIds.add(record.definition.id);
-          return;
-        }
-
-        await new Promise<void>((resolve, reject) => {
-          const onReady = (): void => {
-            cleanup();
-            loadedTrackIds.add(record.definition.id);
-            resolve();
-          };
-
-          const onError = (): void => {
-            cleanup();
-            reject(new Error(formatTrackError(record.definition, 'preload')));
-          };
-
-          const cleanup = (): void => {
-            record.element.removeEventListener('canplaythrough', onReady);
-            record.element.removeEventListener('loadeddata', onReady);
-            record.element.removeEventListener('error', onError);
-          };
-
-          record.element.addEventListener('canplaythrough', onReady, { once: true });
-          record.element.addEventListener('loadeddata', onReady, { once: true });
-          record.element.addEventListener('error', onError, { once: true });
-          record.element.load();
-        });
-      };
-
-      const preloadTrack = async (
-        record: RegisteredTrack,
-        shouldSetLoading: boolean,
-      ): Promise<void> => {
-        if (shouldSetLoading) {
-          publish({
-            status: 'loading',
-            errorMessage: undefined,
-          });
-        }
-
-        try {
-          await preloadElement(record);
-          publish({
-            status: shouldSetLoading ? 'ready' : snapshot.status,
-            errorMessage: undefined,
-          });
-        } catch (error) {
-          const message =
-            error instanceof Error ? error.message : formatTrackError(record.definition, 'preload');
-
-          publish(
-            {
-              status: 'error',
-              errorMessage: message,
-            },
-            {
-              type: 'audio:error',
-              payload: {
-                trackId: record.definition.id,
-                label: record.definition.label,
-                message,
-              },
-            },
-          );
-
-          throw new Error(message);
-        }
-      };
-
-      teardown = (): void => {
-        for (const record of tracks.values()) {
-          record.element.pause();
-          record.element.removeEventListener('ended', record.onEnded);
-          record.element.removeEventListener('error', record.onError);
-          record.element.src = '';
-          record.element.load();
-        }
-
-        tracks.clear();
-        loadedTrackIds.clear();
-        listeners.clear();
-      };
-
-      return {
-        registerTrack(track) {
-          if (tracks.has(track.id)) {
-            throw new Error(`Audio track already registered: ${track.id}`);
-          }
-
-          const element = new Audio(track.src);
-          element.preload = 'auto';
-
-          const onEnded = (): void => {
-            if (snapshot.activeTrackId !== track.id) {
-              return;
-            }
-
-            publish(
-              {
-                status: 'ready',
-                errorMessage: undefined,
-              },
-              {
-                type: 'audio:ended',
-                payload: {
-                  trackId: track.id,
-                  label: track.label,
-                },
-              },
-            );
-          };
-
-          const onError = (): void => {
-            const message = formatTrackError(track, 'playback');
-
-            if (snapshot.status === 'error' && snapshot.errorMessage === message) {
-              return;
-            }
-
-            publish(
-              {
-                activeTrackId: snapshot.activeTrackId ?? track.id,
-                status: 'error',
-                errorMessage: message,
-              },
-              {
-                type: 'audio:error',
-                payload: {
-                  trackId: track.id,
-                  label: track.label,
-                  message,
-                },
-              },
-            );
-          };
-
-          const record: RegisteredTrack = {
-            definition: {
-              ...track,
-              volume: clampVolume(track.volume ?? 1),
-            },
-            element,
-            onEnded,
-            onError,
-          };
-
-          element.addEventListener('ended', onEnded);
-          element.addEventListener('error', onError);
-          applyElementSettings(record);
-          tracks.set(track.id, record);
-        },
-        async preload(trackId) {
-          const record = requireTrack(trackId);
-          const shouldSetLoading =
-            snapshot.status === 'idle' ||
-            snapshot.status === 'loading' ||
-            snapshot.status === 'ready';
-
-          await preloadTrack(record, shouldSetLoading);
-        },
-        async play(trackId) {
-          const nextTrackId = trackId ?? snapshot.activeTrackId;
-
-          if (!nextTrackId) {
-            return;
-          }
-
-          const nextRecord = requireTrack(nextTrackId);
-          const previousTrackId = snapshot.activeTrackId;
-
-          if (previousTrackId && previousTrackId !== nextTrackId) {
-            stopElement(requireTrack(previousTrackId));
-          }
-
-          if (!loadedTrackIds.has(nextTrackId) && nextRecord.element.readyState < 3) {
-            publish({
-              activeTrackId: nextTrackId,
-              status: 'loading',
-              errorMessage: undefined,
-            });
-
-            await preloadTrack(nextRecord, false);
-          }
-
-          if (
-            previousTrackId !== nextTrackId ||
-            nextRecord.element.ended ||
-            (nextRecord.element.duration > 0 &&
-              nextRecord.element.currentTime >= nextRecord.element.duration)
-          ) {
-            try {
-              nextRecord.element.currentTime = 0;
-            } catch {
-              // Ignore currentTime reset failures for browsers without loaded metadata yet.
-            }
-          }
-
-          applyElementSettings(nextRecord);
-
-          try {
-            await nextRecord.element.play();
-            publish({
-              activeTrackId: nextTrackId,
-              status: 'playing',
-              errorMessage: undefined,
-            });
-          } catch (error) {
-            const message =
-              error instanceof Error ? error.message : formatTrackError(nextRecord.definition, 'playback');
-
-            publish(
-              {
-                activeTrackId: nextTrackId,
-                status: 'error',
-                errorMessage: message,
-              },
-              {
-                type: 'audio:error',
-                payload: {
-                  trackId: nextTrackId,
-                  label: nextRecord.definition.label,
-                  message,
-                },
-              },
-            );
-
-            throw new Error(message);
-          }
-        },
-        pause() {
-          if (!snapshot.activeTrackId) {
-            return;
-          }
-
-          const record = requireTrack(snapshot.activeTrackId);
-          record.element.pause();
-
-          publish({
-            status: 'paused',
-            errorMessage: undefined,
-          });
-        },
-        stop() {
-          if (!snapshot.activeTrackId) {
-            return;
-          }
-
-          stopElement(requireTrack(snapshot.activeTrackId));
-
-          publish({
-            status: 'ready',
-            errorMessage: undefined,
-          });
-        },
-        setMuted(next) {
-          const muted = Boolean(next);
-
-          for (const record of tracks.values()) {
-            record.element.muted = muted;
-          }
-
-          publish({
-            muted,
-            errorMessage: undefined,
-          });
-        },
-        setVolume(next) {
-          const volume = clampVolume(next);
-
-          for (const record of tracks.values()) {
-            record.element.volume = clampVolume(volume * (record.definition.volume ?? 1));
-          }
-
-          publish({
-            volume,
-            errorMessage: undefined,
-          });
-        },
-        getSnapshot() {
-          return cloneSnapshot(snapshot);
-        },
-        subscribe(listener) {
-          listeners.add(listener);
-
-          return () => {
-            listeners.delete(listener);
-          };
-        },
-      };
-    },
-    dispose() {
-      teardown?.();
-      teardown = null;
-    },
-  };
-}

package/src/contracts.ts

@@ -1,15 +0,0 @@
-/**
- * Company: EonHive Inc.
- * Title: Adapter Contracts
- * Purpose: Re-export the canonical kernel adapter contracts from @urk/core.
- * Author: Stan Nesi
- * Created: 2026-04-12
- * Updated: 2026-04-15
- * Notes: Vibe coded with Codex.
- */
-
-export type {
-  AdapterRegistration,
-  KernelEvent,
-  RuntimeContext,
-} from '@urk/core';

package/src/dom.ts

@@ -1,16 +0,0 @@
-/**
- * Company: EonHive Inc.
- * Title: DOM Adapter Exports
- * Purpose: Provide a dependency-light adapter surface for DOM-only URK consumers.
- * Author: Stan Nesi
- * Created: 2026-04-23
- * Updated: 2026-04-23
- * Notes: Vibe coded with Codex.
- */
-
-export * from './loading.js';
-export * from './input.js';
-export * from './pointer.js';
-export * from './storage.js';
-export * from './ui-widgets.js';
-export * from './contracts.js';

package/src/index.ts

@@ -1,5 +0,0 @@
-/**
- * URK Adapters - Contract-first capability adapters.
- */
-
-export * from './adapters.js';

package/src/input.ts

@@ -1,207 +0,0 @@
-/**
- * Company: EonHive Inc.
- * Title: Input Adapter
- * Purpose: Normalize keyboard input into a small reusable runtime capability.
- * Author: Stan Nesi
- * Created: 2026-04-20
- * Updated: 2026-04-20
- * Notes: Vibe coded with Codex.
- */
-
-import type { AdapterRegistration, RuntimeContext } from '@urk/core';
-
-export type InputEventPhase = 'down' | 'up';
-
-export interface InputKeyEvent {
-  code: string;
-  key: string;
-  phase: InputEventPhase;
-  repeat: boolean;
-  altKey: boolean;
-  ctrlKey: boolean;
-  metaKey: boolean;
-  shiftKey: boolean;
-  nativeEvent: KeyboardEvent;
-}
-
-export interface InputBinding {
-  code: string;
-  phase?: InputEventPhase;
-  allowRepeat?: boolean;
-  handler: (event: InputKeyEvent) => void;
-}
-
-export type InputListener = (event: InputKeyEvent) => void;
-
-export interface InputAdapterApi {
-  isPressed(code: string): boolean;
-  bindKey(binding: InputBinding): () => void;
-  subscribe(listener: InputListener): () => void;
-  clear(): void;
-}
-
-type InputTarget = Window | Document | HTMLElement;
-
-type BoundInputBinding = {
-  code: string;
-  phase: InputEventPhase;
-  allowRepeat: boolean;
-  handler: (event: InputKeyEvent) => void;
-};
-
-function resolveInputTarget(ctx: RuntimeContext): InputTarget {
-  const serviceTarget = ctx.services.get<unknown>('input:target');
-
-  if (serviceTarget === undefined) {
-    return window;
-  }
-
-  if (serviceTarget === window) {
-    return window;
-  }
-
-  if (typeof Document !== 'undefined' && serviceTarget instanceof Document) {
-    return serviceTarget;
-  }
-
-  if (typeof HTMLElement !== 'undefined' && serviceTarget instanceof HTMLElement) {
-    return serviceTarget;
-  }
-
-  throw new Error('Service input:target must be a Window, Document, or HTMLElement.');
-}
-
-function createInputEvent(
-  phase: InputEventPhase,
-  nativeEvent: KeyboardEvent,
-): InputKeyEvent {
-  return {
-    code: nativeEvent.code || nativeEvent.key,
-    key: nativeEvent.key,
-    phase,
-    repeat: nativeEvent.repeat,
-    altKey: nativeEvent.altKey,
-    ctrlKey: nativeEvent.ctrlKey,
-    metaKey: nativeEvent.metaKey,
-    shiftKey: nativeEvent.shiftKey,
-    nativeEvent,
-  };
-}
-
-export function createInputAdapter(
-  id = 'input-adapter',
-): AdapterRegistration<InputAdapterApi> {
-  let disposeTargetListeners: (() => void) | null = null;
-
-  return {
-    id,
-    capability: 'input',
-    isSupported() {
-      return typeof window !== 'undefined' && typeof document !== 'undefined';
-    },
-    setup(ctx) {
-      const target = resolveInputTarget(ctx);
-      const resetTarget = window;
-      const pressedCodes = new Set<string>();
-      const bindings = new Set<BoundInputBinding>();
-      const listeners = new Set<InputListener>();
-
-      const publish = (event: InputKeyEvent): void => {
-        ctx.events.emit({
-          type: event.phase === 'down' ? 'input:key-down' : 'input:key-up',
-          source: id,
-          payload: event,
-          timestamp: Date.now(),
-        });
-
-        for (const listener of [...listeners]) {
-          listener(event);
-        }
-
-        for (const binding of [...bindings]) {
-          if (binding.code !== event.code || binding.phase !== event.phase) {
-            continue;
-          }
-
-          if (event.repeat && !binding.allowRepeat) {
-            continue;
-          }
-
-          binding.handler(event);
-        }
-      };
-
-      const onKeyDown = (nativeEvent: Event): void => {
-        if (!(nativeEvent instanceof KeyboardEvent)) {
-          return;
-        }
-
-        const event = createInputEvent('down', nativeEvent);
-        pressedCodes.add(event.code);
-        publish(event);
-      };
-
-      const onKeyUp = (nativeEvent: Event): void => {
-        if (!(nativeEvent instanceof KeyboardEvent)) {
-          return;
-        }
-
-        const event = createInputEvent('up', nativeEvent);
-        pressedCodes.delete(event.code);
-        publish(event);
-      };
-
-      const onBlur = (): void => {
-        pressedCodes.clear();
-      };
-
-      target.addEventListener('keydown', onKeyDown);
-      target.addEventListener('keyup', onKeyUp);
-      resetTarget.addEventListener('blur', onBlur);
-
-      // Keep the public API minimal while still ensuring dispose can tear down DOM listeners.
-      disposeTargetListeners = () => {
-        target.removeEventListener('keydown', onKeyDown);
-        target.removeEventListener('keyup', onKeyUp);
-        resetTarget.removeEventListener('blur', onBlur);
-      };
-
-      return {
-        isPressed(code) {
-          return pressedCodes.has(code);
-        },
-        bindKey(binding) {
-          const normalizedBinding: BoundInputBinding = {
-            code: binding.code,
-            phase: binding.phase ?? 'down',
-            allowRepeat: binding.allowRepeat ?? false,
-            handler: binding.handler,
-          };
-
-          bindings.add(normalizedBinding);
-
-          return () => {
-            bindings.delete(normalizedBinding);
-          };
-        },
-        subscribe(listener) {
-          listeners.add(listener);
-
-          return () => {
-            listeners.delete(listener);
-          };
-        },
-        clear() {
-          pressedCodes.clear();
-          bindings.clear();
-          listeners.clear();
-        },
-      };
-    },
-    dispose(_ctx, api) {
-      disposeTargetListeners?.();
-      disposeTargetListeners = null;
-      api.clear();
-    },
-  };
-}