@crossworks/app-build 0.300.140 → 0.400.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,248 @@
1
+ /**
2
+ * Builds the CANVAS runtime: the vendored, pinned, offline library set a
3
+ * Present canvas imports (docs/proposals/canvas-files.md section 6.1). Served
4
+ * by the brain from `/canvas-runtime/`, never from a CDN: some boxes block
5
+ * egress, a CDN would widen the frame CSP to third-party script hosts, and
6
+ * versions would drift.
7
+ *
8
+ * Each library becomes ONE content-hashed ESM file (`<entry>-<hash>.js`), so a
9
+ * canvas frame's import map is an address book only: the browser fetches a
10
+ * library when the canvas imports it, then caches it for good. Three.js addons
11
+ * import `three` through the same map, so a scene and its controls share one
12
+ * Three. Plotly ships only a classic browser build: it is copied as is, and a
13
+ * canvas loads it with a `<script src>`. reveal.js brings its stylesheet and
14
+ * themes. KaTeX's stylesheet and fonts already ride `/share-runtime/katex/`.
15
+ *
16
+ * Output: the files plus `manifest.json` ({ imports, exports, libs, assets }).
17
+ * The canvas frame route reads `imports` for its import map; `libs` names each
18
+ * library's pinned version (release notes, the save check of a later phase).
19
+ * Mini apps read a subset of the same files (app-libraries.ts): the app
20
+ * runtime build copies those `imports` into the app import map and their
21
+ * `exports` into the app import check, so there is one vendored copy.
22
+ */
23
+ import * as fs from 'node:fs';
24
+ import * as path from 'node:path';
25
+ import { createRequire } from 'node:module';
26
+ import { fileURLToPath } from 'node:url';
27
+ import esbuild from 'esbuild';
28
+
29
+ const REAL_DIR = path.dirname(fileURLToPath(import.meta.url));
30
+ const ENTRY_NS = 'canvas-entry';
31
+ const require = createRequire(import.meta.url);
32
+
33
+ /** One importable library: the bare specifier a canvas writes, the entry
34
+ * source that re-exports it, the npm package whose version it pins, and the
35
+ * specifiers left to the import map (a Three addon imports `three`). */
36
+ type CanvasModule = {
37
+ specifier: string;
38
+ entry: string;
39
+ source: string;
40
+ pkg: string;
41
+ external?: string[];
42
+ /** Resolved from the APP that serves the runtime (server/web), not from
43
+ * this package: a private workspace package this published one must not
44
+ * name as a dependency (scripts/publish-contract.mjs refuses that). */
45
+ fromApp?: true;
46
+ };
47
+
48
+ /** The import map's modules, by bare specifier. A canvas writes exactly
49
+ * these names; anything else is not in the set. */
50
+ export const CANVAS_MODULES: readonly CanvasModule[] = [
51
+ { specifier: 'echarts', entry: 'echarts', pkg: 'echarts', source: "export * from 'echarts';" },
52
+ { specifier: 'd3', entry: 'd3', pkg: 'd3', source: "export * from 'd3';" },
53
+ {
54
+ specifier: 'konva',
55
+ entry: 'konva',
56
+ pkg: 'konva',
57
+ source: "import Konva from 'konva';\nexport default Konva;",
58
+ },
59
+ { specifier: 'three', entry: 'three', pkg: 'three', source: "export * from 'three';" },
60
+ {
61
+ specifier: 'three/addons/controls/OrbitControls.js',
62
+ entry: 'three-orbit-controls',
63
+ pkg: 'three',
64
+ source: "export * from 'three/addons/controls/OrbitControls.js';",
65
+ external: ['three'],
66
+ },
67
+ { specifier: 'motion', entry: 'motion', pkg: 'motion', source: "export * from 'motion';" },
68
+ {
69
+ specifier: 'reveal.js',
70
+ entry: 'reveal',
71
+ pkg: 'reveal.js',
72
+ source: "import Reveal from 'reveal.js';\nexport default Reveal;",
73
+ },
74
+ {
75
+ specifier: 'katex',
76
+ entry: 'katex',
77
+ pkg: 'katex',
78
+ source: "import katex from 'katex';\nexport default katex;",
79
+ },
80
+ // The diagram templates' browser runtime (@mantle/diagram-templates): a
81
+ // template canvas imports `mount` from here instead of carrying the
82
+ // runtime inline, so it is its data and a few lines.
83
+ {
84
+ specifier: '@mantle/diagram-templates/browser',
85
+ entry: 'diagram-templates',
86
+ pkg: '@mantle/diagram-templates',
87
+ source: "export * from '@mantle/diagram-templates/browser';",
88
+ fromApp: true,
89
+ },
90
+ {
91
+ specifier: 'alpinejs',
92
+ entry: 'alpine',
93
+ pkg: 'alpinejs',
94
+ source: "import Alpine from 'alpinejs';\nexport default Alpine;",
95
+ },
96
+ ];
97
+
98
+ /** Libraries with a classic browser build only, loaded with `<script src>`
99
+ * (the path is stable, so the authoring skill can name it). */
100
+ const CLASSIC_SCRIPTS: readonly { pkg: string; from: string; to: string }[] = [
101
+ { pkg: 'plotly.js-dist-min', from: 'plotly.min.js', to: 'plotly/plotly.min.js' },
102
+ ];
103
+
104
+ /** Stylesheets copied beside the modules, at stable paths. */
105
+ const STYLE_ASSETS: readonly { pkg: string; from: string; to: string }[] = [
106
+ { pkg: 'reveal.js', from: 'dist/reveal.css', to: 'reveal/reveal.css' },
107
+ { pkg: 'reveal.js', from: 'dist/theme', to: 'reveal/theme' },
108
+ ];
109
+
110
+ export type CanvasRuntimeManifest = {
111
+ /** Bare specifier → hashed URL under the prefix (the import map). */
112
+ imports: Record<string, string>;
113
+ /** Bare specifier → the names its module exports ('default' included when
114
+ * it has one), from esbuild's metafile. The mini-app import check reads
115
+ * it (a wrong name fails the app at link time, past any error boundary). */
116
+ exports: Record<string, string[]>;
117
+ /** npm package → the version this runtime pins. */
118
+ libs: Record<string, string>;
119
+ /** The stable non-module paths (classic scripts, stylesheets). */
120
+ assets: string[];
121
+ builtAt: string;
122
+ };
123
+
124
+ /** A package's install directory. Not `require.resolve('<pkg>/package.json')`:
125
+ * a package whose `exports` omits it (reveal.js) refuses that. */
126
+ function packageDir(pkg: string, from: NodeJS.Require = require): string {
127
+ for (const base of from.resolve.paths(pkg) ?? []) {
128
+ const dir = path.join(base, pkg);
129
+ if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
130
+ }
131
+ throw new Error(`canvas runtime: package '${pkg}' is not installed`);
132
+ }
133
+
134
+ function packageVersion(pkg: string, from: NodeJS.Require = require): string {
135
+ const json = JSON.parse(
136
+ fs.readFileSync(path.join(packageDir(pkg, from), 'package.json'), 'utf8'),
137
+ ) as {
138
+ version: string;
139
+ };
140
+ return json.version;
141
+ }
142
+
143
+ function entryPlugin(appDir: string): esbuild.Plugin {
144
+ const byEntry = new Map(CANVAS_MODULES.map((m) => [m.entry, m]));
145
+ return {
146
+ name: 'canvas-runtime',
147
+ setup(build) {
148
+ build.onResolve({ filter: /^entry:/ }, (args) => ({
149
+ path: args.path.slice('entry:'.length),
150
+ namespace: ENTRY_NS,
151
+ }));
152
+ build.onLoad({ filter: /.*/, namespace: ENTRY_NS }, (args) => ({
153
+ contents: byEntry.get(args.path)?.source ?? '',
154
+ loader: 'js',
155
+ resolveDir: byEntry.get(args.path)?.fromApp ? appDir : REAL_DIR,
156
+ }));
157
+ },
158
+ };
159
+ }
160
+
161
+ /** Leave exactly these specifiers to the import map. Not esbuild's
162
+ * `external`, which also takes every subpath (`three` would take the addon
163
+ * being built, `three/addons/...`, and bundle nothing). */
164
+ function exactExternals(names: readonly string[]): esbuild.Plugin {
165
+ return {
166
+ name: 'canvas-exact-externals',
167
+ setup(build) {
168
+ build.onResolve({ filter: /.*/ }, (args) =>
169
+ names.includes(args.path) ? { path: args.path, external: true } : undefined,
170
+ );
171
+ },
172
+ };
173
+ }
174
+
175
+ /** The canvas runtime's import map JSON for a manifest (imports only). */
176
+ export function canvasImportMapJson(manifest: Pick<CanvasRuntimeManifest, 'imports'>): string {
177
+ return JSON.stringify({ imports: manifest.imports });
178
+ }
179
+
180
+ /**
181
+ * Build the canvas runtime into `outDir` (server/web/public/canvas-runtime)
182
+ * and return its manifest. `urlPrefix` is the public path it is served at;
183
+ * `appDir` is the app that serves it (a `fromApp` module resolves there).
184
+ */
185
+ export async function buildCanvasRuntime(
186
+ outDir: string,
187
+ urlPrefix = '/canvas-runtime/',
188
+ appDir = path.resolve(outDir, '..', '..'),
189
+ ): Promise<CanvasRuntimeManifest> {
190
+ const appRequire = createRequire(path.join(appDir, 'package.json'));
191
+ fs.rmSync(outDir, { recursive: true, force: true });
192
+ fs.mkdirSync(outDir, { recursive: true });
193
+
194
+ const imports: Record<string, string> = {};
195
+ const exports: Record<string, string[]> = {};
196
+ // One build per module: each is self-contained, except the externals it
197
+ // names, which the import map resolves at run time.
198
+ for (const m of CANVAS_MODULES) {
199
+ const result = await esbuild.build({
200
+ entryPoints: [{ in: `entry:${m.entry}`, out: m.entry }],
201
+ bundle: true,
202
+ format: 'esm',
203
+ platform: 'browser',
204
+ target: 'es2020',
205
+ minify: true,
206
+ legalComments: 'none',
207
+ define: { 'process.env.NODE_ENV': '"production"' },
208
+ outdir: outDir,
209
+ entryNames: '[name]-[hash]',
210
+ write: true,
211
+ metafile: true,
212
+ logLevel: 'silent',
213
+ plugins: [entryPlugin(appDir), exactExternals(m.external ?? [])],
214
+ });
215
+ const out = Object.keys(result.metafile.outputs).find((p) => p.endsWith('.js'));
216
+ if (!out) throw new Error(`canvas runtime: no output for '${m.specifier}'`);
217
+ imports[m.specifier] = urlPrefix + path.basename(out);
218
+ exports[m.specifier] = result.metafile.outputs[out]!.exports ?? [];
219
+ }
220
+
221
+ const assets: string[] = [];
222
+ for (const a of [...CLASSIC_SCRIPTS, ...STYLE_ASSETS]) {
223
+ const from = path.join(packageDir(a.pkg), a.from);
224
+ const to = path.join(outDir, a.to);
225
+ fs.mkdirSync(path.dirname(to), { recursive: true });
226
+ fs.cpSync(from, to, { recursive: true });
227
+ assets.push(urlPrefix + a.to);
228
+ }
229
+
230
+ const libs: Record<string, string> = {};
231
+ for (const m of CANVAS_MODULES) {
232
+ libs[m.pkg] = packageVersion(m.pkg, m.fromApp ? appRequire : require);
233
+ }
234
+ for (const s of CLASSIC_SCRIPTS) libs[s.pkg] = packageVersion(s.pkg);
235
+
236
+ const manifest: CanvasRuntimeManifest = {
237
+ imports,
238
+ exports,
239
+ libs,
240
+ assets,
241
+ builtAt: new Date().toISOString(),
242
+ };
243
+ fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
244
+ return manifest;
245
+ }
246
+
247
+ /** The bare specifiers a canvas may import (the import map's keys). */
248
+ export const CANVAS_MODULE_SPECIFIERS: readonly string[] = CANVAS_MODULES.map((m) => m.specifier);
package/src/css.ts CHANGED
@@ -103,3 +103,13 @@ export async function buildAppCss(source: AppSource): Promise<string> {
103
103
  const min = await esbuild.transform(css, { loader: 'css', minify: true });
104
104
  return min.code;
105
105
  }
106
+
107
+ /**
108
+ * A Present canvas's utility CSS (docs/proposals/canvas-files.md section
109
+ * 6.3): the same compile as an app's, over the canvas's one HTML document,
110
+ * so `class="rounded-lg bg-card p-6"` works with no CDN and no in-browser
111
+ * Tailwind. Run on save; the result is stored beside the source.
112
+ */
113
+ export async function buildCanvasCss(html: string): Promise<string> {
114
+ return buildAppCss({ entry: 'index.html', files: { 'index.html': html } });
115
+ }