npm - fixdog - Versions diffs - 0.0.1 - Mend

fixdog 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/README.md +478 -0
package/USAGE.md +77 -0
package/dist/client/index.d.mts +110 -0
package/dist/client/index.d.ts +110 -0
package/dist/client/index.js +1601 -0
package/dist/client/index.mjs +1582 -0
package/dist/client/init.d.mts +67 -0
package/dist/client/init.d.ts +67 -0
package/dist/client/init.js +1609 -0
package/dist/client/init.mjs +1593 -0
package/dist/index.d.mts +158 -0
package/dist/index.d.ts +158 -0
package/dist/index.js +1635 -0
package/dist/index.mjs +1606 -0
package/package.json +57 -0
package/src/api/client.ts +141 -0
package/src/client/index.ts +75 -0
package/src/client/init.tsx +78 -0
package/src/components/ConversationalInputReact.tsx +406 -0
package/src/components/ElementInfoDisplayReact.tsx +84 -0
package/src/components/UiDogSidebarReact.tsx +49 -0
package/src/element-detector.ts +186 -0
package/src/index.ts +228 -0
package/src/instrument.ts +171 -0
package/src/sidebar-initializer.ts +171 -0
package/src/source-resolver.ts +121 -0
package/src/styles/sidebarStyles.ts +597 -0
package/src/types/css.d.ts +9 -0
package/src/types/sidebar.ts +56 -0
package/src/types.ts +119 -0
package/tsconfig.json +23 -0
package/tsup.config.ts +40 -0

package/README.md ADDED Viewed

@@ -0,0 +1,478 @@
+# uidog-sdk-next
+Next.js integration for UiDog using [Bippy](https://github.com/aidenybai/bippy) - element source detection for React apps.
+This package provides **Alt+click element inspection** for Next.js applications, allowing you to click on any element in your app and see its source location (file, line, column) in a sidebar UI.
+## Features
+- **Alt+click** any element to inspect its source location
+- **Hover highlighting** when Alt is pressed
+- **Sidebar UI** for viewing element info and making edit requests
+- Supports **VS Code, Cursor, WebStorm, Atom, Sublime** editors
+- Works with **Next.js 14+** (App Router and Pages Router)
+- **Zero build configuration** - just import and use
+## Requirements
+- Next.js 14.0.0 or higher
+- React 17.0.0 or higher
+- Development mode only (`_debugSource` is stripped in production)
+## Installation
+```bash
+npm install uidog-sdk-next
+# or
+yarn add uidog-sdk-next
+# or
+pnpm add uidog-sdk-next
+```
+## Quick Start
+### Step 1: Create the instrumentation file
+Bippy must load **before React** to properly hook into React's internals. The setup differs based on your Next.js version.
+#### Next.js 15.3+ (Recommended)
+Create `instrumentation-client.ts` in your project root (same level as `package.json`):
+```typescript
+// instrumentation-client.ts
+import "uidog-sdk-next/client";
+```
+That's it! The package will auto-initialize with default settings.
+#### Next.js 14.x - 15.2
+For older Next.js versions, add the import at the very top of your `_app.tsx` or root layout:
+**Pages Router (`pages/_app.tsx`):**
+```typescript
+// pages/_app.tsx
+import "uidog-sdk-next/client"; // MUST be the first import!
+import type { AppProps } from "next/app";
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+```
+**App Router (`app/layout.tsx`):**
+```typescript
+// app/layout.tsx
+import "uidog-sdk-next/client"; // MUST be the first import!
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+### Step 2: Start your development server
+```bash
+npm run dev
+```
+### Step 3: Use it!
+1. Hold **Alt** (Option on Mac) and hover over elements - you'll see a blue highlight
+2. **Alt+click** on any element to open the sidebar
+3. The sidebar shows the element's source location (file, line, column)
+4. Type a message describing changes you want to make
+## Configuration
+### Using UiDogProvider (Optional)
+For more control over configuration, wrap your app with `UiDogProvider`:
+```tsx
+// app/layout.tsx (App Router)
+import "uidog-sdk-next/client"; // Still need this first!
+import { UiDogProvider } from "uidog-sdk-next/init";
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <UiDogProvider
+          editor="cursor" // Editor to open: 'vscode' | 'cursor' | 'webstorm' | 'atom' | 'sublime'
+          modifier="alt" // Key modifier: 'alt' | 'ctrl' | 'meta' | 'shift'
+          enableSidebar={true} // Show sidebar UI (set to false for console-only mode)
+          apiEndpoint="https://api.ui.dog" // API endpoint for edit requests
+        >
+          {children}
+        </UiDogProvider>
+      </body>
+    </html>
+  );
+}
+```
+### Configuration Options
+| Option          | Type      | Default                | Description                                                                                               |
+| --------------- | --------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `editor`        | `string`  | `'cursor'`             | Editor to open. Options: `'vscode'`, `'vscode-insiders'`, `'cursor'`, `'webstorm'`, `'atom'`, `'sublime'` |
+| `modifier`      | `string`  | `'alt'`                | Key to hold for element selection. Options: `'alt'`, `'ctrl'`, `'meta'`, `'shift'`                        |
+| `enableSidebar` | `boolean` | `true`                 | Show the sidebar UI. If `false`, logs to console instead                                                  |
+| `apiEndpoint`   | `string`  | `'https://api.ui.dog'` | API endpoint for edit session requests                                                                    |
+| `projectPath`   | `string`  | `''`                   | Project root path for resolving relative file paths                                                       |
+### Programmatic Configuration
+You can also configure before auto-initialization:
+```typescript
+// instrumentation-client.ts
+import { configureUiDogNext } from "uidog-sdk-next/client";
+configureUiDogNext({
+  editor: "vscode",
+  modifier: "alt",
+  enableSidebar: true,
+});
+```
+### Manual Initialization
+If you need full control, disable auto-init and initialize manually:
+```typescript
+// instrumentation-client.ts
+import { disableAutoInit } from "uidog-sdk-next/client";
+disableAutoInit();
+// Later, in your app code:
+import { initializeUiDogNext } from "uidog-sdk-next";
+initializeUiDogNext({
+  editor: "cursor",
+  enableSidebar: true,
+});
+```
+## Complete Example: Next.js 15 App Router
+### Project Structure
+```
+my-next-app/
+├── instrumentation-client.ts    # UiDog initialization
+├── app/
+│   ├── layout.tsx               # Root layout with UiDogProvider
+│   ├── page.tsx                 # Home page
+│   └── components/
+│       └── Button.tsx           # Example component
+├── package.json
+└── next.config.js
+```
+### Step-by-Step Setup
+**1. Install the package:**
+```bash
+npm install uidog-sdk-next
+```
+**2. Create `instrumentation-client.ts` in project root:**
+```typescript
+// instrumentation-client.ts
+import "uidog-sdk-next/client";
+```
+**3. Update `app/layout.tsx`:**
+```tsx
+// app/layout.tsx
+import { UiDogProvider } from "uidog-sdk-next/init";
+import "./globals.css";
+export const metadata = {
+  title: "My App",
+};
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <UiDogProvider editor="cursor">{children}</UiDogProvider>
+      </body>
+    </html>
+  );
+}
+```
+**4. Create a component to test (`app/components/Button.tsx`):**
+```tsx
+// app/components/Button.tsx
+"use client";
+interface ButtonProps {
+  children: React.ReactNode;
+  onClick?: () => void;
+}
+export function Button({ children, onClick }: ButtonProps) {
+  return (
+    <button
+      onClick={onClick}
+      className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
+    >
+      {children}
+    </button>
+  );
+}
+```
+**5. Use the component (`app/page.tsx`):**
+```tsx
+// app/page.tsx
+import { Button } from "./components/Button";
+export default function Home() {
+  return (
+    <main className="p-8">
+      <h1 className="text-2xl font-bold mb-4">My App</h1>
+      <Button>Click me</Button>
+    </main>
+  );
+}
+```
+**6. Start the dev server:**
+```bash
+npm run dev
+```
+**7. Test it:**
+- Open http://localhost:3000
+- Hold **Alt** and hover over the button - you'll see a blue highlight
+- **Alt+click** on the button
+- The sidebar opens showing `Button.tsx` with line and column numbers
+## Complete Example: Next.js 14 Pages Router
+### Project Structure
+```
+my-next-app/
+├── pages/
+│   ├── _app.tsx                 # App wrapper with UiDog
+│   ├── index.tsx                # Home page
+│   └── components/
+│       └── Card.tsx             # Example component
+├── package.json
+└── next.config.js
+```
+### Step-by-Step Setup
+**1. Install the package:**
+```bash
+npm install uidog-sdk-next
+```
+**2. Update `pages/_app.tsx`:**
+```tsx
+// pages/_app.tsx
+import "uidog-sdk-next/client"; // MUST be first!
+import type { AppProps } from "next/app";
+import { UiDogProvider } from "uidog-sdk-next/init";
+import "../styles/globals.css";
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <UiDogProvider editor="vscode">
+      <Component {...pageProps} />
+    </UiDogProvider>
+  );
+}
+```
+**3. Create a component (`pages/components/Card.tsx`):**
+```tsx
+// pages/components/Card.tsx
+interface CardProps {
+  title: string;
+  description: string;
+}
+export function Card({ title, description }: CardProps) {
+  return (
+    <div className="border rounded-lg p-4 shadow-sm">
+      <h2 className="text-xl font-semibold">{title}</h2>
+      <p className="text-gray-600 mt-2">{description}</p>
+    </div>
+  );
+}
+```
+**4. Use the component (`pages/index.tsx`):**
+```tsx
+// pages/index.tsx
+import { Card } from "./components/Card";
+export default function Home() {
+  return (
+    <div className="p-8">
+      <h1 className="text-2xl font-bold mb-4">My App</h1>
+      <Card
+        title="Welcome"
+        description="Alt+click on this card to see its source location!"
+      />
+    </div>
+  );
+}
+```
+**5. Start and test:**
+```bash
+npm run dev
+```
+## Vite (React) quick start
+- Development only. Import before React mounts so Bippy can hook DevTools.
+- Add at the very top of your entry (e.g., `src/main.tsx`):
+```ts
+if (import.meta.env.DEV) {
+  import("uidog-sdk-next/client");
+}
+```
+- Start Vite with `npm run dev` and use Alt+click. For library DOM (or anything without `_debugSource`), you'll see the DOM snapshot fallback instead of source mapping.
+## API Reference
+### Main Exports (`uidog-sdk-next`)
+```typescript
+import {
+  initializeUiDogNext, // Initialize UiDog manually
+  cleanupUiDogNext, // Cleanup all listeners and UI
+  isUiDogNextInitialized, // Check if initialized
+  openSidebar, // Programmatically open sidebar
+  closeSidebar, // Programmatically close sidebar
+  buildEditorUrl, // Build editor URL from source location
+} from "uidog-sdk-next";
+```
+### Client Exports (`uidog-sdk-next/client`)
+```typescript
+import {
+  configureUiDogNext, // Configure options before auto-init
+  disableAutoInit, // Disable auto-initialization
+  initializeUiDogNext, // Manual initialization
+} from "uidog-sdk-next/client";
+```
+### Provider Export (`uidog-sdk-next/init`)
+```typescript
+import { UiDogProvider } from "uidog-sdk-next/init";
+```
+## Troubleshooting
+### "Could not find source for element"
+This can happen when:
+1. **Production mode**: Source info (`_debugSource`) is stripped in production builds. Make sure you're running in development mode (`npm run dev`).
+2. **Server Components**: React Server Components render on the server and don't have fibers on the client. Only client components can be inspected.
+3. **Library components**: Components from `node_modules` are filtered out. You can only inspect your own source code.
+When source isn't available (e.g., server-rendered DOM), the sidebar will show a **DOM snapshot** instead: trimmed `outerHTML`, text content, attributes, and bounding box. This gives you “something to grab,” but still no file/line info without a client boundary.
+### Sidebar doesn't appear
+1. Make sure you imported `'uidog-sdk-next/client'` **before** any React imports
+2. Check the browser console for `[UiDog Next] Initialized` message
+3. Verify you're holding the correct modifier key (Alt by default)
+### Element highlighting doesn't work
+1. Check that `enableSidebar` is `true` (default)
+2. Try a different modifier key: `modifier="ctrl"` or `modifier="meta"`
+3. Some browser extensions may intercept Alt+click - try disabling them
+### Import order issues
+The import **must** be first:
+```typescript
+// CORRECT
+import "uidog-sdk-next/client";
+import { useState } from "react";
+// WRONG - React loads before bippy can hook in
+import { useState } from "react";
+import "uidog-sdk-next/client";
+```
+## How It Works
+1. **Bippy hooks into React**: When you import `'uidog-sdk-next/client'`, Bippy installs a hook at `window.__REACT_DEVTOOLS_GLOBAL_HOOK__` before React loads.
+2. **React reports fiber info**: As React renders, it reports fiber tree data to the hook, including `_debugSource` metadata.
+3. **Alt+click detection**: When you Alt+click an element, we find its React fiber and extract the source location.
+4. **Sidebar UI**: The sidebar displays the source info and allows you to describe changes you want to make.
+## Limitations
+- **Development only**: `_debugSource` is stripped in production React builds
+- **Client components only**: Server Components don't have client-side fibers
+- **React 17-19**: Bippy supports these React versions
+- **Next.js 14+**: Older versions may work but are not tested
+## License
+MIT
+## Related
+- [uidog-sdk](https://github.com/your-org/uidog-sdk) - Original SDK for Vite/Webpack apps
+- [Bippy](https://github.com/aidenybai/bippy) - React fiber inspection toolkit
+- [LocatorJS](https://github.com/nicepkg/locatorjs) - Alternative approach using Babel transforms

package/USAGE.md ADDED Viewed

@@ -0,0 +1,77 @@
+# Usage Guide
+## Next.js
+### Next.js 15.3+ (recommended)
+1. Create `instrumentation-client.ts` at project root:
+```ts
+import "uidog-sdk-next/client";
+```
+2. Run `npm run dev` and use Alt+click in the browser.
+### Next.js 14.x – 15.2
+- App Router (`app/layout.tsx`), first import:
+```ts
+import "uidog-sdk-next/client";
+```
+- Pages Router (`pages/_app.tsx`), first import:
+```ts
+import "uidog-sdk-next/client"; // must be first!
+```
+- Start dev server and Alt+click.
+### Optional: Provider config (sidebar, editor, modifier)
+```tsx
+// app/layout.tsx or pages/_app.tsx
+import "uidog-sdk-next/client";
+import { UiDogProvider } from "uidog-sdk-next/init";
+export default function RootLayout({ children }) {
+  return (
+    <UiDogProvider
+      editor="cursor"
+      modifier="alt"
+      enableSidebar={true}
+      apiEndpoint="https://api.ui.dog"
+    >
+      {children}
+    </UiDogProvider>
+  );
+}
+```
+## Vite (React)
+Load the client only in dev and **before React mounts**.
+```ts
+// src/main.tsx (or entry), top of file
+if (import.meta.env.DEV) {
+  import("uidog-sdk-next/client");
+}
+// then your normal React render
+```
+Start Vite with `npm run dev` and Alt+click elements in the browser.
+## How to use
+1. Run the dev server.
+2. Hold **Alt** (default modifier) and hover to see highlight.
+3. **Alt+click** an element to open the sidebar.
+4. Sidebar shows source file/line when available; otherwise a DOM snapshot (for server-rendered or library DOM).
+## Notes & limits
+- Dev-only; production builds strip source metadata.
+- Server Components and library DOM won’t have source locations; the sidebar shows a DOM snapshot instead.
+- The import must run before any React import so Bippy can hook DevTools.

package/dist/client/index.d.mts ADDED Viewed

@@ -0,0 +1,110 @@
+type ElementInfoKind = "source" | "dom";
+interface DomSnapshot {
+    outerHTML: string;
+    text: string;
+    attributes: Record<string, string>;
+}
+interface ElementInfo {
+    kind: ElementInfoKind;
+    componentName?: string;
+    filePath?: string;
+    line?: number;
+    column?: number;
+    domSnapshot?: DomSnapshot;
+    box?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+type EditorType = "vscode" | "vscode-insiders" | "cursor" | "webstorm" | "atom" | "sublime";
+interface UiDogNextOptions {
+    /**
+     * Editor to open when clicking elements
+     * @default 'cursor'
+     */
+    editor?: EditorType;
+    /**
+     * Project root path for resolving file paths
+     */
+    projectPath?: string;
+    /**
+     * Modifier key for element selection
+     * @default 'alt'
+     */
+    modifier?: "alt" | "ctrl" | "meta" | "shift";
+    /**
+     * Enable sidebar mode
+     * @default true
+     */
+    enableSidebar?: boolean;
+    /**
+     * API endpoint for edit requests
+     * @default 'https://api.ui.dog'
+     */
+    apiEndpoint?: string;
+}
+declare global {
+    interface Window {
+        __UIDOG_NEXT_INITIALIZED__?: boolean;
+        __UIDOG_SIDEBAR__?: {
+            isOpen: boolean;
+            elementInfo: ElementInfo | null;
+            editorUrl: string | null;
+        };
+    }
+}
+/**
+ * UiDog SDK for Next.js - Main entry point
+ *
+ * Uses Bippy to hook into React's internals for element source detection,
+ * providing a seamless developer experience for inspecting component locations.
+ */
+/**
+ * Initialize UiDog for Next.js
+ *
+ * This function sets up Bippy instrumentation, element detection, and the sidebar UI.
+ * It should be called early in your application's lifecycle, ideally via
+ * instrumentation-client.ts (Next.js 15.3+) or at the top of _app.tsx.
+ */
+declare function initializeUiDogNext(options?: UiDogNextOptions): void;
+/**
+ * Client entry point for UiDog Next.js integration
+ *
+ * This file is designed to be imported in:
+ * - Next.js 15.3+: instrumentation-client.ts at project root
+ * - Next.js 14.x / Pages Router: top of _app.tsx (must be first import)
+ *
+ * IMPORTANT: This file MUST be imported BEFORE React loads to properly
+ * install Bippy's React DevTools hook.
+ *
+ * Usage:
+ * ```typescript
+ * // instrumentation-client.ts (Next.js 15.3+)
+ * import 'uidog-sdk-next/client';
+ * ```
+ *
+ * ```typescript
+ * // pages/_app.tsx (Next.js 14.x / Pages Router)
+ * import 'uidog-sdk-next/client'; // MUST be first import
+ * import type { AppProps } from 'next/app';
+ * // ... rest of your imports
+ * ```
+ */
+/**
+ * Configure UiDog options before initialization
+ * Call this before auto-initialization happens (at DOMContentLoaded)
+ */
+declare function configureUiDogNext(options: UiDogNextOptions): void;
+/**
+ * Disable auto-initialization
+ * Use this if you want to manually initialize UiDog later
+ */
+declare function disableAutoInit(): void;
+export { UiDogNextOptions, configureUiDogNext, disableAutoInit, initializeUiDogNext };