@loupfeed/react 0.1.0

package/LICENSE.md

@@ -0,0 +1,114 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 loupfeed
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to use,
+copy, modify, create derivative works, publicly perform, publicly display and
+redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or service
+that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software that
+   exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee using
+   the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to the
+infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software, you
+must include a copy of or a link to these Terms and Conditions and not remove any
+copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, INCLUDING
+BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, NON-INFRINGEMENT AND TITLE.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN
+IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of the
+Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following will
+apply:
+
+We hereby grant you a license to the Software under the Apache License, Version
+2.0, a copy of which is available at https://www.apache.org/licenses/LICENSE-2.0.
+
+---
+
+## In plain language (non-binding summary)
+
+This is a **Fair Source** license. You can:
+
+- **Self-host and run loupfeed** for your own purposes — including inside a
+  company, on your own servers or cloud account, for your own products.
+- Read, modify, fork, and redistribute the source.
+
+The one thing you may **not** do is offer loupfeed (or something substantially
+similar built from it) **as a competing commercial product or hosted service**.
+
+Two years after each release is published, that version automatically becomes
+available to you under the **Apache License 2.0** (fully open source).
+
+This summary is for convenience only; the Terms and Conditions above govern.

package/dist/index.cjs

@@ -0,0 +1,114 @@
+'use strict';
+
+var react = require('react');
+var core = require('@loupfeed/core');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/index.tsx
+var FeedbackCtx = react.createContext(null);
+function installNavigationBreadcrumbs() {
+  if (typeof window === "undefined") return () => {
+  };
+  let last = window.location.pathname + window.location.search;
+  const record = () => {
+    const to = window.location.pathname + window.location.search;
+    if (to === last) return;
+    core.addBreadcrumb({ category: "navigation", message: `${last} \u2192 ${to}`, data: { from: last, to } });
+    core.setContext("request", { url: window.location.href, route: window.location.pathname });
+    last = to;
+  };
+  const origPush = history.pushState;
+  const origReplace = history.replaceState;
+  history.pushState = function(...args) {
+    const r = origPush.apply(this, args);
+    record();
+    return r;
+  };
+  history.replaceState = function(...args) {
+    const r = origReplace.apply(this, args);
+    record();
+    return r;
+  };
+  window.addEventListener("popstate", record);
+  return () => {
+    history.pushState = origPush;
+    history.replaceState = origReplace;
+    window.removeEventListener("popstate", record);
+  };
+}
+function installClickBreadcrumbs() {
+  if (typeof window === "undefined") return () => {
+  };
+  const onClick = (e) => {
+    if (core.overlay.isInspecting()) return;
+    const target = e.target;
+    const el = target?.closest('button, a, [role="button"], input[type="submit"]');
+    if (!el) return;
+    const text = (el.textContent ?? "").trim().slice(0, 60) || el.getAttribute("aria-label") || el.tagName.toLowerCase();
+    core.addBreadcrumb({
+      category: "ui.click",
+      level: "info",
+      message: text,
+      data: { tag: el.tagName.toLowerCase() }
+    });
+  };
+  window.addEventListener("click", onClick, true);
+  return () => window.removeEventListener("click", onClick, true);
+}
+function FeedbackProvider({
+  children,
+  root,
+  router = "history",
+  overlay: overlayOpts,
+  captureClicks = true
+}) {
+  const [isInspecting, setIsInspecting] = react.useState(false);
+  react.useEffect(() => {
+    if (typeof document === "undefined") return;
+    const rootEl = root?.current ?? document.body;
+    const unmountOverlay = core.mountOverlay({
+      ...overlayOpts,
+      root: rootEl,
+      onSubmit: async (input) => {
+        await core.captureFeedback(input);
+      }
+    });
+    const teardowns = [unmountOverlay];
+    if (router !== "none") teardowns.push(installNavigationBreadcrumbs());
+    if (captureClicks) teardowns.push(installClickBreadcrumbs());
+    return () => teardowns.forEach((fn) => fn());
+  }, []);
+  const value = react.useMemo(
+    () => ({
+      openInspector: () => {
+        core.overlay.open();
+        setIsInspecting(true);
+      },
+      closeInspector: () => {
+        core.overlay.close();
+        setIsInspecting(false);
+      },
+      submit: (input) => core.captureFeedback(input),
+      isInspecting,
+      isRecording: core.replay.isRecording()
+    }),
+    [isInspecting]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(FeedbackCtx.Provider, { value, children });
+}
+function useFeedback() {
+  const ctx = react.useContext(FeedbackCtx);
+  if (!ctx) throw new Error("useFeedback() must be used within <FeedbackProvider>");
+  return ctx;
+}
+
+exports.FeedbackProvider = FeedbackProvider;
+exports.useFeedback = useFeedback;
+Object.keys(core).forEach(function (k) {
+  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function () { return core[k]; }
+  });
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":["createContext","addBreadcrumb","setContext","overlay","useState","useEffect","mountOverlay","captureFeedback","useMemo","replay","jsx","useContext"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @loupfeed/react — thin adapter. The engine lives in @loupfeed/core; this only\n * (a) mounts the overlay into the React tree, and (b) wires router/click\n * breadcrumbs into the scope/context API.\n *\n * NOTE: the Vite plugin is intentionally NOT re-exported here. A runtime adapter\n * must never import a build package (privacy invariant, doc 03). Import the\n * plugin directly from `@loupfeed/vite-plugin` in your `vite.config`.\n */\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n  type ReactNode,\n  type RefObject,\n} from 'react';\nimport {\n  addBreadcrumb,\n  captureFeedback,\n  mountOverlay,\n  overlay,\n  replay,\n  setContext,\n  type FeedbackInput,\n  type OverlayOptions,\n} from '@loupfeed/core';\n\n// Re-export the full core public surface (init, scope API, types, …).\nexport * from '@loupfeed/core';\n\ntype FeedbackContextValue = {\n  /** Enter element-inspect mode. */\n  openInspector(): void;\n  /** Leave inspect mode / close any open composer. */\n  closeInspector(): void;\n  /** Submit feedback programmatically. */\n  submit(input: FeedbackInput): Promise<string>;\n  /** Reflects programmatic inspect toggles (not the built-in launcher). */\n  isInspecting: boolean;\n  /** Session replay is deferred in the MVP — always false. */\n  isRecording: boolean;\n};\n\nconst FeedbackCtx = createContext<FeedbackContextValue | null>(null);\n\nexport interface FeedbackProviderProps {\n  children: ReactNode;\n  /**\n   * Root the selector engine generates structural paths relative to.\n   * Defaults to `document.body`.\n   */\n  root?: RefObject<Element | null>;\n  /** Router integration for auto-navigation breadcrumbs. Default 'history'. */\n  router?: 'react-router' | 'tanstack' | 'history' | 'none';\n  /** Overlay appearance/behavior (accent color, z-index, …). */\n  overlay?: Omit<OverlayOptions, 'root' | 'onSubmit'>;\n  /** Record `ui.click` breadcrumbs for button/link clicks. Default true. */\n  captureClicks?: boolean;\n}\n\nfunction installNavigationBreadcrumbs(): () => void {\n  if (typeof window === 'undefined') return () => {};\n  let last = window.location.pathname + window.location.search;\n  const record = () => {\n    const to = window.location.pathname + window.location.search;\n    if (to === last) return;\n    addBreadcrumb({ category: 'navigation', message: `${last} → ${to}`, data: { from: last, to } });\n    setContext('request', { url: window.location.href, route: window.location.pathname });\n    last = to;\n  };\n  const origPush = history.pushState;\n  const origReplace = history.replaceState;\n  history.pushState = function (this: History, ...args: Parameters<History['pushState']>) {\n    const r = origPush.apply(this, args);\n    record();\n    return r;\n  };\n  history.replaceState = function (this: History, ...args: Parameters<History['replaceState']>) {\n    const r = origReplace.apply(this, args);\n    record();\n    return r;\n  };\n  window.addEventListener('popstate', record);\n  return () => {\n    history.pushState = origPush;\n    history.replaceState = origReplace;\n    window.removeEventListener('popstate', record);\n  };\n}\n\nfunction installClickBreadcrumbs(): () => void {\n  if (typeof window === 'undefined') return () => {};\n  const onClick = (e: MouseEvent) => {\n    if (overlay.isInspecting()) return; // inspect-mode clicks aren't app interactions\n    const target = e.target as Element | null;\n    const el = target?.closest('button, a, [role=\"button\"], input[type=\"submit\"]');\n    if (!el) return;\n    const text =\n      (el.textContent ?? '').trim().slice(0, 60) ||\n      el.getAttribute('aria-label') ||\n      el.tagName.toLowerCase();\n    addBreadcrumb({\n      category: 'ui.click',\n      level: 'info',\n      message: text,\n      data: { tag: el.tagName.toLowerCase() },\n    });\n  };\n  window.addEventListener('click', onClick, true);\n  return () => window.removeEventListener('click', onClick, true);\n}\n\nexport function FeedbackProvider({\n  children,\n  root,\n  router = 'history',\n  overlay: overlayOpts,\n  captureClicks = true,\n}: FeedbackProviderProps): JSX.Element {\n  const [isInspecting, setIsInspecting] = useState(false);\n\n  useEffect(() => {\n    if (typeof document === 'undefined') return;\n    const rootEl = root?.current ?? document.body;\n    const unmountOverlay = mountOverlay({\n      ...overlayOpts,\n      root: rootEl,\n      onSubmit: async (input) => {\n        await captureFeedback(input);\n      },\n    });\n    const teardowns: Array<() => void> = [unmountOverlay];\n    if (router !== 'none') teardowns.push(installNavigationBreadcrumbs());\n    if (captureClicks) teardowns.push(installClickBreadcrumbs());\n    return () => teardowns.forEach((fn) => fn());\n    // Mount once for the lifetime of the provider.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  const value = useMemo<FeedbackContextValue>(\n    () => ({\n      openInspector: () => {\n        overlay.open();\n        setIsInspecting(true);\n      },\n      closeInspector: () => {\n        overlay.close();\n        setIsInspecting(false);\n      },\n      submit: (input: FeedbackInput) => captureFeedback(input),\n      isInspecting,\n      isRecording: replay.isRecording(),\n    }),\n    [isInspecting],\n  );\n\n  return <FeedbackCtx.Provider value={value}>{children}</FeedbackCtx.Provider>;\n}\n\nexport function useFeedback(): FeedbackContextValue {\n  const ctx = useContext(FeedbackCtx);\n  if (!ctx) throw new Error('useFeedback() must be used within <FeedbackProvider>');\n  return ctx;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,44 @@
+import { ReactNode, RefObject } from 'react';
+import { OverlayOptions, FeedbackInput } from '@loupfeed/core';
+export * from '@loupfeed/core';
+
+/**
+ * @loupfeed/react — thin adapter. The engine lives in @loupfeed/core; this only
+ * (a) mounts the overlay into the React tree, and (b) wires router/click
+ * breadcrumbs into the scope/context API.
+ *
+ * NOTE: the Vite plugin is intentionally NOT re-exported here. A runtime adapter
+ * must never import a build package (privacy invariant, doc 03). Import the
+ * plugin directly from `@loupfeed/vite-plugin` in your `vite.config`.
+ */
+
+type FeedbackContextValue = {
+    /** Enter element-inspect mode. */
+    openInspector(): void;
+    /** Leave inspect mode / close any open composer. */
+    closeInspector(): void;
+    /** Submit feedback programmatically. */
+    submit(input: FeedbackInput): Promise<string>;
+    /** Reflects programmatic inspect toggles (not the built-in launcher). */
+    isInspecting: boolean;
+    /** Session replay is deferred in the MVP — always false. */
+    isRecording: boolean;
+};
+interface FeedbackProviderProps {
+    children: ReactNode;
+    /**
+     * Root the selector engine generates structural paths relative to.
+     * Defaults to `document.body`.
+     */
+    root?: RefObject<Element | null>;
+    /** Router integration for auto-navigation breadcrumbs. Default 'history'. */
+    router?: 'react-router' | 'tanstack' | 'history' | 'none';
+    /** Overlay appearance/behavior (accent color, z-index, …). */
+    overlay?: Omit<OverlayOptions, 'root' | 'onSubmit'>;
+    /** Record `ui.click` breadcrumbs for button/link clicks. Default true. */
+    captureClicks?: boolean;
+}
+declare function FeedbackProvider({ children, root, router, overlay: overlayOpts, captureClicks, }: FeedbackProviderProps): JSX.Element;
+declare function useFeedback(): FeedbackContextValue;
+
+export { FeedbackProvider, type FeedbackProviderProps, useFeedback };

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { ReactNode, RefObject } from 'react';
+import { OverlayOptions, FeedbackInput } from '@loupfeed/core';
+export * from '@loupfeed/core';
+
+/**
+ * @loupfeed/react — thin adapter. The engine lives in @loupfeed/core; this only
+ * (a) mounts the overlay into the React tree, and (b) wires router/click
+ * breadcrumbs into the scope/context API.
+ *
+ * NOTE: the Vite plugin is intentionally NOT re-exported here. A runtime adapter
+ * must never import a build package (privacy invariant, doc 03). Import the
+ * plugin directly from `@loupfeed/vite-plugin` in your `vite.config`.
+ */
+
+type FeedbackContextValue = {
+    /** Enter element-inspect mode. */
+    openInspector(): void;
+    /** Leave inspect mode / close any open composer. */
+    closeInspector(): void;
+    /** Submit feedback programmatically. */
+    submit(input: FeedbackInput): Promise<string>;
+    /** Reflects programmatic inspect toggles (not the built-in launcher). */
+    isInspecting: boolean;
+    /** Session replay is deferred in the MVP — always false. */
+    isRecording: boolean;
+};
+interface FeedbackProviderProps {
+    children: ReactNode;
+    /**
+     * Root the selector engine generates structural paths relative to.
+     * Defaults to `document.body`.
+     */
+    root?: RefObject<Element | null>;
+    /** Router integration for auto-navigation breadcrumbs. Default 'history'. */
+    router?: 'react-router' | 'tanstack' | 'history' | 'none';
+    /** Overlay appearance/behavior (accent color, z-index, …). */
+    overlay?: Omit<OverlayOptions, 'root' | 'onSubmit'>;
+    /** Record `ui.click` breadcrumbs for button/link clicks. Default true. */
+    captureClicks?: boolean;
+}
+declare function FeedbackProvider({ children, root, router, overlay: overlayOpts, captureClicks, }: FeedbackProviderProps): JSX.Element;
+declare function useFeedback(): FeedbackContextValue;
+
+export { FeedbackProvider, type FeedbackProviderProps, useFeedback };

package/dist/index.js

@@ -0,0 +1,106 @@
+import { createContext, useState, useEffect, useMemo, useContext } from 'react';
+import { mountOverlay, captureFeedback, replay, overlay, addBreadcrumb, setContext } from '@loupfeed/core';
+export * from '@loupfeed/core';
+import { jsx } from 'react/jsx-runtime';
+
+// src/index.tsx
+var FeedbackCtx = createContext(null);
+function installNavigationBreadcrumbs() {
+  if (typeof window === "undefined") return () => {
+  };
+  let last = window.location.pathname + window.location.search;
+  const record = () => {
+    const to = window.location.pathname + window.location.search;
+    if (to === last) return;
+    addBreadcrumb({ category: "navigation", message: `${last} \u2192 ${to}`, data: { from: last, to } });
+    setContext("request", { url: window.location.href, route: window.location.pathname });
+    last = to;
+  };
+  const origPush = history.pushState;
+  const origReplace = history.replaceState;
+  history.pushState = function(...args) {
+    const r = origPush.apply(this, args);
+    record();
+    return r;
+  };
+  history.replaceState = function(...args) {
+    const r = origReplace.apply(this, args);
+    record();
+    return r;
+  };
+  window.addEventListener("popstate", record);
+  return () => {
+    history.pushState = origPush;
+    history.replaceState = origReplace;
+    window.removeEventListener("popstate", record);
+  };
+}
+function installClickBreadcrumbs() {
+  if (typeof window === "undefined") return () => {
+  };
+  const onClick = (e) => {
+    if (overlay.isInspecting()) return;
+    const target = e.target;
+    const el = target?.closest('button, a, [role="button"], input[type="submit"]');
+    if (!el) return;
+    const text = (el.textContent ?? "").trim().slice(0, 60) || el.getAttribute("aria-label") || el.tagName.toLowerCase();
+    addBreadcrumb({
+      category: "ui.click",
+      level: "info",
+      message: text,
+      data: { tag: el.tagName.toLowerCase() }
+    });
+  };
+  window.addEventListener("click", onClick, true);
+  return () => window.removeEventListener("click", onClick, true);
+}
+function FeedbackProvider({
+  children,
+  root,
+  router = "history",
+  overlay: overlayOpts,
+  captureClicks = true
+}) {
+  const [isInspecting, setIsInspecting] = useState(false);
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const rootEl = root?.current ?? document.body;
+    const unmountOverlay = mountOverlay({
+      ...overlayOpts,
+      root: rootEl,
+      onSubmit: async (input) => {
+        await captureFeedback(input);
+      }
+    });
+    const teardowns = [unmountOverlay];
+    if (router !== "none") teardowns.push(installNavigationBreadcrumbs());
+    if (captureClicks) teardowns.push(installClickBreadcrumbs());
+    return () => teardowns.forEach((fn) => fn());
+  }, []);
+  const value = useMemo(
+    () => ({
+      openInspector: () => {
+        overlay.open();
+        setIsInspecting(true);
+      },
+      closeInspector: () => {
+        overlay.close();
+        setIsInspecting(false);
+      },
+      submit: (input) => captureFeedback(input),
+      isInspecting,
+      isRecording: replay.isRecording()
+    }),
+    [isInspecting]
+  );
+  return /* @__PURE__ */ jsx(FeedbackCtx.Provider, { value, children });
+}
+function useFeedback() {
+  const ctx = useContext(FeedbackCtx);
+  if (!ctx) throw new Error("useFeedback() must be used within <FeedbackProvider>");
+  return ctx;
+}
+
+export { FeedbackProvider, useFeedback };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @loupfeed/react — thin adapter. The engine lives in @loupfeed/core; this only\n * (a) mounts the overlay into the React tree, and (b) wires router/click\n * breadcrumbs into the scope/context API.\n *\n * NOTE: the Vite plugin is intentionally NOT re-exported here. A runtime adapter\n * must never import a build package (privacy invariant, doc 03). Import the\n * plugin directly from `@loupfeed/vite-plugin` in your `vite.config`.\n */\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n  type ReactNode,\n  type RefObject,\n} from 'react';\nimport {\n  addBreadcrumb,\n  captureFeedback,\n  mountOverlay,\n  overlay,\n  replay,\n  setContext,\n  type FeedbackInput,\n  type OverlayOptions,\n} from '@loupfeed/core';\n\n// Re-export the full core public surface (init, scope API, types, …).\nexport * from '@loupfeed/core';\n\ntype FeedbackContextValue = {\n  /** Enter element-inspect mode. */\n  openInspector(): void;\n  /** Leave inspect mode / close any open composer. */\n  closeInspector(): void;\n  /** Submit feedback programmatically. */\n  submit(input: FeedbackInput): Promise<string>;\n  /** Reflects programmatic inspect toggles (not the built-in launcher). */\n  isInspecting: boolean;\n  /** Session replay is deferred in the MVP — always false. */\n  isRecording: boolean;\n};\n\nconst FeedbackCtx = createContext<FeedbackContextValue | null>(null);\n\nexport interface FeedbackProviderProps {\n  children: ReactNode;\n  /**\n   * Root the selector engine generates structural paths relative to.\n   * Defaults to `document.body`.\n   */\n  root?: RefObject<Element | null>;\n  /** Router integration for auto-navigation breadcrumbs. Default 'history'. */\n  router?: 'react-router' | 'tanstack' | 'history' | 'none';\n  /** Overlay appearance/behavior (accent color, z-index, …). */\n  overlay?: Omit<OverlayOptions, 'root' | 'onSubmit'>;\n  /** Record `ui.click` breadcrumbs for button/link clicks. Default true. */\n  captureClicks?: boolean;\n}\n\nfunction installNavigationBreadcrumbs(): () => void {\n  if (typeof window === 'undefined') return () => {};\n  let last = window.location.pathname + window.location.search;\n  const record = () => {\n    const to = window.location.pathname + window.location.search;\n    if (to === last) return;\n    addBreadcrumb({ category: 'navigation', message: `${last} → ${to}`, data: { from: last, to } });\n    setContext('request', { url: window.location.href, route: window.location.pathname });\n    last = to;\n  };\n  const origPush = history.pushState;\n  const origReplace = history.replaceState;\n  history.pushState = function (this: History, ...args: Parameters<History['pushState']>) {\n    const r = origPush.apply(this, args);\n    record();\n    return r;\n  };\n  history.replaceState = function (this: History, ...args: Parameters<History['replaceState']>) {\n    const r = origReplace.apply(this, args);\n    record();\n    return r;\n  };\n  window.addEventListener('popstate', record);\n  return () => {\n    history.pushState = origPush;\n    history.replaceState = origReplace;\n    window.removeEventListener('popstate', record);\n  };\n}\n\nfunction installClickBreadcrumbs(): () => void {\n  if (typeof window === 'undefined') return () => {};\n  const onClick = (e: MouseEvent) => {\n    if (overlay.isInspecting()) return; // inspect-mode clicks aren't app interactions\n    const target = e.target as Element | null;\n    const el = target?.closest('button, a, [role=\"button\"], input[type=\"submit\"]');\n    if (!el) return;\n    const text =\n      (el.textContent ?? '').trim().slice(0, 60) ||\n      el.getAttribute('aria-label') ||\n      el.tagName.toLowerCase();\n    addBreadcrumb({\n      category: 'ui.click',\n      level: 'info',\n      message: text,\n      data: { tag: el.tagName.toLowerCase() },\n    });\n  };\n  window.addEventListener('click', onClick, true);\n  return () => window.removeEventListener('click', onClick, true);\n}\n\nexport function FeedbackProvider({\n  children,\n  root,\n  router = 'history',\n  overlay: overlayOpts,\n  captureClicks = true,\n}: FeedbackProviderProps): JSX.Element {\n  const [isInspecting, setIsInspecting] = useState(false);\n\n  useEffect(() => {\n    if (typeof document === 'undefined') return;\n    const rootEl = root?.current ?? document.body;\n    const unmountOverlay = mountOverlay({\n      ...overlayOpts,\n      root: rootEl,\n      onSubmit: async (input) => {\n        await captureFeedback(input);\n      },\n    });\n    const teardowns: Array<() => void> = [unmountOverlay];\n    if (router !== 'none') teardowns.push(installNavigationBreadcrumbs());\n    if (captureClicks) teardowns.push(installClickBreadcrumbs());\n    return () => teardowns.forEach((fn) => fn());\n    // Mount once for the lifetime of the provider.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  const value = useMemo<FeedbackContextValue>(\n    () => ({\n      openInspector: () => {\n        overlay.open();\n        setIsInspecting(true);\n      },\n      closeInspector: () => {\n        overlay.close();\n        setIsInspecting(false);\n      },\n      submit: (input: FeedbackInput) => captureFeedback(input),\n      isInspecting,\n      isRecording: replay.isRecording(),\n    }),\n    [isInspecting],\n  );\n\n  return <FeedbackCtx.Provider value={value}>{children}</FeedbackCtx.Provider>;\n}\n\nexport function useFeedback(): FeedbackContextValue {\n  const ctx = useContext(FeedbackCtx);\n  if (!ctx) throw new Error('useFeedback() must be used within <FeedbackProvider>');\n  return ctx;\n}\n"]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@loupfeed/react",
+  "version": "0.1.0",
+  "description": "loupfeed React adapter — init(), <FeedbackProvider>, useFeedback(). Mounts the element-anchored feedback overlay and wires router/click breadcrumbs.",
+  "license": "FSL-1.1-ALv2",
+  "homepage": "https://loupfeed.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gilons/loupfeed.git",
+    "directory": "packages/react"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@loupfeed/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.18",
+    "react": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "~5.7.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}