feat(readme): document real-time change streaming and expand README with features, architecture, and configuration updates

changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2026-01-25 - 1.6.0 - feat(readme)
+document real-time change streaming and expand README with features, architecture, and configuration updates
+
+- Add Real-Time Change Streaming section: MongoDB change streams, S3 polling (ETag), activity stream, WebSocket subscriptions, and auto-reconnect behavior
+- Expand S3 and MongoDB feature lists: in-place text editing, enhanced previews (code), show/hide system databases, live indicators, context menus
+- Reintroduce project-level npmextra.json example and clarify environment variable names and priority order
+- Add Architecture and How It Works sections with tree layout and streaming design details
+- Minor wording, formatting, and installation clarifications (prefer pnpm examples, fix LICENSE filename case)
+
 ## 2026-01-25 - 1.5.0 - feat(streaming)
 add real-time streaming (MongoDB change streams & S3 bucket watchers) with WebSocket subscriptions and activity stream UI
 

readme.md

@@ -1,6 +1,6 @@
 # @git.zone/tsview
 
-A powerful developer tool for browsing and managing S3-compatible storage and MongoDB databases through a sleek web UI. Built with TypeScript, designed for developers who need quick, visual access to their data stores during development. 🚀
+A powerful developer tool for browsing and managing S3-compatible storage and MongoDB databases through a sleek web UI — with real-time change streaming baked in. Built with TypeScript, designed for developers who need quick, visual access to their data stores. 🚀
 
 ## Issue Reporting and Security
 
@@ -10,41 +10,47 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 
 ```bash
 # Global installation (recommended for CLI usage)
-npm install -g @git.zone/tsview
-# or
 pnpm add -g @git.zone/tsview
 
 # Local installation (for programmatic usage)
-npm install @git.zone/tsview
-# or
 pnpm add @git.zone/tsview
 ```
 
 ## Features ✨
 
 ### 🗄️ S3 Storage Browser
-- **Column View Navigation** - Mac Finder-style interface with resizable columns for intuitive file browsing
+- **Column View Navigation** — Mac Finder-style interface with resizable columns
-- **List View** - Traditional key-based view with hierarchical navigation
+- **List View** — Traditional key-based view with hierarchical navigation
-- **Real-time Preview** - View images, JSON, text files, and more directly in the browser
+- **Real-time Preview** — View images, JSON, text files, code, and more directly in the browser
-- **Bucket Management** - Create, delete, and switch between buckets
+- **Bucket Management** — Create, delete, and switch between buckets
-- **File Operations** - Upload, download, delete objects with ease
+- **File Operations** — Upload, download, delete objects
-- **Smart Content Type Detection** - Automatic content type recognition for 20+ file types
+- **In-place Text Editing** — Edit text files directly in the browser with change tracking
-- **Breadcrumb Navigation** - Easy path traversal with clickable breadcrumbs
+- **Smart Content Type Detection** — Automatic recognition for 20+ file types
+- **Breadcrumb Navigation** — Clickable path traversal
 
 ### 🍃 MongoDB Browser
-- **Database Explorer** - Hierarchical navigation through databases and collections
+- **Database Explorer** — Hierarchical navigation through databases and collections
-- **Document Viewer** - Paginated table view with sorting and filtering
+- **Database Overview** — Collection counts, data sizes, index stats at a glance
-- **Document Editor** - Full CRUD operations with JSON syntax highlighting
+- **Document Viewer** — Paginated table view with JSON filter support
-- **Index Management** - View, create, and drop indexes
+- **Document Editor** — Full CRUD with syntax-highlighted code editor and change tracking
-- **Aggregation Pipeline** - Run custom aggregation queries (coming soon)
+- **Index Management** — View, create, and drop indexes
-- **Collection Stats** - View document counts, sizes, and storage metrics
+- **Collection Stats** — Document counts, sizes, storage metrics
-- **Server Status** - Monitor connection info and server health
+- **Server Status** — Connection info, version, uptime
+- **Show/Hide System Databases** — Toggle visibility of `admin`, `local`, `config`
+
+### ⚡ Real-Time Change Streaming
+- **MongoDB Change Streams** — Live updates via native MongoDB change streams
+- **S3 Change Detection** — Polling-based bucket monitoring with ETag comparison (5s intervals)
+- **Activity Stream** — Combined timeline of all changes from both sources, filterable by type
+- **Live Indicators** — Green dot + change count badges on active views
+- **WebSocket Subscriptions** — Per-collection, per-bucket, or global activity feed
+- **Auto-Reconnect** — Subscriptions automatically restored after connection loss
 
 ### 🎨 Modern Web UI
 - 🌙 Dark theme designed for developer comfort
 - 📱 Responsive layout with resizable panels
-- ⌨️ Keyboard-friendly navigation
+- ⌨️ Context menus for quick actions
-- 🔌 Zero external runtime dependencies in the browser
+- 🔌 Everything bundled — zero external runtime dependencies in the browser
 
 ## Quick Start 🚀
 
@@ -90,28 +96,6 @@ tsview mongo
 tsview mongodb
 ```
 
-## Configuration via npmextra.json
-
-For project-level configuration, add a `@git.zone/tsview` section to your `npmextra.json`:
-
-```json
-{
-  "@git.zone/tsview": {
-    "port": 3015,
-    "killIfBusy": true,
-    "openBrowser": false
-  }
-}
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `port` | `number` | auto | Fixed port to use (auto-finds from 3010 if not set) |
-| `killIfBusy` | `boolean` | `false` | Kill existing process if port is busy |
-| `openBrowser` | `boolean` | `true` | Automatically open browser on start |
-
-**Priority order:** CLI `--port` flag > `npmextra.json` config > auto-detect
-
 ## Programmatic API
 
 Use tsview as a library in your own tools:
@@ -124,7 +108,7 @@ const viewer = new TsView();
 // Option 1: Load from .nogit/env.json (gitzone service format)
 await viewer.loadConfigFromEnv();
 
-// Option 2: Configure programmatically for local development
+// Option 2: Configure programmatically
 viewer.setS3Config({
   endpoint: 'localhost',
   port: 9000,
@@ -138,7 +122,7 @@ viewer.setMongoConfig({
   mongoDbName: 'mydb'
 });
 
-// Option 3: Configure for cloud services
+// Option 3: Cloud services
 viewer.setS3Config({
   endpoint: 's3.amazonaws.com',
   accessKey: 'AKIAXXXXXXX',
@@ -163,30 +147,53 @@ await viewer.start(3500);
 await viewer.stop();
 ```
 
-## Environment Variables
+## Configuration
 
-The following environment variables are supported in `.nogit/env.json`:
+### Project-level via `npmextra.json`
+
+```json
+{
+  "@git.zone/tsview": {
+    "port": 3015,
+    "killIfBusy": true,
+    "openBrowser": false
+  }
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `port` | `number` | auto | Fixed port (auto-finds from 3010 if not set) |
+| `killIfBusy` | `boolean` | `false` | Kill existing process if port is busy |
+| `openBrowser` | `boolean` | `true` | Automatically open browser on start |
+
+**Port priority:** CLI `--port` flag → `npmextra.json` → auto-detect
+
+### Environment Variables (`.nogit/env.json`)
+
+#### S3
 
-### S3 Configuration
 | Variable | Description |
 |----------|-------------|
-| `S3_ENDPOINT` | S3 server hostname |
+| `S3_ENDPOINT` | S3-compatible server hostname |
-| `S3_PORT` | S3 server port (optional) |
+| `S3_PORT` | Server port (optional) |
 | `S3_ACCESSKEY` | Access key ID |
 | `S3_SECRETKEY` | Secret access key |
 | `S3_USESSL` | Use HTTPS (`true`/`false`) |
 
-### MongoDB Configuration
+#### MongoDB
+
 | Variable | Description |
 |----------|-------------|
-| `MONGODB_URL` | Full MongoDB connection string |
+| `MONGODB_URL` | Full connection string (preferred) |
 | `MONGODB_NAME` | Default database name |
 
-Or use individual MongoDB variables:
+Or use individual variables:
+
 | Variable | Description |
 |----------|-------------|
-| `MONGODB_HOST` | MongoDB hostname |
+| `MONGODB_HOST` | Hostname |
-| `MONGODB_PORT` | MongoDB port |
+| `MONGODB_PORT` | Port |
 | `MONGODB_USER` | Username |
 | `MONGODB_PASS` | Password |
 | `MONGODB_NAME` | Database name |
@@ -197,7 +204,7 @@ tsview works with any S3-compatible storage:
 
 | Provider | Status |
 |----------|--------|
-| **MinIO** | ✅ Perfect for local development |
+| **MinIO** | ✅ Perfect for local dev |
 | **AWS S3** | ✅ Amazon's object storage |
 | **DigitalOcean Spaces** | ✅ Simple object storage |
 | **Backblaze B2** | ✅ S3-compatible API |
@@ -215,10 +222,45 @@ tsview works with any S3-compatible storage:
 | **Data** | `.csv`, `.xml`, `.yaml`, `.yml` |
 | **Documents** | `.pdf` |
 
+## Architecture
+
+```
+tsview/
+├── ts/                           # Backend
+│   ├── api/                      # TypedRequest API handlers
+│   │   ├── handlers.s3.ts        #   S3 bucket & object operations
+│   │   └── handlers.mongodb.ts   #   MongoDB CRUD & admin operations
+│   ├── config/                   # Configuration management
+│   ├── server/                   # Web server (TypedServer + TypedSocket)
+│   ├── streaming/                # Real-time change streaming
+│   │   ├── classes.changestream-manager.ts  # MongoDB + S3 watchers
+│   │   └── interfaces.streaming.ts          # Subscription interfaces
+│   ├── interfaces/               # Shared TypeScript interfaces
+│   └── tsview.classes.tsview.ts  # Main class
+├── ts_web/                       # Frontend
+│   ├── elements/                 # Web components (LitElement)
+│   │   ├── tsview-app.ts         #   App shell + navigation
+│   │   ├── tsview-s3-*.ts        #   S3 browser components
+│   │   ├── tsview-mongo-*.ts     #   MongoDB browser components
+│   │   └── tsview-activity-stream.ts  # Real-time activity feed
+│   ├── services/                 # API + WebSocket clients
+│   ├── styles/                   # Dark theme
+│   └── utilities/                # Formatting helpers
+└── cli.ts.js                     # CLI entry point
+```
+
+### How It Works
+
+1. **Backend** — A `TypedServer` serves the bundled web UI and exposes a typed API via `TypedRequest` over HTTP. A `TypedSocket` WebSocket layer handles real-time streaming subscriptions.
+
+2. **Frontend** — LitElement-based web components communicate with the backend via `TypedRequest`. The `ChangeStreamService` connects over WebSocket and distributes real-time events to active views via RxJS Subjects.
+
+3. **Streaming** — The `ChangeStreamManager` creates MongoDB Change Streams and S3 BucketWatchers on demand (one per subscribed resource). Changes are pushed to subscribed clients and accumulated in a 1000-event ring buffer for the Activity Stream view.
+
 ## Development
 
 ```bash
-# Clone the repository
+# Clone
 git clone https://code.foss.global/git.zone/tsview.git
 cd tsview
 
@@ -235,29 +277,9 @@ pnpm run watch
 pnpm test
 ```
 
-## Architecture
-
-```
-tsview/
-├── ts/                    # Backend TypeScript source
-│   ├── api/               # TypedRequest API handlers
-│   │   ├── handlers.s3.ts
-│   │   └── handlers.mongodb.ts
-│   ├── config/            # Configuration management
-│   ├── server/            # Web server (TypedServer)
-│   ├── interfaces/        # Shared TypeScript interfaces
-│   └── tsview.classes.tsview.ts  # Main class
-├── ts_web/                # Frontend TypeScript source
-│   ├── elements/          # Web components (LitElement)
-│   ├── services/          # API client service
-│   ├── styles/            # Shared theme styles
-│   └── utilities/         # Helper functions
-└── cli.ts.js              # CLI entry point
-```
-
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tsview',
-  version: '1.5.0',
+  version: '1.6.0',
   description: 'A CLI tool for viewing S3 and MongoDB data with a web UI'
 }

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tsview',
-  version: '1.5.0',
+  version: '1.6.0',
   description: 'A CLI tool for viewing S3 and MongoDB data with a web UI'
 }