Refactor builder UX with walkthrough mode, simplified simple mode, and legacy simple-mode archive

src/components/builder/components/CommandPalette.tsx

@@ -1,6 +1,10 @@
 // src/components/builder/components/CommandPalette.tsx
 import React, { useState, useEffect, useRef, useCallback, memo } from 'react';
 import { Command, Search, X } from 'lucide-react';
+import {
+  loadRecentCommandIds,
+  saveRecentCommandIds,
+} from '../systems/storage/builderStorage';
 
 export interface PaletteCommand {
   id: string;
@@ -61,22 +65,13 @@ const CommandPalette: React.FC<Props> = memo(({ isOpen, onClose, commands }) =>
   }, [isOpen]);
 
   useEffect(() => {
-    try {
-      const r = JSON.parse(sessionStorage.getItem('posterium_recent_cmds') || '[]');
-      setRecentIds(r);
-    } catch {
-      /* ignore */
-    }
+    setRecentIds(loadRecentCommandIds());
   }, []);
 
   const recordRecent = useCallback((id: string) => {
     setRecentIds((prev) => {
       const next = [id, ...prev.filter((x) => x !== id)].slice(0, 5);
-      try {
-        sessionStorage.setItem('posterium_recent_cmds', JSON.stringify(next));
-      } catch {
-        /* ignore */
-      }
+      saveRecentCommandIds(next);
       return next;
     });
   }, []);

src/components/builder/components/LayerPanel.tsx

@@ -103,7 +103,8 @@ const ApiKeysPanel: React.FC<{
         className="body-font leading-relaxed"
         style={{ fontSize: 9, color: 'var(--film-text-dim)' }}
       >
-        Override the default API keys used to fetch ratings and posters. Stored in a browser cookie.
+        Override the default API keys used to fetch ratings and posters. Stored in browser
+        localStorage on this device only.
       </p>
 
       {[

src/components/builder/components/ResetDialogue.tsx

@@ -136,7 +136,7 @@ const ResetDialog = memo<Props>(({ isOpen, onClose, onConfirm }) => (
                 }}
               >
                 Badge and layout settings will be restored to defaults. Your current poster source,
-                media IDs, and saved API keys will be kept.
+                media IDs, and saved API keys in local storage will be kept.
               </p>
               <div
                 style={{

src/components/builder/components/navigation/ModeToggle.tsx

@@ -1,6 +1,6 @@
 import React, { memo } from 'react';
 
-export type BuilderMode = 'simple' | 'advanced';
+export type BuilderMode = 'simple' | 'advanced' | 'walkthrough';
 
 interface Props {
   mode: BuilderMode;
@@ -13,21 +13,27 @@ const ModeToggle: React.FC<Props> = memo(({ mode, onChange }) => (
     style={{ background: 'rgba(255,255,255,0.04)', border: '1px solid rgba(196,124,46,0.16)' }}
     aria-label="Builder mode"
   >
-    {(['simple', 'advanced'] as const).map((item) => {
-      const active = mode === item;
+    {(
+      [
+        { id: 'walkthrough', label: 'Walkthrough' },
+        { id: 'simple', label: 'Simple' },
+        { id: 'advanced', label: 'Advanced' },
+      ] as const
+    ).map((item) => {
+      const active = mode === item.id;
       return (
         <button
-          key={item}
+          key={item.id}
           type="button"
-          onClick={() => onChange(item)}
+          onClick={() => onChange(item.id)}
           aria-pressed={active}
-          className="h-7 px-2.5 rounded-md syne-font text-[10px] font-bold uppercase tracking-wider transition-all"
+          className="h-7 px-2.5 rounded-md syne-font text-[10px] font-bold uppercase tracking-[0.16em] transition-all"
           style={{
             color: active ? '#070706' : 'var(--film-text-dim)',
             background: active ? 'var(--film-amber)' : 'transparent',
           }}
         >
-          {item}
+          {item.label}
         </button>
       );
     })}

src/components/builder/components/simple/MediaPicker.tsx

@@ -0,0 +1,149 @@
+import React, { useEffect, useState } from 'react';
+import { Search, Loader2, Film, Tv } from 'lucide-react';
+import type { PosterConfig } from '../../types';
+import { DEFAULT_API_BASE } from '../../utils';
+
+interface SearchResult {
+  id: number;
+  title?: string;
+  name?: string;
+  poster_path?: string;
+  release_date?: string;
+  first_air_date?: string;
+  media_type?: 'movie' | 'tv';
+}
+
+interface Props {
+  config: PosterConfig;
+  setConfig: React.Dispatch<React.SetStateAction<PosterConfig>>;
+  title?: string;
+}
+
+const MediaPicker: React.FC<Props> = ({ config, setConfig, title = 'Media selection' }) => {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<SearchResult[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [selectedTitle, setSelectedTitle] = useState('');
+  const [error, setError] = useState('');
+
+  useEffect(() => {
+    const ctrl = new AbortController();
+    const t = setTimeout(async () => {
+      if (query.trim().length < 2) {
+        setResults([]);
+        setError('');
+        return;
+      }
+
+      setLoading(true);
+      setError('');
+      try {
+        const response = await fetch(`${DEFAULT_API_BASE}/search?q=${encodeURIComponent(query)}`, {
+          signal: ctrl.signal,
+        });
+        const data = await response.json();
+        const next = Array.isArray(data.results)
+          ? data.results.filter(
+              (item: SearchResult) =>
+                item.poster_path && (item.media_type === 'movie' || item.media_type === 'tv')
+            )
+          : [];
+        setResults(next);
+      } catch (error: unknown) {
+        if (error instanceof Error && error.name === 'AbortError') return;
+        setError(
+          error instanceof Error && error.message
+            ? error.message
+            : 'Search failed. Check your connection and try again.'
+        );
+      } finally {
+        setLoading(false);
+      }
+    }, 350);
+
+    return () => {
+      clearTimeout(t);
+      ctrl.abort();
+    };
+  }, [query]);
+
+  const handleSelect = (item: SearchResult) => {
+    const mediaType = item.media_type === 'tv' ? 'tv' : 'movie';
+    setConfig((prev) => ({
+      ...prev,
+      tmdbId: String(item.id),
+      imdbId: undefined,
+      mediaType,
+    }));
+    setSelectedTitle(item.title || item.name || '');
+    setQuery('');
+    setResults([]);
+  };
+
+  return (
+    <div className="space-y-2">
+      <p className="syne-font uppercase tracking-widest" style={{ fontSize: 9, color: 'var(--film-text-dim)' }}>
+        {title}
+      </p>
+
+      <div
+        className="relative flex items-center h-10 rounded-lg"
+        style={{ background: 'rgba(255,255,255,0.04)', border: '1px solid rgba(255,255,255,0.1)' }}
+      >
+        <span className="pl-3" style={{ color: 'var(--film-text-dim)' }}>
+          {loading ? <Loader2 size={12} className="animate-spin" /> : <Search size={12} />}
+        </span>
+        <input
+          aria-label="Search media"
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder="Search a movie or show"
+          className="w-full h-full px-2 bg-transparent border-none outline-none syne-font"
+          style={{ fontSize: 11, color: 'var(--film-cream)' }}
+        />
+      </div>
+
+      {results.length > 0 && (
+        <div
+          className="max-h-56 overflow-y-auto rounded-xl p-1"
+          style={{ background: 'var(--film-mid)', border: '1px solid rgba(255,255,255,0.08)' }}
+        >
+          {results.map((item) => {
+            const label = item.title || item.name || 'Untitled';
+            const year = (item.release_date || item.first_air_date || '').split('-')[0];
+            const isTv = item.media_type === 'tv';
+            return (
+              <button
+                key={item.id}
+                type="button"
+                onClick={() => handleSelect(item)}
+                className="w-full text-left px-2.5 py-2 rounded-lg hover:bg-[rgba(196,124,46,0.1)] transition-colors"
+              >
+                <p className="syne-font truncate" style={{ fontSize: 11, color: 'var(--film-cream)' }}>
+                  {label}
+                </p>
+                <p className="mono-font mt-0.5 flex items-center gap-1.5" style={{ fontSize: 9, color: 'var(--film-text-dim)' }}>
+                  {year || '—'} {isTv ? <Tv size={10} /> : <Film size={10} />} {isTv ? 'TV' : 'Movie'}
+                </p>
+              </button>
+            );
+          })}
+        </div>
+      )}
+
+      {(selectedTitle || config.tmdbId) && (
+        <p className="body-font" style={{ fontSize: 10, color: 'var(--film-text-dim)' }}>
+          Selected: {selectedTitle || `TMDB #${config.tmdbId}`}
+        </p>
+      )}
+
+      {error && (
+        <p className="body-font" style={{ fontSize: 10, color: '#fca5a5' }}>
+          {error}
+        </p>
+      )}
+    </div>
+  );
+};
+
+export default MediaPicker;

src/components/builder/components/simple/SimpleModePanel.tsx

@@ -0,0 +1,87 @@
+import React from 'react';
+import type { PosterConfig, PresetType, RatingType } from '../../types';
+import { ALL_BADGES } from '../../types';
+import SidebarLayout from '../SidebarLayout';
+import { Section, SelectBox, ToggleRow } from '../ui';
+import MediaPicker from './MediaPicker';
+import { SIMPLE_BADGE_OPTIONS } from './constants';
+
+interface Props {
+  config: PosterConfig;
+  setConfig: React.Dispatch<React.SetStateAction<PosterConfig>>;
+}
+
+const PRESET_OPTIONS: { id: PresetType; label: string }[] = [
+  { id: 'custom', label: 'Custom (Keep current)' },
+  { id: 'bl', label: 'Bottom Left' },
+  { id: 'br', label: 'Bottom Right' },
+  { id: 'tl', label: 'Top Left' },
+  { id: 'tr', label: 'Top Right' },
+  { id: 'bc', label: 'Bottom Center' },
+  { id: 'tc', label: 'Top Center' },
+];
+
+const SimpleModePanel: React.FC<Props> = ({ config, setConfig }) => {
+  const update = <K extends keyof PosterConfig>(key: K, value: PosterConfig[K]) => {
+    setConfig((prev) => ({ ...prev, [key]: value }));
+  };
+
+  const toggleBadge = (id: RatingType, enabled: boolean) => {
+    setConfig((prev) => {
+      if (enabled && !prev.ratings.includes(id)) {
+        return { ...prev, ratings: [...prev.ratings, id] };
+      }
+      if (!enabled) {
+        return { ...prev, ratings: prev.ratings.filter((rating) => rating !== id) };
+      }
+      return prev;
+    });
+  };
+
+  return (
+    <SidebarLayout side="left" bodyClassName="px-2 pt-2 pb-8">
+      <Section title="Media" sectionId="simple-media" inset="compact">
+        <MediaPicker config={config} setConfig={setConfig} />
+      </Section>
+
+      <Section title="Theme" sectionId="simple-theme" inset="compact">
+        <SelectBox
+          value={config.theme}
+          onChange={(value) => update('theme', value as PosterConfig['theme'])}
+          options={[
+            { id: 'glass', label: 'Glass' },
+            { id: 'solid', label: 'Solid' },
+          ]}
+        />
+      </Section>
+
+      <Section title="Layout Preset" sectionId="simple-preset" inset="compact">
+        <SelectBox
+          value={config.preset}
+          onChange={(value) => {
+            const nextPreset = value as PresetType;
+            update('preset', nextPreset);
+            if (nextPreset !== 'custom') update('layout', 'row');
+          }}
+          options={PRESET_OPTIONS}
+        />
+      </Section>
+
+      <Section title="Badges" sectionId="simple-badges" inset="compact">
+        {SIMPLE_BADGE_OPTIONS.map((id) => {
+          const label = ALL_BADGES.find((badge) => badge.id === id)?.label ?? id;
+          return (
+            <ToggleRow
+              key={id}
+              label={label}
+              checked={config.ratings.includes(id)}
+              onChange={(enabled) => toggleBadge(id, enabled)}
+            />
+          );
+        })}
+      </Section>
+    </SidebarLayout>
+  );
+};
+
+export default SimpleModePanel;