test(e2e): assert sidebar folder alignment guides by measured x (#3914)

[iamwhatever]

Problem / Motivation

The chat sidebar's three left-edge alignment guides — folder glyph on its connector line; folder name on the agent label / title / subtitle of the sessions inside it; a nested folder's glyph on its sibling sessions' content column — have been broken four times (#1211, #3766, #3903, and twice on paper inside the fix for #3766, PR #3905). Every break was a Tailwind-class derivation that omitted the 2px FOLDER_BODY_INSET_PX container differential between the folder header's box and the nested body's box. Nothing in the class list expresses that 2px, and ChatSidebar.folderAlignment.test.tsx cannot catch it: jsdom has no layout engine, so the file asserts the inputs (class tokens) plus an arithmetic identity whose terms are constants declared in the test itself — it stayed green through every regression.

Why it matters

The alignment guides are the sidebar's visual grammar: when they drift, folders stop reading as heads of their subtrees and nested folders float off their siblings' column. Each of the four regressions shipped a visibly misaligned sidebar and cost a rediscovery-plus-refix cycle, because the only geometry check ran in an engine that cannot measure geometry.

What changed (motivation → approach → change)

Symptom: class-derivation regressions invisible to jsdom. Root cause: no test measures the rendered x-coordinates. Change: add a Playwright spec to the E2E (stub ACP backend, offline) gate — which already runs a real browser against a seeded harness gateway — that seeds one folder, one subfolder, sessions in both, and one ungrouped session via the gateway API, then asserts the guides on getBoundingClientRect().left of the real elements:

• Guide 1: folder glyph on its border-l connector line (depth 1 and 2)
• Guide 2: folder name on the agent label / title of its sessions (depth 1 and 2)
• Guide 3: nested folder glyph on its sibling sessions' content column, plus the root-lane identity (ungrouped session content on the root folder's glyph)
• Depth invariance: the depth-2 connector sits on depth 1's content column

Difference assertions are anchored (root glyph at x>0, indentation strictly increasing with depth) so they cannot hold vacuously on box-less nodes. Seeding requests assert response.ok(), so a seeding 4xx fails as a seeding fault rather than an alignment fault. The settle poll doubles as the render wait and names any selector that never resolves (missing: [aAgent, ...]) instead of timing out bare. The spec seeds and deletes only its own fixtures — no harness-wide wipes.

The tool-call subtitle is not asserted: it requires a live agent turn to render, is a sibling of the title inside the same block container (equal left by construction), and its class parity is pinned by the jsdom test. MIN_EXECUTED_SPECS in test/test_playwright_e2e.py is raised 219 → 220 for the added spec.

Tests

• website/playwright/sidebar-folder-alignment.spec.ts (new): the nine measured-x assertions above, plus three absolute anchors.
• Falsified against the historical regression class: rebuilding the SPA with FOLDER_BODY_INSET_PX mutated 2 → 4 fails the spec with guide 1 depth 1 (glyph on connector): fGlyph=259 vs fConnector=261 while the jsdom test stays green. The missing-selector diagnostics were falsified the same way (a deliberately broken selector fails with missing: [aAgent, aTitle, bAgent, bTitle, uAgent]).

Manual verification

Ran the spec against the same isolated harness the CI gate uses (spawn_feature_gateway + fake ACP backend, throwaway home): green on clean main, red under the injected 2px mutation, green again after revert. Frontend gates (npx tsc -b, npx vitest run — one pre-existing CliPanelCoverage flake, passes in isolation) and backend gates (isort / flake8 / mypy / targeted pytest of the floor-helper tests) all pass.

Why no screenshot: test-only change — a new Playwright spec and a test constant bump; no rendered pixel changes.

Related Issues

Closes #3914

Checklist

• Single commit with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
• Existing tests pass and new tests added for new functionality
• Self-review completed; code follows project style guidelines
• Documentation updated (if applicable)
• No secrets, credentials, or internal references in the diff

[github-actions]

UX Review (Fable 5) — ✅ PASS

Advisory UX-level review of fba36407f7a558511bd7ae42f03161277fa54ae6 — updated in place on each push; does not block merge.

The diff touches only two test files — a new Playwright spec and the executed-spec floor bump. No component code, no user-facing strings, no rendered pixels change. The spec itself exists to protect a UX property (the sidebar's alignment guides) that regressed four times. Nothing in this PR reaches a user's screen, so there is no UX surface to fault.

UX-Verdict: PASS

Test-only change with zero rendered-pixel delta; it adds the first real-geometry guard for a sidebar alignment that shipped broken four times.

[UX-REVIEWED] fba3640

[github-actions]

Design Review (Fable 5) — ✅ PASS

Advisory design-level review of fba36407f7a558511bd7ae42f03161277fa54ae6 — updated in place on each push; does not block merge.

Design-Verdict: PASS

Right layer for a geometry invariant: the fourth-time regression is finally asserted on rendered pixels, in the existing offline E2E gate, with fail-loud diagnostics.

Suggestions

• The spec locates guide elements via structural/Tailwind selectors (.border-l.border-border, span.flex-1, nextElementSibling); a data-testid on the connector, name, and title nodes would keep a markup refactor from failing the spec as "missing selector" when alignment is actually fine — a tiny non-visual product change worth folding in here or immediately after.

[DESIGN-REVIEWED] fba3640

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of fba36407f7a558511bd7ae42f03161277fa54ae6 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fba3640

False positive or not applicable? A repository writer can comment:
/ai-review override gpt fba36407f7a558511bd7ae42f03161277fa54ae6: <one-sentence reason>

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed fba36407f7a558511bd7ae42f03161277fa54ae6 — this comment is updated in place on each push.

Review details

This is a test-only PR: a MIN_EXECUTED_SPECS bump (219→220) and one new Playwright spec. No production code paths change, so there is no reachable security/crash/data-loss/corruption surface. The spec seeds only its own resources and tears them down in afterEach (deleting only IDs it created), and the no-test-side-effects rule matches Python test/**/*.py, not this .spec.ts. Nothing to falsify in the empty candidate list, and no grounded Step-2 finding survives the 80+ bar.

No findings.

[OPUS-REVIEWED] fba3640

Verdict parsed from the review's SHA-scoped output markers for commit fba36407f7a558511bd7ae42f03161277fa54ae6.

False positive or not applicable? A repository writer can comment:
/ai-review override fable fba36407f7a558511bd7ae42f03161277fa54ae6: <one-sentence reason>

[bolichen97]

Tier 1 auto-approve: test (2 files). Criteria: no conflict, no requested changes, security path denylist clean, SAST annotations clean, security checklist all-NO, AI reviewers green. Category: e2e test asserting sidebar folder alignment guides by measured x-coordinate.

[bolichen97]

Tier 1 auto-approve: test (2 files). Criteria: no conflict, no requested changes, security path denylist clean, SAST annotations clean, security checklist all-NO, AI reviewers green. Category: e2e test asserting sidebar folder alignment pixel guides, no production code changes.