@gallop.software/studio 1.5.9 → 2.0.0

package/src/handlers/utils/meta.ts

@@ -0,0 +1,102 @@
+import { promises as fs } from 'fs'
+import type { FullMeta, MetaEntry } from '../../types'
+import { getDataPath } from '../../config'
+
+export async function loadMeta(): Promise<FullMeta> {
+  const metaPath = getDataPath('_studio.json')
+  
+  try {
+    const content = await fs.readFile(metaPath, 'utf-8')
+    return JSON.parse(content) as FullMeta
+  } catch {
+    return {}
+  }
+}
+
+export async function saveMeta(meta: FullMeta): Promise<void> {
+  const dataDir = getDataPath()
+  await fs.mkdir(dataDir, { recursive: true })
+  const metaPath = getDataPath('_studio.json')
+  
+  // Ensure _cdns is at the top by creating ordered object
+  const ordered: FullMeta = {}
+  if (meta._cdns) {
+    ordered._cdns = meta._cdns
+  }
+  // Add all other entries
+  for (const [key, value] of Object.entries(meta)) {
+    if (key !== '_cdns') {
+      ordered[key] = value
+    }
+  }
+  
+  await fs.writeFile(metaPath, JSON.stringify(ordered, null, 2))
+}
+
+/**
+ * Get the CDN URLs array from meta
+ */
+export function getCdnUrls(meta: FullMeta): string[] {
+  return meta._cdns || []
+}
+
+/**
+ * Set the CDN URLs array in meta
+ */
+export function setCdnUrls(meta: FullMeta, urls: string[]): void {
+  meta._cdns = urls
+}
+
+/**
+ * Get or add a CDN URL, returning its index
+ */
+export function getOrAddCdnIndex(meta: FullMeta, cdnUrl: string): number {
+  if (!meta._cdns) {
+    meta._cdns = []
+  }
+  
+  // Normalize URL (remove trailing slash)
+  const normalizedUrl = cdnUrl.replace(/\/$/, '')
+  
+  const existingIndex = meta._cdns.indexOf(normalizedUrl)
+  if (existingIndex >= 0) {
+    return existingIndex
+  }
+  
+  // Add new CDN URL
+  meta._cdns.push(normalizedUrl)
+  return meta._cdns.length - 1
+}
+
+/**
+ * Get a meta entry (excludes special keys like _cdns)
+ */
+export function getMetaEntry(meta: FullMeta, key: string): MetaEntry | undefined {
+  if (key.startsWith('_')) return undefined
+  const value = meta[key]
+  if (Array.isArray(value)) return undefined
+  return value as MetaEntry | undefined
+}
+
+/**
+ * Set a meta entry
+ */
+export function setMetaEntry(meta: FullMeta, key: string, entry: MetaEntry): void {
+  meta[key] = entry
+}
+
+/**
+ * Delete a meta entry
+ */
+export function deleteMetaEntry(meta: FullMeta, key: string): void {
+  delete meta[key]
+}
+
+/**
+ * Get all file entries (excludes special keys like _cdns)
+ */
+export function getFileEntries(meta: FullMeta): Array<[string, MetaEntry]> {
+  return Object.entries(meta).filter(
+    ([key, value]) => !key.startsWith('_') && !Array.isArray(value)
+  ) as Array<[string, MetaEntry]>
+}

package/src/handlers/utils/thumbnails.ts

@@ -0,0 +1,98 @@
+import { promises as fs } from 'fs'
+import path from 'path'
+import sharp from 'sharp'
+import { encode } from 'blurhash'
+import type { MetaEntry, Dimensions } from '../../types'
+import { getPublicPath } from '../../config'
+
+export const FULL_MAX_WIDTH = 2560
+
+export const DEFAULT_SIZES: Record<string, { width: number; suffix: string; key: 'sm' | 'md' | 'lg' }> = {
+  small: { width: 300, suffix: '-sm', key: 'sm' },
+  medium: { width: 700, suffix: '-md', key: 'md' },
+  large: { width: 1400, suffix: '-lg', key: 'lg' },
+}
+
+export async function processImage(
+  buffer: Buffer,
+  imageKey: string
+): Promise<MetaEntry> {
+  const sharpInstance = sharp(buffer)
+  const metadata = await sharpInstance.metadata()
+  const originalWidth = metadata.width || 0
+  const originalHeight = metadata.height || 0
+  const ratio = originalHeight / originalWidth
+
+  // Remove leading slash for path operations
+  const keyWithoutSlash = imageKey.startsWith('/') ? imageKey.slice(1) : imageKey
+  const baseName = path.basename(keyWithoutSlash, path.extname(keyWithoutSlash))
+  const ext = path.extname(keyWithoutSlash).toLowerCase()
+  const imageDir = path.dirname(keyWithoutSlash)
+
+  const imagesPath = getPublicPath('images', imageDir === '.' ? '' : imageDir)
+  await fs.mkdir(imagesPath, { recursive: true })
+
+  const isPng = ext === '.png'
+  const outputExt = isPng ? '.png' : '.jpg'
+
+  // Build the result entry
+  const entry: MetaEntry = {
+    o: { w: originalWidth, h: originalHeight },
+  }
+
+  // Generate full size (capped at FULL_MAX_WIDTH)
+  const fullFileName = imageDir === '.' ? `${baseName}${outputExt}` : `${imageDir}/${baseName}${outputExt}`
+  const fullPath = getPublicPath('images', fullFileName)
+
+  let fullWidth = originalWidth
+  let fullHeight = originalHeight
+
+  if (originalWidth > FULL_MAX_WIDTH) {
+    fullWidth = FULL_MAX_WIDTH
+    fullHeight = Math.round(FULL_MAX_WIDTH * ratio)
+    if (isPng) {
+      await sharp(buffer).resize(fullWidth, fullHeight).png({ quality: 85 }).toFile(fullPath)
+    } else {
+      await sharp(buffer).resize(fullWidth, fullHeight).jpeg({ quality: 85 }).toFile(fullPath)
+    }
+  } else {
+    if (isPng) {
+      await sharp(buffer).png({ quality: 85 }).toFile(fullPath)
+    } else {
+      await sharp(buffer).jpeg({ quality: 85 }).toFile(fullPath)
+    }
+  }
+  entry.f = { w: fullWidth, h: fullHeight }
+
+  // Generate thumbnail sizes
+  for (const [, sizeConfig] of Object.entries(DEFAULT_SIZES)) {
+    const { width: maxWidth, suffix, key } = sizeConfig
+    if (originalWidth <= maxWidth) {
+      continue // Skip if original is smaller than this size
+    }
+
+    const newHeight = Math.round(maxWidth * ratio)
+    const sizeFileName = `${baseName}${suffix}${outputExt}`
+    const sizeFilePath = imageDir === '.' ? sizeFileName : `${imageDir}/${sizeFileName}`
+    const sizePath = getPublicPath('images', sizeFilePath)
+
+    if (isPng) {
+      await sharp(buffer).resize(maxWidth, newHeight).png({ quality: 80 }).toFile(sizePath)
+    } else {
+      await sharp(buffer).resize(maxWidth, newHeight).jpeg({ quality: 80 }).toFile(sizePath)
+    }
+
+    entry[key] = { w: maxWidth, h: newHeight }
+  }
+
+  // Generate blurhash
+  const { data, info } = await sharp(buffer)
+    .resize(32, 32, { fit: 'inside' })
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true })
+
+  entry.b = encode(new Uint8ClampedArray(data), info.width, info.height, 4, 4)
+
+  return entry
+}

package/src/hooks/useFileList.ts

@@ -0,0 +1,143 @@
+import { useEffect, useState, useRef, useCallback } from 'react'
+import { useStudio } from '../components/StudioContext'
+import { studioApi } from '../lib/api'
+import type { FileItem } from '../types'
+
+/**
+ * Shared hook for file list logic used by both Grid and List views
+ * Handles loading, sorting, selection, and navigation
+ */
+export function useFileList() {
+  const {
+    currentPath,
+    setCurrentPath,
+    navigateUp,
+    selectedItems,
+    toggleSelection,
+    selectRange,
+    lastSelectedPath,
+    selectAll,
+    clearSelection,
+    refreshKey,
+    setFocusedItem,
+    triggerRefresh,
+    triggerScan,
+    searchQuery,
+    showError,
+    setFileItems,
+  } = useStudio()
+
+  const [items, setItems] = useState<FileItem[]>([])
+  const [loading, setLoading] = useState(true)
+  const [metaEmpty, setMetaEmpty] = useState(false)
+  const isInitialLoad = useRef(true)
+  const lastPath = useRef(currentPath)
+
+  // Load items when path, refresh, or search changes
+  useEffect(() => {
+    async function loadItems() {
+      const isPathChange = lastPath.current !== currentPath
+      if (isInitialLoad.current || isPathChange) {
+        setLoading(true)
+      }
+      lastPath.current = currentPath
+
+      try {
+        const data = searchQuery && searchQuery.length >= 2
+          ? await studioApi.search(searchQuery)
+          : await studioApi.list(currentPath)
+        const loadedItems = data.items || []
+        setItems(loadedItems)
+        setFileItems(loadedItems)
+        setMetaEmpty(data.isEmpty === true)
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Failed to load items'
+        showError('Load Error', message)
+        setItems([])
+        setFileItems([])
+        setMetaEmpty(false)
+      }
+
+      setLoading(false)
+      isInitialLoad.current = false
+    }
+
+    loadItems()
+  }, [currentPath, refreshKey, searchQuery, showError, setFileItems])
+
+  // Computed values
+  const isAtRoot = currentPath === 'public'
+  const isSearching = searchQuery && searchQuery.length >= 2
+
+  // Sort items: folders first, then alphabetically
+  const sortedItems = [...items].sort((a, b) => {
+    if (a.type === 'folder' && b.type !== 'folder') return -1
+    if (a.type !== 'folder' && b.type === 'folder') return 1
+    return a.name.localeCompare(b.name)
+  })
+
+  const allItemsSelected = sortedItems.length > 0 && sortedItems.every(item => selectedItems.has(item.path))
+  const someItemsSelected = sortedItems.some(item => selectedItems.has(item.path))
+
+  // Handlers
+  const handleItemClick = useCallback((item: FileItem, e: React.MouseEvent) => {
+    if (e.shiftKey && lastSelectedPath) {
+      selectRange(lastSelectedPath, item.path, sortedItems)
+    } else {
+      toggleSelection(item.path)
+    }
+  }, [lastSelectedPath, selectRange, sortedItems, toggleSelection])
+
+  const handleOpen = useCallback((item: FileItem) => {
+    if (item.type === 'folder') {
+      setCurrentPath(item.path)
+    } else {
+      setFocusedItem(item)
+    }
+  }, [setCurrentPath, setFocusedItem])
+
+  const handleGenerateThumbnail = useCallback(async (item: FileItem) => {
+    try {
+      const imageKey = '/' + item.path.replace(/^public\//, '')
+      await studioApi.reprocess([imageKey])
+      triggerRefresh()
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Failed to generate thumbnail'
+      showError('Processing Error', message)
+    }
+  }, [triggerRefresh, showError])
+
+  const handleSelectAll = useCallback(() => {
+    if (allItemsSelected) {
+      clearSelection()
+    } else {
+      selectAll(sortedItems)
+    }
+  }, [allItemsSelected, clearSelection, selectAll, sortedItems])
+
+  return {
+    // State
+    items,
+    loading,
+    sortedItems,
+    metaEmpty,
+
+    // Computed
+    isAtRoot,
+    isSearching,
+    allItemsSelected,
+    someItemsSelected,
+
+    // Context values
+    currentPath,
+    selectedItems,
+    navigateUp,
+
+    // Handlers
+    handleItemClick,
+    handleOpen,
+    handleGenerateThumbnail,
+    handleSelectAll,
+    triggerScan,
+  }
+}

package/src/index.tsx

@@ -0,0 +1,36 @@
+/**
+ * @gallop.software/studio
+ * 
+ * Standalone media manager for Gallop templates.
+ * 
+ * Usage (CLI):
+ * ```bash
+ * # Run Studio for current project
+ * npx @gallop.software/studio --workspace .
+ * 
+ * # Or add to package.json scripts
+ * {
+ *   "scripts": {
+ *     "studio": "studio --workspace ."
+ *   }
+ * }
+ * ```
+ * 
+ * Studio runs as a standalone dev server on port 3001.
+ * It manages files in your project's public/ folder and
+ * stores metadata in _data/_studio.json.
+ */
+
+// Types - for consumers that read _studio.json
+export type {
+  LeanImageEntry,
+  LeanMeta,
+  FileItem,
+  StudioConfig,
+  MetaEntry,
+  FullMeta,
+  Dimensions,
+} from './types'
+
+// Utilities - for generating thumbnail paths
+export { getThumbnailPath, getAllThumbnailPaths, isProcessed } from './types'

package/src/lib/api.ts

@@ -0,0 +1,176 @@
+/**
+ * Typed API client for Studio
+ * Provides type-safe methods for all Studio API endpoints
+ */
+
+import type { FileItem, LeanMeta, LeanImageEntry } from '../types'
+
+// Response types
+interface ListResponse {
+  items: FileItem[]
+  isEmpty?: boolean
+}
+
+interface FoldersResponse {
+  folders: { path: string; name: string; depth: number }[]
+}
+
+interface CountImagesResponse {
+  count: number
+  images: string[]
+}
+
+interface UploadResponse {
+  success: boolean
+  imageKey?: string
+  entry?: LeanImageEntry
+  path?: string
+  message?: string
+  error?: string
+}
+
+interface DeleteResponse {
+  success: boolean
+  deleted: string[]
+  errors?: string[]
+}
+
+interface PushResponse {
+  success: boolean
+  pushed: string[]
+  errors?: string[]
+}
+
+interface ReprocessResponse {
+  success: boolean
+  processed: string[]
+  errors?: string[]
+}
+
+interface CreateFolderResponse {
+  success: boolean
+  path: string
+  error?: string
+}
+
+interface RenameResponse {
+  success: boolean
+  newPath: string
+  error?: string
+}
+
+interface MoveResponse {
+  success: boolean
+  moved: string[]
+  errors?: string[]
+}
+
+class StudioApiClient {
+  private async get<T>(url: string): Promise<T> {
+    const response = await fetch(url)
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}))
+      throw new Error(data.error || `Request failed: ${response.status}`)
+    }
+    return response.json()
+  }
+
+  private async post<T>(url: string, body?: object): Promise<T> {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: body ? { 'Content-Type': 'application/json' } : undefined,
+      body: body ? JSON.stringify(body) : undefined,
+    })
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}))
+      throw new Error(data.error || `Request failed: ${response.status}`)
+    }
+    return response.json()
+  }
+
+  // List handlers
+  async list(path: string = 'public'): Promise<ListResponse> {
+    return this.get(`/api/studio/list?path=${encodeURIComponent(path)}`)
+  }
+
+  async search(query: string): Promise<ListResponse> {
+    return this.get(`/api/studio/search?q=${encodeURIComponent(query)}`)
+  }
+
+  async listFolders(): Promise<FoldersResponse> {
+    return this.get('/api/studio/list-folders')
+  }
+
+  async countImages(): Promise<CountImagesResponse> {
+    return this.get('/api/studio/count-images')
+  }
+
+  async folderImages(folders: string[]): Promise<CountImagesResponse> {
+    return this.get(`/api/studio/folder-images?folders=${encodeURIComponent(folders.join(','))}`)
+  }
+
+  // File handlers
+  async upload(file: File, targetPath: string = 'public'): Promise<UploadResponse> {
+    const formData = new FormData()
+    formData.append('file', file)
+    formData.append('path', targetPath)
+
+    const response = await fetch('/api/studio/upload', {
+      method: 'POST',
+      body: formData,
+    })
+
+    if (!response.ok) {
+      const data = await response.json().catch(() => ({}))
+      throw new Error(data.error || `Upload failed: ${response.status}`)
+    }
+
+    return response.json()
+  }
+
+  async delete(paths: string[]): Promise<DeleteResponse> {
+    return this.post('/api/studio/delete', { paths })
+  }
+
+  async createFolder(parentPath: string, name: string): Promise<CreateFolderResponse> {
+    return this.post('/api/studio/create-folder', { parentPath, name })
+  }
+
+  async rename(oldPath: string, newName: string): Promise<RenameResponse> {
+    return this.post('/api/studio/rename', { oldPath, newName })
+  }
+
+  async move(paths: string[], destination: string): Promise<MoveResponse> {
+    return this.post('/api/studio/move', { paths, destination })
+  }
+
+  // Image handlers
+  async push(imageKeys: string[]): Promise<PushResponse> {
+    return this.post('/api/studio/sync', { imageKeys })
+  }
+
+  async reprocess(imageKeys: string[]): Promise<ReprocessResponse> {
+    return this.post('/api/studio/reprocess', { imageKeys })
+  }
+
+  // Process all returns a stream, handle separately
+  processAllStream(): EventSource {
+    return new EventSource('/api/studio/process-all')
+  }
+}
+
+export const studioApi = new StudioApiClient()
+
+// Export types for consumers
+export type {
+  ListResponse,
+  FoldersResponse,
+  CountImagesResponse,
+  UploadResponse,
+  DeleteResponse,
+  PushResponse,
+  ReprocessResponse,
+  CreateFolderResponse,
+  RenameResponse,
+  MoveResponse,
+}

package/src/types.ts

@@ -0,0 +1,119 @@
+/**
+ * Dimensions object {w, h}
+ */
+export interface Dimensions {
+  w: number
+  h: number
+}
+
+/**
+ * Meta entry - works for images and non-images
+ * o: original dimensions, b: blurhash, c: CDN index
+ * sm/md/lg/f: thumbnail dimensions (presence implies processed)
+ */
+export interface MetaEntry {
+  o?: Dimensions   // original dimensions {w, h}
+  b?: string       // blurhash
+  sm?: Dimensions  // small thumbnail (300px width)
+  md?: Dimensions  // medium thumbnail (700px width)
+  lg?: Dimensions  // large thumbnail (1400px width)
+  f?: Dimensions   // full size (capped at 2560px width)
+  c?: number       // CDN index - index into _cdns array
+}
+
+/**
+ * Full meta schema including special keys
+ * _cdns: Array of CDN base URLs
+ * Other keys: file paths from public folder
+ */
+export interface FullMeta {
+  _cdns?: string[]  // Array of CDN base URLs
+  [key: string]: MetaEntry | string[] | undefined
+}
+
+/**
+ * Meta schema - keyed by path from public folder
+ * Example: { "/portfolio/photo.jpg": { o: {w:2400,h:1600}, b: "...", sm: {w:300,h:200}, ... } }
+ */
+export type LeanMeta = Record<string, MetaEntry>
+
+// Alias for compatibility
+export type LeanImageEntry = MetaEntry
+
+/**
+ * File/folder item for browser
+ */
+export interface FileItem {
+  name: string
+  path: string
+  type: 'file' | 'folder'
+  size?: number
+  dimensions?: { width: number; height: number }
+  isProcessed?: boolean
+  cdnPushed?: boolean
+  cdnBaseUrl?: string  // CDN base URL when pushed to cloud
+  isRemote?: boolean   // true if CDN URL doesn't match R2 (external import)
+  isProtected?: boolean // true for images folder and its contents (cannot select/modify)
+  // Folder-specific properties
+  fileCount?: number
+  totalSize?: number
+  cloudCount?: number   // Number of R2 cloud files in folder
+  remoteCount?: number  // Number of remote (imported URL) files in folder
+  localCount?: number   // Number of local files in folder
+  // For showing thumbnails - path to -sm version if exists
+  thumbnail?: string
+  // Whether a processed thumbnail exists
+  hasThumbnail?: boolean
+}
+
+/**
+ * Studio configuration
+ */
+export interface StudioConfig {
+  r2AccountId?: string
+  r2AccessKeyId?: string
+  r2SecretAccessKey?: string
+  r2BucketName?: string
+  r2PublicUrl?: string
+  thumbnailSizes?: {
+    small: number
+    medium: number
+    large: number
+  }
+}
+
+/**
+ * Get thumbnail path from original image path
+ */
+export function getThumbnailPath(originalPath: string, size: 'sm' | 'md' | 'lg' | 'full'): string {
+  if (size === 'full') {
+    const ext = originalPath.match(/\.\w+$/)?.[0] || '.jpg'
+    const base = originalPath.replace(/\.\w+$/, '')
+    const outputExt = ext.toLowerCase() === '.png' ? '.png' : '.jpg'
+    return `/images${base}${outputExt}`
+  }
+  const ext = originalPath.match(/\.\w+$/)?.[0] || '.jpg'
+  const base = originalPath.replace(/\.\w+$/, '')
+  const outputExt = ext.toLowerCase() === '.png' ? '.png' : '.jpg'
+  return `/images${base}-${size}${outputExt}`
+}
+
+/**
+ * Get all thumbnail paths for an image
+ */
+export function getAllThumbnailPaths(originalPath: string): string[] {
+  return [
+    getThumbnailPath(originalPath, 'full'),
+    getThumbnailPath(originalPath, 'lg'),
+    getThumbnailPath(originalPath, 'md'),
+    getThumbnailPath(originalPath, 'sm'),
+  ]
+}
+
+/**
+ * Check if an image entry is processed (has any thumbnail dimensions)
+ */
+export function isProcessed(entry: MetaEntry | undefined): boolean {
+  if (!entry) return false
+  return !!(entry.f || entry.lg || entry.md || entry.sm)
+}