embedded-react 0.3.0 → 0.4.0

package/src/host-config.js

@@ -18,11 +18,21 @@
 //
 // 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';
+import {DefaultEventPriority} from 'react-reconciler/constants';
+import {NativeUI} from './native-ui.js';
+import {
+  buildProps,
+  buildTextSpans,
+  isEventProp,
+  isTextContent,
+} from './props.js';
+import {
+  flattenSvg,
+  warnVectorCaps,
+  scaleVectorArtifact,
+  encodeVectorGradients,
+} 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
@@ -32,8 +42,11 @@ import { splitAnimatedStyle } from './embedded-react/split-style.js';
  * 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));
+  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);
 }
 
@@ -46,15 +59,100 @@ function applyTextSpans(type, handle, props) {
   if (type === 'Text') NativeUI.setTextSpans(handle, buildTextSpans(props));
 }
 
+/** Resolves an <Svg>'s render-box dimension from style/props, falling back to the source's intrinsic size. */
+function svgBoxSize(props, dim, intrinsic) {
+  const s =
+    props.style && typeof props.style[dim] === 'number'
+      ? props.style[dim]
+      : undefined;
+  const p = typeof props[dim] === 'number' ? props[dim] : undefined;
+  return s ?? p ?? intrinsic;
+}
+
+/**
+ * A `<Svg source={imported}>` whose imported .svg fell back to a RASTER image at build time (the SVG used
+ * features the vector baker can't represent). Returns the artifact, or null for a vector/declarative
+ * Svg. Such a Svg is rendered as an IMAGE node, not a vector node — `props.source.kind` is the discriminator
+ * (an imported artifact's kind is fixed at build time, so it never flips for a given element).
+ */
+function rasterSvgArtifact(type, props) {
+  const src = props && props.source;
+  return type === 'Svg' && src && src.kind === 'raster' ? src : null;
+}
+
+/** Maps a raster `<Svg source>` to equivalent `<Image>` props: the baked asset name + the resolved box size. */
+function rasterImageProps(props, art) {
+  const width = svgBoxSize(props, 'width', art.width);
+  const height = svgBoxSize(props, 'height', art.height);
+  return {
+    ...props,
+    source: art.name,
+    style: {...(props.style || {}), width, height},
+  };
+}
+
 /**
- * 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.
+ * Sets an <Svg>'s vector op-tape. Two sources, source prop wins:
+ *   <Svg source={imported}>  — an imported .svg's baked artifact ({kind:'vector', ops, paints, width,
+ *                              height}); we scale its op-tape from intrinsic px to the node's box.
+ *   <Svg><Path/>...</Svg>    — declarative children flattened here (the Svg owns its subtree; React does
+ *                              not mount the shape children, so we compile them on create + every update).
  */
 function applyVectorOps(type, handle, props) {
   if (type !== 'Svg') return;
-  const { ops, paints } = flattenSvg(props);
-  NativeUI.setVectorOps(handle, ops, paints);
+  let ops;
+  let paints;
+  let gradients;
+  const src = props.source;
+  if (src && src.kind === 'vector' && Array.isArray(src.ops)) {
+    ({ops, paints, gradients} = scaleVectorArtifact(
+      src,
+      svgBoxSize(props, 'width', src.width),
+      svgBoxSize(props, 'height', src.height),
+    ));
+  } else {
+    ({ops, paints} = flattenSvg(props));
+  }
+  warnVectorCaps(
+    ops.length,
+    paints.length,
+    NativeUI.maxVectorOps,
+    NativeUI.maxVectorPaints,
+    gradients ? gradients.length : 0,
+    NativeUI.maxVectorGrads,
+  );
+  NativeUI.setVectorOps(
+    handle,
+    ops,
+    paints,
+    gradients && gradients.length
+      ? encodeVectorGradients(gradients)
+      : undefined,
+  );
+}
+
+/**
+ * Decides whether a committed <Svg> update actually needs its op-tape re-uploaded.
+ *
+ * Re-marshaling a baked vector op-tape across the JS->C bridge every frame is expensive (it dominates an
+ * interactive drag on PSRAM-QuickJS), and it's pure waste when only the node's POSITION changed: a
+ * `<Svg source>` whose imported artifact and resolved box are unchanged renders identical geometry, and its
+ * on-screen movement is already handled by the layout props (left/top/width/height) via applyProps. So we
+ * re-upload only when the source artifact reference changes or the resolved box size changes. Declarative
+ * `<Svg><Path/></Svg>` has no `source` — its shapes live in props/children, which we can't cheaply diff
+ * here, so it always re-flattens (unchanged behavior).
+ */
+function vectorNeedsUpload(type, prevProps, nextProps) {
+  if (type !== 'Svg') return false;
+  if (!nextProps.source) return true; // declarative children: re-flatten as before
+  if (!prevProps || prevProps.source !== nextProps.source) return true;
+  const src = nextProps.source;
+  const iw = src && src.kind === 'vector' ? src.width : undefined;
+  const ih = src && src.kind === 'vector' ? src.height : undefined;
+  return (
+    svgBoxSize(prevProps, 'width', iw) !== svgBoxSize(nextProps, 'width', iw) ||
+    svgBoxSize(prevProps, 'height', ih) !== svgBoxSize(nextProps, 'height', ih)
+  );
 }
 
 /**
@@ -63,7 +161,10 @@ function applyVectorOps(type, handle, props) {
 function applyEvents(handle, prevProps, nextProps) {
   if (prevProps) {
     for (const key in prevProps) {
-      if (isEventProp(key, prevProps[key]) && !(nextProps && isEventProp(key, nextProps[key]))) {
+      if (
+        isEventProp(key, prevProps[key]) &&
+        !(nextProps && isEventProp(key, nextProps[key]))
+      ) {
         NativeUI.setEvent(handle, key, null);
       }
     }
@@ -104,6 +205,14 @@ export const hostConfig = {
 
   // --- Creation ---
   createInstance(type, props) {
+    // A raster-fallback <Svg source> becomes a real Image node (the SVG was rasterized at build time).
+    const raster = rasterSvgArtifact(type, props);
+    if (raster) {
+      const handle = NativeUI.createNode('Image');
+      applyProps('Image', handle, rasterImageProps(props, raster));
+      applyEvents(handle, null, props);
+      return handle;
+    }
     const handle = NativeUI.createNode(type);
     applyProps(type, handle, props);
     applyTextSpans(type, handle, props);
@@ -115,7 +224,7 @@ export const hostConfig = {
     // 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) });
+    NativeUI.setProps(handle, {text: String(text)});
     return handle;
   },
   appendInitialChild(parent, child) {
@@ -162,13 +271,21 @@ export const hostConfig = {
     return true;
   },
   commitUpdate(instance, _payload, type, prevProps, nextProps) {
+    const raster = rasterSvgArtifact(type, nextProps);
+    if (raster) {
+      // The Svg instance is an Image node (raster fallback); re-apply as image props, never vector ops.
+      applyProps('Image', instance, rasterImageProps(nextProps, raster));
+      applyEvents(instance, prevProps, nextProps);
+      return;
+    }
     applyProps(type, instance, nextProps);
     applyTextSpans(type, instance, nextProps);
-    applyVectorOps(type, instance, nextProps);
+    if (vectorNeedsUpload(type, prevProps, nextProps))
+      applyVectorOps(type, instance, nextProps);
     applyEvents(instance, prevProps, nextProps);
   },
   commitTextUpdate(textInstance, _oldText, newText) {
-    NativeUI.setProps(textInstance, { text: String(newText) });
+    NativeUI.setProps(textInstance, {text: String(newText)});
   },
 
   // --- Misc required hooks (no-ops for our renderer) ---
@@ -188,9 +305,11 @@ export const hostConfig = {
 
   // --- Scheduling ---
   scheduleTimeout: (fn, delay) => setTimeout(fn, delay),
-  cancelTimeout: (id) => clearTimeout(id),
+  cancelTimeout: id => clearTimeout(id),
   supportsMicrotasks: true,
   scheduleMicrotask:
-    typeof queueMicrotask === 'function' ? queueMicrotask : (fn) => Promise.resolve().then(fn),
+    typeof queueMicrotask === 'function'
+      ? queueMicrotask
+      : fn => Promise.resolve().then(fn),
   now: () => NativeUI.now(),
 };

package/src/native-ui.js

@@ -20,5 +20,7 @@
 export const NativeUI = globalThis.NativeUI;
 
 if (!NativeUI) {
-  throw new Error('NativeUI global is missing — the QuickJS bridge must be installed before the bundle runs.');
+  throw new Error(
+    'NativeUI global is missing — the QuickJS bridge must be installed before the bundle runs.',
+  );
 }

package/src/props.js

@@ -53,7 +53,14 @@ export function flattenStyleObj(style) {
 }
 
 // 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'];
+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
@@ -81,7 +88,7 @@ export function flattenTextChildren(children, baseStyle) {
     if (text === '') return;
     const last = segments[segments.length - 1];
     if (last && last.style === style) last.text += text;
-    else segments.push({ text, style });
+    else segments.push({text, style});
   };
   const walk = (node, style) => {
     if (node == null || node === false || node === true) return;
@@ -96,7 +103,9 @@ export function flattenTextChildren(children, baseStyle) {
     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;
+      const merged = node.props.style
+        ? Object.assign({}, style, flattenStyleObj(node.props.style))
+        : style;
       walk(node.props.children, merged);
     }
   };
@@ -113,9 +122,9 @@ 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 };
+  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];
     }
@@ -134,7 +143,8 @@ export function buildTextSpans(props) {
  */
 export function resolveImageSource(source) {
   if (typeof source === 'string') return source;
-  if (source && typeof source === 'object' && typeof source.uri === 'string') return source.uri;
+  if (source && typeof source === 'object' && typeof source.uri === 'string')
+    return source.uri;
   return null;
 }
 
@@ -148,8 +158,10 @@ export function buildProps(type, props) {
   // 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;
+    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) {
@@ -162,7 +174,7 @@ export function buildProps(type, props) {
   if (type === 'Text' && isTextContent(props.children)) {
     const base = flattenStyleObj(props.style);
     flat.text = flattenTextChildren(props.children, base)
-      .map((s) => s.text)
+      .map(s => s.text)
       .join('');
   }
   return flat;

package/src/renderer.js

@@ -20,8 +20,8 @@
 // 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';
+import {hostConfig} from './host-config.js';
+import {NativeUI} from './native-ui.js';
 
 const reconciler = Reconciler(hostConfig);
 
@@ -45,7 +45,7 @@ export function createRoot(containerProps) {
     false, // isStrictMode
     null, // concurrentUpdatesByDefaultOverride
     '', // identifierPrefix
-    (error) => console.error('react recoverable error:', error),
+    error => console.error('react recoverable error:', error),
     null, // transitionCallbacks
   );