@sun-asterisk/sungen 3.2.22-beta.1 → 3.2.22-beta.2

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -27,21 +27,26 @@ AND    →  inherits from preceding keyword
 
 ## Step Patterns (70 patterns)
 
+> **Platform legend:** unmarked = `[both]` (compiles on Playwright AND Appium). `[web]` = compiles
+> only on Playwright — the Appium template throws, naming the reason. `[mobile]` = mobile-only
+> vocabulary with no web counterpart. Every marking is checked against a shipped `.hbs` — see
+> **Platform Support** at the end of this section for the full web-only/mobile-only/divergence list.
+
 ### Setup / Form / Interaction
 
 ```
 User is on [T] page | page with {{v}} | dialog
 User fill [T] field | textarea | search | slider | date-picker with {{v}}
-User fill [T] uploader with {{f}}
+User fill [T] uploader with {{f}}                                    [web]
 User clear [T] field
 User check [T] checkbox | toggle | radio
 User uncheck [T] checkbox | toggle
 User select [T] dropdown with {{v}}
 User click [T] button | tab | column | breadcrumb
 User click [T] row with {{v}}
-User try to click [T] button | link          # DISABLED element only — see rule below (v3.3)
+User try to click [T] button | link          # DISABLED element only — see rule below (v3.3) [web]
 User double click [T] element
-User hover [T] icon | row
+User hover [T] icon | row                    # no-op on mobile (see Platform Support)
 User drag [T] to [T2]
 User expand | collapse [T] row
 ```
@@ -60,15 +65,15 @@ NEVER use it for a click that is supposed to work — it deletes the actionabili
 User click [T] button and accept [OK] alert       # PREFERRED (v3.3): natural order,
 User click [T] button and dismiss [Cancel] alert  # compiler registers the listener first
 User click [OK | Cancel] alert                    # two-step form: must come BEFORE the trigger
-User fill [T] alert with {{v}}
+User fill [T] alert with {{v}}                    # no-op on mobile — native prompt fill is app-specific
 User see [message text] alert
 User press Escape key | [Enter] key | Tab key 5 times | Enter on [T] field
-User wait for N seconds | [T] page
+User wait for N seconds | [T] page                # [T] page: web waits for the URL; mobile pauses (settle) — see Platform Support
 User wait for [T] TYPE is visible | hidden | enabled | disabled     # ANY reference (v3.3)
 User wait for [T] TYPE with {{v}}                                    # until it shows the value
 User wait for [T] table to refresh                                   # filter/search/pagination round-trip (v3.3)
 User scroll to [T] section
-User switch to [T] frame | [main] frame
+User switch to [T] frame | [main] frame           # web: iframe; mobile: hybrid-app WebView context (no-op if the screen has no WebView)
 ```
 
 > **Browser alerts (native `window.confirm/alert/prompt` only):** prefer the compound form —
@@ -81,7 +86,7 @@ User switch to [T] frame | [main] frame
 > `wait for N seconds` stays a last resort. `table to refresh` watches the app's loading
 > indicator (`qa/app.yaml` `feedback.loading.indicator`, default `[aria-busy="true"]`).
 
-### Positional table rows (v3.3)
+### Positional table rows (v3.3) `[web]`
 
 ```
 User remember [Col] column in [T] table row {{n}} as {{var}}   # read a cell by POSITION
@@ -135,6 +140,11 @@ Two asymmetries worth knowing rather than discovering:
 2. **A repeated param matches as a subset per key**, which is the same rule as "extra params are
    tolerated": every value you declare must be present, and the URL may carry more.
 
+> **Mobile:** `Then User is on [T] page` **throws** (no URL/address bar on native). `Then User see
+> [T] page` \| `page with {{v}}` **silently no-ops** — the compiled step asserts nothing and the
+> scenario passes regardless. Never use Pattern 8 to prove "landed on screen X" on mobile — assert
+> a screen-marker element instead (`Then User see [X] header`).
+
 The predicate itself lives in `specs/url-assert.ts` (auto-generated, `DO NOT EDIT`). If `[T]` has no
 `type: page` selector entry — or its key collides with a non-page entry, so `value` is something like
 `button` rather than a URL — the step falls back to another path and cannot match the real URL. The
@@ -152,7 +162,7 @@ User see all [Product Card] contain [Add To Cart] button
 
 Use the all-card form whenever a title claims *every / each* card/row exposes something — a single `User see [Add To Cart] button` does NOT prove "each card" and the harness Claim-Proof gate will flag it.
 
-### Table
+### Table `[web]`
 
 ```
 User see [Col] column in [Table] table
@@ -176,7 +186,7 @@ first contact row:
 ```
 → compiles to `expect(table.locator('tbody tr:first-child')).toContainText(v)` — the exact row must hold the value — and still enters row scope for `[Col] column` checks.
 
-### Browser storage (web)
+### Browser storage `[web]`
 
 ```
 Then User see [KEY] in local storage exists
@@ -189,7 +199,7 @@ Then User see key matching "PATTERN" in local storage      # regex over key name
 
 `[KEY]` is a **storage key, not a selector** — never add it to selectors.yaml. It may embed `{{vars}}`: `[{{exclusive_code}}_ACCESS_TOKEN]`. The check runs inside the browser and returns only a boolean, so a failure message never contains the stored value (safe for tokens). There is deliberately no `equals {{expected}}` form. ⚠️ `expect [KEY] in local storage …` is NOT valid (`expect` reads `{{response}}` refs only) — the compiler warns SG-W011.
 
-### Tab order (web only)
+### Tab order `[web]`
 
 ```
 Then User see tab order:
@@ -201,7 +211,7 @@ Then User see tab order:
 
 Focuses row 1 (the pinned origin — there is no separate `focus [X]` step) and asserts it actually HOLDS focus (a non-focusable ref fails loudly), then presses Tab per following row and asserts it receives focus. Cell refs ARE selector references (resolved via selectors.yaml; optional element type after the ref). Requires the `| Ref |` header and ≥2 element rows — a missing header or single row is a compile error, never an empty pass. A mismatch reports the expected ref + the actual focused element (shadow-DOM-aware tag/role/name). Limitations: web only (no Appium); declare tab order OUTSIDE `use dialog`/frame scope (cell locators render page-rooted — put `scope: dialog` on the selector ENTRIES if the elements live in a dialog); focus traps / dynamic comboboxes / `tabindex=-1` reordering / WebKit differences may need `@manual` keyboard-only audits — those stay legitimate manuals.
 
-### Network mocking (optional Mock Driver — `sungen capability add mock`)
+### Network mocking `[web]` (optional Mock Driver — `sungen capability add mock`)
 
 ```gherkin
 @mock
@@ -294,6 +304,42 @@ Full-shape contract check: `expect {{name.body}} matches schema [Ref]` validates
 - **Error (4xx/5xx)** → assert the status (via `@cases` `expect_status` or an explicit `is 4xx`); assert the error message field when the contract defines one.
 - **Anti-pattern** — re-asserting the value you just sent (`{{x.body.email}} is {{email}}` on the thing you created) proves little; assert a **server-derived** field (id, timestamp, computed status) or read it back.
 
+### Platform Support — web-only / mobile-only / divergences
+
+Every claim below is checked against a shipped `.hbs` under
+`adapters/{playwright,appium}/templates/steps/` or a shipped diagnostic — see
+`tests/codegen/adapter-template-parity.run.ts` `DIVERGENCES` for the authoritative one-sided list.
+
+**Web-only `[web]`** — the Appium template throws, naming the reason: `fill [T] uploader with
+{{f}}`, Positional table rows, the whole Table section, Browser storage, Tab order, `@mock`,
+`Then User is on [T] page` (route-assertion). Each targets something native has no equivalent for
+(HTML `<table>`, `<input type=file>`, DOM storage, keyboard-focus traversal, `page.route`, a URL bar).
+
+**Mobile-only `[mobile]`** — the gesture catalog (swipe, long-press, pinch-zoom, pull-to-refresh,
+rotate, background/foreground, notifications, grant-permission, clipboard set, set-geolocation,
+hide-keyboard, tap-top-of) has no web counterpart. Full syntax → `sungen-mobile-gestures`.
+
+**Divergences — compiles on both, means something different:**
+
+| Step | Web | Mobile |
+|---|---|---|
+| `see [T] page` \| `page with {{v}}` | asserts path+query | **silent no-op** — asserts nothing; the scenario passes regardless. Assert a screen-marker element instead |
+| `is on [T] page` \| `open [T] page` (Given/When) | navigates via URL | no-op — the app is already launched; use tap/gesture steps for mobile screen changes |
+| `wait for [T] page` | waits for the URL | fixed `driver.pause(500)` settle — not a real wait condition |
+| `hover [T] icon \| row` | real hover | no-op — hover-revealed content is normally already visible on mobile; use `tap` |
+| `fill [T] alert with {{v}}` | fills native `prompt()` | no-op (comment only) — app-specific, handle manually |
+| `switch to [T] frame` | enters an `<iframe>` | switches a hybrid app's WebView context; no-op on a pure-native screen (no WebView found) |
+| `see [X] with {{v}}` (filtered visibility forms) | CSS `hasText` filter | hand-rolled substring match over `getText()`/`content-desc` (Android) or `label`/`value` (iOS) — same substring semantics, different attribute set |
+| `… is sorted …` / `… is loading` inside a filtered row/state check | reads `aria-sort`/`aria-busy` | **throws** — no native analog for these two states specifically (the plain, unfiltered `is loading` on a spinner still works on both) |
+| `scope: dialog` selector option | resolves inside the dialog | no effect (`SG-W021`) — steps resolve against the whole screen |
+| `open notification panel` (mobile gesture) | n/a | Android-only — throws on iOS |
+
+**Partial support, not full unsupported** — read the `.hbs` before marking anything `[web]`:
+`all-contain-*`, `check`/`uncheck`/`toggle-action`, `contain-text`/`have-text-assertion`,
+`visible-filtered-assertion`, `disabled`/`hidden-with-filter-assertion` are fully supported on
+mobile even though a grep shows a `throw` somewhere in their file — the throw is a normal
+zero-match assertion failure, not a platform gap.
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`
@@ -366,6 +412,9 @@ award:
 
 Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `columns`
 
+`scope` (e.g. `scope: dialog`) is `[web]`-effective only — no Appium template reads `inDialog`, so
+on mobile a dialog-scoped ref still resolves against the whole screen (`SG-W021`).
+
 ## Tags
 
 ### Functional tags (affect code generation)
@@ -383,7 +432,7 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (cleanupPage) |
 | `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (cleanupPage) |
 | `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
-| `@parallel` | Opt-out: fresh page per test instead of serial default (for independent scenarios) |
+| `@parallel` | Opt-out: fresh page per test instead of serial default (for independent scenarios). Compiles on mobile too, but a single device/emulator gets no session-isolation benefit from it |
 | `@beforeAll` | Hook: runs once before all tests → `test.beforeAll()` |
 | `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
 | `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |

package/src/orchestrator/templates/ai-src/skills/sungen-mobile-gestures/SKILL.md

@@ -10,7 +10,8 @@ Document the **mobile-only interactions** that have no web equivalent, so the AI
 during exploration via Appium MCP and (b) write Gherkin steps for them. These are gestures the web
 patterns (`click`, `hover`, `fill`) don't cover.
 
-> Codegen status (Phase 3): the Appium adapter now **compiles** these gesture steps to WebdriverIO:
+> Codegen status: the Appium adapter **compiles** all of the following (verified against the shipped
+> `.hbs` under `adapters/appium/templates/steps/{gestures,actions}/`):
 > - **`tap` / `taps`** — synonym for `click` (→ `.click()`); **`double-tap`** → double-click.
 > - **`scroll to [X]`** → `.scrollIntoView()` (shared `scroll-action` template).
 > - **`swipe <dir> on [X]`** → `mobile: swipeGesture`.
@@ -24,9 +25,19 @@ patterns (`click`, `hover`, `fill`) don't cover.
 > - **`tap top of [X]`** / **`tap [X] at top`** → tap the element's **visible top edge** (`mobile: clickGesture`
 >   at top-centre from the element bounds) instead of its centre — use when the centre is occluded by a
 >   floating bottom bar so a normal centre tap would hit the bar.
->
-> Still exploration-only (no codegen yet): grant/deny permissions, clipboard set/get, dismiss system
-> dialog — author with the `appium_*` tool calls below; templates land in a later phase.
+> - **`dismiss [X]`** (any non-alert element) → best-effort tap-if-shown-within-2.5s, never fails the
+>   step (`dismiss-action`) — for launch interstitials / promo overlays, not the native alert dialog
+>   (that's the existing `accept/dismiss [OK] alert` form).
+> - **`hide the keyboard`** → `driver.hideKeyboard()`. **Android-only** — XCUITest cannot dismiss the
+>   keyboard generically (WDA throws + retries, ~12s wasted); on iOS the step is a silent best-effort
+>   no-op (never fails, just does nothing).
+> - **`grant [X] permission`** → Android `mobile: changePermissions`; iOS (Simulator only) `mobile:
+>   setPermission` — needs the `applesimutils` binary on iOS or the driver fails loud with the install hint.
+> - **`set the clipboard to {{v}}`** → `driver.setClipboard(...)`. **Write-only**: the appium adapter
+>   ships a `clipboard-text-assertion` template that reads the clipboard back, but no Gherkin pattern
+>   requests it yet — there is currently no phrasing that compiles to an actual clipboard-read
+>   assertion. Don't author "see clipboard contains X" expecting it to compile; tag it `@manual` instead.
+> - **`set location to {{lat}}, {{lng}}`** → `driver.setGeoLocation(...)`.
 >
 > 📜 **`scroll to [X]` — two failure modes seen, with the real cause (measured):**
 > 1. *"Default scrollable element '//android.widget.ScrollView' not found"* — wdio's mobile scroll runs
@@ -69,12 +80,14 @@ from `appium_find_element`; screen gestures pass `direction` or coordinates.
 | System back | `User go back` | `action=back` |
 | Drag & drop | `User drag [A] onto [B]` | `appium_drag_and_drop` (separate tool) |
 
-Other device-level actions (separate MCP tools, future Gherkin):
+Other device-level actions (separate MCP tools for exploration; Gherkin now compiles — see codegen
+status above):
 - Rotate: `appium_orientation` — `User rotate to landscape`
 - Permission dialog: `appium_mobile_permissions` / `appium_alert` — `User grant [Location] permission`
 - Background/foreground: `appium_app_lifecycle` — `User send app to background for 5 seconds`
-- Clipboard: `appium_mobile_clipboard` — `User paste into [Field]`
-- Notifications: open panel via `appium_mobile_device_control`
+- Clipboard write: `appium_mobile_clipboard` — `User set the clipboard to {{value}}` (read-back has
+  no Gherkin pattern yet — see codegen status above)
+- Notifications: open panel via `appium_mobile_device_control` — `User open notification panel`
 
 ---
 
@@ -104,6 +117,7 @@ them stable (accessibility-id) so the scroll terminates reliably.
 
 ## What this skill does NOT do
 
-- Does not implement gesture codegen (templates land in a later phase).
 - Does not replace `sungen-gherkin-syntax` — it supplements it with the mobile-only step vocabulary.
 - Does not cover tap/set-value/assertions (those are the shared Tier-1 patterns already supported).
+- Does not yet support a clipboard-READ assertion via Gherkin (see "Write-only" note above) — the
+  template exists but no pattern requests it.

package/src/orchestrator/templates/ai-src/skills/sungen-tc-generation/SKILL.md

@@ -479,7 +479,11 @@ Add cleanup tags per the `sungen-gherkin-syntax` Cleanup table. Key rules:
 
 **Files:** `qa/screens/<screen>/features/<screen>.feature` + `qa/screens/<screen>/test-data/<screen>.yaml`
 
-Use step patterns and element types from `sungen-gherkin-syntax`.
+Use step patterns and element types from `sungen-gherkin-syntax`. For a `@platform:mobile/android/ios`
+screen or flow, first check that skill's **Platform Support** section — never author a step marked
+`[web]` there (tables, browser storage, tab order, `@mock`, uploader, `Then User is on [T] page`) for
+a mobile unit, and read the divergence table before relying on `see [T] page` or `hover` to prove
+anything on mobile. Reach for `sungen-mobile-gestures` for the gesture vocabulary instead.
 **Naming**: reuse the **project's `test-viewpoint.md` IDs** when it declares them (e.g. `VP0`, `MS-HP-001`); otherwise `VP-<CATEGORY>-<NNN>`. Scenario name must use the **same element type** as the steps.
 
 **Test data** — grouped by section, loaded at runtime:

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

@@ -7,12 +7,16 @@
  * `{{name.body.<path>}}`. Base URL + auth come from a `kind: api` datasource in datasources.yaml,
  * with `${VAR}` resolved from .env.qa / process.env — never inline.
  *
+ * Runs on Node's global `fetch` (Node 18+) — no `@playwright/test` import, so this driver loads in
+ * mobile (Appium/Mocha) specs, which carry no Playwright dependency. Previously built on
+ * `APIRequestContext`; ported method-by-method (see `ApiClient.call`) to keep behaviour — including
+ * the `@hybrid` storageState cookie reuse — equivalent on web.
+ *
  * Safety: a datasource flagged `env: production` is refused unless SUNGEN_ALLOW_PROD=1.
  * DO NOT EDIT — regenerated by `sungen generate`.
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { request, type APIRequestContext } from '@playwright/test';
 
 interface ApiDataSource {
   kind?: string;
@@ -56,11 +60,53 @@ function substituteRaw(text: string, params: Record<string, any>): string {
 }
 /** Delete any case-insensitive variant of a header (HTTP header names are case-insensitive, but a
  *  plain object keys on exact case — so a datasource `Content-Type` and our `content-type` would
- *  both be sent). Call before setting, or to let Playwright own the header (multipart boundary). */
+ *  both be sent). Call before setting, or to let fetch own the header (multipart boundary). */
 function deleteHeader(headers: Record<string, string>, name: string): void {
   const lower = name.toLowerCase();
   for (const k of Object.keys(headers)) if (k.toLowerCase() === lower) delete headers[k];
 }
+/** True when `headers` already carries a case-insensitive match for `name` — used to respect an
+ *  explicit catalog header instead of overriding it with our own content-type default. */
+function hasHeader(headers: Record<string, string>, name: string): boolean {
+  const lower = name.toLowerCase();
+  return Object.keys(headers).some((k) => k.toLowerCase() === lower);
+}
+
+/**
+ * Build a `Cookie:` header value from a Playwright storageState JSON file (written by
+ * `sungen makeauth` / `context.storageState()` — `{ cookies: [...], origins: [...] }`), scoped to
+ * the cookies that apply to `url` the way a browser would send them (domain + path + not expired).
+ * Powers `@hybrid`: the API call reuses the UI session's cookies without a browser/Playwright
+ * context. Returns undefined when the file has no cookie that matches `url`.
+ */
+function loadStorageStateCookieHeader(storageStatePath: string, url: string): string | undefined {
+  const abs = path.isAbsolute(storageStatePath) ? storageStatePath : path.join(process.cwd(), storageStatePath);
+  if (!fs.existsSync(abs)) {
+    throw new Error(`API Driver: storageState "${storageStatePath}" not found — run \`sungen makeauth\` first.`);
+  }
+  const state = JSON.parse(fs.readFileSync(abs, 'utf-8')) as {
+    cookies?: Array<{ name: string; value: string; domain?: string; path?: string; expires?: number; secure?: boolean }>;
+  };
+  const cookies = state.cookies || [];
+  if (!cookies.length) return undefined;
+  const target = new URL(url);
+  const nowSec = Date.now() / 1000;
+  const targetIsSecure = target.protocol === 'https:';
+  const matches = cookies.filter((c) => {
+    const domain = (c.domain || '').replace(/^\./, '');
+    const domainOk = !domain || target.hostname === domain || target.hostname.endsWith(`.${domain}`);
+    const pathOk = target.pathname.startsWith(c.path || '/');
+    const notExpired = c.expires === undefined || c.expires < 0 || c.expires > nowSec;
+    // A Secure cookie must never leave over plaintext. Playwright's own cookie jar enforces this,
+    // and this function exists to be EQUIVALENT to it — omitting the check would make a mixed
+    // @hybrid setup (https browser session, http API datasource) leak the session cookie in clear,
+    // a downgrade introduced by us rather than by anything the author wrote.
+    const secureOk = !c.secure || targetIsSecure;
+    return domainOk && pathOk && notExpired && secureOk;
+  });
+  if (!matches.length) return undefined;
+  return matches.map((c) => `${c.name}=${c.value}`).join('; ');
+}
 
 /** A multipart file field embedded by the compiler (string = shorthand for { path }). */
 type FileSpec = string | { path: string; mimeType?: string; filename?: string; name?: string };
@@ -173,11 +219,13 @@ class ApiClient {
     if (req.body !== undefined && req.body !== null) {
       body = JSON.parse(JSON.stringify(req.body).replace(/":([A-Za-z_][A-Za-z0-9_]*)"/g, (_m, p) => JSON.stringify(params[p] ?? null)));
     }
-    // Map the wire format to the right Playwright option (#345): json → data (application/json,
-    // default), form → form (application/x-www-form-urlencoded), multipart → multipart (form-data).
-    // A `files` block is a real upload: read each fixture into a { name, mimeType, buffer } part and
-    // send multipart, with any `body` values riding along as text fields.
-    const bodyOpt: Record<string, unknown> = {};
+    // Map the wire format to a fetch request body (#345): json → JSON string (application/json,
+    // default), form → URL-encoded string, multipart → FormData. A `files` block is a real upload:
+    // read each fixture into a Blob part and send multipart, with any `body` values riding along
+    // as text fields. (Typed as `any`, not fetch's DOM-only `BodyInit`: this package's tsconfig has
+    // no "dom" lib, so that alias isn't in scope even though the global runtime values are.)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- see comment above
+    let fetchBody: any;
     if (req.bodyFile) {
       // Raw-binary body: the whole request body is the fixture's bytes. Content-Type comes from the
       // spec's mimeType (default application/octet-stream) — this is what octet-stream upload
@@ -186,40 +234,70 @@ class ApiClient {
       const fpath = substituteRaw(String(spec.path), params);
       if (fpath) {
         const resolved = resolveFixture(fpath, label);
-        bodyOpt.data = fs.readFileSync(resolved);
+        fetchBody = fs.readFileSync(resolved);
         // Own the Content-Type: drop any datasource default (case-insensitive) so we don't send both.
         deleteHeader(headers, 'content-type');
         headers['content-type'] = spec.mimeType ?? 'application/octet-stream';
       }
     } else if (req.files && Object.keys(req.files).length) {
-      // Playwright generates the multipart/form-data Content-Type (with boundary); drop any datasource
-      // default Content-Type so it doesn't conflict with / duplicate the generated one.
+      // fetch derives the multipart/form-data Content-Type (with boundary) from the FormData body;
+      // drop any datasource default Content-Type so it doesn't conflict with / duplicate it.
       deleteHeader(headers, 'content-type');
-      bodyOpt.multipart = buildMultipart(req.files, body, params, label);
+      fetchBody = buildMultipart(req.files, body, params, label);
     } else if (body !== undefined) {
       const enc = req.encoding ?? 'json';
-      if (enc === 'form') bodyOpt.form = body;
-      else if (enc === 'multipart') bodyOpt.multipart = body;
-      else bodyOpt.data = body;
+      if (enc === 'form') {
+        if (!hasHeader(headers, 'content-type')) headers['content-type'] = 'application/x-www-form-urlencoded';
+        fetchBody = new URLSearchParams(body as Record<string, string>).toString();
+      } else if (enc === 'multipart') {
+        deleteHeader(headers, 'content-type');
+        fetchBody = buildMultipart({}, body, params, label); // no file fields — text fields only
+      } else {
+        if (!hasHeader(headers, 'content-type')) headers['content-type'] = 'application/json';
+        fetchBody = JSON.stringify(body);
+      }
+    }
+
+    // GET/HEAD requests may not carry a body under fetch (undici throws). Refuse LOUDLY rather than
+    // send a request quietly shorter than the catalog says it is — a dropped body reads as a server
+    // bug, not an authoring one. `validateApiEntry` catches this at generate time; this is the
+    // backstop for a catalog that reached the runtime some other way.
+    if (fetchBody !== undefined && /^(GET|HEAD)$/i.test(req.method)) {
+      throw new Error(`API Driver: ${label} — a ${req.method.toUpperCase()} request cannot carry a body. Remove body:/files:/bodyFile: from the catalog entry, or change its method to POST/PUT/PATCH.`);
+    }
+
+    // Full URL (not a baseURL-relative path) so a base path component like /api/v3 is preserved.
+    const fullUrl = joinApiUrl(base, urlPath);
+
+    // @hybrid: `storageState` is the @auth role's saved session (Playwright's `context.storageState()`
+    // JSON) — reuse its cookies (scoped to `fullUrl`'s domain/path) so the request shares the
+    // browser's authenticated session without a browser/Playwright context.
+    if (opts.storageState) {
+      const cookieHeader = loadStorageStateCookieHeader(opts.storageState, fullUrl);
+      if (cookieHeader) {
+        const existingKey = Object.keys(headers).find((k) => k.toLowerCase() === 'cookie');
+        headers[existingKey || 'cookie'] = existingKey ? `${headers[existingKey]}; ${cookieHeader}` : cookieHeader;
+      }
     }
 
-    // Playwright APIRequestContext: same runner/report/retries as UI tests. @hybrid passes
-    // `storageState` (the @auth role's saved session) so the request shares the browser's
-    // authenticated cookies. Disposed per call so no request context lingers and hangs the process.
-    const ctx: APIRequestContext = await request.newContext({
-      extraHTTPHeaders: headers,
-      timeout: req.timeout ?? conf.timeout_ms ?? 15000, // per-endpoint override → datasource → 15s
-      ...(opts.storageState ? { storageState: opts.storageState } : {}),
-    });
+    // Timeout: fetch has no built-in per-request timeout, so abort it manually — mirrors the prior
+    // per-endpoint-override → datasource → 15s default precedence.
+    const timeoutMs = req.timeout ?? conf.timeout_ms ?? 15000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
-      // Full URL (not a baseURL-relative path) so a base path component like /api/v3 is preserved.
-      const res = await ctx.fetch(joinApiUrl(base, urlPath), { method: req.method, ...bodyOpt });
+      const res = await fetch(fullUrl, {
+        method: req.method,
+        headers,
+        ...(fetchBody !== undefined ? { body: fetchBody } : {}),
+        signal: controller.signal,
+      });
       const text = await res.text();
       let parsed: any = text;
       try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }
-      return { status: res.status(), ok: res.ok(), body: parsed, headers: res.headers() };
+      return { status: res.status, ok: res.ok, body: parsed, headers: Object.fromEntries(res.headers.entries()) };
     } finally {
-      await ctx.dispose();
+      clearTimeout(timer);
     }
   }
 

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

@@ -9,9 +9,12 @@
  * Engines: PostgreSQL (`pg`), MySQL (`mysql2`), and SQLite (`better-sqlite3`), lazy-loaded on first use.
  * Config: a `datasources.yaml` at the project root (or qa/), with ${VAR} resolved from env.
  *
+ * Assertions are plain thrown Errors — no `@playwright/test` import — so this helper loads in
+ * mobile (Appium/Mocha) specs too, which carry no Playwright dependency (same reason
+ * `specs/api.ts` runs on Node's global `fetch`).
+ *
  * DO NOT EDIT — regenerated by `sungen generate`.
  */
-import { expect } from '@playwright/test';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -647,12 +650,13 @@ class DataSource {
   async assertRow(table: string, filter: Record<string, any>, expected?: Record<string, any>, datasource?: string): Promise<void> {
     const { engine } = await this.engine(datasource);
     const rows = await engine.findRows(table, filter, 50);
-    expect(rows.length, `Expected a row in "${table}" where ${desc(filter)} — found ${rows.length}`).toBeGreaterThanOrEqual(1);
+    assert(rows.length >= 1, `Expected a row in "${table}" where ${desc(filter)} — found ${rows.length}`);
     if (expected) {
       const row = rows[0];
       for (const [col, val] of Object.entries(expected)) {
         ident(col);
-        expect(String(row[col]), `Column "${col}" of "${table}" where ${desc(filter)}`).toBe(String(val));
+        assert(String(row[col]) === String(val),
+          `Column "${col}" of "${table}" where ${desc(filter)} — expected ${JSON.stringify(String(val))}, found ${JSON.stringify(String(row[col]))}`);
       }
     }
   }
@@ -661,7 +665,7 @@ class DataSource {
   async assertNoRow(table: string, filter: Record<string, any>, datasource?: string): Promise<void> {
     const { engine } = await this.engine(datasource);
     const rows = await engine.findRows(table, filter, 50);
-    expect(rows.length, `Expected NO row in "${table}" where ${desc(filter)} — found ${rows.length}`).toBe(0);
+    assert(rows.length === 0, `Expected NO row in "${table}" where ${desc(filter)} — found ${rows.length}`);
   }
 
   /** Exactly `count` rows must match `filter`. */
@@ -669,7 +673,7 @@ class DataSource {
     const { engine } = await this.engine(datasource);
     const n = await engine.countRows(table, filter);
     const cols = Object.keys(filter);
-    expect(n, `Expected ${count} row(s) in "${table}"${cols.length ? ' where ' + desc(filter) : ''} — found ${n}`).toBe(Number(count));
+    assert(n === Number(count), `Expected ${count} row(s) in "${table}"${cols.length ? ' where ' + desc(filter) : ''} — found ${n}`);
   }
 
   /**
@@ -694,6 +698,16 @@ class DataSource {
   }
 }
 
+/**
+ * Fail a DB assertion. A thrown Error is exactly what BOTH runners report as a test failure
+ * (Playwright and Mocha/WDIO), so this replaces Playwright's `expect(...)` without importing it —
+ * the coupling that kept `specs/db.ts` out of mobile specs. Messages carry expected AND found,
+ * since there is no matcher to print them.
+ */
+function assert(cond: boolean, message: string): void {
+  if (!cond) throw new Error(`[sungen] ${message}`);
+}
+
 function desc(filter: Record<string, any>): string {
   return Object.entries(filter).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(', ');
 }