test(02-05): playwright e2e for PIPE-07 — full Phase-2 loop

- tests/e2e/season1-loop.spec.ts: PIPE-07 smoke covering load → Begin → plant rosemary → fast-forward FakeClock 3min → harvest → fragment-reveal modal → close → journal-icon visible → open journal → fragment present → reload page → fragment persists. Sidesteps Phaser canvas pixel-clicking via window.__tlgStore command dispatch (test-only window slot, production-guarded by import.meta.env.PROD). - playwright.config.ts: bumped webServer timeout 30s → 60s for cold Vite startup; pinned port 5273 + --strictPort to avoid collisions with other dev servers on the user's machine; reuseExistingServer false so the spec always starts a fresh Vite against this project. - package.json: added test:e2e script (npx playwright test). Not added to npm run ci — Playwright is slower than Vitest; manual run before /gsd-verify-work + future v1 release pipeline. - src/content/loader.ts (Rule 3 — Blocking): replaced gray-matter with a 15-line parseFrontmatter helper. gray-matter pulls in Node's Buffer global which is undefined in Vite's browser bundle; the build emits a 'Module "buffer" externalized' warning that masks the runtime ReferenceError. Surfaced under Vite dev mode while running the e2e — Plan 02-03's Markdown loader path (lura-first- letter.md + winter-rose-night.md) was effectively broken in real browsers since shipping. parseFrontmatter handles the strict '---<yaml>---<body>' shape the .md fragments use; bundle dropped from 2.2MB to 1.9MB as a side effect of dropping the unused dep. - deferred-items.md: tracks the gray-matter package.json cleanup (the dep is now unused but kept in package.json for now, scoped out of this plan). - npx playwright test exits 0 (1 spec, 1.5s test runtime); npm run ci exits 0; 308/308 vitest still green. PIPE-07 satisfied end-to-end.
2026-05-09 11:04:32 -04:00
parent 5d58d6cc7b
commit dd486969a9
5 changed files with 304 additions and 16 deletions
@@ -0,0 +1,26 @@
+# Phase 2 — Deferred Items
+
+Items discovered during execution that are out-of-scope for the current
+plan but should be tracked. Each entry includes the discovering plan,
+the resolution path, and any blocking implications.
+
+## Plan 02-05 — Discovered
+
+### `gray-matter` package can be removed from package.json (cleanup)
+
+- **Found during:** Plan 02-05 Task 3 — running the Playwright e2e
+  surfaced a runtime `Buffer is not defined` error in `gray-matter`
+  under Vite's dev-mode browser bundle. Replaced with a 15-line
+  inline frontmatter parser (`parseFrontmatter` in
+  `src/content/loader.ts`) since the only usage was for stripping
+  YAML frontmatter from two `.md` files (Plan 02-03 authored).
+- **Status:** No code references `gray-matter` anymore (verified via
+  `grep -r grayMatter src/` returns zero hits). The dep remains in
+  `package.json` — removing it is a cleanup task, not blocking.
+- **Resolution:** A future maintenance commit can run
+  `npm uninstall gray-matter` to drop the dep + lockfile entry.
+  Bundle size is already smaller (1.9MB vs 2.2MB) because Rolldown
+  tree-shakes the unused module.
+- **Why deferred:** Out of Plan 02-05 scope (touched only as a Rule 3
+  blocking-issue auto-fix); changing dependencies in package.json
+  beyond the minimal fix expands surface unnecessarily.
@@ -14,6 +14,7 @@
    "validate:assets": "node scripts/validate-assets.mjs",
    "check:bundle-split": "node scripts/check-bundle-split.mjs",
    "compile:ink": "node scripts/compile-ink.mjs",
+    "test:e2e": "playwright test",
    "ci": "npm run lint && npm run compile:ink && npm run test && npm run validate:assets && npm run build && npm run check:bundle-split"
  },
  "dependencies": {
@@ -1,16 +1,30 @@
 import { defineConfig } from '@playwright/test';

-// Phase 1: Playwright is installed and configured but ships no specs.
-// First spec lands in Phase 2 (PIPE-07) — a smoke test that asserts the
-// "Tend the garden / Begin" gesture screen mounts and CORE-01 (game loads
-// in <5s) holds. This config exists so Plan 01 proves Playwright is wired.
+// Phase 2 Plan 02-05 — PIPE-07 smoke test landed here. The spec under
+// tests/e2e/season1-loop.spec.ts exercises the full Season-1 loop
+// (load → Begin → plant → fast-forward → harvest → reveal → journal →
+// reload → persist) using FakeClock injection via the ?devtime=fake URL
+// flag (production-guarded by import.meta.env.PROD).
+//
+// webServer.timeout bumped to 60s to absorb Vite dev server's first-time
+// transform of the entry bundle (~2.2MB; typically <8s warm but can
+// exceed 30s cold on a fresh node_modules/.vite cache).
+// Phase 2 Plan 02-05 — Port 5273 chosen to avoid colliding with another
+// Vite project on the dev machine that's bound to the default 5173.
+// reuseExistingServer is intentionally false so the webServer always
+// starts fresh against this project's vite.config.ts (or default port
+// flag below) — `--port 5273 --strictPort` ensures we fail loudly if
+// the port is also taken rather than silently latching onto another app.
+const E2E_PORT = 5273;
+const E2E_BASE_URL = `http://localhost:${E2E_PORT}`;
+
 export default defineConfig({
  testDir: 'tests/e2e',
-  use: { baseURL: 'http://localhost:5173' },
+  use: { baseURL: E2E_BASE_URL },
  webServer: {
-    command: 'npm run dev',
-    url: 'http://localhost:5173',
-    reuseExistingServer: true,
-    timeout: 30_000,
+    command: `npm run dev -- --port ${E2E_PORT} --strictPort`,
+    url: E2E_BASE_URL,
+    reuseExistingServer: false,
+    timeout: 60_000,
  },
 });
@@ -1,4 +1,3 @@
-import grayMatter from 'gray-matter';
 import { parse as parseYAML } from 'yaml';
 import {
  SeasonContentSchema,
@@ -8,6 +7,31 @@ import {
  type UiStrings,
 } from './schemas/index.ts';

+/**
+ * Minimal frontmatter splitter — replaces gray-matter for the Markdown
+ * fragment loader. gray-matter pulls in `Buffer` (Node-only), which
+ * breaks under Vite's browser bundle (Plan 02-05 found this — gray-matter
+ * was working only at build time because Vite externalized buffer with
+ * a warning, but the runtime ReferenceError surfaced in dev mode).
+ *
+ * The Markdown fragments under /content/seasons/<slug>/fragments/*.md
+ * have a strict shape: `---\n<yaml>\n---\n<body>`. This parser handles
+ * exactly that shape; anything else throws so the build / module-eval
+ * fail loudly per PIPE-01.
+ */
+function parseFrontmatter(raw: string): { data: unknown; content: string } {
+  // Strip a leading UTF-8 BOM if present.
+  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+  // Match `---\n<yaml>\n---\n<rest>` (allow CRLF line endings too).
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) {
+    return { data: {}, content: text };
+  }
+  const [, yamlBlock, body] = match;
+  const data = parseYAML(yamlBlock ?? '');
+  return { data: data ?? {}, content: body ?? '' };
+}
+
 /**
 * Vite-native content pipeline (PIPE-01). The glob patterns MUST be
 * string literals at the call site — Vite's plugin walks the AST at build
@@ -47,8 +71,8 @@ function loadYamlFragments(): Fragment[] {

 function loadMdFragments(): Fragment[] {
  return Object.entries(mdFiles).map(([path, raw]) => {
-    const { data, content } = grayMatter(raw);
-    const merged = { ...data, body: content.trim() };
+    const { data, content } = parseFrontmatter(raw);
+    const merged = { ...(data as Record<string, unknown>), body: content.trim() };
    const parsed = FragmentSchema.safeParse(merged);
    if (!parsed.success) {
      throw new Error(`[content] schema violation in ${path}\n${parsed.error.message}`);
@@ -108,8 +132,8 @@ export async function loadSeasonFragments(seasonId: number): Promise<Fragment[]>
  const mdOut: Fragment[] = [];
  for (const [path, loader] of mdMatch) {
    const raw = (await loader()) as string;
-    const { data, content } = grayMatter(raw);
-    const merged = { ...data, body: content.trim() };
+    const { data, content } = parseFrontmatter(raw);
+    const merged = { ...(data as Record<string, unknown>), body: content.trim() };
    const parsed = FragmentSchema.safeParse(merged);
    if (!parsed.success) {
      throw new Error(`[content] schema violation in ${path}\n${parsed.error.message}`);
@@ -165,8 +189,11 @@ export function loadFragmentsFromGlob(
    return parsed.data.fragments;
  });
  const md = Object.entries(mdGlob).map(([path, raw]) => {
-    const { data, content } = grayMatter(raw);
-    const parsed = FragmentSchema.safeParse({ ...data, body: content.trim() });
+    const { data, content } = parseFrontmatter(raw);
+    const parsed = FragmentSchema.safeParse({
+      ...(data as Record<string, unknown>),
+      body: content.trim(),
+    });
    if (!parsed.success) {
      throw new Error(`[content] schema violation in ${path}: ${parsed.error.message}`);
    }
@@ -0,0 +1,220 @@
+import { test, expect, type Page } from '@playwright/test';
+
+/**
+ * PIPE-07 — Phase-2 Season-1 full-loop smoke test.
+ *
+ * Exercises the architecture firewall + save round-trip + FakeClock
+ * fast-forward end-to-end:
+ *
+ *   load (?devtime=fake) → Begin → plant rosemary → fast-forward 3min
+ *   → harvest → fragment-reveal modal → close → journal-icon visible
+ *   → open journal → fragment present → reload page → fragment persists
+ *
+ * The spec uses the test-only window slots PhaserGame.tsx exposes when
+ * the URL flag is set:
+ *   - window.__tlgFakeClock — FakeClock instance with .advance(ms)
+ *   - window.__tlgStore     — appStore (zustand vanilla) for command
+ *                              dispatch + state read
+ * The slots are gated by import.meta.env.PROD so they never appear in
+ * production builds.
+ *
+ * Avoiding pixel-precise canvas clicks: this spec dispatches sim
+ * commands via __tlgStore.enqueueCommand({...}) rather than clicking
+ * tiles in the Phaser canvas. The behavioral coverage (the sim runs the
+ * harvest pipeline → selector picks a fragment → reveal modal pops → it
+ * lands in the journal → reload restores via the save layer) is the
+ * load-bearing verification.
+ */
+
+interface DevTimeWindow {
+  __tlgFakeClock?: { advance: (ms: number) => void };
+  __tlgStore?: {
+    getState: () => {
+      enqueueCommand: (cmd: {
+        kind: 'plantSeed' | 'harvest' | 'compost';
+        tileIdx: number;
+        plantTypeId?: string;
+      }) => void;
+      tiles: Array<{ idx: number; plant: { plantTypeId: string } | null } | null>;
+      harvestedFragmentIds: string[];
+      fragmentRevealId: string | null;
+      pendingCommands: { kind: string }[];
+    };
+  };
+}
+
+async function ensureFreshSave(page: Page): Promise<void> {
+  // Clear IDB + localStorage so each test run starts at first-run state.
+  // Must happen AFTER navigation (browser context required).
+  await page.evaluate(async () => {
+    try {
+      indexedDB.deleteDatabase('tlg-save');
+    } catch {
+      /* no-op */
+    }
+    try {
+      localStorage.clear();
+    } catch {
+      /* no-op */
+    }
+  });
+}
+
+test.describe('PIPE-07 — Season 1 full loop', () => {
+  test('load → begin → plant → fast-forward → harvest → reveal → journal → reload → persist', async ({
+    page,
+  }) => {
+    // 1) Initial navigation to clear state.
+    await page.goto('/?devtime=fake');
+    await ensureFreshSave(page);
+    // Reload after clearing so the boot path sees a fresh DB.
+    await page.goto('/?devtime=fake');
+
+    // 2) Begin screen visible (first run).
+    const beginButton = page.getByRole('button', { name: 'Begin' });
+    await expect(beginButton).toBeVisible({ timeout: 15000 });
+
+    // 3) Press Begin to dismiss + bootstrap audio.
+    await beginButton.click();
+    await expect(beginButton).not.toBeVisible({ timeout: 5000 });
+
+    // 4) Wait for the test-exposed store + fake clock.
+    await page.waitForFunction(() => {
+      const w = window as unknown as DevTimeWindow;
+      return Boolean(w.__tlgStore && w.__tlgFakeClock);
+    });
+
+    // 5) Enqueue a plantSeed command on tile 0.
+    await page.evaluate(() => {
+      const w = window as unknown as DevTimeWindow;
+      w.__tlgStore!.getState().enqueueCommand({
+        kind: 'plantSeed',
+        tileIdx: 0,
+        plantTypeId: 'rosemary',
+      });
+    });
+
+    // 6) Advance the FakeClock by 1s so the Garden scene's update()
+    //    drains a tick and applies the plantSeed command.
+    await page.evaluate(() => {
+      const w = window as unknown as DevTimeWindow;
+      w.__tlgFakeClock!.advance(1000);
+    });
+
+    // Wait for the plantSeed to be applied to tile 0.
+    await page.waitForFunction(
+      () => {
+        const w = window as unknown as DevTimeWindow;
+        return (
+          w.__tlgStore!.getState().tiles[0]?.plant?.plantTypeId === 'rosemary'
+        );
+      },
+      { timeout: 5000 },
+    );
+
+    // 7) Fast-forward growth past 600 ticks (5Hz * 600 = 120s = 2min).
+    //    Advance 3 minutes wall-clock so the rosemary plant is solidly
+    //    in the 'ready' stage.
+    await page.evaluate(() => {
+      const w = window as unknown as DevTimeWindow;
+      w.__tlgFakeClock!.advance(3 * 60 * 1000);
+    });
+
+    // Give the Phaser scene a frame to drain ticks.
+    await page.waitForTimeout(500);
+
+    // 8) Enqueue harvest on tile 0.
+    await page.evaluate(() => {
+      const w = window as unknown as DevTimeWindow;
+      w.__tlgStore!.getState().enqueueCommand({
+        kind: 'harvest',
+        tileIdx: 0,
+      });
+    });
+
+    // Advance the clock + wait for the Phaser scene's update loop to
+    // drain the harvest command. drainCommands runs once per drainTicks
+    // call, which fires once per requestAnimationFrame tick.
+    await page.evaluate(() => {
+      const w = window as unknown as DevTimeWindow;
+      w.__tlgFakeClock!.advance(2000);
+    });
+
+    // Wait for the harvest to actually commit (fragmentRevealId set).
+    await page.waitForFunction(
+      () => {
+        const w = window as unknown as DevTimeWindow;
+        const s = w.__tlgStore!.getState();
+        return (
+          s.harvestedFragmentIds.length > 0 && s.fragmentRevealId !== null
+        );
+      },
+      { timeout: 15000 },
+    );
+
+    // 9) Fragment reveal modal appears with text from a Season 1 fragment.
+    await expect(
+      page.getByRole('dialog', { name: 'A new memory' }),
+    ).toBeVisible({ timeout: 10000 });
+
+    // 10) Capture the harvested fragment id via store.
+    const harvestedId = await page.evaluate(() => {
+      const w = window as unknown as DevTimeWindow;
+      const ids = w.__tlgStore!.getState().harvestedFragmentIds;
+      return ids[ids.length - 1] as string;
+    });
+    expect(harvestedId).toMatch(/^season1\.soil\./);
+
+    // 11) Close reveal modal (Close button has aria-label="Close").
+    await page
+      .getByRole('button', { name: 'Close' })
+      .first()
+      .click();
+    await expect(
+      page.getByRole('dialog', { name: 'A new memory' }),
+    ).not.toBeVisible({ timeout: 5000 });
+
+    // 12) Journal icon appears in corner (D-23: reveals after first harvest).
+    await expect(page.getByTestId('journal-icon')).toBeVisible();
+
+    // 13) Open Journal modal and confirm fragment text + selectable.
+    await page.getByTestId('journal-icon').click();
+    const journal = page.getByRole('dialog', { name: 'Memory Journal' });
+    await expect(journal).toBeVisible();
+    await expect(
+      journal.locator(`[data-fragment-id="${harvestedId}"]`),
+    ).toBeVisible();
+
+    // 14) Reload — fragment must persist (CORE-04 + Phase-2 save lifecycle).
+    //     The save lifecycle hooks (visibilitychange→hidden +
+    //     beforeunload) fire on reload, writing the current state to
+    //     LocalStorage synchronously and best-effort to IDB.
+    await page.reload();
+
+    // Wait for boot to complete; the begin screen should NOT appear
+    // (returning player path).
+    await page.waitForFunction(() => {
+      const w = window as unknown as DevTimeWindow;
+      return Boolean(w.__tlgStore);
+    });
+    await expect(
+      page.getByRole('button', { name: 'Begin' }),
+    ).not.toBeVisible({ timeout: 10000 });
+
+    // 15) The harvested fragment is still in the store.
+    const harvestedAfterReload = await page.evaluate(() => {
+      const w = window as unknown as DevTimeWindow;
+      return w.__tlgStore!.getState().harvestedFragmentIds;
+    });
+    expect(harvestedAfterReload).toContain(harvestedId);
+
+    // 16) Journal still shows the fragment after reload.
+    await expect(page.getByTestId('journal-icon')).toBeVisible();
+    await page.getByTestId('journal-icon').click();
+    await expect(
+      page
+        .getByRole('dialog', { name: 'Memory Journal' })
+        .locator(`[data-fragment-id="${harvestedId}"]`),
+    ).toBeVisible();
+  });
+});