@react-native-motion-kit/text-motion 0.0.0-stage → 0.1.0

package/src/split/segmenter.ts

@@ -0,0 +1,111 @@
+export type SegmenterGranularity = 'grapheme' | 'word';
+
+export type TextMotionSegment = {
+  index: number;
+  isWordLike?: boolean;
+  segment: string;
+};
+
+type SegmenterLike = {
+  segment(input: string): Iterable<TextMotionSegment>;
+};
+
+export type SegmenterRuntime = {
+  Segmenter?: SegmenterConstructor;
+};
+
+export type SegmenterConstructor = new (
+  locale?: string | string[],
+  options?: { granularity: SegmenterGranularity },
+) => SegmenterLike;
+
+const WORD_CHARACTER_SOURCE =
+  '[0-9A-Za-z_\\u00C0-\\u024F\\u0370-\\u03FF\\u0400-\\u04FF\\u0590-\\u05FF\\u0600-\\u06FF\\u0900-\\u097F\\u0E00-\\u0E7F\\u1100-\\u11FF\\u3040-\\u30FF\\u3130-\\u318F\\u3400-\\u9FFF\\uAC00-\\uD7AF\\uF900-\\uFAFF]';
+const WORD_MARK_SOURCE =
+  '[\\u0300-\\u036F\\u1AB0-\\u1AFF\\u1DC0-\\u1DFF\\u20D0-\\u20FF\\uFE20-\\uFE2F]';
+const WORD_CONTINUATION_SOURCE = `(?:${WORD_CHARACTER_SOURCE}|${WORD_MARK_SOURCE})*`;
+const WORD_UNIT_SOURCE = `${WORD_CHARACTER_SOURCE}${WORD_CONTINUATION_SOURCE}`;
+const WORD_LIKE_SOURCE = `${WORD_UNIT_SOURCE}(?:[.'’]${WORD_UNIT_SOURCE})*`;
+const WHITESPACE_SOURCE = '\\s+';
+const WHITESPACE_PATTERN = /^\s+$/u;
+const SURROGATE_PAIR_SOURCE = '[\\uD800-\\uDBFF][\\uDC00-\\uDFFF]';
+const CODE_POINT_SOURCE = `(?:\\r\\n|${SURROGATE_PAIR_SOURCE}|[\\s\\S])`;
+const GRAPHEME_EXTENSION_SOURCE =
+  '[\\u0300-\\u036F\\u1AB0-\\u1AFF\\u1DC0-\\u1DFF\\u20D0-\\u20FF\\uFE20-\\uFE2F\\uFE00-\\uFE0F\\u{E0100}-\\u{E01EF}\\u{1F3FB}-\\u{1F3FF}]';
+const HANGUL_LEADING_SOURCE = '[\\u1100-\\u115F\\uA960-\\uA97C]';
+const HANGUL_VOWEL_SOURCE = '[\\u1160-\\u11A7\\uD7B0-\\uD7C6]';
+const HANGUL_TRAILING_SOURCE = '[\\u11A8-\\u11FF\\uD7CB-\\uD7FB]';
+// Precomposed LV syllables occur every 28 code points, starting at 가 (U+AC00).
+const HANGUL_LV_SOURCE = `[${Array.from({ length: 399 }, (_, index) =>
+  String.fromCharCode(0xac00 + index * 28),
+).join('')}]`;
+const HANGUL_LVT_SOURCE = `(?!${HANGUL_LV_SOURCE})[\\uAC00-\\uD7A3]`;
+// UAX #29 GB6–GB8: L* (V+ | LV V* | LVT) T* | L+ | T+.
+const HANGUL_SYLLABLE_SOURCE = `${HANGUL_LEADING_SOURCE}*(?:${HANGUL_VOWEL_SOURCE}+|${HANGUL_LV_SOURCE}${HANGUL_VOWEL_SOURCE}*|${HANGUL_LVT_SOURCE})${HANGUL_TRAILING_SOURCE}*|${HANGUL_LEADING_SOURCE}+|${HANGUL_TRAILING_SOURCE}+`;
+const BASE_GRAPHEME_SOURCE = `(?:${HANGUL_SYLLABLE_SOURCE}|${CODE_POINT_SOURCE})${GRAPHEME_EXTENSION_SOURCE}*`;
+const JOINED_GRAPHEME_SOURCE = `${BASE_GRAPHEME_SOURCE}(?:\\u200D${BASE_GRAPHEME_SOURCE})*`;
+const REGIONAL_INDICATOR_PAIR_SOURCE = '[\\u{1F1E6}-\\u{1F1FF}]{2}';
+const GRAPHEME_SEGMENT_SOURCE = `${REGIONAL_INDICATOR_PAIR_SOURCE}|${JOINED_GRAPHEME_SOURCE}`;
+const WORD_SEGMENT_SOURCE = `${WORD_LIKE_SOURCE}|${WHITESPACE_SOURCE}|${GRAPHEME_SEGMENT_SOURCE}`;
+const WORD_LIKE_PATTERN = new RegExp(`^${WORD_LIKE_SOURCE}$`, 'u');
+
+export function createSegmenter(
+  granularity: SegmenterGranularity,
+  locale?: string | string[],
+  runtime: SegmenterRuntime | undefined = getDefaultSegmenterRuntime(),
+): SegmenterLike {
+  const Segmenter = runtime?.Segmenter;
+
+  if (Segmenter) {
+    return new Segmenter(locale, { granularity });
+  }
+
+  return createFallbackSegmenter(granularity);
+}
+
+function createFallbackSegmenter(granularity: SegmenterGranularity): SegmenterLike {
+  return {
+    segment(input) {
+      return granularity === 'word'
+        ? segmentWordsWithoutIntl(input)
+        : segmentGraphemesWithoutIntl(input);
+    },
+  };
+}
+
+function segmentWordsWithoutIntl(input: string): TextMotionSegment[] {
+  return Array.from(input.matchAll(createWordSegmentPattern()), createWordSegment);
+}
+
+function segmentGraphemesWithoutIntl(input: string): TextMotionSegment[] {
+  return Array.from(input.matchAll(createGraphemeSegmentPattern()), createSegment);
+}
+
+function createWordSegment(match: RegExpMatchArray): TextMotionSegment {
+  const segment = match[0] ?? '';
+
+  return {
+    index: match.index ?? 0,
+    isWordLike: WORD_LIKE_PATTERN.test(segment) && !WHITESPACE_PATTERN.test(segment),
+    segment,
+  };
+}
+
+function createSegment(match: RegExpMatchArray): TextMotionSegment {
+  return {
+    index: match.index ?? 0,
+    segment: match[0] ?? '',
+  };
+}
+
+function createGraphemeSegmentPattern(): RegExp {
+  return new RegExp(GRAPHEME_SEGMENT_SOURCE, 'gu');
+}
+
+function createWordSegmentPattern(): RegExp {
+  return new RegExp(WORD_SEGMENT_SOURCE, 'gu');
+}
+
+function getDefaultSegmenterRuntime(): SegmenterRuntime | undefined {
+  return globalThis.Intl as unknown as SegmenterRuntime | undefined;
+}

package/src/split/words.ts

@@ -0,0 +1,28 @@
+import type { TextMotionSplitter } from '../types';
+
+import { createTextMotionSplitterHandle } from '../recipe/descriptors';
+import { createTextMotionToken } from './createToken';
+import { createSegmenter } from './segmenter';
+
+/** Split text into word, spacing, and punctuation tokens. */
+export function words(): TextMotionSplitter<'word'> {
+  return createTextMotionSplitterHandle({
+    kind: 'word',
+    split(input, context) {
+      const segmenter = createSegmenter('word', context?.locale);
+
+      return Array.from(segmenter.segment(input), (segment, index) =>
+        createTextMotionToken({
+          index,
+          metadata: { isWordLike: segment.isWordLike === true },
+          sourceRange: {
+            start: segment.index,
+            end: segment.index + segment.segment.length,
+          },
+          text: segment.segment,
+          unit: 'word',
+        }),
+      );
+    },
+  });
+}

package/src/timeline/index.ts

@@ -0,0 +1,4 @@
+export { parallel } from './parallel';
+export { sequence } from './sequence';
+export { stagger, type TextMotionStaggerFrom, type TextMotionStaggerOptions } from './stagger';
+export { wave, type TextMotionWaveOptions } from './wave';

package/src/timeline/parallel.ts

@@ -0,0 +1,30 @@
+import type { TextMotionAnyTimeline, TextMotionTimeline } from '../types';
+
+import {
+  createTextMotionTimelineHandle,
+  readTextMotionTimelineDescriptor,
+} from '../recipe/descriptors';
+
+type TextMotionCompositeTimelineOptions = {
+  timelines: readonly string[];
+};
+
+/** Combine timelines by using the earliest delay for each token. */
+export function parallel(
+  ...timelines: readonly TextMotionAnyTimeline[]
+): TextMotionTimeline<'parallel'> {
+  const descriptors = timelines.map(readTextMotionTimelineDescriptor);
+
+  return createTextMotionTimelineHandle<TextMotionCompositeTimelineOptions, 'parallel'>({
+    kind: 'timeline',
+    name: 'parallel',
+    options: { timelines: descriptors.map((descriptor) => descriptor.name) },
+    delayFor(index, count) {
+      if (descriptors.length === 0) {
+        return 0;
+      }
+
+      return Math.min(...descriptors.map((descriptor) => descriptor.delayFor(index, count)));
+    },
+  });
+}

package/src/timeline/sequence.ts

@@ -0,0 +1,29 @@
+import type { TextMotionAnyTimeline, TextMotionTimeline } from '../types';
+
+import {
+  createTextMotionTimelineHandle,
+  readTextMotionTimelineDescriptor,
+} from '../recipe/descriptors';
+
+type TextMotionCompositeTimelineOptions = {
+  timelines: readonly string[];
+};
+
+/** Combine timelines by adding each timeline delay for a token. */
+export function sequence(
+  ...timelines: readonly TextMotionAnyTimeline[]
+): TextMotionTimeline<'sequence'> {
+  const descriptors = timelines.map(readTextMotionTimelineDescriptor);
+
+  return createTextMotionTimelineHandle<TextMotionCompositeTimelineOptions, 'sequence'>({
+    kind: 'timeline',
+    name: 'sequence',
+    options: { timelines: descriptors.map((descriptor) => descriptor.name) },
+    delayFor(index, count) {
+      return descriptors.reduce(
+        (delay, descriptor) => delay + descriptor.delayFor(index, count),
+        0,
+      );
+    },
+  });
+}

package/src/timeline/stagger.ts

@@ -0,0 +1,60 @@
+import type { TextMotionTimeline } from '../types';
+
+import { createTextMotionTimelineHandle } from '../recipe/descriptors';
+import { validateFiniteTimelineNumber, validateNonNegativeTimelineNumber } from './validation';
+
+/** Origin used when calculating stagger delays. */
+export type TextMotionStaggerFrom = 'start' | 'center' | 'end' | 'edges' | number;
+
+/** Options for {@link stagger}. */
+export type TextMotionStaggerOptions = {
+  /** Token index origin for the stagger. Defaults to `start`. */
+  from?: TextMotionStaggerFrom;
+};
+
+type TextMotionStaggerTimelineOptions = {
+  from: TextMotionStaggerFrom;
+  step: number;
+};
+
+function offsetFrom(index: number, count: number, from: TextMotionStaggerFrom): number {
+  if (typeof from === 'number') {
+    return Math.abs(index - from);
+  }
+
+  if (from === 'center') {
+    return Math.abs(index - (count - 1) / 2);
+  }
+
+  if (from === 'end') {
+    return count - 1 - index;
+  }
+
+  if (from === 'edges') {
+    return Math.min(index, count - 1 - index);
+  }
+
+  return index;
+}
+
+/** Delay each token by a fixed step from the chosen origin. */
+export function stagger(
+  step: number,
+  options: TextMotionStaggerOptions = {},
+): TextMotionTimeline<'stagger'> {
+  const fromOption = options.from ?? 'start';
+  const from =
+    typeof fromOption === 'number'
+      ? validateFiniteTimelineNumber(fromOption, 'stagger from')
+      : fromOption;
+  const safeStep = validateNonNegativeTimelineNumber(step, 'stagger step');
+
+  return createTextMotionTimelineHandle<TextMotionStaggerTimelineOptions, 'stagger'>({
+    kind: 'timeline',
+    name: 'stagger',
+    options: { from, step: safeStep },
+    delayFor(index, count) {
+      return offsetFrom(index, count, from) * safeStep;
+    },
+  });
+}

package/src/timeline/validation.ts

@@ -0,0 +1,29 @@
+const ERROR_PREFIX = '@react-native-motion-kit/text-motion';
+
+export function validateFiniteTimelineNumber(value: number, label: string): number {
+  if (Number.isFinite(value)) {
+    return value;
+  }
+
+  throw new Error(`${ERROR_PREFIX} ${label} must be a finite number.`);
+}
+
+export function validateNonNegativeTimelineNumber(value: number, label: string): number {
+  const finiteValue = validateFiniteTimelineNumber(value, label);
+
+  if (finiteValue >= 0) {
+    return finiteValue;
+  }
+
+  throw new Error(`${ERROR_PREFIX} ${label} must be greater than or equal to 0.`);
+}
+
+export function validatePositiveTimelineNumber(value: number, label: string): number {
+  const finiteValue = validateFiniteTimelineNumber(value, label);
+
+  if (finiteValue > 0) {
+    return finiteValue;
+  }
+
+  throw new Error(`${ERROR_PREFIX} ${label} must be greater than 0.`);
+}

package/src/timeline/wave.ts

@@ -0,0 +1,34 @@
+import type { TextMotionTimeline } from '../types';
+
+import { createTextMotionTimelineHandle } from '../recipe/descriptors';
+import { validateNonNegativeTimelineNumber, validatePositiveTimelineNumber } from './validation';
+
+/** Options for {@link wave}. */
+export type TextMotionWaveOptions = {
+  /** Maximum delay in seconds. Defaults to `0.08`. */
+  amplitude?: number;
+  /** Number of tokens per sine-wave cycle. Defaults to `4`. */
+  wavelength?: number;
+};
+
+type TextMotionWaveTimelineOptions = {
+  amplitude: number;
+  wavelength: number;
+};
+
+/** Create sine-wave token delays for soft rolling text motion. */
+export function wave(options: TextMotionWaveOptions = {}): TextMotionTimeline<'wave'> {
+  const amplitude = validateNonNegativeTimelineNumber(options.amplitude ?? 0.08, 'wave amplitude');
+  const wavelength = validatePositiveTimelineNumber(options.wavelength ?? 4, 'wave wavelength');
+
+  return createTextMotionTimelineHandle<TextMotionWaveTimelineOptions, 'wave'>({
+    kind: 'timeline',
+    name: 'wave',
+    options: { amplitude, wavelength },
+    delayFor(index) {
+      const phase = (index / wavelength) * Math.PI * 2;
+
+      return ((Math.sin(phase) + 1) / 2) * amplitude;
+    },
+  });
+}

package/src/types/index.ts

@@ -0,0 +1,34 @@
+export type {
+  TextMotionAccessibilityPolicy,
+  TextMotionAnyEffect,
+  TextMotionAnyTimeline,
+  TextMotionComponent,
+  TextMotionComponentAccessibilityProps,
+  TextMotionComponentProps,
+  TextMotionComponentTextProps,
+  TextMotionEffect,
+  TextMotionEffectForRenderer,
+  TextMotionInternalRecipeConfig,
+  TextMotionMotionConfig,
+  TextMotionRecipeConfig,
+  TextMotionSpringOptions,
+  TextMotionTimeline,
+  TextMotionTimingOptions,
+} from './recipe';
+export type { TextMotionControls } from '../controls';
+export type {
+  TextMotionCompatibleEffect,
+  TextMotionMissingCapabilities,
+  TextMotionRenderer,
+  TextMotionRendererCapability,
+  TextMotionRendererCapabilityExtension,
+  TextMotionRendererProps,
+} from './renderer';
+export { createTextMotionRendererCapability } from './renderer';
+export type {
+  TextMotionSourceRange,
+  TextMotionSplitContext,
+  TextMotionSplitter,
+  TextMotionToken,
+  TextMotionTokenUnit,
+} from './token';

package/src/types/recipe.ts

@@ -0,0 +1,195 @@
+import type { ComponentType } from 'react';
+import type { StyleProp, TextProps, TextStyle } from 'react-native';
+import type { SharedValue, WithSpringConfig, WithTimingConfig } from 'react-native-reanimated';
+
+import type { TextMotionControls } from '../controls';
+import type {
+  TextMotionCompatibleEffect,
+  TextMotionRenderer,
+  TextMotionRendererCapability,
+} from './renderer';
+import type { TextMotionSplitter } from './token';
+
+type DistributiveOmit<T, Keys extends PropertyKey> = T extends unknown ? Omit<T, Keys> : never;
+
+declare const textMotionEffectBrand: unique symbol;
+declare const textMotionTimelineBrand: unique symbol;
+
+/** @internal Serializable metadata attached to effect descriptors. */
+export type TextMotionEffectDescriptorOptions = Readonly<Record<string, unknown>>;
+
+/** @internal Serializable metadata attached to timeline descriptors. */
+export type TextMotionTimelineDescriptorOptions = Readonly<Record<string, unknown>>;
+
+/** @internal Timeline descriptor consumed by recipe and renderer internals. */
+export type TextMotionTimelineDescriptor<
+  Options extends TextMotionTimelineDescriptorOptions = TextMotionTimelineDescriptorOptions,
+  Name extends string = string,
+> = {
+  kind: 'timeline';
+  name: Name;
+  options?: Options;
+  delayFor(index: number, count: number): number;
+};
+
+/** @internal Timeline descriptor with extension-level options for recipe internals. */
+export type TextMotionAnyTimelineDescriptor = TextMotionTimelineDescriptor;
+
+/** Opaque timeline handle accepted by `.timeline(...)`. */
+export type TextMotionTimeline<Name extends string = string> = {
+  readonly [textMotionTimelineBrand]: {
+    readonly name: Name;
+  };
+};
+
+/** Opaque timeline handle with any timeline name. */
+export type TextMotionAnyTimeline = TextMotionTimeline;
+
+/** @internal Effect descriptor consumed by renderers. */
+export type TextMotionEffectDescriptor<
+  RequiredCapabilities extends TextMotionRendererCapability = TextMotionRendererCapability,
+  Options extends TextMotionEffectDescriptorOptions = TextMotionEffectDescriptorOptions,
+  Name extends string = string,
+> = {
+  kind: 'effect';
+  name: Name;
+  options?: Options;
+  requiredCapabilities: readonly RequiredCapabilities[];
+  effects?: readonly TextMotionAnyEffect[];
+};
+
+/** @internal Effect descriptor with extension-level options for renderer internals. */
+export type TextMotionAnyEffectDescriptor = TextMotionEffectDescriptor;
+
+/** Opaque effect handle accepted by `.effect(...)`. */
+export type TextMotionEffect<
+  RequiredCapabilities extends TextMotionRendererCapability = 'native-text',
+  Name extends string = string,
+> = {
+  readonly [textMotionEffectBrand]: {
+    readonly requiredCapabilities: RequiredCapabilities;
+    readonly name: Name;
+  };
+  and<NextCapabilities extends TextMotionRendererCapability, NextName extends string>(
+    effect: TextMotionEffect<NextCapabilities, NextName>,
+  ): TextMotionEffect<RequiredCapabilities | NextCapabilities>;
+};
+
+/** Opaque effect handle with any required capability. */
+export type TextMotionAnyEffect = TextMotionEffect<TextMotionRendererCapability>;
+
+/** Timing options accepted by text motion renderers. Reduced motion is controlled by accessibility policy. */
+export type TextMotionTimingOptions = DistributiveOmit<WithTimingConfig, 'reduceMotion'>;
+
+/** Spring options accepted by text motion renderers. Reduced motion is controlled by accessibility policy. */
+export type TextMotionSpringOptions = DistributiveOmit<WithSpringConfig, 'reduceMotion'>;
+
+/** Motion primitive used by Reanimated renderers. */
+export type TextMotionMotionConfig =
+  | {
+      kind: 'timing';
+      options?: TextMotionTimingOptions;
+    }
+  | {
+      kind: 'spring';
+      options?: TextMotionSpringOptions;
+    };
+
+/** Accessibility behavior for a text motion recipe. */
+export type TextMotionAccessibilityPolicy = {
+  kind: string;
+  parentLabel: boolean;
+  hideTokensFromAccessibility: boolean;
+  reducedMotion: 'final-state' | 'system';
+};
+
+/** Immutable recipe config produced by {@link TextMotionRecipeBuilder}. */
+export type TextMotionRecipeConfig<
+  _RendererCapabilities extends TextMotionRendererCapability = TextMotionRendererCapability,
+  Timeline extends TextMotionAnyTimeline = TextMotionTimeline,
+  Effects extends readonly TextMotionAnyEffect[] = readonly TextMotionAnyEffect[],
+> = {
+  splitter?: TextMotionSplitter;
+  renderer?: TextMotionRenderer;
+  timeline?: Timeline;
+  effects: Effects;
+  motion?: TextMotionMotionConfig;
+  accessibility?: TextMotionAccessibilityPolicy;
+};
+
+/** Internal recipe shape used by runtime renderers after recipe composition. */
+export type TextMotionInternalRecipeConfig<
+  RendererCapabilities extends TextMotionRendererCapability = TextMotionRendererCapability,
+> = TextMotionRecipeConfig<
+  RendererCapabilities,
+  TextMotionAnyTimeline,
+  readonly TextMotionAnyEffect[]
+>;
+
+/** Accessibility props intentionally supported by text motion components. */
+export type TextMotionComponentAccessibilityProps = Pick<
+  TextProps,
+  | 'accessibilityActions'
+  | 'accessibilityHint'
+  | 'accessibilityLabel'
+  | 'accessibilityLanguage'
+  | 'accessibilityRole'
+  | 'accessibilityState'
+  | 'accessibilityValue'
+  | 'onAccessibilityAction'
+>;
+
+/** Non-child props intentionally supported by text motion components. */
+export type TextMotionComponentTextProps = TextMotionComponentAccessibilityProps &
+  Pick<TextProps, 'allowFontScaling' | 'maxFontSizeMultiplier' | 'nativeID' | 'testID'> & {
+    /** Text style applied to each rendered token. Layout-only text props are not supported. */
+    style?: StyleProp<TextStyle>;
+  };
+
+type TextMotionRawProgressPlaybackProps = {
+  /**
+   * Raw app-owned normalized progress for externally driven playback.
+   *
+   * `0` renders the initial text motion state and `1` renders the final state. Finite values
+   * outside `0..1` are clamped by the renderer; non-finite values are treated as `0`. When
+   * provided, `.motion()` does not drive playback. Use this for scroll, gesture, or synchronized
+   * shared values where the app owns the exact progress.
+   */
+  progress?: SharedValue<number>;
+  controls?: never;
+};
+
+type TextMotionControlsPlaybackProps = {
+  progress?: never;
+  /**
+   * Command channel for event-driven playback.
+   *
+   * The component owns playback execution and uses its recipe `.motion()` config. Use this for
+   * buttons, screen focus, onboarding steps, and replay/reset/stop interactions.
+   */
+  controls?: TextMotionControls;
+};
+
+type TextMotionComponentPlaybackProps =
+  | TextMotionRawProgressPlaybackProps
+  | TextMotionControlsPlaybackProps;
+
+/** Props forwarded from a text motion component to its renderer. */
+export type TextMotionComponentRendererProps = TextMotionComponentTextProps &
+  TextMotionComponentPlaybackProps;
+
+/** Props accepted by components created from text motion recipes. */
+export type TextMotionComponentProps = TextMotionComponentRendererProps & {
+  /** Plain string rendered and split by the recipe splitter. */
+  children: string;
+};
+
+/** React component produced by a text motion recipe. */
+export type TextMotionComponent = ComponentType<TextMotionComponentProps>;
+
+/** Type helper used by `.effect(...)` to enforce renderer capability compatibility. */
+export type TextMotionEffectForRenderer<
+  RendererCapabilities extends TextMotionRendererCapability,
+  RequiredCapabilities extends TextMotionRendererCapability,
+  Effect extends TextMotionEffect<RequiredCapabilities> = TextMotionEffect<RequiredCapabilities>,
+> = TextMotionCompatibleEffect<RendererCapabilities, RequiredCapabilities, Effect>;

package/src/types/renderer.ts

@@ -0,0 +1,91 @@
+import type { ComponentType, ReactNode } from 'react';
+
+import type { TextMotionComponentRendererProps, TextMotionRecipeConfig } from './recipe';
+import type { TextMotionToken } from './token';
+
+declare const textMotionRendererCapabilityBrand: unique symbol;
+declare const textMotionRendererBrand: unique symbol;
+declare const textMotionRenderedLineRendererBrand: unique symbol;
+
+/** Branded renderer capability name for custom renderer packages. */
+export type TextMotionRendererCapabilityExtension<Name extends string = string> = Name & {
+  readonly [textMotionRendererCapabilityBrand]: 'TextMotionRendererCapabilityExtension';
+};
+
+/** Capability supported by a renderer and required by effects. */
+export type TextMotionRendererCapability =
+  | 'native-text'
+  | 'style-transform'
+  | TextMotionRendererCapabilityExtension;
+
+/** @internal Built-in capability used by overlayText line-mask effects. */
+export type TextMotionLineMaskCapability = TextMotionRendererCapabilityExtension<'line-mask'>;
+
+/** Create a branded capability name for a custom renderer. */
+export function createTextMotionRendererCapability<Name extends string>(
+  name: Name,
+): TextMotionRendererCapabilityExtension<Name> {
+  return name as TextMotionRendererCapabilityExtension<Name>;
+}
+
+/** Props passed from the recipe component into a renderer component. */
+export type TextMotionRendererProps<Recipe = TextMotionRecipeConfig> = {
+  children: ReactNode;
+  tokens: readonly TextMotionToken[];
+  recipe: Recipe;
+  textProps?: TextMotionComponentRendererProps;
+};
+
+/** @internal Renderer descriptor consumed by recipe internals. */
+export type TextMotionRendererDescriptor<
+  Capabilities extends TextMotionRendererCapability = TextMotionRendererCapability,
+  Recipe = TextMotionRecipeConfig,
+  MotionUnit extends 'source-token' | 'rendered-line' = 'source-token' | 'rendered-line',
+> = {
+  kind: string;
+  capabilities: readonly Capabilities[];
+  motionUnit?: MotionUnit;
+  Component: ComponentType<TextMotionRendererProps<Recipe>>;
+};
+
+/** Renderer handle used by `.layout(...)`. */
+export type TextMotionRenderer<
+  Capabilities extends TextMotionRendererCapability = TextMotionRendererCapability,
+  Recipe = unknown,
+> = {
+  readonly [textMotionRendererBrand]: {
+    readonly capabilities: Capabilities;
+    readonly recipe: Recipe;
+  };
+};
+
+/** @internal Renderer handle for source-token renderers accepted after `.split(...)`. */
+export type TextMotionSourceTokenRenderer<
+  Capabilities extends TextMotionRendererCapability = TextMotionRendererCapability,
+  Recipe = unknown,
+> = TextMotionRenderer<Capabilities, Recipe> & {
+  readonly [textMotionRenderedLineRendererBrand]?: never;
+};
+
+/** @internal Renderer handle for renderers that own rendered-line layout. */
+export type TextMotionRenderedLineRenderer<
+  Capabilities extends TextMotionRendererCapability = TextMotionRendererCapability,
+  Recipe = unknown,
+> = TextMotionRenderer<Capabilities, Recipe> & {
+  readonly [textMotionRenderedLineRendererBrand]: 'rendered-line';
+};
+
+/** Capabilities required by an effect but missing from a renderer. */
+export type TextMotionMissingCapabilities<
+  RendererCapabilities extends TextMotionRendererCapability,
+  RequiredCapabilities extends TextMotionRendererCapability,
+> = Exclude<RequiredCapabilities, RendererCapabilities>;
+
+/** Effect type gate that rejects effects incompatible with the selected renderer. */
+export type TextMotionCompatibleEffect<
+  RendererCapabilities extends TextMotionRendererCapability,
+  RequiredCapabilities extends TextMotionRendererCapability,
+  Effect,
+> = [TextMotionMissingCapabilities<RendererCapabilities, RequiredCapabilities>] extends [never]
+  ? Effect
+  : never;