@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/components/asset-thumbnails.tsx

@@ -0,0 +1,307 @@
+/**
+ * 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/sdk/widgets';
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react';
+import type { AssetCapabilityKind } from '@volter/sdk/kit/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 { assetThumbnailRenderer } from '@volter/sdk/kit/asset-thumbnails';
+
+/** 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 `.volter-editor-theme`
+ * block; the `--volter-` 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(--volter-asset-icon-folder)',
+  model: 'var(--volter-asset-icon-model)',
+  prefab: 'var(--volter-asset-icon-prefab)',
+  component: 'var(--volter-asset-icon-component)',
+  audio: 'var(--volter-asset-icon-audio)',
+  image: 'var(--volter-asset-icon-image)',
+  video: 'var(--volter-asset-icon-video)',
+  json: 'var(--volter-asset-icon-json)',
+  unknown: 'var(--volter-asset-icon-unknown)',
+  source: 'var(--volter-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 renderer = assetThumbnailRenderer(url);
+  if (!renderer) return Promise.reject(new Error(`No model preview loader for ${url}.`));
+  return renderer.render(url);
+}, 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: `.volter/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="volter-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(--volter-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(--volter-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(--volter-bg-inset)" stroke={color} />
+      <path d="M13 15h26M13 23h18M13 31h22" stroke={color} strokeWidth="3" strokeLinecap="round" />
+    </svg>
+  );
+}

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

@@ -0,0 +1,201 @@
+import { Button, Checkbox, RangeInput, SectionHeader, themeVars } from '@volter/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="volter-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(--volter-asset-icon-audio)" />
+          <path
+            d="M9 8l4-2v12l-4-2H7V10h2zm6 1v6m2-5v4"
+            stroke="var(--volter-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(--volter-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(--volter-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/kit/components/asset-viewers/GenericJsonViewer.tsx

@@ -0,0 +1,102 @@
+import { SectionHeader, themeVars } from '@volter/sdk/widgets';
+import { servedUrl } from '@volter/sdk/kit/served-url';
+import { useEffect, useState } from 'react';
+import { CodeView, type CodeViewLanguage } from '../CodeView';
+
+const labelStyle: React.CSSProperties = {
+  fontSize: 11,
+  color: themeVars.content.muted,
+  marginBottom: 2,
+};
+
+export function GenericJsonViewer({ assetPath }: { assetPath: string }) {
+  const [content, setContent] = useState<string | null>(null);
+  // A file that failed to parse is shown verbatim, so it is shown as plain
+  // text too — JSON highlighting over non-JSON would be a lie about the bytes.
+  const [language, setLanguage] = useState<CodeViewLanguage>('json');
+  const [error, setError] = useState(false);
+  const fileName = assetPath.split('/').pop() ?? assetPath;
+
+  useEffect(() => {
+    let cancelled = false;
+    setContent(null);
+    setError(false);
+    fetch(servedUrl(assetPath))
+      .then((r) => r.text())
+      .then((text) => {
+        // Pretty-print if valid JSON
+        try {
+          const parsed = JSON.parse(text);
+          if (!cancelled) {
+            setLanguage('json');
+            setContent(JSON.stringify(parsed, null, 2));
+          }
+        } catch {
+          if (!cancelled) {
+            setLanguage('text');
+            setContent(text);
+          }
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setError(true);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [assetPath]);
+
+  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>
+      <div
+        // §2.31 P2 amendment: JSON text reads over a local frost layer.
+        className="volter-content-frost"
+        style={{
+          // §2.31: whole-body JSON well goes hairline-only — the panel
+          // surface shows through.
+          border: `1px solid ${themeVars.boundary.default}`,
+          borderRadius: themeVars.shape.small,
+          padding: 8,
+          // CodeView owns the scroll so its line-number gutter stays pinned;
+          // the well keeps the height budget it always had.
+          overflow: 'hidden',
+          maxHeight: 500,
+        }}
+      >
+        {error ? (
+          <span style={{ color: themeVars.semantic.danger, fontSize: 11 }}>
+            Failed to load file
+          </span>
+        ) : content === null ? (
+          <span style={{ color: themeVars.content.muted, fontSize: 11 }}>Loading...</span>
+        ) : (
+          <CodeView
+            value={content}
+            language={language}
+            fontSize={10}
+            maxHeight={484}
+            ariaLabel={`Contents of ${fileName}`}
+          />
+        )}
+      </div>
+      <SectionHeader label="Info" defaultOpen={false}>
+        <div>
+          <div style={labelStyle}>Path</div>
+          <div style={{ fontSize: 11, color: themeVars.content.primary, wordBreak: 'break-all' }}>
+            {assetPath}
+          </div>
+        </div>
+      </SectionHeader>
+    </div>
+  );
+}