@dfosco/storyboard-core 2.2.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,7 @@
     "./svelte-plugin-ui/styles/base.css": "./src/svelte-plugin-ui/styles/base.css"
   },
   "dependencies": {
+    "@primer/octicons": "^19.22.0",
     "alpinejs": "^3.15.8",
     "jsonc-parser": "^3.3.1",
     "tachyons": "^4.12.0"

package/src/index.js

@@ -14,6 +14,8 @@ export { loadFlow, listFlows, flowExists, loadRecord, findRecord, loadObject, de
 export { resolveFlowName, resolveRecordName } from './loader.js'
 // Prototype metadata
 export { listPrototypes, getPrototypeMetadata } from './loader.js'
+// Folder metadata
+export { listFolders, getFolderMetadata } from './loader.js'
 // Deprecated scene aliases
 export { loadScene, listScenes, sceneExists } from './loader.js'
 

package/src/loader.js

@@ -30,13 +30,13 @@ function deepMerge(target, source) {
  * Module-level data index, seeded by init().
  * Shape: { flows: {}, objects: {}, records: {} }
  */
-let dataIndex = { flows: {}, objects: {}, records: {}, prototypes: {} }
+let dataIndex = { flows: {}, objects: {}, records: {}, prototypes: {}, folders: {} }
 
 /**
  * Seed the data index. Call once at app startup before any load functions.
  * The Vite data plugin calls this automatically via the generated virtual module.
  *
- * @param {{ flows?: object, scenes?: object, objects: object, records: object, prototypes?: object }} index
+ * @param {{ flows?: object, scenes?: object, objects: object, records: object, prototypes?: object, folders?: object }} index
  */
 export function init(index) {
   if (!index || typeof index !== 'object') {
@@ -47,6 +47,7 @@ export function init(index) {
     objects: index.objects || {},
     records: index.records || {},
     prototypes: index.prototypes || {},
+    folders: index.folders || {},
   }
 }
 
@@ -303,4 +304,21 @@ export function getPrototypeMetadata(name) {
   return dataIndex.prototypes[name] ?? null
 }
 
+/**
+ * Returns the names of all registered folders.
+ * @returns {string[]}
+ */
+export function listFolders() {
+  return Object.keys(dataIndex.folders)
+}
+
+/**
+ * Returns folder metadata by name.
+ * @param {string} name - Folder name (e.g. "Getting Started")
+ * @returns {object|null} Metadata from the .folder.json file, or null
+ */
+export function getFolderMetadata(name) {
+  return dataIndex.folders[name] ?? null
+}
+
 export { deepMerge }

package/src/loader.test.js

@@ -1,4 +1,4 @@
-import { init, loadFlow, listFlows, flowExists, loadScene, listScenes, sceneExists, loadRecord, findRecord, loadObject, deepMerge, resolveFlowName, resolveRecordName } from './loader.js'
+import { init, loadFlow, listFlows, flowExists, loadScene, listScenes, sceneExists, loadRecord, findRecord, loadObject, deepMerge, resolveFlowName, resolveRecordName, listFolders, getFolderMetadata } from './loader.js'
 
 const makeIndex = () => ({
   flows: {
@@ -416,3 +416,41 @@ describe('error hints for scoped data', () => {
     expect(() => loadRecord('xyz')).not.toThrow(/Did you mean/)
   })
 })
+
+// ── Folder functions ──
+
+describe('listFolders', () => {
+  it('returns empty array when no folders registered', () => {
+    init(makeIndex())
+    expect(listFolders()).toEqual([])
+  })
+
+  it('returns folder names when folders are registered', () => {
+    init({
+      ...makeIndex(),
+      folders: {
+        'Getting Started': { meta: { title: 'Getting Started' } },
+        Advanced: { meta: { title: 'Advanced' } },
+      },
+    })
+    expect(listFolders()).toEqual(['Getting Started', 'Advanced'])
+  })
+})
+
+describe('getFolderMetadata', () => {
+  it('returns null when folder does not exist', () => {
+    init(makeIndex())
+    expect(getFolderMetadata('nonexistent')).toBeNull()
+  })
+
+  it('returns folder metadata when folder exists', () => {
+    init({
+      ...makeIndex(),
+      folders: {
+        'My Folder': { meta: { title: 'My Folder', description: 'A folder' } },
+      },
+    })
+    const meta = getFolderMetadata('My Folder')
+    expect(meta).toEqual({ meta: { title: 'My Folder', description: 'A folder' } })
+  })
+})

package/src/svelte-plugin-ui/components/Octicon.svelte

@@ -0,0 +1,75 @@
+<!--
+  Octicon — renders a Primer Octicon by name.
+
+  Includes custom icon overrides (e.g. folder, folder-open) that replace
+  or extend the Primer set.
+
+  Usage:
+    <Octicon name="repo" />
+    <Octicon name="folder" color="#54aeff" />
+    <Octicon name="folder-open" size={24} />
+    <Octicon name="gear" size={16} label="Settings" />
+    <Octicon name="lock" offsetX={1} offsetY={-1} />
+-->
+
+<script lang="ts">
+  import octicons from '@primer/octicons'
+
+  // Custom SVG paths that override or extend the Primer icon set.
+  // Each entry: viewBox string + path d attribute.
+  const customIcons: Record<string, { viewBox: string; path: string }> = {
+    'folder': {
+      viewBox: '0 0 24 24',
+      path: 'M4 20q-.825 0-1.412-.587T2 18V6q0-.825.588-1.412T4 4h5.175q.4 0 .763.15t.637.425L12 6h8q.825 0 1.413.588T22 8v10q0 .825-.587 1.413T20 20z',
+    },
+    'folder-open': {
+      viewBox: '0 0 24 24',
+      path: 'M4 20q-.825 0-1.412-.587T2 18V6q0-.825.588-1.412T4 4h5.175q.4 0 .763.15t.637.425L12 6h9q.425 0 .713.288T22 7t-.288.713T21 8H7.85q-1.55 0-2.7.975T4 11.45V18l1.975-6.575q.2-.65.738-1.037T7.9 10h12.9q1.025 0 1.613.813t.312 1.762l-1.8 6q-.2.65-.737 1.038T19 20z',
+    },
+  }
+
+  interface Props {
+    name: string
+    size?: number
+    label?: string
+    color?: string
+    offsetX?: number
+    offsetY?: number
+  }
+
+  let { name, size = 16, label, color, offsetX = 0, offsetY = 0 }: Props = $props()
+
+  const ariaAttrs = $derived(
+    label ? `aria-label="${label}"` : 'aria-hidden="true"'
+  )
+
+  const custom = $derived(customIcons[name])
+
+  const svg = $derived(
+    custom
+      ? `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="${custom.viewBox}" fill="currentColor" ${ariaAttrs}><path d="${custom.path}"/></svg>`
+      : octicons[name]?.toSVG({
+          width: size,
+          height: size,
+          ...(label ? { 'aria-label': label } : { 'aria-hidden': 'true' }),
+        }) ?? ''
+  )
+
+  const style = $derived(
+    [
+      color ? `color: ${color}` : '',
+      color ? `fill: ${color}` : '',
+      (offsetX || offsetY) ? `translate: ${offsetX}px ${offsetY}px` : '',
+    ].filter(Boolean).join('; ') || undefined
+  )
+</script>
+
+<span class="octicon" {style}>{@html svg}</span>
+
+<style>
+  .octicon {
+    display: inline-flex;
+    align-items: center;
+    vertical-align: middle;
+  }
+</style>

package/src/svelte-plugin-ui/components/Viewfinder.svelte

@@ -10,6 +10,7 @@
 
 <script lang="ts">
   import { buildPrototypeIndex } from '../../viewfinder.js'
+  import Octicon from './Octicon.svelte'
 
   interface Props {
     title?: string
@@ -37,39 +38,54 @@
       : prototypeIndex.globalFlows
   )
 
-  // Merge global flows into the prototype list as "Other flows"
-  const allGroups = $derived(
-    globalFlows.length > 0
-      ? [
-          ...prototypeIndex.prototypes,
-          {
-            name: 'Other flows',
-            dirName: '__global__',
-            description: null,
-            author: null,
-            gitAuthor: null,
-            icon: null,
-            team: null,
-            tags: null,
-            flows: globalFlows,
-          },
-        ]
-      : prototypeIndex.prototypes
+  // Build a flat display list: folders (with nested prototypes), ungrouped prototypes, global flows
+  const ungroupedProtos = $derived(prototypeIndex.prototypes)
+
+  const folders = $derived(prototypeIndex.folders || [])
+
+  const otherFlows = $derived.by(() => {
+    if (globalFlows.length === 0) return null
+    return {
+      name: 'Other flows',
+      dirName: '__global__',
+      description: null,
+      author: null,
+      gitAuthor: null,
+      lastModified: null,
+      icon: null,
+      team: null,
+      tags: null,
+      flows: globalFlows,
+    }
+  })
+
+  const totalProtos = $derived(
+    ungroupedProtos.length + folders.reduce((sum: number, f: any) => sum + f.prototypes.length, 0)
   )
 
   const totalFlows = $derived(
-    allGroups.reduce((sum: number, p: any) => sum + p.flows.length, 0)
+    ungroupedProtos.reduce((sum: number, p: any) => sum + p.flows.length, 0) +
+    globalFlows.length +
+    folders.reduce((sum: number, f: any) =>
+      sum + f.prototypes.reduce((s: number, p: any) => s + p.flows.length, 0), 0)
   )
 
-  // Expanded state — all prototypes start expanded
+  // Sorting — use pre-sorted arrays from buildPrototypeIndex
+  type SortMode = 'updated' | 'title'
+  let sortBy: SortMode = $state('updated')
+
+  const sortedProtos = $derived(prototypeIndex.sorted?.[sortBy]?.prototypes ?? ungroupedProtos)
+  const sortedFolders = $derived(prototypeIndex.sorted?.[sortBy]?.folders ?? folders)
+
+  // Expanded state — all prototypes and folders start expanded
   let expanded: Record<string, boolean> = $state({})
 
   function isExpanded(dirName: string): boolean {
     return expanded[dirName] ?? true
   }
 
-  function togglePrototype(dirName: string) {
-    expanded[dirName] = !expanded[dirName]
+  function toggle(dirName: string) {
+    expanded[dirName] = !isExpanded(dirName)
   }
 
   function protoRoute(dirName: string): string {
@@ -165,11 +181,32 @@
           <p class="subtitle">{subtitle}</p>
         {/if}
       </div>
+    </div>
+    <div class="controlsRow">
+      <!-- <span class="sceneCount">
+        {(folders.length > 0 ? `${folders.length} folder${folders.length !== 1 ? 's' : ''} · ` : '') + `${totalProtos} prototype${totalProtos !== 1 ? 's' : ''} · ${totalFlows} flow${totalFlows !== 1 ? 's' : ''}`}
+      </span> -->
+      <div class="sortToggle">
+        <button
+          class="sortButton"
+          class:sortButtonActive={sortBy === 'updated'}
+          onclick={() => sortBy = 'updated'}
+        >
+          <Octicon name="clock" size={14} offsetY={-1} />
+          Last updated
+        </button>
+        <button
+          class="sortButton"
+          class:sortButtonActive={sortBy === 'title'}
+          onclick={() => sortBy = 'title'}
+        >
+          <Octicon name="sort-asc" size={14} offsetY={-1} />
+          Title A–Z
+        </button>
+      </div>
       {#if branches && branches.length > 0}
         <div class="branchDropdown">
-          <svg class="branchIcon" width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
-            <path d="M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.492 2.492 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628A2.25 2.25 0 0 1 9.5 3.25Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z" />
-          </svg>
+          <span class="branchIcon"><Octicon size={16} color="var(--fgColor-muted)" offsetY={-1} offsetX={2} name="git-branch" /></span>
           <select
             class="branchSelect"
             onchange={handleBranchChange}
@@ -183,32 +220,61 @@
         </div>
       {/if}
     </div>
-    <p class="sceneCount">
-      {allGroups.length} prototype{allGroups.length !== 1 ? 's' : ''} · {totalFlows} flow{totalFlows !== 1 ? 's' : ''}
-    </p>
   </header>
 
-  {#if allGroups.length === 0}
+  {#if totalProtos === 0 && folders.length === 0}
     <p class="empty">No flows found. Add a <code>*.flow.json</code> file to get started.</p>
   {:else}
     <div class="list">
-      {#each allGroups as proto (proto.dirName)}
+      {#snippet protoEntry(proto)}
         <section class="protoGroup">
-          {#if proto.flows.length > 0}
+          {#if proto.hideFlows && proto.flows.length === 1}
+            <!-- Single flow, hidden — navigates directly to the flow -->
+            <a class="listItem" href={proto.flows[0].route}>
+              <div class="cardBody">
+                <p class="protoName" class:otherflows={proto.dirName === '__global__'}>
+                  {#if proto.icon}<span class="protoIcon">{proto.icon}</span>{/if}
+                  {proto.name}
+                </p>
+                {#if proto.description}
+                  <p class="protoDesc">{proto.description}</p>
+                {/if}
+                {#if proto.author}
+                  {@const authors = Array.isArray(proto.author) ? proto.author : [proto.author]}
+                  <div class="author">
+                    <span class="authorAvatars">
+                      {#each authors as a (a)}
+                        <img
+                          src="https://github.com/{a}.png?size=48"
+                          alt={a}
+                          class="authorAvatar"
+                        />
+                      {/each}
+                    </span>
+                    <span class="authorName">{authors.join(', ')}</span>
+                  </div>
+                {:else if proto.gitAuthor}
+                  <p class="authorPlain">{proto.gitAuthor}</p>
+                {/if}
+              </div>
+            </a>
+          {:else if proto.flows.length > 0}
             <!-- Expandable prototype with flows -->
             <button
               class="listItem protoHeader"
-              onclick={() => togglePrototype(proto.dirName)}
+              onclick={() => toggle(proto.dirName)}
               aria-expanded={isExpanded(proto.dirName)}
             >
               <div class="cardBody">
-                <p class="sceneName">
+                <p class="protoName" class:otherflows={proto.dirName === '__global__'}>
                   {#if proto.icon}<span class="protoIcon">{proto.icon}</span>{/if}
                   {proto.name}
-                  <span class="protoChevron" class:protoChevronOpen={isExpanded(proto.dirName)}>
-                    <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
-                      <path d="M6.22 3.22a.75.75 0 0 1 1.06 0l4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L9.94 8 6.22 4.28a.75.75 0 0 1 0-1.06Z" />
-                    </svg>
+                  <span class="protoChevron">
+                    {#if isExpanded(proto.dirName)}
+                      <Octicon size={12} color="var(--fgColor-disabled)" name="chevron-down" offsetY={-3} offsetX={2} />
+                    {:else}
+                      <Octicon size={12} color="var(--fgColor-disabled)" name="chevron-right" offsetY={-3} offsetX={2} />
+                    {/if}
                   </span>
                 </p>
                 {#if proto.description}
@@ -237,7 +303,7 @@
             <!-- Prototype with no flows — navigates directly -->
             <a class="listItem" href={protoRoute(proto.dirName)}>
               <div class="cardBody">
-                <p class="sceneName">
+                <p class="protoName" class:otherflows={proto.dirName === '__global__'}>
                   {#if proto.icon}<span class="protoIcon">{proto.icon}</span>{/if}
                   {proto.name}
                 </p>
@@ -265,7 +331,7 @@
             </a>
           {/if}
 
-          {#if isExpanded(proto.dirName) && proto.flows.length > 0}
+          {#if !(proto.hideFlows && proto.flows.length === 1) && isExpanded(proto.dirName) && proto.flows.length > 0}
             <div class="flowList">
               {#each proto.flows as flow (flow.key)}
                 <a href={flow.route} class="listItem flowItem">
@@ -275,7 +341,7 @@
                     </div>
                   {/if}
                   <div class="cardBody">
-                    <p class="sceneName">{flow.meta?.title || formatName(flow.name)}</p>
+                    <p class="protoName">{flow.meta?.title || formatName(flow.name)}</p>
                     {#if flow.meta?.description}
                       <p class="flowDesc">{flow.meta.description}</p>
                     {/if}
@@ -285,7 +351,49 @@
             </div>
           {/if}
         </section>
+      {/snippet}
+
+      <!-- Folders with their prototypes -->
+      {#each sortedFolders as folder (folder.dirName)}
+        <section class="folderGroup" class:folderGroupOpen={isExpanded(`folder:${folder.dirName}`)}>
+          <button
+            class="folderHeader"
+            onclick={() => toggle(`folder:${folder.dirName}`)}
+            aria-expanded={isExpanded(`folder:${folder.dirName}`)}
+          >
+            <p class="folderName">
+              <span>
+                {#if isExpanded(`folder:${folder.dirName}`)}
+                  <Octicon size={20} offsetY={-1.5} name="folder-open" color="#54aeff" />
+                {:else}
+                  <Octicon size={20} offsetY={-1.5} name="folder" color="#54aeff" />
+                {/if}
+              </span>
+              {folder.name}
+            </p>
+            {#if folder.description}
+              <p class="folderDesc">{folder.description}</p>
+            {/if}
+          </button>
+          {#if isExpanded(`folder:${folder.dirName}`) && folder.prototypes.length > 0}
+            <div class="folderContent">
+              {#each folder.prototypes as proto (proto.dirName)}
+                {@render protoEntry(proto)}
+              {/each}
+            </div>
+          {/if}
+        </section>
+      {/each}
+
+      <!-- Ungrouped prototypes (not in any folder) -->
+      {#each sortedProtos as proto (proto.dirName)}
+        {@render protoEntry(proto)}
       {/each}
+
+      <!-- Other flows (always at the bottom) -->
+      {#if otherFlows}
+        {@render protoEntry(otherFlows)}
+      {/if}
     </div>
   {/if}
 </div>
@@ -300,19 +408,17 @@
 
   .header {
     max-width: 720px;
-    margin: 0 auto 64px;
+    margin: 0 auto 40px;
   }
 
   .headerTop {
     display: flex;
     align-items: baseline;
-    justify-content: space-between;
     gap: 16px;
   }
 
   .title {
-    font-size: 72px;
-    font-weight: 400;
+    font: var(--text-display-shorthand); 
     margin: 0 0 12px;
     color: var(--fgColor-default, #e6edf3);
     letter-spacing: -0.03em;
@@ -326,11 +432,64 @@
     letter-spacing: 0.01em;
   }
 
-  .sceneCount {
+  .controlsRow {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin: 16px 0 0;
+  }
+
+  /* .sceneCount {
     font-size: 13px;
     color: var(--fgColor-muted, #848d97);
-    margin: 16px 0 0;
     letter-spacing: 0.01em;
+    white-space: nowrap;
+  } */
+
+  .sortToggle {
+    display: flex;
+    gap: 2px;
+    background: var(--bgColor-inset);
+    padding: var(--base-size-4) var(--base-size-6);
+    border-radius: 9999px;
+  }
+
+  .sortButton {
+    display: inline-flex;
+    align-items: center;
+    border-radius: 9999px;
+    gap: 4px;
+    padding: 6px 10px;
+    font-size: 12px;
+    font-family: inherit;
+    color: var(--fgColor-muted, #848d97);
+    background: transparent;
+    border: none;
+    cursor: pointer;
+    transition: color 0.15s, background 0.15s, border-color 0.15s;
+
+    &:first-child {
+      transform: translateX(-1px);
+    }
+
+    &:last-child {
+      transform: translateX(1px);
+    }
+  }
+
+  .sortButton:hover {
+    color: var(--fgColor-default, #e6edf3);
+    background: var(--bgColor-neutral-muted, rgba(110, 118, 129, 0.1));
+  }
+
+  .sortButtonActive {
+    color: var(--fgColor-default, #e6edf3);
+    background: var(--bgColor-neutral-muted, rgba(110, 118, 129, 0.15));
+    border: none;
+  }
+
+  .sortButton:first-child {
+    transform: translateX(-1px);
   }
 
   .branchDropdown {
@@ -339,6 +498,7 @@
     gap: 0;
     flex-shrink: 0;
     position: relative;
+    margin-left: auto;
   }
 
   .branchIcon {
@@ -370,7 +530,7 @@
   }
 
   .branchSelect:hover {
-    border-color: var(--fgColor-muted, #848d97);
+    border-color: #bbbbbb;
   }
 
   .branchSelect:focus-visible {
@@ -381,6 +541,7 @@
   .list {
     display: flex;
     flex-direction: column;
+    gap: var(--base-size-8);
     max-width: 720px;
     margin: 0 auto;
   }
@@ -388,11 +549,79 @@
   .protoGroup {
     display: flex;
     flex-direction: column;
+    gap: var(--base-size-8);
+  }
+
+  .protoGroup > .listItem {
+    border: 1px solid var(--borderColor-muted, #30363d);
+    border-radius: var(--base-size-6);
+  }
+
+  .folderGroup {
+    display: flex;
+    flex-direction: column;
+    gap: var(--base-size-8);
+  }
+
+  .folderHeader {
+    display: flex;
+    flex-direction: row;
+    align-items: baseline;
+    justify-content: flex-start;
+    gap: var(--base-size-8);
+    appearance: none;
+    border: none;
+    border-radius: var(--base-size-6);
+    border: 1px solid var(--borderColor-muted, #30363d);
+    background: none;
+    width: 100%;
+    text-align: left;
+    cursor: pointer;
+    color: inherit;
+    padding: var(--base-size-16);
+
+    &:hover,
+    .folderGroupOpen & {
+      background-color: var(--bgColor-muted, #161b22);
+    }
+  }
+
+
+  .folderGroupOpen .folderHeader {
+    background-color: var(--bgColor-muted, #161b22);
+  }
+
+
+  .folderName {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--base-size-8);
+    font-size: var(--text-body-size-small);
+    font-weight: 600;
+    color: var(--fgColor-default);
+    margin: 0;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    line-height: 1.6;
+  }
+
+  .folderDesc {
+    font-size: var(--text-body-size-small);
+    color: var(--fgColor-muted, #848d97);
+    margin: 0;
+    letter-spacing: 0.01em;
+    text-transform: none;
+    font-weight: 400;
+  }
+
+  .folderContent {
+    display: flex;
+    flex-direction: column;
+    gap: var(--base-size-8);
   }
 
   .listItem {
     display: block;
-    padding: 8px 0;
     text-decoration: none;
     color: inherit;
   }
@@ -405,11 +634,17 @@
     appearance: none;
     border: none;
     background: none;
+    border-radius: var(--base-size-6);
     width: 100%;
     text-align: left;
     cursor: pointer;
     color: inherit;
-    padding: 8px 0;
+    padding: 0;
+  }
+
+  .protoHeader[aria-expanded="true"] .cardBody {
+    background-color: var(--bgColor-muted);
+    border-radius: var(--base-size-6);
   }
 
   .cardBody {
@@ -417,11 +652,11 @@
   }
 
   .cardBody:hover {
-    background-color: var(--bgColor-muted, #161b22);
-    border-radius: 8px;
+    background-color: var(--bgColor-muted);
+    border-radius: var(--base-size-6);
   }
 
-  .sceneName {
+  .protoName {
     font-size: var(--text-title-size-medium);
     font-weight: 400;
     color: var(--fgColor-default, #e6edf3);
@@ -430,23 +665,17 @@
     line-height: 1.6;
     transition: font-style 0.15s ease;
   }
+  
+  .protoName.otherflows {
+    font-size: var(--text-body-size-small);
+    font-weight: 600;
+    text-transform: uppercase;
+    direction: rtl;
 
-  .protoChevron {
-    display: inline-flex;
-    align-items: center;
-    color: var(--fgColor-muted, #848d97);
-    transition: transform 0.15s ease;
-    transform: rotate(0deg);
-    margin-right: 4px;
-    vertical-align: middle;
-  }
-
-  .protoChevronOpen {
-    transform: rotate(90deg);
-  }
+    & .protoChevron {
+      margin-right: var(--base-size-8);
+    }
 
-  .protoIcon {
-    margin-right: 4px;
   }
 
   .protoDesc {
@@ -501,14 +730,14 @@
   }
 
   .flowList {
-    margin: 0 var(--base-size-12);
+    margin: 0;
     padding: 0;
     display: flex;
     flex-direction: column;
   }
 
   .flowItem {
-    border: 1px solid var(--borderColor-muted, #30363d);
+    border: 1px solid var(--borderColor-muted);
     padding: 0;
   }
 
@@ -530,7 +759,7 @@
     border-radius: var(--base-size-6);
   }
 
-  .flowItem .sceneName {
+  .flowItem .protoName {
     font-size: var(--text-title-size-small);
     color: var(--fgColor-muted);
   }

package/src/viewfinder.js

@@ -1,4 +1,4 @@
-import { loadFlow, listFlows, listPrototypes, getPrototypeMetadata } from './loader.js'
+import { loadFlow, listFlows, listPrototypes, getPrototypeMetadata, listFolders, getFolderMetadata } from './loader.js'
 
 /**
  * Deterministic hash from a string — used for seeding generative placeholders.
@@ -71,14 +71,16 @@ export function getFlowMeta(flowName) {
 export const getSceneMeta = getFlowMeta
 
 /**
- * Build a structured prototype index grouping flows by prototype.
+ * Build a structured prototype index grouping flows by prototype,
+ * and prototypes by folder.
  *
  * Returns an object with:
- * - prototypes: array of prototype entries with metadata and their flows
+ * - folders: array of folder entries containing their prototypes
+ * - prototypes: array of ungrouped prototype entries (not in any folder)
  * - globalFlows: flows not belonging to any prototype
  *
  * @param {string[]} [knownRoutes] - Array of known route names
- * @returns {{ prototypes: Array, globalFlows: Array }}
+ * @returns {{ folders: Array, prototypes: Array, globalFlows: Array }}
  */
 export function buildPrototypeIndex(knownRoutes = []) {
   const flows = listFlows()
@@ -95,9 +97,12 @@ export function buildPrototypeIndex(knownRoutes = []) {
       description: meta.description || null,
       author: meta.author || null,
       gitAuthor: raw?.gitAuthor || null,
+      lastModified: raw?.lastModified || null,
       icon: meta.icon || null,
       team: meta.team || null,
       tags: meta.tags || null,
+      hideFlows: meta.hideFlows ?? raw?.hideFlows ?? false,
+      folder: raw?.folder || null,
       flows: [],
     }
   }
@@ -115,9 +120,12 @@ export function buildPrototypeIndex(knownRoutes = []) {
           description: null,
           author: null,
           gitAuthor: null,
+          lastModified: null,
           icon: null,
           team: null,
           tags: null,
+          hideFlows: false,
+          folder: null,
           flows: [],
         }
       }
@@ -138,8 +146,72 @@ export function buildPrototypeIndex(knownRoutes = []) {
     }
   }
 
+  // Build folder entries from .folder.json metadata
+  const folderMap = {}
+  for (const folderName of listFolders()) {
+    const raw = getFolderMetadata(folderName)
+    const meta = raw?.meta || raw || {}
+    folderMap[folderName] = {
+      name: meta.title || folderName,
+      dirName: folderName,
+      description: meta.description || null,
+      icon: meta.icon || null,
+      prototypes: [],
+    }
+  }
+
+  // Partition prototypes into folders vs ungrouped
+  const ungrouped = []
+  for (const proto of Object.values(protoMap)) {
+    if (proto.folder && folderMap[proto.folder]) {
+      folderMap[proto.folder].prototypes.push(proto)
+    } else if (proto.folder) {
+      // Folder referenced but no .folder.json — create an implicit folder
+      folderMap[proto.folder] = {
+        name: proto.folder,
+        dirName: proto.folder,
+        description: null,
+        icon: null,
+        prototypes: [proto],
+      }
+    } else {
+      ungrouped.push(proto)
+    }
+  }
+
+  const folders = Object.values(folderMap)
+  const prototypes = ungrouped
+
+  // Pre-sort by title (A-Z)
+  const sortByTitle = (a, b) => (a.name || '').localeCompare(b.name || '')
+
+  // Pre-sort by last updated (newest first, nulls last)
+  const sortByUpdated = (a, b) => {
+    const aTime = a.lastModified ? new Date(a.lastModified).getTime() : 0
+    const bTime = b.lastModified ? new Date(b.lastModified).getTime() : 0
+    return bTime - aTime
+  }
+
+  // Sort folder contents by their most recently updated prototype
+  const folderByUpdated = (a, b) => {
+    const aMax = Math.max(0, ...a.prototypes.map(p => p.lastModified ? new Date(p.lastModified).getTime() : 0))
+    const bMax = Math.max(0, ...b.prototypes.map(p => p.lastModified ? new Date(p.lastModified).getTime() : 0))
+    return bMax - aMax
+  }
+
   return {
-    prototypes: Object.values(protoMap),
+    folders,
+    prototypes,
     globalFlows,
+    sorted: {
+      title: {
+        prototypes: [...prototypes].sort(sortByTitle),
+        folders: [...folders].map(f => ({ ...f, prototypes: [...f.prototypes].sort(sortByTitle) })).sort(sortByTitle),
+      },
+      updated: {
+        prototypes: [...prototypes].sort(sortByUpdated),
+        folders: [...folders].map(f => ({ ...f, prototypes: [...f.prototypes].sort(sortByUpdated) })).sort(folderByUpdated),
+      },
+    },
   }
 }

package/src/viewfinder.test.js

@@ -1,5 +1,5 @@
 import { init } from './loader.js'
-import { hash, resolveFlowRoute, getFlowMeta, resolveSceneRoute, getSceneMeta } from './viewfinder.js'
+import { hash, resolveFlowRoute, getFlowMeta, resolveSceneRoute, getSceneMeta, buildPrototypeIndex } from './viewfinder.js'
 
 const makeIndex = () => ({
   flows: {
@@ -150,3 +150,168 @@ describe('getSceneMeta (deprecated alias)', () => {
     expect(getSceneMeta('meta-author')).toEqual({ author: 'dfosco' })
   })
 })
+
+// ── buildPrototypeIndex ──
+
+describe('buildPrototypeIndex', () => {
+  it('passes hideFlows from prototype metadata', () => {
+    init({
+      flows: { 'MyProto/only-flow': { meta: { title: 'Only Flow' } } },
+      objects: {},
+      records: {},
+      prototypes: {
+        MyProto: { meta: { title: 'My Proto', hideFlows: true } },
+      },
+    })
+    const { prototypes } = buildPrototypeIndex([])
+    const proto = prototypes.find(p => p.dirName === 'MyProto')
+    expect(proto.hideFlows).toBe(true)
+    expect(proto.flows).toHaveLength(1)
+  })
+
+  it('defaults hideFlows to false when not set', () => {
+    init({
+      flows: { 'Other/flow-a': { meta: { title: 'A' } } },
+      objects: {},
+      records: {},
+      prototypes: {
+        Other: { meta: { title: 'Other Proto' } },
+      },
+    })
+    const { prototypes } = buildPrototypeIndex([])
+    const proto = prototypes.find(p => p.dirName === 'Other')
+    expect(proto.hideFlows).toBe(false)
+  })
+
+  it('reads hideFlows from top-level prototype metadata (outside meta key)', () => {
+    init({
+      flows: { 'TopLevel/only-flow': { meta: { title: 'Only Flow' } } },
+      objects: {},
+      records: {},
+      prototypes: {
+        TopLevel: { meta: { title: 'Top Level' }, hideFlows: true },
+      },
+    })
+    const { prototypes } = buildPrototypeIndex([])
+    const proto = prototypes.find(p => p.dirName === 'TopLevel')
+    expect(proto.hideFlows).toBe(true)
+  })
+
+  it('groups prototypes into folders when folder field is set', () => {
+    init({
+      flows: {
+        'Example/basic': { meta: { title: 'Basic' } },
+        'Signup/default': { meta: { title: 'Default' } },
+      },
+      objects: {},
+      records: {},
+      prototypes: {
+        Example: { meta: { title: 'Examples' }, folder: 'Getting Started' },
+        Signup: { meta: { title: 'Sign Up' }, folder: 'Getting Started' },
+      },
+      folders: {
+        'Getting Started': { meta: { title: 'Getting Started', description: 'Intro prototypes', icon: '📚' } },
+      },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.folders).toHaveLength(1)
+    expect(result.prototypes).toHaveLength(0)
+
+    const folder = result.folders[0]
+    expect(folder.name).toBe('Getting Started')
+    expect(folder.description).toBe('Intro prototypes')
+    expect(folder.icon).toBe('📚')
+    expect(folder.prototypes).toHaveLength(2)
+    expect(folder.prototypes.map(p => p.dirName)).toContain('Example')
+    expect(folder.prototypes.map(p => p.dirName)).toContain('Signup')
+  })
+
+  it('keeps prototypes without a folder as ungrouped', () => {
+    init({
+      flows: {
+        'Grouped/flow-a': {},
+        'Standalone/flow-b': {},
+      },
+      objects: {},
+      records: {},
+      prototypes: {
+        Grouped: { meta: { title: 'Grouped' }, folder: 'MyFolder' },
+        Standalone: { meta: { title: 'Standalone' } },
+      },
+      folders: {
+        MyFolder: { meta: { title: 'My Folder' } },
+      },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.folders).toHaveLength(1)
+    expect(result.prototypes).toHaveLength(1)
+    expect(result.prototypes[0].dirName).toBe('Standalone')
+    expect(result.folders[0].prototypes).toHaveLength(1)
+    expect(result.folders[0].prototypes[0].dirName).toBe('Grouped')
+  })
+
+  it('creates implicit folder when prototype references a folder with no metadata', () => {
+    init({
+      flows: { 'Proto/flow': {} },
+      objects: {},
+      records: {},
+      prototypes: {
+        Proto: { meta: { title: 'Proto' }, folder: 'Implicit' },
+      },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.folders).toHaveLength(1)
+    expect(result.folders[0].name).toBe('Implicit')
+    expect(result.folders[0].prototypes).toHaveLength(1)
+  })
+
+  it('uses folder directory name as display name when no title in metadata', () => {
+    init({
+      flows: {},
+      objects: {},
+      records: {},
+      prototypes: {},
+      folders: {
+        'My Folder': {},
+      },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.folders).toHaveLength(1)
+    expect(result.folders[0].name).toBe('My Folder')
+  })
+
+  it('returns empty folders array when no folders exist', () => {
+    init({
+      flows: { 'A/flow': {} },
+      objects: {},
+      records: {},
+      prototypes: { A: { meta: { title: 'A' } } },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.folders).toHaveLength(0)
+    expect(result.prototypes).toHaveLength(1)
+  })
+
+  it('passes through lastModified from prototype metadata', () => {
+    const ts = '2025-01-15T10:30:00-05:00'
+    init({
+      flows: { 'App/home': {} },
+      objects: {},
+      records: {},
+      prototypes: { App: { meta: { title: 'My App' }, lastModified: ts } },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.prototypes[0].lastModified).toBe(ts)
+  })
+
+  it('defaults lastModified to null when not provided', () => {
+    init({
+      flows: { 'App/home': {} },
+      objects: {},
+      records: {},
+      prototypes: { App: { meta: { title: 'My App' } } },
+    })
+    const result = buildPrototypeIndex([])
+    expect(result.prototypes[0].lastModified).toBeNull()
+  })
+})