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

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
@@ -192,6 +208,62 @@ declare function contains(node: AnyNode, target: AnyNode): boolean;
192
208
  */
193
209
  declare function getNodeTypes(node: AnyNode): Set<NodeType>;
194
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
+
195
267
  /**
196
268
  * Node/document-level canonical `.wf` printing.
197
269
  *
@@ -301,105 +373,6 @@ interface PreviewWrapperOptions {
301
373
  */
302
374
  declare function wrapInPreviewContainer(html: string, viewport: ViewportSize, options?: PreviewWrapperOptions): string;
303
375
 
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
376
  /**
404
377
  * Wireweave DSL Validation
405
378
  *
@@ -1167,6 +1140,11 @@ interface ScreenFields {
1167
1140
  }
1168
1141
  /**
1169
1142
  * A node in the screen-transition graph.
1143
+ *
1144
+ * `id` is the page's declared identifier — a stable slug an author opted into —
1145
+ * and `title` is its display heading. They are separate namespaces: `id` is what
1146
+ * a `navigate` target should key off, `title` is what a reader sees. Either can
1147
+ * be absent.
1170
1148
  */
1171
1149
  interface TransitionScreen {
1172
1150
  id?: string;
@@ -1187,6 +1165,10 @@ interface TransitionEdge {
1187
1165
  * The destination page for a resolved `navigate` edge. Always `null` for
1188
1166
  * `opens` / `toggles` / `action`, which are intra-page or opaque and never
1189
1167
  * cross a page boundary.
1168
+ *
1169
+ * `id` / `title` mirror {@link TransitionScreen}: present when the page
1170
+ * declares them, so a consumer can address the destination by its stable slug
1171
+ * rather than by display text.
1190
1172
  */
1191
1173
  to: {
1192
1174
  pageIndex: number;
@@ -1218,18 +1200,27 @@ interface TransitionEdge {
1218
1200
  };
1219
1201
  };
1220
1202
  /**
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.
1203
+ * Whether `target` names a concrete destination for its kind:
1204
+ * - `navigate`: a page whose `id` matches `target`, or — failing that — whose
1205
+ * `title` matches it. Identifiers are consulted before display text; see
1206
+ * `extract/transitions.ts` for why. Also `true` for an `external` target: a
1207
+ * URL is a complete destination, it is simply not one of this document's
1208
+ * pages, which is why `to` is `null` there.
1224
1209
  * - `opens` / `toggles`: a `Modal` / `Drawer` with `id === target` in the
1225
1210
  * source page.
1226
1211
  * - `action`: always `false` (an opaque handler id has no structural target).
1227
1212
  */
1228
1213
  resolved: boolean;
1229
1214
  /**
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`.
1215
+ * Present, and always `true`, when a `navigate` target is a URL rather than
1216
+ * the name of a page (see `interaction/target.ts`). Such an edge leaves the
1217
+ * document: `to` is `null` because there is no page to point at, and it is
1218
+ * never {@link ScreenTransitionGraph.dangling | dangling} — an outbound link
1219
+ * is a destination the author meant, not a reference that failed to resolve.
1220
+ *
1221
+ * This is what separates an external link from an `action`: both have
1222
+ * `to === null`, but an `action` is an opaque handler with `resolved: false`,
1223
+ * while an external link is a real destination the browser can follow.
1233
1224
  */
1234
1225
  external?: true;
1235
1226
  }
@@ -1240,13 +1231,20 @@ interface ScreenTransitionGraph {
1240
1231
  screens: TransitionScreen[];
1241
1232
  edges: TransitionEdge[];
1242
1233
  /**
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.
1234
+ * The subset of `navigate` edges whose target matched neither a page `id` nor
1235
+ * a page title and is not a URL (`resolved === false`, `to === null`) — a name
1236
+ * that was meant to be a screen and found none. This is the defect list: a
1237
+ * consumer reporting "broken transitions" counts exactly these. Intra-page
1238
+ * `opens` / `toggles` and opaque `action` edges are not page transitions and
1239
+ * never appear here, and neither do `external` links.
1247
1240
  */
1248
1241
  dangling: TransitionEdge[];
1249
- /** URL-shaped `navigate` edges that leave the current document. */
1242
+ /**
1243
+ * The subset of `navigate` edges leaving the document — targets that are URLs
1244
+ * rather than page names ({@link TransitionEdge.external}). Kept apart from
1245
+ * `dangling` so a consumer can show outbound links without counting correct
1246
+ * authoring as breakage.
1247
+ */
1250
1248
  external: TransitionEdge[];
1251
1249
  }
1252
1250
 
@@ -1269,6 +1267,9 @@ interface ScreenTransitionGraph {
1269
1267
  declare function extractScreenFields(page: PageNode): ScreenFields;
1270
1268
  /**
1271
1269
  * Extract {@link ScreenFields} for every page in a document, in document order.
1270
+ *
1271
+ * Reuse definitions are skipped: a `layout` is not a screen and has no fields
1272
+ * of its own until a page is drawn inside it.
1272
1273
  */
1273
1274
  declare function extractAllScreenFields(doc: WireframeDocument): ScreenFields[];
1274
1275
 
@@ -1286,27 +1287,60 @@ declare function extractAllScreenFields(doc: WireframeDocument): ScreenFields[];
1286
1287
  * `nav ["…"]` array items and `nav { item … group { item … } }` block items
1287
1288
  * (including grouped items), plus dropdown and breadcrumb items, are extracted.
1288
1289
  * 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
1290
+ * position in `trigger.item.index`. That position counts only elements that can
1291
+ * hold an intent — dividers and group headings are skipped, in every container
1292
+ * alike — because the index is the handle that points back at an edge's origin,
1293
+ * and an element incapable of producing an edge must not shift what the handle
1294
+ * addresses. `Tabs` items are plain strings without
1290
1295
  * `InteractiveProps` and contribute no transition; their panel content is
1291
1296
  * reached by normal node traversal.
1292
1297
  *
1293
1298
  * ## Resolution semantics
1294
1299
  *
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}.
1300
+ * - **`navigate`** is a page transition. Its trimmed target is matched, exactly
1301
+ * and case-sensitively, against **page `id` first and page `title` second**.
1302
+ *
1303
+ * Identifiers are how this DSL names a target: `opens` / `toggles` already
1304
+ * address a `Modal` or `Drawer` by its `id`, so a page addressed by `id` is
1305
+ * the same rule reaching the one container that had been left out — an author
1306
+ * learns one way to point at something, not two.
1307
+ *
1308
+ * The two are different kinds of name. An `id` is a stable identifier the
1309
+ * author opted into (`page "결제 내역" id=billing`); a `title` is display text
1310
+ * that is optional, need not be unique, and is expected to change as copy is
1311
+ * edited. Resolving identifiers first means rewording a heading cannot
1312
+ * silently turn every edge pointing at that screen into a dangling one. Title
1313
+ * matching stays as the fallback because it is how the corpus is written
1314
+ * today, and dropping it would strand every existing document.
1315
+ *
1316
+ * Consequences of that order, all deterministic:
1317
+ * - When one page's `id` equals another page's `title`, the `id` wins and the
1318
+ * title-named page is not reachable by that string. Identifiers always beat
1319
+ * labels; there is no positional tie-break to reason about.
1320
+ * - Within each namespace, duplicates resolve to the first page in document
1321
+ * order — the same rule the title namespace has always used.
1322
+ * - A target matching neither namespace is read by shape (see `isUrlTarget`).
1323
+ * A URL-shaped one — `navigate="/reset"`, `navigate="https://…"` — is an
1324
+ * {@link ScreenTransitionGraph.external | external} destination, not a
1325
+ * defect: the DSL documents `navigate` as a "URL or page" target, so the
1326
+ * author wrote something the DSL allows and there is no page to find.
1327
+ * Anything else is a name that should have matched a page and did not, and
1328
+ * only that is {@link ScreenTransitionGraph.dangling | dangling}. Counting
1329
+ * external links as dangling would report every correct outbound link as a
1330
+ * broken screen transition.
1301
1331
  * - **`opens` / `toggles`** target an overlay *within the source page*, not
1302
1332
  * 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`.
1333
+ * or `Drawer` in the same page has `id === target` — the overlay containers
1334
+ * are the only nodes these two kinds can address. Being intra-page, they
1335
+ * never appear in `dangling`.
1305
1336
  * - **`action`** is an opaque handler id with no structural destination:
1306
1337
  * `to === null`, `resolved === false`, and it is not `dangling`.
1307
1338
  *
1308
1339
  * Item `href` is a raw anchor, not a declared `navigate` intent, and is
1309
- * excluded — consistent with node-level extraction.
1340
+ * excluded — consistent with node-level extraction. The HTML renderer draws the
1341
+ * same line: it emits the authored `href` and the declared intent side by side
1342
+ * as `data-navigate` / `data-opens` / `data-toggles` / `data-action`, so every
1343
+ * edge derived here has a counterpart a consumer of the markup can act on.
1310
1344
  */
1311
1345
 
1312
1346
  /**
@@ -1406,6 +1440,43 @@ declare function getNodeSource(source: string, doc: WireframeDocument, path: str
1406
1440
  */
1407
1441
  declare function buildDomTree(doc: WireframeDocument, pageIndexBase?: number): DomTreeNode[];
1408
1442
 
1443
+ /**
1444
+ * What a `navigate` target names.
1445
+ *
1446
+ * The DSL documents `navigate` as pointing at "a URL or a page", so every target
1447
+ * is read one of two ways, and the reading decides everything downstream. A page
1448
+ * name resolves against the document and travels to the consumer as declared
1449
+ * intent; a URL is a destination the browser already knows how to reach, so it
1450
+ * belongs in the anchor and the document graph has nothing to say about it.
1451
+ *
1452
+ * The renderer and the transition extractor must read a target identically — the
1453
+ * renderer decides whether the value belongs in `href`, the extractor decides
1454
+ * whether an unmatched value is an authoring mistake. Two copies of that rule
1455
+ * would drift, and the moment they disagree one of the two starts calling
1456
+ * correct authoring a defect. So the rule lives here, below both, and neither
1457
+ * layer has to depend on the other to reach it.
1458
+ */
1459
+ /**
1460
+ * Whether a `navigate` target is a URL rather than the name of a page.
1461
+ *
1462
+ * A URL is recognised by shape, not by resolving it:
1463
+ * - a path or protocol-relative reference — `/reset`, `//cdn.example.com/x`
1464
+ * - an in-page fragment or bare query — `#terms`, `?tab=2`
1465
+ * - anything opening with an RFC 3986 scheme — `https:`, `mailto:`, `tel:`
1466
+ *
1467
+ * A target containing whitespace is never a URL: a URL carrying a space is
1468
+ * invalid until the space is percent-encoded, whereas page titles are written
1469
+ * as prose and routinely contain spaces. Screening on that first is what keeps
1470
+ * an English heading like `"Note: draft"` from reading as a scheme.
1471
+ *
1472
+ * The remaining ambiguities are decided in favour of "page", because a page name
1473
+ * is the common case and the cost of the two mistakes is not symmetric: calling
1474
+ * a page a URL yields a link that goes nowhere, while calling a URL a page
1475
+ * yields an edge reported as unresolved — visible, not silent. So a
1476
+ * schemeless host (`www.example.com`) is a page name; authors write the scheme.
1477
+ */
1478
+ declare function isUrlTarget(target: string | undefined): target is string;
1479
+
1409
1480
  /** A source file and exact span within it. */
1410
1481
  interface AppSourceSpan {
1411
1482
  sourceId: string;
@@ -1607,14 +1678,4 @@ declare function compileApp(document: AppDocument, options?: CompileAppOptions):
1607
1678
  */
1608
1679
  declare function linkAndCompileApp(manifest: AppManifest, modules: readonly AppModuleInput[], options?: CompileAppOptions): AppCompileResult;
1609
1680
 
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 };
1681
+ 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, 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, collectParameterReferences, 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, parameterReferenceName, parseViewportString, printWireframe, resetFigmaIdCounter, resolveAnchor, resolveViewport, validate, walk, walkDocument, wrapInPreviewContainer };