@sun-asterisk/sungen 2.6.12 → 2.6.15

package/src/orchestrator/templates/ai-instructions/copilot-cmd-run-test.md

@@ -1,7 +1,7 @@
 ---
 name: sungen-run-test
 description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure'
-argument-hint: '[name]'
+argument-hint: "[name] [--env <locale>]"
 tools: [read, execute, edit, vscode/askQuestions, playwright/*]
 ---
 
@@ -11,7 +11,24 @@ You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys
 
 ## Parameters
 
-Parse **name** from `$ARGUMENTS`. If missing, ask the user.
+Parse from `$ARGUMENTS`:
+- **name** — screen or flow name. If missing, ask the user.
+- **`--env <locale>`** — optional. Sets `SUNGEN_ENV=<locale>` for the test run so the runtime test-data resolver merges `<name>.<locale>.yaml` over the base, and `playwright.config.ts` writes results to `<name>-test-result.<locale>.json`. Accept `--locale <locale>` as an alias.
+
+If `--env` is passed but no value follows, ask the user which locale to use.
+
+**`--env <locale>` pre-flight**: when `--env` is passed AND the matching overlay file doesn't exist yet (`test-data/<feature>.<locale>.yaml` missing), tests will silently fall back to base locale — the run will execute but won't actually exercise the locale. Before Phase 0.5, check:
+
+```bash
+ls qa/<screens|flows>/<name>/test-data/*.<locale>.yaml 2>/dev/null | wc -l
+```
+
+Count 0 → offer the user:
+- **Run `/sungen-locale <name> <locale>` first** (Recommended) — bootstrap the overlay
+- **Continue anyway** — tests will likely fail on a real locale page
+- **Cancel**
+
+Skip when `--env` matches the base locale.
 
 **Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
 
@@ -52,7 +69,11 @@ Parse **name** from `$ARGUMENTS`. If missing, ask the user.
      name: "Submit"
    ```
 3. **Phase 0.5 — Auth Persistence**: if the feature has `@auth:<role>` tags and `specs/.auth/<role>.json` is missing/expired, run Phase 0.5 from `sungen-selector-fix` — user logs in manually in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json`. Offer `sungen makeauth <role>` as CLI fallback only if `browser_storage_state` isn't available in this MCP version.
-4. Compile: **Screen**: `sungen generate --screen <name>`. **Flow**: `sungen generate --flow <name>`. Default: runtime data loading from YAML. Use `--inline-data` only if user requests compile-time hardcoded values.
+4. Compile via local-first dispatcher so the sungen monorepo's unpublished selector-resolver features (i18n `{{var}}` interpolation, namespaced selector lookup) are picked up:
+   - **Screen**: `[ -x ./bin/sungen.js ] && ./bin/sungen.js generate --screen <name> || npx sungen generate --screen <name>`
+   - **Flow**: `[ -x ./bin/sungen.js ] && ./bin/sungen.js generate --flow <name> || npx sungen generate --flow <name>`
+
+   Default: runtime data loading from YAML. Use `--inline-data` only if user requests compile-time hardcoded values.
 
 ## Run & Fix (phased — per `sungen-selector-fix` skill)
 
@@ -63,13 +84,30 @@ Parse **name** from `$ARGUMENTS`. If missing, ask the user.
 
 ## Playwright command guidelines
 
-**Per-screen/flow JSON results** — each run must write its JSON report to a dedicated path co-located with the `.spec.ts`, so `sungen delivery` can read the correct results:
+**Multi-feature screens** — `sungen generate --screen <name>` produces one `<basename>.spec.ts` per `.feature` file (e.g. `home.spec.ts` + `home-modal.spec.ts`). You must **invoke playwright once per spec file** so each gets its own JSON result that `sungen delivery` can pick up. Do NOT run a single command with the directory as the test argument — that bundles everything into one results file that delivery can't disambiguate.
+
+**Per-spec JSON results** — each invocation writes its JSON report to a path matching the spec basename. When `--env <locale>` was parsed from `$ARGUMENTS`, prepend `SUNGEN_ENV=<locale>` — `playwright.config.ts` auto-inserts `.<locale>` before `.json` in the output path:
 
 ```bash
-# ✅ Screen
+# ✅ Screen with 1 feature
 PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<name>/<name>-test-result.json \
   npx playwright test specs/generated/<name>/<name>.spec.ts
 
+# ✅ Screen with multiple features — loop in shell:
+for spec in specs/generated/<name>/*.spec.ts; do
+  base=$(basename "$spec" .spec.ts)
+  PLAYWRIGHT_JSON_OUTPUT_NAME="specs/generated/<name>/${base}-test-result.json" \
+    npx playwright test "$spec"
+done
+
+# ✅ Locale 'vi' — same loop, just prepend SUNGEN_ENV=vi
+for spec in specs/generated/<name>/*.spec.ts; do
+  base=$(basename "$spec" .spec.ts)
+  SUNGEN_ENV=vi \
+  PLAYWRIGHT_JSON_OUTPUT_NAME="specs/generated/<name>/${base}-test-result.json" \
+    npx playwright test "$spec"
+done
+
 # ✅ Flow
 PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/flows/<name>/<name>-test-result.json \
   npx playwright test specs/generated/flows/<name>/<name>.spec.ts
@@ -88,7 +126,7 @@ npx playwright test specs/generated/<name>/<name>.spec.ts
 
 If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter override.
 
-`sungen delivery` reads the per-screen file first, falls back to the global `test-results/results.json` if missing.
+`sungen delivery` reads per-feature `<basename>-test-result[.env].json` files (one per feature in the screen) and writes one CSV/XLSX per feature (e.g. `home-testcases.csv` + `home-modal-testcases.csv`). When `--env <locale>` was used here, run delivery with the same locale (`/sungen-delivery <name> --env <locale>`) so it picks the matching `*-test-result.<locale>.json` files and produces `*-testcases.<locale>.csv` / `.xlsx`.
 
 ## Next steps
 

package/src/orchestrator/templates/ai-instructions/copilot-config.md

@@ -20,8 +20,9 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-capture-local` | Load existing UI assets (screenshots, mockups, Figma exports) from `requirements/ui/` |
 | `sungen-capture-live` | Capture a live running page via Playwright MCP (snapshot + screenshot) |
 | `sungen-figma-source` | Figma URL → spec_figma.md + ui/*.png + provisional selectors |
+| `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
 
-## Workflow (6 AI commands)
+## Workflow (7 AI commands)
 
 | Command | What it does |
 |---|---|
@@ -31,9 +32,11 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `/sungen-review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen-run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen-delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |
+| `/sungen-locale <name> <locale>` | Bootstrap i18n for a screen — audit selectors, detect locale switch, generate overlay (run before `/sungen-run-test --env <locale>`) |
 
 **Screen path:** add-screen → create-test → review → run-test → delivery.
 **Flow path:** add-flow → create-test → review → run-test → delivery.
+**i18n path:** (after run-test passes for base locale) → locale → run-test --env <locale> → delivery --env <locale>.
 
 `create-test`, `review`, and `run-test` auto-detect context: if `qa/flows/<name>/` exists → flow mode, else `qa/screens/<name>/` → screen mode.
 

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-locale.md

@@ -0,0 +1,291 @@
+---
+name: sungen-locale
+description: 'Bootstrap i18n for a screen/flow — audit hardcoded selector text, detect locale-switch mechanism via live Playwright, generate test-data overlay file. Auto-loaded by /sungen:locale command.'
+user-invocable: false
+---
+
+## Goal
+
+Take a screen/flow whose `selectors/*.yaml` and `.feature` files were authored against the default locale (usually Vietnamese) and prepare it to run against a second locale. Output:
+
+1. `selectors/<feature>.yaml` — hardcoded `name`/`value` replaced with `{{var}}`
+2. `test-data/<feature>.yaml` — base locale, complete with all new keys
+3. `test-data/<feature>.<locale>.yaml` — overlay with only the keys that change
+4. (Optional) `selectors/<feature>.yaml` Pages block updated when locale uses URL prefix or query param
+
+After this skill finishes, `sungen run-test <name> --env <locale>` Just Works.
+
+## Run mode — Live (preferred) vs Offline (fallback)
+
+Pick mode **once at start**, based on whether MCP Playwright can reach the page.
+
+```
+Try: browser_navigate(baseURL)
+  → succeeds + page renders content → LIVE MODE (all 6 phases)
+  → fails (auth blocked, network down, app broken) → OFFLINE MODE
+    (audit + scaffold template + ask user to fill, skip detection phases)
+```
+
+**Live mode is the value-add** — it auto-detects locale switch mechanism and auto-fills translations. Offline mode just makes the file structure right; user fills in text manually.
+
+Announce which mode is being used before Phase 1.
+
+## Phase 1 — Audit selectors (always, no MCP)
+
+For each `.feature` file under the screen, read the matching `selectors/<feature>.yaml`. List every entry whose `name` or `value` field contains literal text WITHOUT `{{…}}` AND is not a CSS/href selector.
+
+Classify each candidate:
+- **`name` field of `role`-type selector** → very likely locale-dependent
+- **`value` field of `text`-type selector** → very likely locale-dependent
+- **`value` of `locator`-type selector** that contains `:has-text("…")` → check if text is in target language
+- **`value` of `page`-type selector** → URL — handled in Phase 3
+- **CSS / href / attribute selectors** (e.g. `a[href="/awards"]`) → skip, locale-invariant
+
+Print the candidate list as a table:
+
+```
+selector key       | field | hardcoded value           | classification
+-------------------+-------+---------------------------+------------------
+nav about          | name  | Giới thiệu SAA 2025       | locale-dependent
+nav awards         | name  | Thông tin giải thưởng     | locale-dependent
+event date         | name  | 26/12/2025                | maybe (date format)
+nav kudos          | name  | Sun* Kudos                | brand — skip
+```
+
+If zero candidates and zero `{{var}}` already in place → screen has no localizable text. Tell user, stop.
+
+## Phase 2 — Capture base locale (LIVE only)
+
+1. Read `playwright.config.ts` for `baseURL`. Read `Path:` from `.feature` for entry path.
+2. If screen has `@auth:<role>` tags, load `specs/.auth/<role>.json` via `browser_set_storage_state` first.
+3. `browser_navigate(baseURL + entryPath)` then `browser_wait_for` for something stable.
+4. Capture:
+   - `browser_snapshot()` — DOM accessibility tree
+   - `browser_evaluate(() => location.href)` — full URL
+   - `browser_evaluate(() => ({ localStorage: {...localStorage}, cookies: document.cookie }))` — storage state hash
+5. For each Phase-1 candidate: verify the hardcoded text actually appears on the page. Drop ones that don't (stale selectors / false positives).
+
+Save state in memory as `baseLocale = { url, snapshot, storage }`.
+
+If page redirects to `/login` (auth blocker) → stop. Print: *"Auth blocked — cannot capture live page. Re-run with `--offline` flag, or unblock auth first."*
+
+## Phase 3 — Switch locale (LIVE only) — detect mechanism + storage delta
+
+Goal: identify (a) HOW to switch the app to the target locale, and (b) WHAT app-side storage state ends up holding the locale preference so a fresh BrowserContext can be primed identically without driving the UI.
+
+Before triggering the switch, capture full storage baseline:
+
+```js
+const before = await browser_evaluate(() => ({
+  sessionStorage: { ...sessionStorage },
+  localStorage:   { ...localStorage },
+  cookies:        document.cookie,
+  url:            location.href,
+}));
+```
+
+Then try mechanisms in order. First one that produces visibly different text wins. For EACH attempt, capture `after` state and diff against `before`.
+
+**3a. URL prefix**
+- `browser_navigate(baseURL + '/' + locale + entryPath)`
+- Wait, snapshot
+- Compare a known Phase-1 candidate's text vs baseLocale
+- If text differs and page didn't 404 → **URL prefix mechanism**. Save `localePrefix = '/' + locale`.
+
+**3b. Query param** (only if 3a failed)
+- `browser_navigate(baseURL + entryPath + '?lang=' + locale)` (also try `?locale=`, `?lng=`, `?l=`, `?language=`)
+- Same diff check
+- If text differs → **Query param mechanism**. Save the variant that worked.
+
+**3c. Language switcher UI** (only if 3a + 3b failed)
+- Look in base-locale snapshot for buttons matching: `'Select language'`, `'Language'`, `'言語'`, `'Ngôn ngữ'`, role=combobox
+- If found, ask user before clicking
+- `browser_click` the switcher, then the locale option
+- Verify text changed
+- If yes → **UI switcher mechanism**.
+
+**3d. None detected** — ask user how to proceed manually.
+
+### Phase 3.5 — Storage diff (always run after Phase 3 succeeds)
+
+After locale text confirmed switched, capture `after` state and diff per area:
+
+```js
+const after = await browser_evaluate(() => ({
+  sessionStorage: { ...sessionStorage },
+  localStorage:   { ...localStorage },
+  cookies:        document.cookie,
+}));
+const sessionDiff = diffEntries(before.sessionStorage, after.sessionStorage);
+const localDiff   = diffEntries(before.localStorage,   after.localStorage);
+const cookieDiff  = diffCookies(before.cookies, after.cookies);
+```
+
+**Filter noise** — only keep entries where:
+- Key name contains `lang|locale|language|i18n|intl` (case-insensitive), OR
+- Value matches `^[a-z]{2}(-[A-Z]{2})?$` or equals the target locale code
+
+Drop noise: auth tokens (`sb-*`, `*-token`, `*-jwt`), analytics (`_ga*`, `_gid`, `_fbp`), app state (`csrf*`, `last-*`).
+
+**Auto-confidence per entry:**
+- High: key name contains locale-related word AND value is a locale code → KEEP, no prompt
+- Medium: only one signal matches → ask user
+- Low: neither matches but key changed → ask user, default skip
+
+### Phase 3.6 — Verification
+
+For each high/medium-confidence storage entry, verify by setting it manually + reloading:
+
+```js
+await browser_evaluate(`() => sessionStorage.setItem('saa-language-preference', 'en')`);
+await browser_navigate(baseURL);  // reload triggers app to read storage on boot
+await browser_snapshot();
+// confirm a known target-locale string appears
+```
+
+Caveat: hard reload kills any in-memory JWT (auth blocker amplifies failure surface). Skip verification if the screen has `@auth:*` tags and JWT persistence is known broken in the app.
+
+If verification fails → drop confidence one tier, ask user.
+
+Save mechanism + verified storage delta to memory for Phase 6.
+
+## Phase 4 — Diff base ↔ target (LIVE only)
+
+For each candidate from Phase 1 that survived Phase 2:
+- Find the SAME element in target-locale snapshot (match by `role`+position, by `aria-label`, by neighbor structure)
+- Extract its text → `targetText`
+- Pair: `(selectorKey, hardcoded baseText, observed targetText)`
+
+If matching fails for a candidate → mark "needs manual" — flag for user input rather than skip silently.
+
+Result: list of triples `{ selectorKey, baseText, targetText, confidence }`.
+
+## Phase 5 — Confirm + edit (always)
+
+Present the proposal table:
+
+```
+selector key       | base text                | target text          | proposed var     | apply?
+-------------------+--------------------------+----------------------+------------------+-------
+nav about          | Giới thiệu SAA 2025      | About SAA 2025       | nav_about        | [✓]
+nav awards         | Thông tin giải thưởng    | Awards Info          | nav_awards       | [✓]
+nav kudos          | Sun* Kudos               | Sun* Kudos           | —                | [skip — same]
+event date         | 26/12/2025               | 26/12/2025           | —                | [skip — same]
+```
+
+Var names: snake_case the selector key. Avoid collisions with existing test-data keys.
+
+Auto-skip rows where `baseText === targetText` (brand names, locale-invariant numbers).
+
+Ask user: *"Review the table. Confirm to apply / edit individual rows / re-run capture / cancel."*
+
+If user wants to edit a row → fall through to a per-row prompt for `var name` or `targetText` correction.
+
+OFFLINE mode: same table but `target text` column blank — user fills via subsequent prompts or by editing the overlay file after the skill finishes.
+
+## Phase 6 — Apply changes (always, after confirmation)
+
+For each confirmed row:
+
+**6a. Update `selectors/<feature>.yaml`**
+
+Replace `name: '<baseText>'` with `name: '{{<varName>}}'`. Preserve quoting style.
+
+**6b. Update `test-data/<feature>.yaml`** (base locale, complete dictionary)
+
+Append new keys at the end, grouped under a `# === i18n: <screen> ===` comment:
+
+```yaml
+# === i18n: home ===
+nav_about: 'Giới thiệu SAA 2025'
+nav_awards: 'Thông tin giải thưởng'
+```
+
+**6c. Create `test-data/<feature>.<locale>.yaml`** (overlay, only diffs)
+
+```yaml
+# home — <locale> overlay. Only keys that change vs base.
+# Run with: SUNGEN_ENV=<locale> npx playwright test ...
+
+nav_about: 'About SAA 2025'
+nav_awards: 'Awards Info'
+```
+
+**6d. (URL/query mechanism only) Update Pages selectors**
+
+URL prefix:
+
+```yaml
+home:
+  type: 'page'
+  value: '{{base_path}}/'
+awards:
+  type: 'page'
+  value: '{{base_path}}/awards'
+```
+
+Add to test-data:
+```yaml
+# base
+base_path: ''
+
+# overlay
+base_path: '/en'
+```
+
+Query param mechanism: append `query_suffix` similarly.
+
+UI switcher: do NOT modify Pages. Write storage delta into `specs/generated/locale-config.json` (sibling of generated `base.ts` + `locale-fixture.ts`) (6f).
+
+**6f. Storage injection config — `specs/generated/locale-config.json` (sibling of generated `base.ts` + `locale-fixture.ts`)**
+
+Always write `specs/generated/locale-config.json` (sibling of generated `base.ts` + `locale-fixture.ts`) with the verified storage delta from Phase 3.5/3.6. Consumed by `specs/locale-fixture.ts` (auto-generated alongside `specs/base.ts`), which wraps Playwright's context and calls `addInitScript` + `addCookies` BEFORE the first navigation.
+
+Schema:
+
+```json
+{
+  "$schema": "sungen-locale-config-v1",
+  "sessionStorage": {
+    "saa-language-preference": "${SUNGEN_ENV}"
+  },
+  "localStorage": {},
+  "cookies": [],
+  "notes": "Detected by /sungen:locale on YYYY-MM-DD. ..."
+}
+```
+
+Use `"${SUNGEN_ENV}"` (or `"{{SUNGEN_ENV}}"`) as placeholder for runtime substitution. Use hardcoded literals when the stored value is fixed regardless of locale. Drop auth tokens / session IDs even if the Phase 3.5 diff captured them.
+
+Multi-locale projects use the same file — placeholder gets substituted at runtime per locale.
+
+**6e. Compile**
+
+Run `sungen generate --screen <name>` (or `--flow`) and report any compile errors. Selectors changed → compile MUST succeed before run-test.
+
+## Phase 7 — Hand off
+
+Print summary:
+- N selectors converted to `{{var}}`
+- M base keys added to `test-data/<feature>.yaml`
+- K overlay keys written to `test-data/<feature>.<locale>.yaml`
+- Pages selectors updated: yes/no
+- Locale-switching mechanism: URL prefix `/en` / query `?lang=en` / UI switcher / manual
+
+Suggest:
+
+```
+/sungen:run-test <name> --env <locale>
+```
+
+## Multi-feature screens
+
+If the screen has multiple `.feature` files (e.g. `home.feature` + `home-modal.feature`), repeat Phase 1 → Phase 6 for each feature file with its own selectors + test-data pair. Phase 2 + 3 run **once per screen** — mechanism is the same. Phase 4 runs per feature because UI scope differs.
+
+## What NOT to do
+
+- Do not edit `.feature` files. The i18n shape is already correct there (`{{var}}` was the convention from the start). Only selectors + test-data need surgery.
+- Do not write a separate selectors file per locale (`home.en.yaml`). One selectors file with `{{var}}` works across all locales.
+- Do not delete keys from the base `test-data/<feature>.yaml`. Always append.
+- Do not run tests in this skill. Hand off to `/sungen:run-test`.
+- Do not commit. Hand off to user.

package/src/orchestrator/templates/playwright.config.ts

@@ -1,5 +1,27 @@
 import { defineConfig, devices } from '@playwright/test';
 
+/**
+ * Resolve the JSON reporter output path.
+ *
+ * Precedence:
+ *   1. `PLAYWRIGHT_JSON_OUTPUT_NAME` if set — used as-is, but a `.<env>`
+ *      segment is inserted before the extension when `SUNGEN_ENV` is also set
+ *      so per-locale runs don't overwrite each other.
+ *   2. `SUNGEN_ENV` only → `test-results/results.<env>.json`.
+ *   3. Otherwise → `test-results/results.json`.
+ */
+function resolveJsonOutputFile(): string {
+  const explicit = process.env.PLAYWRIGHT_JSON_OUTPUT_NAME;
+  const env = process.env.SUNGEN_ENV;
+  if (explicit) {
+    if (!env) return explicit;
+    return explicit.endsWith('.json')
+      ? `${explicit.slice(0, -'.json'.length)}.${env}.json`
+      : `${explicit}.${env}`;
+  }
+  return env ? `test-results/results.${env}.json` : 'test-results/results.json';
+}
+
 /**
  * Read environment variables from file.
  * https://github.com/motdotla/dotenv
@@ -28,16 +50,11 @@ export default defineConfig({
   /* Reporter to use. See https://playwright.dev/docs/test-reporters */
   /* JSON reporter is required by `sungen delivery` to populate test result columns in the exported CSV. */
   /* Output file path is controlled by PLAYWRIGHT_JSON_OUTPUT_NAME env var for per-screen isolation. */
+  /* When SUNGEN_ENV is set, the env name is inserted before `.json` so locale */
+  /* runs don't overwrite each other (e.g. `<name>-test-result.vi.json`). */
   reporter: [
     ['html'],
-    [
-      'json',
-      {
-        outputFile:
-          process.env.PLAYWRIGHT_JSON_OUTPUT_NAME ||
-          'test-results/results.json',
-      },
-    ],
+    ['json', { outputFile: resolveJsonOutputFile() }],
   ],
   /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
   use: {

package/src/orchestrator/templates/specs-base.ts

@@ -1,4 +1,5 @@
 import { test as base, expect, type Page } from '@playwright/test';
+import { applyLocaleInjection } from './locale-fixture';
 
 type CleanupConfig = {
   overlay?: boolean;
@@ -66,6 +67,14 @@ const test = base.extend<{
 }>({
   screenshotOnFailure: [false, { option: true }],
 
+  // Wrap the default `context` fixture so locale state (sessionStorage,
+  // localStorage, cookies) is injected before the first page navigation.
+  // No-op when SUNGEN_ENV is unset or specs/locale-config.json is missing.
+  context: async ({ context }, use) => {
+    await applyLocaleInjection(context);
+    await use(context);
+  },
+
   page: async ({ context }, use) => {
     const page = await context.newPage();
     await use(page);

package/src/orchestrator/templates/specs-locale-fixture.ts

@@ -0,0 +1,105 @@
+/**
+ * Locale state injection — wired into the sungen base test fixture.
+ *
+ * Reads `specs/locale-config.json` (managed by the `/sungen:locale` skill)
+ * and uses `addInitScript` + `addCookies` to seed any sessionStorage /
+ * localStorage / cookie values that the app uses to remember locale.
+ *
+ * Active only when `SUNGEN_ENV` is set. When unset (default base-locale
+ * runs), every call is a no-op so existing test suites are unaffected.
+ *
+ * Auto-managed by `/sungen:locale` — edit `specs/locale-config.json`
+ * rather than this file. If the schema needs to change, update the skill
+ * `sungen-locale` so future captures stay in sync.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { BrowserContext } from '@playwright/test';
+
+interface LocaleCookie {
+  name: string;
+  value: string;
+  domain?: string;
+  url?: string;
+  path?: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'Strict' | 'Lax' | 'None';
+}
+
+interface LocaleInjection {
+  /** Values to write into `sessionStorage` via `addInitScript`. */
+  sessionStorage?: Record<string, string>;
+  /** Values to write into `localStorage` via `addInitScript`. */
+  localStorage?: Record<string, string>;
+  /** Cookies to set via `context.addCookies`. Either `domain` or `url` is required. */
+  cookies?: LocaleCookie[];
+  /** Optional notes from `/sungen:locale` capture — informational only. */
+  notes?: string;
+}
+
+let cached: LocaleInjection | null | undefined;
+
+function loadLocaleConfig(): LocaleInjection | null {
+  if (cached !== undefined) return cached;
+  try {
+    const cfgPath = path.join(__dirname, 'locale-config.json');
+    if (!fs.existsSync(cfgPath)) {
+      cached = null;
+      return null;
+    }
+    const parsed = JSON.parse(fs.readFileSync(cfgPath, 'utf-8')) as LocaleInjection;
+    cached = parsed;
+    return parsed;
+  } catch {
+    cached = null;
+    return null;
+  }
+}
+
+function interpolate(value: string, locale: string): string {
+  return value.replace(/\$\{SUNGEN_ENV\}/g, locale).replace(/\{\{SUNGEN_ENV\}\}/g, locale);
+}
+
+/**
+ * Apply locale state to a freshly-created BrowserContext.
+ * Must be called BEFORE the first page navigation so the `addInitScript`
+ * runs ahead of any app code that reads storage on boot.
+ *
+ * No-op when `SUNGEN_ENV` is unset or `specs/locale-config.json` is missing.
+ */
+export async function applyLocaleInjection(context: BrowserContext): Promise<void> {
+  const locale = process.env.SUNGEN_ENV;
+  if (!locale) return;
+  const cfg = loadLocaleConfig();
+  if (!cfg) return;
+
+  const sessionEntries = Object.entries(cfg.sessionStorage ?? {}).map(
+    ([k, v]) => [k, interpolate(String(v), locale)] as const,
+  );
+  const localEntries = Object.entries(cfg.localStorage ?? {}).map(
+    ([k, v]) => [k, interpolate(String(v), locale)] as const,
+  );
+
+  if (sessionEntries.length || localEntries.length) {
+    await context.addInitScript(
+      ({ sessionEntries, localEntries }) => {
+        for (const [k, v] of sessionEntries) sessionStorage.setItem(k, v);
+        for (const [k, v] of localEntries) localStorage.setItem(k, v);
+      },
+      { sessionEntries, localEntries },
+    );
+  }
+
+  if (cfg.cookies?.length) {
+    await context.addCookies(
+      cfg.cookies.map((c) => ({
+        ...c,
+        value: interpolate(c.value, locale),
+        path: c.path ?? '/',
+      })),
+    );
+  }
+}

package/dist/orchestrator/templates/playwright.config.d.ts

@@ -1,10 +0,0 @@
-/**
- * Read environment variables from file.
- * https://github.com/motdotla/dotenv
- */
-/**
- * See https://playwright.dev/docs/test-configuration.
- */
-declare const _default: import("@playwright/test").PlaywrightTestConfig<{}, {}>;
-export default _default;
-//# sourceMappingURL=playwright.config.d.ts.map

package/dist/orchestrator/templates/playwright.config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"playwright.config.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/playwright.config.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAKH;;GAEG;;AACH,wBAiGG"}