@wireweave/core 3.1.0-beta.4 → 3.1.0-beta.5

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,8 +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 ComponentDefinitionNode, H as ComponentUseNode, I as ContainerComponentNode, J as ContainerNode, K as DataNode, L as DefinitionNode, N as DisplayNode, O as DividerComponentNode, Q as DrawerNode, T as DropdownNode, U as FeedbackNode, W as FooterNode, X as GridNode, _ as HeaderNode, a0 as IconNode, a3 as ImageNode, a4 as InputComponentNode, a5 as InputNode, ab as LayoutDefinitionNode, ac as LayoutNode, ad as LeafNode, ae as LinkNode, ag as ListNode, ah as MainNode, ak as ModalNode, aq as NavNode, ar as NavigationNode, as as NodeType, at as OverlayNode, au as PageNode, av as PlaceholderNode, aw as PopoverNode, az as ProgressNode, aA as RadioNode, aC as RowNode, aD as SectionNode, aE as SelectNode, aH as SidebarNode, aJ as SliderNode, aK as SlotNode, aO as SpinnerNode, aW as SwitchNode, aY as TableNode, aZ as TabsNode, a$ as TextContentNode, b0 as TextNode, b4 as TextareaNode, b6 as TitleNode, b7 as ToastNode, b9 as TooltipNode, be as WireframeDocument, aL as SourceLocation, aS as StateDeclaration, aT as StateGuard, a7 as InteractionEffect, a6 as InputType } from './types-Bb3NSNUs.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, P as DividerNode, R as DrawerPosition, S as DropdownItemNode, V as FlexProps, Y as GridProps, Z as GuardedOutcomeProps, $ as HeightValue, a1 as IconSize, a2 as IconSizeToken, a8 as InteractionHandler, a9 as InteractiveProps, aa as JustifyValue, af as ListItemNode, ai as MarkerColor, aj as MarkerNode, al as NavBlockItem, am as NavChild, an as NavDivider, ao as NavGroupNode, ap as NavItem, ax as Position, ay as PositionProps, aB as RelativeNode, aF as SelectOption, aG as ShadowValue, aI as SizeProps, aM as SpacingProps, aN as SpacingValue, aP as SpinnerSize, aQ as SpinnerSizeToken, aR as StackNode, aU as StateValue, aV as StateValueType, aX as TabNode, a_ as TextAlign, b1 as TextSize, b2 as TextSizeToken, b3 as TextWeight, b5 as TitleLevel, b8 as ToastPosition, ba as TooltipPosition, bb as TopLevelNode, bc as ValueWithUnit, bd as WidthValue } from './types-Bb3NSNUs.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, aA as RowNode, aB as SectionNode, aC as SelectNode, aF as SidebarNode, aH as SliderNode, aI as SlotNode, aM as SpinnerNode, aU as SwitchNode, aW as TableNode, aX as TabsNode, aZ as TextContentNode, a_ as TextNode, b2 as TextareaNode, b4 as TitleNode, b5 as ToastNode, b7 as TooltipNode, bc as WireframeDocument, aJ as SourceLocation, aQ as StateDeclaration, aR as StateGuard, a6 as InteractionEffect, a5 as InputType } from './types-BiDAgo6f.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, aD as SelectOption, aE as ShadowValue, aG as SizeProps, aK as SpacingProps, aL as SpacingValue, aN as SpinnerSize, aO as SpinnerSizeToken, aP as StackNode, aS as StateValue, aT as StateValueType, aV as TabNode, aY as TextAlign, a$ as TextSize, b0 as TextSizeToken, b1 as TextWeight, b3 as TitleLevel, b6 as ToastPosition, b8 as TooltipPosition, b9 as TopLevelNode, ba as ValueWithUnit, bb as WidthValue } from './types-BiDAgo6f.js';
3
3
  export { ExpectedToken, ParseError, ParseErrorInfo, ParseOptions, ParseResult, getErrors, isValid, parse, tryParse } from './parser.js';
4
4
  import { SiteOptions } from './renderer.js';
5
- export { AnnotationStyle, CanvasOptions, CanvasRenderResult, HtmlRenderer, IconData, IconElement, InteractiveAttrs, PageRenderResult, PlacedPage, RenderContext, RenderOptions, RenderResult, ShellMiss, SiteModel, SiteScreen, SiteShell, SvgRenderOptions, SvgRenderResult, ThemeColors, ThemeConfig, anchorIntent, buildSiteModel, createHtmlRenderer, darkTheme, defaultTheme, generateComponentStyles, generateStyles, getIconData, getTheme, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderSite, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions } 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';
6
8
 
7
9
  /**
8
10
  * Type guards for wireweave AST
@@ -17,6 +19,7 @@ declare function hasChildren(node: AnyNode): node is AnyNode & {
17
19
  declare function isLeafNode(node: AnyNode): node is LeafNode;
18
20
  declare function isLayoutNode(node: AnyNode): node is LayoutNode;
19
21
  declare function isPageNode(node: AnyNode): node is PageNode;
22
+ /** A `layout` or `component` definition — a named tree, not a screen. */
20
23
  declare function isDefinitionNode(node: AnyNode): node is DefinitionNode;
21
24
  declare function isLayoutDefinitionNode(node: AnyNode): node is LayoutDefinitionNode;
22
25
  declare function isComponentDefinitionNode(node: AnyNode): node is ComponentDefinitionNode;
@@ -101,19 +104,32 @@ declare function walk(node: AnyNode, callback: WalkCallback, parent?: AnyNode, d
101
104
  /**
102
105
  * Walk through a document's AST
103
106
  *
107
+ * Covers every top-level child — pages *and* reuse definitions — because a walk
108
+ * is about visiting nodes, not about selecting screens.
109
+ *
104
110
  * @param document - The wireframe document
105
111
  * @param callback - Function called for each node
106
112
  */
107
113
  declare function walkDocument(document: WireframeDocument, callback: WalkCallback): void;
108
114
  /**
109
- * Return only the document's pages, in source order.
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.
110
122
  *
111
- * Layout definitions share the document's top-level list with pages but are
112
- * not screens. Page-indexed consumers must use this helper so a definition
113
- * never becomes an accidental page.
123
+ * @param document - The wireframe document
124
+ * @returns Only the `Page` children
114
125
  */
115
126
  declare function documentPages(document: WireframeDocument): PageNode[];
116
- /** Return the document's named layout definitions, in source order. */
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
+ */
117
133
  declare function documentDefinitions(document: WireframeDocument): DefinitionNode[];
118
134
  /**
119
135
  * Find the first node matching a predicate
@@ -301,105 +317,6 @@ interface PreviewWrapperOptions {
301
317
  */
302
318
  declare function wrapInPreviewContainer(html: string, viewport: ViewportSize, options?: PreviewWrapperOptions): string;
303
319
 
304
- /**
305
- * Types for Wireweave DSL Specification
306
- */
307
- /**
308
- * Attribute value type
309
- */
310
- type AttributeValueType = 'boolean' | 'number' | 'string' | 'string[]' | 'object' | 'object[]' | 'enum';
311
- /**
312
- * Attribute definition
313
- */
314
- interface AttributeSpec {
315
- /** Attribute name */
316
- name: string;
317
- /** Value type */
318
- type: AttributeValueType;
319
- /** Enum values (if type is 'enum') */
320
- values?: readonly string[];
321
- /** Description for documentation */
322
- description?: string;
323
- }
324
- /**
325
- * Component category
326
- */
327
- type ComponentCategory = 'layout' | 'grid' | 'container' | 'text' | 'input' | 'display' | 'data' | 'feedback' | 'overlay' | 'navigation' | 'annotation';
328
- /**
329
- * Component definition
330
- */
331
- interface ComponentSpec {
332
- /** Component name (lowercase, as used in DSL) */
333
- name: string;
334
- /** AST node type (PascalCase) */
335
- nodeType: string;
336
- /** Component category */
337
- category: ComponentCategory;
338
- /** Valid attributes for this component (names only, definitions in ATTRIBUTES) */
339
- attributes: readonly string[];
340
- /** Whether this component can have children */
341
- hasChildren: boolean;
342
- /** Description for documentation */
343
- description?: string;
344
- }
345
-
346
- /**
347
- * Wireweave DSL Component Definitions
348
- *
349
- * Complete list of all valid components in Wireweave DSL.
350
- * Each component specifies its valid attributes.
351
- */
352
-
353
- /**
354
- * All valid components in Wireweave DSL
355
- */
356
- declare const COMPONENT_SPECS: readonly ComponentSpec[];
357
- /**
358
- * Set of all valid component names for quick lookup
359
- */
360
- declare const VALID_COMPONENT_NAMES: ReadonlySet<string>;
361
- /**
362
- * Map of component name to spec for quick lookup
363
- */
364
- declare const COMPONENT_MAP: ReadonlyMap<string, ComponentSpec>;
365
- /**
366
- * Map of AST node type to spec for quick lookup
367
- */
368
- declare const NODE_TYPE_MAP: ReadonlyMap<string, ComponentSpec>;
369
- /**
370
- * Get valid attributes for a component (by name or node type)
371
- */
372
- declare function getValidAttributes(componentNameOrType: string): readonly string[] | undefined;
373
- /**
374
- * Check if an attribute is valid for a component
375
- */
376
- declare function isValidAttribute(componentNameOrType: string, attributeName: string): boolean;
377
-
378
- /**
379
- * Wireweave DSL Attribute Definitions
380
- *
381
- * Complete list of all valid attributes in Wireweave DSL.
382
- */
383
-
384
- /**
385
- * All valid attributes in Wireweave DSL
386
- */
387
- declare const ATTRIBUTE_SPECS: readonly AttributeSpec[];
388
- /**
389
- * Set of all valid attribute names for quick lookup
390
- */
391
- declare const VALID_ATTRIBUTE_NAMES: ReadonlySet<string>;
392
- /**
393
- * Map of attribute name to spec for quick lookup
394
- */
395
- declare const ATTRIBUTE_MAP: ReadonlyMap<string, AttributeSpec>;
396
- /**
397
- * Common attributes available to most components
398
- */
399
- declare const COMMON_ATTRIBUTES: readonly string[];
400
- /** Attributes shared by elements that can trigger interactions. */
401
- declare const INTERACTIVE_ATTRIBUTES: readonly string[];
402
-
403
320
  /**
404
321
  * Wireweave DSL Validation
405
322
  *
@@ -1167,6 +1084,11 @@ interface ScreenFields {
1167
1084
  }
1168
1085
  /**
1169
1086
  * A node in the screen-transition graph.
1087
+ *
1088
+ * `id` is the page's declared identifier — a stable slug an author opted into —
1089
+ * and `title` is its display heading. They are separate namespaces: `id` is what
1090
+ * a `navigate` target should key off, `title` is what a reader sees. Either can
1091
+ * be absent.
1170
1092
  */
1171
1093
  interface TransitionScreen {
1172
1094
  id?: string;
@@ -1187,6 +1109,10 @@ interface TransitionEdge {
1187
1109
  * The destination page for a resolved `navigate` edge. Always `null` for
1188
1110
  * `opens` / `toggles` / `action`, which are intra-page or opaque and never
1189
1111
  * cross a page boundary.
1112
+ *
1113
+ * `id` / `title` mirror {@link TransitionScreen}: present when the page
1114
+ * declares them, so a consumer can address the destination by its stable slug
1115
+ * rather than by display text.
1190
1116
  */
1191
1117
  to: {
1192
1118
  pageIndex: number;
@@ -1218,18 +1144,27 @@ interface TransitionEdge {
1218
1144
  };
1219
1145
  };
1220
1146
  /**
1221
- * Whether `target` resolved to a concrete destination for its kind:
1222
- * - `navigate`: a page whose title matches `target`, or a URL-shaped external
1223
- * destination outside this document.
1147
+ * Whether `target` names a concrete destination for its kind:
1148
+ * - `navigate`: a page whose `id` matches `target`, or — failing that — whose
1149
+ * `title` matches it. Identifiers are consulted before display text; see
1150
+ * `extract/transitions.ts` for why. Also `true` for an `external` target: a
1151
+ * URL is a complete destination, it is simply not one of this document's
1152
+ * pages, which is why `to` is `null` there.
1224
1153
  * - `opens` / `toggles`: a `Modal` / `Drawer` with `id === target` in the
1225
1154
  * source page.
1226
1155
  * - `action`: always `false` (an opaque handler id has no structural target).
1227
1156
  */
1228
1157
  resolved: boolean;
1229
1158
  /**
1230
- * Present, and always `true`, when a `navigate` target is a URL rather than a
1231
- * page name. External edges are resolved destinations outside this document,
1232
- * so `to` remains `null` and they never appear in `dangling`.
1159
+ * Present, and always `true`, when a `navigate` target is a URL rather than
1160
+ * the name of a page (see `interaction/target.ts`). Such an edge leaves the
1161
+ * document: `to` is `null` because there is no page to point at, and it is
1162
+ * never {@link ScreenTransitionGraph.dangling | dangling} — an outbound link
1163
+ * is a destination the author meant, not a reference that failed to resolve.
1164
+ *
1165
+ * This is what separates an external link from an `action`: both have
1166
+ * `to === null`, but an `action` is an opaque handler with `resolved: false`,
1167
+ * while an external link is a real destination the browser can follow.
1233
1168
  */
1234
1169
  external?: true;
1235
1170
  }
@@ -1240,13 +1175,20 @@ interface ScreenTransitionGraph {
1240
1175
  screens: TransitionScreen[];
1241
1176
  edges: TransitionEdge[];
1242
1177
  /**
1243
- * The subset of `navigate` edges whose target matched no page title and was
1244
- * not URL-shaped (`resolved === false`, `to === null`). Intra-page
1245
- * `opens` / `toggles`, opaque `action` edges, and external URLs never appear
1246
- * here.
1178
+ * The subset of `navigate` edges whose target matched neither a page `id` nor
1179
+ * a page title and is not a URL (`resolved === false`, `to === null`) — a name
1180
+ * that was meant to be a screen and found none. This is the defect list: a
1181
+ * consumer reporting "broken transitions" counts exactly these. Intra-page
1182
+ * `opens` / `toggles` and opaque `action` edges are not page transitions and
1183
+ * never appear here, and neither do `external` links.
1247
1184
  */
1248
1185
  dangling: TransitionEdge[];
1249
- /** URL-shaped `navigate` edges that leave the current document. */
1186
+ /**
1187
+ * The subset of `navigate` edges leaving the document — targets that are URLs
1188
+ * rather than page names ({@link TransitionEdge.external}). Kept apart from
1189
+ * `dangling` so a consumer can show outbound links without counting correct
1190
+ * authoring as breakage.
1191
+ */
1250
1192
  external: TransitionEdge[];
1251
1193
  }
1252
1194
 
@@ -1269,6 +1211,9 @@ interface ScreenTransitionGraph {
1269
1211
  declare function extractScreenFields(page: PageNode): ScreenFields;
1270
1212
  /**
1271
1213
  * Extract {@link ScreenFields} for every page in a document, in document order.
1214
+ *
1215
+ * Reuse definitions are skipped: a `layout` is not a screen and has no fields
1216
+ * of its own until a page is drawn inside it.
1272
1217
  */
1273
1218
  declare function extractAllScreenFields(doc: WireframeDocument): ScreenFields[];
1274
1219
 
@@ -1286,27 +1231,60 @@ declare function extractAllScreenFields(doc: WireframeDocument): ScreenFields[];
1286
1231
  * `nav ["…"]` array items and `nav { item … group { item … } }` block items
1287
1232
  * (including grouped items), plus dropdown and breadcrumb items, are extracted.
1288
1233
  * Item triggers carry the container's type in `trigger.nodeType` and the item's
1289
- * position in `trigger.item.index`. `Tabs` items are plain strings without
1234
+ * position in `trigger.item.index`. That position counts only elements that can
1235
+ * hold an intent — dividers and group headings are skipped, in every container
1236
+ * alike — because the index is the handle that points back at an edge's origin,
1237
+ * and an element incapable of producing an edge must not shift what the handle
1238
+ * addresses. `Tabs` items are plain strings without
1290
1239
  * `InteractiveProps` and contribute no transition; their panel content is
1291
1240
  * reached by normal node traversal.
1292
1241
  *
1293
1242
  * ## Resolution semantics
1294
1243
  *
1295
- * - **`navigate`** is a page transition. Its target resolves to a page when the
1296
- * target string, trimmed, exactly matches a page `title` (case-sensitive). On
1297
- * duplicate titles the first page in document order wins. When no title
1298
- * matches, URL-shaped targets (`navigate="/dashboard"`, `https://…`) are
1299
- * reported as {@link ScreenTransitionGraph.external | external}; unmatched
1300
- * plain names remain {@link ScreenTransitionGraph.dangling | dangling}.
1244
+ * - **`navigate`** is a page transition. Its trimmed target is matched, exactly
1245
+ * and case-sensitively, against **page `id` first and page `title` second**.
1246
+ *
1247
+ * Identifiers are how this DSL names a target: `opens` / `toggles` already
1248
+ * address a `Modal` or `Drawer` by its `id`, so a page addressed by `id` is
1249
+ * the same rule reaching the one container that had been left out — an author
1250
+ * learns one way to point at something, not two.
1251
+ *
1252
+ * The two are different kinds of name. An `id` is a stable identifier the
1253
+ * author opted into (`page "결제 내역" id=billing`); a `title` is display text
1254
+ * that is optional, need not be unique, and is expected to change as copy is
1255
+ * edited. Resolving identifiers first means rewording a heading cannot
1256
+ * silently turn every edge pointing at that screen into a dangling one. Title
1257
+ * matching stays as the fallback because it is how the corpus is written
1258
+ * today, and dropping it would strand every existing document.
1259
+ *
1260
+ * Consequences of that order, all deterministic:
1261
+ * - When one page's `id` equals another page's `title`, the `id` wins and the
1262
+ * title-named page is not reachable by that string. Identifiers always beat
1263
+ * labels; there is no positional tie-break to reason about.
1264
+ * - Within each namespace, duplicates resolve to the first page in document
1265
+ * order — the same rule the title namespace has always used.
1266
+ * - A target matching neither namespace is read by shape (see `isUrlTarget`).
1267
+ * A URL-shaped one — `navigate="/reset"`, `navigate="https://…"` — is an
1268
+ * {@link ScreenTransitionGraph.external | external} destination, not a
1269
+ * defect: the DSL documents `navigate` as a "URL or page" target, so the
1270
+ * author wrote something the DSL allows and there is no page to find.
1271
+ * Anything else is a name that should have matched a page and did not, and
1272
+ * only that is {@link ScreenTransitionGraph.dangling | dangling}. Counting
1273
+ * external links as dangling would report every correct outbound link as a
1274
+ * broken screen transition.
1301
1275
  * - **`opens` / `toggles`** target an overlay *within the source page*, not
1302
1276
  * another page, so their `to` is always `null`. They resolve when a `Modal`
1303
- * or `Drawer` in the same page has `id === target` (the only nodes that carry
1304
- * an `id`). Being intra-page, they never appear in `dangling`.
1277
+ * or `Drawer` in the same page has `id === target` — the overlay containers
1278
+ * are the only nodes these two kinds can address. Being intra-page, they
1279
+ * never appear in `dangling`.
1305
1280
  * - **`action`** is an opaque handler id with no structural destination:
1306
1281
  * `to === null`, `resolved === false`, and it is not `dangling`.
1307
1282
  *
1308
1283
  * Item `href` is a raw anchor, not a declared `navigate` intent, and is
1309
- * excluded — consistent with node-level extraction.
1284
+ * excluded — consistent with node-level extraction. The HTML renderer draws the
1285
+ * same line: it emits the authored `href` and the declared intent side by side
1286
+ * as `data-navigate` / `data-opens` / `data-toggles` / `data-action`, so every
1287
+ * edge derived here has a counterpart a consumer of the markup can act on.
1310
1288
  */
1311
1289
 
1312
1290
  /**
@@ -1406,6 +1384,43 @@ declare function getNodeSource(source: string, doc: WireframeDocument, path: str
1406
1384
  */
1407
1385
  declare function buildDomTree(doc: WireframeDocument, pageIndexBase?: number): DomTreeNode[];
1408
1386
 
1387
+ /**
1388
+ * What a `navigate` target names.
1389
+ *
1390
+ * The DSL documents `navigate` as pointing at "a URL or a page", so every target
1391
+ * is read one of two ways, and the reading decides everything downstream. A page
1392
+ * name resolves against the document and travels to the consumer as declared
1393
+ * intent; a URL is a destination the browser already knows how to reach, so it
1394
+ * belongs in the anchor and the document graph has nothing to say about it.
1395
+ *
1396
+ * The renderer and the transition extractor must read a target identically — the
1397
+ * renderer decides whether the value belongs in `href`, the extractor decides
1398
+ * whether an unmatched value is an authoring mistake. Two copies of that rule
1399
+ * would drift, and the moment they disagree one of the two starts calling
1400
+ * correct authoring a defect. So the rule lives here, below both, and neither
1401
+ * layer has to depend on the other to reach it.
1402
+ */
1403
+ /**
1404
+ * Whether a `navigate` target is a URL rather than the name of a page.
1405
+ *
1406
+ * A URL is recognised by shape, not by resolving it:
1407
+ * - a path or protocol-relative reference — `/reset`, `//cdn.example.com/x`
1408
+ * - an in-page fragment or bare query — `#terms`, `?tab=2`
1409
+ * - anything opening with an RFC 3986 scheme — `https:`, `mailto:`, `tel:`
1410
+ *
1411
+ * A target containing whitespace is never a URL: a URL carrying a space is
1412
+ * invalid until the space is percent-encoded, whereas page titles are written
1413
+ * as prose and routinely contain spaces. Screening on that first is what keeps
1414
+ * an English heading like `"Note: draft"` from reading as a scheme.
1415
+ *
1416
+ * The remaining ambiguities are decided in favour of "page", because a page name
1417
+ * is the common case and the cost of the two mistakes is not symmetric: calling
1418
+ * a page a URL yields a link that goes nowhere, while calling a URL a page
1419
+ * yields an edge reported as unresolved — visible, not silent. So a
1420
+ * schemeless host (`www.example.com`) is a page name; authors write the scheme.
1421
+ */
1422
+ declare function isUrlTarget(target: string | undefined): target is string;
1423
+
1409
1424
  /** A source file and exact span within it. */
1410
1425
  interface AppSourceSpan {
1411
1426
  sourceId: string;
@@ -1607,14 +1622,4 @@ declare function compileApp(document: AppDocument, options?: CompileAppOptions):
1607
1622
  */
1608
1623
  declare function linkAndCompileApp(manifest: AppManifest, modules: readonly AppModuleInput[], options?: CompileAppOptions): AppCompileResult;
1609
1624
 
1610
- /**
1611
- * Whether a `navigate` target is a URL rather than the name of a page.
1612
- *
1613
- * The renderer and transition extractor share this predicate so an outbound
1614
- * target cannot be rendered as a URL while simultaneously being reported as a
1615
- * broken page reference. Whitespace-bearing values are treated as page names;
1616
- * valid URLs must encode spaces, while page titles commonly contain them.
1617
- */
1618
- declare function isUrlTarget(target: string | undefined): target is string;
1619
-
1620
- export { ANCHOR_LOC_ATTR, ANCHOR_PATH_ATTR, ATTRIBUTE_MAP, ATTRIBUTE_SPECS, 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, type AttributeSpec, type AttributeValueType, AvatarNode, BadgeNode, BreadcrumbNode, ButtonNode, COMMON_ATTRIBUTES, COMPONENT_MAP, COMPONENT_SPECS, CardNode, CheckboxNode, ColNode, type CompileAppOptions, type ComplexityMetrics, type ComponentCategory, ComponentDefinitionNode, type ComponentSpec, 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, INTERACTIVE_ATTRIBUTES, 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, NODE_TYPE_MAP, NavNode, NavigationNode, type NodeChange, type NodePredicate, NodeType, type NormalizedInteraction, type NormalizedInteractionEffect, type NormalizedInteractionHandler, OverlayNode, PageNode, PlaceholderNode, PopoverNode, type PreviewWrapperOptions, ProgressNode, RadioNode, 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, VALID_ATTRIBUTE_NAMES, VALID_COMPONENT_NAMES, type ValidationError, type ValidationOptions, type ValidationResult, type ViewportSize, type WalkCallback, WireframeDocument, analyze, areIdentical, buildAnchorIndex, buildDomTree, calculateViewportScale, cloneNode, collectInteractions, compileApp, contains, countNodes, createAppComponentInstanceId, createAppNodeId, diff, documentDefinitions, documentPages, exportToFigma, exportToFigmaString, exportToJson, exportToJsonString, extractAllScreenFields, extractScreenFields, extractScreenTransitions, find, findAll, findByType, formatWireframeCode, getAncestors, getChangeSummary, getDevicePresets, getMaxDepth, getNodeSource, getNodeTypes, getPageSource, getValidAttributes, 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, isValidAttribute, isValidDevicePreset, linkAndCompileApp, linkApp, mapNodes, normalizeInteractionHandlers, normalizeStateGuard, parseViewportString, printWireframe, resetFigmaIdCounter, resolveAnchor, resolveViewport, validate, walk, walkDocument, wrapInPreviewContainer };
1625
+ 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 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, RadioNode, 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, compileApp, contains, countNodes, createAppComponentInstanceId, createAppNodeId, diff, documentDefinitions, documentPages, exportToFigma, exportToFigmaString, exportToJson, exportToJsonString, extractAllScreenFields, extractScreenFields, extractScreenTransitions, 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, parseViewportString, printWireframe, resetFigmaIdCounter, resolveAnchor, resolveViewport, validate, walk, walkDocument, wrapInPreviewContainer };