Compare commits

...
4 Commits
Author SHA1 Message Date
kfj001 0848cd51be Merge pull request 'Add user instructions to goon plugin UI' (#7) from feature/goon-instructions into master
CI / test (push) Successful in 5m39s
Reviewed-on: http://192.168.1.74:30008/kfj001/goon_plugin/pulls/7
Reviewed-by: kfj001 <kfj001@gmail.com>
2026-08-30 21:27:52 -07:00
kfj001 41723227c0 Slight copy update
CI / test (pull_request) Successful in 5m32s
2026-08-31 04:22:12 +00:00
robot 5da2003cd0 docs: draft PR description
CI / test (pull_request) Successful in 5m31s
2026-08-31 03:27:06 +00:00
robot 97abaf42d9 feat: add user instructions to viewer popup 2026-08-31 03:26:50 +00:00
10 changed files with 507 additions and 0 deletions

No files matched your search

+204
View File
@@ -0,0 +1,204 @@
import { describe, it } from './runner.mjs';
import { JSDOM } from 'jsdom';
const POPUP_HTML = `
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>VidPlex</title>
</head>
<body>
<div id="app">
<h1>VidPlex</h1>
<section class="instructions-panel" role="region" aria-labelledby="instructions-title">
<div class="instructions-header">
<div>
<p class="instructions-kicker">Quick start</p>
<h2 id="instructions-title">How to use VidPlex</h2>
</div>
<button
id="instructions-toggle"
type="button"
class="instructions-toggle"
aria-expanded="true"
aria-controls="instructions-body"
>
Hide instructions
</button>
</div>
<div id="instructions-body" class="instructions-body">
<ol class="instructions-list">
<li>
<strong>Scan videos</strong>
<span>Click <strong>Find Videos</strong> to search the current browser window for videos.</span>
</li>
<li>
<strong>Review the list</strong>
<span>Check the popup list; each found video URL is clickable.</span>
</li>
<li>
<strong>Open the viewer</strong>
<span>Click <strong>Open Viewer</strong> to open the 2x2 grid player in a new window.</span>
</li>
<li>
<strong>Reset and rescan</strong>
<span>Click <strong>Clear</strong> to erase results and scan again.</span>
</li>
</ol>
<p class="instructions-note">Warning: Browser pages, extension pages, and restricted frames can hide videos, so results may be incomplete.</p>
<p class="instructions-learn-more">Learn more tooltip: Read the VidPlex README and audit notes.</p>
</div>
</section>
<button id="find-btn">Find Videos (all tabs)</button>
<div id="video-list" class="video-list" style="display:none;"></div>
<div id="status" class="status" style="min-height:16px;"></div>
<div id="btn-row" class="btn-row" style="display:none;">
<button id="clear-btn" class="btn-secondary">Clear</button>
<button id="open-btn">Open Viewer</button>
</div>
</div>
</body>
</html>`;
function installPopupDom() {
const dom = new JSDOM(POPUP_HTML, { url: 'chrome-extension://test/src/viewer/index.html' });
const previous = {
window: globalThis.window,
document: globalThis.document,
navigator: globalThis.navigator,
chrome: globalThis.chrome,
HTMLElement: globalThis.HTMLElement,
Node: globalThis.Node,
};
globalThis.window = dom.window;
globalThis.document = dom.window.document;
Object.defineProperty(globalThis, 'navigator', {
value: dom.window.navigator,
configurable: true,
writable: true,
});
Object.defineProperty(globalThis, 'HTMLElement', {
value: dom.window.HTMLElement,
configurable: true,
writable: true,
});
Object.defineProperty(globalThis, 'Node', {
value: dom.window.Node,
configurable: true,
writable: true,
});
globalThis.chrome = {
storage: {
local: {
get: async () => ({}),
set: async () => undefined,
remove: async () => undefined,
},
},
tabs: { query: async () => [] },
scripting: { executeScript: async () => [] },
runtime: { getURL: (path) => `chrome-extension://test/${path}` },
windows: { create: async () => ({ id: 1 }) },
};
return {
dom,
cleanup() {
dom.window.close();
globalThis.window = previous.window;
globalThis.document = previous.document;
Object.defineProperty(globalThis, 'navigator', {
value: previous.navigator,
configurable: true,
writable: true,
});
globalThis.chrome = previous.chrome;
Object.defineProperty(globalThis, 'HTMLElement', {
value: previous.HTMLElement,
configurable: true,
writable: true,
});
Object.defineProperty(globalThis, 'Node', {
value: previous.Node,
configurable: true,
writable: true,
});
},
};
}
async function mountPopup() {
const { dom, cleanup } = installPopupDom();
const moduleUrl = new URL('../src/viewer/index.js?test=' + Date.now(), import.meta.url);
await import(moduleUrl.href);
return { dom, cleanup };
}
describe('Viewer popup instructions', () => {
it('renders the drafted instructions copy on mount with accessible labeling', async () => {
const { dom, cleanup } = await mountPopup();
try {
const doc = dom.window.document;
const region = doc.querySelector('.instructions-panel');
const title = doc.getElementById('instructions-title');
const toggle = doc.getElementById('instructions-toggle');
const body = doc.getElementById('instructions-body');
if (!region) throw new Error('Instructions region missing');
if (region.getAttribute('role') !== 'region') throw new Error('Instructions region missing role="region"');
if (region.getAttribute('aria-labelledby') !== 'instructions-title') throw new Error('Instructions region missing aria-labelledby');
if (!title || title.textContent !== 'How to use VidPlex') throw new Error('Instructions title not rendered');
if (!toggle) throw new Error('Instructions toggle missing');
if (toggle.getAttribute('aria-controls') !== 'instructions-body') throw new Error('Toggle missing aria-controls');
if (toggle.getAttribute('aria-expanded') !== 'true') throw new Error('Toggle should start expanded');
if (!body || body.hidden) throw new Error('Instructions body should be visible on mount');
const expectedTexts = [
'Scan videos',
'Click Find Videos to search the current browser window for videos.',
'Review the list',
'Check the popup list; each found video URL is clickable.',
'Open the viewer',
'Click Open Viewer to open the 2x2 grid player in a new window.',
'Reset and rescan',
'Click Clear to erase results and scan again.',
'Warning: Browser pages, extension pages, and restricted frames can hide videos, so results may be incomplete.',
'Learn more tooltip: Read the VidPlex README and audit notes.',
];
for (const text of expectedTexts) {
if (!doc.body.textContent.includes(text)) {
throw new Error(`Missing instructions copy: ${text}`);
}
}
} finally {
cleanup();
}
});
it('toggles the instructions panel open and closed', async () => {
const { dom, cleanup } = await mountPopup();
try {
const doc = dom.window.document;
const toggle = doc.getElementById('instructions-toggle');
const body = doc.getElementById('instructions-body');
if (!toggle || !body) throw new Error('Instructions controls missing');
toggle.click();
if (toggle.getAttribute('aria-expanded') !== 'false') throw new Error('Toggle should collapse the instructions');
if (!body.hidden) throw new Error('Instructions body should be hidden after collapse');
if (toggle.textContent !== 'Show instructions') throw new Error('Collapsed label should switch to Show instructions');
toggle.click();
if (toggle.getAttribute('aria-expanded') !== 'true') throw new Error('Toggle should expand the instructions');
if (body.hidden) throw new Error('Instructions body should be visible after expanding');
if (toggle.textContent !== 'Hide instructions') throw new Error('Expanded label should switch back to Hide instructions');
} finally {
cleanup();
}
});
});
+1
View File
@@ -3,6 +3,7 @@
*/
import './schema.test.mjs';
import './viewer_units.test.mjs';
import './instructions_ui.test.mjs';
import './data_flow.test.mjs';
import './viewer_integration.test.mjs';
import './config_validation.test.mjs';
+25
View File
@@ -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
+17
View File
@@ -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.
+50
View File
@@ -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>

After

Width:  |  Height:  |  Size: 2.5 KiB

+26
View File
@@ -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.
+42
View File
@@ -0,0 +1,42 @@
# Add user instructions to goon plugin UI
Branch: `feature/goon-instructions`
## Summary
Adds an always-visible, collapsible quick-start panel to the VidPlex popup so users can understand the scan / review / open / clear flow without reading the README first.
## Links
- Audit notes: [docs/instructions-audit.md](docs/instructions-audit.md)
- Design notes: [docs/instructions-design.md](docs/instructions-design.md)
- Copy deck: [docs/instructions-copy.md](docs/instructions-copy.md)
- Preview render: [docs/instructions-demo.svg](docs/instructions-demo.svg)
## Testing
- `npm run build`
- `npm test`
Manual verification:
1. Open the extension popup.
2. Confirm the instructions banner renders expanded on mount.
3. Click the toggle and confirm the panel collapses / expands and the label changes.
4. Confirm the main Scan Videos button still works normally.
## Changed files
- `src/viewer/index.html`
- `src/viewer/index.css`
- `src/viewer/index.js`
- `__tests__/instructions_ui.test.mjs`
- `__tests__/run.mjs`
- `docs/instructions-audit.md`
- `docs/instructions-design.md`
- `docs/instructions-copy.md`
- `docs/instructions-demo.svg`
## Acceptance criteria
- A PR exists against `master`.
- The PR description includes summary, links to the design/copy docs, a visual preview, testing steps, changed files, and acceptance criteria.
- Reviewers are requested before handoff.
## Open questions / risks
- The repo still has some pre-existing lint warnings outside this change.
- The preview asset is an SVG render of the UI rather than a raster screenshot.
+84
View File
@@ -32,6 +32,90 @@ h1 {
font-weight: 600;
}
.instructions-panel {
display: flex;
flex-direction: column;
gap: 10px;
padding: 12px;
border: 1px solid var(--border);
border-radius: var(--radius);
background: #f8fafc;
}
.instructions-header {
display: flex;
align-items: flex-start;
justify-content: space-between;
gap: 12px;
}
.instructions-kicker {
margin-bottom: 2px;
font-size: 11px;
font-weight: 700;
letter-spacing: 0.08em;
text-transform: uppercase;
color: #64748b;
}
.instructions-panel h2 {
font-size: 14px;
line-height: 1.3;
font-weight: 600;
}
.instructions-toggle {
flex: 0 0 auto;
padding: 6px 10px;
font-size: 12px;
background: transparent;
color: var(--accent);
border: 1px solid var(--border);
}
.instructions-toggle:hover {
background: #eef2ff;
}
.instructions-body {
display: flex;
flex-direction: column;
gap: 8px;
}
.instructions-body[hidden] {
display: none;
}
.instructions-list {
display: flex;
flex-direction: column;
gap: 8px;
padding-left: 18px;
}
.instructions-list li {
display: flex;
flex-direction: column;
gap: 2px;
}
.instructions-list strong {
font-size: 12px;
}
.instructions-list span,
.instructions-note,
.instructions-learn-more {
font-size: 12px;
line-height: 1.45;
color: #475569;
}
.instructions-note {
color: #7c3aed;
}
button {
padding: 8px 16px;
background: var(--accent);
+42
View File
@@ -9,6 +9,48 @@
<body>
<div id="app">
<h1>VidPlex</h1>
<section class="instructions-panel" role="region" aria-labelledby="instructions-title">
<div class="instructions-header">
<div>
<p class="instructions-kicker">Quick start</p>
<h2 id="instructions-title">How to use VidPlex</h2>
</div>
<button
id="instructions-toggle"
type="button"
class="instructions-toggle"
aria-expanded="true"
aria-controls="instructions-body"
>
Hide instructions
</button>
</div>
<div id="instructions-body" class="instructions-body">
<ol class="instructions-list">
<li>
<strong>Start your videos</strong>
<span>Open the videos you want to play, one per tab, and begin their playback.</span>
</li>
<li>
<strong>Scan videos</strong>
<span>Click <strong>Find Videos</strong> to search the current browser window's tabs for playing videos.</span>
</li>
<li>
<strong>Review the list</strong>
<span>Check to make sure the right number of videos was found.</span>
</li>
<li>
<strong>Open the viewer</strong>
<span>Click <strong>Open Viewer</strong> to open the grid player in a new window.</span>
</li>
<li>
<strong>Reset and rescan</strong>
<span>Click <strong>Clear</strong> to erase results and scan again.</span>
</li>
</ol>
<p class="instructions-note">Warning: Browser pages, extension pages, and restricted frames can hide videos, so results may be incomplete.</p>
</div>
</section>
<button id="find-btn">Find Videos (all tabs)</button>
<div id="video-list" class="video-list" style="display:none;"></div>
<div id="status" class="status" style="min-height:16px;"></div>
+16
View File
@@ -34,10 +34,26 @@ const openBtn = document.getElementById('open-btn');
const statusEl = document.getElementById('status');
const listEl = document.getElementById('video-list');
const btnRow = document.getElementById('btn-row');
const instructionsToggle = document.getElementById('instructions-toggle');
const instructionsBody = document.getElementById('instructions-body');
listEl.style.wordBreak = 'break-word';
listEl.style.whiteSpace = 'pre-wrap';
function setInstructionsExpanded(expanded) {
if (!instructionsToggle || !instructionsBody) return;
instructionsBody.hidden = !expanded;
instructionsToggle.setAttribute('aria-expanded', String(expanded));
instructionsToggle.textContent = expanded ? 'Hide instructions' : 'Show instructions';
}
if (instructionsToggle && instructionsBody) {
setInstructionsExpanded(true);
instructionsToggle.addEventListener('click', () => {
setInstructionsExpanded(instructionsBody.hidden);
});
}
/* ======================================================================== */
/* UI helpers */
/* ======================================================================== */