embedded-react 0.13.0 → 0.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -224,6 +224,58 @@ public on every component for gestures that don't fit the pan shape. Only RN's A
224
224
  `onShouldBlockNativeResponder` is unsupported — holding the responder already blocks the native one
225
225
  (the built-in adjustable-Arc drag deliberately still wins). Passing it, or a typo, warns.
226
226
 
227
+ ### Dragging faster than React — `updateVector` / `updateText`
228
+
229
+ A render per pointer move is the expensive way to drive a gesture. Measured on an ESP32-S3 dragging a
230
+ JS-drawn knob (a `<Path d>` rebuilt every move, state at the root), one frame cost ~103 ms of JS —
231
+ roughly half React's render and half re-marshaling the tree — plus ~51 ms of engine commit. Pushing
232
+ the same geometry straight at the node instead costs **~10 µs of JS**, and about a third of the
233
+ raster, because only that node is dirtied rather than the whole tree.
234
+
235
+ Take a handle from a ref on the `<Svg>` and write to it during the gesture:
236
+
237
+ ```jsx
238
+ const arc = useRef(0);
239
+
240
+ const pan = useRef(
241
+ PanResponder.create({
242
+ onStartShouldSetPanResponder: () => true,
243
+ onPanResponderMove: (e, g) => {
244
+ const deg = angleFor(g.moveX, g.moveY);
245
+ updateVector(arc.current, [
246
+ {arc: [CX, CY, R, 0, deg], stroke: '#f4a261', strokeWidth: 14, cap: 'round'},
247
+ {circle: [handleX(deg), handleY(deg), 8], fill: '#fff'},
248
+ ]);
249
+ },
250
+ onPanResponderRelease: (e, g) => setValue(valueFor(g.moveX, g.moveY)), // re-sync React
251
+ }),
252
+ ).current;
253
+
254
+ <View {...pan.panHandlers} style={{width: W, height: H}}>
255
+ <Svg ref={h => (arc.current = h)} width={W} height={H} />
256
+ </View>;
257
+ ```
258
+
259
+ Each shape is **one geometry key plus its paint** — `arc`/`circle`/`line`/`rect`/`path`, with
260
+ `fill`, `stroke`, `strokeWidth`, `cap`, `join`, `miter`, `fillRule`, `fillGrad`, `strokeGrad`. Note the
261
+ short paint spellings: this is the allocation-free path, not the JSX attribute set. `path` takes a `d`
262
+ string but pays the parser, so prefer the primitives on a hot path. **Arc angles are degrees clockwise
263
+ from 12 o'clock**, which is not the convention an SVG `A` command uses.
264
+
265
+ The optional third argument is a node-local `[x, y, w, h]` bounding the change — give it and only that
266
+ region repaints and flushes, which is a large win for a small update on a big vector node.
267
+
268
+ `updateText(handle, text)` is the same idea for a `<Text>`: it sets the content through a single
269
+ inherited span, so the node's own color/size are untouched.
270
+
271
+ This is a **write-through**, not a new source of truth: the node keeps what you pushed until React next
272
+ renders that element, which overwrites it cleanly. So commit the final value to state when the gesture
273
+ ends — the release handler above — and the declarative tree takes over again. Both flows compile it;
274
+ the AOT lowers `updateVector` the same way.
275
+
276
+ If the shape you are drawing is a dial, reach for `<Dial>` first — it tracks the finger and repaints
277
+ the arc in C, with no JS per move at all.
278
+
227
279
  ## Build
228
280
 
229
281
  ```
@@ -374,7 +426,10 @@ The runtime tiers need the harness exe built once (no SDL); `test:bytecode` also
374
426
  cmake --build bridges/quickjs/build --target er-bridge-quickjs-runtest er-bridge-quickjs-compile
375
427
  ```
376
428
 
377
- Pick the tier by what the code touches: pure marshalling/logic → a co-located `*.unit.test.js`;
429
+ To use a bridge build in another directory, point `ER_BRIDGE_BUILD_DIR` at it. CI runs both runtime tiers
430
+ this way, against the bridge job's two Release builds on Linux (the native and the bare-metal allocator).
431
+
432
+ Pick the tier by what the code touches: pure marshaling/logic → a co-located `*.unit.test.js`;
378
433
  anything that exercises the reconciler → engine pipeline → a `test/runtime/*.runtime.test.jsx`.
379
434
 
380
435
  ## Status & known gaps
@@ -387,6 +442,28 @@ anything that exercises the reconciler → engine pipeline → a `test/runtime/*
387
442
  `clearInterval` and the Promise job queue are serviced each frame by the host pump
388
443
  (`er_bridge_pump`, off the engine clock). React passive effects (`useEffect`) flush on the pump.
389
444
  Covered by `timers.runtime.test.js` and `effects.runtime.test.jsx`.
445
+ - ✅ **`Date.now()` / `performance.now()` in both flows.** Both run on the engine clock, with the same
446
+ surface as the lite JS profile (no `Date` objects). Until the host sets the real time —
447
+ `er_runtime_set_wall_clock()` in Flow A, `er_app_set_wall_clock()` in Flow B — `Date.now()` reads as
448
+ uptime. Flow B holds a timestamp as 64-bit whole milliseconds: keep it in state, a ref, or a local,
449
+ compare it, show it in text, and divide it by a constant with `%` or `Math.floor`/`ceil`/`round`/
450
+ `trunc(a / b)`; a plain `/`, a divisor from state, or mixing it with a float or a boolean is a
451
+ compiler error. Covered by
452
+ `date-now.runtime.test.js`, the AOT's `date-now`, `cc-compile` and `text-lowering` cases, and the
453
+ engine's `test_node_pool`.
454
+ - ✅ **Whole-number math in Flow B is defined.** C leaves a signed overflow, a zero divisor and an
455
+ out-of-range float-to-int conversion undefined, so the generated C gives each an answer: `+`, `-`,
456
+ `*` and negation saturate at the limit of their C type (JS would keep a bigger number; the nearest
457
+ one the type holds keeps its sign and order); `%`, an int ref's `/=`, and `Math.floor`/`ceil`/`round`/
458
+ `trunc` of an int divided by an int give JS's result kept whole and exact, so `x % 0` is 0 and `x / 0`
459
+ saturates; and a float that is NaN or past the int range becomes 0 or
460
+ the nearest int. Constant math is worked out at compile time, as JS would, so `30 * DAY_MS` is an
461
+ exact 64-bit value. Beside a timestamp, or stored into a 64-bit slot, whole-number math is done in
462
+ 64 bits all the way through: `+`, `-`, `*`, negation, `%`, and `Math.floor`/`ceil`/`round`/`trunc`/
463
+ `abs`/`min`/`max`, so `Date.now() + Math.trunc(n * 100000 / 2)` is exact. A handler local or a ternary
464
+ branch is still worked out on its own terms. `Math.abs`, `min` and `max` of ints stay whole numbers,
465
+ and `Math.round` rounds halves up, as JS does. Covered by the AOT's `compile`, `date-now`, `cc-compile` and `text-lowering` cases,
466
+ the last run under UBSan.
390
467
  - ✅ **Animated composition + completion.** `sequence`/`parallel`/`stagger`/`delay`/`loop` and
391
468
  `.start(({ finished }) => …)` all work — composition is pure JS over each child's start/stop, with
392
469
  completion wired through the engine's `on_complete`. Covered by `anim-compose.runtime.test.js`.