@urk/adapters 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @urk/adapters
+
+Contract-first capability adapters that prove URK's v0 kernel surface.
+
+## Reference adapters
+
+- `createPointerAdapter()` - bind DOM targets or pointer surfaces and emit normalized pointer events
+- `createInputAdapter()` - normalize keyboard input, track pressed keys, and bind simple key handlers
+- `createStorageAdapter()` - provide namespaced local/session key-value persistence with swappable backends
+- `createLoadingAdapter()` - track staged progress with an observable loading snapshot
+- `createThreeAdapter()` - mount a small Three scene surface onto a host element and expose render primitives
+- `createUiWidgetsAdapter()` - mount a small overlay shell with status and callout surfaces
+
+## Usage
+
+```ts
+import { createKernel } from '@urk/core';
+import {
+  createInputAdapter,
+  createPointerAdapter,
+  createStorageAdapter,
+  createThreeAdapter,
+  createUiWidgetsAdapter,
+} from '@urk/adapters';
+
+const kernel = createKernel({
+  services: {
+    'three:host': document.querySelector('#scene-host'),
+    'ui:host': document.querySelector('#overlay-host'),
+  },
+  adapters: [
+    createPointerAdapter(),
+    createInputAdapter(),
+    createStorageAdapter({ namespace: 'demo' }),
+    createThreeAdapter(),
+    createUiWidgetsAdapter(),
+  ],
+});
+
+await kernel.boot();
+```
+
+These adapters use the canonical `AdapterRegistration<TApi>` contract from `@urk/core`. They are intentionally small and exist to prove the kernel surface, not to introduce a broad adapter matrix early.
+
+`createInputAdapter()` is deliberately keyboard-first in this milestone:
+
+- pressed-key tracking through `isPressed(code)`
+- key bindings through `bindKey(binding)`
+- normalized keyboard event subscriptions through `subscribe(listener)`
+- no named action map, gamepad support, text-entry model, or focus-management system yet
+
+`createStorageAdapter()` is deliberately small in this milestone:
+
+- local and session key-value access through one adapter capability
+- namespaced keys so clear operations do not wipe unrelated browser storage
+- optional `storage:local` and `storage:session` service overrides for swappable backends
+- no IndexedDB, sync, cross-tab coordination, or product-facing save model yet
+
+`createPointerAdapter()` now covers two small interaction paths:
+
+- `bindTarget(...)` for DOM-target hover and select events
+- `bindSurface(...)` for normalized scene-surface move, leave, and select events
+- no drag model, press-and-hold semantics, or gesture layer yet
+
+`createThreeAdapter()` is deliberately scene-surface-first in this milestone:
+
+- requires a `three:host` `HTMLElement` service
+- owns the `Scene`, `PerspectiveCamera`, `WebGLRenderer`, and mounted canvas
+- keeps renderer and camera size in sync with the host element
+- exposes `raycast(clientX, clientY, objects)` so controllers can own picking behavior
+- does not own scene objects created by controllers
+- does not own selection state, drag helpers, or its own render loop
+
+## Validation
+
+This package is validated for this milestone through type-check/build plus the standalone DOM + Three picking proof in `@urk/examples`.
+
+## Architecture
+
+See `/docs/07_URK/URK_ARCHITECTURE.md`

package/dist/adapters.d.ts

@@ -0,0 +1,11 @@
+/**
+ * URK adapter exports.
+ */
+export * from './loading';
+export * from './input';
+export * from './pointer';
+export * from './storage';
+export * from './three';
+export * from './ui-widgets';
+export * from './contracts';
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/adapters.js

@@ -0,0 +1,11 @@
+/**
+ * URK adapter exports.
+ */
+export * from './loading';
+export * from './input';
+export * from './pointer';
+export * from './storage';
+export * from './three';
+export * from './ui-widgets';
+export * from './contracts';
+//# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/contracts.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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';
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EACV,mBAAmB,EACnB,WAAW,EACX,cAAc,GACf,MAAM,WAAW,CAAC"}

package/dist/contracts.js

@@ -0,0 +1,11 @@
+/**
+ * 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 {};
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * URK Adapters - Contract-first capability adapters.
+ */
+export * from './adapters';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,YAAY,CAAC"}

package/dist/index.js

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

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,YAAY,CAAC"}

package/dist/input.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 } 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;
+}
+export declare function createInputAdapter(id?: string): AdapterRegistration<InputAdapterApi>;
+//# sourceMappingURL=input.d.ts.map

package/dist/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../src/input.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAkB,MAAM,WAAW,CAAC;AAErE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,IAAI,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,eAAe,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,aAAa,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CACzC;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,IAAI,CAAC;IAC3C,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,IAAI,CAAC;IAC/C,KAAK,IAAI,IAAI,CAAC;CACf;AAkDD,wBAAgB,kBAAkB,CAChC,EAAE,SAAkB,GACnB,mBAAmB,CAAC,eAAe,CAAC,CAkHtC"}

package/dist/input.js

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+function resolveInputTarget(ctx) {
+    const serviceTarget = ctx.services.get('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, nativeEvent) {
+    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') {
+    let disposeTargetListeners = 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();
+            const bindings = new Set();
+            const listeners = new Set();
+            const publish = (event) => {
+                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) => {
+                if (!(nativeEvent instanceof KeyboardEvent)) {
+                    return;
+                }
+                const event = createInputEvent('down', nativeEvent);
+                pressedCodes.add(event.code);
+                publish(event);
+            };
+            const onKeyUp = (nativeEvent) => {
+                if (!(nativeEvent instanceof KeyboardEvent)) {
+                    return;
+                }
+                const event = createInputEvent('up', nativeEvent);
+                pressedCodes.delete(event.code);
+                publish(event);
+            };
+            const onBlur = () => {
+                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 = {
+                        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();
+        },
+    };
+}
+//# sourceMappingURL=input.js.map

package/dist/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../src/input.ts"],"names":[],"mappings":"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"}

package/dist/loading.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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;
+}
+export declare function createLoadingAdapter(id?: string): AdapterRegistration<LoadingAdapterApi>;
+//# sourceMappingURL=loading.d.ts.map

package/dist/loading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading.d.ts","sourceRoot":"","sources":["../src/loading.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,CAAC;AAElE,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;IAC1F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC;IAC5C,WAAW,IAAI,eAAe,CAAC;IAC/B,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI,CAAC;CAClD;AA8BD,wBAAgB,oBAAoB,CAClC,EAAE,SAAoB,GACrB,mBAAmB,CAAC,iBAAiB,CAAC,CAwGxC"}

package/dist/loading.js

@@ -0,0 +1,123 @@
+/**
+ * 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.
+ */
+function normalizeStages(stages) {
+    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) {
+    return Math.max(0, Math.min(progress, 1));
+}
+function createEmptySnapshot() {
+    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') {
+    return {
+        id,
+        capability: 'loading',
+        setup(ctx) {
+            let snapshot = createEmptySnapshot();
+            const listeners = new Set();
+            const publish = () => {
+                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 = () => {
+                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);
+                    };
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=loading.js.map

package/dist/loading.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading.js","sourceRoot":"","sources":["../src/loading.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+BH,SAAS,eAAe,CAAC,MAAsB;IAC7C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC5B,GAAG,KAAK;QACR,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;KAC5D,CAAC,CAAC,CAAC;AACN,CAAC;AAED,SAAS,aAAa,CAAC,QAAgB;IACrC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED,SAAS,mBAAmB;IAC1B,OAAO;QACL,MAAM,EAAE,KAAK;QACb,QAAQ,EAAE,KAAK;QACf,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE,kBAAkB;QAC3B,OAAO,EAAE,IAAI;QACb,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,EAAE;QACV,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;KACtB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,EAAE,GAAG,iBAAiB;IAEtB,OAAO;QACL,EAAE;QACF,UAAU,EAAE,SAAS;QACrB,KAAK,CAAC,GAAG;YACP,IAAI,QAAQ,GAAG,mBAAmB,EAAE,CAAC;YACrC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAmB,CAAC;YAE7C,MAAM,OAAO,GAAG,GAAoB,EAAE;gBACpC,MAAM,IAAI,GAAG,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBAE3D,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;oBACd,IAAI,EAAE,iBAAiB;oBACvB,MAAM,EAAE,EAAE;oBACV,OAAO,EAAE,IAAI;oBACb,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;iBACtB,CAAC,CAAC;gBAEH,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;oBACtC,QAAQ,CAAC,IAAI,CAAC,CAAC;gBACjB,CAAC;gBAED,OAAO,IAAI,CAAC;YACd,CAAC,CAAC;YAEF,MAAM,cAAc,GAAG,GAAW,EAAE;gBAClC,OAAO,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAClF,CAAC,CAAC;YAEF,OAAO;gBACL,KAAK,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe;oBACrC,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;oBAC3C,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;oBAEjC,QAAQ,GAAG;wBACT,MAAM,EAAE,IAAI;wBACZ,QAAQ,EAAE,KAAK;wBACf,QAAQ,EAAE,CAAC;wBACX,OAAO;wBACP,OAAO,EAAE,UAAU,CAAC,EAAE;wBACtB,UAAU,EAAE,UAAU,CAAC,KAAK;wBAC5B,MAAM,EAAE,UAAU;wBAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;qBACtB,CAAC;oBAEF,OAAO,OAAO,EAAE,CAAC;gBACnB,CAAC;gBACD,QAAQ,CAAC,OAAO,EAAE,mBAAmB,EAAE,OAAO;oBAC5C,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;oBAE9E,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;wBACtB,MAAM,IAAI,KAAK,CAAC,0BAA0B,OAAO,EAAE,CAAC,CAAC;oBACvD,CAAC;oBAED,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM;yBACnC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC;yBACpB,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;oBAC5D,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;oBACjD,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;oBACrC,MAAM,QAAQ,GACZ,CAAC,cAAc,GAAG,CAAC,YAAY,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,aAAa,CAAC,mBAAmB,CAAC,CAAC;wBAClF,WAAW,CAAC;oBAEd,QAAQ,GAAG;wBACT,GAAG,QAAQ;wBACX,MAAM,EAAE,IAAI;wBACZ,QAAQ;wBACR,OAAO,EAAE,OAAO,IAAI,QAAQ,CAAC,OAAO;wBACpC,OAAO,EAAE,YAAY,CAAC,EAAE;wBACxB,UAAU,EAAE,YAAY,CAAC,KAAK;wBAC9B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;qBACtB,CAAC;oBAEF,OAAO,OAAO,EAAE,CAAC;gBACnB,CAAC;gBACD,QAAQ,CAAC,OAAO,GAAG,kBAAkB;oBACnC,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;oBAEtE,QAAQ,GAAG;wBACT,GAAG,QAAQ;wBACX,MAAM,EAAE,KAAK;wBACb,QAAQ,EAAE,IAAI;wBACd,QAAQ,EAAE,CAAC;wBACX,OAAO;wBACP,OAAO,EAAE,SAAS,EAAE,EAAE,IAAI,IAAI;wBAC9B,UAAU,EAAE,SAAS,EAAE,KAAK,IAAI,IAAI;wBACpC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;qBACtB,CAAC;oBAEF,OAAO,OAAO,EAAE,CAAC;gBACnB,CAAC;gBACD,WAAW;oBACT,OAAO,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvD,CAAC;gBACD,SAAS,CAAC,QAAQ;oBAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;oBAExB,OAAO,GAAG,EAAE;wBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;oBAC7B,CAAC,CAAC;gBACJ,CAAC;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/pointer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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;
+}
+export declare function createPointerAdapter(id?: string): AdapterRegistration<PointerAdapterApi>;
+//# sourceMappingURL=pointer.d.ts.map

package/dist/pointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.d.ts","sourceRoot":"","sources":["../src/pointer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,WAAW,EAAE,UAAU,GAAG,YAAY,CAAC;CACxC;AAED,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,WAAW,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,UAAU,GAAG,YAAY,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,MAAM,EAAE,uBAAuB,GAAG,MAAM,IAAI,CAAC;IACxD,WAAW,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAAC;IAC3D,KAAK,IAAI,IAAI,CAAC;CACf;AAqBD,wBAAgB,oBAAoB,CAClC,EAAE,SAAoB,GACrB,mBAAmB,CAAC,iBAAiB,CAAC,CAqIxC"}