Skip to main content

Wire Protocol

UltimateUI's wire protocol is driven by spec/opcodes.json. Generators use this spec to produce C# writers, TypeScript shim opcode tables, and constants for the native web extension path.

Schema Domain​

Every spec file uses the project domain as its JSON Schema URL:

{
  "$schema": "https://ultimate-ui.hcgstudio.com/spec/opcodes.schema.json"
}

These schema files are served from the Docusaurus static directory. Their source location is docs/static/spec/. After deployment to ultimate-ui.hcgstudio.com, Docusaurus exposes them at:

  • https://ultimate-ui.hcgstudio.com/spec/opcodes.schema.json
  • https://ultimate-ui.hcgstudio.com/spec/elements.schema.json
  • https://ultimate-ui.hcgstudio.com/spec/events.schema.json
  • https://ultimate-ui.hcgstudio.com/spec/styles.schema.json

Current spec files:

  • spec/opcodes.json
  • spec/elements.json
  • spec/events.json
  • spec/styles.json

Frame Lifecycle​

  1. RingEncoder writes the frame header and opcode records.
  2. DomFrameValidator performs local checks before submission.
  3. The WebKitGTK backend passes the frame to the shim.
  4. The shim checks magic, schema version, and payload, then executes DOM work.
  5. The shim returns JsBatchResult, including opsApplied and versionMismatch.

Shim Generation​

TypeScript shim generation entry point:

make shim

This updates:

  • shim/src/opcodes.gen.ts
  • shim/dist/uui-shim.js

If spec/opcodes.json changes, the schema version changes and an old shim refuses mismatched frames.