@lockerverse/react 0.2.156 → 0.2.157

package/README.md

@@ -7,6 +7,17 @@ project, use its local README, `package.json` exports, and public `.d.ts` files.
 Online examples can describe a newer release. Do not import private `dist`
 modules or copy API details from a different SDK version.
 
+## Version-matched integration guides
+
+Read [shared integration rules](guides/integration.md) first, then the guide for
+[auctions](guides/auctions.md), [payment widgets](guides/payment-widgets.md),
+[Events](guides/events.md), or [signup](guides/signup.md). These are stable files
+inside the installed package: `node_modules/@lockerverse/react/guides/`.
+They ship with this release and are generated from the maintained documentation.
+Admin prompts supply public resource identity and a minimum SDK version; they
+do not duplicate these rules. Keep a newer matching stable SDK pair instead of
+downgrading it. Read the installed guides and public types before implementation.
+
 ## Usage guide
 
 - [Install](#install) and [payment quick start](#use)
@@ -693,63 +704,9 @@ plural options type is also exported from `auctions`.
 
 ## Public event listings
 
-Use the public Events entry to show publicly listed Events that are happening
-now, start in the future, or have ended. It does not load ticket or payment UI.
-
-```tsx
-import {
-  LockerversePublicEvents,
-  useLockerversePublicEvents,
-} from "@lockerverse/react/public-events";
-import "@lockerverse/react/public-events.css";
-
-function CommunityEvents() {
-  const events = useLockerversePublicEvents({ communitySlug: "auburn" });
-  return <LockerversePublicEvents events={events} title="Events" theme="light" />;
-}
-```
-
-The hook returns `client`, `events`, `loading`, `error`, and `refresh`. The
-component takes the full hook result so it can show loading, empty, and retry
-states. `title` sets the visible heading, `showHeading` can hide it, and
-`timeZone` controls date display. The default time zone is
-`America/New_York`. Use `style` with `LockerverseStyle` tokens or `className`
-to match the host site. Links open in a new tab when they use HTTP or HTTPS.
-Events can include an optional `imageUrl`. The list uses image cards when an
-image is present and a date tile when it is absent. The default view groups
-events into "Happening now" and "Upcoming". The "Past Events" view loads on
-demand and offers "Load more" for older events. Each card has a share action.
-Sharing uses the event link when one exists; otherwise it uses a link to the
-event card on the host page. For a one-list view, a card link can load up to
-five more pages to find its Event. The visitor can still use Load more.
-
-Pass one configuration object to the hook for a different list. The component
-reads that configuration from the hook result. With `showTabs: false`, it shows
-one full-width list; `includePast` selects whether that list includes ended
-Events. `from`, `to`, and `sort` set the server-side date range and order.
-Without `from` or `to`, a one-list view reads all publicly listed Event
-history. It includes past Events by default and sorts by descending start
-time, so newer Events appear first. With `includePast: false`, the default is
-ascending start time for current and future Events. Each page has 20 Events.
-
-```tsx
-const config = {
-  showTabs: false,
-  includePast: true,
-  from: "2026-09-01T00:00:00.000Z",
-  to: "2026-10-01T00:00:00.000Z",
-  sort: "startAtAsc",
-} as const;
-const events = useLockerversePublicEvents(
-  { communitySlug: "auburn" },
-  { config, initialPage }
-);
-return <LockerversePublicEvents events={events} />;
-```
-
-For server rendering, obtain `initialPage` with the SDK client's `search()`
-and the same date, scope, sort, and page size. Without this configuration,
-`initialEvents` from `list()` keeps the original Upcoming and Past views.
+Read the version-matched [Events integration guide](guides/events.md) for
+`useLockerversePublicEvents`, list configuration, server seeds, and public
+attendee lists. It is generated from the maintained Events documentation.
 
 ## Prefill checkout custom fields
 

package/guides/auctions.md

@@ -0,0 +1,547 @@
+# Lockerverse auctions guide
+
+Package: @lockerverse/react@0.2.157
+
+Generated from this release's maintained documentation. Do not edit this copy.
+
+Read [the shared integration guide](integration.md) first.
+
+## Auctions
+
+Use the [auction example](https://sdk.lockerverse.com/examples/auctions) to browse live data and view the complete source.
+
+## Shared Lockerverse interface
+
+The optional auction UI follows the public Lockerverse web app: image cards and status filters, a photo gallery with a full-screen viewer, item details, and a two-step bid or purchase checkout. It uses the community color by default. Override the shared theme variables with `style` when the host site needs different branding.
+
+The item layout responds to its container width, so the same component can fill a page or sit inside a narrow embed. The SDK supplies its own scoped CSS and does not require Next.js or Tailwind. Dates follow the public app's America/New_York display policy and honor each auction's time-display settings.
+
+For public item pages, pass `backHref` to `LockerverseAuctionItem` so its return controls are real links. Add `onBack` to connect ordinary clicks to the host router or item selection; modified clicks keep native browser behavior. `onBack` without `backHref` keeps the existing button controls. Pass `communityName` only when the host needs to override the API community name. Keep the catalog mounted but hidden while showing an item to preserve the selected auction and filter. The example demonstrates this pattern.
+
+Pass `returnToItemHref` to add a **Return to item** link after a completed bid or purchase. It opens the item URL as a fresh page visit. When `backHref` or `onBack` is also supplied, **View auction items** remains as the secondary action. The completed result uses `backHref` as a fresh page visit when it is set. The link does not reset or resume checkout in the mounted component. Hosts that restore purchase recovery must clear completed recovery before a new page visit.
+
+For internal adoption, import these same SDK components and stylesheet. Keep routing, page metadata, and the site header in the app. Change auction presentation in the SDK rather than copying its markup or styles into a second implementation. The host owns route URLs, metadata, and page chrome; the SDK owns the shared auction presentation.
+
+## Choose your UI
+
+- `@lockerverse/sdk/auctions`: framework-independent clients, validated data, pricing estimates, bids, purchases, and status lookup.
+- `@lockerverse/react/auctions`: `useLockerverseAuctions` and the optional `LockerverseAuctions` catalog. This entry does not import Stripe.
+- `@lockerverse/react/auction-data`: the React data hook only, with no UI, icons, or Stripe.
+- `@lockerverse/react/auction`: one loaded auction and its item cards, without the community auction list or checkout.
+- `@lockerverse/react/auction-item`: optional `LockerverseAuctionItem` detail and card checkout.
+- `@lockerverse/react/auction.css`: catalog and single-auction styles only.
+- `@lockerverse/react/auction-item.css`: item details, gallery, and checkout styles only.
+- `@lockerverse/react/auctions.css`: all auction styles, retained for existing integrations.
+
+```tsx
+import { LockerverseAuctions, useLockerverseAuctions } from "@lockerverse/react/auctions";
+import { LockerverseAuctionItem } from "@lockerverse/react/auction-item";
+import "@lockerverse/react/auctions.css";
+
+const auctions = useLockerverseAuctions({ communitySlug: "auburn" });
+
+// In your component, keep the selected auction and item in application state.
+<LockerverseAuctions
+  auctions={auctions}
+  onSelectItem={(auction, item) => setSelection({ auction, itemId: item.id })}
+  theme="light"
+/>;
+
+// Render only when selection exists. Remount when its resource identity changes.
+<LockerverseAuctionItem
+  key={`${selection.auction.id}:${selection.itemId}`}
+  auction={selection.auction}
+  client={auctions.client}
+  itemId={selection.itemId}
+  onBidSubmitted={handleBidSubmitted}
+  onPurchaseComplete={handlePurchaseComplete}
+  theme="light"
+/>;
+```
+
+Install the same optional Stripe peers as the payment component:
+
+```sh
+npm install @lockerverse/react react react-dom @stripe/react-stripe-js @stripe/stripe-js
+```
+
+Production is the default. For development, explicitly pass `environment: "development"` and the development `apiBaseUrl`.
+
+## Serve auction images through your site
+
+Set `mediaBaseUrl` to an absolute HTTPS URL when your host has a fixed server rewrite to `https://media.lockerverse.com`. For example, configure `/lockerverse-media/:path*` on your host to forward to `https://media.lockerverse.com/:path*`, then pass:
+
+```tsx
+const auctions = useLockerverseAuctions({
+  communitySlug: "wsu",
+  mediaBaseUrl: "https://your-site.example/lockerverse-media",
+});
+```
+
+This option also works with `useLockerverseAuction` and `createLockerverseAuctionClient`. It changes Lockerverse auction, community, and item image URLs on every list, load, and refresh. Other image hosts keep their original URLs. Without this option, all image URLs stay unchanged. The host must configure the rewrite before using the option; the SDK does not create it.
+
+## A page for one auction
+
+Use `LockerverseAuction` when the host already knows which auction to show. It goes straight to that auction's items, without an intermediate auction-list card. Use `useLockerverseAuction(options, auctionSlug)` from `@lockerverse/react/auction-data` for a dedicated page. It calls `client.load(auctionSlug)` directly and never requests the community auction list. The host handles initial loading, errors, and missing auctions before rendering this component.
+
+```tsx
+import { LockerverseAuction } from "@lockerverse/react/auction";
+import "@lockerverse/react/auction.css";
+
+// auction is a validated, loaded Lockerverse auction.
+<LockerverseAuction
+  auction={auction}
+  onSelectItem={(auction, item) => openItem(auction, item.id)}
+  showFilters={false}
+  showHeader={false}
+  showLineup={false}
+  theme="light"
+/>;
+```
+
+`showFilters` and `showHeader` default to `true`. `showLineup` defaults to `false`, so the static introduction and separate count are hidden. These options also work on `LockerverseAuctions`. The auction header omits the auction date range; item dates remain on item cards. Hiding filters shows all items and clears the previous filter. Changing the auction resets its filter. Hiding headings never removes the section's accessible name. `onBack` is optional, so a dedicated auction page does not need a link to all auctions.
+
+### Direct loading and refresh
+
+```tsx
+import { useLockerverseAuction } from "@lockerverse/react/auction-data";
+
+const resource = useLockerverseAuction(
+  { communitySlug: "lckrvrs-internal" },
+  "auction"
+);
+```
+
+The result contains `client`, `auction`, `loading`, `error`, and `refresh()`. Without an initial seed, initial loading has no auction. Refresh keeps the last successful snapshot, including when the request fails. Show a refresh error beside the existing UI. Show a retry button only when loading fails; do not add a manual refresh button to the normal auction view. Community, auction slug, environment, API base URL, and media base URL are immutable: use a new React key when the resource identity changes.
+
+Both data hooks refresh by default after the document changes from hidden to visible. They do not poll, refresh on mount twice, or reload the page. Disable this policy when the host supplies its own refresh:
+
+```tsx
+useLockerverseAuction(options, "auction", { refreshOnReturn: false });
+useLockerverseAuctions(options, { refreshOnReturn: false });
+```
+
+The React-only `AuctionRefreshOptions` type is exported from `auction-data` and `auctions`. Both hooks retain their last successful data during a refresh or failure. Return events during an in-flight read coalesce into at most one later read while visible. Manual refresh still works; older responses cannot replace newer data. Return refresh updates display data, never a bid or payment result. Checkout still reviews server pricing before submission. Use the local [State Lab](https://sdk.lockerverse.com/examples/state-lab) response controls to stage prices, stock, missing items, errors, or independently paused reads. No real bid or charge occurs there.
+
+Try the [complete single-auction example](https://sdk.lockerverse.com/examples/auctions?community=lckrvrs-internal&auction=auction). Its copyable source is self-contained. Community, auction, and item links use native document navigation with `community`, `auction`, and `item` query parameters; existing host parameters are preserved. Direct item links support reload, Back/Forward, new tabs, item-not-found handling, and return to the loaded auction. The community/auction form clears the old item selection. It reads the link before mounting a data hook, so the first request is the auction detail request. An empty auction slug selects the separate all-auctions example.
+
+`LockerverseAuctionItem` accepts fresh same-ID data while selecting an item. Once payment is open, it preserves the transaction snapshot until the user returns to selection. Checkout's own server review takes precedence over an older host snapshot. Keep a selected item mounted during refresh, errors, and item disappearance while a submission or recovery is locked; a loading or not-found branch must never discard it.
+
+For Lovable, start with the built-in styled UI and supported public configuration. Do not automatically switch to headless based on inferred design needs. Use the headless SDK only when a custom implementation is explicitly requested.
+
+### Initial server data
+
+Pass a complete SDK snapshot to the React hook when a server route has already
+loaded it. The plural hook accepts `initialAuctions` in its second argument;
+the singular hook accepts `initialAuction` in its third argument.
+
+```tsx
+import type { LockerverseAuction } from "@lockerverse/sdk/auctions";
+import {
+  useLockerverseAuction,
+  useLockerverseAuctions,
+} from "@lockerverse/react/auction-data";
+
+function useServerAuctions(
+  communitySlug: string,
+  initialAuctions: LockerverseAuction[]
+) {
+  return useLockerverseAuctions(
+    { communitySlug },
+    { initialAuctions }
+  );
+}
+
+function useServerAuction(
+  communitySlug: string,
+  auctionSlug: string,
+  initialAuction: LockerverseAuction
+) {
+  return useLockerverseAuction(
+    { communitySlug },
+    auctionSlug,
+    { initialAuction }
+  );
+}
+```
+
+The seed is read once on mount. An empty `initialAuctions: []` is valid data.
+The seed must belong to the requested community; a singular seed with a
+different auction slug throws a `TypeError`. Later seed prop changes do not
+replace live data. The hook does not mutate the supplied snapshot.
+
+The first browser request still runs, and `loading` remains true while it is
+pending. Render available data during loading; show an initial skeleton only
+when data is null. A failed refresh retains the seed or last successful data.
+Keep checkout mounted during refresh and errors. `refreshOnReturn` remains
+available in the same argument. The named `UseLockerverseAuctionOptions` and
+`UseLockerverseAuctionsOptions` types are exported from `auction-data`; the
+plural options type is also exported from `auctions`.
+
+## Keep the default cards, change selected parts
+
+The built-in card supports `showDescription`, `showMetrics`, and `showTiming` (all default to `true`), plus `className` and `style`. Use `renderItem` to change these without copying card markup:
+
+```tsx
+import {
+  LockerverseAuction,
+  LockerverseAuctionItemCard,
+} from "@lockerverse/react/auction";
+
+<LockerverseAuction
+  auction={auction}
+  onSelectItem={openItem}
+  renderItem={(context) => (
+    <LockerverseAuctionItemCard
+      {...context}
+      showDescription={false}
+      showTiming={false}
+    />
+  )}
+/>;
+```
+
+The card also works by itself in a host-owned list:
+
+```tsx
+<LockerverseAuctionItemCard
+  auction={auction}
+  item={item}
+  onSelect={() => openItem(auction, item.id)}
+  theme="light"
+  showDescription={false}
+/>;
+```
+
+It supplies a lightweight theme scope. Its `className` and `style` apply to that outer scope. Import `@lockerverse/react/auction.css` once for the host list.
+
+Or return your own card. The renderer receives `auction`, `item`, the effective `status`, `onSelect`, `theme`, and inherited theme variables in `style`. Spread this context onto the default card to retain branding. It renders inside an SDK-owned list item; do not return another `<li>`. Keep a keyboard-accessible button or link connected to the supplied action. Render hooks inside a custom React component, not directly inside the render callback. Returning `null` intentionally renders no card.
+
+A custom card can still open `LockerverseAuctionItem` for the built-in item, closed-state, bid, checkout, and recovery flows. Presentation options do not bypass availability or payment rules. Keep uncertainty and recovery information visible. Fully custom flows can continue to use the unchanged headless SDK.
+
+## Host styling and layout
+
+Auction components have a transparent outer background and no outer padding or
+maximum width. Put page padding and width limits on your host container. Card,
+form, and receipt surfaces still use the shared theme variables.
+
+Font family, font size, and date styling are configurable defaults. They are not
+fixed branding rules. Pass variables through `style` or set them on the component
+with a host stylesheet loaded after the SDK stylesheet:
+
+```tsx
+<LockerverseAuction
+  auction={auction}
+  getItemHref={(auction, item) => `/auctions/${auction.path}/items/${item.path}`}
+  style={{
+    "--lockerverse-font-family": "var(--site-font, system-ui)",
+    "--lockerverse-font-size": "16px",
+    "--lockerverse-auction-title-size": "32px",
+    "--lockerverse-auction-card-title-size": "22px",
+    "--lockerverse-auction-date-size": "13px",
+    "--lockerverse-auction-date-transform": "none",
+    "--lockerverse-auction-date-letter-spacing": "normal",
+  }}
+/>
+```
+
+The item title uses `--lockerverse-auction-item-title-size`; the result title uses
+`--lockerverse-auction-result-title-size`. The receipt item title uses
+`--lockerverse-auction-result-receipt-title-size`, with the general subheading size as a fallback.
+General headings use
+`--lockerverse-auction-heading-size` and `--lockerverse-auction-subheading-size`.
+Existing color, border, radius, and font-family variables remain available.
+
+Catalog photos are static by default. Set `autoRotateImages` on the catalog or
+card to opt into rotation. Reduced-motion, focus, and hover behavior still apply.
+Descriptions keep a short card preview; use `showDescription={false}` to hide it.
+The full description remains available on the item page.
+
+## Host routes and filters
+
+Use `getItemHref` for real item links. It preserves open-in-new-tab and ordinary
+browser navigation. A host router can also handle unmodified clicks with
+`onSelectItem`; modified clicks still follow the link.
+
+Use `filter`, `onFilterChange`, and `getFilterHref` to keep the selected filter in
+the URL. Omitting these props keeps the internal filter behavior. The exported
+`LockerverseAuctionItemFilter` type is `all | active | draft | finished`.
+
+For the community auction list, `getAuctionHref` supplies auction links and
+`onSelectAuction` can connect an application router. Hiding filters still shows
+all items. The host must keep controlled values in sync with its URL.
+
+## Public pages and search engines
+
+For a public auction website, use `getItemHref` on the catalog and `backHref` on
+item pages. Each URL must open the correct content on a direct visit, without
+prior browser state. Use `getAuctionHref` when the site has a community auction
+list. `LockerverseAuction` also accepts `backHref` for its **Auctions** control.
+`LockerverseAuctions` passes `backHref` and `itemOrder` to its selected catalog.
+Checkout controls that return to an earlier payment step stay buttons. Return
+links in the item view stay hidden while checkout has an interaction lock.
+
+Set `itemOrder="availability"` to show live items, then upcoming items, then
+closed items. This uses the effective auction and item status, including elapsed
+closing dates. Configured position and creation time still set the order within
+each group. The default, `itemOrder="position"`, keeps the configured item order.
+
+Fetch public data on the server with `createLockerverseAuctionClient().load()`.
+Pass the complete result as `initialAuction` to `useLockerverseAuction`. Render
+the available auction during refresh; do not replace server content with a
+loading screen. The following Next.js example serves a catalog at `/auctions`:
+
+```tsx
+// app/auctions/page.tsx — server component
+import { createLockerverseAuctionClient } from "@lockerverse/sdk/auctions";
+import { AuctionCatalog } from "./AuctionCatalog";
+
+export const dynamic = "force-dynamic";
+
+export default async function AuctionsPage() {
+  const initialAuction = await createLockerverseAuctionClient({
+    communitySlug: "your-community",
+  }).load("your-auction");
+
+  return <AuctionCatalog initialAuction={initialAuction} />;
+}
+```
+
+```tsx
+// app/auctions/AuctionCatalog.tsx — rendered on the server, then hydrated
+"use client";
+
+import type { LockerverseAuction as Auction } from "@lockerverse/sdk/auctions";
+import { LockerverseAuction } from "@lockerverse/react/auction";
+import { useLockerverseAuction } from "@lockerverse/react/auction-data";
+import "@lockerverse/react/auction.css";
+
+export function AuctionCatalog({ initialAuction }: { initialAuction: Auction }) {
+  const { auction, error } = useLockerverseAuction(
+    { communitySlug: "your-community" },
+    initialAuction.slug,
+    { initialAuction }
+  );
+
+  return (
+    <>
+      <h1>Auctions and experiences</h1>
+      {error ? <p role="status">Auction updates are temporarily unavailable.</p> : null}
+      <LockerverseAuction
+        auction={auction ?? initialAuction}
+        getItemHref={(_, item) => `/auctions/items/${encodeURIComponent(item.slug)}`}
+        itemOrder="availability"
+        showHeader={false}
+      />
+    </>
+  );
+}
+```
+
+Create the matching item route with server data too. Resolve the item from the
+auction before its first render, then pass `backHref="/auctions"` and its own
+`returnToItemHref` to `LockerverseAuctionItem`. Keep the mounted item during
+refresh and payment, as described in **Initial server data**. Use a real 404
+response for unknown items. Do not include unlisted preview items in public
+catalogs or sitemaps.
+
+The host website owns document metadata and HTTP routes. For every public auction
+and item route, the host must provide a unique title and description, an absolute
+canonical URL, and server-rendered content. Publish `/sitemap.xml` with the public
+canonical URLs, reference it from `/robots.txt`, and submit it in Search Console.
+The SDK cannot select the host's domain, router, indexing policy, or page title.
+Use verified organization and breadcrumb data for structured data. Add product
+and offer data only when it matches the visible item and sale terms; a current
+bid is not a fixed purchase price.
+
+## Shared results
+
+The item component shows the shared result after a confirmed bid submission or
+paid purchase. Completion callbacks remain available for host routing and data
+refresh. The result is also available separately:
+
+```tsx
+import { LockerverseAuctionResult } from "@lockerverse/react/auction-result";
+import "@lockerverse/react/auction-result.css";
+```
+
+Use the purchase confirmation only after the server reports a paid purchase.
+Receipt amounts alone do not establish payment status. A submitted bid is not a
+winning bid or a payment. Keep unknown and pending transactions mounted until
+their result is resolved.
+
+## Icons and bundle boundaries
+
+Auction UI uses the same Lucide icon definitions as the original Lockerverse app. Each component uses static named imports. There is no dynamic icon-name registry, and text characters are not used as navigation icons.
+
+Import the smallest public entry you need. The core `@lockerverse/sdk/auctions` entry has no React, icons, or UI styles. The React data hook also has no UI imports. The single-auction view does not import the multi-auction browser or Stripe. Item details do not import the catalog; they include their gallery and checkout dependencies. CSS is opt-in through the matching stylesheet above.
+
+A prop such as `showFilters={false}` removes the controls at runtime; it is not a promise that a bundler removes all filter code. Use separate entries for bundle isolation, and use a custom card or the headless API for a substantially different interface.
+
+## Custom UI
+
+```ts
+import { createLockerverseAuctionClient } from "@lockerverse/sdk/auctions";
+
+const client = createLockerverseAuctionClient({ communitySlug: "auburn" });
+const auctions = await client.list();
+const auction = await client.load("auburn-auction");
+```
+
+The auction includes its items, bidding and quantity rules, fee policy, and payment configuration. Read prices and availability from this response. All amounts are integer USD cents. The server validates the final bid and purchase.
+
+The core methods `createBid` and `createPurchase` accept a Stripe confirmation token created on the returned payment account. Bid card collection uses Stripe setup mode and off-session use. Buy-now checkout uses payment mode. The ready-made component handles these steps for card payments, including billing and required shipping addresses.
+
+For custom card-only buy-now Elements, set `paymentMethodTypes: ["card"]` both on Elements and in the `createPurchase` submission. Omit the submission field for automatic payment methods. Include `params.return_url` when creating the confirmation token. The ready-made component handles this configuration.
+
+## Host navigation and submission locks
+
+Connect `onInteractionLockChange(locked)` to every host control that can remove or replace checkout: back links, community selection, router navigation, and reset buttons. `true` covers preparation, a sent operation, and unresolved bid or purchase recovery. The SDK sends the lock before starting submission and releases it when safe; its own back controls follow the same lock.
+
+```tsx
+<LockerverseAuctionItem
+  auction={auction}
+  client={client}
+  itemId={itemId}
+  onInteractionLockChange={setCheckoutLocked}
+  onBack={checkoutLocked ? undefined : closeItem}
+  onUncertain={(kind) => setMessage(`The ${kind} result is unknown. Keep this flow open.`)}
+/>
+```
+
+The host owns its router. Disabling the SDK back button alone cannot block an external route change. If checkout is unexpectedly removed after sending, the SDK still reports a known completion or uncertainty once for that operation. It does not start a new Stripe action after removal, and it never automatically retries a bid. Keep callback state above checkout. Full page reload, browser shutdown, or process termination cannot guarantee callback delivery.
+
+If the host combines the lock with recovery and uncertainty flags, update those flags synchronously in a ref before computing the combined lock. Completion can clear recovery and then release the lock in the same turn.
+
+### Simulated review
+
+The [State Lab](https://sdk.lockerverse.com/examples/state-lab) includes **Auction** previews for a live bid, an unknown bid result, and purchase recovery. It uses the actual SDK components with a local synthetic transport and Stripe adapter. No API or Stripe network calls are made. The response control pauses a request for inspection; the unexpected-removal control deliberately bypasses navigation only inside this labelled simulation. A preflight pause verifies that removal before sending creates no bid. Simulation reset discards synthetic state only.
+
+## Completion and recovery
+
+`onBidSubmitted` means the bid request was submitted. It does not mean the bidder won or a payment was made. If a bid result is unknown, keep the uncertainty visible and do not retry the bid automatically: the bid API has no deduplication key.
+
+`onPurchaseComplete` runs only when Lockerverse reports `paid`. Pending payments remain in checkout, with a status action that does not create another payment. The core equivalent is:
+
+```ts
+const purchase = await client.getPurchaseStatus(auctionSlug, itemId, clientRequestId);
+```
+
+A `null` result means no matching purchase is currently recorded. It does not prove an earlier request has stopped. Retry only the original purchase details with the same `clientRequestId`.
+
+Keep `onPurchaseRecoveryChange` records private. They contain customer data and a Stripe token, plus the original payment account, item, and amounts. A host can retain the record and pass it as `resumePurchase` when remounting the same item and environment. Remove `resumePurchase` when the callback returns `null`; remount before starting a new purchase after a resolved recovery. The SDK does not store these records in browser storage automatically.
+
+`getPurchaseReceipt` returns receipt amounts. Use `getPurchaseStatus` to establish whether payment succeeded.
+
+## Release order
+
+Deploy auction payment configuration and the purchase-status endpoint before publishing this SDK version. Older auction responses can still be browsed; the default checkout requires the new payment configuration.
+
+## Availability while a page stays open
+
+Cards, filters, counts and item controls update at the auction’s known start/end
+boundaries, using one shared timer and a check when the tab becomes visible.
+There is no network polling for these clock changes. Server draft and finished
+states remain authoritative. Time changes never discard an active checkout or
+purchase recovery. Buy-now cards say Preview item before opening, Buy now while
+available, and View item after closing.
+
+## Motion in embedded views
+
+Automatic card rotation and gallery autoplay pause when the component is outside
+the viewport, hidden by its host, or in a background tab. Existing user pause,
+reduced-motion, hover, focus and drag behavior still applies. Manual image
+navigation remains available. A hidden mounted gallery retains its selected image.
+
+The State Lab also includes loading, failed loading, upcoming, live, closed,
+sold-out and timed start/end examples. Switch among a single auction, standalone
+card and community browser, open item details, or hide the preview. Its labelled
+images are local simulation data; the preview sends no auction or Stripe requests.
+
+Auction descriptions render backend-provided rich HTML through React `dangerouslySetInnerHTML`. The SDK does not sanitize this HTML. Supply trusted or upstream-sanitized descriptions. Plain descriptions retain escaped text and line breaks.
+
+### Direct result review
+
+The [auction review page](https://sdk.lockerverse.com/examples/auction-review) can show submitted bids, paid purchases, and unconfirmed receipts without completing checkout. All outcomes are local sample data, rendered by the actual result component. Use Standard SDK to check the default theme or Website style to check the approved host decoration. The photo backdrop, glass badge, and receipt finish belong to the example wrapper, not the SDK defaults. Resize the browser to check mobile layouts.
+
+### External host navigation
+
+Use `getAuctionHref` and `getItemHref` for native links, or connect the same URLs to the host’s existing router. Give `LockerverseAuctionItem` a `returnToItemHref` so a completed result can open the original item again. Its `backHref` must point to the auction even after direct item entry. An optional `onBack` can handle ordinary clicks before checkout completes. Do not use history Back as the only return action.
+
+The [complete external example](https://sdk.lockerverse.com/examples/auctions) retains the mounted item through refresh, errors, and removal from fresh data. Errors and retry stay beside that item. Its pending-only link guard, unload warning, and cancelable Navigation API guard are best effort; forced navigation or browser shutdown can still discard in-memory recovery. The example uses production; use [local result review](https://sdk.lockerverse.com/examples/auction-review) and [State Lab](https://sdk.lockerverse.com/examples/state-lab) for safe completion checks.
+
+
+## Saved auction host integration
+
+Keep the existing framework, router, page structure, and surrounding design.
+Mount one integration for the configured auction. Load it directly with
+`useLockerverseAuction` or `client.load(auctionPath)`; never load the community
+list and filter it. Keep live item settings authoritative. Preserve draft,
+closed, sold-out, shipping, and service-fee behavior. Use the built-in styled
+catalog, gallery, checkout, and results. Use supported theme props and tokens;
+use headless only when explicitly requested. Do not add a second checkout,
+iframe, unrelated Stripe account, or external-site redirect.
+
+Use item slug/path, with stable item ID as fallback, for encoded host URLs.
+Never use item names or list positions. Keep the saved auction identity fixed;
+route parameters must not select another auction or community. The URL is the
+item-selection source. Support direct entry, reload, sharing, Back/Forward,
+and unknown-item handling. Preserve unrelated host query parameters. Supply
+`getItemHref`, `backHref`, and `returnToItemHref`, and connect ordinary clicks
+to the existing router as needed. Do not use history Back as the only return
+control or silently select the first item for an unknown URL.
+
+Keep checkout in a stable mounted route boundary. Pending state includes the
+SDK interaction lock, unresolved purchase recovery, and an uncertain bid.
+Connect it to existing router blockers for item links, site navigation, and
+Back/Forward. Use a pending-only `beforeunload` warning as a best effort, never
+as a promise of durable recovery. Keep normal navigation when not pending.
+Show refresh errors and retry beside the mounted item. Do not replace checkout
+with a loading/error/not-found branch or add a normal manual refresh button.
+Pass fresh same-auction data with the last valid snapshot as fallback.
+
+Keep auction recovery private and in memory by default. It contains contact
+data and a Stripe token. Do not log or persist it as part of a new integration.
+If an existing host already restores recovery, read browser storage in an
+effect, never in server rendering. Render public item content initially inert
+until that read completes. Remount once with `resumePurchase` only for a valid
+record matching the auction, item, client, and environment. Live recovery
+callbacks must not change the item key or remount checkout. When the callback
+returns `null`, clear the stored record and resume prop while keeping the key
+stable. Never serialize recovery into loader data, URLs, or metadata.
+
+### TanStack Start server routes
+
+On an existing TanStack Start SSR site, put the public SDK load in a GET server
+function and call it from each file-route loader. A shared loader also runs
+on client navigation, so do not treat the loader itself as server-only code.
+
+```tsx
+import { createServerFn } from "@tanstack/react-start";
+import { createLockerverseAuctionClient } from "@lockerverse/sdk/auctions";
+
+const auctionOptions = { communitySlug: "your-community" };
+const auctionPath = "your-auction";
+export const getSavedAuction = createServerFn({ method: "GET" }).handler(
+  () => createLockerverseAuctionClient(auctionOptions).load(auctionPath)
+);
+// File route: loader: () => getSavedAuction()
+// const initialAuction = Route.useLoaderData();
+// const resource = useLockerverseAuction(auctionOptions, auctionPath, { initialAuction });
+```
+
+Resolve the item from the same route's params and loader data. Set head title
+from the item and auction names, description from that item's description or
+an item-specific fallback, and `og:image` from its image when present. Render
+`resource.auction ?? initialAuction` outside `ClientOnly`; gallery, text, and
+status must be in the first response. Stripe initialization stays in the
+browser. Include public read data only in loader results.
+
+For static Vite sites, preserve client loading and report that current
+item-specific first-response metadata needs an SSR response or another static
+build. Do not add a per-site server solely for this integration. For SSR,
+verify raw first-response names and metadata, hydration, direct entry, routing,
+and live refresh. Check desktop and 390 by 844 layouts, unavailable states,
+quantity and bid validation, gallery, and both result return controls. Use the
+SDK simulated result preview. Open checkout to inspect saved fees and shipping,
+but do not submit a live bid or payment.