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

package/src/selftest.js

@@ -0,0 +1,123 @@
+/**
+ * Self-test for the engine resolver.
+ *
+ * Runs as `npm test` INSIDE THE PUBLISHED PACKAGE, which is the point: it is
+ * the one check a user can run on the artifact they actually installed, on a
+ * machine we have never seen. So it must depend on nothing but this package —
+ * no dev dependencies, no test runner, no network, no engine binary.
+ *
+ * package.json declared this script for the whole of P1-P6 while the file did
+ * not exist; `npm test` died with MODULE_NOT_FOUND. tools/ci-release-meta.sh
+ * now fails the build when a declared entry point is missing.
+ */
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {resolveEngine, hostTriple, packageNameFor, binaryFileName, SUPPORTED} =
+  require('./resolve');
+
+let passed = 0;
+function check(name, fn) {
+  try {
+    fn();
+    console.log(`  ok  ${name}`);
+    passed++;
+  } catch (e) {
+    console.error(`  FAIL ${name}\n       ${e.message}`);
+    process.exitCode = 1;
+  }
+}
+
+console.log('react-native-impeller-platform selftest');
+
+check('host triple is platform-arch', () => {
+  assert.strictEqual(hostTriple('linux', 'x64'), 'linux-x64');
+  assert.strictEqual(hostTriple('win32', 'x64'), 'win32-x64');
+});
+
+check('engine package name is derived from the triple', () => {
+  assert.strictEqual(
+    packageNameFor('linux-x64'),
+    '@blbaker/react-native-impeller-platform-engine-linux-x64'
+  );
+});
+
+check('binary name is .exe only on win32', () => {
+  assert.strictEqual(binaryFileName('linux'), 'rn-impeller');
+  assert.strictEqual(binaryFileName('darwin'), 'rn-impeller');
+  assert.strictEqual(binaryFileName('win32'), 'rn-impeller.exe');
+});
+
+check('every SUPPORTED triple names a real optionalDependency', () => {
+  // The defect this guards: a triple advertised as supported with no package
+  // published. npm SKIPS a missing optional dependency and exits 0, so the
+  // user gets a silent no-engine install and then an error instructing them to
+  // install something that does not exist.
+  const pkg = require('../package.json');
+  const opt = Object.keys(pkg.optionalDependencies || {});
+  for (const triple of SUPPORTED) {
+    assert.ok(
+      opt.includes(packageNameFor(triple)),
+      `${triple} is SUPPORTED but ${packageNameFor(triple)} is not an optionalDependency`
+    );
+  }
+});
+
+check('every engine optionalDependency is pinned exactly, never a range', () => {
+  // The engine exposes an unstable C ABI. A ^ or ~ range lets npm resolve a
+  // newer engine against an older host, which crashes at runtime rather than
+  // failing to install.
+  const pkg = require('../package.json');
+  for (const [name, spec] of Object.entries(pkg.optionalDependencies || {})) {
+    assert.strictEqual(spec, pkg.version, `${name} is pinned '${spec}', expected '${pkg.version}'`);
+  }
+});
+
+check('an unsupported triple is refused, without demanding the user build it', () => {
+  // ⛔ THIS TEST USED TO REQUIRE THE OPPOSITE.
+  // It asserted the error names IMPELLER_ENGINE_BINARY — i.e. it ENFORCED
+  // telling a consumer whose install just failed to go compile a C++ engine.
+  // A test can pin the wrong behaviour just as firmly as the right one; this
+  // one kept contributor workflow in a consumer error path.
+  assert.throws(
+    () => resolveEngine({platform: 'sunos', arch: 'sparc', env: {}}),
+    (e) =>
+      /does not support sunos-sparc yet/.test(e.message) &&
+      /Supported: /.test(e.message) &&
+      // The message must NOT hand a consumer a build instruction.
+      !/IMPELLER_ENGINE_BINARY/.test(e.message)
+  );
+});
+
+check('IMPELLER_ENGINE_BINARY overrides the installed package', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rni-selftest-'));
+  const fake = path.join(tmp, 'rn-impeller');
+  fs.writeFileSync(fake, '');
+  try {
+    const r = resolveEngine({env: {IMPELLER_ENGINE_BINARY: fake}});
+    assert.strictEqual(r.source, 'env');
+    assert.strictEqual(r.binary, fake);
+  } finally {
+    fs.rmSync(tmp, {recursive: true, force: true});
+  }
+});
+
+check('a missing IMPELLER_ENGINE_BINARY fails loudly, not silently', () => {
+  // "Cannot find it" and "using the default" must never share an outcome: an
+  // override that silently falls back would run a DIFFERENT engine than the
+  // developer asked for, which is the hardest kind of bug to see.
+  assert.throws(
+    () => resolveEngine({env: {IMPELLER_ENGINE_BINARY: '/nonexistent/rn-impeller'}}),
+    /no file exists there/
+  );
+});
+
+console.log(
+  process.exitCode
+    ? 'SELFTEST_FAIL'
+    : `SELFTEST_PASS (${passed} checks)`
+);

package/src/storage/index.js

@@ -0,0 +1,161 @@
+'use strict';
+// ENG-04 shape B, the JS half. An AsyncStorage-shaped API composed on top of
+// the engine's ONE file primitive.
+//
+// WHY THIS LIVES IN JS
+// -------------------
+// The engine vends AppStorage.readFile/writeFile/deleteFile/listFiles and
+// nothing more. That is a deliberate boundary: persistence is not a renderer
+// concern, and if the engine owned a key-value API instead, every later need
+// (structured values, namespacing, encryption, migration) would be a new C++
+// row against a surface frozen in a native release. Here it is a JS change.
+//
+// Same division as Alert.impeller.js: the engine owns the CAPABILITY, JS owns
+// the SHAPE.
+//
+// ⛔ ASYNC ON PURPOSE, OVER A SYNCHRONOUS PRIMITIVE.
+// The native calls are synchronous (small flat files, called from the JS
+// thread). This wrapper is async anyway, because async is the shape every RN
+// storage consumer expects and the one you cannot retrofit later without
+// breaking every caller. If the native half ever moves to a thread pool, no
+// consumer of this module changes.
+
+const {TurboModuleRegistry} = require('react-native');
+
+// ⚠️ get, NOT getEnforcing. An engine built before ENG-04 does not vend
+// AppStorage, and a hard throw at import time would take the whole bundle down
+// on a version mismatch rather than failing the one feature. The null check in
+// mod() turns that into a rejected Promise from the call that needed it.
+const Native = TurboModuleRegistry.get('AppStorage');
+
+function mod() {
+  if (Native == null) {
+    throw new Error(
+      'AppStorage native module is unavailable. The engine binary predates ' +
+        'ENG-04 (run `rn-impeller --list-modules` to confirm) — storage calls ' +
+        'cannot work until the engine is updated.',
+    );
+  }
+  return Native;
+}
+
+// ⛔ KEY ENCODING IS NOT OPTIONAL AND IT IS NOT COSMETIC.
+//
+// The native side enforces a conservative allowlist ([A-Za-z0-9._-], one flat
+// file per key, no nesting) because that is what keeps the container listable
+// and the containment check simple. Real storage keys are not like that:
+// '@myapp/user:profile' is an ordinary AsyncStorage key and would be REJECTED
+// by the primitive.
+//
+// So keys are hex-encoded here. That is reversible, which listKeys() depends
+// on, and it means no key can ever collide with another or escape the
+// container -- a sanitising scheme (replace bad chars with '_') would silently
+// map 'a/b' and 'a_b' onto ONE file, and the caller would never be told.
+function encodeKey(key) {
+  if (typeof key !== 'string') {
+    throw new TypeError('storage key must be a string, got ' + typeof key);
+  }
+  let out = '';
+  for (let i = 0; i < key.length; i++) {
+    const code = key.charCodeAt(i);
+    // Encode the whole BMP code unit, not a byte: charCodeAt can return > 255
+    // for non-ASCII keys, and a 2-hex-digit assumption would truncate them
+    // into collisions ('\u0141' and 'A' both -> '41').
+    out += code.toString(16).padStart(4, '0');
+  }
+  return out + '.v1';
+}
+
+function decodeKey(name) {
+  if (!name.endsWith('.v1')) return null;
+  const body = name.slice(0, -3);
+  if (body.length % 4 !== 0) return null;
+  let out = '';
+  for (let i = 0; i < body.length; i += 4) {
+    const code = parseInt(body.slice(i, i + 4), 16);
+    if (Number.isNaN(code)) return null;
+    out += String.fromCharCode(code);
+  }
+  return out;
+}
+
+// A missing key resolves to null, never to ''. Those are different facts --
+// "nothing stored" vs "an empty string was stored" -- and the native primitive
+// preserves the distinction specifically so this layer can too. Collapsing
+// them would make removeItem() indistinguishable from setItem(k, '').
+async function getItem(key) {
+  return mod().readFile(encodeKey(key));
+}
+
+async function setItem(key, value) {
+  if (typeof value !== 'string') {
+    throw new TypeError(
+      'storage values must be strings (stringify first), got ' + typeof value,
+    );
+  }
+  const ok = mod().writeFile(encodeKey(key), value);
+  if (!ok) {
+    // The primitive returns false for a rejected key, a full disk, or a failed
+    // atomic rename. It does not distinguish them, and neither can this layer
+    // honestly, so the error says what is known rather than guessing.
+    throw new Error('storage write failed for key: ' + key);
+  }
+}
+
+// Idempotent, matching the native half: removing an absent key is success, not
+// an error, because that is the state the caller asked for.
+async function removeItem(key) {
+  const ok = mod().deleteFile(encodeKey(key));
+  if (!ok) throw new Error('storage delete failed for key: ' + key);
+}
+
+// Enumeration comes from the DIRECTORY, not from an index file this module
+// maintains. An index is a second source of truth that drifts the moment a
+// write succeeds and the index update does not.
+async function getAllKeys() {
+  const names = mod().listFiles();
+  const keys = [];
+  for (const name of names) {
+    const decoded = decodeKey(name);
+    // Skip anything this module did not write. A foreign file in the container
+    // is not an error and must not break enumeration for everything else.
+    if (decoded !== null) keys.push(decoded);
+  }
+  return keys;
+}
+
+async function clear() {
+  const keys = await getAllKeys();
+  for (const key of keys) {
+    await removeItem(key);
+  }
+}
+
+async function multiGet(keys) {
+  const out = [];
+  for (const key of keys) {
+    out.push([key, await getItem(key)]);
+  }
+  return out;
+}
+
+async function multiSet(pairs) {
+  for (const [key, value] of pairs) {
+    await setItem(key, value);
+  }
+}
+
+module.exports = {
+  getItem,
+  setItem,
+  removeItem,
+  getAllKeys,
+  clear,
+  multiGet,
+  multiSet,
+  // Exported for the gate: it asserts on the encoding round trip directly
+  // rather than inferring it from a get/set pair, so an encoding bug and a
+  // storage bug cannot be confused for each other.
+  encodeKey,
+  decodeKey,
+};

package/src/viewshot/index.js

@@ -0,0 +1,98 @@
+'use strict';
+// FP-43 — react-native-view-shot's JS API on the engine's RNViewShot module.
+//
+// The engine implements view-shot's native module (captureRef, captureScreen,
+// releaseCapture), so an app that depends on react-native-view-shot works as
+// is; this file is the same surface for apps that do not. The snapshot renders
+// the view's subtree into an offscreen on the raster thread, the png/jpg is
+// encoded off the JS thread, and the Promise resolves on the JS thread.
+//
+// options: {format: 'png' | 'jpg', quality: 0..1, result: 'tmpfile' | 'base64'
+// | 'data-uri', width, height (output pixels), fileName}.
+
+const {TurboModuleRegistry, findNodeHandle} = require('react-native');
+
+const Native = TurboModuleRegistry.get('RNViewShot');
+
+function mod() {
+  if (Native == null) {
+    throw new Error(
+      'RNViewShot native module is unavailable. The engine binary predates FP-43: ' +
+        'view snapshots cannot work until the engine is updated.',
+    );
+  }
+  return Native;
+}
+
+const DEFAULTS = {format: 'png', quality: 1, result: 'tmpfile'};
+
+// view-shot's validateOptions: defaults filled in, bad values reported.
+function validateOptions(input) {
+  const options = {...DEFAULTS, ...(input || {})};
+  const errors = [];
+  if ('width' in options && (typeof options.width !== 'number' || options.width <= 0)) {
+    errors.push('option width should be a positive number');
+    delete options.width;
+  }
+  if ('height' in options && (typeof options.height !== 'number' || options.height <= 0)) {
+    errors.push('option height should be a positive number');
+    delete options.height;
+  }
+  if (typeof options.quality !== 'number' || options.quality < 0 || options.quality > 1) {
+    errors.push('option quality should be a number between 0.0 and 1.0');
+    options.quality = DEFAULTS.quality;
+  }
+  if (options.format === 'jpeg') options.format = 'jpg';
+  if (options.format !== 'png' && options.format !== 'jpg') {
+    errors.push(`option format '${options.format}' is not in valid formats: png | jpg`);
+    options.format = DEFAULTS.format;
+  }
+  if (!['tmpfile', 'base64', 'data-uri'].includes(options.result)) {
+    errors.push(`option result '${options.result}' is not in valid results: tmpfile | base64 | data-uri`);
+    options.result = DEFAULTS.result;
+  }
+  return {options, errors};
+}
+
+function toTag(view) {
+  if (view && typeof view === 'object' && 'current' in view) view = view.current;
+  if (typeof view === 'number') return view;
+  const tag = view == null ? null : findNodeHandle(view);
+  if (tag == null) throw new Error('findNodeHandle failed to resolve view=' + String(view));
+  return tag;
+}
+
+// Resolves with a file:// uri, base64 or a data uri (options.result).
+function captureRef(view, optionsObject) {
+  let tag;
+  try {
+    tag = toTag(view);
+  } catch (e) {
+    return Promise.reject(e);
+  }
+  const {options, errors} = validateOptions(optionsObject);
+  if (__DEV__ && errors.length > 0) {
+    console.warn('react-native-view-shot captureRef options: ' + errors.join(', '));
+  }
+  return mod().captureRef(tag, options);
+}
+
+function captureScreen(optionsObject) {
+  const {options, errors} = validateOptions(optionsObject);
+  if (__DEV__ && errors.length > 0) {
+    console.warn('react-native-view-shot captureScreen options: ' + errors.join(', '));
+  }
+  return mod().captureScreen(options);
+}
+
+// Deletes a tmpfile capture.
+function releaseCapture(uri) {
+  if (typeof uri !== 'string') return;
+  mod().releaseCapture(uri);
+}
+
+function isSupported() {
+  return Native != null;
+}
+
+module.exports = {captureRef, captureScreen, releaseCapture, isSupported};

package/src/worldraster/index.js

@@ -0,0 +1,75 @@
+'use strict';
+// ENG-09 — WorldRaster JS shim.
+//
+// The engine vends ONE primitive: WorldRaster.setPixels(id, rgba, w, h),
+// synchronous, throwing on a mismatched buffer. This file is a thin,
+// defensive wrapper -- same `get` (not `getEnforcing`) pattern as
+// package/src/storage/index.js, so an engine built before ENG-09 fails the
+// one call site that needs WorldRaster rather than taking the whole bundle
+// down at import.
+
+const {TurboModuleRegistry} = require('react-native');
+
+const Native = TurboModuleRegistry.get('WorldRaster');
+
+function mod() {
+  if (Native == null) {
+    throw new Error(
+      'WorldRaster native module is unavailable. The engine binary predates ' +
+        'ENG-09 — world raster calls cannot work until the engine is updated.',
+    );
+  }
+  return Native;
+}
+
+function isSupported() {
+  return Native != null && mod().isSupported();
+}
+
+// id: string — must match the `name` prop set on the <world> host component
+// this buffer is meant for. rgba: ArrayBuffer of exactly w*h*4 bytes,
+// tightly packed RGBA8, row-major, top-to-bottom (the engine performs the
+// Y-flip at paint time; callers never flip).
+function setPixels(id, rgba, w, h) {
+  mod().setPixels(id, rgba, w, h);
+}
+
+// ENG-10 — GPU sprite compositing.
+//
+// registerSprite(textureId, rgba, w, h): upload ONE atlas entry, once.
+// rgba: ArrayBuffer of exactly w*h*4 bytes, STRAIGHT (non-premultiplied)
+// RGBA8, top-to-bottom — canvas ImageData layout. Re-registering the same
+// textureId replaces it.
+function registerSprite(textureId, rgba, w, h) {
+  mod().registerSprite(textureId, rgba, w, h);
+}
+
+// drawSprites(id, sprites): per frame. `id` is the <world name> to composite
+// over; sprites is an Array<{textureId, x, y, w, h, alpha?}> in layout points,
+// BACK-TO-FRONT (list order is paint order). Throws on an unregistered
+// textureId. Pass [] to clear.
+function drawSprites(id, sprites) {
+  mod().drawSprites(id, sprites);
+}
+
+// ENG-21 — setSampling(id, mode): how <world name=id> samples its setPixels
+// terrain and every sprite drawn on it. mode 'nearest' keeps pixel-art edges
+// hard at an integer scale; 'linear' (the default) blends neighbouring texels.
+// Throws on any other mode. Engines built before ENG-21 lack the method; call
+// isSamplingSupported() first if the app must run on them.
+function setSampling(id, mode) {
+  mod().setSampling(id, mode);
+}
+
+function isSamplingSupported() {
+  return Native != null && typeof Native.setSampling === 'function';
+}
+
+module.exports = {
+  isSupported,
+  isSamplingSupported,
+  setPixels,
+  registerSprite,
+  drawSprites,
+  setSampling,
+};

package/templates/app/README.md.tmpl

@@ -0,0 +1,18 @@
+# impeller/
+
+Scaffolded by `npx react-native init-impeller` for **{{displayName}}**.
+
+- `impeller.config.json` — window + app identity. The app name registered by the
+  engine is `{{appName}}`, taken from your `app.json`; the engine runs the same
+  name it registers.
+- `build/` — Metro output for `--platform impeller`. Safe to delete; regenerated
+  by `run-impeller`. Add it to `.gitignore`.
+
+The engine binary is **not** here. It is installed from npm as
+`@blbaker/react-native-impeller-platform-engine-<platform>-<arch>` (an optional dependency of
+`react-native-impeller-platform`) and located at runtime by the resolver. Set
+`IMPELLER_ENGINE_BINARY` to point at a locally built engine instead.
+
+Run it:
+
+    npx react-native run-impeller

package/templates/app/_gitignore

@@ -0,0 +1 @@
+build/

package/templates/app/impeller.config.json.tmpl

@@ -0,0 +1,11 @@
+{
+  "//": "Scaffolded by init-impeller. App identity is derived from your app.json --",
+  "//2": "nothing here is hardcoded to a sample app, and no path is CWD-relative.",
+  "appName": "{{appName}}",
+  "displayName": "{{displayName}}",
+  "window": {
+    "width": 1024,
+    "height": 768,
+    "title": "{{displayName}}"
+  }
+}