@urk/adapters 0.1.2 → 0.1.4

package/src/loading.ts

@@ -1,174 +0,0 @@
-/**
- * Company: EonHive Inc.
- * Title: Loading Adapter
- * Purpose: Track staged loading progress and expose a small observable API.
- * Author: Stan Nesi
- * Created: 2026-04-12
- * Updated: 2026-04-15
- * Notes: Vibe coded with Codex.
- */
-
-import type { AdapterRegistration } from '@urk/core';
-
-export interface LoadingStage {
-  id: string;
-  label: string;
-  weight?: number;
-}
-
-export interface LoadingSnapshot {
-  active: boolean;
-  complete: boolean;
-  progress: number;
-  message: string;
-  stageId: string | null;
-  stageLabel: string | null;
-  stages: LoadingStage[];
-  updatedAt: number;
-}
-
-export type LoadingListener = (snapshot: LoadingSnapshot) => void;
-
-export interface LoadingAdapterApi {
-  begin(stages: LoadingStage[], message?: string): LoadingSnapshot;
-  setStage(stageId: string, progressWithinStage: number, message?: string): LoadingSnapshot;
-  complete(message?: string): LoadingSnapshot;
-  getSnapshot(): LoadingSnapshot;
-  subscribe(listener: LoadingListener): () => void;
-}
-
-function normalizeStages(stages: LoadingStage[]): LoadingStage[] {
-  if (stages.length === 0) {
-    throw new Error('Loading adapter requires at least one stage.');
-  }
-
-  return stages.map((stage) => ({
-    ...stage,
-    weight: stage.weight && stage.weight > 0 ? stage.weight : 1,
-  }));
-}
-
-function clampProgress(progress: number): number {
-  return Math.max(0, Math.min(progress, 1));
-}
-
-function createEmptySnapshot(): LoadingSnapshot {
-  return {
-    active: false,
-    complete: false,
-    progress: 0,
-    message: 'Waiting to start',
-    stageId: null,
-    stageLabel: null,
-    stages: [],
-    updatedAt: Date.now(),
-  };
-}
-
-export function createLoadingAdapter(
-  id = 'loading-adapter',
-): AdapterRegistration<LoadingAdapterApi> {
-  return {
-    id,
-    capability: 'loading',
-    setup(ctx) {
-      let snapshot = createEmptySnapshot();
-      const listeners = new Set<LoadingListener>();
-
-      const publish = (): LoadingSnapshot => {
-        const next = { ...snapshot, stages: [...snapshot.stages] };
-
-        ctx.events.emit({
-          type: 'loading:changed',
-          source: id,
-          payload: next,
-          timestamp: Date.now(),
-        });
-
-        for (const listener of [...listeners]) {
-          listener(next);
-        }
-
-        return next;
-      };
-
-      const getTotalWeight = (): number => {
-        return snapshot.stages.reduce((total, stage) => total + (stage.weight ?? 1), 0);
-      };
-
-      return {
-        begin(stages, message = 'Starting load') {
-          const nextStages = normalizeStages(stages);
-          const firstStage = nextStages[0];
-
-          snapshot = {
-            active: true,
-            complete: false,
-            progress: 0,
-            message,
-            stageId: firstStage.id,
-            stageLabel: firstStage.label,
-            stages: nextStages,
-            updatedAt: Date.now(),
-          };
-
-          return publish();
-        },
-        setStage(stageId, progressWithinStage, message) {
-          const stageIndex = snapshot.stages.findIndex((stage) => stage.id === stageId);
-
-          if (stageIndex === -1) {
-            throw new Error(`Unknown loading stage: ${stageId}`);
-          }
-
-          const previousWeight = snapshot.stages
-            .slice(0, stageIndex)
-            .reduce((total, stage) => total + (stage.weight ?? 1), 0);
-          const currentStage = snapshot.stages[stageIndex];
-          const totalWeight = getTotalWeight();
-          const progress =
-            (previousWeight + (currentStage.weight ?? 1) * clampProgress(progressWithinStage)) /
-            totalWeight;
-
-          snapshot = {
-            ...snapshot,
-            active: true,
-            progress,
-            message: message ?? snapshot.message,
-            stageId: currentStage.id,
-            stageLabel: currentStage.label,
-            updatedAt: Date.now(),
-          };
-
-          return publish();
-        },
-        complete(message = 'Loading complete') {
-          const lastStage = snapshot.stages[snapshot.stages.length - 1] ?? null;
-
-          snapshot = {
-            ...snapshot,
-            active: false,
-            complete: true,
-            progress: 1,
-            message,
-            stageId: lastStage?.id ?? null,
-            stageLabel: lastStage?.label ?? null,
-            updatedAt: Date.now(),
-          };
-
-          return publish();
-        },
-        getSnapshot() {
-          return { ...snapshot, stages: [...snapshot.stages] };
-        },
-        subscribe(listener) {
-          listeners.add(listener);
-
-          return () => {
-            listeners.delete(listener);
-          };
-        },
-      };
-    },
-  };
-}

package/src/pointer.ts

@@ -1,203 +0,0 @@
-/**
- * Company: EonHive Inc.
- * Title: Pointer Adapter
- * Purpose: Normalize pointer target binding and emit interaction events.
- * Author: Stan Nesi
- * Created: 2026-04-12
- * Updated: 2026-04-22
- * Notes: Vibe coded with Codex.
- */
-
-import type { AdapterRegistration } from '@urk/core';
-
-export interface PointerTargetDefinition {
-  id: string;
-  element: HTMLElement;
-  meta?: Record<string, unknown>;
-}
-
-export interface PointerTargetEventPayload {
-  targetId: string;
-  element: HTMLElement;
-  meta?: Record<string, unknown>;
-  nativeEvent: MouseEvent | PointerEvent;
-}
-
-export interface PointerSurfaceDefinition {
-  id: string;
-  element: HTMLElement;
-  meta?: Record<string, unknown>;
-}
-
-export interface PointerSurfaceEventPayload {
-  surfaceId: string;
-  element: HTMLElement;
-  meta?: Record<string, unknown>;
-  clientX: number;
-  clientY: number;
-  localX: number;
-  localY: number;
-  nativeEvent: MouseEvent | PointerEvent;
-}
-
-export interface PointerAdapterApi {
-  bindTarget(target: PointerTargetDefinition): () => void;
-  bindSurface(surface: PointerSurfaceDefinition): () => void;
-  clear(): void;
-}
-
-function getSurfaceCoordinates(
-  element: HTMLElement,
-  nativeEvent: MouseEvent | PointerEvent,
-): {
-  clientX: number;
-  clientY: number;
-  localX: number;
-  localY: number;
-} {
-  const bounds = element.getBoundingClientRect();
-
-  return {
-    clientX: nativeEvent.clientX,
-    clientY: nativeEvent.clientY,
-    localX: nativeEvent.clientX - bounds.left,
-    localY: nativeEvent.clientY - bounds.top,
-  };
-}
-
-export function createPointerAdapter(
-  id = 'pointer-adapter',
-): AdapterRegistration<PointerAdapterApi> {
-  return {
-    id,
-    capability: 'pointer',
-    setup(ctx) {
-      const cleanups = new Map<string, () => void>();
-
-      const emit = <TPayload>(type: string, payload: TPayload): void => {
-        ctx.events.emit({
-          type,
-          source: id,
-          payload,
-          timestamp: Date.now(),
-        });
-      };
-
-      return {
-        bindTarget(target) {
-          if (cleanups.has(target.id)) {
-            throw new Error(`Pointer target already bound: ${target.id}`);
-          }
-
-          const onEnter = (nativeEvent: PointerEvent): void => {
-            emit('pointer:hover', {
-              targetId: target.id,
-              element: target.element,
-              meta: target.meta,
-              nativeEvent,
-            });
-          };
-
-          const onLeave = (nativeEvent: PointerEvent): void => {
-            emit('pointer:leave', {
-              targetId: target.id,
-              element: target.element,
-              meta: target.meta,
-              nativeEvent,
-            });
-          };
-
-          const onSelect = (nativeEvent: MouseEvent): void => {
-            emit('pointer:select', {
-              targetId: target.id,
-              element: target.element,
-              meta: target.meta,
-              nativeEvent,
-            });
-          };
-
-          target.element.addEventListener('pointerenter', onEnter);
-          target.element.addEventListener('pointerleave', onLeave);
-          target.element.addEventListener('click', onSelect);
-
-          const cleanup = (): void => {
-            target.element.removeEventListener('pointerenter', onEnter);
-            target.element.removeEventListener('pointerleave', onLeave);
-            target.element.removeEventListener('click', onSelect);
-          };
-
-          cleanups.set(target.id, cleanup);
-
-          return () => {
-            cleanup();
-            cleanups.delete(target.id);
-          };
-        },
-        bindSurface(surface) {
-          const cleanupKey = `surface:${surface.id}`;
-
-          if (cleanups.has(cleanupKey)) {
-            throw new Error(`Pointer surface already bound: ${surface.id}`);
-          }
-
-          const onMove = (nativeEvent: PointerEvent): void => {
-            emit('pointer:surface-move', {
-              surfaceId: surface.id,
-              element: surface.element,
-              meta: surface.meta,
-              ...getSurfaceCoordinates(surface.element, nativeEvent),
-              nativeEvent,
-            } satisfies PointerSurfaceEventPayload);
-          };
-
-          const onLeave = (nativeEvent: PointerEvent): void => {
-            emit('pointer:surface-leave', {
-              surfaceId: surface.id,
-              element: surface.element,
-              meta: surface.meta,
-              ...getSurfaceCoordinates(surface.element, nativeEvent),
-              nativeEvent,
-            } satisfies PointerSurfaceEventPayload);
-          };
-
-          const onSelect = (nativeEvent: MouseEvent): void => {
-            emit('pointer:surface-select', {
-              surfaceId: surface.id,
-              element: surface.element,
-              meta: surface.meta,
-              ...getSurfaceCoordinates(surface.element, nativeEvent),
-              nativeEvent,
-            } satisfies PointerSurfaceEventPayload);
-          };
-
-          surface.element.addEventListener('pointermove', onMove);
-          surface.element.addEventListener('pointerleave', onLeave);
-          surface.element.addEventListener('click', onSelect);
-
-          const cleanup = (): void => {
-            surface.element.removeEventListener('pointermove', onMove);
-            surface.element.removeEventListener('pointerleave', onLeave);
-            surface.element.removeEventListener('click', onSelect);
-          };
-
-          cleanups.set(cleanupKey, cleanup);
-
-          return () => {
-            cleanup();
-            cleanups.delete(cleanupKey);
-          };
-        },
-        clear() {
-          for (const cleanup of cleanups.values()) {
-            cleanup();
-          }
-
-          cleanups.clear();
-        },
-      };
-    },
-    dispose(_ctx, api) {
-      api.clear();
-    },
-  };
-}

package/src/storage.ts

@@ -1,194 +0,0 @@
-/**
- * Company: EonHive Inc.
- * Title: Storage Adapter
- * Purpose: Expose a small namespaced storage capability for local and session persistence.
- * Author: Stan Nesi
- * Created: 2026-04-21
- * Updated: 2026-04-21
- * Notes: Vibe coded with Codex.
- */
-
-import type { AdapterRegistration, RuntimeContext } from '@urk/core';
-
-export type StorageArea = 'local' | 'session';
-
-export interface StorageAdapterOptions {
-  id?: string;
-  namespace?: string;
-}
-
-export interface StorageAdapterApi {
-  getItem<T = unknown>(key: string, area?: StorageArea): T | null;
-  setItem<T>(key: string, value: T, area?: StorageArea): void;
-  removeItem(key: string, area?: StorageArea): void;
-  listKeys(area?: StorageArea): string[];
-  clear(area?: StorageArea): void;
-}
-
-type StorageBackendLike = {
-  length: number;
-  key(index: number): string | null;
-  getItem(key: string): string | null;
-  setItem(key: string, value: string): void;
-  removeItem(key: string): void;
-};
-
-const DEFAULT_NAMESPACE = 'urk';
-
-function isStorageBackendLike(value: unknown): value is StorageBackendLike {
-  if (typeof value !== 'object' || value === null) {
-    return false;
-  }
-
-  const candidate = value as Partial<StorageBackendLike>;
-
-  return (
-    typeof candidate.length === 'number' &&
-    typeof candidate.key === 'function' &&
-    typeof candidate.getItem === 'function' &&
-    typeof candidate.setItem === 'function' &&
-    typeof candidate.removeItem === 'function'
-  );
-}
-
-function resolveServiceBackend(
-  ctx: RuntimeContext,
-  area: StorageArea,
-): StorageBackendLike | null {
-  const serviceName = area === 'local' ? 'storage:local' : 'storage:session';
-  const value = ctx.services.get<unknown>(serviceName);
-
-  if (value === undefined) {
-    return null;
-  }
-
-  if (!isStorageBackendLike(value)) {
-    throw new Error(
-      `Service ${serviceName} must provide a Storage-compatible backend.`,
-    );
-  }
-
-  return value;
-}
-
-function resolveWindowBackend(area: StorageArea): StorageBackendLike | null {
-  if (typeof window === 'undefined') {
-    return null;
-  }
-
-  try {
-    return area === 'local' ? window.localStorage : window.sessionStorage;
-  } catch (error) {
-    const message =
-      error instanceof Error ? error.message : `Unable to access ${area}Storage.`;
-
-    throw new Error(`Storage adapter could not access ${area}Storage: ${message}`);
-  }
-}
-
-function resolveBackend(ctx: RuntimeContext, area: StorageArea): StorageBackendLike {
-  const serviceBackend = resolveServiceBackend(ctx, area);
-
-  if (serviceBackend) {
-    return serviceBackend;
-  }
-
-  const windowBackend = resolveWindowBackend(area);
-
-  if (windowBackend) {
-    return windowBackend;
-  }
-
-  throw new Error(`Storage adapter requires a ${area} storage backend.`);
-}
-
-function getStoragePrefix(namespace: string): string {
-  return `${namespace}:`;
-}
-
-function getNamespacedKey(namespace: string, key: string): string {
-  return `${getStoragePrefix(namespace)}${key}`;
-}
-
-function collectNamespacedKeys(
-  backend: StorageBackendLike,
-  namespace: string,
-): string[] {
-  const keys: string[] = [];
-  const prefix = getStoragePrefix(namespace);
-
-  for (let index = 0; index < backend.length; index += 1) {
-    const key = backend.key(index);
-
-    if (!key || !key.startsWith(prefix)) {
-      continue;
-    }
-
-    keys.push(key.slice(prefix.length));
-  }
-
-  return keys;
-}
-
-export function createStorageAdapter(
-  options: StorageAdapterOptions = {},
-): AdapterRegistration<StorageAdapterApi> {
-  const id = options.id ?? 'storage-adapter';
-  const namespace = options.namespace?.trim() || DEFAULT_NAMESPACE;
-
-  return {
-    id,
-    capability: 'storage',
-    setup(ctx) {
-      const backends: Record<StorageArea, StorageBackendLike> = {
-        local: resolveBackend(ctx, 'local'),
-        session: resolveBackend(ctx, 'session'),
-      };
-
-      const getBackend = (area: StorageArea = 'local'): StorageBackendLike => {
-        return backends[area];
-      };
-
-      return {
-        getItem<T = unknown>(key: string, area: StorageArea = 'local'): T | null {
-          const raw = getBackend(area).getItem(getNamespacedKey(namespace, key));
-
-          if (raw === null) {
-            return null;
-          }
-
-          try {
-            return JSON.parse(raw) as T;
-          } catch {
-            throw new Error(
-              `Stored value for key "${key}" in ${area} storage is not valid JSON.`,
-            );
-          }
-        },
-        setItem<T>(key: string, value: T, area: StorageArea = 'local'): void {
-          const serialized = JSON.stringify(value);
-
-          if (serialized === undefined) {
-            throw new Error(`Storage value for key "${key}" is not JSON serializable.`);
-          }
-
-          getBackend(area).setItem(getNamespacedKey(namespace, key), serialized);
-        },
-        removeItem(key: string, area: StorageArea = 'local'): void {
-          getBackend(area).removeItem(getNamespacedKey(namespace, key));
-        },
-        listKeys(area: StorageArea = 'local'): string[] {
-          return collectNamespacedKeys(getBackend(area), namespace);
-        },
-        clear(area: StorageArea = 'local'): void {
-          const backend = getBackend(area);
-
-          // Only remove keys owned by this adapter namespace.
-          for (const key of collectNamespacedKeys(backend, namespace)) {
-            backend.removeItem(getNamespacedKey(namespace, key));
-          }
-        },
-      };
-    },
-  };
-}