domscribe

Domscribe

Domscribe bridges running UI and source code. It maps every rendered element to its exact source location and captures live runtime context (props, state, DOM). This works in two directions:

• UI → Code: User clicks an element in the browser, Domscribe captures it as an annotation with source location, runtime context, and user intent. You claim and implement it.
• Code → UI: You're editing a source file and want to know what an element looks like at runtime. Query by file and line to get live props, state, and DOM snapshot.

Setup / Initialization

If domscribe.status returns active: false, Domscribe is not yet configured in this workspace. The .domscribe/ directory is created automatically when the dev server starts with the Domscribe bundler plugin configured. Follow this procedure to set it up:

1. Confirm dormant state — call domscribe.status. If active: false, proceed. Note the cwd in the response.
2. Detect framework — read package.json (at cwd, or at the appRoot from domscribe.config.json if it exists) and match dependencies against the table below.
3. Detect package manager — check which lockfile exists at the project root.
4. Install the package — run the appropriate install command via Bash (e.g., pnpm add -D @domscribe/next).
5. Edit the bundler config — read the config file and apply the integration pattern. Load references/config-patterns.md for the exact import, transformation, and example for each framework.
6. Update .gitignore — if .domscribe is not already listed, append a # Domscribe artifacts comment and .domscribe entry.
7. Inform the user — tell them to start (or restart) their dev server. Domscribe activates automatically on first run.

Framework Detection

Check dependencies and devDependencies in package.json. Match top-down (first match wins):

| Dependency | Framework | | ------------------- | ------------- | | next | next | | nuxt | nuxt | | react + vite | react-vite | | react (no vite) | react-webpack | | vue + vite | vue-vite | | vue (no vite) | vue-webpack | | vite only | other-vite | | webpack only | other-webpack |

Package Mapping

| Framework | Package | Config file | | ------------- | ---------------------- | ------------------- | | next | @domscribe/next | next.config.ts | | nuxt | @domscribe/nuxt | nuxt.config.ts | | react-vite | @domscribe/react | vite.config.ts | | react-webpack | @domscribe/react | webpack.config.js | | vue-vite | @domscribe/vue | vite.config.ts | | vue-webpack | @domscribe/vue | webpack.config.js | | other-vite | @domscribe/transform | vite.config.ts | | other-webpack | @domscribe/transform | webpack.config.js |

Package Manager Detection

| Lockfile | Package manager | | ------------------------ | --------------- | | pnpm-lock.yaml | pnpm | | yarn.lock | yarn | | bun.lock / bun.lockb | bun | | (none) | npm |

Install command pattern: <pm> add -D <package> (pnpm/yarn/bun) or npm install -D <package>.

Monorepo Projects

If domscribe.config.json exists at the project root with an appRoot field, the frontend app lives in that subdirectory. Install packages and find the bundler config relative to appRoot.

If the project appears to be a monorepo (e.g., apps/, packages/ directories, workspace config in package.json) but no domscribe.config.json exists, ask the user which directory contains the frontend app. Then write domscribe.config.json at the project root:

{ "appRoot": "apps/web" }

After Setup

The MCP server starts in dormant mode when no .domscribe/ directory exists. After the user starts their dev server, the bundler plugin creates .domscribe/ automatically. The MCP server will need to restart to detect the new workspace and transition to active mode with the full tool suite.

Editing Components (Code → UI)

Why query runtime state? Source code alone doesn't tell you what props a component actually received, whether a conditional branch rendered, what CSS classes were applied, or what text the user sees. domscribe.query.bySource gives you the live truth from the browser.

When to query (these tasks benefit):

• Visual/styling bugs — "the button is the wrong color." Query reveals the actual className, inline styles, and computed attributes so you can see what CSS is winning.
• Conditional rendering bugs — "this section doesn't show up." Query tells you rendered: false or shows the actual props/state that control the condition.
• Prop tracing — "the title shows 'undefined'." Query shows componentProps with the actual values flowing through, revealing where the chain breaks.
• Verifying your edit worked — After editing, query the same location to confirm the DOM, props, and text updated as expected (HMR will have applied your change).

When NOT to query (save the round-trip):

• Pure logic changes (utils, hooks with no DOM output, API calls)
• Creating new files or components from scratch (nothing to query yet)
• Refactoring (renames, extractions, moves)
• Type errors or build failures (the compiler already tells you what's wrong)

Prerequisite: Runtime queries require the user's dev server to be running and the target component to be rendered in an open browser tab. Before calling domscribe.query.bySource, confirm with the user that they have the relevant page open. If you get browserConnected: false or runtime.rendered: false, ask the user to navigate to the page that renders the component and retry.

Workflow:

1. Confirm the page is open — ask the user if they have the page with the target component open in their browser. If not, ask them to navigate there first.
2. Before editing (if the task matches the scenarios above): Call domscribe.query.bySource with the file path and line number. Inspect runtime.componentProps, runtime.componentState, and runtime.domSnapshot.
3. Edit the component source code.
4. After editing: Call domscribe.query.bySource again to verify your changes took effect in the live browser.

Quick Commands (MCP Prompts)

| Command | Purpose | | ------------------- | ------------------------------ | | process_next | Process next queued annotation | | check_status | System health and queue counts | | explore_component | List elements in a component | | find_annotations | Search annotation history |

All Tools Reference

Tool names below use their MCP registration names (e.g., domscribe.query.bySource). Your client may map these differently — use whatever tool name your environment exposes for the domscribe MCP server.

Source Query (Code → UI)

| Tool | Purpose | | -------------------------- | ---------------------------------------------------------- | | domscribe.query.bySource | Get runtime context for a source location (file + line) | | domscribe.manifest.query | Find all manifest entries by file, component, or tag name | | domscribe.manifest.stats | Manifest coverage statistics (entry/file/component counts) |

Element Resolution (UI → Code)

| Tool | Purpose | | ------------------------- | ---------------------------------- | | domscribe.resolve | Get source location for element ID | | domscribe.resolve.batch | Resolve multiple element IDs |

Annotation Workflow

| Tool | Purpose | | -------------------