@limrun/ui 0.9.0-rc.6 → 0.9.0-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limrun/ui",
-  "version": "0.9.0-rc.6",
+  "version": "0.9.0-rc.7",
   "publishConfig": {
     "access": "public"
   },

package/src/components/inspect-overlay.css

@@ -9,6 +9,11 @@
   /* When click-to-select is enabled, the container also captures clicks
      that fall outside any box so we can clear selection. */
   pointer-events: auto;
+  /* Match Chrome DevTools' crosshair cursor while inspect mode is active.
+     The merged `.rc-inspect-overlay-select .rc-inspect-box` rule below
+     restates the cursor on each inner box, since `.rc-inspect-box` sets
+     its own `cursor: pointer`. */
+  cursor: crosshair;
 }
 
 .rc-inspect-box {
@@ -32,6 +37,7 @@
 
 .rc-inspect-overlay-select .rc-inspect-box {
   pointer-events: auto;
+  cursor: crosshair;
 }
 
 .rc-inspect-box-disabled {

package/src/components/inspect-overlay.tsx

@@ -7,8 +7,9 @@ import {
   AxElement,
   AxPlatform,
   AxSnapshot,
+  axCliTapCommand,
   axElementRoleLabel,
-  axElementSelectorExpression,
+  axElementSelectorObject,
   axElementSummary,
   axElementsEqual,
   clampAxFrameForScreen,
@@ -37,6 +38,10 @@ export interface InspectOverlayProps {
   highlightedId: string | null;
   selectedId: string | null;
   mode: InspectMode;
+  // Optional instance id used to render the "Copy command" CLI snippet
+  // (e.g. `lim ios tap-element --ax-label 'Sign in' --id <instanceId>`)
+  // in the info card. When omitted the Copy command button is hidden.
+  instanceId?: string;
   // Current pointer position in viewport coordinates (clientX/Y). Drives the
   // cursor-anchored preview card while hovering. null when the pointer is
   // outside the device.
@@ -117,6 +122,10 @@ const InspectBox = memo(
           if (!selectable) return;
           e.preventDefault();
           e.stopPropagation();
+          // Chrome DevTools parity: clicking the already-selected element
+          // is a no-op. Re-firing the selection change callback would
+          // needlessly reset the card anchor and consumer-side state.
+          if (selected) return;
           onClick(element, { x: e.clientX, y: e.clientY });
         }}
         style={{
@@ -151,6 +160,9 @@ interface InfoCardProps {
   anchor: { x: number; y: number };
   cursorAnchored: boolean;
   showActions: boolean;
+  // Used to render the "Copy command" CLI snippet. When absent the button
+  // is hidden.
+  instanceId?: string;
   // Receives the element AND the viewport-space coordinate to tap at
   // (the frozen click position). Tapping at the click point — rather than
   // the element's frame center — preserves the user's aim when the
@@ -180,6 +192,7 @@ const InfoCard = memo(function InfoCard({
   anchor,
   cursorAnchored,
   showActions,
+  instanceId,
   onTap,
 }: InfoCardProps) {
   const [copied, setCopied] = useState<string | null>(null);
@@ -235,11 +248,26 @@ const InfoCard = memo(function InfoCard({
     return { left: `${left}px`, top: `${top}px`, transform };
   }, [anchor.x, anchor.y]);
 
-  const selectorExpr = useMemo(() => axElementSelectorExpression(element, platform), [element, platform]);
+  // "Copy selector" returns the raw selector hash as JSON (the same shape
+  // accepted by the CLI / instance API). Every available selector field is
+  // included so the consumer can disambiguate (e.g. `AXLabel + type`).
+  const selectorObject = useMemo(() => axElementSelectorObject(element, platform), [element, platform]);
+  const selectorJson = useMemo(
+    () => (selectorObject ? JSON.stringify(selectorObject, null, 2) : null),
+    [selectorObject],
+  );
+  // "Copy command" emits a selector-based `lim … tap-element …` invocation
+  // that targets this exact element on this exact instance, robust to
+  // layout changes that would invalidate a coordinate-based tap.
+  const cliCommand = useMemo(
+    () => (instanceId ? axCliTapCommand(element, platform, instanceId) : null),
+    [element, platform, instanceId],
+  );
+
   const primaryIdField = platform === 'ios' ? element.selectors.AXUniqueId : element.selectors.resourceId;
   const primaryIdLabel = platform === 'ios' ? 'AXUniqueId' : 'resourceId';
 
-  const handleCopy = useCallback(async (text: string | undefined, key: string) => {
+  const handleCopy = useCallback(async (text: string | null, key: string) => {
     if (!text) return;
     const ok = await copyToClipboard(text);
     if (ok) setCopied(key);
@@ -308,21 +336,22 @@ const InfoCard = memo(function InfoCard({
           <button
             type="button"
             className={clsx('rc-inspect-card-btn', copied === 'selector' && 'rc-inspect-card-btn-copied')}
-            disabled={!selectorExpr}
-            title={selectorExpr ?? 'No usable selector for this element'}
-            onClick={() => handleCopy(selectorExpr ?? undefined, 'selector')}
+            disabled={!selectorJson}
+            title={selectorJson ?? 'No usable selector for this element'}
+            onClick={() => handleCopy(selectorJson, 'selector')}
           >
             {copied === 'selector' ? 'Copied!' : 'Copy selector'}
           </button>
-          <button
-            type="button"
-            className={clsx('rc-inspect-card-btn', copied === 'id' && 'rc-inspect-card-btn-copied')}
-            disabled={!primaryIdField}
-            title={primaryIdField ?? `No ${primaryIdLabel}`}
-            onClick={() => handleCopy(primaryIdField, 'id')}
-          >
-            {copied === 'id' ? 'Copied!' : `Copy ${primaryIdLabel}`}
-          </button>
+          {cliCommand && (
+            <button
+              type="button"
+              className={clsx('rc-inspect-card-btn', copied === 'command' && 'rc-inspect-card-btn-copied')}
+              title={cliCommand}
+              onClick={() => handleCopy(cliCommand, 'command')}
+            >
+              {copied === 'command' ? 'Copied!' : 'Copy command'}
+            </button>
+          )}
         </div>
       )}
     </div>,
@@ -340,6 +369,7 @@ export const InspectOverlay = memo(function InspectOverlay({
   highlightedId,
   selectedId,
   mode,
+  instanceId,
   cursorPosition,
   frozenCursorPosition,
   onSelectChange,
@@ -429,6 +459,7 @@ export const InspectOverlay = memo(function InspectOverlay({
           anchor={anchor}
           cursorAnchored={cursorAnchored}
           showActions={showActions}
+          instanceId={instanceId}
           onTap={onTapElement}
         />
       )}

package/src/components/remote-control.tsx

@@ -65,8 +65,10 @@ interface RemoteControlProps {
    * video stream.
    *
    * - `true` — Select mode. Boxes are clickable, click pins a selection
-   *   with action buttons (Tap / Copy selector / Copy id), ESC clears.
-   *   Device input is blocked while in this mode.
+   *   with action buttons (Tap / Copy selector / Copy command), ESC
+   *   clears. The cursor turns into a crosshair while inspecting and the
+   *   info card hangs off the pointer. Device input is blocked while in
+   *   this mode.
    * - `'hover-only'` — Boxes follow the cursor as a visual preview. Device
    *   input still passes through, so you can drive the simulator while
    *   inspecting.
@@ -74,6 +76,16 @@ interface RemoteControlProps {
    */
   inspectMode?: boolean | 'hover-only';
 
+  /**
+   * Optional instance id used to render the "Copy command" button in the
+   * inspect-mode info card. When provided, the button copies a CLI
+   * invocation like
+   * `lim ios tap-element --ax-label 'Sign in' --type Button --id <instanceId>`
+   * (or its Android equivalent) that targets this exact element on this
+   * exact instance. When omitted the button is hidden.
+   */
+  instanceId?: string;
+
   /**
    * Fires whenever a fresh accessibility snapshot is delivered.
    *
@@ -333,6 +345,7 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
       showFrame = true,
       autoReconnect = false,
       inspectMode,
+      instanceId,
       onAxSnapshotChange,
       onInspectSelectionChange,
       onAxStatusChange,
@@ -2529,6 +2542,7 @@ export const RemoteControl = forwardRef<RemoteControlHandle, RemoteControlProps>
             highlightedId={axHighlightedId}
             selectedId={axSelectedId}
             mode={inspectModeResolved}
+            instanceId={instanceId}
             cursorPosition={axCursorPosition}
             frozenCursorPosition={axFrozenCursorPosition}
             onSelectChange={(element, clickPosition) => {

package/src/core/ax-tree.test.ts

@@ -11,9 +11,11 @@ import {
   AxElement,
   AxSnapshot,
   AX_UNAVAILABLE_ERROR,
+  axCliTapCommand,
   axElementAtPoint,
   axElementRoleLabel,
   axElementSelectorExpression,
+  axElementSelectorObject,
   axElementSummary,
   axElementsEqual,
   axSnapshotsEqual,
@@ -483,6 +485,128 @@ describe('axElementSelectorExpression', () => {
   });
 });
 
+describe('axElementSelectorObject', () => {
+  const mk = (sel: Partial<AxElement['selectors']>, value = ''): AxElement => ({
+    id: '0',
+    path: '0',
+    label: '',
+    value,
+    role: '',
+    type: '',
+    enabled: true,
+    focused: false,
+    frame: { x: 0, y: 0, width: 1, height: 1 },
+    selectors: sel,
+    raw: {},
+  });
+
+  test('iOS: includes every available selector field, mapping className to type', () => {
+    expect(
+      axElementSelectorObject(mk({ AXUniqueId: 'signin', AXLabel: 'Sign in', className: 'Button' }), 'ios'),
+    ).toEqual({ AXUniqueId: 'signin', AXLabel: 'Sign in', type: 'Button' });
+  });
+
+  test('iOS: falls back to AXLabel + type when AXUniqueId is missing', () => {
+    expect(axElementSelectorObject(mk({ AXLabel: 'OK', className: 'Button' }), 'ios')).toEqual({
+      AXLabel: 'OK',
+      type: 'Button',
+    });
+  });
+
+  test('iOS: returns null when only a generic type/className is available', () => {
+    expect(axElementSelectorObject(mk({ className: 'Button' }), 'ios')).toBeNull();
+    expect(axElementSelectorObject(mk({}), 'ios')).toBeNull();
+  });
+
+  test('Android: includes every available selector field', () => {
+    expect(
+      axElementSelectorObject(
+        mk({
+          resourceId: 'com.example:id/submit',
+          contentDesc: 'Submit',
+          text: 'Submit',
+          className: 'android.widget.Button',
+        }),
+        'android',
+      ),
+    ).toEqual({
+      resourceId: 'com.example:id/submit',
+      contentDesc: 'Submit',
+      text: 'Submit',
+      className: 'android.widget.Button',
+    });
+  });
+
+  test('Android: returns null when only a className is present', () => {
+    expect(axElementSelectorObject(mk({ className: 'android.widget.View' }), 'android')).toBeNull();
+    expect(axElementSelectorObject(mk({}), 'android')).toBeNull();
+  });
+});
+
+describe('axCliTapCommand', () => {
+  const mk = (sel: Partial<AxElement['selectors']>): AxElement => ({
+    id: '0',
+    path: '0',
+    label: '',
+    value: '',
+    role: '',
+    type: '',
+    enabled: true,
+    focused: false,
+    frame: { x: 0, y: 0, width: 1, height: 1 },
+    selectors: sel,
+    raw: {},
+  });
+
+  test('iOS: emits tap-element with every available selector flag', () => {
+    expect(
+      axCliTapCommand(
+        mk({ AXUniqueId: 'signin', AXLabel: 'Sign in', className: 'Button' }),
+        'ios',
+        'ios_abc',
+      ),
+    ).toBe(`lim ios tap-element --ax-unique-id signin --ax-label 'Sign in' --type Button --id ios_abc`);
+  });
+
+  test('iOS: AXLabel + type fallback when AXUniqueId is missing', () => {
+    expect(axCliTapCommand(mk({ AXLabel: 'OK', className: 'Button' }), 'ios', 'ios_abc')).toBe(
+      `lim ios tap-element --ax-label OK --type Button --id ios_abc`,
+    );
+  });
+
+  test('Android: emits tap-element with resource-id / content-desc / text / class-name', () => {
+    expect(
+      axCliTapCommand(
+        mk({
+          resourceId: 'com.example:id/submit',
+          contentDesc: 'Submit button',
+          text: 'Submit',
+          className: 'android.widget.Button',
+        }),
+        'android',
+        'and_1',
+      ),
+    ).toBe(
+      `lim android tap-element --resource-id com.example:id/submit --content-desc 'Submit button' --text Submit --class-name android.widget.Button --id and_1`,
+    );
+  });
+
+  test('shell-quotes values containing apostrophes', () => {
+    expect(axCliTapCommand(mk({ AXLabel: `Bob's button` }), 'ios', 'ios_abc')).toBe(
+      `lim ios tap-element --ax-label 'Bob'\\''s button' --id ios_abc`,
+    );
+  });
+
+  test('returns null when no specific selector is available', () => {
+    expect(axCliTapCommand(mk({ className: 'Button' }), 'ios', 'ios_abc')).toBeNull();
+    expect(axCliTapCommand(mk({}), 'android', 'and_1')).toBeNull();
+  });
+
+  test('returns null when instanceId is empty', () => {
+    expect(axCliTapCommand(mk({ AXUniqueId: 'signin' }), 'ios', '')).toBeNull();
+  });
+});
+
 describe('AX_UNAVAILABLE_ERROR', () => {
   test('is a non-empty string customers can compare against', () => {
     expect(typeof AX_UNAVAILABLE_ERROR).toBe('string');

package/src/core/ax-tree.ts

@@ -382,6 +382,113 @@ export function axElementSelectorExpression(el: AxElement, platform: AxPlatform)
   return null;
 }
 
+// Returns a plain selector object for the element using the same key names the
+// CLI / instance API expect (`AXUniqueId`, `AXLabel`, `type` on iOS;
+// `resourceId`, `contentDesc`, `text`, `className` on Android). Includes every
+// CLI-supportable selector field present on the element so the consumer can
+// disambiguate (e.g. `{AXLabel:"Submit", type:"Button"}`).
+//
+// Returns null when the element has no anchor field specific enough to drive
+// a tap — a lone `type` / `className` is intentionally treated as
+// non-actionable to avoid copying a near-useless selector. This mirrors the
+// precedence used by `axElementSelectorExpression`.
+export function axElementSelectorObject(el: AxElement, platform: AxPlatform): Record<string, string> | null {
+  const out: Record<string, string> = {};
+  let hasSpecific = false;
+  if (platform === 'ios') {
+    if (el.selectors.AXUniqueId) {
+      out.AXUniqueId = el.selectors.AXUniqueId;
+      hasSpecific = true;
+    }
+    if (el.selectors.AXLabel) {
+      out.AXLabel = el.selectors.AXLabel;
+      hasSpecific = true;
+    }
+    // `selectors.className` carries the iOS element `type` (e.g. "Button").
+    // The CLI / API expose it under the key `type`, so rename here.
+    if (el.selectors.className) {
+      out.type = el.selectors.className;
+    }
+  } else {
+    if (el.selectors.resourceId) {
+      out.resourceId = el.selectors.resourceId;
+      hasSpecific = true;
+    }
+    if (el.selectors.contentDesc) {
+      out.contentDesc = el.selectors.contentDesc;
+      hasSpecific = true;
+    }
+    if (el.selectors.text) {
+      out.text = el.selectors.text;
+      hasSpecific = true;
+    }
+    if (el.selectors.className) {
+      out.className = el.selectors.className;
+    }
+  }
+  return hasSpecific ? out : null;
+}
+
+// POSIX-safe single quoting for shell command rendering. Bare-prints "safe"
+// tokens (alphanumerics, slashes, dots, etc.) so common identifiers like
+// UUIDs and Android resource IDs (`com.example:id/submit`) stay readable;
+// everything else gets single-quoted with internal apostrophes escaped as
+// `'\''`.
+const shellQuote = (value: string): string => {
+  if (value === '') return "''";
+  if (/^[A-Za-z0-9_./\-:@%+=,]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+};
+
+// Maps `axElementSelectorObject` keys to their `lim … tap-element` CLI
+// flags. Scoped to the keys emitted by `axElementSelectorObject` — any
+// future selector field added there must also be added here.
+const CLI_FLAG_BY_SELECTOR_KEY: Record<AxPlatform, Record<string, string>> = {
+  ios: {
+    AXUniqueId: '--ax-unique-id',
+    AXLabel: '--ax-label',
+    type: '--type',
+  },
+  android: {
+    resourceId: '--resource-id',
+    contentDesc: '--content-desc',
+    text: '--text',
+    className: '--class-name',
+  },
+};
+
+// Renders the `lim` CLI command that taps the element via selector flags
+// rather than coordinates. Includes every CLI-supportable selector field
+// present on the element (same precedence as `axElementSelectorObject`) so
+// matches are unambiguous and resilient to layout changes.
+//
+// Example outputs:
+//   lim ios tap-element --ax-unique-id signin --id <id>
+//   lim ios tap-element --ax-label 'Sign in' --type Button --id <id>
+//   lim android tap-element --resource-id com.example:id/submit --id <id>
+//
+// Returns null when:
+//   - `instanceId` is empty, or
+//   - the element has no field specific enough to drive a selector tap
+//     (matches `axElementSelectorObject` returning null — e.g. only a
+//     generic className/type is available).
+export function axCliTapCommand(el: AxElement, platform: AxPlatform, instanceId: string): string | null {
+  if (!instanceId) return null;
+  const selectors = axElementSelectorObject(el, platform);
+  if (!selectors) return null;
+
+  const flagMap = CLI_FLAG_BY_SELECTOR_KEY[platform];
+  const parts: string[] = ['lim', platform, 'tap-element'];
+  for (const [key, flag] of Object.entries(flagMap)) {
+    const value = selectors[key];
+    if (value) {
+      parts.push(flag, shellQuote(value));
+    }
+  }
+  parts.push('--id', shellQuote(instanceId));
+  return parts.join(' ');
+}
+
 // Cleans up internal-looking role tokens. iOS's `role_description` can be
 // raw strings like "AXGenericElement" or empty when AppKit doesn't have a
 // description for the role. Android sets role to the className which is

package/src/index.ts

@@ -9,8 +9,10 @@ export { useDeviceInstall } from './hooks/use-device-install';
 export type { AxSnapshot, AxElement, AxRect, AxSelectors, AxPlatform } from './core/ax-tree';
 export type { AxStatus } from './core/ax-fetcher';
 export {
+  axCliTapCommand,
   axElementAtPoint,
   axElementSelectorExpression,
+  axElementSelectorObject,
   axElementSummary,
   axElementsEqual,
   axSnapshotsEqual,