feat: add user instructions to viewer popup

2026-08-31 03:26:50 +00:00
1 parent c366f0b8c4
commit 97abaf42d9
@@ -0,0 +1,25 @@
+# Instructions UI audit
+
+## Scope
+This audit covers the VidPlex popup instructions banner added in `src/viewer/index.html`, `src/viewer/index.css`, and `src/viewer/index.js`.
+
+## What the UI now explains
+- How to scan the current page for videos
+- How to review clickable results
+- How to open the 2x2 viewer
+- How to clear and rescan
+- A caveat that browser pages, extension pages, and restricted frames may hide videos
+
+## Accessibility checks
+- The instructions section uses `role="region"` and an accessible label
+- The collapse toggle is wired with `aria-expanded` and `aria-controls`
+- The body is hidden with the `hidden` attribute when collapsed
+
+## UX notes
+- The panel is visible on mount so first-time users see the steps immediately
+- The toggle label changes between “Hide instructions” and “Show instructions”
+- The copy intentionally stays short so the popup remains readable in a narrow extension window
+
+## Validation
+- Covered by `__tests__/instructions_ui.test.mjs`
+- Verified alongside the existing build/test flow in the parent implementation task
@@ -0,0 +1,17 @@
+# Instructions UI copy
+
+## Banner copy
+Quick start
+How to use VidPlex
+
+## Steps
+1. Scan videos — Click Find Videos to search the current browser window for videos.
+2. Review the list — Check the popup list; each found video URL is clickable.
+3. Open the viewer — Click Open Viewer to open the 2x2 grid player in a new window.
+4. Reset and rescan — Click Clear to erase results and scan again.
+
+## Warning copy
+Warning: Browser pages, extension pages, and restricted frames can hide videos, so results may be incomplete.
+
+## Learn-more copy
+Learn more tooltip: Read the VidPlex README and audit notes.
@@ -0,0 +1,50 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-label="VidPlex popup instructions preview">
+  <defs>
+    <style>
+      .bg { fill: #ffffff; }
+      .panel { fill: #f8fafc; stroke: #e2e8f0; stroke-width: 1; }
+      .text { fill: #1a1a2e; font-family: -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif; }
+      .muted { fill: #64748b; }
+      .accent { fill: #4361ee; }
+      .warn { fill: #7c3aed; }
+      .small { font-size: 12px; }
+      .tiny { font-size: 11px; letter-spacing: .08em; font-weight: 700; }
+      .title { font-size: 18px; font-weight: 600; }
+      .h2 { font-size: 14px; font-weight: 600; }
+      .step-title { font-size: 12px; font-weight: 600; }
+      .body { font-size: 12px; fill: #475569; }
+      .button-text { font-size: 12px; fill: #4361ee; }
+      .primary-text { fill: #ffffff; font-size: 14px; }
+    </style>
+  </defs>
+
+  <rect class="bg" x="0" y="0" width="1280" height="720"/>
+  <text class="text title" x="18" y="30">VidPlex</text>
+
+  <rect class="panel" x="17" y="50" width="1264" height="276" rx="10"/>
+  <text class="text muted tiny" x="30" y="72">QUICK START</text>
+  <text class="text h2" x="30" y="90">How to use VidPlex</text>
+
+  <rect x="1150" y="62" width="104" height="28" rx="8" fill="#ffffff" stroke="#e2e8f0"/>
+  <text class="button-text" x="1165" y="80">Hide instructions</text>
+
+  <g class="text">
+    <text class="step-title" x="48" y="126">Scan videos</text>
+    <text class="body" x="48" y="144">Click Find Videos to search the current browser window for videos.</text>
+
+    <text class="step-title" x="48" y="176">Review the list</text>
+    <text class="body" x="48" y="194">Check the popup list; each found video URL is clickable.</text>
+
+    <text class="step-title" x="48" y="226">Open the viewer</text>
+    <text class="body" x="48" y="244">Click Open Viewer to open the 2x2 grid player in a new window.</text>
+
+    <text class="step-title" x="48" y="276">Reset and rescan</text>
+    <text class="body" x="48" y="294">Click Clear to erase results and scan again.</text>
+
+    <text class="warn small" x="30" y="319">Warning: Browser pages, extension pages, and restricted frames can hide videos, so results may be incomplete.</text>
+    <text class="body" x="30" y="348">Learn more tooltip: Read the VidPlex README and audit notes.</text>
+  </g>
+
+  <rect x="17" y="339" width="1264" height="31" rx="8" fill="#4361ee"/>
+  <text class="primary-text" x="561" y="359">Find Videos (all tabs)</text>
+</svg>
@@ -0,0 +1,26 @@
+# Instructions UI design
+
+## Placement
+The instructions banner sits above the primary action button so new users can read the steps before interacting with the popup.
+
+## Structure
+- Short kicker: “Quick start”
+- Heading: “How to use VidPlex”
+- Expand/collapse toggle for users who want a smaller popup
+- Ordered list of the core tasks
+- One warning line for edge cases
+- One short learn-more line that points to the README and audit notes
+
+## Copy strategy
+The microcopy avoids jargon and keeps each step tied to a visible control:
+- Find Videos
+- Open Viewer
+- Clear
+
+## Accessibility strategy
+- A labelled region exposes the whole panel to assistive tech
+- The toggle reflects the current visibility state
+- The collapsed state removes the body from the layout entirely
+
+## Notes
+This design intentionally favors clarity over density because extension popups are small and users typically need the instructions only once.