{"_id":"@abeyjs/inspector","_rev":"3-630792ea0617382f111a8b321c623402","name":"@abeyjs/inspector","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@abeyjs/inspector","version":"0.1.0","license":"MIT","_id":"@abeyjs/inspector@0.1.0","maintainers":[{"name":"abeyjs","email":"abeyjs98@gmail.com"}],"bin":{"abeyjs-inspector-hub":"dist/cli.js"},"dist":{"shasum":"eed998479847b5953b8831570ba7a1d78fca4de3","tarball":"https://registry.npmjs.org/@abeyjs/inspector/-/inspector-0.1.0.tgz","fileCount":30,"integrity":"sha512-W7JWzdIgdI7hZyyJacs1hbBaKjmjohRPAV813XYUxQuw9nf6E2/KaazwnksRkkvnNVByllm/phRpwNMz6vDU1Q==","signatures":[{"sig":"MEQCICilxpF1N1EYtdSshAZwVk9T8yu4B4rSbCJep0C5CD8sAiAskDEgg2eHBSAvNKWDDD6hgJb4VpzabAkI0tnhfIoJEw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43074},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./app":{"types":"./dist/app.d.ts","import":"./dist/app.js"},"./hub":{"types":"./dist/hub-entry.d.ts","import":"./dist/hub-entry.js"}},"gitHead":"24fe5ea792f5be4e8facf7c820025f89265c1467","scripts":{"hub":"node ./dist/cli.js","build":"tsc -p tsconfig.json"},"_npmUser":{"name":"abeyjs","email":"abeyjs98@gmail.com"},"_npmVersion":"10.8.2","description":"Dev-time **AbeyJs Inspector**: a tiny **WebSocket hub** plus a **browser bridge** that streams **`OmegaRuntime`** trace events (`RuntimeTraceEvent` from `@abeyjs/runtime`) to any client that speaks the inspector wire protocol. Use it to watch channel traf","directories":{},"sideEffects":false,"_nodeVersion":"20.20.2","dependencies":{"ws":"^8.18.3","@abeyjs/core":"0.1.0","@abeyjs/runtime":"0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/ws":"^8.18.0","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/inspector_0.1.0_1777685229288_0.6940981388018961","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@abeyjs/inspector","version":"0.1.1","license":"MIT","_id":"@abeyjs/inspector@0.1.1","maintainers":[{"name":"abeyjs","email":"abeyjs98@gmail.com"}],"bin":{"abeyjs-inspector-hub":"dist/cli.js"},"dist":{"shasum":"6cf6b952af805a31a3491fabae3a3bb65145d058","tarball":"https://registry.npmjs.org/@abeyjs/inspector/-/inspector-0.1.1.tgz","fileCount":30,"integrity":"sha512-PxaIRReGXHcq0x3JzWkZcGGWibUWQF6oGqR2c3wibxNs8W+/f6r1g0dIbd2KogKbxhtQUM76cJmYNAQQheQPTg==","signatures":[{"sig":"MEUCIQDZHXqbNIbV7bJi+33/vTnKEykliS97iPPLPHLjQ2867AIgBPgTyhCUS2oZBVy295o91wqsyrPPpA7/ken5q0YGL7g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45632},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./app":{"types":"./dist/app.d.ts","import":"./dist/app.js"},"./hub":{"types":"./dist/hub-entry.d.ts","import":"./dist/hub-entry.js"}},"gitHead":"8e89473e70d292931fe54ab9e184c613a03528d3","scripts":{"hub":"node ./dist/cli.js","build":"tsc -p tsconfig.json"},"_npmUser":{"name":"abeyjs","email":"abeyjs98@gmail.com"},"_npmVersion":"10.8.2","description":"Dev-time **AbeyJs Inspector**: a tiny **WebSocket hub** plus a **browser bridge** that streams **`OmegaRuntime`** trace events (`RuntimeTraceEvent` from `@abeyjs/runtime`) to any client that speaks the inspector wire protocol. Use it to watch channel traf","directories":{},"sideEffects":false,"_nodeVersion":"20.20.2","dependencies":{"ws":"^8.18.3","@abeyjs/core":"0.1.0","@abeyjs/runtime":"0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/ws":"^8.18.0","typescript":"^5.7.0"},"_npmOperationalInternal":{"tmp":"tmp/inspector_0.1.1_1777734118053_0.4752875695855632","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@abeyjs/inspector","version":"0.1.2","license":"MIT","publishConfig":{"access":"public"},"type":"module","sideEffects":false,"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./app":{"types":"./dist/app.d.ts","import":"./dist/app.js"},"./hub":{"types":"./dist/hub-entry.d.ts","import":"./dist/hub-entry.js"}},"scripts":{"build":"tsc -p tsconfig.json","hub":"node ./dist/cli.js"},"bin":{"abeyjs-inspector-hub":"dist/cli.js"},"dependencies":{"@abeyjs/core":"0.1.1","@abeyjs/runtime":"0.1.1","ws":"^8.18.3"},"devDependencies":{"@types/ws":"^8.18.0","typescript":"^5.7.0"},"_id":"@abeyjs/inspector@0.1.2","gitHead":"8e89473e70d292931fe54ab9e184c613a03528d3","description":"Dev-time **AbeyJs Inspector**: a tiny **WebSocket hub** plus a **browser bridge** that streams **`OmegaRuntime`** trace events (`RuntimeTraceEvent` from `@abeyjs/runtime`) to any client that speaks the inspector wire protocol. Use it to watch channel traf","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-QNxm662gAwTnq4pAesJhSudfenwPKnQ2p0roOIZz+EGt9JUJpJnd5CtXu6PHNyskCgidLBpevcnipztW4G8GMg==","shasum":"b6b3ff343f5bd3f22314162280326b79a068f1c7","tarball":"https://registry.npmjs.org/@abeyjs/inspector/-/inspector-0.1.2.tgz","fileCount":16,"unpackedSize":28833,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC5vjagoYdBpVymygY7FPtYu5xGsxr6R36+AIxGu8iXUwIhAI2gszVPSfm4xZeaXNcHZAQt7SYm2YtGLdkhzfP2uqez"}]},"_npmUser":{"name":"abeyjs","email":"abeyjs98@gmail.com"},"directories":{},"maintainers":[{"name":"abeyjs","email":"abeyjs98@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/inspector_0.1.2_1777736190193_0.07098090615192865"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-02T01:27:09.176Z","modified":"2026-05-02T15:36:30.406Z","0.1.0":"2026-05-02T01:27:09.448Z","0.1.1":"2026-05-02T15:01:58.205Z","0.1.2":"2026-05-02T15:36:30.325Z"},"license":"MIT","description":"Dev-time **AbeyJs Inspector**: a tiny **WebSocket hub** plus a **browser bridge** that streams **`OmegaRuntime`** trace events (`RuntimeTraceEvent` from `@abeyjs/runtime`) to any client that speaks the inspector wire protocol. Use it to watch channel traf","maintainers":[{"name":"abeyjs","email":"abeyjs98@gmail.com"}],"readme":"# `@abeyjs/inspector`\r\n\r\nDev-time **AbeyJs Inspector**: a tiny **WebSocket hub** plus a **browser bridge** that streams **`OmegaRuntime`** trace events (`RuntimeTraceEvent` from `@abeyjs/runtime`) to any client that speaks the inspector wire protocol. Use it to watch channel traffic (`omega/http:*`, nav, flows, etc.) in near real time alongside the **`correlationId`** that ties requests to downstream events.\r\n\r\nShips three surfaces (see **`package.json` `exports`**):\r\n\r\n| Subpath | Role |\r\n|---------|------|\r\n| **`@abeyjs/inspector`** | Same as `./app`: **`connectOmegaInspectorAppBridge`** + wire types. |\r\n| **`@abeyjs/inspector/app`** | Explicit import path used in templates (**`omegaSetup`** dynamic import). |\r\n| **`@abeyjs/inspector/hub`** | **`startOmegaInspectorHub`** for embedding or tests. |\r\n\r\n**CLI / binary:** `abeyjs-inspector-hub` (runs **`dist/cli.js`** after build).\r\n\r\n---\r\n\r\n## Architecture\r\n\r\n```\r\n  OmegaRuntime.channel  ──onAll──▶  app bridge  ──WebSocket──▶  Inspector Hub  ──fan-out──▶  inspector UI(s)\r\n        │                                                                  │\r\n        └────────── trace ring buffer (≤2000) ◀──────────────── snapshot ────┘\r\n```\r\n\r\n1. **`OmegaRuntime`** mirrors every bus event into an internal **`_trace`** ring (when tracing is enabled), and exposes **`getTraceSnapshot()`**.\r\n2. **`connectOmegaInspectorAppBridge`** attaches **`runtime.channel.onAll`**, reshapes payloads into **`RuntimeTraceEvent`**, and sends **`{ type:\"trace\", ev }`** frames to the hub.\r\n3. The **hub** (**`startOmegaInspectorHub`**) multiplexes peers by **`appId`**. **Apps** push traces; **inspectors** receive live **`trace`** messages and may request **`trace/snapshot`**.\r\n4. A reference UI lives in **`examples/abeyjs-inspector`** (standalone page that connects with **`role: \"inspector\"`**).\r\n\r\n---\r\n\r\n## Run the hub (CLI)\r\n\r\nAfter building this package:\r\n\r\n```bash\r\nnpm run build -w @abeyjs/inspector\r\nnpm -w @abeyjs/inspector run hub\r\n# or globally / from PATH once linked:\r\nabeyjs-inspector-hub --host 127.0.0.1 --port 7071\r\n```\r\n\r\n**Environment variables** (defaults shown):\r\n\r\n| Variable | Default |\r\n|----------|---------|\r\n| `OMEGA_INSPECTOR_HOST` | `127.0.0.1` |\r\n| `OMEGA_INSPECTOR_PORT` | `7071` |\r\n\r\nCLI flags **`--host`** and **`--port`** override env when supplied.\r\n\r\nHTTP **`GET /**` responds with plain text **`AbeyJs Inspector Hub`** — the WebSocket attaches on the **HTTP upgrade** to the same server (path-agnostic **`ws://host:port/`** endpoint).\r\n\r\n---\r\n\r\n## Wire protocol (`protocol.ts`)\r\n\r\nMessages are UTF-8 **JSON**. The **first** message every socket sends must be **`hello`**.\r\n\r\n### Handshake\r\n\r\n**App or inspector → hub**\r\n\r\n```json\r\n{ \"type\": \"hello\", \"role\": \"app\" | \"inspector\", \"appId\": \"<string>\", \"token\": \"<optional>\" }\r\n```\r\n\r\n**Hub → peer**\r\n\r\n```json\r\n{ \"type\": \"hello/ack\", \"ok\": true, \"appId\": \"...\", \"role\": \"...\", \"hubTime\": 1735689600123 }\r\n```\r\n\r\nOr on bad first frame:\r\n\r\n```json\r\n{ \"type\": \"error\", \"message\": \"Expected hello\" }\r\n```\r\n\r\n(`token` is reserved; the hub **does not** validate secrets yet.)\r\n\r\n### Traces\r\n\r\n**App → hub** (after hello):\r\n\r\n```json\r\n{ \"type\": \"trace\", \"ev\": { \"name\": \"omega/http:request\", \"data\": { }, \"correlationId\": \"…\", \"timestamp\": 1735689600123, \"source\": \"omega-http\" } }\r\n```\r\n\r\nHub **drops** malformed trace frames (missing **`ev.name`**). It **buffers** traces per **`appId`** (**`maxTrace`**, clamped **`50 … 20000`**, default **2000**) and **fans out** to every connected **`inspector`** for that **`appId`**.\r\n\r\nWhen an inspector finishes hello and the hub already has buffered traces, it immediately sends **`trace/snapshot`** with up to **200** recent items.\r\n\r\n### Snapshots\r\n\r\n**Inspector → hub**\r\n\r\n```json\r\n{ \"type\": \"trace/snapshot\", \"limit\": 600 }\r\n```\r\n\r\n**Hub → inspector**\r\n\r\n```json\r\n{ \"type\": \"trace/snapshot\", \"items\": [ /* RuntimeTraceEvent */ ] }\r\n```\r\n\r\n**`limit`** is clamped to **`10 … 2000`** (defaults to **200** if missing/invalid).\r\n\r\n---\r\n\r\n## Browser bridge (`connectOmegaInspectorAppBridge`)\r\n\r\n**Imports:** `@abeyjs/inspector` **or** `@abeyjs/inspector/app`.\r\n\r\n```ts\r\nimport { createOmegaRuntime } from \"@abeyjs/runtime\";\r\nimport { connectOmegaInspectorAppBridge } from \"@abeyjs/inspector\";\r\n\r\nconst runtime = createOmegaRuntime();\r\n\r\nconst bridge = connectOmegaInspectorAppBridge(runtime, {\r\n  url: \"ws://127.0.0.1:7071\",\r\n  appId: \"my-app-dev\",\r\n});\r\n\r\n// teardown\r\nbridge.close();\r\n```\r\n\r\n**Behaviour:**\r\n\r\n- Subscribes with **`runtime.channel.onAll`** and forwards each **`OmegaEvent`** as **`RuntimeTraceEvent`** (`name`, `data`/`payload`, `correlationId`, `timestamp`, `source`).\r\n- Buffers up to **500** events **before** **`hello/ack`** (when the socket is not ready yet); trims oldest.\r\n- Optional **`sendSnapshotOnConnect`** (default **`true`**): pushes **`runtime.getTraceSnapshot().slice(-200)`** after open so the hub receives recent history.\r\n- **Reconnect** (default **`true`**) uses exponential backoff (**`reconnectBaseDelayMs`** × **1.6^attempt**, capped **`reconnectMaxDelayMs`**).\r\n- **`close()`** unsubscribes and closes the **`WebSocket`**.\r\n\r\n**Runtime note:** reconnect scheduling uses **`window.setTimeout`** — load this path only in a **browser** (or stub **`window`**).\r\n\r\n**Returned `ws`:** the initial handle may **`undefined`** until the async connection opens; **`close()`** remains the stable teardown API.\r\n\r\nTemplates wire this in **`omegaSetup`** only on **localhost**, **dev build**, unless **`?omegaInspector=off`** (see generated **`packages/cli/templates/**/omegaSetup.ts`**).\r\n\r\n---\r\n\r\n## Programmatic hub (`startOmegaInspectorHub`)\r\n\r\nFor tests or composing your own tooling:\r\n\r\n```ts\r\nimport { startOmegaInspectorHub } from \"@abeyjs/inspector/hub\";\r\n\r\nconst hub = await startOmegaInspectorHub({ host: \"127.0.0.1\", port: 7071, maxTrace: 2000 });\r\nconsole.log(hub.url); // ws://127.0.0.1:7071\r\n\r\nawait hub.close();\r\n```\r\n\r\nSame WebSocket semantics as the CLI binary.\r\n\r\n---\r\n\r\n## Dependencies\r\n\r\n| Package | Use |\r\n|---------|-----|\r\n| `@abeyjs/runtime` | **`OmegaRuntime`**, **`RuntimeTraceEvent`** shape consumed by hubs/UI. |\r\n| `@abeyjs/core` | **`Unsubscribe`** / channel listener typing in the bridge. |\r\n| `ws` | WebSocket server on Node (hub). |\r\n\r\n---\r\n\r\n## Build\r\n\r\n```bash\r\nnpm run build -w @abeyjs/inspector\r\n```\r\n\r\n---\r\n\r\n## Troubleshooting\r\n\r\n| Symptom | Check |\r\n|---------|--------|\r\n| Hub rejects connection immediately | First frame must be valid **`hello`** JSON with **`type`**, **`role`**, **`appId`**. |\r\n| Inspector shows no traffic | Matching **`appId`** on bridge **and** inspector; confirm an **app** socket is connected, not inspector-only. |\r\n| Floods disconnect | Inspect **`maxTrace`** / inspector UI retention; hub logs first few events plus every 50th. |\r\n| Bridge never attaches | SSR / non-browser: **`window`** missing; **`import(\"@abeyjs/inspector/app\")` only in guarded client branch** (`typeof window`). |\r\n","readmeFilename":"README.md"}