@jgengine/editor 0.10.0 → 0.12.0

package/dist/shell/commandRegistry.d.ts

@@ -0,0 +1,58 @@
+import type { GizmoMode, PlacementTool, SnapMode } from "../uiStore.js";
+import type { BottomDockTab } from "./layoutStore.js";
+/** One executable command-palette entry. */
+export interface PaletteCommand {
+    id: string;
+    title: string;
+    group: string;
+    kbd?: string;
+    keywords?: string;
+    run: () => void;
+}
+/** A scene object the palette can jump to by name/id. */
+export interface PaletteObjectTarget {
+    id: string;
+    label: string;
+    kind: string;
+}
+/** Everything the palette can drive — thin callbacks over existing editor systems. */
+export interface PaletteContext {
+    setGizmoMode(mode: GizmoMode): void;
+    setTool(tool: "select" | "terrain"): void;
+    toggleGrid(): void;
+    toggleContours(): void;
+    toggleSurfaceGrid(): void;
+    toggleElevation(): void;
+    setSnapMode(mode: SnapMode): void;
+    frameAll(): void;
+    frameSelection(): void;
+    undo(): void;
+    redo(): void;
+    save(): void;
+    exportJson(): void;
+    importJson(): void;
+    copyJson(): void;
+    setMode(mode: "play" | "walk" | "hud"): void;
+    startPlacement(tool: PlacementTool): void;
+    openBottomTab(tab: BottomDockTab): void;
+    toggleLeftDock(): void;
+    toggleRightDock(): void;
+    toggleHelp(): void;
+    resetLayout(): void;
+    /** Select + frame a document object by id (jump-to-object). */
+    gotoObject?(id: string): void;
+    /** Live scene objects for object-search rows. */
+    objects?: readonly PaletteObjectTarget[];
+}
+/** Builds the full palette command list from live editor capabilities — no dead entries. */
+export declare function buildPaletteCommands(ctx: PaletteContext): PaletteCommand[];
+/** Loads recent command ids from localStorage (session-shared across games). @internal */
+export declare function loadRecentCommandIds(): string[];
+/** Records a command id at the front of the recent list (deduped, capped). @internal */
+export declare function pushRecentCommandId(id: string): string[];
+/**
+ * Case-insensitive filter over title, group, and keywords.
+ * With an empty query, recent commands (that still exist) float to the top under a virtual order
+ * — the caller groups them visually.
+ */
+export declare function filterPaletteCommands(commands: readonly PaletteCommand[], query: string, recentIds?: readonly string[]): PaletteCommand[];

package/dist/shell/commandRegistry.js

@@ -0,0 +1,133 @@
+import { WELL_KNOWN_MARKER_KINDS } from "@jgengine/core/editor/index";
+import { listSceneKinds } from "@jgengine/core/scene/sceneKinds";
+/** Builds the full palette command list from live editor capabilities — no dead entries. */
+export function buildPaletteCommands(ctx) {
+    const commands = [
+        { id: "tool.select", title: "Select tool", group: "Tools", run: () => ctx.setTool("select") },
+        { id: "tool.terrain", title: "Terrain sculpt/paint tool", group: "Tools", kbd: "T", run: () => ctx.setTool("terrain") },
+        { id: "gizmo.translate", title: "Move gizmo", group: "Tools", kbd: "W", run: () => ctx.setGizmoMode("translate") },
+        { id: "gizmo.rotate", title: "Rotate gizmo", group: "Tools", kbd: "E", run: () => ctx.setGizmoMode("rotate") },
+        { id: "gizmo.scale", title: "Scale gizmo", group: "Tools", kbd: "R", run: () => ctx.setGizmoMode("scale") },
+        { id: "snap.ground", title: "Snap to ground", group: "Snapping", run: () => ctx.setSnapMode("ground") },
+        { id: "snap.grid", title: "Snap to grid", group: "Snapping", run: () => ctx.setSnapMode("grid") },
+        { id: "snap.off", title: "Snapping off", group: "Snapping", run: () => ctx.setSnapMode("off") },
+        { id: "view.grid", title: "Toggle reference grid", group: "View", kbd: "G", run: () => ctx.toggleGrid() },
+        { id: "view.contours", title: "Toggle elevation contours", group: "View", run: () => ctx.toggleContours() },
+        { id: "view.drape", title: "Toggle terrain-draped grid", group: "View", run: () => ctx.toggleSurfaceGrid() },
+        { id: "view.elevation", title: "Toggle elevation readout", group: "View", run: () => ctx.toggleElevation() },
+        { id: "view.frameAll", title: "Frame whole scene", group: "View", kbd: "F", run: () => ctx.frameAll() },
+        { id: "view.frameSelection", title: "Frame selection", group: "View", kbd: "F", run: () => ctx.frameSelection() },
+        { id: "edit.undo", title: "Undo", group: "Edit", kbd: "Ctrl+Z", run: () => ctx.undo() },
+        { id: "edit.redo", title: "Redo", group: "Edit", kbd: "Ctrl+Y", run: () => ctx.redo() },
+        { id: "doc.save", title: "Save scene", group: "Document", kbd: "Ctrl+S", run: () => ctx.save() },
+        { id: "doc.export", title: "Export scene JSON", group: "Document", run: () => ctx.exportJson() },
+        { id: "doc.import", title: "Import scene JSON…", group: "Document", run: () => ctx.importJson() },
+        { id: "doc.copy", title: "Copy scene JSON to clipboard", group: "Document", run: () => ctx.copyJson() },
+        { id: "mode.play", title: "Enter Play mode", group: "Modes", kbd: "F2+E", run: () => ctx.setMode("play") },
+        { id: "mode.walk", title: "Enter Walk mode", group: "Modes", run: () => ctx.setMode("walk") },
+        { id: "mode.hud", title: "Lay out HUD panels", group: "Modes", run: () => ctx.setMode("hud") },
+        { id: "panel.content", title: "Open Content Browser", group: "Panels", kbd: "Ctrl+B", run: () => ctx.openBottomTab("content") },
+        { id: "panel.console", title: "Open Console", group: "Panels", run: () => ctx.openBottomTab("console") },
+        { id: "panel.profiler", title: "Open Profiler", group: "Panels", run: () => ctx.openBottomTab("profiler") },
+        { id: "panel.animation", title: "Open Animation (path flythrough)", group: "Panels", keywords: "timeline path scrub", run: () => ctx.openBottomTab("animation") },
+        { id: "panel.assistant", title: "Open AI Assistant", group: "Panels", run: () => ctx.openBottomTab("assistant") },
+        { id: "panel.left", title: "Toggle hierarchy panel", group: "Panels", run: () => ctx.toggleLeftDock() },
+        { id: "panel.right", title: "Toggle inspector panel", group: "Panels", run: () => ctx.toggleRightDock() },
+        { id: "panel.resetLayout", title: "Reset layout to defaults", group: "Panels", run: () => ctx.resetLayout() },
+        { id: "help.shortcuts", title: "Keyboard shortcuts", group: "Help", kbd: "?", run: () => ctx.toggleHelp() },
+    ];
+    for (const kind of WELL_KNOWN_MARKER_KINDS) {
+        commands.push({
+            id: `add.marker.${kind}`,
+            title: `Add marker: ${kind}`,
+            group: "Add",
+            keywords: "place create marker",
+            run: () => ctx.startPlacement({ tool: "marker", kind }),
+        });
+    }
+    for (const definition of listSceneKinds()) {
+        if (definition.addCategory === undefined)
+            continue;
+        commands.push({
+            id: `add.studio.${definition.kind}`,
+            title: `Add ${definition.label}`,
+            group: "Add",
+            keywords: "place create studio",
+            run: () => ctx.startPlacement(definition.target === "path"
+                ? { tool: "path", kind: definition.kind }
+                : definition.target === "volume"
+                    ? { tool: "volume", kind: definition.kind, shape: "box" }
+                    : { tool: "marker", kind: definition.kind }),
+        });
+    }
+    commands.push({ id: "add.path", title: "Draw path (route)", group: "Add", keywords: "place create", run: () => ctx.startPlacement({ tool: "path", kind: "route" }) }, { id: "add.road", title: "Draw road", group: "Add", keywords: "place create", run: () => ctx.startPlacement({ tool: "path", kind: "road" }) }, { id: "add.zone", title: "Add zone volume", group: "Add", keywords: "place create volume", run: () => ctx.startPlacement({ tool: "volume", kind: "zone", shape: "sphere" }) }, { id: "add.note", title: "Add note", group: "Add", keywords: "place create annotation", run: () => ctx.startPlacement({ tool: "note" }) });
+    if (ctx.gotoObject !== undefined && ctx.objects !== undefined) {
+        for (const object of ctx.objects) {
+            commands.push({
+                id: `goto.object.${object.id}`,
+                title: object.label,
+                group: "Objects",
+                keywords: `jump goto select frame ${object.kind} ${object.id}`,
+                run: () => ctx.gotoObject(object.id),
+            });
+        }
+    }
+    return commands;
+}
+const RECENT_KEY = "jgeditor:palette-recent";
+const RECENT_LIMIT = 8;
+/** Loads recent command ids from localStorage (session-shared across games). @internal */
+export function loadRecentCommandIds() {
+    try {
+        const raw = localStorage.getItem(RECENT_KEY);
+        if (raw === null)
+            return [];
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((entry) => typeof entry === "string").slice(0, RECENT_LIMIT);
+    }
+    catch {
+        return [];
+    }
+}
+/** Records a command id at the front of the recent list (deduped, capped). @internal */
+export function pushRecentCommandId(id) {
+    // Object jump rows are scene-specific and flood the recent list — skip them.
+    if (id.startsWith("goto.object."))
+        return loadRecentCommandIds();
+    const next = [id, ...loadRecentCommandIds().filter((entry) => entry !== id)].slice(0, RECENT_LIMIT);
+    try {
+        localStorage.setItem(RECENT_KEY, JSON.stringify(next));
+    }
+    catch {
+        // ignore quota / private mode
+    }
+    return next;
+}
+/**
+ * Case-insensitive filter over title, group, and keywords.
+ * With an empty query, recent commands (that still exist) float to the top under a virtual order
+ * — the caller groups them visually.
+ */
+export function filterPaletteCommands(commands, query, recentIds = []) {
+    const needle = query.trim().toLowerCase();
+    if (needle.length === 0) {
+        if (recentIds.length === 0)
+            return [...commands];
+        const byId = new Map(commands.map((command) => [command.id, command]));
+        const recent = [];
+        for (const id of recentIds) {
+            const command = byId.get(id);
+            if (command !== undefined)
+                recent.push({ ...command, group: "Recent" });
+        }
+        const recentSet = new Set(recent.map((command) => command.id));
+        return [...recent, ...commands.filter((command) => !recentSet.has(command.id))];
+    }
+    const terms = needle.split(/\s+/);
+    return commands.filter((command) => {
+        const haystack = `${command.title} ${command.group} ${command.keywords ?? ""}`.toLowerCase();
+        return terms.every((term) => haystack.includes(term));
+    });
+}

package/dist/shell/consoleSink.d.ts

@@ -0,0 +1,11 @@
+import type { ConsoleSeverity } from "./consoleStore.js";
+type ConsoleSink = (severity: ConsoleSeverity, source: string, message: string) => void;
+/**
+ * Installs the global console sink (typically the dock console store). Returns a disposer that
+ * clears the sink only if it still points at this callback.
+ * @internal
+ */
+export declare function installEditorConsoleSink(next: ConsoleSink): () => void;
+/** Forwards a real editor event to the installed console sink, if any. @internal */
+export declare function emitEditorConsole(severity: ConsoleSeverity, source: string, message: string): void;
+export {};

package/dist/shell/consoleSink.js

@@ -0,0 +1,17 @@
+let sink = null;
+/**
+ * Installs the global console sink (typically the dock console store). Returns a disposer that
+ * clears the sink only if it still points at this callback.
+ * @internal
+ */
+export function installEditorConsoleSink(next) {
+    sink = next;
+    return () => {
+        if (sink === next)
+            sink = null;
+    };
+}
+/** Forwards a real editor event to the installed console sink, if any. @internal */
+export function emitEditorConsole(severity, source, message) {
+    sink?.(severity, source, message);
+}

package/dist/shell/consoleStore.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Bounded editor event log backing the Console dock tab. Only real editor events are recorded —
+ * notifications, save/import/export results, RPC and agent errors — never fabricated runtime logs.
+ */
+/** Console entry severity, driving the filter chips and row tinting. */
+export type ConsoleSeverity = "info" | "warning" | "error";
+/** One recorded editor event. */
+export interface ConsoleEntry {
+    id: number;
+    at: number;
+    severity: ConsoleSeverity;
+    /** Which editor subsystem produced the event (ui, save, import, agent, rpc). */
+    source: string;
+    message: string;
+}
+/** Subscribable, bounded editor event log. */
+export interface EditorConsoleStore {
+    getEntries(): readonly ConsoleEntry[];
+    log(severity: ConsoleSeverity, source: string, message: string): void;
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    counts(): Record<ConsoleSeverity, number>;
+}
+/** Entries kept before the oldest are dropped. */
+export declare const CONSOLE_CAPACITY = 500;
+/** Creates the editor console store. `now` is injectable for tests. */
+export declare function createEditorConsoleStore(now?: () => number): EditorConsoleStore;

package/dist/shell/consoleStore.js

@@ -0,0 +1,43 @@
+/**
+ * Bounded editor event log backing the Console dock tab. Only real editor events are recorded —
+ * notifications, save/import/export results, RPC and agent errors — never fabricated runtime logs.
+ */
+/** Entries kept before the oldest are dropped. */
+export const CONSOLE_CAPACITY = 500;
+/** Creates the editor console store. `now` is injectable for tests. */
+export function createEditorConsoleStore(now = () => Date.now()) {
+    let entries = [];
+    let nextId = 1;
+    const listeners = new Set();
+    const emit = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    return {
+        getEntries: () => entries,
+        log(severity, source, message) {
+            entries = [...entries, { id: nextId++, at: now(), severity, source, message }];
+            if (entries.length > CONSOLE_CAPACITY)
+                entries = entries.slice(entries.length - CONSOLE_CAPACITY);
+            emit();
+        },
+        clear() {
+            if (entries.length === 0)
+                return;
+            entries = [];
+            emit();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        counts() {
+            const counts = { info: 0, warning: 0, error: 0 };
+            for (const entry of entries)
+                counts[entry.severity] += 1;
+            return counts;
+        },
+    };
+}

package/dist/shell/fields.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Polished numeric field with an axis-colored label chip. The whole field is a drag-scrub
+ * surface (not just the chip): horizontal pointer-drag adjusts by `step` per few pixels while
+ * Alt/Option or double-click focuses the input for precise typing. The input commits finite
+ * values on change and re-normalizes its text on blur. Invalid text never commits.
+ */
+export declare function AxisNumberField({ axis, label, value, onCommit, step, precision, disabled, mixed, }: {
+    /** Axis coloring; omit for a neutral field. */
+    axis?: "x" | "y" | "z";
+    label: string;
+    value: number;
+    onCommit: (value: number) => void;
+    step?: number;
+    precision?: number;
+    disabled?: boolean;
+    /** Multi-select mixed values: show an em dash until the user commits a concrete number. */
+    mixed?: boolean;
+}): import("react").JSX.Element;
+/** Labeled row wrapper aligning a caption with one or more fields. */
+export declare function FieldRow({ label, children, title }: {
+    label: string;
+    children: React.ReactNode;
+    title?: string;
+}): import("react").JSX.Element;
+/** Compact text input row used by the inspector header and component cards. */
+export declare function TextField({ label, value, placeholder, onCommit, }: {
+    label: string;
+    value: string;
+    placeholder?: string;
+    onCommit: (value: string) => void;
+}): import("react").JSX.Element;
+/** Small ghost action used inside section headers (reset, link). */
+export declare function SectionAction({ label, onClick, active, disabled, children, }: {
+    label: string;
+    onClick: () => void;
+    active?: boolean;
+    disabled?: boolean;
+    children: React.ReactNode;
+}): import("react").JSX.Element;

package/dist/shell/fields.js

@@ -0,0 +1,104 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { AXIS_COLORS, FOCUS_RING, INPUT_CLS, NUMERIC } from "./theme.js";
+/** Pixels of pointer drag per `step` of value change when scrubbing an axis chip. */
+const DRAG_PX_PER_STEP = 4;
+function formatValue(value, precision) {
+    const fixed = value.toFixed(precision);
+    // Trim trailing zeros but keep at least one decimal digit ("1.50" -> "1.5", "2.00" -> "2").
+    return fixed.replace(/\.?0+$/, "") || "0";
+}
+/**
+ * Polished numeric field with an axis-colored label chip. The whole field is a drag-scrub
+ * surface (not just the chip): horizontal pointer-drag adjusts by `step` per few pixels while
+ * Alt/Option or double-click focuses the input for precise typing. The input commits finite
+ * values on change and re-normalizes its text on blur. Invalid text never commits.
+ */
+export function AxisNumberField({ axis, label, value, onCommit, step = 0.1, precision = 3, disabled = false, mixed = false, }) {
+    const [text, setText] = useState(() => (mixed ? "—" : formatValue(value, precision)));
+    const [editing, setEditing] = useState(false);
+    const inputRef = useRef(null);
+    const dragRef = useRef(null);
+    useEffect(() => {
+        if (!editing)
+            setText(mixed ? "—" : formatValue(value, precision));
+    }, [value, precision, editing, mixed]);
+    const commitText = (raw) => {
+        if (raw === "—" || raw.trim().length === 0)
+            return;
+        const next = Number(raw);
+        if (Number.isFinite(next) && (mixed || next !== value))
+            onCommit(next);
+    };
+    const onScrubPointerDown = (event) => {
+        if (disabled || editing)
+            return;
+        // Alt/Option starts text edit instead of scrubbing.
+        if (event.altKey) {
+            inputRef.current?.focus();
+            inputRef.current?.select();
+            return;
+        }
+        event.preventDefault();
+        event.currentTarget.setPointerCapture(event.pointerId);
+        // Scrub from the first selected value when mixed — committing absolute values to all.
+        dragRef.current = { pointerId: event.pointerId, startX: event.clientX, startValue: value, moved: false };
+    };
+    const onScrubPointerMove = (event) => {
+        const drag = dragRef.current;
+        if (drag === null || drag.pointerId !== event.pointerId)
+            return;
+        const deltaSteps = Math.round((event.clientX - drag.startX) / DRAG_PX_PER_STEP);
+        if (deltaSteps === 0 && !drag.moved)
+            return;
+        drag.moved = true;
+        const next = drag.startValue + deltaSteps * step;
+        const rounded = Number(next.toFixed(precision));
+        if (rounded !== value)
+            onCommit(rounded);
+    };
+    const onScrubPointerUp = (event) => {
+        const drag = dragRef.current;
+        if (drag === null || drag.pointerId !== event.pointerId)
+            return;
+        dragRef.current = null;
+        // Click without drag focuses the input for precise typing (whole-field scrub UX).
+        if (!drag.moved) {
+            inputRef.current?.focus();
+            inputRef.current?.select();
+        }
+    };
+    const colors = axis !== undefined ? AXIS_COLORS[axis] : null;
+    return (_jsxs("label", { title: `Drag to adjust ${label} · Alt-click or focus input to type`, onPointerDown: onScrubPointerDown, onPointerMove: onScrubPointerMove, onPointerUp: onScrubPointerUp, className: `flex min-w-0 flex-1 cursor-ew-resize items-center overflow-hidden rounded-[5px] border border-white/[0.08] bg-black/30 focus-within:border-cyan-400/50 ${editing ? "cursor-text" : ""}`, children: [_jsxs("span", { className: `relative flex h-6.5 w-6 shrink-0 select-none items-center justify-center border-r border-white/[0.06] bg-white/[0.03] text-[10px] font-semibold uppercase ${colors !== null ? colors.text : "text-neutral-500"}`, children: [colors !== null ? _jsx("span", { className: `absolute inset-y-0 left-0 w-0.5 ${colors.bar}` }) : null, label] }), _jsx("input", { ref: inputRef, type: "text", inputMode: "decimal", value: text, disabled: disabled, "aria-label": label, onFocus: () => setEditing(true), onDoubleClick: (event) => {
+                    event.stopPropagation();
+                    event.currentTarget.select();
+                }, onChange: (event) => {
+                    setText(event.target.value);
+                    commitText(event.target.value);
+                }, onBlur: (event) => {
+                    setEditing(false);
+                    commitText(event.target.value);
+                    setText(formatValue(Number.isFinite(Number(event.target.value)) ? Number(event.target.value) : value, precision));
+                }, onKeyDown: (event) => {
+                    if (event.key === "Enter")
+                        event.currentTarget.blur();
+                    if (event.key === "ArrowUp" || event.key === "ArrowDown") {
+                        event.preventDefault();
+                        const direction = event.key === "ArrowUp" ? 1 : -1;
+                        const next = Number((value + direction * step).toFixed(precision));
+                        onCommit(next);
+                    }
+                }, className: `h-6.5 w-full min-w-0 cursor-text bg-transparent px-1.5 text-right text-[11px] text-neutral-200 outline-none ${NUMERIC} disabled:opacity-40` })] }));
+}
+/** Labeled row wrapper aligning a caption with one or more fields. */
+export function FieldRow({ label, children, title }) {
+    return (_jsxs("div", { className: "flex items-center gap-2", title: title, children: [_jsx("span", { className: "w-16 shrink-0 text-[10px] text-neutral-500", children: label }), _jsx("div", { className: "flex min-w-0 flex-1 items-center gap-1", children: children })] }));
+}
+/** Compact text input row used by the inspector header and component cards. */
+export function TextField({ label, value, placeholder, onCommit, }) {
+    return (_jsx(FieldRow, { label: label, children: _jsx("input", { className: `h-6.5 w-full min-w-0 px-2 ${INPUT_CLS}`, value: value, placeholder: placeholder, "aria-label": label, onChange: (event) => onCommit(event.target.value) }) }));
+}
+/** Small ghost action used inside section headers (reset, link). */
+export function SectionAction({ label, onClick, active = false, disabled = false, children, }) {
+    return (_jsx("button", { type: "button", title: label, "aria-label": label, "aria-pressed": active, disabled: disabled, onClick: onClick, className: `flex h-5 items-center justify-center rounded-[4px] px-1 text-[10px] transition-colors ${FOCUS_RING} ${active ? "bg-cyan-500/20 text-cyan-200" : "text-neutral-500 hover:bg-white/[0.08] hover:text-neutral-200"} disabled:pointer-events-none disabled:opacity-35`, children: children }));
+}

package/dist/shell/formatSavedRelative.d.ts

@@ -0,0 +1,2 @@
+/** Formats a past timestamp as a short relative phrase ("just now", "2m ago", "3h ago"). @internal */
+export declare function formatSavedRelative(savedAtMs: number, nowMs?: number): string;

package/dist/shell/formatSavedRelative.js

@@ -0,0 +1,14 @@
+/** Formats a past timestamp as a short relative phrase ("just now", "2m ago", "3h ago"). @internal */
+export function formatSavedRelative(savedAtMs, nowMs = Date.now()) {
+    const elapsedSec = Math.max(0, Math.floor((nowMs - savedAtMs) / 1000));
+    if (elapsedSec < 45)
+        return "just now";
+    const elapsedMin = Math.floor(elapsedSec / 60);
+    if (elapsedMin < 60)
+        return `${elapsedMin}m ago`;
+    const elapsedHr = Math.floor(elapsedMin / 60);
+    if (elapsedHr < 48)
+        return `${elapsedHr}h ago`;
+    const elapsedDay = Math.floor(elapsedHr / 24);
+    return `${elapsedDay}d ago`;
+}

package/dist/shell/glbThumbnailCache.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Offscreen GLB → PNG thumbnail cache for the Content Browser.
+ * Renders real model bytes once per URL into a data URL; never invents screenshots.
+ * Failures stay honest (glyph fallback). Bounded concurrency + cache eviction keep
+ * the editor from thrashing WebGL or retaining unbounded GPU memory.
+ * @internal
+ */
+import * as THREE from "three";
+/** Lifecycle of one GLB thumbnail render: idle → loading → ready, or error. */
+export type ThumbnailStatus = "idle" | "loading" | "ready" | "error";
+/** Cache entry for one asset's thumbnail: status plus the data URL when ready. */
+export interface ThumbnailState {
+    status: ThumbnailStatus;
+    /** `data:image/png;base64,…` when ready; otherwise null. */
+    dataUrl: string | null;
+}
+/** @internal */
+export declare function setGlbThumbnailLoader(fn: (url: string) => Promise<THREE.Object3D>): void;
+/** @internal Restore production loader after tests. */
+export declare function resetGlbThumbnailLoader(): void;
+/** @internal Clear cache + dispose GPU resources (tests / hot dispose). */
+export declare function clearGlbThumbnailCache(): void;
+/**
+ * Place the camera so the object's bounding sphere fills most of the frame from a
+ * consistent three-quarter angle. Pure math — unit-tested without WebGL.
+ * @internal
+ */
+export declare function frameCameraForBounds(box: THREE.Box3, camera: THREE.PerspectiveCamera, size?: number): void;
+/**
+ * Snapshot of cache state for a model URL. Does not start a render — call
+ * {@link requestGlbThumbnail} first (the React hook does both).
+ * @internal
+ */
+export declare function getGlbThumbnailState(url: string | undefined): ThumbnailState;
+/**
+ * Ensures a thumbnail render is in flight (or already cached) for `url`.
+ * Safe to call repeatedly; concurrent callers share one load.
+ * @internal
+ */
+export declare function requestGlbThumbnail(url: string): void;
+/**
+ * Subscribe to thumbnail state changes for a URL. Returns an unsubscribe.
+ * @internal
+ */
+export declare function subscribeGlbThumbnail(url: string | undefined, listener: () => void): () => void;