fix: improve caption handling and refresh docs

apartsin · apartsin · commit 6ca4f9d7f00d · 2026-02-25T21:10:14.000+02:00
diff --git a/README.md b/README.md
@@ -20,7 +20,8 @@ Web2Comics is a Chrome extension that:
 5. Turn on `Developer mode` (top-right).
 6. Click `Load unpacked`.
 7. Select the extracted `Web2Comics` folder (the folder containing `manifest.json`).
-8. (Optional) Pin the extension from Chrome’s extensions menu.
+8. Web2Comics will open the Options page on first install so you can configure providers.
+9. (Optional) Pin the extension from Chrome’s extensions menu (Chrome does not allow extensions to pin themselves automatically).
 
 ### Option B: Clone the repo (developer workflow)
 
@@ -115,7 +116,7 @@ For step-by-step key/token instructions, see:
 2. Click the Web2Comics extension icon.
 3. Click `Create Comic`.
 4. Choose provider/style (advanced settings optional).
-5. Click `Generate`.
+5. If no providers are configured yet, use `Configure Model Providers` in the popup (or the Options page opened on install), then return and click `Generate`.
 6. Watch live progress in popup/sidepanel.
 7. Review the comic in the side panel.
 8. Click `Download` to export a single comic sheet PNG.
@@ -171,6 +172,9 @@ HUGGINGFACE_INFERENCE_API_TOKEN=...
 - Provider not visible in popup:
   - Configure credentials in `Options -> Providers`
   - Click `Validate`
+- OpenAI key validates but model test fails:
+  - The key may belong to a different OpenAI project or have different model access/billing
+  - Re-paste the key and use `Test Text Model` / `Test Image Model`
 - Gemini free tier says quota/limit `0`:
   - Check AI Studio project eligibility/region and active limits
 - Generation fails on one provider:
diff --git a/docs/user-manual.html b/docs/user-manual.html
@@ -180,7 +180,7 @@ <h1>Web2Comics User Manual</h1>
 
       <section>
         <h2 id="popup-overview">Popup / Generator Wizard Overview</h2>
-        <p>The popup is the main entry point from the extension toolbar icon. It contains onboarding, the action launcher, the comic generator wizard, progress view, and a lightweight history modal.</p>
+        <p>The popup is the main entry point from the extension toolbar icon. It contains the action launcher, the comic generator wizard, progress view, and a lightweight history modal.</p>
         <div class="grid-2">
           <div class="card">
             <h3>Launcher</h3>
@@ -217,8 +217,8 @@ <h3>Step 2: Configure Comic</h3>
           <tr><td>Advanced Options</td><td>Shows detail level, style presets, and custom style creation/selection.</td></tr>
           <tr><td>Detail</td><td>Controls storyboard richness (low/medium/high).</td></tr>
           <tr><td>Style</td><td>Preset art direction or a custom saved style.</td></tr>
-          <tr><td>Custom Style (One-off)</td><td>Enter a temporary style name and description for the current generation.</td></tr>
-          <tr><td>Create New Style…</td><td>Saves a reusable custom style to extension storage for future sessions.</td></tr>
+          <tr><td>Custom (One-off)</td><td>Uses current custom-style defaults without creating a saved style entry.</td></tr>
+          <tr><td>Create New Style…</td><td>Opens a modal to enter style name + description, saves it, and adds it to the style list for future sessions.</td></tr>
         </table>
 
         <h3>Readiness and Generate</h3>
@@ -231,7 +231,7 @@ <h3>Readiness and Generate</h3>
 
       <section>
         <h2 id="popup-progress">Popup Progress View</h2>
-        <p>After generation starts, Web2Comics can automatically open the side panel while the popup shows progress.</p>
+        <p>After generation starts, Web2Comics can attempt to open the side panel while the popup shows progress (Chrome may block auto-open unless it is triggered by a direct user gesture).</p>
         <ul>
           <li><strong>Status text</strong>: current phase (storyboard or image rendering).</li>
           <li><strong>Progress bar</strong>: panel-level completion progress.</li>
@@ -246,6 +246,7 @@ <h2 id="popup-history">Popup History</h2>
         <p>The popup history modal is a quick-access list of previously generated comics.</p>
         <ul>
           <li>Shows recent items with thumbnails and source metadata.</li>
+          <li>Each item has an individual <strong>Delete</strong> action (with confirmation).</li>
           <li>Useful when you want to reopen a comic quickly without opening the side panel browser.</li>
           <li>The full history browsing experience is available in the side panel <em>History Browser</em>.</li>
         </ul>
@@ -265,15 +266,16 @@ <h3>Generation Defaults</h3>
         <ul>
           <li><strong>Default Panel Count</strong>: starting value used in popup.</li>
           <li><strong>Detail Level</strong>: default storyboard detail level.</li>
-          <li><strong>Default Style</strong>: default art style preset for new generations.</li>
-          <li><strong>Custom Style Description</strong>: default custom style description when <code>Custom</code> is selected.</li>
+          <li><strong>Default Style</strong>: default art style preset or saved custom style for new generations.</li>
+          <li><strong>Custom Style Name / Description</strong>: shown when creating a new reusable custom style entry from Options.</li>
           <li><strong>Caption Length</strong>: preferred caption length for generated panels.</li>
         </ul>
+        <p>If you choose <code>Custom...</code> in <strong>Default Style</strong>, the inline custom-style editor appears with a <strong>Create Style</strong> button. After creating a style, it is selected in the list and the inline editor is hidden again.</p>
         <p><strong>Free-tier-first default setup:</strong> Web2Comics starts with <strong>Google Gemini</strong> selected for both text and image generation (when eligible/configured), plus a low-cost default generation profile (fewer panels and lower detail) to maximize the chance that a first run succeeds on free-tier limits.</p>
 
         <h3>Behavior</h3>
         <ul>
-          <li><strong>Automatically open comic viewer after generation</strong>: opens side panel on completion (and optionally progress start behavior may also open it).</li>
+          <li><strong>Automatically open comic viewer after generation</strong>: attempts to open the side panel on completion (Chrome may block auto-open without a user gesture).</li>
           <li><strong>Enable character consistency mode</strong>: provider hint to keep characters visually consistent across panels.</li>
           <li><strong>Debug flag</strong>: shows detailed provider/panel errors and enables richer local debugging behavior.</li>
         </ul>
@@ -306,7 +308,7 @@ <h3>Provider Cards</h3>
 
         <h3>Validation</h3>
         <ul>
-          <li>Use each provider card’s <strong>Validate</strong> button after entering credentials.</li>
+          <li>Use each provider card’s <strong>Validate</strong> button after entering credentials (buttons show a spinner while waiting).</li>
           <li>Web2Comics persists provider validation state in local storage and uses it to gate popup provider visibility/readiness.</li>
           <li>If a selected provider fails due to quota/budget/billing limits during generation, Web2Comics can automatically fall back to other configured providers (free-tier-first) for text and/or image generation.</li>
           <li>Google Gemini is the default first-run provider because it can cover both text and image generation with one key, but free-tier availability depends on Google account/project eligibility and region.</li>
@@ -324,10 +326,11 @@ <h3>OpenAI Model / Speed Controls</h3>
 
       <section>
         <h2 id="options-prompts">Options: Prompts</h2>
-        <p>Prompt templates let you customize storyboard and image prompts for supported providers.</p>
+        <p>Prompt templates let you customize storyboard and image prompts per provider scope.</p>
         <h3>Current support</h3>
         <ul>
-          <li>Provider scopes: <strong>OpenAI</strong> and <strong>Google Gemini</strong>.</li>
+          <li>Provider scopes in the UI: <strong>OpenAI</strong>, <strong>Google Gemini</strong>, <strong>Cloudflare Workers AI</strong>, <strong>OpenRouter</strong>, and <strong>Hugging Face</strong>.</li>
+          <li>Runtime template consumption (current build): <strong>OpenAI</strong> and <strong>Google Gemini</strong>.</li>
           <li>Template types: <strong>Storyboard</strong> and <strong>Image</strong>.</li>
         </ul>
         <h3>Validation behavior</h3>
@@ -391,10 +394,10 @@ <h3>Display modes</h3>
           <li><strong>Panel View</strong>: grid/list view of all panels.</li>
         </ul>
         <h3>Layout Presets</h3>
-        <p>Phase-1 layout presets visually restyle existing strip/grid/carousel engines (for example <em>Classic Strip</em>, <em>Cinema Carousel</em>, <em>Contact Sheet</em>).</p>
+        <p>Web2Comics includes a broad layout preset library (for example <em>Single panel</em>, <em>4-panel grid</em>, <em>Classic comic page</em>, <em>Manga page</em>, <em>Webtoon scroll</em>, <em>Masonry</em>, <em>Guided path</em>, and <em>Carousel</em>). In the current implementation, presets are fully functional layout/view variants built on the side panel render engines and preset-specific styling rules.</p>
         <h3>Download Export</h3>
         <ul>
-          <li>Exports a single composite PNG contact sheet image.</li>
+          <li>Exports a single composite PNG image using the currently selected layout preset.</li>
           <li>Includes source title, source URL, source short-name (for example <code>cnn</code>), panel thumbnails, and captions.</li>
         </ul>
         <h3>Policy handling indicators</h3>
@@ -411,7 +414,7 @@ <h2 id="sidepanel-generation-view">Side Panel: Generation View</h2>
           <li>Shows a comic-like placeholder shell during generation.</li>
           <li>Uses live panel statuses: <code>Pending</code>, <code>Sent</code>, <code>Receiving</code>, <code>Rendering</code>, <code>Completed</code>, <code>Error</code>.</li>
           <li>Matches the currently selected view mode/layout preset for continuity.</li>
-          <li><strong>Cancel</strong> stops the active job.</li>
+          <li><strong>Cancel</strong> stops the active job and shows a <code>Canceling...</code> state while cancellation is being processed.</li>
         </ul>
       </section>
 
diff --git a/sidepanel/sidepanel.js b/sidepanel/sidepanel.js
@@ -116,7 +116,65 @@ class ComicViewer {
     return labels[String(providerId || '')] || String(providerId || 'provider');
   }
 
-  getPanelCaptionText(panel, index) {
+  isCaptionPlaceholderPanel(panel) {
+    if (!panel) return true;
+    if (typeof panel !== 'object') return false;
+    const keys = Object.keys(panel);
+    if (!keys.length) return true;
+    // Placeholder panel objects can contain runtime status only while the storyboard fills in.
+    if (keys.length === 1 && keys[0] === 'runtime_status') return true;
+    return false;
+  }
+
+  looksLikeImagePromptText(text) {
+    const s = String(text || '').trim();
+    if (!s) return false;
+    const lower = s.toLowerCase();
+    if (s.length > 220) return true;
+    const promptPhrases = [
+      'comic panel illustration',
+      'illustration of',
+      'digital art',
+      'cinematic lighting',
+      'highly detailed',
+      'camera angle',
+      'art style',
+      'dramatic lighting',
+      'ultra detailed'
+    ];
+    if (promptPhrases.some((p) => lower.includes(p))) return true;
+    const commaCount = (s.match(/,/g) || []).length;
+    if (commaCount >= 6) return true;
+    return false;
+  }
+
+  getStoryLikeFallbackCaption(panel) {
+    if (!panel || typeof panel !== 'object') return '';
+    const candidates = [
+      panel.beat_summary,
+      panel.summary,
+      panel.beat,
+      panel.narration,
+      panel.description,
+      panel.title,
+      panel.text,
+      panel.text_content,
+      panel.caption_text,
+      panel.dialogue
+    ];
+    for (const candidate of candidates) {
+      const normalized = this.normalizeCaptionValue(candidate);
+      if (normalized && !this.looksLikeImagePromptText(normalized)) return normalized;
+    }
+    return '';
+  }
+
+  getPanelCaptionText(panel, index, options = {}) {
+    const suppressMissingLog = !!options.suppressMissingLog;
+    const fallbackLabel = options.fallbackLabel || ('Panel ' + ((Number(index) || 0) + 1));
+    if (this.isCaptionPlaceholderPanel(panel)) {
+      return fallbackLabel;
+    }
     var caption =
       (panel && (
         panel.caption ||
@@ -131,9 +189,21 @@ class ComicViewer {
         panel.dialogue
       )) || '';
     caption = this.normalizeCaptionValue(caption);
-    if (caption) return caption;
-    this.logMissingCaption(panel, index);
-    return 'Panel ' + ((Number(index) || 0) + 1);
+    if (caption) {
+      const imagePrompt = this.normalizeCaptionValue(
+        panel && (panel.image_prompt || panel.prompt || panel.imagePrompt || panel.visual_prompt || panel.scene_prompt)
+      );
+      if (this.looksLikeImagePromptText(caption) || (imagePrompt && caption === imagePrompt)) {
+        const storyLike = this.getStoryLikeFallbackCaption(panel);
+        if (storyLike && storyLike !== caption) {
+          this.logPromptLikeCaptionSubstitution(panel, index, caption, storyLike);
+          return storyLike;
+        }
+      }
+      return caption;
+    }
+    if (!suppressMissingLog) this.logMissingCaption(panel, index);
+    return fallbackLabel;
   }
 
   normalizeCaptionValue(value) {
@@ -185,6 +255,22 @@ class ComicViewer {
     } catch (_) {}
   }
 
+  logPromptLikeCaptionSubstitution(panel, index, originalCaption, replacementCaption) {
+    try {
+      const sourceUrl = String(this.currentComic?.source?.url || '');
+      const panelId = String(panel?.panel_id || index || 0);
+      const key = `${sourceUrl}|${panelId}|prompt-like`;
+      if (this.missingCaptionNoticeKeys.has(key)) return;
+      this.missingCaptionNoticeKeys.add(key);
+      void this.appendDebugLog('caption.prompt_like_substituted', {
+        panelIndex: Number(index) || 0,
+        panelId: panel?.panel_id || null,
+        originalPreview: String(originalCaption || '').slice(0, 200),
+        replacementPreview: String(replacementCaption || '').slice(0, 200)
+      });
+    } catch (_) {}
+  }
+
   async loadPrefs() {
     const { sidepanelPrefs } = await chrome.storage.local.get('sidepanelPrefs');
     const rawPreset = sidepanelPrefs?.layoutPreset;
@@ -788,7 +874,10 @@ class ComicViewer {
           : '';
       const isCurrent = displayStatus === 'sent' || displayStatus === 'receiving' || displayStatus === 'rendering';
 
-      const safeCaption = this.escapeHtml(this.getPanelCaptionText(panel, index));
+      const safeCaption = this.escapeHtml(this.getPanelCaptionText(panel, index, {
+        suppressMissingLog: true,
+        fallbackLabel: 'Panel ' + (index + 1)
+      }));
       return `
         <div class="gen-panel ${isCurrent ? 'is-current' : ''}">
           <div class="gen-panel-thumb">
diff --git a/tests/integration/sidepanel-page.test.js b/tests/integration/sidepanel-page.test.js
@@ -878,6 +878,46 @@ describe('Sidepanel Page UX', () => {
     expect(String(carouselCaption.textContent)).not.toContain('[object Object]');
   });
 
+  it('prefers story-like caption text when caption looks like an image prompt', async () => {
+    const item = makeHistoryItem(1);
+    item.storyboard.panels = [
+      {
+        panel_id: 'panel_prompty',
+        caption: 'Comic panel illustration of: A dramatic newsroom scene, cinematic lighting, digital art, highly detailed, camera angle from above, ultra detailed editorial style',
+        beat_summary: 'Newsroom reacts to a major breaking update.',
+        image_prompt: 'Comic panel illustration of: A dramatic newsroom scene, cinematic lighting, digital art, highly detailed, camera angle from above, ultra detailed editorial style',
+        artifacts: {
+          image_blob_ref:
+            'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMB/axlF8UAAAAASUVORK5CYII='
+        }
+      }
+    ];
+    const setCalls = [];
+    chrome.storage.local.set.mockImplementation(async (payload) => {
+      setCalls.push(payload);
+    });
+    chrome.storage.local.get.mockImplementation(async (key) => {
+      if (key === 'currentJob') return { currentJob: { status: 'completed', storyboard: item.storyboard } };
+      if (key === 'history') return { history: [item] };
+      if (key === 'sidepanelPrefs') return { sidepanelPrefs: {} };
+      if (key === 'debugLogs') return { debugLogs: [] };
+      return {};
+    });
+
+    await import('../../sidepanel/sidepanel.js');
+    document.dispatchEvent(new Event('DOMContentLoaded'));
+    await flush();
+    await flush();
+
+    const panelCaption = document.querySelector('.comic-strip .panel-caption');
+    expect(String(panelCaption.textContent)).toContain('Newsroom reacts to a major breaking update.');
+    expect(String(panelCaption.textContent)).not.toContain('cinematic lighting');
+
+    const debugSet = setCalls.find((p) => Array.isArray(p.debugLogs));
+    expect(debugSet).toBeTruthy();
+    expect(debugSet.debugLogs.some((e) => e.event === 'caption.prompt_like_substituted')).toBe(true);
+  });
+
   it('logs caption.missing when a panel has no usable caption fields', async () => {
     const item = makeHistoryItem(1);
     item.storyboard.panels = [
@@ -913,6 +953,50 @@ describe('Sidepanel Page UX', () => {
     expect(last.data.panelId).toBe('panel_x');
   });
 
+  it('does not log caption.missing for expected generation placeholders', async () => {
+    const setCalls = [];
+    chrome.storage.local.set.mockImplementation(async (payload) => {
+      setCalls.push(payload);
+    });
+    chrome.storage.local.get.mockImplementation(async (key) => {
+      if (key === 'currentJob') {
+        return {
+          currentJob: {
+            status: 'generating_images',
+            settings: { panel_count: 6 },
+            storyboard: {
+              source: { url: 'https://example.com/article', title: 'Example' },
+              panels: Array.from({ length: 5 }, (_, i) => ({
+                caption: 'Panel caption ' + (i + 1),
+                runtime_status: i < 2 ? 'completed' : 'rendering',
+                artifacts: i < 2 ? {
+                  image_blob_ref:
+                    'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMB/axlF8UAAAAASUVORK5CYII='
+                } : {}
+              }))
+            }
+          }
+        };
+      }
+      if (key === 'history') return { history: [] };
+      if (key === 'sidepanelPrefs') return { sidepanelPrefs: {} };
+      if (key === 'debugLogs') return { debugLogs: [] };
+      return {};
+    });
+
+    await import('../../sidepanel/sidepanel.js');
+    document.dispatchEvent(new Event('DOMContentLoaded'));
+    await flush();
+    await flush();
+
+    const captions = Array.from(document.querySelectorAll('#gen-panels .gen-panel-caption')).map((el) => String(el.textContent || ''));
+    expect(captions).toContain('Panel 6');
+
+    const debugSets = setCalls.filter((p) => Array.isArray(p.debugLogs));
+    const captionMissingLogs = debugSets.flatMap((p) => p.debugLogs).filter((e) => e && e.event === 'caption.missing');
+    expect(captionMissingLogs.length).toBe(0);
+  });
+
   it('escapes history/comic text and sanitizes unsafe source links', async () => {
     const malicious = makeHistoryItem(1);
     malicious.id = 'x"><svg onload=alert(1)>';
