embedded-react 0.1.0

package/src/host-config.js

@@ -0,0 +1,196 @@
+/*
+ * 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.
+ */
+
+// react-reconciler host config: translates React's mutation API into NativeUI.* calls.
+//
+// Instances ARE the integer node handles returned by NativeUI.createNode(). We keep no JS-side
+// wrapper objects — the engine owns the scene graph, the handle is the identity.
+import { DefaultEventPriority } from 'react-reconciler/constants';
+import { NativeUI } from './native-ui.js';
+import { buildProps, buildTextSpans, isEventProp, isTextContent } from './props.js';
+import { flattenSvg } from './embedded-react/svg-ops.js';
+import { splitAnimatedStyle } from './embedded-react/split-style.js';
+
+/**
+ * Applies a node's resolved props, binding any Animated.Value found in its `style` to the matching
+ * node prop (native driver). This makes animated styles work on ANY host element — `<Pressable
+ * style={{ transform: [{ scale: v }] }}>` binds without an Animated.* wrapper — which is what the
+ * Flow B AOT compiler does too, so the two render paths stay in parity. An Animated.* wrapper has
+ * already stripped its bindings into a ref, so splitAnimatedStyle finds none here (no double bind).
+ */
+function applyProps(type, handle, props) {
+  const { staticStyle, bindings } = splitAnimatedStyle(props.style);
+  NativeUI.setProps(handle, buildProps(type, bindings.length ? { ...props, style: staticStyle } : props));
+  for (const b of bindings) b.value.__bind(handle, b.prop);
+}
+
+/**
+ * Applies inline-styled text spans for a <Text> node (no-op for other types). buildTextSpans returns
+ * [] for uniform text, which reverts the node to plain-text rendering — so this also clears stale
+ * spans when a Text changes from styled-runs to a single style across renders.
+ */
+function applyTextSpans(type, handle, props) {
+  if (type === 'Text') NativeUI.setTextSpans(handle, buildTextSpans(props));
+}
+
+/**
+ * Compiles an <Svg>'s declarative children (Path/Circle/G/...) into the node's vector op-tape. Like
+ * text spans, the Svg owns its subtree — React does not mount the shape children (see
+ * shouldSetTextContent), so we flatten props.children here on create and every update.
+ */
+function applyVectorOps(type, handle, props) {
+  if (type !== 'Svg') return;
+  const { ops, paints } = flattenSvg(props);
+  NativeUI.setVectorOps(handle, ops, paints);
+}
+
+/**
+ * Registers/clears on* event handlers. A handler present in old but not new props is cleared.
+ */
+function applyEvents(handle, prevProps, nextProps) {
+  if (prevProps) {
+    for (const key in prevProps) {
+      if (isEventProp(key, prevProps[key]) && !(nextProps && isEventProp(key, nextProps[key]))) {
+        NativeUI.setEvent(handle, key, null);
+      }
+    }
+  }
+  for (const key in nextProps) {
+    if (isEventProp(key, nextProps[key])) {
+      NativeUI.setEvent(handle, key, nextProps[key]);
+    }
+  }
+}
+
+export const hostConfig = {
+  supportsMutation: true,
+  supportsPersistence: false,
+  supportsHydration: false,
+  isPrimaryRenderer: true,
+  noTimeout: -1,
+  warnsIfNotActing: false,
+
+  // --- Context (we carry none) ---
+  getRootHostContext() {
+    return {};
+  },
+  getChildHostContext(parentContext) {
+    return parentContext;
+  },
+  getPublicInstance(instance) {
+    return instance;
+  },
+
+  // --- Commit lifecycle ---
+  prepareForCommit() {
+    return null;
+  },
+  resetAfterCommit() {
+    NativeUI.commit();
+  },
+
+  // --- Creation ---
+  createInstance(type, props) {
+    const handle = NativeUI.createNode(type);
+    applyProps(type, handle, props);
+    applyTextSpans(type, handle, props);
+    applyVectorOps(type, handle, props);
+    applyEvents(handle, null, props);
+    return handle;
+  },
+  createTextInstance(text) {
+    // Raw text is only legal inside <Text> (handled via shouldSetTextContent). This fallback
+    // wraps stray text in a Text node so it still renders rather than crashing.
+    const handle = NativeUI.createNode('Text');
+    NativeUI.setProps(handle, { text: String(text) });
+    return handle;
+  },
+  appendInitialChild(parent, child) {
+    NativeUI.appendChild(parent, child);
+  },
+  finalizeInitialChildren() {
+    return false;
+  },
+  shouldSetTextContent(type, props) {
+    // Own the whole subtree for any flattenable <Text> (strings, interpolation, nested <Text>): React
+    // skips mounting children and we render them via the node's text + spans. Non-flattenable content
+    // (e.g. a <View> inside <Text>) returns false, falling back to mounted child instances.
+    // <Svg> also owns its subtree: the shape children are flattened into the vector op-tape
+    // (applyVectorOps), never mounted as host nodes.
+    return type === 'Svg' || (type === 'Text' && isTextContent(props.children));
+  },
+
+  // --- Mutation ---
+  appendChild(parent, child) {
+    NativeUI.appendChild(parent, child);
+  },
+  appendChildToContainer(container, child) {
+    NativeUI.appendChild(container, child);
+  },
+  insertBefore(parent, child, beforeChild) {
+    NativeUI.insertBefore(parent, child, beforeChild);
+  },
+  insertInContainerBefore(container, child, beforeChild) {
+    NativeUI.insertBefore(container, child, beforeChild);
+  },
+  removeChild(parent, child) {
+    NativeUI.removeChild(parent, child);
+    NativeUI.destroyNode(child);
+  },
+  removeChildFromContainer(container, child) {
+    NativeUI.removeChild(container, child);
+    NativeUI.destroyNode(child);
+  },
+  clearContainer() {
+    // Children are removed individually via removeChildFromContainer.
+  },
+  prepareUpdate() {
+    // Always re-apply: NativeUI.setProps is fully declarative, so a non-null payload is enough.
+    return true;
+  },
+  commitUpdate(instance, _payload, type, prevProps, nextProps) {
+    applyProps(type, instance, nextProps);
+    applyTextSpans(type, instance, nextProps);
+    applyVectorOps(type, instance, nextProps);
+    applyEvents(instance, prevProps, nextProps);
+  },
+  commitTextUpdate(textInstance, _oldText, newText) {
+    NativeUI.setProps(textInstance, { text: String(newText) });
+  },
+
+  // --- Misc required hooks (no-ops for our renderer) ---
+  detachDeletedInstance() {},
+  getCurrentEventPriority() {
+    return DefaultEventPriority;
+  },
+  getInstanceFromNode() {
+    return null;
+  },
+  beforeActiveInstanceBlur() {},
+  afterActiveInstanceBlur() {},
+  prepareScopeUpdate() {},
+  getInstanceFromScope() {
+    return null;
+  },
+
+  // --- Scheduling ---
+  scheduleTimeout: (fn, delay) => setTimeout(fn, delay),
+  cancelTimeout: (id) => clearTimeout(id),
+  supportsMicrotasks: true,
+  scheduleMicrotask:
+    typeof queueMicrotask === 'function' ? queueMicrotask : (fn) => Promise.resolve().then(fn),
+  now: () => NativeUI.now(),
+};

package/src/native-ui.js

@@ -0,0 +1,24 @@
+/*
+ * 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.
+ */
+
+// The QuickJS C bridge (native_ui_bridge.c) installs a global `NativeUI` object before the
+// bundle runs. Re-export it so the rest of the JS imports it cleanly instead of touching the
+// global directly.
+export const NativeUI = globalThis.NativeUI;
+
+if (!NativeUI) {
+  throw new Error('NativeUI global is missing — the QuickJS bridge must be installed before the bundle runs.');
+}

package/src/props.js

@@ -0,0 +1,183 @@
+/*
+ * 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.
+ */
+
+// Pure prop-marshalling helpers. No engine / NativeUI dependency, so these are unit-testable in
+// plain Node (see src/__tests__/props.unit.test.js). The host config wires them to NativeUI.
+
+// Top-level props NativeUI understands directly (not part of `style`). Everything else style-ish is
+// expected inside props.style. Event handlers (on*) are routed separately via setEvent.
+export const PASSTHROUGH = [
+  'numberOfLines',
+  'ellipsizeMode',
+  'value',
+  'placeholder',
+  'placeholderTextColor',
+  'editable',
+  'animating',
+  'visible',
+  'resizeMode',
+  'tintColor',
+  'imageName',
+];
+
+/**
+ * Flattens RN-style `style` (object or nested array) into the `out` object.
+ */
+export function flattenStyle(style, out) {
+  if (!style) return;
+  if (Array.isArray(style)) {
+    for (const s of style) flattenStyle(s, out);
+  } else {
+    Object.assign(out, style);
+  }
+}
+
+/** Flattens a style (object/array) into a fresh plain object. */
+export function flattenStyleObj(style) {
+  const out = {};
+  flattenStyle(style, out);
+  return out;
+}
+
+// Style fields the engine honors per inline text span (everything else inherits from the node).
+const SPAN_STYLE_KEYS = ['color', 'fontSize', 'fontWeight', 'fontStyle', 'textDecorationLine', 'letterSpacing'];
+
+/**
+ * True when a <Text>'s children can be flattened inline — i.e. every leaf is a string/number or a
+ * nested <Text> element. A non-Text element (View, a component) makes it false, so the reconciler
+ * falls back to mounting children as separate instances.
+ */
+export function isTextContent(children) {
+  if (children == null || children === false || children === true) return true;
+  if (typeof children === 'string' || typeof children === 'number') return true;
+  if (Array.isArray(children)) return children.every(isTextContent);
+  // A React element: only nested <Text> participates in inline flattening (type is the 'Text' tag).
+  if (children && children.props !== undefined) return children.type === 'Text';
+  return false;
+}
+
+/**
+ * Walks a <Text>'s children into an ordered list of { text, style } segments. Primitive siblings
+ * share the parent's (base) style object by reference; a nested <Text> with its own style produces
+ * a new merged style object. Adjacent segments with the same style reference are coalesced — so
+ * plain interpolation like `Hi {name}` collapses to a single segment (no spans needed).
+ */
+export function flattenTextChildren(children, baseStyle) {
+  const segments = [];
+  const push = (text, style) => {
+    if (text === '') return;
+    const last = segments[segments.length - 1];
+    if (last && last.style === style) last.text += text;
+    else segments.push({ text, style });
+  };
+  const walk = (node, style) => {
+    if (node == null || node === false || node === true) return;
+    if (typeof node === 'string' || typeof node === 'number') {
+      push(String(node), style);
+      return;
+    }
+    if (Array.isArray(node)) {
+      for (const c of node) walk(c, style);
+      return;
+    }
+    if (node && node.props !== undefined) {
+      // Nested <Text>: merge its style over the inherited one (new object only when it has style,
+      // so an unstyled nested <Text> keeps the same reference and still coalesces with siblings).
+      const merged = node.props.style ? Object.assign({}, style, flattenStyleObj(node.props.style)) : style;
+      walk(node.props.children, merged);
+    }
+  };
+  walk(children, baseStyle);
+  return segments;
+}
+
+/**
+ * Builds the inline-span array for a <Text> (for NativeUI.setTextSpans). Returns [] when the content
+ * is uniformly the base style (plain text — no spans needed); otherwise one span per styled segment,
+ * each carrying only the span-relevant style keys (the engine inherits the rest from the node).
+ */
+export function buildTextSpans(props) {
+  if (!isTextContent(props.children)) return [];
+  const baseStyle = flattenStyleObj(props.style);
+  const segments = flattenTextChildren(props.children, baseStyle);
+  if (!segments.some((s) => s.style !== baseStyle)) return [];
+  return segments.map((s) => {
+    const span = { text: s.text };
+    for (const k of SPAN_STYLE_KEYS) {
+      if (s.style && s.style[k] !== undefined) span[k] = s.style[k];
+    }
+    return span;
+  });
+}
+
+/**
+ * Builds the flat prop bag NativeUI.setProps expects: resolved style + passthrough props + text.
+ */
+/**
+ * Resolves an <Image source> to the engine asset name (the string registered via er_image_load and
+ * stored on the node as imageName). Accepts a bare name string — which is also what the bundler's
+ * image plugin turns `import logo from './logo.png'` into (the file's basename) — or an RN-style
+ * { uri } object. Returns null for anything unresolvable (e.g., a numeric require() id).
+ */
+export function resolveImageSource(source) {
+  if (typeof source === 'string') return source;
+  if (source && typeof source === 'object' && typeof source.uri === 'string') return source.uri;
+  return null;
+}
+
+export function buildProps(type, props) {
+  const flat = {};
+  flattenStyle(props.style, flat);
+  for (const k of PASSTHROUGH) {
+    if (props[k] !== undefined) flat[k] = props[k];
+  }
+  // <Svg> takes width/height as DIRECT props (the react-native-svg convention) — the engine sizes the
+  // vector node from them. Fold them into the resolved style (an explicit style width/height still wins)
+  // so Flow A matches the Flow B AOT, which reads svg.props.width/height directly (compile.mjs emitSvgBox).
+  if (type === 'Svg') {
+    if (flat.width === undefined && props.width !== undefined) flat.width = props.width;
+    if (flat.height === undefined && props.height !== undefined) flat.height = props.height;
+  }
+  // <Image source={...}> resolves to the engine asset name unless imageName was set explicitly.
+  if (flat.imageName === undefined && props.source != null) {
+    const name = resolveImageSource(props.source);
+    if (name != null) flat.imageName = name;
+  }
+  // <Text> content: flatten string/number/nested-<Text> children into the node's full-text string.
+  // The engine renders this when no spans are set; with spans (buildTextSpans) it carries the same
+  // text for the plain-text fallback. Non-flattenable children fall back to mounted child instances.
+  if (type === 'Text' && isTextContent(props.children)) {
+    const base = flattenStyleObj(props.style);
+    flat.text = flattenTextChildren(props.children, base)
+      .map((s) => s.text)
+      .join('');
+  }
+  return flat;
+}
+
+/**
+ * True for an `onXxx` prop whose value is a function (an event handler to route via setEvent).
+ */
+export function isEventProp(key, value) {
+  return (
+    key.length > 2 &&
+    key[0] === 'o' &&
+    key[1] === 'n' &&
+    key[2] >= 'A' &&
+    key[2] <= 'Z' &&
+    typeof value === 'function'
+  );
+}

package/src/renderer.js

@@ -0,0 +1,57 @@
+/*
+ * 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.
+ */
+
+// Public renderer API: createRoot(...).render(<App/>).
+//
+// The container is a real engine View node set as the scene root; React children mount into it.
+// We use LegacyRoot (synchronous) mode so the initial render flushes without depending on the
+// async scheduler/timers — the host's frame loop then paints whatever the tree became.
+import Reconciler from 'react-reconciler';
+import { hostConfig } from './host-config.js';
+import { NativeUI } from './native-ui.js';
+
+const reconciler = Reconciler(hostConfig);
+
+const LegacyRoot = 0;
+
+/**
+ * Creates a root bound to a screen-sized container node.
+ *
+ * @param {object} containerProps  Props for the container View (e.g. width/height/backgroundColor).
+ * @returns {{ render: (element: any) => void }}
+ */
+export function createRoot(containerProps) {
+  const container = NativeUI.createNode('View');
+  NativeUI.setProps(container, containerProps || {});
+  NativeUI.setRoot(container);
+
+  const fiberRoot = reconciler.createContainer(
+    container, // containerInfo — our root node handle
+    LegacyRoot,
+    null, // hydration callbacks
+    false, // isStrictMode
+    null, // concurrentUpdatesByDefaultOverride
+    '', // identifierPrefix
+    (error) => console.error('react recoverable error:', error),
+    null, // transitionCallbacks
+  );
+
+  return {
+    render(element) {
+      reconciler.updateContainer(element, fiberRoot, null, null);
+    },
+  };
+}