@airisu-dev/react-native-live2d-skia 0.0.0-stage → 0.1.0

package/nitrogen/generated/shared/c++/HybridLive2dSkiaSpec.hpp

@@ -0,0 +1,66 @@
+///
+/// HybridLive2dSkiaSpec.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/HybridObject.hpp>)
+#include <NitroModules/HybridObject.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `HybridLive2DModelSpec` to properly resolve imports.
+namespace margelo::nitro::live2dskia { class HybridLive2DModelSpec; }
+
+#include <memory>
+#include "HybridLive2DModelSpec.hpp"
+#include <NitroModules/ArrayBuffer.hpp>
+#include <string>
+
+namespace margelo::nitro::live2dskia {
+
+  using namespace margelo::nitro;
+
+  /**
+   * An abstract base class for `Live2dSkia`
+   * Inherit this class to create instances of `HybridLive2dSkiaSpec` in C++.
+   * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
+   * @example
+   * ```cpp
+   * class HybridLive2dSkia: public HybridLive2dSkiaSpec {
+   * public:
+   *   HybridLive2dSkia(...): HybridObject(TAG) { ... }
+   *   // ...
+   * };
+   * ```
+   */
+  class HybridLive2dSkiaSpec: public virtual HybridObject {
+    public:
+      // Constructor
+      explicit HybridLive2dSkiaSpec(): HybridObject(TAG) { }
+
+      // Destructor
+      ~HybridLive2dSkiaSpec() override = default;
+
+    public:
+      // Properties
+      
+
+    public:
+      // Methods
+      virtual std::shared_ptr<HybridLive2DModelSpec> loadModel(const std::shared_ptr<ArrayBuffer>& moc, const std::string& settingsJson) = 0;
+
+    protected:
+      // Hybrid Setup
+      void loadHybridMethods() override;
+
+    protected:
+      // Tag for logging
+      static constexpr auto TAG = "Live2dSkia";
+  };
+
+} // namespace margelo::nitro::live2dskia

package/nitrogen/generated/shared/c++/MotionPriority.hpp

@@ -0,0 +1,80 @@
+///
+/// MotionPriority.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/NitroHash.hpp>)
+#include <NitroModules/NitroHash.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+namespace margelo::nitro::live2dskia {
+
+  /**
+   * An enum which can be represented as a JavaScript union (MotionPriority).
+   */
+  enum class MotionPriority {
+    IDLE      SWIFT_NAME(idle) = 0,
+    NORMAL      SWIFT_NAME(normal) = 1,
+    FORCE      SWIFT_NAME(force) = 2,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::live2dskia
+
+namespace margelo::nitro {
+
+  // C++ MotionPriority <> JS MotionPriority (union)
+  template <>
+  struct JSIConverter<margelo::nitro::live2dskia::MotionPriority> final {
+    static inline margelo::nitro::live2dskia::MotionPriority fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("idle"): return margelo::nitro::live2dskia::MotionPriority::IDLE;
+        case hashString("normal"): return margelo::nitro::live2dskia::MotionPriority::NORMAL;
+        case hashString("force"): return margelo::nitro::live2dskia::MotionPriority::FORCE;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum MotionPriority - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::live2dskia::MotionPriority arg) {
+      switch (arg) {
+        case margelo::nitro::live2dskia::MotionPriority::IDLE: return JSIConverter<std::string>::toJSI(runtime, "idle");
+        case margelo::nitro::live2dskia::MotionPriority::NORMAL: return JSIConverter<std::string>::toJSI(runtime, "normal");
+        case margelo::nitro::live2dskia::MotionPriority::FORCE: return JSIConverter<std::string>::toJSI(runtime, "force");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert MotionPriority to JS - invalid value: "
+                                    + std::to_string(static_cast<int>(arg)) + "!");
+      }
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isString()) {
+        return false;
+      }
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("idle"):
+        case hashString("normal"):
+        case hashString("force"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,148 @@
 {
   "name": "@airisu-dev/react-native-live2d-skia",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "react-native-live2d-skia is a react native package built with Nitro",
+  "main": "src/index",
+  "types": "src/index",
+  "react-native": "src/index",
+  "source": "src/index",
+  "bin": {
+    "react-native-live2d-skia": "cli/build/index.js"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc --noEmit -p plugin && tsc --noEmit -p cli",
+    "test": "bun test",
+    "verify:package": "bun scripts/verifyPackage.ts",
+    "clean": "git clean -dfX",
+    "build": "bun run typecheck && bob build && tsc -b plugin/tsconfig.build.json cli/tsconfig.build.json",
+    "codegen": "nitrogen --logLevel=debug",
+    "build:node": "tsc -b plugin/tsconfig.build.json cli/tsconfig.build.json",
+    "prepack": "tsc -b plugin/tsconfig.build.json cli/tsconfig.build.json"
+  },
+  "keywords": [
+    "react-native",
+    "react-native-live2d-skia"
+  ],
+  "files": [
+    "src",
+    "!**/*.test.ts",
+    "react-native.config.js",
+    "lib",
+    "nitrogen",
+    "cpp",
+    "nitro.json",
+    "android/build.gradle",
+    "android/fix-prefab.gradle",
+    "android/gradle.properties",
+    "android/CMakeLists.txt",
+    "android/src",
+    "ios/**/*.h",
+    "ios/**/*.m",
+    "ios/**/*.mm",
+    "ios/**/*.cpp",
+    "ios/**/*.swift",
+    "app.plugin.js",
+    "plugin/build",
+    "cli/build",
+    "*.podspec",
+    "README.md"
+  ],
+  "repository": "https://github.com/airisu-dev/react-native-live2d-skia.git",
+  "author": "airisu-dev",
+  "license": "MIT",
+  "bugs": "https://github.com/airisu-dev/react-native-live2d-skia/issues",
+  "homepage": "https://github.com/airisu-dev/react-native-live2d-skia#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.4",
+    "@types/node": "26.6.5",
+    "@types/react": "19.2.0",
+    "nitrogen": "^0.37.1",
+    "react": "19.2.3",
+    "react-native": "0.86.3",
+    "react-native-builder-bob": "^0.40.18",
+    "react-native-nitro-modules": "^0.37.1",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "expo-asset": "*",
+    "expo-file-system": "*",
+    "react": "*",
+    "react-native": "*",
+    "react-native-gesture-handler": "*",
+    "react-native-nitro-modules": "*",
+    "react-native-reanimated": "*",
+    "react-native-skia": ">=3.3.0",
+    "@shopify/react-native-skia": ">=2.10.0",
+    "react-native-worklets": "*"
+  },
+  "peerDependenciesMeta": {
+    "@shopify/react-native-skia": {
+      "optional": true
+    },
+    "react-native-skia": {
+      "optional": true
+    }
+  },
+  "eslintConfig": {
+    "root": true,
+    "extends": [
+      "@react-native",
+      "prettier"
+    ],
+    "plugins": [
+      "prettier"
+    ],
+    "rules": {
+      "prettier/prettier": [
+        "warn",
+        {
+          "quoteProps": "consistent",
+          "singleQuote": true,
+          "tabWidth": 2,
+          "trailingComma": "es5",
+          "useTabs": false
+        }
+      ]
+    }
+  },
+  "eslintIgnore": [
+    "node_modules/",
+    "lib/"
+  ],
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false,
+    "semi": false
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "exclude": "**/{__tests__,__fixtures__,__mocks__}/**,**/*.test.ts",
+    "targets": [
+      "commonjs",
+      "module",
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "cubismSdk": {
+    "latest": "5-r.5",
+    "versions": {
+      "5-r.5": {
+        "sha256": "7ff3a4bbc19c0a8728965aa522ab77eb11b252916453e68a8a78d3b71188bb12"
+      }
+    }
+  }
+}

package/plugin/build/index.d.ts

@@ -0,0 +1,14 @@
+import { type ConfigPlugin } from 'expo/config-plugins';
+export interface Live2dSkiaPluginProps {
+    /** Cubism SDK for Native folder (the one with `cubism-info.yml`), relative to the app's root. */
+    cubismSdkPath: string;
+}
+export declare function nativeProperties(projectRoot: string, platformProjectRoot: string, sdkPath: string): {
+    "live2dSkia.cubismSdkPath": string;
+    "live2dSkia.skiaPackage": string;
+};
+export declare const withLive2dSkia: ConfigPlugin<Live2dSkiaPluginProps | undefined>;
+export declare function skiaPackageOf(projectRoot: string): string;
+export declare function warnIfMissing(sdkDir: string): void;
+declare const _default: ConfigPlugin<Live2dSkiaPluginProps | undefined>;
+export default _default;

package/plugin/build/index.js

@@ -0,0 +1,81 @@
+"use strict";
+// Expo config plugin: tells the native builds where the Cubism SDK for Native is.
+//
+//   "plugins": [["@airisu-dev/react-native-live2d-skia", { "cubismSdkPath": "./vendor/CubismSdkForNative" }]]
+//
+// Cubism Core is proprietary and not shipped: download the SDK with
+// `@airisu-dev/react-native-live2d-skia fetch-sdk`, accepting Live2D's license. The path is relative to the app's root.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withLive2dSkia = void 0;
+exports.nativeProperties = nativeProperties;
+exports.skiaPackageOf = skiaPackageOf;
+exports.warnIfMissing = warnIfMissing;
+const config_plugins_1 = require("expo/config-plugins");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+// Read by android/build.gradle and Live2dSkia.podspec.
+const SDK_PROPERTY = 'live2dSkia.cubismSdkPath';
+const SKIA_PROPERTY = 'live2dSkia.skiaPackage';
+// The Skia packages react-native-live2d-skia can draw with in C++, by preference.
+const SKIA_PACKAGES = ['react-native-skia', '@shopify/react-native-skia'];
+const FETCH_HINT = 'Download it with `@airisu-dev/react-native-live2d-skia fetch-sdk --accept-license` (through npx, bunx, yarn or pnpm).';
+const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, '..', '..', 'package.json'), 'utf8'));
+// Paths are written relative to the native folder, so a prebuilt project
+// still builds after it's moved or checked out somewhere else.
+const relativeTo = (dir, target) => path_1.default.relative(dir, target).split(path_1.default.sep).join('/');
+function nativeProperties(projectRoot, platformProjectRoot, sdkPath) {
+    const sdkDir = path_1.default.resolve(projectRoot, sdkPath);
+    return {
+        [SDK_PROPERTY]: relativeTo(platformProjectRoot, sdkDir),
+        [SKIA_PROPERTY]: skiaPackageOf(projectRoot),
+    };
+}
+const withLive2dSkia = (config, props) => {
+    const sdkPath = props?.cubismSdkPath;
+    if (!sdkPath) {
+        throw new Error('[react-native-live2d-skia] Set the Cubism SDK for Native folder: ' +
+            '["@airisu-dev/react-native-live2d-skia", { "cubismSdkPath": "./vendor/CubismSdkForNative" }]. ' +
+            FETCH_HINT);
+    }
+    config = (0, config_plugins_1.withGradleProperties)(config, (c) => {
+        const { projectRoot, platformProjectRoot } = c.modRequest;
+        warnIfMissing(path_1.default.resolve(projectRoot, sdkPath));
+        const values = nativeProperties(projectRoot, platformProjectRoot, sdkPath);
+        c.modResults = c.modResults.filter((item) => !(item.type === 'property' && item.key in values));
+        for (const [key, value] of Object.entries(values)) {
+            c.modResults.push({ type: 'property', key, value });
+        }
+        return c;
+    });
+    config = (0, config_plugins_1.withPodfileProperties)(config, (c) => {
+        const { projectRoot, platformProjectRoot } = c.modRequest;
+        Object.assign(c.modResults, nativeProperties(projectRoot, platformProjectRoot, sdkPath));
+        return c;
+    });
+    return config;
+};
+exports.withLive2dSkia = withLive2dSkia;
+// The Skia package the app depends on, by its own package.json: in a monorepo
+// both can be installed, but an app uses one. Empty when it has neither: the
+// native build then leaves out the C++ drawer.
+function skiaPackageOf(projectRoot) {
+    const appPackage = JSON.parse(fs_1.default.readFileSync(path_1.default.join(projectRoot, 'package.json'), 'utf8'));
+    const found = SKIA_PACKAGES.filter((name) => appPackage.dependencies?.[name]);
+    if (found.length > 1) {
+        console.warn(`[react-native-live2d-skia] The app depends on both ${found.join(' and ')}: drawing with ${found[0]}. Skia says not to install both.`);
+    }
+    if (found.length === 0) {
+        console.warn(`[react-native-live2d-skia] The app depends on neither ${SKIA_PACKAGES.join(' nor ')}. Install one: react-native-live2d-skia draws with Skia.`);
+    }
+    return found[0] ?? '';
+}
+// Not an error: CI may fetch the SDK after prebuild. The native build checks again.
+function warnIfMissing(sdkDir) {
+    if (!fs_1.default.existsSync(path_1.default.join(sdkDir, 'cubism-info.yml'))) {
+        console.warn(`[react-native-live2d-skia] Cubism SDK for Native not found at ${sdkDir}. ${FETCH_HINT}`);
+    }
+}
+exports.default = (0, config_plugins_1.createRunOncePlugin)(exports.withLive2dSkia, pkg.name, pkg.version);

package/src/components/Live2D.tsx

@@ -0,0 +1,131 @@
+import React, { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useFrameCallback, useSharedValue } from 'react-native-reanimated'
+import {
+  createSynchronizable,
+  createWorkletRuntime,
+  scheduleOnRuntime,
+  type WorkletRuntime,
+} from 'react-native-worklets'
+import type { Live2DModel } from '../loader/loadModel'
+import { Group, Picture, Skia, type SkPicture } from '../rendering/skia'
+import { addToTicker, type Live2DFrameStats, type PublishedFrame } from '../rendering/ticker'
+
+export type { Live2DFrameStats } from '../rendering/ticker'
+
+export interface Live2DProps {
+  model: Live2DModel | null
+  /** Top-left position on the canvas. */
+  x?: number
+  y?: number
+  /** Uniform scale of the model's native canvas size. */
+  scale?: number
+  /** Stops animating and keeps the current frame. */
+  paused?: boolean
+  /** Caps the frame rate, e.g. 30 to save battery. Default: the display's refresh rate. */
+  maxFps?: number
+  /** Called about once a second with timings of the animation loop. */
+  onFrameStats?: (stats: Live2DFrameStats) => void
+}
+
+const DISPLAY_SAMPLE_FRAMES = 60
+
+// Shown until the model loads. A recorder must begin recording before it can finish.
+const emptyRecorder = Skia.PictureRecorder()
+emptyRecorder.beginRecording(Skia.XYWHRect(0, 0, 0, 0))
+const EMPTY_PICTURE = emptyRecorder.finishRecordingAsPicture()
+
+// Models animate on a background thread so a busy JS thread doesn't drop frames:
+// one runtime and one loop (rendering/ticker) for every <Live2D>.
+let runtime: WorkletRuntime | null = null
+const live2dRuntime = () => (runtime ??= createWorkletRuntime({ name: 'live2d' }))
+
+export function Live2D({
+  model,
+  x = 0,
+  y = 0,
+  scale = 1,
+  paused = false,
+  maxFps,
+  onFrameStats,
+}: Live2DProps) {
+  // A shared value lets Skia redraw each frame without a React re-render.
+  const picture = useSharedValue<SkPicture>(model?.picture ?? EMPTY_PICTURE)
+  // Reset to the load-time frame only when the model changes, so pausing keeps the current frame.
+  const shownModel = useRef<Live2DModel | null>(null)
+  // The loop publishes frames here. scheduleOnUI can't be called from a custom
+  // worklet runtime (outside Bundle Mode), so the UI thread polls instead.
+  const [latest] = useState(() => createSynchronizable<PublishedFrame>(null))
+  // The frame shown, told back to the loop so it frees only frames no longer shown.
+  const [shown] = useState(() => createSynchronizable(-1))
+  // The display's frame interval: the shortest over a window of UI frames, so
+  // dropped frames don't count. 0 until measured.
+  const [displayFrameMs] = useState(() => createSynchronizable(0))
+  const sampleMin = useSharedValue(Infinity)
+  const sampleCount = useSharedValue(0)
+  useFrameCallback(({ timeSincePreviousFrame }) => {
+    const next = latest.getDirty()
+    if (next && next.frame !== shown.getDirty()) {
+      picture.value = next.picture
+      shown.setBlocking(next.frame)
+    }
+    if (timeSincePreviousFrame !== null && timeSincePreviousFrame > 0) {
+      sampleMin.value = Math.min(sampleMin.value, timeSincePreviousFrame)
+      if (++sampleCount.value >= DISPLAY_SAMPLE_FRAMES) {
+        displayFrameMs.setBlocking(sampleMin.value)
+        sampleMin.value = Infinity
+        sampleCount.value = 0
+      }
+    }
+  })
+
+  // Stable for the loop to call; updated after render, as refs mustn't be written while rendering.
+  const onFrameStatsRef = useRef(onFrameStats)
+  useLayoutEffect(() => {
+    onFrameStatsRef.current = onFrameStats
+  })
+  const reportStats = useCallback((stats: Live2DFrameStats) => onFrameStatsRef.current?.(stats), [])
+  const wantStats = onFrameStats !== undefined
+  const capFrameMs = maxFps ? 1000 / maxFps : 0
+
+  useEffect(() => {
+    if (!model) return
+    if (shownModel.current !== model) {
+      shownModel.current = model
+      // set(), not `.value =`, outside worklets: the React Compiler form.
+      picture.set(model.picture)
+    }
+    if (paused) return
+
+    // Frame numbers restart when the model starts animating again.
+    latest.setBlocking(null)
+    shown.setBlocking(-1)
+    const running = createSynchronizable(true)
+    scheduleOnRuntime(
+      live2dRuntime(),
+      addToTicker,
+      {
+        id: model.id,
+        native: model.native,
+        textures: model.textures,
+        shaders: model.shaders,
+        canvas: model.canvas,
+      },
+      {
+        target: latest,
+        shown,
+        running,
+        displayMs: displayFrameMs,
+        capMs: capFrameMs,
+        report: wantStats ? reportStats : null,
+      },
+    )
+    return () => running.setBlocking(false)
+  }, [model, paused, picture, latest, shown, displayFrameMs, capFrameMs, wantStats, reportStats])
+
+  if (!model) return null
+  return (
+    <Group transform={[{ translateX: x }, { translateY: y }, { scale }]}>
+      <Picture picture={picture} />
+    </Group>
+  )
+}

package/src/components/index.ts

@@ -0,0 +1,2 @@
+export type { Live2DFrameStats, Live2DProps } from './Live2D'
+export { Live2D } from './Live2D'

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export type {
+  Live2DGestureOptions,
+  Live2DGesturesOptions,
+  Live2DGestureTarget,
+} from './useLive2DGesture'
+export { useLive2DGesture, useLive2DGestures } from './useLive2DGesture'
+export type { Live2DModelState } from './useLive2DModel'
+export { useLive2DModel } from './useLive2DModel'

package/src/hooks/useLive2DGesture.ts

@@ -0,0 +1,140 @@
+import { useLayoutEffect, useMemo, useRef } from 'react'
+import { Gesture } from 'react-native-gesture-handler'
+import type { Live2DModel } from '../loader/loadModel'
+
+export interface Live2DGestureTarget {
+  model: Live2DModel | null
+  x?: number
+  y?: number
+  scale?: number
+  /**
+   * Called with the hit areas under a tap. Return true to skip the default
+   * reaction: a `Tap<area>` motion, else a random expression for `Head`, else a `Tap` motion.
+   */
+  onHit?: (hitAreas: string[]) => boolean | void
+  /** Makes the model draggable by long-press. Called with its new top-left; the app moves it. */
+  onMove?: (x: number, y: number) => void
+}
+
+export interface Live2DGesturesOptions {
+  /** Models follow the finger while it's down. Default true. */
+  focus?: boolean
+}
+
+export interface Live2DGestureOptions
+  extends Omit<Live2DGestureTarget, 'model'>,
+    Live2DGesturesOptions {}
+
+function react(model: Live2DModel, hitAreas: string[]) {
+  for (const area of hitAreas) {
+    const group = `Tap${area}`
+    if (model.motionGroups.includes(group)) {
+      model.motion(group)
+      return
+    }
+    if (area === 'Head' && model.expressionNames.length > 0) {
+      model.expression()
+      return
+    }
+  }
+  // Some models have one `Tap` group for every area.
+  if (model.motionGroups.includes('Tap')) model.motion('Tap')
+}
+
+const LONG_PRESS_MS = 350
+
+function toModel({ x = 0, y = 0, scale = 1 }: Live2DGestureTarget, px: number, py: number) {
+  return [(px - x) / scale, (py - y) / scale] as const
+}
+
+function topmostHit(targets: Live2DGestureTarget[], px: number, py: number) {
+  // Later targets are drawn over earlier ones.
+  for (let i = targets.length - 1; i >= 0; i--) {
+    const t = targets[i]!
+    if (!t.model) continue
+    const hitAreas = t.model.hitTest(...toModel(t, px, py))
+    if (hitAreas.length > 0) return { target: t, hitAreas }
+  }
+  return null
+}
+
+/**
+ * Touch interaction for several `<Live2D>` models in one canvas, for a
+ * `<GestureDetector>` around the `<Canvas>`. List targets in drawing order.
+ */
+export function useLive2DGestures(
+  targets: Live2DGestureTarget[],
+  { focus = true }: Live2DGesturesOptions = {},
+) {
+  // The React Compiler miscompiled these callbacks (a `let` shared between them).
+  'use no memo'
+
+  // Read at event time, so the gesture is built once. Updated after render.
+  const latest = useRef(targets)
+  useLayoutEffect(() => {
+    latest.current = targets
+  })
+
+  // The callbacks only run on touch events; the refs rule can't tell through RNGH's builder API.
+  /* eslint-disable react-hooks/refs */
+  return useMemo(() => {
+    const focusAll = (px: number, py: number) => {
+      for (const t of latest.current) t.model?.focus(...toModel(t, px, py))
+    }
+
+    const pan = Gesture.Pan()
+      .runOnJS(true)
+      .enabled(focus)
+      .onBegin((e) => focusAll(e.x, e.y))
+      .onUpdate((e) => focusAll(e.x, e.y))
+      .onFinalize(() => {
+        for (const t of latest.current) t.model?.resetFocus()
+      })
+
+    // Shorter than a long press, so picking a model up isn't also a tap.
+    const tap = Gesture.Tap()
+      .runOnJS(true)
+      .maxDuration(LONG_PRESS_MS - 50)
+      .onEnd((e, success) => {
+        if (!success) return
+        const hit = topmostHit(latest.current, e.x, e.y)
+        if (hit && hit.target.onHit?.(hit.hitAreas) !== true) {
+          react(hit.target.model!, hit.hitAreas)
+        }
+      })
+
+    // The dragged model (found again by model, as targets can change) and the finger's
+    // offset from its top-left. On an object so it survives recompilation.
+    const drag: {
+      current: { model: Live2DModel; dx: number; dy: number } | null
+    } = { current: null }
+    const dragPan = Gesture.Pan()
+      .runOnJS(true)
+      .activateAfterLongPress(LONG_PRESS_MS)
+      .onStart((e) => {
+        const hit = topmostHit(latest.current, e.x, e.y)
+        if (!hit?.target.onMove) return
+        const { model, x = 0, y = 0 } = hit.target
+        drag.current = { model: model!, dx: e.x - x, dy: e.y - y }
+      })
+      .onUpdate((e) => {
+        if (!drag.current) return
+        const { model, dx, dy } = drag.current
+        latest.current.find((t) => t.model === model)?.onMove?.(e.x - dx, e.y - dy)
+      })
+      .onFinalize(() => {
+        drag.current = null
+      })
+
+    return Gesture.Simultaneous(pan, tap, dragPan)
+  }, [focus])
+  /* eslint-enable react-hooks/refs */
+}
+
+/** Touch interaction for one `<Live2D>`. For several models in one canvas, use `useLive2DGestures`. */
+export function useLive2DGesture(
+  model: Live2DModel | null,
+  { focus, ...target }: Live2DGestureOptions = {},
+) {
+  return useLive2DGestures([{ model, ...target }], { focus })
+}