feat: add reproducible Meticulous recording suite

[ryota-murakami]

Summary

• add a dedicated Playwright ingestion suite for 10 Coffee Timer journeys and flush each recording before teardown
• document how Meticulous sessions become Selected Sessions and run in CI
• harden the Meticulous workflow for Next.js companion assets and skip fork/Dependabot PRs without secrets
• fix PWA shortcut startup so the timer does not block on Web Audio without a user gesture

Recorded journeys

• duration editing and stepper boundaries
• start, pause, resume, reset, completion, and restart
• six deterministic themes
• sound, volume, notification toggle, and test notification
• Japanese locale
• rejected sign-in and sign-up navigation
• PWA start/settings shortcuts
• mobile timer/settings controls

Verification

• pnpm meticulous:record — 10/10 passed for the full suite; updated flows re-recorded after review
• pnpm lint
• pnpm typecheck
• pnpm build
• pnpm exec playwright test e2e/pwa-shortcuts.spec.ts e2e/timer-behavior.spec.ts --project="Desktop Chrome" — 9 passed, 1 skipped

Meticulous Dashboard: https://app.meticulous.ai/projects/laststance/coffee-timer?tab=selected-sessions

Summary by CodeRabbit

• New Features
  • Added a dedicated automated Meticulous recording workflow and test project for key user journeys.
  • Added a new Meticulous recording command for running those sessions.
• Bug Fixes
  • PWA “start” shortcut now begins the timer immediately and reliably.
• Documentation
  • Added a full guide for configuring, recording, and validating Meticulous sessions in CI.
• Testing
  • Added E2E coverage for timer controls, themes, sounds, notifications, language switching, authentication, and PWA shortcut screens (desktop + mobile).
  • Ensured Meticulous recording tests don’t run in the standard Playwright suite.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
coffee-timer	Ready	Preview, Comment	Jul 16, 2026 8:57am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 639a1e26-d7ac-4c33-81fe-e0ff9c51d5dc

📥 Commits

Reviewing files that changed from the base of the PR and between 6302fbc and 132e8dd.

📒 Files selected for processing (4)

• .github/workflows/meticulous.yml
• docs/meticulous.md
• e2e/pwa-shortcuts.spec.ts
• proxy.ts

---

📝 Walkthrough

Walkthrough

Adds Meticulous recording infrastructure, dedicated Playwright journeys, PWA shortcut coverage, synchronous shortcut startup, CI gating, and recording workflow documentation.

Changes

Meticulous recording and E2E coverage

Layer / File(s)	Summary
PWA shortcut behavior app/[locale]/page.tsx, proxy.ts, e2e/pwa-shortcuts.spec.ts	Shortcut routes bypass middleware processing, the start shortcut starts synchronously, and settings/start flows receive browser coverage.
Recorder contracts and lifecycle e2e/meticulous/constants.ts, e2e/meticulous/meticulous-window.d.ts, e2e/meticulous/recording-helpers.ts	Adds recorder types and constants, readiness polling, session flushing, and Playwright session URL attachments.
Dedicated recording project and journeys playwright.meticulous.config.ts, e2e/meticulous/recording.spec.ts, package.json, playwright.config.ts	Adds a headed recording project, a recording command, excluded ingestion tests, and ten focused application journeys.
Meticulous CI workflow and documentation .github/workflows/meticulous.yml, docs/meticulous.md	Gates CI for unsupported pull requests and documents recorder setup, session ingestion, CI requirements, and workflow configuration.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RecordingSuite as Playwright recording suite
  participant App as Coffee Timer app
  participant Recorder as Meticulous recorder
  participant TestInfo as Playwright TestInfo
  RecordingSuite->>App: Open journey with recording query
  App->>Recorder: Expose window.Meticulous.record
  RecordingSuite->>App: Execute user flow
  RecordingSuite->>Recorder: Read session URL and flush events
  Recorder-->>TestInfo: Attach session URL

Loading

Possibly related PRs

• laststance/coffee-timer#28: Adds the Meticulous recorder snippet and related application/workflow wiring used by the new recording harness.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding a reproducible Meticulous recording suite.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/meticulous-recordings-ci

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/meticulous.yml:
- Around line 20-23: Replace github.actor with
github.event.pull_request.user.login in the Dependabot skip gate in
.github/workflows/meticulous.yml lines 20-23 and the corresponding documented
example in docs/meticulous.md lines 163-166, preserving the existing conditions
and behavior.

In `@e2e/pwa-shortcuts.spec.ts`:
- Line 8: Update the shortcut navigation steps in the PWA shortcut tests to open
the actual /shortcuts/settings and /shortcuts/start endpoints instead of
directly using the query-string action route. Keep the existing post-redirect UI
assertions unchanged so the tests validate both shortcut routing and resulting
screens.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 24a32938-6e36-4b09-bead-5207656d4c5d

📥 Commits

Reviewing files that changed from the base of the PR and between 60ea897 and 6302fbc.

📒 Files selected for processing (11)

• .github/workflows/meticulous.yml
• app/[locale]/page.tsx
• docs/meticulous.md
• e2e/meticulous/constants.ts
• e2e/meticulous/meticulous-window.d.ts
• e2e/meticulous/recording-helpers.ts
• e2e/meticulous/recording.spec.ts
• e2e/pwa-shortcuts.spec.ts
• package.json
• playwright.config.ts
• playwright.meticulous.config.ts

[alwaysmeticulous]

✅ Meticulous spotted 0 visual differences across 142 screens tested: view results.

Meticulous evaluated ~2 hours of user flows against your PR.

_{Expected differences? Click here. Last updated for commit 132e8dd fix: resolve CodeRabbit Meticulous feedback. This comment will update as new commits are pushed.}