From 6302fbc7595afa0003c2ae770234495161d58017 Mon Sep 17 00:00:00 2001
From: Ryota Murakami <dojce1048@gmail.com>
Date: Thu, 16 Jul 2026 16:50:01 +0900
Subject: [PATCH 1/3] feat: add reproducible Meticulous recording suite

---
 .github/workflows/meticulous.yml      |  12 ++
 app/[locale]/page.tsx                 |  17 +-
 docs/meticulous.md                    | 231 +++++++++++++++++++++++
 e2e/meticulous/constants.ts           |   7 +
 e2e/meticulous/meticulous-window.d.ts |  10 +
 e2e/meticulous/recording-helpers.ts   |  62 +++++++
 e2e/meticulous/recording.spec.ts      | 258 ++++++++++++++++++++++++++
 e2e/pwa-shortcuts.spec.ts             |  29 +++
 package.json                          |   1 +
 playwright.config.ts                  |   2 +
 playwright.meticulous.config.ts       |  33 ++++
 11 files changed, 648 insertions(+), 14 deletions(-)
 create mode 100644 docs/meticulous.md
 create mode 100644 e2e/meticulous/constants.ts
 create mode 100644 e2e/meticulous/meticulous-window.d.ts
 create mode 100644 e2e/meticulous/recording-helpers.ts
 create mode 100644 e2e/meticulous/recording.spec.ts
 create mode 100644 e2e/pwa-shortcuts.spec.ts
 create mode 100644 playwright.meticulous.config.ts

diff --git a/.github/workflows/meticulous.yml b/.github/workflows/meticulous.yml
index ed3db30..739c664 100644
--- a/.github/workflows/meticulous.yml
+++ b/.github/workflows/meticulous.yml
@@ -17,6 +17,10 @@ permissions:
 
 jobs:
   test:
+    if: >-
+      github.event_name != 'pull_request' ||
+      (github.event.pull_request.head.repo.full_name == github.repository &&
+      github.actor != 'dependabot[bot]')
     runs-on: ubuntu-latest
     timeout-minutes: 30
 
@@ -42,6 +46,12 @@ jobs:
           NODE_ENV: production
           METICULOUS_BUILD: 'true'
 
+      # Serve immutable Next.js chunks directly to make visual replays faster and steadier.
+      - name: Prepare companion assets
+        run: |
+          mkdir -p companion-assets/_next
+          cp -r .next/static companion-assets/_next/
+
       - name: Start app
         run: |
           pnpm start &
@@ -52,3 +62,5 @@ jobs:
         with:
           api-token: ${{ secrets.METICULOUS_API_TOKEN }}
           app-url: 'http://localhost:3009'
+          companion-assets-folder: 'companion-assets'
+          companion-assets-regex: '^/_next/static/'
diff --git a/app/[locale]/page.tsx b/app/[locale]/page.tsx
index db33e19..55fc75b 100644
--- a/app/[locale]/page.tsx
+++ b/app/[locale]/page.tsx
@@ -86,20 +86,9 @@ const Home = memo(function Home() {
   )
   useTimerSessionSave(timeRemaining, initialTime, soundPreset, userSetTimeRef)
 
-  // Start timer from PWA shortcut (separate function to handle async)
-  const handleStartFromShortcut = useCallback(async () => {
-    try {
-      await audioManager.initialize()
-      const currentPreset = useSettingsStore.getState().soundPreset
-      if (currentPreset !== 'none') {
-        await audioManager.preload(currentPreset)
-      }
-      useTimerStore.getState().start()
-    } catch (error) {
-      console.error('[Shortcut] Failed to start timer:', error)
-      // Still try to start timer even if audio fails
-      useTimerStore.getState().start()
-    }
+  /** Starts a PWA shortcut timer synchronously because ShortcutHandler has no gesture to unlock Web Audio. @returns Nothing; the timer store is updated immediately. @example handleStartFromShortcut() */
+  const handleStartFromShortcut = useCallback(() => {
+    useTimerStore.getState().start()
   }, [])
 
   // Open settings callback for PWA shortcut (memoized for ShortcutHandler)
diff --git a/docs/meticulous.md b/docs/meticulous.md
new file mode 100644
index 0000000..b68e10d
--- /dev/null
+++ b/docs/meticulous.md
@@ -0,0 +1,231 @@
+# Meticulous recording and CI guide
+
+This note records the current Meticulous behavior and the recommended setup for Coffee Timer. It is based only on Meticulous's official documentation and official `alwaysmeticulous` repositories, plus GitHub's official documentation for fork-secret behavior.
+
+## Executive summary
+
+- A recording is a **session**, but not every recorded session is automatically part of the CI test suite. Meticulous continuously chooses a coverage-maximizing subset called **Selected Sessions**. A critical flow can be forced into the suite with **Add to selected sessions**. [Manual recording](https://app.meticulous.ai/docs/how-to/manually-recording-tests) · [Session selection](https://app.meticulous.ai/docs/how-to/testing-pool)
+- The recorder should be a synchronous native `<script>` in the initial server-rendered `<head>`, before application scripts. Do not use `async`, `defer`, or Next.js `Script`. This is necessary to wrap `fetch` and `XMLHttpRequest` before application code captures their native references. [Recorder installation](https://app.meticulous.ai/docs/recorder-installation) · [Capturing early requests](https://app.meticulous.ai/docs/how-to/ensure-recorder-captures-all-requests)
+- Localhost is a supported and explicitly recommended recording environment. The normal recorder, the Meticulous CLI, and existing Playwright tests can all generate sessions. [Onboarding](https://app.meticulous.ai/docs/onboarding-guide) · [Ingest existing tests](https://app.meticulous.ai/docs/session-recording/ingest-existing-tests)
+- The official current recommendation for a server-rendered Next.js application is `upload-container@v1`. `cloud-compute@v1` is a tunnel-based fallback when a container is not practical. The `github-actions-v2` URL is the name of the setup guide; the current action major version is still `@v1`. [Next.js App Router guide](https://app.meticulous.ai/docs/frameworks/nextjs/app-router) · [Official action repository](https://github.com/alwaysmeticulous/report-diffs-action)
+- Coffee Timer currently has no Dockerfile, so its existing `cloud-compute@v1` approach is a reasonable incremental path. If it stays on `cloud-compute`, the official Next.js configuration includes companion assets for `/_next/static/`.
+
+## How recording becomes a CI test
+
+Meticulous records interactions, DOM changes, and network requests/responses. During replay it restores recorded cookies, local storage, session storage, and stubs XHR, Fetch, and WebSocket responses by default. Static assets are loaded live and are not stubbed. For Next.js App Router, the project setting should be **Stub all requests, apart from requests for server components and static assets** so RSC requests reach the running application. [FAQ](https://app.meticulous.ai/docs/faq-and-troubleshooting) · [Next.js network stubbing](https://app.meticulous.ai/docs/frameworks/nextjs/app-router#network-stubbing-for-server-components)
+
+The lifecycle is:
+
+1. A manual or automated browser interaction creates a session.
+2. Meticulous replays new sessions, measures code/component/route coverage, and updates Selected Sessions.
+3. CI replays Selected Sessions against the PR head and base commit, then compares the resulting snapshots.
+4. To guarantee a critical flow is always included, open that session in the Dashboard and click **Add to selected sessions**. [Session selection](https://app.meticulous.ai/docs/how-to/testing-pool)
+
+Therefore, “the Dashboard shows recordings” and “CI runs those recordings” are related but separate checks. Validate both the **All Sessions** tab and the **Selected Sessions** tab.
+
+## Recorder installation and localhost verification
+
+Coffee Timer already follows the essential integration pattern:
+
+- `app/[locale]/layout.tsx` emits a native synchronous script in `<head>`.
+- `lib/constants/meticulous.ts` uses `https://snippet.meticulous.ai/v1/meticulous.js`.
+- `lib/utils/getMeticulousProjectId.ts` gates it on `NEXT_PUBLIC_METICULOUS_PROJECT_ID`.
+
+For local recording, set the project ID in the uncommitted local environment, start `pnpm dev`, and use `http://localhost:3009/en` or `/ja`. Confirm all of the following:
+
+1. The initial HTML contains the recorder script.
+2. The browser Network panel loads `https://snippet.meticulous.ai/v1/meticulous.js` before application network activity.
+3. `window.Meticulous` exists.
+4. After interacting with the app, the session appears under Dashboard → All Sessions.
+5. `window.Meticulous.record.getSessionUrl()` returns the current session page. [Manual recording](https://app.meticulous.ai/docs/how-to/manually-recording-tests)
+
+If localhost interactions do not appear, use `?meticulousForceRecording=true` as a diagnosis. For internal/non-production recording, `data-is-production-environment="false"` raises the abandonment threshold; `data-force-recording="true"` disables abandonment. These attributes affect recorder load handling, not environment enablement, so enabling the recorder must still be controlled separately. [Recorder troubleshooting](https://app.meticulous.ai/docs/how-to/troubleshoot-recorder)
+
+Recorded requests can include authorization tokens and headers even though plaintext passwords are redacted. Only trusted users should have organization access. The Meticulous API token also grants access to recorded sessions and must remain secret. [Recorder installation](https://app.meticulous.ai/docs/recorder-installation) · [CI setup](https://app.meticulous.ai/docs/github-actions-v2)
+
+## One user flow per recording
+
+### Manual / CLI recording
+
+For deliberate, clearly bounded recordings, the official CLI is the least ambiguous option:
+
+```bash
+npx @alwaysmeticulous/cli record session --apiToken="$METICULOUS_API_TOKEN"
+```
+
+It opens a blank browser. Navigate to `http://localhost:3009/en`, perform exactly one flow, then close the browser. The CLI prints the resulting session link(s). A multi-page navigation may create separate sessions per page so they can replay in parallel. Replay the result locally from the session's **Simulate** tab before selecting it. [Manual recording](https://app.meticulous.ai/docs/how-to/manually-recording-tests)
+
+Repeat the command for each desired flow. This gives the clearest practical “one browser run = one intended test flow” boundary.
+
+### Playwright-generated recording
+
+Meticulous officially supports ingesting existing Playwright tests. Requirements are:
+
+1. The recorder is present while the Playwright page runs.
+2. At the end of every test, and before page close or full-page navigation, await:
+
+   ```ts
+   await page.evaluate(() => window.Meticulous.record.flush())
+   ```
+
+3. In Dashboard → All Sessions, disable **Hide Automated Sessions** to see them. [Ingest existing tests](https://app.meticulous.ai/docs/session-recording/ingest-existing-tests)
+
+The public recorder API exposes `flush()` and `getSessionUrl()`, but no public “start a new session” or “stop this session” method. `flush()` sends buffered data; it is not documented as splitting the current session. [Official public Window API](https://github.com/alwaysmeticulous/meticulous-sdk/blob/82bc03633f0c63e196ce5cf4bd5575fcf65a5bdb/packages/sdk-bundles-api/src/window-api/public-window-api.ts#L192-L237)
+
+Accordingly, for predictable automation boundaries, use one fresh Playwright page/context per test, keep one observable user journey in that test, and flush before teardown. This final sentence is an implementation inference from the official ingest requirements and public API, not a documented Meticulous guarantee about session identifiers.
+
+## Coffee Timer recording set
+
+Record focused flows instead of one long “everything” session. This repository's dedicated ingestion suite at `e2e/meticulous/recording.spec.ts` records ten isolated journeys:
+
+1. Direct duration entry, plus/minus steppers, keyboard arrows, and boundaries.
+2. Start, pause, resume, and reset.
+3. Countdown to zero, completion sound request, restart, and reset.
+4. Light, Dark, Coffee, and all deterministic Liquid Glass themes.
+5. Sound preview/selection, volume extremes, notification toggling, and a test notification.
+6. English-to-Japanese locale switching and Japanese settings UI.
+7. Rejected invalid sign-in plus sign-up form navigation without creating an account.
+8. PWA settings shortcut handling.
+9. PWA start shortcut handling.
+10. Critical timer and settings controls at the mobile viewport.
+
+Run the suite locally with:
+
+```bash
+kill-port 3009
+pnpm meticulous:record
+```
+
+`playwright.meticulous.config.ts` starts `pnpm dev` when port 3009 is free, opens headed Chromium so browser notification permission behaves realistically, uses one worker, and gives every test a fresh browser context. `openMeticulousRecording` adds `?meticulousForceRecording=true` only to these dedicated journeys and fails if the recorder is missing. `flushMeticulousRecording` awaits `window.Meticulous.record.flush()` before teardown and prints each Dashboard session URL. The main `playwright.config.ts` excludes this directory so ordinary E2E runs do not force remote sessions accidentally.
+
+The browser-owned notification permission prompt is intentionally not replayed because it is nondeterministic in headless CI. The notification journey grants permission through Playwright, then records the in-app toggle and **Send test** action. The System theme is also excluded because its visual result depends on the host color scheme; all six deterministic theme variants are recorded instead.
+
+After ingestion, inspect every generated session, replay it locally, and manually select the business-critical flows. Do not assume that merely recording all existing Playwright tests makes all of them run in CI.
+
+## Existing recording
+
+The existing recording does not need to be deleted before recording more flows. New sessions are added to the pool, and Meticulous continuously updates the selected combination as the app changes. A manually pinned recording can be unpinned with **Remove from selected sessions**. [Session selection](https://app.meticulous.ai/docs/how-to/testing-pool)
+
+If an old session becomes unreplayable after the UI/API changes, Meticulous documents that it can safely be ignored: it detects lost coverage and selects newer sessions to cover those paths. [Failed simulation troubleshooting](https://app.meticulous.ai/docs/how-to/troubleshoot-failed-simulations)
+
+Recommended handling for the current single recording:
+
+- Keep it if it replays cleanly and represents a useful flow.
+- Remove it from Selected Sessions if it is redundant, excessively long, or flaky.
+- Add the new focused sessions, then inspect coverage before deciding whether the old recording adds unique value.
+
+## GitHub Actions requirements
+
+Before CI can report correctly:
+
+1. Install the [Meticulous GitHub App](https://github.com/apps/alwaysmeticulous/installations/new).
+2. Add repository Actions secret `METICULOUS_API_TOKEN` from the matching Meticulous project's settings.
+3. Run the workflow on main pushes, pull requests, and `workflow_dispatch`.
+4. Grant all officially required permissions:
+
+   ```yaml
+   permissions:
+     actions: write
+     contents: read
+     issues: write
+     pull-requests: write
+     statuses: read
+   ```
+
+These permissions are used to manage the status check and PR feedback. Meticulous states that it will not work without them. [CI setup](https://app.meticulous.ai/docs/github-actions-v2)
+
+Repository secrets other than `GITHUB_TOKEN` are not provided to workflows triggered by fork pull requests, and the fork PR `GITHUB_TOKEN` is read-only. Consequently, `METICULOUS_API_TOKEN`-dependent runs will not work normally for untrusted fork PRs unless repository policy explicitly changes that behavior; do not switch to `pull_request_target` merely to expose the token to contributor code. [GitHub secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) · [GitHub fork events](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflows-in-forked-repositories)
+
+Coffee Timer skips the Meticulous job for fork pull requests and Dependabot pull requests, where the required repository secret is unavailable. Same-repository pull requests, main pushes, and manual dispatches continue to run the visual replay.
+
+## Correct `cloud-compute` workflow for this repository
+
+Official guidance now prefers `upload-container@v1` for Next.js. If Coffee Timer continues with its current tunnel approach, the documented Next.js version is:
+
+```yaml
+name: Meticulous Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+  workflow_dispatch: {}
+
+permissions:
+  actions: write
+  contents: read
+  issues: write
+  pull-requests: write
+  statuses: read
+
+jobs:
+  test:
+    if: >-
+      github.event_name != 'pull_request' ||
+      (github.event.pull_request.head.repo.full_name == github.repository &&
+      github.actor != 'dependabot[bot]')
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Build Next.js app
+        run: pnpm build
+        env:
+          NODE_ENV: production
+          METICULOUS_BUILD: 'true'
+
+      - name: Prepare companion assets
+        run: |
+          mkdir -p companion-assets/_next
+          cp -r .next/static companion-assets/_next/
+
+      - name: Start app
+        run: |
+          pnpm start &
+          npx wait-on http://localhost:3009/en --timeout 60000
+
+      - name: Run Meticulous tests
+        uses: alwaysmeticulous/report-diffs-action/cloud-compute@v1
+        with:
+          api-token: ${{ secrets.METICULOUS_API_TOKEN }}
+          app-url: 'http://localhost:3009'
+          companion-assets-folder: 'companion-assets'
+          companion-assets-regex: '^/_next/static/'
+```
+
+The action's `github-token` input defaults to `${{ github.token }}`. `api-token` and `app-url` are the required single-project inputs; the other tunnel inputs are optional. [Official cloud-compute action definition](https://github.com/alwaysmeticulous/report-diffs-action/blob/main/cloud-compute/action.yml)
+
+The repository's `.github/workflows/meticulous.yml` has the essential triggers, permissions, secret, production build, live server, `cloud-compute@v1`, and the official Next.js companion-assets setup for `/_next/static/`. If companion assets fail in this app, `cloud-compute` can run without them because those inputs are optional, but omitting them diverges from the current Next.js recommendation and can make static asset delivery slower.
+
+## Branch and first-run behavior
+
+- Meticulous needs both the main-branch run and PR runs. It compares replay snapshots for the PR head against the base commit. Build/runtime configuration must be the same on both sides to avoid environmental false diffs. [FAQ](https://app.meticulous.ai/docs/faq-and-troubleshooting)
+- `workflow_dispatch` lets Meticulous lazily request a missing base run. It is required by the official workflow template. [Official action repository](https://github.com/alwaysmeticulous/report-diffs-action#required-workflow-setup)
+- The PR that first adds the workflow generally has no useful diff result because main has no baseline run yet. Merge it, wait for a successful main run, then open a second PR to verify comparison. [CI setup](https://app.meticulous.ai/docs/github-actions-v2)
+- PR comments are disabled by default for new Meticulous projects; runs remain visible under Dashboard → Test runs. The GitHub App can add a check that stays red for unapproved visual differences and can be made a required check. [CI setup](https://app.meticulous.ai/docs/github-actions-v2)
+
+## Acceptance checklist
+
+- Recorder script is first, synchronous, and visible in initial HTML on localhost.
+- Multiple focused manual/CLI or Playwright-generated sessions appear in All Sessions.
+- Automated sessions are visible when **Hide Automated Sessions** is disabled.
+- Every critical Coffee Timer flow replays locally without error.
+- Critical flows are in Selected Sessions, either automatically or manually.
+- GitHub App is installed and `METICULOUS_API_TOKEN` is configured for the same project.
+- Workflow succeeds on main and creates a base test run.
+- A subsequent PR produces a head-vs-base Meticulous test run.
+- Next.js project settings pass through RSC/static asset requests.
+- Fork/Dependabot pull requests safely skip the job when the API secret is unavailable.
diff --git a/e2e/meticulous/constants.ts b/e2e/meticulous/constants.ts
new file mode 100644
index 0000000..370811d
--- /dev/null
+++ b/e2e/meticulous/constants.ts
@@ -0,0 +1,7 @@
+export const METICULOUS_RECORDER_QUERY = 'meticulousForceRecording=true'
+export const METICULOUS_RECORDER_READY_TIMEOUT_MS = 30_000
+export const METICULOUS_RECORDING_RETRIES = 0
+export const METICULOUS_RECORDING_WORKERS = 1
+export const METICULOUS_WEB_SERVER_TIMEOUT_MS = 120_000
+export const TIMER_COMPLETION_TIMEOUT_MS = 5_000
+export const MOBILE_VIEWPORT = { width: 375, height: 812 }
diff --git a/e2e/meticulous/meticulous-window.d.ts b/e2e/meticulous/meticulous-window.d.ts
new file mode 100644
index 0000000..47baf1e
--- /dev/null
+++ b/e2e/meticulous/meticulous-window.d.ts
@@ -0,0 +1,10 @@
+interface MeticulousRecorder {
+  flush: () => Promise<void>
+  getSessionUrl: () => string
+}
+
+interface Window {
+  Meticulous?: {
+    record?: MeticulousRecorder
+  }
+}
diff --git a/e2e/meticulous/recording-helpers.ts b/e2e/meticulous/recording-helpers.ts
new file mode 100644
index 0000000..dfc519c
--- /dev/null
+++ b/e2e/meticulous/recording-helpers.ts
@@ -0,0 +1,62 @@
+import { expect, type Page, type TestInfo } from '@playwright/test'
+import {
+  METICULOUS_RECORDER_QUERY,
+  METICULOUS_RECORDER_READY_TIMEOUT_MS,
+} from './constants'
+
+/** Opens a route with forced localhost capture and waits until the recorder can accept the journey. @param page Playwright page for this isolated journey. @param path App-relative route, including any existing query. @returns A promise resolved when the page and recorder are ready. @example await openMeticulousRecording(page, '/en') */
+export async function openMeticulousRecording(
+  page: Page,
+  path: string,
+): Promise<void> {
+  const querySeparator = path.includes('?') ? '&' : '?'
+
+  await page.goto(`${path}${querySeparator}${METICULOUS_RECORDER_QUERY}`)
+  await page.waitForLoadState('networkidle')
+
+  await expect
+    .poll(
+      () =>
+        page.evaluate(
+          () => typeof window.Meticulous?.record?.flush === 'function',
+        ),
+      {
+        message:
+          'Meticulous recorder did not initialize. Check NEXT_PUBLIC_METICULOUS_PROJECT_ID and recorder loading.',
+        timeout: METICULOUS_RECORDER_READY_TIMEOUT_MS,
+      },
+    )
+    .toBe(true)
+}
+
+/** Flushes buffered capture before Playwright tears down the page and prints its Dashboard URL. @param page Playwright page containing the active recorder. @param testInfo Metadata used to label and attach the resulting session. @returns A promise resolved after Meticulous acknowledges the recording. @example await flushMeticulousRecording(page, testInfo) */
+export async function flushMeticulousRecording(
+  page: Page,
+  testInfo: TestInfo,
+): Promise<void> {
+  const hasRecorder = await page.evaluate(
+    () => typeof window.Meticulous?.record?.flush === 'function',
+  )
+
+  // A navigation failure can happen before recorder initialization, so preserve the original test error.
+  if (!hasRecorder) return
+
+  const sessionUrl = await page.evaluate(async () => {
+    const recorder = window.Meticulous?.record
+
+    if (!recorder) {
+      throw new Error('Meticulous recorder is unavailable during flush')
+    }
+
+    const currentSessionUrl = recorder.getSessionUrl()
+    await recorder.flush()
+
+    return currentSessionUrl
+  })
+
+  await testInfo.attach('meticulous-session-url', {
+    body: sessionUrl,
+    contentType: 'text/plain',
+  })
+  console.info(`[Meticulous] ${testInfo.title}: ${sessionUrl}`)
+}
diff --git a/e2e/meticulous/recording.spec.ts b/e2e/meticulous/recording.spec.ts
new file mode 100644
index 0000000..18933d2
--- /dev/null
+++ b/e2e/meticulous/recording.spec.ts
@@ -0,0 +1,258 @@
+import { expect, test } from '@playwright/test'
+import { MOBILE_VIEWPORT, TIMER_COMPLETION_TIMEOUT_MS } from './constants'
+import {
+  flushMeticulousRecording,
+  openMeticulousRecording,
+} from './recording-helpers'
+
+test.describe('Meticulous Coffee Timer journeys', () => {
+  test.afterEach(async ({ page }, testInfo) => {
+    // Meticulous must receive buffered events before Playwright closes this fresh context.
+    await flushMeticulousRecording(page, testInfo)
+  })
+
+  test('edits a duration with inputs, steppers, arrow keys, and boundaries', async ({
+    page,
+  }) => {
+    // Arrange
+    await openMeticulousRecording(page, '/en')
+    const minutesInput = page.getByTestId('time-input-minutes')
+    const secondsInput = page.getByTestId('time-input-seconds')
+    const timerDisplay = page.getByTestId('timer-display')
+    const minutesStepper = minutesInput.locator('..')
+
+    await expect(minutesInput).toHaveValue('05')
+    await expect(secondsInput).toHaveValue('00')
+
+    // Act
+    await minutesStepper.getByRole('button', { name: /increase/i }).click()
+    await expect(minutesInput).toHaveValue('06')
+    await minutesStepper.getByRole('button', { name: /decrease/i }).click()
+    await minutesInput.fill('25')
+    await secondsInput.fill('45')
+    await secondsInput.press('ArrowUp')
+    await expect(timerDisplay).toContainText('25:46')
+    await secondsInput.fill('99')
+
+    // Assert
+    await expect(secondsInput).toHaveValue('59')
+    await expect(timerDisplay).toContainText('25:59')
+  })
+
+  test('starts, pauses, resumes, and resets a timer', async ({ page }) => {
+    // Arrange
+    await openMeticulousRecording(page, '/en')
+    await page.getByTestId('time-input-minutes').fill('0')
+    await page.getByTestId('time-input-seconds').fill('15')
+    const timerDisplay = page.getByTestId('timer-display')
+    const startButton = page.getByTestId('timer-start-button')
+
+    // Act
+    await startButton.click()
+    await expect(page.getByTestId('timer-pause-button')).toBeVisible()
+    await page.getByTestId('timer-pause-button').click()
+    await expect(startButton).toBeVisible()
+    await startButton.click()
+    await expect(page.getByTestId('timer-pause-button')).toBeVisible()
+    await page.getByTestId('timer-reset-button').click()
+
+    // Assert
+    await expect(timerDisplay).toContainText('00:15')
+    await expect(startButton).toBeVisible()
+  })
+
+  test('completes a countdown with sound and can restart it', async ({
+    page,
+  }) => {
+    // Arrange
+    await openMeticulousRecording(page, '/en')
+    await page.getByTestId('time-input-minutes').fill('0')
+    await page.getByTestId('time-input-seconds').fill('2')
+    const timerDisplay = page.getByTestId('timer-display')
+    const soundRequest = page.waitForRequest(
+      (request) =>
+        request.url().includes('/sounds/') && request.url().endsWith('.mp3'),
+      { timeout: TIMER_COMPLETION_TIMEOUT_MS },
+    )
+
+    // Act
+    await page.getByTestId('timer-start-button').click()
+
+    // Assert
+    await soundRequest
+    await expect(timerDisplay).toContainText('00:00', {
+      timeout: TIMER_COMPLETION_TIMEOUT_MS,
+    })
+    await page.getByTestId('timer-start-button').click()
+    await expect(page.getByTestId('timer-pause-button')).toBeVisible()
+    await page.getByTestId('timer-reset-button').click()
+    await expect(timerDisplay).toContainText('00:02')
+  })
+
+  test('switches through every deterministic theme', async ({ page }) => {
+    // Arrange
+    await openMeticulousRecording(page, '/en')
+    await page.getByRole('button', { name: /open settings/i }).click()
+    const themeSelector = page.getByTestId('theme-selector')
+    const html = page.locator('html')
+
+    // Act and Assert
+    await themeSelector.click()
+    await page.getByRole('option', { name: 'Dark', exact: true }).click()
+    await expect(html).toHaveAttribute('data-theme', 'dark')
+
+    await themeSelector.click()
+    await page.getByRole('option', { name: 'Light', exact: true }).click()
+    await expect(html).toHaveAttribute('data-theme', 'light')
+
+    await themeSelector.click()
+    await page.getByRole('option', { name: 'Coffee', exact: true }).click()
+    await expect(html).toHaveAttribute('data-theme', 'coffee')
+
+    await themeSelector.click()
+    await page.getByRole('option', { name: 'Glass Light', exact: true }).click()
+    await expect(html).toHaveAttribute('data-theme', 'liquid-glass-light')
+
+    await themeSelector.click()
+    await page.getByRole('option', { name: 'Glass Dark', exact: true }).click()
+    await expect(html).toHaveAttribute('data-theme', 'liquid-glass-dark')
+
+    await themeSelector.click()
+    await page
+      .getByRole('option', { name: 'Glass Coffee', exact: true })
+      .click()
+    await expect(html).toHaveAttribute('data-theme', 'liquid-glass-coffee')
+  })
+
+  test('previews and selects sound, changes volume, and toggles notifications', async ({
+    context,
+    page,
+  }) => {
+    // Arrange
+    await context.grantPermissions(['notifications'], {
+      origin: 'http://localhost:3009',
+    })
+    await openMeticulousRecording(page, '/en')
+    await page.getByRole('button', { name: /open settings/i }).click()
+    const soundSelector = page.getByTestId('sound-selector')
+    const notificationToggle = page.getByRole('switch', {
+      name: /notifications/i,
+    })
+    const soundRequest = page.waitForRequest(
+      (request) => request.url().includes('/sounds/ascending-chime.mp3'),
+      { timeout: TIMER_COMPLETION_TIMEOUT_MS },
+    )
+
+    // Act
+    await soundSelector.click()
+    await page.getByRole('button', { name: /preview ascending chime/i }).click()
+    await soundRequest
+    await page.getByRole('option', { name: 'Bright Ding', exact: true }).click()
+    const volumeSlider = page.getByTestId('volume-slider-thumb')
+    await volumeSlider.press('Home')
+    await expect(volumeSlider).toHaveAttribute('aria-valuenow', '0')
+    await volumeSlider.press('End')
+    await expect(notificationToggle).toHaveAttribute('aria-checked', 'true')
+    await notificationToggle.click()
+    await expect(notificationToggle).toHaveAttribute('aria-checked', 'false')
+    await notificationToggle.click()
+    await page.getByTestId('settings-done-button').click()
+    const sendTestButton = page.getByRole('button', { name: /send test/i })
+    const notificationShown = page.waitForEvent('console', {
+      predicate: (message) =>
+        message.text() === '[Notifications] Notification shown successfully',
+      timeout: TIMER_COMPLETION_TIMEOUT_MS,
+    })
+    await sendTestButton.click()
+    await notificationShown
+
+    // Assert
+    await expect(page.getByTestId('settings-panel')).toBeHidden()
+  })
+
+  test('switches the timer and settings interface to Japanese', async ({
+    page,
+  }) => {
+    // Arrange
+    await openMeticulousRecording(page, '/en')
+
+    // Act
+    await page.getByRole('combobox', { name: 'Language' }).click()
+    await page.getByRole('option', { name: '日本語', exact: true }).click()
+
+    // Assert
+    await expect(page).toHaveURL(/\/ja/)
+    await expect(page.getByRole('button', { name: '開始' })).toBeVisible()
+    await page.getByRole('button', { name: '設定を開く' }).click()
+    await expect(page.getByRole('dialog', { name: '設定' })).toBeVisible()
+    await page.getByRole('button', { name: '完了' }).click()
+  })
+
+  test('rejects an invalid sign-in and navigates through sign-up without creating an account', async ({
+    page,
+  }) => {
+    // Arrange
+    await openMeticulousRecording(page, '/en')
+
+    // Act
+    await page.getByRole('link', { name: 'Sign In', exact: true }).click()
+    await page.getByLabel('Email').fill('recording@example.com')
+    await page.getByLabel('Password').fill('not-a-real-password')
+    await page.getByRole('button', { name: 'Sign In', exact: true }).click()
+    await expect(page.getByRole('alert')).toBeVisible()
+    await page.getByRole('link', { name: 'Sign Up', exact: true }).click()
+    await page.getByLabel('Name').fill('Meticulous Recording')
+    await page.getByLabel('Email').fill('recording@example.com')
+    await page.getByLabel('Password').fill('not-a-real-password')
+
+    // Assert
+    await expect(page.getByRole('heading', { name: 'Sign Up' })).toBeVisible()
+    await page.getByRole('link', { name: 'Sign In', exact: true }).click()
+    await expect(page.getByRole('heading', { name: 'Sign In' })).toBeVisible()
+  })
+
+  test('opens settings from the PWA settings shortcut', async ({ page }) => {
+    // Arrange and Act
+    await openMeticulousRecording(page, '/?action=settings')
+
+    // Assert
+    await expect(page).toHaveURL(/\/en/)
+    await expect(page.getByRole('dialog', { name: /settings/i })).toBeVisible()
+    await page.getByTestId('settings-done-button').click()
+  })
+
+  test('starts the default timer from the PWA start shortcut', async ({
+    page,
+  }) => {
+    // Arrange and Act
+    await openMeticulousRecording(page, '/?action=start')
+
+    // Assert
+    await expect(page).toHaveURL(/\/en/)
+    await expect(page.getByTestId('timer-pause-button')).toBeVisible()
+    await page.getByTestId('timer-reset-button').click()
+    await expect(page.getByTestId('timer-display')).toContainText('05:00')
+  })
+
+  test('uses the critical timer and settings controls on a mobile viewport', async ({
+    page,
+  }) => {
+    // Arrange
+    await page.setViewportSize(MOBILE_VIEWPORT)
+    await openMeticulousRecording(page, '/en')
+    await page.getByTestId('time-input-minutes').fill('1')
+    await page.getByTestId('time-input-seconds').fill('30')
+
+    // Act
+    await page.getByTestId('timer-start-button').click()
+    await expect(page.getByTestId('timer-pause-button')).toBeVisible()
+    await page.getByTestId('timer-pause-button').click()
+    await page.getByTestId('timer-reset-button').click()
+    await page.getByRole('button', { name: /open settings/i }).click()
+
+    // Assert
+    await expect(page.getByTestId('settings-panel')).toBeVisible()
+    await page.getByTestId('settings-done-button').click()
+    await expect(page.getByTestId('timer-display')).toContainText('01:30')
+  })
+})
diff --git a/e2e/pwa-shortcuts.spec.ts b/e2e/pwa-shortcuts.spec.ts
new file mode 100644
index 0000000..568cda3
--- /dev/null
+++ b/e2e/pwa-shortcuts.spec.ts
@@ -0,0 +1,29 @@
+import { expect, test } from '@playwright/test'
+
+test.describe('PWA shortcuts', () => {
+  test('settings shortcut opens the English settings dialog', async ({
+    page,
+  }) => {
+    // Arrange and Act
+    await page.goto('/?action=settings')
+
+    // Assert
+    await expect(page).toHaveURL('http://localhost:3009/en')
+    await expect(page.getByRole('dialog', { name: 'Settings' })).toBeVisible()
+    await page.getByTestId('settings-done-button').click()
+    await expect(page.getByTestId('settings-panel')).toBeHidden()
+  })
+
+  test('start shortcut starts and resets the default five-minute timer', async ({
+    page,
+  }) => {
+    // Arrange and Act
+    await page.goto('/?action=start')
+
+    // Assert
+    await expect(page).toHaveURL('http://localhost:3009/en')
+    await expect(page.getByTestId('timer-pause-button')).toBeVisible()
+    await page.getByTestId('timer-reset-button').click()
+    await expect(page.getByTestId('timer-display')).toContainText('05:00')
+  })
+})
diff --git a/package.json b/package.json
index 8a89240..d44422c 100644
--- a/package.json
+++ b/package.json
@@ -20,6 +20,7 @@
     "e2e:desktop": "playwright test --project=\"Desktop Chrome\"",
     "e2e:tablet": "playwright test --project=\"Tablet Safari\"",
     "e2e:mobile": "playwright test --project=\"Mobile Chrome\"",
+    "meticulous:record": "playwright test --config=playwright.meticulous.config.ts",
     "prepare": "husky",
     "prettier": "prettier --ignore-unknown --write .",
     "clean": "rm -rf .next node_modules .playwright-mcp test-results playwright-report .pnpm-store",
diff --git a/playwright.config.ts b/playwright.config.ts
index a5b0795..bf47c87 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -2,6 +2,8 @@ import { defineConfig, devices } from '@playwright/test'
 
 export default defineConfig({
   testDir: './e2e',
+  // Meticulous ingestion is an explicit local task because it creates remote sessions.
+  testIgnore: '**/meticulous/**',
   fullyParallel: true,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
diff --git a/playwright.meticulous.config.ts b/playwright.meticulous.config.ts
new file mode 100644
index 0000000..6b17b5d
--- /dev/null
+++ b/playwright.meticulous.config.ts
@@ -0,0 +1,33 @@
+import { defineConfig, devices } from '@playwright/test'
+import {
+  METICULOUS_RECORDING_RETRIES,
+  METICULOUS_RECORDING_WORKERS,
+  METICULOUS_WEB_SERVER_TIMEOUT_MS,
+} from './e2e/meticulous/constants'
+
+export default defineConfig({
+  testDir: './e2e/meticulous',
+  fullyParallel: false,
+  forbidOnly: true,
+  retries: METICULOUS_RECORDING_RETRIES,
+  workers: METICULOUS_RECORDING_WORKERS,
+  reporter: [['list']],
+  use: {
+    baseURL: 'http://localhost:3009',
+    // Headed Chromium exposes real notification permission state for the settings journey.
+    headless: false,
+    trace: 'retain-on-failure',
+  },
+  projects: [
+    {
+      name: 'Meticulous Recording',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  webServer: {
+    command: 'pnpm dev',
+    url: 'http://localhost:3009/en',
+    reuseExistingServer: true,
+    timeout: METICULOUS_WEB_SERVER_TIMEOUT_MS,
+  },
+})

From 56dc34c9cbf19d206ee2e145f5d0c11696554b29 Mon Sep 17 00:00:00 2001
From: Ryota Murakami <dojce1048@gmail.com>
Date: Thu, 16 Jul 2026 17:02:17 +0900
Subject: [PATCH 2/3] fix(ci): disable incompatible Meticulous companion assets

---
 .github/workflows/meticulous.yml |  8 --------
 docs/meticulous.md               | 13 +++----------
 2 files changed, 3 insertions(+), 18 deletions(-)

diff --git a/.github/workflows/meticulous.yml b/.github/workflows/meticulous.yml
index 739c664..7096571 100644
--- a/.github/workflows/meticulous.yml
+++ b/.github/workflows/meticulous.yml
@@ -46,12 +46,6 @@ jobs:
           NODE_ENV: production
           METICULOUS_BUILD: 'true'
 
-      # Serve immutable Next.js chunks directly to make visual replays faster and steadier.
-      - name: Prepare companion assets
-        run: |
-          mkdir -p companion-assets/_next
-          cp -r .next/static companion-assets/_next/
-
       - name: Start app
         run: |
           pnpm start &
@@ -62,5 +56,3 @@ jobs:
         with:
           api-token: ${{ secrets.METICULOUS_API_TOKEN }}
           app-url: 'http://localhost:3009'
-          companion-assets-folder: 'companion-assets'
-          companion-assets-regex: '^/_next/static/'
diff --git a/docs/meticulous.md b/docs/meticulous.md
index b68e10d..14f72f8 100644
--- a/docs/meticulous.md
+++ b/docs/meticulous.md
@@ -8,7 +8,7 @@ This note records the current Meticulous behavior and the recommended setup for
 - The recorder should be a synchronous native `<script>` in the initial server-rendered `<head>`, before application scripts. Do not use `async`, `defer`, or Next.js `Script`. This is necessary to wrap `fetch` and `XMLHttpRequest` before application code captures their native references. [Recorder installation](https://app.meticulous.ai/docs/recorder-installation) · [Capturing early requests](https://app.meticulous.ai/docs/how-to/ensure-recorder-captures-all-requests)
 - Localhost is a supported and explicitly recommended recording environment. The normal recorder, the Meticulous CLI, and existing Playwright tests can all generate sessions. [Onboarding](https://app.meticulous.ai/docs/onboarding-guide) · [Ingest existing tests](https://app.meticulous.ai/docs/session-recording/ingest-existing-tests)
 - The official current recommendation for a server-rendered Next.js application is `upload-container@v1`. `cloud-compute@v1` is a tunnel-based fallback when a container is not practical. The `github-actions-v2` URL is the name of the setup guide; the current action major version is still `@v1`. [Next.js App Router guide](https://app.meticulous.ai/docs/frameworks/nextjs/app-router) · [Official action repository](https://github.com/alwaysmeticulous/report-diffs-action)
-- Coffee Timer currently has no Dockerfile, so its existing `cloud-compute@v1` approach is a reasonable incremental path. If it stays on `cloud-compute`, the official Next.js configuration includes companion assets for `/_next/static/`.
+- Coffee Timer currently has no Dockerfile, so its existing `cloud-compute@v1` approach is a reasonable incremental path. The official Next.js configuration documents companion assets for `/_next/static/`, but the current Meticulous API rejects that documented regex; Coffee Timer therefore uses the supported tunnel-only configuration until the upstream incompatibility is fixed.
 
 ## How recording becomes a CI test
 
@@ -140,7 +140,7 @@ Coffee Timer skips the Meticulous job for fork pull requests and Dependabot pull
 
 ## Correct `cloud-compute` workflow for this repository
 
-Official guidance now prefers `upload-container@v1` for Next.js. If Coffee Timer continues with its current tunnel approach, the documented Next.js version is:
+Official guidance now prefers `upload-container@v1` for Next.js. Coffee Timer currently uses this tunnel-only workflow:
 
 ```yaml
 name: Meticulous Tests
@@ -187,11 +187,6 @@ jobs:
           NODE_ENV: production
           METICULOUS_BUILD: 'true'
 
-      - name: Prepare companion assets
-        run: |
-          mkdir -p companion-assets/_next
-          cp -r .next/static companion-assets/_next/
-
       - name: Start app
         run: |
           pnpm start &
@@ -202,13 +197,11 @@ jobs:
         with:
           api-token: ${{ secrets.METICULOUS_API_TOKEN }}
           app-url: 'http://localhost:3009'
-          companion-assets-folder: 'companion-assets'
-          companion-assets-regex: '^/_next/static/'
 ```
 
 The action's `github-token` input defaults to `${{ github.token }}`. `api-token` and `app-url` are the required single-project inputs; the other tunnel inputs are optional. [Official cloud-compute action definition](https://github.com/alwaysmeticulous/report-diffs-action/blob/main/cloud-compute/action.yml)
 
-The repository's `.github/workflows/meticulous.yml` has the essential triggers, permissions, secret, production build, live server, `cloud-compute@v1`, and the official Next.js companion-assets setup for `/_next/static/`. If companion assets fail in this app, `cloud-compute` can run without them because those inputs are optional, but omitting them diverges from the current Next.js recommendation and can make static asset delivery slower.
+The repository's `.github/workflows/meticulous.yml` has the essential triggers, permissions, secret, production build, live server, and `cloud-compute@v1`. The optional companion-assets inputs are intentionally disabled: on 2026-07-16, the live API returned HTTP 400 for the officially documented `^/_next/static/` regex before any replay began. The tunnel serves those static assets without the optimization, which preserves correctness while avoiding the incompatible request. Re-enable companion assets after Meticulous accepts its documented configuration. [Companion assets guide](https://app.meticulous.ai/docs/how-to/companion-assets-advanced)
 
 ## Branch and first-run behavior
 

From 132e8dd323b5e43d1b98573da7240337efed9650 Mon Sep 17 00:00:00 2001
From: Ryota Murakami <dojce1048@gmail.com>
Date: Thu, 16 Jul 2026 17:56:59 +0900
Subject: [PATCH 3/3] fix: resolve CodeRabbit Meticulous feedback

- identify Dependabot pull requests by their author\n- exercise shortcut redirects without locale proxy interference
---
 .github/workflows/meticulous.yml | 2 +-
 docs/meticulous.md               | 2 +-
 e2e/pwa-shortcuts.spec.ts        | 8 ++++----
 proxy.ts                         | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/meticulous.yml b/.github/workflows/meticulous.yml
index 7096571..221d8b3 100644
--- a/.github/workflows/meticulous.yml
+++ b/.github/workflows/meticulous.yml
@@ -20,7 +20,7 @@ jobs:
     if: >-
       github.event_name != 'pull_request' ||
       (github.event.pull_request.head.repo.full_name == github.repository &&
-      github.actor != 'dependabot[bot]')
+      github.event.pull_request.user.login != 'dependabot[bot]')
     runs-on: ubuntu-latest
     timeout-minutes: 30
 
diff --git a/docs/meticulous.md b/docs/meticulous.md
index 14f72f8..b623f19 100644
--- a/docs/meticulous.md
+++ b/docs/meticulous.md
@@ -163,7 +163,7 @@ jobs:
     if: >-
       github.event_name != 'pull_request' ||
       (github.event.pull_request.head.repo.full_name == github.repository &&
-      github.actor != 'dependabot[bot]')
+      github.event.pull_request.user.login != 'dependabot[bot]')
     runs-on: ubuntu-latest
     timeout-minutes: 30
 
diff --git a/e2e/pwa-shortcuts.spec.ts b/e2e/pwa-shortcuts.spec.ts
index 568cda3..115c38c 100644
--- a/e2e/pwa-shortcuts.spec.ts
+++ b/e2e/pwa-shortcuts.spec.ts
@@ -1,11 +1,11 @@
 import { expect, test } from '@playwright/test'
 
 test.describe('PWA shortcuts', () => {
-  test('settings shortcut opens the English settings dialog', async ({
+  test('settings shortcut route opens the English settings dialog', async ({
     page,
   }) => {
     // Arrange and Act
-    await page.goto('/?action=settings')
+    await page.goto('/shortcuts/settings')
 
     // Assert
     await expect(page).toHaveURL('http://localhost:3009/en')
@@ -14,11 +14,11 @@ test.describe('PWA shortcuts', () => {
     await expect(page.getByTestId('settings-panel')).toBeHidden()
   })
 
-  test('start shortcut starts and resets the default five-minute timer', async ({
+  test('start shortcut route starts and resets the default five-minute timer', async ({
     page,
   }) => {
     // Arrange and Act
-    await page.goto('/?action=start')
+    await page.goto('/shortcuts/start')
 
     // Assert
     await expect(page).toHaveURL('http://localhost:3009/en')
diff --git a/proxy.ts b/proxy.ts
index ce12626..9f36ce3 100644
--- a/proxy.ts
+++ b/proxy.ts
@@ -46,7 +46,7 @@ export default function proxy(request: NextRequest) {
 
 export const config = {
   // Match all pathnames except for
-  // - … if they start with `/api`, `/_next` or `/_vercel`
+  // - … if they start with `/api`, `/shortcuts`, `/_next` or `/_vercel`
   // - … the ones containing a dot (e.g. `favicon.ico`)
-  matcher: ['/((?!api|_next|_vercel|.*\\..*).*)'],
+  matcher: ['/((?!api|shortcuts|_next|_vercel|.*\\..*).*)'],
 }