@urk/adapters 0.1.0

package/src/storage.ts

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

package/src/three.ts

@@ -0,0 +1,178 @@
+/**
+ * Company: EonHive Inc.
+ * Title: Three Adapter
+ * Purpose: Mount a small Three.js scene surface behind a stable URK capability contract.
+ * Author: Stan Nesi
+ * Created: 2026-04-22
+ * Updated: 2026-04-22
+ * Notes: Vibe coded with Codex.
+ */
+
+import type { AdapterRegistration } from '@urk/core';
+import * as THREE from 'three';
+
+export interface ThreeAdapterSize {
+  width: number;
+  height: number;
+}
+
+export interface ThreeAdapterApi {
+  getHost(): HTMLElement;
+  getCanvas(): HTMLCanvasElement;
+  getScene(): THREE.Scene;
+  getCamera(): THREE.PerspectiveCamera;
+  getRenderer(): THREE.WebGLRenderer;
+  getSize(): ThreeAdapterSize;
+  resize(): void;
+  render(): void;
+  raycast(
+    clientX: number,
+    clientY: number,
+    objects: THREE.Object3D[],
+  ): THREE.Intersection<THREE.Object3D>[];
+}
+
+function assertHtmlElement(value: unknown, serviceName: string): HTMLElement {
+  if (typeof HTMLElement === 'undefined' || !(value instanceof HTMLElement)) {
+    throw new Error(`Service ${serviceName} must be an HTMLElement.`);
+  }
+
+  return value;
+}
+
+function getHostSize(host: HTMLElement): ThreeAdapterSize {
+  return {
+    width: Math.max(host.clientWidth, 1),
+    height: Math.max(host.clientHeight, 1),
+  };
+}
+
+function getPixelRatio(): number {
+  if (typeof window === 'undefined') {
+    return 1;
+  }
+
+  return Math.min(window.devicePixelRatio || 1, 2);
+}
+
+export function createThreeAdapter(
+  id = 'three-adapter',
+): AdapterRegistration<ThreeAdapterApi> {
+  let disposeResizeTracking: (() => void) | null = null;
+
+  return {
+    id,
+    capability: 'three',
+    isSupported() {
+      return typeof window !== 'undefined' && typeof document !== 'undefined';
+    },
+    setup(ctx) {
+      const host = assertHtmlElement(ctx.services.require('three:host'), 'three:host');
+      const scene = new THREE.Scene();
+      const camera = new THREE.PerspectiveCamera(42, 1, 0.1, 100);
+      const renderer = new THREE.WebGLRenderer({
+        alpha: true,
+        antialias: true,
+      });
+      const raycaster = new THREE.Raycaster();
+      const raycastPointer = new THREE.Vector2();
+
+      camera.position.set(0, 0, 5.75);
+      camera.lookAt(0, 0, 0);
+
+      renderer.outputColorSpace = THREE.SRGBColorSpace;
+      renderer.setClearColor(0x000000, 0);
+      renderer.domElement.style.width = '100%';
+      renderer.domElement.style.height = '100%';
+      renderer.domElement.style.display = 'block';
+      renderer.domElement.style.pointerEvents = 'none';
+
+      host.append(renderer.domElement);
+
+      let size = getHostSize(host);
+
+      const resize = (): void => {
+        size = getHostSize(host);
+        renderer.setPixelRatio(getPixelRatio());
+        renderer.setSize(size.width, size.height, false);
+        camera.aspect = size.width / size.height;
+        camera.updateProjectionMatrix();
+      };
+
+      resize();
+
+      if (typeof ResizeObserver !== 'undefined') {
+        const observer = new ResizeObserver(() => {
+          resize();
+        });
+
+        observer.observe(host);
+        disposeResizeTracking = () => {
+          observer.disconnect();
+        };
+      } else if (typeof window !== 'undefined') {
+        const onResize = (): void => {
+          resize();
+        };
+
+        window.addEventListener('resize', onResize);
+        disposeResizeTracking = () => {
+          window.removeEventListener('resize', onResize);
+        };
+      } else {
+        disposeResizeTracking = null;
+      }
+
+      return {
+        getHost() {
+          return host;
+        },
+        getCanvas() {
+          return renderer.domElement;
+        },
+        getScene() {
+          return scene;
+        },
+        getCamera() {
+          return camera;
+        },
+        getRenderer() {
+          return renderer;
+        },
+        getSize() {
+          return { ...size };
+        },
+        resize,
+        render() {
+          renderer.render(scene, camera);
+        },
+        raycast(clientX, clientY, objects) {
+          if (objects.length === 0) {
+            return [];
+          }
+
+          const bounds = renderer.domElement.getBoundingClientRect();
+
+          if (bounds.width <= 0 || bounds.height <= 0) {
+            return [];
+          }
+
+          raycastPointer.set(
+            ((clientX - bounds.left) / bounds.width) * 2 - 1,
+            -((clientY - bounds.top) / bounds.height) * 2 + 1,
+          );
+
+          raycaster.setFromCamera(raycastPointer, camera);
+
+          return raycaster.intersectObjects(objects, true);
+        },
+      };
+    },
+    dispose(_ctx, api) {
+      disposeResizeTracking?.();
+      disposeResizeTracking = null;
+      api.getRenderer().dispose();
+      api.getCanvas().remove();
+    },
+  };
+}

package/src/ui-widgets.ts

@@ -0,0 +1,120 @@
+/**
+ * Company: EonHive Inc.
+ * Title: UI Widgets Adapter
+ * Purpose: Mount a small overlay shell with status and callout surfaces.
+ * Author: Stan Nesi
+ * Created: 2026-04-12
+ * Updated: 2026-04-15
+ * Notes: Vibe coded with Codex.
+ */
+
+import type { AdapterRegistration } from '@urk/core';
+
+export interface UiWidgetCallout {
+  title: string;
+  body: string;
+  tone?: 'neutral' | 'active' | 'selected';
+}
+
+export interface UiWidgetsAdapterApi {
+  setStatus(message: string): void;
+  showCallout(callout: UiWidgetCallout): void;
+  hideCallout(): void;
+  destroy(): void;
+}
+
+function assertHtmlElement(value: unknown, serviceName: string): HTMLElement {
+  if (typeof HTMLElement === 'undefined' || !(value instanceof HTMLElement)) {
+    throw new Error(`Service ${serviceName} must be an HTMLElement.`);
+  }
+
+  return value;
+}
+
+export function createUiWidgetsAdapter(
+  id = 'ui-widgets-adapter',
+): AdapterRegistration<UiWidgetsAdapterApi> {
+  return {
+    id,
+    capability: 'ui-widgets',
+    setup(ctx) {
+      const host = assertHtmlElement(ctx.services.require('ui:host'), 'ui:host');
+      const root = document.createElement('div');
+      const status = document.createElement('div');
+      const callout = document.createElement('div');
+      const title = document.createElement('div');
+      const body = document.createElement('div');
+
+      root.style.position = 'absolute';
+      root.style.inset = '0';
+      root.style.pointerEvents = 'none';
+      root.style.display = 'flex';
+      root.style.flexDirection = 'column';
+      root.style.justifyContent = 'space-between';
+      root.style.padding = '16px';
+
+      status.style.alignSelf = 'flex-start';
+      status.style.padding = '8px 12px';
+      status.style.borderRadius = '999px';
+      status.style.background = 'rgba(15, 23, 42, 0.82)';
+      status.style.color = '#f8fafc';
+      status.style.fontSize = '13px';
+      status.style.fontWeight = '600';
+      status.style.letterSpacing = '0.02em';
+      status.style.backdropFilter = 'blur(12px)';
+
+      callout.style.alignSelf = 'flex-end';
+      callout.style.maxWidth = '280px';
+      callout.style.padding = '14px 16px';
+      callout.style.borderRadius = '18px';
+      callout.style.background = 'rgba(15, 23, 42, 0.92)';
+      callout.style.color = '#f8fafc';
+      callout.style.boxShadow = '0 20px 45px rgba(15, 23, 42, 0.22)';
+      callout.style.backdropFilter = 'blur(12px)';
+      callout.style.display = 'none';
+
+      title.style.fontSize = '14px';
+      title.style.fontWeight = '700';
+      title.style.marginBottom = '6px';
+
+      body.style.fontSize = '13px';
+      body.style.lineHeight = '1.5';
+      body.style.opacity = '0.92';
+
+      callout.append(title, body);
+      root.append(status, callout);
+      host.append(root);
+
+      const applyTone = (tone: UiWidgetCallout['tone'] = 'neutral'): void => {
+        const palette = {
+          neutral: 'rgba(15, 23, 42, 0.92)',
+          active: 'rgba(14, 116, 144, 0.92)',
+          selected: 'rgba(22, 101, 52, 0.94)',
+        } as const;
+
+        callout.style.background = palette[tone];
+      };
+
+      return {
+        setStatus(message) {
+          status.textContent = message;
+        },
+        showCallout(config) {
+          title.textContent = config.title;
+          body.textContent = config.body;
+          callout.style.display = 'block';
+          applyTone(config.tone);
+        },
+        hideCallout() {
+          callout.style.display = 'none';
+        },
+        destroy() {
+          root.remove();
+        },
+      };
+    },
+    dispose(_ctx, api) {
+      api.destroy();
+    },
+  };
+}