@vgai/editor 0.2.0

package/src/components/inspector-widgets/index.ts

@@ -0,0 +1,22 @@
+/**
+ * The figma-grade inspector widget kit (spec 27 §5 C1,
+ * docs/unified-world-editor/27-visual-react-editing.md). PURE, contract-
+ * driven components — `value` + `onChange` (+ optional `onChangeEnd` for the
+ * commit tick, see `shared.tsx`'s `ChangeHandlers<T>` doc comment) — with NO
+ * wiring into the live inspector/section-registry yet (that is C2, a
+ * separate task). Nothing outside this directory imports from it today
+ * (verify: `grep -rl "inspector-widgets" packages/editor/src` should only
+ * list files inside this directory itself, plus `ui-editor/inspector.tsx`'s
+ * `ANCHOR_PRESETS` export it reuses data FROM, never the reverse).
+ */
+
+export * from './AlignmentGrid';
+export * from './BorderEditor';
+export * from './ColorPicker';
+export type { ColorFormat } from './color-utils';
+export * from './FilterEditor';
+export * from './FontPicker';
+export * from './GradientEditor';
+export * from './ScrubbableInput';
+export * from './ShadowEditor';
+export * from './shared';

package/src/components/inspector-widgets/shared.tsx

@@ -0,0 +1,135 @@
+/**
+ * Shared theme + tiny primitives for the inspector widget kit (spec 27 §5
+ * C1). Colors match the editor's own dark-panel convention (`components/
+ * primitives/Panel.tsx` — `#242424`/`#2c2c2c`/`#333`; `components/
+ * Inspector.tsx`'s `NUM_STYLE` — `#1e1e1e` inputs/`#c5c8ce` text/`#9aa0a6`
+ * muted labels; `#3b82f6` accent from `PrefabSaveDialog.tsx`/
+ * `RootActivateDialog.tsx`) rather than visual-edit's Figma-dark palette, so
+ * the kit drops into this editor's panels without a visual seam.
+ */
+
+import type React from 'react';
+
+export const THEME = {
+  bg: '#242424',
+  surface: '#2c2c2c',
+  surfaceHover: '#333333',
+  border: '#333333',
+  text: '#c5c8ce',
+  textMuted: '#9aa0a6',
+  accent: '#3b82f6',
+  inputBg: '#1e1e1e',
+  dynamic: '#ff79c6',
+  dynamicBg: 'rgba(255,121,198,0.08)',
+} as const;
+
+export const FONT = "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif";
+export const FONT_MONO = "'SF Mono', 'Fira Code', Menlo, Consolas, monospace";
+
+/**
+ * Every widget's change contract (report §"prop shape" for the C2 wiring
+ * step): `onChange` fires on every interaction tick (drag/scrub/keystroke —
+ * the LIVE PREVIEW a caller can apply immediately, mirroring `boxEdit.apply`/
+ * `inspector.set`'s optimistic echo, T0 §2/A4); `onChangeEnd` fires once per
+ * gesture (pointerup/blur/Enter — the COMMIT a caller should push through
+ * `writeStyleAuto`/`inspector.set` as a single undo step, mirroring
+ * `BoxEditProvider.end`). A caller that only cares about single-shot edits
+ * (a `<select>`, a click) may omit `onChangeEnd` — widgets fall back to
+ * treating `onChange` as the commit in that case.
+ */
+export interface ChangeHandlers<T> {
+  value: T;
+  onChange: (value: T) => void;
+  onChangeEnd?: ((value: T) => void) | undefined;
+  disabled?: boolean | undefined;
+}
+
+export function fireChange<T>(handlers: Pick<ChangeHandlers<T>, 'onChange'>, value: T): void {
+  handlers.onChange(value);
+}
+
+export function fireEnd<T>(
+  handlers: Pick<ChangeHandlers<T>, 'onChange' | 'onChangeEnd'>,
+  value: T,
+): void {
+  (handlers.onChangeEnd ?? handlers.onChange)(value);
+}
+
+export function inputStyle(disabled = false): React.CSSProperties {
+  return {
+    background: disabled ? THEME.dynamicBg : THEME.inputBg,
+    color: disabled ? THEME.dynamic : THEME.text,
+    border: `1px solid ${disabled ? 'rgba(255,121,198,0.15)' : THEME.border}`,
+    borderRadius: 3,
+    padding: '3px 6px',
+    fontSize: 11,
+    fontFamily: FONT,
+    outline: 'none',
+    minWidth: 0,
+    cursor: disabled ? 'not-allowed' : undefined,
+    boxSizing: 'border-box',
+  };
+}
+
+export const rowStyle: React.CSSProperties = { display: 'flex', alignItems: 'center', gap: 4 };
+
+export const miniButtonStyle: React.CSSProperties = {
+  background: 'rgba(255,255,255,0.06)',
+  border: 'none',
+  borderRadius: 3,
+  color: THEME.textMuted,
+  fontSize: 10,
+  padding: '3px 6px',
+  cursor: 'pointer',
+  lineHeight: 1,
+};
+
+export function toggleButtonStyle(active: boolean, disabled?: boolean): React.CSSProperties {
+  return {
+    flex: 1,
+    padding: '3px 0',
+    background: active ? THEME.accent : THEME.inputBg,
+    color: active ? '#fff' : THEME.textMuted,
+    border: `1px solid ${active ? THEME.accent : THEME.border}`,
+    borderRadius: 3,
+    fontSize: 10,
+    fontFamily: FONT,
+    cursor: disabled ? 'not-allowed' : 'pointer',
+    opacity: disabled ? 0.4 : 1,
+  };
+}
+
+export function ToggleButton({
+  label,
+  active,
+  disabled,
+  onClick,
+  testId,
+}: {
+  label: React.ReactNode;
+  active: boolean;
+  disabled?: boolean | undefined;
+  onClick: () => void;
+  testId?: string | undefined;
+}): React.ReactElement {
+  return (
+    <button
+      type="button"
+      data-testid={testId}
+      onClick={() => {
+        if (!disabled) onClick();
+      }}
+      style={toggleButtonStyle(active, disabled)}
+    >
+      {label}
+    </button>
+  );
+}
+
+/** `parseNumericValue('12.5px') -> {num: 12.5, unit: 'px'}` (visual-edit :98). */
+export function parseNumericValue(value: string): { num: number; unit: string } {
+  const match = value.match(/^(-?\d+\.?\d*)\s*(px|em|rem|%|vh|vw|deg|s|ms)?$/);
+  if (match) return { num: Number.parseFloat(match[1] ?? '0'), unit: match[2] || '' };
+  const num = Number.parseFloat(value);
+  return { num: Number.isNaN(num) ? 0 : num, unit: '' };
+}

package/src/components/inspectors/AnimationSection.tsx

@@ -0,0 +1,143 @@
+import type { SceneAnimation, SceneEntity } from '@engine/scene/scene-types';
+import { getUserData } from '@engine/scene/user-data';
+import { useEditorStore } from '../../EditorContext';
+import { SectionHeader } from '../primitives/SectionHeader';
+import type { SectionProps } from './multi-edit-utils';
+
+const labelStyle: React.CSSProperties = {
+  fontSize: 10,
+  color: '#8c8c8c',
+  marginBottom: 2,
+};
+
+const inputStyle: React.CSSProperties = {
+  width: '100%',
+  background: '#1e1e1e',
+  color: '#c5c8ce',
+  border: '1px solid #333',
+  borderRadius: 2,
+  padding: '3px 6px',
+  fontSize: 12,
+};
+
+const btnStyle: React.CSSProperties = {
+  background: '#333',
+  color: '#c5c8ce',
+  border: '1px solid #444',
+  borderRadius: 3,
+  padding: '3px 8px',
+  cursor: 'pointer',
+  fontSize: 11,
+};
+
+/**
+ * Plain-gltf-clip animation UI (E5 — the AnimGraph state-machine section this
+ * file used to also render — `.animgraph.json` fetch/parse, the
+ * `animGraphPath`/`graphMeta`/`liveGraph` state, and the parameter-row UI —
+ * was removed with the AnimGraph runtime it drove; see
+ * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §3.3/§11 E5). A GameComponent
+ * that wants discrete state-machine-driven animation now builds its own XState
+ * machine + `bindXStateAnimation` in code (see
+ * packages/engine/src/animation/xstate-animation-binding.ts) — there is no
+ * second authored format or editor section for it.
+ */
+export function AnimationSection({ entities }: SectionProps) {
+  const store = useEditorStore();
+  // Hooks must be unconditional, so we compute with entities[0] always
+  const entity = entities[0]!;
+  const isGltf = entity.mesh?.type === 'gltf';
+  const id = entity.id!;
+  const animation = entity.animation;
+
+  if (entities.length !== 1) return null;
+  if (!isGltf && !animation) return null;
+
+  const update = (partial: Partial<SceneAnimation>) => {
+    store.updateEntity(id, { animation: { ...animation, ...partial } });
+  };
+
+  const obj = store.objectMap.get(id);
+
+  // Available clips from the loaded GLTF model
+  const availableClips = (getUserData(obj, '_availableClips') as string[] | undefined) ?? [];
+
+  if (!animation) {
+    return (
+      <SectionHeader label="Animation" defaultOpen={false}>
+        <button
+          type="button"
+          style={btnStyle}
+          onClick={() => store.updateEntity(id, { animation: {} })}
+        >
+          Add Animation
+        </button>
+      </SectionHeader>
+    );
+  }
+
+  return (
+    <SectionHeader label="Animation">
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+        {/* Autoplay clip picker */}
+        {availableClips.length > 0 && (
+          <div>
+            <div style={labelStyle}>Autoplay Clip</div>
+            <select
+              value={animation.autoplay ?? ''}
+              onChange={(e) => {
+                const val = e.target.value;
+                if (val) {
+                  update({ autoplay: val });
+                } else {
+                  const { autoplay: _, ...rest } = animation;
+                  store.updateEntity(id, { animation: Object.keys(rest).length > 0 ? rest : {} });
+                }
+              }}
+              style={{ ...inputStyle, cursor: 'pointer' }}
+            >
+              <option value="">(none)</option>
+              {availableClips.map((clip) => (
+                <option key={clip} value={clip}>
+                  {clip}
+                </option>
+              ))}
+            </select>
+          </div>
+        )}
+
+        {/* Loop checkbox — shown when autoplay is set */}
+        {animation.autoplay && (
+          <div>
+            <label
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: 4,
+                fontSize: 12,
+                cursor: 'pointer',
+              }}
+            >
+              <input
+                type="checkbox"
+                checked={animation.loop !== false}
+                onChange={(e) => update({ loop: e.target.checked })}
+              />
+              Loop
+            </label>
+          </div>
+        )}
+
+        <button
+          type="button"
+          style={{ ...btnStyle, color: '#F53352', fontSize: 10, padding: '2px 6px' }}
+          onClick={() => {
+            const patch: Record<string, unknown> = { animation: undefined };
+            store.updateEntity(id, patch as Partial<SceneEntity>);
+          }}
+        >
+          Remove Animation
+        </button>
+      </div>
+    </SectionHeader>
+  );
+}

package/src/components/inspectors/AudioSection.tsx

@@ -0,0 +1,215 @@
+import type { SceneAudio } from '@engine/scene/scene-types';
+import { useEffect, useRef, useState } from 'react';
+import { useEditorStore } from '../../EditorContext';
+import { NumberInput } from '../primitives/NumberInput';
+import { SectionHeader } from '../primitives/SectionHeader';
+import { Tooltip } from '../primitives/Tooltip';
+import type { SectionProps } from './multi-edit-utils';
+import { commonBool, commonNum } from './multi-edit-utils';
+
+const labelStyle: React.CSSProperties = { fontSize: 10, color: '#8c8c8c', marginBottom: 2 };
+
+export function AudioSection({ entities, ids }: SectionProps) {
+  const store = useEditorStore();
+  const multi = entities.length > 1;
+  const entity = entities[0]!;
+  const audio = entity.audio;
+
+  // Audio preview — only for single entity but hooks must be unconditional
+  const audioRef = useRef<HTMLAudioElement | null>(null);
+  const [playing, setPlaying] = useState(false);
+
+  const audioSrc = audio?.src;
+  useEffect(() => {
+    return () => {
+      if (audioRef.current) {
+        audioRef.current.pause();
+        audioRef.current = null;
+      }
+      setPlaying(false);
+    };
+  }, [multi ? undefined : audioSrc]);
+
+  if (!entities.every((e) => e.audio)) return null;
+  // After the guard above, audio is guaranteed to be defined
+  const audioData = audio!;
+
+  const togglePreview = () => {
+    if (playing && audioRef.current) {
+      audioRef.current.pause();
+      audioRef.current = null;
+      setPlaying(false);
+      return;
+    }
+    if (!audioData.src) return;
+    const el = new Audio(audioData.src);
+    el.volume = audioData.volume ?? 1;
+    el.loop = audioData.loop ?? false;
+    el.onended = () => {
+      audioRef.current = null;
+      setPlaying(false);
+    };
+    el.play();
+    audioRef.current = el;
+    setPlaying(true);
+  };
+
+  const volume = commonNum(entities, (e) => e.audio?.volume ?? 1);
+  const spatial = commonBool(entities, (e) => e.audio?.spatial !== false);
+  const loop = commonBool(entities, (e) => e.audio?.loop ?? false);
+  const autoplay = commonBool(entities, (e) => e.audio?.autoplay ?? false);
+
+  const update = (partial: Partial<SceneAudio>) => {
+    store.batchMutate(ids, (entity) => {
+      if (entity.audio) Object.assign(entity.audio, partial);
+    });
+  };
+
+  return (
+    <SectionHeader label="Audio">
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+        {/* Source path — single entity only */}
+        {!multi && (
+          <div>
+            <div style={labelStyle}>Source</div>
+            <input
+              value={audioData.src ?? ''}
+              placeholder="path/to/audio.mp3"
+              onChange={(e) => {
+                if (e.target.value) {
+                  update({ src: e.target.value });
+                } else {
+                  const next = { ...audioData };
+                  delete next.src;
+                  store.updateEntity(entity.id!, { audio: next });
+                }
+              }}
+              style={{
+                width: '100%',
+                background: '#1e1e1e',
+                color: '#c5c8ce',
+                border: '1px solid #333',
+                borderRadius: 2,
+                padding: '2px 4px',
+                fontSize: 11,
+              }}
+            />
+          </div>
+        )}
+
+        {/* Preview — single entity only */}
+        {!multi && (
+          <button
+            onClick={togglePreview}
+            disabled={!audioData.src}
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              gap: 4,
+              width: '100%',
+              padding: '3px 0',
+              background: playing ? '#3a2a2a' : '#2a2a2a',
+              color: !audioData.src ? '#555' : playing ? '#e06060' : '#c5c8ce',
+              border: `1px solid ${playing ? '#6a3a3a' : '#333'}`,
+              borderRadius: 2,
+              fontSize: 11,
+              cursor: audioData.src ? 'pointer' : 'default',
+            }}
+          >
+            {playing ? '\u25A0 Stop' : '\u25B6 Preview'}
+          </button>
+        )}
+
+        {/* Spatial */}
+        <div>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+            <input
+              type="checkbox"
+              checked={spatial ?? false}
+              ref={(el) => {
+                if (el) el.indeterminate = spatial === null;
+              }}
+              onChange={(e) => update({ spatial: e.target.checked })}
+            />
+            <Tooltip text="Positional 3D audio vs non-spatial background audio" position="right">
+              <span style={{ fontSize: 11, color: '#c5c8ce' }}>Spatial</span>
+            </Tooltip>
+          </div>
+        </div>
+
+        {/* Volume */}
+        <div>
+          <div style={labelStyle}>Volume</div>
+          <NumberInput value={volume} onChange={(v) => update({ volume: v })} step={0.05} />
+        </div>
+
+        {/* Spatial-only properties — single entity only */}
+        {!multi && spatial === true && (
+          <>
+            <div>
+              <Tooltip text="Distance at which volume starts to reduce" position="right">
+                <div style={labelStyle}>Ref Distance</div>
+              </Tooltip>
+              <NumberInput
+                value={audioData.refDistance ?? 1}
+                onChange={(v) => update({ refDistance: v })}
+                step={0.5}
+              />
+            </div>
+            <div>
+              <Tooltip text="How quickly volume falls off with distance" position="right">
+                <div style={labelStyle}>Rolloff Factor</div>
+              </Tooltip>
+              <NumberInput
+                value={audioData.rolloffFactor ?? 1}
+                onChange={(v) => update({ rolloffFactor: v })}
+                step={0.1}
+              />
+            </div>
+            <div>
+              <Tooltip text="Maximum distance for audio falloff" position="right">
+                <div style={labelStyle}>Max Distance</div>
+              </Tooltip>
+              <NumberInput
+                value={audioData.maxDistance ?? 10000}
+                onChange={(v) => update({ maxDistance: v })}
+                step={1}
+              />
+            </div>
+          </>
+        )}
+
+        {/* Loop */}
+        <div>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+            <input
+              type="checkbox"
+              checked={loop ?? false}
+              ref={(el) => {
+                if (el) el.indeterminate = loop === null;
+              }}
+              onChange={(e) => update({ loop: e.target.checked })}
+            />
+            <span style={{ fontSize: 11, color: '#c5c8ce' }}>Loop</span>
+          </div>
+        </div>
+
+        {/* Autoplay */}
+        <div>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+            <input
+              type="checkbox"
+              checked={autoplay ?? false}
+              ref={(el) => {
+                if (el) el.indeterminate = autoplay === null;
+              }}
+              onChange={(e) => update({ autoplay: e.target.checked })}
+            />
+            <span style={{ fontSize: 11, color: '#c5c8ce' }}>Autoplay</span>
+          </div>
+        </div>
+      </div>
+    </SectionHeader>
+  );
+}

package/src/components/inspectors/BoneAttachmentSection.tsx

@@ -0,0 +1,82 @@
+import type { SceneEntity } from '@engine/scene/scene-types';
+import { useEditorStore } from '../../EditorContext';
+import { SectionHeader } from '../primitives/SectionHeader';
+import type { SectionProps } from './multi-edit-utils';
+import { commonStr } from './multi-edit-utils';
+
+const inputStyle: React.CSSProperties = {
+  width: '100%',
+  background: '#1e1e1e',
+  color: '#c5c8ce',
+  border: '1px solid #333',
+  borderRadius: 2,
+  padding: '3px 4px',
+  fontSize: 11,
+};
+
+const labelStyle: React.CSSProperties = { fontSize: 10, color: '#8c8c8c', marginBottom: 2 };
+
+type BoneAttachment = NonNullable<SceneEntity['boneAttachment']>;
+
+export function BoneAttachmentSection({ entities, ids }: SectionProps) {
+  const store = useEditorStore();
+  if (!entities.every((entity) => entity.boneAttachment)) return null;
+
+  const target = commonStr(entities, (entity) => entity.boneAttachment?.target);
+  const bone = commonStr(entities, (entity) => entity.boneAttachment?.bone);
+  const selected = new Set(ids);
+  const targets = store.allEntities().filter((entity) => entity.id && !selected.has(entity.id));
+
+  const update = (partial: Partial<BoneAttachment>) => {
+    store.batchMutate(ids, (entity) => {
+      if (entity.boneAttachment) Object.assign(entity.boneAttachment, partial);
+    });
+  };
+
+  const remove = () => {
+    store.batchMutate(ids, (entity) => {
+      delete entity.boneAttachment;
+    });
+  };
+
+  return (
+    <SectionHeader label="Bone Attachment">
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+        <div>
+          <div style={labelStyle}>Target entity</div>
+          <select
+            value={target ?? ''}
+            onChange={(event) => update({ target: event.target.value })}
+            style={inputStyle}
+          >
+            {target === null && <option value="">(mixed)</option>}
+            {targets.map((entity) => (
+              <option key={entity.id} value={entity.id}>
+                {entity.name}
+              </option>
+            ))}
+          </select>
+        </div>
+        <div>
+          <div style={labelStyle}>Bone / socket name</div>
+          <input
+            value={bone ?? ''}
+            placeholder="hand_r"
+            onChange={(event) => update({ bone: event.target.value })}
+            style={inputStyle}
+          />
+        </div>
+        <div style={{ fontSize: 10, color: '#777' }}>
+          Transform position, rotation, and scale are the local socket offsets.
+        </div>
+        <button
+          type="button"
+          onClick={remove}
+          style={{ ...inputStyle, cursor: 'pointer', color: '#d98a8a' }}
+        >
+          Remove attachment
+        </button>
+      </div>
+    </SectionHeader>
+  );
+}