@walkeros/explorer 4.2.0-next-1780942291149 → 4.2.0

package/CHANGELOG.md

@@ -1,6 +1,16 @@
 # @walkeros/explorer
 
-## 4.2.0-next-1780942291149
+## 4.2.0
+
+### Minor Changes
+
+- 560d8af: Add a unified tag visualization: the `Tag` atom plus `TagCanvas` and
+  `TagTreeEditor`. It renders walkerOS data-elb tagging as nested rectangles
+  (entity, context, global, action, property) with an auto-laid-out reading view
+  and an overlay you can draw onto a screenshot. The overlay editor supports
+  dragging and resizing rectangles, keeping every tag fully nested or fully
+  separate. The existing `TagSkeleton` and `TagSkeletonOverlay` continue to
+  work.
 
 ### Patch Changes
 
@@ -8,9 +18,13 @@
   update repaints only the error and warning badges instead of re-rendering the
   whole editor. This removes the visible editor flicker when content or markers
   change rapidly.
+- 560d8af: The built bundle now preserves its leading `"use client"` directive,
+  so Next.js treats the package as a client boundary. The minifier could
+  previously strip it, which broke server components that import the package at
+  build time.
 - Updated dependencies [76d32c1]
-- Updated dependencies [18c9469]
-- Updated dependencies [18c9469]
+- Updated dependencies [5b1a134]
+- Updated dependencies [5b1a134]
 - Updated dependencies [908d6f0]
 - Updated dependencies [654ba38]
 - Updated dependencies [c27d3c1]
@@ -26,13 +40,13 @@
 - Updated dependencies [21ac669]
 - Updated dependencies [6a72a32]
 - Updated dependencies [3eb2467]
-- Updated dependencies [7d8ebf9]
-- Updated dependencies [f1c74e8]
+- Updated dependencies [5b1a134]
+- Updated dependencies [23d4b86]
 - Updated dependencies [18c9469]
-  - @walkeros/core@4.2.0-next-1780942291149
-  - @walkeros/collector@4.2.0-next-1780942291149
-  - @walkeros/web-source-browser@4.2.0-next-1780942291149
-  - @walkeros/web-core@4.2.0-next-1780942291149
+  - @walkeros/core@4.2.0
+  - @walkeros/collector@4.2.0
+  - @walkeros/web-source-browser@4.2.0
+  - @walkeros/web-core@4.2.0
 
 ## 4.1.2
 

package/dist/index.d.cts

@@ -1,6 +1,6 @@
+import React, { ReactNode, FC, PropsWithChildren, RefObject } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Destination, WalkerOS, Elb } from '@walkeros/core';
-import React, { ReactNode, FC, PropsWithChildren, RefObject } from 'react';
 import * as monaco_editor from 'monaco-editor';
 import { editor } from 'monaco-editor';
 import { RJSFSchema } from '@rjsf/utils';
@@ -9,6 +9,93 @@ export { Monaco } from '@monaco-editor/react';
 export { Icon } from '@iconify/react';
 import { ClassValue } from 'clsx';
 
+/**
+ * Shared model for the unified tag visualization. One recursive `Tag` atom
+ * (like a DOM element) drives both auto-layout skeletons and overlay editors.
+ * Later building blocks (renderers, overlay editor) consume these types.
+ */
+/** The kind of a tag. Drives color and layout role. */
+type TagType = 'global' | 'context' | 'entity' | 'action' | 'property';
+/** Position and size in the tree's coordinate space. */
+interface TagRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * A single tag node. Recursive: a tag may nest children, mirroring how a
+ * tagged DOM element wraps its descendants.
+ */
+interface Tag$3 {
+    /** Required, stable id: drives selection, diffing, React keys, drag identity. */
+    id: string;
+    type: TagType;
+    /** Tab label. */
+    name: string;
+    /** Resolved value; absent means shape-only (the data is not decided yet). */
+    value?: string;
+    /** Optional freeform caption. */
+    label?: string;
+    /** Present => explicit/overlay position; absent => auto-computed by layout. */
+    rect?: TagRect;
+    /** For type 'context': depth rank where the closest context is 0. */
+    contextIndex?: number;
+    children?: Tag$3[];
+}
+/**
+ * A full tag tree. The coordinate space is grid units for auto layout, or
+ * image-natural pixels when overlaying a screenshot.
+ */
+interface TagTree {
+    width: number;
+    height: number;
+    /** Optional background screenshot, used in overlay mode. */
+    src?: string;
+    roots: Tag$3[];
+}
+/**
+ * Build a stable tag id from a seed and an index, e.g. `product-0`. Pure: no
+ * randomness, no clock. Use during tree construction to give every tag a
+ * deterministic identity.
+ */
+declare function makeTagId(seed: string, index: number): string;
+
+interface TagProps {
+    type: TagType;
+    /** Tab label: the tag's own identifier (entity / context key / global key /
+     * action verb / property key). Never the type word; color conveys the type. */
+    name: string;
+    /** Resolved value; absent means shape-only. */
+    value?: string;
+    /** Optional freeform caption shown centered in the body. */
+    label?: string;
+    /** For type 'context': depth rank (closest = 0). Retained on the model but not
+     * rendered: the tab carries only the identifier. */
+    contextIndex?: number;
+    /** When false the straddle tab is hidden (hover-caption mode); the box and
+     * value still render so geometry never changes. Defaults to true. */
+    showCaption?: boolean;
+    /** Positioning supplied by the layout layer (e.g. overlay coordinates). */
+    style?: React.CSSProperties;
+    className?: string;
+    selected?: boolean;
+    dragging?: boolean;
+    /** When true the header is filled (active). Driven by the hovered containing
+     * chain so the whole related path (e.g. entity + its action) highlights
+     * together, not just the box under the pointer. */
+    highlighted?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * The unified visual atom: one rectangle with a straddling pill-tab header and a
+ * centered body, like a tagged DOM element. The `type` drives color only; the
+ * layout layer supplies `style` and/or nested `children`. Appearance only and
+ * pure: it knows nothing about where it sits or how big it is. All styling is
+ * theme-variable driven via the `.elb-tag-skeleton` BEM block.
+ */
+declare function Tag$2({ type, name, value, label, showCaption, style, className, selected, dragging, highlighted, children, }: TagProps): React.ReactElement;
+
 interface DemoEnv extends Destination.BaseEnv {
     elb: (output: string) => void;
 }
@@ -544,6 +631,277 @@ interface PropertyTableProps {
 }
 declare function PropertyTable({ schema, className, emptyMessage, }: PropertyTableProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * A single key/value detail on a box: a property, a context entry, or a global.
+ * `value` is optional so a skeleton can show the shape ("price") before the
+ * data is decided ("price: 29.99").
+ */
+interface TagSkeletonDetail {
+    key: string;
+    value?: string;
+}
+/** Every container is the same box; the kind only drives color. */
+type BoxKind = 'entity' | 'context' | 'globals';
+
+/**
+ * One tagged entity, rendered as a rectangle. Mirrors walkerOS data-elb
+ * tagging: `entity` is the `data-elb` name, `properties` are the
+ * `data-elb-<entity>` values, `actions` are the `data-elbaction` triggers,
+ * `context` is the `data-elbcontext` scope wrapping this box, and `children`
+ * are nested `data-elb` entities drawn as boxes inside this one.
+ */
+interface TagSkeletonNode {
+    /**
+     * Stable identity. Optional today (falls back to a path-based key); the
+     * overlay editor uses it to select and diff boxes while dragging.
+     */
+    id?: string;
+    entity: string;
+    /** Optional freeform caption, centered inside the box. */
+    label?: string;
+    properties?: TagSkeletonDetail[];
+    /** Trigger:action pairs, e.g. "click:add", "load:view". */
+    actions?: string[];
+    /** data-elbcontext entries wrapping this box. */
+    context?: TagSkeletonDetail[];
+    children?: TagSkeletonNode[];
+}
+interface TagSkeletonProps {
+    /** Root entities. Each renders as a top-level rectangle. */
+    nodes: TagSkeletonNode[];
+    /** data-elbglobals — page-wide scope drawn as the outermost box. */
+    globals?: TagSkeletonDetail[];
+    className?: string;
+}
+/**
+ * Renders a walkerOS tagging skeleton: nested rectangles built from data-elb
+ * semantics (auto layout, content-driven, document nesting). Purely
+ * presentational. Superseded by `TagCanvas`; kept as a thin back-compat wrapper
+ * that adapts `{nodes, globals}` into a `TagTree`. For drawing rectangles onto a
+ * screenshot, see `TagSkeletonOverlay`. All styling lives in theme CSS
+ * variables.
+ */
+declare function TagSkeleton({ nodes, globals, className, }: TagSkeletonProps): React.ReactElement;
+
+/** A rectangle in the grid's coordinate space (image pixels). */
+interface TagOverlayRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One rectangle drawn onto the screenshot. Positioning is flat: every box
+ * anchors to the frame, not to a parent. `kind` only drives color. */
+interface TagOverlayBox {
+    id?: string;
+    /** Defaults to "entity". */
+    kind?: BoxKind;
+    /** Tab label. */
+    name: string;
+    rect: TagOverlayRect;
+    label?: string;
+    actions?: string[];
+    properties?: TagSkeletonDetail[];
+}
+/**
+ * The grid: its own coordinate space (match the screenshot's dimensions) plus
+ * the boxes placed within it. Rects are authored in these units; the frame
+ * renders them as percentages, so any display `size` stays aligned.
+ */
+interface TagGrid {
+    width: number;
+    height: number;
+    boxes: TagOverlayBox[];
+}
+interface TagSkeletonOverlayProps {
+    /** Background screenshot. */
+    src: string;
+    grid: TagGrid;
+    /** Display width of the frame. Number = pixels; string = any CSS width.
+     * Image and grid scale together. Defaults to "100%". */
+    size?: number | string;
+    alt?: string;
+    className?: string;
+}
+/**
+ * Draws a tagging skeleton onto a screenshot. One relative anchor frame sized
+ * to `src`; every box is positioned absolutely as a percentage of that frame,
+ * so changing `size` scales image and grid together. Superseded by `TagCanvas`;
+ * kept as a thin back-compat wrapper that adapts `{src, grid}` into a `TagTree`
+ * with explicit rects. Positioning is flat (logical nesting drives color, not
+ * position). Purely presentational; drag/resize is a separate controlled editor
+ * on top. All styling lives in theme CSS variables.
+ */
+declare function TagSkeletonOverlay({ src, grid, size, alt, className, }: TagSkeletonOverlayProps): React.ReactElement;
+
+interface TagCanvasProps {
+    /** The tag tree to render. Rects are honored verbatim; missing rects are
+     * auto-computed by `layout()`. */
+    tree: TagTree;
+    /** Display width of the anchor frame. Number = pixels; string = any CSS
+     * width. Image and grid scale together. Defaults to "100%". */
+    size?: number | string;
+    /** Alt text for the optional background screenshot. */
+    alt?: string;
+    className?: string;
+    /** Id of the selected tag, if any. */
+    selectedId?: string;
+    /** Id of the tag currently being dragged, if any. */
+    draggingId?: string;
+    /**
+     * Tab visibility. `'always'` (default) shows every straddle tab. `'hover'`
+     * hides all tabs and reveals only the laminar containing chain under the
+     * pointer, so the structure is read on demand without permanent chrome.
+     */
+    captions?: 'always' | 'hover';
+}
+/**
+ * The pure renderer that draws a `TagTree`. It runs `layout()` to resolve every
+ * tag to an absolute rect (auto for reading mode, verbatim for overlays), then
+ * draws one relative anchor frame and positions each `Tag` absolutely as a
+ * percentage of that frame. So changing `size` scales image and grid together.
+ *
+ * When `tree.src` is set the frame shows the screenshot and boxes use the
+ * transparent overlay fill. Purely presentational; drag/resize is a separate
+ * controlled editor on top. All styling lives in theme CSS variables.
+ *
+ * With `captions="hover"` the tabs are hidden until the pointer enters a box;
+ * the revealed set is the laminar containing chain at the pointer (every node
+ * whose rect contains it), computed with an O(n) point-in-rect test per move.
+ */
+declare function TagCanvas({ tree, size, alt, className, selectedId, draggingId, captions, }: TagCanvasProps): React.ReactElement;
+
+interface TagTreeEditorProps {
+    /** The model tree (controlled). The editor never holds model state. */
+    tree: TagTree;
+    /** Called with a new tree on every commit (move/resize/keyboard). */
+    onChange: (tree: TagTree) => void;
+    /** Display width of the anchor frame. Number = px; string = any CSS width. */
+    size?: number | string;
+    className?: string;
+    /** Hysteresis margin in grid units for re-parent arming. */
+    hysteresis?: number;
+    /** Tab visibility forwarded to the inner canvas. Defaults to 'always'. */
+    captions?: 'always' | 'hover';
+}
+/**
+ * Controlled drag/resize editor for a `TagTree`. Owns no model state: it renders
+ * the prop `tree` through `TagCanvas`, holds only transient interaction state in
+ * the pure reducer, and emits a new tree via `onChange` on every commit. Pointer
+ * pixels are converted to the tree's grid-unit space via one measured `scale`
+ * (frame rendered width / tree.width) tracked with a ResizeObserver. Appearance
+ * lives in the atom/SCSS; this component is interaction-only.
+ */
+declare function TagTreeEditor({ tree, onChange, size, className, hysteresis, captions, }: TagTreeEditorProps): React.ReactElement;
+
+/**
+ * Pure auto-layout for a `TagTree`. Turns a recursive tag tree into a flat list
+ * of absolutely positioned rectangles in the tree's grid-unit coordinate space.
+ *
+ * Laminar by construction: any two emitted rects are fully nested or fully
+ * disjoint, never partially overlapping. Geometry mirrors hierarchy (a property
+ * inside an entity is drawn inside it), exactly like DOM nesting.
+ *
+ * Pure: no React, no DOM, no randomness, no clock. Given the same tree and
+ * options it always returns the same result.
+ */
+
+/** One tag with its resolved absolute position and tree placement. */
+interface PositionedTag {
+    tag: Tag$3;
+    rect: TagRect;
+    depth: number;
+    parentId: string | null;
+}
+/** Flattened layout. `nodes` are ordered parents-before-children (paint order). */
+interface LayoutResult {
+    width: number;
+    height: number;
+    nodes: PositionedTag[];
+}
+/** Tunable geometry, all in grid units. */
+interface LayoutOptions {
+    /** Uniform inner padding inside every container. */
+    pad: number;
+    /** Extra top space reserved for a container's straddling tab. */
+    gutter: number;
+    /** Spacing between siblings (rows, leaves, stacked containers). */
+    gap: number;
+    /** Default leaf width before any name-based growth. */
+    leafW: number;
+    /** Leaf height. */
+    leafH: number;
+    /** Minimum width a container may collapse to. */
+    minContainerW: number;
+    /** Minimum height a container may collapse to. */
+    minContainerH: number;
+}
+/**
+ * Lay out a tag tree.
+ *
+ * Per node: an explicit `tag.rect` is honored verbatim; otherwise the rect is
+ * computed (bottom-up measure, top-down place). A tree may freely mix both.
+ *
+ * Roots stack vertically from the origin. The returned canvas size follows one
+ * rule: if the tree carries a `src` (overlay mode) or any root has an explicit
+ * rect, the tree's own `width`/`height` are honored as the canvas (so authored
+ * coordinates stay aligned to the screenshot). Otherwise the canvas is the
+ * computed bounding box of all roots, never smaller than the tree's declared
+ * size.
+ */
+declare function layout(tree: TagTree, opts?: Partial<LayoutOptions>): LayoutResult;
+
+/**
+ * Pure containment rule for the overlay editor. Given a proposed rect and its
+ * geometric context (parent content box, canvas, same-parent siblings, this
+ * node's own children bounding box, and a minimum size), `clampRect` returns a
+ * laminar-valid rect: large enough to hold its children, fully inside its
+ * container, and disjoint from every sibling. When no such position exists it
+ * returns the caller-supplied `fallback` (the pre-drag rect), so the editor can
+ * snap back rather than emit a non-laminar tree.
+ *
+ * Pure: no React, no DOM, no randomness, no clock. Same inputs => same output.
+ */
+
+interface ClampContext {
+    /** Parent's CONTENT box (null = the node sits directly on the canvas root). */
+    parentContent: TagRect | null;
+    /** The full canvas bounds. */
+    canvas: TagRect;
+    /** Resolved rects of same-parent siblings, excluding self. */
+    siblings: TagRect[];
+    /** Union of this node's own children rects, or null when it has none. */
+    childrenBBox: TagRect | null;
+    /** Minimum allowed size for the rect. */
+    min: {
+        w: number;
+        h: number;
+    };
+}
+declare function clampRect(proposed: TagRect, ctx: ClampContext, fallback: TagRect): TagRect;
+
+/**
+ * Map resolved walker events + globals into a {@link TagTree}.
+ *
+ * Reading mode: no rects are set (width/height 0) so {@link TagCanvas} runs
+ * `layout()` to auto-place boxes.
+ *
+ * Dedupe choices:
+ * - Entities are grouped by entity name PLUS a stable signature of their
+ *   resolved `data` (see {@link dataSignature}). Same entity on multiple
+ *   triggers collapses to one Tag; two genuinely different instances (same
+ *   name, different data) stay separate.
+ * - Actions within a group dedupe on the exact action+trigger pair.
+ *
+ * Page-skip: `getEvents` injects a synthetic `page` entity when an action
+ * resolves to no `data-elb` entity. That is not a real tagged entity, so we
+ * drop any event whose `entity` is `page`.
+ */
+declare function scopeToTagTree(scope: Element | Document): TagTree;
+
+declare const Tag$1: typeof Tag$2;
+type Tag$1 = Tag$3;
+
 interface DropdownProps {
     /** Trigger element (button, link, etc.) */
     trigger: React.ReactNode;
@@ -1434,4 +1792,7 @@ 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, ButtonLink, type ButtonLinkProps, 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, CollectorBox, type CollectorBoxProps, type CompletionEntry, DEFAULT_FALLBACK_HTML, Dropdown, DropdownDivider, type DropdownDividerProps, DropdownItem, type DropdownItemProps, type DropdownProps, type ExplorerTheme, type FlowColumn, type FlowItem, FlowMap, type FlowMapProps, type FlowSection, type FlowStageConfig, Footer, type FooterProps, Grid, type GridProps, Header, type HeaderProps, type IntelliSenseContext, LiveCode, type LiveCodeProps, type LoadPackageTypesOptions, MDXCode, MDXProvider, type MonacoSchemaExtension, type PackageInfo, Preview, type PreviewProps, PromotionPlayground, type PromotionPlaygroundProps, PropertyTable, type PropertyTableProps, REFERENCE_PATTERNS, type RefKind, Spinner, type SpinnerProps, type UseDropdownReturn, allowedRefKinds, applyWalkerOSDecorations, cn, createFbqDestination, createGtagDestination, createPlausibleDestination, disposeWalkerOSProviders, enrichFlowConfigSchema, enrichSchema, extractFlowIntelliSenseContext, findWalkerOSReferences, generateModelPath, getContractCompletions, getEnrichedContractSchema, getEnvCompletions, getFlowCompletions, getJsonPathAtOffset, getMappingPathCompletions, getSecretCompletions, getStoreCompletions, getVariableCompletions, getVariablesSchema, initializeMonacoTypes, isMonacoCancellation, lighthouseTheme, loadPackageTypes, loadTypeLibraryFromURL, palenightTheme, registerAllThemes, registerJsonSchema, registerLighthouseTheme, registerPalenightTheme, registerWalkerOSDecorationStyles, registerWalkerOSProviders, registerWalkerOSTypes, removeIntelliSenseContext, resolveTypesUrl, setIntelliSenseContext, setPackageTypesBaseUrl, unregisterJsonSchema, useDropdown, validateWalkerOSReferences };
+declare const Tag: typeof Tag$2;
+type Tag = Tag$1;
+
+export { ArchitectureFlow, type ArchitectureFlowProps, Box, type BoxProps, type BoxTab, BrowserBox, type BrowserBoxProps, Button, ButtonGroup, type ButtonGroupProps, ButtonLink, type ButtonLinkProps, 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, CollectorBox, type CollectorBoxProps, type CompletionEntry, DEFAULT_FALLBACK_HTML, Dropdown, DropdownDivider, type DropdownDividerProps, DropdownItem, type DropdownItemProps, type DropdownProps, type ExplorerTheme, type FlowColumn, type FlowItem, FlowMap, type FlowMapProps, type FlowSection, type FlowStageConfig, Footer, type FooterProps, Grid, type GridProps, Header, type HeaderProps, type IntelliSenseContext, type LayoutOptions, type LayoutResult, LiveCode, type LiveCodeProps, type LoadPackageTypesOptions, MDXCode, MDXProvider, type MonacoSchemaExtension, type PackageInfo, type PositionedTag, Preview, type PreviewProps, PromotionPlayground, type PromotionPlaygroundProps, PropertyTable, type PropertyTableProps, REFERENCE_PATTERNS, type RefKind, Spinner, type SpinnerProps, Tag, TagCanvas, type TagCanvasProps, type TagGrid, type TagOverlayBox, type TagOverlayRect, type TagProps, type TagRect, TagSkeleton, type TagSkeletonDetail, type TagSkeletonNode, TagSkeletonOverlay, type TagSkeletonOverlayProps, type TagSkeletonProps, type TagTree, TagTreeEditor, type TagTreeEditorProps, type TagType, type UseDropdownReturn, allowedRefKinds, applyWalkerOSDecorations, clampRect, cn, createFbqDestination, createGtagDestination, createPlausibleDestination, disposeWalkerOSProviders, enrichFlowConfigSchema, enrichSchema, extractFlowIntelliSenseContext, findWalkerOSReferences, generateModelPath, getContractCompletions, getEnrichedContractSchema, getEnvCompletions, getFlowCompletions, getJsonPathAtOffset, getMappingPathCompletions, getSecretCompletions, getStoreCompletions, getVariableCompletions, getVariablesSchema, initializeMonacoTypes, isMonacoCancellation, layout, lighthouseTheme, loadPackageTypes, loadTypeLibraryFromURL, makeTagId, palenightTheme, registerAllThemes, registerJsonSchema, registerLighthouseTheme, registerPalenightTheme, registerWalkerOSDecorationStyles, registerWalkerOSProviders, registerWalkerOSTypes, removeIntelliSenseContext, resolveTypesUrl, scopeToTagTree, setIntelliSenseContext, setPackageTypesBaseUrl, unregisterJsonSchema, useDropdown, validateWalkerOSReferences };