embedded-react 0.5.3 → 0.7.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.
@@ -0,0 +1,187 @@
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
+ // pack-app — build a Flow A config container (.erpkg) for an app entry, in memory.
18
+ //
19
+ // The shared core behind both `embedded-react build` (writes dist/app.erpkg) and the on-device
20
+ // hot-reload dev loop (streams the bytes straight to the device). Bundles the JSX with esbuild (same
21
+ // import-driven asset discovery as the dev/build paths), precompiles to QuickJS bytecode through the
22
+ // prebuilt sim wasm, bakes images/fonts into an ERPK pack, and serializes the ERCF container — all
23
+ // without touching disk, so the dev loop can rebuild on every save and hand the Buffer to the uploader.
24
+
25
+ import {createRequire} from 'node:module';
26
+ import {pathToFileURL} from 'node:url';
27
+ import {basename, resolve} from 'node:path';
28
+ import {existsSync, mkdirSync, readFileSync} from 'node:fs';
29
+ import {tmpdir} from 'node:os';
30
+
31
+ const require = createRequire(import.meta.url);
32
+
33
+ // QuickJS release the bytecode container targets — MUST match cli.mjs's QJS_TAG and the device loader.
34
+ const QJS_TAG = 'v0.15.0';
35
+
36
+ /**
37
+ * Bundle + compile + bake an app into an ERCF container Buffer.
38
+ *
39
+ * @param {object} o
40
+ * @param {string} o.entry App entry (index.jsx/tsx).
41
+ * @param {string} o.projectRoot Project cwd (for assets.config.js + persist scoping).
42
+ * @param {string} o.libSrc Path to the embedded-react library entry (aliased as 'embedded-react').
43
+ * @param {string[]} o.nodePaths esbuild nodePaths (package + project node_modules).
44
+ * @param {string} o.simDir Dir holding the prebuilt sim wasm (used to compile bytecode).
45
+ * @param {boolean} [o.persist] Apply the useState→persist transform (dev hot reload preserves state).
46
+ * @returns {Promise<{container: Buffer, bytecodeLen: number, assetsLen: number}>}
47
+ */
48
+ export async function packAppContainer({
49
+ entry,
50
+ projectRoot,
51
+ libSrc,
52
+ nodePaths,
53
+ simDir,
54
+ persist = false,
55
+ }) {
56
+ const esbuild = require('esbuild');
57
+ const {bakeImage} = await import('../assets/bake-image.mjs');
58
+ const {bakeFont} = await import('../assets/bake-font.mjs');
59
+ const {emitAssetPack} = await import('../assets/emit-pack.mjs');
60
+ const {emitContainer} = await import('../assets/emit-container.mjs');
61
+ const {registerSvgVectorLoader} = await import('../assets/svg-loader.mjs');
62
+ const {compileToBytecode} = await import('../qjsc-wasm.mjs');
63
+
64
+ const assetName = p => basename(p).replace(/\.[^.]+$/, '');
65
+ const images = new Map();
66
+ const fonts = new Map();
67
+
68
+ // Optionally apply the persist transform to the app's own source (not deps) so plain useState survives
69
+ // a live reload on-device, matching the simulator. The device must have install_persist=true.
70
+ let persistHooks = null;
71
+ if (persist) {
72
+ const {transformPersist, shouldPersist} =
73
+ await import('../persist-transform.mjs');
74
+ const {relative} = await import('node:path');
75
+ const projNorm = projectRoot.replace(/\\/g, '/');
76
+ persistHooks = {transformPersist, shouldPersist, relative, projNorm};
77
+ }
78
+
79
+ const assetPlugin = {
80
+ name: 'embedded-react-assets',
81
+ setup(b) {
82
+ if (persistHooks) {
83
+ b.onLoad({filter: /\.(jsx?|tsx?)$/}, a => {
84
+ const {transformPersist, shouldPersist, relative, projNorm} =
85
+ persistHooks;
86
+ if (!shouldPersist(a.path, projNorm)) return undefined;
87
+ try {
88
+ const loader = a.path.endsWith('.tsx')
89
+ ? 'tsx'
90
+ : a.path.endsWith('.ts')
91
+ ? 'ts'
92
+ : 'jsx';
93
+ return {
94
+ contents: transformPersist(
95
+ readFileSync(a.path, 'utf8'),
96
+ relative(projectRoot, a.path).replace(/\\/g, '/'),
97
+ ),
98
+ loader,
99
+ };
100
+ } catch (e) {
101
+ return {errors: [{text: `persist transform: ${e.message}`}]};
102
+ }
103
+ });
104
+ }
105
+ b.onLoad({filter: /\.(png|jpe?g|webp|gif|bmp)$/i}, a => {
106
+ const n = assetName(a.path);
107
+ images.set(n, a.path);
108
+ return {
109
+ contents: `module.exports = ${JSON.stringify(n)};`,
110
+ loader: 'js',
111
+ };
112
+ });
113
+ b.onLoad({filter: /\.(ttf|otf)$/i}, a => {
114
+ const f = assetName(a.path);
115
+ fonts.set(f, a.path);
116
+ return {
117
+ contents: `module.exports = ${JSON.stringify(f)};`,
118
+ loader: 'js',
119
+ };
120
+ });
121
+ registerSvgVectorLoader(b, (name, p) => images.set(name, p));
122
+ },
123
+ };
124
+
125
+ const tmp = resolve(tmpdir(), 'embedded-react-build');
126
+ mkdirSync(tmp, {recursive: true});
127
+ const bundlePath = resolve(tmp, 'app.bundle.js');
128
+ await esbuild.build({
129
+ entryPoints: [entry],
130
+ bundle: true,
131
+ format: 'iife',
132
+ outfile: bundlePath,
133
+ platform: 'neutral',
134
+ target: 'es2020',
135
+ jsx: 'automatic',
136
+ alias: {'embedded-react': libSrc},
137
+ nodePaths,
138
+ plugins: [assetPlugin],
139
+ define: {'process.env.NODE_ENV': '"production"'},
140
+ legalComments: 'none',
141
+ logLevel: 'silent',
142
+ });
143
+ const bundleSrc = readFileSync(bundlePath, 'utf8');
144
+
145
+ const bytecode = await compileToBytecode(bundleSrc, simDir);
146
+
147
+ const discoveredSizes = [
148
+ ...new Set(
149
+ [...bundleSrc.matchAll(/\bfontSize\s*:\s*(\d+(?:\.\d+)?)/g)].map(m =>
150
+ Math.round(Number(m[1])),
151
+ ),
152
+ ),
153
+ ].sort((a, b) => a - b);
154
+ let cfg = {};
155
+ const cp = resolve(projectRoot, 'assets.config.js');
156
+ if (existsSync(cp))
157
+ cfg = (await import(pathToFileURL(cp).href)).default || {};
158
+ const fontConfig = cfg.fonts || {};
159
+ const fontJobs = [...fonts.entries()].map(([family, path]) => {
160
+ const fc = fontConfig[family] || {};
161
+ return {
162
+ path,
163
+ family,
164
+ sizes: fc.sizes?.length
165
+ ? fc.sizes
166
+ : discoveredSizes.length
167
+ ? discoveredSizes
168
+ : [16],
169
+ bpp: fc.bpp ?? 4,
170
+ glyphs: fc.glyphs ?? 'ascii',
171
+ };
172
+ });
173
+ const imageJobs = [...images.entries()].map(([name, path]) => ({path, name}));
174
+ const bakedImages = imageJobs.map(bakeImage);
175
+ const bakedFonts = fontJobs.map(bakeFont);
176
+ const assetPack =
177
+ bakedImages.length || bakedFonts.length
178
+ ? emitAssetPack({images: bakedImages, fonts: bakedFonts})
179
+ : null;
180
+
181
+ const container = emitContainer({bytecode, assetPack, qjsTag: QJS_TAG});
182
+ return {
183
+ container,
184
+ bytecodeLen: bytecode.length,
185
+ assetsLen: assetPack ? assetPack.length : 0,
186
+ };
187
+ }
@@ -0,0 +1,311 @@
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
+ // pack-split — build the vendor/app SPLIT of a Flow A app, for incremental hot reload.
18
+ //
19
+ // The monolithic packer (pack-app.mjs) inlines react + react-reconciler + the embedded-react library
20
+ // together with the user's source into one ~1 MB bytecode blob. But the framework half never changes
21
+ // when you edit your app, so re-shipping and re-parsing it on every save is pure waste. pack-split cuts
22
+ // the bundle along the one seam that matters:
23
+ //
24
+ // • vendor chunk — react, react/jsx-runtime, and the embedded-react library. Built once. It registers
25
+ // those modules in `globalThis.__er_modules` and installs a `globalThis.require(id)` shim that the
26
+ // app chunk resolves its imports through. ~94% of the bytecode, and stable across edits.
27
+ // • app chunk — the user's own source, with react / react/jsx-runtime / embedded-react marked EXTERNAL
28
+ // so esbuild emits `require(...)` calls instead of inlining them. ~6% of the bytecode; the only thing
29
+ // that changes on a save.
30
+ //
31
+ // The flashed boot container carries BOTH (vendor section + app section); the device runs vendor first,
32
+ // then the app. A hot-reload frame carries only the app chunk — the device keeps the resident vendor and
33
+ // swaps just the app (a "soft reset"). Old monolithic containers still boot unchanged (emit-container's
34
+ // vendor section is optional), so this is backwards-compatible, and production behavior is identical.
35
+
36
+ import {createRequire} from 'node:module';
37
+ import {pathToFileURL} from 'node:url';
38
+ import {basename, dirname, resolve, relative} from 'node:path';
39
+ import {existsSync, readFileSync} from 'node:fs';
40
+
41
+ const require = createRequire(import.meta.url);
42
+
43
+ // QuickJS release the bytecode container targets — MUST match cli.mjs's QJS_TAG, pack-app.mjs, and the
44
+ // device loader.
45
+ const QJS_TAG = 'v0.15.0';
46
+
47
+ // The shared deps the app chunk resolve through the vendor registry instead of inlining.
48
+ export const VENDOR_EXTERNALS = [
49
+ 'react',
50
+ 'react/jsx-runtime',
51
+ 'embedded-react',
52
+ ];
53
+
54
+ const esbuildCommon = nodePaths => ({
55
+ bundle: true,
56
+ format: 'iife',
57
+ platform: 'neutral',
58
+ target: 'es2020',
59
+ jsx: 'automatic',
60
+ nodePaths,
61
+ define: {'process.env.NODE_ENV': '"production"'},
62
+ legalComments: 'none',
63
+ logLevel: 'silent',
64
+ write: false,
65
+ });
66
+
67
+ /**
68
+ * The vendor chunk's synthetic entry source: import the shared deps, register them in a runtime module
69
+ * registry, and install the `require()` shim the app chunk resolves through. esbuild's `__require` helper
70
+ * (emitted for the app chunk's external imports) finds this global `require` at runtime.
71
+ */
72
+ function vendorEntrySource() {
73
+ return `import * as React from 'react';
74
+ import * as JsxRuntime from 'react/jsx-runtime';
75
+ import * as EmbeddedReact from 'embedded-react';
76
+ const reg = (globalThis.__er_modules = globalThis.__er_modules || {});
77
+ reg['react'] = React;
78
+ reg['react/jsx-runtime'] = JsxRuntime;
79
+ reg['embedded-react'] = EmbeddedReact;
80
+ globalThis.require = function (id) {
81
+ const m = reg[id];
82
+ if (!m) throw new Error('embedded-react: module not in vendor registry: ' + id);
83
+ return m;
84
+ };
85
+ `;
86
+ }
87
+
88
+ /**
89
+ * Bundle the vendor chunk (react + reconciler + embedded-react lib) to a self-contained IIFE source.
90
+ *
91
+ * @param {object} o
92
+ * @param {string} o.libSrc embedded-react library entry (aliased as 'embedded-react').
93
+ * @param {string[]} o.nodePaths esbuild nodePaths (package + project node_modules).
94
+ * @returns {Promise<string>} The bundled JS source.
95
+ */
96
+ export async function bundleVendorSource({libSrc, nodePaths}) {
97
+ const esbuild = require('esbuild');
98
+ const out = await esbuild.build({
99
+ ...esbuildCommon(nodePaths),
100
+ stdin: {
101
+ contents: vendorEntrySource(),
102
+ resolveDir: dirname(libSrc),
103
+ sourcefile: 'vendor-entry.js',
104
+ loader: 'js',
105
+ },
106
+ alias: {'embedded-react': libSrc},
107
+ });
108
+ return out.outputFiles[0].text;
109
+ }
110
+
111
+ /**
112
+ * Build an asset-discovering esbuild plugin shared with the monolithic packer's behavior: image/font/svg
113
+ * imports become bare string names (the bytes live in the ERPK pack), and — when persist is on — the app's
114
+ * own source gets the useState→persist transform so state survives a live reload.
115
+ */
116
+ function makeAssetPlugin({images, fonts, persistHooks, projectRoot}) {
117
+ const assetName = p => basename(p).replace(/\.[^.]+$/, '');
118
+ return {
119
+ name: 'embedded-react-assets',
120
+ async setup(b) {
121
+ const {registerSvgVectorLoader} = await import(
122
+ '../assets/svg-loader.mjs'
123
+ );
124
+ if (persistHooks) {
125
+ b.onLoad({filter: /\.(jsx?|tsx?)$/}, a => {
126
+ const {transformPersist, shouldPersist, projNorm} = persistHooks;
127
+ if (!shouldPersist(a.path, projNorm)) return undefined;
128
+ try {
129
+ const loader = a.path.endsWith('.tsx')
130
+ ? 'tsx'
131
+ : a.path.endsWith('.ts')
132
+ ? 'ts'
133
+ : 'jsx';
134
+ return {
135
+ contents: transformPersist(
136
+ readFileSync(a.path, 'utf8'),
137
+ relative(projectRoot, a.path).replace(/\\/g, '/'),
138
+ ),
139
+ loader,
140
+ };
141
+ } catch (e) {
142
+ return {errors: [{text: `persist transform: ${e.message}`}]};
143
+ }
144
+ });
145
+ }
146
+ b.onLoad({filter: /\.(png|jpe?g|webp|gif|bmp)$/i}, a => {
147
+ const n = assetName(a.path);
148
+ images.set(n, a.path);
149
+ return {
150
+ contents: `module.exports = ${JSON.stringify(n)};`,
151
+ loader: 'js',
152
+ };
153
+ });
154
+ b.onLoad({filter: /\.(ttf|otf)$/i}, a => {
155
+ const f = assetName(a.path);
156
+ fonts.set(f, a.path);
157
+ return {
158
+ contents: `module.exports = ${JSON.stringify(f)};`,
159
+ loader: 'js',
160
+ };
161
+ });
162
+ registerSvgVectorLoader(b, (name, p) => images.set(name, p));
163
+ },
164
+ };
165
+ }
166
+
167
+ /**
168
+ * Bundle the app chunk: the user's entry with the shared deps marked external (resolved at runtime through
169
+ * the vendor registry). Returns the bundled source plus the discovered image/font maps for baking.
170
+ */
171
+ export async function bundleAppSource({
172
+ entry,
173
+ projectRoot,
174
+ nodePaths,
175
+ persist = false,
176
+ }) {
177
+ const esbuild = require('esbuild');
178
+ const images = new Map();
179
+ const fonts = new Map();
180
+
181
+ let persistHooks = null;
182
+ if (persist) {
183
+ const {transformPersist, shouldPersist} = await import(
184
+ '../persist-transform.mjs'
185
+ );
186
+ persistHooks = {
187
+ transformPersist,
188
+ shouldPersist,
189
+ projNorm: projectRoot.replace(/\\/g, '/'),
190
+ };
191
+ }
192
+
193
+ const out = await esbuild.build({
194
+ ...esbuildCommon(nodePaths),
195
+ entryPoints: [entry],
196
+ external: VENDOR_EXTERNALS,
197
+ plugins: [makeAssetPlugin({images, fonts, persistHooks, projectRoot})],
198
+ });
199
+ return {source: out.outputFiles[0].text, images, fonts};
200
+ }
201
+
202
+ /** Bake the discovered images/fonts into an ERPK asset pack (or null if there are none). */
203
+ async function bakeAssets({images, fonts, source, projectRoot}) {
204
+ const {bakeImage} = await import('../assets/bake-image.mjs');
205
+ const {bakeFont} = await import('../assets/bake-font.mjs');
206
+ const {emitAssetPack} = await import('../assets/emit-pack.mjs');
207
+
208
+ const discoveredSizes = [
209
+ ...new Set(
210
+ [...source.matchAll(/\bfontSize\s*:\s*(\d+(?:\.\d+)?)/g)].map(m =>
211
+ Math.round(Number(m[1])),
212
+ ),
213
+ ),
214
+ ].sort((a, b) => a - b);
215
+
216
+ let cfg = {};
217
+ const cp = resolve(projectRoot, 'assets.config.js');
218
+ if (existsSync(cp))
219
+ cfg = (await import(pathToFileURL(cp).href)).default || {};
220
+ const fontConfig = cfg.fonts || {};
221
+
222
+ const fontJobs = [...fonts.entries()].map(([family, path]) => {
223
+ const fc = fontConfig[family] || {};
224
+ return {
225
+ path,
226
+ family,
227
+ sizes: fc.sizes?.length
228
+ ? fc.sizes
229
+ : discoveredSizes.length
230
+ ? discoveredSizes
231
+ : [16],
232
+ bpp: fc.bpp ?? 4,
233
+ glyphs: fc.glyphs ?? 'ascii',
234
+ };
235
+ });
236
+ const imageJobs = [...images.entries()].map(([name, path]) => ({path, name}));
237
+ const bakedImages = imageJobs.map(bakeImage);
238
+ const bakedFonts = fontJobs.map(bakeFont);
239
+ return bakedImages.length || bakedFonts.length
240
+ ? emitAssetPack({images: bakedImages, fonts: bakedFonts})
241
+ : null;
242
+ }
243
+
244
+ /**
245
+ * Compile the vendor chunk to a QuickJS bytecode blob. Built once per dev session (it changes only when a
246
+ * dependency changes), so the per-edit reload never re-ships it.
247
+ *
248
+ * @returns {Promise<{bytecode: Buffer, bytecodeLen: number}>}
249
+ */
250
+ export async function packVendor({libSrc, nodePaths, simDir}) {
251
+ const {compileToBytecode} = await import('../qjsc-wasm.mjs');
252
+ const source = await bundleVendorSource({libSrc, nodePaths});
253
+ const bytecode = await compileToBytecode(source, simDir);
254
+ return {bytecode, bytecodeLen: bytecode.length};
255
+ }
256
+
257
+ /**
258
+ * Compile the app chunk to a QuickJS bytecode blob and bake its assets. This is the only thing rebuilt on
259
+ * each save — and the only thing a hot-reload frame carries.
260
+ *
261
+ * @returns {Promise<{bytecode: Buffer, assetPack: Buffer|null, bytecodeLen: number, assetsLen: number}>}
262
+ */
263
+ export async function packApp({
264
+ entry,
265
+ projectRoot,
266
+ libSrc,
267
+ nodePaths,
268
+ simDir,
269
+ persist = false,
270
+ }) {
271
+ const {compileToBytecode} = await import('../qjsc-wasm.mjs');
272
+ const {source, images, fonts} = await bundleAppSource({
273
+ entry,
274
+ projectRoot,
275
+ nodePaths,
276
+ persist,
277
+ });
278
+ const bytecode = await compileToBytecode(source, simDir);
279
+ const assetPack = await bakeAssets({images, fonts, source, projectRoot});
280
+ return {
281
+ bytecode,
282
+ assetPack,
283
+ bytecodeLen: bytecode.length,
284
+ assetsLen: assetPack ? assetPack.length : 0,
285
+ };
286
+ }
287
+
288
+ /**
289
+ * Assemble the flashed BOOT container: vendor + app + assets in one ERCF. The device runs vendor first
290
+ * (installs the registry + require shim), registers assets, then runs the app. Used by `embedded-react
291
+ * build` so the same firmware/artifact serves both production and hot reload.
292
+ */
293
+ export function emitBootContainer({vendorBytecode, appBytecode, assetPack}) {
294
+ return emit({bytecode: appBytecode, vendorBytecode, assetPack});
295
+ }
296
+
297
+ /**
298
+ * Assemble a hot-reload APP frame: the app chunk + its assets, NO vendor. The device keeps the resident
299
+ * vendor and swaps just the app (soft reset). This is the ~64 KB that travels on each save.
300
+ */
301
+ export function emitAppFrame({appBytecode, assetPack}) {
302
+ return emit({bytecode: appBytecode, assetPack});
303
+ }
304
+
305
+ // emitBootContainer/emitAppFrame are async (emit() dynamically imports the emitter) — callers await them.
306
+ async function emit(opts) {
307
+ const {emitContainer} = await import('../assets/emit-container.mjs');
308
+ return emitContainer({...opts, qjsTag: QJS_TAG});
309
+ }
310
+
311
+ export {QJS_TAG};
@@ -0,0 +1,172 @@
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
+ // ERHR — the embedded-react hot-reload transport frame.
18
+ //
19
+ // One self-describing frame that carries an .erpkg (ERCF container) over a byte stream — USB-CDC, a
20
+ // USB-Serial-JTAG console, or a UART. It is the *transport* envelope, a layer ABOVE the ERCF container:
21
+ // ERCF's own CRC proves the config is internally consistent; this frame's CRC proves the bytes arrived
22
+ // intact over the wire (a transfer can truncate/corrupt the ERCF header itself, which ERCF's body CRC
23
+ // does not cover). The magic + length + CRC also let the firmware parser *resync*: on a shared in-band
24
+ // channel (classic ESP32 with one UART-bridge port) the device's own log text is interleaved with
25
+ // uploads, so the receiver scans for "ERHR" and validates before touching the runtime.
26
+ //
27
+ // Little-endian (matches the LE hosts). Header is 16 bytes:
28
+ //
29
+ // magic "ERHR" (4 bytes)
30
+ // proto_version u8 = 1
31
+ // msg_type u8 (1 = LOAD_CONTAINER)
32
+ // flags u16 = 0 (reserved)
33
+ // payload_len u32 — bytes of .erpkg that follow the header
34
+ // payload_crc u32 — CRC-32/IEEE over the payload (same polynomial as ERCF / the C loader)
35
+ // payload bytes[payload_len] — the .erpkg (ERCF container)
36
+ //
37
+ // The mirror of this lives in the firmware parser (bridges/quickjs/er_hotreload.c); the two MUST stay
38
+ // byte-compatible. crc32 is shared with emit-container.mjs so all three CRCs are the one algorithm.
39
+
40
+ import {crc32} from '../assets/emit-container.mjs';
41
+
42
+ export const ERHR_MAGIC = 'ERHR';
43
+ export const ERHR_PROTO_VERSION = 1;
44
+ export const ERHR_HEADER_SIZE = 16;
45
+
46
+ /** Frame message types (room to grow: ping/ack/reset later without a version bump). */
47
+ export const MSG_LOAD_CONTAINER = 1;
48
+
49
+ /**
50
+ * Encodes an .erpkg into an ERHR transport frame ready to write to the device's byte stream.
51
+ *
52
+ * @param {Buffer|Uint8Array} erpkg The ERCF container bytes (from emitContainer).
53
+ * @param {object} [opts]
54
+ * @param {number} [opts.type] Message type (default MSG_LOAD_CONTAINER).
55
+ * @returns {Buffer} The framed bytes (16-byte header + payload).
56
+ */
57
+ export function encodeFrame(erpkg, {type = MSG_LOAD_CONTAINER} = {}) {
58
+ if (!erpkg || !erpkg.length)
59
+ throw new Error('encodeFrame: payload (.erpkg) is required');
60
+ const payload = Buffer.from(erpkg);
61
+ const header = Buffer.alloc(ERHR_HEADER_SIZE);
62
+ header.write(ERHR_MAGIC, 0, 'ascii');
63
+ header.writeUInt8(ERHR_PROTO_VERSION, 4);
64
+ header.writeUInt8(type & 0xff, 5);
65
+ header.writeUInt16LE(0, 6); // flags (reserved)
66
+ header.writeUInt32LE(payload.length >>> 0, 8);
67
+ header.writeUInt32LE(crc32(payload), 12);
68
+ return Buffer.concat([header, payload]);
69
+ }
70
+
71
+ /**
72
+ * A streaming decoder mirroring the firmware parser: feed it arbitrary chunks of a byte stream and it
73
+ * scans for the ERHR magic, parses the header, collects the payload, and verifies the CRC. Used by the
74
+ * host's own tests (to prove host/firmware agreement) and usable for a loopback/echo device.
75
+ *
76
+ * Emits via the callbacks passed to the constructor; tolerant of leading/interleaved non-frame bytes.
77
+ */
78
+ export class FrameDecoder {
79
+ /**
80
+ * @param {object} handlers
81
+ * @param {(payload: Buffer, meta: {type: number}) => void} [handlers.onFrame] A complete, CRC-valid frame.
82
+ * @param {(reason: string) => void} [handlers.onError] A framed payload failed validation.
83
+ */
84
+ constructor({onFrame, onError, maxPayload = 32 * 1024 * 1024} = {}) {
85
+ this.onFrame = onFrame || (() => {});
86
+ this.onError = onError || (() => {});
87
+ this.maxPayload = maxPayload; // guard against a coincidental "ERHR" in noise claiming a huge length
88
+ this._reset();
89
+ }
90
+
91
+ _reset() {
92
+ this._state = 'scan'; // scan magic → header → payload
93
+ this._window = Buffer.alloc(4); // rolling 4-byte window for magic resync
94
+ this._winLen = 0;
95
+ this._header = Buffer.alloc(ERHR_HEADER_SIZE);
96
+ this._headerGot = 4; // magic already in _header once matched
97
+ this._payloadLen = 0;
98
+ this._payloadCrc = 0;
99
+ this._type = 0;
100
+ this._payload = null;
101
+ this._payloadGot = 0;
102
+ }
103
+
104
+ /** Feed a chunk of received bytes. May complete zero, one, or several frames. */
105
+ push(chunk) {
106
+ const data = Buffer.from(chunk);
107
+ for (let i = 0; i < data.length; i++) this._byte(data[i]);
108
+ }
109
+
110
+ _byte(b) {
111
+ if (this._state === 'scan') {
112
+ // Slide the byte into a 4-byte window; a full match transitions to header collection. This
113
+ // naturally handles partial matches and overlaps without backtracking.
114
+ if (this._winLen < 4) {
115
+ this._window[this._winLen++] = b;
116
+ } else {
117
+ this._window.copyWithin(0, 1);
118
+ this._window[3] = b;
119
+ }
120
+ if (this._winLen === 4 && this._window.toString('ascii') === ERHR_MAGIC) {
121
+ this._window.copy(this._header, 0, 0, 4);
122
+ this._headerGot = 4;
123
+ this._winLen = 0;
124
+ this._state = 'header';
125
+ }
126
+ return;
127
+ }
128
+ if (this._state === 'header') {
129
+ this._header[this._headerGot++] = b;
130
+ if (this._headerGot < ERHR_HEADER_SIZE) return;
131
+ const version = this._header.readUInt8(4);
132
+ this._type = this._header.readUInt8(5);
133
+ this._payloadLen = this._header.readUInt32LE(8);
134
+ this._payloadCrc = this._header.readUInt32LE(12);
135
+ if (version !== ERHR_PROTO_VERSION) {
136
+ this.onError(`unsupported protocol version ${version}`);
137
+ this._reset();
138
+ return;
139
+ }
140
+ if (this._payloadLen === 0) {
141
+ this.onError('empty payload');
142
+ this._reset();
143
+ return;
144
+ }
145
+ if (this._payloadLen > this.maxPayload) {
146
+ // Almost certainly a false magic in noise — drop it and keep scanning, don't allocate.
147
+ this.onError(`payload too large (${this._payloadLen} bytes)`);
148
+ this._reset();
149
+ return;
150
+ }
151
+ this._payload = Buffer.alloc(this._payloadLen);
152
+ this._payloadGot = 0;
153
+ this._state = 'payload';
154
+ return;
155
+ }
156
+ // payload
157
+ this._payload[this._payloadGot++] = b;
158
+ if (this._payloadGot < this._payloadLen) return;
159
+ const got = crc32(this._payload);
160
+ if (got !== this._payloadCrc) {
161
+ this.onError(
162
+ `payload CRC mismatch (got ${got.toString(16)}, want ${this._payloadCrc.toString(16)})`,
163
+ );
164
+ this._reset();
165
+ return;
166
+ }
167
+ const payload = this._payload;
168
+ const type = this._type;
169
+ this._reset();
170
+ this.onFrame(payload, {type});
171
+ }
172
+ }