@urk/adapters 0.1.0

package/src/contracts.ts

@@ -0,0 +1,15 @@
+/**
+ * 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/index.ts

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

package/src/input.ts

@@ -0,0 +1,207 @@
+/**
+ * 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();
+    },
+  };
+}

package/src/loading.ts

@@ -0,0 +1,174 @@
+/**
+ * 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

@@ -0,0 +1,203 @@
+/**
+ * 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();
+    },
+  };
+}