embedded-react 0.20.0 → 0.21.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.
Files changed (74) hide show
  1. package/NOTICE +5 -0
  2. package/README.md +1 -0
  3. package/aot/app-file-loader.mjs +116 -0
  4. package/aot/compile.mjs +16 -46
  5. package/aot/compiler/animations.mjs +299 -57
  6. package/aot/compiler/boot.mjs +27 -2
  7. package/aot/compiler/check.mjs +61 -9
  8. package/aot/compiler/collect.mjs +516 -136
  9. package/aot/compiler/contexts.mjs +391 -0
  10. package/aot/compiler/control-flow.mjs +276 -117
  11. package/aot/compiler/custom-hooks.mjs +686 -0
  12. package/aot/compiler/elements/button.mjs +182 -0
  13. package/aot/compiler/elements/image-background.mjs +76 -0
  14. package/aot/compiler/elements/image.mjs +2 -1
  15. package/aot/compiler/elements/props.mjs +38 -3
  16. package/aot/compiler/elements/rewrite.mjs +118 -0
  17. package/aot/compiler/elements/section-list.mjs +370 -0
  18. package/aot/compiler/expressions.mjs +1351 -97
  19. package/aot/compiler/handlers.mjs +1761 -365
  20. package/aot/compiler/helper-values.mjs +312 -0
  21. package/aot/compiler/ir/nodes.mjs +40 -1
  22. package/aot/compiler/ir/reads.mjs +206 -5
  23. package/aot/compiler/ir/text.mjs +5 -1
  24. package/aot/compiler/ir/types.mjs +12 -0
  25. package/aot/compiler/kept-states.mjs +177 -0
  26. package/aot/compiler/list-items.mjs +226 -0
  27. package/aot/compiler/list-order.mjs +586 -0
  28. package/aot/compiler/list-split.mjs +259 -0
  29. package/aot/compiler/loops.mjs +582 -0
  30. package/aot/compiler/lower.mjs +191 -53
  31. package/aot/compiler/native-files.mjs +439 -0
  32. package/aot/compiler/native-header.mjs +335 -0
  33. package/aot/compiler/native-modules.mjs +1173 -0
  34. package/aot/compiler/nodes.mjs +28 -22
  35. package/aot/compiler/options.mjs +3 -2
  36. package/aot/compiler/out.mjs +14 -1
  37. package/aot/compiler/package/animations.mjs +133 -23
  38. package/aot/compiler/package/assemble.mjs +2 -4
  39. package/aot/compiler/package/bytecode.mjs +37 -8
  40. package/aot/compiler/package/checks.mjs +4 -0
  41. package/aot/compiler/package/codegen.mjs +870 -31
  42. package/aot/compiler/package/enums.mjs +10 -0
  43. package/aot/compiler/package/format.mjs +12 -1
  44. package/aot/compiler/package/lower.mjs +658 -161
  45. package/aot/compiler/package/string-caps.mjs +515 -0
  46. package/aot/compiler/package/tables.mjs +24 -0
  47. package/aot/compiler/package/writer.mjs +22 -0
  48. package/aot/compiler/parse.mjs +3 -1
  49. package/aot/compiler/record-shapes.mjs +246 -0
  50. package/aot/compiler/records.mjs +654 -0
  51. package/aot/compiler/reducers.mjs +272 -0
  52. package/aot/compiler/static-eval.mjs +315 -7
  53. package/aot/compiler/style-text.mjs +18 -3
  54. package/aot/compiler/svg.mjs +7 -4
  55. package/aot/compiler/switch-cases.mjs +198 -0
  56. package/aot/compiler/tagged-records.mjs +450 -0
  57. package/aot/compiler/typing.mjs +307 -0
  58. package/aot/compiler/updaters.mjs +320 -0
  59. package/aot/compiler/window-dimensions.mjs +94 -0
  60. package/aot/compiler/worked-values.mjs +319 -0
  61. package/aot/demo-file.mjs +30 -0
  62. package/aot/style-map.mjs +50 -2
  63. package/build.mjs +9 -1
  64. package/cli.mjs +44 -1
  65. package/hotreload/pack-split.mjs +29 -40
  66. package/pack-container.mjs +9 -1
  67. package/package.json +1 -1
  68. package/sim/embedded-react.wasm +0 -0
  69. package/sim-server.mjs +22 -22
  70. package/src/embedded-react/Dimensions.js +37 -0
  71. package/src/embedded-react/SectionList.js +1 -3
  72. package/src/embedded-react/index.d.ts +83 -3
  73. package/src/embedded-react/index.js +2 -0
  74. package/src/embedded-react/nativeModule.js +462 -0
package/NOTICE CHANGED
@@ -47,6 +47,11 @@ under their own respective licenses and copyrights:
47
47
  Licensed under the MIT License.
48
48
  Used by the Flow A bridge to drive the native engine.
49
49
 
50
+ The float-to-text routine in runtime/erb_float.c follows the Ryu algorithm
51
+ (Ulf Adams, "Ryu: Fast Float-to-String Conversion", PLDI 2018) and the
52
+ structure of its reference implementation (https://github.com/ulfjack/ryu),
53
+ Copyright 2018 Ulf Adams, licensed under the Apache License, Version 2.0.
54
+
50
55
  The embedded-react public API (e.g. the View / Text / Pressable / Animated /
51
56
  StyleSheet modules under packages/embedded-react/src/embedded-react/) is an original,
52
57
  independent reimplementation inspired by the React Native API surface. It is not
package/README.md CHANGED
@@ -43,6 +43,7 @@ The package is the React Native analog: hooks come from `react`, everything else
43
43
  | `npx embedded-react build --aot --bake` | A Flow B package as a C array, `dist/app.erpkg.c`, to link into firmware with no spare partition |
44
44
  | `npx embedded-react flash --board NAME` | Writes `dist/app.erpkg` to the board's staging slot, through `esptool` or `picotool`. The last good package stays until the new one passes verification |
45
45
  | `npx embedded-react pack --board NAME` | Writes a slot's image to a file, as a UF2 on the RP2040, for a factory line or a board that isn't attached |
46
+ | `npx embedded-react native-header PACKAGE --out DIR` | Writes a C header for each native module a device package or `.ts` file declares, for the firmware to build against |
46
47
  | `npx embedded-react export` | A self-contained static copy of the simulator with your app, for any static host |
47
48
 
48
49
  ## Where to read more
@@ -0,0 +1,116 @@
1
+ /*
2
+ * Copyright 2026 Cory Lamming
3
+ *
4
+ * Licensed under the Apache License, Version 2.0 (the "License");
5
+ * you may not use this file except in compliance with the License.
6
+ * You may obtain a copy of the License at
7
+ *
8
+ * http://www.apache.org/licenses/LICENSE-2.0
9
+ *
10
+ * Unless required by applicable law or agreed to in writing, software
11
+ * distributed under the License is distributed on an "AS IS" BASIS,
12
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ * See the License for the specific language governing permissions and
14
+ * limitations under the License.
15
+ */
16
+ /*
17
+ * Flow A's esbuild loader for an app's own files. It gives each nativeModule() call its methods' signatures, which
18
+ * the bundle's erased types can't, and in the simulators its mock, then runs the bundler's own transform when it has
19
+ * one. esbuild runs one onLoad per file, so a bundler that transforms the app's files calls this from its own, and
20
+ * loadDependencyFile for every other file, since a package may declare native modules too.
21
+ */
22
+ /*----------------------------------------------------------------------------------------------------------------------
23
+ - Imports
24
+ ---------------------------------------------------------------------------------------------------------------------*/
25
+ import { existsSync, readFileSync } from 'node:fs';
26
+ import { dirname, relative } from 'node:path';
27
+ /*----------------------------------------------------------------------------------------------------------------------
28
+ - Implementation
29
+ ---------------------------------------------------------------------------------------------------------------------*/
30
+ /**
31
+ * esbuild's loader for one of the app's own files.
32
+ *
33
+ * @param path The file.
34
+ * @param transform The bundler's own transform, if it has one.
35
+ * @param options `mocks` for the simulators: each native module runs its mock (`sensors.mock.ts` beside its
36
+ * interface) instead of the firmware's.
37
+ *
38
+ * @returns What esbuild loads, or undefined to let esbuild read the file itself.
39
+ */
40
+ export async function loadAppFile(path, transform, options = {}) {
41
+ const source = readFileSync(path, 'utf8');
42
+ let contents = source;
43
+ // A mock added later rebuilds the app.
44
+ const watchFiles = [];
45
+ if (/\bnativeModule\b/.test(source)) {
46
+ const { addNativeSignatures } = await import('./compiler/native-modules.mjs');
47
+ const { nativeMockFiles, readNativeFiles } = await import('./compiler/native-files.mjs');
48
+ try {
49
+ let mocks;
50
+ if (options.mocks) {
51
+ mocks = new Map();
52
+ for (const [name, candidates] of nativeMockFiles(source, dirname(path))) {
53
+ watchFiles.push(...candidates);
54
+ const found = candidates.find(candidate => existsSync(candidate));
55
+ mocks.set(name, found
56
+ ? './' + relative(dirname(path), found).replace(/\\/g, '/')
57
+ : null);
58
+ }
59
+ }
60
+ contents = addNativeSignatures(source, readNativeFiles(source, dirname(path)), mocks);
61
+ }
62
+ catch (error) {
63
+ const aotError = error;
64
+ // A syntax error is esbuild's to report.
65
+ if (aotError.code !== 'BABEL_PARSER_SYNTAX_ERROR') {
66
+ if (!aotError.message?.startsWith('AOT:'))
67
+ throw error;
68
+ return {
69
+ errors: [
70
+ {
71
+ text: aotError.message.replace(/^AOT: /, ''),
72
+ location: aotError.aotLoc
73
+ ? {
74
+ file: path,
75
+ line: aotError.aotLoc.line,
76
+ column: aotError.aotLoc.column,
77
+ }
78
+ : null,
79
+ notes: aotError.aotHint ? [{ text: aotError.aotHint }] : [],
80
+ },
81
+ ],
82
+ };
83
+ }
84
+ }
85
+ }
86
+ if (transform) {
87
+ contents = transform(contents);
88
+ }
89
+ else if (contents === source) {
90
+ return undefined;
91
+ }
92
+ return {
93
+ contents,
94
+ loader: /\.[cm]?tsx$/.test(path)
95
+ ? 'tsx'
96
+ : /\.[cm]?ts$/.test(path)
97
+ ? 'ts'
98
+ : 'jsx',
99
+ ...(watchFiles.length ? { watchFiles } : {}),
100
+ };
101
+ }
102
+ /**
103
+ * esbuild's loader for a file that isn't the app's own: a package's .ts file that declares native modules gets their
104
+ * signatures, and in the simulators their mocks, as the app's own files do.
105
+ *
106
+ * @param path The file.
107
+ * @param options `mocks` for the simulators (see loadAppFile).
108
+ *
109
+ * @returns What esbuild loads, or undefined to let esbuild read the file itself.
110
+ */
111
+ export async function loadDependencyFile(path, options = {}) {
112
+ if (!/\.[cm]?tsx?$/.test(path) || /\.d\.[cm]?ts$/.test(path)) {
113
+ return undefined;
114
+ }
115
+ return loadAppFile(path, undefined, options);
116
+ }
package/aot/compile.mjs CHANGED
@@ -39,7 +39,7 @@
39
39
  * inline JSX), and the CLI at the bottom reads a demo's App.jsx and writes dist/app.erpkg. The
40
40
  * compiler itself lives in compiler/, one module per stage. The pipeline: parse the App.jsx → collect
41
41
  * the module's component, state, hooks & refs → lower each piece (expressions, styles/text, handlers,
42
- * nodes) → write the lowered app as a package.
42
+ * nodes) → widen the slots that hold 64 bits and type the app → check it → write it as a package.
43
43
  *
44
44
  * compiler/options.mts resolveOptions — screen size + buffer caps, from opts, then ER_AOT_*
45
45
  * compiler/types.mts the types the stages share (Env, StatementContext, state/ref records)
@@ -59,8 +59,10 @@
59
59
  * compiler/nodes.mts emitNode — the element dispatcher + the generic host node
60
60
  * compiler/elements/*.mts typed components: Dial / Switch / TextInput / Modal / FlatList / …
61
61
  * compiler/keyboard.mts setKeyboardConfig({...}) → the keyboard config
62
+ * compiler/native-modules.mts nativeModule() declarations and their interfaces → native calls
62
63
  * compiler/lower.mts lowerApp — run the stages above over the parsed app
63
- * compiler/check.mts the check pass — the values lowering recorded, checked in order
64
+ * compiler/typing.mts what lowering holds in place of a typed value, for the typing pass to fill in
65
+ * compiler/check.mts the typing and check passes — what lowering recorded, run in order
64
66
  * compiler/package/*.mts the package backend: the IR as a Flow B program, its container and report
65
67
  *
66
68
  * The compiler is TypeScript (.mts), which Node runs by stripping the types. tools/stage-npm-package.mjs
@@ -78,7 +80,9 @@ import { analyzeFontSizes, warnFontSizes } from '../assets/font-sizes.mjs';
78
80
  import { formatAotError } from './compiler/diagnostics.mjs';
79
81
  import { resolveOptions } from './compiler/options.mjs';
80
82
  import { bakeSvgArtifacts } from './compiler/collect.mjs';
81
- import { inferWideSlots, sameSlotWidths } from './compiler/expressions.mjs';
83
+ import { nativeHeaders } from './compiler/native-header.mjs';
84
+ import { readModuleFile, readNativeFiles } from './compiler/native-files.mjs';
85
+ import { demoFile } from './demo-file.mjs';
82
86
  import { assemblePackage, bakePackage, compilePanel, packPackage, resourceReport, } from './compiler/package/assemble.mjs';
83
87
  import { MAX_LAYOUTS, runCheck } from './compiler/package/checks.mjs';
84
88
  import { SizeSearch } from './compiler/package/layouts.mjs';
@@ -94,42 +98,7 @@ const FIRST_SIZE = { width: 240, height: 320 };
94
98
  /*----------------------------------------------------------------------------------------------------------------------
95
99
  - Implementation
96
100
  ---------------------------------------------------------------------------------------------------------------------*/
97
- export { bakePackage, bakeSvgArtifacts, packPackage, resourceReport };
98
- /**
99
- * A state or ref slot is typed from its initial value, so `useState(0)` is an int until a setter stores
100
- * Date.now() in it. A compile records every value stored into an int slot (environment.stores), and the typing pass
101
- * infers from them which slots have to hold 64 bits, following a timestamp through every slot it reaches; the
102
- * app is then compiled again with those slots widened, so every read of a slot sees its final type.
103
- *
104
- * @param compileOnce One compile with the given slots widened, recording the values stored into int slots.
105
- *
106
- * @returns What the last compile produced.
107
- */
108
- function compileWidened(compileOnce) {
109
- // The slots found so far that need 64 bits; every pass compiles with all of them widened.
110
- let wide = new Map();
111
- for (;;) {
112
- // Run one pass, holding on to its error instead of throwing it straight away.
113
- const stores = [];
114
- let result;
115
- let error;
116
- try {
117
- result = compileOnce(wide, stores);
118
- }
119
- catch (caught) {
120
- error = caught;
121
- }
122
- // Stop once no slot is inferred to widen; a failed pass with new ones may have failed on a narrow type.
123
- const inferred = inferWideSlots(stores, wide);
124
- if (sameSlotWidths(inferred, wide)) {
125
- if (error) {
126
- throw error;
127
- }
128
- return result;
129
- }
130
- wide = inferred;
131
- }
132
- }
101
+ export { bakePackage, bakeSvgArtifacts, nativeHeaders, packPackage, readModuleFile, readNativeFiles, resourceReport, };
133
102
  /**
134
103
  * Runs a compilation, annotating an AOT error with file:line:col + a source code-frame (+ hint) so the failure
135
104
  * points at the exact unsupported construct.
@@ -138,13 +107,13 @@ function compileWidened(compileOnce) {
138
107
  * @param demo Demo name, for the file the error names when opts has none.
139
108
  * @param options The compile's options.
140
109
  * @param resolved The same options, resolved.
141
- * @param compileOnce One compile, as compileWidened runs it.
110
+ * @param compile The compile.
142
111
  *
143
112
  * @returns What the compile produced.
144
113
  */
145
- function compileLocated(source, demo, options, resolved, compileOnce) {
114
+ function compileLocated(source, demo, options, resolved, compile) {
146
115
  try {
147
- return compileWidened(compileOnce);
116
+ return compile();
148
117
  }
149
118
  catch (error) {
150
119
  // Point an AOT error at its place in the source; any other error passes through unchanged.
@@ -220,7 +189,7 @@ export function compilePackage(source, demo = 'app', compileOptions = {}) {
220
189
  const resolved = searched
221
190
  ? { ...options, screenFrom: 'search' }
222
191
  : options;
223
- panels.push(compileLocated(source, demo, compileOptions, resolved, (wide, stores) => compilePanel(source, resolved, wide, stores)));
192
+ panels.push(compileLocated(source, demo, compileOptions, resolved, () => compilePanel(source, resolved)));
224
193
  };
225
194
  const requested = requestedScreens(compileOptions);
226
195
  if (requested) {
@@ -264,7 +233,7 @@ export function compilePackage(source, demo = 'app', compileOptions = {}) {
264
233
  // CLI entry (`node aot/compile.mts [demo]`), only when run directly: compile a demo into dist/app.erpkg.
265
234
  if (process.argv[1] &&
266
235
  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
267
- // Find the demo's App.jsx, listing the available demos when it is missing.
236
+ // Find the demo's App.tsx or App.jsx, listing the available demos when it is missing.
268
237
  const commandArguments = process.argv.slice(2);
269
238
  const screenAt = commandArguments.indexOf('--screen');
270
239
  const screens = screenAt < 0
@@ -280,7 +249,7 @@ if (process.argv[1] &&
280
249
  const demo = commandArguments.find((argument, index) => !argument.startsWith('--') && (screenAt < 0 || index !== screenAt + 1)) ||
281
250
  process.env.DEMO ||
282
251
  'thermostat';
283
- const appPath = resolve(demosDirectory, demo, 'App.jsx');
252
+ const appPath = demoFile(resolve(demosDirectory, demo), 'App');
284
253
  const availableDemos = existsSync(demosDirectory)
285
254
  ? readdirSync(demosDirectory, { withFileTypes: true })
286
255
  .filter(entry => entry.isDirectory())
@@ -295,8 +264,9 @@ if (process.argv[1] &&
295
264
  let result;
296
265
  try {
297
266
  result = compilePackage(source, demo, {
298
- filename: resolve(demosDirectory, demo, 'App.jsx'),
267
+ filename: appPath,
299
268
  svgArtifacts: await bakeSvgArtifacts(source, resolve(demosDirectory, demo)),
269
+ nativeFiles: readNativeFiles(source, resolve(demosDirectory, demo)),
300
270
  screen: screens?.[0],
301
271
  screens,
302
272
  });