@jgengine/editor 0.10.0 → 0.12.0

package/dist/shell/pathFlythrough.js

@@ -0,0 +1,54 @@
+import { pathFollowSeek, pathLength, } from "@jgengine/core/nav/pathFollow";
+/**
+ * Builds the path-follow config used by the flythrough scrubber. Pure; no document mutation.
+ * Returns null when the path cannot be sampled (fewer than two points).
+ *
+ * @internal
+ */
+export function pathFollowConfigFromEditorPath(path) {
+    if (path.points.length < 2)
+        return null;
+    const waypoints = path.points.map((point) => [point.x, point.y, point.z]);
+    return { waypoints, speed: 1 };
+}
+/**
+ * Lists document paths that can be scrubbed, with length metadata for the dock UI.
+ *
+ * @internal
+ */
+export function listScrubbablePaths(paths) {
+    return paths
+        .map((path) => {
+        const config = pathFollowConfigFromEditorPath(path);
+        const length = config === null ? 0 : pathLength(config);
+        return {
+            id: path.id,
+            kind: path.kind,
+            label: path.label?.trim() || path.id,
+            pointCount: path.points.length,
+            length,
+        };
+    })
+        .filter((entry) => entry.pointCount >= 2);
+}
+/**
+ * Samples a world position along an authored path at normalized progress `t` in `[0, 1]`.
+ * Clamps `t`. Returns null when the path has fewer than two points.
+ *
+ * @internal
+ */
+export function samplePathAt(path, t) {
+    const config = pathFollowConfigFromEditorPath(path);
+    if (config === null)
+        return null;
+    const length = pathLength(config);
+    const clamped = Number.isFinite(t) ? Math.max(0, Math.min(1, t)) : 0;
+    const state = pathFollowSeek(config, { kind: "normalized", value: clamped });
+    return {
+        x: state.position[0],
+        y: state.position[1],
+        z: state.position[2],
+        distance: length * clamped,
+        length,
+    };
+}

package/dist/shell/perfHistory.d.ts

@@ -0,0 +1,70 @@
+import type { EditorPerfSample } from "../session.js";
+/**
+ * Rolling history of real {@link EditorPerfSample}s for the Profiler dock tab's frame-time graph.
+ * Fed by the same 500ms host poll the toolbar pill uses; never fabricates values. Kept outside
+ * React state so recording continues while the profiler tab is closed without rerendering anything.
+ */
+export interface PerfHistoryStore {
+    push(sample: EditorPerfSample): void;
+    getSamples(): readonly EditorPerfSample[];
+    clear(): void;
+    setPaused(paused: boolean): void;
+    isPaused(): boolean;
+    subscribe(listener: () => void): () => void;
+}
+/** Samples retained (~2 minutes at the 500ms poll). */
+export declare const PERF_HISTORY_CAPACITY = 240;
+/** Creates the rolling perf-sample history store. */
+export declare function createPerfHistoryStore(): PerfHistoryStore;
+/** Mean of a numeric series, 0 for empty input. */
+export declare function seriesAverage(values: readonly number[]): number;
+/**
+ * Mean of defined values only — used for optional series (`simMs` / `outsideMs` / `memoryMb`)
+ * so zeros from absent samples do not drag the average down.
+ *
+ * @internal
+ */
+export declare function seriesAverageDefined(values: readonly (number | undefined)[]): number;
+/** Builds an SVG polyline `points` string for a series scaled into a width×height box. */
+export declare function sparklinePoints(values: readonly number[], width: number, height: number, maxValue: number): string;
+/** Minimal frame-stats shape consumed when folding core `devtools.frame.stats()` into a sample. */
+export interface FrameBudgetStatsInput {
+    avgSimMs: number;
+    avgOutsideMs: number;
+    phases: readonly {
+        name: string;
+        avgMs: number;
+    }[];
+}
+/** Optional sim / outside / phase fields derived from real frame-tracker stats (never invented). */
+export interface FrameBudgetFields {
+    simMs: number;
+    outsideMs: number;
+    phases?: readonly {
+        name: string;
+        avgMs: number;
+    }[];
+}
+/**
+ * Map core `devtools.frame.stats()` into optional editor sample fields.
+ * Returns `null` when the frame tracker has no samples yet — callers must omit the series entirely.
+ *
+ * @internal
+ */
+export declare function frameBudgetFromStats(stats: FrameBudgetStatsInput | null): FrameBudgetFields | null;
+/**
+ * True when any sample carries real sim/outside budget fields from the frame tracker.
+ *
+ * @internal
+ */
+export declare function samplesHaveFrameBudget(samples: readonly EditorPerfSample[]): boolean;
+/**
+ * Latest non-empty phase list from the history (newest sample that reported phases).
+ * Empty when no named `measure()` marks have been recorded.
+ *
+ * @internal
+ */
+export declare function latestPhases(samples: readonly EditorPerfSample[]): readonly {
+    name: string;
+    avgMs: number;
+}[];

package/dist/shell/perfHistory.js

@@ -0,0 +1,130 @@
+/** Samples retained (~2 minutes at the 500ms poll). */
+export const PERF_HISTORY_CAPACITY = 240;
+/** Creates the rolling perf-sample history store. */
+export function createPerfHistoryStore() {
+    let samples = [];
+    let paused = false;
+    let lastSampledAt = -1;
+    const listeners = new Set();
+    const emit = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    return {
+        push(sample) {
+            if (paused)
+                return;
+            // The host poll re-reads the same sample between probe windows; only record fresh ones.
+            if (sample.sampledAt === lastSampledAt)
+                return;
+            lastSampledAt = sample.sampledAt;
+            samples = [...samples, sample];
+            if (samples.length > PERF_HISTORY_CAPACITY)
+                samples = samples.slice(samples.length - PERF_HISTORY_CAPACITY);
+            emit();
+        },
+        getSamples: () => samples,
+        clear() {
+            samples = [];
+            lastSampledAt = -1;
+            emit();
+        },
+        setPaused(next) {
+            if (paused === next)
+                return;
+            paused = next;
+            emit();
+        },
+        isPaused: () => paused,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+/** Mean of a numeric series, 0 for empty input. */
+export function seriesAverage(values) {
+    if (values.length === 0)
+        return 0;
+    let sum = 0;
+    for (const value of values)
+        sum += value;
+    return sum / values.length;
+}
+/**
+ * Mean of defined values only — used for optional series (`simMs` / `outsideMs` / `memoryMb`)
+ * so zeros from absent samples do not drag the average down.
+ *
+ * @internal
+ */
+export function seriesAverageDefined(values) {
+    let sum = 0;
+    let count = 0;
+    for (const value of values) {
+        if (value === undefined)
+            continue;
+        sum += value;
+        count += 1;
+    }
+    return count === 0 ? 0 : sum / count;
+}
+/** Builds an SVG polyline `points` string for a series scaled into a width×height box. */
+export function sparklinePoints(values, width, height, maxValue) {
+    if (values.length === 0 || maxValue <= 0)
+        return "";
+    const step = values.length > 1 ? width / (values.length - 1) : 0;
+    return values
+        .map((value, index) => {
+        const x = values.length > 1 ? index * step : width / 2;
+        const y = height - Math.min(1, value / maxValue) * height;
+        return `${x.toFixed(1)},${y.toFixed(1)}`;
+    })
+        .join(" ");
+}
+const MAX_PHASES_IN_SAMPLE = 6;
+function roundMs(value) {
+    return Math.round(value * 100) / 100;
+}
+/**
+ * Map core `devtools.frame.stats()` into optional editor sample fields.
+ * Returns `null` when the frame tracker has no samples yet — callers must omit the series entirely.
+ *
+ * @internal
+ */
+export function frameBudgetFromStats(stats) {
+    if (stats === null)
+        return null;
+    const phases = stats.phases
+        .filter((phase) => Number.isFinite(phase.avgMs) && phase.avgMs > 0 && phase.name.length > 0)
+        .slice(0, MAX_PHASES_IN_SAMPLE)
+        .map((phase) => ({ name: phase.name, avgMs: roundMs(phase.avgMs) }));
+    return {
+        simMs: roundMs(stats.avgSimMs),
+        outsideMs: roundMs(stats.avgOutsideMs),
+        ...(phases.length > 0 ? { phases } : {}),
+    };
+}
+/**
+ * True when any sample carries real sim/outside budget fields from the frame tracker.
+ *
+ * @internal
+ */
+export function samplesHaveFrameBudget(samples) {
+    return samples.some((sample) => sample.simMs !== undefined && sample.outsideMs !== undefined);
+}
+/**
+ * Latest non-empty phase list from the history (newest sample that reported phases).
+ * Empty when no named `measure()` marks have been recorded.
+ *
+ * @internal
+ */
+export function latestPhases(samples) {
+    for (let index = samples.length - 1; index >= 0; index -= 1) {
+        const phases = samples[index]?.phases;
+        if (phases !== undefined && phases.length > 0)
+            return phases;
+    }
+    return [];
+}

package/dist/shell/renameObject.d.ts

@@ -0,0 +1,3 @@
+import { type EditorSession } from "@jgengine/core/editor/index";
+/** Renames a placeable object by writing its label (notes use `text`). Returns false if unknown. @internal */
+export declare function renameEditorObject(session: EditorSession, id: string, nextLabel: string): boolean;

package/dist/shell/renameObject.js

@@ -0,0 +1,25 @@
+import { findEditorMarker, findEditorNote, findEditorPath, findEditorVolume, } from "@jgengine/core/editor/index";
+/** Renames a placeable object by writing its label (notes use `text`). Returns false if unknown. @internal */
+export function renameEditorObject(session, id, nextLabel) {
+    const label = nextLabel.trim();
+    if (label.length === 0)
+        return false;
+    const doc = session.getState().document;
+    if (findEditorMarker(doc, id) !== undefined) {
+        session.dispatch({ type: "setMarker", id, patch: { label } });
+        return true;
+    }
+    if (findEditorVolume(doc, id) !== undefined) {
+        session.dispatch({ type: "setVolume", id, patch: { label } });
+        return true;
+    }
+    if (findEditorPath(doc, id) !== undefined) {
+        session.dispatch({ type: "setPath", id, patch: { label } });
+        return true;
+    }
+    if (findEditorNote(doc, id) !== undefined) {
+        session.dispatch({ type: "setNote", id, patch: { text: label } });
+        return true;
+    }
+    return false;
+}

package/dist/shell/theme.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Editor shell design tokens as Tailwind class constants. One place owns the layered dark theme
+ * (app < panel < control elevation), text scale, and interaction states so every shell component
+ * reads identically. Class strings are complete literals so the host app's Tailwind scan keeps them.
+ */
+/** Application background — the near-black base everything sits on. */
+export declare const APP_BG = "bg-[#0b0d10]";
+/** Panel surface — one elevation step above the app background. */
+export declare const PANEL_BG = "bg-[#111318]";
+/** Elevated control surface — inputs, chips, dropdowns. */
+export declare const CONTROL_BG = "bg-[#191d24]";
+/** Floating layer surface — menus, palettes, popovers. */
+export declare const FLOAT_BG = "bg-[#14171d]";
+/** Low-contrast neutral border used between shell regions. */
+export declare const BORDER = "border-white/[0.07]";
+/** Standard control text row. */
+export declare const TEXT = "text-[12px] text-neutral-300";
+/** Muted metadata text. */
+export declare const TEXT_MUTED = "text-[11px] text-neutral-500";
+/** Micro uppercase section label. */
+export declare const MICRO_LABEL = "text-[10px] font-semibold uppercase tracking-[0.12em] text-neutral-500";
+/** Shared focus ring for keyboard navigation on interactive controls. */
+export declare const FOCUS_RING = "outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/60 focus-visible:ring-offset-0";
+/** Base interactive control: compact, subtle border, hover elevation. */
+export declare const CONTROL = "rounded-[5px] border border-white/[0.07] bg-[#191d24] text-neutral-300 transition-colors hover:bg-[#1f242d] hover:text-neutral-100 outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/60 focus-visible:ring-offset-0";
+/** Active/selected control state — restrained cyan. */
+export declare const CONTROL_ACTIVE = "border-cyan-400/40 bg-cyan-500/15 text-cyan-200 hover:bg-cyan-500/20";
+/** Text input styling shared across shell panels. */
+export declare const INPUT_CLS = "rounded-[5px] border border-white/[0.08] bg-black/40 text-[12px] text-neutral-200 outline-none transition-colors placeholder:text-neutral-600 focus:border-cyan-400/50 focus:bg-black/60 outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/60 focus-visible:ring-offset-0";
+/** Tabular numerals for transforms, metrics, and timing readouts. */
+export declare const NUMERIC = "tabular-nums";
+/** Per-axis accent colors for transform fields (X red, Y green, Z blue — gizmo-matched). */
+export declare const AXIS_COLORS: Record<"x" | "y" | "z", {
+    text: string;
+    bar: string;
+}>;

package/dist/shell/theme.js

@@ -0,0 +1,37 @@
+/**
+ * Editor shell design tokens as Tailwind class constants. One place owns the layered dark theme
+ * (app < panel < control elevation), text scale, and interaction states so every shell component
+ * reads identically. Class strings are complete literals so the host app's Tailwind scan keeps them.
+ */
+/** Application background — the near-black base everything sits on. */
+export const APP_BG = "bg-[#0b0d10]";
+/** Panel surface — one elevation step above the app background. */
+export const PANEL_BG = "bg-[#111318]";
+/** Elevated control surface — inputs, chips, dropdowns. */
+export const CONTROL_BG = "bg-[#191d24]";
+/** Floating layer surface — menus, palettes, popovers. */
+export const FLOAT_BG = "bg-[#14171d]";
+/** Low-contrast neutral border used between shell regions. */
+export const BORDER = "border-white/[0.07]";
+/** Standard control text row. */
+export const TEXT = "text-[12px] text-neutral-300";
+/** Muted metadata text. */
+export const TEXT_MUTED = "text-[11px] text-neutral-500";
+/** Micro uppercase section label. */
+export const MICRO_LABEL = "text-[10px] font-semibold uppercase tracking-[0.12em] text-neutral-500";
+/** Shared focus ring for keyboard navigation on interactive controls. */
+export const FOCUS_RING = "outline-none focus-visible:ring-2 focus-visible:ring-cyan-400/60 focus-visible:ring-offset-0";
+/** Base interactive control: compact, subtle border, hover elevation. */
+export const CONTROL = `rounded-[5px] border border-white/[0.07] bg-[#191d24] text-neutral-300 transition-colors hover:bg-[#1f242d] hover:text-neutral-100 ${FOCUS_RING}`;
+/** Active/selected control state — restrained cyan. */
+export const CONTROL_ACTIVE = "border-cyan-400/40 bg-cyan-500/15 text-cyan-200 hover:bg-cyan-500/20";
+/** Text input styling shared across shell panels. */
+export const INPUT_CLS = `rounded-[5px] border border-white/[0.08] bg-black/40 text-[12px] text-neutral-200 outline-none transition-colors placeholder:text-neutral-600 focus:border-cyan-400/50 focus:bg-black/60 ${FOCUS_RING}`;
+/** Tabular numerals for transforms, metrics, and timing readouts. */
+export const NUMERIC = "tabular-nums";
+/** Per-axis accent colors for transform fields (X red, Y green, Z blue — gizmo-matched). */
+export const AXIS_COLORS = {
+    x: { text: "text-[#f87171]", bar: "bg-[#f87171]" },
+    y: { text: "text-[#4ade80]", bar: "bg-[#4ade80]" },
+    z: { text: "text-[#60a5fa]", bar: "bg-[#60a5fa]" },
+};

package/dist/shell/ui.d.ts

@@ -0,0 +1,84 @@
+import { type ReactNode } from "react";
+import { type IconName } from "./icons.js";
+/** Icon-only control with a mandatory accessible name (tooltip + aria-label). */
+export declare function IconButton({ icon, label, onClick, active, disabled, size, className, tone, }: {
+    icon: IconName;
+    label: string;
+    onClick?: () => void;
+    active?: boolean;
+    disabled?: boolean;
+    size?: number;
+    className?: string;
+    tone?: "neutral" | "ghost";
+}): import("react").JSX.Element;
+/** Thin vertical divider between toolbar clusters. */
+export declare function ToolbarDivider(): import("react").JSX.Element;
+/** Keyboard-shortcut chip rendered inside buttons and menus. */
+export declare function Kbd({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** One choice within a {@link Segmented} control. */
+export interface SegmentedOption<T extends string> {
+    value: T;
+    label: string;
+    icon?: IconName;
+    /** Keyboard hint shown after the label. */
+    kbd?: string;
+    /** Hide the text label and render icon-only (label becomes the tooltip). */
+    iconOnly?: boolean;
+}
+/** Compact segmented control on the elevated-control surface with a cyan active segment. */
+export declare function Segmented<T extends string>({ options, value, onChange, ariaLabel, disabled, }: {
+    options: readonly SegmentedOption<T>[];
+    value: T;
+    onChange: (value: T) => void;
+    ariaLabel: string;
+    disabled?: boolean;
+}): import("react").JSX.Element;
+/** Horizontal tab strip for dock panels (bottom dock, inspector tabs). */
+export declare function PanelTabs<T extends string>({ tabs, active, onSelect, trailing, ariaLabel, }: {
+    tabs: readonly {
+        id: T;
+        label: string;
+        icon?: IconName;
+        badge?: string | number;
+    }[];
+    active: T;
+    onSelect: (id: T) => void;
+    trailing?: ReactNode;
+    ariaLabel: string;
+}): import("react").JSX.Element;
+/** Collapsible component card for the inspector and side panels. */
+export declare function CollapsibleSection({ title, icon, open, onToggle, children, trailing, tone, }: {
+    title: string;
+    icon?: IconName;
+    open: boolean;
+    onToggle: () => void;
+    children: ReactNode;
+    trailing?: ReactNode;
+    /** Optional accent color for the title icon. */
+    tone?: string;
+}): import("react").JSX.Element;
+/** Polished empty state used by unsupported workspaces and empty docks. */
+export declare function EmptyState({ icon, title, description, badge, children, }: {
+    icon: IconName;
+    title: string;
+    description: string;
+    badge?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** Micro uppercase heading used inside panels. */
+export declare function PanelHeading({ children, trailing }: {
+    children: ReactNode;
+    trailing?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Drag handle between shell regions. Pointer-drag resizes continuously; arrow keys resize in
+ * 16px steps for keyboard access. `sign` maps a positive pointer delta to a size increase.
+ */
+export declare function PanelResizer({ orientation, label, onResize, sign, }: {
+    orientation: "vertical" | "horizontal";
+    label: string;
+    onResize: (delta: number) => void;
+    sign?: 1 | -1;
+}): import("react").JSX.Element;

package/dist/shell/ui.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useRef } from "react";
+import { Icon } from "./icons.js";
+import { CONTROL, CONTROL_ACTIVE, FOCUS_RING, MICRO_LABEL } from "./theme.js";
+/** Icon-only control with a mandatory accessible name (tooltip + aria-label). */
+export function IconButton({ icon, label, onClick, active = false, disabled = false, size = 14, className = "", tone = "neutral", }) {
+    const base = tone === "ghost"
+        ? `rounded-[5px] border border-transparent text-neutral-400 transition-colors hover:bg-white/[0.06] hover:text-neutral-100 ${FOCUS_RING}`
+        : CONTROL;
+    return (_jsx("button", { type: "button", title: label, "aria-label": label, "aria-pressed": active, disabled: disabled, onClick: onClick, className: `flex h-7 w-7 shrink-0 items-center justify-center ${base} ${active ? CONTROL_ACTIVE : ""} disabled:pointer-events-none disabled:opacity-35 ${className}`, children: _jsx(Icon, { name: icon, size: size }) }));
+}
+/** Thin vertical divider between toolbar clusters. */
+export function ToolbarDivider() {
+    return _jsx("div", { className: "mx-1 h-5 w-px shrink-0 bg-white/[0.07]", "aria-hidden": "true" });
+}
+/** Keyboard-shortcut chip rendered inside buttons and menus. */
+export function Kbd({ children }) {
+    return (_jsx("kbd", { className: "rounded-[3px] bg-white/[0.07] px-1 py-px font-sans text-[9px] leading-none text-neutral-400 ring-1 ring-inset ring-white/[0.08]", children: children }));
+}
+/** Compact segmented control on the elevated-control surface with a cyan active segment. */
+export function Segmented({ options, value, onChange, ariaLabel, disabled = false, }) {
+    return (_jsx("div", { role: "group", "aria-label": ariaLabel, className: `flex shrink-0 items-center gap-0.5 rounded-[6px] border border-white/[0.07] bg-black/30 p-0.5 ${disabled ? "pointer-events-none opacity-40" : ""}`, children: options.map((option) => {
+            const active = option.value === value;
+            return (_jsxs("button", { type: "button", title: option.kbd !== undefined ? `${option.label} (${option.kbd})` : option.label, "aria-label": option.label, "aria-pressed": active, onClick: () => onChange(option.value), className: `flex h-6 items-center gap-1.5 rounded-[4px] px-2 text-[11px] transition-colors ${FOCUS_RING} ${active
+                    ? "bg-cyan-500/20 text-cyan-100 shadow-[inset_0_0_0_1px_rgba(34,211,238,0.25)]"
+                    : "text-neutral-400 hover:bg-white/[0.06] hover:text-neutral-200"}`, children: [option.icon !== undefined ? _jsx(Icon, { name: option.icon, size: 13 }) : null, option.iconOnly === true ? null : _jsx("span", { children: option.label }), option.kbd !== undefined && option.iconOnly !== true ? (_jsx("kbd", { className: `font-sans text-[9px] ${active ? "text-cyan-200/70" : "text-neutral-600"}`, children: option.kbd })) : null] }, option.value));
+        }) }));
+}
+/** Horizontal tab strip for dock panels (bottom dock, inspector tabs). */
+export function PanelTabs({ tabs, active, onSelect, trailing, ariaLabel, }) {
+    return (_jsxs("div", { role: "tablist", "aria-label": ariaLabel, className: "flex h-8 shrink-0 items-center gap-0.5 border-b border-white/[0.07] px-1.5", children: [tabs.map((tab) => {
+                const selected = tab.id === active;
+                return (_jsxs("button", { type: "button", role: "tab", "aria-selected": selected, onClick: () => onSelect(tab.id), className: `flex h-6.5 items-center gap-1.5 rounded-[5px] px-2.5 text-[11px] transition-colors ${FOCUS_RING} ${selected ? "bg-white/[0.08] text-neutral-100" : "text-neutral-500 hover:bg-white/[0.04] hover:text-neutral-300"}`, children: [tab.icon !== undefined ? _jsx(Icon, { name: tab.icon, size: 13 }) : null, _jsx("span", { children: tab.label }), tab.badge !== undefined ? (_jsx("span", { className: `rounded-full px-1.5 py-px text-[9px] tabular-nums ${selected ? "bg-cyan-500/20 text-cyan-200" : "bg-white/[0.06] text-neutral-500"}`, children: tab.badge })) : null] }, tab.id));
+            }), trailing !== undefined ? _jsx("div", { className: "ml-auto flex items-center gap-1", children: trailing }) : null] }));
+}
+/** Collapsible component card for the inspector and side panels. */
+export function CollapsibleSection({ title, icon, open, onToggle, children, trailing, tone, }) {
+    return (_jsxs("section", { className: "overflow-hidden rounded-[6px] border border-white/[0.07] bg-white/[0.02]", children: [_jsxs("div", { className: "flex h-7.5 items-center gap-1.5 px-1.5", children: [_jsxs("button", { type: "button", "aria-expanded": open, onClick: onToggle, className: `flex min-w-0 flex-1 items-center gap-1.5 rounded-[4px] px-1 py-0.5 text-left ${FOCUS_RING}`, children: [_jsx(Icon, { name: open ? "chevronDown" : "chevronRight", size: 11, className: "shrink-0 text-neutral-500" }), icon !== undefined ? (_jsx(Icon, { name: icon, size: 13, className: "shrink-0 text-neutral-400", style: tone !== undefined ? { color: tone } : undefined })) : null, _jsx("span", { className: "truncate text-[12px] font-medium text-neutral-200", children: title })] }), trailing] }), open ? _jsx("div", { className: "border-t border-white/[0.05] p-2.5", children: children }) : null] }));
+}
+/** Polished empty state used by unsupported workspaces and empty docks. */
+export function EmptyState({ icon, title, description, badge, children, }) {
+    return (_jsxs("div", { className: "flex h-full min-h-0 flex-col items-center justify-center gap-2 p-6 text-center", children: [_jsx("div", { className: "flex h-10 w-10 items-center justify-center rounded-[8px] border border-white/[0.07] bg-white/[0.03] text-neutral-500", children: _jsx(Icon, { name: icon, size: 18 }) }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("div", { className: "text-[12px] font-medium text-neutral-300", children: title }), badge !== undefined ? (_jsx("span", { className: "rounded-full bg-white/[0.06] px-2 py-0.5 text-[9px] font-semibold uppercase tracking-wider text-neutral-500 ring-1 ring-inset ring-white/[0.08]", children: badge })) : null] }), _jsx("p", { className: "max-w-[32ch] text-[11px] leading-relaxed text-neutral-500", children: description }), children] }));
+}
+/** Micro uppercase heading used inside panels. */
+export function PanelHeading({ children, trailing }) {
+    return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("div", { className: MICRO_LABEL, children: children }), trailing !== undefined ? _jsx("div", { className: "ml-auto flex items-center gap-1", children: trailing }) : null] }));
+}
+const RESIZE_KEY_STEP = 16;
+/**
+ * Drag handle between shell regions. Pointer-drag resizes continuously; arrow keys resize in
+ * 16px steps for keyboard access. `sign` maps a positive pointer delta to a size increase.
+ */
+export function PanelResizer({ orientation, label, onResize, sign = 1, }) {
+    const dragState = useRef(null);
+    const onPointerDown = useCallback((event) => {
+        event.preventDefault();
+        event.currentTarget.setPointerCapture(event.pointerId);
+        dragState.current = {
+            pointerId: event.pointerId,
+            last: orientation === "vertical" ? event.clientX : event.clientY,
+        };
+    }, [orientation]);
+    const onPointerMove = useCallback((event) => {
+        const drag = dragState.current;
+        if (drag === null || drag.pointerId !== event.pointerId)
+            return;
+        const position = orientation === "vertical" ? event.clientX : event.clientY;
+        const delta = (position - drag.last) * sign;
+        drag.last = position;
+        if (delta !== 0)
+            onResize(delta);
+    }, [onResize, orientation, sign]);
+    const onPointerUp = useCallback((event) => {
+        if (dragState.current?.pointerId === event.pointerId)
+            dragState.current = null;
+    }, []);
+    const onKeyDown = useCallback((event) => {
+        const grow = orientation === "vertical" ? "ArrowRight" : "ArrowDown";
+        const shrink = orientation === "vertical" ? "ArrowLeft" : "ArrowUp";
+        if (event.key === grow) {
+            event.preventDefault();
+            onResize(RESIZE_KEY_STEP * sign);
+        }
+        else if (event.key === shrink) {
+            event.preventDefault();
+            onResize(-RESIZE_KEY_STEP * sign);
+        }
+    }, [onResize, orientation, sign]);
+    return (_jsx("div", { role: "separator", "aria-label": label, "aria-orientation": orientation, tabIndex: 0, onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: onPointerUp, onKeyDown: onKeyDown, className: `group relative z-10 shrink-0 ${FOCUS_RING} ${orientation === "vertical" ? "w-1 cursor-col-resize" : "h-1 cursor-row-resize"}`, children: _jsx("div", { className: `absolute bg-transparent transition-colors group-hover:bg-cyan-400/40 group-focus-visible:bg-cyan-400/50 ${orientation === "vertical" ? "inset-y-0 left-0 w-1" : "inset-x-0 top-0 h-1"}` }) }));
+}

package/dist/shell/useGlbThumbnail.d.ts

@@ -0,0 +1,8 @@
+import { type ThumbnailState } from "./glbThumbnailCache.js";
+/**
+ * Subscribes to the offscreen GLB thumbnail cache for a model URL.
+ * Without a URL (catalog markers, generators with no mesh) stays idle so the
+ * caller can keep a typed glyph — never invents imagery.
+ * @internal
+ */
+export declare function useGlbThumbnail(url: string | undefined): ThumbnailState;

package/dist/shell/useGlbThumbnail.js

@@ -0,0 +1,19 @@
+import { useSyncExternalStore } from "react";
+import { getGlbThumbnailState, requestGlbThumbnail, subscribeGlbThumbnail, } from "./glbThumbnailCache.js";
+const IDLE = { status: "idle", dataUrl: null };
+/**
+ * Subscribes to the offscreen GLB thumbnail cache for a model URL.
+ * Without a URL (catalog markers, generators with no mesh) stays idle so the
+ * caller can keep a typed glyph — never invents imagery.
+ * @internal
+ */
+export function useGlbThumbnail(url) {
+    const subscribe = (onStoreChange) => {
+        if (url === undefined || url.length === 0)
+            return () => { };
+        requestGlbThumbnail(url);
+        return subscribeGlbThumbnail(url, onStoreChange);
+    };
+    const getSnapshot = () => getGlbThumbnailState(url);
+    return useSyncExternalStore(subscribe, getSnapshot, () => IDLE);
+}

package/dist/terrainReadoutStore.d.ts

@@ -0,0 +1,19 @@
+import type { ElevationReadout, ElevationSummary } from "@jgengine/core/world/terrainGuides";
+/** Live, transient terrain-readability feedback shared by the viewport overlay and the HUD legend. */
+export interface TerrainReadoutState {
+    /** Elevation under the pointer, or `null` when the pointer is off the terrain. */
+    cursor: ElevationReadout | null;
+    /** Elevation stats for the readout region (whole terrain), or `null` before the first build. */
+    summary: ElevationSummary | null;
+    /** The contour interval the overlay chose for the current relief; `0` when flat. */
+    interval: number;
+}
+/** Subscribable store for transient terrain-readout feedback (not persisted — it is live measurement). */
+export interface TerrainReadoutStore {
+    getState(): TerrainReadoutState;
+    setCursor(cursor: ElevationReadout | null): void;
+    setSummary(summary: ElevationSummary | null, interval: number): void;
+    subscribe(listener: () => void): () => void;
+}
+/** Creates the readout store the terrain overlay writes and the HUD reads. */
+export declare function createTerrainReadoutStore(): TerrainReadoutStore;

package/dist/terrainReadoutStore.js

@@ -0,0 +1,36 @@
+/** Creates the readout store the terrain overlay writes and the HUD reads. */
+export function createTerrainReadoutStore() {
+    let state = { cursor: null, summary: null, interval: 0 };
+    const listeners = new Set();
+    const emit = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    return {
+        getState: () => state,
+        setCursor(cursor) {
+            const prev = state.cursor;
+            if (prev === cursor)
+                return;
+            if (prev !== null &&
+                cursor !== null &&
+                prev.height === cursor.height &&
+                prev.x === cursor.x &&
+                prev.z === cursor.z) {
+                return;
+            }
+            state = { ...state, cursor };
+            emit();
+        },
+        setSummary(summary, interval) {
+            state = { ...state, summary, interval };
+            emit();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}