@felipe-software/react-native-gpui 0.0.0-stage → 1.0.1

package/scripts/react-refresh-swc.mjs

@@ -0,0 +1,35 @@
+import { createRequire } from 'node:module'
+
+export function createReactRefreshSwcTransform() {
+  const require = createRequire(import.meta.url)
+  const swc = require('@swc/core')
+
+  return async function transformReactRefresh(source, { filename, isTs, isJsx }) {
+    const result = await swc.transform(source, {
+      filename,
+      sourceMaps: false,
+      jsc: {
+        target: 'es2022',
+        parser: isTs
+          ? { syntax: 'typescript', tsx: isJsx }
+          : { syntax: 'ecmascript', jsx: isJsx },
+        transform: {
+          react: {
+            runtime: 'automatic',
+            development: true,
+            refresh: {
+              refreshReg: '$RNGPUIRefreshReg$',
+              refreshSig: '$RefreshSig$',
+              emitFullSignatures: false,
+            },
+          },
+        },
+      },
+      module: {
+        type: 'es6',
+      },
+    })
+    const moduleId = JSON.stringify(filename)
+    return `const $RNGPUIRefreshReg$ = (type, id) => globalThis.$RefreshReg$(type, ${moduleId} + " " + id);\n${result.code}`
+  }
+}

package/scripts/reanimated-bun-plugin.mjs

@@ -0,0 +1,188 @@
+// Bun-build plugin: wire real react-native-reanimated@4 + react-native-worklets +
+// @tamagui/animations-reanimated for the embedded JavaScriptCore target.
+//
+// HOW IT WORKS (the winning approach — see scripts/prebuild-reanimated.mjs):
+// reanimated's `lib/module` re-export-barrel graph trips Bun's bundler into a
+// tree-shake-then-dangle bug (`import_xN is not defined` at eval). ESBUILD bundles the
+// same graph correctly. So we PRE-BUNDLE reanimated (and @tamagui/animations-reanimated)
+// into self-contained ESM chunks with esbuild (worklets babel transform + native-seam
+// redirect baked in), keeping `react` / `react-native-worklets` / `react-native-gpui`
+// external. This plugin then simply ALIASES:
+//   react-native-reanimated      → .reanimated-prebuilt/react-native-reanimated.mjs
+//   @tamagui/animations-reanimated → .reanimated-prebuilt/tamagui-animations-reanimated.mjs
+//   react-native-worklets        → ts/src/reanimated/worklets.ts (cross-runtime adapter,
+//                                   which force-imports the seam → installs the globals)
+// Bun then just includes those single files — no deep tree-shake of reanimated's graph.
+//
+// gpui runs separate React and UI JavaScriptCore runtimes. Worklets and shared values cross
+// through the adapter, and `global._updateProps` is the off-thread fast path
+// (→ `__rngpui_setNodeStyle` → Rust animated-style overlay → cx.notify without a React
+// re-commit). The prebuilt chunks contain the real reanimated + Tamagui driver; the seam
+// and worklets adapter provide the thin native seam.
+//
+// Run `bun scripts/prebuild-reanimated.mjs` whenever react-native-reanimated or
+// @tamagui/animations-reanimated changes (or on postinstall). If the prebuilt chunk is
+// missing, this plugin throws with that instruction.
+//
+// Usage:
+//   import { reanimatedBunPlugin } from '<rng>/ts/scripts/reanimated-bun-plugin.mjs'
+//   plugins: [reanimatedBunPlugin({ rngTsRoot })]
+//     rngTsRoot      — absolute path to react-native-gpui/ts (seam/worklets/prebuilt live here)
+//     prebuiltDir    — override the prebuilt chunk dir (default: <rngTsRoot>/.reanimated-prebuilt)
+
+import { resolve, sep } from 'node:path'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+
+const LIBRARY_SPECIFIER = /^(?:@felipe-software\/)?react-native-gpui$/
+const BABEL_PACKAGES = '@babel/core @babel/plugin-syntax-jsx @babel/preset-typescript react-native-worklets@0.8.1'
+
+function defaultLibraryEntry(rngTsRoot) {
+  const source = resolve(rngTsRoot, 'src/index.ts')
+  return existsSync(source) ? source : resolve(rngTsRoot, 'dist/index.js')
+}
+
+// worklet keywords — gate the babel transform so we only pay for files that use them.
+const WORKLET_KEYWORDS =
+  /worklet|useAnimatedStyle|useAnimatedProps|useDerivedValue|useAnimatedReaction|useAnimatedGestureHandler|useAnimatedScrollHandler|useFrameCallback|useWorkletCallback|withTiming|withSpring|withDecay|withDelay|withRepeat|runOnUI|createAnimatedPropAdapter/
+
+export function reanimatedBunPlugin(opts = {}) {
+  const rngTsRoot = opts.rngTsRoot
+  if (!rngTsRoot) throw new Error('reanimatedBunPlugin: rngTsRoot is required')
+  const resolveRoot = opts.resolveRoot || rngTsRoot
+  const workletsPath = resolve(rngTsRoot, 'src/reanimated/worklets.ts')
+  const seamPath = resolve(rngTsRoot, 'src/reanimated/seam.ts')
+  const reanimatedHostPath = resolve(rngTsRoot, 'src/reanimated/reanimated-host.ts')
+  const prebuiltDir = opts.prebuiltDir || resolve(rngTsRoot, '.reanimated-prebuilt')
+  const reanimatedChunk = resolve(prebuiltDir, 'react-native-reanimated.mjs')
+  const tamaguiReanimatedChunk = resolve(prebuiltDir, 'tamagui-animations-reanimated.mjs')
+  // the prebuilt chunks emit external `import { View } from "react-native"`; resolve
+  // `react-native` → the gpui RN-compatible index. When the host bundler already aliases
+  // it (the gui app does), pass aliasReactNative:false.
+  const libraryEntry = opts.libraryEntry || defaultLibraryEntry(rngTsRoot)
+  const reactNativeIndex = opts.reactNativeIndex || libraryEntry
+  const aliasReactNative = opts.aliasReactNative !== false
+  const transformSource = opts.transformSource
+  const libraryBuildDir = resolve(rngTsRoot, 'dist') + sep
+
+  // babel worklets transform — applied to APP + Tamagui-driver source (NOT the prebuilt
+  // reanimated chunk, which already ran it, and NOT reanimated node_modules). This is
+  // REQUIRED: `useAnimatedStyle`/`useDerivedValue` read `updater.__closure` to extract
+  // the SharedValues a worklet depends on (its mapper inputs); without the babel lift
+  // the closure is empty, the mapper subscribes to nothing, a `sv.value = …` write never
+  // re-runs the mapper, and a Tamagui spring never advances (snaps to its target). The
+  // lifted function carries `this.__closure` in `__initData.code` so the UI runtime can
+  // deserialize the mapper with the SharedValues it captured.
+  const pluginRequires = [...new Set([resolveRoot, rngTsRoot])].map((dir) => createRequire(resolve(dir, 'package.json')))
+  let babel = null
+  let workletsPluginPath = null
+  let jsxSyntax = null
+  let presetTs = null
+  const loadBabel = (filename) => {
+    if (babel) return
+    for (const pluginRequire of pluginRequires) {
+      try {
+        workletsPluginPath = pluginRequire.resolve('react-native-worklets/plugin')
+        jsxSyntax = pluginRequire.resolve('@babel/plugin-syntax-jsx')
+        presetTs = pluginRequire.resolve('@babel/preset-typescript')
+        babel = pluginRequire('@babel/core')
+        return
+      } catch {}
+    }
+    throw new Error(
+      `[reanimated] ${filename} uses worklets, which need the worklets Babel transform.\n` +
+        `  install: bun add -d ${BABEL_PACKAGES}`,
+    )
+  }
+
+  return {
+    name: 'reanimated prebuilt chunks + worklets seam',
+    setup(build) {
+      if (aliasReactNative) {
+        build.onResolve({ filter: /^react-native$/ }, () => ({ path: reactNativeIndex }))
+        build.onResolve({ filter: LIBRARY_SPECIFIER }, () => ({ path: libraryEntry }))
+      }
+      // react-native-worklets (bare + any subpath) → single-runtime stub. The stub
+      // force-imports the seam, which installs reanimated's globals
+      // (__reanimatedModuleProxy, global._updateProps, __RUNTIME_KIND=2, RN$Bridgeless)
+      // before the reanimated chunk evaluates.
+      build.onResolve({ filter: /^react-native-worklets(\/.*)?$/ }, () => ({ path: workletsPath }))
+
+      // react-native-reanimated → the rngpui host wrapper (stamps the animation
+      // factories for the off-thread worklet runtime — see reanimated-host.ts),
+      // which itself imports the esbuild-prebuilt chunk via the virtual id below.
+      build.onResolve({ filter: /^react-native-reanimated$/ }, () => {
+        if (!existsSync(reanimatedChunk)) {
+          throw new Error(
+            `[reanimated] prebuilt chunk missing: ${reanimatedChunk}\n` +
+              `  run: bun scripts/prebuild-reanimated.mjs`,
+          )
+        }
+        return { path: reanimatedHostPath }
+      })
+      build.onResolve({ filter: /^rngpui-reanimated-prebuilt$/ }, () => ({ path: reanimatedChunk }))
+
+      // @tamagui/animations-reanimated → the esbuild-prebuilt chunk (when present).
+      build.onResolve({ filter: /^@tamagui\/animations-reanimated$/ }, () => {
+        if (existsSync(tamaguiReanimatedChunk)) return { path: tamaguiReanimatedChunk }
+        // not prebuilt (e.g. a bundle that doesn't use the Tamagui reanimated driver) —
+        // let it resolve normally; if the app actually imports it, that surfaces a clear
+        // resolve error pointing at the missing chunk.
+        return undefined
+      })
+
+      // worklet transform on APP + Tamagui-driver source (see the comment above).
+      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async (args) => {
+        // skip: the prebuilt chunks (already transformed), the seam/worklets stub, and
+        // anything inside reanimated/worklets node_modules (the prebuild owns those).
+        if (
+          args.path.startsWith(prebuiltDir) ||
+          args.path === seamPath ||
+          args.path === workletsPath ||
+          /node_modules\/(react-native-reanimated|react-native-worklets)\//.test(args.path)
+        ) {
+          return undefined
+        }
+        const source = await Bun.file(args.path).text()
+        let code = source
+        let transformed = false
+        const isTsx = args.path.endsWith('.tsx')
+        const isTs = /\.(tsx?|mts|cts)$/.test(args.path)
+        const isLibraryBuild = args.path.startsWith(libraryBuildDir)
+        if (!isLibraryBuild && WORKLET_KEYWORDS.test(source)) {
+          loadBabel(args.path)
+          const result = await babel.transformAsync(source, {
+            filename: args.path,
+            babelrc: false,
+            configFile: false,
+            sourceMaps: false,
+            presets: isTs
+              ? [[presetTs, { isTSX: isTsx, allExtensions: isTsx, allowDeclareFields: true }]]
+              : [],
+            plugins: [[jsxSyntax], [workletsPluginPath, { processNestedWorklets: true }]],
+          })
+          if (result?.code) {
+            code = result.code
+            transformed = true
+          }
+        }
+        if (transformSource) {
+          const result = await transformSource(code, {
+            filename: args.path,
+            isTs: transformed ? false : isTs,
+            isJsx: isTsx || args.path.endsWith('.jsx'),
+          })
+          if (result !== code) {
+            code = result
+            transformed = true
+          }
+        }
+        if (!transformed) return undefined
+        return {
+          contents: code,
+          loader: isTsx || args.path.endsWith('.jsx') ? 'jsx' : 'js',
+        }
+      })
+    },
+  }
+}

package/scripts/service-binary.d.mts

@@ -0,0 +1,27 @@
+export type ServiceBinary = {
+    path: string;
+    source: string;
+};
+
+export type ServiceBinaryOptions = {
+    env?: Record<string, string | undefined>;
+    root?: string;
+};
+
+export type PlatformTarget = {
+    os: string;
+    cpu: string;
+    libc?: string;
+};
+
+export declare const MAIN_PACKAGE: string;
+export declare const SERVICE_NAME: string;
+export declare const UI_RUNTIME_NAME: string;
+export declare const packageRoot: string;
+export declare const PLATFORMS: Record<string, PlatformTarget>;
+
+export declare function platformKey(platform?: string, arch?: string): string;
+export declare function platformPackageName(key?: string): string;
+export declare function isRepoCheckout(root?: string): boolean;
+export declare function resolveServiceBinary(options?: ServiceBinaryOptions): ServiceBinary;
+export declare function uiRuntimeEnv(binary: string, options?: ServiceBinaryOptions): { RNGPUI_UI_BUNDLE?: string };

package/scripts/service-binary.mjs

@@ -0,0 +1,100 @@
+import { accessSync, chmodSync, constants, existsSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const MAIN_PACKAGE = "@felipe-software/react-native-gpui";
+export const SERVICE_NAME = "rngpui-service";
+export const UI_RUNTIME_NAME = "ui-runtime.js";
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export const PLATFORMS = {
+    "linux-x64": { os: "linux", cpu: "x64", libc: "glibc" },
+    "linux-arm64": { os: "linux", cpu: "arm64", libc: "glibc" },
+    "darwin-arm64": { os: "darwin", cpu: "arm64" },
+};
+
+export function platformKey(platform = process.platform, arch = process.arch) {
+    return `${platform}-${arch}`;
+}
+
+export function platformPackageName(key = platformKey()) {
+    return `${MAIN_PACKAGE}-${key}`;
+}
+
+export function isRepoCheckout(root = packageRoot) {
+    return existsSync(resolve(root, "..", "rust", "Cargo.toml"));
+}
+
+export function resolveServiceBinary({ env = process.env, root = packageRoot } = {}) {
+    const found = findServiceBinary(env, root);
+    if (found.source !== "RNGPUI_SERVICE") ensureExecutable(found.path);
+    return found;
+}
+
+export function uiRuntimeEnv(binary, { env = process.env, root = packageRoot } = {}) {
+    if (env.RNGPUI_UI_BUNDLE) return {};
+    if (existsSync(join(dirname(binary), UI_RUNTIME_NAME))) return {};
+    const packaged = join(root, "dist", UI_RUNTIME_NAME);
+    return existsSync(packaged) ? { RNGPUI_UI_BUNDLE: packaged } : {};
+}
+
+function findServiceBinary(env, root) {
+    if (env.RNGPUI_SERVICE) {
+        const explicit = resolve(env.RNGPUI_SERVICE);
+        if (!existsSync(explicit)) throw new Error(`RNGPUI_SERVICE points at ${explicit}, which does not exist`);
+        return { path: explicit, source: "RNGPUI_SERVICE" };
+    }
+    const packaged = platformPackageBinary(root);
+    if (packaged) return packaged;
+    const local = localBinaries(root).find((candidate) => existsSync(candidate.path));
+    if (local) return local;
+    throw new Error(missingBinaryMessage(root));
+}
+
+function platformPackageBinary(root) {
+    const name = platformPackageName();
+    try {
+        const manifest = createRequire(join(root, "package.json")).resolve(`${name}/package.json`);
+        const path = join(dirname(manifest), SERVICE_NAME);
+        return existsSync(path) ? { path, source: name } : null;
+    } catch {
+        return null;
+    }
+}
+
+function localBinaries(root) {
+    const native = { path: join(root, "native", SERVICE_NAME), source: "native/" };
+    if (!isRepoCheckout(root)) return [native];
+    const target = resolve(root, "..", "rust", "target");
+    const release = { path: join(target, "release", SERVICE_NAME), source: "rust/target/release" };
+    const debug = { path: join(target, "debug", SERVICE_NAME), source: "rust/target/debug" };
+    const newestFirst = [native, release].sort((a, b) => modifiedAt(b.path) - modifiedAt(a.path));
+    return [...newestFirst, debug];
+}
+
+function modifiedAt(path) {
+    try {
+        return statSync(path).mtimeMs;
+    } catch {
+        return 0;
+    }
+}
+
+function missingBinaryMessage(root) {
+    const key = platformKey();
+    const supported = Object.keys(PLATFORMS).join(", ");
+    if (!PLATFORMS[key]) {
+        return `${MAIN_PACKAGE} has no prebuilt ${SERVICE_NAME} for ${key} (prebuilt: ${supported}). Build it from source and set RNGPUI_SERVICE.`;
+    }
+    const repoHint = isRepoCheckout(root) ? " or run `npm run build:rust && npm run build:native` in ts/" : "";
+    return `${SERVICE_NAME} not found: ${platformPackageName(key)} is not installed. It is an optional dependency of ${MAIN_PACKAGE}; reinstall without --omit=optional / --no-optional, set RNGPUI_SERVICE${repoHint}.`;
+}
+
+function ensureExecutable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+    } catch {
+        chmodSync(path, 0o755);
+    }
+}

package/src/reanimated/colors-processor-shim.ts

@@ -0,0 +1,119 @@
+// Shim for react-native-reanimated's `common/style/processors/colors` module.
+//
+// Why: Bun's bundler mis-orders the init of reanimated's color-processor barrel
+// (`config.ts`'s top-level `const colorAttributes = { process: processColor }` reads
+// the binding before Bun assigns it → "Property 'processColorN' doesn't exist" at
+// bundle eval). The original module also pulls a `'worklet'` `PlatformColor` and the
+// deep `Colors.ts` chain. We replace ONLY this leaf with a self-contained module (all
+// exports are hoisted declarations in one file, so there is no cross-module rename for
+// Bun to drop), preserving the exact public surface the barrel re-exports.
+//
+// Faithfulness: `processColor` returns RN's 32-bit ARGB int (the same form upstream's
+// `processColorInitially` produces), so reanimated's color interpolation + the gpui
+// seam's `processedColorToCss` round-trip identically. `processColorsInProps` mutates
+// color-valued style keys in place to that int form, matching upstream.
+
+type StyleProps = Record<string, unknown>
+
+const COLOR_KEYS = new Set([
+  'color',
+  'backgroundColor',
+  'borderColor',
+  'borderTopColor',
+  'borderRightColor',
+  'borderBottomColor',
+  'borderLeftColor',
+  'borderStartColor',
+  'borderEndColor',
+  'tintColor',
+  'shadowColor',
+  'overlayColor',
+  'textDecorationColor',
+  'textShadowColor',
+])
+
+// RN-style color string/number → 32-bit ARGB int (a>>24, r>>16, g>>8, b). Mirrors
+// react-native's processColor output so reanimated's color interpolation operates on
+// the same numeric form it expects.
+export function processColor(color: unknown): number | null {
+  if (color == null) return null
+  if (typeof color === 'number') return color >>> 0
+  if (typeof color !== 'string') return null
+  const s = color.trim()
+  let m: RegExpExecArray | null
+  if ((m = /^#([0-9a-f]{6})$/i.exec(s))) return (0xff000000 | parseInt(m[1], 16)) >>> 0
+  if ((m = /^#([0-9a-f]{8})$/i.exec(s))) {
+    const n = parseInt(m[1], 16)
+    const a = n & 0xff
+    return (((a << 24) | (n >>> 8)) >>> 0) >>> 0
+  }
+  if ((m = /^#([0-9a-f]{3})$/i.exec(s))) {
+    const h = m[1]
+    const r = parseInt(h[0] + h[0], 16)
+    const g = parseInt(h[1] + h[1], 16)
+    const b = parseInt(h[2] + h[2], 16)
+    return (0xff000000 | (r << 16) | (g << 8) | b) >>> 0
+  }
+  if ((m = /^rgba?\(([^)]+)\)$/i.exec(s))) {
+    const p = m[1].split(',').map((x) => x.trim())
+    const r = parseInt(p[0]) || 0
+    const g = parseInt(p[1]) || 0
+    const b = parseInt(p[2]) || 0
+    let a = p[3] === undefined ? 1 : parseFloat(p[3])
+    if (!(a >= 0)) a = 0
+    if (a > 1) a = 1
+    return ((((a * 255) & 0xff) << 24) | (r << 16) | (g << 8) | b) >>> 0
+  }
+  // named colors / unknown → opaque black (matches RN's fallback shape closely enough).
+  return 0xff000000 >>> 0
+}
+
+export function processColorNumber(value: unknown): number | null {
+  return processColor(value)
+}
+
+export function processColorsInProps(props: StyleProps): void {
+  for (const key of Object.keys(props)) {
+    if (COLOR_KEYS.has(key)) {
+      const processed = processColor(props[key])
+      if (processed != null) props[key] = processed
+    }
+  }
+}
+
+// PlatformColor / DynamicColorIOS — gpui has no native semantic colors; identity-ish.
+export function PlatformColor(...names: string[]): unknown {
+  return names[0]
+}
+
+export function DynamicColorIOS(tuple: { light: unknown; dark: unknown }): unknown {
+  return tuple?.light
+}
+
+// ── worklet-builtin registration ─────────────────────────────────────────────
+// Upstream's updateProps worklet CAPTURES processColorsInProps in its closure.
+// These shim fns are plain (not babel-workletized), so without a builtin brand
+// the cross-runtime serializer ships them as async jsCallback proxies — on the
+// worklet/UI runtime they then do nothing and every color key crosses as
+// undefined (the dropped-dialog-bg bug). Brand + register them so closures
+// serialize as {kind:'builtin', name} and bind to THIS module's implementation
+// on whichever runtime executes (this shim is baked into the prebuilt chunk,
+// which evaluates on both). Constants mirror worklet-runtime.ts — this file
+// cannot import it (the prebuilt chunk keeps the worklets package external).
+const RNGPUI_BUILTIN_NAME = Symbol.for('rngpui.workletBuiltinName')
+function registerColorBuiltin(name: string, fn: (...args: never[]) => unknown): void {
+  try {
+    Object.defineProperty(fn, RNGPUI_BUILTIN_NAME, {
+      value: name,
+      enumerable: false,
+      configurable: true,
+      writable: false,
+    })
+  } catch {}
+  const g = globalThis as unknown as { __rngpui_worklet_builtins?: Map<string, unknown> }
+  if (!g.__rngpui_worklet_builtins) g.__rngpui_worklet_builtins = new Map()
+  g.__rngpui_worklet_builtins.set(name, fn)
+}
+registerColorBuiltin('processColor', processColor)
+registerColorBuiltin('processColorNumber', processColorNumber)
+registerColorBuiltin('processColorsInProps', processColorsInProps)

package/src/reanimated/reanimated-host.ts

@@ -0,0 +1,69 @@
+// `react-native-reanimated` entry for rngpui bundles — the bundler plugins alias
+// the package here, and `rngpui-reanimated-prebuilt` to the prebuilt upstream
+// chunk. Re-exports upstream untouched EXCEPT, on the React runtime with the
+// worklet bridge present, the animation factories — the producer half of
+// sootsim's guestDecorator (plans/off-thread-reanimated.md):
+//
+//  - calling `withTiming(...)` / `withSpring(...)` / … stamps the returned
+//    animation object with a non-enumerable descriptor {type, args} so a direct
+//    `sv.value = withX(...)` write on the React runtime can be re-created and
+//    DRIVEN on the worklet/UI runtime (worklets.ts setValue →
+//    dispatchHostValueSet → HOST_SET_SHARED_VALUE_WORKLET revive).
+//  - each wrapper registers itself as a worklet builtin, so a mapper closure
+//    capturing `withSpring` serializes as {kind:'builtin', name:'withSpring'}
+//    and binds to the UI runtime's OWN factory over there (registered raw by
+//    ui-entry.ts). Without this, closure serialization would ship the wrapper
+//    as code and lose the stamp-free UI-side identity.
+//
+// On the UI runtime (and in bun tests / single-runtime mode) factories pass
+// through untouched — animations are created and driven locally there, no stamp
+// needed. Explicit named exports win over the `export *` per the ES module
+// spec's ambiguity rule, so the wrapped names below shadow the chunk's.
+import * as upstream from 'rngpui-reanimated-prebuilt'
+import { registerWorkletBuiltin } from './worklet-runtime'
+
+export * from 'rngpui-reanimated-prebuilt'
+export { default } from 'rngpui-reanimated-prebuilt'
+
+const RNGPUI_REANIMATED_ANIMATION_DESCRIPTOR = Symbol.for('rngpui.reanimatedAnimationDescriptor')
+
+declare const __rngpui_uiPost: ((arg: string) => void) | undefined
+
+// only the React runtime with a live worklet bridge stamps factories.
+const wrapFactories = typeof __rngpui_uiPost === 'function'
+
+type AnimationFactory = (...args: unknown[]) => unknown
+
+function stamped(name: string, factory: unknown): AnimationFactory {
+  const fn = factory as AnimationFactory
+  if (!wrapFactories || typeof fn !== 'function') return fn
+  const wrapper: AnimationFactory = (...args: unknown[]) => {
+    const out = fn(...args)
+    if (out && (typeof out === 'object' || typeof out === 'function')) {
+      Object.defineProperty(out as object, RNGPUI_REANIMATED_ANIMATION_DESCRIPTOR, {
+        value: { type: name, args },
+        enumerable: false,
+        configurable: true,
+      })
+    }
+    return out
+  }
+  // keep the worklet metadata visible on the wrapper so upstream's
+  // areWorkletsEqual/isWorkletFunction checks treat it like the original.
+  for (const key of ['__workletHash', '__initData', '__closure', '__isAnimationDefinition']) {
+    const value = (fn as unknown as Record<string, unknown>)[key]
+    if (value !== undefined) {
+      Object.defineProperty(wrapper, key, { value, enumerable: false, configurable: true, writable: true })
+    }
+  }
+  registerWorkletBuiltin(name, wrapper)
+  return wrapper
+}
+
+export const withTiming = stamped('withTiming', upstream.withTiming)
+export const withSpring = stamped('withSpring', upstream.withSpring)
+export const withDecay = stamped('withDecay', upstream.withDecay)
+export const withDelay = stamped('withDelay', upstream.withDelay)
+export const withRepeat = stamped('withRepeat', upstream.withRepeat)
+export const withSequence = stamped('withSequence', upstream.withSequence)
+export const withClamp = stamped('withClamp', upstream.withClamp)

package/src/reanimated/rngpui-reanimated-prebuilt.d.ts

@@ -0,0 +1,7 @@
+// virtual module id the bundler plugins map to the esbuild-prebuilt upstream
+// reanimated chunk (.reanimated-prebuilt/react-native-reanimated.mjs). Only
+// reanimated-host.ts imports it; type-wise it IS upstream reanimated.
+declare module 'rngpui-reanimated-prebuilt' {
+  export * from 'react-native-reanimated'
+  export { default } from 'react-native-reanimated'
+}