Packages

Domscribe is organized as a monorepo with 12 published packages. Each package has a well-defined scope and strict dependency boundaries enforced at lint time.

Overview

Architecture Tiers

Packages are organized into four dependency tiers. Each tier can only depend on tiers above it.

Tier 1: Core
  @domscribe/core

Tier 2: Infrastructure
  @domscribe/manifest
  @domscribe/relay
  @domscribe/runtime

Tier 3: Build
  @domscribe/transform

Tier 4: Adapters
  @domscribe/react
  @domscribe/vue
  @domscribe/next
  @domscribe/nuxt
  @domscribe/overlay
  domscribe (CLI)
  @domscribe/mcp

Dependency Graph

@domscribe/core ─────────────────────────────────────────── Foundation
    |
    +-- @domscribe/manifest ─────────────────────────────── Index Management
    |       |
    |       +-- @domscribe/transform ────────────────────── AST Injection
    |       |       |
    |       |       +-- @domscribe/next ─────────────────── Next.js Integration
    |       |       +-- @domscribe/nuxt ─────────────────── Nuxt 3 Module
    |       |
    |       +-- @domscribe/relay ────────────────────────── Dev Server + MCP
    |
    +-- @domscribe/runtime ──────────────────────────────── Browser Context Capture
    |       |
    |       +-- @domscribe/react ────────────────────────── React Adapter
    |       +-- @domscribe/vue ──────────────────────────── Vue 3 Adapter
    |       +-- @domscribe/overlay ──────────────────────── Lit UI Components
    |
    +-- (shared types, schemas, constants, errors)

Package Details

@domscribe/core

The foundation package. All other packages depend on it.

Dependencies: nanoid, zod

Key exports:

• Zod schemas -- Annotation, ManifestEntry, RuntimeContext, AnnotationContext, AnnotationInteraction, SourcePosition, StyleInfo, ComponentMetadata
• Types -- AnnotationStatus (QUEUED, PROCESSING, PROCESSED, FAILED, ARCHIVED), InteractionMode (ELEMENT_CLICK, TEXT_SELECTION)
• Error system -- DomscribeError class implementing RFC 7807 Problem Details. Error codes include DS_VALIDATION_FAILED, DS_MANIFEST_INVALID, DS_MANIFEST_NOTFOUND, DS_ELEMENT_NOT_FOUND, DS_ANNOTATION_*, DS_TRANSFORM_FAILED, DS_RELAY_*, DS_MCP_*
• Utilities -- generateEntryId() (8-char nanoid with custom alphabet), generateAnnotationId() (ann_<nanoid>_<timestamp>), isValidElementId(), migrateAnnotation() (schema migration via "migrate on read" pattern)
• Constants -- API_PATHS, WS_EVENTS, PATTERNS, DEFAULT_CONFIG, PATHS, HTTP_STATUS

@domscribe/manifest

Manages the append-only JSONL manifest that maps DOM elements to source code locations.

Dependencies: @domscribe/core, xxhash-wasm, zod

Components:

• ManifestWriter (singleton per workspace) -- appendEntries(), resolveId(), getEntriesByFile(). Triggers compaction on close if entry count exceeds threshold (default: 500).
• ManifestReader (for relay) -- O(1) entry lookup via three indices: idToEntry, fileToIds, componentToIds. Watches for file changes and emits MANIFEST_UPDATED events.
• IDStabilizer -- Generates HMR-stable IDs via xxhash64(fileContent) plus a position cache. Achieves greater than 80% cache hit rate during HMR cycles. Atomic cache persistence (temp file + rename).
• BatchWriter -- Buffers 50 entries with 100ms flush interval. Automatic flush on process exit.
• ManifestCompactor -- Removes entries for deleted files and keeps only the latest fileHash per file. Atomic rewrite via temp file + rename.

Storage format:

{"id":"A1B2C3D4","file":"src/App.tsx","start":{"line":5,"column":4},"end":{"line":5,"column":30},"tagName":"div","fileHash":"a1b2c3d4e5f6"}

@domscribe/relay

Local development server bridging the browser overlay and coding agents.

Dependencies: @domscribe/core, @domscribe/manifest, fastify, @fastify/cors, @fastify/websocket, @modelcontextprotocol/sdk, commander, zod

Provides:

• REST API for annotation CRUD, manifest queries, and health checks
• WebSocket server for real-time event broadcasting
• MCP stdio adapter exposing 12 tools and 4 prompts
• Daemon lifecycle with file-lock singleton pattern (.domscribe/relay.lock)
• Client libraries: RelayHttpClient (REST) and RelayWebsocketClient (WebSocket events)

@domscribe/transform

AST-level injection of stable data-ds attributes into JSX and Vue templates, plus bundler plugins.

Dependencies: @domscribe/core, @domscribe/manifest, @domscribe/relay, acorn, acorn-jsx, acorn-walk, @babel/parser, @babel/types, magic-string, source-map

Parsers:

Bundler plugins:

@domscribe/runtime

Browser-side context capture system.

Dependencies: @domscribe/core

Key components:

• RuntimeManager (singleton) -- Initializes with a FrameworkAdapter, skips initialization if window.__DOMSCRIBE_RELAY_PORT__ is not set (production guard). Calls captureForElement(element) to produce RuntimeContext.
• FrameworkAdapter interface -- getComponentInstance(), captureProps(), captureState(), getComponentName(), getComponentTree()
• Serialization -- Handles circular references, depth limiting (10 levels), and special types (Functions, Symbols, Maps, Sets, Dates, RegExps, Errors, BigInts)
• Bridge system -- Pluggable transport layer: DirectTransport (synchronous, same-frame) and EventTransport (async, cross-frame)

@domscribe/overlay

In-browser UI built with Lit web components using shadow DOM isolation.

Dependencies: @domscribe/core, @domscribe/runtime, @domscribe/relay, lit

Web components: ds-overlay, ds-tab, ds-sidebar, ds-header, ds-annotation-list, ds-annotation-item, ds-annotation-input, ds-context-panel, ds-element-preview, ds-highlight-box, ds-picker-overlay, ds-tooltip

OverlayStore manages reactive state including mode (collapsed, expanded, picker), relay connection status, selected element, runtime context, manifest entry, and annotations.

@domscribe/react

React framework adapter for runtime context capture.

Dependencies: @domscribe/core, @domscribe/runtime Peer dependencies: react >=16.8.0

Capabilities:

• Three capture strategies: DEVTOOLS, FIBER, BEST_EFFORT
• Fiber traversal via FiberWalker (walkUp(), walkDown(), walkSiblings())
• Component categorization: Functional, Class, ForwardRef, Memo, HOC
• HOC detection for withRouter, connect, styled, memo, forwardRef
• Hook state extraction by traversing the memoizedState linked list

Subpath exports: @domscribe/react/vite, @domscribe/react/webpack, @domscribe/react/auto-init

@domscribe/vue

Vue 3 framework adapter for runtime context capture.

Dependencies: @domscribe/core, @domscribe/runtime Peer dependencies: vue >=3.3.0

Capabilities:

• DOM to VNode to component resolution via __vueParentComponent
• Reactive proxy unwrapping (toRaw/toValue)
• Composition API and Options API support
• Component tree traversal via VNode hierarchy

Subpath exports: @domscribe/vue/vite, @domscribe/vue/webpack, @domscribe/vue/auto-init

@domscribe/next

Next.js integration via config wrapping.

Dependencies: @domscribe/transform, @domscribe/runtime, @domscribe/react Peer dependencies: next >=15.0.0, react ^18.0.0 || ^19.0.0

Provides withDomscribe(options)(nextConfig) which applies the transform plugin in dev mode, injects relay globals and overlay scripts, aliases the overlay to a no-op stub in production, and supports both Webpack (Next.js 15) and Turbopack (Next.js 16+).

Subpath exports: @domscribe/next/runtime (DomscribeDevProvider component), @domscribe/next/noop/overlay (production no-op stub)

@domscribe/nuxt

Nuxt 3+ module for zero-config integration.

Dependencies: @domscribe/relay, @domscribe/transform, @domscribe/runtime, @domscribe/vue Peer dependencies: nuxt >=3.0.0

Auto-starts the relay daemon in dev mode, injects relay globals via app.head, applies Vite and Webpack plugins, and registers a client-only runtime plugin for RuntimeManager and VueAdapter initialization.

domscribe (CLI)

The command-line binary providing domscribe serve, domscribe status, domscribe stop, domscribe init, and domscribe mcp. See the CLI Reference for full documentation.

@domscribe/mcp

Standalone MCP server binary (domscribe-mcp). Runs over stdio and connects to the relay daemon to expose all 12 Domscribe tools and 4 prompts. See the MCP Tools Reference for full tool documentation.