@usequeek/theme-kit 0.1.22 → 0.1.24

package/sdk/error-handler.ts

@@ -6,8 +6,15 @@ import { useUserStore } from '../stores/user-store';
 import { isReauthSuppressed } from './reauth-guard';
 
 /**
- * Returns true if the caught error is an unauthenticated (401) error
- * from the API or SDK token layer.
+ * True when the error is an unauthenticated (401) failure from the API or the
+ * SDK token layer: the customer session is missing, expired or revoked.
+ *
+ * @example
+ * try {
+ *   await client.get('/client/orders');
+ * } catch (error) {
+ *   if (isUnauthenticatedError(error)) triggerReauth('orders');
+ * }
  */
 export function isUnauthenticatedError(err: unknown): boolean {
   if (err instanceof QueekSdkError) {
@@ -18,19 +25,20 @@ export function isUnauthenticatedError(err: unknown): boolean {
 }
 
 /**
- * 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).
+ * Clear the local customer session and open the sign-in modal. Safe to call
+ * repeatedly. The SDK's `onUnauthenticated` callback (configured in
+ * `queek-client.ts`) calls it, so most code never needs to.
+ *
+ * `reason` (usually the request path) is logged to help trace which call
+ * lost the session. It must not contain tokens.
  */
 export function triggerReauth(reason?: string): void {
   if (isReauthSuppressed()) {
-     
-    console.warn(`[queek-sdk] unauthenticated (${reason ?? 'unknown'}) — suppressed, an auth exchange is in flight`);
+    console.warn(`[theme-kit] a request lost its session (${reason ?? 'unknown request'}), but sign-in is in progress, so the customer was not signed out.`);
     return;
   }
   if (reason) {
-     
-    console.warn(`[queek-sdk] unauthenticated → reauth (${reason})`);
+    console.warn(`[theme-kit] session expired on ${reason}: signing the customer out and opening sign-in.`);
   }
   useUserStore.getState().logout();
   useAuthModalStore.getState().open('login');

package/sdk/queek-client.ts

@@ -75,6 +75,16 @@ export function getLastRequestId(): string | null {
 let cachedClient: QueekClientInstance | null = null;
 let cachedSlug: string | null = null;
 
+/**
+ * The Queek customer SDK client for this store, created once and reused.
+ * Browser only: it keeps the customer's tokens in `localStorage` and sends
+ * every request to the same-origin `/api/v1`. A 401 signs the customer out and
+ * opens the sign-in modal (see `triggerReauth`).
+ *
+ * @example
+ * const client = getQueekClient(vendor.slug);
+ * const orders = await client.get('/client/store/orders');
+ */
 export function getQueekClient(vendorSlug?: string): QueekClientInstance {
   const slug = vendorSlug ?? null;
 
@@ -99,7 +109,7 @@ export function getQueekClient(vendorSlug?: string): QueekClientInstance {
   return cachedClient;
 }
 
-/** Read the current access token for one-off requests outside the SDK (e.g. inbox pairing-code mint). */
+/** The customer's current access token, or null when signed out or on the server. For one-off requests outside the SDK; never log it. */
 export function getAccessToken(): string | null {
   return typeof window !== 'undefined' ? localStorage.getItem(ACCESS_KEY) : null;
 }

package/sdk/server-store-client.ts

@@ -120,8 +120,8 @@ function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolic
 
 /**
  * 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.
+ * storefront with `?preview=true&id=<vendorId>`. Set by the host's request proxy, the
+ * only place that sees query params before the fetch layer runs.
  *
  * A preview render MUST bypass the cache outright rather than rely on the API's
  * invalidation call. Invalidation is a distributed handshake — it needs two env vars

package/shared-blocks/embed.tsx

@@ -2,12 +2,16 @@
 
 import type { JSX } from 'react';
 import type { EmbedBlockData } from '../types/block';
+import { useThemeStrings } from '../provider';
 
 /**
  * Framework-owned embed block. Renders an iframe for any external URL
- * (Instagram, Spotify, Twitter, custom). Themes style via `.core-block-embed`.
+ * (a social post, an audio player, any page that allows embedding). Its words come
+ * from the theme strings (`embed.*`). Themes style via `.core-block-embed`.
  */
 export function CoreEmbedBlock({ url }: EmbedBlockData): JSX.Element {
+  const t = useThemeStrings();
+
   if (!url) {
     return (
       <section className="core-block core-block-embed">
@@ -17,7 +21,7 @@ export function CoreEmbedBlock({ url }: EmbedBlockData): JSX.Element {
               <polyline points="16 18 22 12 16 6" />
               <polyline points="8 6 2 12 8 18" />
             </svg>
-            <span>Paste an Instagram, Spotify, or iframe URL</span>
+            <span>{t('embed.placeholder')}</span>
           </div>
         </div>
       </section>
@@ -30,7 +34,7 @@ export function CoreEmbedBlock({ url }: EmbedBlockData): JSX.Element {
         <iframe
           className="core-block-embed__frame"
           src={url}
-          title="Embedded content"
+          title={t('embed.title')}
           allowFullScreen
           loading="lazy"
           referrerPolicy="no-referrer-when-downgrade"

package/shared-blocks/manifest.ts

@@ -20,7 +20,7 @@ export const FRAMEWORK_BLOCK_MANIFEST: Record<string, ThemeManifestVariant[]> =
     { id: 'default', label: 'Quote', default: true, purpose: 'Pull-quote with optional attribution' },
   ],
   embed: [
-    { id: 'default', label: 'Embed', default: true, purpose: 'Instagram, Spotify, Twitter, or any iframe URL' },
+    { id: 'default', label: 'Embed', default: true, purpose: 'Any page that allows embedding, from its URL' },
   ],
   video: [
     { id: 'default', label: 'Video', default: true, purpose: 'Embed a YouTube, Vimeo, or self-hosted video' },

package/shared-blocks/product-qa.tsx

@@ -80,7 +80,7 @@ function AskQuestionPanel({ productSlug }: { productSlug: string }): JSX.Element
     setError(null);
     try {
       const client = getQueekClient(vendor.slug ?? undefined);
-      await client.post(`/client/store/products/${productSlug}/questions`, { question: trimmed });
+      await client.post(`/client/store/products/${encodeURIComponent(productSlug)}/questions`, { question: trimmed });
       setOpen(false);
       setQuestion('');
       setSubmitted(true);

package/stores/address-modal-store.ts

@@ -8,6 +8,7 @@ interface AddressModalState {
   close: () => void;
 }
 
+/** Open and close state for the delivery address modal. Call `useAddressModalStore.getState().open()` from anywhere, or select from it in a component. */
 export const useAddressModalStore = create<AddressModalState>()((set) => ({
   isOpen: false,
   open: () => set({ isOpen: true }),

package/stores/auth-modal-store.ts

@@ -9,6 +9,7 @@ interface AuthModalState {
   close: () => void;
 }
 
+/** Open and close state for the sign-in modal. `open('signup')` starts on the sign-up step. Most code uses `useAuth()` instead. */
 export const useAuthModalStore = create<AuthModalState>()((set) => ({
   isOpen: false,
   mode: 'login',

package/stores/cart-panel-store.ts

@@ -9,6 +9,7 @@ interface CartPanelState {
   toggle: () => void;
 }
 
+/** Open and close state for the cart panel (drawer). Call `useCartPanelStore.getState().open()` from anywhere, or select from it in a component. */
 export const useCartPanelStore = create<CartPanelState>()((set) => ({
   isOpen: false,
   open: () => set({ isOpen: true }),

package/stores/cart-store.ts

@@ -12,11 +12,11 @@ import { productRequiresVariant } from '../utils/match-variant';
 
 interface CartState {
   items: CartItem[];
-  /** Set once per vendor mount (see vendor-shell.tsx) — the store has no
+  /** Set once per vendor mount by the storefront host. The store has no
    *  React context, so this is how it learns the active vendor's currency
-   *  for GA4 event values. The initial value is the platform default as a
-   *  last resort only; vendor-shell overwrites it with the vendor's currency
-   *  on mount. List-level `meta.currency` is never a source. */
+   *  for analytics event values. The initial value is the platform default as
+   *  a last resort only; the host overwrites it with the vendor's currency on
+   *  mount. List-level `meta.currency` is never a source. */
   currency: string;
   setCurrency: (currency: string) => void;
   addProduct: (product: Product, quantity?: number, variant?: ProductVariant | null) => void;
@@ -25,7 +25,7 @@ interface CartState {
   setQuantity: (id: string, shopId: string, quantity: number) => void;
   clearShopCart: (shopId: string) => void;
   /** Replaces a shop's items with the server-persisted cart — only called when
-   *  the local cart for that shop is empty (see use-cart-sync.ts), so this
+   *  the local cart for that shop is empty (by the storefront host), so this
    *  never clobbers what the customer is actively looking at. */
   adoptServerItems: (shopId: string, items: CartItem[]) => void;
 }
@@ -48,6 +48,11 @@ export function makeItemId(productId: string, addons: CartAddon[], variantId?: s
   return `${base}-${addons.map((addon) => addon.item_id).sort().join(',')}`;
 }
 
+/**
+ * The cart store. Prefer the `useCart()` and `useShopCart()` hooks; read this
+ * directly only from non-React code (`useCartStore.getState()`). Lines persist
+ * in `localStorage` under a per-channel key.
+ */
 export const useCartStore = create<CartState>()(
   persist(
     (set, get) => ({
@@ -62,7 +67,7 @@ export const useCartStore = create<CartState>()(
         // save fails server-side, so persisting one only moves the failure to
         // checkout. Themes gate
         // their add button too, but a theme is presentation — correctness
-        // cannot depend on all seven, or on the next one, getting it right.
+        // cannot depend on every theme getting it right.
         if (!variant && productRequiresVariant(product)) {
           toast({
             title: 'Select options',
@@ -75,7 +80,7 @@ export const useCartStore = create<CartState>()(
         const itemId = makeItemId(product.id, addons, variant?.id);
         const addonTotal = addons.reduce((sum, addon) => sum + addon.price, 0);
         // A variant's own price/stock override the base product's — the same
-        // precedence quick-add-page.tsx's matchedVariant already uses.
+        // precedence the quick-add flow uses.
         const unitPrice = (variant?.pricing.sale_amount ?? product.pricing.sale_amount) + addonTotal;
         const itemImage = variant?.media.thumbnail ?? variant?.media.image ?? product.media.thumbnail ?? product.media.image ?? null;
 

package/stores/checkout-store.ts

@@ -15,7 +15,7 @@ export interface ScheduleSlot {
 export type CheckoutTab = 'summary' | 'checkout';
 export type DeliveryType = 'instant' | 'schedule';
 
-/** The Shipbubble courier the customer picked. Its price is re-derived from the
+/** The courier option the customer picked for automated shipping. Its price is re-derived from the
  *  server-cached quote (via request_token + service_code) at fee/order time —
  *  never trusted from the client — so display == charge. */
 export interface ShipbubbleSelection {
@@ -42,7 +42,7 @@ interface CheckoutState {
   paymentMethodName: string | null;
   selectedBankAccount: SelectedBankAccount | null;
   /** instore_qr dine-in only — which of the vendor's tables the customer is
-   *  sitting at (App\Models\VendorTable id). Null for every other flow. */
+   *  sitting at (the table's id). Null for every other flow. */
   selectedTableId: string | null;
   promoCode: string;
   vendorNote: string;
@@ -53,7 +53,7 @@ interface CheckoutState {
   /** Shipping zone UUID — required for a MANUAL shipping order */
   shippingZoneId: string | null;
   shippingZoneName: string | null;
-  /** The picked Shipbubble courier for an AUTOMATED shipping order (transient) */
+  /** The courier option picked for an AUTOMATED shipping order (transient) */
   shipbubbleSelection: ShipbubbleSelection | null;
   /** Total order weight in kg — needed when selected zone has has_weight_pricing: true */
   weightKg: number | null;
@@ -64,7 +64,7 @@ interface CheckoutState {
   /** Transient. True while the customer is searching/changing their delivery
    *  address — the resolved fee is stale then, so surfaces hide it. */
   isEditingAddress: boolean;
-  /** The customer's saved address (CustomerAddress uuid) currently selected for
+  /** The customer's saved address (its uuid) currently selected for
    *  delivery, when they picked one from their address book instead of
    *  searching a fresh address. Lets the API reuse the cached courier
    *  geocode. Null whenever the address came from a fresh Google search. */

package/stores/location-store.ts

@@ -16,6 +16,11 @@ interface LocationState {
   clearLocation: () => void;
 }
 
+/**
+ * The shopper's chosen delivery location (coordinates and address), persisted
+ * per sales channel. Before one is chosen it holds the platform's default map
+ * centre and an empty address.
+ */
 export const useLocationStore = create<LocationState>()(
   persist(
     (set) => ({

package/stores/orders-sheet-store.ts

@@ -11,6 +11,7 @@ interface OrdersSheetState {
   closeDetail: () => void;
 }
 
+/** Open and close state for the customer's orders sheet. Call `useOrdersSheetStore.getState().open()` from anywhere, or select from it in a component. */
 export const useOrdersSheetStore = create<OrdersSheetState>()((set) => ({
   isOpen: false,
   activeOrderId: null,

package/stores/product-modal-store.ts

@@ -10,6 +10,7 @@ interface ProductModalState {
   close: () => void;
 }
 
+/** Open and close state for the quick-view product modal. Call `useProductModalStore.getState().open()` from anywhere, or select from it in a component. */
 export const useProductModalStore = create<ProductModalState>()((set) => ({
   isOpen: false,
   product: null,

package/stores/search-modal-store.ts

@@ -9,6 +9,7 @@ interface SearchModalState {
   close: () => void;
 }
 
+/** Open and close state for the search modal. Call `useSearchModalStore.getState().open()` from anywhere, or select from it in a component. */
 export const useSearchModalStore = create<SearchModalState>()((set) => ({
   isOpen: false,
   initialQuery: '',

package/stores/user-store.ts

@@ -32,7 +32,7 @@ export interface StorefrontUser {
  * the vendor already has the customer physically present, so a phone is not
  * needed to fulfil the order (matches POS, which never requires it either).
  *
- * `requiresEmail` — pass true for an automated-shipping vendor: Shipbubble's
+ * `requiresEmail` — pass true for an automated-shipping vendor: the
  * courier lookup needs a real email, which a phone-OTP-only signup never has.
  * Defaults false everywhere else so this stays a no-op for every other caller.
  */

package/strings/pseudo-locale.ts

@@ -2,7 +2,7 @@
  * Pseudo-locale QA helper.
  *
  * PURE AND SERVER-SAFE: this module imports nothing from `next/*` and nothing
- * from React, so server components, Node tooling (such as the theme check), tests and the
+ * from React, so server components, Node tooling (such as `npm run check` in a theme starter), tests and the
  * browser all share it (precedent: `utils/locale.ts`, `strings/theme-strings.ts`).
  * Keep it that way.
  *

package/theme-context.tsx

@@ -6,6 +6,10 @@ import type { ThemeModule } from './types/theme';
 
 const ThemeContext = createContext<ThemeModule | null>(null);
 
+/**
+ * Makes a theme module available to `useTheme()`. `ThemeMount` renders it for
+ * you; use it directly only when you mount a theme yourself.
+ */
 export function ThemeProvider({
   theme,
   children,
@@ -18,11 +22,17 @@ export function ThemeProvider({
   );
 }
 
+/**
+ * The mounted theme module (manifest, pages, header and footer variants).
+ *
+ * @throws {Error} when called outside `ThemeMount` or `ThemeProvider`. Use
+ * `useOptionalTheme()` where a theme may be absent.
+ */
 export function useTheme(): ThemeModule {
   const theme = useContext(ThemeContext);
 
   if (!theme) {
-    throw new Error('useTheme must be used within ThemeProvider');
+    throw new Error('useTheme() was called outside <ThemeProvider>. Render the component inside <ThemeMount> (or <ThemeProvider theme={...}>).');
   }
 
   return theme;

package/theme-mount.tsx

@@ -49,6 +49,7 @@ class ThemeBoundary extends Component<
   }
 }
 
+/** Props for {@link ThemeMount}. */
 export interface ThemeMountProps {
   theme: ThemeModule;
   headerProps: HeaderProps;
@@ -59,6 +60,19 @@ export interface ThemeMountProps {
   children: ReactNode;
 }
 
+/**
+ * Render a theme: its layout, the header and footer chosen by variant id, and
+ * `children` (the page) between them. A header or footer that throws is
+ * replaced by a visible error box naming the part, so one broken component
+ * does not blank the screen.
+ *
+ * @example
+ * <StorefrontProvider vendor={vendor} config={config} menus={menus}>
+ *   <ThemeMount theme={theme} headerProps={headerProps} footerProps={footerProps}>
+ *     <HomePage blocks={blocks} />
+ *   </ThemeMount>
+ * </StorefrontProvider>
+ */
 export function ThemeMount({
   theme,
   headerProps,

package/utils/format.ts

@@ -125,7 +125,7 @@ export function formatRelativeTime(
 /**
  * Platform default — the LAST resort only. Item rows carry their own
  * `currency` code (see normalizeProduct) and store-wide display uses the
- * vendor's currency (cart-store, set from vendor-shell on mount). A missing
+ * vendor's currency (held in the cart store, which the storefront host sets on mount). A missing
  * or malformed code must resolve through this function, never a bare
  * `?? 'NGN'` at a call site, so the fallback stays in exactly one place.
  */
@@ -144,6 +144,14 @@ export function normalizeCurrencyCode(value: unknown, fallback: string = PLATFOR
   return /^[A-Z]{3}$/.test(cleanFallback) ? cleanFallback : PLATFORM_DEFAULT_CURRENCY;
 }
 
+/**
+ * Format an amount in a currency (ISO 4217 code), in the shopper's locale.
+ * Decimals show only when the amount has them (`₦5,000`, `₦0.28`). An invalid
+ * currency code falls back to the platform default. Never throws.
+ *
+ * @example
+ * formatMoney(5000, 'NGN'); // "₦5,000"
+ */
 export function formatMoney(
   amount: number,
   currency = PLATFORM_DEFAULT_CURRENCY,
@@ -163,6 +171,7 @@ export function formatMoney(
   }
 }
 
+/** A whole-number percentage string, e.g. `toPercent(12.4)` is `"12%"`. */
 export function toPercent(value: number): string {
   return `${Math.max(0, Math.round(value))}%`;
 }

package/utils/menu-link.ts

@@ -11,6 +11,14 @@ export function menuItemKey(item: MenuItem, index: number): string {
   return `${item.type}:${item.ref ?? ''}:${item.meta?.anchor ?? ''}:${index}`;
 }
 
+/**
+ * The link target for a menu item: pages, collections, the shop, the blog, posts
+ * and galleries resolve under `basePath`; a `url` item is used as is; anything
+ * unknown becomes `#`. Pass `useStorefront().basePath` (or use `useHref`).
+ *
+ * @example
+ * <Link href={menuItemToHref(item, basePath)}>{item.label}</Link>
+ */
 export function menuItemToHref(item: MenuItem, basePath: string = ''): string {
   switch (item.type) {
     case 'page': {

package/utils/menu-placement.ts

@@ -0,0 +1,91 @@
+/**
+ * Popover collision handling for the language menu — pure (no DOM reads, no
+ * React) so it is unit-testable with plain numbers.
+ *
+ * The menu is positioned by CSS (under or over its trigger, aligned to the
+ * trigger's inline-start or inline-end edge). This module only decides
+ * whether that preferred placement fits the viewport, and if not, which of
+ * the alternatives to use: flip to the other side, flip the alignment, then
+ * shift horizontally to keep a gutter.
+ */
+
+export type MenuSide = 'bottom' | 'top';
+export type MenuAlign = 'start' | 'end';
+
+export interface Box {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface PlacementInput {
+  trigger: Box;
+  /** The popover's size — independent of where it is placed. */
+  popover: { width: number; height: number };
+  viewport: { width: number; height: number };
+  side: MenuSide;
+  align: MenuAlign;
+  /** Page direction: `'end'` is the right edge in `ltr` and the left edge in `rtl`. */
+  dir: 'ltr' | 'rtl';
+  /** Space kept between the popover and the viewport edge. */
+  gutter?: number;
+  /** Gap between the trigger and the popover. */
+  offset?: number;
+}
+
+export interface Placement {
+  side: MenuSide;
+  align: MenuAlign;
+  /** Horizontal correction in px, in the physical direction (positive = right). */
+  shift: number;
+  /** Room on the chosen side in px: the popover's height cap. */
+  available: number;
+}
+
+const DEFAULT_GUTTER = 16;
+const DEFAULT_OFFSET = 8;
+
+/** Left edge of the popover for an alignment. */
+function leftFor(align: MenuAlign, dir: 'ltr' | 'rtl', trigger: Box, width: number): number {
+  const rightEdgeAligned = (align === 'end') === (dir === 'ltr');
+  return rightEdgeAligned ? trigger.right - width : trigger.left;
+}
+
+/** Overflow (px) of a left edge past the gutters, 0 when it fits. */
+function overflow(left: number, width: number, viewportWidth: number, gutter: number): number {
+  if (left < gutter) return gutter - left;
+  if (left + width > viewportWidth - gutter) return viewportWidth - gutter - (left + width);
+  return 0;
+}
+
+export function computePlacement(input: PlacementInput): Placement {
+  const { trigger, popover, viewport, dir } = input;
+  const gutter = input.gutter ?? DEFAULT_GUTTER;
+  const offset = input.offset ?? DEFAULT_OFFSET;
+
+  const room = {
+    bottom: viewport.height - trigger.bottom - offset - gutter / 2,
+    top: trigger.top - offset - gutter / 2,
+  };
+  const other: MenuSide = input.side === 'bottom' ? 'top' : 'bottom';
+  const side =
+    popover.height <= room[input.side] || room[input.side] >= room[other] ? input.side : other;
+
+  const otherAlign: MenuAlign = input.align === 'end' ? 'start' : 'end';
+  const preferred = overflow(leftFor(input.align, dir, trigger, popover.width), popover.width, viewport.width, gutter);
+  let align = input.align;
+  let shift = preferred;
+  if (preferred !== 0) {
+    const alternative = overflow(leftFor(otherAlign, dir, trigger, popover.width), popover.width, viewport.width, gutter);
+    if (alternative === 0) {
+      align = otherAlign;
+      shift = 0;
+    } else if (Math.abs(alternative) < Math.abs(preferred)) {
+      align = otherAlign;
+      shift = alternative;
+    }
+  }
+
+  return { side, align, shift, available: Math.max(0, Math.floor(room[side])) };
+}

package/utils/to-error.ts

@@ -0,0 +1,4 @@
+/** Normalises anything a `catch` can hand back into an `Error`, so hooks can expose one `error` type. */
+export function toError(value: unknown): Error {
+  return value instanceof Error ? value : new Error(String(value));
+}

package/utils/vendor-host.ts

@@ -84,8 +84,7 @@ export async function resolveCustomDomainVendorSlugRemote(hostname: string): Pro
   }
 
   // Middleware runs server-side — prefer the server-only absolute URL. The
-  // public var can be a same-origin relative path (checkout-proxy rollout),
-  // which `fetch()` can't resolve without a document origin here.
+  // public var can be a same-origin relative path, which `fetch()` can't resolve without a document origin here.
   const baseUrl = process.env.QUEEK_API_URL ?? process.env.NEXT_PUBLIC_QUEEK_API_URL;
   if (!baseUrl) {
     return null;

package/scripts/verify-package.ts

@@ -1,102 +0,0 @@
-/**
- * Consumes the kit the way an OUTSIDER does, from a packed tarball.
- *
- * WHY THIS EXISTS. @usequeek/theme-kit@0.1.0 was published and was broken for
- * every external consumer:
- *
- *     node_modules/@usequeek/theme-kit/provider.tsx(58,5):
- *     error TS2503: Cannot find namespace 'JSX'.
- *
- * 42 modules annotated returns as `JSX.Element`, relying on a GLOBAL JSX
- * namespace that came from a host app's `next-env.d.ts` — not from React.
- * Inside a host app the kit free-rode on that file, so tsc, the tests, the
- * build and the render smoke were ALL green. The workspace supplies exactly the
- * file whose absence is the bug, which is why no in-repo check could ever have
- * found it. (Every module now does `import type { JSX } from 'react'`, and this
- * script proves it.)
- *
- * It packs the CURRENT SOURCE rather than installing the published version, so
- * it fails before a broken version ships instead of after. Installing from the
- * registry would only ever test the last release.
- */
-import { execFileSync } from 'node:child_process';
-import { mkdtempSync, rmSync, writeFileSync, readFileSync, mkdirSync, readdirSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-// The kit package is `"type": "module"`, so `__dirname` does not exist here.
-const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const KIT = ROOT;
-
-function run(cmd: string, args: string[], cwd: string): string {
-  return execFileSync(cmd, args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
-}
-
-function main(): void {
-  const sandbox = mkdtempSync(join(tmpdir(), 'kit-consumer-'));
-  let failed = false;
-
-  try {
-    const kitPkg = JSON.parse(readFileSync(join(KIT, 'package.json'), 'utf-8')) as {
-      name: string; version: string; peerDependencies?: Record<string, string>;
-    };
-
-    console.log(`verify-package: packing ${kitPkg.name}@${kitPkg.version} and consuming it as an outsider`);
-    run('npm', ['pack', '--pack-destination', sandbox], KIT);
-    const tarball = readdirSync(sandbox).find((f) => f.endsWith('.tgz'));
-    if (!tarball) throw new Error('npm pack produced no tarball');
-
-    // Peers are declared by the kit; pin the ones the fixture needs to compile.
-    const peers = kitPkg.peerDependencies ?? {};
-    writeFileSync(join(sandbox, 'package.json'), JSON.stringify({
-      name: 'kit-consumer', private: true, version: '1.0.0',
-      dependencies: {
-        [kitPkg.name]: `file:./${tarball}`,
-        '@queekai/client-sdk': peers['@queekai/client-sdk'] ?? '*',
-        next: '^16.0.0', react: '^19.0.0', 'react-dom': '^19.0.0',
-      },
-      devDependencies: { typescript: '^5', '@types/react': '^19', '@types/react-dom': '^19', '@types/node': '^22' },
-    }, null, 2));
-
-    // `bundler` resolution + no ambient Next types — exactly what a theme
-    // developer's own project looks like. NOT this repo's tsconfig.
-    writeFileSync(join(sandbox, 'tsconfig.json'), JSON.stringify({
-      compilerOptions: {
-        target: 'ES2017', lib: ['dom', 'dom.iterable', 'esnext'], jsx: 'react-jsx',
-        module: 'esnext', moduleResolution: 'bundler', strict: true, noEmit: true,
-        skipLibCheck: true, esModuleInterop: true, isolatedModules: true,
-      },
-      include: ['app/**/*.ts', 'app/**/*.tsx'],
-    }, null, 2));
-
-    mkdirSync(join(sandbox, 'app'), { recursive: true });
-    writeFileSync(join(sandbox, 'app/theme.tsx'), readFileSync(join(ROOT, 'tests/fixtures/external-theme.tsx'), 'utf-8'));
-
-    console.log('verify-package: installing from the tarball…');
-    run('npm', ['install', '--no-audit', '--no-fund'], sandbox);
-
-    console.log('verify-package: typechecking a real theme against it…');
-    try {
-      run(join(sandbox, 'node_modules/.bin/tsc'), ['--noEmit'], sandbox);
-      console.log(`\n✓ ${kitPkg.name} is consumable from outside this repo.`);
-    } catch (error) {
-      const out = (error as { stdout?: string; stderr?: string });
-      console.error('\n✗ the packed kit does NOT work for an external consumer:\n');
-      console.error((out.stdout ?? '') + (out.stderr ?? ''));
-      console.error('Errors inside node_modules/@usequeek/theme-kit are PACKAGE bugs — the kit is');
-      console.error('relying on something only this repo provides. Errors in app/theme.tsx mean the');
-      console.error('fixture drifted from the real API.');
-      failed = true;
-    }
-  } catch (error) {
-    console.error('✗ verify-package failed to run:', (error as Error).message);
-    failed = true;
-  } finally {
-    rmSync(sandbox, { recursive: true, force: true });
-  }
-
-  process.exit(failed ? 1 : 0);
-}
-
-main();