@jgengine/editor 0.10.0

package/dist/uiStore.d.ts

@@ -0,0 +1,108 @@
+import type { EditorSession, EditorVec3, EditorVolumeShape } from "@jgengine/core/editor/index";
+import type { TerraformFalloff, TerraformShape } from "@jgengine/core/world/terraform";
+/** Which top-level editor tool is active: object placement/selection, or terrain sculpting. */
+export type EditorTool = "select" | "terrain";
+/** A heightfield sculpt brush the terrain tool can apply. */
+export type TerrainBrushKind = "raise" | "lower" | "smooth" | "flatten" | "noise" | "ramp";
+/** The terrain tool's active sub-mode: reshape the heightfield, or paint material layers onto it. */
+export type TerrainMode = "sculpt" | "paint";
+/** A paintable terrain material layer — a surface id plus the color it renders as. */
+export interface TerrainMaterial {
+    id: string;
+    label: string;
+    color: string;
+}
+/** The default terrain paint palette (surface id → color) shared by the panel and the mesh. */
+export declare const TERRAIN_MATERIALS: readonly TerrainMaterial[];
+/** Maps every default material id to its render color, for the sculpt mesh's per-cell surface tint. */
+export declare const TERRAIN_MATERIAL_COLORS: Record<string, string>;
+/** Live terrain material-paint controls driven by the terrain tool panel. */
+export interface PaintSettings {
+    material: string;
+    radius: number;
+    shape: TerraformShape;
+}
+/** The terrain tool's default paint controls. */
+export declare const DEFAULT_PAINT_SETTINGS: PaintSettings;
+/** Live terrain-brush controls driven by the terrain tool panel. */
+export interface SculptSettings {
+    brush: TerrainBrushKind;
+    radius: number;
+    strength: number;
+    falloff: TerraformFalloff;
+    shape: TerraformShape;
+    /** Stamp spacing (world units) along a drag — smaller = denser strokes. */
+    spacing: number;
+    /** Flatten target; `null` samples the ground height under the first click. */
+    flattenHeight: number | null;
+    noiseSeed: number;
+    /** Invert modifier — flips raise↔lower for the active brush. */
+    invert: boolean;
+    heightLimit: {
+        min: number | null;
+        max: number | null;
+    };
+}
+/** The terrain tool's default brush controls. */
+export declare const DEFAULT_SCULPT_SETTINGS: SculptSettings;
+/** Which transform gizmo is active for the current selection. */
+export type GizmoMode = "translate" | "rotate" | "scale";
+/** How gizmo drags land: stick to terrain height, quantize to a grid, or free. */
+export type SnapMode = "ground" | "grid" | "off";
+/** The active creation tool — what a viewport click places next. */
+export type PlacementTool = {
+    tool: "marker";
+    kind: string;
+} | {
+    tool: "volume";
+    kind: string;
+    shape: EditorVolumeShape;
+} | {
+    tool: "note";
+} | {
+    tool: "path";
+    kind: string;
+};
+/** @internal Open viewport context menu state (#866); null when closed. */
+export interface EditorContextMenuState {
+    clientX: number;
+    clientY: number;
+    hitId: string | null;
+    ground: EditorVec3 | null;
+}
+/** Transient editor UI state shared between chrome, viewport, and gizmos. */
+export interface EditorUiState {
+    gizmoMode: GizmoMode;
+    snapMode: SnapMode;
+    gridSize: number;
+    showGrid: boolean;
+    placement: PlacementTool | null;
+    pathDraft: readonly EditorVec3[];
+    pathPoint: {
+        pathId: string;
+        index: number;
+    } | null;
+    tool: EditorTool;
+    terrainMode: TerrainMode;
+    sculpt: SculptSettings;
+    paint: PaintSettings;
+    contextMenu: EditorContextMenuState | null;
+}
+/** Subscribable store for the editor's transient UI state (gizmo, snapping, placement). */
+export interface EditorUiStore {
+    getState(): EditorUiState;
+    patch(partial: Partial<EditorUiState>): void;
+    subscribe(listener: () => void): () => void;
+    startPlacement(tool: PlacementTool): void;
+    cancelPlacement(): void;
+    pushDraftPoint(point: EditorVec3): void;
+    commitPathDraft(session: EditorSession): void;
+    setTool(tool: EditorTool): void;
+    setTerrainMode(mode: TerrainMode): void;
+    patchSculpt(partial: Partial<SculptSettings>): void;
+    patchPaint(partial: Partial<PaintSettings>): void;
+}
+/** Creates the shared UI store the editor chrome and viewport both drive. */
+export declare function createEditorUiStore(): EditorUiStore;
+/** Generates a fresh scene-object id for a placement tool click. */
+export declare function newPlacementId(prefix: string): string;

package/dist/uiStore.js

@@ -0,0 +1,128 @@
+/** The default terrain paint palette (surface id → color) shared by the panel and the mesh. */
+export const TERRAIN_MATERIALS = [
+    { id: "grass", label: "Grass", color: "#4b7f3f" },
+    { id: "dirt", label: "Dirt", color: "#6b4f34" },
+    { id: "rock", label: "Rock", color: "#7c7f86" },
+    { id: "sand", label: "Sand", color: "#c2b283" },
+    { id: "mud", label: "Mud", color: "#574433" },
+    { id: "snow", label: "Snow", color: "#eef3f7" },
+    { id: "road", label: "Road", color: "#3a3a3d" },
+    { id: "gravel", label: "Gravel", color: "#8d8d84" },
+];
+/** Maps every default material id to its render color, for the sculpt mesh's per-cell surface tint. */
+export const TERRAIN_MATERIAL_COLORS = Object.fromEntries(TERRAIN_MATERIALS.map((material) => [material.id, material.color]));
+/** The terrain tool's default paint controls. */
+export const DEFAULT_PAINT_SETTINGS = {
+    material: "grass",
+    radius: 12,
+    shape: "circle",
+};
+/** The terrain tool's default brush controls. */
+export const DEFAULT_SCULPT_SETTINGS = {
+    brush: "raise",
+    radius: 12,
+    strength: 1,
+    falloff: "smooth",
+    shape: "circle",
+    spacing: 2,
+    flattenHeight: null,
+    noiseSeed: 1337,
+    invert: false,
+    heightLimit: { min: null, max: null },
+};
+function placementId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.floor(Math.random() * 1296).toString(36)}`;
+}
+/** Creates the shared UI store the editor chrome and viewport both drive. */
+export function createEditorUiStore() {
+    let state = {
+        gizmoMode: "translate",
+        snapMode: "ground",
+        gridSize: 1,
+        showGrid: true,
+        placement: null,
+        pathDraft: [],
+        pathPoint: null,
+        tool: "select",
+        terrainMode: "sculpt",
+        sculpt: { ...DEFAULT_SCULPT_SETTINGS },
+        paint: { ...DEFAULT_PAINT_SETTINGS },
+        contextMenu: null,
+    };
+    const listeners = new Set();
+    const emit = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    const store = {
+        getState: () => state,
+        patch(partial) {
+            state = { ...state, ...partial };
+            emit();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        startPlacement(tool) {
+            state = { ...state, placement: tool, pathDraft: [], pathPoint: null };
+            emit();
+        },
+        cancelPlacement() {
+            if (state.placement === null && state.pathDraft.length === 0)
+                return;
+            state = { ...state, placement: null, pathDraft: [] };
+            emit();
+        },
+        pushDraftPoint(point) {
+            state = { ...state, pathDraft: [...state.pathDraft, point] };
+            emit();
+        },
+        commitPathDraft(session) {
+            const placement = state.placement;
+            if (placement === null || placement.tool !== "path" || state.pathDraft.length < 2) {
+                store.cancelPlacement();
+                return;
+            }
+            session.dispatch({
+                type: "addPath",
+                path: {
+                    id: placementId(placement.kind),
+                    kind: placement.kind,
+                    points: state.pathDraft.map((point) => ({ ...point })),
+                    width: 4,
+                },
+            });
+            state = { ...state, placement: null, pathDraft: [] };
+            emit();
+        },
+        setTool(tool) {
+            if (state.tool === tool)
+                return;
+            // Leaving/entering the terrain tool clears any half-finished placement.
+            state = { ...state, tool, placement: null, pathDraft: [] };
+            emit();
+        },
+        patchSculpt(partial) {
+            state = { ...state, sculpt: { ...state.sculpt, ...partial } };
+            emit();
+        },
+        setTerrainMode(mode) {
+            if (state.terrainMode === mode)
+                return;
+            state = { ...state, terrainMode: mode };
+            emit();
+        },
+        patchPaint(partial) {
+            state = { ...state, paint: { ...state.paint, ...partial } };
+            emit();
+        },
+    };
+    return store;
+}
+/** Generates a fresh scene-object id for a placement tool click. */
+export function newPlacementId(prefix) {
+    return placementId(prefix);
+}

package/dist/useF2Chord.d.ts

@@ -0,0 +1,2 @@
+/** Listens for the engine's F2+<key> chord family and fires on the given code (e.g. "KeyE"). */
+export declare function useF2Chord(code: string, onChord: () => void): void;

package/dist/useF2Chord.js

@@ -0,0 +1,32 @@
+import { useEffect } from "react";
+/** Listens for the engine's F2+<key> chord family and fires on the given code (e.g. "KeyE"). */
+export function useF2Chord(code, onChord) {
+    useEffect(() => {
+        let f2Held = false;
+        const onKeyDown = (event) => {
+            if (event.code === "F2") {
+                f2Held = true;
+                return;
+            }
+            if (event.code === code && f2Held) {
+                event.preventDefault();
+                onChord();
+            }
+        };
+        const onKeyUp = (event) => {
+            if (event.code === "F2")
+                f2Held = false;
+        };
+        const onBlur = () => {
+            f2Held = false;
+        };
+        window.addEventListener("keydown", onKeyDown);
+        window.addEventListener("keyup", onKeyUp);
+        window.addEventListener("blur", onBlur);
+        return () => {
+            window.removeEventListener("keydown", onKeyDown);
+            window.removeEventListener("keyup", onKeyUp);
+            window.removeEventListener("blur", onBlur);
+        };
+    }, [code, onChord]);
+}

package/dist/useStoreSelector.d.ts

@@ -0,0 +1,31 @@
+/** The minimal external-store shape both the editor session and UI store satisfy. */
+export interface SubscribableStore<S> {
+    getState(): S;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Subscribe a component to a **selected slice** of an external store (editor session or UI store)
+ * via `useSyncExternalStore`. The component re-renders only when `selector`'s output changes by
+ * `isEqual` (default `Object.is`) — a gizmo drag no longer rerenders panels that read an unrelated
+ * slice. The selected value is memoized so an equal slice keeps its reference (no render churn).
+ */
+export declare function useStoreSelector<S, T>(store: SubscribableStore<S>, selector: (state: S) => T, isEqual?: (a: T, b: T) => boolean): T;
+/** Shallow array equality — for selectors that return id lists (`selection`) or small tuples. */
+export declare function shallowArrayEqual<T>(a: readonly T[], b: readonly T[]): boolean;
+/** The visible slice of a fixed-row-height list: which rows to mount and the spacer geometry. */
+export interface VirtualWindow {
+    /** First row index to render (inclusive). */
+    start: number;
+    /** Last row index to render (exclusive). */
+    end: number;
+    /** Pixel height of the spacer above the first rendered row. */
+    offsetTop: number;
+    /** Total scroll height of the full list. */
+    totalHeight: number;
+}
+/**
+ * Pure windowing math for a fixed-row-height virtual list: given the scroll offset and viewport,
+ * returns the `[start, end)` row range to mount (padded by `overscan`) plus the spacer heights, so
+ * a 10,000-row outliner only ever mounts the visible handful. No DOM, unit-testable.
+ */
+export declare function virtualWindow(scrollTop: number, viewportHeight: number, rowHeight: number, rowCount: number, overscan?: number): VirtualWindow;

package/dist/useStoreSelector.js

@@ -0,0 +1,51 @@
+import { useCallback, useRef, useSyncExternalStore } from "react";
+/**
+ * Subscribe a component to a **selected slice** of an external store (editor session or UI store)
+ * via `useSyncExternalStore`. The component re-renders only when `selector`'s output changes by
+ * `isEqual` (default `Object.is`) — a gizmo drag no longer rerenders panels that read an unrelated
+ * slice. The selected value is memoized so an equal slice keeps its reference (no render churn).
+ */
+export function useStoreSelector(store, selector, isEqual = Object.is) {
+    const cache = useRef(null);
+    const selectorRef = useRef(selector);
+    selectorRef.current = selector;
+    const equalRef = useRef(isEqual);
+    equalRef.current = isEqual;
+    const subscribe = useCallback((onChange) => store.subscribe(onChange), [store]);
+    const getSnapshot = useCallback(() => {
+        const next = selectorRef.current(store.getState());
+        if (cache.current !== null && equalRef.current(cache.current.value, next))
+            return cache.current.value;
+        cache.current = { value: next };
+        return next;
+    }, [store]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+/** Shallow array equality — for selectors that return id lists (`selection`) or small tuples. */
+export function shallowArrayEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * Pure windowing math for a fixed-row-height virtual list: given the scroll offset and viewport,
+ * returns the `[start, end)` row range to mount (padded by `overscan`) plus the spacer heights, so
+ * a 10,000-row outliner only ever mounts the visible handful. No DOM, unit-testable.
+ */
+export function virtualWindow(scrollTop, viewportHeight, rowHeight, rowCount, overscan = 6) {
+    const totalHeight = rowCount * rowHeight;
+    if (rowCount <= 0 || rowHeight <= 0 || viewportHeight <= 0) {
+        return { start: 0, end: rowCount, offsetTop: 0, totalHeight };
+    }
+    const clampedScroll = Math.max(0, Math.min(scrollTop, Math.max(0, totalHeight - viewportHeight)));
+    const first = Math.floor(clampedScroll / rowHeight);
+    const visible = Math.ceil(viewportHeight / rowHeight);
+    const start = Math.max(0, first - overscan);
+    const end = Math.min(rowCount, first + visible + overscan);
+    return { start, end, offsetTop: start * rowHeight, totalHeight };
+}

package/dist/viewportContextMenu.d.ts

@@ -0,0 +1,24 @@
+/** @internal Movement below this (px) counts as a click; above is a camera drag (#866). */
+export declare const RIGHT_CLICK_SLOP_PX = 4;
+/** @internal True when the pointer released within the drag-vs-click threshold of its down position. */
+export declare function isPointerClick(startX: number, startY: number, endX: number, endY: number, thresholdPx?: number): boolean;
+/** @internal One entry in the editor viewport context menu. */
+export type EditorContextActionId = "frame" | "frameAll" | "duplicate" | "delete" | "createPrefab" | "copy" | "paste" | "addMarker" | "addVolume" | "addPath" | "addNote" | "openAssets";
+/** @internal Label + id for one editor context-menu verb. */
+export interface EditorContextAction {
+    id: EditorContextActionId;
+    label: string;
+    disabled?: boolean;
+    separatorBefore?: boolean;
+}
+/** @internal Inputs for {@link buildEditorContextMenu}. */
+export interface BuildEditorContextMenuInput {
+    hitId: string | null;
+    selection: readonly string[];
+    canPaste: boolean;
+}
+/**
+ * @internal Selection-aware editor context verbs (#866). Hit/selection → frame/duplicate/delete/copy/prefab;
+ * empty ground → place tools + paste when clipboard has content.
+ */
+export declare function buildEditorContextMenu(input: BuildEditorContextMenuInput): readonly EditorContextAction[];

package/dist/viewportContextMenu.js

@@ -0,0 +1,32 @@
+/** @internal Movement below this (px) counts as a click; above is a camera drag (#866). */
+export const RIGHT_CLICK_SLOP_PX = 4;
+/** @internal True when the pointer released within the drag-vs-click threshold of its down position. */
+export function isPointerClick(startX, startY, endX, endY, thresholdPx = RIGHT_CLICK_SLOP_PX) {
+    return Math.hypot(endX - startX, endY - startY) <= thresholdPx;
+}
+/**
+ * @internal Selection-aware editor context verbs (#866). Hit/selection → frame/duplicate/delete/copy/prefab;
+ * empty ground → place tools + paste when clipboard has content.
+ */
+export function buildEditorContextMenu(input) {
+    const hasSelection = input.selection.length > 0 || input.hitId !== null;
+    if (hasSelection) {
+        return [
+            { id: "frame", label: "Frame" },
+            { id: "duplicate", label: "Duplicate" },
+            { id: "copy", label: "Copy" },
+            { id: "delete", label: "Delete", separatorBefore: true },
+            { id: "createPrefab", label: "Create prefab…", separatorBefore: true },
+            { id: "paste", label: "Paste", disabled: !input.canPaste, separatorBefore: true },
+        ];
+    }
+    return [
+        { id: "paste", label: "Paste", disabled: !input.canPaste },
+        { id: "addMarker", label: "Add marker", separatorBefore: true },
+        { id: "addVolume", label: "Add volume (zone)" },
+        { id: "addPath", label: "Draw path" },
+        { id: "addNote", label: "Add note" },
+        { id: "openAssets", label: "Place asset…", separatorBefore: true },
+        { id: "frameAll", label: "Frame all", separatorBefore: true },
+    ];
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@jgengine/editor",
+  "version": "0.10.0",
+  "description": "Scene/world/asset editor for JGengine — loaded lazily by the runner; never import from game entrypoints.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Noisemaker111/jgengine.git",
+    "directory": "packages/editor"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "skills"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist",
+    "check-types": "tsgo --noEmit -p tsconfig.json",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@jgengine/core": "^0.10.0",
+    "@jgengine/react": "^0.10.0",
+    "@jgengine/shell": "^0.10.0"
+  },
+  "peerDependencies": {
+    "@react-three/drei": "^10.0.0",
+    "@react-three/fiber": "^9.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "three": ">=0.170.0"
+  },
+  "devDependencies": {
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.5.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@types/three": "^0.182.0",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "three": "^0.182.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}