react-native-impeller-platform 0.0.0-bootstrap.0 → 0.1.0

package/src/metro-shims/shims/reanimated/values.js

@@ -0,0 +1,264 @@
+'use strict';
+// SC-26. Shared values and the with* animations of the reanimated stub, run
+// on the JS thread by clock.js. An animation is a plain object with
+// start(from, now) and frame(now) -> done; assigning one to sv.value runs it.
+const {now, onFrame} = require('./clock');
+const {Easing, toEasing} = require('./easing');
+const {mix} = require('./interpolate');
+
+const ANIM = Symbol.for('rni.reanimated.animation');
+const isAnimation = (v) => v != null && typeof v === 'object' && v[ANIM] === true;
+
+// Shared values read while a tracker is set are recorded (useAnimatedStyle /
+// useDerivedValue re-run when one of them changes).
+let tracker = null;
+function track(fn) {
+  const prev = tracker;
+  const seen = new Set();
+  tracker = seen;
+  try {
+    return {result: fn(), deps: seen};
+  } finally {
+    tracker = prev;
+  }
+}
+
+class SharedValue {
+  constructor(v) {
+    this._value = v;
+    this._anim = null;
+    this._listeners = new Map();
+    this._seq = 0;
+  }
+  get value() {
+    if (tracker) tracker.add(this);
+    return this._value;
+  }
+  set value(v) {
+    this._anim = null;
+    if (isAnimation(v)) {
+      const anim = v;
+      this._anim = anim;
+      anim.start(this._value, now());
+      onFrame((t) => {
+        if (this._anim !== anim) return false;
+        const done = anim.frame(t);
+        this._write(anim.current);
+        if (done) {
+          this._anim = null;
+          anim.finish(true);
+        }
+        return !done;
+      });
+      return;
+    }
+    this._write(v);
+  }
+  _write(v) {
+    this._value = v;
+    for (const fn of Array.from(this._listeners.values())) fn(v);
+  }
+  get() {
+    return this.value;
+  }
+  set(v) {
+    this.value = typeof v === 'function' ? v(this._value) : v;
+  }
+  modify(fn) {
+    if (fn) this.value = fn(this._value);
+  }
+  addListener(id, fn) {
+    this._listeners.set(id, fn);
+  }
+  removeListener(id) {
+    this._listeners.delete(id);
+  }
+  // internal: subscribe with an auto id
+  _subscribe(fn) {
+    const id = `__rni${this._seq++}`;
+    this._listeners.set(id, fn);
+    return () => this._listeners.delete(id);
+  }
+  _cancel() {
+    const a = this._anim;
+    this._anim = null;
+    if (a) a.finish(false);
+  }
+}
+
+const makeMutable = (v) => new SharedValue(v);
+const cancelAnimation = (sv) => sv && sv._cancel && sv._cancel();
+
+function animation(spec, callback) {
+  // defineProperties, not spread: withDelay forwards toValue through accessors.
+  const a = {
+    [ANIM]: true,
+    current: undefined,
+    finish(ok) {
+      if (callback) callback(ok, this.current);
+    },
+  };
+  return Object.defineProperties(a, Object.getOwnPropertyDescriptors(spec));
+}
+
+function withTiming(toValue, config, callback) {
+  const duration = config && config.duration != null ? config.duration : 300;
+  const ease = toEasing(config && config.easing, Easing.inOut(Easing.quad));
+  return animation({
+    toValue,
+    start(from, t) {
+      this.from = from;
+      this.t0 = t;
+      this.current = from;
+    },
+    frame(t) {
+      const p = duration <= 0 ? 1 : Math.min(1, (t - this.t0) / duration);
+      this.current = p >= 1 ? this.toValue : mix(this.from, this.toValue, ease(p));
+      return p >= 1;
+    },
+  }, callback);
+}
+
+// Damped harmonic oscillator, Reanimated 3's defaults, integrated in 1 ms
+// steps so the result does not depend on the frame rate.
+function withSpring(toValue, config, callback) {
+  const c = {mass: 1, stiffness: 100, damping: 10, velocity: 0, overshootClamping: false,
+    restDisplacementThreshold: 0.01, restSpeedThreshold: 2, ...(config || {})};
+  return animation({
+    toValue,
+    start(from, t) {
+      this.x = typeof from === 'number' ? from : toValue;
+      this.v = c.velocity;
+      this.t = t;
+      this.current = this.x;
+    },
+    frame(t) {
+      const to = this.toValue;
+      let steps = Math.min(Math.max(0, Math.round(t - this.t)), 1000);
+      this.t = t;
+      while (steps-- > 0) {
+        const a = (-c.stiffness * (this.x - to) - c.damping * this.v) / c.mass;
+        this.v += a * 0.001;
+        this.x += this.v * 0.001;
+      }
+      const overshot = c.overshootClamping && (this.x - to) * (this.current - to) < 0;
+      const rest = Math.abs(this.x - to) < c.restDisplacementThreshold && Math.abs(this.v) < c.restSpeedThreshold;
+      this.current = overshot || rest ? to : this.x;
+      return overshot || rest;
+    },
+  }, callback);
+}
+
+function withDecay(config, callback) {
+  const c = {velocity: 0, deceleration: 0.998, ...(config || {})};
+  return animation({
+    start(from, t) {
+      this.x = typeof from === 'number' ? from : 0;
+      this.v = c.velocity;
+      this.t = t;
+      this.current = this.x;
+    },
+    frame(t) {
+      const dt = Math.max(0, t - this.t);
+      this.t = t;
+      const k = Math.pow(c.deceleration, dt);
+      this.x += (this.v / 1000) * ((1 - k) / (1 - c.deceleration));
+      this.v *= k;
+      let done = Math.abs(this.v) < 0.5;
+      if (Array.isArray(c.clamp)) {
+        const [lo, hi] = c.clamp;
+        if (this.x <= lo || this.x >= hi) {
+          this.x = Math.min(Math.max(this.x, lo), hi);
+          done = true;
+        }
+      }
+      this.current = this.x;
+      return done;
+    },
+  }, callback);
+}
+
+const toAnim = (a) => (isAnimation(a) ? a : withTiming(a, {duration: 0}));
+
+function withDelay(delayMs, inner) {
+  const a = toAnim(inner);
+  return animation({
+    get toValue() {
+      return a.toValue;
+    },
+    set toValue(v) {
+      a.toValue = v;
+    },
+    start(from, t) {
+      this.t0 = t;
+      this.from = from;
+      this.started = false;
+      this.current = from;
+    },
+    frame(t) {
+      if (t - this.t0 < delayMs) return false;
+      if (!this.started) {
+        this.started = true;
+        a.start(this.from, this.t0 + delayMs);
+      }
+      const done = a.frame(t);
+      this.current = a.current;
+      if (done) a.finish(true);
+      return done;
+    },
+  });
+}
+
+function withSequence(...inners) {
+  const list = inners.map(toAnim);
+  return animation({
+    start(from, t) {
+      this.i = 0;
+      this.current = from;
+      if (list.length) list[0].start(from, t);
+    },
+    frame(t) {
+      while (this.i < list.length) {
+        const a = list[this.i];
+        const done = a.frame(t);
+        this.current = a.current;
+        if (!done) return false;
+        a.finish(true);
+        this.i++;
+        if (this.i < list.length) list[this.i].start(this.current, t);
+      }
+      return true;
+    },
+  });
+}
+
+// numberOfReps <= 0 repeats forever; reverse swaps the inner animation's
+// target with its start value on every other run.
+function withRepeat(inner, numberOfReps = 2, reverse = false, callback) {
+  const a = toAnim(inner);
+  return animation({
+    start(from, t) {
+      this.n = 0;
+      this.origin = from;
+      this.target = a.toValue;
+      this.current = from;
+      a.start(from, t);
+    },
+    frame(t) {
+      const done = a.frame(t);
+      this.current = a.current;
+      if (!done) return false;
+      a.finish(true);
+      this.n++;
+      if (numberOfReps > 0 && this.n >= numberOfReps) return true;
+      if (reverse && 'toValue' in a) a.toValue = this.n % 2 ? this.origin : this.target;
+      a.start(reverse ? this.current : this.origin, t);
+      return false;
+    },
+  }, callback);
+}
+
+module.exports = {
+  SharedValue, makeMutable, isAnimation, track, cancelAnimation,
+  withTiming, withSpring, withDecay, withDelay, withSequence, withRepeat,
+};

package/src/metro-shims/shims/reanimated.impeller.js

@@ -0,0 +1,90 @@
+'use strict';
+// ENG-19 (moved from HostApp's app-level metro-shims/reanimated-stub.js).
+// react-native-reanimated for the `impeller` platform.
+//
+// WHY: the engine vends no Reanimated / Worklets native module, so the real
+// package cannot initialise, and an app that does not install it cannot even
+// BUNDLE: react-native-css (NativeWind 5) require()s 'react-native-reanimated'
+// from native/reanimated.js on every className render that carries a
+// transition/animation, and Gluestack's motion parts import it at module top.
+//
+// WHAT IT DOES (SC-26): animated components are wrappers that re-render on a
+// JS-thread clock, shared values and with* helpers really animate, and
+// react-native-css transitions / animate-* move. Layout-animation presets stay
+// chainable no-ops. Resolved only when the app has NOT
+// installed react-native-reanimated itself (see metro-shims/index.js).
+const RN = require('react-native');
+const {createAnimatedComponent: animated} = require('./reanimated/component');
+const hooks = require('./reanimated/hooks');
+const values = require('./reanimated/values');
+const {Easing: StubEasing, cubicBezier, cssSteps} = require('./reanimated/easing');
+const {interpolate: interp} = require('./reanimated/interpolate');
+
+// Chainable layout-animation builder: FadeIn.duration(200).delay(50) etc. all
+// return the same inert object.
+const preset = new Proxy(function () {}, {
+  get: (t, k) => (k === '__esModule' ? false : k === 'build' ? () => () => ({}) : () => preset),
+  apply: () => preset,
+});
+
+const Animated = {
+  View: animated(RN.View),
+  Text: animated(RN.Text),
+  Image: animated(RN.Image),
+  ScrollView: animated(RN.ScrollView),
+  FlatList: animated(RN.FlatList),
+  createAnimatedComponent: animated,
+};
+
+const sharedValue = (v) => ({value: v, get: () => v, set: () => {}, modify: () => {}});
+
+module.exports = {
+  __esModule: true,
+  __impellerStub: true,
+  default: Animated,
+  createAnimatedComponent: animated,
+  // layout-animation presets Gluestack's parts reference
+  FadeIn: preset,
+  FadeOut: preset,
+  FadeInUp: preset,
+  FadeInDown: preset,
+  FadeOutUp: preset,
+  FadeOutDown: preset,
+  ZoomIn: preset,
+  ZoomOut: preset,
+  SlideInDown: preset,
+  SlideOutDown: preset,
+  SlideInUp: preset,
+  SlideOutUp: preset,
+  SlideInLeft: preset,
+  SlideOutLeft: preset,
+  SlideInRight: preset,
+  SlideOutRight: preset,
+  Layout: preset,
+  LinearTransition: preset,
+  // hooks and animation helpers (JS-thread implementation, see ./reanimated/)
+  useSharedValue: hooks.useSharedValue,
+  useDerivedValue: hooks.useDerivedValue,
+  useAnimatedStyle: hooks.useAnimatedStyle,
+  useAnimatedProps: hooks.useAnimatedProps,
+  useAnimatedRef: () => ({current: null}),
+  useAnimatedReaction: hooks.useAnimatedReaction,
+  useAnimatedScrollHandler: hooks.useAnimatedScrollHandler,
+  useReducedMotion: () => false,
+  withTiming: values.withTiming,
+  withSpring: values.withSpring,
+  withDecay: values.withDecay,
+  withDelay: values.withDelay,
+  withRepeat: values.withRepeat,
+  withSequence: values.withSequence,
+  cancelAnimation: values.cancelAnimation,
+  runOnJS: (f) => f,
+  runOnUI: (f) => f,
+  interpolate: interp,
+  Extrapolation: {CLAMP: 'clamp', EXTEND: 'extend', IDENTITY: 'identity'},
+  ReduceMotion: {System: 'system', Always: 'always', Never: 'never'},
+  Easing: StubEasing,
+  // CSS-animation timing helpers react-native-css reads
+  cubicBezier,
+  steps: cssSteps,
+};

package/src/platformview/index.js

@@ -0,0 +1,23 @@
+'use strict';
+// FP-44 — platform views (Flutter's PlatformViewLayer + ExternalViewEmbedder).
+//
+// <ImpellerPlatformView color="#00aa00" style={...} /> is a native OS child view
+// (an X11 child window on linux windowed GL) that the engine positions, clips
+// and stacks to the view's box every frame; RN content drawn after it in paint
+// order is composited above it. This first native view is a solid colour.
+// Translate and rect clips are composited; scale/rotate/skew are not (the view
+// is placed at the transformed bounds and the engine logs
+// `platform_view_unsupported`). Hosts without an embedder (darwin, Windows,
+// headless) paint the colour in place.
+
+const {processColor} = require('react-native');
+const NativeComponentRegistry = require('react-native/Libraries/NativeComponent/NativeComponentRegistry');
+
+const ImpellerPlatformView = NativeComponentRegistry.get('ImpellerPlatformView', () => ({
+  uiViewClassName: 'ImpellerPlatformView',
+  bubblingEventTypes: {},
+  directEventTypes: {},
+  validAttributes: {color: {process: processColor}},
+}));
+
+module.exports = {ImpellerPlatformView};

package/src/resolve.js

@@ -0,0 +1,238 @@
+'use strict';
+// Locates the prebuilt Impeller engine binary for the current platform.
+//
+// Delivery model (PLAN D4): the main package declares every
+// `@blbaker/react-native-impeller-platform-engine-<platform>-<arch>` as an OPTIONAL dependency.
+// npm installs only the one matching the host, so a consumer never compiles C++.
+//
+// Rules this file enforces:
+//   1. `IMPELLER_ENGINE_BINARY` env var wins  (local engine development).
+//   2. Otherwise resolve the per-platform package from THIS file's location
+//      (`__dirname`) FIRST -- install and tarball must both work, and an
+//      installed copy must never be outranked by something in the CWD.
+//   3. On failure, throw an error that NAMES the missing package. A resolver that
+//      says "not found" without the package name costs the consumer an hour.
+//   4. Refuse a version mismatch between the engine package and this package.
+//      Silent lockstep drift produces ABI crashes that look like renderer bugs.
+//
+// ⛔ `__dirname` ALONE IS NOT ENOUGH UNDER link:/file: (P10, 2026-09-02)
+//
+// The original comment here said "never from CWD -- link, install and tarball
+// must all work". The first two words were right and the last claim was not
+// TESTED: no gate ever ran the resolver through a symlinked package, so the
+// linked case was asserted in a comment and broken in fact.
+//
+// Under `file:`/`npm link`, node_modules/react-native-impeller-platform is a
+// SYMLINK back to this source checkout. `__dirname` therefore lands in the
+// checkout, whose node_modules does NOT contain the engine package -- the
+// engine lives in the checkout's sibling `packages-engine/engine-<triple>/`,
+// which is where tools/engine-build.sh writes it and which no node_modules
+// walk from anywhere will ever reach. Reproduced: a linked consumer app with
+// the engine package ALSO linked into its own node_modules still failed,
+// because resolution started from the symlink TARGET, not the app.
+//
+// So the anchor list is ordered, not replaced:
+//   a. __dirname                     -- installed + tarball. Unchanged, first.
+//   b. INIT_CWD / process.cwd()      -- the consumer's own tree, which is what
+//                                       __dirname stops pointing at under link:.
+//   c. <checkout>/packages-engine/   -- the linked source tree's own build
+//                                       output, read directly by path.
+// (a) still wins in every shipped install, so this cannot change what a real
+// consumer resolves. It only gives the linked case somewhere true to look.
+//
+// This is deliberately NOT "just set IMPELLER_ENGINE_BINARY in the app's
+// script". Line 79 of this file already rules that out: a package that needs
+// an env var to function has not shipped. That applies to our own dev loop
+// too -- an env var in a downstream app's paint-proof script is a workaround
+// that hides this defect instead of fixing it.
+
+const fs = require('fs');
+const path = require('path');
+
+// ⛔ THIS SET IS A PROMISE, NOT A ROADMAP (P7, 2026-08-14)
+//
+// A triple listed here with no published engine package produces the WORST
+// possible failure: npm silently skips a missing optionalDependency and exits
+// 0, so the user gets a clean install with no engine, then hits the "Missing
+// engine package" error below — which instructs them to install a package that
+// does not exist. A good error message with an impossible instruction.
+//
+// So a triple joins this list when its engine package is BUILT, not when it is
+// planned. `tools/ci-release-meta.sh` fails the build if the two ever disagree.
+// darwin-arm64/darwin-x64/linux-arm64 belong here the moment P6 ships them.
+const SUPPORTED = new Set([
+  'linux-x64',
+  'win32-x64',
+  'darwin-arm64',
+]);
+
+function hostTriple(platform = process.platform, arch = process.arch) {
+  return `${platform}-${arch}`;
+}
+
+function packageNameFor(triple) {
+  return `@blbaker/react-native-impeller-platform-engine-${triple}`;
+}
+
+function binaryFileName(platform = process.platform) {
+  return platform === 'win32' ? 'rn-impeller.exe' : 'rn-impeller';
+}
+
+function ownVersion() {
+  return require('../package.json').version;
+}
+
+/**
+ * Ordered list of places to look for the engine package's package.json.
+ *
+ * ⛔ ORDER IS THE WHOLE SAFETY ARGUMENT. __dirname is index 0, so for any
+ * normally-installed consumer this function returns on the first candidate and
+ * behaves exactly as it did before link: support existed. Everything after it
+ * is reached ONLY when the __dirname walk found nothing -- i.e. only in the
+ * case that used to throw.
+ */
+function engineCandidates(triple, opts) {
+  const env = opts.env || process.env;
+  const cwd = opts.cwd || process.cwd();
+  const out = [];
+
+  // (a) Installed / tarball. Unchanged, and always first.
+  out.push({kind: 'resolve', from: __dirname, source: 'package'});
+
+  // (b) The consumer's own tree. Under link:/file: this is the only anchor that
+  //     still points at the app, because __dirname followed the symlink out of
+  //     it. npm sets INIT_CWD to the directory the command was run from, which
+  //     survives npm running scripts from elsewhere; process.cwd() covers a
+  //     plain `node ...` invocation.
+  const consumerRoots = [env.INIT_CWD, cwd].filter(Boolean);
+  for (const root of consumerRoots) {
+    out.push({kind: 'resolve', from: path.join(root, 'node_modules'), source: 'linked-consumer'});
+  }
+
+  // (c) The linked SOURCE CHECKOUT's own build output. package/src/resolve.js
+  //     -> ../../packages-engine/engine-<triple>. This is a direct path probe,
+  //     not a node_modules walk, because engine-build.sh writes the binary
+  //     there and nothing ever installs it into a node_modules anywhere.
+  out.push({
+    kind: 'path',
+    // The directory is named by the triple, not the package: the npm name is
+    // scoped under a different prefix and does not match the folder.
+    dir: path.join(__dirname, '..', '..', 'packages-engine', `engine-${triple}`),
+    source: 'linked-checkout',
+  });
+
+  return out;
+}
+
+/**
+ * @returns {{binary: string, source: string, packageName: string|null, version: string|null}}
+ */
+function resolveEngine(opts = {}) {
+  const platform = opts.platform || process.platform;
+  const arch = opts.arch || process.arch;
+  const env = opts.env || process.env;
+  const triple = hostTriple(platform, arch);
+
+  const override = env.IMPELLER_ENGINE_BINARY;
+  if (override) {
+    if (!fs.existsSync(override)) {
+      throw new Error(
+        `IMPELLER_ENGINE_BINARY is set to "${override}" but no file exists there.\n` +
+          'Unset it to fall back to the installed engine package.'
+      );
+    }
+    return {binary: path.resolve(override), source: 'env', packageName: null, version: null};
+  }
+
+  if (!SUPPORTED.has(triple)) {
+    // ⛔ DO NOT TELL A CONSUMER TO BUILD THE ENGINE.
+    // This message used to lead with `export IMPELLER_ENGINE_BINARY=...`, which
+    // reads as "the supported fix is to compile a C++ engine yourself" — a
+    // 40-minute Hermes build, a native toolchain, and an env var the app now
+    // depends on forever. That is contributor work leaking into a consumer
+    // error path. A package that needs an env var to function has not shipped.
+    //
+    // Say what is true (this platform is not supported yet) and point at the
+    // one place that will change when it is. The env var is still honoured and
+    // still documented under contributing — it is simply not the answer we hand
+    // to someone whose install just failed.
+    throw new Error(
+      `react-native-impeller-platform does not support ${triple} yet.\n` +
+        `Supported: ${[...SUPPORTED].join(', ')}\n\n` +
+        'Track or request platform support:\n' +
+        '    https://github.com/blbaker/react-native-impeller-platform/issues\n'
+    );
+  }
+
+  const pkgName = packageNameFor(triple);
+  let pkgJsonPath = null;
+  let source = null;
+  const tried = [];
+  for (const cand of engineCandidates(triple, {env, cwd: opts.cwd})) {
+    if (cand.kind === 'resolve') {
+      tried.push(cand.from);
+      try {
+        pkgJsonPath = require.resolve(`${pkgName}/package.json`, {paths: [cand.from]});
+      } catch (e) {
+        continue;
+      }
+    } else {
+      const p = path.join(cand.dir, 'package.json');
+      tried.push(cand.dir);
+      if (!fs.existsSync(p)) continue;
+      pkgJsonPath = p;
+    }
+    source = cand.source;
+    break;
+  }
+
+  if (!pkgJsonPath) {
+    throw new Error(
+      `Missing engine package "${pkgName}".\n` +
+        'It ships as an optional dependency of react-native-impeller-platform and should\n' +
+        'been installed automatically. Install it explicitly:\n\n' +
+        `    npm install ${pkgName}@${ownVersion()}\n\n` +
+        // ⛔ SAY WHERE WE LOOKED. The old message named the package but not the
+        // search path, so a linked checkout whose engine was simply never built
+        // produced the same text as a genuinely broken install.
+        'Looked in:\n' +
+        tried.map((t) => `    ${t}`).join('\n') +
+        '\n\nOr point IMPELLER_ENGINE_BINARY at a locally built engine.'
+    );
+  }
+
+  const enginePkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+  const expected = ownVersion();
+  if (enginePkg.version !== expected) {
+    throw new Error(
+      `Engine version mismatch: ${pkgName}@${enginePkg.version} is installed but\n` +
+        `react-native-impeller-platform@${expected} requires exactly ${expected}.\n` +
+        'The engine C ABI is versioned in lockstep; mixed versions crash at runtime.\n\n' +
+        `    npm install ${pkgName}@${expected}`
+    );
+  }
+
+  const binary = path.join(path.dirname(pkgJsonPath), 'bin', binaryFileName(platform));
+  if (!fs.existsSync(binary)) {
+    throw new Error(
+      `Engine package "${pkgName}" is installed but its binary is missing:\n  ${binary}\n` +
+        // A linked checkout reaches this when the package.json is committed but
+        // packages-engine/*/bin is gitignored and was never built. "Corrupt --
+        // reinstall it" is the wrong instruction there, so name the real fix.
+        (source === 'linked-checkout'
+          ? `This is a LINKED SOURCE CHECKOUT, not an installed package. Build the engine:\n` +
+            `    bash tools/engine-build.sh ${platform} ${arch}`
+          : 'The package is corrupt -- reinstall it.')
+    );
+  }
+  return {binary, source, packageName: pkgName, version: enginePkg.version};
+}
+
+module.exports = {
+  resolveEngine,
+  hostTriple,
+  packageNameFor,
+  binaryFileName,
+  engineCandidates,
+  SUPPORTED,
+};