@vgai/editor 0.4.0-canary.20260715.1 → 0.4.0

package/src/asset-editor-context.tsx

@@ -0,0 +1,130 @@
+/**
+ * Context contributed by the active typed Asset Editor to the existing editor
+ * shell. Asset documents own content; the workspace owns placement. Keeping
+ * this as a tiny external store lets Dockview's persistent Hierarchy,
+ * Inspector, bottom drawer, and status bar render the active document's
+ * context without an Asset Editor recreating those panes inside the center.
+ */
+
+import type { ReactNode } from 'react';
+import { useSyncExternalStore } from 'react';
+import { themeVars } from './design-system';
+import { createHmrRegistrationGroup } from './hmr-registration-group';
+import { registerWorkspaceStatus } from './workspace-status-registry';
+import { registerWorkspaceUtility } from './workspace-utility-registry';
+
+export const ASSET_EDITOR_CONTROLS_UTILITY_ID = 'asset-editor-controls';
+
+export interface AssetEditorContextValue {
+  readonly documentId: string;
+  readonly title: string;
+  readonly type: string;
+  readonly structure?: ReactNode;
+  readonly details?: ReactNode;
+  readonly status?: string;
+  readonly controls?: ReactNode;
+}
+
+interface ActiveAssetEditorContext extends AssetEditorContextValue {
+  readonly token: symbol;
+}
+
+let active: ActiveAssetEditorContext | null = null;
+let version = 0;
+const listeners = new Set<() => void>();
+
+function notifyChanged(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeAssetEditorContext(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function assetEditorContextVersion(): number {
+  return version;
+}
+
+export function getActiveAssetEditorContext(): AssetEditorContextValue | null {
+  return active;
+}
+
+/** Activate one document contribution. The returned disposer only clears the
+ * exact activation it created, so an older tab unmount cannot erase a newer
+ * active tab's context. */
+export function activateAssetEditorContext(value: AssetEditorContextValue): () => void {
+  const token = Symbol(value.documentId);
+  active = { ...value, token };
+  notifyChanged();
+  return () => {
+    if (active?.token !== token) return;
+    active = null;
+    notifyChanged();
+  };
+}
+
+export function AssetEditorControlsUtility() {
+  useSyncExternalStore(subscribeAssetEditorContext, assetEditorContextVersion);
+  const context = getActiveAssetEditorContext();
+  if (!context?.controls) return null;
+  return (
+    <div
+      data-testid="asset-editor-controls"
+      style={{
+        minHeight: 0,
+        padding: 8,
+        color: themeVars.content.primary,
+        pointerEvents: 'auto',
+      }}
+    >
+      {context.controls}
+    </div>
+  );
+}
+
+export function AssetEditorStatus() {
+  useSyncExternalStore(subscribeAssetEditorContext, assetEditorContextVersion);
+  const context = getActiveAssetEditorContext();
+  return context?.status ? (
+    <span data-testid="status-asset-editor" style={{ color: themeVars.content.muted }}>
+      {context.status}
+    </span>
+  ) : null;
+}
+
+const registrationGroup = createHmrRegistrationGroup(
+  import.meta.hot,
+  'asset-editor-shell-contributions',
+);
+
+export function ensureAssetEditorShellContributionsRegistered(): void {
+  registrationGroup.ensure((track) => {
+    track(
+      registerWorkspaceUtility({
+        id: ASSET_EDITOR_CONTROLS_UTILITY_ID,
+        title: 'Asset Controls',
+        Content: AssetEditorControlsUtility,
+        available: () => getActiveAssetEditorContext()?.controls != null,
+        visibleByDefault: false,
+        closeable: true,
+      }),
+    );
+    track(
+      registerWorkspaceStatus({
+        id: 'asset-editor-status',
+        align: 'left',
+        order: 40,
+        Content: AssetEditorStatus,
+      }),
+    );
+  });
+}
+
+ensureAssetEditorShellContributionsRegistered();
+
+export function __resetAssetEditorContextForTest(): void {
+  active = null;
+  notifyChanged();
+}

package/src/asset-preview.ts

@@ -785,6 +785,10 @@ function parseGltfData(
       data,
       new URL('.', sourceUrl).href,
       (gltf) => {
+        // GLTFLoader keeps clips on the GLTF result rather than its scene.
+        // Asset Editor's model contract is Object3D-shaped, so preserve those
+        // clips instead of silently degrading animated assets into static ones.
+        gltf.scene.animations = [...gltf.animations];
         if (!finish(() => resolve(gltf.scene))) {
           disposeOwnedModel(gltf.scene);
         }

package/src/asset-selection.ts

@@ -13,19 +13,19 @@
  * (mirrors `inspector-section-registry.ts`): version counter + subscribe +
  * `__resetForTest`. It deliberately does NOT touch the EditorStore's entity
  * selection — clicking an asset must never deselect/reselect scene entities
- * (§6.1 "selection never unexpectedly..."); instead the Inspector section
- * simply appears for the selected asset, and the selection is auto-cleared
+ * (§6.1 "selection never unexpectedly..."); instead the Inspector gives the
+ * asset domain precedence while retaining that entity selection, and the asset is auto-cleared
  * when the ENTITY selection changes (the user moved on — see
  * `installAssetSelectionAutoClear`).
  */
 
 import type { AssetCapabilities } from './asset-workflow/asset-capabilities';
-import type { AssetKind } from './editor-store';
+import type { AssetKind, OnlineAssetInfo } from './editor-store';
 
 /** The §5.1 compact-selection payload — enough for the Inspector section to
  *  render preview + metadata without re-deriving browser state. */
 export interface SelectedAsset {
-  /** Serving path (`/textures/crate.png`) — doubles as the open-document key. */
+  /** Project serving path, or a stable `online:<source>:<id>` document key. */
   readonly path: string;
   /** Source-owned file name as authored (§8 — `crate.png`). */
   readonly name: string;
@@ -39,6 +39,11 @@ export interface SelectedAsset {
   readonly dependencies?: readonly string[];
   readonly references?: readonly { ownerPath: string; jsonPath: string }[];
   readonly healthCodes?: readonly string[];
+  /** Selection came from the external acquisition Library rather than the
+   * project's owned file tree. `online` carries the provider identity and is
+   * intentionally absent from project assets. */
+  readonly origin?: 'project' | 'library';
+  readonly online?: OnlineAssetInfo;
 }
 
 let _selected: SelectedAsset | null = null;

package/src/asset-workflow/thumbnail-system.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { getStorageBackend } from '../storage';
+import { getStorageBackend, type StorageBackend } from '../storage';
 import type { AssetCatalog } from './asset-types';
 
 export const THUMBNAIL_PROFILE = {
@@ -39,15 +39,24 @@ export const thumbnailManifestSchema = z.object({
 export type ThumbnailManifest = z.infer<typeof thumbnailManifestSchema>;
 
 let manifestPromise: Promise<ThumbnailManifest | null> | null = null;
+
+/** Optional project thumbnail metadata must never block live fallback previews.
+ * HTTP-backed projects can return the Vite HTML shell for an absent file, so
+ * existence and parsing are both guarded at this storage boundary. */
+export async function readProjectThumbnailManifest(
+  backend: Pick<StorageBackend, 'read'>,
+): Promise<ThumbnailManifest | null> {
+  try {
+    return thumbnailManifestSchema.parse(JSON.parse(await backend.read('.vgai/thumbnails.json')));
+  } catch {
+    return null;
+  }
+}
+
 export function loadProjectThumbnailManifest(): Promise<ThumbnailManifest | null> {
   if (!manifestPromise) {
     const backend = getStorageBackend() as ReturnType<typeof getStorageBackend> | undefined;
-    manifestPromise = backend
-      ? backend.read('.vgai/thumbnails.json').then(
-          (content) => thumbnailManifestSchema.parse(JSON.parse(content)),
-          () => null,
-        )
-      : Promise.resolve(null);
+    manifestPromise = backend ? readProjectThumbnailManifest(backend) : Promise.resolve(null);
   }
   return manifestPromise;
 }

package/src/components/AssetBrowser.tsx

@@ -33,7 +33,6 @@ import {
   ThumbnailJobQueue,
 } from '../asset-workflow/thumbnail-system';
 import {
-  accent,
   Button,
   border,
   EditorIcon,
@@ -119,7 +118,12 @@ function AssetIcon({ kind, size = 24 }: { kind: BrowserKind; size?: number }) {
 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 });
+  return getModelThumbnailRenderer().render({
+    url,
+    format,
+    background: 'neutral',
+    output: 'webp',
+  });
 }, 2);
 
 function ModelThumbnail({ url }: { url: string }) {
@@ -175,7 +179,7 @@ function ModelThumbnail({ url }: { url: string }) {
           setManifestPath(null);
           setManifestRejected(true);
         }}
-        style={{ maxWidth: 48, maxHeight: 48, objectFit: 'contain', borderRadius: radius.sm }}
+        style={{ width: '100%', height: '100%', objectFit: 'contain' }}
       />
     );
   }
@@ -209,7 +213,7 @@ function ModelThumbnail({ url }: { url: string }) {
     <img
       src={src}
       alt="model preview"
-      style={{ maxWidth: 48, maxHeight: 48, objectFit: 'contain', borderRadius: radius.sm }}
+      style={{ width: '100%', height: '100%', objectFit: 'contain' }}
     />
   );
 }
@@ -521,8 +525,9 @@ function BrowserEntryCard({
 
   return (
     <div
-      className="vgai-selectable"
+      className="vgai-selectable vgai-project-asset-entry"
       data-selected={selected || undefined}
+      data-view={viewMode}
       role="option"
       aria-selected={selected}
       tabIndex={0}
@@ -543,14 +548,15 @@ function BrowserEntryCard({
         ...(grid ? GRID_ENTRY_STYLE : LIST_ENTRY_STYLE),
         borderRadius: radius.sm,
         cursor,
-        border: selected ? `1px solid ${accent}` : '1px solid transparent',
         userSelect: 'none',
       }}
     >
       <div
+        className="vgai-project-asset-entry__preview"
+        data-testid="asset-entry-preview"
         style={{
           ...(grid
-            ? { width: 48, height: 48, margin: '0 auto 4px' }
+            ? { width: '100%', aspectRatio: '4 / 3', margin: '0 auto' }
             : { width: 18, height: 18, margin: 0 }),
           display: 'flex',
           alignItems: 'center',
@@ -1309,6 +1315,8 @@ export function AssetBrowser({ onOpenScene }: AssetBrowserProps) {
 
         {/* One file-browser surface; grid/list are presentation modes, not navigation. */}
         <div
+          className="vgai-project-assets-results"
+          data-view={viewMode}
           style={{
             flex: 1,
             overflowY: 'auto',

package/src/components/AssetEditorShell.tsx

@@ -1,141 +1,71 @@
 import type { ReactNode } from 'react';
-import { useEffect, useState } from 'react';
-import { Button, border, TextInput, text } from '../design-system';
-import { getCurrentProject } from '../project-manager';
-
-export interface AssetEditorLayout {
-  structureCollapsed: boolean;
-  detailsCollapsed: boolean;
-  structureWidth: number;
-  detailsWidth: number;
-}
-
-const defaults: AssetEditorLayout = {
-  structureCollapsed: false,
-  detailsCollapsed: false,
-  structureWidth: 240,
-  detailsWidth: 300,
-};
-
-export function assetEditorLayoutKey(
-  type: string,
-  projectId = getCurrentProject()?.rootPath ?? '__unscoped__',
-): string {
-  return `vgai:asset-editor-layout:${projectId}:${type}`;
-}
-
-export function readAssetEditorLayout(type: string): AssetEditorLayout {
-  if (typeof localStorage === 'undefined') return defaults;
-  try {
-    return { ...defaults, ...JSON.parse(localStorage.getItem(assetEditorLayoutKey(type)) ?? '{}') };
-  } catch {
-    return defaults;
-  }
-}
+import { useEffect } from 'react';
+import {
+  ASSET_EDITOR_CONTROLS_UTILITY_ID,
+  activateAssetEditorContext,
+} from '../asset-editor-context';
+import { Button } from '../design-system';
+import { showWorkspaceUtility } from '../workspace-dock-controller';
 
 export function AssetEditorShell({
+  documentId,
+  active = true,
   type,
   title,
   toolbar,
   structure,
   details,
   status,
+  controls,
   children,
 }: {
+  documentId: string;
+  active?: boolean;
   type: string;
   title: string;
   toolbar?: ReactNode;
   structure?: ReactNode;
   details?: ReactNode;
-  status?: ReactNode;
+  status?: string;
+  controls?: ReactNode;
   children: ReactNode;
 }) {
-  const [layout, setLayout] = useState(() => readAssetEditorLayout(type));
   useEffect(() => {
-    localStorage.setItem(assetEditorLayoutKey(type), JSON.stringify(layout));
-  }, [layout, type]);
+    if (!active) return;
+    return activateAssetEditorContext({
+      documentId,
+      title,
+      type,
+      ...(structure ? { structure } : {}),
+      ...(details ? { details } : {}),
+      ...(status ? { status } : {}),
+      ...(controls ? { controls } : {}),
+    });
+  }, [active, controls, details, documentId, status, structure, title, type]);
+
+  const hasToolbar = toolbar != null || controls != null;
   return (
     <section
       className="vgai-asset-editor"
       data-testid={`asset-editor:${type}`}
-      data-structure-collapsed={layout.structureCollapsed}
-      data-details-collapsed={layout.detailsCollapsed}
-      style={
-        {
-          '--asset-editor-structure-width': `${layout.structureWidth}px`,
-          '--asset-editor-details-width': `${layout.detailsWidth}px`,
-        } as React.CSSProperties
-      }
+      aria-label={`${title} Asset Editor`}
     >
-      <header className="vgai-asset-editor__toolbar">
-        <strong title={title}>{title}</strong>
-        <div className="vgai-asset-editor__commands">{toolbar}</div>
-        {structure && (
-          <Button
-            type="button"
-            aria-pressed={!layout.structureCollapsed}
-            onClick={() =>
-              setLayout((value) => ({ ...value, structureCollapsed: !value.structureCollapsed }))
-            }
-          >
-            Structure
-          </Button>
-        )}
-        {details && (
-          <Button
-            type="button"
-            aria-pressed={!layout.detailsCollapsed}
-            onClick={() =>
-              setLayout((value) => ({ ...value, detailsCollapsed: !value.detailsCollapsed }))
-            }
-          >
-            Details
-          </Button>
-        )}
-      </header>
-      {structure && (
-        <aside className="vgai-asset-editor__structure" aria-label="Asset structure">
-          {structure}
-          <label className="vgai-asset-editor__resize">
-            Structure width
-            <TextInput
-              aria-label="Asset structure pane width"
-              type="range"
-              min={180}
-              max={420}
-              value={layout.structureWidth}
-              onChange={(event) =>
-                setLayout((value) => ({ ...value, structureWidth: Number(event.target.value) }))
-              }
-            />
-          </label>
-        </aside>
+      {hasToolbar && (
+        <header className="vgai-asset-editor__toolbar">
+          <div className="vgai-asset-editor__commands">{toolbar}</div>
+          {controls != null && (
+            <Button
+              type="button"
+              variant="ghost"
+              size="compact"
+              onClick={() => showWorkspaceUtility(ASSET_EDITOR_CONTROLS_UTILITY_ID)}
+            >
+              Controls
+            </Button>
+          )}
+        </header>
       )}
       <main className="vgai-asset-editor__viewport">{children}</main>
-      {details && (
-        <aside className="vgai-asset-editor__details" aria-label="Asset details">
-          {details}
-          <label className="vgai-asset-editor__resize">
-            Details width
-            <TextInput
-              aria-label="Asset details pane width"
-              type="range"
-              min={220}
-              max={480}
-              value={layout.detailsWidth}
-              onChange={(event) =>
-                setLayout((value) => ({ ...value, detailsWidth: Number(event.target.value) }))
-              }
-            />
-          </label>
-        </aside>
-      )}
-      <footer
-        className="vgai-asset-editor__status"
-        style={{ borderColor: border[1], color: text[2] }}
-      >
-        {status}
-      </footer>
     </section>
   );
 }

package/src/components/AssetImportDetails.tsx

@@ -15,20 +15,37 @@ export function AssetImportDetails({ assetPath }: { assetPath: string }) {
   useEffect(() => {
     let cancelled = false;
     const path = importRecipePath(assetPath);
-    getStorageBackend()
-      .read(path)
+    const backend = getStorageBackend();
+    backend
+      .exists(path)
+      .then((exists) => (exists ? backend.read(path) : null))
       .then(
         (content) => {
           if (cancelled) return;
-          const plan = assetImportPlanSchema.parse(JSON.parse(content));
-          setSaved(plan);
-          setDraft(plan);
-          setError(null);
+          if (content === null) {
+            setSaved(null);
+            setDraft(null);
+            setError(null);
+            return;
+          }
+          try {
+            const plan = assetImportPlanSchema.parse(JSON.parse(content));
+            setSaved(plan);
+            setDraft(plan);
+            setError(null);
+          } catch (cause) {
+            setSaved(null);
+            setDraft(null);
+            setError(
+              `Invalid import recipe: ${cause instanceof Error ? cause.message : String(cause)}`,
+            );
+          }
         },
         () => {
           if (!cancelled) {
             setSaved(null);
             setDraft(null);
+            setError(null);
           }
         },
       );
@@ -50,6 +67,7 @@ export function AssetImportDetails({ assetPath }: { assetPath: string }) {
     return (
       <SectionHeader label="Import">
         <div>No saved import recipe. Native project asset.</div>
+        {error && <div style={{ color: danger }}>{error}</div>}
       </SectionHeader>
     );
   const setSetting = <K extends keyof AssetImportPlan['settings']>(

package/src/components/AssetLibraryPanel.tsx

@@ -8,7 +8,7 @@ import { OnlineAssetBrowser } from './OnlineAssetBrowser';
 export function AssetLibraryPanel() {
   return (
     <div className="vgai-asset-library-panel" data-testid="asset-library-panel">
-      <OnlineAssetBrowser layout="navigator" />
+      <OnlineAssetBrowser />
     </div>
   );
 }

package/src/components/GameHierarchy.tsx

@@ -83,6 +83,11 @@ import {
   faTriangleExclamation,
 } from '@fortawesome/free-solid-svg-icons';
 import { useCallback, useEffect, useReducer, useRef, useState, useSyncExternalStore } from 'react';
+import {
+  assetEditorContextVersion,
+  getActiveAssetEditorContext,
+  subscribeAssetEditorContext,
+} from '../asset-editor-context';
 import { getActiveAuthoring, hasAuthoringOverride } from '../authoring/active-adapter';
 import { CompositeAuthoringAdapter } from '../authoring/composite-authoring-adapter';
 import { requestWorldFocus, worldFocusScenePath } from '../authoring/edit-mode-authoring';
@@ -1342,7 +1347,7 @@ function Row({
 
 // --- Main panel ---
 
-export function GameHierarchy() {
+function SceneHierarchyContent() {
   const store = useEditorStore();
   useSyncExternalStore(store.subscribe, store.getSnapshot);
   const adapter = getActiveAuthoring(store);
@@ -1930,3 +1935,23 @@ export function GameHierarchy() {
     </Panel>
   );
 }
+
+/** The navigator slot follows the active center document. Scene/world
+ * documents use the normal authoring hierarchy; a structured Asset Editor
+ * contributes its model/bone/material outline into this same outer panel. */
+export function GameHierarchy() {
+  useSyncExternalStore(subscribeAssetEditorContext, assetEditorContextVersion);
+  const context = getActiveAssetEditorContext();
+  if (!context?.structure) return <SceneHierarchyContent />;
+  return (
+    <Panel
+      name={`${context.title} Structure`}
+      hideHeader
+      data-testid="asset-editor-structure"
+      onPointerDown={() => setActiveScope('hierarchy')}
+      style={{ flex: 1, minWidth: 0, minHeight: 0, overflow: 'auto' }}
+    >
+      {context.structure}
+    </Panel>
+  );
+}

package/src/components/Inspector.tsx

@@ -27,7 +27,16 @@ import type { AuthoringAdapter, EditorNode, PropertyDescriptor, Transform } from
 import { faXmark } from '@fortawesome/free-solid-svg-icons';
 import { useSyncExternalStore } from 'react';
 import * as THREE from 'three';
-import { assetSelectionVersion, subscribeAssetSelection } from '../asset-selection';
+import {
+  assetEditorContextVersion,
+  getActiveAssetEditorContext,
+  subscribeAssetEditorContext,
+} from '../asset-editor-context';
+import {
+  assetSelectionVersion,
+  getSelectedAsset,
+  subscribeAssetSelection,
+} from '../asset-selection';
 import { getActiveAuthoring } from '../authoring/active-adapter';
 import { CompositeAuthoringAdapter } from '../authoring/composite-authoring-adapter';
 import { ReactWorldAuthoringAdapter } from '../authoring/react-world-authoring-adapter';
@@ -57,6 +66,7 @@ import {
   workspaceDocumentRegistryVersion,
 } from '../workspace-document-registry';
 import { openEntityAssetDocument } from './asset-documents';
+import { AssetSelectionSection } from './asset-selection-section';
 import { groupProperties } from './inspector-property-grouping';
 import { groupLabelStyle, LABEL_COL_WIDTH } from './inspector-widgets/shared';
 
@@ -179,7 +189,7 @@ function AxisRow({
   );
 }
 
-export function Inspector() {
+function SceneInspector() {
   const store = useEditorStore();
   useSyncExternalStore(store.subscribe, store.getSnapshot);
   // Re-render when section registrations change (W3): project inspector
@@ -723,3 +733,29 @@ export function Inspector() {
     </Panel>
   );
 }
+
+/** Asset documents reuse the ONE outer Inspector rather than rendering a
+ * second details rail inside the center document. */
+export function Inspector() {
+  useSyncExternalStore(subscribeAssetEditorContext, assetEditorContextVersion);
+  useSyncExternalStore(subscribeAssetSelection, assetSelectionVersion);
+  const context = getActiveAssetEditorContext();
+  const selectedAsset = getSelectedAsset();
+  if (!context?.details && !selectedAsset) return <SceneInspector />;
+  return (
+    <Panel
+      name="Inspector"
+      hideHeader
+      data-testid="inspector-panel"
+      onPointerDown={() => setActiveScope('inspector')}
+      style={{ overflowY: 'auto' }}
+    >
+      <div
+        data-testid={context ? 'asset-editor-details' : 'asset-selection-details'}
+        style={{ pointerEvents: 'auto', padding: context ? 8 : 0 }}
+      >
+        {context?.details ?? <AssetSelectionSection />}
+      </div>
+    </Panel>
+  );
+}