feat: add @geometra/cli — view any Geometra site in the terminal

New CLI package provides the `geometra` command:
  geometra https://artemis-two.razroo.com/
  geometra ws://localhost:8080/geometra-ws

Connects to the Geometra WebSocket, receives layout+tree frames,
and renders them using @geometra/renderer-terminal with Unicode
box-drawing characters and ANSI 256-color output.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: CharGrnmn

package-lock.json

@@ -0,0 +1,47 @@
+{
+  "name": "@geometra/cli",
+  "version": "1.13.0",
+  "description": "CLI to view any Geometra-powered site in the terminal",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/razroo/geometra",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://razroo.github.io/geometra",
+  "keywords": [
+    "geometra",
+    "cli",
+    "terminal",
+    "tui"
+  ],
+  "bin": {
+    "geometra": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@geometra/core": "^1.12.0",
+    "@geometra/renderer-terminal": "^1.12.0",
+    "textura": "^1.11.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0"
+  }
+}

packages/cli/package.json

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { viewInTerminal } from './viewer.js'
+
+const url = process.argv[2]
+
+if (!url) {
+  console.error('Usage: geometra <url>')
+  console.error('')
+  console.error('  View any Geometra-powered site in the terminal.')
+  console.error('')
+  console.error('Examples:')
+  console.error('  geometra https://artemis-two.razroo.com/')
+  console.error('  geometra http://localhost:5173/')
+  console.error('  geometra ws://localhost:8080/geometra-ws')
+  process.exit(1)
+}
+
+// Resolve WebSocket URL from input
+let wsUrl: string
+
+if (url.startsWith('ws://') || url.startsWith('wss://')) {
+  // Direct WebSocket URL
+  wsUrl = url
+} else {
+  // HTTP(S) URL — derive WebSocket endpoint
+  const parsed = new URL(url)
+  const wsProto = parsed.protocol === 'https:' ? 'wss:' : 'ws:'
+  // Default Geometra WS path
+  wsUrl = `${wsProto}//${parsed.host}/geometra-ws`
+}
+
+console.error(`Connecting to ${wsUrl}...`)
+
+const viewer = viewInTerminal({ url: wsUrl })
+
+// Clean exit on Ctrl+C
+process.on('SIGINT', () => {
+  viewer.close()
+  process.exit(0)
+})
+
+process.on('SIGTERM', () => {
+  viewer.close()
+  process.exit(0)
+})

packages/cli/src/bin.ts

@@ -0,0 +1 @@
+export { viewInTerminal } from './viewer.js'

packages/cli/src/index.ts

@@ -0,0 +1,89 @@
+import { TerminalRenderer } from '@geometra/renderer-terminal'
+import type { ComputedLayout } from 'textura'
+import type { UIElement } from '@geometra/core'
+import WebSocket from 'ws'
+
+interface ServerFrame {
+  type: 'frame'
+  layout: ComputedLayout
+  tree: UIElement
+}
+
+interface ServerPatch {
+  type: 'patch'
+  patches: Array<{ path: number[]; x?: number; y?: number; width?: number; height?: number }>
+}
+
+type ServerMessage = ServerFrame | ServerPatch | { type: string }
+
+function applyPatches(layout: ComputedLayout, patches: ServerPatch['patches']): void {
+  for (const patch of patches) {
+    let node: ComputedLayout = layout
+    for (const idx of patch.path) {
+      node = node.children[idx]!
+    }
+    if (patch.x !== undefined) node.x = patch.x
+    if (patch.y !== undefined) node.y = patch.y
+    if (patch.width !== undefined) node.width = patch.width
+    if (patch.height !== undefined) node.height = patch.height
+  }
+}
+
+export interface ViewOptions {
+  /** WebSocket URL to connect to. */
+  url: string
+  /** Terminal columns (default: stdout columns). */
+  width?: number
+  /** Terminal rows (default: stdout rows). */
+  height?: number
+}
+
+/**
+ * Connect to a Geometra server WebSocket and render in the terminal.
+ * Returns a cleanup function to close the connection.
+ */
+export function viewInTerminal(options: ViewOptions): { close: () => void } {
+  const renderer = new TerminalRenderer({
+    width: options.width,
+    height: options.height,
+  })
+
+  let layout: ComputedLayout | null = null
+  let tree: UIElement | null = null
+
+  const ws = new WebSocket(options.url)
+
+  ws.on('message', (data) => {
+    try {
+      const msg: ServerMessage = JSON.parse(data.toString())
+
+      if (msg.type === 'frame') {
+        const frame = msg as ServerFrame
+        layout = frame.layout
+        tree = frame.tree
+        renderer.render(layout, tree)
+      } else if (msg.type === 'patch' && layout && tree) {
+        applyPatches(layout, (msg as ServerPatch).patches)
+        renderer.render(layout, tree)
+      }
+    } catch {
+      // ignore parse errors
+    }
+  })
+
+  ws.on('error', (err) => {
+    process.stderr.write(`\x1b[31mConnection error: ${err.message}\x1b[0m\n`)
+  })
+
+  ws.on('close', () => {
+    renderer.destroy()
+    process.stderr.write('Disconnected.\n')
+  })
+
+  return {
+    close() {
+      ws.close()
+      renderer.destroy()
+    },
+  }
+}

packages/cli/src/viewer.ts

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["src/**/__tests__/**"]
+}

packages/cli/tsconfig.build.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/client",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Thin client that receives server-computed geometry and paints via renderer",
   "license": "MIT",
   "type": "module",

packages/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/core",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "DOM-free UI framework core: components, signals, reconciler",
   "license": "MIT",
   "type": "module",

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/renderer-canvas",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Canvas2D renderer for Geometra — the singularity frontend framework",
   "license": "MIT",
   "type": "module",

packages/renderer-canvas/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/renderer-terminal",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Terminal/TUI renderer for Geometra — the singularity frontend framework",
   "license": "MIT",
   "type": "module",