@volter/sdk 0.0.0-stage → 0.5.203

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

@@ -0,0 +1,356 @@
+import { AssetViewerSlot } from '@volter/sdk/kit/asset-viewers';
+import { themeVars } from '@volter/sdk/widgets';
+import { useEffect, useState, useSyncExternalStore } from 'react';
+import { declaredRoots } from '@volter/project/adapter/manifest-interpreter';
+import { loadGameManifest, type ResolvedAdapterRoot } from '@volter/project/manifest/load';
+import { assetCapabilities } from '@volter/sdk/kit/asset-capabilities';
+import { getCurrentProject } from '@volter/sdk/kit/project-manager';
+import { projectAdapterFacet, subscribeProjectAdapter } from '@volter/sdk/kit/project-adapter';
+import { resolveFileRegion } from '@volter/sdk/kit/ui-source/file-region-resolver';
+import { editorServerJson } from '@volter/sdk/kit/editor-server-response';
+import {
+  projectModuleChangeMatches,
+  subscribeProjectModuleChange,
+} from '@volter/sdk/kit/project-module-changes';
+import { AssetEditorShell } from '@volter/sdk/kit/components/AssetEditorShell';
+import { CodeView, codeViewLanguage } from '../CodeView';
+import { AudioViewer } from './AudioViewer';
+import { ImageViewer } from './ImageViewer';
+import { JsonAssetDocument } from './JsonAssetDocument';
+
+export type SourceAssetRoute =
+  | 'model'
+  | 'image'
+  | 'audio'
+  | 'json'
+  | 'environment'
+  | 'lut'
+  | 'shader'
+  | 'module'
+  | 'text'
+  | 'binary';
+
+/**
+ * A project script the editor can EXECUTE, and therefore a candidate live
+ * model module (`LiveModuleDocument`). The bound is the dev server's own: only
+ * `src/**` scripts are classified, HMR-stamped and re-served on save
+ * (`server/project-hmr-files.ts`'s `classifyProjectHotUpdate` returns `ignore`
+ * for everything else), so a script outside `src/` could be imported once but
+ * never re-executed — a live document that silently stops being live. Whether
+ * such a module actually BUILDS an `Object3D` is decided by running it, never
+ * by its name.
+ */
+function isProjectScriptPath(assetPath: string): boolean {
+  const clean = (assetPath.split(/[?#]/, 1)[0] ?? '').replace(/^\//, '');
+  return clean.startsWith('src/') && /\.(?:[cm]?[jt]sx?)$/.test(clean);
+}
+
+export function sourceAssetRoute(assetPath: string): SourceAssetRoute {
+  const capability = assetCapabilities(assetPath);
+  if (capability.editor === 'model') return 'model';
+  if (capability.editor === 'image') return 'image';
+  if (capability.editor === 'audio') return 'audio';
+  if (capability.editor === 'data') return 'json';
+  if (capability.editor === 'environment') return 'environment';
+  if (capability.format === 'cube') return 'lut';
+  if (capability.format === 'glsl' || capability.format === 'vert' || capability.format === 'frag')
+    return 'shader';
+  if (isProjectScriptPath(assetPath)) return 'module';
+  if (capability.editor === 'source' && capability.previewable) return 'text';
+  return 'binary';
+}
+
+/**
+ * THE FILE IS THE SUBJECT.
+ *
+ * A source/module document had no selection context of its own, and
+ * `waitForAssetDocumentInspector` waits for exactly that — so
+ * `editor.openAsset('/src/foo.ts', 'source')` opened the document, showed the
+ * code, and then sat until the relay's budget ran out and reported a
+ * `play-stall`: a timeout about the tab for a document that was already on
+ * screen. (The JSON route acked because `JsonAssetDocument` goes through
+ * `AssetEditorShell`.)
+ *
+ * There is no invented subject here and nothing new to publish: a source
+ * document's subject is the FILE, its identity row is the filename and the
+ * kind, and its note is the Info the shell already shows for every other
+ * asset — so it registers through the SAME holder every Asset Lab document
+ * uses (`AssetEditorShell` → `AssetEditorSubject`) rather than growing a
+ * second one.
+ */
+function TextSourcePreview({
+  documentId,
+  assetPath,
+  active = true,
+}: {
+  readonly documentId: string;
+  readonly assetPath: string;
+  readonly active?: boolean;
+}) {
+  const [content, setContent] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const fileName = assetPath.split('/').pop() ?? assetPath;
+  useEffect(() => {
+    let cancelled = false;
+    setContent(null);
+    setError(null);
+    const path = assetPath.replace(/^\//, '');
+    let revision = 0;
+    async function read() {
+      const request = ++revision;
+      try {
+        // The author's file as written — the project's dev server would answer
+        // a module path with its TRANSFORMED output (the globals prelude, the
+        // compiled JSX), which is not the source this document shows.
+        const url = `/__editor/source-file?path=${encodeURIComponent(path)}`;
+        const value = await fetch(url, { cache: 'no-store' }).then((response) => {
+          if (!response.ok) throw new Error(`HTTP ${response.status}`);
+          return response.text();
+        });
+        if (!cancelled && request === revision) {
+          setContent(value);
+          setError(null);
+        }
+      } catch (reason) {
+        if (!cancelled && request === revision)
+          setError(reason instanceof Error ? reason.message : String(reason));
+      }
+    }
+    const refresh = (changed: string) => {
+      if (projectModuleChangeMatches(changed, path)) void read();
+    };
+    const stop = subscribeProjectModuleChange(refresh);
+    void read();
+    return () => {
+      cancelled = true;
+      stop();
+    };
+  }, [assetPath]);
+  return (
+    <AssetEditorShell
+      documentId={documentId}
+      active={active}
+      type="source"
+      title={fileName}
+      sections={[]}
+      status={`source · ${assetPath}`}
+      fill
+    >
+      <div
+        style={{
+          padding: 12,
+          height: '100%',
+          minHeight: 0,
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 8,
+        }}
+      >
+        <div
+          style={{
+            padding: 8,
+            // The well GROWS to the panel instead of stopping at a fixed
+            // budget: this document is a whole tab, and CodeView virtualizes,
+            // so there is nothing to buy by capping it. (It inherited a
+            // 560px ceiling from the small in-panel preview it was cut from,
+            // which left most of a full-tab source document empty.)
+            flex: 1,
+            minHeight: 0,
+            display: 'flex',
+            overflow: 'hidden',
+            background: themeVars.surface.inset,
+            border: `1px solid ${themeVars.boundary.default}`,
+            borderRadius: themeVars.shape.small,
+          }}
+        >
+          {error !== null || content === null ? (
+            <div
+              style={{
+                fontFamily: themeVars.typography.mono,
+                fontSize: 11,
+                lineHeight: 1.5,
+                color: error ? themeVars.semantic.danger : themeVars.content.muted,
+                padding: 4,
+              }}
+            >
+              {error ?? 'Loading…'}
+            </div>
+          ) : (
+            <CodeView
+              value={content}
+              followChanges
+              language={codeViewLanguage(assetPath)}
+              fontSize={11}
+              maxHeight="100%"
+              ariaLabel={`Source of ${assetPath}`}
+            />
+          )}
+        </div>
+      </div>
+    </AssetEditorShell>
+  );
+}
+
+/** A format whose native view no integration in this composition provides: the
+ *  file is still a document with its own identity, like the binary route below. */
+function NoNativeViewer({
+  documentId,
+  assetPath,
+  active,
+}: {
+  readonly documentId: string;
+  readonly assetPath: string;
+  readonly active: boolean;
+}) {
+  const name = assetPath.split('/').pop() ?? assetPath;
+  return (
+    <AssetEditorShell
+      documentId={documentId}
+      active={active}
+      type="source"
+      title={name}
+      sections={[]}
+      status={`no viewer · ${assetPath}`}
+    >
+      <div style={{ padding: 16, color: themeVars.content.muted, fontSize: 12 }}>
+        No editor package in this project renders {name}; the file is available in the project
+        and stays selectable and referenceable.
+      </div>
+    </AssetEditorShell>
+  );
+}
+
+/** Read the file's declared surface before executing a possible model builder.
+ * A DOM or canvas component is source here; calling it outside its renderer
+ * can throw (React hooks), or perform work just to discover it is not a model.
+ * Unplaced modules retain the existing Object3D builder contract. */
+function ProjectModuleSourceViewer({ documentId, assetPath, active }: {
+  documentId: string;
+  assetPath: string;
+  active: boolean;
+}) {
+  const projectRoot = getCurrentProject()?.rootPath;
+  const facet = useSyncExternalStore(subscribeProjectAdapter, projectAdapterFacet);
+  const [roots, setRoots] = useState<readonly ResolvedAdapterRoot[] | null>(null);
+  const [declarationError, setDeclarationError] = useState<string | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    setRoots(null);
+    setDeclarationError(null);
+    if (!projectRoot || !facet) return;
+    void (async () => {
+      try {
+        const raw = await editorServerJson<unknown>(
+          await fetch('/volter.project.json', { cache: 'no-store' }),
+          'Reading this source file’s declared surface failed',
+        );
+        const manifest = loadGameManifest(raw, { configurationKinds: 'defer' });
+        if (!cancelled) setRoots(declaredRoots(manifest));
+      } catch (error) {
+        if (!cancelled) setDeclarationError(error instanceof Error ? error.message : String(error));
+      }
+    })();
+    return () => { cancelled = true; };
+  }, [projectRoot, facet]);
+  const preview = <TextSourcePreview documentId={documentId} assetPath={assetPath} active={active} />;
+  // Unknown declarations are not permission to execute the source.
+  if (!projectRoot || !facet || !roots || declarationError) return <>
+    {declarationError && <div role="alert">{declarationError}</div>}
+    {preview}
+  </>;
+  const path = (assetPath.split(/[?#]/, 1)[0] ?? '').replaceAll('\\', '/').replace(/^\.\//, '').replace(/^\//, '');
+  const region = resolveFileRegion({
+    file: path,
+    projectRelative: path,
+    regions: facet.regions,
+    regionOfEntry: (file) => {
+      const root = roots.find((candidate) => candidate.entry?.replace(/^\.\//, '') === file);
+      return root ? facet.regions.find((candidate) => candidate.id === root.id) : undefined;
+    },
+  });
+  if (region.surface === 'dom' || region.surface === 'canvas') return preview;
+  return <AssetViewerSlot route="module" documentId={documentId} assetPath={assetPath}
+    projectRoot={projectRoot} displayName={assetPath.split('/').pop() ?? assetPath}
+    active={active} fallback={preview} whenUnregistered={preview} />;
+}
+
+/** Viewer for downloaded catalog source/animation files without a magic fallback. */
+export function SourceAssetViewer({
+  documentId,
+  assetPath,
+  active = true,
+}: {
+  documentId: string;
+  assetPath: string;
+  active?: boolean;
+}) {
+  switch (sourceAssetRoute(assetPath)) {
+    case 'model':
+    case 'environment':
+    case 'lut':
+    case 'shader': {
+      // The format's native view is the media integration's
+      // (`@volter/sdk/kit/asset-viewers`); without one, the file is
+      // still opened as what it is.
+      const route = sourceAssetRoute(assetPath) as 'model' | 'environment' | 'lut' | 'shader';
+      return (
+        <AssetViewerSlot
+          route={route}
+          documentId={documentId}
+          assetPath={assetPath}
+          displayName={assetPath.split('/').pop() ?? assetPath}
+          active={active}
+          whenUnregistered={<NoNativeViewer documentId={documentId} assetPath={assetPath} active={active} />}
+        />
+      );
+    }
+    case 'image':
+      return <ImageViewer assetPath={assetPath} />;
+    case 'audio':
+      return <AudioViewer assetPath={assetPath} />;
+    case 'json':
+      // Content-routed: a native three.quarks document opens as the particle
+      // editor, any other JSON keeps the generic viewer.
+      return (
+        <JsonAssetDocument
+          documentId={documentId}
+          assetPath={assetPath}
+          displayName={assetPath.split('/').pop() ?? assetPath}
+          active={active}
+          sections={[]}
+          status={`json · ${assetPath}`}
+        />
+      );
+    case 'module': {
+      // Content-routed, like the quarks JSON above: a project script that
+      // BUILDS an Object3D opens as the live modeling document; anything else
+      // keeps this viewer's text preview.
+      return <ProjectModuleSourceViewer documentId={documentId} assetPath={assetPath} active={active} />;
+    }
+    case 'text':
+      return <TextSourcePreview documentId={documentId} assetPath={assetPath} active={active} />;
+    case 'binary':
+      // Same subject rule as the text route above — the FILE. A document that
+      // publishes nothing is a document `editor.openAsset` can only time out
+      // against, and "no renderer" is not "no identity".
+      return (
+        <AssetEditorShell
+          documentId={documentId}
+          active={active}
+          type="binary source"
+          title={assetPath.split('/').pop() ?? assetPath}
+          sections={[]}
+          status={`binary · ${assetPath}`}
+        >
+          <div style={{ padding: 16, color: themeVars.content.muted, fontSize: 12 }}>
+            <div style={{ color: themeVars.content.primary, fontWeight: 600, marginBottom: 6 }}>
+              {assetPath.split('/').pop()}
+            </div>
+            This binary source is available in the project, but it has no safe in-editor renderer.
+            Its file remains selectable and referenceable without being misidentified as another
+            format.
+          </div>
+        </AssetEditorShell>
+      );
+  }
+}

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

@@ -0,0 +1,102 @@
+/**
+ * One sprite from a packed atlas — Aseprite's cel / Unity's Sprite /
+ * Godot's AtlasTexture. The sheet is the source texture; this paints the
+ * named frame onto the untrimmed canvas at nearest-neighbor.
+ */
+import { useEffect, useRef } from 'react';
+import { integerFitScale } from '../../asset-workflow/image-view-scale';
+import { type PixiSpritesheetFrame, packedFrameRect } from '@volter/sdk/kit/asset-workflow/pixi-spritesheet';
+
+export function paintSpriteFrame(
+  canvas: HTMLCanvasElement,
+  image: CanvasImageSource,
+  frame: PixiSpritesheetFrame,
+): void {
+  const destWidth = Math.max(1, frame.sourceWidth ?? frame.width);
+  const destHeight = Math.max(1, frame.sourceHeight ?? frame.height);
+  canvas.width = destWidth;
+  canvas.height = destHeight;
+  const context = canvas.getContext('2d');
+  if (!context) return;
+  context.imageSmoothingEnabled = false;
+  context.clearRect(0, 0, destWidth, destHeight);
+  const packed = packedFrameRect(frame);
+  if (frame.rotated) {
+    context.save();
+    context.translate(frame.trimX, frame.trimY + packed.width);
+    context.rotate(-Math.PI / 2);
+    context.drawImage(
+      image,
+      packed.x,
+      packed.y,
+      packed.width,
+      packed.height,
+      0,
+      0,
+      packed.width,
+      packed.height,
+    );
+    context.restore();
+    return;
+  }
+  context.drawImage(
+    image,
+    packed.x,
+    packed.y,
+    packed.width,
+    packed.height,
+    frame.trimX,
+    frame.trimY,
+    packed.width,
+    packed.height,
+  );
+}
+
+export function SpritesheetSpriteView({
+  sheetUrl,
+  frame,
+  scale,
+  maxEdge,
+}: {
+  sheetUrl: string;
+  frame: PixiSpritesheetFrame;
+  scale?: number;
+  maxEdge?: number;
+}) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const destWidth = Math.max(1, frame.sourceWidth ?? frame.width);
+  const destHeight = Math.max(1, frame.sourceHeight ?? frame.height);
+  const resolved =
+    maxEdge != null ? integerFitScale(destWidth, destHeight, maxEdge, maxEdge) : (scale ?? 1);
+  const displayWidth = Math.max(1, Math.round(destWidth * resolved));
+  const displayHeight = Math.max(1, Math.round(destHeight * resolved));
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const image = new Image();
+    let cancelled = false;
+    image.onload = () => {
+      if (!cancelled) paintSpriteFrame(canvas, image, frame);
+    };
+    image.src = sheetUrl;
+    return () => {
+      cancelled = true;
+    };
+  }, [frame, sheetUrl]);
+
+  return (
+    <canvas
+      ref={canvasRef}
+      width={destWidth}
+      height={destHeight}
+      aria-hidden
+      style={{
+        width: displayWidth,
+        height: displayHeight,
+        imageRendering: 'pixelated',
+        display: 'block',
+      }}
+    />
+  );
+}

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

@@ -0,0 +1,101 @@
+/**
+ * Video Asset Lab document: the clip itself, with the browser's own controls.
+ *
+ * Deliberately no custom transport, no autoplay and no muting — a reference
+ * clip is watched, and `<video controls>` is already the control surface every
+ * person on this machine knows. The bytes come from the session, which serves
+ * the project's own files.
+ */
+
+import { Text, text } from '@volter/sdk/widgets';
+import { useCallback, useEffect, useState } from 'react';
+
+export function VideoViewer({ assetPath }: { assetPath: string }) {
+  const [failed, setFailed] = useState(false);
+  const [size, setSize] = useState<{ w: number; h: number } | null>(null);
+  const source = assetPath;
+  useEffect(() => {
+    setFailed(false);
+  }, [source]);
+  const name = assetPath.split('/').pop() ?? assetPath;
+  const measure = useCallback((element: HTMLVideoElement | null) => {
+    if (!element) return;
+    if (element.error) {
+      setFailed(true);
+      return;
+    }
+    if (element.videoWidth <= 0) return;
+    setSize((current) =>
+      current && current.w === element.videoWidth && current.h === element.videoHeight
+        ? current
+        : { w: element.videoWidth, h: element.videoHeight },
+    );
+  }, []);
+
+  return (
+    <div
+      data-testid="video-asset-document"
+      style={{
+        height: '100%',
+        minHeight: 240,
+        display: 'flex',
+        flexDirection: 'column',
+        minWidth: 0,
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', gap: 6, padding: '6px 8px' }}>
+        <Text tone="dim" variant="label">
+          {name}
+        </Text>
+        {size && (
+          <Text tone="muted" variant="code">
+            {size.w} × {size.h}
+          </Text>
+        )}
+      </div>
+      <div
+        className="volter-asset-transparency-well"
+        style={{
+          flex: 1,
+          minHeight: 0,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          padding: 12,
+        }}
+      >
+        {failed ? (
+          <div style={{ color: text[2], fontSize: 12, textAlign: 'center' }}>
+            {name} could not be played from {source}. The file may be missing, or its codec may not
+            be one this browser decodes.
+          </div>
+        ) : (
+          <video
+            key={source}
+            src={source}
+            controls
+            playsInline
+            preload="metadata"
+            // MEASURED, not just listened for: a clip whose metadata is already
+            // decoded when React attaches (a cached file, a reopened document)
+            // fires `loadedmetadata` BEFORE the listener exists, and the header
+            // then reported no dimensions over a video the layout had already
+            // sized from real ones. The ref reads the element's own state on
+            // attach; the event covers everything that arrives later.
+            //
+            // `measure` is STABLE and its write is a no-change guard, both for
+            // the same reason: an inline ref is a new function every render, so
+            // React detaches and re-runs it every render, and a `setSize` that
+            // writes a fresh object each time is then an infinite update loop.
+            // Measured here — it took the editor's chrome down with
+            // "Maximum update depth exceeded".
+            ref={measure}
+            onError={() => setFailed(true)}
+            onLoadedMetadata={(event) => measure(event.currentTarget)}
+            style={{ maxWidth: '100%', maxHeight: '100%', display: 'block' }}
+          />
+        )}
+      </div>
+    </div>
+  );
+}