open-index/open-npm huggingface dataset:
npm package: @geometra/client
Description: Thin client that receives server-computed geometry and paints via renderer
Latest version: 1.42.0

# @geometra/client

Thin WebSocket client (~2KB) for Geometra. Connects to a Geometra server and renders streamed layouts on a canvas.

## Install

```bash
npm install @geometra/client
```

## Key exports

- `createClient` — WebSocket client connected to a Geometra server
- `applyServerMessage` — apply a parsed server message to renderer state (advanced/testing)
- `binaryFraming` option — negotiate optional binary GEOM envelopes (same JSON as text frames)

## Usage

```ts
import { createClient } from '@geometra/client'
import { CanvasRenderer } from '@geometra/renderer-canvas'

const canvas = document.getElementById('app') as HTMLCanvasElement
const client = createClient({
  url: 'ws://localhost:3000',
  renderer: new CanvasRenderer({ canvas }),
  canvas,
  // forwards pointer + keyboard + IME composition events to server
  forwardKeyboard: true,
  forwardComposition: true,
  // optional telemetry hook for decode/apply/render budget tracking
  onFrameMetrics: (m) => {
    console.log('frame metrics', m.messageType, m.decodeMs, m.applyMs, m.renderMs)
  },
  // optional: observe closes; auth failures use WebSocket code 4001 and do not auto-reconnect
  onClose: (ev) => {
    if (ev.code === 4001) console.log('auth rejected')
  },
})
```

Auth with `@geometra/auth` is documented in the main repo: [`PLATFORM_AUTH.md`](https://github.com/razroo/geometra/blob/main/PLATFORM_AUTH.md).

## Links

- [Main repo](https://github.com/AiGeekz/geometra)
npm package: @geometra/proxy
Description: Chromium proxy (headed by default) — stream live DOM geometry as Geometra WebSocket frames for MCP and clients
Latest version: 1.42.0

# @geometra/proxy

Chromium proxy ( **`headed` / visible window by default** ) that extracts **live DOM layout** (`getBoundingClientRect`) plus a **synthetic Geometra UI tree** and streams **GEOM v1** `frame` / `patch` messages over WebSocket (JSON text). Use it with [`@geometra/mcp`](../../mcp/README.md) to drive arbitrary web apps without screenshots.

## Install

```bash
npm install @geometra/proxy playwright
npx playwright install chromium
```

## CLI

```bash
npx geometra-proxy https://example.com --port 3200
npx geometra-proxy http://localhost:8080 --width 1440 --height 900
npx geometra-proxy https://example.com --port 3200 --headless
npx geometra-proxy https://example.com --port 3200 --slow-mo 50
```

**Default is a visible browser** so you can watch MCP-driven clicks and typing. Use **`--headless`** (or env **`GEOMETRA_HEADLESS=1`**) for automation on servers / CI. **`--slow-mo <ms>`** (or **`GEOMETRA_SLOW_MO`**) adds Playwright `slowMo` to make actions easier to follow.

The proxy only opens **`http://`** or **`https://`** pages. For debugging you can still choose a fixed `--port`, but `--port 0` asks the OS for an ephemeral free port (useful for tools that auto-spawn the proxy).

Headed vs headless usually does **not** materially change token usage, because token usage comes from MCP response payloads rather than whether Chromium is visible.

## Protocol

Matches `packages/server` GEOM v1: `frame` with `layout`, `tree`, `protocolVersion`; `patch` with `patches`; client messages `resize`, `event` (`onClick`), `key`, `composition`.

Proxy-specific client messages (native Textura servers respond with `error`):

- **`file`** — `paths`, optional `x`/`y`, `strategy` (`auto`|`chooser`|`hidden`|`drop`), optional `dropX`/`dropY` for drop targets.
- **`selectOption`** — `{ type: 'selectOption', x, y, value? | label? | index? }` — native `<select>` only.
- **`listboxPick`** — `{ type: 'listboxPick', label, exact?, openX?, openY? }` — ARIA `role=option` (custom dropdowns).
- **`wheel`** — `{ type: 'wheel', deltaY?, deltaX?, x?, y? }` — scroll / wheel at optional coordinates.

Extraction merges **all nested iframes** (including cross-origin) into root viewport coordinates, walks **open shadow roots**, and best-effort **enriches names** from Chrome’s accessibility tree (CDP) for closed shadow / opaque widgets.

Binary framing is not used (always JSON text), which is what the MCP server expects.

## Limitations

- No shadow-DOM piercing; iframes are not flattened.
- Large DOMs produce large frames; patch coalescing follows the same rules as `@geometra/server`.
npm package: @geometra/renderer-canvas
Description: Canvas2D renderer for Geometra — the geometry protocol for UI
Latest version: 1.42.0

# @geometra/renderer-canvas

Canvas2D renderer for Geometra. Renders UI element trees to an HTML `<canvas>` element with full hit-testing and text selection support.

## Install

```bash
npm install @geometra/renderer-canvas
```

## Key exports

- `createBrowserCanvasClient` — official browser bootstrap for thin-client canvas apps (`createClient` + `CanvasRenderer` + selection + accessibility mirror + focus wiring)
- `CanvasRenderer` — renders Geometra element trees to a canvas context
- `layoutInspector` — optional HUD (frame counter, **render ms** before HUD, node count, depth, root size, focus + Tab order, optional hit path when `inspectorProbe` is set); off by default
- `lastRenderWallMs` — wall time of the last full `render()` (ms), including overlays; readable for HUDs / metrics
- `lastLayoutWallMs` — last `computeLayout` time (ms) when using `createApp` (via optional `Renderer.setFrameTimings`)
- `inspectorProbe` — set `{ x, y }` in layout coordinates before `render` to show `hitPathAtPoint` in the HUD
- `enableSelection` — text selection on the canvas
- `enableAccessibilityMirror` — hidden accessibility DOM mirror from geometry

## Usage

```ts
import { createBrowserCanvasClient } from '@geometra/renderer-canvas'

const canvas = document.getElementById('app') as HTMLCanvasElement
createBrowserCanvasClient({
  canvas,
  url: 'ws://localhost:3200',
  binaryFraming: true,
  autoFocus: true,
  rendererOptions: {
    background: '#08111f',
  },
})
```

If you need lower-level control, the renderer package still exposes `CanvasRenderer`, `enableSelection`, and `enableAccessibilityMirror` directly.

## Links

- [Main repo](https://github.com/AiGeekz/geometra)
npm package: @geometra/renderer-terminal
Description: Terminal/TUI renderer for Geometra — the geometry protocol for UI
Latest version: 1.42.0

# @geometra/renderer-terminal

ANSI terminal renderer for Geometra. Renders UI element trees directly to the terminal using ANSI escape sequences.

## Install

```bash
npm install @geometra/renderer-terminal
```

## Key Export

- `TerminalRenderer` -- renders Geometra element trees to stdout

## Usage

```ts
import { TerminalRenderer } from '@geometra/renderer-terminal'

const renderer = new TerminalRenderer(process.stdout)
renderer.render(tree, layout)
```

## Direction notes

- `dir: 'rtl'` text is right-aligned within each rendered terminal line chunk.
- `dir: 'auto'` inherits parent direction (same baseline behavior as core).
- Full Unicode bidi shaping/reordering is not implemented in the terminal renderer yet.

## Links

- [Main repo](https://github.com/AiGeekz/geometra)
npm package: @geometra/renderer-webgpu
Description: WebGPU renderer scaffold for Geometra
Latest version: 1.42.0

# @geometra/renderer-webgpu

WebGPU renderer scaffold for Geometra.

This package provides:

- Capability detection via `WebGPURenderer.isSupported()`
- Async `init()` for adapter/device bootstrap (stub in first milestone)
- Stable renderer interface integration (`render()`/`destroy()`)

Current status:

- API scaffold is implemented
- Full paint parity with `@geometra/renderer-canvas` is not implemented yet

## Install

```bash
npm install @geometra/renderer-webgpu
```

## Current support

- WebGPU capability detection and async device/context initialization
- Geometry render integration for solid box backgrounds
- 2D clear-pass fallback before `init()` completes
- Optional `onFallbackNeeded(count)` callback when a tree includes unsupported paint features

Current gaps:

- text paint
- selection highlight
- focus/debug overlays
- gradients, shadows, and border-radius parity
- full canvas feature parity

## Usage

```ts
import { createApp, box, text } from '@geometra/core'
import { WebGPURenderer } from '@geometra/renderer-webgpu'

const renderer = new WebGPURenderer({ canvas })
if (WebGPURenderer.isSupported()) {
  await renderer.init()
}

await createApp(
  () => box({ padding: 16 }, [
    text({ text: 'WebGPU scaffold', font: '16px Inter', lineHeight: 22, color: '#fff' }),
  ]),
  renderer,
  { width: 400, height: 200 },
)
```

## Notes

- Call `await renderer.init()` before relying on GPU rendering. Until then, `render()` uses a predictable clear-pass fallback.
- The current implementation is best treated as an MVP backend for capability probes and early integration work, not a canvas replacement.
- For the current backend matrix, see [RENDERER_SUPPORT_MATRIX.md](https://github.com/razroo/geometra/blob/main/RENDERER_SUPPORT_MATRIX.md).
npm package: @geometra/server
Description: Server-side layout engine with WebSocket geometry streaming
Latest version: 1.42.0

# @geometra/server

Server-side layout engine with WebSocket streaming for Geometra. Computes layouts on the server and streams them to thin clients.

## Install

```bash
npm install @geometra/server
```

## Key exports

- `createServer` — Geometra layout server with WebSocket streaming (standalone `port` **or** attach to an existing HTTP server); returned handle includes **`broadcastData(channel, payload)`** for JSON side-channels on the same socket as layout (`type: 'data'` messages)
- `DEFAULT_GEOMETRA_WS_PATH` — default pathname (`/geometra-ws`) when using `httpServer`
- `shouldDeferClientSend` — backpressure helper (used by the server and tests)
- `onTransportMetrics` (option) — per-broadcast deferred send count, coalesced patch delta, binary outbound count
- Binary frame helpers (`encodeBinaryFrameJson`, …) — optional GEOM v1 JSON envelopes; see repo `PROTOCOL_COMPATIBILITY.md`

## Usage

```ts
import { signal, box, text } from '@geometra/core/node'
import { createServer } from '@geometra/server'

const messages = signal(['Hello from server'])

function view() {
  return box({ flexDirection: 'column', padding: 16, gap: 8 },
    messages.value.map((m) =>
      box({ backgroundColor: '#16213e', padding: 10, borderRadius: 8 }, [
        text({ text: m, font: '14px Inter', lineHeight: 20, color: '#fff' }),
      ]),
    ),
  )
}

const server = await createServer(view, { port: 3100, width: 800, height: 500 })
```

### One port: HTTP + WebSocket (attach mode)

Serve static files, REST, and Geometra on the same TCP port by passing your Node `http.Server`. WebSocket clients should connect to `ws(s)://host${wsPath}` (default path `DEFAULT_GEOMETRA_WS_PATH`).

```ts
import http from 'node:http'
import { signal, box, text } from '@geometra/core/node'
import { createServer, DEFAULT_GEOMETRA_WS_PATH } from '@geometra/server'

const count = signal(0)

function view() {
  return box({ padding: 16 }, [
    text({ text: `Count ${count.value}`, font: '16px Inter', lineHeight: 22, color: '#fff' }),
  ])
}

const httpServer = http.createServer((req, res) => {
  if (req.url === '/') {
    res.writeHead(200, { 'Content-Type': 'text/html' })
    res.end('<!doctype html><canvas id="app"></canvas><script type="module" src="/client.js"></script>')
    return
  }
  res.writeHead(404).end()
})

await new Promise<void>((resolve) => httpServer.listen(8080, resolve))

const geometra = await createServer(view, {
  httpServer,
  wsPath: DEFAULT_GEOMETRA_WS_PATH,
  width: 800,
  height: 600,
})

// Thin client: new WebSocket(`ws://localhost:8080${DEFAULT_GEOMETRA_WS_PATH}`)
```

Do not pass both `httpServer` and `port`.

## Links

- [Main repo](https://github.com/AiGeekz/geometra)
npm package: @geometra/ui
Description: Starter UI primitives built on @geometra/core
Latest version: 1.42.0

# @geometra/ui

High-level primitives on top of [`@geometra/core`](../core) (`box`, `text`, signals). Intended for app UIs and demos.

## Stability

| API | Status |
|-----|--------|
| `button`, `input`, `list`, `dialog` | **stable** — covered by tests; breaking changes only with major bumps |
| `checkbox`, `radio`, `tabs` | **stable** |
| `toast`, `commandPalette`, `menu`, `selectControl`, `dataTable`, `treeView`, `comboboxField` | **stable** — behavior tested in `src/__tests__/primitives.test.ts`; visual polish may evolve in minors |

Semantics follow ARIA-like `role` / `ariaLabel` fields where applicable; full platform a11y depends on renderer + mirror (see `@geometra/renderer-canvas`).

## Install

```bash
npm install @geometra/ui
```

## Key exports

- `button`, `checkbox`, `radio`, `tabs`
- `input`, `selectControl`, `comboboxField`
- `dialog`, `toast`, `menu`, `commandPalette`
- `list`, `dataTable`, `treeView`

## Usage

```ts
import { input, toast, dataTable } from '@geometra/ui'
import { box, signal } from '@geometra/core'

const msg = signal('')
const rows = [
  { name: 'Ada', role: 'Admin' },
  { name: 'Linus', role: 'Editor' },
]

function view() {
  return box({ flexDirection: 'column', gap: 8, padding: 16 }, [
    input(msg.value, 'Type…', {
      focused: true,
      onKeyDown: (e) => {
        if (e.key.length === 1) msg.set(msg.peek() + e.key)
      },
    }),
    toast(`Draft: ${msg.value || 'empty'}`, { variant: 'info' }),
    dataTable([{ key: 'name', header: 'Name' }, { key: 'role', header: 'Role' }], rows),
  ])
}
```

## Notes

- Primitives are renderer-agnostic `UIElement` builders. State, focus, menu open/close, filtering, and async data loading stay in your app.
- `input()` is controlled. You provide the current value, focus state, caret/selection state, and keyboard/composition handlers.
- Semantics use `role` and `ariaLabel` hints when applicable, but full platform accessibility still depends on the renderer and host integration.

## Links

- [Main repo](https://github.com/razroo/geometra)
- [Integration cookbook](https://github.com/razroo/geometra/blob/main/INTEGRATION_COOKBOOK.md)