Polish onboarding and export guidance

Author: dicnunz

README.md

@@ -6,6 +6,8 @@ PixelMelt is a desktop-first, local-only web app that turns a single image into
 
 The entire product runs client-side. There is no backend, no auth, no database, and no paid API dependency.
 
+Best results come from faces, masks, flowers, logos, and other bold silhouettes with clear contrast and some negative space around the subject.
+
 ## Highlights
 
 - Upload one image and convert it into a 168x168 material map.
@@ -47,6 +49,15 @@ npm run preview
 npm run check
 ```
 
+## First Run In 20 Seconds
+
+1. Launch the app. `Molten Echo` loads automatically.
+2. Click `Flood` or `Burn` to see how the same source rebuilds into a different scene.
+3. Drag on the stage with `Push`, then switch to `Spark` and click into the hot areas.
+4. Hit `Export 8s WebM` after you like the motion.
+
+If the export controls are disabled, wait for the stage to finish loading and show the first live frame.
+
 ## Demo Flow
 
 1. Launch the app. `Molten Echo` loads automatically.
@@ -57,6 +68,13 @@ npm run check
 6. Upload your own image with the drop zone or file picker.
 7. Click `Record 8s clip` to export a WebM of the live simulation.
 
+## Source Image Tips
+
+- High-contrast subjects read best at `168x168`.
+- Clear silhouettes usually produce the most dramatic melt and burn passes.
+- Transparent or simple backgrounds convert more cleanly than busy photos.
+- Portraits, icons, flowers, masks, and graphic shapes are the sweet spot.
+
 ## How It Works
 
 ### 1. Image Conversion
@@ -97,7 +115,7 @@ The canvas renderer in [`src/components/CanvasStage.tsx`](./src/components/Canva
 
 ### 4. Clip Export
 
-PixelMelt records directly from the display canvas using `canvas.captureStream()` and `MediaRecorder`. Export is intentionally fixed to 8 seconds so the output is lightweight and easy to share.
+PixelMelt records directly from the display canvas using `canvas.captureStream()` and `MediaRecorder`. Export is intentionally fixed to 8 seconds so the output is lightweight and easy to share, and the downloaded file name includes the active source and preset.
 
 ## Project Structure
 

docs/pixelmelt-demo.png

@@ -39,6 +39,20 @@ function formatCompactCount(value: number): string {
   return new Intl.NumberFormat('en-US', { notation: 'compact', maximumFractionDigits: 1 }).format(value)
 }
 
+function formatUiLabel(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1)
+}
+
+function slugifyFilenamePart(value: string): string {
+  const normalized = value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+  return normalized || 'untitled'
+}
+
 export const CanvasStage = forwardRef<CanvasStageHandle, CanvasStageProps>(function CanvasStage(
   { controller, activeTool, activePreset, brushSize, brushIntensity, sourceLabel, paused, sceneStatus },
   ref,
@@ -194,7 +208,7 @@ export const CanvasStage = forwardRef<CanvasStageHandle, CanvasStageProps>(funct
 
   async function recordClip(): Promise<void> {
     const canvas = displayCanvasRef.current
-    if (!canvas) {
+    if (!canvas || sceneStatus !== 'ready' || !latestPayloadRef.current) {
       return
     }
 
@@ -229,7 +243,8 @@ export const CanvasStage = forwardRef<CanvasStageHandle, CanvasStageProps>(funct
       })
 
       const timestamp = new Date().toISOString().replaceAll(':', '-')
-      downloadBlob(blob, `pixelmelt-${activePreset}-${timestamp}.webm`)
+      const sourceSlug = slugifyFilenamePart(sourceLabel)
+      downloadBlob(blob, `pixelmelt-${sourceSlug}-${activePreset}-${timestamp}.webm`)
 
       usePixelMeltStore.getState().setRecording({
         status: 'done',
@@ -259,6 +274,7 @@ export const CanvasStage = forwardRef<CanvasStageHandle, CanvasStageProps>(funct
 
   const metrics = hudPayload?.metrics
   const hasFrame = Boolean(hudPayload)
+  const exportDisabled = sceneStatus !== 'ready' || !hasFrame || recording.status === 'recording' || recording.status === 'saving'
 
   return (
     <section className="pm-panel relative flex min-h-[calc(100vh-3rem)] flex-1 flex-col overflow-hidden rounded-[32px]">
@@ -268,19 +284,39 @@ export const CanvasStage = forwardRef<CanvasStageHandle, CanvasStageProps>(funct
           <div className="font-mono text-[0.72rem] uppercase tracking-[0.24em] text-white/45">Stage</div>
           <div className="mt-1 text-lg font-semibold text-white">{sourceLabel}</div>
           <div className="text-sm text-[var(--pm-text-muted)]">
-            {activePreset} preset • {activeTool} tool • {paused ? 'paused' : 'live worker sim'}
+            {formatUiLabel(activePreset)} scene • {formatUiLabel(activeTool)} brush • {paused ? 'paused' : 'live worker sim'}
           </div>
         </div>
         <button
           type="button"
           onClick={() => void recordClip()}
-          className="rounded-full border border-[var(--pm-warm)] bg-[rgba(255,148,71,0.12)] px-4 py-2 text-sm font-semibold text-white transition hover:bg-[rgba(255,148,71,0.2)]"
+          disabled={exportDisabled}
+          className={cn(
+            'rounded-full border px-4 py-2 text-sm font-semibold transition',
+            exportDisabled
+              ? 'cursor-not-allowed border-white/10 bg-white/[0.03] text-white/45'
+              : 'border-[var(--pm-warm)] bg-[rgba(255,148,71,0.12)] text-white hover:bg-[rgba(255,148,71,0.2)]',
+          )}
         >
           Export 8s WebM
         </button>
       </div>
 
       <div className="relative flex flex-1 items-center justify-center px-6 py-6">
+        {sceneStatus === 'ready' && (
+          <div className="pointer-events-none absolute left-6 top-6 hidden max-w-sm xl:block">
+            <div className="rounded-[24px] border border-white/8 bg-[rgba(7,11,19,0.72)] px-4 py-3 shadow-[0_18px_40px_rgba(0,0,0,0.22)] backdrop-blur">
+              <div className="font-mono text-[0.68rem] uppercase tracking-[0.24em] text-white/40">Quick pass</div>
+              <p className="mt-2 text-sm leading-6 text-white/85">
+                Pick a bold source, rebuild with a preset, then drag with Push or click with Spark before exporting the exact frame state you like.
+              </p>
+              <p className="mt-2 text-xs leading-5 text-[var(--pm-text-muted)]">
+                Best with faces, masks, flowers, logos, and silhouettes that have clear contrast and some empty space around them.
+              </p>
+            </div>
+          </div>
+        )}
+
         <div className="relative flex aspect-square w-full max-w-[880px] items-center justify-center rounded-[30px] border border-white/10 bg-[rgba(2,5,11,0.72)] p-3 shadow-[inset_0_1px_0_rgba(255,255,255,0.04)]">
           <canvas
             ref={displayCanvasRef}

src/components/CanvasStage.tsx

@@ -51,6 +51,8 @@ export function ControlPanel({
 }: ControlPanelProps) {
   const inputRef = useRef<HTMLInputElement>(null)
   const [isDragging, setIsDragging] = useState(false)
+  const activeDemo = demos.find((demo) => demo.id === selectedDemoId) ?? null
+  const usingCustomSource = activeDemo === null
 
   const recordLabel =
     recording.status === 'recording'
@@ -60,6 +62,8 @@ export function ControlPanel({
         : 'Record 8s clip'
 
   const interactionDisabled = sceneStatus === 'booting' || sceneStatus === 'loading'
+  const runControlsDisabled = sceneStatus !== 'ready'
+  const recordDisabled = runControlsDisabled || recording.status === 'recording' || recording.status === 'saving'
 
   return (
     <aside className="pm-panel pm-scrollbar flex h-full min-h-[calc(100vh-3rem)] flex-col overflow-y-auto rounded-[28px] p-6 text-sm text-white/90">
@@ -80,13 +84,22 @@ export function ControlPanel({
         <div className="flex items-center justify-between">
           <div>
             <h2 className="text-base font-semibold text-white">Input</h2>
-            <p className="text-xs text-[var(--pm-text-muted)]">Upload one image or start from a seeded demo scene.</p>
+            <p className="text-xs text-[var(--pm-text-muted)]">Upload once, rebuild with presets, then sculpt and export from the same source.</p>
           </div>
           <span className="rounded-full border border-white/10 px-2.5 py-1 font-mono text-[0.7rem] uppercase tracking-[0.22em] text-white/55">
             {sceneStatus}
           </span>
         </div>
 
+        <div className="grid grid-cols-3 gap-2 text-[0.68rem] font-medium uppercase tracking-[0.18em] text-white/60">
+          {['pick source', 'rebuild preset', 'export clip'].map((step, index) => (
+            <div key={step} className="rounded-[18px] border border-white/8 bg-black/10 px-3 py-2">
+              <div className="font-mono text-[0.62rem] text-white/30">0{index + 1}</div>
+              <div className="mt-1 leading-4">{step}</div>
+            </div>
+          ))}
+        </div>
+
         <button
           type="button"
           onClick={() => inputRef.current?.click()}
@@ -144,10 +157,23 @@ export function ControlPanel({
           }}
         />
 
+        <div className="rounded-[22px] border border-white/8 bg-black/10 p-3">
+          <div className="flex items-center justify-between text-[0.72rem] uppercase tracking-[0.2em] text-white/45">
+            <span>Current source</span>
+            <span className="font-mono">{usingCustomSource ? 'upload' : 'demo'}</span>
+          </div>
+          <div className="mt-2 text-sm font-semibold text-white">{sourceLabel}</div>
+          <p className="mt-1 text-xs leading-5 text-[var(--pm-text-muted)]">
+            {usingCustomSource
+              ? 'Using your upload. Presets will keep rebuilding from this image until you swap the source.'
+              : activeDemo.description}
+          </p>
+        </div>
+
         <div className="space-y-2">
           <div className="flex items-center justify-between">
             <span className="text-xs uppercase tracking-[0.2em] text-white/45">Seeded demos</span>
-            <span className="font-mono text-[0.72rem] text-white/45">{sourceLabel}</span>
+            <span className="font-mono text-[0.72rem] text-white/45">instant start</span>
           </div>
           <div className="grid grid-cols-3 gap-2">
             {demos.map((demo) => (
@@ -170,7 +196,7 @@ export function ControlPanel({
             ))}
           </div>
           <p className="text-xs leading-5 text-[var(--pm-text-muted)]">
-            {demos.find((demo) => demo.id === selectedDemoId)?.description}
+            Faces, masks, logos, flowers, and bold silhouettes with clean negative space usually produce the strongest melts.
           </p>
         </div>
 
@@ -273,31 +299,41 @@ export function ControlPanel({
       <section className="mb-6 rounded-3xl border border-white/8 bg-white/[0.03] p-4">
         <div className="mb-3">
           <h2 className="text-base font-semibold text-white">Run</h2>
-          <p className="text-xs text-[var(--pm-text-muted)]">Pause to inspect, reset to re-seed, export straight from the canvas.</p>
+          <p className="text-xs text-[var(--pm-text-muted)]">Pause to inspect, reset to re-seed, then export the exact stage you see as an 8-second WebM.</p>
         </div>
         <div className="grid grid-cols-2 gap-2">
           <button
             type="button"
             onClick={onPauseToggle}
-            className="rounded-[18px] border border-white/12 bg-white/[0.05] px-4 py-3 font-semibold text-white transition hover:border-white/22 hover:bg-white/[0.08]"
+            disabled={runControlsDisabled}
+            className={cn(
+              'rounded-[18px] border border-white/12 bg-white/[0.05] px-4 py-3 font-semibold text-white transition',
+              runControlsDisabled ? 'cursor-not-allowed opacity-50' : 'hover:border-white/22 hover:bg-white/[0.08]',
+            )}
           >
             {paused ? 'Resume sim' : 'Pause sim'}
           </button>
           <button
             type="button"
             onClick={onReset}
-            className="rounded-[18px] border border-white/12 bg-white/[0.05] px-4 py-3 font-semibold text-white transition hover:border-white/22 hover:bg-white/[0.08]"
+            disabled={runControlsDisabled}
+            className={cn(
+              'rounded-[18px] border border-white/12 bg-white/[0.05] px-4 py-3 font-semibold text-white transition',
+              runControlsDisabled ? 'cursor-not-allowed opacity-50' : 'hover:border-white/22 hover:bg-white/[0.08]',
+            )}
           >
             Reset scene
           </button>
           <button
             type="button"
             onClick={onRecord}
-            disabled={recording.status === 'recording' || recording.status === 'saving'}
+            disabled={recordDisabled}
             className={cn(
               'col-span-2 rounded-[18px] border px-4 py-3 font-semibold transition',
-              recording.status === 'recording' || recording.status === 'saving'
-                ? 'cursor-progress border-amber-300/20 bg-amber-300/10 text-amber-100'
+              recordDisabled
+                ? recording.status === 'recording' || recording.status === 'saving'
+                  ? 'cursor-progress border-amber-300/20 bg-amber-300/10 text-amber-100'
+                  : 'cursor-not-allowed border-white/10 bg-white/[0.03] text-white/45'
                 : 'border-[var(--pm-warm)] bg-[rgba(255,148,71,0.12)] text-white hover:bg-[rgba(255,148,71,0.2)]',
             )}
           >