Schema Contract

A capture model that separates dev review from inspect export.

Quey now supports two related but distinct output modes. Dev mode is for reviewing a live element with source and design context. Inspect mode adds a portable HTML export layer for agent editing workflows.

View repository Installation

Core Design

The panel should answer identity, location, design, and action in one pass.

Schema zone

Dev Mode

Dev mode captures the live element plus source-aware context when available. It is optimized for panel review and rich clipboard summaries.

Schema zone

Inspect Mode

Inspect mode still captures the same structural payload, but it also attaches inspectExport HTML so agents can paste or transform the selected subtree directly.

Schema zone

Location

The UI favors semanticPath for readable breadcrumbs, while selectorPath and xpath stay in the payload for exact targeting.

Schema zone

Clipboard

Dev mode copies a readable inspection summary plus JSON. Inspect mode adds text/html and uses inspectExport output for the plain-text clipboard value.

Schema zone

Region Capture

Region capture copies the screenshot image plus a primary element, related elements, page context, semantics, and stack hints so agents receive more than pixels.

Schema zone

Style Workspace

Style mode replaces the generic dock actions with focused Frame, Font, and Color tools so the panel body matches the style category being edited.

Example Output

Human-readable panel data and mode-specific clipboard exports should stay aligned.

The website page mirrors the repo contract in schema/README.md, but keeps it in a product-facing format so we can evolve the UI and the data model together.

Dev payload · application/x-uitoolbar+json

{
  "mode": "dev",
  "url": "http://localhost:3000",
  "element": {
    "tagName": "button",
    "role": "button",
    "accessibleName": "Sign Up",
    "text": "Sign Up",
    "bounds": { "top": 24, "left": 120, "width": 140, "height": 40 }
  },
  "identity": {
    "primaryName": "Interactive",
    "rawName": "IdleExpandedInteractive",
    "stateTags": ["idle", "expanded"],
    "fileName": "Message.tsx",
    "filePath": "src/components/Message.tsx",
    "line": 42
  },
  "location": {
    "selectorPath": "button.rounded-lg:nth-of-type(1)",
    "semanticPath": ["Page", "Main", "Section 2", "Card"],
    "classList": ["rounded-lg", "gap-2", "bg-zinc-900"]
  },
  "design": {
    "background": { "token": "--zinc-900", "resolved": "#18181b" },
    "foreground": { "token": "--text-primary", "resolved": "#ffffff" },
    "fontSizePx": 14,
    "fontWeight": 500,
    "borderRadiusPx": 12,
    "display": "flex",
    "layoutTokens": ["flex", "gap-2", "rounded-lg"]
  },
  "devContext": {
    "framework": "react",
    "sourceAvailable": true
  },
  "inspectExport": null,
  "metadata": {
    "xpath": "/html/body/main/section/button[1]"
  }
}

Inspect Export

Inspect mode adds export-ready HTML without dropping the base capture contract.

The core payload stays stable across both modes. Inspect mode simply fills the inspectExport block and changes what is copied into plain text and HTML clipboard channels.

Inspect-only addition

{
  "mode": "inspect",
  "inspectExport": {
    "cleanHtml": "<button class=\"launch-btn\">Launch</button>",
    "tailwindHtml": "<button class=\"inline-flex rounded-lg px-4 py-2\">Launch</button>",
    "warnings": []
  }
}

Region Capture

Screenshot capture now carries semantic region metadata instead of shipping pixels alone.

A dragged screenshot region can resolve to a primary element plus nearby related elements. That means agents can receive the image, semantic path, stack hints, and element summaries in the same handoff.

Region metadata payload

{
  "rect": { "top": 24, "left": 32, "width": 920, "height": 56 },
  "page": {
    "title": "PocketUI",
    "host": "pocketui.app"
  },
  "primaryElement": {
    "location": {
      "semanticPath": ["Page", "Header", "Nav", "Div"]
    },
    "element": {
      "tagName": "div",
      "text": "PocketUI Features Pricing Free Tools Join waitlist"
    }
  },
  "relatedElements": [
    {
      "location": {
        "semanticPath": ["Page", "Header", "Nav", "a"]
      },
      "element": {
        "tagName": "a",
        "text": "Join waitlist"
      }
    }
  ]
}

Style Workspace

Style editing is now split into focused Frame, Font, and Color tools.

The Style tab no longer reuses the generic dock. It swaps in style-specific actions so layout controls live under Frame, text controls live under Font, and color editing gets its own Color panel with a dedicated picker flow.

Style sections

Frame → padding, gap, border-radius
Font → font-size, font-weight
Color → color, background-color, border-color