schemeta/README.md

# 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

```bash
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`.
- 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`

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:
```json
{
  "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:

```json
{
  "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):

```json
{
  "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:

```json
{
  "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:

```bash
npm run mcp
```

Tools:
- `schemeta_compile`
- `schemeta_analyze`
- `schemeta_ui_bundle`

## Workspace behavior highlights

- Fit-to-view default on load/import/apply
- `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
- Keyboard shortcuts:
  - `Ctrl/Cmd+Z` undo
  - `Ctrl/Cmd+Shift+Z` or `Ctrl/Cmd+Y` redo
  - `Space` rotate selected components (or pan when no 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:

```bash
npx playwright install chromium
npm run test:ui
```

Refresh visual baselines intentionally:

```bash
UPDATE_SNAPSHOTS=1 npm run test:ui
```

Baselines are stored in `tests/baselines/ui/`.