@crossworks/app-build 0.400.44 → 0.400.56
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/package.json +19 -3
- package/src/app-libraries.build.test.ts +143 -0
- package/src/app-libraries.metafile.test.ts +2 -11
- package/src/app-libraries.test.ts +44 -13
- package/src/app-libraries.ts +75 -15
- package/src/build-runtime.ts +35 -6
- package/src/canvas-runtime.ts +68 -0
- package/src/index.ts +19 -1
- package/src/runtime-exports.fixture.ts +57 -0
- package/src/runtime-imports.test.ts +43 -6
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@crossworks/app-build",
|
|
3
|
-
"version": "0.400.
|
|
3
|
+
"version": "0.400.56",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"main": "./src/index.ts",
|
|
6
6
|
"types": "./src/index.ts",
|
|
@@ -12,25 +12,41 @@
|
|
|
12
12
|
],
|
|
13
13
|
"dependencies": {
|
|
14
14
|
"@babel/parser": "7.29.9",
|
|
15
|
-
"@
|
|
15
|
+
"@dnd-kit/core": "6.3.1",
|
|
16
|
+
"@dnd-kit/sortable": "10.0.0",
|
|
17
|
+
"@mantle/share-ui": "npm:@crossworks/share-ui@0.400.56",
|
|
16
18
|
"@tailwindcss/oxide": "^4.3.3",
|
|
19
|
+
"@tanstack/react-table": "9.3.1",
|
|
20
|
+
"@tanstack/react-virtual": "3.14.24",
|
|
17
21
|
"alpinejs": "3.17.5",
|
|
18
22
|
"d3": "7.9.0",
|
|
23
|
+
"date-fns": "4.4.0",
|
|
24
|
+
"dompurify": "3.4.17",
|
|
19
25
|
"echarts": "6.1.0",
|
|
20
26
|
"esbuild": "^0.28.2",
|
|
27
|
+
"fuse.js": "7.5.0",
|
|
21
28
|
"katex": "0.19.1",
|
|
22
29
|
"konva": "10.9.0",
|
|
23
30
|
"lucide-react": "^1.64.0",
|
|
31
|
+
"markdown-it": "15.0.3",
|
|
32
|
+
"mathjs": "15.2.0",
|
|
24
33
|
"motion": "14.7.1",
|
|
34
|
+
"papaparse": "5.7.0",
|
|
35
|
+
"pdf-lib": "1.17.1",
|
|
25
36
|
"plotly.js-dist-min": "4.1.2",
|
|
37
|
+
"qrcode": "1.5.4",
|
|
26
38
|
"react": "^19.3.1",
|
|
27
39
|
"react-dom": "^19.3.1",
|
|
28
40
|
"reveal.js": "6.0.2",
|
|
29
41
|
"tailwindcss": "^4.3.3",
|
|
30
|
-
"three": "0.186.1"
|
|
42
|
+
"three": "0.186.1",
|
|
43
|
+
"zod": "4.6.7"
|
|
31
44
|
},
|
|
32
45
|
"devDependencies": {
|
|
46
|
+
"@types/markdown-it": "14.2.0",
|
|
33
47
|
"@types/node": "^26.6.6",
|
|
48
|
+
"@types/papaparse": "5.5.2",
|
|
49
|
+
"@types/qrcode": "1.5.6",
|
|
34
50
|
"@types/react": "^19.3.0",
|
|
35
51
|
"@types/react-dom": "^19.3.0",
|
|
36
52
|
"typescript": "^5.9.3"
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The libraries an app imports, against the REAL runtimes: this builds the
|
|
3
|
+
* canvas runtime and the app runtime from the installed packages, as the
|
|
4
|
+
* deploy does, then
|
|
5
|
+
*
|
|
6
|
+
* - holds the test fixture (LIBRARY_EXPORTS_FIXTURE) to the canvas
|
|
7
|
+
* runtime's manifest, so a library upgrade that drops a name the other
|
|
8
|
+
* tests rely on fails here (the app runtime's own drift test is
|
|
9
|
+
* runtime-exports.drift.test.ts);
|
|
10
|
+
* - builds a sample app per library, and every canvas_library app guide's
|
|
11
|
+
* example App.tsx (docs/canvas-libraries/app/), with the real export map,
|
|
12
|
+
* so a guide that names an export the runtime lacks fails the gates
|
|
13
|
+
* without a browser (canvas-render/app-library-examples.test.ts then runs
|
|
14
|
+
* each one in a real frame).
|
|
15
|
+
*/
|
|
16
|
+
import * as fs from 'node:fs';
|
|
17
|
+
import * as os from 'node:os';
|
|
18
|
+
import * as path from 'node:path';
|
|
19
|
+
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
|
|
20
|
+
import { APP_CANVAS_LIBRARIES, APP_LIBRARY_SPECIFIERS } from './app-libraries';
|
|
21
|
+
import { buildCanvasRuntime } from './canvas-runtime';
|
|
22
|
+
import { buildRuntime, type RuntimeManifest } from './build-runtime';
|
|
23
|
+
import { buildApp } from './index';
|
|
24
|
+
import { LIBRARY_EXPORTS_FIXTURE } from './runtime-exports.fixture';
|
|
25
|
+
|
|
26
|
+
const ROOT = path.resolve(__dirname, '../../..');
|
|
27
|
+
const APP_GUIDES = path.join(ROOT, 'docs/canvas-libraries/app');
|
|
28
|
+
|
|
29
|
+
/** One small app per library: the imports a builder writes first. */
|
|
30
|
+
const SAMPLES: Record<string, string> = {
|
|
31
|
+
mathjs:
|
|
32
|
+
"import { evaluate, unit } from 'mathjs';\nconsole.log(evaluate('2 inch to cm'), unit(5, 'bar').toNumber('kPa'));",
|
|
33
|
+
'date-fns':
|
|
34
|
+
"import { format, addDays } from 'date-fns';\nconsole.log(format(addDays(new Date(2026, 0, 1), 3), 'yyyy-MM-dd'));",
|
|
35
|
+
zod: "import { z } from 'zod';\nconsole.log(z.object({ tag: z.string().min(1) }).safeParse({ tag: 'P-101' }).success);",
|
|
36
|
+
'fuse.js': "import Fuse from 'fuse.js';\nconsole.log(new Fuse(['pump', 'valve']).search('pmp'));",
|
|
37
|
+
papaparse:
|
|
38
|
+
"import Papa from 'papaparse';\nconsole.log(Papa.parse('a,b\\n1,2', { header: true }).data);",
|
|
39
|
+
'pdf-lib':
|
|
40
|
+
"import { PDFDocument, StandardFonts } from 'pdf-lib';\nvoid PDFDocument.create().then((d) => d.embedFont(StandardFonts.Helvetica));",
|
|
41
|
+
qrcode: "import QRCode from 'qrcode';\nconsole.log(QRCode.create('TAG-1').modules.size);",
|
|
42
|
+
'markdown-it':
|
|
43
|
+
"import MarkdownIt from 'markdown-it';\nconsole.log(new MarkdownIt().render('# Hi'));",
|
|
44
|
+
dompurify: "import DOMPurify from 'dompurify';\nconsole.log(DOMPurify.sanitize('<b>ok</b>'));",
|
|
45
|
+
'@tanstack/react-table':
|
|
46
|
+
"import { useTable, tableFeatures, createColumnHelper } from '@tanstack/react-table';\nconsole.log(useTable, tableFeatures, createColumnHelper);",
|
|
47
|
+
'@tanstack/react-virtual':
|
|
48
|
+
"import { useVirtualizer } from '@tanstack/react-virtual';\nconsole.log(useVirtualizer);",
|
|
49
|
+
'@dnd-kit/core':
|
|
50
|
+
"import { DndContext, useDraggable } from '@dnd-kit/core';\nconsole.log(DndContext, useDraggable);",
|
|
51
|
+
'@dnd-kit/sortable':
|
|
52
|
+
"import { SortableContext, useSortable, arrayMove } from '@dnd-kit/sortable';\nconsole.log(SortableContext, useSortable, arrayMove);",
|
|
53
|
+
};
|
|
54
|
+
|
|
55
|
+
function appExampleOf(md: string): string {
|
|
56
|
+
const m = /## App example\n+```tsx\n([\s\S]*?)\n```/.exec(md);
|
|
57
|
+
if (!m) throw new Error('no ## App example tsx block');
|
|
58
|
+
return m[1]!;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
describe('the app libraries, against the real runtimes', () => {
|
|
62
|
+
let tmp: string;
|
|
63
|
+
let canvas: Awaited<ReturnType<typeof buildCanvasRuntime>>;
|
|
64
|
+
let app: RuntimeManifest;
|
|
65
|
+
|
|
66
|
+
beforeAll(async () => {
|
|
67
|
+
tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'mantle-libs-'));
|
|
68
|
+
canvas = await buildCanvasRuntime(
|
|
69
|
+
path.join(tmp, 'canvas-runtime'),
|
|
70
|
+
'/canvas-runtime/',
|
|
71
|
+
path.join(ROOT, 'server/web'),
|
|
72
|
+
);
|
|
73
|
+
app = await buildRuntime(path.join(tmp, 'app-runtime'), '/app-runtime/', canvas);
|
|
74
|
+
}, 240_000);
|
|
75
|
+
|
|
76
|
+
afterAll(() => {
|
|
77
|
+
if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
it('the fixture covers every canvas library an app reads, with real names only', () => {
|
|
81
|
+
expect(Object.keys(LIBRARY_EXPORTS_FIXTURE).sort()).toEqual(
|
|
82
|
+
APP_CANVAS_LIBRARIES.map((l) => l.specifier).sort(),
|
|
83
|
+
);
|
|
84
|
+
for (const [spec, names] of Object.entries(LIBRARY_EXPORTS_FIXTURE)) {
|
|
85
|
+
const real = new Set(canvas.exports[spec]);
|
|
86
|
+
for (const name of names) expect(real, `${spec} should export ${name}`).toContain(name);
|
|
87
|
+
}
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
it('every library an app may import is in the app import map, at a file that exists', () => {
|
|
91
|
+
for (const spec of APP_LIBRARY_SPECIFIERS) {
|
|
92
|
+
const url = app.imports[spec];
|
|
93
|
+
expect(url, spec).toBeTruthy();
|
|
94
|
+
const dir = url!.startsWith('/canvas-runtime/') ? 'canvas-runtime' : 'app-runtime';
|
|
95
|
+
expect(fs.existsSync(path.join(tmp, dir, path.basename(url!))), url).toBe(true);
|
|
96
|
+
expect(app.exports[spec]?.length, spec).toBeGreaterThan(0);
|
|
97
|
+
}
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
it('there is a sample for every library', () => {
|
|
101
|
+
expect(Object.keys(SAMPLES).every((s) => APP_LIBRARY_SPECIFIERS.includes(s))).toBe(true);
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
for (const [spec, body] of Object.entries(SAMPLES)) {
|
|
105
|
+
it(`a sample app importing '${spec}' builds, with the import left bare`, async () => {
|
|
106
|
+
const res = await buildApp(
|
|
107
|
+
{
|
|
108
|
+
entry: 'App.tsx',
|
|
109
|
+
files: { 'App.tsx': `${body}\nexport default function App() { return <div />; }\n` },
|
|
110
|
+
},
|
|
111
|
+
{ runtimeExports: app.exports },
|
|
112
|
+
);
|
|
113
|
+
expect(res.errors).toEqual([]);
|
|
114
|
+
expect(res.ok).toBe(true);
|
|
115
|
+
expect(res.code).toContain(JSON.stringify(spec));
|
|
116
|
+
expect(res.code!.length).toBeLessThan(5000);
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
const guides = fs.readdirSync(APP_GUIDES).filter((f) => f.endsWith('.md'));
|
|
121
|
+
for (const file of guides) {
|
|
122
|
+
it(`the ${file} app example builds against the real export map`, async () => {
|
|
123
|
+
const example = appExampleOf(fs.readFileSync(path.join(APP_GUIDES, file), 'utf8'));
|
|
124
|
+
const res = await buildApp(
|
|
125
|
+
{ entry: 'App.tsx', files: { 'App.tsx': example } },
|
|
126
|
+
{ runtimeExports: app.exports },
|
|
127
|
+
);
|
|
128
|
+
expect(res.errors).toEqual([]);
|
|
129
|
+
expect(res.ok).toBe(true);
|
|
130
|
+
});
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
it('the papaparse module refuses download and worker, and parses text', async () => {
|
|
134
|
+
const url = canvas.imports['papaparse']!;
|
|
135
|
+
const mod = (await import(path.join(tmp, 'canvas-runtime', path.basename(url)))) as {
|
|
136
|
+
default: { parse: (i: string, c?: Record<string, unknown>) => { data: unknown[] } };
|
|
137
|
+
};
|
|
138
|
+
const Papa = mod.default;
|
|
139
|
+
expect(() => Papa.parse('https://x.invalid/a.csv', { download: true })).toThrow(/download/);
|
|
140
|
+
expect(() => Papa.parse('a,b', { worker: true })).toThrow(/worker/);
|
|
141
|
+
expect(Papa.parse('a,b\n1,2', { header: true }).data).toEqual([{ a: '1', b: '2' }]);
|
|
142
|
+
});
|
|
143
|
+
});
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* each build's inputs.
|
|
7
7
|
*/
|
|
8
8
|
import { describe, expect, it, vi } from 'vitest';
|
|
9
|
-
import { RUNTIME_EXPORTS_FIXTURE } from './runtime-exports.fixture';
|
|
9
|
+
import { LIBRARY_EXPORTS_FIXTURE, RUNTIME_EXPORTS_FIXTURE } from './runtime-exports.fixture';
|
|
10
10
|
|
|
11
11
|
const seen = vi.hoisted(() => [] as string[][]);
|
|
12
12
|
|
|
@@ -23,16 +23,7 @@ vi.mock('esbuild', async (importOriginal) => {
|
|
|
23
23
|
const { buildApp, APP_LIBRARY_SPECIFIERS } = await import('./index');
|
|
24
24
|
|
|
25
25
|
/** The runtime shapes of the libraries (subsets), as app-libraries.test.ts. */
|
|
26
|
-
const RT: Record<string, string[]> = {
|
|
27
|
-
...RUNTIME_EXPORTS_FIXTURE,
|
|
28
|
-
echarts: ['init'],
|
|
29
|
-
d3: ['select'],
|
|
30
|
-
three: ['Scene'],
|
|
31
|
-
'three/addons/controls/OrbitControls.js': ['OrbitControls'],
|
|
32
|
-
konva: ['default'],
|
|
33
|
-
katex: ['default'],
|
|
34
|
-
'@mantle/diagram-templates/browser': ['render'],
|
|
35
|
-
};
|
|
26
|
+
const RT: Record<string, string[]> = { ...RUNTIME_EXPORTS_FIXTURE, ...LIBRARY_EXPORTS_FIXTURE };
|
|
36
27
|
|
|
37
28
|
describe('library imports read no file', () => {
|
|
38
29
|
for (const spec of APP_LIBRARY_SPECIFIERS) {
|
|
@@ -6,22 +6,19 @@
|
|
|
6
6
|
*/
|
|
7
7
|
import { describe, expect, it } from 'vitest';
|
|
8
8
|
import { buildApp, type AppSource } from './index';
|
|
9
|
-
import {
|
|
9
|
+
import {
|
|
10
|
+
APP_CANVAS_LIBRARIES,
|
|
11
|
+
APP_LIBRARY_SPECIFIERS,
|
|
12
|
+
APP_RUNTIME_LIBRARIES,
|
|
13
|
+
appCanvasLibraries,
|
|
14
|
+
} from './app-libraries';
|
|
15
|
+
import { addRuntimeLibraries } from './build-runtime';
|
|
10
16
|
import { CANVAS_MODULE_SPECIFIERS } from './canvas-runtime';
|
|
11
|
-
import { RUNTIME_EXPORTS_FIXTURE } from './runtime-exports.fixture';
|
|
17
|
+
import { LIBRARY_EXPORTS_FIXTURE, RUNTIME_EXPORTS_FIXTURE } from './runtime-exports.fixture';
|
|
12
18
|
|
|
13
19
|
/** The fixture plus the library shapes the canvas runtime manifest records
|
|
14
|
-
* (subsets;
|
|
15
|
-
const RT: Record<string, string[]> = {
|
|
16
|
-
...RUNTIME_EXPORTS_FIXTURE,
|
|
17
|
-
echarts: ['init', 'graphic', 'use'],
|
|
18
|
-
d3: ['select', 'scaleLinear', 'axisBottom'],
|
|
19
|
-
three: ['Scene', 'WebGLRenderer', 'PerspectiveCamera', 'Mesh'],
|
|
20
|
-
'three/addons/controls/OrbitControls.js': ['OrbitControls'],
|
|
21
|
-
konva: ['default'],
|
|
22
|
-
katex: ['default'],
|
|
23
|
-
'@mantle/diagram-templates/browser': ['domMeasurer', 'mount', 'render'],
|
|
24
|
-
};
|
|
20
|
+
* (subsets; app-libraries.build.test.ts checks them against the real build). */
|
|
21
|
+
const RT: Record<string, string[]> = { ...RUNTIME_EXPORTS_FIXTURE, ...LIBRARY_EXPORTS_FIXTURE };
|
|
25
22
|
|
|
26
23
|
const app = (body: string): AppSource => ({
|
|
27
24
|
entry: 'App.tsx',
|
|
@@ -125,4 +122,38 @@ describe('mini-app library imports', () => {
|
|
|
125
122
|
);
|
|
126
123
|
expect(out.imports['reveal.js']).toBeUndefined();
|
|
127
124
|
});
|
|
125
|
+
|
|
126
|
+
it('every library carries a one-line hint an agent can read', () => {
|
|
127
|
+
for (const l of [...APP_CANVAS_LIBRARIES, ...APP_RUNTIME_LIBRARIES]) {
|
|
128
|
+
expect(l.hint.trim().length, l.specifier).toBeGreaterThan(3);
|
|
129
|
+
expect(l.hint.length, l.specifier).toBeLessThanOrEqual(80);
|
|
130
|
+
expect(l.hint, l.specifier).not.toMatch(/[\n\u2013\u2014]/);
|
|
131
|
+
}
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
it('a runtime library may not take a runtime entry or specifier, nor a chunk name', () => {
|
|
135
|
+
const base = (): { entries: Record<string, string>; specs: Record<string, string> } => ({
|
|
136
|
+
entries: { host: 'h', react: 'r' },
|
|
137
|
+
specs: { '@host': 'host' },
|
|
138
|
+
});
|
|
139
|
+
const lib = (entry: string, specifier = 'x-lib') => [
|
|
140
|
+
{ specifier, entry, guide: 'g', hint: 'h' },
|
|
141
|
+
];
|
|
142
|
+
for (const [entry, specifier, why] of [
|
|
143
|
+
['host', 'x-lib', /entry 'host' is taken/],
|
|
144
|
+
['x-lib', '@host', /specifier '@host' is taken/],
|
|
145
|
+
['chunk', 'x-lib', /not a usable entry name/],
|
|
146
|
+
['chunk-a', 'x-lib', /not a usable entry name/],
|
|
147
|
+
['Bad Name', 'x-lib', /not a usable entry name/],
|
|
148
|
+
] as const) {
|
|
149
|
+
const b = base();
|
|
150
|
+
expect(() => addRuntimeLibraries(b.entries, b.specs, lib(entry, specifier))).toThrow(why);
|
|
151
|
+
}
|
|
152
|
+
const b = base();
|
|
153
|
+
addRuntimeLibraries(b.entries, b.specs, lib('x-lib'));
|
|
154
|
+
expect(b.specs['x-lib']).toBe('x-lib');
|
|
155
|
+
expect(b.entries['x-lib']).toBe('export * from "x-lib";');
|
|
156
|
+
// The same library twice is refused on the second pass.
|
|
157
|
+
expect(() => addRuntimeLibraries(b.entries, b.specs, lib('x-lib'))).toThrow(/taken/);
|
|
158
|
+
});
|
|
128
159
|
});
|
package/src/app-libraries.ts
CHANGED
|
@@ -8,36 +8,96 @@
|
|
|
8
8
|
* import check, so the bundler leaves the import bare (index.ts) and the
|
|
9
9
|
* frame resolves it, as it resolves React.
|
|
10
10
|
*
|
|
11
|
-
* The
|
|
12
|
-
*
|
|
13
|
-
* (build-runtime.ts), not taken from
|
|
11
|
+
* The exceptions are the libraries that import React (`motion/react`, the
|
|
12
|
+
* TanStack table and virtualizer, dnd-kit): they are built into the APP
|
|
13
|
+
* runtime against the one shared React (build-runtime.ts), not taken from
|
|
14
|
+
* the canvas set, which has no React.
|
|
15
|
+
*
|
|
16
|
+
* Each library is its own content-hashed file, fetched only when an app
|
|
17
|
+
* imports it: the import map is an address book, so a large library (pdf-lib,
|
|
18
|
+
* mathjs) costs an app that does not import it nothing.
|
|
14
19
|
*
|
|
15
20
|
* Every entry is an exact specifier. A subpath (`echarts/core`,
|
|
16
21
|
* `three/examples/jsm/...`) is refused like any other unlisted import.
|
|
17
22
|
*/
|
|
18
23
|
|
|
19
|
-
/** A
|
|
20
|
-
*
|
|
21
|
-
|
|
24
|
+
/** A library an app may import: the specifier as written in app source,
|
|
25
|
+
* the canvas_library guide that covers it, and a one-line hint of what to
|
|
26
|
+
* use it for, written for agents to read as is. */
|
|
27
|
+
export type AppLibrary = Readonly<{ specifier: string; guide: string; hint: string }>;
|
|
28
|
+
|
|
29
|
+
/** An app-runtime library: also the entry it is built as (build-runtime.ts). */
|
|
30
|
+
export type AppRuntimeLibrary = AppLibrary & Readonly<{ entry: string }>;
|
|
22
31
|
|
|
23
32
|
/** Taken from the canvas runtime's manifest (must be in CANVAS_MODULES). */
|
|
24
33
|
export const APP_CANVAS_LIBRARIES: readonly AppLibrary[] = [
|
|
25
|
-
{ specifier: 'echarts', guide: 'echarts' },
|
|
26
|
-
{ specifier: 'd3', guide: 'd3' },
|
|
27
|
-
{ specifier: 'three', guide: 'three' },
|
|
34
|
+
{ specifier: 'echarts', guide: 'echarts', hint: 'business charts and dashboards' },
|
|
35
|
+
{ specifier: 'd3', guide: 'd3', hint: 'custom charts, scales, shapes, force graphs' },
|
|
36
|
+
{ specifier: 'three', guide: 'three', hint: '3D scenes' },
|
|
28
37
|
// The addon imports `three` through the import map, so a scene and its
|
|
29
38
|
// controls share one Three.
|
|
30
|
-
{
|
|
31
|
-
|
|
32
|
-
|
|
39
|
+
{
|
|
40
|
+
specifier: 'three/addons/controls/OrbitControls.js',
|
|
41
|
+
guide: 'three',
|
|
42
|
+
hint: 'orbit, zoom and pan for a 3D scene',
|
|
43
|
+
},
|
|
44
|
+
{ specifier: 'konva', guide: 'konva', hint: '2D shapes people drag and click' },
|
|
45
|
+
{ specifier: 'katex', guide: 'katex', hint: 'typeset formulas' },
|
|
33
46
|
// The diagram templates (flow, pid): `render` + `domMeasurer` draw a
|
|
34
47
|
// template's data to an SVG string in the app's own document.
|
|
35
|
-
{
|
|
48
|
+
{
|
|
49
|
+
specifier: '@mantle/diagram-templates/browser',
|
|
50
|
+
guide: 'diagram-templates',
|
|
51
|
+
hint: 'flow and P&ID diagrams drawn from data',
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
specifier: 'mathjs',
|
|
55
|
+
guide: 'mathjs',
|
|
56
|
+
hint: 'units and engineering maths, formulas a person types for their own use',
|
|
57
|
+
},
|
|
58
|
+
{ specifier: 'date-fns', guide: 'date-fns', hint: 'dates: format, add business days, ranges' },
|
|
59
|
+
{ specifier: 'zod', guide: 'zod', hint: 'form checks and the shape of rows' },
|
|
60
|
+
{ specifier: 'fuse.js', guide: 'fuse', hint: 'fuzzy search (typos, partial words)' },
|
|
61
|
+
{ specifier: 'papaparse', guide: 'papaparse', hint: 'CSV in and out' },
|
|
62
|
+
{ specifier: 'pdf-lib', guide: 'pdf-lib', hint: 'make or fill a PDF' },
|
|
63
|
+
{ specifier: 'qrcode', guide: 'qrcode', hint: 'QR codes for labels and tags' },
|
|
64
|
+
// One guide: markdown-it's HTML reaches the DOM only through DOMPurify.
|
|
65
|
+
{
|
|
66
|
+
specifier: 'markdown-it',
|
|
67
|
+
guide: 'markdown',
|
|
68
|
+
hint: 'markdown to HTML; always pass the HTML through dompurify',
|
|
69
|
+
},
|
|
70
|
+
{ specifier: 'dompurify', guide: 'markdown', hint: 'sanitize HTML before it reaches the DOM' },
|
|
36
71
|
];
|
|
37
72
|
|
|
38
73
|
/** Built into the app runtime itself (build-runtime.ts ENTRY_SRC). */
|
|
39
|
-
export const APP_RUNTIME_LIBRARIES: readonly
|
|
40
|
-
{ specifier: 'motion/react', guide: 'motion' },
|
|
74
|
+
export const APP_RUNTIME_LIBRARIES: readonly AppRuntimeLibrary[] = [
|
|
75
|
+
{ specifier: 'motion/react', guide: 'motion', entry: 'motion-react', hint: 'animation' },
|
|
76
|
+
{
|
|
77
|
+
specifier: '@tanstack/react-table',
|
|
78
|
+
guide: 'tanstack-table',
|
|
79
|
+
entry: 'tanstack-table',
|
|
80
|
+
hint: 'big grids: sort, filter (v9 API: useTable)',
|
|
81
|
+
},
|
|
82
|
+
{
|
|
83
|
+
specifier: '@tanstack/react-virtual',
|
|
84
|
+
guide: 'tanstack-virtual',
|
|
85
|
+
entry: 'tanstack-virtual',
|
|
86
|
+
hint: 'long lists that render only the rows on screen',
|
|
87
|
+
},
|
|
88
|
+
// Sortable imports core: splitting gives both one copy, so one drag context.
|
|
89
|
+
{
|
|
90
|
+
specifier: '@dnd-kit/core',
|
|
91
|
+
guide: 'dnd-kit',
|
|
92
|
+
entry: 'dnd-kit-core',
|
|
93
|
+
hint: 'drag and drop',
|
|
94
|
+
},
|
|
95
|
+
{
|
|
96
|
+
specifier: '@dnd-kit/sortable',
|
|
97
|
+
guide: 'dnd-kit',
|
|
98
|
+
entry: 'dnd-kit-sortable',
|
|
99
|
+
hint: 'reorder a list or a board by dragging (with @dnd-kit/core)',
|
|
100
|
+
},
|
|
41
101
|
];
|
|
42
102
|
|
|
43
103
|
/** Canvas libraries an app may NOT import, and why. The error text names
|
package/src/build-runtime.ts
CHANGED
|
@@ -28,7 +28,11 @@ import { createRequire } from 'node:module';
|
|
|
28
28
|
import { fileURLToPath } from 'node:url';
|
|
29
29
|
import esbuild from 'esbuild';
|
|
30
30
|
import { KIT } from './kit.ts';
|
|
31
|
-
import {
|
|
31
|
+
import {
|
|
32
|
+
APP_RUNTIME_LIBRARIES,
|
|
33
|
+
appCanvasLibraries,
|
|
34
|
+
type AppRuntimeLibrary,
|
|
35
|
+
} from './app-libraries.ts';
|
|
32
36
|
|
|
33
37
|
const REAL_DIR = path.dirname(fileURLToPath(import.meta.url));
|
|
34
38
|
const ENTRY_NS = 'rt-entry';
|
|
@@ -67,10 +71,6 @@ const ENTRY_SRC: Record<string, string> = {
|
|
|
67
71
|
badge: KIT['@/components/ui/badge']!,
|
|
68
72
|
separator: KIT['@/components/ui/separator']!,
|
|
69
73
|
host: KIT['@host']!,
|
|
70
|
-
// Motion's React API (app-libraries.ts): it imports React, so it is built
|
|
71
|
-
// here, where splitting gives it the one shared React, not in the canvas
|
|
72
|
-
// runtime. ESM, so `export *` carries its names across the boundary.
|
|
73
|
-
'motion-react': "export * from 'motion/react';",
|
|
74
74
|
};
|
|
75
75
|
|
|
76
76
|
/** Specifier as written in app source → entry name. This is the contract the
|
|
@@ -88,9 +88,38 @@ export const RUNTIME_SPECIFIERS: Record<string, string> = {
|
|
|
88
88
|
'@/components/ui/badge': 'badge',
|
|
89
89
|
'@/components/ui/separator': 'separator',
|
|
90
90
|
'@host': 'host',
|
|
91
|
-
'motion/react': 'motion-react',
|
|
92
91
|
};
|
|
93
92
|
|
|
93
|
+
/**
|
|
94
|
+
* Add the libraries that import React (app-libraries.ts) to the entries and
|
|
95
|
+
* the specifier map: built here, where splitting gives them the one shared
|
|
96
|
+
* React, not in the canvas runtime. ESM, so `export *` carries their names
|
|
97
|
+
* across the boundary. Throws on a name that is taken: a library entry or
|
|
98
|
+
* specifier equal to a runtime one would replace it silently (an entry named
|
|
99
|
+
* `host` would replace the bridge), and an entry named like `chunk` would be
|
|
100
|
+
* read as one of the split chunks.
|
|
101
|
+
*/
|
|
102
|
+
export function addRuntimeLibraries(
|
|
103
|
+
entries: Record<string, string>,
|
|
104
|
+
specifiers: Record<string, string>,
|
|
105
|
+
libraries: readonly AppRuntimeLibrary[],
|
|
106
|
+
): void {
|
|
107
|
+
for (const l of libraries) {
|
|
108
|
+
if (/^chunk($|-)/.test(l.entry) || !/^[a-z][a-z0-9-]*$/.test(l.entry)) {
|
|
109
|
+
throw new Error(`app runtime: library entry '${l.entry}' is not a usable entry name`);
|
|
110
|
+
}
|
|
111
|
+
if (Object.hasOwn(entries, l.entry)) {
|
|
112
|
+
throw new Error(`app runtime: library entry '${l.entry}' is taken`);
|
|
113
|
+
}
|
|
114
|
+
if (Object.hasOwn(specifiers, l.specifier)) {
|
|
115
|
+
throw new Error(`app runtime: library specifier '${l.specifier}' is taken`);
|
|
116
|
+
}
|
|
117
|
+
entries[l.entry] = `export * from ${JSON.stringify(l.specifier)};`;
|
|
118
|
+
specifiers[l.specifier] = l.entry;
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
addRuntimeLibraries(ENTRY_SRC, RUNTIME_SPECIFIERS, APP_RUNTIME_LIBRARIES);
|
|
122
|
+
|
|
94
123
|
/** esbuild plugin: serve the virtual entry sources + bind the kit's own
|
|
95
124
|
* `@/lib/utils` import to the same `utils` module (so `cn` isn't duplicated).
|
|
96
125
|
* Everything else (react, react-dom, scheduler) resolves from node_modules and
|
package/src/canvas-runtime.ts
CHANGED
|
@@ -92,6 +92,74 @@ export const CANVAS_MODULES: readonly CanvasModule[] = [
|
|
|
92
92
|
entry: 'alpine',
|
|
93
93
|
pkg: 'alpinejs',
|
|
94
94
|
source: "import Alpine from 'alpinejs';\nexport default Alpine;",
|
|
95
|
+
}, // The mini-app kit (app-libraries.ts): plain libraries with no React, so
|
|
96
|
+
// one vendored file each, here, as the canvas set. Each loads only when
|
|
97
|
+
// imported; none reaches the network or compiles code at run time (the
|
|
98
|
+
// app-library browser test watches the frame).
|
|
99
|
+
{ specifier: 'mathjs', entry: 'mathjs', pkg: 'mathjs', source: "export * from 'mathjs';" },
|
|
100
|
+
{
|
|
101
|
+
specifier: 'date-fns',
|
|
102
|
+
entry: 'date-fns',
|
|
103
|
+
pkg: 'date-fns',
|
|
104
|
+
source: "export * from 'date-fns';",
|
|
105
|
+
},
|
|
106
|
+
{
|
|
107
|
+
specifier: 'zod',
|
|
108
|
+
entry: 'zod',
|
|
109
|
+
pkg: 'zod',
|
|
110
|
+
// Zod 4 compiles object parsers with `new Function` when it may, and
|
|
111
|
+
// probes for that on first use. The frame has no 'unsafe-eval': the
|
|
112
|
+
// probe would fail (caught) and log a CSP violation. jitless skips the
|
|
113
|
+
// probe and the object compile, so parsing never asks. What jitless does
|
|
114
|
+
// not cover is code that asks itself: `z.compile()` (it tries, is
|
|
115
|
+
// refused, and falls back or throws) or a `config({ jitless: false })`.
|
|
116
|
+
// The CSP refuses both; the zod guide says not to.
|
|
117
|
+
source: "import { config } from 'zod';\nconfig({ jitless: true });\nexport * from 'zod';",
|
|
118
|
+
},
|
|
119
|
+
{
|
|
120
|
+
specifier: 'fuse.js',
|
|
121
|
+
entry: 'fuse',
|
|
122
|
+
pkg: 'fuse.js',
|
|
123
|
+
source: "import Fuse from 'fuse.js';\nexport default Fuse;",
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
specifier: 'papaparse',
|
|
127
|
+
entry: 'papaparse',
|
|
128
|
+
pkg: 'papaparse',
|
|
129
|
+
// Papa Parse can fetch a URL (`download`, by XHR) and start a worker
|
|
130
|
+
// from a blob (`worker`). A canvas or an app parses text or a File it
|
|
131
|
+
// already holds; this says so, rather than leave the frame's CSP to
|
|
132
|
+
// refuse the request with a less helpful error.
|
|
133
|
+
source: [
|
|
134
|
+
"import Papa from 'papaparse';",
|
|
135
|
+
'const parse = Papa.parse;',
|
|
136
|
+
'Papa.parse = function (input, config) {',
|
|
137
|
+
' if (config && (config.download || config.worker)) {',
|
|
138
|
+
" throw new Error(\"Papa.parse: 'download' and 'worker' are off here (no network, no workers). Pass the CSV text or a File.\");",
|
|
139
|
+
' }',
|
|
140
|
+
' return parse.call(Papa, input, config);',
|
|
141
|
+
'};',
|
|
142
|
+
'export default Papa;',
|
|
143
|
+
].join('\n'),
|
|
144
|
+
},
|
|
145
|
+
{ specifier: 'pdf-lib', entry: 'pdf-lib', pkg: 'pdf-lib', source: "export * from 'pdf-lib';" },
|
|
146
|
+
{
|
|
147
|
+
specifier: 'qrcode',
|
|
148
|
+
entry: 'qrcode',
|
|
149
|
+
pkg: 'qrcode',
|
|
150
|
+
source: "import QRCode from 'qrcode';\nexport default QRCode;",
|
|
151
|
+
},
|
|
152
|
+
{
|
|
153
|
+
specifier: 'markdown-it',
|
|
154
|
+
entry: 'markdown-it',
|
|
155
|
+
pkg: 'markdown-it',
|
|
156
|
+
source: "import MarkdownIt from 'markdown-it';\nexport default MarkdownIt;",
|
|
157
|
+
},
|
|
158
|
+
{
|
|
159
|
+
specifier: 'dompurify',
|
|
160
|
+
entry: 'dompurify',
|
|
161
|
+
pkg: 'dompurify',
|
|
162
|
+
source: "import DOMPurify from 'dompurify';\nexport default DOMPurify;",
|
|
95
163
|
},
|
|
96
164
|
];
|
|
97
165
|
|
package/src/index.ts
CHANGED
|
@@ -560,6 +560,23 @@ function importedNames(clause: string): { names: string[]; namespace: boolean }
|
|
|
560
560
|
return { names, namespace };
|
|
561
561
|
}
|
|
562
562
|
|
|
563
|
+
/** A module's export names for an error. A large surface (mathjs exports
|
|
564
|
+
* over a thousand) is cut, so the message stays one a model reads; the
|
|
565
|
+
* names close to the wanted one come first, so the cut never hides them. */
|
|
566
|
+
const EXPORTS_SHOWN = 60;
|
|
567
|
+
function exportList(names: readonly string[], wanted: string): string {
|
|
568
|
+
if (names.length <= EXPORTS_SHOWN) return names.join(', ');
|
|
569
|
+
const w = wanted.toLowerCase();
|
|
570
|
+
const lower = (n: string) => n.toLowerCase();
|
|
571
|
+
// A name holding the wanted one first (`evaluat` finds `evaluate`), then
|
|
572
|
+
// one the wanted name holds (`formatDate` finds `format`), never a name
|
|
573
|
+
// so short that every word holds it (mathjs exports `e`).
|
|
574
|
+
const holding = w === 'default' ? [] : names.filter((n) => lower(n).includes(w));
|
|
575
|
+
const held = w === 'default' ? [] : names.filter((n) => n.length >= 3 && w.includes(lower(n)));
|
|
576
|
+
const shown = [...new Set([...holding, ...held, ...names])].slice(0, EXPORTS_SHOWN);
|
|
577
|
+
return `${shown.join(', ')} and ${names.length - shown.length} more (canvas_library with for: 'app' gives the usual imports)`;
|
|
578
|
+
}
|
|
579
|
+
|
|
563
580
|
/**
|
|
564
581
|
* Static lint: every import of a SHARED RUNTIME specifier must name something
|
|
565
582
|
* that specifier actually exports.
|
|
@@ -606,7 +623,7 @@ export function lintRuntimeImports(
|
|
|
606
623
|
? `'${spec}' has no default export. Use a named import, e.g. import { ${available[0]} } from '${spec}'.`
|
|
607
624
|
: `'${spec}' does not export '${name}'.`;
|
|
608
625
|
out.push({
|
|
609
|
-
text: `${hint} It exports: ${available
|
|
626
|
+
text: `${hint} It exports: ${exportList(available, name)}. Left as-is the app builds but fails to load in the browser, with no error the app can catch.`,
|
|
610
627
|
location: { file, line, column },
|
|
611
628
|
});
|
|
612
629
|
}
|
|
@@ -628,6 +645,7 @@ export {
|
|
|
628
645
|
APP_LIBRARY_SPECIFIERS,
|
|
629
646
|
APP_RUNTIME_LIBRARIES,
|
|
630
647
|
} from './app-libraries';
|
|
648
|
+
export { KIT_UI_IMPORTS } from './kit';
|
|
631
649
|
|
|
632
650
|
export async function buildApp(
|
|
633
651
|
source: AppSource,
|
|
@@ -29,4 +29,61 @@ export const RUNTIME_EXPORTS_FIXTURE: Record<string, string[]> = {
|
|
|
29
29
|
'@/components/ui/separator': ['Separator'],
|
|
30
30
|
'@host': ['__mount', 'host'],
|
|
31
31
|
'motion/react': ['motion', 'AnimatePresence', 'animate', 'useAnimate', 'useReducedMotion'],
|
|
32
|
+
'@tanstack/react-table': [
|
|
33
|
+
'useTable',
|
|
34
|
+
'tableFeatures',
|
|
35
|
+
'createColumnHelper',
|
|
36
|
+
'createSortedRowModel',
|
|
37
|
+
'rowSortingFeature',
|
|
38
|
+
'sortFn_alphanumeric',
|
|
39
|
+
'columnFilteringFeature',
|
|
40
|
+
'globalFilteringFeature',
|
|
41
|
+
'createFilteredRowModel',
|
|
42
|
+
'filterFn_includesString',
|
|
43
|
+
'FlexRender',
|
|
44
|
+
],
|
|
45
|
+
'@tanstack/react-virtual': ['useVirtualizer', 'useWindowVirtualizer'],
|
|
46
|
+
'@dnd-kit/core': [
|
|
47
|
+
'DndContext',
|
|
48
|
+
'closestCenter',
|
|
49
|
+
'KeyboardSensor',
|
|
50
|
+
'PointerSensor',
|
|
51
|
+
'useSensor',
|
|
52
|
+
'useSensors',
|
|
53
|
+
'useDraggable',
|
|
54
|
+
'useDroppable',
|
|
55
|
+
'DragOverlay',
|
|
56
|
+
],
|
|
57
|
+
'@dnd-kit/sortable': [
|
|
58
|
+
'SortableContext',
|
|
59
|
+
'useSortable',
|
|
60
|
+
'arrayMove',
|
|
61
|
+
'sortableKeyboardCoordinates',
|
|
62
|
+
'verticalListSortingStrategy',
|
|
63
|
+
],
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* The canvas-runtime libraries an app reads (app-libraries.ts
|
|
68
|
+
* APP_CANVAS_LIBRARIES), as subsets of what the canvas runtime's manifest
|
|
69
|
+
* records. `app-libraries.build.test.ts` builds the real canvas runtime and
|
|
70
|
+
* asserts every name here is real and every library is here.
|
|
71
|
+
*/
|
|
72
|
+
export const LIBRARY_EXPORTS_FIXTURE: Record<string, string[]> = {
|
|
73
|
+
echarts: ['init', 'graphic', 'use'],
|
|
74
|
+
d3: ['select', 'scaleLinear', 'axisBottom'],
|
|
75
|
+
three: ['Scene', 'WebGLRenderer', 'PerspectiveCamera', 'Mesh'],
|
|
76
|
+
'three/addons/controls/OrbitControls.js': ['OrbitControls'],
|
|
77
|
+
konva: ['default'],
|
|
78
|
+
katex: ['default'],
|
|
79
|
+
'@mantle/diagram-templates/browser': ['domMeasurer', 'mount', 'render'],
|
|
80
|
+
mathjs: ['evaluate', 'unit', 'create', 'all', 'format', 'round'],
|
|
81
|
+
'date-fns': ['format', 'addDays', 'differenceInCalendarDays', 'parseISO', 'isWeekend'],
|
|
82
|
+
zod: ['z', 'object', 'string', 'number', 'ZodError', 'prettifyError'],
|
|
83
|
+
'fuse.js': ['default'],
|
|
84
|
+
papaparse: ['default'],
|
|
85
|
+
'pdf-lib': ['PDFDocument', 'StandardFonts', 'rgb'],
|
|
86
|
+
qrcode: ['default'],
|
|
87
|
+
'markdown-it': ['default'],
|
|
88
|
+
dompurify: ['default'],
|
|
32
89
|
};
|
|
@@ -125,9 +125,9 @@ describe('buildApp: type-only imports', () => {
|
|
|
125
125
|
});
|
|
126
126
|
|
|
127
127
|
it.each([
|
|
128
|
-
"import type {
|
|
129
|
-
"import { type
|
|
130
|
-
"export type {
|
|
128
|
+
"import type { Schema } from 'yup';",
|
|
129
|
+
"import { type Schema } from 'yup';",
|
|
130
|
+
"export type { Schema } from 'yup';",
|
|
131
131
|
])('allows a disallowed package imported type-only: %s', async (head) => {
|
|
132
132
|
const res = await buildApp(app(head), { runtimeExports: RT });
|
|
133
133
|
expect(res.errors).toEqual([]);
|
|
@@ -135,12 +135,12 @@ describe('buildApp: type-only imports', () => {
|
|
|
135
135
|
});
|
|
136
136
|
|
|
137
137
|
it.each([
|
|
138
|
-
"import {
|
|
139
|
-
"import { type
|
|
138
|
+
"import { object } from 'yup'; console.log(object);",
|
|
139
|
+
"import { type Schema, object } from 'yup'; console.log(object);",
|
|
140
140
|
])('refuses the same package imported as a value: %s', async (head) => {
|
|
141
141
|
const res = await buildApp(app(head), { runtimeExports: RT });
|
|
142
142
|
expect(res.ok).toBe(false);
|
|
143
|
-
expect(res.errors[0]!.text).toContain("Import '
|
|
143
|
+
expect(res.errors[0]!.text).toContain("Import 'yup' is not allowed in a mini app");
|
|
144
144
|
});
|
|
145
145
|
});
|
|
146
146
|
|
|
@@ -197,3 +197,40 @@ describe('lintRuntimeImports: re-exports link like imports', () => {
|
|
|
197
197
|
expect(lintRuntimeImports(src({ 'a.ts': text }), RT)).toEqual([]);
|
|
198
198
|
});
|
|
199
199
|
});
|
|
200
|
+
|
|
201
|
+
describe('lintRuntimeImports: a large export list is cut', () => {
|
|
202
|
+
// mathjs exports over a thousand names: listing them all would bury the fix.
|
|
203
|
+
const big = Array.from({ length: 1200 }, (_, i) => `fn${i}`).concat(['evaluate', 'evaluateAll']);
|
|
204
|
+
const runtime = { ...RT, mathjs: big };
|
|
205
|
+
|
|
206
|
+
it('names the close matches first, then cuts the list', () => {
|
|
207
|
+
const msgs = lintRuntimeImports(
|
|
208
|
+
src({ 'a.ts': "import { evalute } from 'mathjs';\n" }),
|
|
209
|
+
runtime,
|
|
210
|
+
);
|
|
211
|
+
expect(msgs).toHaveLength(1);
|
|
212
|
+
const text = msgs[0]!.text;
|
|
213
|
+
expect(text).toContain("'mathjs' does not export 'evalute'");
|
|
214
|
+
expect(text).toContain('and 1142 more');
|
|
215
|
+
expect(text.length).toBeLessThan(1200);
|
|
216
|
+
const misspelt = lintRuntimeImports(
|
|
217
|
+
src({ 'a.ts': "import { evaluat } from 'mathjs';\n" }),
|
|
218
|
+
runtime,
|
|
219
|
+
);
|
|
220
|
+
expect(misspelt[0]!.text).toMatch(/It exports: evaluate, evaluateAll, fn0/);
|
|
221
|
+
});
|
|
222
|
+
|
|
223
|
+
it('does not rank a one-letter export as close', () => {
|
|
224
|
+
const withE = { ...RT, mathjs: ['e', 'pi', ...big] };
|
|
225
|
+
const msgs = lintRuntimeImports(src({ 'a.ts': "import { nope } from 'mathjs';\n" }), withE);
|
|
226
|
+
expect(msgs[0]!.text).toMatch(/It exports: e, pi, fn0/);
|
|
227
|
+
const fmt = { ...RT, mathjs: [...big, 'format'] };
|
|
228
|
+
const held = lintRuntimeImports(src({ 'a.ts': "import { formatUnit } from 'mathjs';\n" }), fmt);
|
|
229
|
+
expect(held[0]!.text).toMatch(/It exports: format, fn0/);
|
|
230
|
+
});
|
|
231
|
+
|
|
232
|
+
it('keeps a short list whole', () => {
|
|
233
|
+
const msgs = lintRuntimeImports(src({ 'a.ts': "import host from '@host';\n" }), RT);
|
|
234
|
+
expect(msgs[0]!.text).not.toContain('more (');
|
|
235
|
+
});
|
|
236
|
+
});
|