phase 1.2: JS/TS client library — wire-compatible mirror of Python

js/ workspace shipping @zawwarsami/zhub on npm. browser + Node clients
can publish() and connect() with the same primitives as Python. tsc
checks clean locally; CI gets a parallel js-test job.

components:
- js/package.json: ESM-only, single dependency on `ws` for Node, types
  via tsc emit. exports field with .d.ts.
- js/tsconfig.json: strict, ES2022 target, declaration+types.
- js/src/manifest.ts: Manifest + Capability types, chatOnlyManifest()
  helper, byte-equivalent JSON shape to Python.
- js/src/protocol.ts: Envelope + helpers (registerPublisher,
  registerConnection, chatRequest, chatResponse, chatChunk,
  invokeRequest, invokeResult, errorEnvelope). request_id matches
  Python's uuid4().hex (32 lowercase hex chars).
- js/src/errors.ts: ZhubError hierarchy mirroring Python.
- js/src/client.ts: ZhubPublication + ZhubConnection classes with
  publish() and connect() factories.
    * Auto-reconnect with backoff (mirrors Phase 1.5 Python).
    * Picks global WebSocket in browsers, falls back to `ws` in Node.
    * Streaming chat (sync + async iterators yield chat-chunks).
    * Bidirectional invoke (publisher.invoke(cid, cap, args)).
    * AuthError on register_failed = terminal, no busy-loop.
- js/src/index.ts: re-exports.
- js/test/protocol.test.ts: 9 cases — all envelope shapes round-trip
  + match Python wire format exactly.
- js/test/manifest.test.ts: 3 cases — chatOnlyManifest defaults,
  rate_limit thread-through, public flag.
- js/README.md: install + publish + connect examples + browser caveat.
- .github/workflows/ci.yml: js-test job runs npm install + tsc check
  + vitest. parallel with python matrix + kotlin job.

local testing caveat (proot only): rollup native binding dlopen blocked
in Termux, so vitest can't run locally. tsc-noEmit is clean. CI runs
the full vitest suite on real Linux.

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

Author: Zawwarsami16

.github/workflows/ci.yml

@@ -58,3 +58,29 @@ jobs:
         working-directory: kotlin
         run: |
           gradle test build --no-daemon --stacktrace
+
+  js-test:
+    name: JS/TS module test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: js/package-lock.json
+
+      - name: Install
+        working-directory: js
+        run: npm install --no-audit --no-fund
+
+      - name: Type check
+        working-directory: js
+        run: npx tsc -p tsconfig.json --noEmit
+
+      - name: Test
+        working-directory: js
+        run: npm test

js/README.md

@@ -0,0 +1,63 @@
+# @zawwarsami/zhub — JS/TS client
+
+Browser + Node client for [zhub](https://github.com/Zawwarsami16/zhub). Wire-compatible with the Python core. Same `publish()` and `connect()` primitives.
+
+## Install
+
+```bash
+npm install @zawwarsami/zhub
+```
+
+## Publish (Node)
+
+```typescript
+import { publish } from '@zawwarsami/zhub';
+
+const pub = publish({
+  name: 'my-ai',
+  description: 'A custom AI agent',
+  hubUrl: 'wss://hub.example.com',
+  chatHandler: (messages) => {
+    const last = messages.find((m) => m.role === 'user')?.content ?? '';
+    return `You said: ${last}`;
+  },
+});
+
+while (!pub.apiKey) await new Promise((r) => setTimeout(r, 50));
+console.log('URL:', `https://hub.example.com${pub.baseUrl}`);
+console.log('KEY:', pub.apiKey);
+```
+
+## Connect — chat from a browser/Node client
+
+```typescript
+import { connect } from '@zawwarsami/zhub';
+
+const conn = connect({
+  aiName: 'my-ai',
+  apiKey: 'zk_a8f2c9...',
+  hubUrl: 'wss://hub.example.com',
+  capabilities: {
+    send_whatsapp: [
+      {
+        type: 'object',
+        required: ['to', 'message'],
+        properties: { to: { type: 'string' }, message: { type: 'string' } },
+      },
+      async (args) => ({ delivered: true, to: args.to }),
+    ],
+  },
+});
+
+await new Promise((r) => setTimeout(r, 500));
+const reply = await conn.chat([{ role: 'user', content: 'hi' }]);
+console.log('AI replied:', reply.text);
+```
+
+## Browser usage
+
+The library uses the global `WebSocket` when present (browsers) and falls back to `ws` in Node. Connect-mode is the primary browser use case. Publish-mode also works in browsers.
+
+## API parity with Python
+
+Field names on the wire match Python's `zhub.protocol`. Both sides interoperate against the same hub.