embedded-react 0.12.0 → 0.13.0

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
@@ -37,6 +37,32 @@ AppRegistry.registerComponent('demo', () => App);
37
37
  `embedded-react` resolves as a Node **package self-reference** (`package.json` `name` + `exports`),
38
38
  so esbuild and Vitest find it with no aliases.
39
39
 
40
+ `<FlatList>` renders, but it is a thin `<ScrollView>` alias — no virtualization, every row mounts and
41
+ stays mounted, and only `data` / `renderItem` / `keyExtractor` / `style` are honored. See [`FlatList` is
42
+ a `ScrollView`
43
+ alias](https://github.com/TheMasterCoder007/embedded-react#flatlist-is-a-scrollview-alias) for the node
44
+ budget it costs and what to do with a long list.
45
+
46
+ `<Button>`, `<ImageBackground>` and `<SectionList>` are JavaScript wrappers over the primitives, the
47
+ way RN implements them — a styled `<Pressable>` + `<Text>`, a `<View>` with an absolutely-filled
48
+ `<Image>` behind its children, and a `<ScrollView>` whose sections lay out as flat siblings. They add
49
+ no engine node, they are **Flow A only** (the AOT names them and tells you the tree to write instead),
50
+ and `<SectionList>` inherits every `<FlatList>` caveat plus a header and footer per section. See
51
+ [`Button`, `ImageBackground` and `SectionList` are JSX, not
52
+ nodes](https://github.com/TheMasterCoder007/embedded-react#button-imagebackground-and-sectionlist-are-jsx-not-nodes).
53
+
54
+ `<TouchableOpacity>` is a wrapper too, but a cheaper one: it is a `<Pressable>` whose opacity is bound to
55
+ a press animation, so it costs no extra node and it compiles in **both flows**. The dim runs on the
56
+ native driver — no JS per frame — and every `<Pressable>` prop works on it unchanged. See
57
+ [`<TouchableOpacity>` dims on the native
58
+ driver](https://github.com/TheMasterCoder007/embedded-react#touchableopacity-dims-on-the-native-driver).
59
+
60
+ RN modules that wrap an operating system — `StatusBar`, `SafeAreaView`, `AppState`, `Appearance`,
61
+ `Linking`, `AccessibilityInfo` — are **intentionally absent**; a microcontroller has no OS for them to
62
+ wrap. See [Intentionally absent React Native
63
+ APIs](https://github.com/TheMasterCoder007/embedded-react#intentionally-absent-react-native-apis) for
64
+ the full list and what to use instead.
65
+
40
66
  ## Simulate — `npx embedded-react dev`
41
67
 
42
68
  Run your app in a browser with hot reload — no native toolchain, no repo clone. The engine is compiled to
@@ -67,12 +93,13 @@ npx embedded-react export --out sim-export # then: npx serve sim-export (or d
67
93
  ```
68
94
  src/
69
95
  embedded-react/ the public package surface (what apps import)
70
- index.js barrel: components, StyleSheet, Platform, AppRegistry, Animated, Easing
96
+ index.js barrel: components, StyleSheet, Platform, AppRegistry, Animated, PanResponder, Easing
71
97
  components.js host component tags (View, Text, … → ERNodeType)
72
98
  StyleSheet.js create() / flatten()
73
99
  Platform.js { OS: 'embedded', select }
74
100
  AppRegistry.js registerComponent(...) → mounts into a screen-sized root
75
101
  Animated.js Value / timing / spring / decay / View|Text|Image / interpolate
102
+ PanResponder.js create(config) → panHandlers: drag/swipe/fling over the responder system
76
103
  Easing.js easing tokens (+ bezier) → engine curves
77
104
  split-style.js pure: split style into static props + animated bindings
78
105
  __tests__/ co-located UNIT tests for the pure surface
@@ -94,6 +121,7 @@ assets/ build-time asset bakers (pure JS, no native deps) —
94
121
  build.mjs esbuild a demo's index.jsx → dist/app.bundle.js + bake its imported assets
95
122
  pack-container.mjs bundle + bytecode-compile + bake → dist/app.erpkg config container (npm run pack)
96
123
  assets/emit-container.mjs ERCF container writer (sections + QuickJS version stamp + CRC32)
124
+ compile-bin.mjs finds er-bridge-quickjs-compile (shared with the parity harness)
97
125
  vitest.config.js unit test config
98
126
  ```
99
127
 
@@ -123,10 +151,79 @@ page change. Hiding costs a repaint, and a hidden page costs nothing per frame e
123
151
  rendering into it.
124
152
 
125
153
  `visible={false}` is the same switch under the other spelling, with an explicit `style.display`
126
- winning over it (`<Modal visible>` is unaffected — that is the Modal's own show/hide prop). Both work in Flow B too, where `display` can be static or
154
+ winning over it (`<Modal visible>` is unaffected — that is the Modal's own show/hide prop). Both work
155
+ in Flow B too, where `display` can be static or state-driven — `display: page === 'home' ? 'flex' : 'none'`
156
+ compiles, but a state-driven one has to be a string literal or a ternary of them, whereas `visible` takes
157
+ any boolean expression. Either spelling lowers to a `p.display` write in `app_update`, so hiding costs no
158
+ node churn there either. The one gap is `visible` on an `<Svg>`, which the AOT rejects outright: wrap it
159
+ (`<View visible={…}><Svg …/></View>`) and the whole subtree goes with the View.
127
160
  The trade is memory: a cached page holds its nodes for the life of the app, so cache
128
161
  the pages you flip between, not every page.
129
162
 
163
+ ### Gestures — `PanResponder`
164
+
165
+ The raw touch events already carry the travel and the speed (`e.dx`/`e.dy`, `e.vx`/`e.vy` — see below),
166
+ which is enough for a one-off flick. A real drag wants more: an anchor that starts at zero, however, the
167
+ gesture was won, ownership against a scrolling ancestor, and a teardown hook for when the gesture is
168
+ taken away. `PanResponder` is that, in the RN shape (and it compiles in Flow B as well as Flow A):
169
+
170
+ ```jsx
171
+ const pan = useRef(
172
+ PanResponder.create({
173
+ onStartShouldSetPanResponder: () => true,
174
+ onPanResponderMove: (e, g) => setX(g.dx),
175
+ onPanResponderRelease: (e, g) => (g.vx > 0.5 ? next() : settle()),
176
+ }),
177
+ ).current;
178
+
179
+ <View style={styles.overlay} {...pan.panHandlers} />;
180
+ ```
181
+
182
+ Create it **once** per component and keep it in a ref — the handlers close over one gesture state, so
183
+ re-creating it per render throws the drag away. `gestureState` carries `x0`/`y0` (the grant point),
184
+ `dx`/`dy` (travel since the grant), `vx`/`vy` (px per ms), `moveX`/`moveY`, `numberActiveTouches` and
185
+ `stateID`. Returning `true` from `onMoveShouldSetPanResponder` claims the gesture mid-pan and re-anchors
186
+ `dx`/`dy` at that point, so a slop threshold never shows up as a jump. With neither should-set callback
187
+ supplied nothing is ever granted — same as RN.
188
+
189
+ `panHandlers` are the RN **responder props** — should-set queries plus `onResponderGrant`/`Move`/
190
+ `Release`/`Terminate` — wired straight into the engine's C responder system, so claiming is real
191
+ *negotiation*, not just listening:
192
+
193
+ - **A granted pan OWNS the gesture.** A `ScrollView` ancestor will not auto-scroll under it, and a
194
+ `onMoveShouldSetPanResponder` claim takes the gesture *back* from a scroller that already started
195
+ (which then stops dead — no coasting).
196
+ - **Negotiation covers the subtree.** The engine asks every node on the hit chain — capture phase
197
+ root→leaf first (the `*Capture` config keys), then bubble leaf→root — so one responder on a wrapper
198
+ claims its children's touches, and an outer responder can pre-empt an inner one.
199
+ - **Losing and defending are callbacks.** A refused claim lands on `onPanResponderReject` (and is
200
+ re-asked on every later move while the predicate keeps returning true); a challenger asking for the
201
+ gesture hits the holder's `onPanResponderTerminationRequest` — return `false` to keep it (absent =
202
+ yield, as in RN).
203
+ - **`onPanResponderTerminate` is the undo hook.** It fires when the host cancels the touch sequence,
204
+ when a fresh touch-down arrives on a finger whose previous sequence never ended, and when the
205
+ responder yields to a challenger.
206
+ - **Single gesture.** The engine events carry no finger id, so extra fingers fold into ONE gesture:
207
+ `numberActiveTouches` counts them and the last to lift releases — both true in either flow. Flow A
208
+ additionally reports each join and leave through `onPanResponderStart`/`End`; Flow B has no
209
+ equivalent (next bullet).
210
+ - **Flow B compiles it too.** The AOT recognises `useRef(PanResponder.create({…})).current` and the
211
+ `{...pan.panHandlers}` spread as a whole and lowers them onto the same C responder system — the
212
+ should-set predicates become `er_responder_query_set` callbacks and the rest become responder event
213
+ handlers, with `g.dx`/`g.vx` reading the engine's own payload. No JS state machine is copied into the
214
+ generated C. Only `onPanResponderStart`/`End` — the two that fold EXTRA fingers into one gesture —
215
+ are Flow A only, and the AOT fails the build by name rather than dropping them. The watch-face demo's
216
+ swipe pager is the worked example: one source, both flows.
217
+
218
+ As promised above: the raw touch events carry the same fields the responder ones do — `e.dx`/`e.dy` from
219
+ touch-down and `e.vx`/`e.vy` in px per ms — so `onTouchEnd={e => e.vx > 0.4 && next()}` needs no
220
+ recognizer at all, in either flow.
221
+
222
+ The low-level responder props (`onStartShouldSetResponder`, `onResponderGrant`, …) are themselves
223
+ public on every component for gestures that don't fit the pan shape. Only RN's Android-specific
224
+ `onShouldBlockNativeResponder` is unsupported — holding the responder already blocks the native one
225
+ (the built-in adjustable-Arc drag deliberately still wins). Passing it, or a typo, warns.
226
+
130
227
  ## Build
131
228
 
132
229
  ```
@@ -170,15 +267,26 @@ file's basename.
170
267
  RGB565 images through its opaque copy fast path (no per-pixel blending).
171
268
  - **Fonts:** TTF/OTF → pre-rasterized `BitmapFont` glyphs (`bake-font.mjs`, via `opentype.js` + a
172
269
  pure-JS rasterizer). The engine has no runtime rasterizer, so the baker rasterizes **exactly the
173
- literal `fontSize` values the bundle uses**. Computed/dynamic sizes snap to the nearest baked size
174
- at runtime — pin them in `assets.config.js` if needed.
270
+ `fontSize` values the app uses**. Discovery folds constants, so a token-driven type scale bakes
271
+ what it means — `const TYPE = {body: 14, title: 22}` read as `fontSize: TYPE.title`, including a
272
+ scale handed to a component as a prop, and both arms of a `screen.width` ternary. A size that only
273
+ exists at runtime can't be seen; the build **warns** and names the expression, because at runtime
274
+ it silently snaps to the nearest baked size. Sizes the bake missed are warned about the same way,
275
+ against your fonts or against the built-in one — pin them in `assets.config.js` if you want a
276
+ different set. Only the glyphs you ask for are baked: printable ASCII, plus a named symbol set and
277
+ any per-app characters you add.
175
278
 
176
279
  Optional per-demo overrides live in `demos/<demo>/assets.config.js`:
177
280
 
178
281
  ```js
179
282
  export default {
180
283
  fonts: {
181
- Inter: { sizes: [14, 18, 24], bpp: 4, glyphs: 'common' }, // bpp 1|2|4|8 (4 default); glyphs: 'ascii'|'common'|'minimal'|'greek'|[codepoints]
284
+ Inter: {
285
+ sizes: [14, 18, 24], // bpp 1|2|4|8 (4 default)
286
+ bpp: 4,
287
+ glyphs: 'common', // 'ascii'|'minimal'|'common'|'greek'|'common-greek'|[codepoints]
288
+ extraGlyphs: '⌘⏻№', // this app's own characters, on top of `glyphs`
289
+ },
182
290
  },
183
291
  images: {
184
292
  bg: { format: 'rgb565' }, // 16-bit bake for opaque art; default is 'argb8888'
@@ -186,6 +294,21 @@ export default {
186
294
  };
187
295
  ```
188
296
 
297
+ `extraGlyphs` takes the characters themselves or their codepoints (`[0x2318, '⏻']`) — the named sets
298
+ can't anticipate every UI. Every bake path checks the app's text against what it baked and **warns
299
+ about characters that have no glyph**, since the engine silently substitutes `?` for them on the
300
+ device and nothing else tells you:
301
+
302
+ ```
303
+ embedded-react: 1 character(s) in the app's text have no baked glyph and will render as '?':
304
+ U+2318 '⌘' missing from Inter in "press ⌘S to save"
305
+ fix: assets.config.js → fonts: {Inter: {extraGlyphs: "⌘"}}
306
+ ```
307
+
308
+ The check reads string literals (and, for Flow B's unbundled JSX, element text), so text assembled
309
+ at runtime is out of its reach. It also says when the .ttf itself has no such glyph — then no config
310
+ change helps and the font is the thing to change.
311
+
189
312
  The engine's **built-in default font** (`engine/font/font_data.c`, the Inter fallback used by any
190
313
  text without a custom `fontFamily`) is generated by the same baker — regenerate it with
191
314
  `npm run build:builtin-font` (then re-run the engine text tests, as glyph metrics shift slightly).
@@ -275,6 +398,15 @@ anything that exercises the reconciler → engine pipeline → a `test/runtime/*
275
398
  tweens every node whose computed rect moved on the next commit (in C — no per-frame JS). `Presets`
276
399
  / `create` / `Types` / `Properties` and the `easeInEaseOut`/`linear`/`spring` shorthands. Covered
277
400
  by `layout-animation` unit + `layout-anim.runtime.test.jsx`.
401
+ - ✅ **`PanResponder` + the gesture responder system.** The full RN config minus only the
402
+ Android-specific `onShouldBlockNativeResponder`: should-set predicates (with `*Capture` variants),
403
+ grant / move / release / terminate / reject / termination-request, `onPanResponderStart`/`End` for
404
+ extra fingers, and a `gestureState` (`x0`/`y0`, `dx`/`dy`, `vx`/`vy`, `numberActiveTouches`) — wired
405
+ to the ENGINE's responder negotiation, so a granted pan blocks a ScrollView's auto-scroll and can
406
+ take a started scroll over. The low-level responder props are public on every component, and **Flow B
407
+ compiles the same config** — the AOT lowers it onto that C responder system, minus only
408
+ `onPanResponderStart`/`End`. Covered by `pan-responder` unit + `pan-responder.runtime.test.jsx` + the
409
+ AOT's `compile`/`cc-compile` PanResponder cases + the engine's `test_input` responder cases.
278
410
  - ✅ **Interpolate `extrapolate`.** `interpolate({ inputRange, outputRange, extrapolate })` supports
279
411
  `'extend'` (default) / `'clamp'` / `'identity'`, with per-end `extrapolateLeft`/`extrapolateRight`
280
412
  overrides. Math is engine-tested (`test_interpolate`); the bridge path by
@@ -287,6 +419,13 @@ anything that exercises the reconciler → engine pipeline → a `test/runtime/*
287
419
  it's just `useState`, so the same app code runs everywhere. `usePersistentState` is the underlying
288
420
  helper, also exported for explicit use. See
289
421
  [tools/simulator in the repo](https://github.com/TheMasterCoder007/embedded-react/blob/master/tools/simulator/README.md).
422
+ - ✅ **`<Dial>` — the native arc widget.** Dials, gauges and progress rings as ONE engine node
423
+ (`ER_NODE_ARC`) instead of a re-tessellated `<Svg>`: track + value indicator, optional backing band,
424
+ segment gaps, round caps, a circle / image / child-anchored knob, solid / conic / radial indicator paint.
425
+ `value` accepts an `Animated.Value` (bound natively — no JS per frame; each tick repaints only the swept
426
+ sliver), and `adjustable` gives built-in drag-to-set with the quantized value delivered to `onChange(v)`.
427
+ `<Switch onValueChange>` now also fires in Flow A (it was AOT-only). Covered by `dial.runtime.test.jsx`
428
+ and the engine's `test_arc`.
290
429
  - ✅ **`npx embedded-react dev`** — the WASM simulator runs your app in a browser with hot reload, from your
291
430
  own project directory, with the engine `.wasm` shipped prebuilt (no Emscripten for consumers). See above.
292
431
  - ✅ **`npm create embedded-react@latest my-app`** — scaffolds a fresh standalone project (a styled card with a