@garagem-ai/site-sdk 0.5.2 → 0.6.0

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.
Files changed (42) hide show
  1. package/README.md +16 -25
  2. package/dist/index.d.mts +296 -28
  3. package/dist/index.d.ts +296 -28
  4. package/dist/index.js +469 -53
  5. package/dist/index.js.map +1 -1
  6. package/dist/index.mjs +458 -51
  7. package/dist/index.mjs.map +1 -1
  8. package/dist/react.d.mts +18 -60
  9. package/dist/react.d.ts +18 -60
  10. package/dist/react.js +265 -874
  11. package/dist/react.js.map +1 -1
  12. package/dist/react.mjs +246 -841
  13. package/dist/react.mjs.map +1 -1
  14. package/dist/{search-engine-4ocM0UPk.d.mts → search-engine-CtnLzmwW.d.mts} +13 -181
  15. package/dist/{search-engine-4ocM0UPk.d.ts → search-engine-CtnLzmwW.d.ts} +13 -181
  16. package/package.json +11 -13
  17. package/src/amenity-labels.ts +9 -2
  18. package/src/fetchers.ts +2 -1
  19. package/src/index.ts +20 -2
  20. package/src/internal/url.ts +1 -0
  21. package/src/leads.ts +45 -6
  22. package/src/listing-card-model.ts +4 -1
  23. package/src/listing-detail.ts +8 -2
  24. package/src/phone-countries.ts +97 -0
  25. package/src/phone.ts +431 -0
  26. package/src/presentation.ts +1 -24
  27. package/src/react/index.ts +1 -11
  28. package/src/react/public-search-snapshot.ts +165 -0
  29. package/src/react/staged-filters-mirror.ts +38 -0
  30. package/src/react/types.ts +17 -30
  31. package/src/react/use-public-search.ts +121 -42
  32. package/src/search-engine.ts +3 -0
  33. package/src/studio-contract.ts +63 -21
  34. package/src/types.ts +12 -0
  35. package/src/react/cn.ts +0 -3
  36. package/src/react/listing-card.tsx +0 -98
  37. package/src/react/listing-detail-fields.tsx +0 -119
  38. package/src/react/search-chrome.tsx +0 -29
  39. package/src/react/search.css +0 -214
  40. package/src/react/styles/index.ts +0 -1
  41. package/src/react/styles/search-chrome-css.generated.ts +0 -5
  42. package/src/react/styles/search-chrome-styles.tsx +0 -31
@@ -1,31 +1,8 @@
1
1
  /**
2
2
  * Presentation helpers with no UI framework.
3
- * React / React Native / Flutter adapters consume these formatters and
4
- * CSS custom-property names; they must not live inside JSX.
3
+ * Adapters consume these formatters; they must not live inside JSX.
5
4
  */
6
5
 
7
- export const SEARCH_CSS_VARS = {
8
- cardRadius: "--garagem-listing-card-radius",
9
- cardGap: "--garagem-listing-card-gap",
10
- priceSize: "--garagem-listing-price-size",
11
- mediaRatio: "--garagem-listing-media-ratio",
12
- controlHeight: "--garagem-search-control-height",
13
- iconSize: "--garagem-search-icon-size",
14
- skeleton: "--garagem-skeleton",
15
- } as const;
16
-
17
- /** Paste into generated `globals.css` to override tokens. Layout lives in the chrome artifact. */
18
- export const SEARCH_CSS_RECIPE = `:root {
19
- ${SEARCH_CSS_VARS.cardRadius}: 0.75rem;
20
- ${SEARCH_CSS_VARS.cardGap}: 1.5rem;
21
- ${SEARCH_CSS_VARS.priceSize}: 1.125rem;
22
- ${SEARCH_CSS_VARS.mediaRatio}: 4 / 3;
23
- ${SEARCH_CSS_VARS.controlHeight}: 2.75rem;
24
- ${SEARCH_CSS_VARS.iconSize}: 1.25rem;
25
- ${SEARCH_CSS_VARS.skeleton}: var(--muted, #e7e5e4);
26
- }
27
- `;
28
-
29
6
  export function formatListingPrice(
30
7
  amount: number | null | undefined,
31
8
  locale = "pt-BR",
@@ -1,18 +1,8 @@
1
1
  "use client";
2
2
 
3
- export { ListingCard } from "./listing-card";
4
- export { ListingDetailFields } from "./listing-detail-fields";
5
- export type {
6
- ListingDetailFieldsClassNames,
7
- ListingDetailFieldsProps,
8
- } from "./listing-detail-fields";
9
- export { SearchChromeStyles } from "./styles";
10
- export { ResultsSkeleton } from "./search-chrome";
11
3
  export { usePublicSearch } from "./use-public-search";
12
4
  export type {
13
- ListingCardClassNames,
14
- ListingCardProps,
15
- ListingCardSlots,
5
+ PublicSearchSnapshot,
16
6
  PublicSearchState,
17
7
  SiteIdInput,
18
8
  UsePublicSearchOptions,
@@ -0,0 +1,165 @@
1
+ import {
2
+ canonicalizeSearchHref,
3
+ readPublicSearch,
4
+ type LocationNameTables,
5
+ } from "../search-engine";
6
+ import type { Listing, SearchUi, SearchUiDictionary } from "../types";
7
+ import type { PublicSearchSnapshot } from "./types";
8
+
9
+ type SeededPublicSearchState = {
10
+ schema: SearchUi | null;
11
+ listings: Listing[];
12
+ page: number;
13
+ total: number;
14
+ totalPages: number;
15
+ locationNames: LocationNameTables | null;
16
+ catalogId: string | null;
17
+ loading: boolean;
18
+ };
19
+
20
+ function hrefParts(href: string): { pathname: string; search: string } {
21
+ const q = href.indexOf("?");
22
+ if (q < 0) return { pathname: href, search: "" };
23
+ return { pathname: href.slice(0, q), search: href.slice(q + 1) };
24
+ }
25
+
26
+ function searchHrefKey(pathname: string, search: string): string {
27
+ const qs = search.replace(/^\?/, "");
28
+ return qs ? `${pathname}?${qs}` : pathname;
29
+ }
30
+
31
+ /**
32
+ * True when both keys encode the same logical search (same pathFilters +
33
+ * applied), including when one is a non-canonical request URL and the other is
34
+ * its `canonicalizeSearchHref` rewrite.
35
+ */
36
+ export function searchKeysRepresentSameQuery(
37
+ a: string | null,
38
+ b: string,
39
+ dictionary?: SearchUiDictionary
40
+ ): boolean {
41
+ if (a == null) return false;
42
+ if (a === b) return true;
43
+ const left = hrefParts(a);
44
+ const right = hrefParts(b);
45
+ const leftCanon =
46
+ canonicalizeSearchHref(left.pathname, left.search, dictionary) ??
47
+ searchHrefKey(left.pathname, left.search);
48
+ const rightCanon =
49
+ canonicalizeSearchHref(right.pathname, right.search, dictionary) ??
50
+ searchHrefKey(right.pathname, right.search);
51
+ return leftCanon === rightCanon;
52
+ }
53
+
54
+ /**
55
+ * Schema or rows — `total: 0` alone is not enough to specialize the heading.
56
+ * Listings without an explicit `total` still count as trusted once seeded with
57
+ * a non-zero derived count (see {@link resolveSeedTotal}).
58
+ */
59
+ export function hasTrustedSearchSnapshot(
60
+ initial?: PublicSearchSnapshot | null
61
+ ): boolean {
62
+ return Boolean(initial?.schema || initial?.listings?.length);
63
+ }
64
+
65
+ /**
66
+ * Heading count for first paint. Never default a non-empty listings seed to `0`
67
+ * — that flashes cards beside "0 imóveis" until the client refetch fills total.
68
+ */
69
+ export function resolveSeedTotal(
70
+ initial?: PublicSearchSnapshot | null
71
+ ): number {
72
+ if (typeof initial?.total === "number") return initial.total;
73
+ return initial?.listings?.length ?? 0;
74
+ }
75
+
76
+ /**
77
+ * Prefer a freshly fetched location table. Never replace a painted SSR table
78
+ * with `null` when the locations request fails or is skipped.
79
+ */
80
+ export function preferFetchedLocationNames(
81
+ previous: LocationNameTables | null,
82
+ fetched: LocationNameTables | null
83
+ ): LocationNameTables | null {
84
+ return fetched ?? previous;
85
+ }
86
+
87
+ /**
88
+ * Failed `getSearchUi` must not wipe a trusted SSR schema/toolbar. Only clear
89
+ * when we were already in a client-only loading path.
90
+ */
91
+ export function shouldClearPaintedSearchOnSchemaFailure(
92
+ keepSnapshot: boolean
93
+ ): boolean {
94
+ return !keepSnapshot;
95
+ }
96
+
97
+ /**
98
+ * Painted ownership advances only after listings successfully load for a URL.
99
+ * `canonicalizeSearchHref` must not reassign the ownership key — logical
100
+ * equivalence for rewrites is handled by {@link searchKeysRepresentSameQuery}.
101
+ * Advancing early makes a later leftover-order navigation look already-painted,
102
+ * so prior cards survive a failed `queryListings`.
103
+ */
104
+ export function shouldAdvancePaintedSearchKeyOnCanonicalize(): boolean {
105
+ return false;
106
+ }
107
+
108
+ /**
109
+ * Flip `loading` only when the visitor leaves the painted logical search.
110
+ * A canonicalize rewrite of the same query must keep the SSR heading/cards
111
+ * mounted (`if (search.loading) return null` consumers).
112
+ */
113
+ export function shouldSetLoadingOnSearchKeyChange(options: {
114
+ paintedSearchKey: string | null;
115
+ searchKey: string;
116
+ dictionary?: SearchUiDictionary;
117
+ }): boolean {
118
+ return !searchKeysRepresentSameQuery(
119
+ options.paintedSearchKey,
120
+ options.searchKey,
121
+ options.dictionary
122
+ );
123
+ }
124
+
125
+ /**
126
+ * Failed `queryListings` must not replace painted cards/count while we are
127
+ * still on the logical search the snapshot (or last successful fetch) owns —
128
+ * including after `canonicalizeSearchHref` rewrites the string form. A
129
+ * different logical search may clear — the visitor navigated away.
130
+ */
131
+ export function shouldPreservePaintedListingsOnRefetchFailure(options: {
132
+ paintedSearchKey: string | null;
133
+ searchKey: string;
134
+ dictionary?: SearchUiDictionary;
135
+ }): boolean {
136
+ return searchKeysRepresentSameQuery(
137
+ options.paintedSearchKey,
138
+ options.searchKey,
139
+ options.dictionary
140
+ );
141
+ }
142
+
143
+ /** Query text already known from the URL, so the field is filled in the SSR HTML. */
144
+ export function initialQueryDraft(
145
+ pathname: string,
146
+ search: string,
147
+ dictionary?: SearchUiDictionary
148
+ ): string {
149
+ return readPublicSearch(pathname, search, dictionary).applied.query || "";
150
+ }
151
+
152
+ export function seedPublicSearchState(
153
+ initial?: PublicSearchSnapshot | null
154
+ ): SeededPublicSearchState {
155
+ return {
156
+ schema: initial?.schema ?? null,
157
+ listings: initial?.listings ?? [],
158
+ page: initial?.page ?? 1,
159
+ total: resolveSeedTotal(initial),
160
+ totalPages: initial?.totalPages ?? 1,
161
+ locationNames: initial?.locationNames ?? null,
162
+ catalogId: initial?.catalogId ?? null,
163
+ loading: !hasTrustedSearchSnapshot(initial),
164
+ };
165
+ }
@@ -0,0 +1,38 @@
1
+ import { applyPathFilter, clearStagedPathFilters } from "../search-engine";
2
+ import type { SearchPathFilters } from "../types";
3
+
4
+ /**
5
+ * Mutable mirror of staged path filters.
6
+ *
7
+ * React `setState` only schedules an update, so `stageFilter` then
8
+ * `applyStaged` in the same click would otherwise navigate the previous
9
+ * closed-over `staged` value and drop the write (e.g. Área drafts).
10
+ * Every staged write path updates this mirror synchronously; `applyStaged`
11
+ * reads it.
12
+ */
13
+ export class StagedFiltersMirror {
14
+ private current: SearchPathFilters;
15
+
16
+ constructor(initial: SearchPathFilters = {}) {
17
+ this.current = initial;
18
+ }
19
+
20
+ get value(): SearchPathFilters {
21
+ return this.current;
22
+ }
23
+
24
+ replace(next: SearchPathFilters): SearchPathFilters {
25
+ this.current = next;
26
+ return this.current;
27
+ }
28
+
29
+ stage(filterId: string, value: unknown): SearchPathFilters {
30
+ this.current = applyPathFilter(this.current, filterId, value);
31
+ return this.current;
32
+ }
33
+
34
+ clear(keepFilterIds: readonly string[] = []): SearchPathFilters {
35
+ this.current = clearStagedPathFilters(this.current, keepFilterIds);
36
+ return this.current;
37
+ }
38
+ }
@@ -1,49 +1,36 @@
1
- import type { CSSProperties, ReactNode } from "react";
2
-
3
1
  import type {
4
2
  AppliedSearchQuery,
5
3
  Listing,
6
4
  SearchPathFilters,
7
5
  SearchUi,
8
6
  } from "../types";
9
- import type { ListingCardModel } from "../listing-card-model";
10
7
  import type { LocationNameTables } from "../search-engine";
11
8
 
12
- export type ListingCardClassNames = {
13
- root?: string;
14
- media?: string;
15
- badge?: string;
16
- body?: string;
17
- price?: string;
18
- title?: string;
19
- location?: string;
20
- features?: string;
21
- cta?: string;
22
- };
23
-
24
- export type ListingCardSlots = {
25
- media?: ReactNode;
26
- badge?: ReactNode;
27
- cta?: ReactNode;
28
- };
29
-
30
- export type ListingCardProps = {
31
- listing: Listing | ListingCardModel;
32
- href?: string;
33
- className?: string;
34
- classNames?: ListingCardClassNames;
35
- slots?: ListingCardSlots;
36
- style?: CSSProperties;
37
- };
38
-
39
9
  export type SiteIdInput =
40
10
  | string
41
11
  | Promise<string>
42
12
  | (() => string | Promise<string>);
43
13
 
14
+ export type PublicSearchSnapshot = {
15
+ schema?: SearchUi | null;
16
+ listings?: Listing[];
17
+ page?: number;
18
+ total?: number;
19
+ totalPages?: number;
20
+ locationNames?: LocationNameTables | null;
21
+ catalogId?: string | null;
22
+ };
23
+
44
24
  export type UsePublicSearchOptions = {
45
25
  siteId: SiteIdInput;
46
26
  baseUrl?: string;
27
+ /**
28
+ * Query string without `?`, from the server page's `searchParams`.
29
+ * The hook must not call Next's search-params hook: that suspends the
30
+ * tree, and Next leaves the resolved HTML in a hidden node until JS runs.
31
+ */
32
+ search?: string;
33
+ initial?: PublicSearchSnapshot;
47
34
  };
48
35
 
49
36
  export type PublicSearchState = {
@@ -1,7 +1,7 @@
1
1
  "use client";
2
2
 
3
3
  import { useCallback, useEffect, useMemo, useRef, useState } from "react";
4
- import { usePathname, useRouter, useSearchParams } from "next/navigation";
4
+ import { usePathname, useRouter } from "next/navigation";
5
5
 
6
6
  import { getSearchUi, queryListings } from "../fetchers";
7
7
  import { coerceSiteId, normalizeBaseUrl } from "../internal/url";
@@ -9,7 +9,6 @@ import {
9
9
  applyPathFilter,
10
10
  buildQueryListingsParams,
11
11
  canonicalizeSearchHref,
12
- clearStagedPathFilters,
13
12
  hrefForAppliedChange,
14
13
  hrefForPathFilters,
15
14
  readPublicSearch,
@@ -21,6 +20,17 @@ import type {
21
20
  SiteIdInput,
22
21
  UsePublicSearchOptions,
23
22
  } from "./types";
23
+ import {
24
+ hasTrustedSearchSnapshot,
25
+ initialQueryDraft,
26
+ preferFetchedLocationNames,
27
+ seedPublicSearchState,
28
+ shouldAdvancePaintedSearchKeyOnCanonicalize,
29
+ shouldClearPaintedSearchOnSchemaFailure,
30
+ shouldPreservePaintedListingsOnRefetchFailure,
31
+ shouldSetLoadingOnSearchKeyChange,
32
+ } from "./public-search-snapshot";
33
+ import { StagedFiltersMirror } from "./staged-filters-mirror";
24
34
 
25
35
  async function resolveSiteIdInput(siteId: SiteIdInput): Promise<string> {
26
36
  const value = typeof siteId === "function" ? siteId() : siteId;
@@ -34,29 +44,42 @@ function currentHref(pathname: string, search: string): string {
34
44
  export function usePublicSearch(
35
45
  options: UsePublicSearchOptions
36
46
  ): PublicSearchState {
37
- const { siteId, baseUrl } = options;
47
+ const { siteId, baseUrl, initial, search: searchFromServer = "" } = options;
38
48
  const router = useRouter();
39
49
  const pathname = usePathname() || "/imoveis";
40
- const searchParams = useSearchParams();
41
- const search = searchParams.toString();
50
+ const search = searchFromServer;
51
+ const searchKey = search ? `${pathname}?${search}` : pathname;
52
+ const [seed] = useState(() => seedPublicSearchState(initial));
53
+ const keepSnapshotRef = useRef(hasTrustedSearchSnapshot(initial));
54
+ const lastSearchKeyRef = useRef(keepSnapshotRef.current ? searchKey : null);
42
55
 
43
56
  const siteIdRef = useRef(siteId);
44
57
  siteIdRef.current = siteId;
45
58
  const siteIdToken = typeof siteId === "string" ? siteId : null;
46
59
 
47
- const [catalogId, setCatalogId] = useState<string | null>(null);
48
- const [schema, setSchema] = useState<SearchUi | null>(null);
49
- const [listings, setListings] = useState<PublicSearchState["listings"]>([]);
50
- const [page, setPage] = useState(1);
51
- const [total, setTotal] = useState(0);
52
- const [totalPages, setTotalPages] = useState(1);
53
- const [loading, setLoading] = useState(true);
54
- const [qDraft, setQDraft] = useState("");
55
- const [staged, setStaged] = useState<SearchPathFilters>({});
60
+ const [catalogId, setCatalogId] = useState<string | null>(seed.catalogId);
61
+ const [schema, setSchema] = useState<SearchUi | null>(seed.schema);
62
+ const [listings, setListings] = useState<PublicSearchState["listings"]>(
63
+ seed.listings
64
+ );
65
+ const [page, setPage] = useState(seed.page);
66
+ const [total, setTotal] = useState(seed.total);
67
+ const [totalPages, setTotalPages] = useState(seed.totalPages);
68
+ const [loading, setLoading] = useState(seed.loading);
69
+ const [qDraft, setQDraft] = useState(() =>
70
+ initialQueryDraft(pathname, search, initial?.schema?.dictionary)
71
+ );
72
+ const stagedMirrorRef = useRef(new StagedFiltersMirror());
73
+ const [staged, setStagedState] = useState<SearchPathFilters>({});
56
74
  const [locationNames, setLocationNames] = useState<LocationNameTables | null>(
57
- null
75
+ seed.locationNames
58
76
  );
59
77
 
78
+ const replaceStaged = useCallback((next: SearchPathFilters) => {
79
+ stagedMirrorRef.current.replace(next);
80
+ setStagedState(next);
81
+ }, []);
82
+
60
83
  const parsed = useMemo(
61
84
  () => readPublicSearch(pathname, search, schema?.dictionary),
62
85
  [pathname, search, schema?.dictionary]
@@ -67,14 +90,14 @@ export function usePublicSearch(
67
90
  }, [parsed.applied.query]);
68
91
 
69
92
  const resetStagedFromUrl = useCallback(() => {
70
- setStaged({ ...parsed.pathFilters });
71
- }, [parsed.pathFilters]);
93
+ replaceStaged({ ...parsed.pathFilters });
94
+ }, [parsed.pathFilters, replaceStaged]);
72
95
 
73
96
  useEffect(() => {
74
- setStaged({ ...parsed.pathFilters });
75
- }, [parsed.pathFilters]);
97
+ replaceStaged({ ...parsed.pathFilters });
98
+ }, [parsed.pathFilters, replaceStaged]);
76
99
 
77
- const locationsRef = useRef<LocationNameTables | null>(null);
100
+ const locationsRef = useRef<LocationNameTables | null>(seed.locationNames);
78
101
 
79
102
  useEffect(() => {
80
103
  if (!schema) return;
@@ -83,15 +106,24 @@ export function usePublicSearch(
83
106
  search,
84
107
  schema.dictionary
85
108
  );
86
- if (canonical) router.replace(canonical);
109
+ if (!canonical) return;
110
+ // Never reassign painted ownership here — logical equivalence for the
111
+ // rewrite is handled by searchKeysRepresentSameQuery. Advancing early
112
+ // makes a later leftover-order navigation look already-painted.
113
+ if (shouldAdvancePaintedSearchKeyOnCanonicalize()) {
114
+ lastSearchKeyRef.current = canonical;
115
+ }
116
+ router.replace(canonical);
87
117
  }, [pathname, search, schema, router]);
88
118
 
89
119
  useEffect(() => {
90
120
  let active = true;
91
- setCatalogId(null);
92
- setSchema(null);
93
- setListings([]);
94
- setLoading(true);
121
+ if (!keepSnapshotRef.current) {
122
+ setCatalogId(null);
123
+ setSchema(null);
124
+ setListings([]);
125
+ setLoading(true);
126
+ }
95
127
  resolveSiteIdInput(siteIdRef.current)
96
128
  .then((id) => {
97
129
  if (active) setCatalogId(id);
@@ -108,11 +140,13 @@ export function usePublicSearch(
108
140
  if (!catalogId) return;
109
141
  const id = catalogId;
110
142
  let active = true;
111
- locationsRef.current = null;
112
- setLocationNames(null);
113
- setSchema(null);
114
- setListings([]);
115
- setLoading(true);
143
+ if (!keepSnapshotRef.current) {
144
+ locationsRef.current = null;
145
+ setLocationNames(null);
146
+ setSchema(null);
147
+ setListings([]);
148
+ setLoading(true);
149
+ }
116
150
  async function loadSchema() {
117
151
  try {
118
152
  const nextSchema = await getSearchUi({ siteId: id, baseUrl });
@@ -131,14 +165,25 @@ export function usePublicSearch(
131
165
  }
132
166
  }
133
167
  if (!active) return;
134
- locationsRef.current = locations;
135
- setLocationNames(locations);
168
+ const nextLocations = preferFetchedLocationNames(
169
+ locationsRef.current,
170
+ locations
171
+ );
172
+ locationsRef.current = nextLocations;
173
+ setLocationNames(nextLocations);
136
174
  setSchema(nextSchema);
175
+ keepSnapshotRef.current = false;
137
176
  } catch {
138
177
  if (active) {
139
- locationsRef.current = null;
140
- setLocationNames(null);
141
- setSchema(null);
178
+ // Trusted SSR paint survives a failed getSearchUi; client-only paths clear.
179
+ if (
180
+ shouldClearPaintedSearchOnSchemaFailure(keepSnapshotRef.current)
181
+ ) {
182
+ keepSnapshotRef.current = false;
183
+ locationsRef.current = null;
184
+ setLocationNames(null);
185
+ setSchema(null);
186
+ }
142
187
  setLoading(false);
143
188
  }
144
189
  }
@@ -155,7 +200,15 @@ export function usePublicSearch(
155
200
  const id = catalogId;
156
201
  let active = true;
157
202
  async function loadListings() {
158
- setLoading(true);
203
+ if (
204
+ shouldSetLoadingOnSearchKeyChange({
205
+ paintedSearchKey: lastSearchKeyRef.current,
206
+ searchKey,
207
+ dictionary: currentSchema.dictionary,
208
+ })
209
+ ) {
210
+ setLoading(true);
211
+ }
159
212
  try {
160
213
  const { pathFilters, applied } = readPublicSearch(
161
214
  pathname,
@@ -177,15 +230,27 @@ export function usePublicSearch(
177
230
  setPage(response.page || 1);
178
231
  setTotal(response.total || 0);
179
232
  setTotalPages(response.totalPages || 1);
233
+ lastSearchKeyRef.current = searchKey;
234
+ keepSnapshotRef.current = false;
180
235
  } catch {
181
- if (active) {
236
+ if (
237
+ active &&
238
+ !shouldPreservePaintedListingsOnRefetchFailure({
239
+ paintedSearchKey: lastSearchKeyRef.current,
240
+ searchKey,
241
+ dictionary: currentSchema.dictionary,
242
+ })
243
+ ) {
182
244
  setListings([]);
183
245
  setPage(1);
184
246
  setTotal(0);
185
247
  setTotalPages(1);
248
+ keepSnapshotRef.current = false;
186
249
  }
187
250
  } finally {
188
- if (active) setLoading(false);
251
+ if (active) {
252
+ setLoading(false);
253
+ }
189
254
  }
190
255
  }
191
256
  loadListings();
@@ -216,17 +281,31 @@ export function usePublicSearch(
216
281
  [go, pathname, search, schema, parsed.pathFilters]
217
282
  );
218
283
 
284
+ const setStaged = useCallback(
285
+ (next: SearchPathFilters) => {
286
+ replaceStaged(next);
287
+ },
288
+ [replaceStaged]
289
+ );
290
+
219
291
  const stageFilter = useCallback((filterId: string, value: unknown) => {
220
- setStaged((current) => applyPathFilter(current, filterId, value));
292
+ setStagedState(stagedMirrorRef.current.stage(filterId, value));
221
293
  }, []);
222
294
 
223
295
  const applyStaged = useCallback(() => {
224
296
  if (!schema) return;
225
- go(hrefForPathFilters(pathname, search, schema.dictionary, staged));
226
- }, [go, pathname, search, schema, staged]);
297
+ go(
298
+ hrefForPathFilters(
299
+ pathname,
300
+ search,
301
+ schema.dictionary,
302
+ stagedMirrorRef.current.value
303
+ )
304
+ );
305
+ }, [go, pathname, search, schema]);
227
306
 
228
307
  const clearStaged = useCallback(() => {
229
- setStaged((current) => clearStagedPathFilters(current));
308
+ setStagedState(stagedMirrorRef.current.clear());
230
309
  }, []);
231
310
 
232
311
  const submitQuery = useCallback(() => {
@@ -305,6 +305,9 @@ export function canonicalizeSearchHref(
305
305
  search: string,
306
306
  dictionary?: SearchUiDictionary
307
307
  ): string | null {
308
+ // A preview prefix is not a filter. Replacing it rewrites the URL forever.
309
+ if (pathname.includes("/api/v0-preview/")) return null;
310
+ if (isListingDetailPath(pathname)) return null;
308
311
  const { pathFilters, applied } = readPublicSearch(
309
312
  pathname,
310
313
  search,