@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
@@ -1,127 +1,107 @@
1
- import { a1 as WireframeDocument, A as AnyNode, P as PageNode } from './types-hEr_afgw.cjs';
1
+ import { P as PageNode, L as LayoutDefinitionNode, W as WireframeDocument, A as AnyNode, C as ComponentUseNode, I as InteractiveProps, G as GuardedOutcomeProps } from './types-CGRi1k2N.cjs';
2
+ import { R as RenderContext, a as RenderOptions, T as ThemeConfig, b as RenderResult, A as AnnotationStyle, P as PageRenderResult, C as CanvasOptions, c as CanvasRenderResult, S as SvgRenderOptions, d as SvgRenderResult } from './index-DyXaMSgd.cjs';
3
+ export { e as SiteOptions, f as ThemeColors, g as darkTheme, h as defaultTheme, i as getTheme, r as renderSite } from './index-DyXaMSgd.cjs';
2
4
 
3
5
  /**
4
- * Renderer type definitions for wireweave
5
- *
6
- * Provides types for rendering options, themes, and context
7
- */
8
- interface RenderOptions {
9
- /** Theme variant */
10
- theme?: 'light' | 'dark';
11
- /** Scale factor for sizing */
12
- scale?: number;
13
- /** Include CSS styles in output */
14
- includeStyles?: boolean;
15
- /** Minify output (no indentation/newlines) */
16
- minify?: boolean;
17
- /** CSS class prefix for scoping */
18
- classPrefix?: string;
19
- /** Background color (e.g., '#ffffff', 'transparent') */
20
- background?: string;
21
- }
22
- interface RenderResult {
23
- /** Rendered HTML content */
24
- html: string;
25
- /** Generated CSS styles */
26
- css: string;
27
- }
28
- /**
29
- * Result of rendering a single page in isolation (`renderPage`).
30
- * Carries the resolved pixel dimensions so callers (export pipelines, hosts)
31
- * can size their wrapper without re-resolving viewport/device themselves.
6
+ * The screen model behind `renderSite` — which pages become screens, which
7
+ * shell each one is drawn inside, and what names address it.
8
+ *
9
+ * Nothing here renders. It answers three questions the site renderer and its
10
+ * inline runtime both need the *same* answer to, so the answer is computed once
11
+ * and handed to both.
12
+ *
13
+ * ## Totality
14
+ *
15
+ * A wireframe document can name a layout that does not exist, declare two pages
16
+ * with the same `id`, or use a layout with no `slot`. None of those is a parse
17
+ * error (see the note on `WireframeDocument`), so none of them may stop a
18
+ * render either: every function here is total. Where a document is ambiguous
19
+ * the rule is always **first-wins in document order** — the same rule
20
+ * `extract/transitions.ts` already applies to titles — and the loser is not
21
+ * dropped silently: it is rendered with a `data-wf-*` marker naming what went
22
+ * unmet, so a reader of the output can see it and `validation/` can report it
23
+ * with a source location.
32
24
  */
33
- interface PageRenderResult extends RenderResult {
34
- width: number;
35
- height: number;
36
- }
37
- interface CanvasOptions extends RenderOptions {
38
- /** Gap between auto-laid-out pages, in pixels. Default `64`. */
39
- gap?: number;
40
- }
41
- interface CanvasRenderResult extends RenderResult {
42
- /** Total canvas width — bounding box of all pages. */
43
- width: number;
44
- /** Total canvas height — bounding box of all pages. */
45
- height: number;
46
- }
47
- interface SvgRenderOptions {
48
- /** Width of the SVG viewport */
49
- width?: number;
50
- /** Height of the SVG viewport */
51
- height?: number;
52
- /** Padding around content */
53
- padding?: number;
54
- /** Scale factor */
55
- scale?: number;
56
- /** Background color */
57
- background?: string;
58
- /** Font family */
59
- fontFamily?: string;
60
- /** Theme variant */
61
- theme?: 'light' | 'dark';
25
+
26
+ /** Why a page that declared `uses=` is not composed into a shell after all. */
27
+ type ShellMiss =
28
+ /** No `layout` in the document carries that name. */
29
+ 'unknown-layout'
30
+ /** The layout exists but has no `slot`, so it has nowhere to put a page. */
31
+ | 'slotless-layout';
32
+ /** One page, as a screen of the composed document. */
33
+ interface SiteScreen {
34
+ /** Position in `documentPages(doc)`. This is the screen's DOM key. */
35
+ index: number;
36
+ page: PageNode;
37
+ /**
38
+ * The variant this screen draws, when its page came from a `variants=` list.
39
+ *
40
+ * Read off the page rather than derived here: `expandVariants` has already
41
+ * turned one variant-bearing page into one page per variant by the time a
42
+ * model is built, so each of those pages is a screen like any other and this
43
+ * only records which one it is.
44
+ */
45
+ variant?: string;
46
+ /** Name of the shell this screen is composed into, when it has one. */
47
+ shell?: string;
48
+ /** Set when `uses=` was declared and could not be honoured. */
49
+ miss?: {
50
+ uses: string;
51
+ reason: ShellMiss;
52
+ };
53
+ /**
54
+ * The public name this screen *owns* — the name that resolves to it.
55
+ *
56
+ * Absent when the page declared no name, and also when every name it declared
57
+ * is already owned by an earlier page. A screen without a name is still
58
+ * reachable: its index addresses it.
59
+ */
60
+ name?: string;
62
61
  }
63
- interface SvgRenderResult {
64
- /** Rendered SVG content */
65
- svg: string;
66
- /** Actual width */
62
+ /** One layout, emitted once, hosting every screen that uses it. */
63
+ interface SiteShell {
64
+ /** The `layout <name>` identifier, which `uses=` addresses. */
65
+ name: string;
66
+ layout: LayoutDefinitionNode;
67
+ /** Screens composed into this shell, in document order. */
68
+ screens: SiteScreen[];
69
+ /**
70
+ * Frame size of the shell, resolved from its first screen's page.
71
+ *
72
+ * A layout has no viewport of its own — it is the pages that declare one — so
73
+ * the first page to use it fixes the frame. A later page resolving to a
74
+ * different size is a conflict the author has to settle; it is marked on that
75
+ * screen rather than resized, because silently stretching one page's frame to
76
+ * another's is the kind of change that is invisible until a screenshot.
77
+ */
67
78
  width: number;
68
- /** Actual height */
69
79
  height: number;
70
80
  }
71
- interface RenderContext {
72
- /** Resolved render options */
73
- options: Required<RenderOptions>;
74
- /** Theme configuration */
75
- theme: ThemeConfig;
76
- /** Current nesting depth for indentation */
77
- depth: number;
78
- }
79
- interface ThemeColors {
80
- /** Primary action color */
81
- primary: string;
82
- /** Secondary/muted action color */
83
- secondary: string;
84
- /** Success state color */
85
- success: string;
86
- /** Warning state color */
87
- warning: string;
88
- /** Danger/error state color */
89
- danger: string;
90
- /** Muted/disabled color */
91
- muted: string;
92
- /** Background color */
93
- background: string;
94
- /** Foreground/text color */
95
- foreground: string;
96
- /** Border color */
97
- border: string;
98
- }
99
- interface ThemeConfig {
100
- /** Color palette */
101
- colors: ThemeColors;
102
- /** Spacing scale (number -> px value) */
103
- spacing: Record<number, string>;
104
- /** Border radius */
105
- radius: string;
106
- /** Font family */
107
- fontFamily: string;
108
- /** Shadow styles */
109
- shadows: Record<string, string>;
81
+ interface SiteModel {
82
+ screens: SiteScreen[];
83
+ /** Shells in first-use order — the order pages first reference them. */
84
+ shells: SiteShell[];
85
+ /**
86
+ * Every name that addresses a screen → that screen's index.
87
+ *
88
+ * Built exactly like `extract/transitions.ts` resolves `navigate`: the `id`
89
+ * namespace is consulted before the `title` namespace, and within each
90
+ * namespace the first page in document order wins. A `navigate` target and a
91
+ * URL fragment therefore land on the same screen the transition graph says
92
+ * they do — one resolution rule, two consumers.
93
+ */
94
+ names: Map<string, number>;
95
+ /** Screen shown when no fragment selects one. `-1` for a document with no pages. */
96
+ entry: number;
110
97
  }
111
98
  /**
112
- * Default wireframe theme using black/white/gray palette
113
- * Follows wireweave design principles for sketch-like appearance
114
- */
115
- declare const defaultTheme: ThemeConfig;
116
- /**
117
- * Dark theme configuration
118
- * Inverts colors for dark mode display
119
- */
120
- declare const darkTheme: ThemeConfig;
121
- /**
122
- * Get theme configuration by name
99
+ * Derive the screen model of a document.
100
+ *
101
+ * Pure and deterministic: same document in, same model out, whatever the
102
+ * document contains.
123
103
  */
124
- declare function getTheme(name: 'light' | 'dark'): ThemeConfig;
104
+ declare function buildSiteModel(doc: WireframeDocument): SiteModel;
125
105
 
126
106
  /**
127
107
  * Base HTML Renderer for wireweave
@@ -152,7 +132,12 @@ declare abstract class BaseRenderer {
152
132
  */
153
133
  render(document: WireframeDocument): RenderResult;
154
134
  /**
155
- * Render a complete wireframe document
135
+ * Render a complete wireframe document.
136
+ *
137
+ * Only pages are drawn. A document's top level also holds `layout` and
138
+ * `component` definitions, which are reusable fragments a page refers to —
139
+ * drawing one would put a screen on the canvas that the author never wrote a
140
+ * page for, and would do it the moment the reuse feature was used at all.
156
141
  */
157
142
  protected renderDocument(document: WireframeDocument): string;
158
143
  /**
@@ -179,6 +164,20 @@ declare abstract class BaseRenderer {
179
164
  * Escape HTML special characters
180
165
  */
181
166
  protected escapeHtml(text: string): string;
167
+ /**
168
+ * The DOM id an authored id becomes under this render's `idScope`.
169
+ *
170
+ * One function so that "what is the id in the document" has one answer. A
171
+ * renderer that prefixed at some emission sites and not others would produce
172
+ * a document where `#confirm` resolves for one element and `#s0-confirm` for
173
+ * another, which is worse than either convention alone.
174
+ *
175
+ * Only identity is prefixed. The interaction attributes that point at an
176
+ * overlay still carry the name their author wrote — they are spelled in one
177
+ * file (`html/interactive.ts`) and read by whoever consumes them, which
178
+ * composes the scope back on. See `RenderOptions.idScope`.
179
+ */
180
+ protected scopedId(id: string): string;
182
181
  /**
183
182
  * Build a CSS class string from an array of class names
184
183
  */
@@ -213,7 +212,30 @@ declare class HtmlRenderer extends BaseRenderer {
213
212
  * Node type to renderer method mapping
214
213
  */
215
214
  private readonly nodeRenderers;
216
- constructor(options?: RenderOptions);
215
+ /**
216
+ * Node → anchor-path map for the document currently being rendered. Non-null
217
+ * only while rendering with `sourceAnchors` enabled.
218
+ */
219
+ private pathMap;
220
+ /**
221
+ * Base index added to page anchor paths. Non-zero when a page is rendered in
222
+ * isolation (canvas per-page composition) but must keep its true document
223
+ * index in the anchor scheme.
224
+ */
225
+ private readonly pageIndexBase;
226
+ /**
227
+ * HTML the next `slot` renders, or `null` when there is none to place.
228
+ *
229
+ * Set for the duration of one `renderFragment` call and consumed by the first
230
+ * slot reached, so it never leaks into an unrelated render.
231
+ */
232
+ private slotContent;
233
+ constructor(options?: RenderOptions, pageIndexBase?: number);
234
+ /**
235
+ * Render a document, building the anchor-path map first when anchors are
236
+ * enabled so `renderNode` / `renderPage` can inject each node's path.
237
+ */
238
+ render(document: WireframeDocument): RenderResult;
217
239
  /**
218
240
  * Get render context for external renderer functions
219
241
  */
@@ -234,6 +256,45 @@ declare class HtmlRenderer extends BaseRenderer {
234
256
  * Render any AST node
235
257
  */
236
258
  protected renderNode(node: AnyNode): string;
259
+ /**
260
+ * Render the `slot` of a layout — the position a page's content is placed at.
261
+ *
262
+ * The element is always emitted, filled or not. A layout is a shell, and a
263
+ * shell keeps its shape whether or not something is currently inside it;
264
+ * collapsing the slot away when empty would make the frame reflow between an
265
+ * isolated render of the layout and a composed one.
266
+ */
267
+ protected renderSlot(): string;
268
+ /**
269
+ * Render one linked component invocation with its stable instance marker.
270
+ *
271
+ * The wrapper is identified by `data-` attributes and carries no class. It
272
+ * declares `display: contents`, so by construction it has no box of its own
273
+ * and its children lay out as though it were not there — which is the whole
274
+ * point: an invocation must not disturb the layout of what it expands to.
275
+ * A class is the hook a stylesheet paints a box through, and any rule that
276
+ * gave this one a box would defeat `display: contents`; there is therefore
277
+ * no style it could ever legitimately carry. It emitted
278
+ * `${this.prefix}-component-instance` regardless, which no rule in the
279
+ * generated CSS defined and nothing read — a class the markup advertises as
280
+ * styleable while the stylesheet leaves it undefined. Identity that exists
281
+ * to be *queried* rather than *painted* belongs in `data-`, alongside the
282
+ * `data-wf-component` / `data-wf-instance` pair already carrying it.
283
+ */
284
+ protected renderComponentUse(node: ComponentUseNode): string;
285
+ /**
286
+ * Render a list of nodes with no page frame around them.
287
+ *
288
+ * The frame — viewport size, background, the CSS reset every component
289
+ * depends on — belongs to whatever is composing these nodes. `renderSite`
290
+ * uses this twice per shell: once for the layout's own markup, where
291
+ * `slotContent` is the screens that live in it, and once per screen for that
292
+ * page's body.
293
+ *
294
+ * @param nodes - Nodes to render, in order
295
+ * @param slotContent - HTML placed inside the first `slot` encountered
296
+ */
297
+ renderFragment(nodes: AnyNode[], slotContent?: string | null): string;
237
298
  /**
238
299
  * Render children nodes
239
300
  */
@@ -354,7 +415,7 @@ declare function createHtmlRenderer(options?: RenderOptions): HtmlRenderer;
354
415
  * @param prefix - CSS class prefix (default: 'wf')
355
416
  * @returns Complete CSS string
356
417
  */
357
- declare function generateStyles(theme: ThemeConfig, prefix?: string): string;
418
+ declare function generateStyles(theme: ThemeConfig, prefix?: string, annotationStyle?: AnnotationStyle): string;
358
419
 
359
420
  /**
360
421
  * Component-specific CSS styles for wireweave
@@ -368,7 +429,7 @@ declare function generateStyles(theme: ThemeConfig, prefix?: string): string;
368
429
  /**
369
430
  * Generate all component-specific CSS styles
370
431
  */
371
- declare function generateComponentStyles(_theme: ThemeConfig, prefix?: string): string;
432
+ declare function generateComponentStyles(_theme: ThemeConfig, prefix?: string, annotationStyle?: AnnotationStyle): string;
372
433
 
373
434
  /**
374
435
  * Page renderer — single-Page primitive.
@@ -455,12 +516,145 @@ declare function layoutCanvas(pages: PageNode[], gap?: number): {
455
516
  declare function renderCanvas(doc: WireframeDocument, options?: CanvasOptions): CanvasRenderResult;
456
517
 
457
518
  /**
458
- * Lucide Icons Data
519
+ * Interaction intent → HTML attributes.
520
+ *
521
+ * `navigate` / `opens` / `toggles` / `action` are the declared interaction
522
+ * intent of a wireframe element (see {@link InteractiveProps}). They are the
523
+ * only structural link between screens, so every consumer of rendered
524
+ * output — the studio runtime, the transition graph, a prototype harness —
525
+ * finds them by these four `data-*` names.
526
+ *
527
+ * This module is their single owner. The attribute names are written down
528
+ * exactly once, here; renderers ask for the record and never spell the names
529
+ * themselves. Before this existed the block was copy-pasted into five
530
+ * renderers, and the sixth (`navigation.ts`) simply never got a copy — nav,
531
+ * tab and breadcrumb items parsed their interaction intent and then dropped it
532
+ * on the floor, which is the failure mode this module exists to make
533
+ * impossible to repeat.
534
+ *
535
+ * `__tests__/renderer-interactive.test.ts` enforces the single-owner property:
536
+ * it fails if any other file under `src/renderer/` spells one of these names.
537
+ */
538
+
539
+ /** The `data-*` attribute name carrying each interaction kind. */
540
+ declare const INTERACTIVE_ATTR_NAMES: readonly ["data-navigate", "data-opens", "data-toggles", "data-action"];
541
+ /** Internal: the shape of {@link InteractiveAttrs}'s keys. Consumers use that. */
542
+ type InteractiveAttrName = (typeof INTERACTIVE_ATTR_NAMES)[number];
543
+ /**
544
+ * Marks a `data-navigate` whose target is a URL rather than a page name.
545
+ *
546
+ * Only elements that are not anchors ever carry it: an anchor puts a URL in its
547
+ * `href` and emits no `data-navigate` at all, so there is nothing left to
548
+ * qualify. A button or a current-page `<span>` has no `href` to move the target
549
+ * into, so the URL travels in the data attribute — and without this marker every
550
+ * consumer would have to re-derive, from the string, the thing the renderer
551
+ * already worked out.
552
+ *
553
+ * That re-derivation is the point. {@link isUrlTarget} is a TypeScript predicate;
554
+ * the site runtime is generated JavaScript. A second copy of the rule over there
555
+ * is a drift surface by construction, and the two copies disagreeing means the
556
+ * runtime starts hunting for a screen named `https://…`. So the judgment is made
557
+ * once, here, at render time, and shipped as a fact the runtime only reads.
558
+ *
559
+ * The single-owner gate in `__tests__/renderer-interactive.test.ts` covers this
560
+ * name for free: it contains `data-navigate`, so any other file under
561
+ * `src/renderer/` that spells it is already an offender.
562
+ */
563
+ declare const EXTERNAL_NAVIGATE_ATTR = "data-navigate-external";
564
+ /** Typed runtime markers, owned beside the legacy interaction attributes. */
565
+ declare const TYPED_INTERACTION_ATTR = "data-wf-on";
566
+ declare const VISIBLE_GUARD_ATTR = "data-wf-visible-when";
567
+ declare const ENABLED_GUARD_ATTR = "data-wf-enabled-when";
568
+ /**
569
+ * The `href` an anchor gets when it has no destination of its own.
570
+ *
571
+ * An anchor must have an `href` to be a link — focusable, keyboard-activatable,
572
+ * announced as a link — but a wireframe anchor usually has nowhere to go: its
573
+ * intent, if any, travels as `data-navigate` and names a screen, not a URL.
574
+ * `#` is the standard inert stand-in, and it is a *statement by the renderer*:
575
+ * this element's `href` carries no destination.
459
576
  *
460
- * Auto-generated from lucide package.
461
- * Do not edit manually.
577
+ * It is exported because the site runtime needs to read that statement back.
578
+ * The browser's default action for `#` is a same-document navigation, and inside
579
+ * the `srcdoc` frame consumers mount the wireframe in, `#` resolves against the
580
+ * *embedder's* URL — so an unhandled click walks the frame out of the wireframe
581
+ * and loads the host app inside it. Measured on a 20-screen demo: 44 such
582
+ * anchors, frame URL `about:srcdoc` → `<host page>#`, host assets refetched.
583
+ *
584
+ * The runtime must therefore distinguish "inert" from "a real link the author
585
+ * asked for", and re-deriving that from the string over there is the drift
586
+ * surface {@link EXTERNAL_NAVIGATE_ATTR} exists to avoid. So the value is owned
587
+ * here and embedded into the generated script, like the attribute names.
588
+ */
589
+ declare const INERT_HREF = "#";
590
+ /**
591
+ * Attribute record for one element; absent intents stay `undefined`.
592
+ *
593
+ * The marker is boolean because it carries no value of its own — it qualifies
594
+ * the target next to it. `buildAttrsString` renders `true` as `name="name"`,
595
+ * which is the form that survives the XML parsing of an SVG `foreignObject`.
596
+ */
597
+ type InteractiveAttrs = Record<InteractiveAttrName, string | undefined> & Record<typeof EXTERNAL_NAVIGATE_ATTR, true | undefined> & Record<typeof TYPED_INTERACTION_ATTR | typeof VISIBLE_GUARD_ATTR | typeof ENABLED_GUARD_ATTR, string | undefined>;
598
+ /** Guard attributes accepted by ordinary nodes that do not carry events. */
599
+ declare function guardedOutcomeAttrs(node: Partial<GuardedOutcomeProps>): Record<typeof VISIBLE_GUARD_ATTR | typeof ENABLED_GUARD_ATTR, string | undefined>;
600
+ /**
601
+ * The interaction attributes of any node carrying {@link InteractiveProps}.
462
602
  *
463
- * Total icons: 1666
603
+ * The result is spread into a renderer's attribute record, or passed straight
604
+ * to `buildAttrsString` — which drops `undefined` entries, so an element with
605
+ * no declared intent emits nothing at all.
606
+ *
607
+ * Emission order is fixed (navigate, opens, toggles, action) so that rendered
608
+ * HTML stays byte-stable across runs; the marker sits next to the target it
609
+ * qualifies.
610
+ */
611
+ declare function interactiveAttrs(node: Partial<InteractiveProps>): InteractiveAttrs;
612
+ /**
613
+ * The `href` and interaction attributes of an element rendered as an `<a>`.
614
+ *
615
+ * An anchor is the one element with two channels that can carry a destination,
616
+ * so it is the one element where they can contradict each other — and it is the
617
+ * only place the choice between them has to be made. Both halves of that choice
618
+ * are decided here so a renderer never has to know the rule:
619
+ *
620
+ * - An authored `href` is the anchor and is left exactly as written.
621
+ * - Otherwise a URL-shaped `navigate` (see {@link isUrlTarget}) becomes the
622
+ * `href`, and no `data-navigate` goes out beside it. A URL is not a screen:
623
+ * emitting both would hand a consumer two destinations for one element and
624
+ * send a runtime hunting for a screen named `https://…`.
625
+ * - Otherwise the `navigate` target names a page. The anchor stays inert `#` —
626
+ * `href="교환소 지도"` is a broken relative link — and the intent travels as
627
+ * `data-navigate` for the consumer that knows what pages are.
628
+ *
629
+ * When an `href` *and* a URL-shaped `navigate` are both authored, both are
630
+ * emitted unchanged: the element already has its destination, and quietly
631
+ * dropping the second one would hide a contradiction only the author can settle.
632
+ * Naming that conflict belongs to validation, not to rendering.
633
+ *
634
+ * Elements that are not anchors keep {@link interactiveAttrs}: with no `href` to
635
+ * move it into, a URL-shaped target has only the data attribute to travel in,
636
+ * and dropping it there would discard what the author wrote. Those are the
637
+ * elements {@link EXTERNAL_NAVIGATE_ATTR} exists for.
638
+ */
639
+ declare function anchorIntent(node: Partial<InteractiveProps> & {
640
+ href?: string;
641
+ }): {
642
+ href: string;
643
+ attrs: InteractiveAttrs;
644
+ };
645
+
646
+ /**
647
+ * GENERATED FILE -- DO NOT EDIT.
648
+ *
649
+ * The icon dataset, generated from the installed `lucide` package by
650
+ * `scripts/generate-icons.mjs` (`pnpm build:icons`). Names kept beyond what
651
+ * lucide ships come from `scripts/icon-overrides.mjs`; add them there, never
652
+ * here, or the next regeneration deletes them.
653
+ *
654
+ * Total icons: 1667
655
+ *
656
+ * The lookup, alias and rendering code that consumes this lives in
657
+ * `./lucide-icons.ts` and is hand-written.
464
658
  *
465
659
  * @license ISC License
466
660
  *
@@ -477,12 +671,43 @@ declare function renderCanvas(doc: WireframeDocument, options?: CanvasOptions):
477
671
  type IconElement = [string, Record<string, string>];
478
672
  type IconData = IconElement[];
479
673
  declare const lucideIcons: Record<string, IconData>;
674
+
675
+ /**
676
+ * Icon lookup and SVG rendering.
677
+ *
678
+ * HAND-WRITTEN. The dataset this reads is generated -- see
679
+ * `./lucide-icons.generated.ts` and `scripts/generate-icons.mjs`. The two were
680
+ * a single file until the split: it carried an "Auto-generated ... Do not edit
681
+ * manually" header while the alias table, the alias branches in `getIconData`,
682
+ * the `renderIconSvg` signature and all of `renderUnknownIconSvg` below were
683
+ * added by hand, so running the generator would have destroyed working code
684
+ * that four renderers import. Data and code now have one owner each.
685
+ *
686
+ * The dataset's exports are re-exported here so `src/index.ts` can keep
687
+ * re-exporting this module and the public surface is unchanged.
688
+ */
689
+
690
+ /**
691
+ * Get icon data by name.
692
+ *
693
+ * Resolution order is exact key, then alias, then camelCase folded to
694
+ * kebab-case, then that folded name through the aliases. A name that survives
695
+ * all four is not drawable, and the caller renders the placeholder below.
696
+ */
480
697
  declare function getIconData(name: string): IconData | undefined;
481
698
  /**
482
699
  * Render icon data to SVG string
483
700
  */
484
701
  declare function renderIconSvg(data: IconData, _size?: number, // size is now controlled by CSS, this param is kept for API compatibility
485
702
  strokeWidth?: number, className?: string, styleAttr?: string): string;
703
+ /**
704
+ * Render the canonical "unknown icon" placeholder SVG — a dashed circle with a
705
+ * `?` glyph. Shared by every renderer (icon node, button, input) so an
706
+ * unresolved icon name always produces the SAME visual placeholder and never
707
+ * leaks the raw DSL name as literal text. Callers add a
708
+ * `title="Unknown icon: <name>"` on the wrapping element for hover context.
709
+ */
710
+ declare function renderUnknownIconSvg(className?: string, size?: number, styleAttr?: string): string;
486
711
 
487
712
  /**
488
713
  * Renderer module for wireweave
@@ -528,4 +753,4 @@ declare function renderToHtml(document: WireframeDocument, options?: RenderOptio
528
753
  */
529
754
  declare function renderToSvg(document: WireframeDocument, options?: SvgRenderOptions): SvgRenderResult;
530
755
 
531
- export { type CanvasOptions, type CanvasRenderResult, HtmlRenderer, type IconData, type IconElement, type PageRenderResult, type PlacedPage, type RenderContext, type RenderOptions, type RenderResult, type SvgRenderOptions, type SvgRenderResult, type ThemeColors, type ThemeConfig, createHtmlRenderer, darkTheme, defaultTheme, generateComponentStyles, generateStyles, getIconData, getTheme, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderToHtml, renderToSvg, resolvePageDimensions };
756
+ export { AnnotationStyle, CanvasOptions, CanvasRenderResult, ENABLED_GUARD_ATTR, EXTERNAL_NAVIGATE_ATTR, HtmlRenderer, INERT_HREF, INTERACTIVE_ATTR_NAMES, type IconData, type IconElement, type InteractiveAttrs, PageRenderResult, type PlacedPage, RenderContext, RenderOptions, RenderResult, type ShellMiss, type SiteModel, type SiteScreen, type SiteShell, SvgRenderOptions, SvgRenderResult, TYPED_INTERACTION_ATTR, ThemeConfig, VISIBLE_GUARD_ATTR, anchorIntent, buildSiteModel, createHtmlRenderer, generateComponentStyles, generateStyles, getIconData, guardedOutcomeAttrs, interactiveAttrs, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions };