@walkeros/explorer 4.8.0-next-1791441510508 → 4.8.0

package/dist/index.d.cts

@@ -1,9 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Destination, WalkerOS, Flow, Elb } from '@walkeros/core';
-import React, { ReactNode } from 'react';
+import { Destination, WalkerOS, Flow, Collector } from '@walkeros/core';
+import React, { ReactNode, AriaAttributes, ReactElement, ButtonHTMLAttributes } from 'react';
 import * as monaco_editor from 'monaco-editor';
 import { editor } from 'monaco-editor';
 import { RJSFSchema } from '@rjsf/utils';
+import { SourceBrowser } from '@walkeros/web-source-browser';
 import { Monaco } from '@monaco-editor/react';
 export { Monaco } from '@monaco-editor/react';
 export { Icon } from '@iconify/react';
@@ -18,7 +19,6 @@ interface PromotionPlaygroundProps {
     initialCss?: string;
     initialJs?: string;
     initialMapping?: string;
-    labelCode?: string;
     labelPreview?: string;
     labelEvents?: string;
     labelMapping?: string;
@@ -28,19 +28,33 @@ interface PromotionPlaygroundProps {
 /**
  * PromotionPlayground - Full walkerOS demonstration with live code editing
  *
- * Shows the complete chain:
- * 1. Code Editor - Edit HTML/CSS/JS with walkerOS data attributes
- * 2. Preview - Live rendered output that captures real events
- * 3. Events - Real events captured from preview interactions
- * 4. Mapping - Apply transformations and see destination output
- * 5. Result - Final destination function calls
- *
- * Uses a single unified collector flow:
- * - PromotionPlayground owns the collector with destinations
- * - Preview initializes browser source using parent's elb
- * - Events flow through one collector to all destinations
+ * Shows the complete chain, one box each:
+ * 1. Preview - the live page, with HTML/CSS/JS tabs to edit it; captures real events
+ * 2. Events - the events the preview sent
+ * 3. Mapping - editable rules for the destination
+ * 4. Result - the destination call each event becomes
+ *
+ * One collector runs the flow: Preview binds a browser source to it, and its
+ * destinations fill the Events and Result boxes. Whatever fails says so in
+ * the box it concerns.
+ */
+declare function PromotionPlayground({ initialHtml, initialCss, initialJs, initialMapping, labelPreview, labelEvents, labelMapping, labelResult, destination: destinationProp, }: PromotionPlaygroundProps): react_jsx_runtime.JSX.Element;
+
+interface PlaygroundProps {
+    eyebrow?: ReactNode;
+    title?: ReactNode;
+    lead?: ReactNode;
+}
+/**
+ * The walkerOS playground: a tagged component, the event it sends, the
+ * mapping and the vendor call it becomes, live.
+ *
+ * One real flow runs the chain. `startFlow` starts a collector with the
+ * browser source scoped to the preview's shadow root and the gtag destination
+ * with the editor's mapping. The destination's `window` is a stub that hands
+ * each gtag call to the Result panel instead of sending it to GA4.
  */
-declare function PromotionPlayground({ initialHtml, initialCss, initialJs, initialMapping, labelCode, labelPreview, labelEvents, labelMapping, labelResult, destination: destinationProp, }: PromotionPlaygroundProps): react_jsx_runtime.JSX.Element;
+declare function Playground({ eyebrow, title, lead, }: PlaygroundProps): react_jsx_runtime.JSX.Element;
 
 interface LiveCodeProps {
     input: unknown;
@@ -52,6 +66,7 @@ interface LiveCodeProps {
     labelInput?: string;
     labelConfig?: string;
     labelOutput?: string;
+    /** Plain words in the empty Result box, such as why a run returns nothing. */
     emptyText?: string;
     disableInput?: boolean;
     disableConfig?: boolean;
@@ -61,7 +76,7 @@ interface LiveCodeProps {
     format?: boolean;
     rowHeight?: 'auto' | 'equal' | 'synced' | number;
     /** Language for the Result panel. Defaults to json (the typical output
-     * shape). Set to `javascript` when emptyText includes `//` comments. */
+     * shape). */
     outputLanguage?: string;
     /** Language for the Config panel. Defaults to `json`. Override when the
      * Config panel content is not JSON. */
@@ -291,6 +306,12 @@ interface CodeBoxProps extends Omit<CodeProps, 'code'> {
         errors: number;
         warnings: number;
     }) => void;
+    /** Plain words shown over the editor while `code` is empty, such as what fills it. */
+    placeholder?: string;
+    /** What failed for this box, shown above the editor with an icon and the word Error. */
+    error?: string;
+    /** `status` for input validation the reader is typing through; `alert` (default) otherwise. */
+    errorRole?: 'alert' | 'status';
     footer?: React.ReactNode;
     height?: string | number;
     style?: React.CSSProperties;
@@ -335,7 +356,7 @@ interface CodeBoxProps extends Omit<CodeProps, 'code'> {
  *   showFormat
  * />
  */
-declare function CodeBox({ code, language, onChange, disabled, autoHeight, label, header, showHeader, tabs, activeTab: controlledActiveTab, onTabChange, defaultTab, showTrafficLights, showCopy, showFormat, showSettings, onValidationIssues, footer, height, style, className, ...codeProps }: CodeBoxProps): react_jsx_runtime.JSX.Element;
+declare function CodeBox({ code, language, onChange, disabled, autoHeight, label, header, showHeader, tabs, activeTab: controlledActiveTab, onTabChange, defaultTab, showTrafficLights, showCopy, showFormat, showSettings, onValidationIssues, placeholder, error, errorRole, footer, height, style, className, ...codeProps }: CodeBoxProps): react_jsx_runtime.JSX.Element;
 
 interface CodeDiffBoxProps {
     original: string;
@@ -553,7 +574,16 @@ interface PreviewProps {
     html?: string;
     css?: string;
     js?: string;
-    elb?: Elb.Fn;
+    /**
+     * The collector that captures the preview's events. Preview binds a browser
+     * source to its document through the collector's own source wiring, so
+     * every click and load event runs the collector's pipeline. Without it the
+     * preview only renders. The source is the preview's own, not one of the
+     * collector's `sources`: `walker consent` and `walker user` do not reach
+     * it, and the collector's status does not list it.
+     */
+    collector?: Collector.Instance;
+    /** The box's name; with `editable`, the name of its first tab. */
     label?: string;
     /**
      * Opt-in editor tabs. When true, the header shows a `tabs` ButtonGroup to
@@ -574,8 +604,8 @@ interface PreviewProps {
  * Preview - HTML preview wrapped in a Box with highlight buttons
  *
  * Renders HTML in an isolated iframe with highlight buttons footer.
- * When elb is provided, initializes walkerOS browser source in iframe
- * that pushes events to the parent collector.
+ * With a collector, a walkerOS browser source captures the iframe's events
+ * into it; a source that fails to start says so in the box.
  *
  * Load semantics mirror a real browser: `load` triggers (and pageview) fire
  * once on the initial load and again only when the user clicks Reload. Editing
@@ -586,10 +616,62 @@ interface PreviewProps {
  * // Read-only preview
  * <Preview html={html} css={css} label="Preview" />
  *
- * // Interactive preview with event capture (elb from parent collector)
- * <Preview html={html} css={css} elb={elb} label="Preview" />
+ * // Interactive preview that captures events into a collector
+ * <Preview html={html} css={css} collector={collector} label="Preview" />
+ */
+declare function Preview({ html, css, js, collector, label, editable, initialTab, onHtmlChange, onCssChange, onJsChange, lineNumbers, wordWrap, }: PreviewProps): react_jsx_runtime.JSX.Element;
+
+interface ViewSourceProps extends AriaAttributes {
+    /** Exactly one element: the component whose HTML is shown. */
+    children: ReactElement;
+    /**
+     * The page's elb (the browser source's push). After an edit is applied, and
+     * after Reset brings the original back, ViewSource calls
+     * `elb('walker init', element)` so the new nodes get their triggers.
+     */
+    elb?: SourceBrowser.Push;
+    /**
+     * Lets the wrapped element fill a stretched grid or flex cell as it does
+     * unwrapped (cards in a grid row). The root and its content become
+     * one-column grids: an auto-height element fills the cell, its margins,
+     * own self-alignment and explicit height still apply, and its vertical
+     * margins stay inside the wrapper. Leave it off for an element centered
+     * with auto margins (a section with `mx-auto`), which a grid shrinks to
+     * fit.
+     */
+    stretch?: boolean;
+    className?: string;
+    id?: string;
+    [dataAttribute: `data-${string}`]: string | undefined;
+}
+/**
+ * ViewSource - shows a component's live HTML in place and lets you edit it.
+ *
+ * Wraps exactly one element and adds no frame of its own. A toggle at the
+ * top right switches between Visual and Code. Code shows the element's live
+ * HTML, formatted and editable, on a dark code surface; the code covers the
+ * element's visible box (its border box when it paints a background or
+ * border, else its content box inside the padding), and the toggle sits at
+ * that box's top right. Escape leaves the editor for the toggle.
+ * Back in Visual, a changed edit replaces the element as plain HTML (React
+ * handlers inside it are inactive) and `elb('walker init', element)`
+ * registers its triggers. Reset, an icon beside the toggle, mounts the
+ * original children again and registers theirs the same way.
+ *
+ * ViewSources nest: an outer snapshot shows the inner wrapped elements
+ * without their wrappers, and only the innermost hovered toolbar shows. An
+ * applied outer edit is plain HTML, so it has no inner wrappers until Reset.
+ *
+ * Wrap the outermost tagged element of a section, never an element inside one
+ * with a click action: a click on the toolbar bubbles to the wrapper's
+ * ancestors.
+ *
+ * @example
+ * <ViewSource elb={elb}>
+ *   <PromotionHero />
+ * </ViewSource>
  */
-declare function Preview({ html, css, js, elb, label, editable, initialTab, onHtmlChange, onCssChange, onJsChange, lineNumbers, wordWrap, }: PreviewProps): react_jsx_runtime.JSX.Element;
+declare function ViewSource({ children, elb, stretch, className, ...rest }: ViewSourceProps): react_jsx_runtime.JSX.Element;
 
 interface CodeDiffSummary {
     /** Count of hunks that exist only in modified (pure additions). */
@@ -659,8 +741,15 @@ interface BoxProps {
     showTrafficLights?: boolean;
     /** Pins the box to one theme, whatever the page theme (a dark island). */
     theme?: Theme;
+    /** What failed in this box, shown above its content with an icon and the word Error. */
+    error?: string;
+    /**
+     * How the error is announced: `alert` (default) interrupts, for a failure;
+     * `status` waits, for input validation that changes as the reader types.
+     */
+    errorRole?: 'alert' | 'status';
 }
-declare function Box({ header, headerActions, footer, children, className, style, height, minHeight, maxHeight, tiny, resizable, showHeader, tabs, activeTab: controlledActiveTab, onTabChange, defaultTab, showTrafficLights, theme, }: BoxProps): react_jsx_runtime.JSX.Element;
+declare function Box({ header, headerActions, footer, children, className, style, height, minHeight, maxHeight, tiny, resizable, showHeader, tabs, activeTab: controlledActiveTab, onTabChange, defaultTab, showTrafficLights, theme, error, errorRole, }: BoxProps): react_jsx_runtime.JSX.Element;
 
 interface GridProps {
     children: React.ReactNode;
@@ -670,6 +759,13 @@ interface GridProps {
      */
     columns?: number;
     minBoxWidth?: number | string;
+    /**
+     * Fixed box width in px: one row at every container width, scrolled
+     * sideways and snapping to each box. A box never grows past the row, so a
+     * narrow container still shows the edge of the next one. Overrides
+     * `columns` and `minBoxWidth`.
+     */
+    boxWidth?: number;
     gap?: number | string;
     rowHeight?: 'auto' | 'equal' | 'synced' | number;
     maxRowHeight?: number | string | 'none';
@@ -682,7 +778,8 @@ interface GridProps {
  * Provides consistent grid layout for box components with horizontal
  * scrolling when content exceeds available space. Boxes keep a minimum width.
  * By default all boxes share one row; `columns` sets the boxes per row and
- * wraps the rest. Narrow containers stack the boxes.
+ * wraps the rest. Narrow containers stack the boxes. `boxWidth` keeps one
+ * row of fixed-width boxes at every width instead.
  *
  * @example
  * // 5 boxes with default 350px minimum width
@@ -703,6 +800,15 @@ interface GridProps {
  * </Grid>
  *
  * @example
+ * // One row of 350px boxes, scrolled sideways on any screen
+ * <Grid boxWidth={350}>
+ *   <Preview ... />
+ *   <CodeBox ... />
+ *   <CodeBox ... />
+ *   <CodeBox ... />
+ * </Grid>
+ *
+ * @example
  * // Custom row height
  * <Grid columns={2} rowHeight={300}>
  *   <CodeBox ... />
@@ -729,7 +835,7 @@ interface GridProps {
  *   <CodeBox ... />
  * </Grid>
  */
-declare function Grid({ children, columns, minBoxWidth, gap, rowHeight, maxRowHeight, showScrollButtons, className, }: GridProps): react_jsx_runtime.JSX.Element;
+declare function Grid({ children, columns, minBoxWidth, boxWidth, gap, rowHeight, maxRowHeight, showScrollButtons, className, }: GridProps): react_jsx_runtime.JSX.Element;
 
 interface HeaderProps {
     label: string;
@@ -774,6 +880,33 @@ interface ButtonGroupProps {
  */
 declare function ButtonGroup({ buttons, onButtonClick, className, variant, }: ButtonGroupProps): react_jsx_runtime.JSX.Element;
 
+interface ToggleButtonOption {
+    label: string;
+    value: string;
+}
+interface ToggleButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'onChange' | 'onClick' | 'type' | 'value'> {
+    options: ToggleButtonOption[];
+    value: string;
+    onChange: (value: string) => void;
+    /**
+     * Which label the button shows: the option a click switches to (`next`,
+     * the default, so the label names the action) or the selected one
+     * (`current`, so the label names the state).
+     */
+    shows?: 'next' | 'current';
+}
+/**
+ * ToggleButton - one button that switches between options. A click selects
+ * the next option after `value` (after the last, the first). By default it
+ * shows that next option, so its label names the action; with
+ * `shows="current"` it shows the selected one.
+ *
+ * Every label sits in the same grid cell and only one is visible, so the
+ * button always takes the longest label's width and never changes size. An
+ * `aria-label` should contain the shown word ("Show code" for "Code").
+ */
+declare function ToggleButton({ options, value, onChange, shows, className, ...rest }: ToggleButtonProps): react_jsx_runtime.JSX.Element;
+
 /**
  * Detect `@monaco-editor/loader`'s cancelation rejection.
  *
@@ -1072,4 +1205,4 @@ declare function validateWalkerOSReferences(text: string, context: Partial<Intel
  */
 declare function extractFlowIntelliSenseContext(json: string): Partial<IntelliSenseContext>;
 
-export { ArchitectureFlow, type ArchitectureFlowProps, Box, type BoxProps, type BoxTab, BrowserBox, type BrowserBoxProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Code, CodeBox, type CodeBoxProps, type CodeBoxTab, CodeDiff, CodeDiffBox, type CodeDiffBoxProps, type CodeDiffProps, type CodeDiffSummary, type CodeProps, CodeSnippet, type CodeSnippetProps, CodeStatic, type CodeStaticProps, CodeView, type CodeViewProps, type CodeViewTab, type CompletionEntry, ELB_THEME_DARK, type FlowColumn, type FlowItem, FlowMap, type FlowMapProps, type FlowSection, type FlowStageConfig, Grid, type GridProps, Header, type HeaderProps, type IntelliSenseContext, LiveCode, type LiveCodeProps, type LoadPackageTypesOptions, type MonacoSchemaExtension, type PackageInfo, Preview, type PreviewProps, PromotionPlayground, type PromotionPlaygroundProps, PropertyTable, type PropertyTableProps, REFERENCE_PATTERNS, type RefKind, StepExample, type StepExampleProps, allowedRefKinds, applyWalkerOSDecorations, disposeWalkerOSProviders, enrichFlowConfigSchema, enrichSchema, extractFlowIntelliSenseContext, findWalkerOSReferences, generateModelPath, getContractCompletions, getEnrichedContractSchema, getEnvCompletions, getFlowCompletions, getJsonPathAtOffset, getMappingPathCompletions, getSecretCompletions, getStoreCompletions, getVariableCompletions, getVariablesSchema, initializeMonacoTypes, isMonacoCancellation, loadPackageTypes, loadTypeLibraryFromURL, registerJsonSchema, registerTheme, registerWalkerOSDecorationStyles, registerWalkerOSProviders, registerWalkerOSTypes, removeIntelliSenseContext, resolveTypesUrl, setIntelliSenseContext, setPackageTypesBaseUrl, unregisterJsonSchema, validateWalkerOSReferences };
+export { ArchitectureFlow, type ArchitectureFlowProps, Box, type BoxProps, type BoxTab, BrowserBox, type BrowserBoxProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Code, CodeBox, type CodeBoxProps, type CodeBoxTab, CodeDiff, CodeDiffBox, type CodeDiffBoxProps, type CodeDiffProps, type CodeDiffSummary, type CodeProps, CodeSnippet, type CodeSnippetProps, CodeStatic, type CodeStaticProps, CodeView, type CodeViewProps, type CodeViewTab, type CompletionEntry, ELB_THEME_DARK, type FlowColumn, type FlowItem, FlowMap, type FlowMapProps, type FlowSection, type FlowStageConfig, Grid, type GridProps, Header, type HeaderProps, type IntelliSenseContext, LiveCode, type LiveCodeProps, type LoadPackageTypesOptions, type MonacoSchemaExtension, type PackageInfo, Playground, type PlaygroundProps, Preview, type PreviewProps, PromotionPlayground, type PromotionPlaygroundProps, PropertyTable, type PropertyTableProps, REFERENCE_PATTERNS, type RefKind, StepExample, type StepExampleProps, ToggleButton, type ToggleButtonProps, ViewSource, type ViewSourceProps, allowedRefKinds, applyWalkerOSDecorations, disposeWalkerOSProviders, enrichFlowConfigSchema, enrichSchema, extractFlowIntelliSenseContext, findWalkerOSReferences, generateModelPath, getContractCompletions, getEnrichedContractSchema, getEnvCompletions, getFlowCompletions, getJsonPathAtOffset, getMappingPathCompletions, getSecretCompletions, getStoreCompletions, getVariableCompletions, getVariablesSchema, initializeMonacoTypes, isMonacoCancellation, loadPackageTypes, loadTypeLibraryFromURL, registerJsonSchema, registerTheme, registerWalkerOSDecorationStyles, registerWalkerOSProviders, registerWalkerOSTypes, removeIntelliSenseContext, resolveTypesUrl, setIntelliSenseContext, setPackageTypesBaseUrl, unregisterJsonSchema, validateWalkerOSReferences };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Destination, WalkerOS, Flow, Elb } from '@walkeros/core';
-import React, { ReactNode } from 'react';
+import { Destination, WalkerOS, Flow, Collector } from '@walkeros/core';
+import React, { ReactNode, AriaAttributes, ReactElement, ButtonHTMLAttributes } from 'react';
 import * as monaco_editor from 'monaco-editor';
 import { editor } from 'monaco-editor';
 import { RJSFSchema } from '@rjsf/utils';
+import { SourceBrowser } from '@walkeros/web-source-browser';
 import { Monaco } from '@monaco-editor/react';
 export { Monaco } from '@monaco-editor/react';
 export { Icon } from '@iconify/react';
@@ -18,7 +19,6 @@ interface PromotionPlaygroundProps {
     initialCss?: string;
     initialJs?: string;
     initialMapping?: string;
-    labelCode?: string;
     labelPreview?: string;
     labelEvents?: string;
     labelMapping?: string;
@@ -28,19 +28,33 @@ interface PromotionPlaygroundProps {
 /**
  * PromotionPlayground - Full walkerOS demonstration with live code editing
  *
- * Shows the complete chain:
- * 1. Code Editor - Edit HTML/CSS/JS with walkerOS data attributes
- * 2. Preview - Live rendered output that captures real events
- * 3. Events - Real events captured from preview interactions
- * 4. Mapping - Apply transformations and see destination output
- * 5. Result - Final destination function calls
- *
- * Uses a single unified collector flow:
- * - PromotionPlayground owns the collector with destinations
- * - Preview initializes browser source using parent's elb
- * - Events flow through one collector to all destinations
+ * Shows the complete chain, one box each:
+ * 1. Preview - the live page, with HTML/CSS/JS tabs to edit it; captures real events
+ * 2. Events - the events the preview sent
+ * 3. Mapping - editable rules for the destination
+ * 4. Result - the destination call each event becomes
+ *
+ * One collector runs the flow: Preview binds a browser source to it, and its
+ * destinations fill the Events and Result boxes. Whatever fails says so in
+ * the box it concerns.
+ */
+declare function PromotionPlayground({ initialHtml, initialCss, initialJs, initialMapping, labelPreview, labelEvents, labelMapping, labelResult, destination: destinationProp, }: PromotionPlaygroundProps): react_jsx_runtime.JSX.Element;
+
+interface PlaygroundProps {
+    eyebrow?: ReactNode;
+    title?: ReactNode;
+    lead?: ReactNode;
+}
+/**
+ * The walkerOS playground: a tagged component, the event it sends, the
+ * mapping and the vendor call it becomes, live.
+ *
+ * One real flow runs the chain. `startFlow` starts a collector with the
+ * browser source scoped to the preview's shadow root and the gtag destination
+ * with the editor's mapping. The destination's `window` is a stub that hands
+ * each gtag call to the Result panel instead of sending it to GA4.
  */
-declare function PromotionPlayground({ initialHtml, initialCss, initialJs, initialMapping, labelCode, labelPreview, labelEvents, labelMapping, labelResult, destination: destinationProp, }: PromotionPlaygroundProps): react_jsx_runtime.JSX.Element;
+declare function Playground({ eyebrow, title, lead, }: PlaygroundProps): react_jsx_runtime.JSX.Element;
 
 interface LiveCodeProps {
     input: unknown;
@@ -52,6 +66,7 @@ interface LiveCodeProps {
     labelInput?: string;
     labelConfig?: string;
     labelOutput?: string;
+    /** Plain words in the empty Result box, such as why a run returns nothing. */
     emptyText?: string;
     disableInput?: boolean;
     disableConfig?: boolean;
@@ -61,7 +76,7 @@ interface LiveCodeProps {
     format?: boolean;
     rowHeight?: 'auto' | 'equal' | 'synced' | number;
     /** Language for the Result panel. Defaults to json (the typical output
-     * shape). Set to `javascript` when emptyText includes `//` comments. */
+     * shape). */
     outputLanguage?: string;
     /** Language for the Config panel. Defaults to `json`. Override when the
      * Config panel content is not JSON. */
@@ -291,6 +306,12 @@ interface CodeBoxProps extends Omit<CodeProps, 'code'> {
         errors: number;
         warnings: number;
     }) => void;
+    /** Plain words shown over the editor while `code` is empty, such as what fills it. */
+    placeholder?: string;
+    /** What failed for this box, shown above the editor with an icon and the word Error. */
+    error?: string;
+    /** `status` for input validation the reader is typing through; `alert` (default) otherwise. */
+    errorRole?: 'alert' | 'status';
     footer?: React.ReactNode;
     height?: string | number;
     style?: React.CSSProperties;
@@ -335,7 +356,7 @@ interface CodeBoxProps extends Omit<CodeProps, 'code'> {
  *   showFormat
  * />
  */
-declare function CodeBox({ code, language, onChange, disabled, autoHeight, label, header, showHeader, tabs, activeTab: controlledActiveTab, onTabChange, defaultTab, showTrafficLights, showCopy, showFormat, showSettings, onValidationIssues, footer, height, style, className, ...codeProps }: CodeBoxProps): react_jsx_runtime.JSX.Element;
+declare function CodeBox({ code, language, onChange, disabled, autoHeight, label, header, showHeader, tabs, activeTab: controlledActiveTab, onTabChange, defaultTab, showTrafficLights, showCopy, showFormat, showSettings, onValidationIssues, placeholder, error, errorRole, footer, height, style, className, ...codeProps }: CodeBoxProps): react_jsx_runtime.JSX.Element;
 
 interface CodeDiffBoxProps {
     original: string;
@@ -553,7 +574,16 @@ interface PreviewProps {
     html?: string;
     css?: string;
     js?: string;
-    elb?: Elb.Fn;
+    /**
+     * The collector that captures the preview's events. Preview binds a browser
+     * source to its document through the collector's own source wiring, so
+     * every click and load event runs the collector's pipeline. Without it the
+     * preview only renders. The source is the preview's own, not one of the
+     * collector's `sources`: `walker consent` and `walker user` do not reach
+     * it, and the collector's status does not list it.
+     */
+    collector?: Collector.Instance;
+    /** The box's name; with `editable`, the name of its first tab. */
     label?: string;
     /**
      * Opt-in editor tabs. When true, the header shows a `tabs` ButtonGroup to
@@ -574,8 +604,8 @@ interface PreviewProps {
  * Preview - HTML preview wrapped in a Box with highlight buttons
  *
  * Renders HTML in an isolated iframe with highlight buttons footer.
- * When elb is provided, initializes walkerOS browser source in iframe
- * that pushes events to the parent collector.
+ * With a collector, a walkerOS browser source captures the iframe's events
+ * into it; a source that fails to start says so in the box.
  *
  * Load semantics mirror a real browser: `load` triggers (and pageview) fire
  * once on the initial load and again only when the user clicks Reload. Editing
@@ -586,10 +616,62 @@ interface PreviewProps {
  * // Read-only preview
  * <Preview html={html} css={css} label="Preview" />
  *
- * // Interactive preview with event capture (elb from parent collector)
- * <Preview html={html} css={css} elb={elb} label="Preview" />
+ * // Interactive preview that captures events into a collector
+ * <Preview html={html} css={css} collector={collector} label="Preview" />
+ */
+declare function Preview({ html, css, js, collector, label, editable, initialTab, onHtmlChange, onCssChange, onJsChange, lineNumbers, wordWrap, }: PreviewProps): react_jsx_runtime.JSX.Element;
+
+interface ViewSourceProps extends AriaAttributes {
+    /** Exactly one element: the component whose HTML is shown. */
+    children: ReactElement;
+    /**
+     * The page's elb (the browser source's push). After an edit is applied, and
+     * after Reset brings the original back, ViewSource calls
+     * `elb('walker init', element)` so the new nodes get their triggers.
+     */
+    elb?: SourceBrowser.Push;
+    /**
+     * Lets the wrapped element fill a stretched grid or flex cell as it does
+     * unwrapped (cards in a grid row). The root and its content become
+     * one-column grids: an auto-height element fills the cell, its margins,
+     * own self-alignment and explicit height still apply, and its vertical
+     * margins stay inside the wrapper. Leave it off for an element centered
+     * with auto margins (a section with `mx-auto`), which a grid shrinks to
+     * fit.
+     */
+    stretch?: boolean;
+    className?: string;
+    id?: string;
+    [dataAttribute: `data-${string}`]: string | undefined;
+}
+/**
+ * ViewSource - shows a component's live HTML in place and lets you edit it.
+ *
+ * Wraps exactly one element and adds no frame of its own. A toggle at the
+ * top right switches between Visual and Code. Code shows the element's live
+ * HTML, formatted and editable, on a dark code surface; the code covers the
+ * element's visible box (its border box when it paints a background or
+ * border, else its content box inside the padding), and the toggle sits at
+ * that box's top right. Escape leaves the editor for the toggle.
+ * Back in Visual, a changed edit replaces the element as plain HTML (React
+ * handlers inside it are inactive) and `elb('walker init', element)`
+ * registers its triggers. Reset, an icon beside the toggle, mounts the
+ * original children again and registers theirs the same way.
+ *
+ * ViewSources nest: an outer snapshot shows the inner wrapped elements
+ * without their wrappers, and only the innermost hovered toolbar shows. An
+ * applied outer edit is plain HTML, so it has no inner wrappers until Reset.
+ *
+ * Wrap the outermost tagged element of a section, never an element inside one
+ * with a click action: a click on the toolbar bubbles to the wrapper's
+ * ancestors.
+ *
+ * @example
+ * <ViewSource elb={elb}>
+ *   <PromotionHero />
+ * </ViewSource>
  */
-declare function Preview({ html, css, js, elb, label, editable, initialTab, onHtmlChange, onCssChange, onJsChange, lineNumbers, wordWrap, }: PreviewProps): react_jsx_runtime.JSX.Element;
+declare function ViewSource({ children, elb, stretch, className, ...rest }: ViewSourceProps): react_jsx_runtime.JSX.Element;
 
 interface CodeDiffSummary {
     /** Count of hunks that exist only in modified (pure additions). */
@@ -659,8 +741,15 @@ interface BoxProps {
     showTrafficLights?: boolean;
     /** Pins the box to one theme, whatever the page theme (a dark island). */
     theme?: Theme;
+    /** What failed in this box, shown above its content with an icon and the word Error. */
+    error?: string;
+    /**
+     * How the error is announced: `alert` (default) interrupts, for a failure;
+     * `status` waits, for input validation that changes as the reader types.
+     */
+    errorRole?: 'alert' | 'status';
 }
-declare function Box({ header, headerActions, footer, children, className, style, height, minHeight, maxHeight, tiny, resizable, showHeader, tabs, activeTab: controlledActiveTab, onTabChange, defaultTab, showTrafficLights, theme, }: BoxProps): react_jsx_runtime.JSX.Element;
+declare function Box({ header, headerActions, footer, children, className, style, height, minHeight, maxHeight, tiny, resizable, showHeader, tabs, activeTab: controlledActiveTab, onTabChange, defaultTab, showTrafficLights, theme, error, errorRole, }: BoxProps): react_jsx_runtime.JSX.Element;
 
 interface GridProps {
     children: React.ReactNode;
@@ -670,6 +759,13 @@ interface GridProps {
      */
     columns?: number;
     minBoxWidth?: number | string;
+    /**
+     * Fixed box width in px: one row at every container width, scrolled
+     * sideways and snapping to each box. A box never grows past the row, so a
+     * narrow container still shows the edge of the next one. Overrides
+     * `columns` and `minBoxWidth`.
+     */
+    boxWidth?: number;
     gap?: number | string;
     rowHeight?: 'auto' | 'equal' | 'synced' | number;
     maxRowHeight?: number | string | 'none';
@@ -682,7 +778,8 @@ interface GridProps {
  * Provides consistent grid layout for box components with horizontal
  * scrolling when content exceeds available space. Boxes keep a minimum width.
  * By default all boxes share one row; `columns` sets the boxes per row and
- * wraps the rest. Narrow containers stack the boxes.
+ * wraps the rest. Narrow containers stack the boxes. `boxWidth` keeps one
+ * row of fixed-width boxes at every width instead.
  *
  * @example
  * // 5 boxes with default 350px minimum width
@@ -703,6 +800,15 @@ interface GridProps {
  * </Grid>
  *
  * @example
+ * // One row of 350px boxes, scrolled sideways on any screen
+ * <Grid boxWidth={350}>
+ *   <Preview ... />
+ *   <CodeBox ... />
+ *   <CodeBox ... />
+ *   <CodeBox ... />
+ * </Grid>
+ *
+ * @example
  * // Custom row height
  * <Grid columns={2} rowHeight={300}>
  *   <CodeBox ... />
@@ -729,7 +835,7 @@ interface GridProps {
  *   <CodeBox ... />
  * </Grid>
  */
-declare function Grid({ children, columns, minBoxWidth, gap, rowHeight, maxRowHeight, showScrollButtons, className, }: GridProps): react_jsx_runtime.JSX.Element;
+declare function Grid({ children, columns, minBoxWidth, boxWidth, gap, rowHeight, maxRowHeight, showScrollButtons, className, }: GridProps): react_jsx_runtime.JSX.Element;
 
 interface HeaderProps {
     label: string;
@@ -774,6 +880,33 @@ interface ButtonGroupProps {
  */
 declare function ButtonGroup({ buttons, onButtonClick, className, variant, }: ButtonGroupProps): react_jsx_runtime.JSX.Element;
 
+interface ToggleButtonOption {
+    label: string;
+    value: string;
+}
+interface ToggleButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'onChange' | 'onClick' | 'type' | 'value'> {
+    options: ToggleButtonOption[];
+    value: string;
+    onChange: (value: string) => void;
+    /**
+     * Which label the button shows: the option a click switches to (`next`,
+     * the default, so the label names the action) or the selected one
+     * (`current`, so the label names the state).
+     */
+    shows?: 'next' | 'current';
+}
+/**
+ * ToggleButton - one button that switches between options. A click selects
+ * the next option after `value` (after the last, the first). By default it
+ * shows that next option, so its label names the action; with
+ * `shows="current"` it shows the selected one.
+ *
+ * Every label sits in the same grid cell and only one is visible, so the
+ * button always takes the longest label's width and never changes size. An
+ * `aria-label` should contain the shown word ("Show code" for "Code").
+ */
+declare function ToggleButton({ options, value, onChange, shows, className, ...rest }: ToggleButtonProps): react_jsx_runtime.JSX.Element;
+
 /**
  * Detect `@monaco-editor/loader`'s cancelation rejection.
  *
@@ -1072,4 +1205,4 @@ declare function validateWalkerOSReferences(text: string, context: Partial<Intel
  */
 declare function extractFlowIntelliSenseContext(json: string): Partial<IntelliSenseContext>;
 
-export { ArchitectureFlow, type ArchitectureFlowProps, Box, type BoxProps, type BoxTab, BrowserBox, type BrowserBoxProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Code, CodeBox, type CodeBoxProps, type CodeBoxTab, CodeDiff, CodeDiffBox, type CodeDiffBoxProps, type CodeDiffProps, type CodeDiffSummary, type CodeProps, CodeSnippet, type CodeSnippetProps, CodeStatic, type CodeStaticProps, CodeView, type CodeViewProps, type CodeViewTab, type CompletionEntry, ELB_THEME_DARK, type FlowColumn, type FlowItem, FlowMap, type FlowMapProps, type FlowSection, type FlowStageConfig, Grid, type GridProps, Header, type HeaderProps, type IntelliSenseContext, LiveCode, type LiveCodeProps, type LoadPackageTypesOptions, type MonacoSchemaExtension, type PackageInfo, Preview, type PreviewProps, PromotionPlayground, type PromotionPlaygroundProps, PropertyTable, type PropertyTableProps, REFERENCE_PATTERNS, type RefKind, StepExample, type StepExampleProps, allowedRefKinds, applyWalkerOSDecorations, disposeWalkerOSProviders, enrichFlowConfigSchema, enrichSchema, extractFlowIntelliSenseContext, findWalkerOSReferences, generateModelPath, getContractCompletions, getEnrichedContractSchema, getEnvCompletions, getFlowCompletions, getJsonPathAtOffset, getMappingPathCompletions, getSecretCompletions, getStoreCompletions, getVariableCompletions, getVariablesSchema, initializeMonacoTypes, isMonacoCancellation, loadPackageTypes, loadTypeLibraryFromURL, registerJsonSchema, registerTheme, registerWalkerOSDecorationStyles, registerWalkerOSProviders, registerWalkerOSTypes, removeIntelliSenseContext, resolveTypesUrl, setIntelliSenseContext, setPackageTypesBaseUrl, unregisterJsonSchema, validateWalkerOSReferences };
+export { ArchitectureFlow, type ArchitectureFlowProps, Box, type BoxProps, type BoxTab, BrowserBox, type BrowserBoxProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, Code, CodeBox, type CodeBoxProps, type CodeBoxTab, CodeDiff, CodeDiffBox, type CodeDiffBoxProps, type CodeDiffProps, type CodeDiffSummary, type CodeProps, CodeSnippet, type CodeSnippetProps, CodeStatic, type CodeStaticProps, CodeView, type CodeViewProps, type CodeViewTab, type CompletionEntry, ELB_THEME_DARK, type FlowColumn, type FlowItem, FlowMap, type FlowMapProps, type FlowSection, type FlowStageConfig, Grid, type GridProps, Header, type HeaderProps, type IntelliSenseContext, LiveCode, type LiveCodeProps, type LoadPackageTypesOptions, type MonacoSchemaExtension, type PackageInfo, Playground, type PlaygroundProps, Preview, type PreviewProps, PromotionPlayground, type PromotionPlaygroundProps, PropertyTable, type PropertyTableProps, REFERENCE_PATTERNS, type RefKind, StepExample, type StepExampleProps, ToggleButton, type ToggleButtonProps, ViewSource, type ViewSourceProps, allowedRefKinds, applyWalkerOSDecorations, disposeWalkerOSProviders, enrichFlowConfigSchema, enrichSchema, extractFlowIntelliSenseContext, findWalkerOSReferences, generateModelPath, getContractCompletions, getEnrichedContractSchema, getEnvCompletions, getFlowCompletions, getJsonPathAtOffset, getMappingPathCompletions, getSecretCompletions, getStoreCompletions, getVariableCompletions, getVariablesSchema, initializeMonacoTypes, isMonacoCancellation, loadPackageTypes, loadTypeLibraryFromURL, registerJsonSchema, registerTheme, registerWalkerOSDecorationStyles, registerWalkerOSProviders, registerWalkerOSTypes, removeIntelliSenseContext, resolveTypesUrl, setIntelliSenseContext, setPackageTypesBaseUrl, unregisterJsonSchema, validateWalkerOSReferences };