embedded-react 0.5.2 → 0.6.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/assets/emit-container.mjs +16 -5
- package/cli.mjs +188 -104
- package/hotreload/dev-device.mjs +260 -0
- package/hotreload/pack-app.mjs +187 -0
- package/hotreload/pack-split.mjs +311 -0
- package/hotreload/protocol.mjs +172 -0
- package/hotreload/uploader.mjs +200 -0
- package/hotreload/watch-tree.mjs +103 -0
- package/package.json +6 -1
- package/sim/embedded-react.wasm +0 -0
- package/sim-server.mjs +2 -1
- package/src/embedded-react/AppRegistry.js +10 -2
|
@@ -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
|
+
}
|