anentrypoint-design 0.0.381 → 0.0.382

package/src/components/editor-primitives/batch.js

@@ -0,0 +1,60 @@
+// ---------------------------------------------------------------------------
+// BatchProgressLabel — sequential batch-operation progress readout: "label
+// (i/n)" while in flight. Ported from docstudio's sequential upload badge
+// and bulk-action progress button (both show a live count against a total
+// while processing one item at a time). Pure display — the host owns the
+// actual queue/loop; this only renders its current {done, total} state.
+// done === 0 renders the bare label with no count suffix (nothing has
+// happened yet); done === total renders as complete with no live-region
+// churn once settled.
+// ---------------------------------------------------------------------------
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+const h = webjsx.createElement;
+
+export function BatchProgressLabel({ label = 'Processing', done = 0, total = 0, key } = {}) {
+    const inFlight = total > 0 && done < total;
+    const suffix = total > 0 ? ` (${done}/${total})` : '';
+    return h('span', { key, class: 'ds-ep-batchprogress', role: 'status', 'aria-live': inFlight ? 'polite' : 'off' },
+        label + suffix);
+}
+
+// formatBatchOutcome — pure string helper for the aggregate toast shown once
+// a batch settles: "N/total succeeded" plus a truncated failed-name list
+// when any items failed, matching docstudio's attach-bar/bulk-action
+// aggregation copy. Handles all three outcome shapes (all-succeed, all-fail,
+// partial) and truncates a long failed-name list ("...and N more") instead
+// of growing the toast unboundedly for a big batch.
+export function formatBatchOutcome({ succeeded = 0, total = 0, failedNames = [], maxNames = 3 } = {}) {
+    if (total === 0) return '';
+    if (failedNames.length === 0) return `${succeeded}/${total} succeeded`;
+    const shown = failedNames.slice(0, maxNames).join(', ');
+    const more = failedNames.length > maxNames ? ` and ${failedNames.length - maxNames} more` : '';
+    return `${succeeded}/${total} succeeded; failed: ${shown}${more}`;
+}
+
+// runBatchSequential — pure async orchestration companion to
+// BatchProgressLabel/formatBatchOutcome: runs `items` through `fn` one at a
+// time (never in parallel, matching docstudio's rate-limited bulk-action
+// runner), never aborting on a single item's failure. `onProgress({done,
+// total})` fires after each item settles so a host can drive
+// BatchProgressLabel live; the final `{succeeded, total, failedNames}`
+// return shape feeds formatBatchOutcome directly. `fn` receives (item, index)
+// and may reject/throw — a rejection is recorded as a failure keyed by
+// `item.name != null ? item.name : String(item)`, never re-thrown.
+export async function runBatchSequential(items = [], fn, onProgress) {
+    const total = items.length;
+    let succeeded = 0;
+    const failedNames = [];
+    for (let i = 0; i < total; i += 1) {
+        const item = items[i];
+        try {
+            await fn(item, i);
+            succeeded += 1;
+        } catch (err) {
+            failedNames.push(item && item.name != null ? item.name : String(item));
+        }
+        if (onProgress) onProgress({ done: i + 1, total });
+    }
+    return { succeeded, total, failedNames };
+}

package/src/components/editor-primitives/chrome.js

@@ -0,0 +1,146 @@
+// Editor chrome — the action/navigation bars that frame an editor surface:
+// Toolbar (three-slot), ToolbarRow (flat wrapping row), Tabs (WAI-ARIA tabs
+// with a sliding underline), IconButtonGroup (segmented toggle row). Pure
+// factories, h-based, theme-token driven. All visuals route through CSS
+// classes defined in editor-primitives.css; no hex/rgba literals appear here.
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+import { Icon } from '../shell.js';
+import { kids } from './shared.js';
+const h = webjsx.createElement;
+
+export function Toolbar({ leading = [], trailing = [], dense = false, children } = {}) {
+    const cls = 'ds-ep-toolbar' + (dense ? ' dense' : '');
+    return h('div', { class: cls, role: 'toolbar' },
+        h('div', { class: 'ds-ep-toolbar-leading' }, ...kids(leading)),
+        children != null ? h('div', { class: 'ds-ep-toolbar-center' }, ...kids(children)) : null,
+        h('div', { class: 'ds-ep-toolbar-trailing' }, ...kids(trailing))
+    );
+}
+
+// ---------------------------------------------------------------------------
+// ToolbarRow — a flat, wrapping row of arbitrary action nodes (buttons,
+// inputs, chips) with no leading/center/trailing slot structure. Toolbar's
+// three-slot split is the wrong shape when a caller just wants "this row of
+// controls, left to right, wrapping on narrow viewports" — the exact shape
+// gmsniff's panels.js hand-rolled as a bare '.gm-toolbar' div because Toolbar
+// didn't cover it. Accepts children as varargs or a single array.
+// ---------------------------------------------------------------------------
+export function ToolbarRow(...actions) {
+    const flat = actions.length === 1 && Array.isArray(actions[0]) ? actions[0] : actions;
+    return h('div', { class: 'ds-ep-toolbar-row', role: 'toolbar' }, ...kids(flat));
+}
+
+export function Tabs({ items = [], active, onChange, children, 'aria-label': ariaLabel, onClose, scroll = false } = {}) {
+    // Roving tabindex + arrow nav per WAI-ARIA tabs pattern.
+    // Only the active tab is in the tab order; arrows move focus + activate.
+    const activeIdx = Math.max(0, items.findIndex(it => it.id === active));
+    const onTabKeyDown = (e, idx) => {
+        let next = null;
+        if (e.key === 'ArrowRight') next = (idx + 1) % items.length;
+        else if (e.key === 'ArrowLeft') next = (idx - 1 + items.length) % items.length;
+        else if (e.key === 'Home') next = 0;
+        else if (e.key === 'End') next = items.length - 1;
+        if (next == null) return;
+        e.preventDefault();
+        const nextId = items[next]?.id;
+        if (nextId && onChange) onChange(nextId);
+        // Move focus on next paint (so the newly rendered active button gets focus)
+        queueMicrotask(() => {
+            const head = e.currentTarget?.parentElement;
+            const btn = head?.querySelectorAll('[role="tab"]')[next];
+            if (btn) btn.focus();
+        });
+    };
+    // Position the sliding underline from the active tab's geometry. The ref is
+    // on the OUTER .ds-ep-tabs (position:relative) — the indicator is its child,
+    // NOT the flex head's (an abspos child of a horizontal flex row mis-sizes to
+    // 0 in Chromium). Runs on every render (ref fires after applyDiff) so a tab
+    // change re-measures; the CSS transition animates the move. left/width come
+    // from the active tab; top sits the bar on the head's bottom edge.
+    const positionSlider = (root) => {
+        if (!root) return;
+        const head = root.querySelector('.ds-ep-tabs-head');
+        const active = root.querySelector('.ds-ep-tab.active');
+        const ind = root.querySelector('.ds-ep-tab-indicator');
+        if (!head || !active || !ind) return;
+        // Size via left+right insets, NOT width: an abspos element's inline
+        // `width` computes to 0 in some flex-sibling layouts (Chromium), but
+        // left+right insets size reliably. left/right animate via the CSS
+        // transition on .ds-ep-tab-indicator.
+        const rootW = root.offsetWidth;
+        const l = active.offsetLeft, w = active.offsetWidth;
+        ind.style.left = l + 'px';
+        ind.style.right = Math.max(0, rootW - l - w) + 'px';
+        ind.style.top = (head.offsetTop + head.offsetHeight - 2) + 'px';
+        head.classList.add('has-slider');
+    };
+    // scroll=true: tabs size to content (min/max-width) instead of stretching
+    // equally (flex:1) — the shape pi-web's TabBar uses for an open-file strip
+    // where tab count is unbounded and overflow-x scroll (already on
+    // .ds-ep-tabs-head) needs real per-tab widths to have something to scroll.
+    // onClose: per-item close affordance — a close button plus middle-click
+    // (auxclick button 1) to close, matching pi-web's TabBar. Opt-in: passing
+    // onClose without scroll still renders close buttons on the flex:1 tabs.
+    const closable = typeof onClose === 'function';
+    return h('div', { class: 'ds-ep-tabs', ref: positionSlider },
+        h('div', { class: 'ds-ep-tabs-head' + (scroll ? ' scroll' : ''), role: 'tablist', 'aria-label': ariaLabel || 'tabs' },
+            ...items.map((it, idx) => h('span', {
+                key: it.id,
+                class: 'ds-ep-tab-wrap' + (it.id === active ? ' active' : ''),
+                onmousedown: closable ? (e) => { if (e.button === 1) e.preventDefault(); } : null,
+                onauxclick: closable ? (e) => {
+                    if (e.button !== 1) return;
+                    e.preventDefault();
+                    e.stopPropagation();
+                    onClose(it.id);
+                } : null
+            },
+                h('button', {
+                    type: 'button',
+                    class: 'ds-ep-tab' + (it.id === active ? ' active' : ''),
+                    role: 'tab',
+                    id: 'tab-' + it.id,
+                    title: typeof it.label === 'string' ? it.label : undefined,
+                    'aria-selected': it.id === active ? 'true' : 'false',
+                    'aria-controls': 'tabpanel-' + it.id,
+                    'aria-label': typeof it.label === 'string' ? it.label : ('tab ' + (idx + 1)),
+                    tabindex: idx === activeIdx ? '0' : '-1',
+                    onclick: () => onChange && onChange(it.id),
+                    onkeydown: (e) => onTabKeyDown(e, idx)
+                }, it.label),
+                closable ? h('button', {
+                    type: 'button',
+                    class: 'ds-ep-tab-close',
+                    title: 'Close',
+                    'aria-label': 'Close ' + (typeof it.label === 'string' ? it.label : 'tab'),
+                    onclick: (e) => { e.stopPropagation(); onClose(it.id); }
+                }, Icon('x', { size: 14 })) : null
+            ))
+        ),
+        // The sliding underline — child of the outer column (see positionSlider).
+        // Keyed + decorative. Renders at 0-width until positioned (no-JS: hidden).
+        h('span', { key: '__ind', class: 'ds-ep-tab-indicator', 'aria-hidden': 'true' }),
+        h('div', {
+            class: 'ds-ep-tabs-body',
+            role: 'tabpanel',
+            id: active ? 'tabpanel-' + active : undefined,
+            'aria-labelledby': active ? 'tab-' + active : undefined,
+            tabindex: '0'
+        }, ...kids(children))
+    );
+}
+
+export function IconButtonGroup({ items = [], value, onChange, dense = false } = {}) {
+    return h('div', { class: 'ds-ep-btngrp' + (dense ? ' dense' : ''), role: 'group' },
+        ...items.map((it) => h('button', {
+            key: it.id,
+            type: 'button',
+            class: 'ds-ep-btngrp-btn' + (it.id === value ? ' active' : ''),
+            title: it.title || it.label || it.id,
+            'aria-pressed': it.id === value ? 'true' : 'false',
+            disabled: it.disabled ? 'disabled' : null,
+            onclick: () => { if (!it.disabled && onChange) onChange(it.id); }
+        }, it.glyph != null ? it.glyph : it.label))
+    );
+}

package/src/components/editor-primitives/collapse.js

@@ -0,0 +1,46 @@
+// Progressive disclosure — Collapse (a single controlled toggle panel) and
+// CollapseGroup (the accordion wrapper enforcing single-open-at-a-time).
+// Both are controlled: the caller owns `expanded`/`openId` state, same
+// pattern as Drawer/Dialog's `open`/`onClose` — no internal state.
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+const h = webjsx.createElement;
+
+// ---------------------------------------------------------------------------
+// Collapse — progressive-disclosure toggle panel (screen-real-estate
+// density: property inspectors, nested settings, FAQ-style panels).
+// Controlled component: caller owns `expanded` state and passes `onToggle`,
+// same pattern as Drawer/Dialog `open`/`onClose` above — no internal state.
+// ---------------------------------------------------------------------------
+export function Collapse({ title, expanded = false, onToggle, children, key } = {}) {
+    return h('div', { key, class: 'ds-ep-collapse' + (expanded ? ' is-expanded' : '') },
+        h('button', {
+            type: 'button', class: 'ds-ep-collapse-head',
+            'aria-expanded': expanded ? 'true' : 'false',
+            onclick: () => { if (onToggle) onToggle(!expanded); },
+        },
+            h('span', { class: 'ds-ep-collapse-chevron' }, expanded ? 'v' : '>'),
+            h('span', { class: 'ds-ep-collapse-title' }, title)),
+        expanded ? h('div', { class: 'ds-ep-collapse-body' }, children) : null);
+}
+
+// ---------------------------------------------------------------------------
+// CollapseGroup — accordion wrapper enforcing single-open-at-a-time when
+// `accordion=true` (default false — group just lays out children, each
+// Collapse still individually controlled). `openId`/`onOpenChange` drive the
+// accordion; `items` is [{id, title, children}].
+// ---------------------------------------------------------------------------
+export function CollapseGroup({ items = [], openId, onOpenChange, accordion = false, key } = {}) {
+    return h('div', { key, class: 'ds-ep-collapse-group' },
+        ...items.map((it) => Collapse({
+            key: it.id,
+            title: it.title,
+            expanded: accordion ? it.id === openId : Boolean(it.expanded),
+            onToggle: (next) => {
+                if (!onOpenChange) return;
+                if (accordion) onOpenChange(next ? it.id : null);
+                else onOpenChange(it.id, next);
+            },
+            children: it.children,
+        })));
+}

package/src/components/editor-primitives/context-menu.js

@@ -0,0 +1,127 @@
+// Context menu — the right-click/long-press menu surface: ContextMenu (the
+// viewport-clamped, keyboard-navigable menu itself) plus useContextMenu, the
+// helper that wires right-click + long-press on a target element and hands
+// the caller an {x, y, items} payload to render it from.
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+const h = webjsx.createElement;
+
+// ---------------------------------------------------------------------------
+// ContextMenu — items, anchor {x,y}, onClose. Viewport-clamped. Keyboard nav.
+// ---------------------------------------------------------------------------
+export function ContextMenu({ items = [], anchor = { x: 0, y: 0 }, onClose } = {}) {
+    let rootEl = null;
+    const close = () => { if (onClose) onClose(); };
+    const select = (it) => {
+        if (it.disabled || it.separator) return;
+        if (it.onSelect) it.onSelect();
+        close();
+    };
+    const onKey = (e) => {
+        const btns = rootEl ? [...rootEl.querySelectorAll('button[data-ix]')] : [];
+        const active = document.activeElement;
+        const idx = btns.indexOf(active);
+        if (e.key === 'Escape') { e.preventDefault(); close(); }
+        else if (e.key === 'ArrowDown') { e.preventDefault(); (btns[(idx + 1) % btns.length] || btns[0])?.focus(); }
+        else if (e.key === 'ArrowUp') { e.preventDefault(); (btns[(idx - 1 + btns.length) % btns.length] || btns[0])?.focus(); }
+        else if (e.key === 'Enter' && idx >= 0) { e.preventDefault(); btns[idx].click(); }
+    };
+    return h('div', {
+        class: 'ds-ep-ctxmenu-backdrop',
+        onmousedown: (e) => { if (e.target === e.currentTarget) close(); },
+        oncontextmenu: (e) => { e.preventDefault(); close(); },
+    },
+        h('div', {
+            class: 'ds-ep-ctxmenu',
+            role: 'menu',
+            tabindex: '-1',
+            onkeydown: onKey,
+            ref: (el) => {
+                if (!el) {
+                    // Unmount: unhook the resize re-clamp bound on mount.
+                    if (rootEl && rootEl._dsCtxClampOff) { rootEl._dsCtxClampOff(); }
+                    rootEl = null;
+                    return;
+                }
+                rootEl = el;
+                // Position at the anchor immediately, then clamp once layout has
+                // settled — measuring synchronously in ref reads a zero-size box
+                // (children not yet painted), so the clamp must run post-layout.
+                const ax = anchor.x || 0, ay = anchor.y || 0;
+                el.style.left = ax + 'px';
+                el.style.top = ay + 'px';
+                const coarse = typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches;
+                const clamp = () => {
+                    const vw = window.innerWidth, vh = window.innerHeight;
+                    const r = el.getBoundingClientRect();
+                    let x = ax, y = ay;
+                    // Touch: keep the menu clear of the lifting finger — nudge
+                    // below the touch point, or open above when it fits and the
+                    // anchor sits in the lower half (lift-off would otherwise
+                    // activate the first item).
+                    if (coarse) {
+                        y = ay + 10;
+                        if (ay > vh / 2 && ay - r.height >= 4) y = ay - r.height;
+                    }
+                    if (x + r.width > vw) x = Math.max(4, vw - r.width - 4);
+                    if (y + r.height > vh) y = Math.max(4, vh - r.height - 4);
+                    el.style.left = x + 'px';
+                    el.style.top = y + 'px';
+                };
+                requestAnimationFrame(clamp);
+                // Re-clamp on resize/orientation change for the menu's lifetime.
+                window.addEventListener('resize', clamp);
+                el._dsCtxClampOff = () => { window.removeEventListener('resize', clamp); el._dsCtxClampOff = null; };
+                // setTimeout(0), not queueMicrotask: the triggering contextmenu/click
+                // event's own default focus can otherwise win the race and leave focus
+                // outside the menu, breaking keyboard arrow-nav/Escape.
+                setTimeout(() => { el.querySelector('button[data-ix]')?.focus(); }, 0);
+            }
+        },
+            ...items.map((it, i) => it.separator
+                ? h('div', { key: 'sep' + i, class: 'ds-ep-ctxmenu-sep', role: 'separator' })
+                : h('button', {
+                    key: i, type: 'button', role: 'menuitem',
+                    'data-ix': String(i),
+                    class: 'ds-ep-ctxmenu-item' + (it.danger ? ' danger' : '') + (it.disabled ? ' disabled' : ''),
+                    disabled: it.disabled ? 'disabled' : null,
+                    onclick: () => select(it),
+                },
+                    it.icon != null ? h('span', { class: 'ds-ep-ctxmenu-icon' }, it.icon) : null,
+                    h('span', { class: 'ds-ep-ctxmenu-label' }, it.label)
+                ))
+        )
+    );
+}
+
+// Helper: wires right-click + long-press to a target ref. Caller manages state.
+export function useContextMenu(targetEl, items, openCb) {
+    if (!targetEl) return () => {};
+    let touchTimer = null, lastOpen = 0;
+    // Android fires the native contextmenu event on long-press AND our 500ms
+    // touch timer — dedupe so the menu opens once, not twice (open/flicker).
+    const open = (x, y) => {
+        if (Date.now() - lastOpen < 700) return;
+        lastOpen = Date.now();
+        if (openCb) openCb({ x, y, items });
+    };
+    const onCtx = (e) => { e.preventDefault(); open(e.clientX, e.clientY); };
+    const onTouchStart = (e) => {
+        const t = e.touches && e.touches[0]; if (!t) return;
+        touchTimer = setTimeout(() => { touchTimer = null; open(t.clientX, t.clientY); }, 500);
+    };
+    const cancel = () => { if (touchTimer) { clearTimeout(touchTimer); touchTimer = null; } };
+    targetEl.addEventListener('contextmenu', onCtx);
+    targetEl.addEventListener('touchstart', onTouchStart, { passive: true });
+    targetEl.addEventListener('touchmove', cancel, { passive: true });
+    targetEl.addEventListener('touchend', cancel);
+    targetEl.addEventListener('touchcancel', cancel);
+    return () => {
+        targetEl.removeEventListener('contextmenu', onCtx);
+        targetEl.removeEventListener('touchstart', onTouchStart);
+        targetEl.removeEventListener('touchmove', cancel);
+        targetEl.removeEventListener('touchend', cancel);
+        targetEl.removeEventListener('touchcancel', cancel);
+        cancel();
+    };
+}

package/src/components/editor-primitives/diagnostics.js

@@ -0,0 +1,44 @@
+// ---------------------------------------------------------------------------
+// InfoRow / InfoSection / DiagnosticsPanel — static debug/system-info
+// readouts: a bordered section of label + monospace-value rows. Ported from
+// docstudio's diagnostics page (auth/streaming/service-worker state, recent
+// client errors, environment facts). Distinct from PropertyGrid, which is
+// for EDITABLE properties — these rows are read-only display, never inputs.
+// `data == null` (not yet loaded) renders a loading placeholder row instead
+// of an empty section, so a panel never flashes an empty bordered box before
+// its first data arrives; `onRefresh` renders a trailing refresh button that
+// reuses the section's own header row rather than shifting layout beneath it.
+// ---------------------------------------------------------------------------
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+const h = webjsx.createElement;
+
+export function InfoRow({ label, value, key } = {}) {
+    return h('div', { key, class: 'ds-ep-inforow' },
+        h('span', { class: 'ds-ep-inforow-label' }, label),
+        h('span', { class: 'ds-ep-inforow-value' }, value == null || value === '' ? '—' : String(value)));
+}
+
+export function InfoSection({ title, rows, key } = {}) {
+    const children = [
+        title ? h('h3', { key: 'title', class: 'ds-ep-infosection-title' }, title) : null,
+        rows == null
+            ? h('div', { key: 'body-loading', class: 'ds-ep-infosection-loading', role: 'status' }, 'Loading…')
+            : h('div', { key: 'body-rows', class: 'ds-ep-infosection-rows' }, ...rows.map((r, i) => InfoRow({ ...r, key: r.key != null ? r.key : i })))
+    ].filter(Boolean);
+    return h('section', { key, class: 'ds-ep-infosection' }, ...children);
+}
+
+export function DiagnosticsPanel({ title = 'Diagnostics', sections = [], onRefresh, refreshing = false, key } = {}) {
+    const headChildren = [
+        h('h2', { key: 'title', class: 'ds-ep-diagnostics-title' }, title),
+        onRefresh ? h('button', {
+            key: 'refresh', type: 'button', class: 'ds-ep-diagnostics-refresh', disabled: refreshing, 'aria-busy': refreshing ? 'true' : 'false',
+            onclick: () => onRefresh()
+        }, refreshing ? 'Refreshing…' : 'Refresh') : null
+    ].filter(Boolean);
+    return h('div', { key, class: 'ds-ep-diagnostics' },
+        h('div', { key: 'head', class: 'ds-ep-diagnostics-head' }, ...headChildren),
+        ...sections.map((s, i) => InfoSection({ ...s, key: s.key || i }))
+    );
+}

package/src/components/editor-primitives/focus-trap.js

@@ -0,0 +1,26 @@
+// ---------------------------------------------------------------------------
+// FocusTrap — wraps subtree, traps Tab/Shift+Tab. Mount/unmount lifecycle is
+// managed via DOM-level keydown listener attached when first focused.
+// ---------------------------------------------------------------------------
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+import { kids, FOCUSABLE_SEL, trapTabKey } from './shared.js';
+const h = webjsx.createElement;
+
+export function FocusTrap({ children } = {}) {
+    return h('div', {
+        class: 'ds-ep-focustrap',
+        tabindex: '-1',
+        ref: (el) => {
+            if (!el || el._dsTrap) return;
+            el._dsTrap = true;
+            el.addEventListener('keydown', (e) => trapTabKey(el, e));
+            // Auto-focus first focusable
+            queueMicrotask(() => {
+                const first = el.querySelector(FOCUSABLE_SEL);
+                if (first) first.focus();
+                else el.focus();
+            });
+        }
+    }, ...kids(children));
+}

package/src/components/editor-primitives/json-viewer.js

@@ -0,0 +1,123 @@
+// ---------------------------------------------------------------------------
+// JsonViewer — monospace data preview (max-height + scroll), generalizing
+// gmsniff's gm-json. Accepts a pre-stringified string OR any value
+// (objects/arrays get JSON.stringify(v, null, 2); null/undefined render the
+// empty-state text rather than the literal string "undefined"/"null").
+//
+// mode selects rendering; 'plain' is the historical contract (children[0] is
+// the raw text string, verbatim for string input) and stays the default so
+// every existing consumer is untouched:
+//   'plain'     — flat <pre>, raw text.
+//   'highlight' — flat <pre>, text tokenized into ds-ep-json-* spans
+//                 (key/string/number/boolean/null). A string that does not
+//                 parse as JSON falls back to plain text — arbitrary prose is
+//                 never falsely tokenized.
+//   'tree'      — collapsible <details> tree per nested object/array, open
+//                 above treeDepth (default 2), each summary carrying a
+//                 child-count tag. Scalars/unparseable input fall back to
+//                 'highlight'/plain respectively.
+// copyable=true wraps the viewer with a copy-to-clipboard button (transient
+// copied/failed feedback, no dependencies).
+// ---------------------------------------------------------------------------
+
+import * as webjsx from '../../../vendor/webjsx/index.js';
+const h = webjsx.createElement;
+
+const JSON_NUM_CHARS = '0123456789eE+.-';
+
+// Linear single-pass scan — no regex, no backtracking, safe on truncated
+// input (an unterminated string just consumes to end-of-text).
+function tokenizeJson(text) {
+    const toks = [];
+    let i = 0, plain = '';
+    const flush = () => { if (plain) { toks.push(['', plain]); plain = ''; } };
+    while (i < text.length) {
+        const c = text[i];
+        if (c === '"') {
+            const start = i;
+            i++;
+            while (i < text.length && text[i] !== '"') { if (text[i] === '\\') i++; i++; }
+            i = Math.min(i + 1, text.length);
+            let j = i;
+            while (j < text.length && (text[j] === ' ' || text[j] === '\t' || text[j] === '\n' || text[j] === '\r')) j++;
+            flush();
+            toks.push([text[j] === ':' ? 'k' : 's', text.slice(start, i)]);
+            continue;
+        }
+        if (c === '-' || (c >= '0' && c <= '9')) {
+            const start = i;
+            i++;
+            while (i < text.length && JSON_NUM_CHARS.includes(text[i])) i++;
+            flush();
+            toks.push(['n', text.slice(start, i)]);
+            continue;
+        }
+        if (text.startsWith('true', i)) { flush(); toks.push(['b', 'true']); i += 4; continue; }
+        if (text.startsWith('false', i)) { flush(); toks.push(['b', 'false']); i += 5; continue; }
+        if (text.startsWith('null', i)) { flush(); toks.push(['z', 'null']); i += 4; continue; }
+        plain += c; i++;
+    }
+    flush();
+    return toks;
+}
+
+function highlightJsonSpans(text) {
+    return tokenizeJson(text).map(([t, s]) => t ? h('span', { class: 'ds-ep-json-' + t }, s) : s);
+}
+
+function jsonTreeNode(key, val, depth, treeDepth) {
+    const keyParts = key != null ? [h('span', { class: 'ds-ep-json-k' }, JSON.stringify(key)), ': '] : [];
+    if (val !== null && typeof val === 'object') {
+        const isArr = Array.isArray(val);
+        const entries = isArr ? val.map((v) => [null, v]) : Object.entries(val);
+        if (!entries.length) return h('div', { class: 'ds-ep-json-leaf' }, ...keyParts, isArr ? '[]' : '{}');
+        const tag = isArr ? '[' + entries.length + ']' : '{' + entries.length + '}';
+        return h('details', { class: 'ds-ep-json-node', open: depth < treeDepth ? true : null },
+            h('summary', { class: 'ds-ep-json-sum' }, ...keyParts, h('span', { class: 'ds-ep-json-tag' }, tag)),
+            h('div', { class: 'ds-ep-json-kids' }, ...entries.map(([k, v]) => jsonTreeNode(k, v, depth + 1, treeDepth))));
+    }
+    const t = typeof val === 'string' ? 's' : typeof val === 'number' ? 'n' : typeof val === 'boolean' ? 'b' : 'z';
+    return h('div', { class: 'ds-ep-json-leaf' }, ...keyParts, h('span', { class: 'ds-ep-json-' + t }, JSON.stringify(val) ?? String(val)));
+}
+
+function jsonCopyButton(text) {
+    return h('button', {
+        type: 'button', class: 'ds-ep-json-copy', title: 'copy JSON', 'aria-label': 'copy JSON',
+        onclick: (e) => {
+            const btn = e.currentTarget;
+            const show = (label, ok) => {
+                btn.textContent = label;
+                btn.classList.toggle('copied', ok);
+                setTimeout(() => { btn.textContent = 'copy'; btn.classList.remove('copied'); }, 1200);
+            };
+            try {
+                navigator.clipboard.writeText(text).then(() => show('copied', true), () => show('failed', false));
+            } catch {
+                show('failed', false);
+            }
+        },
+    }, 'copy');
+}
+
+export function JsonViewer({ value, emptyText = 'no data', maxHeight, mode = 'plain', copyable = false, treeDepth = 2 } = {}) {
+    let text, parsed;
+    let knownJson = false;
+    if (value == null) text = null;
+    else if (typeof value === 'string') text = value;
+    else { try { text = JSON.stringify(value, null, 2); knownJson = text != null; parsed = value; } catch { text = String(value); } }
+    if (!text) return h('div', { class: 'ds-ep-json ds-ep-json-empty' }, emptyText);
+    const style = maxHeight ? ('max-height:' + maxHeight) : null;
+    if (!knownJson && (mode === 'highlight' || mode === 'tree')) {
+        try { parsed = JSON.parse(text); knownJson = true; } catch { /* swallow: not JSON — render plain */ }
+    }
+    let body;
+    if (mode === 'tree' && knownJson && parsed !== null && typeof parsed === 'object') {
+        body = h('div', { class: 'ds-ep-json ds-ep-json-tree', style }, jsonTreeNode(null, parsed, 0, treeDepth));
+    } else if ((mode === 'highlight' || mode === 'tree') && knownJson) {
+        body = h('pre', { class: 'ds-ep-json ds-ep-json-hl', style }, ...highlightJsonSpans(text));
+    } else {
+        body = h('pre', { class: 'ds-ep-json', style }, text);
+    }
+    if (!copyable) return body;
+    return h('div', { class: 'ds-ep-json-wrap' }, jsonCopyButton(text), body);
+}