[ShuhaoZQGG]

Closes #90

Why

In Simple Format import the role was detected from the whole line, so keywords in the speaker's name beat the role written in parentheses: Tim Timer (Standard Speech) imported as Short Roles ("timer"), and Dominique - General Evaluation (Table Topics) as General Evaluation. #77 already made a custom role in the bracket win; this is the built-in half.

What changes

• A line's role is now resolved in this order: custom role matched against the bracket, then the bracket's own built-in keywords, then the whole line (the old behaviour, kept as the last fallback for lines with no useful bracket).
• detectRoleFromText takes an optional fallback (default 'Standard Speech', so every other caller is unchanged); the parser passes null to fall through to the whole line.
• Side effect, as the plan intends: a loose keyword in the bracket now beats a more specific name, e.g. Dominique - Table Topics Master (Speaker 1) becomes Standard Speech.
• Spec agenda-import gains IM-05 and a needs line (built-in roles not hidden).

Security

None. Client-side parsing only.

Production impact

The shared parser runs in both the Zoom app and the web app; after release, master users get bracket-first detection on Simple Format import. No flags, no migration. Rollback is a revert.

Testing

• npm test: 2225 pass (verify station); CI test pass on cf14fc5
• npm run test:e2e: 42 pass (verify station), incl. "the bracket's built-in role beats the name (Simple Format import: words in the speaker name override the role in parentheses #90)"
• npm run test:specs: valid (7 specs)
• Oracle: .factory/oracles/90.json — simpleFormatParser.test.js AC-1/AC-2 fail on the old parser, AC-3/AC-4 guard current behaviour; e2e/zoom.timer-flow.spec.js Simple Format import: words in the speaker name override the role in parentheses #90 test

Evidence (real Zoom client)

Run 2026-11-11 16:39–16:51 EST, Zoom 7.2.5 on macOS 26.7.2, dev version c80dca2b (this branch @ 0ba1f1c, committed vars). Spec agenda-import, IM-01…IM-05.

• IM-01 ✅ three custom roles saved; dropdown lists Opening, Closing Remarks, Hand over in order.
• IM-02 ✅ paste into the real webview → "Imported 6 speaker(s)"; rows Opening · Closing Remarks · Closing Remarks · Hand over · Ice Breaker · Short Roles, all as specified. PostHog agenda_imported 21:44:27 UTC from zoom.timer-dev.simple-tech.app: import_type: bulk, items_count: 6, custom_role_count: 4.
• IM-03 ✅ "Cam-Ly - Opening" drives the real video: no colour at 0:08, GREEN at 0:20, YELLOW at 0:36, RED at 0:50 (Opening's 15/30/45 s).
• IM-04 ✅ FINISH, Clear All, test roles removed.
• IM-05 ⚠️ the Simple Format import: words in the speaker name override the role in parentheses #90 fix itself passes: Tim Timer (Standard Speech) → Standard Speech, Dominique - General Evaluation (Table Topics) → Table Topics ("Imported 2 speaker(s)"; PostHog agenda_imported bulk/2/0). The Live-tab half could not be checked, see below.

Not verified

• IM-05 Live tab (Standard Speech 5/6/7 min): the test device hides the built-in roles, so its dropdown has no Standard Speech; selecting the row loaded ChairToast1 (0:30/0:45/1:00). That fallback is LiveTab.jsx behaviour from e876ca8, not this diff. The plain-browser Playwright test covers it. Spec needs now says built-ins must be visible.
• Pre-existing finding (not this PR): an agenda row whose role is a hidden built-in is timed with the first listed role, with no notice, while the row still shows its original role. Noted under the spec's Not covered.
• IM-03's count of setVirtualBackground calls and all localStorage reads: Zoom's webview inspector is off on this Mac, so on-screen rows, the request log and PostHog stood in.
• The test device kept its 17 existing custom roles (user data) instead of starting clean; the branch parser run with that exact list gives the same results as a clean device.

Look here first

• packages/shared/simpleFormatParser.js:92-96 — the new resolution order
• packages/shared/timingRules.js:69-70 — the fallback parameter (default unchanged)

[ShuhaoZQGG]

plan — Since #77 a custom role in the brackets already wins, so only the built-in half of #90 is left: when the bracket names no custom role, detection runs on the whole line and a keyword in the name (Tim Timer, Dominique - General Evaluation) beats the bracket's built-in role. The fix tries the bracket's own keywords before falling back to the whole line, via an optional fallback parameter on detectRoleFromText (default unchanged for every other caller). Five acceptance criteria; oracle tests at the unit, Playwright and Zoom-client (new IM-05) layers.

Open questions (defaults apply if you just add plan:approved):

• Q1. Tim Timer (Pathways L2): the bracket has no role words. Keep today's whole-line detection (Short Roles)? Default: yes.
• Q2. Ice Breaker - Ana (Speaker 1): the bracket wins (Standard Speech)? Default: yes.

[ShuhaoZQGG]

plan gate — Approved by @ShuhaoZQGG in chat. Q1 and Q2 take the plan's defaults (yes to both).

[ShuhaoZQGG]

plan gate — The first build run (42438263153) failed at Install, before Claude started. When this PR was retargeted to dev, GitHub kept its merge ref on the old base, so the run used the old workflow (ubuntu-latest, which Playwright 1.58 doesn't support). The branch is now updated with dev, and plan:approved was re-added to start the build again.

[claude]

oracle —

• simpleFormatParser.test.js AC-1 (Tim Timer (Standard Speech)): fails now, gets Short Roles.
• same file AC-2 (General Evaluation (Table Topics)): fails now, gets General Evaluation.
• AC-3 (Person (A), Tim Timer (Pathways L2)) and AC-4 (custom Closing): pass now, guard current behaviour.
• e2e/zoom.timer-flow.spec.js "the bracket's built-in role beats the name (Simple Format import: words in the speaker name override the role in parentheses #90)": fails on the row-role assertion (wrong roles shown).
• agenda-import IM-05 (AC-5) added, spec set to status: stale for factory-zoom. test:specs passes.

[claude]

implement — detectRoleFromText takes an optional fallback (default 'Standard Speech'; null returns null when nothing matched), and parseSimpleFormatText now tries custom role, then the bracket's built-in keywords, then the whole line. Added unit tests for fallback in timingRules.test.js. Oracle tests, npm test (2225) and the zoom-flow Playwright spec pass; test:specs valid. IM-05 still needs the real Zoom run.

[claude]

verify — npm test (2225 pass), test:e2e (42 pass), test:specs, check-oracle, build all pass; CI test passes. No riskHigh paths touched. Fresh-context review: no blocking findings. AC-1/AC-2 tests fail on the old parser; AC-3/AC-4 are intentional regression guards; AC-5 awaits the real-Zoom run (agenda-import IM-05, status stale). Note for the report: a loose keyword in the bracket now beats a more specific name (e.g. Dominique - Table Topics Master (Speaker 1) becomes Standard Speech), as the plan intends. No fix rounds needed. Handing off with needs:zoom-test.

[ShuhaoZQGG]

zoom — Waiting. The 17:00 run deployed this branch (0ba1f1c) to dev (version c80dca2b) and started Zoom, but the Mac's screen was locked, so no agenda-import step ran (unlocking needs a password). zoom:testing is removed and needs:zoom-test stays; the next scheduled run, or /factory-zoom 130 with the screen unlocked, picks it up.