@volter/editor-core 0.5.57

package/src/components/asset-thumbnails.tsx

@@ -0,0 +1,312 @@
+/**
+ * Shared asset-thumbnail visuals for browser-style surfaces: the flat kind
+ * icon, the synthetic per-kind glyph thumbnails, and the live model-thumbnail
+ * resolution pipeline (project manifest first, then the shared offscreen
+ * render queue). Extracted verbatim from AssetBrowser so FolderPreviewTile can
+ * composite the exact same visuals inside folder tiles without an import
+ * cycle; behavior for direct asset tiles is unchanged.
+ */
+
+import {
+  faBoxArchive,
+  faCode,
+  faCubes,
+  faFile,
+  faFileCode,
+  faFileImage,
+  faFilm,
+  faFolder,
+  faMusic,
+  faPuzzlePiece,
+} from '@fortawesome/free-solid-svg-icons';
+import { border, EditorIcon } from '@volter/editor-sdk/widgets';
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+import type { AssetCapabilityKind } from '../asset-workflow/asset-capabilities';
+import {
+  getAssetAudioPreview,
+  loadAudioWaveformPeaks,
+  subscribeAssetAudioPreview,
+} from '../asset-workflow/audio-preview-player';
+import { AUDIO_WAVEFORM_BARS } from '../asset-workflow/audio-waveform';
+import {
+  loadProjectThumbnailManifest,
+  ThumbnailJobQueue,
+} from '../asset-workflow/thumbnail-system';
+import { getModelThumbnailRenderer, modelThumbnailFormat } from '../model-thumbnail';
+
+/** Every kind a browser entry can carry: capability kinds plus directories. */
+export type AssetGlyphKind = AssetCapabilityKind | 'component' | 'folder';
+
+/**
+ * Per-kind category colors. Defined in theme.css's `.vgai-editor-theme`
+ * block; the `--vgai-` prefix keeps them under the design-system migration
+ * guard's dangling-variable check, so a definition can no longer be deleted
+ * without failing the unit gate (which is exactly how the earlier `--asset-*`
+ * spelling silently became invisible glyphs).
+ */
+export const assetIconColors: Record<AssetGlyphKind, string> = {
+  folder: 'var(--vgai-asset-icon-folder)',
+  model: 'var(--vgai-asset-icon-model)',
+  prefab: 'var(--vgai-asset-icon-prefab)',
+  component: 'var(--vgai-asset-icon-component)',
+  audio: 'var(--vgai-asset-icon-audio)',
+  image: 'var(--vgai-asset-icon-image)',
+  video: 'var(--vgai-asset-icon-video)',
+  json: 'var(--vgai-asset-icon-json)',
+  unknown: 'var(--vgai-asset-icon-unknown)',
+  source: 'var(--vgai-asset-icon-source)',
+};
+
+export const assetIconMap: Record<AssetGlyphKind, typeof faFolder> = {
+  folder: faFolder,
+  model: faCubes,
+  prefab: faPuzzlePiece,
+  component: faCode,
+  audio: faMusic,
+  image: faFileImage,
+  video: faFilm,
+  json: faFileCode,
+  unknown: faFile,
+  source: faBoxArchive,
+};
+
+export function AssetIcon({ kind, size = 24 }: { kind: AssetGlyphKind; size?: number }) {
+  return (
+    <EditorIcon
+      icon={assetIconMap[kind]}
+      style={{ fontSize: size, color: assetIconColors[kind] }}
+    />
+  );
+}
+
+/** Queue priority for thumbnails a direct asset tile requests. */
+export const ASSET_TILE_THUMBNAIL_PRIORITY = 100;
+/** Folder composite cells queue below direct asset tiles — they must never delay them. */
+export const FOLDER_CELL_THUMBNAIL_PRIORITY = 50;
+
+/** Renders an offscreen 3D preview thumbnail for supported model assets. */
+export const projectThumbnailQueue = new ThumbnailJobQueue<string>((url) => {
+  const format = modelThumbnailFormat(url);
+  if (!format) return Promise.reject(new Error(`No model preview loader for ${url}.`));
+  return getModelThumbnailRenderer().render({
+    url,
+    format,
+    background: 'neutral',
+    output: 'webp',
+  });
+}, 2);
+
+export interface ModelThumbnailSource {
+  /** Manifest image path or rendered data URL; null while resolving. */
+  src: string | null;
+  /** True when `src` is a manifest path whose file may turn out missing. */
+  fromManifest: boolean;
+  failed: boolean;
+  /** Discard a broken manifest path and fall back to a live render. */
+  rejectManifest(): void;
+}
+
+/**
+ * Resolve a model asset's thumbnail: `.vgai/thumbnails.json` manifest entry
+ * first, otherwise a live offscreen render through the shared queue at the
+ * given priority.
+ */
+export function useModelThumbnailSource(url: string, priority: number): ModelThumbnailSource {
+  const [src, setSrc] = useState<string | null>(null);
+  const [failed, setFailed] = useState(false);
+  const [manifestPath, setManifestPath] = useState<string | null>(null);
+  const [manifestRejected, setManifestRejected] = useState(false);
+
+  useEffect(() => {
+    setSrc(null);
+    setFailed(false);
+    setManifestPath(null);
+    setManifestRejected(false);
+  }, [url]);
+
+  useEffect(() => {
+    let cancelled = false;
+    let queued: ReturnType<typeof projectThumbnailQueue.request> | null = null;
+    void loadProjectThumbnailManifest()
+      .then((read) => {
+        if (cancelled) return;
+        // A read-only consumer: `absent` and `unreadable` both mean "no
+        // manifest entry to serve", and both fall through to a live render.
+        const entry =
+          read.status === 'ok' ? read.manifest.entries[url.replace(/^\/+/, '')] : undefined;
+        if (
+          !manifestRejected &&
+          entry?.path &&
+          (entry.state === 'generated' || entry.state === 'upstream')
+        ) {
+          setManifestPath(entry.path.startsWith('/') ? entry.path : `/${entry.path}`);
+          return;
+        }
+        queued = projectThumbnailQueue.request(url, priority);
+        return queued.promise;
+      })
+      .then((dataUrl) => {
+        if (!cancelled && dataUrl) setSrc(dataUrl);
+      })
+      .catch(() => {
+        if (!cancelled) setFailed(true);
+      });
+    return () => {
+      cancelled = true;
+      queued?.cancel();
+    };
+  }, [manifestRejected, priority, url]);
+
+  const rejectManifest = useCallback(() => {
+    setManifestPath(null);
+    setManifestRejected(true);
+  }, []);
+
+  return { src: manifestPath ?? src, fromManifest: manifestPath !== null, failed, rejectManifest };
+}
+
+export function ModelThumbnail({ url }: { url: string }) {
+  const thumbnail = useModelThumbnailSource(url, ASSET_TILE_THUMBNAIL_PRIORITY);
+
+  if (thumbnail.failed) return <AssetIcon kind="model" />;
+  if (thumbnail.fromManifest && thumbnail.src) {
+    return (
+      <img
+        src={thumbnail.src}
+        alt="cached model preview"
+        onError={thumbnail.rejectManifest}
+        style={{ width: '100%', height: '100%', objectFit: 'contain' }}
+      />
+    );
+  }
+  if (!thumbnail.src) {
+    // Loading spinner
+    return (
+      <div
+        style={{
+          width: 28,
+          height: 28,
+          margin: '0 auto',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+        }}
+      >
+        <div
+          className="vgai-anim-spin"
+          style={{
+            width: 16,
+            height: 16,
+            border: `2px solid ${border[2]}`,
+            borderTopColor: assetIconColors.model,
+            borderRadius: '50%',
+          }}
+        />
+      </div>
+    );
+  }
+  return (
+    <img
+      src={thumbnail.src}
+      alt="model preview"
+      style={{ width: '100%', height: '100%', objectFit: 'contain' }}
+    />
+  );
+}
+
+export function AudioAssetThumb({ url, name }: { url: string; name: string }) {
+  const [peaks, setPeaks] = useState<readonly number[]>(() =>
+    Array.from({ length: AUDIO_WAVEFORM_BARS }, () => 0.15),
+  );
+  const preview = useSyncExternalStore(subscribeAssetAudioPreview, getAssetAudioPreview);
+  useEffect(() => {
+    let cancelled = false;
+    void loadAudioWaveformPeaks(url).then((next) => {
+      if (!cancelled) setPeaks(next);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [url]);
+  const active = preview.url === url;
+  const progress = active ? preview.progress : 0;
+  return (
+    <div
+      role="img"
+      aria-label={`${name} waveform preview`}
+      style={{
+        display: 'flex',
+        // Midline, like a DAW clip — flex-end reads as a histogram piled at the top.
+        alignItems: 'center',
+        gap: 1,
+        width: '86%',
+        height: '62%',
+      }}
+    >
+      {peaks.map((amplitude, index) => {
+        const played = index / peaks.length <= progress;
+        return (
+          <i
+            key={index}
+            style={{
+              flex: 1,
+              height: `${12 + amplitude * 88}%`,
+              background: 'var(--vgai-asset-icon-audio)',
+              opacity: active && played ? 1 : 0.28,
+              borderRadius: 1,
+            }}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+export function TypedAssetThumbnail({
+  kind,
+  name,
+  variant = 'tile',
+}: {
+  kind: AssetGlyphKind;
+  name: string;
+  /** 'cell' scales the glyph fluidly for folder-composite cells. */
+  variant?: 'tile' | 'cell';
+}) {
+  const color = assetIconColors[kind];
+  const cell = variant === 'cell';
+  if (kind === 'audio') {
+    return (
+      <svg
+        role="img"
+        aria-label={`${name} waveform preview`}
+        viewBox="0 0 64 48"
+        width={cell ? '78%' : 52}
+        height={cell ? '78%' : 44}
+      >
+        <rect width="64" height="48" rx="4" fill="var(--vgai-bg-inset)" />
+        {Array.from({ length: 16 }, (_, index) => (
+          <rect
+            key={index}
+            x={index * 4 + 1}
+            y={24 - ((index * 13) % 18) / 2}
+            width="2"
+            height={((index * 13) % 18) + 3}
+            fill={color}
+          />
+        ))}
+      </svg>
+    );
+  }
+  return (
+    <svg
+      role="img"
+      aria-label={`${name} ${kind} preview`}
+      viewBox="0 0 52 48"
+      width={cell ? '66%' : 48}
+      height={cell ? '72%' : 44}
+    >
+      <rect x="5" y="3" width="42" height="42" rx="4" fill="var(--vgai-bg-inset)" stroke={color} />
+      <path d="M13 15h26M13 23h18M13 31h22" stroke={color} strokeWidth="3" strokeLinecap="round" />
+    </svg>
+  );
+}

package/src/components/asset-viewers/AudioViewer.tsx

@@ -0,0 +1,201 @@
+import { Button, Checkbox, RangeInput, SectionHeader, themeVars } from '@volter/editor-sdk/widgets';
+import { useEffect, useRef, useState } from 'react';
+
+const labelStyle: React.CSSProperties = {
+  fontSize: 11,
+  color: themeVars.content.dim,
+  marginBottom: 2,
+};
+
+export function AudioViewer({ assetPath }: { assetPath: string }) {
+  const audioRef = useRef<HTMLAudioElement>(null);
+  const [playing, setPlaying] = useState(false);
+  const [duration, setDuration] = useState<number | null>(null);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [loop, setLoop] = useState(false);
+  const [volume, setVolume] = useState(1);
+  const fileName = assetPath.split('/').pop() ?? assetPath;
+  const ext = assetPath.split('.').pop()?.toUpperCase() ?? '';
+
+  // Pause when component unmounts (tab closed or switched)
+  useEffect(() => {
+    return () => {
+      audioRef.current?.pause();
+    };
+  }, []);
+
+  const togglePlay = () => {
+    const el = audioRef.current;
+    if (!el) return;
+    if (playing) {
+      el.pause();
+    } else {
+      el.play();
+    }
+    setPlaying(!playing);
+  };
+
+  const formatTime = (t: number) => {
+    const m = Math.floor(t / 60);
+    const s = Math.floor(t % 60);
+    return `${m}:${s.toString().padStart(2, '0')}`;
+  };
+
+  return (
+    <div style={{ padding: 8, display: 'flex', flexDirection: 'column', gap: 8 }}>
+      <div
+        style={{
+          fontWeight: 600,
+          fontSize: 12,
+          color: themeVars.content.primary,
+          wordBreak: 'break-all',
+        }}
+      >
+        {fileName}
+      </div>
+      {/* Player */}
+      <div
+        // §2.31 P2 amendment: player controls read over a local frost layer.
+        className="vgai-content-frost"
+        style={{
+          width: '100%',
+          // §2.31: hairline-only player card — no fill over the surface.
+          border: `1px solid ${themeVars.boundary.default}`,
+          borderRadius: themeVars.shape.small,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          flexDirection: 'column',
+          gap: 8,
+          padding: 16,
+        }}
+      >
+        {/* Audio icon */}
+        <svg viewBox="0 0 24 24" width={48} height={48}>
+          <rect x="3" y="3" width="18" height="18" rx="2" fill="var(--vgai-asset-icon-audio)" />
+          <path
+            d="M9 8l4-2v12l-4-2H7V10h2zm6 1v6m2-5v4"
+            stroke="var(--vgai-text-1)"
+            strokeWidth="1.5"
+            fill="none"
+            strokeLinecap="round"
+          />
+        </svg>
+        {/* Progress */}
+        {duration != null && (
+          <div
+            style={{
+              width: '100%',
+              fontSize: 10,
+              color: themeVars.content.muted,
+              textAlign: 'center',
+            }}
+          >
+            {formatTime(currentTime)} / {formatTime(duration)}
+          </div>
+        )}
+        {/* Scrub bar */}
+        {duration != null && duration > 0 && (
+          <div
+            style={{
+              width: '100%',
+              height: 4,
+              background: themeVars.surface.raised,
+              borderRadius: themeVars.shape.small,
+              cursor: 'pointer',
+              position: 'relative',
+            }}
+            onClick={(e) => {
+              const rect = e.currentTarget.getBoundingClientRect();
+              const frac = (e.clientX - rect.left) / rect.width;
+              if (audioRef.current) {
+                audioRef.current.currentTime = frac * duration;
+              }
+            }}
+          >
+            <div
+              style={{
+                width: `${(currentTime / duration) * 100}%`,
+                height: '100%',
+                background: 'var(--vgai-asset-icon-audio)',
+                borderRadius: themeVars.shape.small,
+              }}
+            />
+          </div>
+        )}
+        <Button type="button" variant="secondary" size="comfortable" onClick={togglePlay}>
+          {playing ? 'Pause' : 'Play'}
+        </Button>
+        <div
+          role="img"
+          aria-label="Audio waveform"
+          style={{ width: '100%', height: 36, display: 'flex', alignItems: 'center', gap: 2 }}
+        >
+          {Array.from({ length: 48 }, (_, index) => (
+            <i
+              key={index}
+              style={{
+                flex: 1,
+                height: `${20 + ((index * 37) % 75)}%`,
+                background: 'var(--vgai-asset-icon-audio)',
+                opacity: index / 48 <= currentTime / (duration || 1) ? 1 : 0.3,
+              }}
+            />
+          ))}
+        </div>
+        <label style={{ fontSize: 11, color: themeVars.content.muted }}>
+          <Checkbox checked={loop} onChange={(event) => setLoop(event.target.checked)} /> Loop
+        </label>
+        <label style={{ fontSize: 11, color: themeVars.content.muted }}>
+          Volume{' '}
+          <RangeInput
+            aria-label="Audio volume"
+            min="0"
+            max="1"
+            step="0.05"
+            value={volume}
+            onChange={(event) => {
+              const value = Number(event.target.value);
+              setVolume(value);
+              if (audioRef.current) audioRef.current.volume = value;
+            }}
+          />
+        </label>
+      </div>
+      <audio
+        ref={audioRef}
+        src={assetPath}
+        loop={loop}
+        onLoadedMetadata={() => {
+          if (audioRef.current) setDuration(audioRef.current.duration);
+        }}
+        onTimeUpdate={() => {
+          if (audioRef.current) setCurrentTime(audioRef.current.currentTime);
+        }}
+        onEnded={() => setPlaying(false)}
+      />
+      <SectionHeader label="Info">
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+          <div>
+            <div style={labelStyle}>Path</div>
+            <div style={{ fontSize: 11, color: themeVars.content.primary, wordBreak: 'break-all' }}>
+              {assetPath}
+            </div>
+          </div>
+          {duration != null && (
+            <div>
+              <div style={labelStyle}>Duration</div>
+              <div style={{ fontSize: 11, color: themeVars.content.primary }}>
+                {formatTime(duration)}
+              </div>
+            </div>
+          )}
+          <div>
+            <div style={labelStyle}>Format</div>
+            <div style={{ fontSize: 11, color: themeVars.content.primary }}>{ext}</div>
+          </div>
+        </div>
+      </SectionHeader>
+    </div>
+  );
+}

package/src/components/asset-viewers/EntityModelDocument.tsx

@@ -0,0 +1,122 @@
+import { themeVars } from '@volter/editor-sdk/widgets';
+import { getUserData } from '@volter/editor-threejs/ecs/user-data';
+import { useCallback, useSyncExternalStore } from 'react';
+import type * as THREE from 'three';
+import {
+  assetPreviewSubject,
+  createAssetPreviewSnapshot,
+  disposeAssetPreviewSnapshot,
+} from '../../asset-preview';
+import { useEditorStore } from '../../editor-runtime';
+import { Object3DDocumentViewport } from '../StageHost';
+
+function entityClips(source: THREE.Object3D): THREE.AnimationClip[] {
+  const discovered = new Set<THREE.AnimationClip>();
+  source.traverse((object) => {
+    const runtime = getUserData(object, '_animationRuntime');
+    if (runtime) for (const clip of runtime.clips.values()) discovered.add(clip);
+    const clips = getUserData(object, '_animClips');
+    if (clips) for (const clip of clips.values()) discovered.add(clip);
+    for (const clip of object.animations) discovered.add(clip);
+  });
+  return [...discovered];
+}
+
+/**
+ * Isolated native projection of a live `Object3D`; the source graph is never
+ * reparented (`createAssetPreviewSnapshot` copies it).
+ *
+ * The object comes in already resolved, so this component has no way to fail
+ * for a thing that is on screen — it is the honest shared body of both the
+ * Asset Lab's entity document ({@link EntityModelDocument}, which resolves the
+ * scene entity and owns the "no longer available" case) and the inspector's
+ * preview section (`components/InspectorObjectPreview.tsx`), whose subject the
+ * composer has already proved previewable.
+ */
+export function Object3DSnapshotDocument({
+  documentId,
+  source,
+  sourcePath,
+  displayName,
+  active,
+  chromeless = false,
+  revision = 0,
+  modelSource,
+}: {
+  readonly documentId: string;
+  readonly source: THREE.Object3D;
+  /** Human-readable provenance line for the viewport's own chrome. */
+  readonly sourcePath?: string;
+  readonly displayName: string;
+  readonly active: boolean;
+  readonly chromeless?: boolean;
+  /** Bump to rebuild the snapshot when the source graph mutated in place. */
+  readonly revision?: number;
+  readonly modelSource?: { readonly kind: 'entity'; readonly entityId: string };
+}) {
+  const build = useCallback(() => {
+    // The mesh under the click, or the skeleton root that owns its bones.
+    const root = createAssetPreviewSnapshot(assetPreviewSubject(source));
+    const animations = entityClips(source);
+    root.animations = [...animations];
+    return {
+      root,
+      animations,
+      dispose() {
+        disposeAssetPreviewSnapshot(root);
+      },
+    };
+  }, [source, revision]);
+  return (
+    <Object3DDocumentViewport
+      documentId={documentId}
+      sourcePath={sourcePath ?? displayName}
+      displayName={displayName}
+      build={build}
+      active={active}
+      chromeless={chromeless}
+      // The chromeless host is the inspector's preview, which remounts on
+      // every selection — it draws through the shared renderer instead of
+      // building one per click (`inspector-preview-renderer.ts`). A full
+      // document lives as long as its panel and keeps its own.
+      rendererLane={chromeless ? 'inspector-preview' : 'own'}
+      assetType="entity"
+      {...(modelSource ? { modelSource } : {})}
+    />
+  );
+}
+
+/** The Asset Lab document for one live scene entity. */
+export function EntityModelDocument({
+  documentId,
+  entityId,
+  displayName,
+  active,
+}: {
+  readonly documentId: string;
+  readonly entityId: string;
+  readonly displayName: string;
+  readonly active: boolean;
+}) {
+  const store = useEditorStore();
+  const storeVersion = useSyncExternalStore(store.subscribe, store.getSnapshot);
+  const source = store.objectMap.get(entityId);
+
+  if (!source)
+    return (
+      <div role="alert" style={{ padding: 20, color: themeVars.semantic.danger }}>
+        Scene entity {entityId} is no longer available.
+      </div>
+    );
+  return (
+    <Object3DSnapshotDocument
+      documentId={documentId}
+      source={source}
+      sourcePath={`Entity ${entityId}`}
+      displayName={displayName}
+      active={active}
+      revision={storeVersion}
+      modelSource={{ kind: 'entity', entityId }}
+    />
+  );
+}