@garagem-ai/site-sdk 0.10.1 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -112,13 +112,13 @@ The payloads are aggregates and a trimmed estimate. They never include
112
112
  cadastral ids, IPTU lookups, ITBI transactions, comparables, or unit
113
113
  inventory. Do not request or invent those fields.
114
114
 
115
- | API | Description |
116
- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
117
- | `getNeighborhoodSummary({ siteId, query, next? })` | P25 / P50 / P75 price per m² and sample size for a neighborhood. `query` is `{ city, neighborhood, propertyType?, type? }`. `type: "rent"` answers `listing_type_unsupported` (sale only). Cache with `next: { revalidate: 900 }`. |
118
- | `getListingMarketPosition({ siteId, listingId, next? })` | The listing's public price per m² versus the neighborhood median (`percentVsMedian`, `band`). Copy comes from `marketPositionLabel` / `priceBandLabel` (both return `null` when unavailable). |
119
- | `requestPriceEstimate({ siteId, input })` | Trimmed estimate for visitor-entered characteristics (`city`, `areaSqm`, optional neighborhood, bedrooms, parking, property type). Rate limited per visitor. Call it from a submit handler, not on page load. |
120
- | `marketPositionLabel(position)` | pt-BR line such as `8% abaixo da mediana do bairro`. |
121
- | `priceBandLabel(position)` | pt-BR quartile line such as `Na faixa do bairro, abaixo da mediana`. |
115
+ | API | Description |
116
+ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
117
+ | `getNeighborhoodSummary({ siteId, query, next? })` | P25 / P50 / P75 price per m² and sample size for a neighborhood. `query` is `{ city, neighborhood, propertyType?, type? }`. `type: "rent"` answers `listing_type_unsupported` (sale only). Cache with `next: { revalidate: 900 }`. |
118
+ | `getListingMarketPosition({ siteId, listingId, next? })` | The listing's public price per m² versus the neighborhood median (`percentVsMedian`, `band`). Copy comes from `marketPositionLabel` / `priceBandLabel` (both return `null` when unavailable). |
119
+ | `requestPriceEstimate({ siteId, input })` | Trimmed estimate for visitor-entered characteristics (`city`, `areaSqm`, optional neighborhood, bedrooms, bathrooms, parking, property type, `latitude`, `longitude`). Rate limited per visitor. Call it from a submit handler, not on page load. |
120
+ | `marketPositionLabel(position)` | pt-BR line such as `8% abaixo da mediana do bairro`. |
121
+ | `priceBandLabel(position)` | pt-BR quartile line such as `Na faixa do bairro, abaixo da mediana`. |
122
122
 
123
123
  `reason` is a code (`module_not_enabled`, `city_unsupported`, `no_data`,
124
124
  `rate_limited`, …). Do not print it. When `available` is false, `message`
package/dist/index.d.mts CHANGED
@@ -1,5 +1,5 @@
1
- import { F as FetchLike, R as RequestNextOptions, L as ListingDetail, a as ListingLocation, b as ListingMedia, S as SearchPathFilters, c as SearchUiDictionary, Q as QueryListingsFilters, A as AppliedSearchQuery, d as AppliedSearchChange, e as ListingFilters, f as ListingsResult, g as Site, h as SearchListingsParams, i as SearchListingsResult, j as SearchUi, k as QueryListingsParams, l as QueryListingsResult, m as SimilarListingsResult, C as CmsCollection, n as CmsEntriesResult, o as CmsEntry, B as BoundaryCity, p as BoundaryLayerOptions, M as MapsCoordinates, T as TravelTimeCacheOptions, q as TravelTimeCache, r as MapsFetchOptions, s as BoundaryLayer, t as ListingWithLocation, u as StaticMapOptions, v as StreetViewAvailabilityOptions, w as StreetViewAvailability, x as StreetViewOptions, N as NeighborhoodBoundaryOptions, y as NeighborhoodBoundary, z as TravelDestination, D as TravelMode, E as TravelTimeOptions, G as TravelTime, H as TravelTimesOptions, I as TravelTimeElement, J as Listing, P as PhotoSearchParams, K as PhotoSearchResult, O as PhotoSearchItem, U as ListingWithMatchedPhoto, V as MatchedListingPhoto } from './types-photo-search-DIoV75SN.mjs';
2
- export { W as BoundaryFeature, X as BoundaryFeatureCollection, Y as BoundaryGeometry, Z as BoundaryLayerUrlKind, _ as BoundarySourceLayer, $ as CmsEntryStatus, a0 as CmsFieldDefinition, a1 as CmsFieldType, a2 as CmsSeoData, a3 as FORBIDDEN_SEARCH_QUERY_KEYS, a4 as GaragemSdkError, a5 as GetCmsCollectionOptions, a6 as GetCmsCollectionsOptions, a7 as GetCmsEntriesOptions, a8 as GetCmsEntryOptions, a9 as GetListingOptions, aa as GetListingsOptions, ab as GetSearchUiOptions, ac as GetSimilarListingsOptions, ad as GetSiteOptions, ae as ListingBusinessType, af as ListingCardModel, ag as ListingPriceVisibility, ah as ListingPropertySummary, ai as LocationNameTables, aj as MAP_POLYGON_MAX_VERTICES, ak as MAP_SEARCH_DEFAULT_PAGE_SIZE, al as MAP_SEARCH_MAX_PAGE_SIZE, am as MAP_VIEWPORT_DEBOUNCE_MS, an as MapBounds, ao as MapBoundsSearchOptions, ap as MapPin, aq as MapPinCluster, ar as MapPolygon, as as MapPolygonSearchOptions, at as MapSearchResult, au as MapsBaseOptions, av as QueryListingsLocation, aw as QueryListingsOptions, ax as SEARCH_EMPTY_COPY, ay as SEARCH_SORT_RELEVANCE, az as SearchChromeModel, aA as SearchListingsOptions, aB as SearchPathLocation, aC as SearchUiFilter, aD as SearchUiOption, aE as StaticMapStyle, aF as TOOLBAR_PRIMARY_FILTER_IDS, aG as applyPathFilter, aH as buildQueryListingsParams, aI as canonicalizeSearchHref, aJ as capMapPage, aK as capMapPageSize, aL as clearStagedPathFilters, aM as clusterPins, aN as countFacetChoices, aO as countOptionLabel, aP as displayPathLocation, aQ as getCmsCollection, aR as getCmsCollections, aS as getCmsEntries, aT as getCmsEntry, aU as getListing, aV as getListings, aW as getSearchUi, aX as getSimilarListings, aY as getSite, aZ as hrefForAppliedChange, a_ as hrefForPathFilters, a$ as hrefWithExplicitPage, b0 as isListingDetailPath, b1 as isMapBounds, b2 as isMapPolygon, b3 as listingLocationLabel, b4 as mapClusterCellDegrees, b5 as mapSearchPins, b6 as paginationPages, b7 as pathFilterHasOption, b8 as pathFilterValue, b9 as publicSearchHref, ba as queryListings, bb as rangeDraftFromPath, bc as readPublicSearch, bd as searchChromeModel, be as searchHrefUsesLegacyFilterQuery, bf as searchListings, bg as searchListingsInBounds, bh as searchListingsInPolygon, bi as searchResultsHeading, bj as searchSortOptions, bk as toListingCardModel, bl as toolbarFilterIds, bm as visibleSearchFilters } from './types-photo-search-DIoV75SN.mjs';
1
+ import { F as FetchLike, R as RequestNextOptions, L as ListingDetail, a as ListingLocation, b as ListingMedia, S as SearchPathFilters, c as SearchUiDictionary, Q as QueryListingsFilters, A as AppliedSearchQuery, d as AppliedSearchChange, e as ListingFilters, f as ListingsResult, g as Site, h as SearchListingsParams, i as SearchListingsResult, j as SearchUi, k as QueryListingsParams, l as QueryListingsResult, m as SimilarListingsResult, C as CmsCollection, n as CmsEntriesResult, o as CmsEntry, B as BoundaryCity, p as BoundaryLayerOptions, M as MapsCoordinates, T as TravelTimeCacheOptions, q as TravelTimeCache, r as MapsFetchOptions, s as BoundaryLayer, t as ListingWithLocation, u as StaticMapOptions, v as StreetViewAvailabilityOptions, w as StreetViewAvailability, x as StreetViewOptions, N as NeighborhoodBoundaryOptions, y as NeighborhoodBoundary, z as TravelDestination, D as TravelMode, E as TravelTimeOptions, G as TravelTime, H as TravelTimesOptions, I as TravelTimeElement, J as Listing, P as PhotoSearchParams, K as PhotoSearchResult, O as PhotoSearchItem, U as ListingWithMatchedPhoto, V as MatchedListingPhoto } from './types-photo-search-Bmf1f1-Y.mjs';
2
+ export { W as BoundaryFeature, X as BoundaryFeatureCollection, Y as BoundaryGeometry, Z as BoundaryLayerUrlKind, _ as BoundarySourceLayer, $ as CmsEntryStatus, a0 as CmsFieldDefinition, a1 as CmsFieldType, a2 as CmsSeoData, a3 as FORBIDDEN_SEARCH_QUERY_KEYS, a4 as GaragemSdkError, a5 as GetCmsCollectionOptions, a6 as GetCmsCollectionsOptions, a7 as GetCmsEntriesOptions, a8 as GetCmsEntryOptions, a9 as GetListingOptions, aa as GetListingsOptions, ab as GetSearchUiOptions, ac as GetSimilarListingsOptions, ad as GetSiteOptions, ae as ListingBusinessType, af as ListingCardModel, ag as ListingPriceVisibility, ah as ListingPropertySummary, ai as LocationNameTables, aj as MAP_POLYGON_MAX_VERTICES, ak as MAP_SEARCH_DEFAULT_PAGE_SIZE, al as MAP_SEARCH_MAX_PAGE_SIZE, am as MAP_VIEWPORT_DEBOUNCE_MS, an as MapBounds, ao as MapBoundsSearchOptions, ap as MapBucket, aq as MapPin, ar as MapPinCluster, as as MapPolygon, at as MapPolygonSearchOptions, au as MapSearchResult, av as MapsBaseOptions, aw as QueryListingsLocation, ax as QueryListingsOptions, ay as SEARCH_EMPTY_COPY, az as SEARCH_SORT_RELEVANCE, aA as SearchChromeModel, aB as SearchListingsOptions, aC as SearchPathLocation, aD as SearchUiFilter, aE as SearchUiOption, aF as StaticMapStyle, aG as TOOLBAR_PRIMARY_FILTER_IDS, aH as applyPathFilter, aI as buildQueryListingsParams, aJ as canonicalizeSearchHref, aK as capMapPage, aL as capMapPageSize, aM as clearStagedPathFilters, aN as clusterBuckets, aO as clusterPins, aP as countFacetChoices, aQ as countOptionLabel, aR as displayPathLocation, aS as getCmsCollection, aT as getCmsCollections, aU as getCmsEntries, aV as getCmsEntry, aW as getListing, aX as getListings, aY as getSearchUi, aZ as getSimilarListings, a_ as getSite, a$ as hrefForAppliedChange, b0 as hrefForPathFilters, b1 as hrefWithExplicitPage, b2 as isListingDetailPath, b3 as isMapBounds, b4 as isMapPolygon, b5 as listingLocationLabel, b6 as mapClusterCellDegrees, b7 as mapSearchPins, b8 as paginationPages, b9 as pathFilterHasOption, ba as pathFilterValue, bb as publicSearchHref, bc as queryListings, bd as rangeDraftFromPath, be as readPublicSearch, bf as searchChromeModel, bg as searchHrefUsesLegacyFilterQuery, bh as searchListings, bi as searchListingsInBounds, bj as searchListingsInPolygon, bk as searchResultsHeading, bl as searchSortOptions, bm as toListingCardModel, bn as toolbarFilterIds, bo as visibleSearchFilters } from './types-photo-search-Bmf1f1-Y.mjs';
3
3
 
4
4
  /**
5
5
  * Visit-lead schedule: hours in, slots out. Pure — no fetch, no React.
@@ -527,10 +527,11 @@ declare const STUDIO_SDK_CONTRACT: {
527
527
  * Phone mask helpers shipped in 0.6.0. Map search
528
528
  * (`useMapSearch`, `searchListingsInBounds`) shipped in 0.9.0 — 0.7.0
529
529
  * does not export them. Property registration shipped in 0.10.0.
530
- * Search filter helpers (`visibleSearchFilters` / `toolbarFilterIds`)
531
- * shipped in 0.4.12 and remain on this pin.
530
+ * Weighted map buckets (`map.buckets`, clustered by the hook) shipped
531
+ * in 0.11.0. Search filter helpers (`visibleSearchFilters` /
532
+ * `toolbarFilterIds`) shipped in 0.4.12 and remain on this pin.
532
533
  */
533
- readonly minNpmVersion: "0.10.0";
534
+ readonly minNpmVersion: "0.11.0";
534
535
  /** Historical: older tarballs inject card CSS when those components mount. */
535
536
  readonly selfInjectSince: "0.4.2";
536
537
  readonly chromeStrategy: "app-owned";
@@ -592,7 +593,7 @@ declare const STUDIO_SDK_CONTRACT: {
592
593
  * `toolbarFilterIds` (shipped in 0.4.12). Do not confuse with
593
594
  * `unpublishedSearchExports` (`searchChromeModel`, …).
594
595
  */
595
- readonly searchExports: readonly ["searchResultsHeading", "searchSortOptions", "visibleSearchFilters", "toolbarFilterIds", "paginationPages", "hrefWithExplicitPage"];
596
+ readonly searchExports: readonly ["searchResultsHeading", "searchSortOptions", "visibleSearchFilters", "toolbarFilterIds", "paginationPages", "hrefWithExplicitPage", "countOptionLabel", "countFacetChoices"];
596
597
  /**
597
598
  * Main-package helpers in git / newer tarballs but not required on
598
599
  * `minNpmVersion`. Prompts must not mention these until the pin bumps and
@@ -611,6 +612,12 @@ declare const STUDIO_SDK_CONTRACT: {
611
612
  * pin sentence does not name it.
612
613
  */
613
614
  readonly mapsSince: "0.9.0";
615
+ /**
616
+ * `useMapSearch` returns weighted location buckets (`map.buckets`, and
617
+ * `map.clusters` built from them) when the matches overflow one page.
618
+ * The map-search guidance teaches bucket clicks only from this pin on.
619
+ */
620
+ readonly mapBucketsSince: "0.11.0";
614
621
  readonly mapsExports: readonly ["listingStaticMapUrl", "listingStreetViewUrl", "listingStreetViewAvailable", "neighborhoodBoundaryLayer", "boundaryLayerUrl", "travelTimeFromListing", "searchListingsInBounds", "searchListingsInPolygon", "clusterPins"];
615
622
  /**
616
623
  * Market-data helpers (neighborhood price summary, listing market
@@ -1192,6 +1199,10 @@ interface PriceEstimateInput {
1192
1199
  parkingSpots?: number;
1193
1200
  propertyType?: MarketPropertyType;
1194
1201
  listingType?: MarketListingType;
1202
+ /** From the address suggestion. Not a form field. */
1203
+ latitude?: number;
1204
+ /** From the address suggestion. Not a form field. */
1205
+ longitude?: number;
1195
1206
  }
1196
1207
  type PriceEstimateConfidence = "high" | "medium" | "low";
1197
1208
  interface PriceEstimate {
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { F as FetchLike, R as RequestNextOptions, L as ListingDetail, a as ListingLocation, b as ListingMedia, S as SearchPathFilters, c as SearchUiDictionary, Q as QueryListingsFilters, A as AppliedSearchQuery, d as AppliedSearchChange, e as ListingFilters, f as ListingsResult, g as Site, h as SearchListingsParams, i as SearchListingsResult, j as SearchUi, k as QueryListingsParams, l as QueryListingsResult, m as SimilarListingsResult, C as CmsCollection, n as CmsEntriesResult, o as CmsEntry, B as BoundaryCity, p as BoundaryLayerOptions, M as MapsCoordinates, T as TravelTimeCacheOptions, q as TravelTimeCache, r as MapsFetchOptions, s as BoundaryLayer, t as ListingWithLocation, u as StaticMapOptions, v as StreetViewAvailabilityOptions, w as StreetViewAvailability, x as StreetViewOptions, N as NeighborhoodBoundaryOptions, y as NeighborhoodBoundary, z as TravelDestination, D as TravelMode, E as TravelTimeOptions, G as TravelTime, H as TravelTimesOptions, I as TravelTimeElement, J as Listing, P as PhotoSearchParams, K as PhotoSearchResult, O as PhotoSearchItem, U as ListingWithMatchedPhoto, V as MatchedListingPhoto } from './types-photo-search-DIoV75SN.js';
2
- export { W as BoundaryFeature, X as BoundaryFeatureCollection, Y as BoundaryGeometry, Z as BoundaryLayerUrlKind, _ as BoundarySourceLayer, $ as CmsEntryStatus, a0 as CmsFieldDefinition, a1 as CmsFieldType, a2 as CmsSeoData, a3 as FORBIDDEN_SEARCH_QUERY_KEYS, a4 as GaragemSdkError, a5 as GetCmsCollectionOptions, a6 as GetCmsCollectionsOptions, a7 as GetCmsEntriesOptions, a8 as GetCmsEntryOptions, a9 as GetListingOptions, aa as GetListingsOptions, ab as GetSearchUiOptions, ac as GetSimilarListingsOptions, ad as GetSiteOptions, ae as ListingBusinessType, af as ListingCardModel, ag as ListingPriceVisibility, ah as ListingPropertySummary, ai as LocationNameTables, aj as MAP_POLYGON_MAX_VERTICES, ak as MAP_SEARCH_DEFAULT_PAGE_SIZE, al as MAP_SEARCH_MAX_PAGE_SIZE, am as MAP_VIEWPORT_DEBOUNCE_MS, an as MapBounds, ao as MapBoundsSearchOptions, ap as MapPin, aq as MapPinCluster, ar as MapPolygon, as as MapPolygonSearchOptions, at as MapSearchResult, au as MapsBaseOptions, av as QueryListingsLocation, aw as QueryListingsOptions, ax as SEARCH_EMPTY_COPY, ay as SEARCH_SORT_RELEVANCE, az as SearchChromeModel, aA as SearchListingsOptions, aB as SearchPathLocation, aC as SearchUiFilter, aD as SearchUiOption, aE as StaticMapStyle, aF as TOOLBAR_PRIMARY_FILTER_IDS, aG as applyPathFilter, aH as buildQueryListingsParams, aI as canonicalizeSearchHref, aJ as capMapPage, aK as capMapPageSize, aL as clearStagedPathFilters, aM as clusterPins, aN as countFacetChoices, aO as countOptionLabel, aP as displayPathLocation, aQ as getCmsCollection, aR as getCmsCollections, aS as getCmsEntries, aT as getCmsEntry, aU as getListing, aV as getListings, aW as getSearchUi, aX as getSimilarListings, aY as getSite, aZ as hrefForAppliedChange, a_ as hrefForPathFilters, a$ as hrefWithExplicitPage, b0 as isListingDetailPath, b1 as isMapBounds, b2 as isMapPolygon, b3 as listingLocationLabel, b4 as mapClusterCellDegrees, b5 as mapSearchPins, b6 as paginationPages, b7 as pathFilterHasOption, b8 as pathFilterValue, b9 as publicSearchHref, ba as queryListings, bb as rangeDraftFromPath, bc as readPublicSearch, bd as searchChromeModel, be as searchHrefUsesLegacyFilterQuery, bf as searchListings, bg as searchListingsInBounds, bh as searchListingsInPolygon, bi as searchResultsHeading, bj as searchSortOptions, bk as toListingCardModel, bl as toolbarFilterIds, bm as visibleSearchFilters } from './types-photo-search-DIoV75SN.js';
1
+ import { F as FetchLike, R as RequestNextOptions, L as ListingDetail, a as ListingLocation, b as ListingMedia, S as SearchPathFilters, c as SearchUiDictionary, Q as QueryListingsFilters, A as AppliedSearchQuery, d as AppliedSearchChange, e as ListingFilters, f as ListingsResult, g as Site, h as SearchListingsParams, i as SearchListingsResult, j as SearchUi, k as QueryListingsParams, l as QueryListingsResult, m as SimilarListingsResult, C as CmsCollection, n as CmsEntriesResult, o as CmsEntry, B as BoundaryCity, p as BoundaryLayerOptions, M as MapsCoordinates, T as TravelTimeCacheOptions, q as TravelTimeCache, r as MapsFetchOptions, s as BoundaryLayer, t as ListingWithLocation, u as StaticMapOptions, v as StreetViewAvailabilityOptions, w as StreetViewAvailability, x as StreetViewOptions, N as NeighborhoodBoundaryOptions, y as NeighborhoodBoundary, z as TravelDestination, D as TravelMode, E as TravelTimeOptions, G as TravelTime, H as TravelTimesOptions, I as TravelTimeElement, J as Listing, P as PhotoSearchParams, K as PhotoSearchResult, O as PhotoSearchItem, U as ListingWithMatchedPhoto, V as MatchedListingPhoto } from './types-photo-search-Bmf1f1-Y.js';
2
+ export { W as BoundaryFeature, X as BoundaryFeatureCollection, Y as BoundaryGeometry, Z as BoundaryLayerUrlKind, _ as BoundarySourceLayer, $ as CmsEntryStatus, a0 as CmsFieldDefinition, a1 as CmsFieldType, a2 as CmsSeoData, a3 as FORBIDDEN_SEARCH_QUERY_KEYS, a4 as GaragemSdkError, a5 as GetCmsCollectionOptions, a6 as GetCmsCollectionsOptions, a7 as GetCmsEntriesOptions, a8 as GetCmsEntryOptions, a9 as GetListingOptions, aa as GetListingsOptions, ab as GetSearchUiOptions, ac as GetSimilarListingsOptions, ad as GetSiteOptions, ae as ListingBusinessType, af as ListingCardModel, ag as ListingPriceVisibility, ah as ListingPropertySummary, ai as LocationNameTables, aj as MAP_POLYGON_MAX_VERTICES, ak as MAP_SEARCH_DEFAULT_PAGE_SIZE, al as MAP_SEARCH_MAX_PAGE_SIZE, am as MAP_VIEWPORT_DEBOUNCE_MS, an as MapBounds, ao as MapBoundsSearchOptions, ap as MapBucket, aq as MapPin, ar as MapPinCluster, as as MapPolygon, at as MapPolygonSearchOptions, au as MapSearchResult, av as MapsBaseOptions, aw as QueryListingsLocation, ax as QueryListingsOptions, ay as SEARCH_EMPTY_COPY, az as SEARCH_SORT_RELEVANCE, aA as SearchChromeModel, aB as SearchListingsOptions, aC as SearchPathLocation, aD as SearchUiFilter, aE as SearchUiOption, aF as StaticMapStyle, aG as TOOLBAR_PRIMARY_FILTER_IDS, aH as applyPathFilter, aI as buildQueryListingsParams, aJ as canonicalizeSearchHref, aK as capMapPage, aL as capMapPageSize, aM as clearStagedPathFilters, aN as clusterBuckets, aO as clusterPins, aP as countFacetChoices, aQ as countOptionLabel, aR as displayPathLocation, aS as getCmsCollection, aT as getCmsCollections, aU as getCmsEntries, aV as getCmsEntry, aW as getListing, aX as getListings, aY as getSearchUi, aZ as getSimilarListings, a_ as getSite, a$ as hrefForAppliedChange, b0 as hrefForPathFilters, b1 as hrefWithExplicitPage, b2 as isListingDetailPath, b3 as isMapBounds, b4 as isMapPolygon, b5 as listingLocationLabel, b6 as mapClusterCellDegrees, b7 as mapSearchPins, b8 as paginationPages, b9 as pathFilterHasOption, ba as pathFilterValue, bb as publicSearchHref, bc as queryListings, bd as rangeDraftFromPath, be as readPublicSearch, bf as searchChromeModel, bg as searchHrefUsesLegacyFilterQuery, bh as searchListings, bi as searchListingsInBounds, bj as searchListingsInPolygon, bk as searchResultsHeading, bl as searchSortOptions, bm as toListingCardModel, bn as toolbarFilterIds, bo as visibleSearchFilters } from './types-photo-search-Bmf1f1-Y.js';
3
3
 
4
4
  /**
5
5
  * Visit-lead schedule: hours in, slots out. Pure — no fetch, no React.
@@ -527,10 +527,11 @@ declare const STUDIO_SDK_CONTRACT: {
527
527
  * Phone mask helpers shipped in 0.6.0. Map search
528
528
  * (`useMapSearch`, `searchListingsInBounds`) shipped in 0.9.0 — 0.7.0
529
529
  * does not export them. Property registration shipped in 0.10.0.
530
- * Search filter helpers (`visibleSearchFilters` / `toolbarFilterIds`)
531
- * shipped in 0.4.12 and remain on this pin.
530
+ * Weighted map buckets (`map.buckets`, clustered by the hook) shipped
531
+ * in 0.11.0. Search filter helpers (`visibleSearchFilters` /
532
+ * `toolbarFilterIds`) shipped in 0.4.12 and remain on this pin.
532
533
  */
533
- readonly minNpmVersion: "0.10.0";
534
+ readonly minNpmVersion: "0.11.0";
534
535
  /** Historical: older tarballs inject card CSS when those components mount. */
535
536
  readonly selfInjectSince: "0.4.2";
536
537
  readonly chromeStrategy: "app-owned";
@@ -592,7 +593,7 @@ declare const STUDIO_SDK_CONTRACT: {
592
593
  * `toolbarFilterIds` (shipped in 0.4.12). Do not confuse with
593
594
  * `unpublishedSearchExports` (`searchChromeModel`, …).
594
595
  */
595
- readonly searchExports: readonly ["searchResultsHeading", "searchSortOptions", "visibleSearchFilters", "toolbarFilterIds", "paginationPages", "hrefWithExplicitPage"];
596
+ readonly searchExports: readonly ["searchResultsHeading", "searchSortOptions", "visibleSearchFilters", "toolbarFilterIds", "paginationPages", "hrefWithExplicitPage", "countOptionLabel", "countFacetChoices"];
596
597
  /**
597
598
  * Main-package helpers in git / newer tarballs but not required on
598
599
  * `minNpmVersion`. Prompts must not mention these until the pin bumps and
@@ -611,6 +612,12 @@ declare const STUDIO_SDK_CONTRACT: {
611
612
  * pin sentence does not name it.
612
613
  */
613
614
  readonly mapsSince: "0.9.0";
615
+ /**
616
+ * `useMapSearch` returns weighted location buckets (`map.buckets`, and
617
+ * `map.clusters` built from them) when the matches overflow one page.
618
+ * The map-search guidance teaches bucket clicks only from this pin on.
619
+ */
620
+ readonly mapBucketsSince: "0.11.0";
614
621
  readonly mapsExports: readonly ["listingStaticMapUrl", "listingStreetViewUrl", "listingStreetViewAvailable", "neighborhoodBoundaryLayer", "boundaryLayerUrl", "travelTimeFromListing", "searchListingsInBounds", "searchListingsInPolygon", "clusterPins"];
615
622
  /**
616
623
  * Market-data helpers (neighborhood price summary, listing market
@@ -1192,6 +1199,10 @@ interface PriceEstimateInput {
1192
1199
  parkingSpots?: number;
1193
1200
  propertyType?: MarketPropertyType;
1194
1201
  listingType?: MarketListingType;
1202
+ /** From the address suggestion. Not a form field. */
1203
+ latitude?: number;
1204
+ /** From the address suggestion. Not a form field. */
1205
+ longitude?: number;
1195
1206
  }
1196
1207
  type PriceEstimateConfidence = "high" | "medium" | "low";
1197
1208
  interface PriceEstimate {
package/dist/index.js CHANGED
@@ -63,6 +63,7 @@ __export(src_exports, {
63
63
  capMapPageSize: () => capMapPageSize,
64
64
  clearStagedPathFilters: () => clearStagedPathFilters,
65
65
  clearTravelTimeCache: () => clearTravelTimeCache,
66
+ clusterBuckets: () => clusterBuckets,
66
67
  clusterPins: () => clusterPins,
67
68
  coarsenCoordinates: () => coarsenCoordinates,
68
69
  coerceNpmVersion: () => coerceNpmVersion,
@@ -3018,6 +3019,7 @@ function isVideoPlatformUrl(url) {
3018
3019
  }
3019
3020
  function overlayKind(type, src) {
3020
3021
  if (type === "image" || type === "photo") return null;
3022
+ if (/\.(mp4|webm|ogg|mov)(\?|#|$)/i.test(src)) return "video";
3021
3023
  const host = new URL(src).hostname.toLowerCase();
3022
3024
  if (type === "tour" || type === "virtual_tour" || host.includes("matterport")) {
3023
3025
  return "tour";
@@ -3259,10 +3261,11 @@ var STUDIO_SDK_CONTRACT = {
3259
3261
  * Phone mask helpers shipped in 0.6.0. Map search
3260
3262
  * (`useMapSearch`, `searchListingsInBounds`) shipped in 0.9.0 — 0.7.0
3261
3263
  * does not export them. Property registration shipped in 0.10.0.
3262
- * Search filter helpers (`visibleSearchFilters` / `toolbarFilterIds`)
3263
- * shipped in 0.4.12 and remain on this pin.
3264
+ * Weighted map buckets (`map.buckets`, clustered by the hook) shipped
3265
+ * in 0.11.0. Search filter helpers (`visibleSearchFilters` /
3266
+ * `toolbarFilterIds`) shipped in 0.4.12 and remain on this pin.
3264
3267
  */
3265
- minNpmVersion: "0.10.0",
3268
+ minNpmVersion: "0.11.0",
3266
3269
  /** Historical: older tarballs inject card CSS when those components mount. */
3267
3270
  selfInjectSince: "0.4.2",
3268
3271
  chromeStrategy: "app-owned",
@@ -3373,7 +3376,9 @@ var STUDIO_SDK_CONTRACT = {
3373
3376
  "visibleSearchFilters",
3374
3377
  "toolbarFilterIds",
3375
3378
  "paginationPages",
3376
- "hrefWithExplicitPage"
3379
+ "hrefWithExplicitPage",
3380
+ "countOptionLabel",
3381
+ "countFacetChoices"
3377
3382
  ],
3378
3383
  /**
3379
3384
  * Main-package helpers in git / newer tarballs but not required on
@@ -3396,6 +3401,12 @@ var STUDIO_SDK_CONTRACT = {
3396
3401
  * pin sentence does not name it.
3397
3402
  */
3398
3403
  mapsSince: "0.9.0",
3404
+ /**
3405
+ * `useMapSearch` returns weighted location buckets (`map.buckets`, and
3406
+ * `map.clusters` built from them) when the matches overflow one page.
3407
+ * The map-search guidance teaches bucket clicks only from this pin on.
3408
+ */
3409
+ mapBucketsSince: "0.11.0",
3399
3410
  mapsExports: [
3400
3411
  "listingStaticMapUrl",
3401
3412
  "listingStreetViewUrl",
@@ -3461,7 +3472,7 @@ function isSellerLeadOnPin(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3461
3472
  function studioSellerLeadSdkInstruction(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3462
3473
  if (!isSellerLeadOnPin(pin)) return "";
3463
3474
  const names = STUDIO_SDK_CONTRACT.sellerLeadExports.join(", ");
3464
- return `Property registration (\`/anunciar-imovel\`, client component): import ${names}, isValidPhone, toE164 from \`${STUDIO_SDK_PACKAGE}\`. Address: load Maps JS only through \`<script src="https://maps.fndn.ai/sdk.js?callback=initPlaces" async defer />\` (Places is included; never a Google key, never \`maps.googleapis.com\`), then \`google.maps.places.Autocomplete\` with \`componentRestrictions: { country: "br" }\` and pt-BR. Picking a suggestion fills fullAddress, street, number, neighborhood, city, state (the 2-letter code), postalCode, latitude and longitude from the place; a typed address without a suggestion is not enough. The visitor confirms number or "Sem n\xFAmero", bloco/torre or "N\xE3o tem", unidade or "N\xE3o tem" (noNumber, noBlocoTorre, noUnidade). Block the next group while \`sellerAddressErrors(address)\` has keys and show each message on its field. Owner: name, email and phone are all required \u2014 \`isValidName\`, \`isValidEmail\`, the phone mask with \`isValidPhone(toE164(phone))\`. Photos: \`await uploadSellerLeadPhoto({ siteId, baseUrl: GARAGEM_API_BASE, file, publishableKey })\` per file (JPG/PNG/WEBP, 10MB, up to 30), keep the returned URLs. Photo session: \`const schedule = sellerPhotoSchedule(config)\` and \`slotsForDate(schedule, day)\` for the hours. Submit once with \`await submitSellerLead({ siteId, baseUrl: GARAGEM_API_BASE, publishableKey, owner: { name, email, phone }, address, property: { businessType, saleValue, rentValue, condoFee, totalArea, bedrooms, bathrooms, suites, parkingSpaces }, photos, photoSession: { date, time }, photoSchedule: schedule })\` (omit what the visitor did not fill). Errors are \`LeadSubmitError\`: \`duplicate_property\` \u2192 "Este im\xF3vel j\xE1 est\xE1 cadastrado. Nossa equipe entrar\xE1 em contato."; \`invalid_address\` \u2192 ask to pick the address again; anything else \u2192 a retry message. Disable the submit while pending and show a success state after it resolves. Never POST the leads webhook by hand.`;
3475
+ return `Property registration (\`/anunciar-imovel\`, client component): import ${names}, isValidPhone, toE164 from \`${STUDIO_SDK_PACKAGE}\`. Address: load Maps JS only through \`<script src="https://maps.fndn.ai/sdk.js?callback=initPlaces" async defer />\` (Places is included; never a Google key, never \`maps.googleapis.com\`), then \`google.maps.places.Autocomplete\` with \`componentRestrictions: { country: "br" }\` and pt-BR. Picking a suggestion fills fullAddress, street, number, neighborhood, city, state (the 2-letter code), postalCode, country, latitude and longitude from the place and replaces every one of those values. Show CEP, Rua, N\xFAmero, Bairro, Cidade, Estado and Pa\xEDs as editable inputs bound to postalCode, street, number, neighborhood, city, state and country; the visitor can edit every value submitSellerLead sends. Latitude and longitude come from \`place.geometry.location.lat()\` and \`.lng()\`, are stored on the address and sent, and they are not inputs. A typed address without a suggestion is not enough. The visitor confirms number or "Sem n\xFAmero", bloco/torre or "N\xE3o tem", unidade or "N\xE3o tem" (noNumber, noBlocoTorre, noUnidade). Block the next group while \`sellerAddressErrors(address)\` has keys and show each message on its field. Owner: name, email and phone are all required \u2014 \`isValidName\`, \`isValidEmail\`, the phone mask with \`isValidPhone(toE164(phone))\`. Photos: \`await uploadSellerLeadPhoto({ siteId, baseUrl: GARAGEM_API_BASE, file, publishableKey })\` per file (JPG/PNG/WEBP, 10MB, up to 30), keep the returned URLs. Photo session: \`const schedule = sellerPhotoSchedule(config)\` and \`slotsForDate(schedule, day)\` for the hours. Submit once with \`await submitSellerLead({ siteId, baseUrl: GARAGEM_API_BASE, publishableKey, owner: { name, email, phone }, address, property: { businessType, saleValue, rentValue, condoFee, totalArea, bedrooms, bathrooms, suites, parkingSpaces }, photos, photoSession: { date, time }, photoSchedule: schedule })\` (omit what the visitor did not fill). Errors are \`LeadSubmitError\`: \`duplicate_property\` \u2192 "Este im\xF3vel j\xE1 est\xE1 cadastrado. Nossa equipe entrar\xE1 em contato."; \`invalid_address\` \u2192 ask to pick the address again; anything else \u2192 a retry message. Disable the submit while pending and show a success state after it resolves. Never POST the leads webhook by hand.`;
3465
3476
  }
3466
3477
  function isPhotoSearchOnPin(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3467
3478
  return compareSemver(pin, STUDIO_SDK_CONTRACT.photoSearchSince) >= 0;
@@ -3601,7 +3612,7 @@ function studioAmenityInstruction() {
3601
3612
  function studioSearchInstruction() {
3602
3613
  const reactNames = STUDIO_SDK_CONTRACT.reactExports.join(", ");
3603
3614
  const libNames = STUDIO_SDK_CONTRACT.searchExports.join(", ");
3604
- return `Search: import ${reactNames} from \`${STUDIO_SDK_PACKAGE}/react\`. From \`${STUDIO_SDK_PACKAGE}\` import ${libNames}. Prefetch \`getSearchUi\` + \`queryListings\` on the server page. \`const search = usePublicSearch({ siteId, baseUrl: GARAGEM_API_BASE, search: searchFromServer, initial })\` where \`searchFromServer\` is \`new URLSearchParams(await searchParams).toString()\` \u2014 never shorthand \`{ search }\` beside \`const search =\` (temporal dead zone). Do not wrap this UI in \`<Suspense>\` and do not add a route \`loading\` file \u2014 heading and cards are ordinary elements in the document, visible with JavaScript off. Compose the page UI in the app \u2014 do not paste a canonical search TSX. Required chrome (design is free; omit none): query (\`qDraft\` / \`setQDraft\` / form \`preventDefault\` + \`submitQuery\`), heading (count span FIRST then h1 from \`searchResultsHeading(search.pathFilters, search.schema?.dictionary, search.locationNames)\` \u2014 never \`searchResultsHeading({})\`), toolbar (\`toolbarFilterIds\` + \`applyFilter\`; range \u201CAtualizar\u201D on that toolbar item only) vs sheet (\`visibleSearchFilters\` extras, \`stageFilter\`, one footer \`applyStaged\`), sort (\`searchSortOptions\` + \`setSort\`; first option id is \`""\` / \u201CMais relevantes\u201D \u2014 map **only** that empty id to Select sentinel \`"relevancia"\` (\`opt.id || "relevancia"\`), never \`SelectItem value=""\` and never give \u201CMais recentes\u201D (\`id: "recentes"\`, \`?ordenar=recentes\`) that sentinel; on change \`setSort(id === "relevancia" ? "" : id)\` so recentes stays recentes. Closed trigger shows the option \`.label\`, never \`{search.applied.sort}\`), grid (\`listings.map\` + the site listing-card module; listing-card-skeleton only for a slot whose content is still unknown, never as a Suspense fallback; do not \`throw\` in that chrome), pagination (\`paginationPages\` + \`hrefWithExplicitPage\`). Never interpolate \`schema\`, \`pathFilters\`, or a filter object as a React child. \`queryListings\` key is \`params\`. The URL is the document. Count text is \`{search.total}\` only. Heading is one row; font size lives on the container and the span and h1 use \`font-size: inherit\`. Sort trigger shows the option label (\u201CMais relevantes\u201D when \`ordenar\` is absent), chevron at the end, same height as the toolbar controls. Toolbar ranges open a Popover form (not DropdownMenu \u2014 Menu typeahead swallows digit keys) whose submit calls \`applyFilter\`; the popup clips and the two inputs stay inside (\`min-w-0\`, no \`w-64\`). Reset min/max drafts when the popover opens and when the applied path range changes. The sheet omits toolbar ids (price, bedrooms) so Pre\xE7o is never a heading without inputs. Sheet DialogContent uses \`h-[min(640px,85dvh)]\` (not max-h alone) so the body ScrollArea can move. Tipo de im\xF3vel, caracter\xEDsticas and comodidades each use a nested ScrollArea with \`h-56 overflow-hidden\` (viewport \`h-full\`). Area is two inputs in schema order with no \u201CAplicar\u201D; the footer stages then applyStaged. Never read \`staged[filter.id]\` \u2014 path keys are \`bedrooms\` / \`listingType\` / \`bathrooms\`. Bedrooms Select reads \`pathFilters.bedrooms\` so \`/imoveis/4-quartos\` checks \`"4"\` and shows the same trigger dot as price. Bathrooms and parking pressed state uses \`pathFilterHasOption\`. Limpar keeps location plus toolbar price and bedrooms via \`clearStagedPathFilters\` and \`toolbarFilterIds\`; do not call \`clearStaged\` for that button. It enables only when staged has a path filter other than location and those kept toolbar ids. Each multi-select \`stageFilter\` value is one option id, never a concatenated slug; \`checked\` uses \`pathFilterHasOption\`. Listing type does not pass the clicked id: no path value shows every checkbox checked, unchecking one stages the other option's id, and the last box stays checked. Price inputs use formatGroupedInteger. The closed price and bedrooms triggers keep the filter label plus a dot when set \u2014 never the literal range. Empty price calls applyFilter(id, undefined); never send 0 or 1000000000. Area is a plain integer (not that mask). The results button stageFilter property_area_total with both drafts, then applyStaged. Never send 0 or 100000. Count buttons pass the option id (\`"2"\`), never the label \`"2+"\`. Property type, features, and amenities render in pt-BR label order. Do not set \`[data-slot="search-sort"] { flex-direction: column }\` in a \`<style>\` tag; that selector is row so the chevron sits beside the label. Empty copy: ${JSON.stringify(SEARCH_EMPTY_COPY)}`;
3615
+ return `Search: import ${reactNames} from \`${STUDIO_SDK_PACKAGE}/react\`. From \`${STUDIO_SDK_PACKAGE}\` import ${libNames}. Prefetch \`getSearchUi\` + \`queryListings\` on the server page. \`const search = usePublicSearch({ siteId, baseUrl: GARAGEM_API_BASE, search: searchFromServer, initial })\` where \`searchFromServer\` is \`new URLSearchParams(await searchParams).toString()\` \u2014 never shorthand \`{ search }\` beside \`const search =\` (temporal dead zone). Do not wrap this UI in \`<Suspense>\` and do not add a route \`loading\` file \u2014 heading and cards are ordinary elements in the document, visible with JavaScript off. Compose the page UI in the app \u2014 do not paste a canonical search TSX. Required chrome (design is free; omit none): query (\`qDraft\` / \`setQDraft\` / form \`preventDefault\` + \`submitQuery\`), heading (count span FIRST then h1 from \`searchResultsHeading(search.pathFilters, search.schema?.dictionary, search.locationNames)\` \u2014 never \`searchResultsHeading({})\`), toolbar (\`toolbarFilterIds\` + \`applyFilter\`; range \u201CAtualizar\u201D on that toolbar item only) vs sheet (\`visibleSearchFilters\` extras, \`stageFilter\`, one footer \`applyStaged\`), sort (\`searchSortOptions\` + \`setSort\`; first option id is \`""\` / \u201CMais relevantes\u201D \u2014 map **only** that empty id to Select sentinel \`"relevancia"\` (\`opt.id || "relevancia"\`), never \`SelectItem value=""\` and never give \u201CMais recentes\u201D (\`id: "recentes"\`, \`?ordenar=recentes\`) that sentinel; on change \`setSort(id === "relevancia" ? "" : id)\` so recentes stays recentes. Closed trigger shows the option \`.label\`, never \`{search.applied.sort}\`), grid (\`listings.map\` + the site listing-card module; listing-card-skeleton only for a slot whose content is still unknown, never as a Suspense fallback; do not \`throw\` in that chrome), pagination (\`paginationPages\` + \`hrefWithExplicitPage\`). Never interpolate \`schema\`, \`pathFilters\`, or a filter object as a React child. \`queryListings\` key is \`params\`. The URL is the document. Count text is \`{search.total}\` only. Heading is one row; font size lives on the container and the span and h1 use \`font-size: inherit\`. Sort trigger shows the option label (\u201CMais relevantes\u201D when \`ordenar\` is absent), chevron at the end, same height as the toolbar controls. Toolbar ranges open a Popover form (not DropdownMenu \u2014 Menu typeahead swallows digit keys) whose submit calls \`applyFilter\`; the popup clips and the two inputs stay inside (\`min-w-0\`, no \`w-64\`). Reset min/max drafts when the popover opens and when the applied path range changes. The sheet omits toolbar ids (price, bedrooms) so Pre\xE7o is never a heading without inputs. Sheet DialogContent uses \`h-[min(640px,85dvh)]\` (not max-h alone) so the body ScrollArea can move. Tipo de im\xF3vel, caracter\xEDsticas and comodidades each use a nested ScrollArea with \`h-56 overflow-hidden\` (viewport \`h-full\`). Area is two inputs in schema order with no \u201CAplicar\u201D; the footer stages then applyStaged. Never read \`staged[filter.id]\` \u2014 path keys are \`bedrooms\` / \`listingType\` / \`bathrooms\`. Bedrooms Select reads \`pathFilters.bedrooms\` so \`/imoveis/4-quartos\` checks \`"4"\` and shows the same trigger dot as price. Bathrooms and parking pressed state uses \`pathFilterHasOption\`. Limpar keeps location plus toolbar price and bedrooms via \`clearStagedPathFilters\` and \`toolbarFilterIds\`; do not call \`clearStaged\` for that button. It enables only when staged has a path filter other than location and those kept toolbar ids. Each multi-select \`stageFilter\` value is one option id, never a concatenated slug; \`checked\` uses \`pathFilterHasOption\`. Listing type does not pass the clicked id: no path value shows every checkbox checked, unchecking one stages the other option's id, and the last box stays checked. Price inputs use formatGroupedInteger. The closed price and bedrooms triggers keep the filter label plus a dot when set \u2014 never the literal range. Empty price calls applyFilter(id, undefined); never send 0 or 1000000000. Area is a plain integer (not that mask). The results button stageFilter property_area_total with both drafts, then applyStaged. Never send 0 or 100000. Count buttons pass the option id (\`"2"\`), never the label \`"2+"\`. Count-button text is \`countOptionLabel(option)\`; never map id \`"0"\` to "Studio" (only bedrooms gets that label, from the schema). Property type, features, and amenities render in pt-BR label order. Do not set \`[data-slot="search-sort"] { flex-direction: column }\` in a \`<style>\` tag; that selector is row so the chevron sits beside the label. Empty copy: ${JSON.stringify(SEARCH_EMPTY_COPY)}`;
3605
3616
  }
3606
3617
  function mapsExportsPublished(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3607
3618
  return compareSemver(pin, STUDIO_SDK_CONTRACT.mapsSince) >= 0;
@@ -3611,9 +3622,21 @@ function studioMapsInstruction(options = {}) {
3611
3622
  const names = STUDIO_SDK_CONTRACT.mapsExports.join(", ");
3612
3623
  return `Maps on listing detail: from \`${STUDIO_SDK_PACKAGE}\` import ${names}. \`listing.location.coordinates\` is already masked by the site's privacy settings (\u2248100 m by default) \u2014 pass the listing object as-is; never un-mask, never re-geocode the street address to get a sharper point, never add decimals (\`maxDecimals\` can only coarsen). Always pass \`siteId\` (the resolved site id / publishable key) so maps.fndn.ai meters the site. Static map: \`const mapSrc = listingStaticMapUrl(listing, { width: 640, height: 320, zoom: 15, style: "roadmap", siteId })\` then \`{mapSrc ? <img src={mapSrc} alt={model.location.label} /> : null}\` \u2014 \`null\` means no coordinates, so omit the block (never a placeholder image). Zoom is capped by the coordinate precision (16 on the default mask); do not work around it. Street View: on the server page \`const sv = await listingStreetViewAvailable(listing, { siteId })\` (metadata is free), and only when \`sv.available\` render \`<img src={listingStreetViewUrl(listing, { width: 640, height: 400, siteId })} alt="Street View" />\` \u2014 the image is billed per load. Neighbourhood outline on an interactive map: load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` (never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`); in \`initMap\` do \`const outline = await neighborhoodBoundaryLayer(listing.location.city, listing.location.neighborhood, { siteId })\` and \`if (outline.feature) map.data.addGeoJson(outline.feature)\`; with MapLibre the vector source url is \`boundaryLayerUrl(listing.location.city)\`. Travel time (\u201Cquanto tempo at\xE9\u2026\u201D): \`const trip = await travelTimeFromListing(listing, destination, { mode: "driving", siteId })\` gives \`{ minutes, distanceKm }\` or \`null\` (hide the row). Every uncached call is a billed Google Directions request: call it on demand \u2014 a destination the visitor typed, or at most one fixed landmark per listing page \u2014 never per listing card, never inside a search loop, keep the SDK cache on (default 15 min LRU, \`cache: null\` only in tests), and do not re-run it on every render.`;
3613
3624
  }
3625
+ var MAP_CLUSTER_MEMBERS_CLICK = "`const members = map.pins.filter((pin) => cluster.pinIds.includes(pin.id))`, then `fitBounds` a LatLngBounds of their coordinates with about 64px padding, so the listings land inside the new view and split into chips.";
3626
+ var MAP_CLUSTER_SAME_POINT = "When every member has the same coordinates, or the map is already at zoom 18, do not zoom: open a small list of those listings, each with its price and a link.";
3627
+ function studioMapClusterClickInstruction(buckets) {
3628
+ if (!buckets) {
3629
+ return `Clicking a cluster opens its members: ${MAP_CLUSTER_MEMBERS_CLICK} Do not step the zoom around \`cluster.lat\`/\`cluster.lng\`: that point is approximate and the area around it can come back empty. ${MAP_CLUSTER_SAME_POINT}`;
3630
+ }
3631
+ return `Clicking a cluster depends on \`cluster.pinIds\`. A cluster with members (\`cluster.pinIds.length > 0\`) opens them: ${MAP_CLUSTER_MEMBERS_CLICK} For such a cluster do not step the zoom around \`cluster.lat\`/\`cluster.lng\`: that point is approximate and the area around it can come back empty. ${MAP_CLUSTER_SAME_POINT} A cluster with empty \`pinIds\` is a bucket and has no members to fit: on click center the map on \`cluster.lat\`/\`cluster.lng\` and zoom in two levels \u2014 the next viewport search returns finer buckets or the listings themselves.`;
3632
+ }
3614
3633
  function studioMapSearchInstruction(options = {}) {
3615
3634
  if (!mapsExportsPublished(options.pin)) return "";
3616
- return `Map search on \`/imoveis\` (list and map of the same query). The list stays: keep \`usePublicSearch\` for the list, including its sort and pagination. The visitor switches on the same page. \`?modo=mapa\` is the map \u2014 read it on first paint. The list is the URL without \`modo\`; do not write \`modo=lista\` or \`modo=grade\`. Choosing the map sets \`modo=mapa\` and drops \`page\`. Choosing the list removes \`modo\`. On the map, hide sort and pagination. Do not add a map pager. The heading stays. Filters apply to both. Load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` \u2014 never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`, never \`maps.googleapis.com\`, never \`@vis.gl/react-google-maps\`. From \`${STUDIO_SDK_PACKAGE}/react\` import useMapSearch; it fetches, debounces, and clusters. \`const map = useMapSearch({ siteId, baseUrl: GARAGEM_API_BASE, bounds, zoom, q, sort, location, filters, publishableKey })\` with the same q, sort, location, filters, and publishableKey as the list. Pass the map's current zoom on every zoom change, including after a cluster click. Changing zoom recomputes \`map.clusters\` and does not refetch; a bounds change refetches. Do not send filter_by, vector_query, or nl_query from the browser. Request page 1 and pageSize at most 100. Do not walk totalPages. Pins are the masked coordinates the API returned \u2014 plot them as returned, never geocode the street. Render \`map.clusters\` with \`google.maps.Marker\` (no map id needed), in two styles that never look alike. A cluster (\`count > 1\`) is a filled circle in the brand color with a white border and the white count as its label. A listing (\`count === 1\` with \`cluster.pin\`) is a white rounded-rectangle chip with a brand-color border, labelled with the short price in the brand color ("R$ 850 mil", "R$ 1,2 mi"; "Consulte" when the price is null or 0): \`icon: { path: "M-34,-12 h68 a6,6 0 0 1 6,6 v12 a6,6 0 0 1 -6,6 h-68 a6,6 0 0 1 -6,-6 v-12 a6,6 0 0 1 6,-6 z", fillColor: "#ffffff", fillOpacity: 1, strokeColor: brand, strokeWeight: 1.5, scale: 1, labelOrigin: new google.maps.Point(0, 0) }\`. Never draw a listing as a dot or a circle, and never without its price. Clicking a listing selects it and shows its card. Clicking a cluster opens its members: \`const members = map.pins.filter((pin) => cluster.pinIds.includes(pin.id))\`, then \`fitBounds\` a LatLngBounds of their coordinates with about 64px padding, so the listings land inside the new view and split into chips. Do not step the zoom around \`cluster.lat\`/\`cluster.lng\`: that point is approximate and the area around it can come back empty. When every member has the same coordinates, or the map is already at zoom 18, do not zoom: open a small list of those listings, each with its price and a link. Layout, top to bottom: query, heading, toolbar, then the view. On desktop the toolbar is one row: featured filters on the left, and the list/map toggle immediately beside the sort select on the right. On a narrow screen the filters stay in one horizontal scroll that does not wrap, and the toggle plus the sort sit together on the row below that scroll. On the map the sort is hidden, so the toggle keeps that place beside where the sort was. In map mode the map fills the remaining viewport height, with a minimum of about 240px. Keep the hook's 400ms viewport debounce. A drawn polygon is not required. Do not add a separate /mapa route, a regions page, or a map on the listing page. Do not call Street View or travel time inside the map search.`;
3635
+ const pin = options.pin ?? STUDIO_SDK_CONTRACT.minNpmVersion;
3636
+ const hasBuckets = compareSemver(pin, STUDIO_SDK_CONTRACT.mapBucketsSince) >= 0;
3637
+ const buckets = hasBuckets ? " When the matches do not fit on one page, the hook builds `map.clusters` from location buckets whose counts add up to `map.total`; render them as they come and never fetch or merge more pages. Draw a bucket like any other cluster." : "";
3638
+ const clusterClick = studioMapClusterClickInstruction(hasBuckets);
3639
+ return `Map search on \`/imoveis\` (list and map of the same query). The list stays: keep \`usePublicSearch\` for the list, including its sort and pagination. The visitor switches on the same page. \`?modo=mapa\` is the map \u2014 read it on first paint. The list is the URL without \`modo\`; do not write \`modo=lista\` or \`modo=grade\`. Choosing the map sets \`modo=mapa\` and drops \`page\`. Choosing the list removes \`modo\`. On the map, hide sort and pagination. Do not add a map pager. The heading stays. Filters apply to both. Load Maps JS ONLY through \`<script src="https://maps.fndn.ai/sdk.js?callback=initMap" async defer />\` \u2014 never a Google key in the app, never \`NEXT_PUBLIC_GOOGLE_MAPS_API_KEY\`, never \`maps.googleapis.com\`, never \`@vis.gl/react-google-maps\`. From \`${STUDIO_SDK_PACKAGE}/react\` import useMapSearch; it fetches, debounces, and clusters. \`const map = useMapSearch({ siteId, baseUrl: GARAGEM_API_BASE, bounds, zoom, q, sort, location, filters, publishableKey })\` with the same q, sort, location, filters, and publishableKey as the list. Pass the map's current zoom on every zoom change, including after a cluster click. Changing zoom recomputes \`map.clusters\` and does not refetch; a bounds change refetches. Do not send filter_by, vector_query, or nl_query from the browser. Request page 1 and pageSize at most 100. Do not walk totalPages. Pins are the masked coordinates the API returned \u2014 plot them as returned, never geocode the street. Render \`map.clusters\` with \`google.maps.Marker\` (no map id needed), in two styles that never look alike. A cluster (\`count > 1\`) is a filled circle in the brand color with a white border and the white count as its label. A listing (\`count === 1\` with \`cluster.pin\`) is a white rounded-rectangle chip with a brand-color border, labelled with the short price in the brand color ("R$ 850 mil", "R$ 1,2 mi"; "Consulte" when the price is null or 0): \`icon: { path: "M-34,-12 h68 a6,6 0 0 1 6,6 v12 a6,6 0 0 1 -6,6 h-68 a6,6 0 0 1 -6,-6 v-12 a6,6 0 0 1 6,-6 z", fillColor: "#ffffff", fillOpacity: 1, strokeColor: brand, strokeWeight: 1.5, scale: 1, labelOrigin: new google.maps.Point(0, 0) }\`. Never draw a listing as a dot or a circle, and never without its price. Clicking a listing selects it and shows its card. The card content is \`toListingCardModel(map.listings.find((listing) => listing.id === pin.id))\` and shows, in order: a large cover (\`coverSrc\`, aspect 4/3, full card width), title, \`priceLabel\`, \`locationLabel\`, then the facts that are present: \`bedrooms\` quartos, \`bathrooms\` banheiros, \`parkingSpaces\` vagas, \`areaM2\` m\xB2. Title and price alone are incomplete. On a wide screen the card opens next to its pin, never at the bottom of the map, where it falls below the viewport when the page is scrolled. Use one \`google.maps.InfoWindow\` and open it on the clicked marker: \`infoWindow.open({ map: googleMap, anchor: marker })\`. Its content is a div that React fills with \`createPortal\`. The InfoWindow pans the map so the card is in view. On a narrow screen the same card sits in a bottom sheet across the map width. Dismissing it leaves the pins. While \`map.loading\` the map is \`aria-busy\` with a visible progress indicator and the previous pins stay mounted. ${clusterClick} Layout, top to bottom: query, heading, toolbar, then the view. Lista and Mapa are icon buttons with the site tooltip and \`aria-label\` \u201CLista\u201D / \u201CMapa\u201D, not icon-plus-text. On desktop the toolbar is one row: featured filters on the left, and the list/map toggle immediately beside the sort select on the right. On a narrow screen the filters stay in one horizontal scroll that does not wrap, and the toggle plus the sort sit together on the row below that scroll. That row fits the viewport and never widens the page; sort may truncate. On the map the sort is hidden, so the toggle keeps that place beside where the sort was. In map mode the map fills the remaining viewport height, with a minimum of about 240px. Keep the hook's 400ms viewport debounce. A drawn polygon is not required. Do not add a separate /mapa route, a regions page, or a map on the listing page. Do not call Street View or travel time inside the map search.${buckets}`;
3617
3640
  }
3618
3641
  function marketExportsAvailableAt(pin) {
3619
3642
  return compareSemver(pin, STUDIO_SDK_CONTRACT.marketExportsSince) >= 0;
@@ -3627,7 +3650,7 @@ function studioMarketInstruction(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
3627
3650
  return `Market data: import ${names} from \`${STUDIO_SDK_PACKAGE}\`. **IPTU module required.** Every helper returns \`{ available: false, reason }\` (HTTP 200, never a throw) unless the site's organization has the IPTU module (\`iptu_itbi_integration\`) and the city is covered \u2014 most sites get \`available: false\`. ALWAYS render these blocks conditionally: \`if (!result.available) return null\` (omit the whole section, heading included); never a placeholder, never \u201Cdados indispon\xEDveis\u201D, never a local fallback number. The payloads carry only aggregates and a trimmed estimate \u2014 never render, request, or invent cadastral ids, IPTU lookups, ITBI transactions, comparables, or addresses from market data. Reasons are codes (\`module_not_enabled\`, \`city_unsupported\`, \`no_data\`, \`rate_limited\`, \u2026) \u2014 do not print them. Three blocks (all optional, design is free):
3628
3651
  - Neighborhood summary (listing detail, optionally search heading): \`const summary = await ${summary}({ siteId, baseUrl: GARAGEM_API_BASE, query: { city: listing.location.city, neighborhood: listing.location.neighborhood } })\`. Render \`summary.pricePerSqmFormatted.p25\` / \`.p50\` / \`.p75\` (strings, already \`R$ X/m\xB2\`) and \`summary.sampleSize\` (\u201Ccom base em N vendas\u201D); omit the sample line when null.
3629
3652
  - Listing market position (listing detail, near the price): \`const position = await ${position}({ siteId, baseUrl: GARAGEM_API_BASE, listingId: listing.id })\`. Copy comes from the helpers only: \`${positionLabel}(position)\` (\u201C8% abaixo da mediana do bairro\u201D) and \`${bandLabel}(position)\` (\u201CNa faixa do bairro, abaixo da mediana\u201D); both return \`null\` when unavailable \u2014 hide the line on \`null\`. Show \`position.listingPricePerSqmFormatted\` vs \`position.medianPricePerSqmFormatted\` if a comparison row is wanted. Do not compute the percent in the app.
3630
- - Visitor price estimate (\`/anunciar\` or a dedicated page, client component): a form with city, bairro, \xE1rea (m\xB2), quartos, vagas, tipo; on submit \`const estimate = await ${estimate}({ siteId, baseUrl: GARAGEM_API_BASE, input: { city, neighborhood, areaSqm, bedrooms, parkingSpots, propertyType } })\`. Render \`estimate.estimatedPriceFormatted\` with the range \`estimate.rangeLowFormatted\` \u2013 \`estimate.rangeHighFormatted\` and \`estimate.confidenceLabel\` mapped to pt-BR (alta / m\xE9dia / baixa). When \`available\` is false show \`estimate.message\` (pt-BR, already written) and the contact CTA. It is rate limited per visitor \u2014 disable the submit while pending. Never call it on page load.
3653
+ - Visitor price estimate (its own page, never \`/anunciar\` or \`/anunciar-imovel\`, client component): an address suggestion fills editable fields for city, bairro, \xE1rea (m\xB2), quartos, banheiros, vagas, tipo; latitude and longitude come from the suggestion and are not inputs. On submit \`const input = { city, neighborhood, areaSqm, bedrooms, bathrooms, parkingSpots, propertyType, latitude, longitude }; const estimate = await ${estimate}({ siteId, baseUrl: GARAGEM_API_BASE, input })\`. Render \`estimate.estimatedPriceFormatted\` with the range \`estimate.rangeLowFormatted\` \u2013 \`estimate.rangeHighFormatted\` and \`estimate.confidenceLabel\` mapped to pt-BR (alta / m\xE9dia / baixa). When \`available\` is false show \`estimate.message\` (pt-BR, already written) and the contact CTA. It is rate limited per visitor \u2014 disable the submit while pending. Never call it on page load.
3631
3654
  Fetch on the server page (\`next: { revalidate: 900 }\`) for the summary and position; the estimate is a user action. Resolve \`siteId\` the same way as every other SDK call.`;
3632
3655
  }
3633
3656
  function studioPhotoSearchInstruction(pin = STUDIO_SDK_CONTRACT.minNpmVersion) {
@@ -4385,21 +4408,24 @@ function mapSearchPins(listings) {
4385
4408
  }
4386
4409
  return pins;
4387
4410
  }
4388
- function listingsResult(listings, meta, requestedPageSize) {
4411
+ function listingsResult(result, requestedPageSize) {
4412
+ const listings = result.listings ?? [];
4389
4413
  return {
4390
4414
  pins: mapSearchPins(listings),
4391
4415
  cards: listings.map((listing) => toListingCardModel(listing)),
4392
4416
  listings,
4393
- page: meta.page ?? 1,
4394
- pageSize: meta.limit ?? requestedPageSize,
4395
- total: meta.total ?? listings.length,
4396
- totalPages: meta.totalPages ?? 0
4417
+ page: result.page ?? 1,
4418
+ pageSize: result.limit ?? requestedPageSize,
4419
+ total: result.total ?? listings.length,
4420
+ totalPages: result.totalPages ?? 0,
4421
+ buckets: result.buckets ?? []
4397
4422
  };
4398
4423
  }
4399
4424
  function searchParams(area, options) {
4400
4425
  const params = {
4401
4426
  page: capMapPage(options.page),
4402
- limit: capMapPageSize(options.pageSize)
4427
+ limit: capMapPageSize(options.pageSize),
4428
+ buckets: true
4403
4429
  };
4404
4430
  if (options.q !== void 0) params.q = options.q;
4405
4431
  if (options.sort !== void 0) params.sort = options.sort;
@@ -4420,7 +4446,7 @@ async function runMapSearch(siteId, area, options) {
4420
4446
  publishableKey: options.publishableKey,
4421
4447
  next: options.next
4422
4448
  });
4423
- return listingsResult(result.listings ?? [], result, pageSize);
4449
+ return listingsResult(result, pageSize);
4424
4450
  }
4425
4451
  async function searchListingsInBounds(siteId, options) {
4426
4452
  if (!isMapBounds(options.bounds)) {
@@ -4445,63 +4471,63 @@ function clampZoom(zoom) {
4445
4471
  function mapClusterCellDegrees(zoom) {
4446
4472
  return 360 / 2 ** clampZoom(zoom) / 4;
4447
4473
  }
4448
- function usablePin(pin) {
4449
- return finitePair(pin.lat, pin.lng) !== null && !(pin.lat === 0 && pin.lng === 0);
4474
+ function usablePoint(point) {
4475
+ return finitePair(point.lat, point.lng) !== null && !(point.lat === 0 && point.lng === 0);
4450
4476
  }
4451
4477
  function groupPrecision(group) {
4452
4478
  let max = 0;
4453
- for (const pin of group) {
4479
+ for (const point of group) {
4454
4480
  max = Math.max(
4455
4481
  max,
4456
- coordinateDecimals(pin.lat),
4457
- coordinateDecimals(pin.lng)
4482
+ coordinateDecimals(point.lat),
4483
+ coordinateDecimals(point.lng)
4458
4484
  );
4459
4485
  }
4460
4486
  return max;
4461
4487
  }
4462
- function multiCluster(key, group) {
4463
- const lat = group.reduce((sum, pin) => sum + pin.lat, 0) / group.length;
4464
- const lng = group.reduce((sum, pin) => sum + pin.lng, 0) / group.length;
4465
- const center = coarsenCoordinates({ lat, lng }, groupPrecision(group));
4466
- return {
4467
- id: key,
4468
- lat: center.lat,
4469
- lng: center.lng,
4470
- count: group.length,
4471
- pinIds: group.map((pin) => pin.id),
4472
- pin: null
4473
- };
4474
- }
4475
- function singleCluster(pin) {
4476
- return {
4477
- id: pin.id,
4478
- lat: pin.lat,
4479
- lng: pin.lng,
4480
- count: 1,
4481
- pinIds: [pin.id],
4482
- pin
4483
- };
4484
- }
4485
- function clusterPins(pins, zoom) {
4486
- if (pins.length === 0) return [];
4488
+ function gridCells(points, zoom, weight) {
4487
4489
  const cell = mapClusterCellDegrees(zoom);
4488
4490
  const groups = /* @__PURE__ */ new Map();
4489
- for (const pin of pins) {
4490
- if (!usablePin(pin)) continue;
4491
- const key = `${Math.floor(pin.lat / cell)}:${Math.floor(pin.lng / cell)}`;
4491
+ for (const point of points) {
4492
+ if (!usablePoint(point)) continue;
4493
+ const key = `${Math.floor(point.lat / cell)}:${Math.floor(point.lng / cell)}`;
4492
4494
  const list = groups.get(key);
4493
- if (list) list.push(pin);
4494
- else groups.set(key, [pin]);
4495
- }
4496
- const clusters = [];
4497
- for (const [key, group] of groups) {
4498
- const only = group[0];
4499
- clusters.push(
4500
- group.length === 1 && only ? singleCluster(only) : multiCluster(key, group)
4501
- );
4495
+ if (list) list.push(point);
4496
+ else groups.set(key, [point]);
4502
4497
  }
4503
- clusters.sort((a, b) => a.id.localeCompare(b.id));
4504
- return clusters;
4498
+ return [...groups].map(([key, members]) => {
4499
+ const count = members.reduce((sum, point) => sum + weight(point), 0);
4500
+ const only = members.length === 1 ? members[0] : void 0;
4501
+ const center = only ?? coarsenCoordinates(
4502
+ {
4503
+ lat: members.reduce((sum, p) => sum + p.lat * weight(p), 0) / count,
4504
+ lng: members.reduce((sum, p) => sum + p.lng * weight(p), 0) / count
4505
+ },
4506
+ groupPrecision(members)
4507
+ );
4508
+ return {
4509
+ id: only?.id ?? key,
4510
+ lat: center.lat,
4511
+ lng: center.lng,
4512
+ count,
4513
+ pinIds: [],
4514
+ pin: null,
4515
+ members
4516
+ };
4517
+ }).sort((a, b) => a.id.localeCompare(b.id));
4518
+ }
4519
+ function clusterPins(pins, zoom) {
4520
+ return gridCells(pins, zoom, () => 1).map(({ members, ...cluster }) => ({
4521
+ ...cluster,
4522
+ pinIds: members.map((pin) => pin.id),
4523
+ pin: members.length === 1 ? members[0] ?? null : null
4524
+ }));
4525
+ }
4526
+ function clusterBuckets(buckets, zoom) {
4527
+ const weighted = buckets.filter((bucket) => bucket.count > 0);
4528
+ return gridCells(weighted, zoom, (bucket) => bucket.count).map(
4529
+ ({ members: _members, ...cluster }) => cluster
4530
+ );
4505
4531
  }
4506
4532
 
4507
4533
  // src/fetchers-photos.ts
@@ -5066,6 +5092,7 @@ function applyMatchedPhotoCover(cards, photoResults, options = {}) {
5066
5092
  capMapPageSize,
5067
5093
  clearStagedPathFilters,
5068
5094
  clearTravelTimeCache,
5095
+ clusterBuckets,
5069
5096
  clusterPins,
5070
5097
  coarsenCoordinates,
5071
5098
  coerceNpmVersion,