@wireweave/core 3.1.0-beta.1 → 3.1.0-beta.10

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/dist/index.d.ts CHANGED
@@ -1,7 +1,10 @@
1
- import { h as AnyNode, A as AccordionNode, a as AlertNode, j as AvatarNode, B as BadgeNode, r as BreadcrumbNode, s as ButtonNode, C as CardNode, w as CheckboxNode, x as ColNode, z as ContainerComponentNode, D as ContainerNode, E as DataNode, G as DisplayNode, H as DividerComponentNode, J as DrawerNode, M as DropdownNode, N as FeedbackNode, P as FooterNode, Q as GridNode, S as HeaderNode, U as IconNode, X as ImageNode, Y as InputComponentNode, Z as InputNode, a1 as LayoutNode, a2 as LeafNode, a3 as LinkNode, a5 as ListNode, a6 as MainNode, a9 as ModalNode, af as NavNode, ag as NavigationNode, ah as NodeType, ai as OverlayNode, aj as PageNode, ak as PlaceholderNode, al as PopoverNode, ao as ProgressNode, ap as RadioNode, ar as RowNode, as as SectionNode, at as SelectNode, aw as SidebarNode, ay as SliderNode, aC as SpinnerNode, aG as SwitchNode, aI as TableNode, aJ as TabsNode, aL as TextContentNode, aM as TextNode, aQ as TextareaNode, aS as TitleNode, aT as ToastNode, aV as TooltipNode, aZ as WireframeDocument, az as SourceLocation, _ as InputType } from './types-BDbXDhTp.js';
2
- export { b as AlertVariant, c as AlignValue, d as AnchorPosition, e as AnnotationItemNode, f as AnnotationNode, g as AnnotationsNode, i as AppearanceProps, k as AvatarSize, l as AvatarSizeToken, m as BadgeSize, n as BadgeSizeToken, o as BadgeVariant, p as BaseNode, q as BreadcrumbItem, t as ButtonSize, u as ButtonSizeToken, v as ButtonVariant, y as CommonProps, F as DirectionValue, I as DividerNode, K as DrawerPosition, L as DropdownItemNode, O as FlexProps, R as GridProps, T as HeightValue, V as IconSize, W as IconSizeToken, $ as InteractiveProps, a0 as JustifyValue, a4 as ListItemNode, a7 as MarkerColor, a8 as MarkerNode, aa as NavBlockItem, ab as NavChild, ac as NavDivider, ad as NavGroupNode, ae as NavItem, am as Position, an as PositionProps, aq as RelativeNode, au as SelectOption, av as ShadowValue, ax as SizeProps, aA as SpacingProps, aB as SpacingValue, aD as SpinnerSize, aE as SpinnerSizeToken, aF as StackNode, aH as TabNode, aK as TextAlign, aN as TextSize, aO as TextSizeToken, aP as TextWeight, aR as TitleLevel, aU as ToastPosition, aW as TooltipPosition, aX as ValueWithUnit, aY as WidthValue } from './types-BDbXDhTp.js';
1
+ import { h as AnyNode, A as AccordionNode, a as AlertNode, j as AvatarNode, B as BadgeNode, r as BreadcrumbNode, s as ButtonNode, C as CardNode, w as CheckboxNode, x as ColNode, z as ComponentDefinitionNode, H as ComponentUseNode, I as ContainerComponentNode, J as ContainerNode, K as DataNode, L as DefinitionNode, N as DisplayNode, O as DividerComponentNode, P as DrawerNode, S as DropdownNode, T as FeedbackNode, V as FooterNode, W as GridNode, Z as HeaderNode, $ as IconNode, a2 as ImageNode, a3 as InputComponentNode, a4 as InputNode, aa as LayoutDefinitionNode, ab as LayoutNode, ac as LeafNode, ad as LinkNode, af as ListNode, ag as MainNode, aj as ModalNode, ao as NavNode, ap as NavigationNode, aq as NodeType, ar as OverlayNode, as as PageNode, at as PlaceholderNode, au as PopoverNode, ax as ProgressNode, ay as RadioNode, aB as RowNode, aC as SectionNode, aD as SelectNode, aG as SidebarNode, aI as SliderNode, aJ as SlotNode, aN as SpinnerNode, aV as SwitchNode, aX as TableNode, aY as TabsNode, a_ as TextContentNode, a$ as TextNode, b3 as TextareaNode, b5 as TitleNode, b6 as ToastNode, b8 as TooltipNode, be as WireframeDocument, aK as SourceLocation, aR as StateDeclaration, aS as StateGuard, a6 as InteractionEffect, a5 as InputType } from './types-vhPCZpAW.js';
2
+ export { b as AlertVariant, c as AlignValue, d as AnchorPosition, e as AnnotationItemNode, f as AnnotationNode, g as AnnotationsNode, i as AppearanceProps, k as AvatarSize, l as AvatarSizeToken, m as BadgeSize, n as BadgeSizeToken, o as BadgeVariant, p as BaseNode, q as BreadcrumbItem, t as ButtonSize, u as ButtonSizeToken, v as ButtonVariant, y as CommonProps, D as ComponentInputValue, E as ComponentParameter, F as ComponentParameterType, G as ComponentSlotFill, M as DirectionValue, Q as DrawerPosition, R as DropdownItemNode, U as FlexProps, X as GridProps, Y as GuardedOutcomeProps, _ as HeightValue, a0 as IconSize, a1 as IconSizeToken, a7 as InteractionHandler, a8 as InteractiveProps, a9 as JustifyValue, ae as ListItemNode, ah as MarkerColor, ai as MarkerNode, ak as NavBlockItem, al as NavChild, am as NavGroupNode, an as NavItem, av as Position, aw as PositionProps, az as RelativeNode, aA as RepeatNode, aE as SelectOption, aF as ShadowValue, aH as SizeProps, aL as SpacingProps, aM as SpacingValue, aO as SpinnerSize, aP as SpinnerSizeToken, aQ as StackNode, aT as StateValue, aU as StateValueType, aW as TabNode, aZ as TextAlign, b0 as TextSize, b1 as TextSizeToken, b2 as TextWeight, b4 as TitleLevel, b7 as ToastPosition, b9 as TooltipPosition, ba as TopLevelNode, bb as ValueWithUnit, bc as VariantScopedProps, bd as WidthValue } from './types-vhPCZpAW.js';
3
3
  export { ExpectedToken, ParseError, ParseErrorInfo, ParseOptions, ParseResult, getErrors, isValid, parse, tryParse } from './parser.js';
4
- export { CanvasOptions, CanvasRenderResult, HtmlRenderer, IconData, IconElement, PageRenderResult, PlacedPage, RenderContext, RenderOptions, RenderResult, SvgRenderOptions, SvgRenderResult, ThemeColors, ThemeConfig, createHtmlRenderer, darkTheme, defaultTheme, generateComponentStyles, generateStyles, getIconData, getTheme, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions } from './renderer.js';
4
+ import { SiteOptions } from './renderer.js';
5
+ export { AnnotationStyle, CanvasOptions, CanvasRenderResult, ENABLED_GUARD_ATTR, EXTERNAL_NAVIGATE_ATTR, HtmlRenderer, INERT_HREF, INTERACTIVE_ATTR_NAMES, IconData, IconElement, InteractiveAttrs, PageRenderResult, PlacedPage, RenderContext, RenderOptions, RenderResult, ShellMiss, SiteModel, SiteScreen, SiteShell, SvgRenderOptions, SvgRenderResult, TYPED_INTERACTION_ATTR, ThemeColors, ThemeConfig, VISIBLE_GUARD_ATTR, anchorIntent, buildSiteModel, createHtmlRenderer, darkTheme, defaultTheme, generateComponentStyles, generateStyles, getIconData, getTheme, guardedOutcomeAttrs, interactiveAttrs, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderSite, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions } from './renderer.js';
6
+ import { ComponentCategory } from './spec.js';
7
+ export { ATTRIBUTE_MAP, ATTRIBUTE_OVERRIDES, ATTRIBUTE_SPECS, AttributeOverride, AttributeSpec, AttributeValueType, BLOCK_NODE_SPECS, BOX_ATTRIBUTES, COMPONENT_MAP, COMPONENT_NAMES, COMPONENT_SPECS, COMPONENT_SPEC_BY_NAME, CONTAINER_ATTRIBUTES, ComponentSpec, ELEMENT_NODE_TYPE_MAP, GRAMMAR_BLOCK_NODE_TYPES, GRAMMAR_CHILD_KEYWORDS, GRAMMAR_ELEMENTS, GrammarBlockNodeType, GrammarElementName, GrammarNodeType, INTERACTIVE_ATTRIBUTES, LUCIDE_ICON_NAMES, NODE_TYPE_MAP, VALID_ATTRIBUTE_NAMES, VALID_COMPONENT_NAMES, attributeFor, getValidAttributes, isValidAttribute } from './spec.js';
5
8
 
6
9
  /**
7
10
  * Type guards for wireweave AST
@@ -16,6 +19,12 @@ declare function hasChildren(node: AnyNode): node is AnyNode & {
16
19
  declare function isLeafNode(node: AnyNode): node is LeafNode;
17
20
  declare function isLayoutNode(node: AnyNode): node is LayoutNode;
18
21
  declare function isPageNode(node: AnyNode): node is PageNode;
22
+ /** A `layout` or `component` definition — a named tree, not a screen. */
23
+ declare function isDefinitionNode(node: AnyNode): node is DefinitionNode;
24
+ declare function isLayoutDefinitionNode(node: AnyNode): node is LayoutDefinitionNode;
25
+ declare function isComponentDefinitionNode(node: AnyNode): node is ComponentDefinitionNode;
26
+ declare function isComponentUseNode(node: AnyNode): node is ComponentUseNode;
27
+ declare function isSlotNode(node: AnyNode): node is SlotNode;
19
28
  declare function isHeaderNode(node: AnyNode): node is HeaderNode;
20
29
  declare function isMainNode(node: AnyNode): node is MainNode;
21
30
  declare function isFooterNode(node: AnyNode): node is FooterNode;
@@ -95,10 +104,33 @@ declare function walk(node: AnyNode, callback: WalkCallback, parent?: AnyNode, d
95
104
  /**
96
105
  * Walk through a document's AST
97
106
  *
107
+ * Covers every top-level child — pages *and* reuse definitions — because a walk
108
+ * is about visiting nodes, not about selecting screens.
109
+ *
98
110
  * @param document - The wireframe document
99
111
  * @param callback - Function called for each node
100
112
  */
101
113
  declare function walkDocument(document: WireframeDocument, callback: WalkCallback): void;
114
+ /**
115
+ * The document's pages, in source order.
116
+ *
117
+ * A document's children are not all screens: `layout` and `component`
118
+ * definitions sit alongside `page` as top-level siblings. Anything that counts,
119
+ * indexes, renders or exports *screens* must select them through this helper
120
+ * rather than reading `document.children` directly — otherwise a definition
121
+ * silently becomes screen #0.
122
+ *
123
+ * @param document - The wireframe document
124
+ * @returns Only the `Page` children
125
+ */
126
+ declare function documentPages(document: WireframeDocument): PageNode[];
127
+ /**
128
+ * The document's reuse definitions (`layout` / `component`), in source order.
129
+ *
130
+ * @param document - The wireframe document
131
+ * @returns Only the definition children
132
+ */
133
+ declare function documentDefinitions(document: WireframeDocument): DefinitionNode[];
102
134
  /**
103
135
  * Find the first node matching a predicate
104
136
  *
@@ -176,6 +208,292 @@ declare function contains(node: AnyNode, target: AnyNode): boolean;
176
208
  */
177
209
  declare function getNodeTypes(node: AnyNode): Set<NodeType>;
178
210
 
211
+ /**
212
+ * Component parameter references (`"$name"`) — one traversal, one pattern.
213
+ *
214
+ * A component body may reference a declared parameter anywhere a string value
215
+ * sits: a top-level prop (`title "$name"`), a nested object (an interaction
216
+ * effect's `target`), or an element of an array (`effects[]`). Substitution at
217
+ * link time walks all three. Validation must walk exactly the same shape, or a
218
+ * reference that gets substituted is never checked — an undeclared name then
219
+ * survives as the literal string `"$too"` with no diagnostic.
220
+ *
221
+ * Both the linker and the document validator therefore share the traversal and
222
+ * the pattern defined here rather than re-deriving either.
223
+ */
224
+
225
+ /**
226
+ * The parameter name a string value references, or `undefined` when the value
227
+ * is ordinary text.
228
+ *
229
+ * @param value - Any value; only whole-string references match.
230
+ * @returns The referenced name without its `$`, or `undefined`.
231
+ * @public
232
+ */
233
+ declare function parameterReferenceName(value: unknown): string | undefined;
234
+ /**
235
+ * One `"$name"` reference found inside a component body.
236
+ *
237
+ * @public
238
+ */
239
+ interface ComponentParameterReference {
240
+ /** Referenced parameter name, without its `$`. */
241
+ name: string;
242
+ /**
243
+ * Property key the reference was found under. Nested keys report the leaf
244
+ * key (`target`), which is what an author sees in the source text.
245
+ */
246
+ key: string;
247
+ /** Nearest enclosing AST node, for diagnostic location and node type. */
248
+ node: AnyNode;
249
+ }
250
+ /**
251
+ * Every parameter reference reachable from a component's children.
252
+ *
253
+ * Mirrors link-time substitution exactly: it descends into arrays and plain
254
+ * objects as well as child nodes, and skips `loc` so a source location can
255
+ * never be mistaken for authored content. `ComponentUse` subtrees are skipped —
256
+ * a nested invocation's inputs belong to that component's own scope, and its
257
+ * body is validated where it is defined.
258
+ *
259
+ * @param children - The component definition's children.
260
+ * @returns References in traversal order.
261
+ * @public
262
+ * @example
263
+ * `collectParameterReferences(definition.children).map((item) => item.name)`
264
+ */
265
+ declare function collectParameterReferences(children: readonly AnyNode[]): ComponentParameterReference[];
266
+
267
+ /**
268
+ * `repeat N { … }` expansion — folding syntax turned into the tree it denotes.
269
+ *
270
+ * ## Why this is a pass over the document, not a case in the renderer
271
+ *
272
+ * `repeat` has to disappear before anything *measures* the tree, not merely
273
+ * before something draws it. The renderer builds its anchor index up front:
274
+ * `HtmlRenderer.render` calls `buildAnchorPathMap(document)` before emitting a
275
+ * byte, and that map is keyed by **node object identity**. A `Repeat` expanded
276
+ * lazily inside `renderNode` would hand back copies the map has never seen, so
277
+ * every copy but the first would render without a `data-wf-path` and the anchor
278
+ * count would stop matching the index — the exact drift `anchor-path.ts` exists
279
+ * to prevent. Expanding the whole document first means the map, the markup, the
280
+ * DOM map and the UX rules all see one identical tree.
281
+ *
282
+ * It is equally deliberate that this is **not** in the parser. The AST keeps the
283
+ * `Repeat` node so the printer can write `repeat 6` back out; expanding at parse
284
+ * time would make `parse(print(parse(src)))` return six bodies where the source
285
+ * had one, breaking the round-trip law the corpus harness pins.
286
+ *
287
+ * ## Identity and source anchors
288
+ *
289
+ * Every copy is a fresh deep clone, never a shared reference — see above for why
290
+ * identity matters. Clones intentionally keep the `loc` of the body they came
291
+ * from: all six copies of `repeat 6 { … }` really do originate at one span of
292
+ * source, so pointing back at it is accurate, and it is the same thing component
293
+ * expansion already does. Uniqueness comes from position instead — anchor paths
294
+ * are child indices (`0.2.1`), so the copies land at distinct sibling indices
295
+ * automatically and no two share a path.
296
+ */
297
+
298
+ /**
299
+ * Total node budget for one expansion.
300
+ *
301
+ * Nesting multiplies — `repeat 100 { repeat 100 { … } }` is ten thousand bodies
302
+ * — so a per-`repeat` cap on `N` would not bound the result. The budget is
303
+ * therefore on the **expanded total**, which is the quantity that actually costs
304
+ * anything, and it is checked as the tree is built so a runaway document stops
305
+ * early instead of being materialised and then rejected.
306
+ *
307
+ * The number is the page-complexity ceiling `ux-rules` already applies
308
+ * (`MAX_PAGE_ELEMENTS`, 50) times ten. Tying it to that constant rather than
309
+ * inventing a figure keeps one notion of "too big for a wireframe" in the
310
+ * codebase; the multiplier is headroom, so that a document merely worth warning
311
+ * about still renders — `tooManyPageElements` reports at 50 and this refuses at
312
+ * 500, leaving an order of magnitude in which a document is complained about
313
+ * but still drawn, and only past that is it refused outright.
314
+ */
315
+ declare const REPEAT_EXPANSION_BUDGET = 500;
316
+ /** Thrown when an expansion would exceed {@link REPEAT_EXPANSION_BUDGET}. */
317
+ declare class RepeatBudgetError extends Error {
318
+ constructor(budget: number);
319
+ }
320
+ /**
321
+ * Replace every `repeat N { … }` in a document with `N` copies of its body.
322
+ *
323
+ * Idempotent by construction — the result contains no `Repeat` nodes, so a
324
+ * second application is a no-op. A document with no `repeat` is returned as-is,
325
+ * identity included, so the common case costs one traversal and no allocation.
326
+ *
327
+ * @param document - Parsed wireframe document
328
+ * @returns The document with all `repeat` nodes expanded
329
+ * @throws {RepeatBudgetError} when expansion exceeds {@link REPEAT_EXPANSION_BUDGET}
330
+ * @public
331
+ * @example
332
+ * `const drawable = expandRepeats(parse(source))`
333
+ */
334
+ declare function expandRepeats(document: WireframeDocument): WireframeDocument;
335
+
336
+ /**
337
+ * `page … variants=[a, b, c]` expansion — one page turned into the screens it denotes.
338
+ *
339
+ * ## What a variant is, and why it is not a state
340
+ *
341
+ * A wireframe usually has to show a screen in several conditions: loading,
342
+ * empty, populated, failed. The language already has `states` for that, and it
343
+ * is the wrong tool: a `state` is a runtime value the site runtime flips and
344
+ * `visibleWhen` guards read, so *something in the wireframe has to flip it*.
345
+ * That something is a control the product does not have — a reviewer opening
346
+ * the artifact sees state-switching buttons among the real UI and cannot tell
347
+ * which is which. It also produces one board, so the conditions are only
348
+ * visible one at a time, and any block common to two conditions is written
349
+ * twice because a guard has no disjunction.
350
+ *
351
+ * A variant moves the same information from a toggle inside the screen to an
352
+ * axis of the document: `variants=[loading, empty, ready]` draws the page three
353
+ * times, side by side, with no switching UI in any of them. The artifact
354
+ * becomes the sheet of state-by-state boards a reviewer reads top to bottom,
355
+ * and the common blocks are shared because they are one authored body.
356
+ *
357
+ * ## Why this is a document pass, like `repeat`
358
+ *
359
+ * For the reason spelled out at length in `expand-repeats.ts`: the renderer
360
+ * builds `buildAnchorPathMap(document)` up front and keys it by **node object
361
+ * identity**. Two variant boards sharing one child tree would be two boards the
362
+ * map has seen once, so the second would render without `data-wf-path` and the
363
+ * anchor count would stop matching the index. Every variant is therefore a
364
+ * fresh deep clone, and `loc` is deliberately shared: all three boards really do
365
+ * originate at one span of source.
366
+ *
367
+ * Doing it here rather than in each renderer is also what keeps the surfaces
368
+ * agreeing. `render`'s canvas counts pages and `renderSite` builds a screen
369
+ * model; if each expanded on its own, a variant would be a canvas board and a
370
+ * site screen by two separate rules that could drift. They both run this pass
371
+ * and then count what it produced.
372
+ *
373
+ * And, as with `repeat`, this is deliberately **not** in the parser: the AST
374
+ * keeps `variants` so the printer writes it back out, and expanding at parse
375
+ * time would break the `parse(print(parse(src)))` round-trip law the corpus
376
+ * harness pins.
377
+ */
378
+
379
+ /**
380
+ * Replace every page declaring `variants=` with one page per variant.
381
+ *
382
+ * Each produced page carries `variant` naming which one it is and no longer
383
+ * carries `variants`, so the result declares none and a second application is a
384
+ * no-op. A document with no variants is returned as-is, identity included, so
385
+ * the common case costs one scan and no allocation — the property every
386
+ * existing document relies on to render exactly as it did before.
387
+ *
388
+ * @param document - Parsed wireframe document
389
+ * @returns The document with all variant-bearing pages expanded
390
+ * @public
391
+ * @example
392
+ * `const drawable = expandVariants(parse(source))`
393
+ */
394
+ declare function expandVariants(document: WireframeDocument): WireframeDocument;
395
+
396
+ /**
397
+ * `when=` filtering — dropping the elements a board does not draw.
398
+ *
399
+ * ## What `when` says, and why it is not a guard
400
+ *
401
+ * `visibleWhen` already answers "should this be on screen right now": the
402
+ * element is rendered onto every board, carries `data-wf-visible-when`, and the
403
+ * site runtime shows and hides it as state changes. `when` answers a different
404
+ * question — *which boards is this element part of at all* — and it answers it
405
+ * before anything renders. An element scoped to `loading` is not hidden on the
406
+ * `ready` board; it is absent from it, so no state change can bring it back and
407
+ * nothing in that board's markup refers to it.
408
+ *
409
+ * The two are therefore orthogonal, not alternatives, and this pass is careful
410
+ * to leave guards alone: it deletes `when` from the nodes it keeps and touches
411
+ * no other property, so `when=ready visibleWhen={…}` survives as a guard on the
412
+ * ready board. Collapsing them would lose the case the feature exists for.
413
+ *
414
+ * ## Why disjunction is the point
415
+ *
416
+ * A guard compares one state to one value, so a block belonging to two
417
+ * conditions could only be written twice. That is not a stylistic cost: the two
418
+ * copies are edited separately and drift, and a reviewer reading the sheet
419
+ * cannot tell whether a difference between them is intentional. `when=[loading,
420
+ * empty]` is the same block, authored once, drawn on both boards — the header
421
+ * shared by three states is one header, and it stays one.
422
+ *
423
+ * ## Why it runs inside variant expansion
424
+ *
425
+ * Filtering needs to know which board it is filtering *for*, and that fact
426
+ * exists only after `expandVariants` has turned one authored page into one page
427
+ * per name and stamped each with `page.variant`. Running as a separate pass
428
+ * afterwards would have to rediscover the same association by walking the
429
+ * document again; running before expansion would have no board to ask about.
430
+ * So the board is filtered at the moment it is cloned, while the name is in
431
+ * hand — see `expand-variants.ts`.
432
+ *
433
+ * ## The rule, stated once
434
+ *
435
+ * An element is drawn on a board **iff its `when` set contains that board's
436
+ * variant**. Everything else follows from that one sentence rather than from a
437
+ * list of cases:
438
+ *
439
+ * - No `when` at all → drawn on every board. This is what keeps every document
440
+ * written before the attribute existed rendering byte-for-byte as it did.
441
+ * - A board with no variant (a page that declared no `variants=`) matches no
442
+ * name, so *any* `when` filters the element out. That is the honest reading
443
+ * rather than a convenient one: the element declares membership in a board
444
+ * this page never declared, and drawing it anyway would make `when` mean
445
+ * "sometimes nothing", which is the silently-dropped-value failure the spec
446
+ * gates exist to prevent. `validate()` reports the same document, so the
447
+ * author is told rather than left to discover an empty board.
448
+ * - A parent that is filtered out takes its children with it, whatever they
449
+ * say. A child scoped to `ready` inside a parent scoped to `loading` cannot
450
+ * be drawn on either board — there is no board where both are present — and
451
+ * the contradiction is reported by `validate()` rather than resolved here.
452
+ */
453
+
454
+ /**
455
+ * The variant names an element declares, trimmed, blanks and duplicates dropped.
456
+ *
457
+ * Both spellings collapse to the same set, because `when=loading` and
458
+ * `when=[loading]` denote the same membership and nothing downstream should
459
+ * have to know which the author typed.
460
+ *
461
+ * A `when` that is present but names nothing — `when=[]`, or a blank string —
462
+ * yields an empty set, which matches no board. It is deliberately not treated
463
+ * as "no `when`": the author wrote the attribute, and answering an empty list
464
+ * with "every board" would make the emptiest possible scope the widest one.
465
+ */
466
+ declare function variantScope(node: AnyNode): string[] | undefined;
467
+ /**
468
+ * Drop from `children` everything not drawn on `variant`'s board.
469
+ *
470
+ * Identity-preserving: a subtree carrying no `when` anywhere is returned as the
471
+ * same array, so a board of a document that uses no scoping costs one scan.
472
+ *
473
+ * @param children - The board's children, already cloned by variant expansion
474
+ * @param variant - The board's variant name, or `undefined` for an unnamed board
475
+ * @returns The children this board draws
476
+ * @internal
477
+ */
478
+ declare function filterVariantScope(children: AnyNode[], variant: string | undefined): AnyNode[];
479
+ /**
480
+ * Apply `when` filtering to every page of a document that expansion did not.
481
+ *
482
+ * Variant-bearing pages are filtered as they are cloned, inside
483
+ * `expandVariants`, because that is where the board's name exists. This covers
484
+ * the rest: a page that declared no `variants=` is still a board, an unnamed
485
+ * one, and an element scoped to a name it never declared is not drawn on it.
486
+ *
487
+ * Layout and component definitions are filtered through the pages that use
488
+ * them, not here — a definition has no board of its own, and scoping inside one
489
+ * resolves against whichever page pulled it in.
490
+ *
491
+ * @param document - A document whose variant-bearing pages are already expanded
492
+ * @returns The document with unnamed boards filtered
493
+ * @internal
494
+ */
495
+ declare function filterUnscopedPages(document: WireframeDocument): WireframeDocument;
496
+
179
497
  /**
180
498
  * Node/document-level canonical `.wf` printing.
181
499
  *
@@ -285,103 +603,6 @@ interface PreviewWrapperOptions {
285
603
  */
286
604
  declare function wrapInPreviewContainer(html: string, viewport: ViewportSize, options?: PreviewWrapperOptions): string;
287
605
 
288
- /**
289
- * Types for Wireweave DSL Specification
290
- */
291
- /**
292
- * Attribute value type
293
- */
294
- type AttributeValueType = 'boolean' | 'number' | 'string' | 'string[]' | 'enum';
295
- /**
296
- * Attribute definition
297
- */
298
- interface AttributeSpec {
299
- /** Attribute name */
300
- name: string;
301
- /** Value type */
302
- type: AttributeValueType;
303
- /** Enum values (if type is 'enum') */
304
- values?: readonly string[];
305
- /** Description for documentation */
306
- description?: string;
307
- }
308
- /**
309
- * Component category
310
- */
311
- type ComponentCategory = 'layout' | 'grid' | 'container' | 'text' | 'input' | 'display' | 'data' | 'feedback' | 'overlay' | 'navigation' | 'annotation';
312
- /**
313
- * Component definition
314
- */
315
- interface ComponentSpec {
316
- /** Component name (lowercase, as used in DSL) */
317
- name: string;
318
- /** AST node type (PascalCase) */
319
- nodeType: string;
320
- /** Component category */
321
- category: ComponentCategory;
322
- /** Valid attributes for this component (names only, definitions in ATTRIBUTES) */
323
- attributes: readonly string[];
324
- /** Whether this component can have children */
325
- hasChildren: boolean;
326
- /** Description for documentation */
327
- description?: string;
328
- }
329
-
330
- /**
331
- * Wireweave DSL Component Definitions
332
- *
333
- * Complete list of all valid components in Wireweave DSL.
334
- * Each component specifies its valid attributes.
335
- */
336
-
337
- /**
338
- * All valid components in Wireweave DSL
339
- */
340
- declare const COMPONENT_SPECS: readonly ComponentSpec[];
341
- /**
342
- * Set of all valid component names for quick lookup
343
- */
344
- declare const VALID_COMPONENT_NAMES: ReadonlySet<string>;
345
- /**
346
- * Map of component name to spec for quick lookup
347
- */
348
- declare const COMPONENT_MAP: ReadonlyMap<string, ComponentSpec>;
349
- /**
350
- * Map of AST node type to spec for quick lookup
351
- */
352
- declare const NODE_TYPE_MAP: ReadonlyMap<string, ComponentSpec>;
353
- /**
354
- * Get valid attributes for a component (by name or node type)
355
- */
356
- declare function getValidAttributes(componentNameOrType: string): readonly string[] | undefined;
357
- /**
358
- * Check if an attribute is valid for a component
359
- */
360
- declare function isValidAttribute(componentNameOrType: string, attributeName: string): boolean;
361
-
362
- /**
363
- * Wireweave DSL Attribute Definitions
364
- *
365
- * Complete list of all valid attributes in Wireweave DSL.
366
- */
367
-
368
- /**
369
- * All valid attributes in Wireweave DSL
370
- */
371
- declare const ATTRIBUTE_SPECS: readonly AttributeSpec[];
372
- /**
373
- * Set of all valid attribute names for quick lookup
374
- */
375
- declare const VALID_ATTRIBUTE_NAMES: ReadonlySet<string>;
376
- /**
377
- * Map of attribute name to spec for quick lookup
378
- */
379
- declare const ATTRIBUTE_MAP: ReadonlyMap<string, AttributeSpec>;
380
- /**
381
- * Common attributes available to most components
382
- */
383
- declare const COMMON_ATTRIBUTES: readonly string[];
384
-
385
606
  /**
386
607
  * Wireweave DSL Validation
387
608
  *
@@ -981,6 +1202,84 @@ interface AnalysisOptions {
981
1202
  */
982
1203
  declare function analyze(doc: WireframeDocument, options?: AnalysisOptions): AnalysisResult;
983
1204
 
1205
+ /** Overlay toggle is distinct from the typed boolean-state `toggle` effect. */
1206
+ type NormalizedInteractionEffect = InteractionEffect | {
1207
+ kind: 'toggle-overlay';
1208
+ target: string;
1209
+ } | {
1210
+ kind: 'legacy-action';
1211
+ action: string;
1212
+ };
1213
+ interface NormalizedInteractionHandler {
1214
+ event: 'click';
1215
+ guard?: StateGuard;
1216
+ effects: NormalizedInteractionEffect[];
1217
+ }
1218
+ interface NormalizedInteraction {
1219
+ screenIndex: number;
1220
+ source: 'screen' | 'layout';
1221
+ signature: string;
1222
+ handler: NormalizedInteractionHandler;
1223
+ /** Present when this entry came from a legacy scalar intent attribute. */
1224
+ legacyKind?: InteractionKind;
1225
+ trigger: {
1226
+ nodeType: NodeType;
1227
+ label?: string;
1228
+ loc?: SourceLocation;
1229
+ item?: {
1230
+ index: number;
1231
+ };
1232
+ };
1233
+ }
1234
+ type InteractionDiagnosticCode = 'invalid-state-declaration' | 'duplicate-state-declaration' | 'invalid-interaction-handler' | 'unknown-legacy-action';
1235
+ interface InteractionDiagnostic {
1236
+ code: InteractionDiagnosticCode;
1237
+ message: string;
1238
+ screenIndex?: number;
1239
+ source?: 'screen' | 'layout';
1240
+ loc?: SourceLocation;
1241
+ }
1242
+ interface InteractionModel {
1243
+ states: StateDeclaration[];
1244
+ interactions: NormalizedInteraction[];
1245
+ diagnostics: InteractionDiagnostic[];
1246
+ }
1247
+ /** Normalize a guard object emitted by the generic DSL object grammar. */
1248
+ declare function normalizeStateGuard(value: unknown): StateGuard | undefined;
1249
+ /**
1250
+ * Normalize the public `on=` shape. Malformed handlers are inert; diagnostics
1251
+ * are added by {@link collectInteractions}, where screen/source context exists.
1252
+ */
1253
+ declare function normalizeInteractionHandlers(value: unknown): NormalizedInteractionHandler[];
1254
+ /** Stable payload shared by rendered DOM markers and the runtime registry. */
1255
+ declare function interactionSignature(handler: NormalizedInteractionHandler): string;
1256
+ /**
1257
+ * The canonical interaction/state source for graph extraction and renderSite.
1258
+ * Layout intent is expanded once per screen using that layout, so shared chrome
1259
+ * has the same reachable routes in both consumers.
1260
+ *
1261
+ * ## Components are read through the linker, never from here
1262
+ *
1263
+ * Screens and layouts are walked; `component` definitions are not. That is the
1264
+ * boundary, not an omission. A handler inside a definition is written against
1265
+ * the component's *parameters* — `target="$to"` — so before an invocation binds
1266
+ * its inputs there is no destination to record, only the name of one. Walking
1267
+ * definitions here would register `"$to"` as a route and invent a graph edge to
1268
+ * a screen that does not exist, and a component used twice with different
1269
+ * inputs is two different routes that a single walk of the definition cannot
1270
+ * tell apart.
1271
+ *
1272
+ * Binding those inputs is `linkApp`'s job: `expandComponentUse` substitutes the
1273
+ * invocation's inputs, fills its slots, and hands back a tree whose handlers
1274
+ * name real targets. So `linkAndCompileApp` — link, then compile — sees every
1275
+ * component interaction, while `renderSite(parse(src))` on a document that
1276
+ * never went through the linker leaves each invocation
1277
+ * `data-wf-component-unresolved` and contributes no interactions. Handlers
1278
+ * written directly on a screen or a layout work in both paths; only handlers
1279
+ * *inside a component definition* require the linked path.
1280
+ */
1281
+ declare function collectInteractions(doc: WireframeDocument): InteractionModel;
1282
+
984
1283
  /**
985
1284
  * Types for the deterministic extraction module.
986
1285
  *
@@ -1091,8 +1390,14 @@ interface ScreenFields {
1091
1390
  }
1092
1391
  /**
1093
1392
  * A node in the screen-transition graph.
1393
+ *
1394
+ * `id` is the page's declared identifier — a stable slug an author opted into —
1395
+ * and `title` is its display heading. They are separate namespaces: `id` is what
1396
+ * a `navigate` target should key off, `title` is what a reader sees. Either can
1397
+ * be absent.
1094
1398
  */
1095
1399
  interface TransitionScreen {
1400
+ id?: string;
1096
1401
  title?: string;
1097
1402
  index: number;
1098
1403
  loc?: SourceLocation;
@@ -1103,20 +1408,32 @@ interface TransitionScreen {
1103
1408
  interface TransitionEdge {
1104
1409
  from: {
1105
1410
  pageIndex: number;
1411
+ id?: string;
1106
1412
  title?: string;
1107
1413
  };
1108
1414
  /**
1109
1415
  * The destination page for a resolved `navigate` edge. Always `null` for
1110
1416
  * `opens` / `toggles` / `action`, which are intra-page or opaque and never
1111
1417
  * cross a page boundary.
1418
+ *
1419
+ * `id` / `title` mirror {@link TransitionScreen}: present when the page
1420
+ * declares them, so a consumer can address the destination by its stable slug
1421
+ * rather than by display text.
1112
1422
  */
1113
1423
  to: {
1114
1424
  pageIndex: number;
1425
+ id?: string;
1115
1426
  title?: string;
1116
1427
  } | null;
1117
1428
  /** The raw target string as written in the DSL. */
1118
1429
  target: string;
1119
1430
  kind: InteractionKind;
1431
+ /** Typed event metadata; absent for legacy scalar interaction attributes. */
1432
+ event?: 'click';
1433
+ guard?: StateGuard;
1434
+ effect?: NormalizedInteractionEffect;
1435
+ /** A shared-layout edge is expanded once for every screen using that layout. */
1436
+ source?: 'screen' | 'layout';
1120
1437
  /**
1121
1438
  * What fired the transition. For a component node, `nodeType` is that node's
1122
1439
  * type. For a menu item inside a nav/dropdown/breadcrumb, `nodeType` is the
@@ -1133,13 +1450,29 @@ interface TransitionEdge {
1133
1450
  };
1134
1451
  };
1135
1452
  /**
1136
- * Whether `target` resolved to a concrete destination for its kind:
1137
- * - `navigate`: a page whose title matches `target`.
1453
+ * Whether `target` names a concrete destination for its kind:
1454
+ * - `navigate`: a page whose `id` matches `target`, or — failing that — whose
1455
+ * `title` matches it. Identifiers are consulted before display text; see
1456
+ * `extract/transitions.ts` for why. Also `true` for an `external` target: a
1457
+ * URL is a complete destination, it is simply not one of this document's
1458
+ * pages, which is why `to` is `null` there.
1138
1459
  * - `opens` / `toggles`: a `Modal` / `Drawer` with `id === target` in the
1139
1460
  * source page.
1140
1461
  * - `action`: always `false` (an opaque handler id has no structural target).
1141
1462
  */
1142
1463
  resolved: boolean;
1464
+ /**
1465
+ * Present, and always `true`, when a `navigate` target is a URL rather than
1466
+ * the name of a page (see `interaction/target.ts`). Such an edge leaves the
1467
+ * document: `to` is `null` because there is no page to point at, and it is
1468
+ * never {@link ScreenTransitionGraph.dangling | dangling} — an outbound link
1469
+ * is a destination the author meant, not a reference that failed to resolve.
1470
+ *
1471
+ * This is what separates an external link from an `action`: both have
1472
+ * `to === null`, but an `action` is an opaque handler with `resolved: false`,
1473
+ * while an external link is a real destination the browser can follow.
1474
+ */
1475
+ external?: true;
1143
1476
  }
1144
1477
  /**
1145
1478
  * The screen-transition graph derived from a whole document.
@@ -1148,11 +1481,21 @@ interface ScreenTransitionGraph {
1148
1481
  screens: TransitionScreen[];
1149
1482
  edges: TransitionEdge[];
1150
1483
  /**
1151
- * The subset of `navigate` edges whose target matched no page title
1152
- * (`resolved === false`, `to === null`). Intra-page `opens` / `toggles` and
1153
- * opaque `action` edges are not page transitions and never appear here.
1484
+ * The subset of `navigate` edges whose target matched neither a page `id` nor
1485
+ * a page title and is not a URL (`resolved === false`, `to === null`) — a name
1486
+ * that was meant to be a screen and found none. This is the defect list: a
1487
+ * consumer reporting "broken transitions" counts exactly these. Intra-page
1488
+ * `opens` / `toggles` and opaque `action` edges are not page transitions and
1489
+ * never appear here, and neither do `external` links.
1154
1490
  */
1155
1491
  dangling: TransitionEdge[];
1492
+ /**
1493
+ * The subset of `navigate` edges leaving the document — targets that are URLs
1494
+ * rather than page names ({@link TransitionEdge.external}). Kept apart from
1495
+ * `dangling` so a consumer can show outbound links without counting correct
1496
+ * authoring as breakage.
1497
+ */
1498
+ external: TransitionEdge[];
1156
1499
  }
1157
1500
 
1158
1501
  /**
@@ -1174,6 +1517,9 @@ interface ScreenTransitionGraph {
1174
1517
  declare function extractScreenFields(page: PageNode): ScreenFields;
1175
1518
  /**
1176
1519
  * Extract {@link ScreenFields} for every page in a document, in document order.
1520
+ *
1521
+ * Reuse definitions are skipped: a `layout` is not a screen and has no fields
1522
+ * of its own until a page is drawn inside it.
1177
1523
  */
1178
1524
  declare function extractAllScreenFields(doc: WireframeDocument): ScreenFields[];
1179
1525
 
@@ -1191,27 +1537,60 @@ declare function extractAllScreenFields(doc: WireframeDocument): ScreenFields[];
1191
1537
  * `nav ["…"]` array items and `nav { item … group { item … } }` block items
1192
1538
  * (including grouped items), plus dropdown and breadcrumb items, are extracted.
1193
1539
  * Item triggers carry the container's type in `trigger.nodeType` and the item's
1194
- * position in `trigger.item.index`. `Tabs` items are plain strings without
1540
+ * position in `trigger.item.index`. That position counts only elements that can
1541
+ * hold an intent — dividers and group headings are skipped, in every container
1542
+ * alike — because the index is the handle that points back at an edge's origin,
1543
+ * and an element incapable of producing an edge must not shift what the handle
1544
+ * addresses. `Tabs` items are plain strings without
1195
1545
  * `InteractiveProps` and contribute no transition; their panel content is
1196
1546
  * reached by normal node traversal.
1197
1547
  *
1198
1548
  * ## Resolution semantics
1199
1549
  *
1200
- * - **`navigate`** is a page transition. Its target resolves to a page when the
1201
- * target string, trimmed, exactly matches a page `title` (case-sensitive). On
1202
- * duplicate titles the first page in document order wins. URL-style targets
1203
- * (`navigate="/dashboard"`) do not match a title and are reported as
1204
- * {@link ScreenTransitionGraph.dangling | dangling}. This mirrors the DSL,
1205
- * where `navigate` is documented as a "URL or page" target.
1550
+ * - **`navigate`** is a page transition. Its trimmed target is matched, exactly
1551
+ * and case-sensitively, against **page `id` first and page `title` second**.
1552
+ *
1553
+ * Identifiers are how this DSL names a target: `opens` / `toggles` already
1554
+ * address a `Modal` or `Drawer` by its `id`, so a page addressed by `id` is
1555
+ * the same rule reaching the one container that had been left out — an author
1556
+ * learns one way to point at something, not two.
1557
+ *
1558
+ * The two are different kinds of name. An `id` is a stable identifier the
1559
+ * author opted into (`page "결제 내역" id=billing`); a `title` is display text
1560
+ * that is optional, need not be unique, and is expected to change as copy is
1561
+ * edited. Resolving identifiers first means rewording a heading cannot
1562
+ * silently turn every edge pointing at that screen into a dangling one. Title
1563
+ * matching stays as the fallback because it is how the corpus is written
1564
+ * today, and dropping it would strand every existing document.
1565
+ *
1566
+ * Consequences of that order, all deterministic:
1567
+ * - When one page's `id` equals another page's `title`, the `id` wins and the
1568
+ * title-named page is not reachable by that string. Identifiers always beat
1569
+ * labels; there is no positional tie-break to reason about.
1570
+ * - Within each namespace, duplicates resolve to the first page in document
1571
+ * order — the same rule the title namespace has always used.
1572
+ * - A target matching neither namespace is read by shape (see `isUrlTarget`).
1573
+ * A URL-shaped one — `navigate="/reset"`, `navigate="https://…"` — is an
1574
+ * {@link ScreenTransitionGraph.external | external} destination, not a
1575
+ * defect: the DSL documents `navigate` as a "URL or page" target, so the
1576
+ * author wrote something the DSL allows and there is no page to find.
1577
+ * Anything else is a name that should have matched a page and did not, and
1578
+ * only that is {@link ScreenTransitionGraph.dangling | dangling}. Counting
1579
+ * external links as dangling would report every correct outbound link as a
1580
+ * broken screen transition.
1206
1581
  * - **`opens` / `toggles`** target an overlay *within the source page*, not
1207
1582
  * another page, so their `to` is always `null`. They resolve when a `Modal`
1208
- * or `Drawer` in the same page has `id === target` (the only nodes that carry
1209
- * an `id`). Being intra-page, they never appear in `dangling`.
1583
+ * or `Drawer` in the same page has `id === target` — the overlay containers
1584
+ * are the only nodes these two kinds can address. Being intra-page, they
1585
+ * never appear in `dangling`.
1210
1586
  * - **`action`** is an opaque handler id with no structural destination:
1211
1587
  * `to === null`, `resolved === false`, and it is not `dangling`.
1212
1588
  *
1213
1589
  * Item `href` is a raw anchor, not a declared `navigate` intent, and is
1214
- * excluded — consistent with node-level extraction.
1590
+ * excluded — consistent with node-level extraction. The HTML renderer draws the
1591
+ * same line: it emits the authored `href` and the declared intent side by side
1592
+ * as `data-navigate` / `data-opens` / `data-toggles` / `data-action`, so every
1593
+ * edge derived here has a counterpart a consumer of the markup can act on.
1215
1594
  */
1216
1595
 
1217
1596
  /**
@@ -1311,4 +1690,242 @@ declare function getNodeSource(source: string, doc: WireframeDocument, path: str
1311
1690
  */
1312
1691
  declare function buildDomTree(doc: WireframeDocument, pageIndexBase?: number): DomTreeNode[];
1313
1692
 
1314
- export { ANCHOR_LOC_ATTR, ANCHOR_PATH_ATTR, ATTRIBUTE_MAP, ATTRIBUTE_SPECS, type AccessibilityMetrics, AccordionNode, AlertNode, type AnalysisOptions, type AnalysisResult, type AnchorEntry, AnyNode, type AttributeChange, type AttributeSpec, type AttributeValueType, AvatarNode, BadgeNode, BreadcrumbNode, ButtonNode, COMMON_ATTRIBUTES, COMPONENT_MAP, COMPONENT_SPECS, CardNode, CheckboxNode, ColNode, type ComplexityMetrics, type ComponentCategory, type ComponentSpec, type ComponentStats, ContainerComponentNode, ContainerNode, type ContentAnalysis, DEFAULT_VIEWPORT, DEVICE_PRESETS, DataNode, type DiffChangeType, type DiffOptions, type DiffResult, type DiffSummary, DisplayNode, DividerComponentNode, type DomTreeNode, DrawerNode, DropdownNode, type ExportOptions, FeedbackNode, type FigmaAutoLayout, type FigmaColor, type FigmaCounterAxisAlign, type FigmaExportResult, type FigmaLayoutMode, type FigmaNode, type FigmaNodeType, type FigmaPrimaryAxisAlign, type FigmaSize, type FigmaSizingMode, type FigmaSolidFill, type FigmaStroke, type FigmaTextAlign, type FigmaTextStyle, FooterNode, GridNode, HeaderNode, IconNode, ImageNode, InputComponentNode, InputNode, InputType, type InteractionKind, type JsonExportResult, type JsonNode, type LayoutAnalysis, LayoutNode, LeafNode, LinkNode, ListNode, MainNode, ModalNode, NODE_TYPE_MAP, NavNode, NavigationNode, type NodeChange, type NodePredicate, NodeType, OverlayNode, PageNode, PlaceholderNode, PopoverNode, type PreviewWrapperOptions, ProgressNode, RadioNode, RowNode, type ScreenAction, type ScreenDisplay, type ScreenElement, type ScreenFields, type ScreenFieldsSummary, type ScreenInput, type ScreenTransitionGraph, SectionNode, SelectNode, SidebarNode, SliderNode, SourceLocation, type SourceSlice, SpinnerNode, SwitchNode, TableNode, TabsNode, TextContentNode, TextNode, TextareaNode, TitleNode, ToastNode, TooltipNode, type TransitionEdge, type TransitionScreen, type TreeMetrics, VALID_ATTRIBUTE_NAMES, VALID_COMPONENT_NAMES, type ValidationError, type ValidationOptions, type ValidationResult, type ViewportSize, type WalkCallback, WireframeDocument, analyze, areIdentical, buildAnchorIndex, buildDomTree, calculateViewportScale, cloneNode, contains, countNodes, diff, exportToFigma, exportToFigmaString, exportToJson, exportToJsonString, extractAllScreenFields, extractScreenFields, extractScreenTransitions, find, findAll, findByType, formatWireframeCode, getAncestors, getChangeSummary, getDevicePresets, getMaxDepth, getNodeSource, getNodeTypes, getPageSource, getValidAttributes, getValidationErrors, hasChildren, importFromJson, isAccordionNode, isAlertNode, isAvatarNode, isBadgeNode, isBreadcrumbNode, isButtonNode, isCardNode, isCheckboxNode, isColNode, isContainerComponentNode, isContainerNode, isDataNode, isDisplayNode, isDividerNode, isDrawerNode, isDropdownNode, isFeedbackNode, isFooterNode, isGridNode, isHeaderNode, isIconNode, isImageNode, isInputComponentNode, isInputNode, isLayoutNode, isLeafNode, isLinkNode, isListNode, isMainNode, isModalNode, isNavNode, isNavigationNode, isNodeType, isOverlayNode, isPageNode, isPlaceholderNode, isPopoverNode, isProgressNode, isRadioNode, isRowNode, isSectionNode, isSelectNode, isSidebarNode, isSliderNode, isSpinnerNode, isSwitchNode, isTableNode, isTabsNode, isTextContentNode, isTextNode, isTextareaNode, isTitleNode, isToastNode, isTooltipNode, isValidAst, isValidAttribute, isValidDevicePreset, mapNodes, parseViewportString, printWireframe, resetFigmaIdCounter, resolveAnchor, resolveViewport, validate, walk, walkDocument, wrapInPreviewContainer };
1693
+ /**
1694
+ * What a `navigate` target names.
1695
+ *
1696
+ * The DSL documents `navigate` as pointing at "a URL or a page", so every target
1697
+ * is read one of two ways, and the reading decides everything downstream. A page
1698
+ * name resolves against the document and travels to the consumer as declared
1699
+ * intent; a URL is a destination the browser already knows how to reach, so it
1700
+ * belongs in the anchor and the document graph has nothing to say about it.
1701
+ *
1702
+ * The renderer and the transition extractor must read a target identically — the
1703
+ * renderer decides whether the value belongs in `href`, the extractor decides
1704
+ * whether an unmatched value is an authoring mistake. Two copies of that rule
1705
+ * would drift, and the moment they disagree one of the two starts calling
1706
+ * correct authoring a defect. So the rule lives here, below both, and neither
1707
+ * layer has to depend on the other to reach it.
1708
+ */
1709
+ /**
1710
+ * Whether a `navigate` target is a URL rather than the name of a page.
1711
+ *
1712
+ * A URL is recognised by shape, not by resolving it:
1713
+ * - a path or protocol-relative reference — `/reset`, `//cdn.example.com/x`
1714
+ * - an in-page fragment or bare query — `#terms`, `?tab=2`
1715
+ * - anything opening with an RFC 3986 scheme — `https:`, `mailto:`, `tel:`
1716
+ *
1717
+ * A target containing whitespace is never a URL: a URL carrying a space is
1718
+ * invalid until the space is percent-encoded, whereas page titles are written
1719
+ * as prose and routinely contain spaces. Screening on that first is what keeps
1720
+ * an English heading like `"Note: draft"` from reading as a scheme.
1721
+ *
1722
+ * The remaining ambiguities are decided in favour of "page", because a page name
1723
+ * is the common case and the cost of the two mistakes is not symmetric: calling
1724
+ * a page a URL yields a link that goes nowhere, while calling a URL a page
1725
+ * yields an edge reported as unresolved — visible, not silent. So a
1726
+ * schemeless host (`www.example.com`) is a page name; authors write the scheme.
1727
+ */
1728
+ declare function isUrlTarget(target: string | undefined): target is string;
1729
+
1730
+ /** A source file and exact span within it. */
1731
+ interface AppSourceSpan {
1732
+ sourceId: string;
1733
+ location: SourceLocation;
1734
+ }
1735
+ /** The two reusable definition kinds addressable by an app reference. */
1736
+ type AppDefinitionKind = 'layout' | 'component';
1737
+ /** Every stable, top-level node kind in a linked application. */
1738
+ type AppNodeKind = AppDefinitionKind | 'screen';
1739
+ /** A manifest entry assigning one module its stable application namespace. */
1740
+ interface AppManifestModule {
1741
+ id: string;
1742
+ namespace: string;
1743
+ location: SourceLocation;
1744
+ }
1745
+ /**
1746
+ * Core-owned manifest describing the modules that make up one application.
1747
+ * @public
1748
+ */
1749
+ interface AppManifest {
1750
+ id: string;
1751
+ sourceId: string;
1752
+ modules: readonly AppManifestModule[];
1753
+ }
1754
+ /** A reference to a layout or component, local to the owner namespace by default. */
1755
+ interface AppReferenceInput {
1756
+ kind: AppDefinitionKind;
1757
+ id: string;
1758
+ namespace?: string;
1759
+ source: AppSourceSpan;
1760
+ }
1761
+ interface AppNodeInput<TNode> {
1762
+ /** Stable identifier within the module namespace and node kind. */
1763
+ id: string;
1764
+ node: TNode;
1765
+ source: AppSourceSpan;
1766
+ }
1767
+ /** A layout declaration and the reusable definitions it depends on. */
1768
+ interface AppLayoutInput extends AppNodeInput<LayoutDefinitionNode> {
1769
+ references?: readonly AppReferenceInput[];
1770
+ }
1771
+ /** A component declaration and the reusable definitions it depends on. */
1772
+ interface AppComponentInput extends AppNodeInput<ComponentDefinitionNode> {
1773
+ references?: readonly AppReferenceInput[];
1774
+ }
1775
+ /** A screen declaration and the layouts/components it consumes. */
1776
+ interface AppScreenInput extends AppNodeInput<PageNode> {
1777
+ references?: readonly AppReferenceInput[];
1778
+ }
1779
+ /**
1780
+ * One parsed Wireweave module supplied to the Core linker.
1781
+ * @public
1782
+ */
1783
+ interface AppModuleInput {
1784
+ id: string;
1785
+ source: AppSourceSpan;
1786
+ layouts: readonly AppLayoutInput[];
1787
+ components: readonly AppComponentInput[];
1788
+ screens: readonly AppScreenInput[];
1789
+ }
1790
+ /** Opaque stable identity assigned by the linker. */
1791
+ type AppNodeId = string & {
1792
+ readonly __appNodeId: unique symbol;
1793
+ };
1794
+ /** Stable identity of one expanded component invocation. */
1795
+ type AppComponentInstanceId = string & {
1796
+ readonly __appComponentInstanceId: unique symbol;
1797
+ };
1798
+ /** A reference whose target has been resolved to stable app identity. */
1799
+ interface ResolvedAppReference {
1800
+ kind: AppDefinitionKind;
1801
+ id: string;
1802
+ namespace: string;
1803
+ targetId: AppNodeId;
1804
+ source: AppSourceSpan;
1805
+ }
1806
+ interface ResolvedAppNode<TKind extends AppNodeKind, TNode> {
1807
+ nodeId: AppNodeId;
1808
+ kind: TKind;
1809
+ id: string;
1810
+ moduleId: string;
1811
+ namespace: string;
1812
+ node: TNode;
1813
+ source: AppSourceSpan;
1814
+ references: readonly ResolvedAppReference[];
1815
+ }
1816
+ type ResolvedAppLayout = ResolvedAppNode<'layout', LayoutDefinitionNode>;
1817
+ type ResolvedAppComponent = ResolvedAppNode<'component', ComponentDefinitionNode>;
1818
+ type ResolvedAppScreen = ResolvedAppNode<'screen', PageNode>;
1819
+ /** Stable node-to-source mapping emitted in manifest order. */
1820
+ interface AppSourceMapEntry {
1821
+ nodeId: AppNodeId;
1822
+ source: AppSourceSpan;
1823
+ }
1824
+ /** One resolved module in a linked application document. */
1825
+ interface ResolvedAppModule {
1826
+ id: string;
1827
+ namespace: string;
1828
+ layouts: readonly ResolvedAppLayout[];
1829
+ components: readonly ResolvedAppComponent[];
1830
+ screens: readonly ResolvedAppScreen[];
1831
+ }
1832
+ /**
1833
+ * Core's dependency-closed representation of a multi-module application.
1834
+ * @public
1835
+ */
1836
+ interface AppDocument {
1837
+ type: 'AppDocument';
1838
+ id: string;
1839
+ modules: readonly ResolvedAppModule[];
1840
+ layouts: readonly ResolvedAppLayout[];
1841
+ components: readonly ResolvedAppComponent[];
1842
+ screens: readonly ResolvedAppScreen[];
1843
+ sourceMap: readonly AppSourceMapEntry[];
1844
+ }
1845
+ /** Stable machine-readable linker diagnostic kinds. */
1846
+ type AppLinkDiagnosticCode = 'missing-module' | 'duplicate-module' | 'duplicate-namespace' | 'duplicate-definition' | 'duplicate-screen' | 'missing-reference' | 'cyclic-reference' | 'invalid-component-definition' | 'invalid-component-invocation';
1847
+ /**
1848
+ * A deterministic linker failure with the exact source span that caused it.
1849
+ * @public
1850
+ */
1851
+ interface AppLinkDiagnostic {
1852
+ code: AppLinkDiagnosticCode;
1853
+ message: string;
1854
+ source: AppSourceSpan;
1855
+ }
1856
+ type AppLinkResult = {
1857
+ ok: true;
1858
+ document: AppDocument;
1859
+ diagnostics: readonly [];
1860
+ } | {
1861
+ ok: false;
1862
+ document: null;
1863
+ diagnostics: readonly AppLinkDiagnostic[];
1864
+ };
1865
+
1866
+ /**
1867
+ * Create the stable identity used by linked documents and source maps.
1868
+ * Each segment is encoded so punctuation in authored identifiers cannot collide.
1869
+ *
1870
+ * @public
1871
+ */
1872
+ declare function createAppNodeId(namespace: string, kind: AppNodeKind, id: string): AppNodeId;
1873
+ /** Create the stable identity of an invocation from its owner and structural path. */
1874
+ declare function createAppComponentInstanceId(ownerId: AppNodeId, targetId: AppNodeId, path: readonly number[]): AppComponentInstanceId;
1875
+ /**
1876
+ * Link parsed Wireweave modules into one dependency-closed application document.
1877
+ * The function is pure and returns no document whenever validation finds an error.
1878
+ *
1879
+ * @public
1880
+ * @example
1881
+ * `const result = linkApp(manifest, modules)`
1882
+ */
1883
+ declare function linkApp(manifest: AppManifest, modules: readonly AppModuleInput[]): AppLinkResult;
1884
+
1885
+ /**
1886
+ * Options for {@link compileApp}.
1887
+ *
1888
+ * Application artifacts always use neutral annotation styling. The option is
1889
+ * intentionally omitted here so every compiler caller gets the same wireframe
1890
+ * presentation while legacy render entry points keep their historical default.
1891
+ *
1892
+ * @public
1893
+ */
1894
+ type CompileAppOptions = Omit<SiteOptions, 'annotationStyle'>;
1895
+ /** Result of linking modules and compiling the resulting application. @public */
1896
+ type AppCompileResult = {
1897
+ ok: true;
1898
+ document: AppDocument;
1899
+ html: string;
1900
+ diagnostics: readonly [];
1901
+ } | {
1902
+ ok: false;
1903
+ document: null;
1904
+ html: null;
1905
+ diagnostics: readonly AppLinkDiagnostic[];
1906
+ };
1907
+ /**
1908
+ * Compile one linked application into a deterministic, self-contained HTML document.
1909
+ *
1910
+ * The linker has already expanded component invocations and resolved shared
1911
+ * layouts. This function only projects those resolved nodes into the generic
1912
+ * site compositor, using stable app identities for layout names so modules
1913
+ * cannot collide.
1914
+ *
1915
+ * @public
1916
+ * @example
1917
+ * `const html = compileApp(linked.document)`
1918
+ */
1919
+ declare function compileApp(document: AppDocument, options?: CompileAppOptions): string;
1920
+ /**
1921
+ * Link application modules and compile them when linking succeeds.
1922
+ *
1923
+ * Linker diagnostics remain explicit and no partial HTML is emitted on failure.
1924
+ *
1925
+ * @public
1926
+ * @example
1927
+ * `const result = linkAndCompileApp(manifest, modules)`
1928
+ */
1929
+ declare function linkAndCompileApp(manifest: AppManifest, modules: readonly AppModuleInput[], options?: CompileAppOptions): AppCompileResult;
1930
+
1931
+ export { ANCHOR_LOC_ATTR, ANCHOR_PATH_ATTR, type AccessibilityMetrics, AccordionNode, AlertNode, type AnalysisOptions, type AnalysisResult, type AnchorEntry, AnyNode, 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 AppScreenInput, type AppSourceMapEntry, type AppSourceSpan, type AttributeChange, AvatarNode, BadgeNode, BreadcrumbNode, ButtonNode, CardNode, CheckboxNode, ColNode, type CompileAppOptions, type ComplexityMetrics, ComponentCategory, ComponentDefinitionNode, type ComponentParameterReference, type ComponentStats, ComponentUseNode, ContainerComponentNode, ContainerNode, type ContentAnalysis, DEFAULT_VIEWPORT, DEVICE_PRESETS, DataNode, DefinitionNode, type DiffChangeType, type DiffOptions, type DiffResult, type DiffSummary, DisplayNode, DividerComponentNode, type DomTreeNode, DrawerNode, DropdownNode, type ExportOptions, FeedbackNode, type FigmaAutoLayout, type FigmaColor, type FigmaCounterAxisAlign, type FigmaExportResult, type FigmaLayoutMode, type FigmaNode, type FigmaNodeType, type FigmaPrimaryAxisAlign, type FigmaSize, type FigmaSizingMode, type FigmaSolidFill, type FigmaStroke, type FigmaTextAlign, type FigmaTextStyle, FooterNode, GridNode, HeaderNode, IconNode, ImageNode, InputComponentNode, InputNode, InputType, type InteractionDiagnostic, type InteractionDiagnosticCode, InteractionEffect, type InteractionKind, type InteractionModel, type JsonExportResult, type JsonNode, type LayoutAnalysis, LayoutDefinitionNode, LayoutNode, LeafNode, LinkNode, ListNode, MainNode, ModalNode, NavNode, NavigationNode, type NodeChange, type NodePredicate, NodeType, type NormalizedInteraction, type NormalizedInteractionEffect, type NormalizedInteractionHandler, OverlayNode, PageNode, PlaceholderNode, PopoverNode, type PreviewWrapperOptions, ProgressNode, REPEAT_EXPANSION_BUDGET, RadioNode, RepeatBudgetError, type ResolvedAppComponent, type ResolvedAppLayout, type ResolvedAppModule, type ResolvedAppReference, type ResolvedAppScreen, RowNode, type ScreenAction, type ScreenDisplay, type ScreenElement, type ScreenFields, type ScreenFieldsSummary, type ScreenInput, type ScreenTransitionGraph, SectionNode, SelectNode, SidebarNode, SiteOptions, SliderNode, SlotNode, SourceLocation, type SourceSlice, SpinnerNode, StateDeclaration, StateGuard, SwitchNode, TableNode, TabsNode, TextContentNode, TextNode, TextareaNode, TitleNode, ToastNode, TooltipNode, type TransitionEdge, type TransitionScreen, type TreeMetrics, type ValidationError, type ValidationOptions, type ValidationResult, type ViewportSize, type WalkCallback, WireframeDocument, analyze, areIdentical, buildAnchorIndex, buildDomTree, calculateViewportScale, cloneNode, collectInteractions, collectParameterReferences, compileApp, contains, countNodes, createAppComponentInstanceId, createAppNodeId, diff, documentDefinitions, documentPages, expandRepeats, expandVariants, exportToFigma, exportToFigmaString, exportToJson, exportToJsonString, extractAllScreenFields, extractScreenFields, extractScreenTransitions, filterUnscopedPages, filterVariantScope, find, findAll, findByType, formatWireframeCode, getAncestors, getChangeSummary, getDevicePresets, getMaxDepth, getNodeSource, getNodeTypes, getPageSource, getValidationErrors, hasChildren, importFromJson, interactionSignature, isAccordionNode, isAlertNode, isAvatarNode, isBadgeNode, isBreadcrumbNode, isButtonNode, isCardNode, isCheckboxNode, isColNode, isComponentDefinitionNode, isComponentUseNode, isContainerComponentNode, isContainerNode, isDataNode, isDefinitionNode, isDisplayNode, isDividerNode, isDrawerNode, isDropdownNode, isFeedbackNode, isFooterNode, isGridNode, isHeaderNode, isIconNode, isImageNode, isInputComponentNode, isInputNode, isLayoutDefinitionNode, isLayoutNode, isLeafNode, isLinkNode, isListNode, isMainNode, isModalNode, isNavNode, isNavigationNode, isNodeType, isOverlayNode, isPageNode, isPlaceholderNode, isPopoverNode, isProgressNode, isRadioNode, isRowNode, isSectionNode, isSelectNode, isSidebarNode, isSliderNode, isSlotNode, isSpinnerNode, isSwitchNode, isTableNode, isTabsNode, isTextContentNode, isTextNode, isTextareaNode, isTitleNode, isToastNode, isTooltipNode, isUrlTarget, isValidAst, isValidDevicePreset, linkAndCompileApp, linkApp, mapNodes, normalizeInteractionHandlers, normalizeStateGuard, parameterReferenceName, parseViewportString, printWireframe, resetFigmaIdCounter, resolveAnchor, resolveViewport, validate, variantScope, walk, walkDocument, wrapInPreviewContainer };