shopsense-mobile 0.1.0

package/CURSOR_INTEGRATION_PROMPT.md

@@ -0,0 +1,147 @@
+# Cursor Agent: Integrate `shopsense-widget` (Expo / React Native)
+
+Paste this file into **Cursor Agent**, or click **Open in Cursor** in `README.md` to load the same instructions via Cursor’s prompt deeplink (`cursor.com/link/prompt`).
+
+## Context
+
+`shopsense-widget` provides `ShopSenseRoot`, `ShopSenseWidget`, and `PersistentWebView` for a ShopSense WebView shell. With `ShopSenseRoot` at the app root, `ShopSenseWidget` registers config and renders **nothing**; the visible UI is `PersistentWebView`.
+
+## Requirements
+
+1. **Dependencies**  
+   Ensure the app depends on `shopsense-widget`, `react-native-webview`, and `expo-router` (peer deps).
+
+2. **Root layout**  
+   - Wrap the app in `ShopSenseRoot` once.  
+   - Do **not** place `PersistentWebView` as a direct **flex sibling** of the Expo `Stack` at root — both would use `flex: 1` and split the screen ~50/50. Either remove root `PersistentWebView` and mount it on the search screen below the app bar, or use a different layout that does not share vertical flex with the navigator.
+
+3. **Search screen**  
+   - Use your existing screen wrapper (e.g. `RootLayout` with `showScrollView={false}`).  
+   - Ensure the non-scroll branch wraps children in `View` with `{ flex: 1, minHeight: 0 }` so height flows to children.  
+   - Inside that screen, render:
+     - `ShopSenseWidget` with `zoneId`, `baseUrl`, `apiBase`, and optional callbacks (`onProductSelect`, `onDebugMessage`).  
+     - `PersistentWebView` as a **sibling** in a `View` with `{ flex: 1, minHeight: 0 }` so the WebView fills the area **below** the app bar.
+   - Implement **fallback** (native search) using widget-driven status:
+     - The package emits `WIDGET_STATUS` and `WEBVIEW_*` events via `onDebugMessage`.
+     - Use `statusTimeoutMs` (default `10000`) so a slow/down server fails fast and your UI can switch to fallback.
+     - When `WIDGET_STATUS.payload.state === "failed"` (including timeout) or when `WEBVIEW_ERROR/WEBVIEW_HTTP_ERROR` occurs, conditionally render your fallback screen (e.g. `app/app/search.jsx`) instead of leaving the user stuck.
+
+4. **Callbacks**  
+   Wire `onProductSelect` to your navigation or cart flow; optionally log `onDebugMessage` during development.
+
+5. **Verify**  
+   Open the search route: the WebView should fill the full height below the header with no large empty band above the widget.
+
+## Minimal screen shape (illustrative)
+
+```tsx
+import { PersistentWebView, ShopSenseWidget } from "shopsense-widget";
+import { View } from "react-native";
+
+// Inside your layout component that already renders the app bar:
+<View style={{ flex: 1, minHeight: 0 }}>
+  <ShopSenseWidget
+    zoneId={YOUR_ZONE_ID}
+    baseUrl="https://your-widget-host"
+    apiBase="https://your-widget-host/api/api"
+    onProductSelect={(product) => {
+      /* navigate or handle */
+    }}
+  />
+  <PersistentWebView />
+</View>
+```
+
+Adjust imports and layout names to match your app.
+
+## Reference implementation (copy/paste)
+
+This is a working example from `app/app/shopsense-search.jsx` showing:
+
+- Passing `extraParams` only when logged in
+- Using `statusTimeoutMs` to fail fast
+- Conditional rendering of `app/app/search.jsx` as fallback when the widget fails
+
+```jsx
+import { router } from "expo-router";
+import React, { useCallback, useMemo, useState } from "react";
+import { View } from "react-native";
+import { useSelector } from "react-redux";
+import { PersistentWebView, ShopSenseWidget } from "shopsense-widget";
+import RootLayout from "../src/modules/shared/RootLayout/RootLayout";
+import { SCREENS } from "../src/modules/shared/constants";
+import { getStateId } from "../src/modules/shared/utils";
+import SearchFallback from "./search";
+
+export default function ShopSenseSearchScreen() {
+  const token = useSelector((state) => state?.authReducer?.tokens?.accessToken);
+  const user = useSelector((state) => state?.authReducer?.user);
+  const [showFallback, setShowFallback] = useState(false);
+
+  const extraParams = useMemo(() => {
+    if (!token) return undefined;
+
+    return {
+      customerTier: user?.tier,
+      pricingTier: user?.pricingTier,
+      stateId: getStateId?.(user) ?? undefined,
+      viewSpecificCategory: user?.viewSpecificCategory,
+      viewSpecificProduct: user?.viewSpecificProduct,
+    };
+  }, [token, user]);
+
+  const handleDebugMessage = useCallback((msg) => {
+    if (msg?.type === "WIDGET_STATUS") {
+      const state = msg?.payload?.state;
+      if (state === "failed") {
+        setShowFallback(true);
+        return;
+      }
+      if (state === "succeeded") {
+        setShowFallback(false);
+      }
+    }
+
+    if (msg?.type === "WEBVIEW_ERROR" || msg?.type === "WEBVIEW_HTTP_ERROR") {
+      setShowFallback(true);
+    }
+  }, []);
+
+  if (showFallback) {
+    return <SearchFallback />;
+  }
+
+  return (
+    <RootLayout showScrollView={false} title="Search">
+      <View style={{ flex: 1, minHeight: 0 }}>
+        <ShopSenseWidget
+          baseUrl="https://dev.shopsense.pro"
+          apiBase="https://dev.shopsense.pro/api/api"
+          zoneId={35}
+          extraParams={extraParams}
+          statusTimeoutMs={10000}
+          onProductSelect={() => {
+            const product = {
+              alias:
+                "coca-cola-beverage-soda-can-12oz-ct-12ct-bx-2bx-cs-24ct-cs-original",
+              productId: 85721,
+            };
+
+            router.push({
+              pathname: SCREENS.PRODUCT_DETAILS,
+              params: { id: product.productId, alias: product.alias },
+            });
+          }}
+          onDebugMessage={handleDebugMessage}
+        />
+
+        <PersistentWebView />
+      </View>
+    </RootLayout>
+  );
+}
+```
+
+---
+
+If you change this file, update the `[cursor-integration]` link at the bottom of `README.md` (re-encode the same `Task:` + reference block with `encodeURIComponent` for `https://cursor.com/link/prompt?text=…`).

package/README.md

@@ -0,0 +1,117 @@
+## shopsense-widget (React Native)
+
+Thin WebView shell for the ShopSense widget.
+
+### Cursor: implement this package in one click
+
+Click **[ⓘ Open integration prompt in Cursor][cursor-integration]** to open Cursor with a pre-filled Agent prompt (official [`cursor.com/link/prompt`](https://cursor.com/docs/integrations/deeplinks#prompts) deeplink). It includes the full checklist from [`CURSOR_INTEGRATION_PROMPT.md`](./CURSOR_INTEGRATION_PROMPT.md). If the link does not open the app, paste that file’s contents into **Cursor Agent** instead.
+
+### 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)
+  - Can keep the WebView **persisted** (depends on where you mount `PersistentWebView`; root vs screen trade-offs are described below)
+
+### 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 `PersistentWebView` (layout matters)
+
+`PersistentWebView` must not be a **flex sibling** of your root navigator (e.g. Expo Router `Stack`) with both using `flex: 1` — that splits the screen ~50/50 and shrinks the WebView.
+
+**Recommended:** mount `PersistentWebView` on the screen that shows the widget, **below** your app bar, inside a `View` with `{ flex: 1, minHeight: 0 }`, next to `ShopSenseWidget` (see step 3). That fills the height under the header correctly.
+
+**Alternative (single root mount):** keep one `PersistentWebView` at the app root only if you position it so it does not share vertical flex with the navigator (for example absolute fill behind transparent content — more complex). Prefer co-locating with the search screen unless you need the WebView to stay mounted across all routes.
+
+#### 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. Render `PersistentWebView` in the **same** flex container (below your header) so the WebView receives height.
+
+```tsx
+import { PersistentWebView, ShopSenseWidget } from "shopsense-widget";
+import { View } from "react-native";
+
+export default function SearchScreen() {
+  return (
+    <View style={{ flex: 1, minHeight: 0 }}>
+      <ShopSenseWidget
+        zoneId={35}
+        // Optional: fail fast if the widget doesn't become ready (default: 10000ms)
+        statusTimeoutMs={10000}
+        onProductSelect={(product) => {
+          // override default deep link navigation
+          // product = { id, alias }
+        }}
+        onDebugMessage={(msg) => {
+          // optional: WIDGET_STATUS / console / errors
+          console.log(msg);
+        }}
+      />
+      <PersistentWebView />
+    </View>
+  );
+}
+```
+
+Wrap that block in your own layout (app bar, safe area) as needed.
+
+### 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).
+
+#### `statusTimeoutMs`
+
+Optional. Maximum time (ms) to wait for the widget to report `WIDGET_STATUS: succeeded` after a WebView load starts.
+
+- **default**: `10000`
+- **behavior**: on timeout, the package emits `WIDGET_STATUS` with `payload.state = "failed"` and `payload.error.message = "timeout"` so your app can conditionally render a fallback UI.
+
+### 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.
+
+[cursor-integration]: https://cursor.com/link/prompt?text=Task%3A%20Integrate%20the%20%60shopsense-widget%60%20package%20into%20this%20Expo%20(expo-router)%20React%20Native%20app.%0A%0AFirst%20open%20and%20follow%20%60packages%2Fshopsense-widget%2FCURSOR_INTEGRATION_PROMPT.md%60%20in%20the%20workspace.%20Implement%20all%20steps%20there.%0A%0A---%20Reference%20(same%20as%20that%20file)%20---%0A%23%20Cursor%20Agent%3A%20Integrate%20%60shopsense-widget%60%20(Expo%20%2F%20React%20Native)%0A%0APaste%20this%20file%20into%20**Cursor%20Agent**%2C%20or%20click%20**Open%20in%20Cursor**%20in%20%60README.md%60%20to%20load%20the%20same%20instructions%20via%20Cursor%E2%80%99s%20prompt%20deeplink%20(%60cursor.com%2Flink%2Fprompt%60).%0A%0A%23%23%20Context%0A%0A%60shopsense-widget%60%20provides%20%60ShopSenseRoot%60%2C%20%60ShopSenseWidget%60%2C%20and%20%60PersistentWebView%60%20for%20a%20ShopSense%20WebView%20shell.%20With%20%60ShopSenseRoot%60%20at%20the%20app%20root%2C%20%60ShopSenseWidget%60%20registers%20config%20and%20renders%20**nothing**%3B%20the%20visible%20UI%20is%20%60PersistentWebView%60.%0A%0A%23%23%20Requirements%0A%0A1.%20**Dependencies**%20%20%0A%20%20%20Ensure%20the%20app%20depends%20on%20%60shopsense-widget%60%2C%20%60react-native-webview%60%2C%20and%20%60expo-router%60%20(peer%20deps).%0A%0A2.%20**Root%20layout**%20%20%0A%20%20%20-%20Wrap%20the%20app%20in%20%60ShopSenseRoot%60%20once.%20%20%0A%20%20%20-%20Do%20**not**%20place%20%60PersistentWebView%60%20as%20a%20direct%20**flex%20sibling**%20of%20the%20Expo%20%60Stack%60%20at%20root%20%E2%80%94%20both%20would%20use%20%60flex%3A%201%60%20and%20split%20the%20screen%20~50%2F50.%20Either%20remove%20root%20%60PersistentWebView%60%20and%20mount%20it%20on%20the%20search%20screen%20below%20the%20app%20bar%2C%20or%20use%20a%20different%20layout%20that%20does%20not%20share%20vertical%20flex%20with%20the%20navigator.%0A%0A3.%20**Search%20screen**%20%20%0A%20%20%20-%20Use%20your%20existing%20screen%20wrapper%20(e.g.%20%60RootLayout%60%20with%20%60showScrollView%3D%7Bfalse%7D%60).%20%20%0A%20%20%20-%20Ensure%20the%20non-scroll%20branch%20wraps%20children%20in%20%60View%60%20with%20%60%7B%20flex%3A%201%2C%20minHeight%3A%200%20%7D%60%20so%20height%20flows%20to%20children.%20%20%0A%20%20%20-%20Inside%20that%20screen%2C%20render%3A%0A%20%20%20%20%20-%20%60ShopSenseWidget%60%20with%20%60zoneId%60%2C%20%60baseUrl%60%2C%20%60apiBase%60%2C%20and%20optional%20callbacks%20(%60onProductSelect%60%2C%20%60onDebugMessage%60).%20%20%0A%20%20%20%20%20-%20%60PersistentWebView%60%20as%20a%20**sibling**%20in%20a%20%60View%60%20with%20%60%7B%20flex%3A%201%2C%20minHeight%3A%200%20%7D%60%20so%20the%20WebView%20fills%20the%20area%20**below**%20the%20app%20bar.%0A%20%20%20-%20Implement%20**fallback**%20(native%20search)%20using%20widget-driven%20status%3A%0A%20%20%20%20%20-%20The%20package%20emits%20%60WIDGET_STATUS%60%20and%20%60WEBVIEW_*%60%20events%20via%20%60onDebugMessage%60.%0A%20%20%20%20%20-%20Use%20%60statusTimeoutMs%60%20(default%20%6010000%60)%20so%20a%20slow%2Fdown%20server%20fails%20fast%20and%20your%20UI%20can%20switch%20to%20fallback.%0A%20%20%20%20%20-%20When%20%60WIDGET_STATUS.payload.state%20%3D%3D%3D%20%22failed%22%60%20(including%20timeout)%20or%20when%20%60WEBVIEW_ERROR%2FWEBVIEW_HTTP_ERROR%60%20occurs%2C%20conditionally%20render%20your%20fallback%20screen%20(e.g.%20%60app%2Fapp%2Fsearch.jsx%60)%20instead%20of%20leaving%20the%20user%20stuck.%0A%0A4.%20**Callbacks**%20%20%0A%20%20%20Wire%20%60onProductSelect%60%20to%20your%20navigation%20or%20cart%20flow%3B%20optionally%20log%20%60onDebugMessage%60%20during%20development.%0A%0A5.%20**Verify**%20%20%0A%20%20%20Open%20the%20search%20route%3A%20the%20WebView%20should%20fill%20the%20full%20height%20below%20the%20header%20with%20no%20large%20empty%20band%20above%20the%20widget.%0A%0A%23%23%20Minimal%20screen%20shape%20(illustrative)%0A%0A%60%60%60tsx%0Aimport%20%7B%20PersistentWebView%2C%20ShopSenseWidget%20%7D%20from%20%22shopsense-widget%22%3B%0Aimport%20%7B%20View%20%7D%20from%20%22react-native%22%3B%0A%0A%2F%2F%20Inside%20your%20layout%20component%20that%20already%20renders%20the%20app%20bar%3A%0A%3CView%20style%3D%7B%7B%20flex%3A%201%2C%20minHeight%3A%200%20%7D%7D%3E%0A%20%20%3CShopSenseWidget%0A%20%20%20%20zoneId%3D%7BYOUR_ZONE_ID%7D%0A%20%20%20%20baseUrl%3D%22https%3A%2F%2Fyour-widget-host%22%0A%20%20%20%20apiBase%3D%22https%3A%2F%2Fyour-widget-host%2Fapi%2Fapi%22%0A%20%20%20%20onProductSelect%3D%7B(product)%20%3D%3E%20%7B%0A%20%20%20%20%20%20%2F*%20navigate%20or%20handle%20*%2F%0A%20%20%20%20%7D%7D%0A%20%20%2F%3E%0A%20%20%3CPersistentWebView%20%2F%3E%0A%3C%2FView%3E%0A%60%60%60%0A%0AAdjust%20imports%20and%20layout%20names%20to%20match%20your%20app.%0A%0A%23%23%20Reference%20implementation%20(copy%2Fpaste)%0A%0AThis%20is%20a%20working%20example%20from%20%60app%2Fapp%2Fshopsense-search.jsx%60%20showing%3A%0A%0A-%20Passing%20%60extraParams%60%20only%20when%20logged%20in%0A-%20Using%20%60statusTimeoutMs%60%20to%20fail%20fast%0A-%20Conditional%20rendering%20of%20%60app%2Fapp%2Fsearch.jsx%60%20as%20fallback%20when%20the%20widget%20fails%0A%0A%60%60%60jsx%0Aimport%20%7B%20router%20%7D%20from%20%22expo-router%22%3B%0Aimport%20React%2C%20%7B%20useCallback%2C%20useMemo%2C%20useState%20%7D%20from%20%22react%22%3B%0Aimport%20%7B%20View%20%7D%20from%20%22react-native%22%3B%0Aimport%20%7B%20useSelector%20%7D%20from%20%22react-redux%22%3B%0Aimport%20%7B%20PersistentWebView%2C%20ShopSenseWidget%20%7D%20from%20%22shopsense-widget%22%3B%0Aimport%20RootLayout%20from%20%22..%2Fsrc%2Fmodules%2Fshared%2FRootLayout%2FRootLayout%22%3B%0Aimport%20%7B%20SCREENS%20%7D%20from%20%22..%2Fsrc%2Fmodules%2Fshared%2Fconstants%22%3B%0Aimport%20%7B%20getStateId%20%7D%20from%20%22..%2Fsrc%2Fmodules%2Fshared%2Futils%22%3B%0Aimport%20SearchFallback%20from%20%22.%2Fsearch%22%3B%0A%0Aexport%20default%20function%20ShopSenseSearchScreen()%20%7B%0A%20%20const%20token%20%3D%20useSelector((state)%20%3D%3E%20state%3F.authReducer%3F.tokens%3F.accessToken)%3B%0A%20%20const%20user%20%3D%20useSelector((state)%20%3D%3E%20state%3F.authReducer%3F.user)%3B%0A%20%20const%20%5BshowFallback%2C%20setShowFallback%5D%20%3D%20useState(false)%3B%0A%0A%20%20const%20extraParams%20%3D%20useMemo(()%20%3D%3E%20%7B%0A%20%20%20%20if%20(!token)%20return%20undefined%3B%0A%0A%20%20%20%20return%20%7B%0A%20%20%20%20%20%20customerTier%3A%20user%3F.tier%2C%0A%20%20%20%20%20%20pricingTier%3A%20user%3F.pricingTier%2C%0A%20%20%20%20%20%20stateId%3A%20getStateId%3F.(user)%20%3F%3F%20undefined%2C%0A%20%20%20%20%20%20viewSpecificCategory%3A%20user%3F.viewSpecificCategory%2C%0A%20%20%20%20%20%20viewSpecificProduct%3A%20user%3F.viewSpecificProduct%2C%0A%20%20%20%20%7D%3B%0A%20%20%7D%2C%20%5Btoken%2C%20user%5D)%3B%0A%0A%20%20const%20handleDebugMessage%20%3D%20useCallback((msg)%20%3D%3E%20%7B%0A%20%20%20%20if%20(msg%3F.type%20%3D%3D%3D%20%22WIDGET_STATUS%22)%20%7B%0A%20%20%20%20%20%20const%20state%20%3D%20msg%3F.payload%3F.state%3B%0A%20%20%20%20%20%20if%20(state%20%3D%3D%3D%20%22failed%22)%20%7B%0A%20%20%20%20%20%20%20%20setShowFallback(true)%3B%0A%20%20%20%20%20%20%20%20return%3B%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20if%20(state%20%3D%3D%3D%20%22succeeded%22)%20%7B%0A%20%20%20%20%20%20%20%20setShowFallback(false)%3B%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%0A%20%20%20%20if%20(msg%3F.type%20%3D%3D%3D%20%22WEBVIEW_ERROR%22%20%7C%7C%20msg%3F.type%20%3D%3D%3D%20%22WEBVIEW_HTTP_ERROR%22)%20%7B%0A%20%20%20%20%20%20setShowFallback(true)%3B%0A%20%20%20%20%7D%0A%20%20%7D%2C%20%5B%5D)%3B%0A%0A%20%20if%20(showFallback)%20%7B%0A%20%20%20%20return%20%3CSearchFallback%20%2F%3E%3B%0A%20%20%7D%0A%0A%20%20return%20(%0A%20%20%20%20%3CRootLayout%20showScrollView%3D%7Bfalse%7D%20title%3D%22Search%22%3E%0A%20%20%20%20%20%20%3CView%20style%3D%7B%7B%20flex%3A%201%2C%20minHeight%3A%200%20%7D%7D%3E%0A%20%20%20%20%20%20%20%20%3CShopSenseWidget%0A%20%20%20%20%20%20%20%20%20%20baseUrl%3D%22https%3A%2F%2Fdev.shopsense.pro%22%0A%20%20%20%20%20%20%20%20%20%20apiBase%3D%22https%3A%2F%2Fdev.shopsense.pro%2Fapi%2Fapi%22%0A%20%20%20%20%20%20%20%20%20%20zoneId%3D%7B35%7D%0A%20%20%20%20%20%20%20%20%20%20extraParams%3D%7BextraParams%7D%0A%20%20%20%20%20%20%20%20%20%20statusTimeoutMs%3D%7B10000%7D%0A%20%20%20%20%20%20%20%20%20%20onProductSelect%3D%7B()%20%3D%3E%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20const%20product%20%3D%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20alias%3A%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22coca-cola-beverage-soda-can-12oz-ct-12ct-bx-2bx-cs-24ct-cs-original%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20productId%3A%2085721%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%3B%0A%0A%20%20%20%20%20%20%20%20%20%20%20%20router.push(%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20pathname%3A%20SCREENS.PRODUCT_DETAILS%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20params%3A%20%7B%20id%3A%20product.productId%2C%20alias%3A%20product.alias%20%7D%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D)%3B%0A%20%20%20%20%20%20%20%20%20%20%7D%7D%0A%20%20%20%20%20%20%20%20%20%20onDebugMessage%3D%7BhandleDebugMessage%7D%0A%20%20%20%20%20%20%20%20%2F%3E%0A%0A%20%20%20%20%20%20%20%20%3CPersistentWebView%20%2F%3E%0A%20%20%20%20%20%20%3C%2FView%3E%0A%20%20%20%20%3C%2FRootLayout%3E%0A%20%20)%3B%0A%7D%0A%60%60%60%0A%0A---%0A%0AIf%20you%20change%20this%20file%2C%20update%20the%20%60%5Bcursor-integration%5D%60%20link%20at%20the%20bottom%20of%20%60README.md%60%20(re-encode%20the%20same%20%60Task%3A%60%20%2B%20reference%20block%20with%20%60encodeURIComponent%60%20for%20%60https%3A%2F%2Fcursor.com%2Flink%2Fprompt%3Ftext%3D%E2%80%A6%60).%0A
+

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "shopsense-mobile",
+  "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,296 @@
+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, statusTimeoutMs } =
+    useShopSense();
+  const lastLoggedUrlRef = useRef(null as string | null);
+  const statusBridgeInstalledRef = useRef(false);
+  const statusTimeoutRef = useRef(null as ReturnType<typeof setTimeout> | null);
+  const lastStatusStateRef = useRef(null as string | null);
+
+  const clearStatusTimeout = useCallback(() => {
+    if (statusTimeoutRef.current) {
+      clearTimeout(statusTimeoutRef.current);
+      statusTimeoutRef.current = 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)) {
+        if (msg?.type === "WIDGET_STATUS") {
+          const nextState =
+            typeof (msg as any)?.payload?.state === "string"
+              ? String((msg as any).payload.state)
+              : null;
+          if (nextState) {
+            lastStatusStateRef.current = nextState;
+            if (nextState === "succeeded" || nextState === "failed") {
+              clearStatusTimeout();
+            }
+          }
+        }
+        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]
+  );
+
+  const injectStatusBridge = useCallback(() => {
+    const wv = webViewRef?.current as any;
+    if (!wv?.injectJavaScript) return;
+
+    // Install once per WebView lifetime; it survives navigations within the same document.
+    if (statusBridgeInstalledRef.current) return;
+    statusBridgeInstalledRef.current = true;
+
+    wv.injectJavaScript(
+      `(function(){try{
+        if (window.__shopsenseStatusBridgeInstalled) return true;
+        window.__shopsenseStatusBridgeInstalled = true;
+
+        var lastKey = '';
+        function post(type, payload){
+          try{
+            var wv = window.ReactNativeWebView;
+            if (!wv || !wv.postMessage) return;
+            wv.postMessage(JSON.stringify({ type: type, payload: payload, source: 'web' }));
+          }catch(e){}
+        }
+
+        function snapshotStatus(){
+          try{
+            var s = window.ShopSenseWidgetStatus;
+            if (!s) return;
+            var key = '';
+            try{ key = JSON.stringify(s); }catch(e){ key = String(s && s.state); }
+            if (key && key !== lastKey) {
+              lastKey = key;
+              post('WIDGET_STATUS', s);
+            }
+          }catch(e){}
+        }
+
+        // Send as soon as possible, then poll for updates.
+        snapshotStatus();
+        window.addEventListener('load', snapshotStatus, { once: true });
+        setInterval(snapshotStatus, 500);
+      }catch(e){};return true;})();`
+    );
+  }, [webViewRef]);
+
+  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 },
+          });
+
+          clearStatusTimeout();
+          lastStatusStateRef.current = null;
+
+          const timeoutMs =
+            typeof statusTimeoutMs === "number" ? statusTimeoutMs : 10000;
+          if (timeoutMs > 0) {
+            statusTimeoutRef.current = setTimeout(() => {
+              // Only fail if we didn't already get a terminal status.
+              if (
+                lastStatusStateRef.current === "succeeded" ||
+                lastStatusStateRef.current === "failed"
+              ) {
+                return;
+              }
+              callbacksRef.current.onDebugMessage?.({
+                type: "WIDGET_STATUS",
+                source: "native",
+                payload: {
+                  state: "failed",
+                  updatedAt: Date.now(),
+                  error: { message: "timeout" },
+                },
+              });
+            }, timeoutMs);
+          }
+        }}
+        onLoadEnd={(e: any) => {
+          callbacksRef.current.onDebugMessage?.({
+            type: "WEBVIEW_LOAD_END",
+            source: "native",
+            payload: { url: e?.nativeEvent?.url },
+          });
+          // Ensure we can observe widget loader status (window.ShopSenseWidgetStatus)
+          // and forward it as WIDGET_STATUS via the normal onDebugMessage pipeline.
+          injectStatusBridge();
+        }}
+        onError={(e: any) => {
+          clearStatusTimeout();
+          callbacksRef.current.onDebugMessage?.({
+            type: "WEBVIEW_ERROR",
+            source: "native",
+            payload: e?.nativeEvent,
+          });
+        }}
+        onHttpError={(e: any) => {
+          clearStatusTimeout();
+          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: {
+    ...StyleSheet.absoluteFillObject,
+    backgroundColor: "#fff",
+    overflow: "hidden",
+  },
+  hidden: {
+    // Keep the WebView mounted & full size but invisible (so it can preload).
+    opacity: 0,
+  },
+  webview: {
+    flex: 1,
+    backgroundColor: "transparent",
+  },
+});
+

package/src/ShopSenseWidget.tsx

@@ -0,0 +1,109 @@
+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,
+    statusTimeoutMs,
+    autoShowOnFocus = true,
+    ...config
+  } = props;
+
+  const ctx = useShopSense();
+  const { callbacksRef, setConfig, setStatusTimeoutMs, 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]);
+
+  useEffect(() => {
+    if (typeof statusTimeoutMs === "number") {
+      setStatusTimeoutMs(statusTimeoutMs);
+    }
+  }, [setStatusTimeoutMs, statusTimeoutMs]);
+
+  // 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,118 @@
+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">
+  >;
+  /** Widget status timeout override (ms). */
+  statusTimeoutMs: number;
+  setStatusTimeoutMs: (ms: number) => void;
+};
+
+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 [statusTimeoutMs, setStatusTimeoutMsState] = useState(10000);
+
+  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 setStatusTimeoutMs = useCallback((ms: number) => {
+    const next = Number.isFinite(ms) ? Math.max(0, Math.floor(ms)) : 10000;
+    setStatusTimeoutMsState(next);
+  }, []);
+
+  const value = useMemo(
+    () => ({
+      config,
+      visible,
+      setConfig,
+      show,
+      hide,
+      webViewRef,
+      lastWebViewUrlRef,
+      callbacksRef,
+      statusTimeoutMs,
+      setStatusTimeoutMs,
+    }),
+    [callbacksRef, config, hide, lastWebViewUrlRef, setConfig, setStatusTimeoutMs, show, statusTimeoutMs, visible, webViewRef]
+  );
+
+  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,79 @@
+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;
+  /**
+   * Max time (ms) to wait for the widget to report `WIDGET_STATUS: succeeded`
+   * after a page load begins. If exceeded, the package emits:
+   * `{ type: "WIDGET_STATUS", payload: { state: "failed", error: { message: "timeout" }, ... } }`.
+   *
+   * Default: 10000
+   */
+  statusTimeoutMs?: number;
+  /**
+   * 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"]
+}
+