ttyglass 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-13
+
+### Added
+
+- Run an arbitrary TUI command through a real PTY or Windows ConPTY session and interact with it from a local browser.
+- Preview terminal output with built-in color schemes and dynamic or exact fixed terminal dimensions.
+- Collect bounded, structured application diagnostics separately from terminal output using a dependency-free HTTP contract.
+- Send diagnostics from TypeScript directly or through a JSON-line sink compatible with loggers such as Pino.
+- Guide Codex and Claude Code through safe visual TUI inspection with packaged agent skills.
+
+### Security
+
+- Restrict the observer and diagnostics service to loopback, authenticate each session with a fresh token, validate browser origins, and terminate the owned terminal process tree when the session ends.
+
+[Unreleased]: https://github.com/MrMaxie/ttyglass/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/MrMaxie/ttyglass/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,158 @@
+# ttyglass
+
+<p align="center">
+  <img src="assets/ttyglass-logo.svg" alt="ttyglass" width="240">
+</p>
+
+<p align="center">
+  Run a real terminal UI in a local browser for visual testing, interaction debugging, and agent-assisted review.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ttyglass"><img src="https://img.shields.io/npm/v/ttyglass" alt="npm version"></a>
+  <a href="https://github.com/MrMaxie/ttyglass/actions/workflows/publish.yml"><img src="https://github.com/MrMaxie/ttyglass/actions/workflows/publish.yml/badge.svg" alt="CI"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache 2.0 license"></a>
+</p>
+
+ttyglass is a native Nim executable that wraps any TUI command in a real PTY or Windows ConPTY session and mirrors it into an authenticated browser page on `127.0.0.1`. The observed project does not need ttyglass configuration, a ttyglass dependency, or source changes.
+
+## Quick start
+
+Run a TUI without installing ttyglass:
+
+```sh
+npx ttyglass --open -- lazygit
+```
+
+Or run a project command from another directory:
+
+```sh
+npx ttyglass --open --cwd ../my-app -- npm run tui
+```
+
+Everything before `--` configures ttyglass. Everything after `--` is the command and its arguments.
+
+## Why ttyglass
+
+- Observe the real TUI instead of a reconstructed screenshot or text dump.
+- Send keyboard input and resize the underlying PTY from the browser.
+- Preview ANSI output with Catppuccin Mocha, Gruvbox Dark, Nord, Dracula, or Tokyo Night.
+- Switch between a terminal that follows the browser and an exact fixed row and column size.
+- Keep application diagnostics outside the terminal without changing the TUI layout.
+- Give Codex or Claude Code a browser surface it can inspect and interact with safely.
+- Run against an arbitrary project without adding ttyglass to that project.
+
+The server binds only to loopback and uses a fresh token for the browser and diagnostics connections. The terminal process is scoped to that ttyglass session.
+
+## Installation
+
+The quickest option is `npx`:
+
+```sh
+npx ttyglass -- <command> [arguments...]
+```
+
+Install the command globally if you use it often:
+
+```sh
+npm install --global ttyglass
+ttyglass -- <command> [arguments...]
+```
+
+Nub users can run the same package without installing it:
+
+```sh
+nubx -y ttyglass -- <command> [arguments...]
+```
+
+ttyglass currently requires Node.js 24.18.0.
+
+Prebuilt executables are provided for Windows x64, Linux x64 with glibc, macOS x64, and macOS arm64. npm selects the matching optional package; installing ttyglass does not compile Nim or native code.
+
+## Usage
+
+```text
+ttyglass [options] -- <command> [arguments...]
+```
+
+Examples:
+
+```sh
+npx ttyglass -- lazygit
+npx ttyglass --open -- btop
+npx ttyglass --cwd ../app -- npm run tui
+npx ttyglass --port 4173 -- cargo run
+```
+
+ttyglass prints an authenticated URL such as `http://127.0.0.1:4173/#token=...`. Open that exact URL unless `--open` already opened it.
+
+| Option | Description |
+| --- | --- |
+| `--cwd <path>` | Run the observed command from this directory. |
+| `--port <number>` | Use a fixed loopback port instead of an available port. |
+| `--diagnostics-limit <count>` | Keep between 1 and 5000 application diagnostic entries. The default is 500. |
+| `--open` | Open the authenticated browser URL after startup. |
+| `--no-open` | Print the URL without opening a browser. This is the default. |
+| `-h`, `--help` | Show command help. |
+| `--version` | Show the installed package version. |
+
+## Terminal display
+
+Open Display to change how the observed terminal is rendered. Color schemes remap ANSI, indexed, and application-supplied RGB colors inside the TUI without changing the ttyglass interface.
+
+Dynamic sizing follows the available browser space. Fixed sizing keeps the exact columns and rows you enter and makes the browser terminal viewport scrollable when necessary. Opening Diagnostics never covers terminal content.
+
+## Application diagnostics
+
+Every observed command receives `TTYGLASS_DIAGNOSTICS_URL` and `TTYGLASS_DIAGNOSTICS_TOKEN`. The application can send JSON or newline-delimited JSON to that loopback endpoint using only its language standard library.
+
+Diagnostics are optional, bounded in memory, and visible only for the current session. ttyglass does not put its own lifecycle or resize events in the Diagnostics panel.
+
+See [Diagnostics without a ttyglass library](docs/diagnostics.md) for the record format and dependency-free Node.js and Python examples.
+
+## TypeScript API
+
+TypeScript applications can import a direct diagnostic sender or a JSON-line sink compatible with loggers such as Pino:
+
+```ts
+import { createTtyglassSink, sendTtyglassDiagnostic } from 'ttyglass';
+
+await sendTtyglassDiagnostic({
+  source: 'checkout',
+  level: 'info',
+  event: 'screen.loaded',
+  fields: { items: 3 },
+});
+
+const sink = createTtyglassSink({ source: 'checkout' });
+```
+
+Both APIs are no-ops by default outside a ttyglass session. See [Optional TypeScript diagnostics](docs/typescript.md) for integration details.
+
+## Agent use
+
+The npm package includes dedicated [Codex and Claude Code skills](skills/README.md). They explain how an agent should start ttyglass, inspect the rendered TUI, collect diagnostics, state what it actually verified, and clean up the session.
+
+## Development
+
+The runtime core is Nim 2.2.12. It owns the CLI, local server, WebSocket transport, diagnostics ingestion, PTY or ConPTY bridge, process cleanup, and embedded browser assets. TypeScript is limited to the npm launcher, optional diagnostics helpers, tests, and repository scripts. Svelte is limited to the browser UI.
+
+```sh
+nimble install --depsOnly --accept
+nub install
+just fmt
+just check
+just build
+just test
+just package-check
+```
+
+`just package-check` builds the publishable tarball, validates its contents, runs the packaged CLI through `npx`, exercises a real terminal and diagnostics session, and imports the public TypeScript API from a clean consumer project.
+
+Native dependencies are pinned in `ttyglass.nimble` and `nimble.lock`. npm and frontend dependencies are pinned in their manifests and `nub.lock`.
+
+Releases follow [Semantic Versioning](https://semver.org/). See [CHANGELOG.md](CHANGELOG.md) for notable changes.
+
+## License
+
+ttyglass is licensed under the [Apache License 2.0](LICENSE).

package/assets/ttyglass-logo.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="92 92 328 334" role="img" aria-label="TTYGlass logo">
+  <path fill="#6EADBC" fill-rule="evenodd" d="
+    M156 92
+    C118 92 92 118 92 156
+    V318
+    C92 343 104 362 125 373
+    L154 327
+    H150
+    C142 327 136 321 136 313
+    V169
+    C136 157 145 148 157 148
+    H355
+    C367 148 376 157 376 169
+    V313
+    C376 321 370 327 362 327
+    H358
+    L387 373
+    C408 362 420 343 420 318
+    V156
+    C420 118 394 92 356 92
+    Z
+
+    M220 278
+    H292
+    L311 306
+    H201
+    Z
+
+    M194 322
+    H318
+    L344 360
+    H168
+    Z
+
+    M163 377
+    H349
+    L382 426
+    H130
+    Z
+  "/>
+</svg>

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+const targets = new Map([
+    ['win32:x64', { executable: 'ttyglass.exe', packageName: '@maxiedev/ttyglass-win32-x64' }],
+    ['linux:x64', { executable: 'ttyglass', packageName: '@maxiedev/ttyglass-linux-x64-gnu' }],
+    ['darwin:x64', { executable: 'ttyglass', packageName: '@maxiedev/ttyglass-darwin-x64' }],
+    ['darwin:arm64', { executable: 'ttyglass', packageName: '@maxiedev/ttyglass-darwin-arm64' }],
+]);
+const target = targets.get(`${process.platform}:${process.arch}`);
+if (target === undefined) {
+    process.stderr.write(`ttyglass: unsupported platform ${process.platform}/${process.arch}\n`);
+    process.exitCode = 1;
+}
+else {
+    const require = createRequire(import.meta.url);
+    let manifestPath;
+    try {
+        manifestPath = require.resolve(`${target.packageName}/package.json`);
+    }
+    catch {
+        process.stderr.write(`ttyglass: the native package ${target.packageName} is missing. Reinstall ttyglass without --no-optional.\n`);
+        process.exit(1);
+    }
+    const executable = resolve(dirname(manifestPath), 'bin', target.executable);
+    const child = spawn(executable, process.argv.slice(2), {
+        stdio: 'inherit',
+        windowsHide: true,
+    });
+    child.once('error', (error) => {
+        process.stderr.write(`ttyglass: could not start the native executable: ${error.message}\n`);
+        process.exitCode = 1;
+    });
+    child.once('exit', (code, signal) => {
+        if (signal !== null) {
+            process.kill(process.pid, signal);
+            return;
+        }
+        process.exitCode = code ?? 1;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAO7C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAuB;IAC5C,CAAC,WAAW,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,8BAA8B,EAAE,CAAC;IAC1F,CAAC,WAAW,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,kCAAkC,EAAE,CAAC;IAC1F,CAAC,YAAY,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,+BAA+B,EAAE,CAAC;IACxF,CAAC,cAAc,EAAE,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,iCAAiC,EAAE,CAAC;CAC7F,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AAClE,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;IACzB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC;IAC7F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;KAAM,CAAC;IACN,MAAM,OAAO,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,YAAoB,CAAC;IACzB,IAAI,CAAC;QACH,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,MAAM,CAAC,WAAW,eAAe,CAAC,CAAC;IACvE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gCAAgC,MAAM,CAAC,WAAW,0DAA0D,CAC7G,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC5E,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QACrD,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,IAAI;KAClB,CAAC,CAAC;IACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oDAAoD,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;QAC5F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;QAClC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAClC,OAAO;QACT,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,IAAI,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/diagnostics.d.ts

@@ -0,0 +1,19 @@
+import type { DiagnosticRecord } from './types.js';
+export interface SendDiagnosticOptions {
+    endpoint?: string;
+    token?: string;
+    timeoutMilliseconds?: number;
+    throwOnError?: boolean;
+    fetchImplementation?: typeof fetch;
+}
+export interface TtyglassSinkOptions extends SendDiagnosticOptions {
+    source?: string;
+    onError?: (error: unknown) => void;
+}
+export interface TtyglassSink {
+    write(chunk: string | Uint8Array): boolean;
+    flush(): Promise<void>;
+}
+export declare function sendTtyglassDiagnostic(record: DiagnosticRecord, options?: SendDiagnosticOptions): Promise<boolean>;
+export declare function createTtyglassSink(options?: TtyglassSinkOptions): TtyglassSink;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,OAAO,KAAK,CAAC;CACpC;AAED,MAAM,WAAW,mBAAoB,SAAQ,qBAAqB;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAgCD,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAwCD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAqClF"}

package/dist/diagnostics.js

@@ -0,0 +1,126 @@
+const pinoLevels = new Map([
+    [10, 'trace'],
+    [20, 'debug'],
+    [30, 'info'],
+    [40, 'warn'],
+    [50, 'error'],
+    [60, 'fatal'],
+]);
+function isLoopbackEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        return (url.protocol === 'http:' &&
+            (url.hostname === '127.0.0.1' || url.hostname === 'localhost' || url.hostname === '[::1]'));
+    }
+    catch {
+        return false;
+    }
+}
+function resolveConnection(options) {
+    const endpoint = options.endpoint ?? process.env.TTYGLASS_DIAGNOSTICS_URL;
+    const token = options.token ?? process.env.TTYGLASS_DIAGNOSTICS_TOKEN;
+    if (endpoint === undefined || token === undefined || !isLoopbackEndpoint(endpoint)) {
+        return undefined;
+    }
+    return { endpoint, token };
+}
+export async function sendTtyglassDiagnostic(record, options = {}) {
+    const connection = resolveConnection(options);
+    if (connection === undefined) {
+        return false;
+    }
+    try {
+        const fetchImplementation = options.fetchImplementation ?? fetch;
+        const response = await fetchImplementation(connection.endpoint, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${connection.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(record),
+            signal: AbortSignal.timeout(options.timeoutMilliseconds ?? 1_000),
+        });
+        if (!response.ok) {
+            throw new Error(`ttyglass diagnostics returned HTTP ${response.status}`);
+        }
+        return true;
+    }
+    catch (error) {
+        if (options.throwOnError === true) {
+            throw error;
+        }
+        return false;
+    }
+}
+function fromJsonLine(line, source) {
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            return { ...(source === undefined ? {} : { source }), event: 'log', message: line };
+        }
+        const input = parsed;
+        const fields = { ...input };
+        delete fields.time;
+        delete fields.level;
+        delete fields.name;
+        delete fields.source;
+        delete fields.event;
+        delete fields.msg;
+        delete fields.message;
+        const time = input.time;
+        const recordSource = typeof input.source === 'string' ? input.source : typeof input.name === 'string' ? input.name : source;
+        const message = typeof input.message === 'string' ? input.message : typeof input.msg === 'string' ? input.msg : undefined;
+        return {
+            ...(typeof time === 'string' || typeof time === 'number' ? { time } : {}),
+            ...(recordSource === undefined ? {} : { source: recordSource }),
+            level: typeof input.level === 'number'
+                ? (pinoLevels.get(input.level) ?? 'info')
+                : typeof input.level === 'string'
+                    ? input.level
+                    : 'info',
+            event: typeof input.event === 'string' ? input.event : 'log',
+            ...(message === undefined ? {} : { message }),
+            fields,
+        };
+    }
+    catch {
+        return { ...(source === undefined ? {} : { source }), event: 'log', message: line };
+    }
+}
+export function createTtyglassSink(options = {}) {
+    let buffered = '';
+    let pending = Promise.resolve();
+    function enqueue(line) {
+        if (line.length === 0) {
+            return;
+        }
+        const record = fromJsonLine(line, options.source);
+        pending = pending
+            .then(async () => {
+            await sendTtyglassDiagnostic(record, { ...options, throwOnError: true });
+        })
+            .catch((error) => {
+            options.onError?.(error);
+        });
+    }
+    return {
+        write(chunk) {
+            buffered += typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
+            for (;;) {
+                const newline = buffered.indexOf('\n');
+                if (newline < 0) {
+                    break;
+                }
+                enqueue(buffered.slice(0, newline).trimEnd());
+                buffered = buffered.slice(newline + 1);
+            }
+            return true;
+        },
+        async flush() {
+            enqueue(buffered.trimEnd());
+            buffered = '';
+            await pending;
+        },
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { SendDiagnosticOptions, TtyglassSink, TtyglassSinkOptions, } from './diagnostics.js';
+export { createTtyglassSink, sendTtyglassDiagnostic } from './diagnostics.js';
+export type { DiagnosticLevel, DiagnosticRecord, NormalizedDiagnosticRecord, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,qBAAqB,EACrB,YAAY,EACZ,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createTtyglassSink, sendTtyglassDiagnostic } from './diagnostics.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+export type DiagnosticLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export interface DiagnosticRecord {
+    time?: string | number | Date;
+    source?: string;
+    level?: DiagnosticLevel | number;
+    event?: string;
+    message?: string;
+    fields?: Record<string, unknown>;
+}
+export interface NormalizedDiagnosticRecord {
+    time: string;
+    source: string;
+    level: DiagnosticLevel;
+    event: string;
+    message?: string;
+    fields: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEtF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,eAAe,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/diagnostics.md

@@ -0,0 +1,79 @@
+# Diagnostics without a ttyglass library
+
+ttyglass keeps application diagnostics separate from the terminal stream and from ttyglass's own process state. The Diagnostics panel contains only records submitted by the observed application. Every observed command receives two environment variables:
+
+- `TTYGLASS_DIAGNOSTICS_URL`: a loopback-only HTTP endpoint for the current run.
+- `TTYGLASS_DIAGNOSTICS_TOKEN`: the bearer token for that endpoint.
+
+Send either one JSON object with `Content-Type: application/json` or newline-delimited JSON. Use this record shape:
+
+```json
+{
+  "time": "2026-09-12T12:00:00.000Z",
+  "source": "checkout",
+  "level": "info",
+  "event": "screen.loaded",
+  "message": "Checkout screen is ready",
+  "fields": {
+    "items": 3
+  }
+}
+```
+
+All fields are optional. `level` accepts `trace`, `debug`, `info`, `warn`, `error`, or `fatal`. Unknown top-level fields are ignored. `fields` must contain JSON values, with at most 32 entries per object or array and at most three nested container levels. A request may contain up to 100 records and 64 KiB.
+
+## Node.js standard library
+
+```js
+import { request } from 'node:http';
+
+export function ttyglassDiagnostic(record) {
+  const endpoint = process.env.TTYGLASS_DIAGNOSTICS_URL;
+  const token = process.env.TTYGLASS_DIAGNOSTICS_TOKEN;
+  if (!endpoint || !token) return;
+
+  const body = JSON.stringify(record);
+  const outgoing = request(endpoint, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(body),
+    },
+  });
+  outgoing.on('error', () => {});
+  outgoing.end(body);
+}
+```
+
+## Python standard library
+
+```python
+import json
+import os
+import urllib.request
+
+
+def ttyglass_diagnostic(record):
+    endpoint = os.environ.get("TTYGLASS_DIAGNOSTICS_URL")
+    token = os.environ.get("TTYGLASS_DIAGNOSTICS_TOKEN")
+    if not endpoint or not token:
+        return
+
+    body = json.dumps(record).encode("utf-8")
+    request = urllib.request.Request(
+        endpoint,
+        data=body,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+    )
+    try:
+        urllib.request.urlopen(request, timeout=1).close()
+    except OSError:
+        pass
+```
+
+Logging is optional and should never stop the observed application. Do not include secrets, credentials, personal data, or unrelated environment values. ttyglass keeps a bounded in-memory history for the current run and does not upload it.

package/docs/typescript.md

@@ -0,0 +1,37 @@
+# Optional TypeScript diagnostics
+
+The package exports a direct sender and a small writable sink. Both are no-ops by default when the application does not run under ttyglass.
+
+## Direct events
+
+```ts
+import { sendTtyglassDiagnostic } from 'ttyglass';
+
+await sendTtyglassDiagnostic({
+  source: 'checkout',
+  level: 'info',
+  event: 'screen.loaded',
+  fields: { items: 3 },
+});
+```
+
+## Pino destination
+
+ttyglass does not depend on Pino. Its sink implements the `write(string)` destination contract used by Pino and other JSON-line loggers.
+
+```ts
+import pino from 'pino';
+import { createTtyglassSink } from 'ttyglass';
+
+const ttyglass = createTtyglassSink({ source: 'checkout' });
+const logger = pino(ttyglass);
+
+logger.info({ items: 3 }, 'Checkout screen is ready');
+
+// Flush only when the process already has an orderly shutdown path.
+await ttyglass.flush();
+```
+
+The sink maps Pino numeric levels and moves `time`, `level`, `name`, `msg`, and `message` into ttyglass record fields. Remaining JSON properties become diagnostic `fields`.
+
+If a logger cannot accept a writable destination, call `sendTtyglassDiagnostic` from a temporary adapter instead. Remove the adapter when visual debugging no longer needs those events.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "ttyglass",
+  "version": "1.0.0",
+  "description": "Observe and debug real terminal user interfaces in a local browser.",
+  "keywords": [
+    "tui",
+    "terminal",
+    "pty",
+    "debugging",
+    "developer-tools"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrMaxie/ttyglass.git"
+  },
+  "homepage": "https://github.com/MrMaxie/ttyglass#readme",
+  "bugs": {
+    "url": "https://github.com/MrMaxie/ttyglass/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "engines": {
+    "node": "24.18.0"
+  },
+  "packageManager": "nub@0.7.5",
+  "workspaces": [
+    "frontend",
+    "packages/*"
+  ],
+  "bin": {
+    "ttyglass": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "assets/ttyglass-logo.svg",
+    "dist",
+    "docs",
+    "skills",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/clean.ts && nub --filter @ttyglass/frontend run build && node scripts/build-native.ts && tsc -p tsconfig.node.json",
+    "check": "nub --filter @ttyglass/frontend run check && biome check src test tests scripts && tsc --noEmit -p tsconfig.node.json && nimble check && nimble c --compileOnly --path:src test/test_diagnostics.nim && nimble c --compileOnly --path:src test/test_ipc.nim",
+    "format": "nub --filter @ttyglass/frontend run format && biome format --write src test tests scripts",
+    "package:check": "nub run check && nub run test && node scripts/verify-package.ts",
+    "package:check:published": "node scripts/verify-package.ts --published",
+    "prepack": "nub run build",
+    "prepublishOnly": "nub run package:check",
+    "pretest": "nub run build",
+    "test": "nimble c -r --path:src --nimcache:.local/nimcache/test-diagnostics --out:.local/test-diagnostics test/test_diagnostics.nim && nimble c -r --path:src --nimcache:.local/nimcache/test-ipc --out:.local/test-ipc test/test_ipc.nim && node --test test/*.test.ts",
+    "ttyglass": "node dist/cli.js"
+  },
+  "optionalDependencies": {
+    "@maxiedev/ttyglass-darwin-arm64": "1.0.0",
+    "@maxiedev/ttyglass-darwin-x64": "1.0.0",
+    "@maxiedev/ttyglass-linux-x64-gnu": "1.0.0",
+    "@maxiedev/ttyglass-win32-x64": "1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.13",
+    "@types/node": "22.20.2",
+    "typescript": "7.0.2"
+  }
+}

package/skills/README.md

@@ -0,0 +1,8 @@
+# Agent skills
+
+ttyglass includes separate skill entrypoints for Codex and Claude Code:
+
+- `skills/codex/SKILL.md`
+- `skills/claude/SKILL.md`
+
+Copy or link the appropriate directory into the skill location used by the agent installation. Keep the package copy as the source of truth so the agent guidance stays aligned with the installed ttyglass version.

package/skills/claude/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: ttyglass
+description: Run and inspect a real terminal user interface in ttyglass when Claude Code needs visual evidence, keyboard interaction, resize verification, or separate diagnostics without modifying the observed project.
+---
+
+# Inspect a TUI with ttyglass
+
+Use ttyglass to let Claude Code see and operate a real TUI through a local browser. It is for visual assessment, interaction debugging, responsive terminal checks, and diagnostics that must remain separate from the terminal screen.
+
+## Workflow
+
+1. Identify the exact project command that normally starts the TUI. Do not create a mock screen or project-specific wrapper.
+2. From the tested project directory, run `ttyglass -- <command> <arguments>`. Put ttyglass options before `--` and preserve the tested command after it.
+3. Read the authenticated loopback URL printed by ttyglass and open that exact URL with an available browser tool.
+4. Verify the real rendered state before interacting. Exercise only actions authorized by the user.
+5. Check relevant terminal sizes, keyboard navigation, focus, errors, loading and empty states, and process exit behavior. Use Diagnostics for investigation data, not as a substitute for the visible TUI.
+6. Capture evidence only when requested or required by the parent task. State which states and sizes were actually observed.
+7. Close the browser client and stop ttyglass when finished. Confirm the observed process ended.
+
+## Safety
+
+- ttyglass is a local observation tool, not authorization to mutate project or external state.
+- Use the exact loopback URL printed for the current run. Never expose it, its fragment token, or diagnostics token outside the local task.
+- Do not put credentials, personal data, complete environment dumps, or unrelated project content in diagnostics.
+- Do not claim native terminal behavior from a static mock or DOM-only recreation. ttyglass must be connected to the real PTY or ConPTY process.
+- If browser automation is unavailable, report that visual interaction remains unverified instead of inferring it from tests.
+
+See the package `README.md` for CLI options and `docs/diagnostics.md` for dependency-free diagnostic records.

package/skills/codex/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: ttyglass
+description: Run and inspect a real terminal user interface in ttyglass when Codex needs visual evidence, keyboard interaction, resize verification, or separate diagnostics without modifying the observed project.
+---
+
+# Inspect a TUI with ttyglass
+
+Use ttyglass to let Codex see and operate a real TUI through a local browser. It is for visual assessment, interaction debugging, responsive terminal checks, and diagnostics that must remain separate from the terminal screen.
+
+## Workflow
+
+1. Identify the exact project command that normally starts the TUI. Do not create a mock screen or project-specific wrapper.
+2. From the tested project directory, run `ttyglass -- <command> <arguments>`. Put ttyglass options before `--` and preserve the tested command after it.
+3. Read the authenticated loopback URL printed by ttyglass and open that exact URL in the available Codex browser.
+4. Verify the real rendered state before interacting. Exercise only actions authorized by the user.
+5. Check relevant terminal sizes, keyboard navigation, focus, errors, loading and empty states, and process exit behavior. Use Diagnostics for investigation data, not as a substitute for the visible TUI.
+6. Capture evidence only when requested or required by the parent task. State which states and sizes were actually observed.
+7. Close the browser client and stop ttyglass when finished. Confirm the observed process ended.
+
+## Safety
+
+- ttyglass is a local observation tool, not authorization to mutate project or external state.
+- Use the exact loopback URL printed for the current run. Never expose it, its fragment token, or diagnostics token outside the local task.
+- Do not put credentials, personal data, complete environment dumps, or unrelated project content in diagnostics.
+- Do not claim native terminal behavior from a static mock or DOM-only recreation. ttyglass must be connected to the real PTY or ConPTY process.
+- If browser automation is unavailable, report that visual interaction remains unverified instead of inferring it from tests.
+
+See the package `README.md` for CLI options and `docs/diagnostics.md` for dependency-free diagnostic records.