itamatrix 0.1.0

package/DESIGN.md

@@ -0,0 +1,247 @@
+# itamatrix — CLI for ITA Matrix flight search
+
+A command-line interface to [ITA Matrix](https://matrix.itasoftware.com/search) (Google's
+airfare search engine). Dual-purpose output: human-readable tables for interactive use,
+JSON for scripting and AI agents.
+
+## Goals
+
+- Query Matrix from the terminal: one-way, round-trip, multi-city, price calendar.
+- Expose advanced controls (cabin, stops, carriers, ITA routing codes).
+- Output auto-detects context: TTY → table, piped → JSON (`--json` / `--table` to force).
+- Distribute via npm (`npx itamatrix`).
+
+## Non-goals (v1)
+
+- Booking / purchase (Matrix doesn't sell tickets; it's search-only).
+- Account/login features (Matrix is anonymous — see findings).
+- Real-time price monitoring / alerts.
+
+---
+
+## Findings — live probe (cookieless, 2026-06)
+
+Captured by driving the real site with Playwright and intercepting network traffic.
+
+1. **No auth.** `/search` loads anonymously; no login wall, no cookie required.
+
+2. **Search state is base64-encoded JSON in the URL.** Submitting a search redirects to
+   `/flights?search=<base64>`. The decoded payload is the canonical, reconstructable
+   search spec:
+
+   ```json
+   {
+     "type": "round-trip",
+     "slices": [{
+       "origin": ["BOS"], "dest": ["LAX"],
+       "dates": { "searchDateType": "specific",
+                  "departureDate": "2026-08-10", "returnDate": "2026-08-17", "...": "..." }
+     }],
+     "options": { "cabin": "COACH", "stops": "-1", "extraStops": "1",
+                  "allowAirportChanges": "true", "showOnlyAvailable": "true" },
+     "pax": { "adults": "1" }
+   }
+   ```
+
+3. **Real backend endpoint:**
+
+   ```text
+   POST https://content-alkalimatrix-pa.googleapis.com/v1/search?key=AIza…&alt=json
+   headers: x-alkali-application-key: applications/matrix
+            x-alkali-auth-apps-namespace: alkali_v2
+            x-alkali-auth-entities-namespace: alkali_v2
+            content-type: application/json
+   body: {
+     "summarizers": ["solutionList","carrierStopMatrix","itineraryPriceSlider",
+                     "itinerary{Carrier,Origins,Destinations,StopCount}List",
+                     "itinerary{Departure,Arrival}TimeRanges","durationSliderItinerary",
+                     "currencyNotice","warningsItinerary"],
+     "inputs": { "slices":[…], "pax":{"adults":1}, "cabin":"COACH",
+                 "page":{"current":1,"size":25}, "sorts":"default",
+                 "maxLegsRelativeToMin":1, "changeOfAirport":true, "checkAvailability":true },
+     "summarizerSet": "wholeTrip",
+     "bgProgramResponse": "!LC-lL0vN…"   // BotGuard token — see blocker
+   }
+   ```
+
+4. **Result schema** (`result_full.json` saved as fixture):
+
+   ```text
+   response.solutionList: { solutions[25], minPrice, solutionCount, pages }
+     solution: { displayTotal:"USD439.81", passengerCount, pricings,
+                 itinerary:{ slices:[{ origin{code,name}, destination, departure, arrival,
+                                       flights:["UA2210"], cabins:["COACH"], duration,
+                                       ext.warnings:["OVERNIGHT"] }] },
+                 ext:{ price, pricePerMile } }
+   response.{carrierStopMatrix, itineraryPriceSlider, *TimeRanges, itineraryStopCountList}  // facets
+   ```
+
+5. **BotGuard — present but surmountable.** The search body carries `bgProgramResponse`, an
+   anti-bot token minted by Google's `Waa/Create` + `bg.js`. Verified by probe:
+   - **Pure-HTTP client is not viable** — cannot forge the token; must run Google's JS.
+   - **Bundled Playwright Chromium, headless, WORKS** (3/3 reliable, ~30–55 s) with two cheap
+     stealth tweaks: strip `"Headless"` from the UA string + hide `navigator.webdriver`.
+     No system Chrome, no display, no `xvfb` needed.
+   - **Earlier "headless blocked" was a false alarm** — it was a *timeout*, not a block.
+     Matrix searches genuinely take **40–60 s**; short cutoffs left the spinner spinning.
+     Use a ≥90 s timeout.
+   - **Direct nav to `/flights?search=…` does NOT trigger a search** — the search call
+     only fires from the in-app Search-button flow. The base64 URL encodes *state*, not a query.
+
+6. **Results now arrive via `/batch`, not `/v1/search`** (verified P1, 2026-06). The live
+   site issues `POST content-alkalimatrix-pa.googleapis.com/batch` returning
+   `multipart/mixed`; one part is an `application/http` wrapper whose JSON body is the
+   search result (top-level `solutionList`, `carrierStopMatrix`, … — same shape as
+   `result_full.json`). Many `/batch` calls fire (autocomplete, facets), so the driver
+   inspects bodies and picks the part containing `solutionList`. Form driving notes:
+   trip type is a `[role=tab]` ("Round Trip"/"One Way"); origin/dest are two
+   `[role=combobox]` "Add airport" autocompletes (pick first option); round-trip dates are
+   `input.mat-start-date`/`input.mat-end-date`, one-way is `input.mat-datepicker-input`
+   (M/D/YYYY, set via `fill()` + blur, then click the calendar backdrop to commit).
+
+---
+
+## Architecture
+
+**Browser-driven, bundled Playwright Chromium, headless.** Google's JS must run to mint the
+BotGuard token, but headless bundled Chromium suffices with light stealth — no system Chrome,
+no display.
+
+Per query:
+
+```text
+launch chromium (headless) with UA stripped of "Headless" + navigator.webdriver hidden
+  → goto /search
+  → set origin / dest / dates / options (native-setter value injection, not clicks)
+  → click Search
+  → intercept POST content-alkalimatrix-pa…/v1/search response  (timeout ≥90 s)
+  → parse JSON → render (table | json)
+```
+
+One browser instance is reused across the process lifetime. A **persistent daemon** (warm
+BotGuard session, IPC from CLI) is a later optimization for sub-second repeat queries.
+
+### Layout
+
+```text
+itamatrix/
+  src/
+    cli.ts                 # commander; TTY-detect → table|json
+    browser/session.ts     # launch chrome, drive form, click, intercept /v1/search
+    browser/forms.ts       # set slices/dates/pax/cabin/stops via native setters
+    model/types.ts         # zod schemas derived from result_full.json
+    render/table.ts
+    render/json.ts
+    commands/search.ts
+    commands/multicity.ts
+    commands/calendar.ts
+  fixtures/result_full.json
+```
+
+### Command surface
+
+```text
+itamatrix search BOS LAX --depart 2026-08-10 --return 2026-08-17 \
+  --pax 1 --cabin economy --stops 1 --carriers UA,AA --sort price --limit 20
+
+itamatrix multicity \
+  --leg JFK:NRT:2026-08-10 --leg NRT:SIN:2026-08-15 --leg SIN:JFK:2026-08-20
+
+itamatrix calendar BOS LAX --depart-range 2026-08-01:2026-08-31 --trip-length 7
+
+# global: --json | --table  --currency USD  --routing "<ITA routing codes>"
+```
+
+### Full option set
+
+Extracted from the live form (incl. Advanced Controls). Every Matrix control is exposed.
+"API field" = where it lands in the `/v1/search` `inputs` (or the base64 `options`/`pax`).
+
+**Trip type** — `search` (round-trip via `--return`), `--one-way`, `multicity` command.
+Maps to `slices` count + symmetry.
+
+**Per-slice routing** (repeatable per leg):
+
+| CLI flag | Control | Values | API field |
+|----------|---------|--------|-----------|
+| `<ORIGIN>` | Origin | airport/city codes, multiple OK | `slices[].origins[]` |
+| `<DEST>` | Destination | airport/city codes, multiple OK | `slices[].destinations[]` |
+| `--routing "<codes>"` | Routing Codes | ITA path language (carriers, vias, operators) — see [docs/ROUTING_CODES.md](docs/ROUTING_CODES.md) | passed through, per slice |
+| `--ext "<codes>"` | Extension Codes | ITA faring & filter codes (`f bc=`, `MAXDUR`, `-OVERNIGHTS`…) — see [docs/ROUTING_CODES.md](docs/ROUTING_CODES.md) | passed through, per slice |
+
+**Dates & times** (per slice):
+
+| CLI flag | Control | Values | API field |
+|----------|---------|--------|-----------|
+| `--depart` / `--return` | Start/End date | `YYYY-MM-DD` | `slices[].date` |
+| `--date-basis` | Departure / Arrival | `depart` \| `arrive` | `slices[].isArrivalDate` |
+| `--date-window` | This day only / day before / day after / +/-1 / +/-2 | `0`,`-1`,`+1`,`1`,`2` | `slices[].dateModifier{minus,plus}` |
+| `--times` | Preferred times | `early-am,am,midday,afternoon,evening,night` (6 windows) | `slices[].filter.times` |
+| `--calendar` | "See calendar of lowest fares" | flag → calendar mode | `searchDateType: lowestFare` |
+
+**Passengers** (`--pax` shorthand or individual):
+
+| CLI flag | Control | Range | API field |
+|----------|---------|-------|-----------|
+| `--adults` | Adults (18-61) | int | `pax.adults` |
+| `--seniors` | Seniors (62+) | int | `pax.seniors` |
+| `--youths` | Youths (12-17) | int | `pax.youths` |
+| `--children` | Children (2-11) | int | `pax.children` |
+| `--infants-seat` | Infants in seat (<2) | int | `pax.infantsInSeat` |
+| `--infants-lap` | Infants in lap (<2) | int | `pax.infantsInLap` |
+
+**Trip options:**
+
+| CLI flag | Control | Values | API field |
+|----------|---------|--------|-----------|
+| `--stops` | Stops | `none`(nonstop) \| `1` \| `2` \| `any`(no limit) | `options.stops` (`0/1/2/-1`) |
+| `--extra-stops` | Extra stops | `none` \| `1` \| `2` \| `any` | `options.extraStops` / `maxLegsRelativeToMin` |
+| `--cabin` | Cabin | `cheapest` \| `premium-economy` \| `business` \| `first` | `inputs.cabin` (`COACH`/`PREMIUM-COACH`/`BUSINESS-OR-HIGHER`/`FIRST`) |
+| `--currency` | Currency | ISO code (e.g. `USD`) | sales currency |
+| `--sales-city` | Sales City | airport/city code | sales city |
+| `--allow-airport-changes` / `--no-airport-changes` | Allow airport changes | bool (default on) | `inputs.changeOfAirport` |
+| `--available-only` / `--all` | Only show available seats | bool (default on) | `inputs.checkAvailability` |
+
+**Output/paging:**
+
+| CLI flag | Meaning |
+|----------|---------|
+| `--limit N` | page size (Matrix default 25) → `inputs.page.size` |
+| `--sort` | `default` \| `price` \| `duration` \| `depart` \| `arrive` → `inputs.sorts` |
+| `--json` / `--table` | force output format |
+
+---
+
+## Trade-offs
+
+- **Bundles Chromium (~150 MB); ~30–60 s per query.** Search latency is server-side (Matrix
+  itself is slow), not browser overhead — a daemon won't fix it; only result caching would.
+- **Coupled to the live DOM + network shape.** Form selectors and the `/v1/search` schema can
+  change without notice. Mitigation: thin selector layer (`forms.ts`), zod parse with clear
+  errors on schema drift, fixture-based tests.
+- **Rejected: pure-HTTP client.** Cleanest and fastest, but impossible — BotGuard token.
+
+---
+
+## Build plan
+
+| Phase | Scope | Ships |
+|-------|-------|-------|
+| P1 | session driver + `search` (one-way/round-trip) + table/json output | ✅ done |
+| P2 | filters/options: cabin, stops, carriers, ITA routing codes | ✅ done |
+| P3 | `multicity` (N slices), `calendar` (lowest-fare-per-date) | ✅ done |
+| P4 | npm packaging (`npx itamatrix`), result caching | ✅ done |
+| P5 | **agent skill** — NL → routing/extension codes via [docs/ROUTING_CODES.md](docs/ROUTING_CODES.md), wraps the CLI ([skills/itamatrix](skills/itamatrix/SKILL.md)) | ✅ done |
+
+## Open questions
+
+- **`calendar` response schema is unconfirmed.** No live fixture was captured for the
+  lowest-fare calendar `/batch` body, so `extractCalendarPayload` matches any plausible
+  calendar summarizer key and `normalizeCalendar` deep-scans the payload for date→price
+  pairs rather than binding to a schema. Capture a real fixture and tighten to a zod
+  schema (like `result_full.json`) once available; calendar form selectors are likewise
+  provisional and live in `forms.ts` (the coupled layer).
+- Daemon IPC mechanism (unix socket vs local HTTP) — superseded by P4 disk
+  result caching (`src/cache.ts`, spec-keyed, 60-min TTL, `--no-cache`/`--cache-ttl`).
+  Repeat queries are instant without a warm-process; a daemon stays a non-goal.
+- Server/CI use — works as-is (headless, no display needed). Just `npx playwright install chromium`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eran Krakovsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# itamatrix
+
+A command-line interface to [ITA Matrix](https://matrix.itasoftware.com/search)
+(Google's airfare search engine). Output auto-detects context: a TTY gets a
+human-readable table, a pipe gets JSON for scripting and AI agents.
+
+See [DESIGN.md](DESIGN.md) for architecture and [docs/ROUTING_CODES.md](docs/ROUTING_CODES.md)
+for the ITA routing/extension code language.
+
+## Install
+
+```bash
+npx itamatrix search BOS LAX --depart 2026-08-10
+```
+
+Or install globally:
+
+```bash
+npm install -g itamatrix
+```
+
+itamatrix drives a headless Chromium (Google's anti-bot JS must run). The
+bundled Playwright browser is required once:
+
+```bash
+npx playwright install chromium
+```
+
+If it is missing, itamatrix prints this exact command.
+
+## Usage
+
+```bash
+# Round-trip
+itamatrix search BOS LAX --depart 2026-08-10 --return 2026-08-17 \
+  --adults 1 --cabin business --stops 1 --carriers UA,AA --limit 20
+
+# Multi-city
+itamatrix multicity \
+  --leg JFK:NRT:2026-08-10 --leg NRT:SIN:2026-08-15 --leg SIN:JFK:2026-08-20
+
+# Price calendar (lowest fare per departure date)
+itamatrix calendar BOS LAX --depart-range 2026-08-01:2026-08-31 --trip-length 7
+
+# Global: --json | --table to force output format
+```
+
+Each query takes 30–60 s — Matrix itself is slow server-side.
+
+## Caching
+
+Results are cached on disk keyed by the full search spec, so a repeated query
+returns instantly instead of re-driving the browser. Applies to every command.
+
+| Flag | Meaning |
+|------|---------|
+| (default) | use cache; entries are fresh for 60 minutes |
+| `--cache-ttl <minutes>` | change the freshness window (e.g. `--cache-ttl 5`) |
+| `--no-cache` | bypass the cache and always query live |
+
+Cache location: `$XDG_CACHE_HOME/itamatrix`, falling back to `~/.cache/itamatrix`.
+Caching is best-effort — a read/write failure degrades silently to a live query.
+
+## Agent skill
+
+[`skills/itamatrix/SKILL.md`](skills/itamatrix/SKILL.md) is a Claude Code agent
+skill that turns a natural-language trip request ("cheapest business-class
+nonstop to London on oneworld next August") into the right command plus ITA
+[routing/extension codes](docs/ROUTING_CODES.md), then runs the CLI.
+
+Install it with [`npx skills`](https://www.npmjs.com/package/skills) straight
+from the repo:
+
+```bash
+npx skills add ekrako/itamatrix          # discovers skills/itamatrix/SKILL.md
+npx skills add ekrako/itamatrix -g       # install globally (user-level)
+```
+
+Or drop the `skills/` directory into an agent's skill path manually.
+
+The skill's **Command reference** section is generated from the CLI's own
+commander definitions, so it can't drift from the real flags:
+
+```bash
+npm run gen:skill          # regenerate after changing the CLI
+npm run gen:skill:check    # CI/pre-commit: fail if the skill is stale
+```
+
+A `core.hooksPath` pre-commit hook (`.githooks/pre-commit`, installed by `npm
+install`'s `prepare` step) runs the skill-drift check, `typecheck`, and
+`lint:md` on every commit.
+
+## Development
+
+```bash
+npm run dev -- search BOS LAX --depart 2026-08-10   # run from source
+npm test                                            # vitest
+npm run typecheck
+npm run lint:md                                     # markdownlint-cli2
+npm run build
+```

package/dist/browser/batch.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Matrix returns search results inside a `multipart/mixed` `/batch` response:
+ * each part is an `application/http` wrapper around a JSON body. Rather than
+ * parse MIME framing, scan the raw text for balanced top-level JSON objects and
+ * return the first one that looks like a search result (`solutionList`).
+ */
+export declare function extractSearchPayload(batchBody: string): unknown | null;
+export declare function extractCalendarPayload(batchBody: string): unknown | null;

package/dist/browser/batch.js

@@ -0,0 +1,87 @@
+/**
+ * Matrix returns search results inside a `multipart/mixed` `/batch` response:
+ * each part is an `application/http` wrapper around a JSON body. Rather than
+ * parse MIME framing, scan the raw text for balanced top-level JSON objects and
+ * return the first one that looks like a search result (`solutionList`).
+ */
+export function extractSearchPayload(batchBody) {
+    for (const obj of jsonObjects(batchBody)) {
+        if (obj && typeof obj === "object" && "solutionList" in obj)
+            return obj;
+    }
+    return null;
+}
+/**
+ * Keys the price-calendar ("lowest fare") response is expected to carry. The
+ * exact shape is unconfirmed (no captured fixture yet — DESIGN P3); this matches
+ * any plausible calendar summarizer, and `normalizeCalendar` deep-scans for
+ * date→price pairs so it tolerates which key actually wins.
+ */
+const CALENDAR_KEYS = [
+    "calendarSliceList",
+    "lowestFareCalendar",
+    "overlayPriceBuckets",
+    "dateGridList",
+    "monthOfYearList",
+];
+export function extractCalendarPayload(batchBody) {
+    for (const obj of jsonObjects(batchBody)) {
+        if (!obj || typeof obj !== "object")
+            continue;
+        const root = "response" in obj ? obj.response : obj;
+        if (root && typeof root === "object" && hasCalendarKey(root)) {
+            return obj;
+        }
+    }
+    return null;
+}
+function hasCalendarKey(obj) {
+    return CALENDAR_KEYS.some((k) => k in obj);
+}
+/** Yields every balanced, parseable top-level `{...}` object in `text`. */
+function* jsonObjects(text) {
+    let i = 0;
+    while (i < text.length) {
+        if (text[i] !== "{") {
+            i++;
+            continue;
+        }
+        const end = matchBrace(text, i);
+        if (end === -1)
+            break;
+        const slice = text.slice(i, end + 1);
+        try {
+            yield JSON.parse(slice);
+        }
+        catch {
+            // Not a self-contained object at this position; skip past the brace.
+        }
+        i = end + 1;
+    }
+}
+/** Index of the `}` matching the `{` at `start`, string/escape aware; -1 if none. */
+function matchBrace(text, start) {
+    let depth = 0;
+    let inStr = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+        const c = text[i];
+        if (inStr) {
+            if (escaped)
+                escaped = false;
+            else if (c === "\\")
+                escaped = true;
+            else if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"')
+            inStr = true;
+        else if (c === "{")
+            depth++;
+        else if (c === "}" && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+//# sourceMappingURL=batch.js.map

package/dist/browser/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../src/browser/batch.ts"],"names":[],"mappings":"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"}

package/dist/browser/batch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser/batch.test.js

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { extractCalendarPayload, extractSearchPayload } from "./batch.js";
+import { parseSearchResponse } from "../model/types.js";
+const batchBody = readFileSync(fileURLToPath(new URL("../../fixtures/batch_multipart.txt", import.meta.url)), "utf8");
+describe("extractSearchPayload", () => {
+    it("pulls the solutionList payload out of a multipart /batch body", () => {
+        const payload = extractSearchPayload(batchBody);
+        expect(payload).not.toBeNull();
+        const resp = parseSearchResponse(payload);
+        expect(resp.solutionList.solutions.length).toBeGreaterThan(0);
+    });
+    it("returns null when no part carries a solutionList", () => {
+        expect(extractSearchPayload('--b\r\n\r\n{"foo":1}\r\n--b--')).toBeNull();
+    });
+    it("skips earlier non-result parts and finds a later solutionList", () => {
+        const body = '--b\r\n\r\n{"airports":["a"]}\r\n' +
+            '--b\r\n\r\n{"solutionList":{"solutions":[{"id":"X","displayTotal":"USD1","itinerary":{"slices":[]}}]}}\r\n--b--';
+        const payload = extractSearchPayload(body);
+        expect(payload.solutionList.solutions).toHaveLength(1);
+    });
+    it("ignores a brace inside a JSON string without misparsing", () => {
+        const body = '--b\r\n\r\n{"note":"a } brace","solutionList":{"solutions":[]}}\r\n--b--';
+        expect(extractSearchPayload(body)).not.toBeNull();
+    });
+});
+describe("extractCalendarPayload", () => {
+    it("pulls a part carrying a calendar key out of a /batch body", () => {
+        const body = '--b\r\n\r\n{"solutionList":{"solutions":[]}}\r\n' +
+            '--b\r\n\r\n{"response":{"calendarSliceList":{"days":[]}}}\r\n--b--';
+        expect(extractCalendarPayload(body)).not.toBeNull();
+    });
+    it("returns null when no part has a calendar-shaped payload", () => {
+        expect(extractCalendarPayload('--b\r\n\r\n{"solutionList":{}}\r\n--b--')).toBeNull();
+    });
+});
+//# sourceMappingURL=batch.test.js.map

package/dist/browser/batch.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.test.js","sourceRoot":"","sources":["../../src/browser/batch.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,SAAS,GAAG,YAAY,CAC5B,aAAa,CAAC,IAAI,GAAG,CAAC,oCAAoC,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC7E,MAAM,CACP,CAAC;AAEF,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,MAAM,OAAO,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;QAChD,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAChE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,CAAC,oBAAoB,CAAC,+BAA+B,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC3E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,MAAM,IAAI,GACR,mCAAmC;YACnC,iHAAiH,CAAC;QACpH,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAA+C,CAAC;QACzF,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,IAAI,GAAG,0EAA0E,CAAC;QACxF,MAAM,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IACpD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;IACtC,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,IAAI,GACR,kDAAkD;YAClD,oEAAoE,CAAC;QACvE,MAAM,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,CAAC,sBAAsB,CAAC,yCAAyC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IACvF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/browser/forms.d.ts

@@ -0,0 +1,26 @@
+import type { Page } from "playwright";
+import type { CalendarSpec, MultiCitySpec, SearchSpec } from "../model/spec.js";
+/**
+ * Drives the Matrix search form and clicks Search.
+ *
+ * NOTE: this layer is intentionally thin and is the part most coupled to the
+ * live DOM (DESIGN.md "Trade-offs"). Selectors target the Angular Material
+ * markup observed on matrix.itasoftware.com/search. If Matrix restructures the
+ * form, failures surface here with a clear message.
+ */
+export declare function driveSearchForm(page: Page, spec: SearchSpec): Promise<void>;
+/**
+ * Drives the multi-city form: selects the Multi-City tab, materialises one row
+ * per leg, fills each leg's origin/destination/date, then applies the shared
+ * cabin/stops controls and clicks Search. The response is the same
+ * `solutionList` shape as a normal search (N slices instead of 1–2).
+ */
+export declare function driveMultiCityForm(page: Page, spec: MultiCitySpec): Promise<void>;
+/**
+ * Drives the price-calendar form: "See calendar of lowest fares" over a
+ * departure-date range. With `tripLength` it's a round-trip calendar; without,
+ * one-way. Selectors here are provisional — the calendar UI/response could not
+ * be captured for P3 (DESIGN), so this is the thinnest, most likely-to-drift
+ * layer; failures surface with a clear message.
+ */
+export declare function driveCalendarForm(page: Page, spec: CalendarSpec): Promise<void>;