react-native-impeller-platform 0.0.0-stage → 0.3.1

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# react-native-impeller-platform
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An out-of-tree React Native platform whose renderer is
+[Impeller](https://github.com/flutter/engine/tree/main/impeller), Flutter's
+graphics engine. React components mount through Fabric into a scene graph that
+Impeller paints — no DOM, no native view hierarchy, no per-platform UI toolkit.
+
+**Status: pre-release, and honest about it.** The rendering, the JS↔native
+module seam and the packaging are gated by pixel tests on every commit, but the
+API surface is small and the published platform list is short. See "Supported
+platforms" before installing.
+
+## Install
+
+> **Not published yet.** These packages are configured to publish **publicly**,
+> but nothing has been released to npm — publishing stays deliberately gated
+> while the API settles. Until the first release, install from a git checkout or
+> a packed tarball. The command below will work once a version ships.
+
+```bash
+npm install react-native-impeller-platform
+```
+
+The engine binary is not in this package. It installs automatically as an
+optional dependency matching your platform and architecture.
+
+## Supported platforms
+
+| Platform | Engine package | Status |
+|---|---|---|
+| linux-x64 | `@blbaker/react-native-impeller-platform-engine-linux-x64` | builds + renders |
+| win32-x64 | `@blbaker/react-native-impeller-platform-engine-win32-x64` | builds + renders |
+| darwin-arm64 | `@blbaker/react-native-impeller-platform-engine-darwin-arm64` | builds + renders |
+| darwin-x64, linux-arm64 | — | not started |
+
+Nothing is on npm yet — see Install. "builds + renders" means the engine
+package exists, installs into an app outside the repo, and puts correct pixels
+on screen there (P1 consumer + P2 mount + P3 conformance + P4 module seam).
+
+**A platform is listed only once its engine package actually exists.** npm
+silently skips a missing optional dependency and exits 0, so declaring a
+platform we cannot ship would give you a clean install with no engine — and
+then an error telling you to install a package that does not exist.
+
+If your platform is not listed, it is not supported yet. `resolveEngine` says so
+directly rather than failing obscurely at runtime.
+
+## Not published yet — what that means for you
+
+Until the first release lands on npm there is no consumer story, and this
+README will not pretend otherwise. **Do not build the engine to use this
+package.** Compiling Hermes from source, installing Xcode and cmake, packing
+tarballs by hand, or running a local registry are all things a *contributor to
+this repo* does. A consumer runs `npm install` and nothing else.
+
+If you want to use `react-native-impeller-platform` in an app today, the honest
+answer is: wait for the release. The install above is the entire intended
+experience, and it is one command deliberately — the engine arrives as an
+optional dependency selected by your platform, with no build step, no native
+toolchain, and no environment variables.
+
+`IMPELLER_ENGINE_BINARY` exists for engine development, not for consumption. If
+you find yourself setting it in an app, something is wrong with the package and
+that is a bug worth reporting.
+
+---
+
+# Contributing to this repo
+
+Everything below is for working ON react-native-impeller-platform. None of it is
+required — or appropriate — for using the published package.
+
+## Installing it locally, before the first npm release
+
+You can consume the package on this machine exactly the way a published install
+works — `npm install react-native-impeller-platform`, no flags, no env vars, no
+build step in the consuming app — with a throwaway local registry:
+
+```bash
+npx verdaccio --listen 127.0.0.1:4873
+cd package && npm publish --registry http://127.0.0.1:4873
+cd ../packages-engine/engine-$(node -p 'process.platform+"-"+process.arch') \
+  && npm publish --registry http://127.0.0.1:4873
+
+# in a scratch app — exactly what a published install will look like
+npm install react-native-impeller-platform --registry http://127.0.0.1:4873
+```
+
+Keep `--registry` on that one command instead of writing it into the app's
+`.npmrc`. A global `registry=` line routes the app's entire dependency graph
+through a throwaway server, which is a supply-chain change nobody asked for. A
+scoped line (`@blbaker:registry=http://127.0.0.1:4873`)
+only covers the engine packages, because the main package is unscoped.
+
+Bump the version in every `package.json` before re-publishing; a registry
+refuses to overwrite an existing version, the same as npmjs.
+
+(Baker's own dev loop also keeps a *persistent* local registry running via a
+systemd/launchd unit and a wrapper script, so he doesn't have to repeat the
+steps above on every rebuild. That wrapper and its unit files are specific to
+his machines and aren't included in this public copy; the commands above are
+the portable, manual equivalent.)
+
+## Building the engine
+
+```bash
+bash tools/engine-build.sh <platform> <arch>   # e.g. darwin arm64
+```
+
+Needs a C++ toolchain, `cmake`, `ninja` and Node 18+ (on macOS: full Xcode, not
+just Command Line Tools). The first run compiles Hermes from source at the exact
+tag React Native pins — budget ~40 minutes; later builds reuse it.
+
+## Testing the consumer experience
+
+```bash
+bash tools/pack-and-consume.sh   # installs packed tarballs into a pristine app
+```
+
+Installing a tarball by path hand-places the package and **cannot** exercise
+what a real user hits: npm reading `optionalDependencies` and selecting the
+one engine whose `os`/`cpu` match. npm skips an optional dependency it cannot
+use *and exits 0*, so every failure in that path is silent — `pack-and-consume.sh`
+still only proves the by-path install. For the by-name, real-`npm publish`
+version of this check (a by-name registry gate isn't part of this repo), use the manual verdaccio recipe above and check both that the
+host's engine arrived and that no foreign-platform engine did.
+
+## Using a locally built engine (engine development only)
+
+`IMPELLER_ENGINE_BINARY` points the resolver at a binary you built yourself:
+
+```bash
+export IMPELLER_ENGINE_BINARY=/path/to/rn-impeller
+```
+
+It takes priority over the installed engine package and skips the version
+lockstep check.
+
+> **This is not a consumer workaround.** It exists so engine developers can test
+> a build without packing it. If a platform has no published engine package, the
+> answer is to publish one — not to tell users to set an environment variable.
+> A package that requires an env var to function has not shipped.
+
+## Versioning
+
+The host package and every engine package are released in **lockstep at exactly
+the same version**, and the resolver refuses a mismatched pair rather than
+letting it fail at runtime:
+
+```
+Engine version mismatch: @blbaker/react-native-impeller-platform-engine-linux-x64@0.0.2 is installed
+but react-native-impeller-platform@0.0.1 requires exactly 0.0.1.
+```
+
+The engine exposes a C ABI that is not stable across versions, so this is a hard
+requirement, not a convention. Never pin an engine package with `^` or `~`;
+`tools/ci-release-meta.sh` fails the build if a range appears.
+
+## Requirements
+
+- Node.js >= 20
+- React Native >= 0.86 (peer dependency)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "react-native-impeller-platform",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Out-of-tree React Native platform rendered with Flutter's Impeller engine",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blbaker/react-native-impeller-platform.git",
+    "directory": "package"
+  },
+  "homepage": "https://blbaker.github.io/react-native-impeller-platform/",
+  "bugs": {
+    "url": "https://github.com/blbaker/react-native-impeller-platform/issues"
+  },
+  "author": "Brandon Baker",
+  "keywords": [
+    "react-native",
+    "react-native-platform",
+    "out-of-tree-platform",
+    "impeller",
+    "flutter",
+    "desktop",
+    "linux",
+    "macos",
+    "windows"
+  ],
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "templates",
+    "react-native.config.js",
+    "README.md"
+  ],
+  "bin": {
+    "impeller-engine-path": "src/bin/engine-path.js"
+  },
+  "scripts": {
+    "test": "node src/selftest.js"
+  },
+  "peerDependencies": {
+    "react-native": ">=0.86.0"
+  },
+  "optionalDependencies": {
+    "@blbaker/react-native-impeller-platform-engine-darwin-arm64": "0.3.1",
+    "@blbaker/react-native-impeller-platform-engine-linux-x64": "0.3.1",
+    "@blbaker/react-native-impeller-platform-engine-win32-x64": "0.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,24 @@
+// CLI + platform registration for the `impeller` out-of-tree platform.
+//
+// PLAN D1: `npmPackageName` is deliberately NOT set. Setting it declares this
+// package a react-native FORK and makes the CLI/Metro redirect InitializeCore into
+// it -- the exact failure documented in the skia-platform packaging notes. This is
+// an OVERLAY platform: it sits beside stock react-native.
+const cli = require('./src/cli');
+
+module.exports = {
+  commands: cli.commands,
+  platforms: {
+    impeller: {
+      linkConfig: () => ({
+        isInstalled: () => false,
+        register: () => {},
+        unregister: () => {},
+        copyAssets: () => {},
+        unlinkAssets: () => {},
+      }),
+      projectConfig: (root, userConfig) => (userConfig ? {...userConfig, root} : null),
+      dependencyConfig: () => null,
+    },
+  },
+};

package/src/bin/engine-path.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+// Prints the resolved engine binary path, or a naming-the-package error on stderr.
+// Used by CI gates and by consumers debugging an install.
+const {resolveEngine} = require('../resolve');
+try {
+  const r = resolveEngine();
+  process.stdout.write(r.binary + '\n');
+} catch (e) {
+  process.stderr.write(e.message + '\n');
+  process.exit(1);
+}

package/src/cli/index.js

@@ -0,0 +1,20 @@
+'use strict';
+const {initImpeller} = require('./init');
+const {runImpeller} = require('./run');
+
+const commands = [
+  {
+    name: 'init-impeller',
+    description: 'Scaffold the impeller/ folder into this React Native app',
+    options: [{name: '--force', description: 'Overwrite existing scaffolded files'}],
+    func: (argv, config, args) => initImpeller(argv, config, {force: Boolean(args && args.force)}),
+  },
+  {
+    name: 'run-impeller',
+    description: 'Bundle with Metro (platform=impeller) and launch the Impeller engine',
+    options: [{name: '--release', description: 'Build a production bundle'}],
+    func: (argv, config) => runImpeller(argv, config, {}),
+  },
+];
+
+module.exports = {commands, initImpeller, runImpeller};

package/src/cli/init.js

@@ -0,0 +1,112 @@
+'use strict';
+// `npx react-native init-impeller`
+//
+// PLAN D5: SCAFFOLD, NOT HARDCODE. Everything app-specific is derived from the
+// consumer's app.json/package.json at scaffold time. No "playground", no
+// workspaceRoot, no monorepo assumptions, no CWD-relative runtime paths.
+
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATE_DIR = path.join(__dirname, '..', '..', 'templates', 'app');
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function detectAppName(root) {
+  const appJson = path.join(root, 'app.json');
+  if (fs.existsSync(appJson)) {
+    const j = readJson(appJson);
+    if (j.name) return j.name;
+  }
+  const pkgJson = path.join(root, 'package.json');
+  if (fs.existsSync(pkgJson)) {
+    const j = readJson(pkgJson);
+    if (j.name) return j.name;
+  }
+  throw new Error(
+    'Cannot determine the app name: neither app.json nor package.json has a "name".\n' +
+      'Run init-impeller from the root of a React Native app.'
+  );
+}
+
+function detectDisplayName(root, fallback) {
+  const appJson = path.join(root, 'app.json');
+  if (fs.existsSync(appJson)) {
+    const j = readJson(appJson);
+    if (j.displayName) return j.displayName;
+  }
+  return fallback;
+}
+
+function render(text, vars) {
+  return text.replace(/\{\{(\w+)\}\}/g, (m, k) => {
+    if (!(k in vars)) throw new Error(`Template references unknown variable {{${k}}}`);
+    return vars[k];
+  });
+}
+
+function copyTemplate(srcDir, destDir, vars, {force, log}) {
+  fs.mkdirSync(destDir, {recursive: true});
+  for (const entry of fs.readdirSync(srcDir, {withFileTypes: true})) {
+    const src = path.join(srcDir, entry.name);
+    const outName = entry.name.replace(/^_/, '.').replace(/\.tmpl$/, '');
+    const dest = path.join(destDir, outName);
+    if (entry.isDirectory()) {
+      copyTemplate(src, dest, vars, {force, log});
+      continue;
+    }
+    if (fs.existsSync(dest) && !force) {
+      log(`  skip   ${path.relative(process.cwd(), dest)} (exists, use --force)`);
+      continue;
+    }
+    fs.writeFileSync(dest, render(fs.readFileSync(src, 'utf8'), vars));
+    log(`  write  ${path.relative(process.cwd(), dest)}`);
+  }
+}
+
+function ensureMetroConfig(root, {log}) {
+  const p = path.join(root, 'metro.config.js');
+  const wrapped = `const {withImpeller} = require('react-native-impeller-platform/src/metro-shims');`;
+  if (!fs.existsSync(p)) {
+    fs.writeFileSync(
+      p,
+      `${wrapped}\nconst {getDefaultConfig} = require('@react-native/metro-config');\n\nmodule.exports = withImpeller(getDefaultConfig(__dirname));\n`
+    );
+    log('  write  metro.config.js');
+    return;
+  }
+  const existing = fs.readFileSync(p, 'utf8');
+  if (existing.includes('withImpeller')) {
+    log('  ok     metro.config.js already wraps withImpeller');
+    return;
+  }
+  // Wrap, do not replace: preserve whatever the app already exports.
+  const patched =
+    `${wrapped}\n` +
+    existing.replace(/module\.exports\s*=\s*/, 'const __impellerBase = ') +
+    `\nmodule.exports = withImpeller(__impellerBase);\n`;
+  fs.writeFileSync(p, patched);
+  log('  patch  metro.config.js (wrapped existing export with withImpeller)');
+}
+
+function initImpeller(argv, config, options = {}) {
+  const root = (config && config.root) || process.cwd();
+  const log = options.log || console.log;
+  const force = Boolean(options.force);
+
+  const appName = detectAppName(root);
+  const vars = {
+    appName,
+    displayName: detectDisplayName(root, appName),
+  };
+
+  log(`init-impeller: scaffolding impeller/ for app "${appName}"`);
+  copyTemplate(TEMPLATE_DIR, path.join(root, 'impeller'), vars, {force, log});
+  ensureMetroConfig(root, {log});
+  log('Done. Next: npx react-native run-impeller');
+  return {appName, dir: path.join(root, 'impeller')};
+}
+
+module.exports = {initImpeller, detectAppName, render, TEMPLATE_DIR};

package/src/cli/run.js

@@ -0,0 +1,73 @@
+'use strict';
+// `npx react-native run-impeller`
+//
+// Builds a bundle with Metro (platform=impeller) and launches the engine binary,
+// passing the bundle as an ABSOLUTE path. PLAN D5: the engine has NO CWD probe and
+// no fallback bundle location -- if the path is wrong we want a loud failure, not a
+// stale bundle rendered from some other directory.
+
+const fs = require('fs');
+const path = require('path');
+const {spawnSync} = require('child_process');
+const {resolveEngine} = require('../resolve');
+
+function readAppConfig(root) {
+  const appJson = path.join(root, 'app.json');
+  if (fs.existsSync(appJson)) {
+    const j = JSON.parse(fs.readFileSync(appJson, 'utf8'));
+    if (j.name) return j;
+  }
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  return {name: pkg.name};
+}
+
+function bundle(root, {dev, entryFile, outDir, log, cliBin}) {
+  fs.mkdirSync(outDir, {recursive: true});
+  const out = path.join(outDir, 'index.impeller.bundle');
+  const args = [
+    cliBin || require.resolve('@react-native-community/cli/build/bin.js', {paths: [root]}),
+    'bundle',
+    '--platform',
+    'impeller',
+    '--dev',
+    String(Boolean(dev)),
+    '--entry-file',
+    entryFile,
+    '--bundle-output',
+    out,
+    '--assets-dest',
+    path.join(outDir, 'assets'),
+  ];
+  log(`bundling: node ${args.slice(1).join(' ')}`);
+  const r = spawnSync(process.execPath, args, {cwd: root, stdio: 'inherit'});
+  if (r.status !== 0) {
+    throw new Error(`Metro bundle failed with exit code ${r.status}`);
+  }
+  if (!fs.existsSync(out)) {
+    throw new Error(`Metro reported success but produced no bundle at ${out}`);
+  }
+  return out;
+}
+
+function runImpeller(argv = [], config, options = {}) {
+  const root = (config && config.root) || process.cwd();
+  const log = options.log || console.log;
+  const dev = !argv.includes('--release');
+  const entryFile = options.entryFile || 'index.js';
+  const outDir = path.join(root, 'impeller', 'build');
+
+  const app = readAppConfig(root);
+  const bundlePath = options.bundlePath || bundle(root, {dev, entryFile, outDir, log, cliBin: options.cliBin});
+  const {binary, source, packageName} = resolveEngine();
+  log(`engine: ${binary} (${source}${packageName ? ` -- ${packageName}` : ''})`);
+
+  const engineArgs = ['--bundle', path.resolve(bundlePath), '--app-name', app.name, ...argv.filter((a) => a !== '--release')];
+  if (options.dryRun) return {binary, engineArgs, bundlePath};
+
+  const r = spawnSync(binary, engineArgs, {cwd: root, stdio: 'inherit'});
+  if (r.error) throw r.error;
+  process.exitCode = r.status === null ? 1 : r.status;
+  return {binary, engineArgs, bundlePath, status: r.status};
+}
+
+module.exports = {runImpeller, bundle};

package/src/externaltexture/index.js

@@ -0,0 +1,58 @@
+'use strict';
+// FP-42 — external textures (Flutter's Texture widget + TextureRegistry).
+//
+// <ImpellerTextureView textureId={id} style={...} /> paints the latest frame of
+// the engine's texture `id` inside the view's clip, transform and opacity.
+// Native producers (video, camera) register textures from C++; this module
+// adds a test producer from JS. Same `get` (not `getEnforcing`) pattern as
+// ../worldraster: an engine without the module fails only the calls that need it.
+
+const {TurboModuleRegistry} = require('react-native');
+const NativeComponentRegistry = require('react-native/Libraries/NativeComponent/NativeComponentRegistry');
+
+const Native = TurboModuleRegistry.get('ImpellerTextureRegistry');
+
+function mod() {
+  if (Native == null) {
+    throw new Error(
+      'ImpellerTextureRegistry native module is unavailable. The engine binary ' +
+        'predates FP-42: external textures cannot work until the engine is updated.',
+    );
+  }
+  return Native;
+}
+
+function isSupported() {
+  return Native != null && mod().isSupported();
+}
+
+// A native animated test pattern at `fps`; returns its texture id. maxFrames > 0
+// stops it after that many frames (the last one stays registered).
+function registerTestProducer(fps, width, height, maxFrames = 0) {
+  return mod().registerTestProducer(fps, width, height, maxFrames);
+}
+
+// Stops painting `id` (views showing it paint nothing). False: unknown id.
+function unregister(id) {
+  return mod().unregister(id);
+}
+
+// Tells the engine texture `id` has a new frame (native producers do this).
+function markFrameAvailable(id) {
+  mod().markFrameAvailable(id);
+}
+
+const ImpellerTextureView = NativeComponentRegistry.get('ImpellerTextureView', () => ({
+  uiViewClassName: 'ImpellerTextureView',
+  bubblingEventTypes: {},
+  directEventTypes: {},
+  validAttributes: {textureId: true},
+}));
+
+module.exports = {
+  isSupported,
+  registerTestProducer,
+  unregister,
+  markFrameAvailable,
+  ImpellerTextureView,
+};

package/src/index.js

@@ -0,0 +1,12 @@
+'use strict';
+const {resolveEngine, hostTriple, packageNameFor} = require('./resolve');
+const {withImpeller} = require('./metro-shims');
+const cli = require('./cli');
+
+module.exports = {
+  resolveEngine,
+  hostTriple,
+  packageNameFor,
+  withImpeller,
+  commands: cli.commands,
+};