diff --git a/docs/superpowers/plans/2026-06-16-output-tab-four-acts.html b/docs/superpowers/plans/2026-06-16-output-tab-four-acts.html new file mode 100644 index 0000000..8036db7 --- /dev/null +++ b/docs/superpowers/plans/2026-06-16-output-tab-four-acts.html @@ -0,0 +1,183 @@ + + + + + + Output Tab — Four-Act Narrative — Implementation Plan + + + +
+ +
+

Output Tab — Four-Act Narrative

+
+ Implementation plan · Pillar A · 2026-06-16 · branch feat/output-tab-four-acts
+ Overview for review. The exact step-by-step code (TDD steps, commands, commits) lives in the companion .md. +
+
+ +
+ Goal. Restructure the flat 28-tab nav into a four-act narrative (Decide → Understand → Go Deeper → Act) — keeping every panel, render function, and deep link — via a pure act-model module and a two-tier nav, then a few targeted UX fixes. +
+ +

Architecture

+

Keep the existing #t0–#t27 panels, their render functions, and show(n) behavior. Add a pure, unit-tested output-acts.js that groups tab indices into four ordered acts. Replace the flat nav markup with a two-tier nav (primary act row + a secondary row showing only the active act's tabs), generated from the model. Make show(n) also highlight the owning act and render its secondary row. No background.js / message-contract changes.

+ +
+ Why this is lower-risk than a rewrite (confirmed by reading the code): + +
+
+ One coupling fixed: show() currently toggles panels by DOM index (idx === n), relying on panel order matching tab number. Task 4 switches to selecting by id (#t{n}) so it stays correct regardless of order. +
+ +

The four acts (tab grouping)

+ +

All 28 indices map to exactly one act (verified by a unit test).

+ +

Tasks

+ +
+ Phase 1 — Foundation +
+
Task 1 · Pure act model create
+
output-acts.js + tests/output-acts.test.js
+
Full TDD: ACTS, TAB_LABELS, actForTab(), tabsForAct(), ACT_ORDER. Tests assert every index 0–27 is covered exactly once, plus helper correctness.
+
+
+ +
+ Phase 2 — Two-tier nav +
+
Task 2 · Nav containers + styles modify
+
output-tab.html
+
Replace the flat .tab-nav + dropdown menus with two containers (#act-nav, #act-subnav) and Mono-Ink styles (secondary row reuses .tab-btn).
+
+
+
Task 3 · Render the nav from the model modify
+
output-tab.js
+
Import the model; renderActNav() (primary acts) + renderSubNav(actId) (active act's tabs). Buttons keep data-tab so the existing show() path is reused.
+
+
+ +
+ Phase 3 — Routing +
+
Task 4 · show() selects by id + tracks the act modify
+
output-tab.js
+
Panels by #t{n}; set the active act button + render/mark its secondary row; hash + per-repo recall kept verbatim.
+
+
+
Task 5 · Two-tier click handling + tooltips modify
+
output-tab.js
+
Act click → show its first tab; subnav click → show(n). Remove the old dropdown handlers; re-point the explainer tooltips at the persistent #act-subnav (delegated, survives re-renders).
+
+
+
Task 6 · Deep-link/restore order modify if needed
+
output-tab.js
+
Ensure renderActNav() runs before the initial hash/recall route resolves; show() handles the rest.
+
+
+ +
+ Phase 4 — Targeted UX fixes +
+
Task 7 · Decision control to the top of Decide modify
+
output-tab.js, output-tab.html
+
Re-anchor the Adopt/Trial/Hold/Reject block after the fit chip + bottom line (was buried at the bottom). Internals unchanged.
+
+
+
Task 8 · Highlights anchor, not cross-navigate modify
+
output-tab.js (renderHighlights)
+
A highlight click switches to its section and scrolls it into view (reduced-motion aware) instead of silently swapping context.
+
+
+
Task 9 · Previews jump to canonical (dedupe) modify
+
output-tab.js
+
Ensure each Verdict preview (tech stack, top flags) has a jump to its full section (15, 8). Previews stay — one source of truth.
+
+
+
Task 10 · "Run all lenses" in the Go-Deeper subnav modify
+
output-tab.js (renderSubNav)
+
Relocate the run-all control (from the removed Lenses dropdown) into the Go-Deeper secondary row.
+
+
+ +
+ Phase 5 — Folded-in journey win +
+
Task 11 · Circular library ↔ output nav modify
+
output-tab.js, library.js
+
One clear, reversible path each way (focus/reuse an existing tab rather than orphaning new ones).
+
+
+ +
+ Phase 6 — Verification +
+
Task 12 · Full pass
+
vitest run (857 + 5 new) · eslint . 0 errors · check:html · node --check · Playwright screenshots at 320/768/1024/1440 + deep-link, keyboard, reduced-motion, a11y checks.
+
+
+ +

Spec coverage & honest gaps

+ + +

Out of scope (per spec)

+

Gamification/juice (Pillar 3), settings redesign, new analysis features, rewriting section internals or the analysis pipeline.

+ + + +
+ + diff --git a/docs/superpowers/plans/2026-06-16-output-tab-four-acts.md b/docs/superpowers/plans/2026-06-16-output-tab-four-acts.md new file mode 100644 index 0000000..45a4172 --- /dev/null +++ b/docs/superpowers/plans/2026-06-16-output-tab-four-acts.md @@ -0,0 +1,577 @@ +# Output Tab — Four-Act Narrative — Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Restructure the output tab's flat 28-tab nav into a four-act narrative (Decide → Understand → Go Deeper → Act) — keeping every panel, render function, and deep link — by introducing a pure act-model module and a two-tier nav, then a few targeted UX fixes. + +**Architecture:** Keep the existing `#t0`–`#t27` panels, their render functions, and `show(n)` **unchanged in behavior**. Add a pure, unit-tested `output-acts.js` that groups tab indices into four ordered acts. Replace the flat `.tab-nav` markup with a two-tier nav (primary act row + a secondary row showing only the active act's tabs), generated from the act model. Make `show(n)` also highlight the owning act and render its secondary row. Layer on targeted UX fixes (decision-to-top, previews→jumps, highlights-anchor) as isolated tasks. No `background.js` / message-contract changes. + +**Tech Stack:** Vanilla ES modules (zero-build, no deps), Vitest (pure logic only — no DOM env), `node --check` for DOM glue, existing `*-demo.html` harness + Playwright for visual checks. Brand: Mono Ink, motion behind `prefers-reduced-motion` (`--dur-*`/`--ease-*` tokens already in `themes.css`). + +--- + +## Why this is lower-risk than a rewrite + +Confirmed by reading the current code: +- **Slugs already exist** (`TAB_SLUGS` in `output-tab.js:2200`) and `show()` already writes `#slug` + persists `repolens_tab_`. So existing deep links and per-repo recall **already work** — the act model only adds "which act owns this tab" on top. +- **Lens labeling already exists** — `initScanTips()` (`output-tab.js:2257`) shows BEST-FOR / SKIP-IF / COST tooltips per tab, and the `?`-guide lists every lens with cost. Deep Dive already has staged progress (`ddProgressHtml`). So "label lenses" is mostly **surfacing what exists** under the Go-Deeper act, not new work. +- The nav is a single `.tab-nav` block (`output-tab.html:845-885`) and one click handler (`output-tab.js:2231`). Swapping flat→two-tier is contained. + +⚠️ **One coupling to fix:** `show(n)` toggles panels via `forEach((c, idx) => ... idx === n)` (`output-tab.js:2212`) — it relies on `.tab-content` DOM order matching the tab index. Today that holds (`#t0`…`#t27` are in order). Task 6 changes this to select by id (`#t${n}`) so it stays correct regardless of DOM order. + +--- + +## File Structure + +- **Create** `output-acts.js` — pure act model: `ACTS`, `TAB_LABELS`, `actForTab()`, `tabsForAct()`, `ACT_ORDER`. No DOM, no imports. One responsibility: the tab↔act grouping + labels. +- **Create** `tests/output-acts.test.js` — completeness + helper tests. +- **Modify** `output-tab.html` — replace the `.tab-nav` inner markup (845-885) with two-tier containers (`#act-nav`, `#act-subnav`); keep all `#t0`–`#t27` panels untouched. +- **Modify** `output-tab.js` — import the act model; render the two-tier nav; make `show(n)` select panels by id and set the active act + secondary row; update the nav click handler. +- **Modify** the verdict/decision render in `output-tab.js` (Task 8) — move decision control to the top. +- **Modify** `renderHighlights` in `output-tab.js` (Task 10) — anchor instead of cross-navigate. + +--- + +## Phase 1 — Foundation: the pure act model + +### Task 1: Create the act model + +**Files:** +- Create: `output-acts.js` +- Test: `tests/output-acts.test.js` + +- [ ] **Step 1: Write the failing test** + +```js +// tests/output-acts.test.js +import { describe, it, expect } from 'vitest'; +import { ACTS, ACT_ORDER, TAB_LABELS, actForTab, tabsForAct } from '../output-acts.js'; + +describe('act model', () => { + it('orders the four acts', () => { + expect(ACT_ORDER).toEqual(['decide', 'understand', 'deeper', 'act']); + }); + + it('covers every tab index 0..27 exactly once', () => { + const all = ACTS.flatMap((a) => a.tabs).sort((x, y) => x - y); + expect(all).toEqual(Array.from({ length: 28 }, (_, i) => i)); + expect(new Set(all).size).toBe(28); // no duplicates + }); + + it('maps a tab to its owning act', () => { + expect(actForTab(9)).toBe('decide'); + expect(actForTab(7)).toBe('understand'); // Health + expect(actForTab(10)).toBe('deeper'); // Deep Dive + expect(actForTab(17)).toBe('act'); // Versus + expect(actForTab(99)).toBeNull(); + }); + + it('lists tabs for an act in display order', () => { + expect(tabsForAct('decide')).toEqual([9]); + expect(tabsForAct('understand')[0]).toBe(0); // ELI5 leads + expect(tabsForAct('nope')).toEqual([]); + }); + + it('has a label for every tab it groups', () => { + for (const t of ACTS.flatMap((a) => a.tabs)) { + expect(typeof TAB_LABELS[t]).toBe('string'); + expect(TAB_LABELS[t].length).toBeGreaterThan(0); + } + }); +}); +``` + +- [ ] **Step 2: Run it and confirm it fails** + +Run: `npx vitest run tests/output-acts.test.js` +Expected: FAIL — `Cannot find module '../output-acts.js'`. + +- [ ] **Step 3: Write the module** + +```js +// output-acts.js +// Pure act model for the output tab. Groups the existing tab indices (the #t0..#t27 +// panels) into four ordered "acts" — Decide, Understand, Go Deeper, Act — for a +// two-tier nav. No DOM, no network, no imports: this is the testable contract the +// nav rendering and show() build on. Tab indices and slugs are unchanged from the +// existing TAB_SLUGS, so deep links and per-repo recall keep working. + +export const ACTS = [ + { id: 'decide', label: 'Decide', tabs: [9] }, + { id: 'understand', label: 'Understand', tabs: [0, 1, 2, 3, 4, 5, 8, 6, 7, 15] }, + { id: 'deeper', label: 'Go Deeper', tabs: [10, 27, 11, 12, 13, 14, 21, 22, 23, 24] }, + { id: 'act', label: 'Act', tabs: [25, 16, 17, 18, 19, 20, 26] }, +]; + +export const ACT_ORDER = ACTS.map((a) => a.id); + +// Tab index → human label (mirrors the current nav button text; used to render +// the secondary row from the model instead of hardcoded HTML). +export const TAB_LABELS = { + 9: 'Verdict', + 0: 'ELI5', 1: 'Technical', 2: 'Use Cases', 3: 'Skip If', 4: 'Enables', + 5: 'Pros / Cons', 8: 'Red Flags', 6: 'Alternatives', 7: 'Health', 15: 'Tech Stack', + 10: 'Deep Dive', 27: 'Canvas', 11: 'Systems', 12: 'Ideate', 13: 'Prioritize', + 14: 'SKTPG', 21: 'Docs Quality', 22: 'Maintenance', 23: 'License', 24: 'Since Last Scan', + 25: 'Fits MY Stack?', 16: 'Similar', 17: 'Versus', 18: 'Synergies', + 19: 'Connections', 20: 'Combine', 26: 'Ask', +}; + +const ACT_BY_TAB = (() => { + const m = {}; + for (const a of ACTS) for (const t of a.tabs) m[t] = a.id; + return m; +})(); + +/** @returns {string|null} the act id owning tab `n`, or null. */ +export function actForTab(n) { + return Object.prototype.hasOwnProperty.call(ACT_BY_TAB, n) ? ACT_BY_TAB[n] : null; +} + +/** @returns {number[]} the tab indices in an act, in display order. */ +export function tabsForAct(id) { + const a = ACTS.find((x) => x.id === id); + return a ? a.tabs : []; +} +``` + +- [ ] **Step 4: Run tests and confirm they pass** + +Run: `npx vitest run tests/output-acts.test.js` +Expected: PASS (5 tests). + +- [ ] **Step 5: Lint the new module** + +Run: `npx eslint output-acts.js tests/output-acts.test.js` +Expected: 0 errors. + +- [ ] **Step 6: Commit** + +```bash +git add output-acts.js tests/output-acts.test.js +git commit -m "feat(output): pure four-act model for the output tab" +``` + +--- + +## Phase 2 — Two-tier nav + +### Task 2: Replace the flat nav markup with two-tier containers + +**Files:** +- Modify: `output-tab.html:845-885` (the `.tab-nav` block) + +- [ ] **Step 1: Replace the markup** + +Replace the entire `
…
` block (current lines 845-885, the flat buttons + Lenses/Library menus) with two empty containers that `output-tab.js` will populate from the act model: + +```html + + +
+``` + +- [ ] **Step 2: Add the nav styles** + +Add to the ` + + +
+ +
+

Output Tab — Four-Act Narrative

+
+ Pillar A · 2026-06-16 · Status: Approved (design) — pending implementation plan
+ Surface: the extension's analysis/verdict view (output-tab.html + output-tab.js) +
+
+ Part of a 3-pillar "simpler to use and digest" effort: +
Pillar A — Output-tab narrative ← this spec, building first
+
Pillar B — Cross-app journey (circular nav, entry points, save/discovery clarity)
+
Pillar 3 — The Knowledge Game (library + corkboard + canvas: smooth, juicy, addictive — mastery + discovery + collection + crafting, to "plug pieces together and think in new ways")
+
+
+ +

Problem

+

The output tab is information-rich and genuinely good — the problem is purely presentation and flow. From a current-state audit:

+
    +
  1. 28 flat tabs. Verdict, ELI5, Technical, Use-Cases, Skip-If, Enables, Pros-Cons, Alternatives, Health, Red-Flags, Tech-Stack, + Deep-Dive/Systems/Ideate/Prioritize/SKTPG, + Docs/Maintenance/License/Diff/Fits-Stack, + Similar/Versus/Synergies/Connections/Combine, + Ask/Canvas. No sense of what to read first or in what order.
    2. +
  2. No narrative, weak wayfinding. The Verdict landing tries to be everything (11 stacked sections, flat hierarchy); the Decision control (Adopt/Trial/Hold/Reject) is buried ~2000px down; key info is previewed on Verdict but fully rendered elsewhere with no jump links; fit verdict, red flags, and tech stack each render in two places.
    3. +
  3. Opaque "lenses," hidden prerequisites. "Lens" is never explained; Canvas silently needs Deep Dive first; library tabs need 2+ scans; multi-stage runs give no progress/ETA.
    4. +
+ +

Goals

+ + +

Non-goals

+ + +

Structure: chosen approach

+

Four Acts, two-tier navigation. Four primary acts as the top-level nav; each act opens its own focused, bounded view containing its grouped sections. The user always knows which act they are in; never an endless scroll. Keyboard navigation preserved. Cleanest fit for the zero-build codebase.

+ +

The four acts — complete section mapping

+

Default = shown immediately after a scan. On-demand = user triggers an AI run.

+ +
+ ① DECIDE +

"should I use this, and what do I do about it?" — the landing

+ + + + + + + + + + +
ElementWhenNotes
Fit verdict (level + label + why)DefaultAnchored at top
Bottom line (one-liner)Default
Decision control (Adopt/Trial/Hold/Reject + note)DefaultMoved to the top (was buried at page bottom)
At-a-glance facts (health, stars/license/lang, pros/cons/flag counts)DefaultCompact summary row
Top red flags (up to 3)DefaultDistinct "warning" treatment; link to full list
Where-to-start cardsDefaultif present
Since-last-scan diff calloutDefaultif prior scan
"Worth noting" highlightsDefaultNow anchor to their home section (no context-thrash)
+
+ +
+ ② UNDERSTAND +

deep reading; all pre-computed, no waiting

+ + + + + + + + + + + + +
ElementWhenNotes
ELI5 (+ analogies)Default
TechnicalDefault
Use Cases (4-grid)Default
Skip If (4-grid)Default
EnablesDefault
Pros / Cons (full)DefaultVerdict shows counts → jump here
Red Flags (full list)DefaultDecide shows top 3 → jump to the canonical full list here
AlternativesDefault
Health (full: 4 signals + summary)DefaultAdd metric explanations
Tech Stack (full: built_with + key_dependencies)DefaultVerdict shows language chips → jump here
+

De-duplication rule: where Verdict shows a preview, the full version lives here and Verdict links to it. One source of truth per element.

+
+ +
+ ③ GO DEEPER +

on-demand lenses about THIS repo; each a labeled card

+

Each lens card shows: name · one-line "what it does" · prerequisite badge · time estimate · live stage progress.

+ + + + + + + + + + +
LensPrerequisiteNotes
Deep Dive (atoms → lineage → Feynman)—~90s, 3 stages with progress
Canvas / BlueprintNeeds Deep Diveprereq badge shown
Systems / Ideate / Prioritize—framework chips
SKTPG—auto-run by default (toggle)
Docs Quality—
Maintenance—can be slow; show progress
Licenselibrary context
Since Last Scanprior scan
+
+ +
+ ④ ACT +

do something with it

+ + + + + + +
ElementNotes
Saveclear saved-state feedback
Ask this reporequires a completed scan — state up front
Share
Against your library: Similar · Versus · Synergies · Connections · Combine · Fits-My-StackHonest "needs N scans" unlock states. Deeper gamified treatment is Pillar 3.
+
+ +

Navigation & interaction

+ + +

Component design (isolation + testability)

+

Extract a pure act-model module (e.g. output-acts.js), no DOM/network, exporting: ACTS, sectionToAct(), routeForHash() / hashForRoute(), LEGACY_SLUG_MAP + resolveLegacySlug(), and keyboardMap. output-tab.js consumes it to render the act shell and route; section render functions stay as-is and mount into act containers. Routing/grouping logic becomes unit-testable independent of the DOM.

+ +

Constraints honored

+ + +

Testing

+ + +

Migration / rollout

+
    +
  1. Build the pure act-model module + act shell + routing (tested first).
    2. +
  2. Move sections into acts group-by-group, keeping tests green.
    3. +
  3. Add the legacy-hash redirect so existing #slug links resolve.
    4. +
  4. Preserve auto-save, lens runners, and all message contracts (front-end only).
    5. +
+ +

Acceptance criteria

+ + +
+ Resolved decisions: Four Acts (two-tier nav) · decision control → top of Decide · library-relational features → Act (gamified depth deferred to Pillar 3) · circular library↔output nav folded into A. +
+ +
RepoLens · Pillar A design spec · review this, then it becomes an implementation plan.
+ +
+ + diff --git a/docs/superpowers/specs/2026-06-16-output-tab-four-acts-design.md b/docs/superpowers/specs/2026-06-16-output-tab-four-acts-design.md new file mode 100644 index 0000000..dc492e0 --- /dev/null +++ b/docs/superpowers/specs/2026-06-16-output-tab-four-acts-design.md @@ -0,0 +1,153 @@ +# Output Tab — Four-Act Narrative (Pillar A) + +- **Date:** 2026-06-16 +- **Status:** Approved (design) — pending implementation plan +- **Surface:** the extension's analysis/verdict view (`output-tab.html` + `output-tab.js`) +- **Part of:** a 3-pillar "make the app simpler to use and digest" effort + - **Pillar A — Output-tab narrative** ← *this spec, building first* + - **Pillar B — Cross-app journey** (circular nav, entry points, save/discovery clarity) + - **Pillar 3 — The Knowledge Game** (library + corkboard + canvas made smooth, juicy, and addictive; mastery + discovery + collection + crafting, in service of "plug pieces together and think in new ways") + +## Problem + +The output tab is information-rich and genuinely good — the problem is purely presentation and flow. From a current-state audit: + +1. **28 flat tabs.** Verdict, ELI5, Technical, Use-Cases, Skip-If, Enables, Pros-Cons, Alternatives, Health, Red-Flags, Tech-Stack, + Deep-Dive/Systems/Ideate/Prioritize/SKTPG, + Docs/Maintenance/License/Diff/Fits-Stack, + Similar/Versus/Synergies/Connections/Combine, + Ask/Canvas. No sense of what to read first or in what order. +2. **No narrative, weak wayfinding.** The Verdict landing tries to be everything (11 stacked sections, flat hierarchy); the **Decision control (Adopt/Trial/Hold/Reject) is buried ~2000px down**; key info is *previewed* on Verdict but *fully* rendered elsewhere with no jump links; fit verdict, red flags, and tech stack each render in two places. +3. **Opaque "lenses," hidden prerequisites.** "Lens" is never explained; Canvas silently needs Deep Dive first; library tabs need 2+ scans; multi-stage runs give no progress/ETA. + +## Goals + +- Reorganize the output tab into a **four-act narrative**: **Decide → Understand → Go Deeper → Act**. +- Add real hierarchy, wayfinding (preview → jump), and lens clarity (label + prerequisite + time estimate + live progress). +- **Preserve every piece of information**, all functionality, all deep links, and per-repo position recall. Nothing is removed. + +## Non-goals + +- No rewrite of individual section internals or the analysis pipeline (`background.js` runners, prompts, parsers stay as-is). +- No gamification / motion juice (that is Pillar 3). +- No settings redesign, no new analysis features. +- **One folded-in exception:** the small circular library↔output navigation fix (it is central to "flow" and cheap). + +## Structure: chosen approach + +**Four Acts, two-tier navigation.** Four primary acts as the top-level nav; each act opens its own focused, bounded view containing its grouped sections. The user always knows which act they are in; never an endless scroll. Keyboard navigation preserved. Cleanest fit for the zero-build codebase. + +## The four acts — complete section mapping + +Every current destination keeps a home. "Default" = shown immediately after a scan; "On-demand" = user triggers an AI run. + +### ① DECIDE — *"should I use this, and what do I do about it?"* (the landing) + +| Element | Default/On-demand | Notes | +|---|---|---| +| Fit verdict (level + label + why) | Default | Anchored at top | +| Bottom line (one-liner) | Default | | +| **Decision control** (Adopt/Trial/Hold/Reject + note) | Default | **Moved to the top** (was buried at page bottom) | +| At-a-glance facts (health score, stars/license/language, pros/cons/flag counts) | Default | Compact summary row | +| Top red flags (up to 3) | Default | Distinct "warning" treatment; link to full list in Understand | +| Where-to-start cards (`start_here`) | Default (if present) | | +| Since-last-scan diff callout | Default (if prior scan) | fit/health change | +| "Worth noting" highlights | Default | Now **anchor** to their home section (no context-thrash navigation) | + +### ② UNDERSTAND — *deep reading; all pre-computed, no waiting* + +| Element | Default/On-demand | Notes | +|---|---|---| +| ELI5 (+ analogies) | Default | | +| Technical | Default | | +| Use Cases (4-grid) | Default | | +| Skip If (4-grid) | Default | | +| Enables | Default | | +| Pros / Cons (full) | Default | Verdict shows counts → jump here | +| Red Flags (full list) | Default | Decide shows top 3 → jump to the canonical full list here | +| Alternatives | Default | | +| Health (full: 4 signals + summary) | Default | **Add metric explanations** (what each signal means) | +| Tech Stack (full: built_with + key_dependencies) | Default | Verdict shows language chips → jump here | + +De-duplication rule: where Verdict shows a preview (fit, top flags, tech stack), the **full** version lives here and Verdict links to it. One source of truth per element. + +### ③ GO DEEPER — *on-demand lenses about THIS repo; each a labeled card* + +Each lens renders as a card with: **name · one-line "what it does" · prerequisite badge (if any) · time estimate · live stage progress.** + +| Lens | Prerequisite | Notes | +|---|---|---| +| Deep Dive (atoms → lineage → Feynman) | — | ~90s, 3 stages with progress | +| Canvas / Blueprint | **Needs Deep Dive** | prereq badge shown | +| Systems (PDCA/DMAIC/Loops/TOC) | — | framework chips | +| Ideate (SCAMPER/Lateral/TRIZ/Morph) | — | framework chips | +| Prioritize (Eisenhower/Pareto) | — | framework chips | +| SKTPG | — | auto-run by default (toggle) | +| Docs Quality | — | | +| Maintenance | — | can be slow on large repos; show progress | +| License | library context | | +| Since Last Scan | prior scan | | + +### ④ ACT — *do something with it* + +| Element | Notes | +|---|---| +| Save | clear saved-state feedback | +| Ask this repo | requires a completed scan — state this up front | +| Share | | +| **Against your library:** Similar · Versus · Synergies · Connections · Combine · Fits-My-Stack | Honest "needs N scans" unlock states. The **deeper, gamified treatment of these is Pillar 3**; here they get a clean home + honest states. | + +## Navigation & interaction + +- **Persistent header** — repo name, meta pills (stars/license/language), fit chip — always visible across acts. +- **Primary nav** — four acts (`DECIDE · Understand · Go Deeper · Act`). Default landing = **Decide**. +- **Secondary nav within an act** — for Understand, a section list with hierarchy; for Go Deeper / Act, a grid of labeled cards. +- **Keyboard** — `1`–`4` select acts; within-act secondary keys for sections; preserve existing `r` (rerun), `f` (fresh), `l` (library), `o` (open source). +- **Deep-linking** — new hash scheme (`#decide`, `#understand/health`, `#deeper/deep-dive`, `#act/versus`). A **legacy slug map** translates every old `#slug` to its new act/section so existing links and bookmarks still resolve. +- **Per-repo recall** — extend the stored position (`repolens_tab_`) to remember act + section. + +## Component design (for isolation + testability) + +Extract a **pure act-model module** (e.g. `output-acts.js`), no DOM/network, exporting: + +- `ACTS` — the ordered acts and the sections grouped under each. +- `sectionToAct(sectionId)` — which act owns a section. +- `routeForHash(hash)` / `hashForRoute(act, section)` — round-trippable hash routing. +- `LEGACY_SLUG_MAP` + `resolveLegacySlug(slug)` — old `#slug` → new route. +- `keyboardMap` — key → act/section. + +`output-tab.js` consumes this module to render the act shell and route; section render functions stay as-is and mount into act containers. This keeps the routing/grouping logic unit-testable independently of the DOM. + +## Constraints honored + +- **Zero-build, zero-dep, vanilla ES modules.** Reorganize `output-tab.html` + `output-tab.js`; no framework, no bundler, no new runtime deps. +- **Brand = Mono Ink**, stop-slop/human voice, **no emoji on product surfaces**, motion behind `prefers-reduced-motion` (reuse `--dur-*` / `--ease-*` tokens). +- **No DOM test environment** — pure logic to vitest; DOM/SW glue via `node --check` + a `*-demo.html` harness. +- **No `background.js` contract changes** — message types (`DEEP_DIVE`, `SKTPG`, `MAINTENANCE`, …) are unchanged; this is a front-end reorganization only. + +## Testing + +- **vitest (pure):** act-model completeness (every current slug maps to exactly one act/section), legacy-slug resolution, hash round-trip, keyboard map. +- **`node --check`** on `output-tab.js` / HTML glue. +- **Visual:** an `output-tab` demo harness (`*-demo.html`); Playwright screenshots at 320 / 768 / 1024 / 1440; reduced-motion behavior; accessibility (keyboard nav, focus order, contrast). +- Existing suite stays green; `eslint .` 0 errors; HTML parse gate passes. + +## Migration / rollout + +1. Build the pure act-model module + the act shell + routing (tested first). +2. Move sections into acts group-by-group, keeping tests green at each step. +3. Add the legacy-hash redirect so existing `#slug` links resolve. +4. Preserve auto-save, lens runners, and all message contracts (front-end only). + +## Acceptance criteria + +- [ ] All ~28 destinations reachable, grouped into the four acts. +- [ ] Decision control lives in Decide, visible without scrolling. +- [ ] No element rendered twice as a source of truth — previews jump to the canonical section. +- [ ] Every lens shows what-it-does + prerequisite + time estimate + live progress. +- [ ] Old deep links resolve via the legacy map; keyboard nav works; per-repo recall works. +- [ ] Verdict landing is scannable with clear hierarchy. +- [ ] All existing tests pass + new act-model tests; `eslint .` 0 errors; HTML gate passes. + +## Resolved decisions + +- Structure = Four Acts, two-tier nav. +- Decision control → top of Decide. +- Library-relational features → Act (deeper gamified treatment deferred to Pillar 3). +- Circular library↔output nav fix folded into A. diff --git a/library.js b/library.js index 399506a..62e37a1 100644 --- a/library.js +++ b/library.js @@ -532,10 +532,29 @@ function openNote(repoId, btn) { panel.querySelector('.lc-note-save')?.addEventListener('click', saveNote); } -function openRow(repoId) { +// Forward path (library → output). Before opening a fresh output tab, focus an +// already-open output tab for the same repo so re-clicking a card round-trips +// instead of orphaning duplicate analysis tabs. Output tabs set their title to +// `… {repoId} — RepoLens` (output-tab.js), which is what we match on — the random +// session key never reaches the URL, so the title is the only stable repo signal. +async function focusExistingOutputTab(repoId) { + try { + const tabs = await chrome.tabs.query({ url: chrome.runtime.getURL('output-tab.html') + '*' }); + const existing = tabs.find((t) => typeof t.title === 'string' && t.title.includes(`${repoId} — RepoLens`)); + if (!existing) return false; + await chrome.tabs.update(existing.id, { active: true }); + await chrome.windows.update(existing.windowId, { focused: true }); + return true; + } catch { + return false; + } +} + +async function openRow(repoId) { const cached = cacheByRepo.get(repoId); - if (cached) openCachedAnalysis(cached); - else openSource(repoId); + if (!cached) { openSource(repoId); return; } + if (await focusExistingOutputTab(repoId)) return; + openCachedAnalysis(cached); } function openSource(repoId) { diff --git a/output-acts.js b/output-acts.js new file mode 100644 index 0000000..9eccc23 --- /dev/null +++ b/output-acts.js @@ -0,0 +1,65 @@ +// output-acts.js +// Pure act model for the output tab. Groups the existing tab indices (the #t0..#t27 +// panels) into four ordered "acts" — Decide, Understand, Go Deeper, Act — for a +// two-tier nav. No DOM, no network, no imports: this is the testable contract the +// nav rendering and show() build on. Tab indices and slugs are unchanged from the +// existing TAB_SLUGS, so deep links and per-repo recall keep working. + +export const ACTS = [ + { id: 'decide', label: 'Decide', tabs: [9] }, + { id: 'understand', label: 'Understand', tabs: [0, 1, 2, 3, 4, 5, 8, 6, 7, 15] }, + { id: 'deeper', label: 'Go Deeper', tabs: [10, 27, 11, 12, 13, 14, 21, 22, 23, 24] }, + { id: 'act', label: 'Act', tabs: [25, 16, 17, 18, 19, 20, 26] }, +]; + +export const ACT_ORDER = ACTS.map((a) => a.id); + +// Tab index → human label (mirrors the current nav button text; used to render +// the secondary row from the model instead of hardcoded HTML). +export const TAB_LABELS = { + 9: 'Verdict', + 0: 'ELI5', + 1: 'Technical', + 2: 'Use Cases', + 3: 'Skip If', + 4: 'Enables', + 5: 'Pros / Cons', + 8: 'Red Flags', + 6: 'Alternatives', + 7: 'Health', + 15: 'Tech Stack', + 10: 'Deep Dive', + 27: 'Canvas', + 11: 'Systems', + 12: 'Ideate', + 13: 'Prioritize', + 14: 'SKTPG', + 21: 'Docs Quality', + 22: 'Maintenance', + 23: 'License', + 24: 'Since Last Scan', + 25: 'Fits MY Stack?', + 16: 'Similar', + 17: 'Versus', + 18: 'Synergies', + 19: 'Connections', + 20: 'Combine', + 26: 'Ask', +}; + +const ACT_BY_TAB = (() => { + const m = {}; + for (const a of ACTS) for (const t of a.tabs) m[t] = a.id; + return m; +})(); + +/** @returns {string|null} the act id owning tab `n`, or null. */ +export function actForTab(n) { + return Object.prototype.hasOwnProperty.call(ACT_BY_TAB, n) ? ACT_BY_TAB[n] : null; +} + +/** @returns {number[]} the tab indices in an act, in display order. */ +export function tabsForAct(id) { + const a = ACTS.find((x) => x.id === id); + return a ? a.tabs : []; +} diff --git a/output-tab.html b/output-tab.html index 43cbcfc..24a5c13 100644 --- a/output-tab.html +++ b/output-tab.html @@ -70,6 +70,13 @@ .tab-btn:hover { color: var(--text-sub); } .tab-btn.active { color: var(--accent); border-bottom-color: var(--accent); } + .act-nav { background: var(--surface); border-bottom: 1px solid var(--border); padding: 0 32px; display: flex; gap: 4px; } + .act-tab { padding: 14px 20px; font-size: 13px; font-weight: 700; letter-spacing: -0.01em; color: var(--text-faint); cursor: pointer; background: none; border: none; border-bottom: 2px solid transparent; transition: color var(--dur-fast) var(--ease-out), border-color var(--dur-fast) var(--ease-out); } + .act-tab:hover { color: var(--text-sub); } + .act-tab.active { color: var(--accent); border-bottom-color: var(--accent); } + .act-subnav { background: var(--surface-alt); border-bottom: 1px solid var(--border); padding: 8px 32px; display: flex; gap: 4px; flex-wrap: wrap; } + .act-subnav:empty { display: none; } + /* Grouped tab menus (Lenses / Library) — chunked to cut nav clutter */ .tab-menu { position: relative; } .tab-menu-btn { padding: 14px 16px; font: 600 12px/1 inherit; color: var(--text-faint); cursor: pointer; background: none; border: none; border-bottom: 2px solid transparent; white-space: nowrap; } @@ -303,7 +310,7 @@ .sk-row .sub { width: 100%; color: var(--text-sub); font-size: 12px; line-height: 1.5; margin-top: 2px; } /* Decision Log */ - .dl-block { margin-top: 28px; border-top: 1px solid var(--border); padding-top: 20px; } + .dl-block { margin: 16px 0; } .dl-label { font-size: 10px; font-weight: 700; letter-spacing: 1.5px; text-transform: uppercase; color: var(--text-faint); margin-bottom: 12px; } .dl-choices { display: flex; gap: 8px; flex-wrap: wrap; margin-bottom: 12px; } .dl-btn { padding: 6px 16px; border-radius: 999px; font-size: 12px; font-weight: 600; cursor: pointer; border: 1px solid var(--border-2); background: var(--surface); color: var(--text-sub); transition: background var(--dur-fast) var(--ease-out), color var(--dur-fast) var(--ease-out), border-color var(--dur-fast) var(--ease-out), transform var(--dur-fast) var(--ease-out); } @@ -841,48 +848,9 @@
- -
- - - - - - - - - - - - - -
+ + +
diff --git a/output-tab.js b/output-tab.js index 1352507..cc40812 100644 --- a/output-tab.js +++ b/output-tab.js @@ -39,6 +39,7 @@ import { snapshotTrend, sparkline } from './snapshots.js'; import { introStageB, COPY } from './onboarding.js'; import { startCoachmark } from './coachmark.js'; import { clearDemoEverywhere, isDemo } from './demo-repo.js'; +import { ACTS, TAB_LABELS, actForTab, tabsForAct } from './output-acts.js'; // Apply the saved theme ASAP (before render) to minimise flash. initTheme(); @@ -364,6 +365,8 @@ async function init() { initOutputPalette(data); // Restore tab: URL hash takes priority (explicit intent), then per-repo memory. + // Default landing (no hash, no stored tab) = Decide, with its act-tab marked + // active so routing state is consistent on first view. const hashTab = SLUG_TO_TAB[location.hash.slice(1)]; if (hashTab != null) { show(hashTab, { updateHash: false }); @@ -371,7 +374,10 @@ async function init() { chrome.storage.local.get(`repolens_tab_${data.repoId}`).then((res) => { const stored = res[`repolens_tab_${data.repoId}`]; if (stored != null && stored !== 9) show(stored, { updateHash: true }); - }).catch(() => {}); + else show(9, { updateHash: false }); + }).catch(() => show(9, { updateHash: false })); + } else { + show(9, { updateHash: false }); } // Header logo becomes Vee, reacting to the verdict (one-shot pop/squint on mount). @@ -811,7 +817,12 @@ function renderHighlights(d) { } host.querySelectorAll('.hl-row.clickable').forEach(row => { - row.addEventListener('click', () => show(Number(row.dataset.jump))); + row.addEventListener('click', () => { + const n = Number(row.dataset.jump); + show(n); + const behavior = matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth'; + document.getElementById('t' + n)?.scrollIntoView({ behavior, block: 'start' }); + }); }); } @@ -1926,7 +1937,7 @@ function verdictDashboard(d) { : ''; const jump = (id, label) => ``; - const jumps = `
${jump(7, "Why it's " + (score >= 70 ? 'healthy' : 'mixed'))}${jump(8, 'What to watch')}${jump(6, 'Alternatives')}${jump(10, 'Deep Dive')}
`; + const jumps = `
${jump(7, "Why it's " + (score >= 70 ? 'healthy' : 'mixed'))}${jump(8, 'What to watch')}${jump(15, 'Tech Stack')}${jump(6, 'Alternatives')}${jump(10, 'Deep Dive')}
`; const diff = d.diff; const diffCallout = (() => { @@ -1958,6 +1969,7 @@ function verdictDashboard(d) {

${what}

${esc(fit.label)}${esc(fit.why)}
${line} +
${cells}
${flags} ${entries} @@ -2108,7 +2120,10 @@ async function renderDecisionControl(d) { `; - host.appendChild(block); + // Anchor near the top of Decide (after fit + bottom line); fall back to host end. + const anchor = host.querySelector('#vd-decision-anchor'); + if (anchor) anchor.appendChild(block); + else host.appendChild(block); let selected = existing?.decision || null; @@ -2207,18 +2222,69 @@ const TAB_SLUGS = { }; const SLUG_TO_TAB = Object.fromEntries(Object.entries(TAB_SLUGS).map(([k, v]) => [v, Number(k)])); +// Two-tier act nav: a primary row of acts, and a secondary row of the active +// act's tabs. Both are generated from the act model so the grouping has one +// source of truth. Buttons keep `data-tab` so the existing show() path is reused. +function renderActNav() { + const nav = document.getElementById('act-nav'); + if (!nav) return; + nav.innerHTML = ACTS.map( + (a) => ``, + ).join(''); +} + +function renderSubNav(actId) { + const sub = document.getElementById('act-subnav'); + if (!sub) return; + const tabs = tabsForAct(actId); + // A single-tab act (Decide) needs no secondary row. + sub.innerHTML = tabs.length <= 1 + ? '' + : tabs.map((n) => ``).join(''); + + if (actId === 'deeper') { + sub.insertAdjacentHTML('afterbegin', + ``); + } + + // Mark scan buttons that have an explainer with a subtle ⓘ (per-render, so + // freshly-rendered subnav buttons get one; the tip listeners in initScanTips + // delegate from #act-subnav and survive this re-render). + sub.querySelectorAll('.tab-btn[data-tab]').forEach((btn) => { + if (explainerFor(btn.dataset.tab) && !btn.querySelector('.tip-i')) { + const i = document.createElement('span'); + i.className = 'tip-i'; + i.textContent = 'ⓘ'; + btn.appendChild(i); + } + }); + + // The Go-Deeper subnav owns the SKTPG button; re-apply its visibility setting + // now that #tab-sktpg has just been (re)rendered, so an off-toggle still hides it. + if (actId === 'deeper' && typeof applySktpgVisibility === 'function') applySktpgVisibility(); +} + function show(n, { updateHash = true } = {}) { - document.querySelectorAll('.tab-btn').forEach(b => b.classList.toggle('active', Number(b.dataset.tab) === n)); - document.querySelectorAll('.tab-content').forEach((c, idx) => c.classList.toggle('active', idx === n)); - // Blueprint canvas mounts lazily on every activation path (click, #hash deep-link, per-repo restore). - // renderCanvas is idempotent (dataset.mounted guard) and null-safe, so calling it on each show(27) is cheap. + // Active tab button (in the secondary row) + active panel (by id, not DOM order). + document.querySelectorAll('.tab-btn').forEach((b) => b.classList.toggle('active', Number(b.dataset.tab) === n)); + document.querySelectorAll('.tab-content').forEach((c) => c.classList.remove('active')); + document.getElementById(`t${n}`)?.classList.add('active'); + + // Active act: highlight it and render its secondary row (if not already shown). + const actId = actForTab(n); + document.querySelectorAll('.act-tab').forEach((b) => b.classList.toggle('active', b.dataset.act === actId)); + const sub = document.getElementById('act-subnav'); + if (sub && sub.dataset.act !== actId) { + renderSubNav(actId); + sub.dataset.act = actId || ''; + } + // Re-mark the active secondary button after a possible re-render. + document.querySelectorAll('#act-subnav .tab-btn').forEach((b) => b.classList.toggle('active', Number(b.dataset.tab) === n)); + + // Blueprint canvas mounts lazily on every activation path (idempotent + null-safe). if (n === 27) renderCanvas(lastData).catch((err) => console.error('[canvas] render failed', err)); - // Reflect the active tab on its parent menu button + close any open menus. - document.querySelectorAll('.tab-menu').forEach(m => { - const owns = [...m.querySelectorAll('.tab-btn')].some(b => Number(b.dataset.tab) === n); - m.querySelector('.tab-menu-btn')?.classList.toggle('active', owns); - m.classList.remove('open'); - }); + if (updateHash && TAB_SLUGS[n]) { history.replaceState(null, '', `#${TAB_SLUGS[n]}`); } @@ -2227,47 +2293,34 @@ function show(n, { updateHash = true } = {}) { } } -// Nav clicks: open/close a grouped menu, run-all, or switch tab. -document.querySelector('.tab-nav')?.addEventListener('click', e => { - const menuBtn = e.target.closest('.tab-menu-btn'); - if (menuBtn) { - const menu = menuBtn.closest('.tab-menu'); - const wasOpen = menu.classList.contains('open'); - document.querySelectorAll('.tab-menu').forEach(m => m.classList.remove('open')); - if (!wasOpen) menu.classList.add('open'); - return; - } - if (e.target.closest('#run-all-lenses')) { runAllLenses(); return; } - const btn = e.target.closest('[data-tab]'); - if (btn) { - const n = Number(btn.dataset.tab); - show(n); - if (n === 19) renderConnections(lastData); // network tab — pull fresh on each open (like Similar) - // (canvas, tab 27, is dispatched inside show() so deep-link/restore paths render it too) - } +// Primary act row: clicking an act shows its first tab. +document.getElementById('act-nav')?.addEventListener('click', (e) => { + const btn = e.target.closest('.act-tab'); + if (!btn) return; + const first = tabsForAct(btn.dataset.act)[0]; + if (first != null) show(first); }); -// Close menus on an outside click. -document.addEventListener('click', e => { - if (!e.target.closest('.tab-nav')) document.querySelectorAll('.tab-menu').forEach(m => m.classList.remove('open')); +// Secondary row: clicking a tab switches panels (same contract as before). +document.getElementById('act-subnav')?.addEventListener('click', (e) => { + if (e.target.closest('#run-all-lenses')) { runAllLenses(); return; } + const btn = e.target.closest('[data-tab]'); + if (!btn) return; + const n = Number(btn.dataset.tab); + show(n); + if (n === 19) renderConnections(lastData); // Connections: pull fresh on each open }); // Scan explainers: a styled "when to use / skip" tooltip on each on-demand scan // button, shown on hover OR keyboard focus. Static copy lives in explainers.js. function initScanTips() { const tip = document.getElementById('scan-tip'); - const nav = document.querySelector('.tab-nav'); + const nav = document.getElementById('act-subnav'); if (!tip || !nav) return; - // Mark scan buttons that have an explainer with a subtle ⓘ. - nav.querySelectorAll('.tab-btn[data-tab]').forEach(btn => { - if (explainerFor(btn.dataset.tab) && !btn.querySelector('.tip-i')) { - const i = document.createElement('span'); - i.className = 'tip-i'; - i.textContent = 'ⓘ'; - btn.appendChild(i); - } - }); + // ⓘ markers are added per-render in renderSubNav() so freshly-rendered + // subnav buttons get one; the listeners below delegate from the persistent + // #act-subnav element, so they survive each subnav re-render. const showFor = (btn) => { const e = explainerFor(btn.dataset.tab); @@ -2297,6 +2350,7 @@ function initScanTips() { nav.addEventListener('focusout', hide); } initScanTips(); +renderActNav(); // ─── "?" Guide overlay — feature discovery on demand ────────────────────────── // One small button; the overlay explains scanning, the tabs, every lens (from @@ -2393,8 +2447,18 @@ document.getElementById('copy-url')?.addEventListener('click', async () => { await copyWithFlash(document.getElementById('copy-url'), url); }); -document.getElementById('open-library')?.addEventListener('click', () => { - chrome.tabs.create({ url: chrome.runtime.getURL('library.html') }); +// Return path (output → library): focus an existing Library tab if one is open, +// otherwise open a fresh one. Mirrors background.js's focus-or-create idiom so the +// library ↔ output round-trip never orphans duplicate Library tabs. +document.getElementById('open-library')?.addEventListener('click', async () => { + const libUrl = chrome.runtime.getURL('library.html'); + const [existing] = await chrome.tabs.query({ url: libUrl }); + if (existing) { + await chrome.tabs.update(existing.id, { active: true }); + await chrome.windows.update(existing.windowId, { focused: true }); + } else { + chrome.tabs.create({ url: libUrl }); + } }); const CURRENT_VERSION = '3.0.0'; diff --git a/tests/output-acts.test.js b/tests/output-acts.test.js new file mode 100644 index 0000000..47d9d10 --- /dev/null +++ b/tests/output-acts.test.js @@ -0,0 +1,35 @@ +import { describe, it, expect } from 'vitest'; +import { ACTS, ACT_ORDER, TAB_LABELS, actForTab, tabsForAct } from '../output-acts.js'; + +describe('act model', () => { + it('orders the four acts', () => { + expect(ACT_ORDER).toEqual(['decide', 'understand', 'deeper', 'act']); + }); + + it('covers every tab index 0..27 exactly once', () => { + const all = ACTS.flatMap((a) => a.tabs).sort((x, y) => x - y); + expect(all).toEqual(Array.from({ length: 28 }, (_, i) => i)); + expect(new Set(all).size).toBe(28); // no duplicates + }); + + it('maps a tab to its owning act', () => { + expect(actForTab(9)).toBe('decide'); + expect(actForTab(7)).toBe('understand'); // Health + expect(actForTab(10)).toBe('deeper'); // Deep Dive + expect(actForTab(17)).toBe('act'); // Versus + expect(actForTab(99)).toBeNull(); + }); + + it('lists tabs for an act in display order', () => { + expect(tabsForAct('decide')).toEqual([9]); + expect(tabsForAct('understand')[0]).toBe(0); // ELI5 leads + expect(tabsForAct('nope')).toEqual([]); + }); + + it('has a label for every tab it groups', () => { + for (const t of ACTS.flatMap((a) => a.tabs)) { + expect(typeof TAB_LABELS[t]).toBe('string'); + expect(TAB_LABELS[t].length).toBeGreaterThan(0); + } + }); +});