@ankhorage/zora 21.0.22 → 21.1.0

package/src/features/game/meta/gameMeasurementProbeMeta.ts

@@ -0,0 +1,72 @@
+import type { ZoraComponentMeta } from '../../../types/authoring';
+
+/*** Describe a non-visual source/target geometry sampling adapter for one Game instance. */
+export const gameMeasurementProbeMeta = {
+  name: 'GameMeasurementProbe',
+  category: 'component',
+  description:
+    'Measures two registered game entities and reports their raw rendered bounds through a generic Game event.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Game measurement probe',
+    defaultProps: {
+      sourceId: 'source',
+      targetId: 'target',
+      eventType: 'game.measurement',
+      delayMs: 0,
+      enabled: true,
+    },
+  },
+  bindings: {
+    props: {
+      sourceId: { value: { type: 'string' }, acceptsFallback: true },
+      targetId: { value: { type: 'string' }, acceptsFallback: true },
+      eventType: { value: { type: 'string' }, acceptsFallback: true },
+      entityId: { value: { type: 'string' }, acceptsFallback: true },
+      delayMs: { value: { type: 'number' }, acceptsFallback: true },
+      enabled: { value: { type: 'boolean' }, acceptsFallback: true },
+    },
+  },
+  props: {
+    sourceId: {
+      type: 'string',
+      category: 'Measurement',
+      label: 'Source id',
+      authoring: { authority: 'instance' },
+    },
+    targetId: {
+      type: 'string',
+      category: 'Measurement',
+      label: 'Target id',
+      authoring: { authority: 'instance' },
+    },
+    eventType: {
+      type: 'string',
+      category: 'Measurement',
+      label: 'Event type',
+      default: 'game.measurement',
+      authoring: { authority: 'instance' },
+    },
+    entityId: {
+      type: 'string',
+      category: 'Measurement',
+      label: 'Game entity id',
+      authoring: { authority: 'instance' },
+    },
+    delayMs: {
+      type: 'number',
+      category: 'Measurement',
+      label: 'Delay (ms)',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    enabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Enabled',
+      default: true,
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/game/meta/gameMeta.ts

@@ -0,0 +1,115 @@
+import type { ZoraComponentMeta } from '../../../types/authoring';
+
+/*** Describe the embeddable config-driven Game runtime/presentation boundary for ZORA authoring. */
+export const gameMeta = {
+  name: 'Game',
+  category: 'pattern',
+  description:
+    'Embeds one config-driven game session inside ordinary ZORA layout and emits domain-neutral game outputs.',
+  directManifestNode: true,
+  allowedChildren: [
+    'GameEntity',
+    'GameInputZone',
+    'GameMeasurementProbe',
+    'GameOverlay',
+    'Gradient',
+    'Image',
+    'View',
+  ],
+  blueprint: {
+    label: 'Game',
+    defaultProps: {
+      definition: {
+        id: 'game',
+        initialPhase: 'playing',
+        stages: [{ id: 'main' }],
+        rules: [],
+      },
+      seed: 0,
+      resetKey: '',
+      autoAdvanceTime: true,
+      minHeight: 320,
+      fill: false,
+      clip: true,
+    },
+  },
+  bindings: {
+    props: {
+      definition: {
+        value: { type: 'object' },
+        acceptsFallback: true,
+      },
+      input: {
+        value: { type: 'record' },
+        acceptsFallback: true,
+      },
+    },
+  },
+  events: {
+    output: {
+      label: 'Game output',
+      eventType: 'game.output',
+      description: 'Emitted when the platform-neutral game runtime produces an app/domain output.',
+      payloadFields: [
+        { path: 'type', type: 'string' },
+        { path: 'payload', type: 'record' },
+      ],
+    },
+  },
+  props: {
+    seed: {
+      type: 'number',
+      category: 'Runtime',
+      label: 'Initial seed',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    resetKey: {
+      type: 'string',
+      category: 'Runtime',
+      label: 'Reset key',
+      default: '',
+      authoring: { authority: 'instance' },
+    },
+    autoAdvanceTime: {
+      type: 'boolean',
+      category: 'Runtime',
+      label: 'Advance scheduled effects',
+      default: true,
+      authoring: { authority: 'instance' },
+    },
+    aspectRatio: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Aspect ratio',
+      authoring: { authority: 'instance' },
+    },
+    minHeight: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Minimum height',
+      default: 320,
+      authoring: { authority: 'instance' },
+    },
+    fill: {
+      type: 'boolean',
+      category: 'Layout',
+      label: 'Fill available space',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    clip: {
+      type: 'boolean',
+      category: 'Layout',
+      label: 'Clip overflow',
+      default: true,
+      authoring: { authority: 'instance' },
+    },
+    accessibilityLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Accessibility label',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/game/meta/gameOverlayMeta.ts

@@ -0,0 +1,66 @@
+import type { ZoraComponentMeta } from '../../../types/authoring';
+
+/*** Describe a generic absolute game layer for HUD, feedback, and phase content. */
+export const gameOverlayMeta = {
+  name: 'GameOverlay',
+  category: 'layout',
+  description: 'Absolute presentation layer for HUD, feedback, controls, and phase content.',
+  directManifestNode: true,
+  allowedChildren: [
+    'Badge',
+    'Button',
+    'ButtonGroup',
+    'Card',
+    'GameEntity',
+    'Heading',
+    'Icon',
+    'Image',
+    'Progress',
+    'ProgressRing',
+    'Text',
+    'View',
+  ],
+  blueprint: {
+    label: 'Game overlay',
+    defaultProps: { placement: 'fill', blocking: false, padding: 0 },
+  },
+  props: {
+    placement: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Placement',
+      enum: [
+        'fill',
+        'center',
+        'top',
+        'bottom',
+        'top-left',
+        'top-right',
+        'bottom-left',
+        'bottom-right',
+      ],
+      default: 'fill',
+      authoring: { authority: 'instance' },
+    },
+    blocking: {
+      type: 'boolean',
+      category: 'Interaction',
+      label: 'Block pointer input',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    padding: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Padding',
+      default: 0,
+      authoring: { authority: 'instance' },
+    },
+    accessibilityLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Accessibility label',
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/game/public.test.tsx

@@ -0,0 +1,64 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+import type { ZoraProvider as ZoraProviderComponent } from '../theme/runtime';
+import type { GameEntity as GameEntityComponent, GameField as GameFieldComponent } from './public';
+
+const webDistRoot = join(import.meta.dir, '../../../web-dist');
+
+test('generic web materialization renders Game field and entity without a plugin catalog', async () => {
+  const manifest: unknown = await Bun.file(join(webDistRoot, 'manifest.json')).json();
+  if (
+    typeof manifest !== 'object' ||
+    manifest === null ||
+    !('artifacts' in manifest) ||
+    !Array.isArray(manifest.artifacts)
+  ) {
+    throw new Error('Expected a generated web artifact catalog.');
+  }
+  const artifactNames = Object.values(manifest.artifacts as readonly unknown[])
+    .filter(
+      (artifact) => typeof artifact === 'object' && artifact !== null && 'exportName' in artifact,
+    )
+    .map((artifact) => artifact.exportName);
+  const exports = new Set(artifactNames);
+  for (const name of [
+    'Game',
+    'GameField',
+    'GameEntity',
+    'GameInputZone',
+    'GameMeasurementProbe',
+    'GameOverlay',
+  ]) {
+    expect(exports.has(name), name).toBe(true);
+  }
+
+  const { GameField } = (await import(
+    pathToFileURL(join(webDistRoot, 'components/game-field/index.js')).href
+  )) as { GameField: typeof GameFieldComponent };
+  const { GameEntity } = (await import(
+    pathToFileURL(join(webDistRoot, 'components/game-entity/index.js')).href
+  )) as { GameEntity: typeof GameEntityComponent };
+  const { ZoraProvider } = (await import(
+    pathToFileURL(join(webDistRoot, 'runtime/ZoraProvider.js')).href
+  )) as { ZoraProvider: typeof ZoraProviderComponent };
+  const browser = new Window();
+  browser.document.body.innerHTML = renderToStaticMarkup(
+    <ZoraProvider mode="light">
+      <GameField testID="field">
+        <GameEntity x={25} y={40} testID="entity" />
+      </GameField>
+    </ZoraProvider>,
+  );
+  expect(browser.document.querySelector('[data-testid="field"]')).not.toBeNull();
+  expect(browser.document.querySelector('[data-testid="field"]')?.getAttribute('style')).toContain(
+    'min-height:320px',
+  );
+  expect(browser.document.querySelector('[data-testid="entity"]')).not.toBeNull();
+  browser.close();
+});

package/src/features/game/public.ts

@@ -0,0 +1,19 @@
+export type {
+  GameEntityEasing,
+  GameEntityMotionProps,
+  GameEntityProps,
+  GameFieldProps,
+  GameInputZoneProps,
+  GameKeyboardBinding,
+  GameMeasurementProbeProps,
+  GameOverlayPlacement,
+  GameOverlayProps,
+  GamePointerEvents,
+  GameProps,
+} from '../../types/gamePresentation';
+export { Game } from './adapters/inbound/Game';
+export { GameEntity } from './adapters/inbound/GameEntity';
+export { GameField } from './adapters/inbound/GameField';
+export { GameInputZone } from './adapters/inbound/GameInputZone';
+export { GameMeasurementProbe } from './adapters/inbound/GameMeasurementProbe';
+export { GameOverlay } from './adapters/inbound/GameOverlay';

package/src/features/game/utils/clampGamePercentage.ts

@@ -0,0 +1,4 @@
+/*** Clamp one game presentation coordinate to the inclusive field-percentage range. */
+export function clampGamePercentage(value: number): number {
+  return Math.min(100, Math.max(0, value));
+}

package/src/features/game/utils/resolveGameEntityMotionPlan.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveGameEntityMotionPlan } from './resolveGameEntityMotionPlan';
+
+describe('resolveGameEntityMotionPlan configuration', () => {
+  test('preserves explicit transition and repeating alternate motion', () => {
+    expect(
+      resolveGameEntityMotionPlan(
+        {
+          transitionDurationMs: 70,
+          transitionEasing: 'ease-out',
+          motionOffsetY: 8,
+          motionDurationMs: 1200,
+          motionDelayMs: 100,
+          motionEasing: 'ease-in-out',
+          motionRepeat: true,
+          motionAlternate: true,
+        },
+        false,
+      ),
+    ).toEqual({
+      transitionDurationMs: 70,
+      transitionEasing: 'ease-out',
+      motionDurationMs: 1200,
+      motionDelayMs: 100,
+      motionEasing: 'ease-in-out',
+      motionEnabled: true,
+      motionRepeat: true,
+      motionAlternate: true,
+      motionPaused: false,
+    });
+  });
+
+  test('uses alternate only for repeating motion', () => {
+    expect(
+      resolveGameEntityMotionPlan(
+        { motionOffsetY: 5, motionDurationMs: 100, motionAlternate: true },
+        false,
+      ).motionAlternate,
+    ).toBe(false);
+  });
+});
+
+describe('resolveGameEntityMotionPlan reduced motion', () => {
+  test('disables decorative motion and transitions', () => {
+    const plan = resolveGameEntityMotionPlan(
+      { transitionDurationMs: 80, motionOffsetX: 12, motionDurationMs: 500 },
+      true,
+    );
+
+    expect(plan.transitionDurationMs).toBe(0);
+    expect(plan.motionEnabled).toBe(false);
+  });
+
+  test('keeps essential trajectories enabled', () => {
+    const plan = resolveGameEntityMotionPlan(
+      { motionOffsetY: 70, motionDurationMs: 600, motionEssential: true },
+      true,
+    );
+
+    expect(plan.motionEnabled).toBe(true);
+  });
+});

package/src/features/game/utils/resolveGameEntityMotionPlan.ts

@@ -0,0 +1,53 @@
+import type { GameEntityEasing, GameEntityMotionProps } from '../../../types/gamePresentation';
+
+export interface GameEntityMotionPlan {
+  readonly transitionDurationMs: number;
+  readonly transitionEasing: GameEntityEasing;
+  readonly motionDurationMs: number;
+  readonly motionDelayMs: number;
+  readonly motionEasing: GameEntityEasing;
+  readonly motionEnabled: boolean;
+  readonly motionRepeat: boolean;
+  readonly motionAlternate: boolean;
+  readonly motionPaused: boolean;
+}
+
+/*** Normalize serializable GameEntity motion props against the current reduced-motion preference. */
+export function resolveGameEntityMotionPlan(
+  props: GameEntityMotionProps,
+  reduceMotion: boolean,
+): GameEntityMotionPlan {
+  const essential = props.motionEssential === true;
+  const motionEnabled =
+    hasMotionOffset(props) &&
+    normalizeDuration(props.motionDurationMs) > 0 &&
+    (!reduceMotion || essential);
+
+  return {
+    transitionDurationMs: reduceMotion ? 0 : normalizeDuration(props.transitionDurationMs),
+    transitionEasing: props.transitionEasing ?? 'linear',
+    motionDurationMs: normalizeDuration(props.motionDurationMs),
+    motionDelayMs: normalizeDuration(props.motionDelayMs),
+    motionEasing: props.motionEasing ?? 'linear',
+    motionEnabled,
+    motionRepeat: props.motionRepeat === true,
+    motionAlternate: props.motionRepeat === true && props.motionAlternate === true,
+    motionPaused: props.motionPaused === true,
+  };
+}
+
+/*** Return whether any relative presentation offset requires a motion timeline. */
+function hasMotionOffset(props: GameEntityMotionProps): boolean {
+  return (
+    (props.motionOffsetX ?? 0) !== 0 ||
+    (props.motionOffsetY ?? 0) !== 0 ||
+    (props.motionOpacityDelta ?? 0) !== 0 ||
+    (props.motionScaleDelta ?? 0) !== 0 ||
+    (props.motionRotationDelta ?? 0) !== 0
+  );
+}
+
+/*** Clamp an optional duration to a finite non-negative millisecond value. */
+function normalizeDuration(value: number | undefined): number {
+  return value === undefined || !Number.isFinite(value) ? 0 : Math.max(0, value);
+}

package/src/features/game/utils/toGamePercentage.ts

@@ -0,0 +1,6 @@
+import { clampGamePercentage } from './clampGamePercentage';
+
+/*** Convert one game percentage coordinate to React Native percentage style syntax. */
+export function toGamePercentage(value: number): `${number}%` {
+  return `${clampGamePercentage(value)}%`;
+}

package/src/features/game/utils/useAnimatedGameEntityValue.ts

@@ -0,0 +1,41 @@
+import React from 'react';
+import { Animated, Easing } from 'react-native';
+
+import type { GameEntityEasing } from '../../../types/gamePresentation';
+
+/*** Animate one bound numeric GameEntity presentation value toward its latest session-driven target. */
+export function useAnimatedGameEntityValue(
+  target: number,
+  durationMs: number,
+  easing: GameEntityEasing,
+): Animated.Value {
+  const [value] = React.useState(() => new Animated.Value(target));
+
+  React.useEffect(() => {
+    value.stopAnimation();
+
+    if (durationMs === 0) {
+      value.setValue(target);
+      return undefined;
+    }
+
+    const animation = Animated.timing(value, {
+      toValue: target,
+      duration: durationMs,
+      easing: resolveGameEntityEasing(easing),
+      useNativeDriver: false,
+    });
+    animation.start();
+    return () => animation.stop();
+  }, [durationMs, easing, target, value]);
+
+  return value;
+}
+
+/*** Map serializable easing names onto React Native easing functions. */
+function resolveGameEntityEasing(easing: GameEntityEasing) {
+  if (easing === 'ease-in') return Easing.in(Easing.ease);
+  if (easing === 'ease-out') return Easing.out(Easing.ease);
+  if (easing === 'ease-in-out') return Easing.inOut(Easing.ease);
+  return Easing.linear;
+}

package/src/features/game/utils/useGameEntityAnimatedStyle.ts

@@ -0,0 +1,87 @@
+import { Animated } from 'react-native';
+
+import type { GameEntityProps } from '../../../types/gamePresentation';
+import { resolveGameEntityMotionPlan } from './resolveGameEntityMotionPlan';
+import { useAnimatedGameEntityValue } from './useAnimatedGameEntityValue';
+import { useGameEntityMotionProgress } from './useGameEntityMotionProgress';
+import { useGameReducedMotion } from './useGameReducedMotion';
+
+interface GameEntityAnimatedValues {
+  readonly x: Animated.Value;
+  readonly y: Animated.Value;
+  readonly opacity: Animated.Value;
+  readonly scale: Animated.Value;
+  readonly rotation: Animated.Value;
+  readonly progress: Animated.Value;
+}
+
+/*** Compose bound GameEntity values with optional relative presentation motion. */
+export function useGameEntityAnimatedStyle(input: GameEntityProps) {
+  const reduceMotion = useGameReducedMotion();
+  const plan = resolveGameEntityMotionPlan(input, reduceMotion);
+  const values: GameEntityAnimatedValues = {
+    x: useAnimatedGameEntityValue(input.x ?? 0, plan.transitionDurationMs, plan.transitionEasing),
+    y: useAnimatedGameEntityValue(input.y ?? 0, plan.transitionDurationMs, plan.transitionEasing),
+    opacity: useAnimatedGameEntityValue(
+      input.opacity ?? 1,
+      plan.transitionDurationMs,
+      plan.transitionEasing,
+    ),
+    scale: useAnimatedGameEntityValue(
+      input.scale ?? 1,
+      plan.transitionDurationMs,
+      plan.transitionEasing,
+    ),
+    rotation: useAnimatedGameEntityValue(
+      input.rotation ?? 0,
+      plan.transitionDurationMs,
+      plan.transitionEasing,
+    ),
+    progress: useGameEntityMotionProgress(plan),
+  };
+
+  return createGameEntityAnimatedStyle(values, input);
+}
+
+/*** Build one animated React Native style from base values and relative motion progress. */
+function createGameEntityAnimatedStyle(values: GameEntityAnimatedValues, input: GameEntityProps) {
+  const left = Animated.add(values.x, Animated.multiply(values.progress, input.motionOffsetX ?? 0));
+  const top = Animated.add(values.y, Animated.multiply(values.progress, input.motionOffsetY ?? 0));
+  const opacity = Animated.add(
+    values.opacity,
+    Animated.multiply(values.progress, input.motionOpacityDelta ?? 0),
+  );
+  const scale = Animated.add(
+    values.scale,
+    Animated.multiply(values.progress, input.motionScaleDelta ?? 0),
+  );
+  const rotation = Animated.add(
+    values.rotation,
+    Animated.multiply(values.progress, input.motionRotationDelta ?? 0),
+  );
+
+  return {
+    left: left.interpolate({
+      inputRange: [-10_000, 10_000],
+      outputRange: ['-10000%', '10000%'],
+    }),
+    top: top.interpolate({
+      inputRange: [-10_000, 10_000],
+      outputRange: ['-10000%', '10000%'],
+    }),
+    opacity: opacity.interpolate({
+      inputRange: [0, 1],
+      outputRange: [0, 1],
+      extrapolate: 'clamp',
+    }),
+    transform: [
+      { scale },
+      {
+        rotate: rotation.interpolate({
+          inputRange: [-36_000, 36_000],
+          outputRange: ['-36000deg', '36000deg'],
+        }),
+      },
+    ],
+  };
+}

package/src/features/game/utils/useGameEntityMeasurement.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+import type { View } from 'react-native';
+
+import { measureGameEntity } from '../adapters/inbound/measureGameEntity';
+import { GameRuntimeContext } from '../composition/GameRuntimeContext';
+
+/*** Register one optional measurable GameEntity view inside its local Game scope. */
+export function useGameEntityMeasurement(
+  elementRef: React.RefObject<View | null>,
+  measurementId: string | undefined,
+): void {
+  const runtime = React.useContext(GameRuntimeContext);
+  const registerMeasurement = runtime?.registerMeasurement;
+
+  React.useEffect(() => {
+    if (measurementId === undefined || registerMeasurement === undefined) return undefined;
+    return registerMeasurement(measurementId, () => measureGameEntity(elementRef.current));
+  }, [elementRef, measurementId, registerMeasurement]);
+}