googlemaps-kit 0.6.0 → 0.7.0

package/docs/finance-research.md

@@ -0,0 +1,153 @@
+# Google Finance consumer client
+
+Investigated and verified on **2026-10-29**, build
+`boq_finhub-uiserver_20261026.07_p0`. This client implements the public consumer
+quote, instrument-suggestion, and sampled-price chart surfaces. It does not
+claim to reproduce all of Google Finance, provide a licensed market-data feed,
+or expose paid/AI research features.
+
+```ts
+import { finance } from 'googlemaps-kit/finance';
+
+const client = finance();
+const quote = await client.quote('GOOGL:NASDAQ');
+const suggestions = await client.search('Microsoft');
+const chart = await client.chart('GOOGL:NASDAQ', { range: '1M' });
+
+console.log(quote.price, quote.currency, quote.time);
+console.log(quote.extendedMarket);
+console.log(suggestions.matches);
+console.log(chart.sessions.flatMap(session => session.points));
+```
+
+Instrument strings use **symbol:exchange** order, as Google Finance URLs do.
+Objects `{ symbol: 'GOOGL', exchange: 'NASDAQ' }` are also accepted. `search`
+returns identifiable instrument suggestions, deduplicating repeated UI groups;
+it does not return an arbitrary natural-language or AI answer.
+
+Configuration supports `fetch`, `timeoutMs`, `language`, and `userAgent`.
+Methods accept an `AbortSignal`. Requests have a body-read deadline and do not
+automatically retry a block or failure. `FinanceError` exports the shared
+`GoogleWebError` class with `kind`, optional HTTP `status`, `rpcCode`, and
+`retryAfterMs`. Rate-limit/automated-query responses remain errors.
+
+## Runtime and static evidence
+
+- Ordinary headless Chromium rendered a complete GOOGL quote page. A generic
+  non-browser user agent had previously received an unsupported-client page.
+  The client therefore uses the exact captured browser user-agent family for
+  device negotiation; users may override it. Runtime browser evidence:
+  `ev_8b8ce4e3adf9f17541b4db84cde49b10828e312435ad8735c6596efac93c2ccd`.
+- REA analyzed **66 observed scripts**, providing static descriptors and field
+  access evidence:
+  `ev_681d6f6b8601b800f9884383e2c34fd76024911ff6b8305bd91f61b0f7c97950`.
+  Static analysis does not establish endpoint execution; direct HTTP replay
+  below supplies the runtime verification.
+- Direct anonymous HTTP replay returned 200 with real data for quote summary,
+  search suggestions, pricing details, and all eight chart ranges. No API key
+  or signed-in cookies were supplied. The complete client also passed an
+  opted-in live test for quote, search, and monthly chart.
+- Original runtime HTML, requests, responses, and scripts remain in untracked
+  scratch storage. Offline tests use copied public-data payloads under
+  `tests/fixtures/finance/`; shipped code has no dependency on scratch files.
+
+## Verified protocol
+
+Bootstrap `https://www.google.com/finance/?hl=en` and read `WIZ_global_data`:
+`eptZe=/finance/_/FinHubUi/`, `FdrFJe` session, and `cfb2h` build. Calls POST
+form-encoded `f.req` to
+`https://www.google.com/finance/_/FinHubUi/data/batchexecute`, passing `rpcids`,
+`source-path`, `f.sid`, `bl`, `hl`, and `rt=c`. Responses contain XSSI-prefixed,
+framed `wrb.fr` JSON payloads. Captured anonymous requests omitted `at`.
+
+| RPC | Shipped descriptor | Verified arguments | Client method |
+| --- | --- | --- | --- |
+| `gCvqoe` | `/FinanceHubService.ListEntitySummary` | `[[[null,[symbol,exchange]]]]` | `quote` |
+| `XB3kn` | `/FinanceHubService.GetSearchSuggestions` | `[query,null,1]` | `search` |
+| `c2u4wc` | `/FinanceHubService.ListHistoricalPricingData` | `[[[null,[symbol,exchange]]],rangeEnum]` | `chart` |
+| `dlNq8b` | Pricing-detail surface | `[[[null,[symbol,exchange]]],1,1,1]` | Captured and replayed; not exposed by this client |
+
+Browser traffic also registered and sometimes executed earnings/research RPCs,
+including `Xs5i3b` (GetEarningsTranscriptHighlights), `Iaiw6c` (GetEarningsFiles),
+and `TNo8E` (GetRelatedEarnings). Those are not the quote/search endpoints and
+are not part of the public SDK contract. No claim of paid research parity is
+made from their presence in a bundle.
+
+### Quote fields
+
+`gCvqoe` response field 1 is repeated EntitySummary; each entry's field 1 is a
+security node. The following are one-based security field numbers:
+
+| Field | Meaning established by capture and renderer |
+| --- | --- |
+| 1 | Entity ID |
+| 2 | `[symbol,exchange]` |
+| 3 | Display name |
+| 5 | Currency |
+| 6 | Regular price tuple `[price,change,changePercent,...]` |
+| 8 | Previous close |
+| 12 | Reported data timestamp `[seconds,nanos]` |
+| 13 | Exchange time-zone name |
+| 14 | UTC offset seconds |
+| 17 | Extended-session price tuple |
+| 18 | Regular price timestamp |
+| 19 | Extended-session price timestamp |
+| 25 | Source enum; returned as an opaque code when present |
+
+The successful GOOGL capture contained regular price **324.89 USD** and
+extended price **292.50 USD**. These are fixture observations, not current
+recommendations or promised live prices. The parser keeps them separate and
+preserves zero prices/changes and original precision.
+
+`reportedTime`, `time`, and `extendedMarket.time` are distinct source values.
+The payload does not establish a guaranteed delay interval, so `delayStatus`
+is `not-disclosed`; the SDK does not label every quote real-time. Some exchanges
+or instruments can be delayed, missing, or unsupported. See Google's
+[Finance data disclaimer](https://www.google.com/googlefinance/disclaimer/) and
+[GOOGLEFINANCE limitations](https://support.google.com/docs/answer/3093281?hl=en).
+The Sheets function and this consumer web transport are separate interfaces.
+
+### Historical charts
+
+The UI's range enum is statically explicit and each range was replayed
+successfully for GOOGL:
+
+| Range | Enum | Observed interval seconds | Observed points |
+| --- | --- | --- | --- |
+| `1D` | 1 | 60 | 632 across regular and extended sessions |
+| `5D` | 2 | 1800 | 70 |
+| `1M` | 3 | 86400 | 23 |
+| `6M` | 4 | 86400 | 128 |
+| `YTD` | 5 | 86400 | 209 |
+| `1Y` | 6 | 86400 | 252 |
+| `5Y` | 7 | 604800 | 262 |
+| `MAX` | 8 | 604800 | 1159 |
+
+These intervals/counts describe the captured responses and may vary. `MAX`
+does not imply a complete daily trading history. The response's field 4 groups
+session headers and points. Each point is `[DateTime,priceTuple,volume]`.
+DateTime months are one-based, and field 8 contains a UTC-offset message;
+converting to ISO time must apply that offset rather than the execution host's
+time zone. Session codes remain numeric: `1` and `3` were observed for regular
+and extended data in the day capture.
+
+Only verified price, time, and volume are normalized for chart points. Other
+price-tuple values vary with the selected chart baseline and remain available
+in `raw`, avoiding an incorrect “percent change” interpretation.
+
+## Validation and limits
+
+Sixteen offline unit tests cover captured layouts, duplicate suggestions,
+regular/extended separation, zero values, UTC offsets, malformed/missing data,
+the request envelope, blocking, cancellation, and local validation.
+
+```sh
+npx vitest run tests/unit/finance
+GMAPS_LIVE=1 FINANCE_LIVE=1 npx vitest run tests/live/finance.test.ts
+npm run type-check
+```
+
+All passed during implementation. Live tests require explicit opt-in and are
+excluded from the ordinary unit suite. Authentication-gated portfolios,
+watchlists, premium research, AI generation, and undocumented tuple fields
+remain outside this client's verified scope.

package/docs/finance.md

@@ -0,0 +1,43 @@
+# Google Finance
+
+```ts
+import { finance } from 'googlemaps-kit/finance';
+
+const market = finance();
+const quote = await market.quote('GOOGL:NASDAQ');
+console.log(quote.name, quote.price, quote.currency, quote.time);
+console.log(quote.extendedMarket);
+
+const matches = await market.search('Microsoft');
+const chart = await market.chart('GOOGL:NASDAQ', { range: '1M' });
+console.log(matches.matches, chart.sessions);
+```
+
+Instrument strings use `symbol:exchange`, matching the website's quote URL.
+Objects `{ symbol, exchange }` are also accepted. Charts support `1D`, `5D`,
+`1M`, `6M`, `YTD`, `1Y`, `5Y`, and `MAX`. Their sampling interval and available
+session groups come from Google, not a locally reconstructed price history.
+
+Quote results separate regular and extended-session prices and timestamps.
+They also preserve currency, previous close, source-reported time, exchange
+timezone and UTC offset where returned. `delayStatus` is `not-disclosed`;
+the client does not infer that a quote is real-time. Raw positional payloads
+remain available on all results.
+
+Configuration accepts `fetch`, `timeoutMs` (default 30 seconds), `language`
+(default `en`) and `userAgent`. The default user agent is the ordinary browser
+used for the successful capture, because Google served an unsupported-device
+page to a generic HTTP client. All methods accept `signal`; requests are not
+automatically retried. `FinanceError` exposes `kind`, HTTP `status`, RPC code
+and `retryAfterMs` where available. A captured missing-instrument status is
+reported with RPC code 5.
+
+This is a public quote/search/chart interface, with no API key or browser
+runtime dependency. It does not implement portfolios, account operations,
+AI investment answers, every asset type, fundamentals or exchange-data
+licensing. See Google's [data information](https://www.google.com/googlefinance/disclaimer/)
+and the [protocol research](finance-research.md) for exact contracts, live
+evidence and remaining limits.
+
+Run all public-client probes with `npm run test:google-public:live` or Finance
+alone with `GMAPS_LIVE=1 FINANCE_LIVE=1 npx vitest run tests/live/finance.test.ts`.

package/docs/gemini-web.md

@@ -0,0 +1,36 @@
+# Gemini consumer web interface
+
+Anonymous browser generation actually returned two marker answers during research on October 29, 2026. HTTP bootstrap alone does not establish that generation works. This module keeps the two operations separate.
+
+```ts
+import { geminiWeb } from 'googlemaps-kit/gemini-web';
+
+const metadata = await geminiWeb().inspect();
+console.log(metadata.build, metadata.generation); // generation: 'unverified'
+```
+
+`inspect()` fetches the public app HTML and reports its build plus the presence of anonymous session/prompt-token fields. It does not expose token values or generate an answer.
+
+## Actual generation through a browser
+
+```ts
+import { geminiWeb } from 'googlemaps-kit/gemini-web';
+
+const client = geminiWeb({ page });
+const answer = await client.generate('Explain a binary search in two sentences.');
+console.log(answer.text, answer.conversationUrl);
+```
+
+`page` is a caller-owned browser Page implementing the exported `GeminiBrowserPage` subset: `url`, `goto`, `content`, and the needed locator methods. A normal Playwright Page implements this interface. No browser package is bundled or required by the package's other methods; the caller supplies and closes its own browser. Use a fresh anonymous context to reproduce the research environment.
+
+`generate()` navigates that page to Gemini if necessary, fills the observed text composer and submits with Enter. It uses the page's existing conversation. It returns only after a **new**, prompt-matched model response has nonempty text, `aria-busy="false"`, and the observed completed-response footer. Existing answers, echoed prompts and incomplete responses cannot satisfy the wait. Output is visible plain text with paragraph boundaries, not the original Markdown source. Generation requires this browser adapter; no HTTP-only generation method is claimed.
+
+The current anonymous app used `geminiweb-pa.clients6.google.com/v1/processSession` with browser WebChannel/protobuf traffic. Its generation request contained a browser anti-abuse token. The SDK lets the genuine website perform that protocol; it does not manufacture, harvest or replay browser tokens, cookies or account credentials.
+
+Configuration accepts `page`, `fetch`, `timeoutMs` (90 seconds by default) and `pollIntervalMs` (500 ms). `generate(prompt, { signal?, timeoutMs? })` supports caller cancellation and an overall deadline. Cancellation stops the SDK's wait and prevents subsequent submission steps; a prompt already submitted to the website may continue generating. Concurrent generations through one client are rejected so responses cannot be mixed. No automatic retries or model-selection options are implemented.
+
+Only ordinary anonymous text generation and its observed DOM are verified. Availability varies by device, region and Google policy. Sign-in, consent or access challenges are surfaced. Images, files, connected apps, account history, saved state, paid plans, model identity and API-equivalent quotas are not established by this interface. The app's displayed `Flash-Lite` label is an observation, not a verified model-version guarantee.
+
+Google's [Gemini Apps help](https://support.google.com/gemini/answer/13275745?hl=en) describes limited signed-out text features. This consumer website is separate from Google's supported developer Gemini API and its billing. See the [research ledger](./google-ai-books-research.md) for runtime evidence and limitations.
+
+Offline tests run with `npx vitest run tests/unit/gemini-web`. Optional network probes are in `tests/live/google-ai-books.test.ts`; set `GMAPS_LIVE=1 GOOGLE_AI_BOOKS_LIVE=1` and run that file explicitly. The browser-generation case additionally requires `GEMINI_PLAYWRIGHT_MODULE` (an installed Playwright module path) and `GEMINI_BROWSER_EXECUTABLE` (the browser executable path). Without them, only Books metadata and Gemini bootstrap are probed.

package/docs/google-ai-books-research.md

@@ -0,0 +1,53 @@
+# Gemini, Books, Ads Keyword Planner and Search Console
+
+Observed October 29, 2026. Each service has its own evidence boundary. All probes used anonymous public requests or a new browser context. No account credentials, cookies, paid entitlements or existing user sessions were read. Ads probes were read-only; no campaigns, budgets or account settings were changed.
+
+## Gemini consumer web
+
+| Question | Observed evidence | Outcome |
+| --- | --- | --- |
+| Is HTTP bootstrap available? | `gemini.google.com/app?hl=en` returned HTTP 200 with current `WIZ_global_data` build/session metadata and no `SNlM0e` field. | Bootstrap implemented; generation remains unverified from this alone. |
+| Is signed-out browser text generation allowed here? | A fresh Chromium 156 context displayed a composer and returned `GEMINI_PUBLIC_PROBE_20261029` and `GEMINI_PROTOCOL_PROBE_20261029` for the two synthetic echo prompts. | Actual anonymous generation observed. |
+| Which current transport is used? | Browser resource and request capture showed `geminiweb-pa.clients6.google.com/v1/processSession`, WebChannel framing and base64/protobuf request data. The generation request included a long browser anti-abuse token. | Transport shape observed; token algorithm, full schema and a working plain-HTTP replay remain unresolved. No token evasion is implemented. |
+| Which DOM identifies completed answers? | `model-response` → `message-content` → `.markdown[aria-busy="false"]`, accompanied by `.response-footer.complete`. User echoes live in separate `user-query` containers. | Verified parser and caller-owned browser adapter implemented. |
+| Does the implemented SDK work beyond inspection? | A separate fresh browser run through `geminiWeb({ page }).generate(...)` returned exactly `GEMINI_SDK_PROBE_20261029`, with a response ID. | Actual SDK generation verified. |
+
+REA inventory evidence: `ev_936d2cf1a5b355fb214a409714f31613616df92589bf54e8cad669a0f76d9c9f`. Initial bundle evidence, limited to the app and the general gstatic origin: `ev_3691a13b7b3097660d166432bbacd1c80690ce95955d379af515a3122df11cff` (16 scripts). Expanded evidence including the actually observed `gemini.gstatic.com` origin: `ev_6f400a58e6634b7ace918f4215cffd6c7609bb4625625dbc155b5e608d3a517a` (68 scripts, 3,766,371 AST nodes, no parse failures). The latter resolves the original incomplete CDN boundary.
+
+REA statically analyzes captured source; it does not execute it or prove every function ran. Generation was separately observed through real page interaction and model-response DOM. Server-side internals, uncaptured dynamic behavior, signed-in features and underlying model versions remain unknown. Sanitized executed DOM and bootstrap fixture provenance is recorded in `tests/fixtures/gemini-web/README.md`; neither fixture retains account data or anti-abuse tokens.
+
+Google's [Gemini Apps help](https://support.google.com/gemini/answer/13275745?hl=en) documents that some signed-out text interactions are available, subject to device and location. These observations do not establish unlimited use, developer API equivalence, paid-model access, image generation, account history or connected-app permissions.
+
+## Google Books
+
+| Surface | Actual outcome | Implementation |
+| --- | --- | --- |
+| Books v1 `volumes?q=isbn:9780131103627&maxResults=1` | HTTP 429, query quota exceeded for Google's default consumer project. | No successful v1 search client claimed. |
+| Books v1 `volumes/zyTCAlFPjgYC` | Same HTTP 429 quota denial. | No successful v1 retrieval client claimed. |
+| Public `books.google.com/books?id=zyTCAlFPjgYC&hl=en` | HTTP 200 with a regional redirect to books.google.co.in; OpenGraph metadata and an English bibliographic table contained title, two authors, publisher/year, edition, two ISBNs and 384-page length. | Bounded metadata-by-volume-ID client and actual sanitized fixture implemented. |
+
+Google's [Books v1 guide](https://developers.google.com/books/docs/v1/using) documents public metadata search/get, API keys, and separately authorized library operations. Documentation of those methods is not evidence that the unauthenticated calls succeeded here. The [Dynamic Links guide](https://developers.google.com/books/docs/dynamic-links) describes preview/viewability links but specifically says its geography-dependent interface is not designed for server-side or offline queries; that surface was not repurposed as a server metadata service.
+
+No scanned pages, preview content, full text, purchases or paywalled material were requested. Current implementation is public bibliographic metadata only; query search and broader Books API parity remain unresolved. Fixture provenance is in `tests/fixtures/books/README.md`.
+
+## Ads Keyword Planner
+
+| Boundary | Actual evidence | Outcome |
+| --- | --- | --- |
+| Consumer UI | `ads.google.com/aw/keywordplanner/home?hl=en` redirected to `accounts.google.com/v3/signin/identifier`, titled Google Ads sign-in. | No anonymous keyword metrics observed. |
+| Read-only Ads API | `googleads.googleapis.com/v26/customers:listAccessibleCustomers` returned HTTP 401 missing authentication. | No account data retrieved and no mutation attempted. |
+| Documented feature mapping | Google's keyword planning docs map keyword ideas, historical metrics and forecasts to `KeywordPlanIdeaService`. | Documented capability, not an executed anonymous equivalent. |
+
+The current [access-level policy](https://developers.google.com/google-ads/api/docs/api-policy/access-levels) says developer tokens were sunset on September 9, 2026 and access is managed per Google Cloud project. Its Explorer restrictions explicitly include KeywordPlanIdeaService, so planning requires an appropriate higher access level. Some older generated summaries on Google's OAuth/header pages still mention developer tokens; those summaries are not treated as overriding the newer policy body.
+
+[Google Ads authorization](https://developers.google.com/google-ads/api/rest/auth) requires OAuth with `https://www.googleapis.com/auth/adwords`, appropriate customer access, and a manager login-customer-id where applicable. The [keyword planning guide](https://developers.google.com/google-ads/api/docs/keyword-planning/overview) describes the supported operations and tighter rate limits. No authorized planning request, account billing behavior or keyword metric response was executed. No fake anonymous metrics or paid-service replacement is implemented.
+
+## Search Console
+
+| Boundary | Actual evidence | Outcome |
+| --- | --- | --- |
+| Public UI entry | `search.google.com/search-console?hl=en` returned its public `/search-console/about` page. | Public marketing entry, not property analytics. |
+| Read-only property list | `www.googleapis.com/webmasters/v3/sites` returned HTTP 401 missing authentication. | No private properties, analytics or URL Inspection data retrieved. |
+| Documented authorization | OAuth token plus appropriate property access; readonly scope is `https://www.googleapis.com/auth/webmasters.readonly`, read/write scope is `https://www.googleapis.com/auth/webmasters`. | Access boundary established, not anonymously bypassed. |
+
+Google's [authorization guide](https://developers.google.com/webmaster-tools/v1/how-tos/authorizing) requires authenticated requests, and its [overview](https://developers.google.com/webmaster-tools/about) requires appropriate owner/full/read access to managed properties. Public page checks and private Search Console analytics are distinct. No credential flow, property ownership verification, account data extraction or account mutation was performed. Authorized API execution remains unverified and no anonymous equivalent is claimed.

package/docs/google-media-research.md

@@ -0,0 +1,105 @@
+# YouTube and Lens investigation
+
+Date: 2026-10-29. Scope: anonymous consumer metadata and search surfaces, plus a
+Lens upload using a synthetic image. No account, subscription, age restriction,
+CAPTCHA, or protected-media gate was bypassed. Browser interception aborted media
+resources, googlevideo hosts and videoplayback paths before they downloaded
+content.
+
+## Findings
+
+| ID | Evidence and result | Implementation and boundary |
+| --- | --- | --- |
+| YM-01 | Direct watch HTML HTTP 200 for `bC8fvcpocBU`; inline `ytInitialPlayerResponse` had OK playability, metadata, microformat and caption-track records. | `video()` normalizes public metadata and keeps the raw player/initial payloads. It does not request streams. |
+| YM-02 | Direct watch HTML for `dQw4w9WgXc` contained ERROR playability with an unavailable reason; its oEmbed request returned 400. | Restricted/unavailable player states are preserved. No attempt was made to restore access. |
+| YM-03 | Direct `/results?search_query=Google+for+Developers` returned HTTP 200 with `ytInitialData`, classic video/channel renderers, and an opaque continuation. | `search()` parses retained result renderers and anonymous client context. |
+| YM-04 | POST `/youtubei/v1/search?prettyPrint=false` returned HTTP 200 using the discovered continuation and a minimal `context.client`; no fixed key was required. The SDK live continuation test also passed. | `continueSearch()` sends the opaque token and page-provided version/context. Version, language, region and optional visitor data are retained; unrelated client fingerprint fields are omitted. |
+| YM-05 | Direct `/oembed?url=...&format=json` for `bC8fvcpocBU` returned HTTP 200. | `oembed()` returns the complete typed provider object. |
+| YM-06 | A separate public `Google Developers playlist` query returned HTTP 200 with `lockupViewModel`, content type PLAYLIST, collection thumbnails and byline metadata. The legacy `playlistRenderer` was absent. | Current observed playlist lockups are normalized; unobserved legacy playlist renderers are not claimed. |
+| YM-07 | An advertised `/api/timedtext` URL returned HTTP 200 with zero bytes, as did the browser's caption request. | Caption-track metadata is exposed; transcript content is unresolved. Empty content is not treated as proof that captions do not exist. |
+| LM-01 | A Google Images file chooser uploaded a locally created 600x200 PNG with synthetic test text. `/v3/upload?ep=gsbubb...` returned 303 to a Google Search Lens session. | `createSearch()` reproduces multipart transport and returns the issued redirect without loading recognition results. |
+| LM-02 | The resulting Google Search page displayed an unusual-traffic CAPTCHA. | OCR and visual-match schemas remain unverified. Collection stopped at the gate. |
+| LM-03 | Shipped Google Images module UEShwc constructs `/v3/upload`, multipart `encoded_image`, optional `processed_image_dimensions`, file entry point `gsbubb`, URL entry point `gsbubu`, locale, timestamp and viewport parameters. URL images use GET navigation. | Source-derived request and navigation builders are implemented. The URL-image route was not separately exercised. |
+
+The official public test video used for successful metadata is Google's own
+[Introducing Google for Developers!](https://www.youtube.com/watch?v=bC8fvcpocBU).
+No video content was downloaded. Fixture descriptions and metadata are retained
+only as necessary for protocol tests.
+
+## REA and artifact identity
+
+REA analyzed the exact extracted `var ytInitialPlayerResponse = ...` bootstrap
+statement from the successful watch capture as inert JavaScript. Evidence:
+`ev_4c02a4dbd1187f08caba6500b96a4390b215548332b51c130d5ed6fbb7ff9517`.
+The isolated artifact had three graph nodes and complete parsing of that
+statement. This establishes source structure; successful direct HTTP captures
+and the three live SDK tests establish the observed request behavior.
+
+For Lens, the observed parent Images script SHA-256 is
+`dc26401f442b86fe1bda52a406505c98e36c9da00fa22642b8dce1d30e2a0d0a`.
+The isolated UEShwc module consists of its first 4,409 source bytes plus the
+original wrapper's closing statement, so it can be parsed independently. REA
+produced evidence
+`ev_17fc2f463bcf07230fa3dfe55975fec04dabac969e31f4efc4fd8437f54063fa`,
+with six graph nodes. It did not execute Google's code or establish that every
+optional mode is available. An attempt to analyze the entire parent script
+exceeded the tool transport limit; conclusions use the focused module instead.
+
+REA target discovery evidence
+`ev_2ae58e65ef2494e0cb89c4f859870bf38b4be9067ff20c81523c151252239c09`
+identified the own-launched Google Images page. A passive navigation observation,
+`ev_c6bfab5b5d7ccd686e75a9d28e13406addc88cf9952b3f1db2effd2088132b43`,
+ended when that first browser was closed and did not capture the later upload.
+It is not used as upload evidence. The controlled browser's saved network
+records and the subsequent source inspection supply LM-01 through LM-03.
+
+## Parsing and protocol scope
+
+YouTube bootstrap extraction balances JSON object braces while respecting string
+escapes and uses JSON.parse; no page JavaScript is evaluated by the SDK. Search
+normalization is restricted to observed main-result and continuation containers,
+with explicit advertising containers excluded. Unknown renderer/data variants
+remain available in raw payloads. Display counts and relative dates remain text,
+so localization is not mistaken for a precise numeric value.
+
+The continuation body uses the discovered token and client name/version from
+`ytcfg.set(...).INNERTUBE_CONTEXT.client`, plus available locale/region/visitor
+fields. Its WEB header uses client number 1, as the captured page configuration
+specified. It is an anonymous consumer protocol, not the documented YouTube
+Data API. No hardcoded page API key or credential is shipped.
+
+Lens request construction comes from the shipped upload module and the
+successful browser upload. Its fixed viewport values are SDK choices for the
+transport, rather than a claim about a caller's actual device. No image resize,
+OCR geometry, visual-match, product-match, or AI overview schema is inferred
+from the challenged results page.
+
+## Coverage checklist
+
+| Surface | Status |
+| --- | --- |
+| YouTube public watch metadata and playability | Observed and implemented. |
+| YouTube search and anonymous continuation | Observed, implemented and live-tested. |
+| YouTube video/channel search renderers and current playlist lockups | Observed and implemented. |
+| YouTube oEmbed | Observed, implemented and live-tested. |
+| YouTube caption track metadata | Observed and implemented. |
+| YouTube transcript content | Unresolved: empty timed-text responses. |
+| YouTube protected media, signature decoding, account-only operations | Outside this public metadata implementation. |
+| Lens file upload and issued results redirect | Observed; transport implemented. |
+| Lens URL-image navigation construction | Static evidence; builder implemented. |
+| Lens OCR, visual matches, and result-page parsing | Unresolved behind the observed traffic challenge. |
+
+[Google Lens image-search help](https://support.google.com/websearch/answer/1325808?hl=en)
+describes public file and URL workflows. [YouTube embed help](https://support.google.com/youtube/answer/171780?hl=en)
+describes consumer embedding. These sources describe product behavior; the
+request and response contracts above come from the captured consumer surfaces.
+
+## Verification
+
+`npx vitest run tests/unit/youtube tests/unit/lens` verifies offline parser,
+request-construction, raw-preservation and failure behavior. The opt-in command
+`GMAPS_LIVE=1 npx vitest run tests/live/google-media.test.ts` passed watch metadata,
+oEmbed, and initial search plus continuation. The Lens live upload was performed
+once through the ordinary browser with the synthetic image and stopped at its
+results challenge. Mocked redirect tests do not claim a successful recognition
+response.

package/docs/google-search-research.md

@@ -0,0 +1,36 @@
+# Google Search research ledger
+
+Observed October 29, 2026. Scope: anonymous public Search HTML, autocomplete, organic links/snippets, related questions/searches, and actual Google AI Overviews. No signed-in account, proxy, CAPTCHA solution or alternate-IP mechanism was used.
+
+## Findings
+
+| Question | Observation | Status |
+| --- | --- | --- |
+| Can anonymous autocomplete return structured suggestions? | `suggestqueries.google.com/complete/search?client=firefox&q=typescript&hl=en` returned HTTP 200 and a JSON tuple containing the original query, ten suggestion strings, and subtype metadata. | Observed; implemented and live tested. |
+| Does plain Node fetch return Search results? | `www.google.com/search?q=what+is+typescript&hl=en&gl=us` returned HTTP 200, a JavaScript retry/enable-JavaScript interstitial, no `h3` result titles and no recognized result container. | Observed; explicitly classified. |
+| Does normal browser execution resolve that page? | Unmodified headless Chromium 156 executed the page and followed a 302 redirect to `/sorry/index`. The final HTTP 200 page reported unusual traffic and displayed reCAPTCHA, with no result titles. | Observed; explicitly classified. |
+| Can organic titles, URLs and snippets be extracted from current Search markup? | No successful result page was obtained in this environment. A bounded parser handles linked `h3` titles under `#search`/`#rso`, common snippet containers, and basic link decoding. | Experimental structural implementation; current live markup unverified. |
+| Can actual AI Overview text and sources be retrieved? | No overview was returned before the access challenge. The parser supports explicitly labeled semantic regions without generating any content. No private overview request format was established. | Unresolved; no claim of live retrieval or absence. |
+| Can related questions be expanded or fetched separately? | The blocked result page exposed no usable question expansion flow. Only explicitly labeled supplied HTML is parsed. | Expansion protocol unresolved. |
+
+## Runtime evidence
+
+REA target discovery `ev_c930379ae4d43fe4ea4aeee9f3a4d6204fe81b600ac9ed7bde7b9c57a2afbf5a` observed a Chrome 156 page at Google's `/sorry/index` after the normal Search navigation.
+
+REA bundle evidence `ev_e6d7545da32207ae31b9a9fae90991ad7f8d92dbe362c804c220390b2f2a0eba` observed and analyzed seven scripts from that denied page, with no parse failures. This establishes the captured denial page, not the missing Search/AI subsystem. The selected scope was `https://www.google.com` at loopback CDP endpoint `http://127.0.0.1:9341` with a 500 ms observation window.
+
+REA's static bundle analysis does not execute JavaScript; browser navigation was performed separately. Its findings do not establish earlier network activity, server-side behavior, string-built endpoints, encrypted configuration, uncaptured origins, or code from an unavailable successful result page. No endpoint inference from the CAPTCHA scripts is used as a Search or AI Overview API.
+
+## Fixtures and evidence quality
+
+`tests/fixtures/google-search/provenance.json` records capture dates, original SHA-256 digests, transports and sanitization for the actual responses. The saved autocomplete tuple is unchanged. HTML fixtures remove scripts, frames, challenge/form values, event handlers, origin-trial data and tracking values; the network IP is redacted. The meaningful interstitial and unusual-traffic structures are preserved.
+
+`structural-search.html` is synthetic. It tests safe handling of the parser's declared HTML contract, including snippets, a semantic overview region, related content and advertisement exclusions. It is deliberately separated from live evidence and does not establish Google's current positive markup. Unknown or incomplete HTML remains `unrecognized`, and an unrecognized overview remains `unverified`.
+
+## Official access and pricing
+
+Google's current [Custom Search JSON API overview](https://developers.google.com/custom-search/v1/overview) states that the API is closed to new customers and existing customers must transition by January 1, 2027. For existing customers until discontinuation it lists 100 free queries per day, then $5 per 1,000 requests up to 10,000 queries per day. It requires an API key and configured Programmable Search Engine. This implementation does not use that API.
+
+Google's [AI features documentation](https://developers.google.com/search/docs/appearance/ai-features) explains that AI Overviews appear selectively and often do not trigger. An empty parser result therefore cannot establish whether an overview was generated for a query. Google's [Search help page](https://support.google.com/websearch/answer/14901683?co=GENIE.Platform%3DDesktop&hl=en) describes the Web filter as excluding AI Overviews, but this investigation did not verify that filter's request parameters or use it as an overview-retrieval mechanism.
+
+No documented public method for retrieving Google.com's actual AI Overview text was established by this investigation. A generated response from a different model or product would not establish that result and is not substituted here. The remaining work requires an accessible successful Search response and observed loading/expansion behavior; the current implementation is not full Search or AI Overview protocol parity.

package/docs/google-search.md

@@ -0,0 +1,53 @@
+# Google Search and autocomplete
+
+The `googlemaps-kit/google-search` entry point provides anonymous autocomplete and a Search HTML request/parser. Autocomplete worked against Google's public endpoint during research on October 29, 2026. Search returned a JavaScript interstitial in Node and an unusual-traffic challenge in Chromium. Successful organic results, related questions and AI Overview extraction have **not** been verified against a live response.
+
+```ts
+import { googleSearch } from 'googlemaps-kit/google-search';
+
+const client = googleSearch({ language: 'en', country: 'us' });
+const suggestions = await client.suggest('typescript');
+console.log(suggestions.suggestions);
+
+const response = await client.search('what is typescript');
+console.log(response.status, response.organic, response.aiOverview);
+```
+
+No API key or additional runtime dependency is required. Public availability does not imply a quota guarantee. The client makes one request per method call, does not retry automatically, and does not solve or bypass challenges.
+
+## Response status
+
+| `status` | Meaning |
+| --- | --- |
+| `results` | Supported result links or an explicitly labeled overview region were extracted. HTML extraction remains experimental. |
+| `empty` | A recognized Search container includes an explicit no-results message. |
+| `blocked` | HTTP 403/429, a `/sorry/` destination, or a recognized unusual-traffic challenge. |
+| `javascript-required` | An enable-JavaScript interstitial was returned without recognizable result links. |
+| `consent-required` | The response is Google's consent page. |
+| `unrecognized` | The parser cannot establish that the HTML is a supported result page. |
+
+`aiOverview.status` is `present` only for an explicitly labeled `AI Overview` region, `blocked` when Search access is denied, and `unverified` otherwise. Missing or unfamiliar markup never becomes an absent overview. The client does not generate substitute text or call Gemini. `text` and `sources` are extracted only from the supplied region; hidden or deferred content is not retrieved.
+
+## Methods and options
+
+`client.suggest(query, { language?, country?, signal? })` calls `https://suggestqueries.google.com/complete/search?client=firefox`. It returns `{ query, suggestions, raw }`, preserving unknown tuple metadata. Its payload is independent of Search result pages.
+
+`client.search(query, { language?, country?, start?, safe?, signal?, includeRawHtml? })` requests `https://www.google.com/search`. `start` must be a nonnegative integer; `safe` is `active` or `off`. It returns the query, final source URL, HTTP status, extraction status, organic links, related content, overview status and warnings. Raw HTML is retained only when requested. `Retry-After`, when present, is available as `retryAfterMs` and is not automatically acted on.
+
+`googleSearch({ fetch?, language?, country?, timeoutMs? })` defaults to Node's `fetch`, language `en`, country `us`, and a 20-second deadline covering both response headers and body. Caller cancellation preserves its reason. Other failures throw `GoogleSearchError` with `kind` equal to `http`, `network`, `parse`, or `timeout`.
+
+## Supplying HTML
+
+```ts
+import { parseGoogleSearchHtml } from 'googlemaps-kit/google-search';
+
+const response = parseGoogleSearchHtml(savedHtml, {
+  sourceUrl: 'https://www.google.com/search?q=typescript&hl=en',
+});
+```
+
+The parser does not execute scripts. Its provisional structural contract recognizes `#search`/`#rso`, linked `h3` result titles, common snippet containers, and explicitly labeled regions for `AI Overview`, `People also ask`, and `Related searches`. Google may use other structures, localization, asynchronous content or experiments. Positive extraction tests use an explicitly synthetic fixture; they establish this parser contract rather than current Google markup. Real captured fixtures establish only autocomplete and the two access-challenge states.
+
+Run offline coverage with `npx vitest run tests/unit/google-search`. Run the optional network probes with `GMAPS_LIVE=1 GOOGLE_SEARCH_LIVE=1 npx vitest run tests/live/google-search.test.ts`; the Search probe reports whether it reached results or a recognized challenge. A passing blocked probe does not establish working Search extraction.
+
+See [the research ledger](./google-search-research.md) for observations, evidence and remaining gaps.