@wireweave/core 4.0.0-beta.0 → 4.0.0-beta.13

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.
Files changed (50) hide show
  1. package/README.md +17 -462
  2. package/dist/app.cjs +50 -0
  3. package/dist/app.d.cts +488 -0
  4. package/dist/app.d.ts +488 -0
  5. package/dist/app.js +1 -0
  6. package/dist/chunk-3RWGG5EC.js +18042 -0
  7. package/dist/chunk-4TMDPWPR.cjs +186 -0
  8. package/dist/chunk-4UZBGIGJ.cjs +4359 -0
  9. package/dist/chunk-5DGRIQDU.cjs +824 -0
  10. package/dist/chunk-ETV4XYOV.cjs +5 -0
  11. package/dist/chunk-FS6A6EJ4.js +4345 -0
  12. package/dist/chunk-IMUVIIJR.cjs +18051 -0
  13. package/dist/chunk-JJWAFHSV.js +821 -0
  14. package/dist/chunk-MD6MNOEQ.cjs +2884 -0
  15. package/dist/chunk-PKBMQBKP.js +5 -0
  16. package/dist/chunk-R5WBZWBC.js +180 -0
  17. package/dist/chunk-V3HVWC7C.js +2874 -0
  18. package/dist/chunk-XYACLXXF.js +51484 -0
  19. package/dist/chunk-ZPHNXJRY.cjs +51590 -0
  20. package/dist/index-BGU_4N4W.d.ts +240 -0
  21. package/dist/index-BlNYFaZd.d.cts +337 -0
  22. package/dist/index-Cx4-VXVS.d.ts +337 -0
  23. package/dist/index-DyXaMSgd.d.cts +240 -0
  24. package/dist/index.cjs +1844 -58238
  25. package/dist/index.d.cts +556 -102
  26. package/dist/index.d.ts +556 -102
  27. package/dist/index.js +1163 -58104
  28. package/dist/interaction.cjs +26 -0
  29. package/dist/interaction.d.cts +3 -0
  30. package/dist/interaction.d.ts +3 -0
  31. package/dist/interaction.js +1 -0
  32. package/dist/parser.cjs +34 -6611
  33. package/dist/parser.d.cts +11 -2
  34. package/dist/parser.d.ts +11 -2
  35. package/dist/parser.js +1 -6585
  36. package/dist/renderer.cjs +119 -50537
  37. package/dist/renderer.d.cts +348 -123
  38. package/dist/renderer.d.ts +348 -123
  39. package/dist/renderer.js +3 -50499
  40. package/dist/spec.cjs +94 -0
  41. package/dist/spec.d.cts +301 -0
  42. package/dist/spec.d.ts +301 -0
  43. package/dist/spec.js +1 -0
  44. package/dist/{types-hEr_afgw.d.cts → types-CGRi1k2N.d.cts} +307 -27
  45. package/dist/{types-hEr_afgw.d.ts → types-CGRi1k2N.d.ts} +307 -27
  46. package/dist/types-Dkgr0Wyc.d.cts +75 -0
  47. package/dist/types-Dkgr0Wyc.d.ts +75 -0
  48. package/dist/v4-types-2ORUg6To.d.cts +137 -0
  49. package/dist/v4-types-2ORUg6To.d.ts +137 -0
  50. package/package.json +112 -35
package/README.md CHANGED
@@ -1,476 +1,31 @@
1
- <p align="center">
2
- <img src="https://docs.wireweave.org/assets/wireweave-core.svg" width="128" height="128" alt="Wireweave Core">
3
- </p>
1
+ # @wireweave/core
4
2
 
5
- <h1 align="center">@wireweave/core</h1>
3
+ Wireweave is a concise UI wireframe language with deterministic parsing, reusable modules, canonical printing and neutral HTML/SVG rendering. Core compiles authored screens, state and interactions; people and programs can use it without an agent harness, account or hosted service.
6
4
 
7
- <p align="center">Core parser and renderers for Wireweave DSL</p>
5
+ ## Contract
8
6
 
9
- ## Installation
7
+ The language contract is [LANGUAGE](../../docs/spec/LANGUAGE.md), with formal syntax in [language.ebnf](../../docs/spec/language.ebnf), canonical data in [schema.json](../../docs/spec/schema.json), and positive/negative [examples](../../docs/spec/examples.json). [RUNTIME](../../docs/spec/RUNTIME.md) defines fixed viewports, native controls, route/history, fixture simulation, structured implementation obligations and standalone HTML. [TOOLING](../../docs/spec/TOOLING.md) defines library APIs, CLI/MCP/editor/markdown adapters and release validation.
10
8
 
11
- ```bash
12
- npm install @wireweave/core
13
- # or
14
- pnpm add @wireweave/core
15
- # or
16
- yarn add @wireweave/core
17
- ```
18
-
19
- ## Quick Start
9
+ The language and schema versions are explicit artifact inputs. Product claims are tied to the installed release's conformance manifest. A schema-valid example and a running browser artifact are different evidence.
20
10
 
21
- ```typescript
22
- import { parse, render, renderToSvg, renderToHtml } from '@wireweave/core';
11
+ ## Author a screen
23
12
 
24
- const source = `
25
- page "Hello" {
26
- card p=4 {
27
- title "Welcome"
28
- text "Hello, wireweave!"
29
- button "Get Started" primary
30
- }
13
+ ```wireframe
14
+ page "Contact" id=contact viewport="1440x900" {
15
+ main {
16
+ title "Contact" level=1
17
+ text "Choose how to contact the team."
18
+ link "Email" href="mailto:team@example.com"
31
19
  }
32
- `;
33
-
34
- // Parse DSL to AST
35
- const doc = parse(source);
36
-
37
- // Render to HTML + CSS
38
- const { html, css } = render(doc);
39
-
40
- // Render to complete HTML document
41
- const fullHtml = renderToHtml(doc);
42
-
43
- // Render to SVG
44
- const { svg, width, height } = renderToSvg(doc);
45
- ```
46
-
47
- ## API Reference
48
-
49
- ### Parser
50
-
51
- #### `parse(source: string): WireframeDocument`
52
-
53
- Parses wireframe DSL source code into an AST (Abstract Syntax Tree).
54
-
55
- ```typescript
56
- import { parse } from '@wireweave/core';
57
-
58
- const doc = parse('page { text "Hello" }');
59
- console.log(doc.children[0].type); // 'Page'
60
- ```
61
-
62
- **Throws**: `ParseError` if the source contains syntax errors.
63
-
64
- ### HTML Renderer
65
-
66
- #### `render(doc: WireframeDocument, options?: RenderOptions): RenderResult`
67
-
68
- Renders the AST to HTML and CSS.
69
-
70
- ```typescript
71
- import { parse, render } from '@wireweave/core';
72
-
73
- const doc = parse('page { card { text "Hello" } }');
74
- const { html, css } = render(doc);
75
- ```
76
-
77
- **Options**:
78
- | Option | Type | Default | Description |
79
- |--------|------|---------|-------------|
80
- | `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
81
-
82
- **Returns**: `{ html: string, css: string }`
83
-
84
- #### `renderToHtml(doc: WireframeDocument, options?: RenderOptions): string`
85
-
86
- Renders the AST to a complete HTML document with embedded CSS.
87
-
88
- ```typescript
89
- import { parse, renderToHtml } from '@wireweave/core';
90
-
91
- const doc = parse('page "Test" { text "Hello" }');
92
- const html = renderToHtml(doc, { theme: 'dark' });
93
- // Returns: <!DOCTYPE html><html>...</html>
94
- ```
95
-
96
- ### SVG Renderer
97
-
98
- #### `renderToSvg(doc: WireframeDocument, options?: SvgRenderOptions): SvgRenderResult`
99
-
100
- Renders the AST to SVG format.
101
-
102
- ```typescript
103
- import { parse, renderToSvg } from '@wireweave/core';
104
-
105
- const doc = parse('page { button "Click" primary }');
106
- const { svg, width, height } = renderToSvg(doc, {
107
- width: 800,
108
- padding: 20
109
- });
110
- ```
111
-
112
- **Options**:
113
- | Option | Type | Default | Description |
114
- |--------|------|---------|-------------|
115
- | `width` | `number` | `1200` | SVG width in pixels |
116
- | `padding` | `number` | `24` | Padding around content |
117
- | `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
118
-
119
- **Returns**: `{ svg: string, width: number, height: number }`
120
-
121
- ### Analysis
122
-
123
- #### `analyze(doc: WireframeDocument, options?: AnalysisOptions): AnalysisResult`
124
-
125
- Analyzes a wireframe document and returns comprehensive statistics.
126
-
127
- ```typescript
128
- import { parse, analyze } from '@wireweave/core';
129
-
130
- const doc = parse('page { card { text "Hello" button "Click" } }');
131
- const result = analyze(doc);
132
-
133
- console.log(result.summary);
134
- // { totalComponents: 4, uniqueTypes: 4, mostUsedType: 'Page', ... }
135
-
136
- console.log(result.tree);
137
- // { totalNodes: 4, maxDepth: 3, avgDepth: 2, ... }
138
-
139
- console.log(result.accessibility);
140
- // { score: 100, imagesWithAlt: 0, inputsWithLabels: 0, ... }
141
-
142
- console.log(result.complexity);
143
- // { score: 2, level: 'simple', interactiveElements: 1, ... }
144
- ```
145
-
146
- **Options**:
147
- | Option | Type | Default | Description |
148
- |--------|------|---------|-------------|
149
- | `includeComponentBreakdown` | `boolean` | `true` | Include component statistics |
150
- | `includeAccessibility` | `boolean` | `true` | Include accessibility metrics |
151
- | `includeComplexity` | `boolean` | `true` | Include complexity analysis |
152
- | `includeLayout` | `boolean` | `true` | Include layout analysis |
153
- | `includeContent` | `boolean` | `true` | Include content analysis |
154
-
155
- ### Diff (Document Comparison)
156
-
157
- #### `diff(oldDoc: WireframeDocument, newDoc: WireframeDocument, options?: DiffOptions): DiffResult`
158
-
159
- Compares two wireframe documents and returns detailed differences.
160
-
161
- ```typescript
162
- import { parse, diff } from '@wireweave/core';
163
-
164
- const oldDoc = parse('page { text "Hello" }');
165
- const newDoc = parse('page { text "Hello" button "Click" }');
166
-
167
- const result = diff(oldDoc, newDoc);
168
-
169
- console.log(result.identical); // false
170
- console.log(result.description); // "Added 1 component(s): Button."
171
- console.log(result.summary);
172
- // { addedCount: 1, removedCount: 0, changedCount: 0, ... }
173
- ```
174
-
175
- #### `areIdentical(oldDoc: WireframeDocument, newDoc: WireframeDocument): boolean`
176
-
177
- Quick check if two documents are identical.
178
-
179
- ```typescript
180
- import { parse, areIdentical } from '@wireweave/core';
181
-
182
- const doc1 = parse('page { text "Hello" }');
183
- const doc2 = parse('page { text "Hello" }');
184
-
185
- console.log(areIdentical(doc1, doc2)); // true
186
- ```
187
-
188
- #### `getChangeSummary(oldDoc: WireframeDocument, newDoc: WireframeDocument): string`
189
-
190
- Returns a human-readable summary of changes.
191
-
192
- ```typescript
193
- import { parse, getChangeSummary } from '@wireweave/core';
194
-
195
- const oldDoc = parse('page { text "A" }');
196
- const newDoc = parse('page { text "B" }');
197
-
198
- console.log(getChangeSummary(oldDoc, newDoc));
199
- // "Modified 1 component(s)."
200
- ```
201
-
202
- ### Export
203
-
204
- #### `exportToJson(doc: WireframeDocument, options?: ExportOptions): JsonExportResult`
205
-
206
- Exports wireframe to JSON format.
207
-
208
- ```typescript
209
- import { parse, exportToJson } from '@wireweave/core';
210
-
211
- const doc = parse('page { card { text "Hello" } }');
212
- const result = exportToJson(doc);
213
-
214
- console.log(result.version); // "1.0.0"
215
- console.log(result.pages); // [{ type: 'page', children: [...] }]
216
- console.log(result.metadata);
217
- // { exportedAt: '...', nodeCount: 3, componentTypes: ['card', 'page', 'text'] }
218
- ```
219
-
220
- #### `exportToJsonString(doc: WireframeDocument, options?: ExportOptions): string`
221
-
222
- Exports wireframe to JSON string.
223
-
224
- ```typescript
225
- import { parse, exportToJsonString } from '@wireweave/core';
226
-
227
- const doc = parse('page { text "Hello" }');
228
- const json = exportToJsonString(doc, { prettyPrint: true });
229
- ```
230
-
231
- #### `exportToFigma(doc: WireframeDocument): FigmaExportResult`
232
-
233
- Exports wireframe to Figma-compatible format.
234
-
235
- ```typescript
236
- import { parse, exportToFigma } from '@wireweave/core';
237
-
238
- const doc = parse('page { card { text "Hello" } }');
239
- const result = exportToFigma(doc);
240
-
241
- console.log(result.document); // Figma-compatible node tree
242
- console.log(result.componentMappings);
243
- // { page: 'CANVAS', card: 'FRAME', text: 'TEXT' }
244
- ```
245
-
246
- ### AST Utilities
247
-
248
- #### `walk(node: ASTNode, callback: WalkCallback): void`
249
-
250
- Traverses the AST tree depth-first.
251
-
252
- ```typescript
253
- import { parse } from '@wireweave/core';
254
- import { walk } from '@wireweave/core/ast';
255
-
256
- const doc = parse('page { card { text "A" text "B" } }');
257
- walk(doc.children[0], (node, parent, depth) => {
258
- console.log(`${node.type} at depth ${depth}`);
259
- });
260
- ```
261
-
262
- #### `find(node: ASTNode, predicate: (n: ASTNode) => boolean): ASTNode | undefined`
263
-
264
- Finds the first node matching the predicate.
265
-
266
- ```typescript
267
- import { find } from '@wireweave/core/ast';
268
-
269
- const button = find(doc.children[0], n => n.type === 'Button');
270
- ```
271
-
272
- #### `findAll(node: ASTNode, predicate: (n: ASTNode) => boolean): ASTNode[]`
273
-
274
- Finds all nodes matching the predicate.
275
-
276
- ```typescript
277
- import { findAll } from '@wireweave/core/ast';
278
-
279
- const buttons = findAll(doc.children[0], n => n.type === 'Button');
280
- ```
281
-
282
- #### `findByType<T>(node: ASTNode, type: string): T[]`
283
-
284
- Finds all nodes of a specific type.
285
-
286
- ```typescript
287
- import { findByType } from '@wireweave/core/ast';
288
- import type { ButtonNode } from '@wireweave/core';
289
-
290
- const buttons = findByType<ButtonNode>(doc.children[0], 'Button');
291
- ```
292
-
293
- #### `countNodes(node: ASTNode): number`
294
-
295
- Counts all nodes in the tree.
296
-
297
- #### `getMaxDepth(node: ASTNode): number`
298
-
299
- Returns the maximum nesting depth.
300
-
301
- #### `cloneNode<T>(node: T): T`
302
-
303
- Creates a deep copy of a node.
304
-
305
- ## Type Definitions
306
-
307
- ### WireframeDocument
308
-
309
- ```typescript
310
- interface WireframeDocument {
311
- type: 'Document';
312
- children: PageNode[];
313
- }
314
- ```
315
-
316
- ### PageNode
317
-
318
- ```typescript
319
- interface PageNode {
320
- type: 'Page';
321
- title?: string;
322
- children: ASTNode[];
323
- // ... spacing attributes
324
- }
325
- ```
326
-
327
- ### Common Node Properties
328
-
329
- All nodes include:
330
- - `type: string` - Node type (e.g., 'Button', 'Card')
331
- - `location?: Location` - Source location info
332
- - Spacing: `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl`, `m`, `mx`, `my`, `mt`, `mr`, `mb`, `ml`
333
- - Size: `w`, `h`
334
-
335
- ### Component-Specific Properties
336
-
337
- ```typescript
338
- // Button
339
- interface ButtonNode {
340
- type: 'Button';
341
- content: string;
342
- primary?: boolean;
343
- secondary?: boolean;
344
- outline?: boolean;
345
- ghost?: boolean;
346
- danger?: boolean;
347
- disabled?: boolean;
348
- }
349
-
350
- // Input
351
- interface InputNode {
352
- type: 'Input';
353
- label?: string;
354
- placeholder?: string;
355
- inputType?: 'text' | 'email' | 'password' | 'search' | 'tel' | 'url' | 'number';
356
- required?: boolean;
357
- disabled?: boolean;
358
20
  }
359
-
360
- // Card
361
- interface CardNode {
362
- type: 'Card';
363
- title?: string;
364
- children: ASTNode[];
365
- }
366
-
367
- // Col
368
- interface ColNode {
369
- type: 'Col';
370
- span?: number;
371
- sm?: number;
372
- md?: number;
373
- lg?: number;
374
- xl?: number;
375
- children: ASTNode[];
376
- }
377
- ```
378
-
379
- ## DSL Syntax Reference
380
-
381
- ### Page Structure
382
-
383
- ```
384
- page "Title" {
385
- header { }
386
- main { }
387
- footer { }
388
- sidebar { }
389
- aside { }
390
- }
391
- ```
392
-
393
- ### Layout
394
-
395
- ```
396
- // Grid columns (12-column system)
397
- row {
398
- col span=6 { } // 50% width
399
- col span=6 { } // 50% width
400
- }
401
-
402
- // Responsive breakpoints
403
- col span=12 sm=6 md=4 lg=3 xl=2 { }
404
-
405
- // Flexbox
406
- row flex justify=center align=center gap=4 wrap { }
407
- // justify: start, end, center, between, around, evenly
408
- // align: start, end, center, stretch, baseline
409
- // direction: row, row-reverse, column, column-reverse
410
- ```
411
-
412
- ### Spacing Scale
413
-
414
- Values use a 4px base: `1 = 4px`, `2 = 8px`, `4 = 16px`, etc.
415
-
416
21
  ```
417
- card p=4 m=2 { } // padding: 16px, margin: 8px
418
- button mt=4 mb=2 // margin-top: 16px, margin-bottom: 8px
419
- ```
420
-
421
- ### Size
422
-
423
- ```
424
- image w=400 h=300 // width: 400px, height: 300px
425
- card w=full // width: 100%
426
- ```
427
-
428
- ### Comments
429
22
 
430
- ```
431
- // Single line comment
432
-
433
- /* Multi-line
434
- comment */
435
-
436
- page {
437
- // Comment inside block
438
- text "Hello"
439
- }
440
- ```
23
+ A multi-screen app declares an entry and modules. Internal links use screen IDs, state has app/shell/screen/component scope, shared structure uses layout/component/slot, and externally implemented effects remain typed obligations. Core preserves the same meaning across canvas, executable HTML and machine-readable handoff.
441
24
 
442
- ## Error Handling
25
+ ## Install and validate
443
26
 
444
- ```typescript
445
- import { parse } from '@wireweave/core';
446
-
447
- try {
448
- const doc = parse('page { invalid }');
449
- } catch (error) {
450
- if (error.name === 'ParseError') {
451
- console.log(error.message);
452
- // "Syntax error at line 1, column 8: ..."
453
- console.log(error.location);
454
- // { start: { line: 1, column: 8 }, end: { ... } }
455
- }
456
- }
457
- ```
458
-
459
- ## Browser Support
460
-
461
- The core library works in both Node.js and browser environments. For browser usage:
462
-
463
- ```html
464
- <script type="module">
465
- import { parse, render } from '@wireweave/core';
466
-
467
- const doc = parse('page { text "Hello" }');
468
- const { html, css } = render(doc);
469
-
470
- document.body.innerHTML = `<style>${css}</style>${html}`;
471
- </script>
472
- ```
27
+ Install the Core version pinned by the consuming project's toolchain profile with `npm install @wireweave/core@<version>`. ESM/CJS and typed subpaths are described in the tool contract. Core itself performs no account, filesystem or network operations.
473
28
 
474
- ## License
29
+ Library code is checked with typecheck, lint, generated parser/catalog checks, unit tests and browser conformance. Contract data is checked against Draft 2020-12 JSON Schema and semantic fixtures. The public tool surface includes parse/print, link/compile, fragment/canvas/SVG, validation, transition extraction, analysis, diff, export and traversal; their inputs, failures and execution scope have one definition in TOOLING.
475
30
 
476
- MIT
31
+ MIT license. Part of the Wireweave public monorepo.
package/dist/app.cjs ADDED
@@ -0,0 +1,50 @@
1
+ 'use strict';
2
+
3
+ var chunk4UZBGIGJ_cjs = require('./chunk-4UZBGIGJ.cjs');
4
+
5
+
6
+
7
+ Object.defineProperty(exports, "advanceClock", {
8
+ enumerable: true,
9
+ get: function () { return chunk4UZBGIGJ_cjs.advanceClock; }
10
+ });
11
+ Object.defineProperty(exports, "compileApp", {
12
+ enumerable: true,
13
+ get: function () { return chunk4UZBGIGJ_cjs.compileApp; }
14
+ });
15
+ Object.defineProperty(exports, "createAppBundle", {
16
+ enumerable: true,
17
+ get: function () { return chunk4UZBGIGJ_cjs.createAppBundle; }
18
+ });
19
+ Object.defineProperty(exports, "createAppComponentInstanceId", {
20
+ enumerable: true,
21
+ get: function () { return chunk4UZBGIGJ_cjs.createAppComponentInstanceId; }
22
+ });
23
+ Object.defineProperty(exports, "createAppNodeId", {
24
+ enumerable: true,
25
+ get: function () { return chunk4UZBGIGJ_cjs.createAppNodeId; }
26
+ });
27
+ Object.defineProperty(exports, "createRuntime", {
28
+ enumerable: true,
29
+ get: function () { return chunk4UZBGIGJ_cjs.createRuntime; }
30
+ });
31
+ Object.defineProperty(exports, "linkAndCompileApp", {
32
+ enumerable: true,
33
+ get: function () { return chunk4UZBGIGJ_cjs.linkAndCompileApp; }
34
+ });
35
+ Object.defineProperty(exports, "linkApp", {
36
+ enumerable: true,
37
+ get: function () { return chunk4UZBGIGJ_cjs.linkApp; }
38
+ });
39
+ Object.defineProperty(exports, "reduceEvent", {
40
+ enumerable: true,
41
+ get: function () { return chunk4UZBGIGJ_cjs.reduceEvent; }
42
+ });
43
+ Object.defineProperty(exports, "renderSite", {
44
+ enumerable: true,
45
+ get: function () { return chunk4UZBGIGJ_cjs.renderSite; }
46
+ });
47
+ Object.defineProperty(exports, "resetRuntime", {
48
+ enumerable: true,
49
+ get: function () { return chunk4UZBGIGJ_cjs.resetRuntime; }
50
+ });