### Initialize Domscribe Project

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Run this command to start the setup wizard for Domscribe. The wizard guides you through connecting your AI agent and adding Domscribe to your application.

```bash
npx domscribe init
```

--------------------------------

### Install Dependencies and Run Tasks

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Use these commands to install project dependencies and then build, test, and lint the project. Ensure you have pnpm installed.

```bash
pnpm install
nx run-many -t build test lint typecheck
```

--------------------------------

### Installation

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-transform/README.md

Install @domscribe/transform as a development dependency.

```APIDOC
## Install

```bash
npm install -D @domscribe/transform
```

> **Note:** You probably want a framework adapter instead (`@domscribe/react`, `@domscribe/vue`, `@domscribe/next`, `@domscribe/nuxt`). Those packages wrap this one and handle framework-specific wiring automatically.
```

--------------------------------

### Install @domscribe/verify

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-verify/README.md

Install the package using npm. This is an internal package and likely not needed for direct installation.

```bash
npm install @domscribe/verify
```

--------------------------------

### Installation

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-react/README.md

Install the React adapter for Domscribe as a development dependency.

```APIDOC
## Install

```bash
npm install -D @domscribe/react
```
```

--------------------------------

### Install @domscribe/overlay

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-overlay/README.md

Use npm to install the package. This is usually handled by framework adapters.

```bash
npm install @domscribe/overlay
```

--------------------------------

### Installation

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-runtime/README.md

Install the @domscribe/runtime package using npm.

```APIDOC
## Install

```bash
npm install @domscribe/runtime
```
```

--------------------------------

### Install @domscribe/runtime

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-runtime/README.md

Install the runtime package via npm.

```bash
npm install @domscribe/runtime
```

--------------------------------

### Install @domscribe/vue

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-vue/README.md

Install the package as a development dependency.

```bash
npm install -D @domscribe/vue
```

--------------------------------

### Install @domscribe/manifest

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-manifest/README.md

Use npm to install the package as a dependency.

```bash
npm install @domscribe/manifest
```

--------------------------------

### Install @domscribe/mcp

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-mcp/README.md

Installation commands for the MCP server package.

```bash
npm install @domscribe/mcp
```

```bash
npx -y @domscribe/mcp
```

--------------------------------

### Install @domscribe/relay

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-relay/README.md

Install the package via npm.

```bash
npm install @domscribe/relay
```

--------------------------------

### Install @domscribe/react

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-react/README.md

Install the React adapter for Domscribe as a development dependency.

```bash
npm install -D @domscribe/react
```

--------------------------------

### Install @domscribe/transform

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-transform/README.md

Install the @domscribe/transform package as a development dependency.

```bash
npm install -D @domscribe/transform
```

--------------------------------

### Install @domscribe/core

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-core/README.md

Use npm to install the core Domscribe package. Note that framework adapters are usually preferred.

```bash
npm install @domscribe/core
```

--------------------------------

### Install GitHub Copilot Plugin for Domscribe

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Command to install the Domscribe plugin for GitHub Copilot.

```bash
copilot plugin install patchorbit/domscribe
```

--------------------------------

### Example Response for domscribe.query.bySource

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-mcp/README.md

Sample JSON response showing source location and live runtime data.

```json
{
  "sourceLocation": {
    "file": "src/components/Button.tsx",
    "line": 12,
    "column": 4,
    "componentName": "Button",
    "tagName": "button"
  },
  "runtime": {
    "componentProps": { "variant": "secondary", "onClick": "[Function]" },
    "componentState": { "hook_0": false, "hook_1": "idle" },
    "domSnapshot": {
      "tagName": "button",
      "attributes": { "class": "btn-secondary", "type": "submit" },
      "innerText": "Save changes"
    }
  },
  "browserConnected": true
}
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Use this command to install project dependencies. Ensure you are using pnpm, not npm.

```bash
pnpm install
```

--------------------------------

### Example Response: domscribe.query.bySource

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-mcp/README.md

Example response structure for the `domscribe.query.bySource` tool, illustrating source location and runtime data.

```APIDOC
### `domscribe.query.bySource`

Returns the source location matched in the manifest plus live runtime data captured from the browser.

```json
{
  "sourceLocation": {
    "file": "src/components/Button.tsx",
    "line": 12,
    "column": 4,
    "componentName": "Button",
    "tagName": "button"
  },
  "runtime": {
    "componentProps": {
      "variant": "secondary",
      "onClick": "[Function]"
    },
    "componentState": {
      "hook_0": false,
      "hook_1": "idle"
    },
    "domSnapshot": {
      "tagName": "button",
      "attributes": {
        "class": "btn-secondary",
        "type": "submit"
      },
      "innerText": "Save changes"
    }
  },
  "browserConnected": true
}
```
```

--------------------------------

### Install Domscribe Extension for Gemini CLI

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Installs the Domscribe extension for the Gemini CLI using its GitHub repository.

```bash
gemini extensions install https://github.com/patchorbit/domscribe
```

--------------------------------

### Any Framework Webpack Plugin for DOM-to-Source Mapping

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Configure Domscribe for DOM-to-source mapping in any framework using Webpack by installing `@domscribe/transform/plugins/webpack` and adding `DomscribeWebpackPlugin` to your `webpack.config.js`. This setup is for development and includes an overlay.

```javascript
const {
  DomscribeWebpackPlugin,
} = require('@domscribe/transform/plugins/webpack');

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        exclude: /node_modules/,
        enforce: 'pre',
        use: [
          {
            loader: '@domscribe/transform/webpack-loader',
            options: { enabled: isDevelopment },
          },
        ],
      },
    ],
  },
  plugins: [
    new DomscribeWebpackPlugin({
      enabled: isDevelopment,
      overlay: true,
    }),
  ],
};
```

--------------------------------

### MCP Tool Schema Example

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

An example schema for an MCP tool, demonstrating the structure for defining tool name, description, and input schema.

```json
{
  "name": "annotation-get",
  "description": "Retrieve an annotation by its ID",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": { "type": "string", "description": "Annotation ID (ann_*)" }
    },
    "required": ["id"]
  }
}
```

--------------------------------

### Add Domscribe Skills for Any Agent

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Installs the Domscribe skills using npx. Ensure you have Node.js and npm installed.

```sh
npx skills add patchorbit/domscribe
```

--------------------------------

### Subpath Exports Example: Auto Initialization

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Example of accessing a subpath export for auto-initialization within the @domscribe/overlay package.

```bash
@domscribe/overlay/auto-init
```

--------------------------------

### Install Domscribe via Package Managers

Source: https://github.com/patchorbit/domscribe/blob/main/skills/domscribe/references/config-patterns.md

Use these commands to install Domscribe as a development dependency based on your project's lockfile.

```bash
pnpm add -D
```

```bash
yarn add -D
```

```bash
bun add -D
```

```bash
npm install -D
```

--------------------------------

### Subpath Exports Example: Vue Auto Initialization

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Example of accessing a subpath export for auto-initialization within the @domscribe/vue package.

```bash
@domscribe/vue/auto-init
```

--------------------------------

### Subpath Exports Example: React Auto Initialization

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Example of accessing a subpath export for auto-initialization within the @domscribe/react package.

```bash
@domscribe/react/auto-init
```

--------------------------------

### Run Verdaccio Local Registry

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Starts a local npm registry on port 4873 using the specified configuration file.

```bash
npx verdaccio --config .verdaccio/config.yml --listen 4873
```

--------------------------------

### Run E2E Tests

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Execute end-to-end tests. This requires Verdaccio and published packages. Environment variables like SKIP_SETUP, SKIP_PUBLISH, and SKIP_INSTALL can be used to skip specific setup steps.

```bash
nx e2e domscribe-test-fixtures
```

--------------------------------

### MCP Prompts Reference

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-mcp/README.md

Reference for pre-built prompts that guide agents through common Domscribe workflows.

```APIDOC
## MCP Prompts

Pre-built prompts that guide agents through common Domscribe workflows.

| Prompt | Purpose |
|---|---|
| `process_next` | Guide through annotation processing |
| `check_status` | Check relay status |
| `explore_component` | Explore component metadata |
| `find_annotations` | Search for annotations |
```

--------------------------------

### Verdaccio Pipeline Steps

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

Outlines the steps involved in the Verdaccio pipeline for integration and end-to-end testing. This sequence is crucial for setting up a local package registry and testing package publishing and installation.

```text
1. Start Verdaccio on port 4873
2. Build all packages (nx run-many -t build)
3. Version: prerelease (dev.N)
4. Sync-dist: resolve workspace deps
5. Publish to localhost:4873
6. For each fixture:
   a. Generate .npmrc pointing to Verdaccio
   b. npm install --no-package-lock
   c. Write .domscribe-install-stamp
7. Run tests (integration or e2e)

```

--------------------------------

### Subpath Exports Example: Vite Plugin

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Example of accessing a subpath export for a Vite plugin within the @domscribe/transform package.

```bash
@domscribe/transform/plugins/vite
```

--------------------------------

### Install @domscribe/nuxt

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-nuxt/README.md

Use this command to add the Domscribe module to your Nuxt 3+ project dependencies.

```bash
npm install @domscribe/nuxt
```

--------------------------------

### GET /api/manifest

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

Queries manifest entries.

```APIDOC
## GET /api/manifest

### Description
Queries manifest entries.

### Method
GET

### Endpoint
/api/manifest

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **entries** (array) - An array of manifest entry objects.
```

--------------------------------

### Subpath Exports Example: Webpack Loader

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Example of accessing a subpath export for a Webpack loader within the @domscribe/transform package.

```bash
@domscribe/transform/webpack-loader
```

--------------------------------

### GET /api/annotations

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

Lists all annotations available in the system.

```APIDOC
## GET /api/annotations

### Description
Lists all annotations available in the system.

### Method
GET

### Endpoint
/api/annotations

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **annotations** (array) - An array of annotation objects.
```

--------------------------------

### Subpath Exports Example: Vue Webpack Integration

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Example of accessing a subpath export for Webpack integration within the @domscribe/vue package.

```bash
@domscribe/vue/webpack
```

--------------------------------

### Subpath Exports Example: Webpack Plugin

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Example of accessing a subpath export for a Webpack plugin within the @domscribe/transform package.

```bash
@domscribe/transform/plugins/webpack
```

--------------------------------

### HTML Wordmark Usage Example

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-overlay/src/assets/logo-assets.html

Demonstrates how to implement the Domscribe wordmark using a span element with the 'wordmark' CSS class.

```html
<span class="wordmark">domscribe</span>
```

--------------------------------

### Subpath Exports Example: Vue Vite Integration

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Example of accessing a subpath export for Vite integration within the @domscribe/vue package.

```bash
@domscribe/vue/vite
```

--------------------------------

### GET /domscribe.status

Source: https://github.com/patchorbit/domscribe/blob/main/domscribe-power/POWER.md

Retrieves system health and queue information.

```APIDOC
## GET /domscribe.status

### Description
Relays system health, manifest status, and current queue counts.

### Method
GET

### Endpoint
/domscribe.status

### Response
#### Success Response (200)
- **health** (string) - System status
- **manifest** (object) - Manifest metadata
- **queueCount** (integer) - Number of pending annotations
```

--------------------------------

### Usage Grid Layout

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-overlay/src/assets/logo-assets.html

Defines a two-column grid layout for usage examples. Includes a media query to stack columns on smaller screens.

```css
.usage-grid { display: grid;
  grid-template-columns: repeat(2, 1fr);
  gap: 24px;
}

@media (max-width: 800px) {
  .usage-grid { grid-template-columns: 1fr; }
  .comparison { grid-temp
```

--------------------------------

### Subpath Exports Example: React Vite Integration

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Example of accessing a subpath export for Vite integration within the @domscribe/react package.

```bash
@domscribe/react/vite
```

--------------------------------

### GET /ws

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

WebSocket upgrade endpoint for real-time event subscriptions.

```APIDOC
## GET /ws

### Description
WebSocket upgrade endpoint for real-time event subscriptions.

### Method
GET

### Endpoint
/ws

### Parameters
None

### Request Example
None

### Response
#### Success Response (101)
- **Upgrade** (string) - Indicates a WebSocket upgrade.
- **Connection** (string) - Indicates an upgrade connection.
```

--------------------------------

### Any Framework Vite Plugin for DOM-to-Source Mapping

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Use the `@domscribe/transform/plugins/vite` package for DOM-to-source mapping in any framework with Vite. This setup does not include runtime capture.

```typescript
import { defineConfig } from 'vite';
import { domscribe } from '@domscribe/transform/plugins/vite';

export default defineConfig({
  plugins: [domscribe()],
});
```

--------------------------------

### Vue Webpack Plugin Setup with Domscribe

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Configure Domscribe for Vue 3+ projects using Webpack by installing `@domscribe/vue/webpack` and adding `DomscribeWebpackPlugin` to your `webpack.config.js`. This setup includes a pre-loader for development.

```javascript
const { DomscribeWebpackPlugin } = require('@domscribe/vue/webpack');

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        exclude: /node_modules/,
        enforce: 'pre',
        use: [
          {
            loader: '@domscribe/transform/webpack-loader',
            options: { enabled: isDevelopment },
          },
        ],
      },
    ],
  },
  plugins: [
    new DomscribeWebpackPlugin({
      enabled: isDevelopment,
      overlay: true,
    }),
  ],
};
```

--------------------------------

### Nuxt 3+ Configuration with Domscribe

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Add Domscribe to your Nuxt 3+ project by installing the `@domscribe/nuxt` package and including it in your `nuxt.config.ts` modules array.

```typescript
export default defineNuxtConfig({
  modules: ['@domscribe/nuxt'],
});
```

--------------------------------

### Vue Vite Plugin Setup with Domscribe

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Integrate Domscribe into Vue 3+ projects using Vite by installing `@domscribe/vue/vite` and adding the `domscribe()` plugin to your `vite.config.ts`.

```typescript
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { domscribe } from '@domscribe/vue/vite';

export default defineConfig({
  plugins: [vue(), domscribe()],
});
```

--------------------------------

### React Vite Plugin Setup with Domscribe

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Configure Domscribe for React 18-19 projects using Vite by installing `@domscribe/react/vite` and adding the `domscribe()` plugin to your `vite.config.ts`.

```typescript
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { domscribe } from '@domscribe/react/vite';

export default defineConfig({
  plugins: [react(), domscribe()],
});
```

--------------------------------

### React Webpack Plugin Setup with Domscribe

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Set up Domscribe for React 18-19 projects using Webpack by installing `@domscribe/react/webpack` and adding `DomscribeWebpackPlugin` to your `webpack.config.js`. This configuration includes a pre-loader for development.

```javascript
const { DomscribeWebpackPlugin } = require('@domscribe/react/webpack');

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        exclude: /node_modules/,
        enforce: 'pre',
        use: [
          {
            loader: '@domscribe/transform/webpack-loader',
            options: { enabled: isDevelopment },
          },
        ],
      },
    ],
  },
  plugins: [
    new DomscribeWebpackPlugin({
      enabled: isDevelopment,
      overlay: true,
    }),
  ],
};
```

--------------------------------

### Build, Lint, and Test All Packages

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Execute this command to build, lint, and test all packages within the repository, excluding the test-fixtures package.

```bash
pnpm build:all
```

--------------------------------

### POST /RuntimeManager/initialize

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-runtime/CUSTOM_ADAPTERS.md

Registers a custom framework adapter with the Domscribe runtime.

```APIDOC
## POST /RuntimeManager/initialize

### Description
Initializes the Domscribe runtime with a specific framework adapter instance.

### Request Body
- **adapter** (FrameworkAdapter) - Required - An instance of a class implementing the FrameworkAdapter interface.

### Request Example
```ts
RuntimeManager.getInstance().initialize({
  adapter: new SvelteAdapter(),
});
```
```

--------------------------------

### RuntimeManager Initialization

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-runtime/README.md

Initialize the RuntimeManager singleton with adapter and configuration options.

```APIDOC
## RuntimeManager Initialization

### Description
Initialize the RuntimeManager singleton to manage the active adapter and provide the capture API.

### Method
```typescript
RuntimeManager.getInstance().initialize(options: RuntimeOptions)
```

### Parameters
#### Request Body
- **adapter** (FrameworkAdapter) - Required - Framework adapter for context capture.
- **phase** (1 | 2) - Optional - Feature phase gate. Phase 1: props and state capture. Phase 2: event flow and performance metrics (future).
- **debug** (boolean) - Optional - Enable debug logging.
- **redactPII** (boolean) - Optional - Redact sensitive values (emails, tokens) in captured data.
- **blockSelectors** (string[]) - Optional - CSS selectors for elements to skip during capture.
- **serialization** (SerializationConstraints) - Optional - Serialization constraints for captured props and state.

### Request Example
```json
{
  "adapter": myAdapter,
  "phase": 1,
  "debug": false,
  "redactPII": true,
  "blockSelectors": [],
  "serialization": {
    "maxDepth": 6,
    "maxArrayLength": 20,
    "maxStringLength": 2048,
    "maxProperties": 50,
    "maxTotalBytes": 262144
  }
}
```

### Response
`initialize()` is safe to call multiple times — subsequent calls with the same configuration are no-ops.

### Notes
`initialize()` returns a Promise that resolves when the runtime is ready.
```

--------------------------------

### Configure MCP Server

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-mcp/README.md

Add the domscribe server to your MCP configuration file.

```json
{
  "mcpServers": {
    "domscribe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@domscribe/mcp"]
    }
  }
}
```

--------------------------------

### Nx Build Pipeline Flow

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

Illustrates the build process from source code to a publish-ready package.json, including steps like tsc compilation and sync-dist script execution.

```text
Source (packages/domscribe-*/src/)
    │
    ▼ tsc (via @nx/js/typescript)
    │
dist/packages/domscribe-*
    │
    ▼ sync-dist (scripts/sync-dist.mjs)
    │  - Copy version from source package.json
    │  - Resolve workspace:* → actual versions
    │  - Generate subpath exports from distExports
    │  - Patch bin entries from distBin
    │  - Remove distExports/distBin fields
    │
dist/packages/domscribe-*/package.json (publish-ready)
```

--------------------------------

### Configuration Options

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-transform/README.md

Details on configuration options for Relay and Overlay.

```APIDOC
## Configuration

### Shared Options — Relay

These options apply to the `relay` field across all bundler plugins.

| Option      | Type      | Default           | Description                                              |
|-------------|-----------|-------------------|----------------------------------------------------------|
| `autoStart` | `boolean` | `true`            | Auto-start the relay daemon if not running               |
| `port`      | `number`  | `0` (dynamic)     | Relay server port (only used when starting)              |
| `host`      | `string`  | `'127.0.0.1'`     | Relay server host (only used when starting)              |
| `bodyLimit` | `number`  | `10485760` (10MB) | Max request body size in bytes (only used when starting) |

### Shared Options — Overlay

These options apply when `overlay` is set to an object instead of a boolean.

| Option        | Type                        | Default       | Description                          |
|---------------|-----------------------------|---------------|--------------------------------------|
| `initialMode` | `'collapsed' | 'expanded'` | `'collapsed'` | Initial display mode for the overlay |
| `debug`       | `boolean`                   | `false`       | Enable debug logging in the overlay  |
```

--------------------------------

### Monorepo Initialization with Domscribe

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Initialize Domscribe in a monorepo by specifying the application root directory using the `--app-root` flag during `npx domscribe init`.

```bash
npx domscribe init --app-root apps/web
```

--------------------------------

### Minimal SvelteAdapter Implementation

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-runtime/CUSTOM_ADAPTERS.md

A basic implementation of the `FrameworkAdapter` for Svelte, demonstrating how to capture component instance, props, state, and name. Includes version detection.

```typescript
import type { FrameworkAdapter } from '@domscribe/runtime';

export class SvelteAdapter implements FrameworkAdapter {
  readonly name = 'svelte';
  readonly version: string | undefined;

  constructor() {
    // Detect framework version if possible
    this.version = this.detectVersion();
  }

  getComponentInstance(element: HTMLElement): unknown | null {
    // Svelte 5 attaches component context to DOM elements
    // via __svelte_meta or similar internal property.
    // Walk up from the element to find the owning component.
    const meta = (element as any).__svelte_meta;
    return meta?.component ?? null;
  }

  captureProps(component: unknown): Record<string, unknown> | null {
    if (!this.isSvelteComponent(component)) return null;

    // Extract props from the component's public API
    // Svelte 5 runes: read from the component's exported bindings
    try {
      const props: Record<string, unknown> = {};
      // ... framework-specific extraction logic
      return Object.keys(props).length > 0 ? props : null;
    } catch {
      return null;
    }
  }

  captureState(component: unknown): Record<string, unknown> | null {
    if (!this.isSvelteComponent(component)) return null;

    // Extract reactive state
    try {
      const state: Record<string, unknown> = {};
      // ... framework-specific extraction logic
      return Object.keys(state).length > 0 ? state : null;
    } catch {
      return null;
    }
  }

  getComponentName(component: unknown): string | null {
    if (!this.isSvelteComponent(component)) return null;
    // Svelte components often have a constructor name or metadata
    return (component as any).constructor?.name ?? null;
  }

  private isSvelteComponent(value: unknown): boolean {
    // Type guard for your framework's component instances
    return value != null && typeof value === 'object';
  }

  private detectVersion(): string | undefined {
    try {
      return (globalThis as any).__svelte?.version;
    } catch {
      return undefined;
    }
  }
}
```

--------------------------------

### Subpath Exports Example: React Webpack Integration

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Example of accessing a subpath export for Webpack integration within the @domscribe/react package.

```bash
@domscribe/react/webpack
```

--------------------------------

### POST /domscribe.query.bySource

Source: https://github.com/patchorbit/domscribe/blob/main/domscribe-power/POWER.md

Queries runtime and manifest data for a specific file and line number.

```APIDOC
## POST /domscribe.query.bySource

### Description
Retrieves runtime data and manifest information for an element at a specific source location.

### Method
POST

### Endpoint
/domscribe.query.bySource

### Parameters
#### Request Body
- **file** (string) - Required - Absolute file path from manifest
- **line** (integer) - Required - 1-indexed line number
- **tolerance** (integer) - Optional - Match elements within N lines (default: 0)
- **column** (integer) - Optional - 0-indexed column number
- **includeRuntime** (boolean) - Optional - Skip browser query if true (default: true)

### Response
#### Success Response (200)
- **sourceLocation** (object) - Confirmed file, line range, tag, and component name
- **runtime** (object) - Live browser data (props, state, DOM snapshot)
- **browserConnected** (boolean) - Status of the WebSocket browser connection
```

--------------------------------

### Run Integration Tests

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Execute integration tests for the test-fixtures package.

```bash
nx integration domscribe-test-fixtures
```

--------------------------------

### Running the Styling Falsifier Harness

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-test-fixtures/styling/README.md

Provides commands to run the falsifier for CI verification, baseline recording, and grading external agent output.

```bash
# CI default — verifies the mechanism (should be 100% pass).
pnpm test:falsifier

# Re-record baselines after editing an /after route.
pnpm test:falsifier:record

# Grade an external agent's output directory.
pnpm test:falsifier -- --mode=measure --agent-output=/path/to/agent/png/dir
```

--------------------------------

### Run Domscribe CLI Commands

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-relay/README.md

Manage the relay server process and workspace configuration using the provided CLI commands.

```bash
domscribe serve     # Start relay server (foreground or --daemon)
domscribe status    # Check relay daemon status
domscribe stop      # Stop relay daemon
domscribe init      # Setup wizard (agent + framework configuration)
domscribe mcp       # Run as MCP server via stdio
```

--------------------------------

### GET /api/health

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

Performs a health check on the relay server.

```APIDOC
## GET /api/health

### Description
Performs a health check on the relay server.

### Method
GET

### Endpoint
/api/health

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **health** (string) - Indicates the health status of the server (e.g., 'ok').
```

--------------------------------

### Build a Single Package

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Use this command to perform a build operation on a specific package, identified by its name.

```bash
nx build domscribe-core
```

--------------------------------

### GET /api/manifest/:id

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

Resolves a single manifest entry by its ID.

```APIDOC
## GET /api/manifest/:id

### Description
Resolves a single manifest entry by its ID.

### Method
GET

### Endpoint
/api/manifest/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the manifest entry.
```

--------------------------------

### GET /api/annotations/:id

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

Retrieves a specific annotation by its unique ID.

```APIDOC
## GET /api/annotations/:id

### Description
Retrieves a specific annotation by its unique ID.

### Method
GET

### Endpoint
/api/annotations/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the annotation.
```

--------------------------------

### GET /api/status

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

Retrieves the current server status and manifest statistics.

```APIDOC
## GET /api/status

### Description
Retrieves the current server status and manifest statistics.

### Method
GET

### Endpoint
/api/status

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - The current status of the server.
- **manifestStats** (object) - Statistics about the manifest entries.
```

--------------------------------

### Initialize RuntimeManager

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-runtime/README.md

Initialize the singleton RuntimeManager with a framework adapter and configuration options.

```typescript
import { RuntimeManager } from '@domscribe/runtime';

const runtime = RuntimeManager.getInstance();
await runtime.initialize({
  adapter: myAdapter,
  phase: 1,
  debug: false,
  redactPII: true,
  blockSelectors: [],
});
```

--------------------------------

### Registering a Custom Adapter

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-runtime/CUSTOM_ADAPTERS.md

Initializes the Domscribe RuntimeManager with a custom framework adapter, such as the SvelteAdapter, in your application's entry point.

```typescript
import { RuntimeManager } from '@domscribe/runtime';
import { SvelteAdapter } from './svelte-adapter';

RuntimeManager.getInstance().initialize({
  adapter: new SvelteAdapter(),
});
```

--------------------------------

### MCP Tool Schema

Source: https://github.com/patchorbit/domscribe/blob/main/TECHNICAL_SPEC.md

Example schema for an MCP tool, specifically for retrieving an annotation by its ID.

```APIDOC
## MCP Tool Schema (example)

```json
{
  "name": "annotation-get",
  "description": "Retrieve an annotation by its ID",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Annotation ID (ann_*)"
      }
    },
    "required": ["id"]
  }
}
```
```

--------------------------------

### Local Registry Pipeline

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Commands for managing the local registry pipeline, including building, versioning, syncing, publishing, and running integration/e2e tests.

```bash
pnpm release:local
```

```bash
pnpm pipeline:full
```

```bash
pnpm pipeline:e2e
```

--------------------------------

### Configure Webpack Plugin

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-transform/README.md

Instantiate the DomscribeWebpackPlugin with desired options for Webpack builds. Ensure correct import path.

```typescript
import { DomscribeWebpackPlugin } from '@domscribe/transform/plugins/webpack';

new DomscribeWebpackPlugin({
  enabled: true,
  debug: false,
  relay: { autoStart: true, port: 0, host: '127.0.0.1' },
  overlay: true,
});
```

--------------------------------

### Configure Webpack with Domscribe

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-react/README.md

Add the DomscribeWebpackPlugin to your Webpack configuration. Refer to the @domscribe/transform README for a complete Webpack setup.

```javascript
const { DomscribeWebpackPlugin } = require('@domscribe/react/webpack');

// Add to plugins array + add webpack loader rule
// (see @domscribe/transform README for full webpack config)
```

--------------------------------

### Lint a Single Package

Source: https://github.com/patchorbit/domscribe/blob/main/CLAUDE.md

Execute the linting process for a specified package.

```bash
nx lint domscribe-core
```

--------------------------------

### Next.js Configuration with Domscribe

Source: https://github.com/patchorbit/domscribe/blob/main/README.md

Integrate Domscribe into your Next.js 15+ project by installing the `@domscribe/next` package and wrapping your Next.js config with `withDomscribe()`.

```typescript
import type { NextConfig } from 'next';
import { withDomscribe } from '@domscribe/next';

const nextConfig: NextConfig = {};

export default withDomscribe()(nextConfig);
```

--------------------------------

### Overlay Configuration Options

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-overlay/README.md

Defines the configuration interface for the overlay, specifying initial display mode, debug logging, and sidebar width.

```typescript
interface OverlayOptions {
  initialMode?: 'collapsed' | 'expanded' | 'capturing';
  debug?: boolean;
  sidebarWidth?: number;
}
```

--------------------------------

### FrameworkAdapter Interface

Source: https://github.com/patchorbit/domscribe/blob/main/packages/domscribe-runtime/README.md

Defines the core methods required to implement a framework-specific adapter for Domscribe.

```APIDOC
## FrameworkAdapter Interface

### Description
Adapters implement the FrameworkAdapter interface to bridge the runtime to a specific framework's internal component model.

### Interface Definition
- **name** (string) - The name of the adapter.
- **version** (string) - Optional version identifier.
- **getComponentInstance(element: HTMLElement)** - Returns the framework component instance associated with the DOM element.
- **captureProps(component: unknown)** - Extracts props from the component instance.
- **captureState(component: unknown)** - Extracts state from the component instance.
- **getComponentName(component: unknown)** - Optional: Returns the display name of the component.
- **getComponentTree(component: unknown)** - Optional: Returns the component hierarchy as a ComponentTreeNode.
- **getSerializationHints()** - Optional: Returns configuration for skipping internal framework keys during serialization.
```