shopsense-test 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+## shopsense-widget (React Native)
+
+Thin WebView shell for the ShopSense widget.
+
+### Goals
+
+- **No UI owned by the package**: all HTML/JS/CSS is served by your server.
+- Package only:
+  - Renders a WebView pointing to your server page
+  - Passes widget config (zone + optional params) via query params
+  - Bridges product selections back to native (callback or default deep link)
+  - Keeps the WebView **persisted** across navigation
+
+### Install
+
+Add the package to your monorepo and import from it. Peer deps must exist in the app:
+
+- `react`
+- `react-native`
+- `react-native-webview`
+- `expo-router`
+
+### Usage
+
+#### 1) Wrap your app root once
+
+```tsx
+import { ShopSenseRoot } from "shopsense-widget";
+
+export default function RootLayout() {
+  return (
+    <ShopSenseRoot>
+      {/* your app routes */}
+    </ShopSenseRoot>
+  );
+}
+```
+
+#### 2) Mount the persistent WebView once (recommended)
+
+Mount `PersistentWebView` **once** at the root so it never unmounts/reloads when you leave the search screen.
+
+```tsx
+import { PersistentWebView } from "shopsense-widget";
+
+export default function RootLayout() {
+  return (
+    <ShopSenseRoot>
+      <View style={{ flex: 1, position: "relative" }}>
+        {/* your app routes */}
+        <PersistentWebView />
+      </View>
+    </ShopSenseRoot>
+  );
+}
+```
+
+#### 3) Register config + callbacks on your Search screen
+
+Render `ShopSenseWidget` on the screen where you want it active. It registers config/callbacks and toggles show/hide on focus.
+
+```tsx
+import { ShopSenseWidget } from "shopsense-widget";
+
+export default function SearchScreen() {
+  return (
+    <ShopSenseWidget
+      zoneId={35}
+      onProductSelect={(product) => {
+        // override default deep link navigation
+        // product = { id, alias }
+      }}
+      onDebugMessage={(msg) => {
+        // optional: WIDGET_STATUS / console / errors
+        console.log(msg);
+      }}
+    />
+  );
+}
+```
+
+### Configuration
+
+Only `zoneId` is required.
+
+All other config is optional and depends on how your widget shell is hosted (defaults are handled by the package and your shell).
+
+### Server contract
+
+Your server must host an HTML page (default path: `/embed/widget.html`) that:
+
+- Reads query params such as: `zone` (and any optional parameters you support)
+- Loads the ShopSense widget JS/CSS from your server/CDN
+- Posts `NAVIGATE_TO_PRODUCT` to the React Native WebView bridge when a product is tapped:
+
+```json
+{ "type": "NAVIGATE_TO_PRODUCT", "payload": { "id": 123, "alias": "slug" } }
+```
+
+### Default navigation behavior
+
+If `onProductSelect` is **not** provided, the package opens:
+
+`app.shopsense://product/:id/:alias`
+
+Your app must register the deep link scheme for this to work.
+

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "shopsense-test",
+  "version": "0.1.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "sideEffects": false,
+  "license": "UNLICENSED",
+  "peerDependencies": {
+    "expo-router": "*",
+    "react": "*",
+    "react-native": "*",
+    "react-native-webview": "*"
+  }
+}

package/src/PersistentWebView.tsx

@@ -0,0 +1,206 @@
+import React, { memo, useCallback, useEffect, useMemo, useRef } from "react";
+import { StyleSheet, View } from "react-native";
+import type { WebViewMessageEvent } from "react-native-webview";
+import { WebView } from "react-native-webview";
+import { useShopSense } from "./context";
+import {
+  extractProductSelect,
+  isDebugMessage,
+  tryParseJsonMessage,
+} from "./message";
+import { defaultOpenProduct } from "./navigation";
+import { buildWidgetUri } from "./url";
+
+export const PersistentWebView = memo(function PersistentWebView() {
+  const { config, visible, webViewRef, callbacksRef, lastWebViewUrlRef } =
+    useShopSense();
+  const lastLoggedUrlRef = useRef(null as string | null);
+
+  const uri = useMemo(() => {
+    if (!config) return null;
+    return buildWidgetUri(config);
+  }, [config]);
+
+  useEffect(() => {
+    if (uri) {
+      console.log("[ShopSenseWebView] initial uri:", uri);
+    }
+  }, [uri]);
+
+  useEffect(() => {
+    if (!visible) return;
+    const wv = webViewRef?.current as any;
+    if (!wv?.injectJavaScript) return;
+
+    // When returning from a native screen (Product → Back), the WebView doesn't get a
+    // browser "pageshow" event. If Layout 2 was hidden by the widget runtime, we need
+    // to re-show the existing container so results re-appear without requiring typing.
+    //
+    // Important: do NOT dispatch `hashchange` here — that forces a refetch. We only
+    // want to restore the already-rendered view/state.
+    wv.injectJavaScript(
+      `(function(){try{
+        var el = document.getElementById('lookin-widget-container');
+        if (el) {
+          el.style.display = 'block';
+          el.style.visibility = 'visible';
+          el.style.opacity = '1';
+        }
+        document.dispatchEvent(new CustomEvent('lookin:layout2'));
+      }catch(e){};return true;})();`
+    );
+  }, [visible, webViewRef]);
+
+  const handleMessage = useCallback(
+    (event: WebViewMessageEvent) => {
+      const raw = event?.nativeEvent?.data;
+      const msg = tryParseJsonMessage(raw);
+
+      // Debug messages
+      if (isDebugMessage(msg)) {
+        callbacksRef.current.onDebugMessage?.(msg);
+      }
+
+      const o = msg && typeof msg === "object" ? (msg as any) : null;
+      if (o?.type === "NAVIGATE_TO_PRODUCT") {
+        // Snapshot the last known URL before handing off to native navigation.
+        // This helps with persistence/debug when users return via Back.
+        lastWebViewUrlRef.current =
+          lastWebViewUrlRef.current ?? (o?.payload as any)?.productUrl ?? null;
+
+        const payload = o?.payload;
+        const product = extractProductSelect(payload);
+
+        if (product) {
+          if (callbacksRef.current.onProductSelect) {
+            callbacksRef.current.onProductSelect(product);
+          } else {
+            defaultOpenProduct(product);
+          }
+        }
+      }
+
+      callbacksRef.current.onMessage?.(msg);
+    },
+    [callbacksRef]
+  );
+
+  if (!uri) return null;
+
+  return (
+    <View
+      pointerEvents={visible ? "auto" : "none"}
+      style={[styles.container, !visible && styles.hidden]}
+    >
+      <WebView
+        ref={(r: any) => {
+          webViewRef.current = r;
+        }}
+        source={{ uri }}
+        onMessage={handleMessage}
+        onShouldStartLoadWithRequest={(req: any) => {
+          const nextUrl = typeof req?.url === "string" ? req.url : null;
+          if (nextUrl && lastLoggedUrlRef.current !== nextUrl) {
+            lastLoggedUrlRef.current = nextUrl;
+            console.log("[ShopSenseWebView] url:", nextUrl);
+          }
+          callbacksRef.current.onDebugMessage?.({
+            type: "WEBVIEW_SHOULD_START",
+            source: "native",
+            payload: {
+              url: req?.url,
+              navigationType: (req as any)?.navigationType,
+              isTopFrame: (req as any)?.isTopFrame,
+              mainDocumentURL: (req as any)?.mainDocumentURL,
+              hasTargetFrame: (req as any)?.hasTargetFrame,
+              method: (req as any)?.method,
+            },
+          });
+          return true;
+        }}
+        onNavigationStateChange={(navState: any) => {
+          if (typeof navState?.url === "string") {
+            lastWebViewUrlRef.current = navState.url;
+            if (lastLoggedUrlRef.current !== navState.url) {
+              lastLoggedUrlRef.current = navState.url;
+              console.log("[ShopSenseWebView] url:", navState.url);
+            }
+          }
+          callbacksRef.current.onDebugMessage?.({
+            type: "WEBVIEW_NAV_STATE",
+            source: "native",
+            payload: {
+              url: navState?.url,
+              title: (navState as any)?.title,
+              loading: navState?.loading,
+              canGoBack: navState?.canGoBack,
+              canGoForward: navState?.canGoForward,
+            },
+          });
+        }}
+        onLoadStart={(e: any) => {
+          callbacksRef.current.onDebugMessage?.({
+            type: "WEBVIEW_LOAD_START",
+            source: "native",
+            payload: { url: e?.nativeEvent?.url },
+          });
+        }}
+        onLoadEnd={(e: any) => {
+          callbacksRef.current.onDebugMessage?.({
+            type: "WEBVIEW_LOAD_END",
+            source: "native",
+            payload: { url: e?.nativeEvent?.url },
+          });
+        }}
+        onError={(e: any) => {
+          callbacksRef.current.onDebugMessage?.({
+            type: "WEBVIEW_ERROR",
+            source: "native",
+            payload: e?.nativeEvent,
+          });
+        }}
+        onHttpError={(e: any) => {
+          callbacksRef.current.onDebugMessage?.({
+            type: "WEBVIEW_HTTP_ERROR",
+            source: "native",
+            payload: e?.nativeEvent,
+          });
+        }}
+        javaScriptEnabled
+        domStorageEnabled
+        startInLoadingState
+        mixedContentMode="compatibility"
+        keyboardDisplayRequiresUserAction={false}
+        scrollEnabled
+        nestedScrollEnabled
+        bounces
+        showsVerticalScrollIndicator
+        // Keep the WebView mounted & stateful; hide/show via styles above.
+        style={styles.webview}
+      />
+    </View>
+  );
+});
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    minHeight: 0,
+    width: "100%",
+    backgroundColor: "#fff",
+    overflow: "hidden",
+  },
+  hidden: {
+    // Keep the WebView at full size but invisible; collapsing to 0 can
+    // cause some WebView implementations to discard their render tree.
+    opacity: 0,
+    height: 1,
+    flex: 0,
+    overflow: "hidden",
+  },
+  webview: {
+    flex: 1,
+    backgroundColor: "transparent",
+  },
+});
+

package/src/ShopSenseWidget.tsx

@@ -0,0 +1,102 @@
+import React, { memo, useCallback, useEffect, useMemo } from "react";
+import type { ReactNode } from "react";
+import { View } from "react-native";
+import { useFocusEffect } from "expo-router";
+import type { ShopSenseWidgetProps } from "./types";
+import { ShopSenseProvider, useShopSense, useShopSenseOptional } from "./context";
+import { PersistentWebView } from "./PersistentWebView";
+
+function ShopSenseWidgetInner(props: ShopSenseWidgetProps) {
+  const {
+    onDebugMessage,
+    onMessage,
+    onProductSelect,
+    autoShowOnFocus = true,
+    ...config
+  } = props;
+
+  const ctx = useShopSense();
+  const { callbacksRef, setConfig, show, hide } = ctx;
+
+  // Stabilize the config object so we don't call setConfig on every render.
+  const stableConfig = useMemo(() => {
+    const extraParamsKey = config.extraParams
+      ? JSON.stringify(config.extraParams)
+      : "";
+    return {
+      baseUrl: config.baseUrl,
+      zoneId: config.zoneId,
+      apiBase: config.apiBase,
+      uiDensity: config.uiDensity,
+      widgetPath: config.widgetPath,
+      extraParams: config.extraParams,
+      // internal key for memo deps
+      __extraParamsKey: extraParamsKey,
+    } as const;
+  }, [
+    config.baseUrl,
+    config.zoneId,
+    config.apiBase,
+    config.uiDensity,
+    config.widgetPath,
+    config.extraParams ? JSON.stringify(config.extraParams) : "",
+  ]);
+
+  // Keep latest callbacks without re-mounting the WebView.
+  useEffect(() => {
+    callbacksRef.current = { onProductSelect, onMessage, onDebugMessage };
+  }, [callbacksRef, onProductSelect, onMessage, onDebugMessage]);
+
+  // Update config.
+  useEffect(() => {
+    // Strip internal key before storing
+    const { __extraParamsKey, ...toStore } = stableConfig as any;
+    setConfig(toStore);
+  }, [setConfig, stableConfig]);
+
+  // Auto show/hide based on screen focus (persistent WebView stays mounted).
+  useFocusEffect(
+    useCallback(() => {
+      if (!autoShowOnFocus) return () => {};
+      show();
+      return () => hide();
+    }, [autoShowOnFocus, hide, show])
+  );
+
+  // This component itself renders nothing; the provider renders the WebView.
+  return null;
+}
+
+/**
+ * Public component API.
+ *
+ * If rendered within a `ShopSenseProvider`, it registers config + callbacks and uses the
+ * provider's persistent WebView.
+ *
+ * If rendered without a provider, it self-hosts the provider and persistent WebView.
+ */
+export const ShopSenseWidget = memo(function ShopSenseWidget(props: ShopSenseWidgetProps) {
+  const ctx = useShopSenseOptional();
+
+  if (ctx) {
+    return <ShopSenseWidgetInner {...props} />;
+  }
+
+  return (
+    <ShopSenseProvider>
+      <View style={{ flex: 1, minHeight: 0 }}>
+        <ShopSenseWidgetInner {...props} />
+        <PersistentWebView />
+      </View>
+    </ShopSenseProvider>
+  );
+});
+
+/**
+ * Place once at app root. It only provides context — render `PersistentWebView`
+ * inside your search screen (below AppBar) so the WebView does not cover the app chrome.
+ */
+export function ShopSenseRoot({ children }: { children: ReactNode }) {
+  return <ShopSenseProvider>{children}</ShopSenseProvider>;
+}
+

package/src/context.tsx

@@ -0,0 +1,107 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type { MutableRefObject, ReactNode } from "react";
+import { View } from "react-native";
+import type { ShopSenseWidgetConfig, ShopSenseWidgetProps } from "./types";
+
+type ShopSenseContextValue = {
+  /** Latest config the provider should render. */
+  config: ShopSenseWidgetConfig | null;
+  /** Whether the persistent WebView is currently visible. */
+  visible: boolean;
+  /** Replace config (does not automatically show). */
+  setConfig: (config: ShopSenseWidgetConfig) => void;
+  /** Show the persistent WebView (optionally overriding config). */
+  show: (config?: ShopSenseWidgetConfig) => void;
+  /** Hide the persistent WebView without unmounting it. */
+  hide: () => void;
+  /** Ref to the mounted WebView instance. */
+  webViewRef: MutableRefObject<unknown>;
+  /** Last known navigation URL inside the WebView (for persistence/debug). */
+  lastWebViewUrlRef: MutableRefObject<string | null>;
+  /** Props/callbacks from the last mounted ShopSenseWidget. */
+  callbacksRef: MutableRefObject<
+    Pick<ShopSenseWidgetProps, "onProductSelect" | "onMessage" | "onDebugMessage">
+  >;
+};
+
+export const ShopSenseContext = createContext(null as ShopSenseContextValue | null);
+
+export function ShopSenseProvider({ children }: { children?: ReactNode }) {
+  const [config, setConfigState] = useState(null as ShopSenseWidgetConfig | null);
+  const [visible, setVisible] = useState(false);
+
+  const webViewRef = useRef(null as unknown);
+  const lastWebViewUrlRef = useRef(null as string | null);
+  const callbacksRef = useRef(
+    {} as Pick<
+      ShopSenseWidgetProps,
+      "onProductSelect" | "onMessage" | "onDebugMessage"
+    >
+  );
+
+  const lastConfigKeyRef = useRef("");
+  const setConfig = useCallback((next: ShopSenseWidgetConfig) => {
+    // Avoid pointless state updates that can cause focus-effect churn.
+    const key = JSON.stringify(next);
+    if (key === lastConfigKeyRef.current) return;
+    lastConfigKeyRef.current = key;
+    setConfigState(next);
+  }, []);
+
+  const show = useCallback((next?: ShopSenseWidgetConfig) => {
+    if (next) {
+      const key = JSON.stringify(next);
+      if (key !== lastConfigKeyRef.current) {
+        lastConfigKeyRef.current = key;
+        setConfigState(next);
+      }
+    }
+    setVisible(true);
+  }, []);
+
+  const hide = useCallback(() => {
+    setVisible(false);
+  }, []);
+
+  const value = useMemo(
+    () => ({
+      config,
+      visible,
+      setConfig,
+      show,
+      hide,
+      webViewRef,
+      lastWebViewUrlRef,
+      callbacksRef,
+    }),
+    [config, visible, hide, setConfig, show]
+  );
+
+  return (
+    <ShopSenseContext.Provider value={value}>
+      {/* flex:1 so the persistent WebView (absolute fill) has a bounded parent like the native root */}
+      <View style={{ flex: 1 }}>{children}</View>
+    </ShopSenseContext.Provider>
+  );
+}
+
+export function useShopSense() {
+  const ctx = useContext(ShopSenseContext);
+  if (!ctx) {
+    throw new Error("useShopSense must be used within ShopSenseProvider");
+  }
+  return ctx;
+}
+
+/** Internal: like useShopSense but returns null instead of throwing. */
+export function useShopSenseOptional() {
+  return useContext(ShopSenseContext);
+}
+

package/src/index.ts

@@ -0,0 +1,12 @@
+export { ShopSenseWidget, ShopSenseRoot } from "./ShopSenseWidget";
+export { PersistentWebView } from "./PersistentWebView";
+export { ShopSenseProvider, useShopSense } from "./context";
+export { DEFAULT_BASE_URL } from "./url";
+export type {
+  ShopSenseDebugMessage,
+  ShopSenseProductSelect,
+  ShopSenseWidgetConfig,
+  ShopSenseWidgetProps,
+  UiDensity,
+} from "./types";
+

package/src/message.ts

@@ -0,0 +1,106 @@
+import type { ShopSenseDebugMessage, ShopSenseProductSelect } from "./types";
+
+function asObject(v: unknown): Record<string, unknown> | null {
+  return v && typeof v === "object" ? (v as Record<string, unknown>) : null;
+}
+
+export function tryParseJsonMessage(raw: unknown): unknown {
+  if (typeof raw !== "string") return raw;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+export function isDebugMessage(msg: unknown): msg is ShopSenseDebugMessage {
+  const o = asObject(msg);
+  const type = o?.type;
+  return (
+    typeof type === "string" &&
+    (type.startsWith("WIDGET_") || type.startsWith("WEBVIEW_"))
+  );
+}
+
+function pickPositiveInt(v: unknown): number | null {
+  if (typeof v === "number" && Number.isFinite(v) && v > 0) {
+    return Math.floor(v);
+  }
+  if (typeof v === "string") {
+    const t = v.trim();
+    if (!t) return null;
+    const n = parseInt(t, 10);
+    if (Number.isFinite(n) && n > 0) return n;
+  }
+  return null;
+}
+
+function pickNonEmptyString(v: unknown): string | undefined {
+  return typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+}
+
+/** Last path segment, for `/shop/123-cool-widget` → `123-cool-widget`. */
+function lastPathSegmentFromUrl(url: string): string | undefined {
+  try {
+    const noHash = url.split("#")[0] ?? "";
+    const noQuery = noHash.split("?")[0] ?? "";
+    const parts = noQuery.split("/").filter(Boolean);
+    const last = parts[parts.length - 1];
+    if (!last) return undefined;
+    return decodeURIComponent(last);
+  } catch {
+    return undefined;
+  }
+}
+
+function parseIdFromUrlPath(url: string): number | null {
+  const seg = lastPathSegmentFromUrl(url);
+  if (!seg) return null;
+  const hyphen = /^(\d+)[-_](.+)$/.exec(seg);
+  if (hyphen) {
+    return pickPositiveInt(hyphen[1]);
+  }
+  return pickPositiveInt(seg);
+}
+
+/**
+ * Extract `{ id, alias }` from a NAVIGATE_TO_PRODUCT payload.
+ * Accepts multiple shapes (id/productId/sku when numeric, alias/urlAlias/slug/name, URL paths).
+ */
+export function extractProductSelect(payload: unknown): ShopSenseProductSelect | null {
+  const o = asObject(payload);
+  if (!o) return null;
+
+  const productUrlStr = pickNonEmptyString(o.productUrl);
+  const urlAliasStr = pickNonEmptyString(o.urlAlias);
+
+  const idFromFields =
+    pickPositiveInt(o.id) ??
+    pickPositiveInt(o.productId) ??
+    pickPositiveInt(o.product_id) ??
+    pickPositiveInt(o.sku);
+
+  const idFromUrl =
+    (productUrlStr ? parseIdFromUrlPath(productUrlStr) : null) ??
+    (urlAliasStr && urlAliasStr.includes("/")
+      ? parseIdFromUrlPath(urlAliasStr)
+      : null);
+
+  const id = idFromFields ?? idFromUrl;
+
+  const alias =
+    pickNonEmptyString(o.alias) ??
+    urlAliasStr ??
+    pickNonEmptyString(o.slug) ??
+    pickNonEmptyString(o.handle) ??
+    pickNonEmptyString(o.productName) ??
+    pickNonEmptyString(o.name) ??
+    pickNonEmptyString(o.title) ??
+    pickNonEmptyString(o.sku) ??
+    (productUrlStr ? lastPathSegmentFromUrl(productUrlStr) : undefined) ??
+    "";
+
+  if (!id || !alias) return null;
+  return { id, alias };
+}
+

package/src/navigation.ts

@@ -0,0 +1,9 @@
+import { Linking } from "react-native";
+import type { ShopSenseProductSelect } from "./types";
+
+export function defaultOpenProduct(product: ShopSenseProductSelect): void {
+  const alias = encodeURIComponent(product.alias);
+  const url = `app.shopsense://product/${product.id}/${alias}`;
+  void Linking.openURL(url);
+}
+

package/src/shims.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Minimal stubs for peer deps.
+ *
+ * Important: do NOT install a second copy of `react-native` under this package.
+ * When this package is consumed via `file:` in an RN app, Metro can pick up the
+ * nested `node_modules/react-native` and crash with codegen errors.
+ */
+declare module "react" {
+  // Keep these loose; the app provides real React types at build time.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const React: any;
+  export default React;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const createContext: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const useContext: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type ReactNode = any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type MutableRefObject<T = any> = any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const memo: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const useCallback: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const useEffect: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const useMemo: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const useRef: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const useState: any;
+}
+
+declare module "expo-router" {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const useFocusEffect: any;
+}
+
+declare module "react-native" {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const StyleSheet: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const View: any;
+}
+
+declare module "react-native-webview" {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const WebView: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type WebViewMessageEvent = any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export type WebViewProps = any;
+}
+

package/src/types.ts

@@ -0,0 +1,71 @@
+export type UiDensity = "compact" | "comfortable";
+
+export type ShopSenseProductSelect = {
+  id: number;
+  alias: string;
+};
+
+export type ShopSenseDebugMessage =
+  | { type: "WIDGET_STATUS"; payload: unknown; source?: string }
+  | { type: "WIDGET_SCRIPT_LOADED"; payload: unknown; source?: string }
+  | { type: "WIDGET_SCRIPT_ERROR"; payload: unknown; source?: string }
+  | { type: "WIDGET_CONSOLE"; payload: unknown; source?: string }
+  | { type: "WIDGET_RUNTIME_ERROR"; payload: unknown; source?: string }
+  | { type: "WIDGET_UNHANDLED_REJECTION"; payload: unknown; source?: string }
+  | { type: "WIDGET_HTML_LOADED"; payload: unknown; source?: string }
+  | { type: "WEBVIEW_SHOULD_START"; payload: unknown; source?: string }
+  | { type: "WEBVIEW_NAV_STATE"; payload: unknown; source?: string }
+  | { type: "WEBVIEW_LOAD_START"; payload: unknown; source?: string }
+  | { type: "WEBVIEW_LOAD_END"; payload: unknown; source?: string }
+  | { type: "WEBVIEW_ERROR"; payload: unknown; source?: string }
+  | { type: "WEBVIEW_HTTP_ERROR"; payload: unknown; source?: string };
+
+export type ShopSenseWidgetConfig = {
+  /**
+   * Server origin that hosts the widget shell HTML (and any assets your shell loads).
+   *
+   * Default: `https://app.shopsense.pro`
+   */
+  baseUrl?: string;
+  zoneId: number;
+  apiBase?: string;
+  uiDensity?: UiDensity;
+  /**
+   * Full URL path on your server that hosts the widget shell HTML.
+   * Example: "/embed/widget.html" or "/widget/search".
+   *
+   * The package never hardcodes any UI; your server serves the full HTML/JS/CSS.
+   */
+  widgetPath?: string;
+  /**
+   * Additional query params to include in the URL to your server page.
+   * Useful for A/B tests or tenant routing.
+   */
+  extraParams?: Record<string, string | number | boolean | undefined>;
+};
+
+export type ShopSenseWidgetProps = ShopSenseWidgetConfig & {
+  /**
+   * Called when the user taps a product in the widget.
+   * If provided, overrides the default deep link navigation (app.shopsense://product/:id/:alias).
+   */
+  onProductSelect?: (product: ShopSenseProductSelect) => void;
+  /**
+   * Raw message handler for all messages coming from the WebView.
+   * Called after internal handling unless prevented by errors.
+   */
+  onMessage?: (message: unknown) => void;
+  /**
+   * Optional debug event handler. Receives widget diagnostics:
+   * WIDGET_STATUS, WIDGET_SCRIPT_LOADED/ERROR, WIDGET_CONSOLE, runtime errors, etc.
+   */
+  onDebugMessage?: (msg: ShopSenseDebugMessage) => void;
+  /**
+   * Whether the widget should show itself when the containing screen is focused,
+   * and hide when unfocused, while staying mounted for persistence.
+   *
+   * Default: true (requires ShopSenseProvider).
+   */
+  autoShowOnFocus?: boolean;
+};
+

package/src/url.ts

@@ -0,0 +1,39 @@
+import type { ShopSenseWidgetConfig } from "./types";
+
+export const DEFAULT_BASE_URL = "https://app.shopsense.pro";
+
+function trimTrailingSlash(v: string) {
+  return v.replace(/\/+$/, "");
+}
+
+function ensureLeadingSlash(v: string) {
+  if (!v) return "/";
+  return v.startsWith("/") ? v : `/${v}`;
+}
+
+export function buildWidgetUri(config: ShopSenseWidgetConfig): string {
+  const base = trimTrailingSlash(config.baseUrl ?? DEFAULT_BASE_URL);
+  const path = ensureLeadingSlash(config.widgetPath ?? "/embed/widget.html");
+
+  const url = new URL(`${base}${path}`);
+  url.searchParams.set("zone", String(config.zoneId));
+
+  if (config.apiBase) {
+    url.searchParams.set("apiBase", config.apiBase);
+  }
+  if (config.uiDensity) {
+    url.searchParams.set("uiDensity", config.uiDensity);
+  }
+
+  const extra = config.extraParams ?? {};
+  for (const [k, v] of Object.entries(extra)) {
+    if (v === undefined) continue;
+    url.searchParams.set(k, String(v));
+  }
+
+  // Force a stable URL ordering for easier debugging.
+  url.searchParams.sort();
+
+  return url.toString();
+}
+

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM"],
+    "jsx": "react",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}
+