SCHEMETA

AI-Native schematic compiler and visual teaching workspace.

This version includes:

• Deterministic JSON validation, ERC, topology extraction
• Auto-generic symbol synthesis for unknown components/pins (deterministic fallback)
• Auto-template synthesis for common passives/connectors (R/C/L/D/LED/J/P)
• Constraint-aware placement, orthogonal routing, net-stub schematic mode
• SVG rendering with bus grouping, tie symbols, junctions, and legend
• Workspace UI for navigation, drag/lock placement, isolate/highlight, diagnostics focus, and direct graph editing
• JSON power tools: validate, format, sort keys, copy minimal repro
• REST + MCP integration (compile/analyze + UI bundle metadata)

Run

npm run start

Open:

• Workspace: http://localhost:8787/
• Health: http://localhost:8787/health
• MCP UI bundle descriptor: http://localhost:8787/mcp/ui-bundle

Version metadata:

• REST and MCP tool responses include api_version and schema_version.
• REST responses also include request_id and x-request-id for request correlation.
• Current values: api_version=0.3.0, schema_version=1.0.0.
• Compatibility policy (current): additive, backward-compatible fields may be introduced in the same API minor version.

Operational limits:

• MAX_BODY_BYTES (default 2097152) limits request payload size.
• MAX_REQUESTS_PER_MINUTE (default 120) applies per-client throttling for POST API endpoints.
• SCHEMETA_AUTH_TOKEN (optional) enforces bearer/API-key auth for POST API endpoints.
  • send either Authorization: Bearer <token> or x-api-key: <token>

Docs:

• docs/release-checklist.md
• docs/operations-runbook.md
• docs/quality-gates.md
• docs/phase4-execution-plan.md
• docs/phase5-execution-plan.md
• docs/fixtures.md
• docs/api-mcp-contracts.md

CI:

• .gitea/workflows/ci.yml runs syntax checks + full test suite on push/PR.
• CI also runs browser regression (npm run test:ui) after installing Playwright Chromium.

REST API

POST /compile

Input:

{
  "payload": { "...": "SJM" },
  "options": {
    "render_mode": "schematic_stub",
    "show_labels": true,
    "generic_symbols": true
  }
}

payload can also be posted directly (backward compatible).

Output includes:

• errors, warnings with id + suggestion
• focus_map for issue-to-canvas targeting
• layout (resolved placements)
• layout_metrics (crossings, overlaps, label collisions, tie points, bus groups)
• bus_groups
• render_mode_used
• svg

POST /analyze

Input: same payload model format Output: ERC + topology summary (power domains, clock source/sink, buses, paths)

generic_symbols defaults to true. When enabled, missing symbols or missing pins on generic symbols are synthesized from net usage and surfaced as warnings:

• auto_template_symbol_created (for recognized common parts like resistor/capacitor/etc.)
• auto_template_symbol_hydrated (template shorthand expanded to full runtime symbol)
• auto_generic_symbol_created
• auto_generic_symbol_hydrated (generic shorthand expanded to full runtime symbol)
• auto_generic_pin_created

Shorthand symbols are supported for concise AI output:

{
  "symbols": {
    "r_std": { "template_name": "resistor" },
    "x_generic": { "category": "generic" }
  }
}

symbol_id, category, body, and pins are auto-filled as needed during compile/analyze.

Instance-level built-in parts are also supported (no symbol definition required):

{
  "instances": [
    {
      "ref": "R1",
      "part": "resistor",
      "properties": { "value": "10k" },
      "placement": { "x": null, "y": null, "rotation": 0, "locked": false }
    }
  ]
}

Supported part values: resistor, capacitor, inductor, diode, led, connector, generic.

Per-pin editor hints are supported through instance properties:

{
  "instances": [
    {
      "ref": "R1",
      "part": "resistor",
      "properties": {
        "value": "10k",
        "pin_ui": {
          "1": { "show_net_label": true },
          "2": { "show_net_label": false }
        }
      },
      "placement": { "x": null, "y": null, "rotation": 0, "locked": false }
    }
  ]
}

POST /layout/auto

Computes fresh placement (ignores current locks), returns:

• updated model
• compiled result in compile

POST /layout/tidy

Computes placement tidy while respecting locks, returns:

• updated model
• compiled result in compile

MCP

Start stdio MCP server:

npm run mcp

Tools:

• schemeta_compile
• schemeta_analyze
• schemeta_ui_bundle

Workspace behavior highlights

• Fit-to-view default on load/import/apply
• Focus-selection + reset-view controls for faster navigation in dense schematics
• Reset Sample one-click deterministic baseline restore for QA/demo loops
• Space + drag pan, wheel zoom, fit button
• Net/component/pin selection with dimming + isolate toggles
• Selected panel editors for component properties, full pin properties, full symbol body/pin editing, and net connect/disconnect operations
• Click diagnostics to jump/flash focused net/component/pin
• Auto Layout and Auto Tidy actions
• Shortcuts helper modal and Ctrl/Cmd+K command palette quick actions
• Keyboard shortcuts:
  • Ctrl/Cmd+Z undo
  • Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y redo
  • Ctrl/Cmd+K open command palette
  • Space rotate selected components (or pan when no selection)
  • F focus current selection
  • Alt+Enter apply current selection editor (component/pin/net)
  • Alt+C connect selected pin to chosen net

Browser Regression

Run browser interaction + visual regression checks:

npx playwright install chromium
npm run test:ui

Metrics report artifact:

• output/playwright/ui-metrics-report.json

Refresh visual baselines intentionally:

UPDATE_SNAPSHOTS=1 npm run test:ui

Baselines are stored in tests/baselines/ui/.