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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,4 @@
1
- import { be as WireframeDocument, h as AnyNode, au as PageNode, H as ComponentUseNode, ab as LayoutDefinitionNode, a9 as InteractiveProps } from './types-Bb3NSNUs.cjs';
1
+ import { bc as WireframeDocument, h as AnyNode, as as PageNode, H as ComponentUseNode, aa as LayoutDefinitionNode, a8 as InteractiveProps, Y as GuardedOutcomeProps } from './types-BiDAgo6f.cjs';
2
2
 
3
3
  /**
4
4
  * Renderer type definitions for wireweave
@@ -20,7 +20,10 @@ interface RenderOptions {
20
20
  classPrefix?: string;
21
21
  /** Background color (e.g., '#ffffff', 'transparent') */
22
22
  background?: string;
23
- /** Explicit neutral mode preserves the historical presentation by default. */
23
+ /**
24
+ * Annotation presentation. Defaults to `legacy` so existing render output
25
+ * stays unchanged; use `neutral` for deterministic grayscale annotations.
26
+ */
24
27
  annotationStyle?: AnnotationStyle;
25
28
  /**
26
29
  * Emit source-anchor attributes (`data-wf-path` / `data-wf-loc`) on each
@@ -28,7 +31,27 @@ interface RenderOptions {
28
31
  * `false` — output is byte-identical to non-anchored rendering when off.
29
32
  */
30
33
  sourceAnchors?: boolean;
31
- /** Prefix authored overlay ids with a renderer-owned scope. */
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
+ */
32
55
  idScope?: string;
33
56
  }
34
57
  interface RenderResult {
@@ -164,7 +187,12 @@ declare abstract class BaseRenderer {
164
187
  */
165
188
  render(document: WireframeDocument): RenderResult;
166
189
  /**
167
- * Render a complete wireframe document
190
+ * Render a complete wireframe document.
191
+ *
192
+ * Only pages are drawn. A document's top level also holds `layout` and
193
+ * `component` definitions, which are reusable fragments a page refers to —
194
+ * drawing one would put a screen on the canvas that the author never wrote a
195
+ * page for, and would do it the moment the reuse feature was used at all.
168
196
  */
169
197
  protected renderDocument(document: WireframeDocument): string;
170
198
  /**
@@ -191,7 +219,19 @@ declare abstract class BaseRenderer {
191
219
  * Escape HTML special characters
192
220
  */
193
221
  protected escapeHtml(text: string): string;
194
- /** Return the DOM id for an authored id under this renderer's scope. */
222
+ /**
223
+ * The DOM id an authored id becomes under this render's `idScope`.
224
+ *
225
+ * One function so that "what is the id in the document" has one answer. A
226
+ * renderer that prefixed at some emission sites and not others would produce
227
+ * a document where `#confirm` resolves for one element and `#s0-confirm` for
228
+ * another, which is worse than either convention alone.
229
+ *
230
+ * Only identity is prefixed. The interaction attributes that point at an
231
+ * overlay still carry the name their author wrote — they are spelled in one
232
+ * file (`html/interactive.ts`) and read by whoever consumes them, which
233
+ * composes the scope back on. See `RenderOptions.idScope`.
234
+ */
195
235
  protected scopedId(id: string): string;
196
236
  /**
197
237
  * Build a CSS class string from an array of class names
@@ -238,7 +278,12 @@ declare class HtmlRenderer extends BaseRenderer {
238
278
  * index in the anchor scheme.
239
279
  */
240
280
  private readonly pageIndexBase;
241
- /** Content supplied by a site renderer for the next layout slot. */
281
+ /**
282
+ * HTML the next `slot` renders, or `null` when there is none to place.
283
+ *
284
+ * Set for the duration of one `renderFragment` call and consumed by the first
285
+ * slot reached, so it never leaks into an unrelated render.
286
+ */
242
287
  private slotContent;
243
288
  constructor(options?: RenderOptions, pageIndexBase?: number);
244
289
  /**
@@ -266,11 +311,29 @@ declare class HtmlRenderer extends BaseRenderer {
266
311
  * Render any AST node
267
312
  */
268
313
  protected renderNode(node: AnyNode): string;
269
- /** Render the first slot with the supplied page content, if any. */
314
+ /**
315
+ * Render the `slot` of a layout — the position a page's content is placed at.
316
+ *
317
+ * The element is always emitted, filled or not. A layout is a shell, and a
318
+ * shell keeps its shape whether or not something is currently inside it;
319
+ * collapsing the slot away when empty would make the frame reflow between an
320
+ * isolated render of the layout and a composed one.
321
+ */
270
322
  protected renderSlot(): string;
271
323
  /** Render one linked component invocation with its stable instance marker. */
272
324
  protected renderComponentUse(node: ComponentUseNode): string;
273
- /** Render nodes without adding a page frame, optionally filling a slot. */
325
+ /**
326
+ * Render a list of nodes with no page frame around them.
327
+ *
328
+ * The frame — viewport size, background, the CSS reset every component
329
+ * depends on — belongs to whatever is composing these nodes. `renderSite`
330
+ * uses this twice per shell: once for the layout's own markup, where
331
+ * `slotContent` is the screens that live in it, and once per screen for that
332
+ * page's body.
333
+ *
334
+ * @param nodes - Nodes to render, in order
335
+ * @param slotContent - HTML placed inside the first `slot` encountered
336
+ */
274
337
  renderFragment(nodes: AnyNode[], slotContent?: string | null): string;
275
338
  /**
276
339
  * Render children nodes
@@ -492,41 +555,175 @@ declare function layoutCanvas(pages: PageNode[], gap?: number): {
492
555
  */
493
556
  declare function renderCanvas(doc: WireframeDocument, options?: CanvasOptions): CanvasRenderResult;
494
557
 
495
- /** Why a page that declared `uses=` was not composed into a layout. */
496
- type ShellMiss = 'unknown-layout' | 'slotless-layout';
558
+ /**
559
+ * The screen model behind `renderSite` — which pages become screens, which
560
+ * shell each one is drawn inside, and what names address it.
561
+ *
562
+ * Nothing here renders. It answers three questions the site renderer and its
563
+ * inline runtime both need the *same* answer to, so the answer is computed once
564
+ * and handed to both.
565
+ *
566
+ * ## Totality
567
+ *
568
+ * A wireframe document can name a layout that does not exist, declare two pages
569
+ * with the same `id`, or use a layout with no `slot`. None of those is a parse
570
+ * error (see the note on `WireframeDocument`), so none of them may stop a
571
+ * render either: every function here is total. Where a document is ambiguous
572
+ * the rule is always **first-wins in document order** — the same rule
573
+ * `extract/transitions.ts` already applies to titles — and the loser is not
574
+ * dropped silently: it is rendered with a `data-wf-*` marker naming what went
575
+ * unmet, so a reader of the output can see it and `validation/` can report it
576
+ * with a source location.
577
+ */
578
+
579
+ /** Why a page that declared `uses=` is not composed into a shell after all. */
580
+ type ShellMiss =
581
+ /** No `layout` in the document carries that name. */
582
+ 'unknown-layout'
583
+ /** The layout exists but has no `slot`, so it has nowhere to put a page. */
584
+ | 'slotless-layout';
585
+ /** One page, as a screen of the composed document. */
497
586
  interface SiteScreen {
498
- /** Position in documentPages(document), used as the stable screen key. */
587
+ /** Position in `documentPages(doc)`. This is the screen's DOM key. */
499
588
  index: number;
500
589
  page: PageNode;
590
+ /** Name of the shell this screen is composed into, when it has one. */
501
591
  shell?: string;
592
+ /** Set when `uses=` was declared and could not be honoured. */
502
593
  miss?: {
503
594
  uses: string;
504
595
  reason: ShellMiss;
505
596
  };
506
- /** The first declared id or title that resolves back to this screen. */
597
+ /**
598
+ * The public name this screen *owns* — the name that resolves to it.
599
+ *
600
+ * Absent when the page declared no name, and also when every name it declared
601
+ * is already owned by an earlier page. A screen without a name is still
602
+ * reachable: its index addresses it.
603
+ */
507
604
  name?: string;
508
605
  }
606
+ /** One layout, emitted once, hosting every screen that uses it. */
509
607
  interface SiteShell {
608
+ /** The `layout <name>` identifier, which `uses=` addresses. */
510
609
  name: string;
511
610
  layout: LayoutDefinitionNode;
611
+ /** Screens composed into this shell, in document order. */
512
612
  screens: SiteScreen[];
613
+ /**
614
+ * Frame size of the shell, resolved from its first screen's page.
615
+ *
616
+ * A layout has no viewport of its own — it is the pages that declare one — so
617
+ * the first page to use it fixes the frame. A later page resolving to a
618
+ * different size is a conflict the author has to settle; it is marked on that
619
+ * screen rather than resized, because silently stretching one page's frame to
620
+ * another's is the kind of change that is invisible until a screenshot.
621
+ */
513
622
  width: number;
514
623
  height: number;
515
624
  }
516
625
  interface SiteModel {
517
626
  screens: SiteScreen[];
627
+ /** Shells in first-use order — the order pages first reference them. */
518
628
  shells: SiteShell[];
629
+ /**
630
+ * Every name that addresses a screen → that screen's index.
631
+ *
632
+ * Built exactly like `extract/transitions.ts` resolves `navigate`: the `id`
633
+ * namespace is consulted before the `title` namespace, and within each
634
+ * namespace the first page in document order wins. A `navigate` target and a
635
+ * URL fragment therefore land on the same screen the transition graph says
636
+ * they do — one resolution rule, two consumers.
637
+ */
519
638
  names: Map<string, number>;
639
+ /** Screen shown when no fragment selects one. `-1` for a document with no pages. */
520
640
  entry: number;
521
641
  }
522
- /** Build the page/shell/name model shared by the site renderer and runtime. */
642
+ /**
643
+ * Derive the screen model of a document.
644
+ *
645
+ * Pure and deterministic: same document in, same model out, whatever the
646
+ * document contains.
647
+ */
523
648
  declare function buildSiteModel(doc: WireframeDocument): SiteModel;
524
649
 
650
+ /**
651
+ * `renderSite` — a whole wireframe document as one navigable HTML file.
652
+ *
653
+ * The other renderers answer "what does this screen look like". This one
654
+ * answers "what does this product look like": every page of a document, the
655
+ * shells they share, and the moves between them, in a single file with no
656
+ * server, no build step and no dependencies. Open it and click.
657
+ *
658
+ * ## What makes it one document rather than N concatenated
659
+ *
660
+ * Three things exist once, however many screens there are:
661
+ *
662
+ * - **the stylesheet** — component styles are generated per document, not per
663
+ * page, so N screens cost one copy instead of N;
664
+ * - **the runtime** — one inline script drives every screen;
665
+ * - **each layout** — a `layout` referenced by `uses=` is emitted once, and
666
+ * every page using it is hosted inside that one copy at the `slot` position.
667
+ *
668
+ * The third is the one that has to be structural. Emitting a copy of the shell
669
+ * per screen and hiding all but one with CSS produces the same picture while
670
+ * keeping every byte the shared shell exists to remove; the shell is therefore
671
+ * shared in the DOM, and only screens are switched.
672
+ *
673
+ * ## Ids under composition
674
+ *
675
+ * An authored `id` is unique inside the page that declares it. Once several
676
+ * pages share a document that guarantee is gone, so every screen and every
677
+ * shell renders under an id scope of its own and the runtime composes the scope
678
+ * with the authored name when it looks an overlay up. Two screens can both
679
+ * declare `confirm` and each opens its own.
680
+ *
681
+ * ## What is left alone
682
+ *
683
+ * A page with no `uses=` renders exactly as `renderPage` renders it, frame and
684
+ * all, as its own screen. That is the whole corpus today, so composition is
685
+ * something a document opts into and nothing changes shape without being asked.
686
+ *
687
+ * `render` / `renderToHtml` / `renderCanvas` / `renderToSvg` are untouched:
688
+ * `renderSite` is a fifth entry point beside them, not a mode of them.
689
+ */
690
+
691
+ /**
692
+ * Options for {@link renderSite}.
693
+ *
694
+ * A subset of {@link RenderOptions}: `includeStyles` is meaningless for a
695
+ * standalone document that has nowhere else to get its styles from, and
696
+ * `sourceAnchors` is omitted because an anchor path names a node's position
697
+ * under one page — a shell belongs to every page that uses it and has no single
698
+ * such position, so the scheme has nothing true to say about it.
699
+ */
525
700
  interface SiteOptions extends Pick<RenderOptions, 'theme' | 'classPrefix' | 'background' | 'annotationStyle'> {
701
+ /** `<title>` of the produced document. Defaults to the entry page's title. */
526
702
  title?: string;
703
+ /**
704
+ * The screen shown when the URL carries no fragment.
705
+ *
706
+ * Named the way everything else names a screen — an `id` or a `title`, put
707
+ * through {@link SiteModel.names}, so a caller writes the same string here
708
+ * that it would write in a `navigate=` and lands on the same page. Taking an
709
+ * index instead would make the option depend on document order, which is the
710
+ * one thing a caller holding a screen name does not know.
711
+ *
712
+ * Defaults to the first page in document order. A name that addresses no
713
+ * screen leaves that default in place and is marked on the site container as
714
+ * `data-wf-entry-unresolved`, the way an unmet `uses=` is marked on its
715
+ * screen: the request stays visible in the artefact instead of disappearing
716
+ * between the call and the HTML.
717
+ */
527
718
  entry?: string;
528
719
  }
529
- /** Render pages and their optional named layouts as one self-contained site. */
720
+ /**
721
+ * Render a whole document as one navigable, self-contained HTML file.
722
+ *
723
+ * @param document - Parsed wireframe document
724
+ * @param options - Site render options
725
+ * @returns A complete HTML document, ready to write to disk and open
726
+ */
530
727
  declare function renderSite(document: WireframeDocument, options?: SiteOptions): string;
531
728
 
532
729
  /**
@@ -579,6 +776,28 @@ declare const EXTERNAL_NAVIGATE_ATTR = "data-navigate-external";
579
776
  declare const TYPED_INTERACTION_ATTR = "data-wf-on";
580
777
  declare const VISIBLE_GUARD_ATTR = "data-wf-visible-when";
581
778
  declare const ENABLED_GUARD_ATTR = "data-wf-enabled-when";
779
+ /**
780
+ * The `href` an anchor gets when it has no destination of its own.
781
+ *
782
+ * An anchor must have an `href` to be a link — focusable, keyboard-activatable,
783
+ * announced as a link — but a wireframe anchor usually has nowhere to go: its
784
+ * intent, if any, travels as `data-navigate` and names a screen, not a URL.
785
+ * `#` is the standard inert stand-in, and it is a *statement by the renderer*:
786
+ * this element's `href` carries no destination.
787
+ *
788
+ * It is exported because the site runtime needs to read that statement back.
789
+ * The browser's default action for `#` is a same-document navigation, and inside
790
+ * the `srcdoc` frame consumers mount the wireframe in, `#` resolves against the
791
+ * *embedder's* URL — so an unhandled click walks the frame out of the wireframe
792
+ * and loads the host app inside it. Measured on a 20-screen demo: 44 such
793
+ * anchors, frame URL `about:srcdoc` → `<host page>#`, host assets refetched.
794
+ *
795
+ * The runtime must therefore distinguish "inert" from "a real link the author
796
+ * asked for", and re-deriving that from the string over there is the drift
797
+ * surface {@link EXTERNAL_NAVIGATE_ATTR} exists to avoid. So the value is owned
798
+ * here and embedded into the generated script, like the attribute names.
799
+ */
800
+ declare const INERT_HREF = "#";
582
801
  /**
583
802
  * Attribute record for one element; absent intents stay `undefined`.
584
803
  *
@@ -587,6 +806,20 @@ declare const ENABLED_GUARD_ATTR = "data-wf-enabled-when";
587
806
  * which is the form that survives the XML parsing of an SVG `foreignObject`.
588
807
  */
589
808
  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>;
809
+ /** Guard attributes accepted by ordinary nodes that do not carry events. */
810
+ declare function guardedOutcomeAttrs(node: Partial<GuardedOutcomeProps>): Record<typeof VISIBLE_GUARD_ATTR | typeof ENABLED_GUARD_ATTR, string | undefined>;
811
+ /**
812
+ * The interaction attributes of any node carrying {@link InteractiveProps}.
813
+ *
814
+ * The result is spread into a renderer's attribute record, or passed straight
815
+ * to `buildAttrsString` — which drops `undefined` entries, so an element with
816
+ * no declared intent emits nothing at all.
817
+ *
818
+ * Emission order is fixed (navigate, opens, toggles, action) so that rendered
819
+ * HTML stays byte-stable across runs; the marker sits next to the target it
820
+ * qualifies.
821
+ */
822
+ declare function interactiveAttrs(node: Partial<InteractiveProps>): InteractiveAttrs;
590
823
  /**
591
824
  * The `href` and interaction attributes of an element rendered as an `<a>`.
592
825
  *
@@ -622,12 +855,17 @@ declare function anchorIntent(node: Partial<InteractiveProps> & {
622
855
  };
623
856
 
624
857
  /**
625
- * Lucide Icons Data
858
+ * GENERATED FILE -- DO NOT EDIT.
859
+ *
860
+ * The icon dataset, generated from the installed `lucide` package by
861
+ * `scripts/generate-icons.mjs` (`pnpm build:icons`). Names kept beyond what
862
+ * lucide ships come from `scripts/icon-overrides.mjs`; add them there, never
863
+ * here, or the next regeneration deletes them.
626
864
  *
627
- * Auto-generated from lucide package.
628
- * Do not edit manually.
865
+ * Total icons: 1667
629
866
  *
630
- * Total icons: 1666
867
+ * The lookup, alias and rendering code that consumes this lives in
868
+ * `./lucide-icons.ts` and is hand-written.
631
869
  *
632
870
  * @license ISC License
633
871
  *
@@ -644,6 +882,29 @@ declare function anchorIntent(node: Partial<InteractiveProps> & {
644
882
  type IconElement = [string, Record<string, string>];
645
883
  type IconData = IconElement[];
646
884
  declare const lucideIcons: Record<string, IconData>;
885
+
886
+ /**
887
+ * Icon lookup and SVG rendering.
888
+ *
889
+ * HAND-WRITTEN. The dataset this reads is generated -- see
890
+ * `./lucide-icons.generated.ts` and `scripts/generate-icons.mjs`. The two were
891
+ * a single file until the split: it carried an "Auto-generated ... Do not edit
892
+ * manually" header while the alias table, the alias branches in `getIconData`,
893
+ * the `renderIconSvg` signature and all of `renderUnknownIconSvg` below were
894
+ * added by hand, so running the generator would have destroyed working code
895
+ * that four renderers import. Data and code now have one owner each.
896
+ *
897
+ * The dataset's exports are re-exported here so `src/index.ts` can keep
898
+ * re-exporting this module and the public surface is unchanged.
899
+ */
900
+
901
+ /**
902
+ * Get icon data by name.
903
+ *
904
+ * Resolution order is exact key, then alias, then camelCase folded to
905
+ * kebab-case, then that folded name through the aliases. A name that survives
906
+ * all four is not drawable, and the caller renders the placeholder below.
907
+ */
647
908
  declare function getIconData(name: string): IconData | undefined;
648
909
  /**
649
910
  * Render icon data to SVG string
@@ -703,4 +964,4 @@ declare function renderToHtml(document: WireframeDocument, options?: RenderOptio
703
964
  */
704
965
  declare function renderToSvg(document: WireframeDocument, options?: SvgRenderOptions): SvgRenderResult;
705
966
 
706
- export { type AnnotationStyle, type CanvasOptions, type CanvasRenderResult, HtmlRenderer, type IconData, type IconElement, type InteractiveAttrs, type PageRenderResult, type PlacedPage, type RenderContext, type RenderOptions, type RenderResult, type ShellMiss, type SiteModel, type SiteOptions, type SiteScreen, type SiteShell, type SvgRenderOptions, type SvgRenderResult, type ThemeColors, type ThemeConfig, anchorIntent, buildSiteModel, createHtmlRenderer, darkTheme, defaultTheme, generateComponentStyles, generateStyles, getIconData, getTheme, layoutCanvas, lucideIcons, render, renderCanvas, renderIconSvg, renderPage, renderSite, renderToHtml, renderToSvg, renderUnknownIconSvg, resolvePageDimensions };
967
+ export { type AnnotationStyle, type CanvasOptions, type CanvasRenderResult, ENABLED_GUARD_ATTR, EXTERNAL_NAVIGATE_ATTR, HtmlRenderer, INERT_HREF, INTERACTIVE_ATTR_NAMES, type IconData, type IconElement, type InteractiveAttrs, type PageRenderResult, type PlacedPage, type RenderContext, type RenderOptions, type RenderResult, type ShellMiss, type SiteModel, type SiteOptions, type SiteScreen, type SiteShell, type SvgRenderOptions, type SvgRenderResult, TYPED_INTERACTION_ATTR, type ThemeColors, type 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 };