googlemaps-kit 0.5.0 → 0.7.0

package/docs/internal/reverse-engineering.md

@@ -0,0 +1,85 @@
+# Reverse-engineering notes — Maps web client internals
+
+Field notes from deobfuscating the Google Maps web app bundles
+(`maps.m.en.*` bootstrap + lazy modules) and its Web Worker loaders. Everything
+documented here is implemented somewhere in `src/`; this file records *how the
+client does it* so future changes can be re-derived.
+
+## Bundle layout
+
+| Piece | URL shape | Notes |
+|-------|-----------|-------|
+| Bootstrap | `/maps/_/js/k=maps.m.en.<key>.O/m=<initial>/am=<am>/rs=<rs>` | WIZ loader, `eptZe` = batchexecute prefix |
+| Lazy modules | same + `ck=` client key | The server validates module *sets*; arbitrary lists 404 |
+| Workers / WASM | `/maps/_/wa/<wli-entry>[.loader.js]` | `_/js/` → `_/wa/` swap decoded from `_.bTc` |
+
+The `wli` preload hints in the page HTML (`m.<bundle>.<feature>.O`) name the
+worker bundles: `smIQCHgOkp8` → **mapcore** (3D renderer),
+`7P4nUyqPXWw` → **loadSv** (Street View), `syLOIf-d1F0` → **loadSvVtl**
+(SV vector tiles), `yDBEh32NTLI` → labeler.
+
+Workers are Emscripten shells; the renderers are WASM sidecars fetched
+relative to the loader (`renderer_binary_web_release.wasm`,
+`streetview_imp_wasm_cc_binary.wasm`, …). Message protocol is
+`{ command, payload }` with transferable `ArrayBuffer`s (command 6 =
+label/paint prep).
+
+## vt layer descriptors (`_.er`)
+
+Named overlay layers serialise into the `/maps/vt?pb=` layer block as
+field 1 = type enum, field 2 = name string, field 3 = per-layer number,
+field 4 = repeated key/value app options:
+
+```
+!2m2!1e5!2sshading                 hillshade raster (global, z8+)
+!2m2!1e6!2scontours                contour lines (z13–15)
+!2m2!1e2!2sair-quality-heatmap     AQI heatmap (z5–15, city detail)
+```
+
+The JS switch also defines traffic (+`incidents`/`incidents_text`/
+`seconds_into_week` options), transit (+`sp=2`, number 999999), bike,
+`svv` (SV coverage vectors with camera/epoch options), indoor,
+`crisis2`, `area-busyness`, `hotel-categorical-search`, `lore-p13n`,
+`lore-rec`, `travel-map-reachability`. Those answer only inside the full
+client style context — probed directly they return a valid-but-blank ~220-byte
+placeholder PNG. That placeholder is how "no data" is signalled for the
+working layers too.
+
+## rocktree octree (`kh.google.com/rt/<planetoid>`)
+
+- `PlanetoidMetadata` → root epoch (key field 1 → subfield 2) and radius.
+- `BulkMetadata/pb=!1m2!1s<path>!2u<epoch>` → nodes carry packed
+  path+flags (level = low 2 bits + 1, 3 bits per octant), per-node epochs,
+  quantised OBB (centre deltas × metres-per-texel + Euler angles), and
+  imagery epoch. Flag bit 16 = NodeData requires `!3u{imageryEpoch}` —
+  sending it unrequested yields HTTP 404; flag bit 8 = metadata-only node.
+- `NodeData/pb=!1m2!1s<path>!2u<epoch>!2e1[!3u<img>]!4b0` → globe-from-mesh
+  matrix (16 doubles), meshes whose vertices are three byte planes of running
+  deltas, triangle strips encoded as back-references, UVs as two delta planes
+  mod a wrap value, plus a 512×512 JPEG texture.
+- Planets: `earth` (r 6371010 m), `mars` (3389500 m), `moon` (1737400 m).
+
+## Street View
+
+- `photometa v1` pb includes section list ids; id **18** opts into the
+  quantised depth raster (512×256) shipped alongside tiles.
+- Panorama tile pyramid geometry comes from `tileSizes` /
+  `maxTileDimensions` / `tileFaceSize`; there is no video endpoint — the web
+  client renders equirectangular panoramas from these tiles.
+- Imagery: `streetviewpixels-pa.googleapis.com/v1/{thumbnail,tile}`
+  (`cb_client=maps_sv.tactile`), no auth.
+- Legacy `GeoPhotoService.SingleImageQuery` is gone from current bundles;
+  photometa is the canonical metadata surface.
+
+## batchexecute registrations (`_.cy`)
+
+Service-path format (`/MapsService.Method` as rpcid) works anonymously;
+legacy short ids require the WIZ `SNlM0e` token. Confirmed id ↔ path pairs:
+`EvxQ3b`→GetAreaTraffic, `hspqX`→ListEntityPhotos, `T4jwAf`→GetViewportMetadata,
+`JGUSi`→GetUserPrefs, `PDqRpc`→WriteUserPrefs, `erVIH`→GetMapDetails,
+`EGR9cd`→CallAskMapsAgent (signed-in only).
+
+## Worker sources
+
+Loader sources (captured locally during analysis, not checked in) are
+Emscripten glue; no Maps business logic ships in them.

package/docs/lens.md

@@ -0,0 +1,54 @@
+# Google Lens
+
+The Lens client starts an image search and returns Google's issued results URL.
+It also builds image-URL navigation links. OCR and visual-match results remain
+unverified because the observed results page required a traffic challenge.
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { lens } from 'googlemaps-kit/lens';
+
+const client = lens({ locale: 'en-US' });
+const image = await readFile('/absolute/path/to/image-you-want-to-search.png');
+const session = await client.createSearch(image, {
+  filename: 'image.png',
+  mimeType: 'image/png',
+});
+console.log(session.url);
+```
+
+`createSearch()` uploads the caller-supplied `Uint8Array` or `Blob` as multipart
+`encoded_image`. The result contains the redirect URL and original redirect
+status, location header and body. It stops at that redirect and does not load
+results pages. Opening the URL can still require consent, sign-in, or a traffic
+challenge.
+
+`width` and `height`, when supplied together, populate the website's optional
+`processed_image_dimensions` field. They should describe the supplied image.
+The client does not resize or inspect image contents. PNG, JPEG, WebP and GIF
+media types are accepted by its interface.
+
+```ts
+const link = client.searchUrl('https://example.com/public-image.png');
+```
+
+`searchUrl()` constructs the current shipped upload service's URL-image
+navigation using `/v3/upload?url=...`. This is supported by static source evidence;
+the URL-image path was not separately executed after the observed upload results
+hit a challenge. Building the link performs no upload or request. Google's
+[image-search help](https://support.google.com/websearch/answer/1325808?hl=en)
+describes file upload and image-URL search in the consumer interface.
+
+The live investigation used only a synthetic image containing test text. The
+actual file upload returned HTTP 303, then its Google Search destination showed
+an unusual-traffic CAPTCHA. No CAPTCHA was solved, and no OCR or visual-match
+response schema is claimed from that session. The library therefore exposes
+upload/navigation transport, without an unverified recognition parser.
+
+Configuration accepts an injected `fetch`, `locale`, and `timeoutMs` (30 seconds
+by default). Upload options accept an `AbortSignal`. `LensError.kind` distinguishes
+`http`, `blocked`, `auth-required`, `rate-limit`, `parse`, `network`, and `timeout`.
+Requests are issued once and redirects to challenge pages are reported explicitly.
+
+Run offline tests with `npx vitest run tests/unit/lens`. The media live suite
+covers YouTube; it does not repeat an upload into the observed Lens challenge.

package/docs/maps-revalidation.md

@@ -0,0 +1,31 @@
+# Existing Maps capabilities
+
+The Maps implementation predates the additional Google consumer clients.
+This pass reused its source, wire builders, captured fixtures and explicit
+surface-status catalog rather than treating every registered RPC as verified.
+`src/known-surfaces.ts` and `src/platform/catalog.ts` retain the per-surface
+working, partial, authentication and unsupported boundaries.
+
+Representative anonymous live checks on 2026-10-29:
+
+| Capability | Observed result |
+| --- | --- |
+| Reviews | Five-review page plus rating total/aggregate; 20 deduplicated reviews over two further pages |
+| Forward geocoding | HSR Layout resolved to coordinates and its Bengaluru address |
+| Reverse geocoding | Existing HSR fixture coordinates resolved to a Bengaluru address |
+| Driving directions | HSR→Koramangala returned a 14-minute, 4.5km route with one leg and turn instructions |
+| Viewport weather | Populated HSR response returned `28°` and `Sunny`, following an initial metadata stub |
+
+These values describe captured checks, not fixed expected travel times or
+weather. The existing core offline suite covers place/search parsers, reviews,
+directions, tiles, photo/panorama formats and auth boundaries. This pass also
+fixed authenticated review fallback cursor propagation and corrected two
+supported environment-API request contracts; see [Reviews](reviews-research.md)
+and [environment access](environment-research.md).
+
+The consumer SDK is not full parity with every Maps Platform SKU. In particular,
+keyed enterprise fields, authenticated Ask Maps/history, private lists,
+session-dependent overlays, and endpoints marked unverified retain their
+existing limits. Public Places' five-review cap and the consumer review page
+protocol are separate contracts. Official API prices and credentials remain
+documented in the [service inventory](google-services-research.md).

package/docs/news.md

@@ -0,0 +1,35 @@
+# Google News public feeds
+
+```ts
+import { googleNews } from 'googlemaps-kit/news';
+
+const news = googleNews({ language: 'en-US', country: 'US' });
+const headlines = await news.headlines();
+const results = await news.search('Google AI');
+for (const article of results.articles) {
+  console.log(article.title, article.source?.name, article.publishedAt, article.url);
+}
+```
+
+The client reads public `/rss` and `/rss/search` feeds without an API key or
+browser. It returns channel metadata, titles, publication times, source names,
+source homepages and article links. Article links remain Google's RSS redirect
+URLs; the client does not claim to decode them into publisher article URLs.
+Descriptions remain HTML strings supplied by the feed. Full articles, arbitrary
+pagination, personalized feeds and a complete news index are outside this API.
+
+Configure `fetch`, `timeoutMs`, `language`, `country`, and optional `edition`
+(`US:en`, for example). Each method accepts locale overrides and `signal`.
+Default deadline is 30 seconds including the response body. Errors propagate
+as `GoogleWebError`; no automatic retries occur. XML parsing is limited to the
+observed RSS contract, never evaluates HTML and rejects entity declarations.
+CDATA contents are preserved verbatim, ordinary XML entities are decoded once,
+and comments are ignored. The parser rejects mismatched or truncated elements
+and bounds input to 10 million characters, 50,000 elements and 64 nesting levels.
+
+The search feed returned HTTP 200 and valid public data on 2026-10-29. Its
+`hl`, `gl`, `ceid`, and `q` parameters were captured directly. Feed metadata
+includes Google's usage notice; the returned `copyright` field preserves it.
+No general paid Google News query API was established in the official-source
+[service catalog](google-services-research.md). Paid third-party news APIs are
+separate products.

package/docs/pagespeed-research.md

@@ -0,0 +1,153 @@
+# PageSpeed Insights wire research
+
+Investigated on 2026-10-29 against `pagespeed.web.dev`, build
+`boq_chrome-lightbrary-ui_20261027.04_p0`. These are observations of Google's
+public web client, not a claim that undocumented interfaces are stable.
+
+## Evidence and verification
+
+- Bootstrap HTML exposes `eptZe=/_/PagespeedUi/`, `cfb2h` as the build label,
+  `FdrFJe` as the page session identifier, and `pDzS6=3`.
+- Browser network capture observed `nqfuif` with arguments
+  `["https://example.com/",3]`; that browser attempt received an automated-query
+  HTTP 429 page. Direct HTTP replay subsequently returned a successful creation
+  response. A browser failure therefore does not establish that the web RPC is
+  unavailable.
+- Successful create, `LsX2he` poll, and `CBayme` get responses were captured.
+  Analysis `bidxril0yk` for `https://example.com/` contained six completed
+  records: page CrUX, origin CrUX, and Lighthouse for both mobile and desktop.
+  The saved analysis page also contained the complete analysis in its server
+  preload data (`ds:0`).
+- The public `runPagespeed` endpoint was probed without an API key and returned
+  HTTP 429 with `quota_limit_value=0`. This is the observed quota state, not
+  evidence that every caller needs a key or that the web RPC shares that quota.
+- Static analysis inspected 25 downloaded scripts, all parsed successfully,
+  totaling 257,599 AST nodes. Browser inventory evidence:
+  `ev_33511f751b9d5da9383dae0f6f3ad5ac7b56056f11c6fb9ab0b66a8fba60d3b8`.
+  Bundle analysis evidence:
+  `ev_a9a73ecc0dc732329bf2835d27fe016bb9717d1e528a9d905dbc0885dbfc864e`.
+- Original captures and downloaded bundles remain in the untracked research
+  scratch directory. Shipped code and tests must not depend on those files.
+
+## Transports and RPCs
+
+Web calls POST form-encoded `f.req` to
+`https://pagespeed.web.dev/_/PagespeedUi/data/batchexecute`. The observed request
+used `rpcids`, `source-path=/analysis`, `f.sid`, `bl`, `hl`, `_reqid`, and `rt=c`.
+Its body was `[[[rpcid, JSON.stringify(args), null, "generic"]]]` under `f.req`;
+the observed anonymous create omitted `at`. Responses use Google's XSSI prefix,
+length-framed JSON, and `wrb.fr` records containing JSON-encoded payloads.
+
+| RPC | Purpose | Request arguments | Response | Evidence |
+| --- | --- | --- | --- | --- |
+| `nqfuif` | Create analysis | `[url, context, null, useOriginalUrl]`; trailing defaults can be omitted | Field 1 contains Analysis | Builder and successful live response |
+| `CBayme` | Get saved analysis | `[analysisId]` | Analysis directly | Explicit `/Pagespeed.GetAnalysis` descriptor and successful live response |
+| `LsX2he` | Refresh pending records | `[analysisId, [recordId, ...]]` | Field 1 is repeated Result | Polling code and successful live response |
+| `deISwc` | Legacy report preparation; URL resolution is an inference | `[url, null, formFactor]` | Observed `[url, url]`; response getter reads field 2 as string | Legacy `/report` builder and live probe; no complete semantic descriptor |
+| `zKzUAb` | Unknown | Unknown | Unknown | Descriptor only; request class `dIqFbe`, response `CAV36d`; no caller or field accesses found |
+
+The create context comes from `WIZ_global_data.pDzS6`, observed as `3`. Its
+semantic enum name is unknown. It must not be interpreted as mobile or desktop:
+the successful creation produced both form factors. Static create code attaches
+`X-Rawurl: <url>` and places the `use_original_url` boolean in field 4.
+
+The official API is a separate JSON transport:
+`GET https://www.googleapis.com/pagespeedonline/v5/runPagespeed`. Its options
+and quota behavior must not be inferred from the web client's positional RPCs.
+
+## Analysis and result layouts
+
+Field numbers below are one-based protobuf field numbers; ordinary JSON array
+indices are one less. This distinction matters when writing parsers.
+
+| Analysis field | Meaning |
+| --- | --- |
+| 1 | Saved analysis ID |
+| 2 | Analysis URL |
+| 3 | Status; `1` initiates polling, `2` observed for completed analysis |
+| 4 | Opaque context/location value; observed `3`, forwarded to the Lighthouse renderer |
+| 5 | Repeated Result records |
+| 6 | Map entries `[formFactor, originalUrl]`, used for redirect comparison |
+| 7 | Timestamp `[seconds, nanos]`, displayed as the report creation time |
+
+| Result field | Meaning |
+| --- | --- |
+| 1 | Original subject URL |
+| 2 | Resolved/final subject URL; origin records omit the trailing slash |
+| 3 | Form factor: `1` mobile, `2` desktop |
+| 4 | Kind: `1` Lighthouse, `2` origin CrUX, `3` page CrUX |
+| 5 | Unidentified data alternative; not exercised in the successful capture |
+| 6 | CrUX record; mutually exclusive with fields 5 and 10 |
+| 7 | Status: `1` pending, `2` complete |
+| 8 | Error/status message; code field 1, message field 2 |
+| 9 | Record ID used by polling and cache replacement |
+| 10 | Lighthouse result serialized as a JSON string |
+
+The UI polls every 3,000 ms, requesting only records whose status is `1`, and
+replaces records by ID. It stops when none are pending. A completed record can
+carry an error; completion does not imply successful Lighthouse or CrUX data.
+The UI recognizes error code `5` as missing CrUX data. Redirect handling compares
+the original and final URL's origin plus pathname, ignoring query and fragment.
+
+Saved links use `/analysis/<analysisId>` or
+`/analysis/<sanitizedUrl>/<analysisId>`, optionally with `form_factor=mobile` or
+`form_factor=desktop`. The sanitized URL is decorative: retrieval uses the ID.
+The UI removes the `url` query parameter after creation and retains the ID.
+
+## CrUX layout and units
+
+For `crux = result[5]` using zero-based JavaScript indices:
+
+- `crux[0][0]` is the record key. Index 0 holds an origin URL; index 4 holds a
+  page URL. Index 2 is the CrUX device enum: `2` PHONE and `1` DESKTOP in the
+  successful capture. This is the reverse of the outer Result form-factor enum.
+- `crux[1]` contains entries `[metricName, metricValue]`.
+- For the observed numeric metrics, `distribution = metricValue[1]`.
+  `distribution[0][0]` contains histogram bins;
+  `distribution[1][0]` contains the 75th-percentile typed value.
+- Each bin is `[typedStart, typedEndOrNull, density]`. A missing upper bound
+  denotes the final open-ended bin. Densities are fractions, not percentages.
+- Typed values contain numeric milliseconds at index 1, or decimal strings at
+  index 2 for dimensionless CLS values. Preserve numeric zero.
+- `crux[3]` is the collection period:
+  `[[startYear,startMonth,startDay],[endYear,endMonth,endDay]]`, with one-based
+  months. The successful capture covered 2026-09-30 through 2026-10-27.
+
+Metrics can omit histograms while retaining a percentile, as observed for the
+LCP image subparts. Entries can also have `null` values, as observed for
+`navigation_types` and `largest_contentful_paint_resource_type`. Unknown metric
+names and raw values should survive parsing; do not assume every entry has
+three bins or a percentile.
+
+The bootstrap metric configuration supplied these thresholds:
+
+| Metric | UI enum | Good upper bound | Needs-improvement upper bound | Unit |
+| --- | --- | --- | --- | --- |
+| `largest_contentful_paint` | 1 | 2500 | 4000 | ms |
+| `first_contentful_paint` | 2 | 1800 | 3000 | ms |
+| `cumulative_layout_shift` | 3 | 0.10 | 0.25 | unitless |
+| `experimental_time_to_first_byte` | 10 | 800 | 1800 | ms |
+| `interaction_to_next_paint` | 11 | 200 | 500 | ms |
+
+Static UI code includes metrics in the Core Web Vitals assessment only when
+they have three histogram bins and a numeric or decimal percentile. It marks
+the assessment unavailable if LCP or CLS is missing. It passes when their
+percentiles are within the good thresholds and INP is also good when present;
+missing INP alone does not fail the assessment. Good and needs-improvement
+upper bounds are inclusive in the UI's percentile-based rating code.
+
+## Lighthouse and remaining limits
+
+Both successful Lighthouse records used Lighthouse 13.5.0, contained 159 audits,
+and included all of `performance`,
+`accessibility`, `best-practices`, `seo`, and `agentic-browsing`. Preserve the full
+Lighthouse JSON, dynamic audit/category names, screenshots, warnings,
+configuration, environment, and timings rather than hard-coding four categories.
+Scores use the original 0–1 representation.
+
+Unknowns remain explicit: the semantic name of the create context enum, the
+field-5 Result alternative, the purpose and arguments of `zKzUAb`, all enum
+values not exercised here, and the complete semantics of legacy `deISwc`.
+Descriptor registration alone does not establish a working endpoint. No claim
+is made that automated-query blocking, quotas, or saved-report retention are
+constant across networks, sessions, or future builds.

package/docs/pagespeed.md

@@ -0,0 +1,135 @@
+# PageSpeed Insights
+
+```ts
+import { pageSpeed, PageSpeedError } from 'googlemaps-kit/pagespeed';
+
+const speed = pageSpeed({ locale: 'en-US' });
+const analysis = await speed.analyze('https://example.com/');
+console.log(analysis.reportUrl);
+
+for (const result of analysis.results) {
+  if (result.error) console.error(result.strategy, result.type, result.error);
+  if (result.lighthouse) console.log(result.strategy, result.lighthouse.categories);
+  if (result.fieldData) console.log(result.strategy, result.type, result.fieldData);
+}
+```
+
+The web transport uses the same create/get/poll RPCs as `pagespeed.web.dev`.
+It requires Node 18+ and has no browser or API-key dependency. Creation starts
+both mobile and desktop Lighthouse runs, plus separate page and origin CrUX
+jobs for each strategy. The website controls their categories and test settings.
+
+## Methods
+
+| Method | Behavior |
+| --- | --- |
+| `analyze(url, options?)` | Create jobs, then wait for completion |
+| `createAnalysis(url, options?)` | Return the initial analysis and pending result IDs |
+| `getAnalysis(idOrReportUrl, options?)` | Retrieve a saved analysis |
+| `pollAnalysis(analysisOrId, options?)` | Refresh pending records once, merging by result ID |
+| `waitForAnalysis(analysisOrId, options?)` | Poll until jobs finish or the deadline expires |
+| `runPagespeed(url, options?)` | Call the separate, documented v5 API |
+
+All methods accept `signal`. Create accepts `useOriginalUrl`, matching the web
+client's redirect option. Wait and analyze accept `pollIntervalMs` (default
+3000), `timeoutMs` (default 180000), and `onProgress`. This timeout bounds the
+waiting phase; `analyze` starts its wait after creation. Client configuration
+`timeoutMs` separately bounds each HTTP request, including its body (default
+120000). No request is retried automatically, avoiding duplicate analysis jobs.
+
+```ts
+const controller = new AbortController();
+const started = await speed.createAnalysis('https://example.com/', {
+  signal: controller.signal,
+});
+console.log(started.id);
+
+const completed = await speed.waitForAnalysis(started, {
+  signal: controller.signal,
+  timeoutMs: 240_000,
+  onProgress: report => console.log(report.results.map(r => [r.strategy, r.type, r.status])),
+});
+
+const saved = await speed.getAnalysis(completed.reportUrl);
+```
+
+## Results and exports
+
+Each `analysis.results` entry has `id`, `strategy`, `type`, `status`, and its
+original wire `raw` value. `type` is `lighthouse`, `page`, `origin`, or `unknown`.
+Unknown enum values also survive as `typeCode`, `statusCode`, and `strategyCode`.
+An analysis being complete means its jobs have finished; inspect each result's
+`error` and Lighthouse's `runtimeError` before using its scores.
+
+`result.lighthouse` is the complete Lighthouse JSON. Scores remain on the
+original 0–1 scale, and audits, category names, screenshots, diagnostics,
+opportunities, environment, and configuration survive unchanged. It can be
+saved as a Lighthouse report without converting it:
+
+```ts
+import { writeFile } from 'node:fs/promises';
+
+const mobile = analysis.results.find(r => r.type === 'lighthouse' && r.strategy === 'mobile');
+if (mobile?.lighthouse) {
+  await writeFile('mobile.lighthouse.json', JSON.stringify(mobile.lighthouse, null, 2));
+}
+```
+
+Field-data results expose all metric names, 75th percentiles, histogram bins,
+categorical fractions, collection dates, and `coreWebVitals`. Millisecond values
+remain milliseconds; CLS is dimensionless; densities and fractions are 0–1.
+Open-ended histogram bins omit `end`. Some metrics have only a percentile.
+`coreWebVitals` is `passed`, `failed`, or `unavailable`; insufficient field data
+is never turned into a zero score. Unknown metric payloads remain in `raw`.
+
+`buildReportUrl(id, strategy?)` creates a shareable website URL.
+`parseReportId(idOrReportUrl)` validates IDs and PageSpeed report links.
+
+## Official v5 API
+
+The official transport is explicit. A user-supplied API key is sent only to
+Google's official API, never to the web RPC transport.
+
+```ts
+const api = pageSpeed({ apiKey: process.env.PAGESPEED_API_KEY });
+const report = await api.runPagespeed('https://example.com/', {
+  strategy: 'mobile',
+  categories: ['performance', 'accessibility', 'best-practices', 'seo'],
+  locale: 'en-US',
+});
+console.log(report.lighthouseResult?.categories.performance?.score);
+```
+
+This method defaults to desktop and the API's performance-only category set.
+It also accepts `captchaToken`, `utmCampaign`, and `utmSource`.
+An omitted key uses Google's anonymous quota, which returned HTTP 429 with a
+zero daily quota during this investigation. Supplying a key uses that project's
+configured quota. See Google's [API reference](https://developers.google.com/speed/docs/insights/rest/v5/pagespeedapi/runpagespeed).
+
+## Errors and coverage
+
+`PageSpeedError.kind` distinguishes `http`, `rpc`, `parse`, `timeout`, and
+`network`. HTTP errors expose `status` and, when supplied by Google,
+`retryAfterMs`. RPC failures expose `rpcCode`. Caller cancellation propagates
+the abort signal's reason. Missing field data and audit errors belong to the
+individual job rather than failing unrelated jobs.
+
+The [research ledger](pagespeed-research.md) records live evidence, wire slots,
+and remaining unknowns. Create/get/poll succeeded without a browser using a
+public example page. Undocumented endpoints, saved-report retention, network
+blocking, and quotas can change. The uncalled `zKzUAb` descriptor and partially
+understood legacy `deISwc` RPC are documented but are not exposed as invented
+features.
+
+Run the example from the repository with:
+
+```sh
+npx tsx examples/pagespeed.ts https://example.com/
+```
+
+It writes complete mobile and desktop Lighthouse JSON files. Offline coverage
+lives under `tests/unit/pagespeed`; live coverage is opt-in:
+
+```sh
+npm run test:pagespeed:live
+```

package/docs/reviews-research.md

@@ -0,0 +1,33 @@
+# Reviews validation
+
+The repository already implements public Maps reviews through GetLocalBoqProxy,
+embedded place-preview fallback, rating aggregates, and a signed-in legacy RPC.
+Consumer review viewing and the paid Places API are distinct interfaces.
+
+On 2026-10-29 `examples/reviews-list.ts` succeeded anonymously for the existing
+CEVI fixture: one five-review page, 890 total ratings, aggregate score 4.3,
+and 20 deduplicated reviews across two subsequent pages. These counts describe
+that run and will change as reviews are added. No new authenticated live access
+was performed during this investigation.
+
+The audit found an authenticated fallback pagination bug: `listAll` updated its
+local cursor but failed to pass it into `listRpc`, repeating the same page.
+It now passes the updated token and preserves continuation when `maxPages`
+stops the loop. Offline regression tests verify cursor progression, cross-page
+deduplication and final-page exhaustion without network calls.
+
+Current capabilities include review text, ratings, author metadata, photos,
+owner replies, review attributes, translation metadata, pagination and aggregate
+histograms where the endpoint returns them. Search/rating filters are applied
+to fetched records locally, not represented as full server-side search.
+`reviewCount` is the number returned; `totalReviews` is the place-wide total.
+
+Google's supported public Places details API returns at most five relevance-sorted
+reviews, with `reviews` in the Enterprise + Atmosphere field group. Authorized
+Business Profile reviews are a separate interface for managed verified locations.
+See [Places fields](https://developers.google.com/maps/documentation/places/web-service/place-details),
+[Place reviews limit](https://developers.google.com/maps/documentation/places/web-service/reference/rest/v1/places)
+and [Business Profile reviews](https://developers.google.com/my-business/reference/rest/v4/accounts.locations.reviews/list).
+
+Private profiles, account actions, writing/deleting reviews, and bypassing
+authentication are not capabilities of the anonymous review reader.

package/docs/translate.md

@@ -0,0 +1,78 @@
+# Google Translate consumer client
+
+```ts
+import { googleTranslate } from 'googlemaps-kit/translate';
+
+const translate = googleTranslate();
+const result = await translate.translate('Good morning', { from: 'en', to: 'hi' });
+console.log(result.text, result.detectedLanguage);
+
+const suggestions = await translate.suggest('hello', { from: 'en', to: 'es' });
+const languages = await translate.languages();
+const speechLanguages = await translate.speechLanguages();
+const speech = await translate.speech(result.text, { language: 'hi' });
+```
+
+`speech.audio` contains MP3 bytes and `speech.mimeType` is `audio/mpeg`.
+The client uses anonymous TranslateWebserverUi calls. No API key or browser is
+required at runtime. Configuration accepts `fetch`, `timeoutMs` (30 seconds by
+default, including the response body), and interface `locale`. Every method
+accepts `signal`; no request retries automatically.
+
+Omit `from` to request language detection as part of translation. Output includes
+translated groups/segments, their source text when returned, detected language,
+and the unmodified positional `raw` response. Segments retain the website's
+space-before flag; paragraph line breaks survive. Language support is discovered
+from the server rather than inferred from a fixed list. The language selector
+includes `auto` for detection; `to` and speech require a concrete language.
+
+`GoogleWebError.kind` distinguishes blocking, HTTP, RPC, malformed responses,
+deadlines and network errors. Google can reject individual requests or languages.
+The client surfaces those failures instead of returning empty translated text.
+
+This is a consumer text/speech interface. Google Cloud Translation's supported
+paid API also offers enterprise features such as glossaries, custom models,
+document layout preservation and regional processing; those capabilities are
+outside this client. See [Cloud pricing](https://cloud.google.com/products/translate/pricing)
+and [API editions](https://docs.cloud.google.com/translate/docs/api-overview).
+
+## Evidence
+
+On 2026-10-29, build `boq_translate-webserver_20261027.05_p0`, an ordinary
+anonymous browser session and direct HTTP replay both returned successful data.
+Captured calls:
+
+| RPC | Shipped service name | Verified arguments |
+| --- | --- | --- |
+| `MkEWBc` | `/DataService.GetTranslation` | `[[text, source, target, 1, null, 1], []]` |
+| `AVdN8` | Translation suggestions | `[text, source, target]` |
+| `jQ1olc` | `/DataService.GetTts` | `[text, language, null, null, [0]]` |
+| `n9wk7` | `/DataService.GetSupportedLanguageNames` | `[]` |
+| `ycyxUb` | `/DataService.GetSupportedTtsLanguages` | `[]` |
+
+Bootstrap uses the current `cfb2h` build and string `FdrFJe` session ID from
+`WIZ_global_data`; the anonymous capture had no `SNlM0e` token. Calls use
+`/_/TranslateWebserverUi/data/batchexecute`, form-encoded `f.req`, XSSI and
+length-framed `wrb.fr` responses. No private account state is needed.
+
+The translation is in response field 2. Its field 1 contains groups; each group's
+field 6 contains segments. Segment field 1 is translated text, field 3 is the
+space-before flag, and field 7 is original text. Top-level field 3 is the detected
+language. TTS field 1 is base64 MP3. Supported-language names are pairs in
+response field 1. TTS language entries also contain an opaque numeric parameter
+(`200` in this capture); only the language codes are normalized, with the full
+entries retained in `raw`.
+
+Verified sample pairs include English→Hindi, English→Spanish and detected
+English→French with several sentences and a newline. Groups without segments
+use their first field as fallback translated text, matching the shipped display
+helper. Transliteration, images, documents, websites, account history,
+saved translations, AI tools and advanced translation engines remain untested.
+
+REA browser inventory evidence:
+`ev_cd09166bd0dc1031d356ae2973023a91a61ae1c2f195729841e766a84702c022`.
+Bundle evidence:
+`ev_e3b423c389b0510f55c936ffcb7b1291548fc2c9ad057cc8975cb56fe1ddfe3b`
+(52 scripts, 924,446 AST nodes, no parse failures). Static observations do not
+prove every declared feature executed. Captured fixture provenance is recorded
+in `tests/fixtures/translate/README.md`.