react-grab 0.1.47 → 0.1.48-dev.06cda9a

package/README.md

@@ -5,7 +5,7 @@
 
 Copy any UI element for your agent.
 
-React Grab points agents to the actual source behind each selection. Agents are [**2× faster**](https://benchmark.react-grab.com/) and more accurate when using React Grab.
+React Grab points agents to the actual source behind each selection. Agents are [**2× faster**](https://react-grab.com/benchmarks) and more accurate when using React Grab.
 
 [**Website →**](https://react-grab.com)
 
@@ -114,72 +114,31 @@ if (process.env.NODE_ENV === "development") {
 }
 ```
 
-## Plugins
+## Build your own React Grab
 
-Use plugins to extend React Grab's built-in UI with context menu actions, toolbar menu items, lifecycle hooks, and theme overrides.
+Build a custom interface with the selection engine from `react-grab/primitives`. Use its APIs for hit testing, source context, page freezing, clipboard access, and editor navigation.
 
-Register a plugin using the `registerPlugin` export:
+### Customize hit testing
 
-```js
-import { registerPlugin } from "react-grab";
+Scope hit testing to a container or replace the default element filter with your own rules.
 
-registerPlugin({
-  name: "my-plugin",
-  hooks: {
-    onElementSelect: (element) => {
-      console.log("Selected:", element.tagName);
-    },
-  },
-});
-```
-
-If writing in React, register inside a `useEffect`:
+```typescript
+import { getElementAtPoint, isElementGrabbable } from "react-grab/primitives";
 
-```jsx
-import { registerPlugin, unregisterPlugin } from "react-grab";
-
-useEffect(() => {
-  registerPlugin({
-    name: "my-plugin",
-    actions: [
-      {
-        id: "my-action",
-        label: "My Action",
-        shortcut: "M",
-        onAction: (context) => {
-          console.log("Action on:", context.element);
-          context.hideContextMenu();
-        },
-      },
-    ],
+export const getPickerTarget = (
+  event: PointerEvent,
+  appElement: Element,
+  toolbarElement: Element,
+): Element | null =>
+  getElementAtPoint(event.clientX, event.clientY, {
+    container: appElement,
+    filter: (candidate) =>
+      isElementGrabbable(candidate) &&
+      !toolbarElement.contains(candidate),
   });
-
-  return () => unregisterPlugin("my-plugin");
-}, []);
-```
-
-Actions use a `target` field to control where they appear. Omit `target` (or set `"context-menu"`) for the right-click menu, or set `"toolbar"` for the toolbar dropdown:
-
-```js
-actions: [
-  {
-    id: "inspect",
-    label: "Inspect",
-    shortcut: "I",
-    onAction: (ctx) => console.dir(ctx.element),
-  },
-  {
-    id: "toggle-freeze",
-    label: "Freeze",
-    // Only show in the toolbar
-    target: "toolbar",
-    isActive: () => isFrozen,
-    onAction: () => toggleFreeze(),
-  },
-];
 ```
 
-See [`packages/react-grab/src/types.ts`](https://github.com/aidenybai/react-grab/blob/main/packages/react-grab/src/types.ts) for the full `Plugin`, `PluginHooks`, and `PluginConfig` interfaces.
+Add `data-react-grab-ignore` to your picker interface so hit testing skips its subtree.
 
 ## Resources & Contributing Back
 

package/dist/{copy-content-CqFXlS9J.d.ts → copy-content-CNRKFr6F.d.ts}

@@ -6,6 +6,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { ReactNode } from "react";
+
 //#region ../../node_modules/.pnpm/solid-js@1.9.12/node_modules/solid-js/types/reactive/observable.d.ts
 declare global {
   interface SymbolConstructor {
@@ -23,6 +25,17 @@ interface Position {
   x: number;
   y: number;
 }
+interface ElementAtPointOptions {
+  container?: Element;
+  filter?: (element: Element) => boolean;
+}
+interface ElementBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  borderRadius: string;
+}
 type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? T[P] extends ((...args: unknown[]) => unknown) ? T[P] : DeepPartial<T[P]> : T[P] };
 interface Theme {
   /**
@@ -138,11 +151,13 @@ interface AgentContext<T = unknown> {
   sessionId?: string;
 }
 type ActivationMode = "toggle" | "hold";
-interface ActionContextHooks {
-  transformHtmlContent: (html: string, elements: Element[]) => Promise<string>;
+interface OpenFileActionHooks {
   onOpenFile: (filePath: string, lineNumber?: number) => boolean | void;
   transformOpenFileUrl: (url: string, filePath: string, lineNumber?: number) => string;
 }
+interface ActionContextHooks extends OpenFileActionHooks {
+  transformHtmlContent: (html: string, elements: Element[]) => Promise<string>;
+}
 interface ActionContext {
   element: Element;
   elements: Element[];
@@ -214,6 +229,12 @@ interface EnumPendingEdit {
 }
 type PendingEdit = NumericPendingEdit | ColorPendingEdit | EnumPendingEdit;
 type PendingEdits = PendingEdit[];
+interface DesignTokenResolver {
+  readonly hasTokens: boolean;
+  matchColor: (hex: string) => string | null;
+  matchLength: (px: number, cssProperty: string) => string | null;
+  stepLength: (px: number, direction: 1 | -1, cssProperty: string) => number | null;
+}
 interface PreviewStyles {
   apply: (cssProperties: readonly string[], cssValue: string) => void;
   restore: () => void;
@@ -222,16 +243,15 @@ interface PreviewStyles {
 interface EditPanelState {
   element: Element;
   position: Position;
-  selectionBounds: OverlayBounds;
   properties: EditableProperty[];
   preview: PreviewStyles;
   filePath?: string;
   lineNumber?: number;
   componentName?: string;
   tagName?: string;
-  htmlPreview?: string;
   initialSearchQuery?: string;
   hasSessionEdits?: boolean;
+  designTokens?: DesignTokenResolver;
 }
 interface ContextMenuAction {
   id: string;
@@ -242,34 +262,35 @@ interface ContextMenuAction {
   enabled?: boolean | ((context: ActionContext) => boolean);
   onAction: (context: ContextMenuActionContext) => void | Promise<void>;
 }
-interface ArrowNavigationItem {
+interface HierarchyItem {
   tagName: string;
   componentName?: string;
+  depth: number;
+  isLast: boolean;
 }
-interface ArrowNavigationState {
-  items: ArrowNavigationItem[];
+interface HierarchyState {
+  items: HierarchyItem[];
   activeIndex: number;
-  isVisible: boolean;
 }
 interface PluginHooks {
-  onActivate?: () => void;
-  onDeactivate?: () => void;
-  onElementHover?: (element: Element) => void;
+  onActivate?: () => void | Promise<void>;
+  onDeactivate?: () => void | Promise<void>;
+  onElementHover?: (element: Element) => void | Promise<void>;
   onElementSelect?: (element: Element) => boolean | void | Promise<boolean>;
-  onDragStart?: (startX: number, startY: number) => void;
-  onDragEnd?: (elements: Element[], bounds: DragRect) => void;
+  onDragStart?: (startX: number, startY: number) => void | Promise<void>;
+  onDragEnd?: (elements: Element[], bounds: DragRect) => void | Promise<void>;
   onBeforeCopy?: (elements: Element[]) => void | Promise<void>;
   transformCopyContent?: (content: string, elements: Element[]) => string | Promise<string>;
-  onAfterCopy?: (elements: Element[], success: boolean) => void;
-  onCopySuccess?: (elements: Element[], content: string) => void;
-  onCopyError?: (error: Error) => void;
-  onStateChange?: (state: ReactGrabState) => void;
-  onPromptModeChange?: (isPromptMode: boolean, context: PromptModeContext) => void;
-  onSelectionBox?: (visible: boolean, bounds: OverlayBounds | null, element: Element | null) => void;
-  onDragBox?: (visible: boolean, bounds: OverlayBounds | null) => void;
-  onGrabbedBox?: (bounds: OverlayBounds, element: Element) => void;
-  onElementLabel?: (visible: boolean, variant: ElementLabelVariant, context: ElementLabelContext) => void;
-  onContextMenu?: (element: Element, position: Position) => void;
+  onAfterCopy?: (elements: Element[], success: boolean) => void | Promise<void>;
+  onCopySuccess?: (elements: Element[], content: string) => void | Promise<void>;
+  onCopyError?: (error: Error) => void | Promise<void>;
+  onStateChange?: (state: ReactGrabState) => void | Promise<void>;
+  onPromptModeChange?: (isPromptMode: boolean, context: PromptModeContext) => void | Promise<void>;
+  onSelectionBox?: (visible: boolean, bounds: OverlayBounds | null, element: Element | null) => void | Promise<void>;
+  onDragBox?: (visible: boolean, bounds: OverlayBounds | null) => void | Promise<void>;
+  onGrabbedBox?: (bounds: OverlayBounds, element: Element) => void | Promise<void>;
+  onElementLabel?: (visible: boolean, variant: ElementLabelVariant, context: ElementLabelContext) => void | Promise<void>;
+  onContextMenu?: (element: Element, position: Position) => void | Promise<void>;
   onOpenFile?: (filePath: string, lineNumber?: number) => boolean | void;
   transformHtmlContent?: (html: string, elements: Element[]) => string | Promise<string>;
   transformAgentContext?: (context: AgentContext, elements: Element[]) => AgentContext | Promise<AgentContext>;
@@ -281,7 +302,7 @@ interface PluginConfig {
   options?: SettableOptions;
   actions?: ContextMenuAction[];
   hooks?: PluginHooks;
-  cleanup?: () => void;
+  cleanup?: () => undefined;
 }
 interface Plugin {
   name: string;
@@ -293,6 +314,12 @@ interface Plugin {
 }
 interface Options {
   enabled?: boolean;
+  /**
+   * Confine React Grab to a single container element instead of the whole page.
+   * Hit-testing, the toolbar viewport, and scroll re-anchoring are scoped to it.
+   * Used by the demo build to scope the showcase to its card.
+   */
+  container?: HTMLElement;
   activationMode?: ActivationMode;
   keyHoldDuration?: number;
   allowActivationInsideInput?: boolean;
@@ -324,12 +351,31 @@ interface Options {
 interface SettableOptions extends Options {
   enabled?: never;
   telemetry?: never;
+  container?: never;
 }
 interface SourceInfo {
   filePath: string;
   lineNumber: number | null;
   componentName: string | null;
 }
+interface SelectedElementPayload {
+  tagName: string;
+  id?: string;
+  className?: string;
+  textContent?: string;
+  componentName?: string;
+  filePath?: string;
+  lineNumber?: number;
+  columnNumber?: number;
+}
+interface ElementSelectedEventDetail {
+  elements: SelectedElementPayload[];
+}
+declare global {
+  interface WindowEventMap {
+    "react-grab:element-selected": CustomEvent<ElementSelectedEventDetail>;
+  }
+}
 interface ToolbarState {
   edge: "top" | "bottom" | "left" | "right";
   ratio: number;
@@ -353,6 +399,7 @@ interface ReactGrabAPI {
   getToolbarState: () => ToolbarState | null;
   setToolbarState: (state: Partial<ToolbarState>) => void;
   onToolbarStateChange: (callback: (state: ToolbarState) => void) => () => void;
+  reset: () => void;
   dispose: () => void;
   copyElement: (elements: Element | Element[]) => Promise<boolean>;
   getSource: (element: Element) => Promise<SourceInfo | null>;
@@ -398,13 +445,19 @@ interface FrozenLabelEntry {
   bounds: OverlayBounds;
   mouseX?: number;
 }
+interface FrozenLabelEntryAccessor {
+  read: () => FrozenLabelEntry | null;
+}
+interface SelectionLabelInstanceAccessor {
+  read: () => SelectionLabelInstance | null;
+}
 interface ReactGrabRendererProps {
   selectionVisible?: boolean;
   selectionBounds?: OverlayBounds;
   selectionBoundsMultiple?: OverlayBounds[];
   selectionShouldSnap?: boolean;
   selectionElementsCount?: number;
-  frozenLabelEntries?: FrozenLabelEntry[];
+  frozenLabelEntryAccessors?: FrozenLabelEntryAccessor[];
   pendingShiftPreviewEntry?: FrozenLabelEntry;
   selectionFilePath?: string;
   selectionLineNumber?: number;
@@ -412,9 +465,10 @@ interface ReactGrabRendererProps {
   selectionComponentName?: string;
   selectionLabelVisible?: boolean;
   selectionLabelStatus?: SelectionLabelStatus;
-  selectionArrowNavigationState?: ArrowNavigationState;
-  onArrowNavigationSelect?: (index: number) => void;
+  hierarchyState?: HierarchyState;
+  hierarchyMenuPosition?: DropdownAnchor | null;
   labelInstances?: SelectionLabelInstance[];
+  labelInstanceAccessors?: SelectionLabelInstanceAccessor[];
   dragVisible?: boolean;
   dragBounds?: OverlayBounds;
   grabbedBoxes?: Array<{
@@ -427,12 +481,15 @@ interface ReactGrabRendererProps {
   inputValue?: string;
   isPromptMode?: boolean;
   onShowContextMenuInstance?: (instanceId: string) => void;
+  onRetryInstance?: (instanceId: string) => void;
+  onAcknowledgeErrorInstance?: (instanceId: string) => void;
   onLabelInstanceHoverChange?: (instanceId: string, isHovered: boolean) => void;
   onInputChange?: (value: string) => void;
   onInputSubmit?: () => void;
   onToggleExpand?: () => void;
   selectionLabelShakeCount?: number;
   onConfirmDismiss?: () => void;
+  onOpenSelectionFile?: () => void;
   discardPrompt?: SelectionDiscardPrompt;
   toolbarVisible?: boolean;
   isActive?: boolean;
@@ -514,7 +571,7 @@ interface ReactGrabEntry {
   frames?: ReactGrabStackFrame[];
 }
 //#endregion
-//#region ../../node_modules/.pnpm/bippy@0.5.41_react@19.2.6/node_modules/bippy/dist/core.d.ts
+//#region ../../node_modules/.pnpm/bippy@0.6.0_react@19.2.6/node_modules/bippy/dist/unsubscribe.d.ts
 type Flags = number;
 type Lanes = number;
 type TypeOfMode = number;
@@ -604,6 +661,14 @@ interface Effect {
 interface Family {
   current: unknown;
 }
+/**
+ * React 19 flight metadata for a server component owner (ReactComponentInfo).
+ * Unlike client owners it has no `tag`; the owner chain continues via `owner`.
+ */
+interface RendererRefreshUpdate {
+  staleFamilies: Set<Family>;
+  updatedFamilies: Set<Family>;
+}
 /**
  * Represents a react-internal Fiber node.
  */
@@ -654,6 +719,7 @@ interface ReactDevToolsGlobalHook {
   onCommitFiberRoot: (rendererID: number, root: FiberRoot, priority: number | void) => void;
   onCommitFiberUnmount: (rendererID: number, fiber: Fiber) => void;
   onPostCommitFiberRoot: (rendererID: number, root: FiberRoot) => void;
+  onScheduleFiberRoot?: (rendererID: number, root: FiberRoot, children: ReactNode) => void;
   renderers: Map<number, ReactRenderer>;
   supportsFiber: boolean;
   supportsFlight: boolean;
@@ -672,10 +738,7 @@ interface ReactRenderer {
   overridePropsRenamePath?: (fiber: Fiber, oldPath: Array<number | string>, newPath: Array<number | string>) => void;
   reconcilerVersion: string;
   rendererPackageName: string;
-  scheduleRefresh?: (root: FiberRoot, update: {
-    staleFamilies: Set<Family>;
-    updatedFamilies: Set<Family>;
-  }) => void;
+  scheduleRefresh?: (root: FiberRoot, update: RendererRefreshUpdate) => void;
   scheduleRoot?: (root: FiberRoot, element: React.ReactNode) => void;
   scheduleUpdate?: (fiber: Fiber) => void;
   setErrorHandler?: (newShouldErrorImpl: (fiber: Fiber) => boolean) => void;
@@ -686,28 +749,30 @@ interface ReactRenderer {
 declare global {
   var __REACT_DEVTOOLS_GLOBAL_HOOK__: ReactDevToolsGlobalHook | undefined;
 } //#endregion
-//#region src/rdt-hook.d.ts
-/**
- * Returns `true` if bippy's instrumentation is active.
- */
-declare const isInstrumentationActive: () => boolean;
-/**
- * Returns the latest fiber (since it may be double-buffered).
- */
+//#region src/unsubscribe.d.ts
 //#endregion
-//#region ../../node_modules/.pnpm/bippy@0.5.41_react@19.2.6/node_modules/bippy/dist/source.d.ts
+//#region ../../node_modules/.pnpm/bippy@0.6.0_react@19.2.6/node_modules/bippy/dist/source.d.ts
 //#region src/source/parse-stack.d.ts
 interface StackFrame {
   args?: unknown[];
   columnNumber?: number;
   lineNumber?: number;
+  enclosingLineNumber?: number;
+  enclosingColumnNumber?: number;
   fileName?: string;
   functionName?: string;
   source?: string;
   isServer?: boolean;
   isSymbolicated?: boolean;
+  isIgnoreListed?: boolean;
 }
 //#endregion
+//#region ../../node_modules/.pnpm/bippy@0.6.0_react@19.2.6/node_modules/bippy/dist/core.d.ts
+/**
+ * Returns `true` if bippy's instrumentation is active.
+ */
+declare const isInstrumentationActive: () => boolean;
+//#endregion
 //#region src/utils/copy-content.d.ts
 interface CopyContentOptions {
   componentName?: string;
@@ -717,4 +782,4 @@ interface CopyContentOptions {
 }
 declare const copyContent: (content: string, options?: CopyContentOptions) => boolean;
 //#endregion
-export { ToolbarState as A, ReactGrabAPI as C, SettableOptions as D, Rect as E, SourceInfo as O, PromptModeContext as S, ReactGrabState as T, OverlayBounds as _, ActionContext as a, PluginHooks as b, AgentContext as c, DeepPartial as d, DragRect as f, Options as g, GrabbedBox as h, isInstrumentationActive as i, Theme as k, ContextMenuAction as l, ElementLabelVariant as m, StackFrame as n, ActionContextHooks as o, ElementLabelContext as p, Fiber as r, ActivationMode as s, copyContent as t, ContextMenuActionContext as u, Plugin as v, ReactGrabRendererProps as w, Position as x, PluginConfig as y };
+export { Rect as A, PluginConfig as C, ReactGrabAPI as D, PromptModeContext as E, ToolbarState as F, SettableOptions as M, SourceInfo as N, ReactGrabRendererProps as O, Theme as P, Plugin as S, Position as T, ElementSelectedEventDetail as _, ActionContext as a, Options as b, AgentContext as c, DeepPartial as d, DragRect as f, ElementLabelVariant as g, ElementLabelContext as h, Fiber as i, SelectedElementPayload as j, ReactGrabState as k, ContextMenuAction as l, ElementBounds as m, isInstrumentationActive as n, ActionContextHooks as o, ElementAtPointOptions as p, StackFrame as r, ActivationMode as s, copyContent as t, ContextMenuActionContext as u, GrabbedBox as v, PluginHooks as w, OverlayBounds as x, OpenFileActionHooks as y };