@wireweave/core 3.1.0-beta.9 → 4.0.0-beta.12

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 -126
  2. package/dist/app.cjs +31 -0
  3. package/dist/app.d.cts +488 -0
  4. package/dist/app.d.ts +488 -0
  5. package/dist/app.js +31 -0
  6. package/dist/chunk-3RWGG5EC.js +18088 -0
  7. package/dist/chunk-4TMDPWPR.cjs +196 -0
  8. package/dist/chunk-5DGRIQDU.cjs +842 -0
  9. package/dist/chunk-7VTK6LHL.cjs +4374 -0
  10. package/dist/chunk-ETV4XYOV.cjs +7 -0
  11. package/dist/chunk-IMUVIIJR.cjs +18088 -0
  12. package/dist/chunk-JJWAFHSV.js +842 -0
  13. package/dist/chunk-MD6MNOEQ.cjs +2905 -0
  14. package/dist/chunk-PKBMQBKP.js +7 -0
  15. package/dist/chunk-QOS4IC75.js +4374 -0
  16. package/dist/chunk-R5WBZWBC.js +196 -0
  17. package/dist/chunk-V3HVWC7C.js +2905 -0
  18. package/dist/chunk-WV724EAW.js +0 -0
  19. package/dist/chunk-XENFKHRC.cjs +1 -0
  20. package/dist/chunk-XYACLXXF.js +51612 -0
  21. package/dist/chunk-ZPHNXJRY.cjs +51612 -0
  22. package/dist/index-Br7pNaf3.d.cts +240 -0
  23. package/dist/index-CghCKUPx.d.ts +337 -0
  24. package/dist/index-Da_B3eoM.d.ts +240 -0
  25. package/dist/index-G906GEtg.d.cts +337 -0
  26. package/dist/index.cjs +963 -64577
  27. package/dist/index.d.cts +13 -522
  28. package/dist/index.d.ts +13 -522
  29. package/dist/index.js +711 -64118
  30. package/dist/interaction.cjs +17 -0
  31. package/dist/interaction.d.cts +3 -0
  32. package/dist/interaction.d.ts +3 -0
  33. package/dist/interaction.js +17 -0
  34. package/dist/parser.cjs +18 -7832
  35. package/dist/parser.d.cts +10 -1
  36. package/dist/parser.d.ts +10 -1
  37. package/dist/parser.js +16 -7800
  38. package/dist/renderer.cjs +7 -53162
  39. package/dist/renderer.d.cts +19 -239
  40. package/dist/renderer.d.ts +19 -239
  41. package/dist/renderer.js +37 -53137
  42. package/dist/spec.cjs +42 -2883
  43. package/dist/spec.d.cts +4 -75
  44. package/dist/spec.d.ts +4 -75
  45. package/dist/spec.js +25 -2818
  46. package/dist/types-Dkgr0Wyc.d.cts +75 -0
  47. package/dist/types-Dkgr0Wyc.d.ts +75 -0
  48. package/dist/v4-types-Baz9yqAS.d.cts +137 -0
  49. package/dist/v4-types-Baz9yqAS.d.ts +137 -0
  50. package/package.json +22 -1
package/README.md CHANGED
@@ -1,140 +1,31 @@
1
1
  # @wireweave/core
2
2
 
3
- The parser and renderer for the Wireweave wireframe DSL.
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.
4
4
 
5
- ## What it does
5
+ ## Contract
6
6
 
7
- `@wireweave/core` turns Wireweave's text-based DSL into an AST and back into visual output. It provides:
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.
8
8
 
9
- - **Parser** — a Peggy-generated parser that converts `.wf` / `.wireframe` source into a typed AST, with strict and error-recovering modes.
10
- - **Renderers** — render the AST to HTML+CSS, a standalone HTML document, or SVG. Multi-page documents are auto-composed onto a bounded canvas; single-page documents render in legacy single-board mode.
11
- - **Multi-page canvas** — `.wf` supports multiple pages positioned on a canvas (`page "..." at(x, y)`) with per-page `viewport` / `device` presets.
12
- - **AST utilities** — type guards and traversal helpers (`walkDocument`, `find`, `findByType`, …).
13
- - **Validation** — check AST nodes against the DSL specification.
14
- - **Diff** — structurally compare two documents.
15
- - **Export** — convert the AST to JSON or a Figma-compatible structure.
16
- - **Analyze** — compute statistics plus accessibility, complexity, layout, and content metrics.
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.
17
10
 
18
- ## Install
11
+ ## Author a screen
19
12
 
20
- ```bash
21
- npm i @wireweave/core
22
- ```
23
-
24
- ## Usage
25
-
26
- ```typescript
27
- import { parse, render, renderToHtml, renderToSvg } from '@wireweave/core'
28
-
29
- const source = `
30
- page "Home" {
31
- card p=4 {
32
- title "Welcome"
33
- text "Hello, Wireweave!"
34
- button "Get Started" primary
35
- }
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"
36
19
  }
37
- `
38
-
39
- // Parse DSL into an AST
40
- const doc = parse(source)
41
-
42
- // Render to HTML fragment + CSS
43
- const { html, css } = render(doc)
44
-
45
- // Render to a standalone HTML document
46
- const fullHtml = renderToHtml(doc)
47
-
48
- // Render to SVG (multi-page docs auto-compose onto a canvas)
49
- const { svg, width, height } = renderToSvg(doc)
20
+ }
50
21
  ```
51
22
 
52
- ### Multi-page canvas
53
-
54
- ```typescript
55
- const doc = parse(`
56
- page "Login" at(0, 0) viewport=mobile {
57
- button "Sign in" primary
58
- }
59
- page "Home" at(420, 0) viewport=mobile {
60
- text "Welcome back"
61
- }
62
- `)
63
-
64
- const { svg } = renderToSvg(doc) // viewBox sized to the canvas bounding box
65
- ```
66
-
67
- ### Analyze, diff, and export
68
-
69
- ```typescript
70
- import { parse, analyze, diff, exportToJson, exportToFigma } from '@wireweave/core'
71
-
72
- const a = parse(sourceA)
73
- const b = parse(sourceB)
74
-
75
- const stats = analyze(a) // totals, accessibility score, complexity, layout, content
76
- const changes = diff(a, b) // added / removed / changed / moved nodes
77
- const json = exportToJson(a) // serializable AST
78
- const figma = exportToFigma(a) // Figma-compatible node tree
79
- ```
80
-
81
- ### Print back to canonical DSL
82
-
83
- ```typescript
84
- import { parse, printWireframe, formatWireframeCode } from '@wireweave/core'
85
-
86
- const doc = parse(source)
87
- const canonical = printWireframe(doc) // deterministic canonical `.wf` text
88
- const formatted = formatWireframeCode(source) // parse + reprint in one step
89
- ```
90
-
91
- The printer emits a single canonical form (fixed indentation, attribute
92
- ordering, quoting, blank-line policy) with round-trip guarantees:
93
- `parse(printWireframe(doc))` is structurally equivalent to `doc`, printing is
94
- idempotent, and already-canonical text reprints byte-identical. Comments are
95
- not preserved (the parser drops them before the AST).
96
-
97
- ### Walk the AST
98
-
99
- ```typescript
100
- import { parse, walkDocument, findByType, isButtonNode } from '@wireweave/core'
101
-
102
- const doc = parse(source)
103
-
104
- walkDocument(doc, (node) => {
105
- if (isButtonNode(node)) {
106
- console.log(node.content)
107
- }
108
- })
109
-
110
- const buttons = findByType(doc.children[0], 'Button')
111
- ```
112
-
113
- ## Main API
114
-
115
- | Export | Description |
116
- | --------------------------------------------------------------- | --------------------------------------------------------------------------- |
117
- | `parse(source, options?)` | Parse DSL into a `WireframeDocument`; throws `ParseError` on syntax errors. |
118
- | `tryParse` / `isValid` / `getErrors` | Error-recovering parse, boolean check, and error list. |
119
- | `printWireframe` / `formatWireframeCode` | Canonical `.wf` printer — AST → deterministic DSL text (round-trip safe). |
120
- | `render(doc, options?)` | Render to `{ html, css }`. Auto canvas mode for multi-page docs. |
121
- | `renderToHtml(doc, options?)` | Render to a complete standalone HTML document string. |
122
- | `renderToSvg(doc, options?)` | Render to `{ svg, width, height }` using `foreignObject` (HTML+CSS in SVG). |
123
- | `renderPage` / `renderCanvas` / `layoutCanvas` | Explicit single-page / multi-page composition primitives. |
124
- | `validate` / `isValidAst` / `getValidationErrors` | Validate AST nodes against the DSL spec. |
125
- | `analyze(doc, options?)` | Statistics plus accessibility, complexity, layout, and content metrics. |
126
- | `diff(oldDoc, newDoc, options?)` | Structural diff; also `areIdentical`, `getChangeSummary`. |
127
- | `exportToJson` / `importFromJson` / `exportToFigma` | Format conversion to/from JSON and to Figma. |
128
- | `walkDocument` / `walk` / `find` / `findAll` / `findByType` | AST traversal helpers. |
129
- | `resolveViewport` / `DEVICE_PRESETS` / `wrapInPreviewContainer` | Viewport sizing, device presets, preview scaling. |
130
- | AST types + `is*` guards | `WireframeDocument`, `AnyNode`, node types, and type guards. |
131
-
132
- Subpath entries are available for `@wireweave/core/parser` and `@wireweave/core/renderer`.
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.
133
24
 
134
- The build runs `build:grammar` (Peggy) before the TypeScript build to regenerate the parser from `src/grammar/wireframe.peggy`.
25
+ ## Install and validate
135
26
 
136
- Part of the [Wireweave monorepo](https://github.com/wireweave/wireweave).
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.
137
28
 
138
- ## 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.
139
30
 
140
- MIT
31
+ MIT license. Part of the Wireweave public monorepo.
package/dist/app.cjs ADDED
@@ -0,0 +1,31 @@
1
+ "use strict";Object.defineProperty(exports, "__esModule", {value: true});
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
13
+ var _chunk7VTK6LHLcjs = require('./chunk-7VTK6LHL.cjs');
14
+ require('./chunk-IMUVIIJR.cjs');
15
+ require('./chunk-5DGRIQDU.cjs');
16
+ require('./chunk-ZPHNXJRY.cjs');
17
+ require('./chunk-MD6MNOEQ.cjs');
18
+ require('./chunk-ETV4XYOV.cjs');
19
+
20
+
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+
30
+
31
+ exports.advanceClock = _chunk7VTK6LHLcjs.advanceClock; exports.compileApp = _chunk7VTK6LHLcjs.compileApp; exports.createAppBundle = _chunk7VTK6LHLcjs.createAppBundle; exports.createAppComponentInstanceId = _chunk7VTK6LHLcjs.createAppComponentInstanceId; exports.createAppNodeId = _chunk7VTK6LHLcjs.createAppNodeId; exports.createRuntime = _chunk7VTK6LHLcjs.createRuntime; exports.linkAndCompileApp = _chunk7VTK6LHLcjs.linkAndCompileApp; exports.linkApp = _chunk7VTK6LHLcjs.linkApp; exports.reduceEvent = _chunk7VTK6LHLcjs.reduceEvent; exports.renderSite = _chunk7VTK6LHLcjs.renderSite; exports.resetRuntime = _chunk7VTK6LHLcjs.resetRuntime;
package/dist/app.d.cts ADDED
@@ -0,0 +1,488 @@
1
+ import { aK as SourceLocation, aa as LayoutDefinitionNode, z as ComponentDefinitionNode, as as PageNode } from './types-vhPCZpAW.cjs';
2
+ import { J as JsonObject, k as V4SourceSpan, P as ParsedDocument, a as CanonicalModule, g as JsonValue } from './v4-types-Baz9yqAS.cjs';
3
+ import { S as SiteOptions } from './index-Br7pNaf3.cjs';
4
+
5
+ /** A source file and exact span within it. */
6
+ interface AppSourceSpan {
7
+ sourceId: string;
8
+ location: SourceLocation;
9
+ }
10
+ /** The two reusable definition kinds addressable by an app reference. */
11
+ type AppDefinitionKind = 'layout' | 'component';
12
+ /** Every stable, top-level node kind in a linked application. */
13
+ type AppNodeKind = AppDefinitionKind | 'screen';
14
+ /** A manifest entry assigning one module its stable application namespace. */
15
+ interface AppManifestModule {
16
+ id: string;
17
+ namespace: string;
18
+ location: SourceLocation;
19
+ }
20
+ /**
21
+ * Core-owned manifest describing the modules that make up one application.
22
+ * @public
23
+ */
24
+ interface AppManifest {
25
+ id: string;
26
+ sourceId: string;
27
+ modules: readonly AppManifestModule[];
28
+ }
29
+ /** A reference to a layout or component, local to the owner namespace by default. */
30
+ interface AppReferenceInput {
31
+ kind: AppDefinitionKind;
32
+ id: string;
33
+ namespace?: string;
34
+ source: AppSourceSpan;
35
+ }
36
+ interface AppNodeInput<TNode> {
37
+ /** Stable identifier within the module namespace and node kind. */
38
+ id: string;
39
+ node: TNode;
40
+ source: AppSourceSpan;
41
+ }
42
+ /** A layout declaration and the reusable definitions it depends on. */
43
+ interface AppLayoutInput extends AppNodeInput<LayoutDefinitionNode> {
44
+ references?: readonly AppReferenceInput[];
45
+ }
46
+ /** A component declaration and the reusable definitions it depends on. */
47
+ interface AppComponentInput extends AppNodeInput<ComponentDefinitionNode> {
48
+ references?: readonly AppReferenceInput[];
49
+ }
50
+ /** A screen declaration and the layouts/components it consumes. */
51
+ interface AppScreenInput extends AppNodeInput<PageNode> {
52
+ references?: readonly AppReferenceInput[];
53
+ }
54
+ /**
55
+ * One parsed Wireweave module supplied to the Core linker.
56
+ * @public
57
+ */
58
+ interface AppModuleInput {
59
+ id: string;
60
+ source: AppSourceSpan;
61
+ layouts: readonly AppLayoutInput[];
62
+ components: readonly AppComponentInput[];
63
+ screens: readonly AppScreenInput[];
64
+ }
65
+ /** Opaque stable identity assigned by the linker. */
66
+ type AppNodeId = string & {
67
+ readonly __appNodeId: unique symbol;
68
+ };
69
+ /** Stable identity of one expanded component invocation. */
70
+ type AppComponentInstanceId = string & {
71
+ readonly __appComponentInstanceId: unique symbol;
72
+ };
73
+ /** A reference whose target has been resolved to stable app identity. */
74
+ interface ResolvedAppReference {
75
+ kind: AppDefinitionKind;
76
+ id: string;
77
+ namespace: string;
78
+ targetId: AppNodeId;
79
+ source: AppSourceSpan;
80
+ }
81
+ interface ResolvedAppNode<TKind extends AppNodeKind, TNode> {
82
+ nodeId: AppNodeId;
83
+ kind: TKind;
84
+ id: string;
85
+ moduleId: string;
86
+ namespace: string;
87
+ node: TNode;
88
+ source: AppSourceSpan;
89
+ references: readonly ResolvedAppReference[];
90
+ }
91
+ type ResolvedAppLayout = ResolvedAppNode<'layout', LayoutDefinitionNode>;
92
+ type ResolvedAppComponent = ResolvedAppNode<'component', ComponentDefinitionNode>;
93
+ type ResolvedAppScreen = ResolvedAppNode<'screen', PageNode>;
94
+ /** Stable node-to-source mapping emitted in manifest order. */
95
+ interface AppSourceMapEntry {
96
+ nodeId: AppNodeId;
97
+ source: AppSourceSpan;
98
+ }
99
+ /** One resolved module in a linked application document. */
100
+ interface ResolvedAppModule {
101
+ id: string;
102
+ namespace: string;
103
+ layouts: readonly ResolvedAppLayout[];
104
+ components: readonly ResolvedAppComponent[];
105
+ screens: readonly ResolvedAppScreen[];
106
+ }
107
+ /**
108
+ * Core's dependency-closed representation of a multi-module application.
109
+ * @public
110
+ */
111
+ interface AppDocument {
112
+ type: 'AppDocument';
113
+ id: string;
114
+ modules: readonly ResolvedAppModule[];
115
+ layouts: readonly ResolvedAppLayout[];
116
+ components: readonly ResolvedAppComponent[];
117
+ screens: readonly ResolvedAppScreen[];
118
+ sourceMap: readonly AppSourceMapEntry[];
119
+ }
120
+ /** Stable machine-readable linker diagnostic kinds. */
121
+ type AppLinkDiagnosticCode = 'missing-module' | 'duplicate-module' | 'duplicate-namespace' | 'duplicate-definition' | 'duplicate-screen' | 'missing-reference' | 'cyclic-reference' | 'invalid-component-definition' | 'invalid-component-invocation';
122
+ /**
123
+ * A deterministic linker failure with the exact source span that caused it.
124
+ * @public
125
+ */
126
+ interface AppLinkDiagnostic {
127
+ code: AppLinkDiagnosticCode;
128
+ message: string;
129
+ source: AppSourceSpan;
130
+ }
131
+ type AppLinkResult = {
132
+ ok: true;
133
+ document: AppDocument;
134
+ diagnostics: readonly [];
135
+ } | {
136
+ ok: false;
137
+ document: null;
138
+ diagnostics: readonly AppLinkDiagnostic[];
139
+ };
140
+
141
+ interface Diagnostic {
142
+ severity: 'error';
143
+ code: string;
144
+ phase: 'schema' | 'import' | 'link' | 'compile';
145
+ sourceId: string;
146
+ start: number;
147
+ end: number;
148
+ path: string;
149
+ messageKey: string;
150
+ details: JsonObject;
151
+ related: {
152
+ sourceId: string;
153
+ start: number;
154
+ end: number;
155
+ }[];
156
+ }
157
+ type AppResult<T> = {
158
+ ok: true;
159
+ value: T;
160
+ diagnostics: readonly [];
161
+ } | {
162
+ ok: false;
163
+ value: null;
164
+ html: null;
165
+ diagnostics: readonly Diagnostic[];
166
+ };
167
+ interface ScreenReference {
168
+ namespace: string;
169
+ id: string;
170
+ variant?: string;
171
+ }
172
+ interface CreateAppBundleOptions {
173
+ id: string;
174
+ entry: ScreenReference;
175
+ profile: JsonObject;
176
+ states: JsonObject[];
177
+ registry: ParsedDocument['registry'];
178
+ fixtures: JsonObject[];
179
+ /** Exact original module bytes. Source maps address these bytes as moduleId.wf. */
180
+ moduleSources: Readonly<Record<string, string>>;
181
+ }
182
+ declare const bundleBrand: unique symbol;
183
+ declare const linkedBrand: unique symbol;
184
+ interface AppBundle {
185
+ readonly [bundleBrand]: true;
186
+ readonly schemaVersion: '1.0.0';
187
+ readonly languageVersion: '4.0.0';
188
+ readonly id: string;
189
+ readonly entry: Readonly<ScreenReference>;
190
+ readonly profile: Readonly<JsonObject>;
191
+ readonly states: readonly JsonObject[];
192
+ readonly registry: Readonly<ParsedDocument['registry']>;
193
+ readonly fixtures: readonly JsonObject[];
194
+ readonly modules: readonly CanonicalModule[];
195
+ }
196
+ type InstanceStep = {
197
+ kind: 'use';
198
+ id: string;
199
+ } | {
200
+ kind: 'repeat';
201
+ id: string;
202
+ index: number;
203
+ };
204
+ interface LinkedIdentity {
205
+ namespace: string;
206
+ definitionKind: 'page' | 'layout' | 'component';
207
+ definitionId: string;
208
+ instanceRoot: {
209
+ kind: 'screen';
210
+ namespace: string;
211
+ id: string;
212
+ } | {
213
+ kind: 'shell';
214
+ namespace: string;
215
+ id: string;
216
+ profileDigest: string;
217
+ };
218
+ instancePath: InstanceStep[];
219
+ localId: string;
220
+ }
221
+ interface SourceMapEntry {
222
+ renderedId: string;
223
+ identity: LinkedIdentity;
224
+ moduleId: string;
225
+ source: Readonly<V4SourceSpan>;
226
+ invocationSources: readonly Readonly<V4SourceSpan>[];
227
+ requirementRefs: readonly string[];
228
+ obligationRefs: readonly string[];
229
+ operationIds: readonly string[];
230
+ }
231
+ interface LinkedApp {
232
+ readonly [linkedBrand]: true;
233
+ readonly kind: 'LinkedApp';
234
+ readonly languageVersion: '4.0.0';
235
+ readonly id: string;
236
+ readonly digest: string;
237
+ readonly sourceMap: readonly SourceMapEntry[];
238
+ }
239
+ interface AppArtifact {
240
+ readonly kind: 'AppArtifact';
241
+ readonly schemaVersion: '1.0.0';
242
+ readonly languageVersion: '4.0.0';
243
+ readonly html: string;
244
+ readonly mediaType: 'text/html';
245
+ readonly byteLength: number;
246
+ readonly digest: string;
247
+ readonly modelDigest: string;
248
+ readonly profileDigest: string;
249
+ readonly runtimeDigest: string;
250
+ readonly registryDigest: string;
251
+ readonly entry: Readonly<ScreenReference>;
252
+ readonly screenIndex: readonly {
253
+ route: ScreenReference;
254
+ renderedId: string;
255
+ }[];
256
+ readonly operationIndex: readonly {
257
+ renderedId: string;
258
+ handlerId: string;
259
+ operationId: string;
260
+ executionClass: string;
261
+ operation: JsonObject;
262
+ }[];
263
+ readonly diagnostics: readonly [];
264
+ readonly sourceMap: readonly SourceMapEntry[];
265
+ readonly manifest: {
266
+ readonly appId: string;
267
+ readonly modelDigest: string;
268
+ readonly profileDigest: string;
269
+ readonly registryDigest: string;
270
+ readonly htmlDigest: string;
271
+ readonly runtimeDigest: string;
272
+ readonly executionScope: 'standard-1';
273
+ readonly unsupportedOperations: readonly {
274
+ renderedId: string;
275
+ handlerId: string;
276
+ operationId: string;
277
+ }[];
278
+ };
279
+ }
280
+ declare function createAppBundle(documents: readonly ParsedDocument[], options: CreateAppBundleOptions): AppResult<AppBundle>;
281
+
282
+ /**
283
+ * Create the stable identity used by linked documents and source maps.
284
+ * Each segment is encoded so punctuation in authored identifiers cannot collide.
285
+ *
286
+ * @public
287
+ */
288
+ declare function createAppNodeId(namespace: string, kind: AppNodeKind, id: string): AppNodeId;
289
+ /** Create the stable identity of an invocation from its owner and structural path. */
290
+ declare function createAppComponentInstanceId(ownerId: AppNodeId, targetId: AppNodeId, path: readonly number[]): AppComponentInstanceId;
291
+ /**
292
+ * Link parsed Wireweave modules into one dependency-closed application document.
293
+ * The function is pure and returns no document whenever validation finds an error.
294
+ *
295
+ * @public
296
+ * @example
297
+ * `const result = linkApp(manifest, modules)`
298
+ */
299
+ declare function linkApp(bundle: AppBundle): AppResult<LinkedApp>;
300
+ declare function linkApp(manifest: AppManifest, modules: readonly AppModuleInput[]): AppLinkResult;
301
+
302
+ /**
303
+ * Options for {@link compileApp}.
304
+ *
305
+ * Application artifacts always use neutral annotation styling. The option is
306
+ * intentionally omitted here so every compiler caller gets the same wireframe
307
+ * presentation while legacy render entry points keep their historical default.
308
+ *
309
+ * @public
310
+ */
311
+ type CompileAppOptions = Omit<SiteOptions, 'annotationStyle'>;
312
+ /** Result of linking modules and compiling the resulting application. @public */
313
+ type AppCompileResult = {
314
+ ok: true;
315
+ document: AppDocument;
316
+ html: string;
317
+ diagnostics: readonly [];
318
+ } | {
319
+ ok: false;
320
+ document: null;
321
+ html: null;
322
+ diagnostics: readonly AppLinkDiagnostic[];
323
+ };
324
+ /**
325
+ * Compile one linked application into a deterministic, self-contained HTML document.
326
+ *
327
+ * The linker has already expanded component invocations and resolved shared
328
+ * layouts. This function only projects those resolved nodes into the generic
329
+ * site compositor, using stable app identities for layout names so modules
330
+ * cannot collide.
331
+ *
332
+ * @public
333
+ * @example
334
+ * `const html = compileApp(linked.document)`
335
+ */
336
+ declare function compileApp(document: LinkedApp): AppResult<AppArtifact>;
337
+ declare function compileApp(document: AppDocument, options?: CompileAppOptions): string;
338
+ /**
339
+ * Link application modules and compile them when linking succeeds.
340
+ *
341
+ * Linker diagnostics remain explicit and no partial HTML is emitted on failure.
342
+ *
343
+ * @public
344
+ * @example
345
+ * `const result = linkAndCompileApp(manifest, modules)`
346
+ */
347
+ declare function linkAndCompileApp(bundle: AppBundle): AppResult<AppArtifact>;
348
+ declare function linkAndCompileApp(manifest: AppManifest, modules: readonly AppModuleInput[], options?: CompileAppOptions): AppCompileResult;
349
+ type RuntimeInput = {
350
+ kind: 'event';
351
+ source: LinkedIdentity;
352
+ event: 'click' | 'input' | 'change' | 'submit' | 'keydown' | 'focus' | 'blur';
353
+ value?: JsonValue;
354
+ checked?: boolean;
355
+ key?: string;
356
+ } | {
357
+ kind: 'advanceClock';
358
+ deltaMs: number;
359
+ } | {
360
+ kind: 'address';
361
+ fragment: string;
362
+ } | {
363
+ kind: 'reset';
364
+ };
365
+ interface RuntimeOperation {
366
+ id: string;
367
+ executionClass: 'executable' | 'simulated' | 'specified';
368
+ effect: JsonObject;
369
+ after: string[];
370
+ onFailure: 'stop' | 'continue';
371
+ }
372
+ interface RuntimeTrace {
373
+ schemaVersion: '1.0.0';
374
+ appId: string;
375
+ modelDigest: string;
376
+ profileDigest: string;
377
+ sequence: number;
378
+ resetGeneration: number;
379
+ virtualTime: number;
380
+ route: ScreenReference | null;
381
+ source: LinkedIdentity | null;
382
+ renderedId: string | null;
383
+ handlerId: string | null;
384
+ operationId: string | null;
385
+ executionClass: string;
386
+ event: JsonObject;
387
+ stateDeltaDigest: string;
388
+ result: string;
389
+ diagnostic: string | null;
390
+ }
391
+ interface RuntimeControl {
392
+ value: JsonValue;
393
+ checked: boolean;
394
+ pending?: boolean;
395
+ }
396
+ interface RuntimeActivation {
397
+ id: number;
398
+ owner: string;
399
+ handlerId: string;
400
+ event: JsonObject;
401
+ index: number;
402
+ statuses: Record<string, string>;
403
+ }
404
+ interface RuntimeRequest {
405
+ id: string;
406
+ generation: number;
407
+ sequence: number;
408
+ activation: number;
409
+ owner: string;
410
+ operation: RuntimeOperation;
411
+ resultKey: string;
412
+ statusKey: string;
413
+ errorKey: string;
414
+ deadline: number;
415
+ responseAt: number;
416
+ outcome: string;
417
+ value: JsonValue;
418
+ }
419
+ interface RuntimeScheduled {
420
+ time: number;
421
+ priority: number;
422
+ sequence: number;
423
+ requestId: string;
424
+ generation: number;
425
+ owner: string;
426
+ operationId: string;
427
+ }
428
+ interface RuntimeQueued {
429
+ source: string;
430
+ event: JsonObject;
431
+ handlerId: string | null;
432
+ }
433
+ interface RuntimeBrowserEffect {
434
+ kind: 'push' | 'replace' | 'traverse' | 'compensate' | 'external';
435
+ fragment: string;
436
+ sequence: number;
437
+ delta: number;
438
+ }
439
+ interface RuntimeSnapshot {
440
+ modelDigest: string;
441
+ profileDigest: string;
442
+ resetGeneration: number;
443
+ virtualTime: number;
444
+ sequence: number;
445
+ requestSequence: number;
446
+ activationSequence: number;
447
+ states: Record<string, JsonValue>;
448
+ controls: Record<string, RuntimeControl>;
449
+ invalid: Record<string, string>;
450
+ route: ScreenReference | null;
451
+ address: string;
452
+ history: {
453
+ fragment: string;
454
+ sequence: number;
455
+ }[];
456
+ historyIndex: number;
457
+ nextHistorySequence: number;
458
+ overlays: {
459
+ id: string;
460
+ opener: string | null;
461
+ modal: boolean;
462
+ }[];
463
+ focus: string | null;
464
+ selection: Record<string, number>;
465
+ expanded: Record<string, boolean>;
466
+ viewMode: 'fixed' | 'accessible';
467
+ fixtureCursors: Record<string, number>;
468
+ requests: Record<string, RuntimeRequest>;
469
+ reservations: Record<string, string>;
470
+ activations: Record<string, RuntimeActivation>;
471
+ queue: RuntimeQueued[];
472
+ scheduled: RuntimeScheduled[];
473
+ trace: RuntimeTrace[];
474
+ effects: RuntimeBrowserEffect[];
475
+ diagnostic: string | null;
476
+ suspended: boolean;
477
+ }
478
+ /** Creates fresh state from the verified linked model; no DOM or wall clock is consulted. */
479
+ declare function createRuntime(linked: LinkedApp, options?: {
480
+ fragment?: string;
481
+ }): RuntimeSnapshot;
482
+ /** Applies one closed conformance input. The supplied snapshot is never mutated. */
483
+ declare function reduceEvent(snapshot: RuntimeSnapshot, input: RuntimeInput): RuntimeSnapshot;
484
+ declare function advanceClock(snapshot: RuntimeSnapshot, deltaMs: number): RuntimeSnapshot;
485
+ declare function resetRuntime(snapshot: RuntimeSnapshot): RuntimeSnapshot;
486
+ declare function renderSite(bundle: AppBundle): AppResult<AppArtifact>;
487
+
488
+ export { type AppArtifact, type AppBundle, type AppCompileResult, type AppComponentInput, type AppComponentInstanceId, type AppDefinitionKind, type AppDocument, type AppLayoutInput, type AppLinkDiagnostic, type AppLinkDiagnosticCode, type AppLinkResult, type AppManifest, type AppManifestModule, type AppModuleInput, type AppNodeId, type AppNodeKind, type AppReferenceInput, type AppResult, type AppScreenInput, type AppSourceMapEntry, type AppSourceSpan, type CompileAppOptions, type CreateAppBundleOptions, type Diagnostic, type InstanceStep, type LinkedApp, type LinkedIdentity, type ResolvedAppComponent, type ResolvedAppLayout, type ResolvedAppModule, type ResolvedAppReference, type ResolvedAppScreen, type RuntimeBrowserEffect, type RuntimeInput, type RuntimeSnapshot, type RuntimeTrace, type ScreenReference, type SourceMapEntry, advanceClock, compileApp, createAppBundle, createAppComponentInstanceId, createAppNodeId, createRuntime, linkAndCompileApp, linkApp, reduceEvent, renderSite, resetRuntime };