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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/README.md +17 -462
  2. package/dist/app.cjs +50 -0
  3. package/dist/app.d.cts +488 -0
  4. package/dist/app.d.ts +488 -0
  5. package/dist/app.js +1 -0
  6. package/dist/chunk-3RWGG5EC.js +18042 -0
  7. package/dist/chunk-4TMDPWPR.cjs +186 -0
  8. package/dist/chunk-4UZBGIGJ.cjs +4359 -0
  9. package/dist/chunk-5DGRIQDU.cjs +824 -0
  10. package/dist/chunk-ETV4XYOV.cjs +5 -0
  11. package/dist/chunk-FS6A6EJ4.js +4345 -0
  12. package/dist/chunk-IMUVIIJR.cjs +18051 -0
  13. package/dist/chunk-JJWAFHSV.js +821 -0
  14. package/dist/chunk-MD6MNOEQ.cjs +2884 -0
  15. package/dist/chunk-PKBMQBKP.js +5 -0
  16. package/dist/chunk-R5WBZWBC.js +180 -0
  17. package/dist/chunk-V3HVWC7C.js +2874 -0
  18. package/dist/chunk-XYACLXXF.js +51484 -0
  19. package/dist/chunk-ZPHNXJRY.cjs +51590 -0
  20. package/dist/index-BGU_4N4W.d.ts +240 -0
  21. package/dist/index-BlNYFaZd.d.cts +337 -0
  22. package/dist/index-Cx4-VXVS.d.ts +337 -0
  23. package/dist/index-DyXaMSgd.d.cts +240 -0
  24. package/dist/index.cjs +1844 -58238
  25. package/dist/index.d.cts +556 -102
  26. package/dist/index.d.ts +556 -102
  27. package/dist/index.js +1163 -58104
  28. package/dist/interaction.cjs +26 -0
  29. package/dist/interaction.d.cts +3 -0
  30. package/dist/interaction.d.ts +3 -0
  31. package/dist/interaction.js +1 -0
  32. package/dist/parser.cjs +34 -6611
  33. package/dist/parser.d.cts +11 -2
  34. package/dist/parser.d.ts +11 -2
  35. package/dist/parser.js +1 -6585
  36. package/dist/renderer.cjs +119 -50537
  37. package/dist/renderer.d.cts +348 -123
  38. package/dist/renderer.d.ts +348 -123
  39. package/dist/renderer.js +3 -50499
  40. package/dist/spec.cjs +94 -0
  41. package/dist/spec.d.cts +301 -0
  42. package/dist/spec.d.ts +301 -0
  43. package/dist/spec.js +1 -0
  44. package/dist/{types-hEr_afgw.d.cts → types-CGRi1k2N.d.cts} +307 -27
  45. package/dist/{types-hEr_afgw.d.ts → types-CGRi1k2N.d.ts} +307 -27
  46. package/dist/types-Dkgr0Wyc.d.cts +75 -0
  47. package/dist/types-Dkgr0Wyc.d.ts +75 -0
  48. package/dist/v4-types-2ORUg6To.d.cts +137 -0
  49. package/dist/v4-types-2ORUg6To.d.ts +137 -0
  50. package/package.json +112 -35
@@ -0,0 +1,240 @@
1
+ import { W as WireframeDocument } from './types-CGRi1k2N.js';
2
+
3
+ /**
4
+ * Renderer type definitions for wireweave
5
+ *
6
+ * Provides types for rendering options, themes, and context
7
+ */
8
+ /** Annotation presentation used by the renderer. */
9
+ type AnnotationStyle = 'legacy' | 'neutral';
10
+ interface RenderOptions {
11
+ /** Theme variant */
12
+ theme?: 'light' | 'dark';
13
+ /** Scale factor for sizing */
14
+ scale?: number;
15
+ /** Include CSS styles in output */
16
+ includeStyles?: boolean;
17
+ /** Minify output (no indentation/newlines) */
18
+ minify?: boolean;
19
+ /** CSS class prefix for scoping */
20
+ classPrefix?: string;
21
+ /** Background color (e.g., '#ffffff', 'transparent') */
22
+ background?: string;
23
+ /**
24
+ * Annotation presentation. Defaults to `legacy` so existing render output
25
+ * stays unchanged; use `neutral` for deterministic grayscale annotations.
26
+ */
27
+ annotationStyle?: AnnotationStyle;
28
+ /**
29
+ * Emit source-anchor attributes (`data-wf-path` / `data-wf-loc`) on each
30
+ * rendered component element, enabling DOM ↔ AST ↔ source mapping. Default
31
+ * `false` — output is byte-identical to non-anchored rendering when off.
32
+ */
33
+ sourceAnchors?: boolean;
34
+ /**
35
+ * Prefix prepended to every DOM `id` this render emits.
36
+ *
37
+ * An authored `id` is unique inside the page that declares it and nowhere
38
+ * else, which is all a page needs while it is a document of its own. Compose
39
+ * several pages into one document and that stops being true: two screens
40
+ * declaring `confirm` produce two elements with the same id, and a duplicate
41
+ * id is not a rendering bug — the picture is right — but it is a lie told to
42
+ * every reader of the DOM. Devtools resolve it to the first match, the
43
+ * accessibility tree treats `aria-*` references as pointing at one element,
44
+ * and any external tool doing `#confirm` gets an arbitrary one of them.
45
+ *
46
+ * Default `''` — no prefix, so output is byte-identical to unscoped
47
+ * rendering when unset, which is what every existing entry point does.
48
+ * `renderSite` sets it per screen and per shell, because it is the one
49
+ * renderer that puts pages of different origin in the same document.
50
+ *
51
+ * Authored intent is not rewritten: the interaction attributes that point at
52
+ * an overlay keep the name their author wrote, and their consumer composes
53
+ * the scope back on. The prefix belongs to identity, not to intent.
54
+ */
55
+ idScope?: string;
56
+ }
57
+ interface RenderResult {
58
+ /** Rendered HTML content */
59
+ html: string;
60
+ /** Generated CSS styles */
61
+ css: string;
62
+ }
63
+ /**
64
+ * Result of rendering a single page in isolation (`renderPage`).
65
+ * Carries the resolved pixel dimensions so callers (export pipelines, hosts)
66
+ * can size their wrapper without re-resolving viewport/device themselves.
67
+ */
68
+ interface PageRenderResult extends RenderResult {
69
+ width: number;
70
+ height: number;
71
+ }
72
+ interface CanvasOptions extends RenderOptions {
73
+ /** Gap between auto-laid-out pages, in pixels. Default `64`. */
74
+ gap?: number;
75
+ }
76
+ interface CanvasRenderResult extends RenderResult {
77
+ /** Total canvas width — bounding box of all pages. */
78
+ width: number;
79
+ /** Total canvas height — bounding box of all pages. */
80
+ height: number;
81
+ }
82
+ interface SvgRenderOptions {
83
+ /** Width of the SVG viewport */
84
+ width?: number;
85
+ /** Height of the SVG viewport */
86
+ height?: number;
87
+ /** Padding around content */
88
+ padding?: number;
89
+ /** Scale factor */
90
+ scale?: number;
91
+ /** Background color */
92
+ background?: string;
93
+ /** Font family */
94
+ fontFamily?: string;
95
+ /** Theme variant */
96
+ theme?: 'light' | 'dark';
97
+ }
98
+ interface SvgRenderResult {
99
+ /** Rendered SVG content */
100
+ svg: string;
101
+ /** Actual width */
102
+ width: number;
103
+ /** Actual height */
104
+ height: number;
105
+ }
106
+ interface RenderContext {
107
+ /** Resolved render options */
108
+ options: Required<RenderOptions>;
109
+ /** Theme configuration */
110
+ theme: ThemeConfig;
111
+ /** Current nesting depth for indentation */
112
+ depth: number;
113
+ }
114
+ interface ThemeColors {
115
+ /** Primary action color */
116
+ primary: string;
117
+ /** Secondary/muted action color */
118
+ secondary: string;
119
+ /** Success state color */
120
+ success: string;
121
+ /** Warning state color */
122
+ warning: string;
123
+ /** Danger/error state color */
124
+ danger: string;
125
+ /** Muted/disabled color */
126
+ muted: string;
127
+ /** Background color */
128
+ background: string;
129
+ /** Foreground/text color */
130
+ foreground: string;
131
+ /** Border color */
132
+ border: string;
133
+ }
134
+ interface ThemeConfig {
135
+ /** Color palette */
136
+ colors: ThemeColors;
137
+ /** Spacing scale (number -> px value) */
138
+ spacing: Record<number, string>;
139
+ /** Border radius */
140
+ radius: string;
141
+ /** Font family */
142
+ fontFamily: string;
143
+ /** Shadow styles */
144
+ shadows: Record<string, string>;
145
+ }
146
+ /**
147
+ * Default wireframe theme using black/white/gray palette
148
+ * Follows wireweave design principles for sketch-like appearance
149
+ */
150
+ declare const defaultTheme: ThemeConfig;
151
+ /**
152
+ * Dark theme configuration
153
+ * Inverts colors for dark mode display
154
+ */
155
+ declare const darkTheme: ThemeConfig;
156
+ /**
157
+ * Get theme configuration by name
158
+ */
159
+ declare function getTheme(name: 'light' | 'dark'): ThemeConfig;
160
+
161
+ /**
162
+ * `renderSite` — a whole wireframe document as one navigable HTML file.
163
+ *
164
+ * The other renderers answer "what does this screen look like". This one
165
+ * answers "what does this product look like": every page of a document, the
166
+ * shells they share, and the moves between them, in a single file with no
167
+ * server, no build step and no dependencies. Open it and click.
168
+ *
169
+ * ## What makes it one document rather than N concatenated
170
+ *
171
+ * Three things exist once, however many screens there are:
172
+ *
173
+ * - **the stylesheet** — component styles are generated per document, not per
174
+ * page, so N screens cost one copy instead of N;
175
+ * - **the runtime** — one inline script drives every screen;
176
+ * - **each layout** — a `layout` referenced by `uses=` is emitted once, and
177
+ * every page using it is hosted inside that one copy at the `slot` position.
178
+ *
179
+ * The third is the one that has to be structural. Emitting a copy of the shell
180
+ * per screen and hiding all but one with CSS produces the same picture while
181
+ * keeping every byte the shared shell exists to remove; the shell is therefore
182
+ * shared in the DOM, and only screens are switched.
183
+ *
184
+ * ## Ids under composition
185
+ *
186
+ * An authored `id` is unique inside the page that declares it. Once several
187
+ * pages share a document that guarantee is gone, so every screen and every
188
+ * shell renders under an id scope of its own and the runtime composes the scope
189
+ * with the authored name when it looks an overlay up. Two screens can both
190
+ * declare `confirm` and each opens its own.
191
+ *
192
+ * ## What is left alone
193
+ *
194
+ * A page with no `uses=` renders exactly as `renderPage` renders it, frame and
195
+ * all, as its own screen. That is the whole corpus today, so composition is
196
+ * something a document opts into and nothing changes shape without being asked.
197
+ *
198
+ * `render` / `renderToHtml` / `renderCanvas` / `renderToSvg` are untouched:
199
+ * `renderSite` is a fifth entry point beside them, not a mode of them.
200
+ */
201
+
202
+ /**
203
+ * Options for {@link renderSite}.
204
+ *
205
+ * A subset of {@link RenderOptions}: `includeStyles` is meaningless for a
206
+ * standalone document that has nowhere else to get its styles from, and
207
+ * `sourceAnchors` is omitted because an anchor path names a node's position
208
+ * under one page — a shell belongs to every page that uses it and has no single
209
+ * such position, so the scheme has nothing true to say about it.
210
+ */
211
+ interface SiteOptions extends Pick<RenderOptions, 'theme' | 'classPrefix' | 'background' | 'annotationStyle'> {
212
+ /** `<title>` of the produced document. Defaults to the entry page's title. */
213
+ title?: string;
214
+ /**
215
+ * The screen shown when the URL carries no fragment.
216
+ *
217
+ * Named the way everything else names a screen — an `id` or a `title`, put
218
+ * through {@link SiteModel.names}, so a caller writes the same string here
219
+ * that it would write in a `navigate=` and lands on the same page. Taking an
220
+ * index instead would make the option depend on document order, which is the
221
+ * one thing a caller holding a screen name does not know.
222
+ *
223
+ * Defaults to the first page in document order. A name that addresses no
224
+ * screen leaves that default in place and is marked on the site container as
225
+ * `data-wf-entry-unresolved`, the way an unmet `uses=` is marked on its
226
+ * screen: the request stays visible in the artefact instead of disappearing
227
+ * between the call and the HTML.
228
+ */
229
+ entry?: string;
230
+ }
231
+ /**
232
+ * Render a whole document as one navigable, self-contained HTML file.
233
+ *
234
+ * @param document - Parsed wireframe document
235
+ * @param options - Site render options
236
+ * @returns A complete HTML document, ready to write to disk and open
237
+ */
238
+ declare function renderSite(document: WireframeDocument, options?: SiteOptions): string;
239
+
240
+ export { type AnnotationStyle as A, type CanvasOptions as C, type PageRenderResult as P, type RenderContext as R, type SvgRenderOptions as S, type ThemeConfig as T, type RenderOptions as a, type RenderResult as b, type CanvasRenderResult as c, type SvgRenderResult as d, type SiteOptions as e, type ThemeColors as f, darkTheme as g, defaultTheme as h, getTheme as i, renderSite as r };
@@ -0,0 +1,337 @@
1
+ import { S as SourceLocation, a$ as StateDeclaration, b0 as StateGuard, aF as InteractionEffect, K as NodeType, W as WireframeDocument, aE as InputType } from './types-CGRi1k2N.cjs';
2
+ import { C as ComponentCategory } from './types-Dkgr0Wyc.cjs';
3
+
4
+ /** Overlay toggle is distinct from the typed boolean-state `toggle` effect. */
5
+ type NormalizedInteractionEffect = InteractionEffect | {
6
+ kind: 'toggle-overlay';
7
+ target: string;
8
+ } | {
9
+ kind: 'legacy-action';
10
+ action: string;
11
+ };
12
+ interface NormalizedInteractionHandler {
13
+ event: 'click';
14
+ guard?: StateGuard;
15
+ effects: NormalizedInteractionEffect[];
16
+ }
17
+ interface NormalizedInteraction {
18
+ screenIndex: number;
19
+ source: 'screen' | 'layout';
20
+ signature: string;
21
+ handler: NormalizedInteractionHandler;
22
+ /** Present when this entry came from a legacy scalar intent attribute. */
23
+ legacyKind?: InteractionKind;
24
+ trigger: {
25
+ nodeType: NodeType;
26
+ label?: string;
27
+ loc?: SourceLocation;
28
+ item?: {
29
+ index: number;
30
+ };
31
+ };
32
+ }
33
+ type InteractionDiagnosticCode = 'invalid-state-declaration' | 'duplicate-state-declaration' | 'invalid-interaction-handler' | 'unknown-legacy-action';
34
+ interface InteractionDiagnostic {
35
+ code: InteractionDiagnosticCode;
36
+ message: string;
37
+ screenIndex?: number;
38
+ source?: 'screen' | 'layout';
39
+ loc?: SourceLocation;
40
+ }
41
+ interface InteractionModel {
42
+ states: StateDeclaration[];
43
+ interactions: NormalizedInteraction[];
44
+ diagnostics: InteractionDiagnostic[];
45
+ }
46
+ /** Normalize a guard object emitted by the generic DSL object grammar. */
47
+ declare function normalizeStateGuard(value: unknown): StateGuard | undefined;
48
+ /**
49
+ * Normalize the public `on=` shape. Malformed handlers are inert; diagnostics
50
+ * are added by {@link collectInteractions}, where screen/source context exists.
51
+ */
52
+ declare function normalizeInteractionHandlers(value: unknown): NormalizedInteractionHandler[];
53
+ /** Stable payload shared by rendered DOM markers and the runtime registry. */
54
+ declare function interactionSignature(handler: NormalizedInteractionHandler): string;
55
+ /**
56
+ * The canonical interaction/state source for graph extraction and renderSite.
57
+ * Layout intent is expanded once per screen using that layout, so shared chrome
58
+ * has the same reachable routes in both consumers.
59
+ *
60
+ * ## Components are read through the linker, never from here
61
+ *
62
+ * Screens and layouts are walked; `component` definitions are not. That is the
63
+ * boundary, not an omission. A handler inside a definition is written against
64
+ * the component's *parameters* — `target="$to"` — so before an invocation binds
65
+ * its inputs there is no destination to record, only the name of one. Walking
66
+ * definitions here would register `"$to"` as a route and invent a graph edge to
67
+ * a screen that does not exist, and a component used twice with different
68
+ * inputs is two different routes that a single walk of the definition cannot
69
+ * tell apart.
70
+ *
71
+ * Binding those inputs is `linkApp`'s job: `expandComponentUse` substitutes the
72
+ * invocation's inputs, fills its slots, and hands back a tree whose handlers
73
+ * name real targets. So `linkAndCompileApp` — link, then compile — sees every
74
+ * component interaction, while `renderSite(parse(src))` on a document that
75
+ * never went through the linker leaves each invocation
76
+ * `data-wf-component-unresolved` and contributes no interactions. Handlers
77
+ * written directly on a screen or a layout work in both paths; only handlers
78
+ * *inside a component definition* require the linked path.
79
+ */
80
+ declare function collectInteractions(doc: WireframeDocument): InteractionModel;
81
+
82
+ /**
83
+ * Types for the deterministic extraction module.
84
+ *
85
+ * These shapes mirror the SSOT (single-source-of-truth) Screen skeleton slots —
86
+ * title / UI 요소·입력 필드 / 표시 데이터 / 전이 — so a downstream SSOT authoring
87
+ * step can map a parsed `WireframeDocument` onto Screen nodes without any prose
88
+ * generation. Everything here is derived structurally from the AST; there is no
89
+ * heuristic text synthesis.
90
+ */
91
+
92
+ /**
93
+ * The kind of interaction an interactive node triggers, taken directly from the
94
+ * DSL `InteractiveProps` (`navigate` / `opens` / `toggles` / `action`).
95
+ */
96
+ type InteractionKind = 'navigate' | 'opens' | 'toggles' | 'action';
97
+ /**
98
+ * A meaningful UI node on a screen (any real AST component node below the page).
99
+ */
100
+ interface ScreenElement {
101
+ nodeType: NodeType;
102
+ category: ComponentCategory;
103
+ /** Short caption: form label, card/section title, avatar/icon name, etc. */
104
+ label?: string;
105
+ /** Textual body for content-bearing nodes (text/title/link/button/badge…). */
106
+ content?: string;
107
+ loc?: SourceLocation;
108
+ }
109
+ /**
110
+ * A form input field (the 7 `InputComponentNode` types — excludes Button, which
111
+ * the spec files under the `input` category but is an action, not a field).
112
+ */
113
+ interface ScreenInput {
114
+ nodeType: NodeType;
115
+ label?: string;
116
+ /** Present on `Input` only. */
117
+ inputType?: InputType;
118
+ placeholder?: string;
119
+ required?: boolean;
120
+ disabled?: boolean;
121
+ /** Present on `Select` — option labels, normalised to strings. */
122
+ options?: string[];
123
+ loc?: SourceLocation;
124
+ }
125
+ /**
126
+ * A display / data / text node — the read-only "표시 데이터" of a screen.
127
+ */
128
+ interface ScreenDisplay {
129
+ nodeType: NodeType;
130
+ category: ComponentCategory;
131
+ content?: string;
132
+ label?: string;
133
+ loc?: SourceLocation;
134
+ }
135
+ /**
136
+ * A single interaction emitted by a node. A node carrying more than one
137
+ * `InteractiveProps` (e.g. `navigate` + `action`) yields one entry per prop, in
138
+ * a fixed order (navigate, opens, toggles, action).
139
+ */
140
+ interface ScreenAction {
141
+ nodeType: NodeType;
142
+ label?: string;
143
+ kind: InteractionKind;
144
+ /** The raw target string as written in the DSL. */
145
+ target: string;
146
+ /**
147
+ * Present when the action is a menu item inside a nav/dropdown/breadcrumb
148
+ * container rather than a component node. `nodeType` is then the container's
149
+ * type, `label` is the item's label, and `index` is its position within the
150
+ * container's flattened item list.
151
+ */
152
+ item?: {
153
+ index: number;
154
+ };
155
+ /** The container node's location for item-level actions; items carry no `loc`. */
156
+ loc?: SourceLocation;
157
+ }
158
+ /**
159
+ * Per-screen derived counts and boolean rollups.
160
+ */
161
+ interface ScreenFieldsSummary {
162
+ /** Total meaningful component nodes below the page. */
163
+ total: number;
164
+ /** Count of nodes per component category. */
165
+ byCategory: Record<ComponentCategory, number>;
166
+ inputCount: number;
167
+ displayCount: number;
168
+ actionCount: number;
169
+ /** At least one form input field is present. */
170
+ hasForm: boolean;
171
+ /** At least one navigation-category node (nav/tabs/breadcrumb) is present. */
172
+ hasNavigation: boolean;
173
+ /** At least one overlay container (modal/drawer/popover/tooltip/dropdown). */
174
+ hasOverlay: boolean;
175
+ }
176
+ /**
177
+ * The full structured field set extracted from one page.
178
+ */
179
+ interface ScreenFields {
180
+ title?: string;
181
+ viewport?: string | number;
182
+ device?: string;
183
+ elements: ScreenElement[];
184
+ inputs: ScreenInput[];
185
+ displayData: ScreenDisplay[];
186
+ actions: ScreenAction[];
187
+ summary: ScreenFieldsSummary;
188
+ loc?: SourceLocation;
189
+ }
190
+ /**
191
+ * A node in the screen-transition graph.
192
+ *
193
+ * `id` is the page's declared identifier — a stable slug an author opted into —
194
+ * and `title` is its display heading. They are separate namespaces: `id` is what
195
+ * a `navigate` target should key off, `title` is what a reader sees. Either can
196
+ * be absent.
197
+ */
198
+ interface TransitionScreen {
199
+ id?: string;
200
+ title?: string;
201
+ index: number;
202
+ loc?: SourceLocation;
203
+ }
204
+ /**
205
+ * A resolved or dangling transition trigger.
206
+ */
207
+ interface TransitionEdge {
208
+ from: {
209
+ pageIndex: number;
210
+ id?: string;
211
+ title?: string;
212
+ };
213
+ /**
214
+ * The destination page for a resolved `navigate` edge. Always `null` for
215
+ * `opens` / `toggles` / `action`, which are intra-page or opaque and never
216
+ * cross a page boundary.
217
+ *
218
+ * `id` / `title` mirror {@link TransitionScreen}: present when the page
219
+ * declares them, so a consumer can address the destination by its stable slug
220
+ * rather than by display text.
221
+ */
222
+ to: {
223
+ pageIndex: number;
224
+ id?: string;
225
+ title?: string;
226
+ } | null;
227
+ /** The raw target string as written in the DSL. */
228
+ target: string;
229
+ kind: InteractionKind;
230
+ /** Typed event metadata; absent for legacy scalar interaction attributes. */
231
+ event?: 'click';
232
+ guard?: StateGuard;
233
+ effect?: NormalizedInteractionEffect;
234
+ /** A shared-layout edge is expanded once for every screen using that layout. */
235
+ source?: 'screen' | 'layout';
236
+ /**
237
+ * What fired the transition. For a component node, `nodeType` is that node's
238
+ * type. For a menu item inside a nav/dropdown/breadcrumb, `nodeType` is the
239
+ * container's type, `label` is the item's label, and `item.index` is the
240
+ * item's position within the container — the presence of `item` marks an
241
+ * item-level trigger.
242
+ */
243
+ trigger: {
244
+ nodeType: NodeType;
245
+ label?: string;
246
+ loc?: SourceLocation;
247
+ item?: {
248
+ index: number;
249
+ };
250
+ };
251
+ /**
252
+ * Whether `target` names a concrete destination for its kind:
253
+ * - `navigate`: a page whose `id` matches `target`, or — failing that — whose
254
+ * `title` matches it. Identifiers are consulted before display text; see
255
+ * `extract/transitions.ts` for why. Also `true` for an `external` target: a
256
+ * URL is a complete destination, it is simply not one of this document's
257
+ * pages, which is why `to` is `null` there.
258
+ * - `opens` / `toggles`: a `Modal` / `Drawer` with `id === target` in the
259
+ * source page.
260
+ * - `action`: always `false` (an opaque handler id has no structural target).
261
+ */
262
+ resolved: boolean;
263
+ /**
264
+ * Present, and always `true`, when a `navigate` target is a URL rather than
265
+ * the name of a page (see `interaction/target.ts`). Such an edge leaves the
266
+ * document: `to` is `null` because there is no page to point at, and it is
267
+ * never {@link ScreenTransitionGraph.dangling | dangling} — an outbound link
268
+ * is a destination the author meant, not a reference that failed to resolve.
269
+ *
270
+ * This is what separates an external link from an `action`: both have
271
+ * `to === null`, but an `action` is an opaque handler with `resolved: false`,
272
+ * while an external link is a real destination the browser can follow.
273
+ */
274
+ external?: true;
275
+ }
276
+ /**
277
+ * The screen-transition graph derived from a whole document.
278
+ */
279
+ interface ScreenTransitionGraph {
280
+ screens: TransitionScreen[];
281
+ edges: TransitionEdge[];
282
+ /**
283
+ * The subset of `navigate` edges whose target matched neither a page `id` nor
284
+ * a page title and is not a URL (`resolved === false`, `to === null`) — a name
285
+ * that was meant to be a screen and found none. This is the defect list: a
286
+ * consumer reporting "broken transitions" counts exactly these. Intra-page
287
+ * `opens` / `toggles` and opaque `action` edges are not page transitions and
288
+ * never appear here, and neither do `external` links.
289
+ */
290
+ dangling: TransitionEdge[];
291
+ /**
292
+ * The subset of `navigate` edges leaving the document — targets that are URLs
293
+ * rather than page names ({@link TransitionEdge.external}). Kept apart from
294
+ * `dangling` so a consumer can show outbound links without counting correct
295
+ * authoring as breakage.
296
+ */
297
+ external: TransitionEdge[];
298
+ }
299
+
300
+ /**
301
+ * What a `navigate` target names.
302
+ *
303
+ * The DSL documents `navigate` as pointing at "a URL or a page", so every target
304
+ * is read one of two ways, and the reading decides everything downstream. A page
305
+ * name resolves against the document and travels to the consumer as declared
306
+ * intent; a URL is a destination the browser already knows how to reach, so it
307
+ * belongs in the anchor and the document graph has nothing to say about it.
308
+ *
309
+ * The renderer and the transition extractor must read a target identically — the
310
+ * renderer decides whether the value belongs in `href`, the extractor decides
311
+ * whether an unmatched value is an authoring mistake. Two copies of that rule
312
+ * would drift, and the moment they disagree one of the two starts calling
313
+ * correct authoring a defect. So the rule lives here, below both, and neither
314
+ * layer has to depend on the other to reach it.
315
+ */
316
+ /**
317
+ * Whether a `navigate` target is a URL rather than the name of a page.
318
+ *
319
+ * A URL is recognised by shape, not by resolving it:
320
+ * - a path or protocol-relative reference — `/reset`, `//cdn.example.com/x`
321
+ * - an in-page fragment or bare query — `#terms`, `?tab=2`
322
+ * - anything opening with an RFC 3986 scheme — `https:`, `mailto:`, `tel:`
323
+ *
324
+ * A target containing whitespace is never a URL: a URL carrying a space is
325
+ * invalid until the space is percent-encoded, whereas page titles are written
326
+ * as prose and routinely contain spaces. Screening on that first is what keeps
327
+ * an English heading like `"Note: draft"` from reading as a scheme.
328
+ *
329
+ * The remaining ambiguities are decided in favour of "page", because a page name
330
+ * is the common case and the cost of the two mistakes is not symmetric: calling
331
+ * a page a URL yields a link that goes nowhere, while calling a URL a page
332
+ * yields an edge reported as unresolved — visible, not silent. So a
333
+ * schemeless host (`www.example.com`) is a page name; authors write the scheme.
334
+ */
335
+ declare function isUrlTarget(target: string | undefined): target is string;
336
+
337
+ export { type InteractionDiagnostic as I, type NormalizedInteraction as N, type ScreenFields as S, type TransitionEdge as T, type ScreenTransitionGraph as a, type InteractionDiagnosticCode as b, type InteractionKind as c, type InteractionModel as d, type NormalizedInteractionEffect as e, type NormalizedInteractionHandler as f, type ScreenAction as g, type ScreenDisplay as h, type ScreenElement as i, type ScreenFieldsSummary as j, type ScreenInput as k, type TransitionScreen as l, collectInteractions as m, interactionSignature as n, isUrlTarget as o, normalizeInteractionHandlers as p, normalizeStateGuard as q };