@ankhorage/zora 25.7.0 → 25.8.0

package/src/capabilities/index.test.ts

@@ -1,9 +1,11 @@
 import { readFileSync } from 'node:fs';
 
-import { isCapability } from '@ankhorage/contracts/capabilities';
+import { isCapability, isCapabilityId } from '@ankhorage/capability';
+import type { Capability } from '@ankhorage/contracts/capability';
 import { isRecord } from '@ankhorage/utility/object';
 import { expect, test } from 'bun:test';
 
+import { ZORA_COMPONENT_META } from '../features/registry';
 import { CAPABILITIES } from './index';
 
 const packageJson: unknown = JSON.parse(
@@ -13,11 +15,66 @@ const packageCapabilities =
   isRecord(packageJson) && isRecord(packageJson.ankh) ? packageJson.ankh.capabilities : undefined;
 
 test('publishes valid, uniquely identified canonical ZORA capabilities', () => {
-  expect(CAPABILITIES).toHaveLength(2);
   expect(CAPABILITIES.every(isCapability)).toBe(true);
   expect(new Set(CAPABILITIES.map((capability) => capability.id)).size).toBe(CAPABILITIES.length);
 });
 
+test('projects each direct-manifest event metadata entry into one canonical event capability', () => {
+  const metadataEvents = Object.values(ZORA_COMPONENT_META)
+    .filter((component) => component.directManifestNode)
+    .flatMap((component) => Object.values(component.events ?? {}));
+  const eventCapabilities = CAPABILITIES.filter((capability) => capability.access.includes('emit'));
+
+  expect(eventCapabilities).toHaveLength(
+    new Set(metadataEvents.map((event) => event.eventType)).size,
+  );
+  const eventCapabilitiesById = new Map<Capability['id'], Capability>(
+    eventCapabilities.map((capability) => [capability.id, capability]),
+  );
+
+  for (const event of metadataEvents) {
+    if (!isCapabilityId(event.eventType)) throw new Error(`Invalid event id: ${event.eventType}`);
+    const capability = eventCapabilitiesById.get(event.eventType);
+    expect(capability?.owner).toBe('@ankhorage/zora');
+    expect(capability?.access).toEqual(['emit']);
+    expect(capability?.binding).toEqual({ kind: 'event', bindableAs: ['source'] });
+    expect(capability?.label).toBe(event.label);
+    expect(capability?.description).toBe(event.description);
+  }
+});
+
+test('projects event payload metadata into matching output schemas', () => {
+  const eventCapabilities = new Map<Capability['id'], Capability>(
+    CAPABILITIES.filter((capability) => capability.access.includes('emit')).map((capability) => [
+      capability.id,
+      capability,
+    ]),
+  );
+
+  for (const component of Object.values(ZORA_COMPONENT_META)) {
+    if (!component.directManifestNode) continue;
+    for (const event of Object.values(component.events ?? {})) {
+      if (!isCapabilityId(event.eventType)) throw new Error(`Invalid event id: ${event.eventType}`);
+      const capability = eventCapabilities.get(event.eventType);
+      const schema = capability?.output?.schema;
+      expect(schema?.type).toBe('object');
+
+      for (const field of event.payloadFields ?? []) {
+        if (field.path.includes('.')) continue;
+        const fieldSchema = Object.entries(schema?.properties ?? {}).find(
+          ([fieldName]) => fieldName === field.path,
+        )?.[1];
+        expect(fieldSchema?.type).toBe(
+          field.type === 'record' ? 'object' : field.type === 'unknown' ? undefined : field.type,
+        );
+        expect(fieldSchema?.additionalProperties).toBe(field.type === 'record' ? true : undefined);
+        expect(fieldSchema?.title).toBe(field.label);
+        expect(fieldSchema?.description).toBe(field.description);
+      }
+    }
+  }
+});
+
 test('keeps Ankh package metadata identical to the canonical catalog', () => {
   expect(Array.isArray(packageCapabilities)).toBe(true);
   if (!Array.isArray(packageCapabilities)) {
@@ -37,18 +94,33 @@ test('exports the catalog from the public capabilities subpath', async () => {
 });
 
 test('preserves the executable action semantics of ZORA provider capabilities', () => {
-  expect(CAPABILITIES).toEqual([
-    expect.objectContaining({
-      id: 'zora.create',
-      owner: '@ankhorage/zora',
-      access: ['invoke'],
-      binding: { kind: 'action', bindableAs: ['target'] },
-    }),
-    expect.objectContaining({
-      id: 'zora.sync',
-      owner: '@ankhorage/zora',
-      access: ['invoke'],
-      binding: { kind: 'action', bindableAs: ['target'] },
-    }),
+  const actions = CAPABILITIES.filter((capability) => capability.access.includes('invoke'));
+  expect(actions.map((capability) => capability.id)).toEqual(['zora.create', 'zora.sync']);
+  expect(actions.every((capability) => capability.binding.kind === 'action')).toBe(true);
+  expect(actions.every((capability) => capability.binding.bindableAs.includes('target'))).toBe(
+    true,
+  );
+});
+
+test('built public capability entrypoint imports under Node ESM', async () => {
+  const subprocess = Bun.spawn(
+    [
+      'node',
+      '--input-type=module',
+      '-e',
+      "import('./dist/capabilities/index.js').then(({ CAPABILITIES }) => { if (!Array.isArray(CAPABILITIES)) process.exit(1); });",
+    ],
+    {
+      cwd: process.cwd(),
+      stderr: 'pipe',
+      stdout: 'pipe',
+    },
+  );
+  const [exitCode, stderr] = await Promise.all([
+    subprocess.exited,
+    new Response(subprocess.stderr).text(),
   ]);
+
+  expect(stderr).toBe('');
+  expect(exitCode).toBe(0);
 });

package/src/capabilities/index.ts

@@ -1,4 +1,6 @@
-import type { Capability } from '@ankhorage/contracts/capabilities';
+import type { Capability } from '@ankhorage/contracts/capability';
+
+import { createEventCapabilities } from '../features/registry/createEventCapabilities.js';
 
 export const CAPABILITIES = [
   {
@@ -60,4 +62,5 @@ export const CAPABILITIES = [
       },
     },
   },
-] as const satisfies readonly Capability[];
+  ...createEventCapabilities(),
+] satisfies readonly Capability[];

package/src/cli/index.test.ts

@@ -6,7 +6,9 @@ import provider from './index';
 test('publishes ZORA create and sync through the Ankh provider', () => {
   expect(provider.id).toBe('@ankhorage/zora');
   expect(provider.category).toBe('zora');
-  expect(provider.capabilities).toBe(CAPABILITIES);
+  expect(provider.capabilities).toEqual(
+    CAPABILITIES.filter((capability) => capability.access.includes('invoke')),
+  );
   expect(provider.commands).toEqual([
     {
       path: ['create'],
@@ -24,9 +26,9 @@ test('publishes ZORA create and sync through the Ankh provider', () => {
   expect(provider.handlers[1]?.path).toEqual(['sync']);
 });
 
-test('maps every provider command to one canonical capability independent of catalog order', () => {
+test('maps every provider command to one executable canonical capability independent of catalog order', () => {
   const commandCapabilityIds = provider.commands.map((command) => command.capability);
-  const capabilityIds = CAPABILITIES.map((capability) => capability.id);
+  const capabilityIds = provider.capabilities.map((capability) => capability.id);
 
   expect(new Set(commandCapabilityIds).size).toBe(commandCapabilityIds.length);
   expect(new Set(commandCapabilityIds)).toEqual(new Set(capabilityIds));

package/src/cli/index.ts

@@ -3,7 +3,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import type { AnkhRuntimeCommandProvider } from '@ankhorage/ankh';
-import type { Capability } from '@ankhorage/contracts/capabilities';
+import type { Capability } from '@ankhorage/contracts/capability';
 
 import { CAPABILITIES } from '../capabilities';
 import { create } from './commands/create';
@@ -19,12 +19,15 @@ const SYNC_COMMAND = {
   capability: 'zora.sync' satisfies Capability['id'],
   summary: 'Regenerate the declared ZORA web materialization.',
 } as const;
+const COMMAND_CAPABILITIES = CAPABILITIES.filter((capability) =>
+  capability.access.includes('invoke'),
+);
 
 const provider = {
   id: '@ankhorage/zora',
   category: 'zora',
   version: readPackageVersion(),
-  capabilities: CAPABILITIES,
+  capabilities: COMMAND_CAPABILITIES,
   commands: [CREATE_COMMAND, SYNC_COMMAND],
   handlers: [
     {

package/src/features/grid-interactions/adapters/inbound/GridInteractions.test.tsx

@@ -0,0 +1,143 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import type { GridInteractions as GridInteractionsComponent } from './GridInteractions';
+
+const webDistRoot = join(import.meta.dir, '../../../../../web-dist');
+
+/*** Loads the independently bundled RNW interaction adapter through its public artifact path. */
+function loadGridInteractions() {
+  return import(
+    pathToFileURL(join(webDistRoot, 'components/grid-interactions/index.js')).href
+  ) as Promise<{ GridInteractions: typeof GridInteractionsComponent }>;
+}
+
+test('keeps a mounted RNW keyboard boundary current across parent rerenders', async () => {
+  const browser = new Window();
+  const restore = installBrowserGlobals(browser);
+  const host = document.createElement('div');
+  document.body.append(host);
+  const root = createRoot(host);
+  const { GridInteractions } = await loadGridInteractions();
+  const firstIntents: unknown[] = [];
+  const secondIntents: unknown[] = [];
+  const render = (
+    onIntent: (intent: unknown) => void,
+    interactionPolicy?: 'passive',
+    resizeHandle?: 'bottom-right',
+  ) => (
+    <GridInteractions
+      interactionPolicy={interactionPolicy}
+      items={[{ height: 2, id: 'a', width: 3, x: 1, y: 1 }]}
+      onIntent={onIntent}
+      selectedIds={['a']}
+      testID="grid-interactions"
+      resizeHandle={resizeHandle}
+      viewport={{
+        height: 100,
+        offsetX: 0,
+        offsetY: 0,
+        pixelsPerUnitX: 2,
+        pixelsPerUnitY: 4,
+        width: 100,
+      }}
+    >
+      <span>nested target</span>
+    </GridInteractions>
+  );
+
+  try {
+    await renderGridInteractions(
+      root,
+      render((intent) => firstIntents.push(intent)),
+    );
+    await renderGridInteractions(
+      root,
+      render((intent) => secondIntents.push(intent)),
+    );
+
+    const keyboard = host.querySelector<HTMLElement>(
+      '[aria-label="Grid interaction keyboard controls"]',
+    );
+    if (!keyboard) throw new Error('Missing keyboard interaction proxy');
+    const resize = new browser.KeyboardEvent('keydown', {
+      altKey: true,
+      bubbles: true,
+      cancelable: true,
+      key: 'ArrowRight',
+    });
+    await dispatch(keyboard, resize);
+    const acceleratedMove = new browser.KeyboardEvent('keydown', {
+      bubbles: true,
+      cancelable: true,
+      key: 'ArrowDown',
+      shiftKey: true,
+    });
+    await dispatch(keyboard, acceleratedMove);
+    await renderGridInteractions(
+      root,
+      render((intent) => secondIntents.push(intent), 'passive'),
+    );
+    const passiveKey = new browser.KeyboardEvent('keydown', { bubbles: true, key: 'ArrowLeft' });
+    await dispatch(keyboard, passiveKey);
+    expect(keyboard.getAttribute('tabindex')).toBe('-1');
+
+    expect(firstIntents).toEqual([]);
+    expect(secondIntents).toEqual([
+      { type: 'resize', itemIds: ['a'], rects: [{ height: 2, id: 'a', width: 4, x: 1, y: 1 }] },
+      { type: 'move', itemIds: ['a'], rects: [{ height: 2, id: 'a', width: 3, x: 1, y: 11 }] },
+    ]);
+    expect(resize.defaultPrevented).toBe(true);
+    expect(acceleratedMove.defaultPrevented).toBe(true);
+    expect(passiveKey.defaultPrevented).toBe(false);
+  } finally {
+    await act(() => Promise.resolve().then(() => root.unmount()));
+    host.remove();
+    browser.close();
+    restore();
+  }
+});
+
+/*** Installs the DOM globals that the independently bundled RNW adapter requires. */
+function installBrowserGlobals(browser: Window): () => void {
+  const keys = [
+    'window',
+    'document',
+    'Node',
+    'navigator',
+    'ShadowRoot',
+    'IS_REACT_ACT_ENVIRONMENT',
+  ] as const;
+  const previous = keys.map(
+    (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+  );
+  Object.assign(globalThis, {
+    IS_REACT_ACT_ENVIRONMENT: true,
+    Node: browser.Node,
+    ShadowRoot: browser.ShadowRoot,
+    document: browser.document,
+    navigator: browser.navigator,
+    window: browser,
+  });
+  return () => {
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  };
+}
+
+/*** Flushes one mounted RNW render before the next synthetic input event. */
+function renderGridInteractions(root: ReturnType<typeof createRoot>, component: React.ReactNode) {
+  return act(() => Promise.resolve().then(() => root.render(component)));
+}
+
+/*** Dispatches one browser input event through React's RNW adapter boundary. */
+function dispatch(target: HTMLElement, event: Event) {
+  return act(() => Promise.resolve().then(() => target.dispatchEvent(event)));
+}

package/src/features/grid-interactions/adapters/inbound/GridInteractions.tsx

@@ -0,0 +1,79 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import type {
+  GridInteractionsController,
+  GridInteractionsProps,
+} from '../../../../types/grid-interactions';
+import { createGridInteractionsController } from '../../application/createGridInteractionsController';
+import { createGridInteractionsPointerQueue } from './createGridInteractionsPointerQueue';
+import { GridInteractionsKeyboardProxy } from './GridInteractionsKeyboardProxy';
+import { resolveGridInteractionPointer } from './resolveGridInteractionPointer';
+
+/*** Adapts native responder and keyboard events to the controlled grid interaction boundary. */
+export function GridInteractions({
+  children,
+  interactionPolicy,
+  resizeHandle,
+  testID,
+  ...props
+}: GridInteractionsProps) {
+  const controllerProps = React.useMemo(
+    () => ({ ...props, interactionPolicy }),
+    [interactionPolicy, props],
+  );
+  const [controller] = React.useState<GridInteractionsController>(() =>
+    createGridInteractionsController(controllerProps),
+  );
+  const surfaceRef = React.useRef<View>(null);
+  const [pointerQueue] = React.useState(() => createGridInteractionsPointerQueue());
+  React.useLayoutEffect(() => controller.update(controllerProps), [controller, controllerProps]);
+  React.useLayoutEffect(() => {
+    pointerQueue.activate();
+    return () => {
+      pointerQueue.dispose();
+      controller.cancel();
+    };
+  }, [controller, pointerQueue]);
+  const withPointer = (
+    event: Parameters<typeof resolveGridInteractionPointer>[0],
+    handlePointer: (pointer: ReturnType<typeof resolveGridInteractionPointer>) => void,
+  ) => {
+    const surface = surfaceRef.current;
+    if (!surface) return;
+    const eventSnapshot = { nativeEvent: { ...event.nativeEvent } };
+    pointerQueue.enqueue(surface, (origin) =>
+      handlePointer(resolveGridInteractionPointer(eventSnapshot, origin)),
+    );
+  };
+  const enabled = interactionPolicy !== 'passive';
+
+  return (
+    <View
+      accessible
+      accessibilityLabel="Grid interaction surface"
+      accessibilityRole="adjustable"
+      ref={surfaceRef}
+      testID={testID}
+      onResponderGrant={(event) =>
+        withPointer(event, (pointer) => controller.begin(pointer, resizeHandle))
+      }
+      onResponderMove={(event) => withPointer(event, controller.move)}
+      onResponderRelease={(event) => withPointer(event, controller.end)}
+      onResponderTerminate={() => {
+        pointerQueue.cancel();
+        controller.cancel();
+      }}
+      onStartShouldSetResponder={() => enabled}
+    >
+      <GridInteractionsKeyboardProxy
+        enabled={enabled}
+        onKeyDown={(key, keyPointer) => {
+          return controller.keyDown(key, keyPointer);
+        }}
+      >
+        {children}
+      </GridInteractionsKeyboardProxy>
+    </View>
+  );
+}

package/src/features/grid-interactions/adapters/inbound/GridInteractionsKeyboardProxy.native.tsx

@@ -0,0 +1,14 @@
+import type React from 'react';
+
+import type { GridInteractionPointer } from '../../../../types/grid-interactions';
+
+/*** Leaves native accessibility focus untouched where browser keyboard events are unavailable. */
+export function GridInteractionsKeyboardProxy({ children }: GridInteractionsKeyboardProxyProps) {
+  return <>{children}</>;
+}
+
+interface GridInteractionsKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly enabled: boolean;
+  readonly onKeyDown: (key: string, pointer: GridInteractionPointer) => boolean;
+}

package/src/features/grid-interactions/adapters/inbound/GridInteractionsKeyboardProxy.tsx

@@ -0,0 +1 @@
+export { GridInteractionsKeyboardProxy } from './GridInteractionsKeyboardProxy.native';

package/src/features/grid-interactions/adapters/inbound/GridInteractionsKeyboardProxy.web.tsx

@@ -0,0 +1,41 @@
+import type React from 'react';
+
+import type { GridInteractionPointer } from '../../../../types/grid-interactions';
+
+/*** Adapts web keyboard movement and resize commands without changing native responder behavior. */
+export function GridInteractionsKeyboardProxy({
+  children,
+  enabled,
+  onKeyDown,
+}: GridInteractionsKeyboardProxyProps) {
+  return (
+    <div
+      aria-label="Grid interaction keyboard controls"
+      onKeyDown={(event) => {
+        if (!enabled) return;
+        if (
+          onKeyDown(event.key, {
+            altKey: event.altKey,
+            ctrlKey: event.ctrlKey,
+            metaKey: event.metaKey,
+            shiftKey: event.shiftKey,
+            x: 0,
+            y: 0,
+          })
+        ) {
+          event.preventDefault();
+        }
+      }}
+      style={{ display: 'contents' }}
+      tabIndex={enabled ? 0 : -1}
+    >
+      {children}
+    </div>
+  );
+}
+
+interface GridInteractionsKeyboardProxyProps {
+  readonly children: React.ReactNode;
+  readonly enabled: boolean;
+  readonly onKeyDown: (key: string, pointer: GridInteractionPointer) => boolean;
+}

package/src/features/grid-interactions/adapters/inbound/createGridInteractionsPointerQueue.test.ts

@@ -0,0 +1,98 @@
+import { expect, test } from 'bun:test';
+
+import { createGridInteractionsPointerQueue } from './createGridInteractionsPointerQueue';
+import { resolveGridInteractionPointer } from './resolveGridInteractionPointer';
+
+test('invalidates pending native responder callbacks after cancellation', () => {
+  const callbacks: ((x: number, y: number) => void)[] = [];
+  const origins: unknown[] = [];
+  const queue = createGridInteractionsPointerQueue();
+  const surface = {
+    measureInWindow: (callback: (x: number, y: number) => void) => callbacks.push(callback),
+  };
+
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  queue.cancel();
+  callbacks[0]?.(10, 20);
+
+  expect(origins).toEqual([]);
+  expect(callbacks).toHaveLength(1);
+});
+
+test('invalidates an active native responder measurement across unmount and remount', () => {
+  const callbacks: ((x: number, y: number) => void)[] = [];
+  const origins: unknown[] = [];
+  const queue = createGridInteractionsPointerQueue();
+  const surface = {
+    measureInWindow: (callback: (x: number, y: number) => void) => callbacks.push(callback),
+  };
+
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  queue.dispose();
+  queue.activate();
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  callbacks[1]?.(30, 40);
+  callbacks[0]?.(10, 20);
+
+  expect(origins).toEqual([{ x: 30, y: 40 }]);
+});
+
+test('retires a canceled measurement slot without waiting for its callback', () => {
+  const callbacks: ((x: number, y: number) => void)[] = [];
+  const origins: unknown[] = [];
+  const queue = createGridInteractionsPointerQueue();
+  const surface = {
+    measureInWindow: (callback: (x: number, y: number) => void) => callbacks.push(callback),
+  };
+
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  queue.cancel();
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  callbacks[1]?.(30, 40);
+  queue.enqueue(surface, (origin) => origins.push(origin));
+  callbacks[0]?.(10, 20);
+  callbacks[2]?.(50, 60);
+
+  expect(origins).toEqual([
+    { x: 30, y: 40 },
+    { x: 50, y: 60 },
+  ]);
+});
+
+test('uses the latest RNW surface origin for each serialized pointer', () => {
+  const origins = [
+    { left: 10, top: 20 },
+    { left: 15, top: 25 },
+  ];
+  const resolvedOrigins: unknown[] = [];
+  const queue = createGridInteractionsPointerQueue();
+  const surface = {
+    getBoundingClientRect: () => origins.shift(),
+  };
+
+  queue.enqueue(surface, (origin) => resolvedOrigins.push(origin));
+  queue.enqueue(surface, (origin) => resolvedOrigins.push(origin));
+
+  expect(resolvedOrigins).toEqual([
+    { x: 10, y: 20 },
+    { x: 15, y: 25 },
+  ]);
+});
+
+test('preserves native responder-local coordinates while measuring asynchronously', () => {
+  const callbacks: ((x: number, y: number) => void)[] = [];
+  const pointers: unknown[] = [];
+  const queue = createGridInteractionsPointerQueue();
+  const surface = {
+    measureInWindow: (callback: (x: number, y: number) => void) => callbacks.push(callback),
+  };
+  const event = { nativeEvent: { locationX: 7, locationY: 9 } };
+
+  queue.enqueue(surface, (origin) => {
+    pointers.push(resolveGridInteractionPointer(event, origin));
+  });
+  callbacks[0]?.(10, 20);
+
+  expect(pointers).toEqual([{ x: 7, y: 9 }]);
+});

package/src/features/grid-interactions/adapters/inbound/createGridInteractionsPointerQueue.ts

@@ -0,0 +1,94 @@
+/*** Serializes native responder measurements and invalidates work from canceled interaction lifecycles. */
+export function createGridInteractionsPointerQueue() {
+  let active = true;
+  let generation = 0;
+  let measuring = false;
+  let measurementId = 0;
+  let activeMeasurementId: number | undefined;
+  let pending: readonly GridInteractionPointerWork[] = [];
+
+  const processNext = () => {
+    if (measuring) return;
+    const pointerWork = pending.at(0);
+    if (pointerWork === undefined) return;
+    pending = pending.slice(1);
+    measuring = true;
+    const currentMeasurementId = ++measurementId;
+    activeMeasurementId = currentMeasurementId;
+    let settled = false;
+    measureSurfaceOrigin(pointerWork.surface, (origin) => {
+      if (settled) return;
+      settled = true;
+      if (activeMeasurementId !== currentMeasurementId) return;
+      try {
+        if (active && pointerWork.generation === generation) {
+          pointerWork.handleOrigin(origin);
+        }
+      } finally {
+        activeMeasurementId = undefined;
+        measuring = false;
+        processNext();
+      }
+    });
+  };
+
+  return {
+    activate: () => {
+      active = true;
+    },
+    enqueue: (
+      surface: GridInteractionSurface,
+      handleOrigin: (origin: GridInteractionSurfaceOrigin) => void,
+    ) => {
+      if (!active) return;
+      pending = [...pending, { generation, handleOrigin, surface }];
+      processNext();
+    },
+    cancel: () => {
+      generation += 1;
+      pending = [];
+      activeMeasurementId = undefined;
+      measuring = false;
+    },
+    dispose: () => {
+      active = false;
+      generation += 1;
+      pending = [];
+      activeMeasurementId = undefined;
+      measuring = false;
+    },
+  };
+}
+
+interface GridInteractionPointerWork {
+  readonly generation: number;
+  readonly handleOrigin: (origin: GridInteractionSurfaceOrigin) => void;
+  readonly surface: GridInteractionSurface;
+}
+
+interface GridInteractionSurface {
+  readonly getBoundingClientRect?: () => Pick<DOMRect, 'left' | 'top'>;
+  readonly measureInWindow?: (callback: (x: number, y: number) => void) => void;
+}
+
+interface GridInteractionSurfaceOrigin {
+  readonly x: number;
+  readonly y: number;
+}
+
+/*** Resolves the current surface origin through RNW DOM geometry or native asynchronous measurement. */
+function measureSurfaceOrigin(
+  surface: GridInteractionSurface,
+  onOrigin: (origin: GridInteractionSurfaceOrigin) => void,
+) {
+  const rect = surface.getBoundingClientRect?.();
+  if (rect) {
+    onOrigin({ x: rect.left, y: rect.top });
+    return;
+  }
+  if (surface.measureInWindow !== undefined) {
+    surface.measureInWindow((x, y) => onOrigin({ x, y }));
+    return;
+  }
+  onOrigin({ x: 0, y: 0 });
+}