@crossworks/app-build 0.400.45 → 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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/app-build",
3
- "version": "0.400.45",
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
- "@mantle/share-ui": "npm:@crossworks/share-ui@0.400.45",
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 { APP_CANVAS_LIBRARIES, APP_LIBRARY_SPECIFIERS, appCanvasLibraries } from './app-libraries';
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; the browser test checks the real build). */
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
  });
@@ -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 one exception is `motion/react`: Motion's React API imports React, so
12
- * it is built into the APP runtime against the one shared React
13
- * (build-runtime.ts), not taken from the canvas set, which has no React.
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 canvas-runtime module an app may import: the specifier as written in
20
- * app source, and the canvas_library guide that covers it. */
21
- export type AppLibrary = Readonly<{ specifier: string; guide: string }>;
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
- { specifier: 'three/addons/controls/OrbitControls.js', guide: 'three' },
31
- { specifier: 'konva', guide: 'konva' },
32
- { specifier: 'katex', guide: 'katex' },
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
- { specifier: '@mantle/diagram-templates/browser', guide: 'diagram-templates' },
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 AppLibrary[] = [
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
@@ -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 { appCanvasLibraries } from './app-libraries.ts';
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
@@ -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.join(', ')}. Left as-is the app builds but fails to load in the browser, with no error the app can catch.`,
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 { ZodType } from 'zod';",
129
- "import { type ZodType } from 'zod';",
130
- "export type { ZodType } from 'zod';",
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 { z } from 'zod'; console.log(z);",
139
- "import { type ZodType, z } from 'zod'; console.log(z);",
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 'zod' is not allowed in a mini app");
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
+ });