mcard-studio 0.0.0-stage → 0.0.2

package/src/components/studio/views/cardViewlets/spatial3d/hooks/use3DModelLoader.ts

@@ -0,0 +1,118 @@
+/**
+ * 3D Model Loader Hook
+ * Canonical Path: src/components/studio/views/cardViewlets/spatial3d/hooks/use3DModelLoader.ts
+ */
+
+import { useState, useEffect, useRef } from 'react';
+import * as THREE from 'three';
+import { modelLoaderRegistry } from '../modelLoaderRegistry';
+
+export interface ModelStats {
+  vertices: number;
+  faces: number;
+}
+
+export interface Use3DModelLoaderOptions {
+  rawUrl: string;
+  formatExt: string;
+  modelGroupRef: React.RefObject<THREE.Group | null>;
+}
+
+export function use3DModelLoader(options: Use3DModelLoaderOptions) {
+  const { rawUrl, formatExt, modelGroupRef } = options;
+
+  const [isLoading, setIsLoading] = useState(true);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [stats, setStats] = useState<ModelStats>({ vertices: 0, faces: 0 });
+  const originalMaterialsRef = useRef<Map<THREE.Mesh, THREE.Material | THREE.Material[]>>(new Map());
+
+  useEffect(() => {
+    let isSubscribed = true;
+    setIsLoading(true);
+    setLoadError(null);
+
+    async function load() {
+      try {
+        const loadedRoot = await modelLoaderRegistry.load(formatExt, rawUrl);
+        if (!isSubscribed) return;
+
+        const modelGroup = modelGroupRef.current;
+        if (!modelGroup) return;
+
+        // Clear previous models
+        while (modelGroup.children.length > 0) {
+          modelGroup.remove(modelGroup.children[0]);
+        }
+        originalMaterialsRef.current.clear();
+
+        let totalVertices = 0;
+        let totalFaces = 0;
+
+        loadedRoot.traverse((child: any) => {
+          if (child.isMesh) {
+            child.castShadow = true;
+            child.receiveShadow = true;
+
+            if (child.geometry && !child.geometry.attributes.normal) {
+              child.geometry.computeVertexNormals();
+            }
+
+            originalMaterialsRef.current.set(child, child.material);
+
+            if (!child.material || (Array.isArray(child.material) && child.material.length === 0)) {
+              child.material = new THREE.MeshStandardMaterial({
+                color: 0x4daafc,
+                roughness: 0.4,
+                metalness: 0.2,
+                side: THREE.DoubleSide,
+              });
+            }
+
+            if (child.geometry) {
+              const geom = child.geometry;
+              if (geom.attributes.position) {
+                totalVertices += geom.attributes.position.count;
+              }
+              if (geom.index) {
+                totalFaces += geom.index.count / 3;
+              } else if (geom.attributes.position) {
+                totalFaces += geom.attributes.position.count / 3;
+              }
+            }
+          }
+        });
+
+        // Center and normalize model dimensions
+        const box = new THREE.Box3().setFromObject(loadedRoot);
+        const center = box.getCenter(new THREE.Vector3());
+        const size = box.getSize(new THREE.Vector3());
+        const maxDim = Math.max(size.x, size.y, size.z);
+        const scale = maxDim > 0 ? 2.5 / maxDim : 1;
+
+        loadedRoot.position.sub(center);
+        loadedRoot.scale.setScalar(scale);
+
+        modelGroup.add(loadedRoot);
+        setStats({ vertices: totalVertices, faces: Math.round(totalFaces) });
+        setIsLoading(false);
+      } catch (err: any) {
+        if (!isSubscribed) return;
+        setLoadError(err.message || 'Failed to load 3D model');
+        setIsLoading(false);
+      }
+    }
+
+    load();
+
+    return () => {
+      isSubscribed = false;
+    };
+  }, [rawUrl, formatExt, modelGroupRef]);
+
+  return {
+    isLoading,
+    loadError,
+    stats,
+    originalMaterialsRef,
+  };
+}

package/src/components/studio/views/cardViewlets/spatial3d/hooks/useRenderMode.ts

@@ -0,0 +1,50 @@
+/**
+ * Render Mode Toggle Hook
+ * Canonical Path: src/components/studio/views/cardViewlets/spatial3d/hooks/useRenderMode.ts
+ */
+
+import { useState, useEffect } from 'react';
+import * as THREE from 'three';
+
+export type RenderMode = 'shaded' | 'wireframe' | 'normals';
+
+export function useRenderMode(
+  modelGroupRef: React.RefObject<THREE.Group | null>,
+  originalMaterialsRef: React.RefObject<Map<THREE.Mesh, THREE.Material | THREE.Material[]>>
+) {
+  const [renderMode, setRenderMode] = useState<RenderMode>('shaded');
+
+  useEffect(() => {
+    const modelGroup = modelGroupRef.current;
+    if (!modelGroup) return;
+
+    modelGroup.traverse((child: any) => {
+      if (child.isMesh) {
+        if (renderMode === 'wireframe') {
+          if (Array.isArray(child.material)) {
+            child.material.forEach((m: any) => (m.wireframe = true));
+          } else if (child.material) {
+            child.material.wireframe = true;
+          }
+        } else if (renderMode === 'normals') {
+          child.material = new THREE.MeshNormalMaterial({ wireframe: false });
+        } else {
+          const orig = originalMaterialsRef.current?.get(child);
+          if (orig) {
+            child.material = orig;
+            if (Array.isArray(child.material)) {
+              child.material.forEach((m: any) => (m.wireframe = false));
+            } else {
+              child.material.wireframe = false;
+            }
+          }
+        }
+      }
+    });
+  }, [renderMode, modelGroupRef, originalMaterialsRef]);
+
+  return {
+    renderMode,
+    setRenderMode,
+  };
+}

package/src/components/studio/views/cardViewlets/spatial3d/hooks/useThreeScene.ts

@@ -0,0 +1,168 @@
+/**
+ * Three.js WebGL Scene Hook
+ * Canonical Path: src/components/studio/views/cardViewlets/spatial3d/hooks/useThreeScene.ts
+ *
+ * Implements DEL-304-07:
+ * - Decouples isRotating from scene setup effect (INV-304-14)
+ * - Clean WebGL context, geometries, and materials disposal on unmount (Cordis Rule 3 / G8)
+ */
+
+import { useEffect, useRef, useCallback } from 'react';
+import * as THREE from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+
+export interface UseThreeSceneOptions {
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  canvasRef: React.RefObject<HTMLCanvasElement | null>;
+  showGrid?: boolean;
+  isRotating?: boolean;
+}
+
+export function useThreeScene(options: UseThreeSceneOptions) {
+  const { containerRef, canvasRef, showGrid = true, isRotating = true } = options;
+
+  const sceneRef = useRef<THREE.Scene | null>(null);
+  const cameraRef = useRef<THREE.PerspectiveCamera | null>(null);
+  const rendererRef = useRef<THREE.WebGLRenderer | null>(null);
+  const controlsRef = useRef<OrbitControls | null>(null);
+  const modelGroupRef = useRef<THREE.Group | null>(null);
+  const gridRef = useRef<THREE.GridHelper | null>(null);
+  const isRotatingRef = useRef(isRotating);
+
+  // Keep isRotatingRef in sync without triggering scene re-instantiation
+  useEffect(() => {
+    isRotatingRef.current = isRotating;
+  }, [isRotating]);
+
+  // Sync grid visibility
+  useEffect(() => {
+    if (gridRef.current) {
+      gridRef.current.visible = showGrid;
+    }
+  }, [showGrid]);
+
+  // Reset Camera
+  const resetCamera = useCallback(() => {
+    if (cameraRef.current && controlsRef.current) {
+      cameraRef.current.position.set(2.8, 2.2, 3.8);
+      controlsRef.current.target.set(0, 0, 0);
+      controlsRef.current.update();
+    }
+  }, []);
+
+  // Main Scene Setup Effect (Zero isRotating in dependencies, INV-304-14)
+  useEffect(() => {
+    const container = containerRef.current;
+    const canvas = canvasRef.current;
+    if (!container || !canvas) return;
+
+    const width = container.clientWidth || 600;
+    const height = container.clientHeight || 400;
+
+    const renderer = new THREE.WebGLRenderer({
+      canvas,
+      antialias: true,
+      alpha: true,
+      powerPreference: 'high-performance',
+    });
+    renderer.setSize(width, height);
+    renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
+    renderer.shadowMap.enabled = true;
+    renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+    rendererRef.current = renderer;
+
+    const scene = new THREE.Scene();
+    scene.background = new THREE.Color(0x18181b);
+    sceneRef.current = scene;
+
+    const camera = new THREE.PerspectiveCamera(45, width / height, 0.05, 500);
+    camera.position.set(2.8, 2.2, 3.8);
+    cameraRef.current = camera;
+
+    const controls = new OrbitControls(camera, canvas);
+    controls.enableDamping = true;
+    controls.dampingFactor = 0.08;
+    controls.rotateSpeed = 0.8;
+    controls.zoomSpeed = 1.0;
+    controls.panSpeed = 0.8;
+    controls.target.set(0, 0, 0);
+    controlsRef.current = controls;
+
+    // Lighting
+    const ambientLight = new THREE.AmbientLight(0xffffff, 1.4);
+    const keyLight = new THREE.DirectionalLight(0xffffff, 1.8);
+    keyLight.position.set(6, 12, 8);
+    keyLight.castShadow = true;
+
+    const fillLight = new THREE.DirectionalLight(0x75beff, 1.0);
+    fillLight.position.set(-8, -4, -6);
+
+    const backLight = new THREE.DirectionalLight(0xffeedd, 0.8);
+    backLight.position.set(0, 8, -8);
+
+    scene.add(ambientLight, keyLight, fillLight, backLight);
+
+    // Ground Grid & Axes
+    const grid = new THREE.GridHelper(10, 20, 0x007acc, 0x2d2d30);
+    grid.position.y = -1.2;
+    grid.visible = showGrid;
+    scene.add(grid);
+    gridRef.current = grid;
+
+    const axes = new THREE.AxesHelper(1.2);
+    axes.position.y = -1.2;
+    scene.add(axes);
+
+    // Model Container Group
+    const modelGroup = new THREE.Group();
+    scene.add(modelGroup);
+    modelGroupRef.current = modelGroup;
+
+    // Animation Loop
+    let animId: number;
+    const animate = () => {
+      animId = requestAnimationFrame(animate);
+
+      if (isRotatingRef.current && modelGroupRef.current) {
+        modelGroupRef.current.rotation.y += 0.008;
+      }
+
+      controls.update();
+      renderer.render(scene, camera);
+    };
+    animate();
+
+    // Resize Handling
+    const resizeObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const newW = entry.contentRect.width;
+        const newH = entry.contentRect.height;
+        if (newW > 0 && newH > 0) {
+          camera.aspect = newW / newH;
+          camera.updateProjectionMatrix();
+          renderer.setSize(newW, newH);
+        }
+      }
+    });
+    resizeObserver.observe(container);
+
+    // Cordis Rule 3 / G8: Clean WebGL disposal
+    return () => {
+      cancelAnimationFrame(animId);
+      resizeObserver.disconnect();
+      controls.dispose();
+      renderer.dispose();
+      renderer.forceContextLoss();
+      scene.clear();
+    };
+  }, [containerRef, canvasRef]); // isRotating explicitly omitted (INV-304-14)
+
+  return {
+    sceneRef,
+    cameraRef,
+    rendererRef,
+    controlsRef,
+    modelGroupRef,
+    resetCamera,
+  };
+}

package/src/components/studio/views/cardViewlets/spatial3d/modelLoaderRegistry.ts

@@ -0,0 +1,92 @@
+/**
+ * Pluggable 3D Model Loader Registry
+ * Canonical Path: src/components/studio/views/cardViewlets/spatial3d/modelLoaderRegistry.ts
+ *
+ * Implements DEL-304-07:
+ * Decouples format-specific parsing (OBJ, STL, 3DS, GLTF/GLB) into a pluggable registry.
+ */
+
+import * as THREE from 'three';
+import { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader.js';
+import { STLLoader } from 'three/examples/jsm/loaders/STLLoader.js';
+import { TDSLoader } from 'three/examples/jsm/loaders/TDSLoader.js';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js';
+
+export type ModelLoaderFn = (rawUrl: string) => Promise<THREE.Object3D>;
+
+class ModelLoaderRegistry {
+  private loaders = new Map<string, ModelLoaderFn>();
+
+  constructor() {
+    this.registerDefaults();
+  }
+
+  register(ext: string, loader: ModelLoaderFn): void {
+    this.loaders.set(ext.toLowerCase(), loader);
+  }
+
+  async load(ext: string, rawUrl: string): Promise<THREE.Object3D> {
+    const extLower = ext.toLowerCase();
+    const loader = this.loaders.get(extLower);
+    if (!loader) {
+      throw new Error(`Unsupported 3D file format: .${extLower}`);
+    }
+    return loader(rawUrl);
+  }
+
+  private registerDefaults(): void {
+    // Wavefront OBJ
+    this.register('obj', async (url) => {
+      const res = await fetch(url);
+      if (!res.ok) throw new Error(`HTTP ${res.status} fetching OBJ`);
+      const text = await res.text();
+      return new OBJLoader().parse(text);
+    });
+
+    // Stereolithography STL
+    this.register('stl', async (url) => {
+      const res = await fetch(url);
+      if (!res.ok) throw new Error(`HTTP ${res.status} fetching STL`);
+      const buffer = await res.arrayBuffer();
+      const geometry = new STLLoader().parse(buffer);
+      geometry.computeVertexNormals();
+      const material = new THREE.MeshStandardMaterial({
+        color: 0x388bfd,
+        roughness: 0.35,
+        metalness: 0.25,
+        side: THREE.DoubleSide,
+      });
+      return new THREE.Mesh(geometry, material);
+    });
+
+    // 3D Studio
+    this.register('3ds', async (url) => {
+      const res = await fetch(url);
+      if (!res.ok) throw new Error(`HTTP ${res.status} fetching 3DS`);
+      const buffer = await res.arrayBuffer();
+      return new TDSLoader().parse(buffer, '');
+    });
+
+    // GLTF / GLB
+    const gltfLoader = async (url: string) => {
+      const res = await fetch(url);
+      if (!res.ok) throw new Error(`HTTP ${res.status} fetching GLTF/GLB`);
+      const buffer = await res.arrayBuffer();
+      const loader = new GLTFLoader();
+      const dracoLoader = new DRACOLoader();
+      dracoLoader.setDecoderPath('/draco/');
+      loader.setDRACOLoader(dracoLoader);
+      const gltf = await new Promise<any>((resolve, reject) => {
+        loader.parse(buffer, '', resolve, reject);
+      });
+      dracoLoader.dispose();
+      return gltf.scene as THREE.Object3D;
+    };
+
+    this.register('gltf', gltfLoader);
+    this.register('glb', gltfLoader);
+  }
+}
+
+export const modelLoaderRegistry = new ModelLoaderRegistry();

package/src/components/studio/views/cardViewlets/toolbar/CardPanelActionsToolbar.tsx

@@ -0,0 +1,256 @@
+/**
+ * Universal CardPanel Actions Toolbar (Sprint 318)
+ * Canonical Path: src/components/studio/views/cardViewlets/toolbar/CardPanelActionsToolbar.tsx
+ * Deliverable: DEL-318-02
+ *
+ * Provides a universal, top-level action ribbon above all 19 viewlets in CardPanel.tsx.
+ * Renders Save/Export, Upload/Replace, Directory Export, and custom viewlet action slots.
+ *
+ * Enforces Invariants:
+ * - INV-318-02: Universal Action Presence across all viewlets
+ * - INV-318-03: Viewlet Customization Protocol (extraActions slot)
+ * - INV-318-04: A11y & Keyboard Shortcuts
+ */
+
+import React from 'react';
+import type { MCardFileNode } from '../../../../../stores/mcardStore';
+import { useMCardFileSystemBridge } from './useMCardFileSystemBridge';
+
+export interface CardPanelActionsToolbarProps {
+  mcard: MCardFileNode;
+  detectedType?: string;
+  extraActions?: React.ReactNode;
+  onContentReplaced?: (newContent: string | Uint8Array, newHash: string) => void;
+  className?: string;
+}
+
+export const CardPanelActionsToolbar: React.FC<CardPanelActionsToolbarProps> = ({
+  mcard,
+  detectedType,
+  extraActions,
+  onContentReplaced,
+  className,
+}) => {
+  const {
+    isSaving,
+    isReplacing,
+    isExportingDir,
+    isCopied,
+    statusMessage,
+    statusType,
+    handleSave,
+    handleReplace,
+    handleCopy,
+    handleExportDir,
+  } = useMCardFileSystemBridge({ mcard, onContentReplaced });
+
+  if (!mcard) return null;
+
+  const isFolder = mcard.handle?.endsWith(':') || mcard.detectedType === 'schema';
+  const shortHash = mcard.hash ? (mcard.hash.startsWith('blake3:') ? mcard.hash.slice(7, 15) : mcard.hash.slice(0, 8)) : '';
+
+  return (
+    <div
+      className={`card-panel-actions-toolbar ${className || ''}`}
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        height: '28px',
+        padding: '0 10px',
+        backgroundColor: '#181818',
+        borderBottom: '1px solid #2d2d2d',
+        fontSize: '11px',
+        color: '#cccccc',
+        flexShrink: 0,
+        userSelect: 'none',
+        gap: '8px',
+      }}
+    >
+      {/* Left Segment: MCard Metadata Telemetry */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: '8px', overflow: 'hidden' }}>
+        <span
+          style={{
+            fontWeight: 600,
+            color: '#e0e0e0',
+            whiteSpace: 'nowrap',
+            textOverflow: 'ellipsis',
+            overflow: 'hidden',
+            maxWidth: '180px',
+          }}
+          title={mcard.path || mcard.handle}
+        >
+          {mcard.name || mcard.path?.split('/').pop() || 'Card'}
+        </span>
+
+        {mcard.mimeType && (
+          <span
+            style={{
+              padding: '1px 5px',
+              backgroundColor: '#252526',
+              border: '1px solid #3c3c3c',
+              borderRadius: '3px',
+              color: '#9cdcfe',
+              fontSize: '10px',
+              whiteSpace: 'nowrap',
+            }}
+          >
+            {mcard.mimeType}
+          </span>
+        )}
+
+        {shortHash && (
+          <span
+            style={{
+              padding: '1px 5px',
+              backgroundColor: '#1e1e1e',
+              border: '1px solid #333333',
+              borderRadius: '3px',
+              color: '#858585',
+              fontSize: '10px',
+              fontFamily: 'monospace',
+              whiteSpace: 'nowrap',
+            }}
+            title={`Full BLAKE3 Hash: ${mcard.hash}`}
+          >
+            #{shortHash}
+          </span>
+        )}
+
+        {/* Transient Action Status Message */}
+        {statusMessage && (
+          <span
+            style={{
+              padding: '1px 6px',
+              borderRadius: '3px',
+              fontSize: '10px',
+              fontWeight: 500,
+              backgroundColor: statusType === 'error' ? 'rgba(244, 135, 113, 0.2)' : 'rgba(115, 201, 145, 0.2)',
+              color: statusType === 'error' ? '#f48771' : '#73c991',
+              border: `1px solid ${statusType === 'error' ? '#f48771' : '#73c991'}`,
+              animation: 'fadeIn 0.15s ease-in',
+            }}
+          >
+            {statusMessage}
+          </span>
+        )}
+      </div>
+
+      {/* Right Segment: Viewlet Specific Controls + Native File Bridge Actions */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: '6px', flexShrink: 0 }}>
+        {/* Custom Viewlet Action Slot (INV-318-03) */}
+        {extraActions && (
+          <div style={{ display: 'flex', alignItems: 'center', gap: '4px', marginRight: '6px' }}>
+            {extraActions}
+          </div>
+        )}
+
+        {/* Export Directory Action (if folder or collection) */}
+        {isFolder && (
+          <button
+            type="button"
+            data-testid="card-action-export-dir"
+            disabled={isExportingDir}
+            onClick={handleExportDir}
+            title="Export Directory Subtree to OS Folder"
+            aria-label="Export Directory"
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: '4px',
+              padding: '2px 7px',
+              backgroundColor: '#2d2d2d',
+              color: '#e0e0e0',
+              border: '1px solid #3c3c3c',
+              borderRadius: '3px',
+              cursor: isExportingDir ? 'wait' : 'pointer',
+              fontSize: '10px',
+            }}
+          >
+            <span>📁</span>
+            <span>{isExportingDir ? 'Exporting...' : 'Export Folder'}</span>
+          </button>
+        )}
+
+        {/* Copy File / Content Button */}
+        <button
+          type="button"
+          data-testid="card-action-copy"
+          onClick={handleCopy}
+          title="Copy MCard content or binary to OS Clipboard"
+          aria-label="Copy to Clipboard"
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '4px',
+            padding: '2px 8px',
+            backgroundColor: isCopied ? '#2e7d32' : '#2a2d2e',
+            color: isCopied ? '#ffffff' : '#cccccc',
+            border: '1px solid #3c3c3c',
+            borderRadius: '3px',
+            cursor: 'pointer',
+            fontSize: '10px',
+            fontWeight: 500,
+            transition: 'all 0.1s ease',
+          }}
+        >
+          <span>{isCopied ? '✓' : '📋'}</span>
+          <span>{isCopied ? 'Copied' : 'Copy'}</span>
+        </button>
+
+        {/* Save / Export File Button */}
+        <button
+          type="button"
+          data-testid="card-action-save"
+          disabled={isSaving}
+          onClick={handleSave}
+          title="Save / Export MCard to OS File System (Cmd+S / Ctrl+S)"
+          aria-label="Save to Disk"
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '4px',
+            padding: '2px 8px',
+            backgroundColor: '#0e639c',
+            color: '#ffffff',
+            border: 'none',
+            borderRadius: '3px',
+            cursor: isSaving ? 'wait' : 'pointer',
+            fontSize: '10px',
+            fontWeight: 500,
+            transition: 'background 0.1s ease',
+          }}
+        >
+          <span>📥</span>
+          <span>{isSaving ? 'Saving...' : 'Save As'}</span>
+        </button>
+
+        {/* Upload / Replace File Button */}
+        <button
+          type="button"
+          data-testid="card-action-replace"
+          disabled={isReplacing}
+          onClick={handleReplace}
+          title="Upload / Replace MCard from OS File System (Cmd+Shift+R)"
+          aria-label="Replace File"
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '4px',
+            padding: '2px 8px',
+            backgroundColor: '#2a2d2e',
+            color: '#cccccc',
+            border: '1px solid #3c3c3c',
+            borderRadius: '3px',
+            cursor: isReplacing ? 'wait' : 'pointer',
+            fontSize: '10px',
+            transition: 'all 0.1s ease',
+          }}
+        >
+          <span>📤</span>
+          <span>{isReplacing ? 'Replacing...' : 'Replace'}</span>
+        </button>
+      </div>
+    </div>
+  );
+};