@dfosco/storyboard 0.12.0 → 0.12.2

package/src/core/data/artifactIndex.js

@@ -1,5 +1,50 @@
+import { parseCanvasId } from '../canvas/identity.js'
+
 const ARTIFACT_INDEX_SCHEMA_VERSION = 1
 
+/**
+ * Folder-independent identity for a canvas, mirroring how prototypes are
+ * matched across branches by their (folder-independent) `dirName`.
+ *
+ * The full canvas id is path-based (e.g. `widget/design-system`), so the same
+ * canvas living at the root on one branch and inside a folder on another would
+ * otherwise key differently and render as duplicate cross-branch cards. We key
+ * by the canvas name instead — proto-scoped canvases keep their prototype
+ * segment so two prototypes with same-named canvases never collide.
+ */
+export function canvasMatchKey(id) {
+  const { namespace, segments, name } = parseCanvasId(String(id || ''))
+  if (namespace === 'prototype') {
+    const scope = segments.length >= 2 ? segments[segments.length - 2] : ''
+    return scope ? `proto:${scope}/${name}` : `proto:${name}`
+  }
+  return name
+}
+
+/**
+ * Collapse the remote canvas map (keyed by full path id) into a map keyed by
+ * folder-independent match key, merging the branch lists of any entries that
+ * resolve to the same canvas. This makes matching resilient to canvases that
+ * moved between folders (or root ↔ folder) across branches, and keeps the
+ * behavior correct for both freshly-aggregated and legacy indexes.
+ */
+function collapseRemoteCanvases(remoteCanvases) {
+  const byKey = new Map()
+  for (const [id, entry] of Object.entries(remoteCanvases || {})) {
+    const key = canvasMatchKey(id)
+    const existing = byKey.get(key)
+    if (existing) {
+      existing.entry = {
+        ...existing.entry,
+        branches: [...(existing.entry.branches || []), ...(entry?.branches || [])],
+      }
+    } else {
+      byKey.set(key, { id, entry: { ...entry, branches: [...(entry?.branches || [])] } })
+    }
+  }
+  return byKey
+}
+
 function stripBranchSegments(basePath) {
   let path = typeof basePath === 'string' && basePath.trim() ? basePath : '/'
   path = path.replace(/[?#].*$/, '')
@@ -188,9 +233,9 @@ export function mergeArtifactIndexIntoPrototypeIndex(localIndex, remoteIndex, cu
 
   const baseIndex = localIndex || {}
   const remotePrototypes = remoteIndex.prototypes || {}
-  const remoteCanvases = remoteIndex.canvases || {}
+  const remoteCanvasesByKey = collapseRemoteCanvases(remoteIndex.canvases)
   const localPrototypeIds = new Set()
-  const localCanvasIds = new Set()
+  const localCanvasKeys = new Set()
 
   const enrichPrototype = (proto) => {
     const id = proto?.dirName
@@ -202,10 +247,11 @@ export function mergeArtifactIndexIntoPrototypeIndex(localIndex, remoteIndex, cu
 
   const enrichCanvas = (canvas) => {
     const id = canvas?.dirName
-    if (id) localCanvasIds.add(id)
-    const remoteEntry = id ? remoteCanvases[id] : null
-    if (!remoteEntry) return { ...canvas }
-    return { ...canvas, branches: branchesForLocalCard(remoteEntry, currentBranch) }
+    const key = id ? canvasMatchKey(id) : null
+    if (key) localCanvasKeys.add(key)
+    const remote = key ? remoteCanvasesByKey.get(key) : null
+    if (!remote) return { ...canvas }
+    return { ...canvas, branches: branchesForLocalCard(remote.entry, currentBranch) }
   }
 
   const folders = (baseIndex.folders || []).map(folder => ({
@@ -220,8 +266,8 @@ export function mergeArtifactIndexIntoPrototypeIndex(localIndex, remoteIndex, cu
     if (!localPrototypeIds.has(id)) prototypes.push(createBranchOnlyPrototype(id, remoteEntry))
   }
 
-  for (const [id, remoteEntry] of Object.entries(remoteCanvases)) {
-    if (!localCanvasIds.has(id)) canvases.push(createBranchOnlyCanvas(id, remoteEntry))
+  for (const [key, { id, entry }] of remoteCanvasesByKey) {
+    if (!localCanvasKeys.has(key)) canvases.push(createBranchOnlyCanvas(id, entry))
   }
 
   return {

package/src/core/data/artifactIndex.test.js

@@ -134,6 +134,58 @@ describe('mergeArtifactIndexIntoPrototypeIndex', () => {
     expect(merged.folders[0].canvases[0].branches.map(branch => branch.branch)).toEqual(['topic'])
   })
 
+  it('matches canvases across branches by folder-independent name (no duplicate when a canvas moved folders)', () => {
+    // Local canvas lives at the root ("design-system"); the remote index has the
+    // same canvas keyed under a folder path ("widget/design-system") because it
+    // sits inside a folder on other branches. They are the same canvas and must
+    // collapse into a single card — never a duplicate branch-only entry.
+    const localIndex = makeLocalIndex()
+    localIndex.canvases = [
+      { name: 'Design System', dirName: 'design-system', folder: null, route: '/canvas/design-system', isCanvas: true },
+    ]
+    const remoteIndex = makeRemoteIndex()
+    remoteIndex.canvases['widget/design-system'] = {
+      id: 'widget/design-system',
+      branches: [
+        { branch: 'main', folder: '', name: 'Design System', route: '/canvas/design-system', folderName: null },
+        { branch: 'topic', folder: 'branch--topic/', name: 'Design System', route: '/canvas/widget/design-system', folderName: 'widget' },
+      ],
+    }
+
+    const merged = mergeArtifactIndexIntoPrototypeIndex(localIndex, remoteIndex, 'main')
+
+    const matches = merged.canvases.filter(canvas => canvas.name === 'Design System')
+    expect(matches).toHaveLength(1)
+    expect(matches[0].dirName).toBe('design-system')
+    expect(matches[0].isBranchOnly).toBeFalsy()
+    expect(matches[0].branches.map(branch => branch.branch)).toEqual(['topic'])
+  })
+
+  it('merges branches for the same canvas split across folder-path keys in a legacy index', () => {
+    // A legacy (pre-collapse) index can hold the same canvas under two keys —
+    // one at the root, one under a folder. The merge must fold both branch
+    // lists into a single local card.
+    const localIndex = makeLocalIndex()
+    localIndex.canvases = [
+      { name: 'Design System', dirName: 'design-system', folder: null, route: '/canvas/design-system', isCanvas: true },
+    ]
+    const remoteIndex = makeRemoteIndex()
+    remoteIndex.canvases['design-system'] = {
+      id: 'design-system',
+      branches: [{ branch: 'main', folder: '', name: 'Design System', route: '/canvas/design-system', folderName: null }],
+    }
+    remoteIndex.canvases['widget/design-system'] = {
+      id: 'widget/design-system',
+      branches: [{ branch: 'topic', folder: 'branch--topic/', name: 'Design System', route: '/canvas/widget/design-system', folderName: 'widget' }],
+    }
+
+    const merged = mergeArtifactIndexIntoPrototypeIndex(localIndex, remoteIndex, 'main')
+
+    const matches = merged.canvases.filter(canvas => canvas.name === 'Design System')
+    expect(matches).toHaveLength(1)
+    expect(matches[0].branches.map(branch => branch.branch)).toEqual(['topic'])
+  })
+
   it('synthesizes remote-only prototype and canvas cards with prefixed IDs', () => {
     const localIndex = makeLocalIndex()
     const remoteIndex = makeRemoteIndex()

package/src/core/data/viewfinder.js

@@ -323,9 +323,10 @@ export function buildPrototypeIndex(knownRoutes = []) {
       const key = typeof p === 'string' ? p : p?.name
       if (key) orderMap.set(key, idx)
     })
+    const stripDraft = (k) => (typeof k === 'string' ? k.split('/').filter(seg => seg !== 'drafts').join('/') : k)
     entry.pages.sort((a, b) => {
-      const aKey = a.id ?? a.name
-      const bKey = b.id ?? b.name
+      const aKey = stripDraft(a.id ?? a.name)
+      const bKey = stripDraft(b.id ?? b.name)
       const aIdx = orderMap.has(aKey) ? orderMap.get(aKey) : Infinity
       const bIdx = orderMap.has(bKey) ? orderMap.get(bKey) : Infinity
       return aIdx - bIdx

package/src/core/data/viewfinder.test.js

@@ -342,6 +342,45 @@ describe('buildPrototypeIndex', () => {
     const result = buildPrototypeIndex([])
     expect(result.prototypes[0].lastModified).toBeNull()
   })
+
+  it('sorts drafts canvas-group pages by pageOrder despite the drafts/ id prefix', () => {
+    const meta = {
+      title: 'Security Vision',
+      pageOrder: [
+        'security-vision/1-security-vision',
+        'security-vision/2-confidence-scores',
+        'security-vision/3-final-updates',
+      ],
+    }
+    // Pages are registered in reverse discovery order; their ids keep `drafts/`
+    // but pageOrder is authored without it (the correct convention).
+    init({
+      flows: {},
+      objects: {},
+      records: {},
+      canvases: {
+        'drafts/security-vision/3-final-updates': {
+          title: '3 Final Updates', _group: 'security-vision', _isPrivate: true, _canvasMeta: meta,
+        },
+        'drafts/security-vision/2-confidence-scores': {
+          title: '2 Confidence Scores', _group: 'security-vision', _isPrivate: true, _canvasMeta: meta,
+        },
+        'drafts/security-vision/1-security-vision': {
+          title: '1 Security Vision', _group: 'security-vision', _isPrivate: true, _canvasMeta: meta,
+        },
+      },
+    })
+    const result = buildPrototypeIndex([])
+    const card = result.canvases.find(c => c._group === 'security-vision')
+    expect(card).toBeTruthy()
+    // Title comes from .meta.json, not a page title.
+    expect(card.name).toBe('Security Vision')
+    expect(card.pages.map(p => p.id)).toEqual([
+      'drafts/security-vision/1-security-vision',
+      'drafts/security-vision/2-confidence-scores',
+      'drafts/security-vision/3-final-updates',
+    ])
+  })
 })
 
 // ── appendTokens ──

package/src/core/scaffold/scaffold-integration.test.js

@@ -284,6 +284,30 @@ describe('storyboard-scaffold integration', () => {
     const after = fs.readFileSync(path.join(tmp, '.gitignore'), 'utf-8')
     expect(after).toContain('STALE')
   })
+
+  it('force-syncs the package-owned base set onto a fresh client', () => {
+    runScaffolder(tmp)
+
+    // Tier-1 infra configs land (iron-clad base — customers never edit these).
+    for (const f of ['vite.config.js', 'vitest.config.js', 'eslint.config.js', 'tsconfig.json']) {
+      expect(fs.existsSync(path.join(tmp, f)), `${f} should be scaffolded`).toBe(true)
+    }
+    // The new `home` library surface lands so /-resolution works everywhere.
+    expect(fs.existsSync(path.join(tmp, 'src/library/home.jsx'))).toBe(true)
+    // No svelte stub is ever scaffolded.
+    expect(fs.existsSync(path.join(tmp, 'svelte.config.js'))).toBe(false)
+    // The scaffolded eslint config carries no svelte reference.
+    expect(fs.readFileSync(path.join(tmp, 'eslint.config.js'), 'utf-8')).not.toContain('svelte')
+  }, 20000)
+
+  it('overwrites a customer-modified vite.config.js (updateable = force-sync)', () => {
+    runScaffolder(tmp)
+    const vitePath = path.join(tmp, 'vite.config.js')
+    const pristine = fs.readFileSync(vitePath, 'utf-8')
+    fs.writeFileSync(vitePath, '// customer tampering\n', 'utf-8')
+    runScaffolder(tmp)
+    expect(fs.readFileSync(vitePath, 'utf-8')).toBe(pristine)
+  }, 20000)
 })
 
 // ---------------------------------------------------------------------------

package/src/core/stores/configSchema.js

@@ -207,6 +207,56 @@
  * @property {string}  [default]  — default global theme ID. Use `"system"` to follow OS preference.
  */
 
+/**
+ * @typedef {(string|{dev?: string, prod?: string, default?: string})} RouteTarget
+ *   Target page for a configured route path. Either:
+ *   - a string — the page name (no leading slash) used in every environment,
+ *     e.g. `"home"`, `"workspace"`, or a flat component like `"Dashboard"`.
+ *   - an object — a per-environment target. `dev` is used when
+ *     `import.meta.env.DEV` is true (running `storyboard dev`); `prod` is used
+ *     in production builds; `default` is the fallback when the active env key
+ *     is absent. See {@link resolveRouteTarget} for resolution order.
+ */
+
+/**
+ * @typedef {Record<string, RouteTarget>} RoutesConfig
+ *   Map of route path → {@link RouteTarget}. The index path `"/"` controls
+ *   which page renders at the site root. Default: `{ "/": "home" }`
+ *   (behavior-preserving — today's SimpleWorkspace landing).
+ */
+
+/**
+ * @typedef {object} HomePageConfig
+ *   Presentation props for the `home` surface (SimpleWorkspace landing). The
+ *   library `home.jsx`/`index.jsx` files spread these — customers configure the
+ *   surface here and never edit the JSX.
+ * @property {string} [title]    — app name shown in the header (default "Storyboard")
+ * @property {string} [subtitle] — sub-line under the title
+ */
+
+/**
+ * @typedef {object} WorkspacePageConfig
+ *   Presentation props for the `workspace` surface (Viewfinder). Spread by the
+ *   library `workspace.jsx`; customers configure here, never edit the JSX.
+ * @property {string}  [title]            — app name (default "Storyboard")
+ * @property {string}  [subtitle]         — sub-line under the title
+ * @property {string|null} [logo]         — logo node/text; falsy → render `logoIcon`
+ * @property {string}  [logoIcon]         — Octicon/Iconoir name (default "iconoir/key-command")
+ * @property {boolean} [showAllArtifacts] — show the combined "All" tab (default false)
+ * @property {boolean} [showPrototypes]   — show the Prototypes tab (default true)
+ * @property {boolean} [showCanvases]     — show the Canvases tab (default true)
+ * @property {boolean} [showComponents]   — show the Components tab (default true)
+ */
+
+/**
+ * @typedef {object} PagesConfig
+ *   Per-surface presentation props, keyed by surface/target name. Holds every
+ *   prop the library workspace pages used to hardcode, so customers configure
+ *   surfaces purely via config. Behavior-preserving defaults match today's UX.
+ * @property {HomePageConfig}      [home]
+ * @property {WorkspacePageConfig} [workspace]
+ */
+
 /**
  * @typedef {object} StoryboardConfig
  * @property {string}   [customDomain]
@@ -225,6 +275,8 @@
  * @property {HotPoolConfig} [hotPool]
  * @property {CommandPaletteConfig} [commandPalette]
  * @property {CustomerModeConfig} [customerMode]
+ * @property {RoutesConfig} [routes] — map of route path → target page. Controls which page renders at each path; `"/"` sets the index. Default `{ "/": "home" }`.
+ * @property {PagesConfig} [pages] — per-surface presentation props (title, subtitle, logo, tab toggles) for the `home` and `workspace` surfaces. Customers configure surfaces here instead of editing library JSX.
  * @property {ThemesConfig} [theming]
  * @property {Record<string, object>} [widgets] — Custom widget metadata (server-side). Maps widget type string → definition (label, icon, chrome, interaction, connectors, features, props). Consumer entries override built-in widget metadata for collision detection, default sizes, prompt-exec config, etc. Browser-side widget components are registered separately via `mountStoryboardCore({ widgets })`. See `DOCS/custom-widgets.md`.
  */
@@ -348,6 +400,33 @@ export const configDefaults = {
     protoHomepage: '',
     canvasHomepage: '',
   },
+  // Route table: path → target page. `"/"` selects the index surface.
+  // Behavior-preserving default — today `/` renders the `home` surface
+  // (SimpleWorkspace). A target is either a string (all envs) or a
+  // per-env object `{ dev, prod, default }` resolved by resolveRouteTarget.
+  // Example consumer override: { "/": { "dev": "workspace", "prod": "home" } }.
+  routes: {
+    '/': 'home',
+  },
+  // Per-surface presentation props, keyed by surface name. The library
+  // workspace pages spread these so customers never edit the JSX. Defaults
+  // reproduce today's exact titles/subtitles and tab visibility.
+  pages: {
+    home: {
+      title: 'Storyboard',
+      subtitle: 'Collaborative workspace for design & code',
+    },
+    workspace: {
+      title: 'Storyboard',
+      subtitle: 'Where design work goes',
+      logo: null,
+      logoIcon: 'iconoir/key-command',
+      showAllArtifacts: false,
+      showPrototypes: true,
+      showCanvases: true,
+      showComponents: true,
+    },
+  },
   theming: {
     // Minimal default theme registry. Consumers add more in their own
     // storyboard.config.json — see README#theming. IDs starting with "dark"
@@ -413,3 +492,22 @@ export function getConfig(raw = {}) {
 export function getConfigDefaults() {
   return JSON.parse(JSON.stringify(configDefaults))
 }
+
+/**
+ * Resolve a configured route path to a target page name for the active env.
+ *
+ * Resolution order for an object target: exact env key (`dev`/`prod`) →
+ * `default` → the other env key → `null`. A string target is returned as-is.
+ *
+ * @param {RoutesConfig|undefined} routes — the `routes` config map
+ * @param {string} path — route path to resolve (e.g. `"/"`)
+ * @param {{ dev?: boolean }} [env] — environment flags (default reads `import.meta.env.DEV` at call sites)
+ * @returns {string|null} the target page name, or `null` if unconfigured
+ */
+export function resolveRouteTarget(routes, path, { dev } = {}) {
+  const entry = routes?.[path]
+  if (!entry) return null
+  if (typeof entry === 'string') return entry || null
+  if (typeof entry !== 'object') return null
+  return (dev ? entry.dev : entry.prod) ?? entry.default ?? entry.prod ?? entry.dev ?? null
+}

package/src/core/stores/configSchema.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { getConfig, getConfigDefaults, configDefaults, builtinPasteRules } from './configSchema.js'
+import { getConfig, getConfigDefaults, configDefaults, builtinPasteRules, resolveRouteTarget } from './configSchema.js'
 
 describe('configSchema', () => {
   describe('getConfigDefaults', () => {
@@ -85,4 +85,78 @@ describe('configSchema', () => {
       expect(JSON.stringify(configDefaults)).toBe(before)
     })
   })
+
+  describe('routes + pages defaults', () => {
+    it('defaults routes["/"] to "home" (behavior-preserving)', () => {
+      const c = getConfig({})
+      expect(c.routes).toEqual({ '/': 'home' })
+    })
+
+    it('defaults the home surface props to today’s values', () => {
+      const c = getConfig({})
+      expect(c.pages.home).toEqual({
+        title: 'Storyboard',
+        subtitle: 'Collaborative workspace for design & code',
+      })
+    })
+
+    it('defaults the workspace surface props to today’s values', () => {
+      const c = getConfig({})
+      expect(c.pages.workspace).toEqual({
+        title: 'Storyboard',
+        subtitle: 'Where design work goes',
+        logo: null,
+        logoIcon: 'iconoir/key-command',
+        showAllArtifacts: false,
+        showPrototypes: true,
+        showCanvases: true,
+        showComponents: true,
+      })
+    })
+
+    it('merges a partial pages override without dropping sibling defaults', () => {
+      const c = getConfig({ pages: { home: { title: 'My App' } } })
+      expect(c.pages.home.title).toBe('My App')
+      expect(c.pages.home.subtitle).toBe('Collaborative workspace for design & code')
+      expect(c.pages.workspace.showPrototypes).toBe(true)
+    })
+
+    it('replaces the routes map when a user provides one', () => {
+      const c = getConfig({ routes: { '/': { dev: 'workspace', prod: 'home' } } })
+      expect(c.routes['/']).toEqual({ dev: 'workspace', prod: 'home' })
+    })
+  })
+
+  describe('resolveRouteTarget', () => {
+    it('returns null for an unconfigured path', () => {
+      expect(resolveRouteTarget({ '/': 'home' }, '/missing')).toBeNull()
+      expect(resolveRouteTarget(undefined, '/')).toBeNull()
+    })
+
+    it('returns a string target in every environment', () => {
+      expect(resolveRouteTarget({ '/': 'home' }, '/', { dev: true })).toBe('home')
+      expect(resolveRouteTarget({ '/': 'home' }, '/', { dev: false })).toBe('home')
+    })
+
+    it('picks the dev target in dev and prod target in prod', () => {
+      const routes = { '/': { dev: 'workspace', prod: 'home' } }
+      expect(resolveRouteTarget(routes, '/', { dev: true })).toBe('workspace')
+      expect(resolveRouteTarget(routes, '/', { dev: false })).toBe('home')
+    })
+
+    it('falls back to default when the active env key is absent', () => {
+      const routes = { '/': { dev: 'workspace', default: 'home' } }
+      expect(resolveRouteTarget(routes, '/', { dev: false })).toBe('home')
+      expect(resolveRouteTarget(routes, '/', { dev: true })).toBe('workspace')
+    })
+
+    it('falls back to the other env key when nothing else matches', () => {
+      expect(resolveRouteTarget({ '/': { prod: 'home' } }, '/', { dev: true })).toBe('home')
+      expect(resolveRouteTarget({ '/': { dev: 'workspace' } }, '/', { dev: false })).toBe('workspace')
+    })
+
+    it('treats an empty-string target as unconfigured', () => {
+      expect(resolveRouteTarget({ '/': '' }, '/')).toBeNull()
+    })
+  })
 })

package/src/internals/SimpleWorkspace/SimpleWorkspace.jsx

@@ -39,6 +39,12 @@ import Workspace, { CreateMenu } from '../Viewfinder.jsx'
 import Icon from '../Icon.jsx'
 import css from './SimpleWorkspace.module.css'
 
+/* ─── localStorage keys ─── */
+
+const SHOW_DRAFTS_KEY = 'sb-home-show-drafts'
+const GROUP_BY_FOLDERS_KEY = 'sb-home-group-folders'
+const COLLAPSED_FOLDERS_KEY = 'sb-home-collapsed-folders'
+
 /* ─── Helpers ─── */
 
 function withBase(basePath, route) {
@@ -154,12 +160,23 @@ function AvatarStack({ authors }) {
 
 /* ─── Cards ─── */
 
-function FolderCard({ folder }) {
+function FolderCard({ folder, collapsed, onToggle }) {
   const isPrivate = !!folder.isPrivate
   return (
-    <div className={`${css.folderCard}${isPrivate ? ' ' + css.folderCardPrivate : ''}`}>
+    <button
+      type="button"
+      className={`${css.folderCard} ${css.folderCardButton}${isPrivate ? ' ' + css.folderCardPrivate : ''}`}
+      onClick={onToggle}
+      aria-expanded={!collapsed}
+    >
+      <span
+        className={collapsed ? css.folderChevron : css.folderChevronExpanded}
+        aria-hidden="true"
+      >
+        <ChevronRightIcon size={14} />
+      </span>
       <span className={css.folderIcon} aria-hidden="true">
-        <Icon name="folder" size={18} />
+        <Icon name={collapsed ? 'folder' : 'folder-open'} size={18} />
       </span>
       <span className={css.folderName}>{folder.dirName.replace(/\.folder$/, '').toUpperCase()}</span>
       {isPrivate && (
@@ -172,7 +189,7 @@ function FolderCard({ folder }) {
         </span>
       )}
       {folder.description && <span className={css.folderDesc}>{folder.description}</span>}
-    </div>
+    </button>
   )
 }
 
@@ -341,19 +358,61 @@ function SimpleWorkspaceImpl({
   const [showAll, setShowAll] = useState(false)
   const [showCreate, setShowCreate] = useState(false)
 
+  // List-control state (persisted to localStorage)
+  const [showDrafts, setShowDrafts] = useState(() => {
+    try { return localStorage.getItem(SHOW_DRAFTS_KEY) !== 'false' } catch { return true }
+  })
+  const [groupByFolders, setGroupByFolders] = useState(() => {
+    try { return localStorage.getItem(GROUP_BY_FOLDERS_KEY) !== 'false' } catch { return true }
+  })
+  const [collapsedFolders, setCollapsedFolders] = useState(() => {
+    try {
+      const raw = localStorage.getItem(COLLAPSED_FOLDERS_KEY)
+      const parsed = raw ? JSON.parse(raw) : []
+      return new Set(Array.isArray(parsed) ? parsed : [])
+    } catch { return new Set() }
+  })
+
+  const toggleShowDrafts = useCallback(() => {
+    setShowDrafts(prev => {
+      const next = !prev
+      try { localStorage.setItem(SHOW_DRAFTS_KEY, String(next)) } catch { /* empty */ }
+      return next
+    })
+  }, [])
+  const toggleGroupByFolders = useCallback(() => {
+    setGroupByFolders(prev => {
+      const next = !prev
+      try { localStorage.setItem(GROUP_BY_FOLDERS_KEY, String(next)) } catch { /* empty */ }
+      return next
+    })
+  }, [])
+  const toggleFolder = useCallback((dirName) => {
+    setCollapsedFolders(prev => {
+      const next = new Set(prev)
+      if (next.has(dirName)) next.delete(dirName)
+      else next.add(dirName)
+      try { localStorage.setItem(COLLAPSED_FOLDERS_KEY, JSON.stringify([...next])) } catch { /* empty */ }
+      return next
+    })
+  }, [])
+
   const canFilter = !!(ghUser.name || ghUser.login)
 
-  // Filter by tab + (optionally) "mine".
-  // Draft / private items (e.g. canvases under `drafts/`) are kept — they render
-  // with an EyeClosedIcon badge so the user can still see and reach them.
+  // Filter by tab + (optionally) "mine" + (optionally) drafts.
+  // Draft / private items (e.g. canvases under `drafts/`) render with an
+  // EyeClosedIcon badge; the "Show drafts" toggle can hide them entirely.
   const visibleItems = useMemo(() => {
     const tabType = activeTab === 'prototypes' ? 'prototype' : 'canvas'
     let pool = allItems.filter(i => i.type === tabType)
     if (!showAll && canFilter) {
       pool = pool.filter(i => isMine(i, ghUser.name, ghUser.login))
     }
+    if (!showDrafts) {
+      pool = pool.filter(i => !i.isPrivate)
+    }
     return pool
-  }, [allItems, activeTab, showAll, canFilter, ghUser.name, ghUser.login])
+  }, [allItems, activeTab, showAll, canFilter, ghUser.name, ghUser.login, showDrafts])
 
   // Folders visible only if they contain at least one visible item of the active tab type.
   // Private folders (e.g. `drafts/`) are kept and rendered with a draft badge.
@@ -455,6 +514,16 @@ function SimpleWorkspaceImpl({
                 ? `No ${activeTab === 'prototypes' ? 'prototypes' : 'canvases'} created by you yet.`
                 : `No ${activeTab === 'prototypes' ? 'prototypes' : 'canvases'} found.`}
             </div>
+          ) : !groupByFolders ? (
+            /* Flat list — folders ignored, all items inline */
+            sortedItems.map(item => (
+              <ArtifactRow
+                key={item.id}
+                item={item}
+                basePath={basePath}
+                branchBasePath={branchBasePath}
+              />
+            ))
           ) : (
             <>
               {/* Ungrouped items first (no folder) */}
@@ -467,22 +536,29 @@ function SimpleWorkspaceImpl({
                 />
               ))}
 
-              {/* Then each folder as a section: header + its items */}
+              {/* Then each folder as a collapsible section: header + its items */}
               {visibleFolders.map(folder => {
                 const folderItems = grouped.byFolder.get(folder.dirName) || []
+                const collapsed = collapsedFolders.has(folder.dirName)
                 return (
                   <section key={folder.dirName} className={css.folderSection}>
-                    <FolderCard folder={folder} />
-                    <div className={css.folderItems}>
-                      {folderItems.map(item => (
-                        <ArtifactRow
-                          key={item.id}
-                          item={item}
-                          basePath={basePath}
-                          branchBasePath={branchBasePath}
-                        />
-                      ))}
-                    </div>
+                    <FolderCard
+                      folder={folder}
+                      collapsed={collapsed}
+                      onToggle={() => toggleFolder(folder.dirName)}
+                    />
+                    {!collapsed && (
+                      <div className={css.folderItems}>
+                        {folderItems.map(item => (
+                          <ArtifactRow
+                            key={item.id}
+                            item={item}
+                            basePath={basePath}
+                            branchBasePath={branchBasePath}
+                          />
+                        ))}
+                      </div>
+                    )}
                   </section>
                 )
               })}
@@ -492,6 +568,26 @@ function SimpleWorkspaceImpl({
 
         {/* Footer actions */}
         <div className={css.footer}>
+          <div className={css.controls}>
+            <label className={css.controlLabel}>
+              <input
+                type="checkbox"
+                className={css.controlCheckbox}
+                checked={showDrafts}
+                onChange={toggleShowDrafts}
+              />
+              Show drafts
+            </label>
+            <label className={css.controlLabel}>
+              <input
+                type="checkbox"
+                className={css.controlCheckbox}
+                checked={groupByFolders}
+                onChange={toggleGroupByFolders}
+              />
+              Group by folders
+            </label>
+          </div>
           {ghUser.loaded && canFilter && hiddenCount > 0 && (
             <button
               type="button"