@react-spot/core 0.0.1

package/README.md

@@ -0,0 +1,144 @@
+# @react-spot/core
+
+`@react-spot/core` is the low-level package that powers the React Trace inspector widget. It gives you the `Trace` component, the plugin contract, and the hooks/utilities that official and custom plugins use.
+
+Use this package when you want to:
+
+- Mount the inspector yourself
+- Choose exactly which plugins to enable
+- Build custom plugins against the public core API
+
+If you want the batteries-included bundle with all official plugins pre-wired, use `react-trace` instead.
+
+## Installation
+
+```bash
+pnpm add --dev @react-spot/core
+```
+
+Peer requirements:
+
+- `react >= 18`
+- `react-dom >= 18`
+
+## Minimal usage
+
+Change your dev script to export the project root e.g.:
+
+```diff
+-    "dev": "vite"
++    "dev": "VITE_ROOT=$(pwd) vite",
+```
+
+Then add it next to your app:
+
+```tsx
+import { Trace } from '@react-spot/core'
+
+import App from './App'
+
+export function Root() {
+  return (
+    <>
+      <App />
+      <Trace root={import.meta.env.VITE_ROOT} />
+    </>
+  )
+}
+```
+
+`root` must be the absolute path to the project being inspected.
+
+## When to use `@react-spot/core` vs `react-trace`
+
+- Use `@react-spot/core` when you want a custom plugin list or your own plugins.
+- Use `react-trace` when you want the default bundle of official plugins (`preview`, `copy-to-clipboard`, `open-editor`, and `comments`) with one import.
+
+## `Trace` component
+
+`Trace` is the widget entrypoint exported by this package.
+
+### Props
+
+- `root: string` — absolute project root path
+- `plugins?: TracePlugin[]` — plugin instances to mount
+- `position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'` — initial toolbar position
+- `minimized?: boolean` — whether the widget starts minimized by default
+
+## Plugin model
+
+Plugins implement `TracePlugin`:
+
+```ts
+interface TracePlugin {
+  name: string
+  toolbar?: ComponentType
+  actionPanel?: ComponentType
+  settings?: ComponentType
+}
+```
+
+- `toolbar` renders inside the widget toolbar.
+- `actionPanel` renders inside the selected-component action menu.
+- `settings` renders inside the widget settings popover.
+
+Plugin-owned components receive no props. Read shared widget state through the exported hooks instead.
+
+### Minimal plugin example
+
+> Tip: Run `pnpm create react-trace-plugin` to scaffold a full plugin package with build config and production stubs.
+
+```tsx
+import {
+  Trace,
+  useSelectedContext,
+  type TracePlugin,
+} from '@react-spot/core'
+
+function SelectionInfo() {
+  const context = useSelectedContext()
+  return context ? <button type="button">{context.displayName}</button> : null
+}
+
+const examplePlugin: TracePlugin = {
+  name: 'Example',
+  toolbar: SelectionInfo,
+}
+
+export function AppShell() {
+  return <Trace root="/absolute/path/to/project" plugins={[examplePlugin]} />
+}
+```
+
+## Exported hooks
+
+- `useProjectRoot()` — returns the current project root string
+- `useInspectorActive()` — returns whether inspector mode is active
+- `useDeactivateInspector()` — returns a callback that turns inspector mode off
+- `useSelectedContext()` — returns the currently selected `ComponentContext | null`
+- `useClearSelectedContext()` — returns a callback that clears the current selection
+- `useSelectedSource()` — returns the currently selected `ComponentSource | null`
+- `useWidgetPortalContainer()` — returns the widget portal container element
+
+## Exported utilities and constants
+
+- `settingsPluginAtom(pluginKey)` — returns a writable Jotai atom for a section of `TraceSettings`
+- `IS_MAC` — `true` on macOS/iOS user agents
+- `MOD_KEY` — platform-specific modifier key label (`⌘` or `Ctrl`)
+
+## Exported types
+
+- `ComponentContext` — full context of an inspected component (element, name, breadcrumb, props, sources)
+- `ComponentSource` — source file location (`fileName`, `lineNumber`, `columnNumber`, `relativePath`, `absolutePath`)
+- `TracePlugin`
+- `TraceProps`
+- `TraceSettings`
+
+## Notes for plugin authors
+
+- `useWidgetPortalContainer()` lets plugin popovers, tooltips, and menus render inside the widget portal instead of `document.body`.
+- `settingsPluginAtom()` is keyed by `TraceSettings`, so plugin settings should live under a stable top-level key.
+
+## Production builds
+
+This package publishes development and production entrypoints. In production mode, the exported `Trace` component resolves to a no-op stub, which keeps the inspector at zero runtime cost when production export conditions are used.

package/dist/chunk-zc3tnsvq.js

@@ -0,0 +1,36 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+
+//#endregion
+export { __reExport as n, __exportAll as t };

package/dist/index-CyjjTUAd.d.ts

@@ -0,0 +1,67 @@
+import { ComponentType } from "react";
+
+//#region src/types.d.ts
+type EditorPreset = 'vscode' | 'cursor' | 'windsurf' | 'webstorm' | 'intellij' | 'zed';
+interface ComponentSource {
+  fileName: string;
+  lineNumber: number;
+  columnNumber: number;
+  /** Path relative to the project root, e.g. "src/App.tsx" */
+  relativePath: string;
+  /** Absolute filesystem path, e.g. "/Users/you/project/src/App.tsx" */
+  absolutePath: string;
+}
+interface ComponentContext {
+  element: HTMLElement;
+  displayName: string;
+  /** e.g. ['Card', 'p', 'code'] — nearest React component down to the hovered DOM element */
+  breadcrumb: string[];
+  all: Array<{
+    source: ComponentSource | null;
+    names: string[];
+  }>;
+  props: Record<string, unknown>;
+}
+interface TracePlugin {
+  name: string;
+  /**
+   * Component to render inside the widget's toolbar.
+   */
+  toolbar?: ComponentType;
+  /**
+   * Component to render inside the settings dropdown.
+   */
+  settings?: ComponentType;
+}
+type WidgetPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface TraceProps {
+  /**
+   * Absolute path to the project root, forwarded to all plugins
+   */
+  root: string;
+  /**
+   * Editor to open files in when clicking a component.
+   * @default 'vscode'
+   */
+  editor?: EditorPreset;
+  plugins?: TracePlugin[];
+  position?: WidgetPosition;
+  minimized?: boolean;
+}
+interface TraceSettings {
+  core: {
+    position: WidgetPosition;
+    minimized: boolean;
+  };
+}
+//#endregion
+//#region src/utils/platform.d.ts
+/** True when running on macOS / iOS */
+declare const IS_MAC: boolean;
+/** The modifier key label for the current platform */
+declare const MOD_KEY: string;
+import * as import_jotai_vanilla from "jotai/vanilla";
+import * as import_jotai_react from "jotai/react";
+//#endregion
+export { ComponentSource as a, TraceProps as c, ComponentContext as i, TraceSettings as l, IS_MAC as n, EditorPreset as o, MOD_KEY as r, TracePlugin as s, index_d_exports as t };
+//# sourceMappingURL=index-CyjjTUAd.d.ts.map

package/dist/index-CyjjTUAd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CyjjTUAd.d.ts","names":[],"sources":["../src/types.ts","../src/utils/platform.ts","../../../node_modules/.pnpm/jotai@2.18.0_@babel+core@7.29.0_@babel+template@7.28.6_@types+react@19.2.14_react@19.2.4/node_modules/jotai/esm/index.d.mts"],"x_google_ignoreList":[2],"mappings":";;;KAEY,YAAA;AAAA,UAQK,eAAA;EACf,QAAA;EACA,UAAA;EACA,YAAA;;EAEA,YAAA;EAbsB;EAetB,YAAA;AAAA;AAAA,UAGe,gBAAA;EACf,OAAA,EAAS,WAAA;EACT,WAAA;EAVA;EAYA,UAAA;EACA,GAAA,EAAK,KAAA;IAAQ,MAAA,EAAQ,eAAA;IAAwB,KAAA;EAAA;EAC7C,KAAA,EAAO,MAAA;AAAA;AAAA,UAGQ,WAAA;EACf,IAAA;EALqB;;;EASrB,OAAA,GAAU,aAAA;EARG;;;EAYb,QAAA,GAAW,aAAA;AAAA;AAAA,KAGR,cAAA;AAAA,UAEY,UAAA;EAlBF;;;EAsBb,IAAA;EArBO;;;AAGT;EAuBE,MAAA,GAAS,YAAA;EACT,OAAA,GAAU,WAAA;EACV,QAAA,GAAW,cAAA;EACX,SAAA;AAAA;AAAA,UAGe,aAAA;EACf,IAAA;IACE,QAAA,EAAU,cAAA;IACV,SAAA;EAAA;AAAA;;;;cC5DS,MAAA;;cAKA,OAAA"}

package/dist/index-ujwIx3_4.d.cts

@@ -0,0 +1,69 @@
+import { ComponentType } from "react";
+
+//#region \0rolldown/runtime.js
+//#endregion
+//#region src/types.d.ts
+type EditorPreset = 'vscode' | 'cursor' | 'windsurf' | 'webstorm' | 'intellij' | 'zed';
+interface ComponentSource {
+  fileName: string;
+  lineNumber: number;
+  columnNumber: number;
+  /** Path relative to the project root, e.g. "src/App.tsx" */
+  relativePath: string;
+  /** Absolute filesystem path, e.g. "/Users/you/project/src/App.tsx" */
+  absolutePath: string;
+}
+interface ComponentContext {
+  element: HTMLElement;
+  displayName: string;
+  /** e.g. ['Card', 'p', 'code'] — nearest React component down to the hovered DOM element */
+  breadcrumb: string[];
+  all: Array<{
+    source: ComponentSource | null;
+    names: string[];
+  }>;
+  props: Record<string, unknown>;
+}
+interface TracePlugin {
+  name: string;
+  /**
+   * Component to render inside the widget's toolbar.
+   */
+  toolbar?: ComponentType;
+  /**
+   * Component to render inside the settings dropdown.
+   */
+  settings?: ComponentType;
+}
+type WidgetPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface TraceProps {
+  /**
+   * Absolute path to the project root, forwarded to all plugins
+   */
+  root: string;
+  /**
+   * Editor to open files in when clicking a component.
+   * @default 'vscode'
+   */
+  editor?: EditorPreset;
+  plugins?: TracePlugin[];
+  position?: WidgetPosition;
+  minimized?: boolean;
+}
+interface TraceSettings {
+  core: {
+    position: WidgetPosition;
+    minimized: boolean;
+  };
+}
+//#endregion
+//#region src/utils/platform.d.ts
+/** True when running on macOS / iOS */
+declare const IS_MAC: boolean;
+/** The modifier key label for the current platform */
+declare const MOD_KEY: string;
+import * as import_jotai_vanilla from "jotai/vanilla";
+import * as import_jotai_react from "jotai/react";
+//#endregion
+export { ComponentSource as a, TraceProps as c, ComponentContext as i, TraceSettings as l, IS_MAC as n, EditorPreset as o, MOD_KEY as r, TracePlugin as s, index_d_exports as t };
+//# sourceMappingURL=index-ujwIx3_4.d.cts.map

package/dist/index-ujwIx3_4.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-ujwIx3_4.d.cts","names":[],"sources":["../src/types.ts","../src/utils/platform.ts","../../../node_modules/.pnpm/jotai@2.18.0_@babel+core@7.29.0_@babel+template@7.28.6_@types+react@19.2.14_react@19.2.4/node_modules/jotai/esm/index.d.mts"],"x_google_ignoreList":[2],"mappings":";;;;;KAEY,YAAA;AAAA,UAQK,eAAA;EACf,QAAA;EACA,UAAA;EACA,YAAA;;EAEA,YAAA;;EAEA,YAAA;AAAA;AAAA,UAGe,gBAAA;EACf,OAAA,EAAS,WAAA;EACT,WAAA;;EAEA,UAAA;EACA,GAAA,EAAK,KAAA;IAAQ,MAAA,EAAQ,eAAA;IAAwB,KAAA;EAAA;EAC7C,KAAA,EAAO,MAAA;AAAA;AAAA,UAGQ,WAAA;EACf,IAAA;;;;EAIA,OAAA,GAAU,aAAA;;;;EAIV,QAAA,GAAW,aAAA;AAAA;AAAA,KAGR,cAAA;AAAA,UAEY,UAAA;;;;EAIf,IAAA;EA7CsB;;;;EAkDtB,MAAA,GAAS,YAAA;EACT,OAAA,GAAU,WAAA;EACV,QAAA,GAAW,cAAA;EACX,SAAA;AAAA;AAAA,UAGe,aAAA;EACf,IAAA;IACE,QAAA,EAAU,cAAA;IACV,SAAA;EAAA;AAAA;;;;cC5DS,MAAA;;cAKA,OAAA"}