@ankhorage/zora 25.6.0 → 25.6.2

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/matrix-grid/adapters/inbound/MatrixGrid.test.tsx

@@ -0,0 +1,232 @@
+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';
+
+const browserKeys = [
+  'window',
+  'document',
+  'Node',
+  'navigator',
+  'ShadowRoot',
+  'IS_REACT_ACT_ENVIRONMENT',
+] as const;
+const webDistRoot = join(import.meta.dir, '../../../../../web-dist');
+const load = (path: string) => import(pathToFileURL(join(webDistRoot, path)).href);
+
+/*** Mount MatrixGrid through React Native Web and restore the ambient DOM after each assertion. */
+async function withMatrixDom(assertion: (host: HTMLElement, browser: Window) => Promise<void>) {
+  const browser = new Window();
+  const previous = browserKeys.map(
+    (key) => [key, Object.getOwnPropertyDescriptor(globalThis, key)] as const,
+  );
+  Object.assign(globalThis, {
+    IS_REACT_ACT_ENVIRONMENT: true,
+    window: browser,
+    document: browser.document,
+    Node: browser.Node,
+    navigator: browser.navigator,
+    ShadowRoot: browser.ShadowRoot,
+  });
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  try {
+    await assertion(host, browser);
+  } finally {
+    browser.close();
+    for (const [key, descriptor] of previous) {
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  }
+}
+
+const layout = {
+  columns: Array.from({ length: 100 }, (_, index) => ({
+    id: `column-${index}`,
+    size: 10 + (index % 3),
+  })),
+  rows: Array.from({ length: 100 }, (_, index) => ({ id: `row-${index}`, size: 8 + (index % 4) })),
+};
+
+const cells = layout.rows.flatMap((row) =>
+  layout.columns.map((column) => ({
+    id: `${row.id}-${column.id}`,
+    rowId: row.id,
+    columnId: column.id,
+  })),
+);
+
+type MatrixGridComponent = React.ComponentType<{
+  readonly cells: typeof cells;
+  readonly height: number;
+  readonly layout: typeof layout;
+  readonly onSelectionChange?: (ids: readonly string[]) => void;
+  readonly onViewportChange?: (viewport: unknown) => void;
+  readonly renderCell: (cell: { readonly id: string }) => React.ReactNode;
+  readonly selectedCellIds?: readonly string[];
+  readonly selectionMode?: 'multi';
+  readonly testID: string;
+  readonly viewport?: {
+    readonly height: number;
+    readonly offsetX: number;
+    readonly offsetY: number;
+    readonly pixelsPerUnitX: number;
+    readonly pixelsPerUnitY: number;
+    readonly width: number;
+  };
+  readonly width: number;
+  readonly zoomX?: number;
+  readonly zoomY?: number;
+}>;
+
+type ZoraProviderComponent = React.ComponentType<{ readonly children: React.ReactNode }>;
+
+test('mounts only visible sparse cells with independent axis zoom and preserves native-web selection', async () => {
+  await withMatrixDom(async (host, browser) => {
+    const selected: (readonly string[])[] = [];
+    const root = createRoot(host);
+    const { MatrixGrid } = (await load('components/matrix-grid/MatrixGrid.js')) as {
+      MatrixGrid: MatrixGridComponent;
+    };
+    const { ZoraProvider } = (await load('runtime/ZoraProvider.js')) as {
+      ZoraProvider: ZoraProviderComponent;
+    };
+    try {
+      act(() =>
+        root.render(
+          <ZoraProvider>
+            <MatrixGrid
+              cells={cells}
+              height={96}
+              layout={layout}
+              selectedCellIds={[]}
+              selectionMode="multi"
+              testID="matrix"
+              viewport={{
+                height: 96,
+                offsetX: 0,
+                offsetY: 0,
+                pixelsPerUnitX: 2,
+                pixelsPerUnitY: 3,
+                width: 120,
+              }}
+              width={120}
+              onSelectionChange={(ids) => selected.push(ids)}
+              renderCell={(cell) => <span>{cell.id}</span>}
+            />
+          </ZoraProvider>,
+        ),
+      );
+      const mountedCells = host.querySelectorAll('[data-testid^="matrix-cell-"]');
+      expect(cells).toHaveLength(10_000);
+      expect(mountedCells.length).toBeGreaterThan(1);
+      expect(mountedCells.length).toBeLessThan(100);
+      const target = host.querySelector('[data-testid="matrix-cell-row-1-column-1"]');
+      expect(target).not.toBeNull();
+      expect(target?.parentElement?.getAttribute('style')).toContain('left: 20px');
+      expect(target?.parentElement?.getAttribute('style')).toContain('top: 24px');
+      void act(() => target?.dispatchEvent(new browser.MouseEvent('click', { bubbles: true })));
+      expect(selected).toEqual([['row-1-column-1']]);
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});
+
+test('does not propose controlled viewports on mount or fresh parent callback identities', async () => {
+  await withMatrixDom(async (host) => {
+    const proposals: unknown[] = [];
+    const root = createRoot(host);
+    const { MatrixGrid } = (await load('components/matrix-grid/MatrixGrid.js')) as {
+      MatrixGrid: MatrixGridComponent;
+    };
+    const { ZoraProvider } = (await load('runtime/ZoraProvider.js')) as {
+      ZoraProvider: ZoraProviderComponent;
+    };
+    const render = () => (
+      <ZoraProvider>
+        <MatrixGrid
+          cells={cells}
+          height={96}
+          layout={layout}
+          testID="controlled-matrix"
+          viewport={{
+            height: 96,
+            offsetX: 0,
+            offsetY: 0,
+            pixelsPerUnitX: 2,
+            pixelsPerUnitY: 3,
+            width: 120,
+          }}
+          width={120}
+          onViewportChange={(proposal) => proposals.push(proposal)}
+          renderCell={(cell) => <span>{cell.id}</span>}
+        />
+      </ZoraProvider>
+    );
+    try {
+      act(() => root.render(render()));
+      act(() => root.render(render()));
+      expect(proposals).toEqual([]);
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});
+
+test('proposes an uncontrolled horizontal pan in world units while retaining independent axis zoom', async () => {
+  await withMatrixDom(async (host, browser) => {
+    const proposals: unknown[] = [];
+    const root = createRoot(host);
+    const { MatrixGrid } = (await load('components/matrix-grid/MatrixGrid.js')) as {
+      MatrixGrid: MatrixGridComponent;
+    };
+    const { ZoraProvider } = (await load('runtime/ZoraProvider.js')) as {
+      ZoraProvider: ZoraProviderComponent;
+    };
+    try {
+      act(() =>
+        root.render(
+          <ZoraProvider>
+            <MatrixGrid
+              cells={cells}
+              height={96}
+              layout={layout}
+              testID="uncontrolled-matrix"
+              width={120}
+              zoomX={2}
+              zoomY={3}
+              onViewportChange={(proposal) => proposals.push(proposal)}
+              renderCell={(cell) => <span>{cell.id}</span>}
+            />
+          </ZoraProvider>,
+        ),
+      );
+      const horizontalScroll = host.querySelector(
+        '[data-testid="uncontrolled-matrix-horizontal-scroll"]',
+      );
+      if (!horizontalScroll) throw new Error('Missing MatrixGrid horizontal scroll viewport.');
+      horizontalScroll.scrollLeft = 40;
+      await act(async () => {
+        horizontalScroll.dispatchEvent(new browser.Event('scroll', { bubbles: true }));
+        await new Promise<void>((resolve) => browser.setTimeout(resolve, 200));
+      });
+      expect(proposals).toEqual([
+        {
+          height: 96,
+          offsetX: 20,
+          offsetY: 0,
+          pixelsPerUnitX: 2,
+          pixelsPerUnitY: 3,
+          width: 120,
+        },
+      ]);
+    } finally {
+      act(() => root.unmount());
+    }
+  });
+});

package/src/features/matrix-grid/adapters/inbound/MatrixGrid.tsx

@@ -0,0 +1,142 @@
+import {
+  getVisibleMatrixCells,
+  type GridMatrixCellPlacement,
+  type GridViewport,
+} from '@ankhorage/grid-view';
+import { Pressable } from '@ankhorage/surface';
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import type { MatrixGridProps } from '../../../../types/matrix-grid';
+import { GridView } from '../../../grid-view/public';
+import { resolveSelectionEventIntent } from '../../../selection/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
+import { resolveMatrixGridContentSize } from '../../application/resolveMatrixGridContentSize';
+import { resolveMatrixGridSelection } from '../../application/resolveMatrixGridSelection';
+
+/*** Compose the canonical GridView around released sparse matrix placement and culling geometry. */
+function MatrixGridInner({
+  accessibilityLabel = 'Matrix grid',
+  cells,
+  height,
+  interactionPolicy,
+  layout,
+  onSelectionChange,
+  onViewportChange,
+  overscanPixels = 160,
+  renderCell,
+  selectedCellIds = [],
+  selectionMode = 'single',
+  testID,
+  viewport: controlledViewport,
+  width,
+  zoomX = 1,
+  zoomY = 1,
+}: MatrixGridProps) {
+  const { theme } = useZoraTheme();
+  const contentSize = React.useMemo(() => resolveMatrixGridContentSize(layout), [layout]);
+  const initialViewport = React.useMemo<GridViewport>(
+    () => ({ height, offsetX: 0, offsetY: 0, pixelsPerUnitX: zoomX, pixelsPerUnitY: zoomY, width }),
+    [height, width, zoomX, zoomY],
+  );
+  const [uncontrolledViewport, setUncontrolledViewport] = React.useState(initialViewport);
+  const viewport = controlledViewport ?? uncontrolledViewport;
+  const visibleCells = React.useMemo(
+    () => getVisibleMatrixCells(layout, cells, viewport, overscanPixels),
+    [cells, layout, overscanPixels, viewport],
+  );
+
+  const visibleCellById = React.useMemo(
+    () => new Map(visibleCells.map((cell) => [cell.id, cell])),
+    [visibleCells],
+  );
+
+  const handleViewportChange = React.useCallback(
+    (proposal: GridViewport) => {
+      if (controlledViewport === undefined) setUncontrolledViewport(proposal);
+      onViewportChange?.(proposal);
+    },
+    [controlledViewport, onViewportChange],
+  );
+
+  const activateCell = React.useCallback(
+    (cell: GridMatrixCellPlacement, event: unknown) => {
+      if (interactionPolicy === 'passive') return;
+      const intent = resolveSelectionEventIntent(event, 'pointer');
+      onSelectionChange?.(
+        resolveMatrixGridSelection(selectedCellIds, cell.id, intent, selectionMode),
+      );
+    },
+    [interactionPolicy, onSelectionChange, selectedCellIds, selectionMode],
+  );
+  return (
+    <View accessibilityLabel={accessibilityLabel}>
+      <GridView
+        contentHeight={contentSize.height}
+        contentWidth={contentSize.width}
+        height={height}
+        interactionPolicy={interactionPolicy}
+        items={visibleCells}
+        overscanPixels={0}
+        renderItem={(item) => {
+          const cell = visibleCellById.get(item.id);
+          if (!cell) return null;
+          return renderMatrixCell(
+            cell,
+            selectedCellIds,
+            theme.semantics.neutral.divider,
+            theme.colors.primary,
+            renderCell,
+            activateCell,
+            testID,
+          );
+        }}
+        testID={testID}
+        viewport={viewport}
+        width={width}
+        onViewportChange={handleViewportChange}
+      />
+    </View>
+  );
+}
+
+/*** Render one positioned sparse cell with native/web accessible selection semantics. */
+function renderMatrixCell(
+  cell: GridMatrixCellPlacement,
+  selectedCellIds: readonly string[],
+  dividerColor: string,
+  selectedColor: string,
+  renderCell: MatrixGridProps['renderCell'],
+  activateCell: (cell: GridMatrixCellPlacement, event: unknown) => void,
+  testID: string | undefined,
+) {
+  const selected = selectedCellIds.includes(cell.id);
+  return (
+    <Pressable
+      key={cell.id}
+      accessibilityLabel={`Cell ${cell.id}`}
+      accessibilityRole="button"
+      accessibilityState={{ selected }}
+      style={[
+        styles.cell,
+        {
+          borderColor: selected ? selectedColor : dividerColor,
+          height: '100%',
+          width: '100%',
+        },
+      ]}
+      testID={testID === undefined ? undefined : `${testID}-cell-${cell.id}`}
+      onPress={(event) => activateCell(cell, event)}
+    >
+      {renderCell(cell)}
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  cell: { borderWidth: 1, height: '100%', overflow: 'hidden', width: '100%' },
+});
+
+/*** A code-first generic sparse matrix grid; formulas and domain vocabulary remain external. */
+export const MatrixGrid = withZoraThemeScope(MatrixGridInner);

package/src/features/matrix-grid/application/resolveMatrixGridContentSize.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveMatrixGridContentSize } from './resolveMatrixGridContentSize';
+
+describe('resolveMatrixGridContentSize', () => {
+  test('sums variable matrix axes without materializing logical cells', () => {
+    expect(
+      resolveMatrixGridContentSize({
+        columns: [
+          { id: 'beat', size: 40 },
+          { id: 'bar', size: 60 },
+        ],
+        rows: [
+          { id: 'bass', size: 24 },
+          { id: 'lead', size: 36 },
+        ],
+      }),
+    ).toEqual({ height: 60, width: 100 });
+  });
+
+  test('rejects non-finite cumulative axis geometry through the published grid-view contract', () => {
+    expect(() =>
+      resolveMatrixGridContentSize({
+        columns: [
+          { id: 'left', size: Number.MAX_VALUE },
+          { id: 'right', size: Number.MAX_VALUE },
+        ],
+        rows: [{ id: 'row', size: 1 }],
+      }),
+    ).toThrow('Layout axis cumulative world coordinates must be finite.');
+  });
+});

package/src/features/matrix-grid/application/resolveMatrixGridContentSize.ts

@@ -0,0 +1,28 @@
+import {
+  getMatrixCellPlacement,
+  getVisibleMatrixCells,
+  type GridMatrixLayout,
+} from '@ankhorage/grid-view';
+
+/*** Resolve total sparse-matrix world extents without expanding its logical cells. */
+export function resolveMatrixGridContentSize(layout: GridMatrixLayout) {
+  const finalRow = layout.rows.at(-1);
+  const finalColumn = layout.columns.at(-1);
+  if (!finalRow || !finalColumn) {
+    getVisibleMatrixCells(layout, [], {
+      height: 1,
+      offsetX: 0,
+      offsetY: 0,
+      pixelsPerUnitX: 1,
+      pixelsPerUnitY: 1,
+      width: 1,
+    });
+    return { height: 0, width: 0 };
+  }
+  const finalCell = getMatrixCellPlacement(layout, {
+    id: 'matrix-grid-content-boundary',
+    rowId: finalRow.id,
+    columnId: finalColumn.id,
+  });
+  return { height: finalCell.y + finalCell.height, width: finalCell.x + finalCell.width };
+}

package/src/features/matrix-grid/application/resolveMatrixGridSelection.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveMatrixGridSelection } from './resolveMatrixGridSelection';
+
+describe('resolveMatrixGridSelection', () => {
+  test('preserves the canonical single and multi selection intent rules', () => {
+    expect(resolveMatrixGridSelection(['a'], 'b', 'toggle', 'single')).toEqual(['b']);
+    expect(resolveMatrixGridSelection(['a'], 'b', 'toggle', 'multi')).toEqual(['a', 'b']);
+  });
+});

package/src/features/matrix-grid/application/resolveMatrixGridSelection.ts

@@ -0,0 +1,15 @@
+import { applySelectionIntent, type SelectionIntent } from '@ankhorage/utility/selection';
+
+import type { SelectionMode } from '../../../types/selection';
+
+/*** Apply ZORA's canonical selection intent while retaining the configured selection mode. */
+export function resolveMatrixGridSelection(
+  selectedIds: readonly string[],
+  cellId: string,
+  intent: SelectionIntent,
+  mode: SelectionMode,
+): readonly string[] {
+  return mode === 'single'
+    ? applySelectionIntent(selectedIds, cellId, 'replace')
+    : applySelectionIntent(selectedIds, cellId, intent);
+}