List.mjs Redesign Plan #

Current State #

A simple scrollable list of all pieces and prompts with basic text buttons.

Goal #

A comprehensive, categorized reference with multiple typefaces, parameter documentation, and rich visual hierarchy—similar to colors.mjs, moods.mjs, and chat.mjs.

---

Data Structure (from /docs.json) #

The docs endpoint returns:

{
  api: {
    structure: { boot, paint, act, sim, beat, leave, meta, preview, ... },
    interaction: { pen, pens, pen3d, event },
    graphics: { line, point, box, wipe, ink, circle, ... },
    sound: { "sound.time", "sound.bpm", ... },
    network: { "net.signup", "net.login", ... },
    state: { store, ... },
    math: { num, geo, ... },
    util: { ... },
  },
  prompts: { // Commands typed directly
    tezos: { sig, desc, params[], done },
    keep: { sig, desc, params[], done },
    tape: { sig, desc, params[], done },
    mood: { sig, desc, params[], done },
    ...
  },
  pieces: { // Loadable pieces
    clock: { sig, desc, colon[], params[], examples[], done },
    colors: { sig, desc, done },
    chat: { sig, desc, done },
    ...
  }
}

---

New Architecture #

1. View Modes (Tab/Section Navigation) #

• All — Flat alphabetical list (current behavior)
• Pieces — Just loadable pieces, categorized
• Commands — Prompt commands only
• API — Developer reference (structure, graphics, sound, network, etc.)

2. Categories for Pieces #

Group pieces by theme (can be auto-detected or manual):

• 🎨 Creative Tools — colors, line, box, fill, brush, camera, crop
• 🎵 Audio/Music — clock, tone, bleep, chord, synth, bubble
• 🎮 Games — brick-breaker, pong, snake, balls
• 💬 Social — chat, mood, moods, field, scream
• 🤖 AI/LLM — sotce, bf, gf, bro, sis, dad, angel
• 📹 Media — tape, video, camera, selfie
• 🎰 Random/Fun — spin, flower, wiggle, wand
• 💼 System — prompt, handle, wallet, tezos, keep
• 🔧 Dev Tools — debug, api, list, docs
• 🌍 World/3D — field, fly, world
• 🙈 Hidden — Items with hidden: true

3. Categories for API #

Use existing structure:

• 🏛️ Structure — boot, paint, act, sim, beat, leave, meta
• 🖱️ Interaction — pen, pens, event
• 🖌️ Graphics — line, box, wipe, ink, circle, write
• 🔊 Sound — sound.time, sound.bpm, sound.play
• 🌐 Network — net.signup, net.login, net.userRequest
• 💾 State — store, params, colon
• 🔢 Math/Geometry — num, geo, help
• 🎛️ UI — ui.Button, ui.TextInput

---

UI Design #

Layout #

┌─────────────────────────────────────────┐
│ 📚 LIST                     [search: _] │  ← Header with search
├─────────────────────────────────────────┤
│ [All] [Pieces] [Commands] [API]         │  ← Tab buttons
├─────────────────────────────────────────┤
│ ▼ 🎨 Creative Tools (12)                │  ← Collapsible category
│   box          Draw rectangles          │
│   colors       An index of usable...    │
│   fill         Fill with solid color    │
│                                         │
│ ▼ 🎵 Audio/Music (8)                    │
│   clock        Musical clock with...    │
│   tone         Play a tone              │
│                                         │
│ ▸ 🎮 Games (4)                          │  ← Collapsed category
│ ▸ 💬 Social (6)                         │
└─────────────────────────────────────────┘

Detail Panel (on selection) #

┌─────────────────────────────────────────┐
│ clock                    MatrixChunky8  │
│ ─────────────────────────────────────── │
│ Musical clock with melody, waveforms,   │
│ Hz shifts, and parallel tracks.         │
│                                         │
│ Usage: clock[:divisor] [melody] [sync]  │  ← signature
│                                         │
│ Colon Parameters:                       │
│   divisor   number   Time divisor       │
│                      (0.5=faster)       │
│                                         │
│ Parameters:                             │
│   melody    string   Notes like cdefg   │
│   sync      "sync"   UTC sync mode      │
│                                         │
│ Examples:                               │
│   clock cdefg                           │
│   clock:0.5 {square}cdefgab             │
│   clock (ceg) (dfa)                     │
│                                         │
│           [ Try It ]                    │  ← Jump to piece
└─────────────────────────────────────────┘

---

Visual Features #

Typography Hierarchy #

• Category headers: MatrixChunky8 or custom large font, colored
• Item names: Default typeface, color-coded by type
• Descriptions: Smaller/dimmer text
• Signatures: Monospace style
• Parameters: Indented, typed

Color Scheme (Dark/Light) #

const scheme = {
  dark: {
    background: [16, 16, 24],
    categoryHeader: [180, 200, 255],
    pieceName: [100, 255, 150],
    commandName: [255, 200, 100],
    apiName: [200, 150, 255],
    description: [120, 120, 140],
    signature: [80, 180, 180],
    parameter: [180, 180, 200],
    searchBox: [40, 40, 50],
    tabActive: [100, 200, 255],
    tabInactive: [80, 80, 100],
  },
  light: {
    // Lighter variants...
  }
};

Interactive Features #

• Search filter: Type to filter items in real-time
• Collapsible categories: Click header to expand/collapse
• Keyboard navigation: Arrow keys, Enter to select
• Touch-friendly: Large tap targets
• Scroll memory: Remember position per tab

---

Implementation Steps #

Phase 1: Data & State #

1. Fetch docs via net.requestDocs()
2. Parse into categorized structure
3. State management for:
   • Current tab (all/pieces/commands/api)
   • Expanded categories
   • Search filter
   • Selected item
   • Scroll positions per tab

Phase 2: Core UI #

1. Tab bar with mode switching
2. Category headers (collapsible)
3. Item rows with name + description
4. Scroll handling per category

Phase 3: Detail Panel #

1. Show on item selection
2. Display signature, description
3. Render colon params, params, examples
4. "Try It" button → jump()

Phase 4: Search & Polish #

1. Search input field
2. Keyboard navigation
3. Theme support (dark/light)
4. Animations/transitions
5. Save state on leave

---

Code Structure #

// list.mjs - Comprehensive API & Piece Reference

// Data
let docs = null;
let categories = {};
let currentTab = "all"; // all | pieces | commands | api
let expandedCategories = new Set();
let searchFilter = "";
let selectedItem = null;
let scrollPositions = { all: 0, pieces: 0, commands: 0, api: 0 };

// Categories
const PIECE_CATEGORIES = { /* ... */ };
const API_CATEGORIES = { /* from docs.api structure */ };

// Color schemes
const scheme = { dark: { /* ... */ }, light: { /* ... */ } };

// UI elements
let tabs = [];
let categoryHeaders = [];
let itemButtons = [];
let searchInput = null;

async function boot({ ui, net, store, typeface }) {
  // Load docs
  docs = await net.requestDocs();
  
  // Build categories
  buildCategories();
  
  // Restore state
  currentTab = await store.retrieve("list:tab") || "all";
  scrollPositions = await store.retrieve("list:scrolls") || { /* defaults */ };
  expandedCategories = new Set(await store.retrieve("list:expanded") || []);
  
  // Build UI elements
  buildTabs(ui);
  buildItems(ui, typeface);
}

function paint({ wipe, ink, screen, dark }) {
  const pal = dark ? scheme.dark : scheme.light;
  wipe(pal.background);
  
  // Header
  ink(pal.categoryHeader).write("📚 LIST", { x: 6, y: 6 }, "MatrixChunky8");
  
  // Tabs
  renderTabs(ink, pal);
  
  // Content based on tab
  switch (currentTab) {
    case "pieces": renderPieces(ink, pal); break;
    case "commands": renderCommands(ink, pal); break;
    case "api": renderAPI(ink, pal); break;
    default: renderAll(ink, pal);
  }
  
  // Detail panel if item selected
  if (selectedItem) renderDetail(ink, pal);
}

function act({ event: e, jump, needsPaint }) {
  // Tab switching
  // Category expand/collapse
  // Item selection
  // Search input
  // Scroll handling
  // Keyboard navigation
}

function leave({ store }) {
  store["list:tab"] = currentTab;
  store["list:scrolls"] = scrollPositions;
  store["list:expanded"] = Array.from(expandedCategories);
  store.persist("list:tab", "list:scrolls", "list:expanded");
}

---

Responsive Design #

Screen Size Breakpoints #

const TINY = 128;   // ~128x128 (minimal AC resolution)
const SMALL = 192;  // ~192x192  
const MEDIUM = 320; // ~320x240
const LARGE = 480;  // Full detail mode

Tiny Mode (width < 128) #

• No tabs — Single "All" view only
• No categories — Flat alphabetical list
• Compact rows: Name only, no description
• No detail panel — Direct jump on tap
• Single column, ~10px row height
• No search — Just scroll

┌──────────┐
│ LIST     │
├──────────┤
│ box      │
│ chat     │
│ clock    │
│ colors   │
│ fill     │
│ line     │
│ mood     │
└──────────┘

Small Mode (128 ≤ width < 192) #

• Tabs as icons — 📦 🎯 📡 (no text)
• Categories collapsed by default
• Short descriptions — Truncated to ~15 chars
• No detail panel — Inline expand or direct jump

┌─────────────────┐
│ LIST   [📦🎯📡]│
├─────────────────┤
│ ▸ 🎨 Creative   │
│ ▼ 🎵 Audio      │
│   clock   Mus.. │
│   tone    Play. │
│ ▸ 💬 Social     │
└─────────────────┘

Medium Mode (192 ≤ width < 320) #

• Full tabs with text
• Categories visible
• Descriptions — Truncated to ~25 chars
• Detail panel — Overlay/modal on selection

┌────────────────────────────┐
│ 📚 LIST        [search: _] │
├────────────────────────────┤
│ [All] [Pieces] [Cmds] [API]│
├────────────────────────────┤
│ ▼ 🎨 Creative Tools (12)   │
│   box       Draw rectangles│
│   colors    An index of... │
└────────────────────────────┘

Large Mode (width ≥ 320) #

• Full UI as designed
• Side panel for details (or overlay)
• Full descriptions
• Keyboard shortcuts visible

Adaptive Functions #

function getLayoutMode(screen) {
  if (screen.width < 128) return "tiny";
  if (screen.width < 192) return "small";
  if (screen.width < 320) return "medium";
  return "large";
}

function getRowHeight(mode) {
  return { tiny: 10, small: 12, medium: 14, large: 16 }[mode];
}

function getMaxDescLength(mode) {
  return { tiny: 0, small: 15, medium: 25, large: 50 }[mode];
}

function showTabs(mode) {
  return mode !== "tiny";
}

function showCategories(mode) {
  return mode !== "tiny";
}

function showSearch(mode) {
  return mode === "medium" || mode === "large";
}

Dynamic Recalculation #

• Recalculate layout on screen resize
• Store scroll position per mode (tiny scrolls faster)
• Button hitboxes scale with row height

---

Open Questions #

1. Detail panel placement: Overlay? Side panel? New screen?
2. Search scope: Just names or also descriptions?
3. API view depth: Show all params inline or click-to-expand?
4. Favorites/Bookmarks: Allow starring items?

---

References #

• colors.mjs — Scrollable categorized list with color swatches
• moods.mjs — Virtual viewport, day-grouped items, theme support
• chat.mjs — Complex UI with multiple panels
• prompt.mjs — Autocomplete, command parsing

---

Timeline Estimate #

• Phase 1 (Data): 1-2 hours
• Phase 2 (Core UI): 3-4 hours
• Phase 3 (Detail): 2-3 hours
• Phase 4 (Polish): 2-3 hours

Total: ~8-12 hours