@usequeek/theme-kit 0.1.0

package/sdk/client.ts

@@ -0,0 +1,221 @@
+import { getActivePlatform } from './platform';
+
+// SERVER-side only (SSR data fetching, server-to-server — never reaches the
+// browser, so the real absolute host is correct and required here).
+export const API_BASE_URL = process.env.QUEEK_API_URL ?? process.env.NEXT_PUBLIC_QUEEK_API_URL ?? 'http://127.0.0.1:8000/api/v1';
+// BROWSER-side only (createBrowserClient below, "for client components/hooks").
+// Hardcoded relative on purpose, same reasoning as queek-client.ts's
+// API_BASE_URL: next.config.ts's rewrite already proxies /api/v1/client/:path*
+// to the backend server-side, so the browser never needs the real host. This
+// used to read NEXT_PUBLIC_QUEEK_API_URL directly — when that's set to the
+// same absolute value as the server-side QUEEK_API_URL, every hook built on
+// createBrowserClient (products, shop, categories, reviews, related products,
+// product questions, QR collections) leaked api.usequeek.com straight into
+// the browser Network tab, bypassing the proxy entirely.
+const PUBLIC_API_BASE_URL = '/api/v1';
+
+export interface RequestOptions extends RequestInit {
+  query?: Record<string, string | number | boolean | string[] | null | undefined>;
+  /** Abort budget. Omit to leave the request unbounded (browser default). */
+  timeoutMs?: number;
+  /**
+   * Server-only. A policy caches the read; `null` forces `no-store`; `undefined`
+   * leaves fetch untouched (the browser path, where `next` options are inert).
+   */
+  cachePolicy?: RequestCachePolicy | null;
+}
+
+export interface RequestCachePolicy {
+  revalidate: number;
+  tags: string[];
+}
+
+/**
+ * Browser abort budgets. Generous on purpose — these exist so a hung request
+ * eventually releases, not to enforce an SLA on a shopper's mobile connection.
+ *
+ * A write gets far more room than a read, and `request()` NEVER retries: an
+ * aborted POST may already have reached the backend, so re-sending it could
+ * duplicate an order or a payment.
+ */
+const BROWSER_GET_TIMEOUT_MS = 15_000;
+const BROWSER_POST_TIMEOUT_MS = 25_000;
+
+/**
+ * Carries the HTTP status so callers can tell a genuine "this does not exist"
+ * (404) apart from an infrastructure failure (5xx, timeout, network). That
+ * distinction is load-bearing in `app/[vendor]/layout.tsx`: 404 must render
+ * not-found, while a backend blip must NOT — a 404 on every URL of a live store
+ * is how storefronts get deindexed.
+ */
+export class ApiRequestError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly url: string,
+  ) {
+    super(`Request failed with status ${status}`);
+    this.name = 'ApiRequestError';
+  }
+}
+
+/**
+ * Thrown in place of the raw `DOMException` that `AbortSignal.timeout()`
+ * produces. `DOMException` passes `instanceof Error` but its `message` is a
+ * getter with no setter — Next's dev bundler (`setup-dev-bundler.js`,
+ * `logErrorWithOriginalStack`) unconditionally does `err.message = ...` on
+ * anything `instanceof Error` when rendering the dev overlay, which crashes
+ * with "Cannot set property message of ... which has only a getter" and
+ * cascades into unhandledRejection noise. Rewrapping into a plain, settable
+ * Error here — the one place every SSR/browser fetch funnels through — stops
+ * that crash without touching the abort/timeout semantics themselves.
+ */
+export class ApiTimeoutError extends Error {
+  constructor(
+    public readonly url: string,
+    public readonly timeoutMs: number,
+    { cause }: { cause?: unknown } = {},
+  ) {
+    super(`Request to ${url} timed out after ${timeoutMs}ms`);
+    this.name = 'ApiTimeoutError';
+    this.cause = cause;
+  }
+}
+
+/**
+ * For fetchers whose caller renders not-found on a null result.
+ *
+ * Returns null ONLY for a real 404 and rethrows everything else. A bare
+ * `catch { return null }` there turns a backend timeout or 5xx into a 404 for a
+ * product/page that exists — which is what deindexes a store's highest-value
+ * URLs during a blip, and became far more likely once SSR fetches gained an
+ * abort budget.
+ *
+ * `status` is read structurally rather than via `instanceof`: the class is
+ * emitted once per bundler layer, so an `instanceof` check across the RSC/SSR
+ * boundary can be silently false.
+ */
+export function swallowNotFound(error: unknown): null {
+  if ((error as { status?: number } | null)?.status === 404) {
+    return null;
+  }
+
+  throw error;
+}
+
+function withQuery(path: string, query?: RequestOptions['query']): string {
+  if (!query) {
+    return path;
+  }
+
+  const params = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(query)) {
+    if (value === null || value === undefined || value === '') {
+      continue;
+    }
+
+    // Laravel's query parser only builds a real array from bracket notation
+    // (`key[]=a&key[]=b`) — a plain comma-joined `key=a,b` (URLSearchParams'
+    // default for an array via String()) arrives server-side as a single
+    // string, failing an `array` validation rule outright.
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        params.append(`${key}[]`, String(item));
+      }
+      continue;
+    }
+
+    params.set(key, String(value));
+  }
+
+  const queryString = params.toString();
+
+  return queryString === '' ? path : `${path}?${queryString}`;
+}
+
+export async function request<T>(baseUrl: string, path: string, options: RequestOptions & { credentials?: RequestCredentials } = {}, extraHeaders?: Record<string, string>): Promise<T> {
+  // HARD RULE: the storefront only ever calls the `/v1/client/*` scope. That scope's
+  // ResolveClientContext middleware resolves the vendor AND forces the platform
+  // (storefront/instore_qr), so prices are always the storefront's (no marketplace
+  // commission). Legacy v1 routes (/products, /vendors/*, /categories) bypass that
+  // middleware → wrong platform → wrong price. Never call them from here.
+  if (!path.startsWith('/client/')) {
+    throw new Error(`Storefront may only call /v1/client/* routes — got "${path}". Use createServerStoreClient / createBrowserClient (which prefix /client/store).`);
+  }
+
+  const { query, timeoutMs, cachePolicy, ...init } = options;
+  const url = `${baseUrl}${withQuery(path, query)}`;
+
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+    ...(extraHeaders ?? {}),
+    ...((init.headers as Record<string, string> | undefined) ?? {}),
+  };
+
+  // Only idempotent, unauthenticated reads may be cached. A POST must always
+  // reach the origin, and a bearer token means the response is per-user — the
+  // data cache is shared across every visitor, so caching either would serve one
+  // customer's data to another.
+  const method = (init.method ?? 'GET').toUpperCase();
+  const cacheable = method === 'GET' && headers.Authorization === undefined && !!cachePolicy;
+
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      ...init,
+      headers,
+      ...(timeoutMs === undefined ? {} : { signal: AbortSignal.timeout(timeoutMs) }),
+      ...(cacheable
+        ? { next: { revalidate: cachePolicy.revalidate, tags: cachePolicy.tags } }
+        : cachePolicy === undefined
+          ? {}
+          : { cache: 'no-store' as const }),
+      ...(init.credentials ? { credentials: init.credentials } : {}),
+    });
+  } catch (error) {
+    if (error instanceof DOMException && (error.name === 'TimeoutError' || error.name === 'AbortError')) {
+      throw new ApiTimeoutError(url, timeoutMs ?? 0, { cause: error });
+    }
+    throw error;
+  }
+
+  if (!response.ok) {
+    throw new ApiRequestError(response.status, url);
+  }
+
+  return response.json() as Promise<T>;
+}
+
+// createServerClient (legacy v1 routes, no client-context middleware) was removed:
+// SSR reads now go through createServerStoreClient (/client/store/*) so the platform
+// is always forced server-side. Do NOT reintroduce a raw-v1 client here.
+
+/**
+ * Browser-side client for client components/hooks.
+ * Uses client-store routes (/client/store/*) with Origin + X-Vendor-Slug vendor resolution.
+ */
+export function createBrowserClient(vendorSlug?: string, token?: string): {
+  get: <T>(path: string, query?: RequestOptions['query']) => Promise<T>;
+  post: <T>(path: string, body?: unknown) => Promise<T>;
+} {
+  // Built per-request so X-Platform reflects the active platform at call time
+  // (e.g. the /qr page runs on `instore_qr` while the rest is `storefront`).
+  const buildHeaders = (): Record<string, string> => {
+    const headers: Record<string, string> = { 'X-Platform': getActivePlatform() };
+    if (token) headers['Authorization'] = `Bearer ${token}`;
+    if (vendorSlug) headers['X-Vendor-Slug'] = vendorSlug;
+    return headers;
+  };
+
+  return {
+    get: <T>(path: string, query?: RequestOptions['query']) =>
+      request<T>(PUBLIC_API_BASE_URL, `/client/store${path}`, { query, timeoutMs: BROWSER_GET_TIMEOUT_MS }, buildHeaders()),
+    post: <T>(path: string, body?: unknown) =>
+      request<T>(PUBLIC_API_BASE_URL, `/client/store${path}`, {
+        method: 'POST',
+        body: body ? JSON.stringify(body) : undefined,
+        timeoutMs: BROWSER_POST_TIMEOUT_MS,
+      }, buildHeaders()),
+  };
+}

package/sdk/error-handler.ts

@@ -0,0 +1,37 @@
+'use client';
+
+import { QueekSdkError } from '@queekai/client-sdk';
+import { useAuthModalStore } from '../stores/auth-modal-store';
+import { useUserStore } from '../stores/user-store';
+import { isReauthSuppressed } from './reauth-guard';
+
+/**
+ * Returns true if the caught error is an unauthenticated (401) error
+ * from the backend or SDK token layer.
+ */
+export function isUnauthenticatedError(err: unknown): boolean {
+  if (err instanceof QueekSdkError) {
+    if (err.code === 'unauthenticated') return true;
+    if (err.status === 401) return true;
+  }
+  return false;
+}
+
+/**
+ * Reset local user state and open the auth modal. Safe to call
+ * repeatedly (idempotent). Called by the SDK's onUnauthenticated
+ * callback (configured in queek-client.ts).
+ */
+export function triggerReauth(reason?: string): void {
+  if (isReauthSuppressed()) {
+     
+    console.warn(`[queek-sdk] unauthenticated (${reason ?? 'unknown'}) — suppressed, an auth exchange is in flight`);
+    return;
+  }
+  if (reason) {
+     
+    console.warn(`[queek-sdk] unauthenticated → reauth (${reason})`);
+  }
+  useUserStore.getState().logout();
+  useAuthModalStore.getState().open('login');
+}

package/sdk/platform.ts

@@ -0,0 +1,78 @@
+/**
+ * Active API platform holder.
+ *
+ * Every API request the storefront makes carries an `X-Platform` header so the
+ * backend can resolve the right config + fees. Most of the site runs on the
+ * `storefront` channel; the in-core QR ordering page (`/qr`) runs on `instore_qr`.
+ *
+ * The two client factories (`createBrowserClient`, `getQueekClient`) and the
+ * per-platform data caches read this holder. `<PlatformScope>` mutates it
+ * synchronously during render so descendant hooks fetch under the right platform.
+ *
+ * BROWSER-ONLY BY CONSTRUCTION — do not remove the guard in `setActivePlatform`.
+ * `'use client'` components are still rendered on the server during SSR, so
+ * `<PlatformScope>`'s render-time mutation used to run server-side too. Because
+ * this is module state in a long-lived Node process, a single SSR render of
+ * `/qr` flipped the holder to `instore_qr` for every subsequent request, for
+ * every vendor — the `useEffect` reset only ever runs in the browser. That made
+ * `server-store-client`'s `X-Platform` header non-deterministic.
+ *
+ * SSR therefore always reads `storefront`, which is correct: server-side fetches
+ * only ever load storefront-channel content, and the backend's
+ * ResolveClientContext re-derives and forces the platform regardless.
+ */
+export type Platform = 'storefront' | 'instore_qr';
+
+let activePlatform: Platform = 'storefront';
+
+export function getActivePlatform(): Platform {
+  return activePlatform;
+}
+
+export function setActivePlatform(platform: Platform): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  activePlatform = platform;
+}
+
+/**
+ * A `zustand/persist` storage engine that isolates instore_qr's client state
+ * from the ordinary storefront's, even though both run on the SAME origin (a
+ * vendor's own subdomain serves `/` and `/qr` alike, so plain `localStorage`
+ * is shared between them by default). Every key this writes while `instore_qr`
+ * is active gets a `qr-` prefix, so a value set on the ordinary storefront is
+ * simply invisible to `/qr` and vice versa — no in-memory state to keep in
+ * sync, no risk of one flow reading the other's leftovers.
+ *
+ * This is what a stale, non-QR `deliveryMode` (e.g. "pickup", picked earlier
+ * on the ordinary storefront) reaching a `/qr` dine-in checkout and getting
+ * its packaging wrongly enforced would have been caught by (production
+ * incident 30/8/26 — Kili Foods "Nkwobi"; see DeliveryModePicker's own fix
+ * for that specific symptom). Apply this to every persisted store/key a `/qr`
+ * flow touches EXCEPT auth (`queek-storefront-user`, the access/refresh
+ * tokens in `queek-client.ts`) — a signed-in customer must stay signed in
+ * across both.
+ */
+export function platformScopedStorage(): {
+  getItem: (name: string) => string | null;
+  setItem: (name: string, value: string) => void;
+  removeItem: (name: string) => void;
+} {
+  return {
+    getItem: (name) => (typeof window === 'undefined' ? null : localStorage.getItem(platformScopedKey(name))),
+    setItem: (name, value) => {
+      if (typeof window !== 'undefined') localStorage.setItem(platformScopedKey(name), value);
+    },
+    removeItem: (name) => {
+      if (typeof window !== 'undefined') localStorage.removeItem(platformScopedKey(name));
+    },
+  };
+}
+
+/** The raw-localStorage-call equivalent of `platformScopedStorage` — for code
+ *  that isn't a zustand store (e.g. the anonymous cart-session token). */
+export function platformScopedKey(name: string): string {
+  return getActivePlatform() === 'instore_qr' ? `qr-${name}` : name;
+}

package/sdk/queek-client.ts

@@ -0,0 +1,104 @@
+'use client';
+
+import { createQueekClient, type QueekClientInstance, type StorageAdapter } from '@queekai/client-sdk';
+import { triggerReauth } from './error-handler';
+import { getActivePlatform } from './platform';
+
+// This file is 'use client' — every export here only ever runs in the browser.
+// ALWAYS same-origin-relative, on purpose: next.config.ts's rewrite already
+// proxies /api/v1/client/:path* to the real backend server-side, so the
+// browser never needs (or should have) the backend's actual host. Reading
+// NEXT_PUBLIC_QUEEK_API_URL here would let a misconfigured env var (e.g. the
+// same absolute value used for the SERVER-side QUEEK_API_URL) leak
+// api.usequeek.com straight into every client-side request — confirmed live,
+// visible in the browser Network tab for autocomplete/resolve/fees/couriers/
+// addresses. No such var read = structurally impossible to leak it from here.
+export const API_BASE_URL = '/api/v1';
+export const QUEEK_AUTH_URL = process.env.NEXT_PUBLIC_QUEEK_AUTH_URL ?? 'https://auth.usequeek.com';
+
+const ACCESS_KEY = 'queek_client_access_token';
+const REFRESH_KEY = 'queek_client_refresh_token';
+
+// SSR-safe localStorage adapter — tokens survive page refresh
+const localStorageAdapter: StorageAdapter = {
+  getItem: (key) => (typeof window !== 'undefined' ? localStorage.getItem(key) : null),
+  setItem: (key, value) => { if (typeof window !== 'undefined') localStorage.setItem(key, value); },
+  removeItem: (key) => { if (typeof window !== 'undefined') localStorage.removeItem(key); },
+};
+
+/**
+ * The SDK's HTTP layer hardcodes `X-Platform: storefront` (auth.js) and writes
+ * it AFTER any per-request headers, so neither `config.platform` nor a request
+ * override can change it. We intercept via `config.fetch` and rewrite the header
+ * to the active platform at request time — so `/qr` requests (config, fees,
+ * product detail, order submit, auth) are correctly stamped `instore_qr` while
+ * the rest of the site stays `storefront`. Reads the holder per request, so a
+ * single cached client serves both platforms.
+ */
+const platformFetch: typeof fetch = (input, init) => {
+  if (init?.headers) {
+    const headers = new Headers(init.headers);
+    headers.set('X-Platform', getActivePlatform());
+    return fetch(input, { ...init, headers });
+  }
+  return fetch(input, init);
+};
+
+let cachedClient: QueekClientInstance | null = null;
+let cachedSlug: string | null = null;
+
+export function getQueekClient(vendorSlug?: string): QueekClientInstance {
+  const slug = vendorSlug ?? null;
+
+  if (cachedClient && cachedSlug === slug) {
+    return cachedClient;
+  }
+
+  cachedClient = createQueekClient({
+    baseUrl: API_BASE_URL,
+    fetch: platformFetch,
+    ...(slug ? { vendorSlug: slug } : {}),
+    accessTokenStorage: localStorageAdapter,
+    refreshTokenStorage: localStorageAdapter,
+    accessTokenStorageKey: ACCESS_KEY,
+    refreshTokenStorageKey: REFRESH_KEY,
+    onUnauthenticated: ({ path }) => {
+      triggerReauth(path);
+    },
+  });
+  cachedSlug = slug;
+
+  return cachedClient;
+}
+
+/** Read the current access token for one-off requests outside the SDK (e.g. inbox pairing-code mint). */
+export function getAccessToken(): string | null {
+  return typeof window !== 'undefined' ? localStorage.getItem(ACCESS_KEY) : null;
+}
+
+/**
+ * Headers for a raw `fetch` to the API outside the SDK. Needed only for verbs
+ * the SDK does not expose (it has GET/POST/PUT/DELETE — no PATCH). Mirrors the
+ * headers the SDK sends so the request is authenticated + scoped identically.
+ */
+export function clientAuthHeaders(vendorSlug?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    'Content-Type': 'application/json',
+    'X-Platform': getActivePlatform(),
+  };
+  const token = getAccessToken();
+  if (token) headers.Authorization = `Bearer ${token}`;
+  if (vendorSlug) headers['X-Vendor-Slug'] = vendorSlug;
+  return headers;
+}
+
+/** Persist tokens from external auth flows (Google OAuth, email-password) and reset the SDK cache. */
+export function setAuthTokens(accessToken: string, refreshToken: string): void {
+  if (typeof window === 'undefined') return;
+  localStorage.setItem(ACCESS_KEY, accessToken);
+  localStorage.setItem(REFRESH_KEY, refreshToken);
+  // Reset cache so the next getQueekClient() reads the new tokens from localStorage.
+  cachedClient = null;
+  cachedSlug = null;
+}

package/sdk/reauth-guard.ts

@@ -0,0 +1,27 @@
+let suppressed = false;
+let suppressTimer: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * Suppress the global "401 → log out + open login modal" handler (see error-handler.ts
+ * triggerReauth) for a window of time. Exists for a real race: on page load, an already-present
+ * (possibly stale/expired) token is still in localStorage while an auth exchange — a channel
+ * magic-link resolve, an OAuth callback — is establishing a NEW session. Other components mounted
+ * globally (e.g. useCartSync) fire their own authenticated requests independently and don't know
+ * an exchange is in flight; if THEIR request 401s on the stale token and that response lands
+ * AFTER the exchange has already applied the new session, the global handler would silently wipe
+ * the brand-new login (logout() clears user/isAuthenticated, though not the token itself) and
+ * reopen the login modal — the customer ends up looking logged out even though the exchange
+ * actually succeeded. Call suppressReauth() before starting an exchange; the window covers both
+ * the exchange itself and any stale in-flight request whose 401 arrives shortly after.
+ */
+export function suppressReauth(forMs = 8000): void {
+  suppressed = true;
+  if (suppressTimer) clearTimeout(suppressTimer);
+  suppressTimer = setTimeout(() => {
+    suppressed = false;
+  }, forMs);
+}
+
+export function isReauthSuppressed(): boolean {
+  return suppressed;
+}

package/sdk/server-store-client.ts

@@ -0,0 +1,165 @@
+import { headers } from 'next/headers';
+import { resolveCustomDomainVendorSlug, resolveCustomDomainVendorSlugRemote, resolveSubdomainVendorSlug } from '../utils/vendor-host';
+import { API_BASE_URL, request, type RequestCachePolicy, type RequestOptions } from './client';
+import { getActivePlatform } from './platform';
+
+/**
+ * Origin of the incoming storefront request, forwarded to the backend so it
+ * resolves the vendor exactly as it does for a real browser request (subdomain,
+ * apex/path and custom-domain storefronts all work with zero configuration).
+ *
+ * MUST be read OUTSIDE a React `cache()` scope — `headers()` is a dynamic API
+ * and throws when called inside a cached function. Callers read it here, then
+ * pass the value into the cached fetchers.
+ */
+export async function getRequestOrigin(): Promise<string | undefined> {
+  const h = await headers();
+  const host = h.get('host');
+  if (!host) return undefined;
+  const proto = h.get('x-forwarded-proto') ?? (host.includes('localhost') ? 'http' : 'https');
+  return `${proto}://${host}`;
+}
+
+/**
+ * Absolute store base URL for the current request — the single source of truth
+ * for the subdomain-vs-path `basePath` resolution (subdomain/custom-domain
+ * storefronts serve at the bare origin; path-based access serves under
+ * `/vendor-slug`). Every canonical URL, sitemap entry, and JSON-LD `url` field
+ * must derive from this instead of re-deriving `basePath` inline — see
+ * `app/[vendor]/layout.tsx` and `app/[vendor]/products/[slug]/page.tsx`, which
+ * used to duplicate this logic before it was extracted here.
+ */
+export async function resolveStoreBaseUrl(vendor: string): Promise<string | null> {
+  const origin = await getRequestOrigin();
+  if (!origin) return null;
+
+  const h = await headers();
+  const host = h.get('host')?.split(':')[0] ?? '';
+  const isSubdomain = !!(
+    resolveSubdomainVendorSlug(host) ??
+    resolveCustomDomainVendorSlug(host) ??
+    (host ? await resolveCustomDomainVendorSlugRemote(host) : null)
+  );
+  const basePath = isSubdomain ? '' : `/${vendor}`;
+
+  return `${origin}${basePath}`;
+}
+
+/**
+ * Server-side client for the unified `/client/store/*` scope — SSR CMS content
+ * (theme, menus, pages, posts, galleries, policies). The vendor is resolved from
+ * the forwarded request `Origin` (+ `X-Vendor-Slug`); pass `origin` from
+ * {@link getRequestOrigin}. Replaces the legacy v1 `/vendors/{slug}/store/*` routes.
+ */
+/**
+ * Abort budget for SSR reads. Sized above the observed p99 of the slowest
+ * bootstrap call (`/theme`, ~4.4s) with headroom, so it never fails a legitimate
+ * slow response — its job is to stop in-flight renders accumulating without
+ * bound when the backend hangs, not to enforce an SLA.
+ */
+const SSR_TIMEOUT_MS = 8_000;
+
+/**
+ * Which SSR reads may be cached, for how long, and under which tags.
+ *
+ * ALLOWLIST BY DESIGN — anything unmatched returns null and always hits the
+ * origin. Never add cart, checkout, fulfillment, follow-status, reviews or
+ * questions here: they are per-visitor or must be live, and the data cache is
+ * shared across every visitor of a store.
+ *
+ * Tags are per vendor so one store's edit never flushes another's. The TTL is a
+ * safety net, not the primary mechanism — `POST /api/revalidate?tag=…` from the
+ * backend is what makes an edit show up immediately.
+ */
+function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolicy | null {
+  const vendor = `v:${vendorSlug}`;
+  const policy = (revalidate: number, suffix: string, extra?: string): RequestCachePolicy => ({
+    revalidate,
+    tags: extra ? [vendor, `${vendor}:${suffix}`, `${vendor}:${extra}`] : [vendor, `${vendor}:${suffix}`],
+  });
+
+  // `/config` is deliberately NOT here: nothing fetches it server-side today, and
+  // its response varies by platform (VendorConfigRequest), so allowlisting it
+  // would let a future SSR caller that omits `platform` collapse two platforms
+  // onto one cached entry.
+  if (path === '/info') return policy(300, 'profile');
+  // Combines /theme + /menus + /pages-chrome into one backend round trip (see
+  // StoreContentController::bootstrapForClient). Tagged with all three resource
+  // suffixes so a merchant edit to any one of them busts this entry — the
+  // existing observers (MenuObserver, PostObserver, VendorConfigObserver)
+  // already emit exactly these suffixes, no backend change needed.
+  if (path === '/bootstrap') return { revalidate: 300, tags: [vendor, `${vendor}:theme`, `${vendor}:menus`, `${vendor}:pages`] };
+  if (path === '/blog-categories') return policy(300, 'posts');
+  if (/^\/pages(\/[^/]+)?$/.test(path)) return policy(300, 'pages');
+  if (/^\/posts(\/[^/]+)?$/.test(path)) return policy(300, 'posts');
+  if (/^\/policies(\/[^/]+)?$/.test(path)) return policy(300, 'policies');
+  if (/^\/galleries(\/[^/]+)?$/.test(path)) return policy(300, 'galleries');
+  if (/^\/categories(\/[^/]+\/products)?$/.test(path)) return policy(300, 'categories');
+  if (/^\/collections(\/[^/]+\/products)?$/.test(path)) return policy(300, 'collections');
+
+  // Shorter, because price and stock live here: a stale card that a shopper then
+  // cannot buy at the shown price is a trust problem, even though the backend
+  // recomputes both at order time.
+  if (path === '/products') return policy(60, 'products');
+
+  const product = /^\/products\/([^/]+)(?:\/related)?$/.exec(path);
+  if (product) return policy(60, 'products', `product:${product[1]}`);
+
+  return null;
+}
+
+/**
+ * True when this render is the merchant editor's preview iframe, which loads the
+ * storefront with `?preview=true&id=<vendorId>`. Set by `proxy.ts`, which is the only
+ * place that can see query params before the fetch layer runs.
+ *
+ * A preview render MUST bypass the cache outright rather than rely on the backend's
+ * invalidation call. Invalidation is a distributed handshake — it needs two env vars
+ * to match across two repos and a live HTTP round trip — and when any part of that
+ * is wrong it fails SILENTLY, leaving a merchant staring at an unchanged store for
+ * the full TTL. The editor is the one surface where "eventually" is not acceptable,
+ * and it already knows it is the editor, so it should not have to ask anyone.
+ *
+ * The backend still flushes tags on save; that is what keeps the PUBLIC store fresh.
+ * This just removes the editor's dependence on it.
+ */
+async function isPreviewRender(): Promise<boolean> {
+  const h = await headers();
+
+  return h.get('x-queek-preview') === '1';
+}
+
+export function createServerStoreClient(vendorSlug: string, origin?: string): {
+  get: <T>(path: string, query?: RequestOptions['query']) => Promise<T>;
+  post: <T>(path: string, body?: unknown) => Promise<T>;
+} {
+  const buildHeaders = (): Record<string, string> => {
+    const out: Record<string, string> = {
+      'X-Platform': getActivePlatform(),
+      'X-Vendor-Slug': vendorSlug,
+    };
+    if (origin) out.Origin = origin;
+    return out;
+  };
+
+  return {
+    get: async <T>(path: string, query?: RequestOptions['query']) =>
+      request<T>(
+        API_BASE_URL,
+        `/client/store${path}`,
+        {
+          query,
+          timeoutMs: SSR_TIMEOUT_MS,
+          cachePolicy: (await isPreviewRender()) ? null : resolveCachePolicy(vendorSlug, path),
+        },
+        buildHeaders(),
+      ),
+    post: <T>(path: string, body?: unknown) =>
+      request<T>(API_BASE_URL, `/client/store${path}`, {
+        method: 'POST',
+        body: body ? JSON.stringify(body) : undefined,
+        timeoutMs: SSR_TIMEOUT_MS,
+        cachePolicy: null,
+      }, buildHeaders()),
+  };
+}

package/shared-blocks/button.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import Link from 'next/link';
+import type { ButtonBlockData } from '../types/block';
+
+/**
+ * Framework-owned button block. Respects per-block bg_color/text_color
+ * overrides from vendor data. Everything else is styled via the theme's
+ * `.core-block-button` CSS.
+ */
+export function CoreButtonBlock({ text, url, bg_color, text_color }: ButtonBlockData): JSX.Element | null {
+  const label = text ?? '';
+  if (!label) return null;
+
+  const style: React.CSSProperties = {};
+  if (bg_color) style.backgroundColor = bg_color;
+  if (text_color) style.color = text_color;
+  const hasCustomStyle = Object.keys(style).length > 0;
+
+  return (
+    <section className="core-block core-block-button-wrap">
+      {url ? (
+        <Link
+          href={url}
+          className="core-block-button"
+          style={hasCustomStyle ? style : undefined}
+        >
+          {label}
+        </Link>
+      ) : (
+        <button
+          type="button"
+          className="core-block-button"
+          style={hasCustomStyle ? style : undefined}
+        >
+          {label}
+        </button>
+      )}
+    </section>
+  );
+}