embedded-react 0.1.0

package/src/embedded-react/Animated.js

@@ -0,0 +1,352 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Animated — the React Native analog, backed by the engine's native-driver value system
+// (er_anim_value_*). An Animated.Value is a handle to an engine-side float; binding it to a node
+// prop (via Animated.View) lets the engine advance the animation each frame with NO per-frame JS.
+import { createElement, useRef, useEffect } from 'react';
+import { NativeUI } from '../native-ui.js';
+import { splitAnimatedStyle } from './split-style.js';
+
+/** A standalone animatable value bound to an engine-side float. */
+export class AnimatedValue {
+  constructor(initial = 0) {
+    this.__animated = true;
+    this._handle = NativeUI.animValueCreate(initial);
+    this._value = initial;
+    this._destroyed = false;
+  }
+
+  setValue(v) {
+    this._value = v;
+    NativeUI.animValueSet(this._handle, v);
+  }
+
+  /**
+   * Releases the engine-side value slot. The engine's value pool is fixed-size (unlike RN, where the
+   * JS value is simply garbage-collected), so a value tied to a mounting/unmounting component must be
+   * freed explicitly — see useAnimatedValue. Idempotent; the value must not be used after destroy().
+   */
+  destroy() {
+    if (this._destroyed) return;
+    this._destroyed = true;
+    NativeUI.animValueDestroy(this._handle);
+  }
+
+  __getValue() {
+    return NativeUI.animValueGet(this._handle);
+  }
+
+  __bind(node, prop) {
+    // The engine applies the current value on bind and ignores duplicate (node, prop) pairs, so
+    // this is safe to call on every render.
+    NativeUI.animValueBind(this._handle, node, prop);
+  }
+
+  interpolate(config) {
+    return new AnimatedInterpolation(this, config);
+  }
+}
+
+/**
+ * A value derived from a parent Animated.Value through a piecewise-linear interpolation.
+ * config = { inputRange, outputRange, extrapolate?, extrapolateLeft?, extrapolateRight? }; the
+ * extrapolate tokens ('extend' | 'clamp' | 'identity') control behavior outside the input range.
+ */
+export class AnimatedInterpolation {
+  constructor(parent, config) {
+    this.__animated = true;
+    this._parent = parent;
+    this._config = config;
+  }
+
+  __bind(node, prop) {
+    NativeUI.animValueBindInterpolated(this._parent._handle, node, prop, this._config);
+  }
+
+  interpolate(config) {
+    // Chained interpolation isn't supported by the engine; re-map against the same parent.
+    return new AnimatedInterpolation(this._parent, config);
+  }
+}
+
+/** Wraps fn so it runs at most once, regardless of how many times it is invoked. */
+function once(fn) {
+  let called = false;
+  return (arg) => {
+    if (called) return;
+    called = true;
+    if (fn) fn(arg);
+  };
+}
+
+/**
+ * Wraps a NativeUI animation call in an object with start()/stop() (RN's animation handle shape).
+ *
+ * start(onComplete) wires the engine's completion callback through the bridge: onComplete is called
+ * with `{ finished }` when the animation ends naturally (finished: true) or is interrupted by a new
+ * animation / stop() (finished: false). `_value` is exposed so Animated.loop can reset it between
+ * iterations.
+ */
+function makeAnimation(value, toValue, config) {
+  let handle = 0;
+  return {
+    _value: value,
+    start(onComplete) {
+      // Always pass a wrapper so we can null out the (possibly recycled) handle on completion.
+      const cb = (finished) => {
+        handle = 0;
+        if (onComplete) onComplete({ finished: !!finished });
+      };
+      handle = NativeUI.animValueAnimate(value._handle, toValue, config, cb);
+    },
+    stop() {
+      if (handle) NativeUI.animStop(handle);
+    },
+  };
+}
+
+export function timing(value, config = {}) {
+  const { toValue = 0, useNativeDriver, ...rest } = config;
+  return makeAnimation(value, toValue, { type: 'timing', ...rest });
+}
+
+export function spring(value, config = {}) {
+  const { toValue = 0, useNativeDriver, ...rest } = config;
+  return makeAnimation(value, toValue, { type: 'spring', ...rest });
+}
+
+export function decay(value, config = {}) {
+  const { useNativeDriver, ...rest } = config;
+  // Decay coasts from its velocity; the engine ignores the target, so pass the current value.
+  return makeAnimation(value, value.__getValue(), { type: 'decay', ...rest });
+}
+
+// --- Composition -------------------------------------------------------------------------------
+// These are pure JS over each child animation's start()/stop() + the §2 timer globals. The engine
+// deactivates a finished animation before firing its completion callback, so chaining the next
+// animation from inside a completion handler is safe (no per-frame JS — each child still runs in C).
+
+/** Runs animations one after another; each starts when the previous finishes. */
+export function sequence(animations) {
+  let current = 0;
+  let stopped = false;
+  return {
+    start(onComplete) {
+      const done = once(onComplete);
+      const next = (result) => {
+        if (stopped || !result || result.finished === false) {
+          done({ finished: false });
+          return;
+        }
+        if (current >= animations.length) {
+          done({ finished: true });
+          return;
+        }
+        animations[current++].start(next);
+      };
+      next({ finished: true }); // kick off the first entry
+    },
+    stop() {
+      stopped = true;
+      if (current > 0 && current <= animations.length) animations[current - 1].stop();
+    },
+  };
+}
+
+/** Runs animations simultaneously; completes when all finish. stopTogether (default true). */
+export function parallel(animations, config) {
+  const stopTogether = !config || config.stopTogether !== false;
+  let stopped = false;
+  return {
+    start(onComplete) {
+      const done = once(onComplete);
+      const total = animations.length;
+      if (total === 0) {
+        done({ finished: true });
+        return;
+      }
+      let doneCount = 0;
+      let anyUnfinished = false;
+      const onChild = (result) => {
+        doneCount++;
+        if (!result || result.finished === false) {
+          anyUnfinished = true;
+          if (stopTogether && !stopped) {
+            stopped = true;
+            for (const a of animations) a.stop();
+          }
+        }
+        if (doneCount >= total) done({ finished: !anyUnfinished });
+      };
+      for (const a of animations) a.start(onChild);
+    },
+    stop() {
+      stopped = true;
+      for (const a of animations) a.stop();
+    },
+  };
+}
+
+/** Like parallel, but each animation starts `delay` ms after the previous one (uses setTimeout). */
+export function stagger(delay, animations) {
+  let stopped = false;
+  const timers = [];
+  return {
+    start(onComplete) {
+      const done = once(onComplete);
+      const total = animations.length;
+      if (total === 0) {
+        done({ finished: true });
+        return;
+      }
+      let doneCount = 0;
+      let anyUnfinished = false;
+      const onChild = (result) => {
+        doneCount++;
+        if (!result || result.finished === false) anyUnfinished = true;
+        if (doneCount >= total) done({ finished: !anyUnfinished });
+      };
+      animations.forEach((a, i) => {
+        if (i === 0) {
+          a.start(onChild);
+        } else {
+          timers.push(
+            setTimeout(() => {
+              if (!stopped) a.start(onChild);
+            }, delay * i),
+          );
+        }
+      });
+    },
+    stop() {
+      stopped = true;
+      for (const t of timers) clearTimeout(t);
+      for (const a of animations) a.stop();
+    },
+  };
+}
+
+/** An animation that simply waits `time` ms — useful as a spacer inside sequence (uses setTimeout). */
+export function delay(time) {
+  let timer = 0;
+  return {
+    start(onComplete) {
+      const done = once(onComplete);
+      timer = setTimeout(() => {
+        timer = 0;
+        done({ finished: true });
+      }, time);
+    },
+    stop() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = 0;
+      }
+    },
+  };
+}
+
+/**
+ * Repeats an animation. iterations: -1 (default) loops forever; otherwise that many times.
+ * By default the underlying value is reset to its loop-start position before each iteration
+ * (resetBeforeIteration), matching RN — so a timing 0→1 repeats 0→1 rather than ping-ponging.
+ */
+export function loop(animation, config) {
+  const iterations = config && Number.isInteger(config.iterations) ? config.iterations : -1;
+  const resetBeforeIteration = !config || config.resetBeforeIteration !== false;
+  let stopped = false;
+  return {
+    _value: animation._value,
+    start(onComplete) {
+      const done = once(onComplete);
+      const startValue = resetBeforeIteration && animation._value ? animation._value.__getValue() : null;
+      let count = 0;
+      const run = (result) => {
+        if (stopped || !result || result.finished === false) {
+          done({ finished: false });
+          return;
+        }
+        if (iterations >= 0 && count >= iterations) {
+          done({ finished: true });
+          return;
+        }
+        count++;
+        if (resetBeforeIteration && animation._value && startValue != null && count > 1) {
+          animation._value.setValue(startValue);
+        }
+        animation.start(run);
+      };
+      run({ finished: true });
+    },
+    stop() {
+      stopped = true;
+      animation.stop();
+    },
+  };
+}
+
+/**
+ * Returns a stable Animated.Value that persists across renders (the analog of
+ * `useRef(new Animated.Value(initial)).current`), and frees the engine-side value slot when the
+ * component unmounts. The unmount cleanup matters here in a way it doesn't in React Native: the
+ * engine's value pool is fixed-size, so a value owned by a mounting/unmounting component (e.g., a list
+ * row or a tab screen) would otherwise leak a slot on every unmount.
+ */
+export function useAnimatedValue(initial = 0) {
+  const ref = useRef(null);
+  if (ref.current == null) {
+    ref.current = new AnimatedValue(initial);
+  }
+  // Empty deps → the cleanup runs only on unmount. `initial` is read once on the first render (matching
+  // useRef semantics); later changes don't recreate the value, as in React Native.
+  useEffect(() => {
+    const value = ref.current;
+    return () => value.destroy();
+  }, []);
+  return ref.current;
+}
+
+/**
+ * Wraps a host component so animated values in its `style` are bound to the node (native driver).
+ */
+export function createAnimatedComponent(Component) {
+  return function AnimatedComponent(props) {
+    const { style, ...rest } = props;
+    const { staticStyle, bindings } = splitAnimatedStyle(style);
+    const ref = (node) => {
+      if (node == null) return; // unmount
+      for (const b of bindings) b.value.__bind(node, b.prop);
+    };
+    return createElement(Component, { ...rest, style: staticStyle, ref });
+  };
+}
+
+export const Animated = {
+  Value: AnimatedValue,
+  View: createAnimatedComponent('View'),
+  Text: createAnimatedComponent('Text'),
+  Image: createAnimatedComponent('Image'),
+  timing,
+  spring,
+  decay,
+  sequence,
+  parallel,
+  stagger,
+  delay,
+  loop,
+  createAnimatedComponent,
+};

package/src/embedded-react/AppRegistry.js

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// AppRegistry — the RN entry point. An app registers a root component; the runtime mounts it into
+// a screen-sized container.
+//
+// In React Native the native side calls runApplication when the activity starts. Our host model is
+// "running the bundle IS starting the app", so registerComponent mounts immediately into a root
+// sized from the host-injected `screen` global. (A host-driven runApplication can be split out
+// later when the C host owns app lifecycle.)
+import { createElement } from 'react';
+import { createRoot } from '../renderer.js';
+
+let registered = null;
+
+export const AppRegistry = {
+  /**
+   * Registers a root component and mounts it. `componentProvider` is a zero-arg function returning
+   * the component (RN signature), so the component module isn't evaluated until registration.
+   */
+  registerComponent(appKey, componentProvider) {
+    registered = { appKey, Component: componentProvider() };
+    AppRegistry.runApplication(appKey);
+    return appKey;
+  },
+
+  /**
+   * Mounts the registered root component into a fresh screen-sized container.
+   */
+  runApplication(appKey) {
+    if (!registered) return;
+    if (appKey && appKey !== registered.appKey) return;
+    const root = createRoot({ width: screen.width, height: screen.height });
+    root.render(createElement(registered.Component));
+  },
+};

package/src/embedded-react/Easing.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Easing tokens. The engine implements a fixed set of easing curves (ERAnimEasing), so unlike RN's
+// composable Easing functions these are string tokens the bridge maps to the engine enum. `bezier`
+// returns a control-point object the bridge reads as a custom cubic-bezier curve.
+export const Easing = {
+  linear: 'linear',
+  ease: 'ease',
+  easeIn: 'easeIn',
+  easeOut: 'easeOut',
+  easeInOut: 'easeInOut',
+  quadIn: 'quadIn',
+  quadOut: 'quadOut',
+  quadInOut: 'quadInOut',
+  cubicIn: 'cubicIn',
+  cubicOut: 'cubicOut',
+  cubicInOut: 'cubicInOut',
+  bounceOut: 'bounceOut',
+  elasticOut: 'elasticOut',
+
+  /** Custom cubic-bezier curve via control points. */
+  bezier(x1, y1, x2, y2) {
+    return { x1, y1, x2, y2 };
+  },
+};

package/src/embedded-react/LayoutAnimation.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// LayoutAnimation — the React Native analog. Calling configureNext(...) before a state update that
+// changes layout makes the engine tween every node whose computed rect moved (instead of snapping)
+// on the next commit. Backed by the engine's er_layout_anim_configure_next; the tween advances in C
+// each frame (er_layout_anim_tick), so there's no per-frame JS.
+import { NativeUI } from '../native-ui.js';
+import { Types, Properties, Presets, toEngineConfig, create } from './layout-anim-config.js';
+
+/**
+ * Arms a layout animation for the next commit. Call right before the setState that changes layout.
+ * onAnimationDidEnd is approximated with a timer (the engine config carries no completion hook).
+ */
+export function configureNext(config, onAnimationDidEnd) {
+  NativeUI.configureNextLayoutAnimation(toEngineConfig(config));
+  if (typeof onAnimationDidEnd === 'function') {
+    const ms = config && typeof config.duration === 'number' ? config.duration : 300;
+    setTimeout(onAnimationDidEnd, ms);
+  }
+}
+
+export const LayoutAnimation = {
+  configureNext,
+  create,
+  Types,
+  Properties,
+  Presets,
+  easeInEaseOut: (onDone) => configureNext(Presets.easeInEaseOut, onDone),
+  linear: (onDone) => configureNext(Presets.linear, onDone),
+  spring: (onDone) => configureNext(Presets.spring, onDone),
+};

package/src/embedded-react/Platform.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Platform — minimal RN analog. OS is "embedded"; select() picks the embedded entry (falling back
+// to default) so apps can write Platform.select({ embedded: ..., default: ... }).
+export const Platform = {
+  OS: 'embedded',
+  select(specifics) {
+    if (specifics == null) return undefined;
+    if ('embedded' in specifics) return specifics.embedded;
+    return specifics.default;
+  },
+};

package/src/embedded-react/StyleSheet.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// StyleSheet — the React Native analog. `create` is an identity pass-through (styles are plain
+// objects the host config flattens at setProps time); `flatten` collapses nested arrays/objects.
+export const StyleSheet = {
+  create(styles) {
+    return styles;
+  },
+
+  flatten(style) {
+    if (!style) return {};
+    if (Array.isArray(style)) {
+      const out = {};
+      for (const s of style) Object.assign(out, StyleSheet.flatten(s));
+      return out;
+    }
+    return style;
+  },
+
+  hairlineWidth: 1,
+  absoluteFill: { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 },
+};

package/src/embedded-react/components.js

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Host components. Each is the string tag the reconciler passes to NativeUI.createNode(), which
+// maps it onto an ERNodeType. JSX `<View/>` → createElement('View', ...) → createInstance('View').
+export const View = 'View';
+export const Text = 'Text';
+export const Image = 'Image';
+export const ScrollView = 'ScrollView';
+export const FlatList = 'FlatList';
+export const Pressable = 'Pressable';
+// TouchableOpacity is RN's press-with-opacity wrapper; for now it maps to the same Pressable node.
+export const TouchableOpacity = 'Pressable';
+export const TextInput = 'TextInput';
+export const Switch = 'Switch';
+export const ActivityIndicator = 'ActivityIndicator';
+export const Modal = 'Modal';
+
+// SVG surface. <Svg> is the only host node (→ ER_NODE_VECTOR); the shape tags below are descriptive
+// children that the host config flattens into the Svg node's op-tape (they are never mounted on their
+// own — like raw text inside <Text>). Use them only inside an <Svg>.
+export const Svg = 'Svg';
+export const Path = 'Path';
+export const Circle = 'Circle';
+export const Ellipse = 'Ellipse';
+export const Rect = 'Rect';
+export const Line = 'Line';
+export const G = 'G';
+// Arc convenience primitive (not a standard SVG element): a circular arc given a center, radius, and
+// start/end angles in DEGREES clockwise from 12 o'clock. Flattens to a native arc op — cheap to update.
+export const Arc = 'Arc';

package/src/embedded-react/imperative.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2026 Cory Lamming
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Imperative escape hatch for high-frequency interactive updates.
+//
+// Going through React on every pointer move is too slow on some devices — the
+// reconcile + flatten dominate. For continuous gestures (e.g., dragging a dial), grab a node handle via
+// a ref and push updates directly here: it skips React entirely and, for vectors, skips the d-string
+// parser too. Commit back to React state when the gesture ends so the declarative tree re-syncs.
+import { NativeUI } from '../native-ui.js';
+import { shapesToVector } from './svg-ops.js';
+
+/**
+ * Imperatively sets an <Svg> node's geometry from primitive shape descriptors (see shapesToVector).
+ * @param {number} handle      The node handle from a ref on an <Svg/>.
+ * @param {Array}  shapes      Flat array of shape descriptors ({arc}/{circle}/{line}/{rect}/{path} + paint).
+ * @param {Array}  [dirtyRect] Optional node-local [x, y, w, h] bounding the change; when given, only that
+ *                             region is repainted and flushed (a big win for small updates on a large
+ *                             vector node). Omit to repaint the whole node box.
+ */
+export function updateVector(handle, shapes, dirtyRect) {
+  if (handle == null) return;
+  const { ops, paints } = shapesToVector(shapes);
+  NativeUI.setVectorOps(handle, ops, paints, dirtyRect);
+}
+
+/**
+ * Imperatively sets a <Text> node's text content WITHOUT disturbing its style (uses a single inherited
+ * span, so color/size/etc. from the node's props are preserved). A later React render reverts cleanly.
+ * @param {number} handle  The node handle from a ref on a <Text/>.
+ * @param {string} text    New text content.
+ */
+export function updateText(handle, text) {
+  if (handle == null) return;
+  NativeUI.setTextSpans(handle, [{ text: String(text) }]);
+}
+
+/**
+ * Customises the on-screen software keyboard's appearance and/or layout. Only effective when the engine was
+ * built with the keyboard enabled (ERUI_ONSCREEN_KEYBOARD=1); a no-op otherwise. The config is a plain
+ * object of colours/sizes plus an optional `layers` array; omit `layers` to keep the built-in QWERTY:
+ *
+ *   setKeyboardConfig({ keyColor: '#fff', labelColor: '#111', fontSize: 20,
+ *     layers: [ [ [ { char: 'a' }, ... ],                                    // a row
+ *                 [ { label: 'shift', layer: 1, highlight: true }, ... ] ],  // a row with a layer-switch key
+ *               ... ] });                                                    // more layers
+ *
+ * Key shapes: { char } types it; { char: ' ', span } a space bar; { label, layer } switches layer;
+ * { label, backspace } / { label, done }; optional `span` (grid columns) and `highlight` (lit on its layer).
+ * Pass nothing/null to restore the default.
+ * @param {object} [config]  Keyboard config, or null for the built-in default.
+ */
+export function setKeyboardConfig(config) {
+  NativeUI.setKeyboardConfig(config || null);
+}