add js class

Reviewed-on: #10

AI_prompt.md

@@ -0,0 +1,154 @@
+Consider the following scenarios:
+Scenario 1: The "Command & Control" Loop (Low Latency)Focus: Small payloads, Core NATS, bi-directional JSON.The Action: A user on a JavaScript dashboard clicks a "Start Simulation" button. This sends a JSON configuration (parameters like step_size and iterations) to Julia.The Flow: * JS (Sender): Recognizes the message is small ($< 10KB$). Packages it as a direct transport JSON envelope.Julia (Receiver): Listens on the NATS subject, decodes the JSON, and immediately acknowledges receipt with a "Running" status.Project Requirement Met: Fast, low-overhead communication for control signals without involving the fileserver.
+Scenario 2: The "Deep Dive" Analysis (High Bandwidth)Focus: Large Arrow tables, Claim-Check pattern, Julia to JS.The Action: Julia finishes a heavy computation and produces a 500MB DataFrame with 10 million rows. It needs to send this to the JS frontend for visualization (e.g., using Perspective.js or D3).The Flow:Julia (Sender): Converts the DataFrame to an Arrow IPC stream. It sees the size is $> 1MB$, so it uploads the bytes to the HTTP fileserver. It then publishes a NATS message with transport: "link" and the URL.JS (Receiver): Receives the URL, fetches the data via fetch(), and uses tableFromIPC() to load the data into memory with zero-copy.Project Requirement Met: Handling massive datasets that exceed NATS message limits while maintaining data integrity across languages.
+Scenario 3: Live Audio/Signal Processing (Multimedia & Metadata)Focus: Raw binary, bi-directional streaming, NATS Headers.The Action: The JS client captures a 2-second "chunk" of microphone audio. It needs Julia to perform a Fast Fourier Transform (FFT) or AI transcription.The Flow:JS (Sender): Sends the raw binary WAV/PCM data. It uses NATS Headers to store the metadata ($fs = 44.1kHz$, $channels = 1$) to keep the payload purely binary.Julia (Receiver): Processes the audio and sends back a JSON result (the transcription) and an Arrow Table (the frequency spectrum data).Project Requirement Met: Bi-directional flow involving mixed media (Audio) and technical results (Arrow).
+Scenario 4: The "Catch-Up" (Persistence & JetStream)Focus: NATS JetStream, late-joining consumers, state sync.The Action: Julia is constantly publishing "System Health" updates. The JS dashboard is closed for 10 minutes. When the user re-opens the dashboard, they need to see the last 10 minutes of history.The Flow:NATS (Server): Uses a JetStream with a Limits retention policy.JS (Consumer): Connects and requests a "Replay" from the last 10 minutes. It receives a mix of direct (small updates) and link (historical snapshots) messages.Project Requirement Met: Temporal decoupling—consumers can receive data that was sent while they were offline.
+
+Role: Principal Systems Architect & Lead Software Engineer.Objective: Implement a high-performance, bi-directional data bridge between a Julia service and a JavaScript (Node.js) service using NATS (Core & JetStream).⚠️ STRICT ARCHITECTURAL CONSTRAINTS (Non-Negotiable)Transport Strategy (Claim-Check Pattern):Direct Path: If payload is < 1MB, send data directly via NATS inside the message envelope (Base64 encoded).Link Path: If payload is > 1MB, upload to a shared HTTP fileserver/store. The NATS message must only contain the metadata and the download URL.Tabular Data Format: * MUST use Apache Arrow IPC Stream for all tables/DataFrames. No CSV or standard JSON-serialization of tables allowed.System Symmetry: * Both services must function as Producers AND Consumers.Modular Elegance: * Implementation must be abstracted into a SmartSend function and a SmartReceive handler. The developer calling these functions should not need to care if the data is going via NATS direct or HTTP link.Technical Stack & Use CasesJulia: NATS.jl, Arrow.jl, JSON3.jl, HTTP.jl.Node.js: nats.js, apache-arrow.Scenarios to Support: * Large Data: Sending a 500MB Arrow table from Julia $\rightarrow$ JS.Media: Sending a 5MB WAV file from JS $\rightarrow$ Julia.Signals: Sending small JSON control commands ($< 10KB$) directly via NATS.Implementation Requirements1. Unified JSON Envelope:Define a schema containing: correlation_id (UUID), type (table/binary/json), transport (direct/link), payload (if direct), and url (if link).2. The Julia Module:Implement SmartSend(subject, data, type): Handles Arrow serialization to an IOBuffer, checks size, and manages HTTP uploads for large blobs.Implement SmartReceive(msg): Parses envelope, handles the HTTP fetch with Exponential Backoff (to avoid race conditions), and restores the DataFrame.Include a basic HTTP.listen server to serve as the temporary storage.3. The JavaScript Module:Implement a symmetric SmartSend using nats.js and apache-arrow.Implement a JetStream Pull Consumer for SmartReceive to ensure backpressure and memory safety.4. Performance & Reliability:Demonstrate "Zero-Copy" reading of the Arrow IPC stream on the JS side.Log the correlation_id at every stage for distributed tracing.
+
+
+
+
+
+
+
+Create a walkthrough for Julia service-A service sending a mix-content chat message to Julia service-B. the chat message must includes 
+
+
+
+
+
+I updated the following:
+- NATSBridge.jl. Essentially I add NATS_connection keyword and new publish_message function to support the keyword. 
+Use them and ONLY them as ground truth.
+Then update the following files accordingly:
+- architecture.md
+- implementation.md
+
+All API should be semantically consistent and naming should be consistent across the board.
+
+
+
+
+
+
+
+
+
+Task: Update NATSBridge.js to reflect recent changes in NATSBridge.jl and docs
+Context: NATSBridge.jl and docs has been updated.
+Requirements:
+Source of Truth: Treat the updated NATSBridge.jl and docs as the definitive source.
+API Consistency: Ensure the Main Package API (e.g., smartsend(), publish_message()) uses consistent naming across all three supported languages.
+Ecosystem Variance: Low-level native functions (e.g., NATS.connect(), JSON.read()) should follow the conventions of the specific language ecosystem and do not require cross-language consistency.
+
+
+
+
+
+
+
+I'm expanding this Julia package (NATSBridge) into a cross-platform project by adding a JavaScript and Python/MicroPython implementation. To ensure accuracy, the Julia src directory will serve as the ground truth, as the documentation may be outdated.
+
+My goal is to maintain interface parity at the high-level API for a consistent user experience, while ensuring the low-level implementation adheres strictly to the idiomatic conventions of each respective language (e.g., multiple dispatch in Julia vs. asynchronous, prototype, or class-based patterns in JS and Python/MicroPython)
+
+Now, help me do the following:
+1) check architecture.md for any mistake.
+
+
+
+
+Help me expands this Julia package (NATSBridge) into a cross-platform project by adding a JavaScript and Python/MicroPython implementation. To ensure accuracy,  NATSBridge.jl will serve as the ground truth, as the documentation may be outdated.
+
+My goal is to maintain interface parity at the high-level API for a consistent user experience, while ensuring the low-level implementation adheres strictly to the idiomatic conventions of each respective language (e.g., multiple dispatch in Julia vs. asynchronous, prototype, or class-based patterns in JS and Python/MicroPython)
+
+Now do the following:
+1) check docs to see if there is any mistake.
+
+
+
+
+
+I'm expanding this Julia package (NATSBridge) into a cross-platform project by adding 
+a JavaScript, Python and MicroPython implementation. 
+The following will serve as the ground truth:
+- test_julia_mix_payloads_sender.jl
+- NATSBridge.jl
+- test_julia_mix_payloads_receiver.jl
+- architecture.md
+
+My goal is to maintain interface parity at the high-level API for a consistent user experience, 
+while ensuring the low-level implementation adheres strictly to the idiomatic conventions of each 
+respective language (e.g., multiple dispatch in Julia vs. asynchronous, prototype, or class-based 
+patterns in JS, Python and MicroPython)
+
+Now, help me do the following:
+1) Check whether natsbridge.js needs update or it already up to date.
+
+
+
+
+
+
+
+# ---------------------------------------------- 100 --------------------------------------------- #
+
+Got it — let’s rebuild your table in my own teaching style, keeping it crisp, intuitive, and easy for students to grasp. I’ll emphasize **purpose, audience, format, example, and KPI** in a way that flows like a story of how projects move from idea → contract → design → code → review → operations.
+
+---
+
+### SDD + GitOps Documentation Framework
+
+| Document        | Purpose (Rationale) | Primary Audience | Format / Content | Example (SaaS Context) | Measurement (KPI) |
+|-----------------|---------------------|-----------------|------------------|------------------------|-------------------|
+| **Requirements** | Capture the **business intent** — why we’re building this and what success looks like. Defines boundaries and user‑visible outcomes. | Stakeholders, Product Owners, Lead Developers | User stories, PRDs, acceptance criteria, non‑functional constraints. | “System must process tabular data from Julia to SvelteKit UI with <200ms latency for 5‑member teams.” | 95% of requests complete <200ms (synthetic monitoring). |
+| **Specification** | The **technical contract** — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. | Developers, QA Engineers, CI/CD pipelines | OpenAPI, Protobuf, AsyncAPI. Endpoint definitions, schemas, error codes. | `contract.yaml` defining a NATS subject that accepts Arrow streams with snake_case headers. | 100% of messages validated against spec (CI block rate). |
+| **Architecture** | The **blueprint** — how components fit together, interact, and scale. Guides system structure and trade‑offs. | Architects, Senior Developers, DevOps | C4 diagrams, Mermaid.js, component/network/storage models. | Diagram showing 6‑node cluster routing traffic via Caddy → Node.js API → Julia pods. | 100% of major decisions logged with trade‑off analysis. |
+| **Walkthrough** | The **story of flow** — shows how pieces connect end‑to‑end and why steps are sequenced. Builds intuition for new devs. | New Developers, Team Members | TOUR.md, Loom videos, sequence diagrams. Step‑by‑step traces with rationale. | “UI sends JSON → Node.js wraps Claim‑Check → Julia pulls Arrow data (prevents NATS overflow).” | New developers ship feature in <2 days (PR timeline). |
+| **Implementation** | The **real code** — business logic, helpers, tests, configs. Where design becomes executable. | Developers, Code Reviewers | Source code, README.md, unit tests, setup scripts. | Julia function for matrix calculation + SvelteKit component rendering table. | >80% unit test coverage, <5% drift from spec. |
+| **Validation** | The **enforcer** — ensures implementation matches the spec. Blocks drift and human error. | Automation servers, QA, Lead Developers | CI jobs, contract tests, linting, integration checks. | CI job rejects PR with camelCase field not allowed by YAML spec. | <1% of PRs bypass validation gates. |
+| **Runbook** | The **operational manual** — how the system lives in production, scales, and recovers. Guides on‑call engineers. | DevOps, SREs, On‑call Developers | K8s manifests, Helm charts, Markdown guides. Deployment, scaling, backup/restore, troubleshooting. | GitOps manifest ensuring 6 Julia replicas restart if memory >80%. | MTTR <15 minutes for P1 incidents. |
+
+
+
+
+
+
+
+
+# ---------------------------------------------- 100 --------------------------------------------- #
+
+SDD + GitOps Documentation Stack
+Document,"Purpose (The ""Rationale"")",Primary Audience,Format / Content,Example (SaaS Context),"Measurement (KPI)"
+Requirements,"Defines the ""Why"" and the Business Boundary. It sets the constraints and success criteria so the team knows when a feature is ""done"" from a user's perspective.","Stakeholders, Product Owners, Lead Developers","Format: User Stories, PRDs. Content: Functional goals, non-functional requirements (latency, scale), and explicit ""out-of-scope"" items.","""The system must process high-volume tabular data from Julia to the SvelteKit UI with <200ms latency for 5-member teams."",""Pass/Fail: 95% of requests complete <200ms (measured via synthetic monitoring)""
+The Spec,"The Technical Contract. It serves as the single source of truth that defines the shape of data. In SDD, this file drives code generation and automated testing.","Developers, QA Engineers, CI/CD Pipelines","Format: OpenAPI (YAML), Protobuf, AsyncAPI. Content: Endpoint definitions, strict data types, error codes, and request/response schemas.",A contract.yaml defining a NATS subject that accepts an Apache Arrow stream with specific snake_case headers.",""Schema Validation Rate: 100% of messages validated against spec (CI block rate)""
+Architecture,"The Structural Blueprint. It explains how the ""pieces"" are arranged in the cluster. It defines the relationships between services, databases, and external providers.","System Architects, Senior Developers, DevOps","Format: C4 Model Diagrams, Mermaid.js. Content: Component diagrams, network flow, storage strategy, and technology stack definitions.",A diagram showing how the 6-node cluster routes traffic through Caddy to the Node.js API and offloads heavy math to Julia pods.",""Architecture Decision Log: 100% of major decisions documented with trade-off analysis""
+Walkthrough,"The Intuition & Flow. It connects multiple APIs/services into a cohesive end-to-end story. It explains the ""steps"" and the ""rationale"" behind the sequence of operations.","New Developers, Current Team Members","Format: TOUR.md, Loom videos, Sequence Diagrams. Content: Step-by-step trace of a feature, explanation of state changes, and the ""why"" behind complex logic.","""End-to-End Trace:"" 1. UI sends JSON to Node.js. 2. Node.js wraps it in a Claim-Check. 3. Julia pulls the Arrow data. Rationale: This prevents NATS memory overflow.",""Onboarding Velocity: New developers deploy feature in <2 days (tracked via PR timeline)""
+Implementation,"The Functional Reality. This is the actual execution of the logic. In SDD, parts of this are auto-generated to ensure it never drifts from the Spec.","Developers, Code Reviewers","Format: Source Code (Git), README.md. Content: Business logic, internal helper functions, unit tests, and local setup instructions.",The Julia function that performs the matrix calculation and the SvelteKit component that renders the resulting table.",""Code Coverage: >80% unit test coverage, <5% test drift from spec""
+Validation,"The Enforcement Layer. It ensures that the ""Reality"" (Code) actually matches the ""Contract"" (Spec). It prevents human error from breaking the system.","Automation Servers, QA, Lead Developers","Format: GitHub Actions, Dredd, Prism. Content: Contract tests, linting rules, and integration tests that check API compliance.",A CI job that blocks a Pull Request because a developer added a camelCase field that isn't allowed in the shared YAML spec.",""Block Rate: <1% of PRs reach production without validation (CI gate pass rate)""
+Runbook,"The Operational Life-Support. It defines how the system lives in production and how to fix it. In GitOps, the ""State"" is declared here.","DevOps, SREs, On-call Developers","Format: K8s Manifests, Helm Charts, Markdown. Content: Deployment steps, scaling triggers, backup/restore commands, and troubleshooting guides.",A GitOps manifest in Flux that ensures 6 replicas of the Julia service are always running and restarts them if memory hits 80%.",""MTTR: <15 minutes for P1 incidents (tracked via incident management system)""
+
+Do you understand the provided text? Don't fucking change the table content. I want you to add "Measurement (KPI)" column. it is only example of course. This table will be used for consult and teaching.
+
+
+# ---------------------------------------------- 100 --------------------------------------------- #
+
+Can you write the table and explain this approach and each doc in details then save to docs/SDD_FRAMEWORK.md so I can consult it later.
+Don't forget to add How to use this approach effectively.
+
+
+# ---------------------------------------------- 100 --------------------------------------------- #
+
+Since I develop src folder before I adopt SDD_FRAMEWORK.md approach, can you check src folder and my current doc files then write docs/requirements.md  according to SDD framework? Treat src as ground truth.
+
+# ---------------------------------------------- 100 --------------------------------------------- #
+
+
+
+
+
+
+
+
+
+

AI_prompt.txt

@@ -1,103 +0,0 @@
-Consider the following scenarios:
-Scenario 1: The "Command & Control" Loop (Low Latency)Focus: Small payloads, Core NATS, bi-directional JSON.The Action: A user on a JavaScript dashboard clicks a "Start Simulation" button. This sends a JSON configuration (parameters like step_size and iterations) to Julia.The Flow: * JS (Sender): Recognizes the message is small ($< 10KB$). Packages it as a direct transport JSON envelope.Julia (Receiver): Listens on the NATS subject, decodes the JSON, and immediately acknowledges receipt with a "Running" status.Project Requirement Met: Fast, low-overhead communication for control signals without involving the fileserver.
-Scenario 2: The "Deep Dive" Analysis (High Bandwidth)Focus: Large Arrow tables, Claim-Check pattern, Julia to JS.The Action: Julia finishes a heavy computation and produces a 500MB DataFrame with 10 million rows. It needs to send this to the JS frontend for visualization (e.g., using Perspective.js or D3).The Flow:Julia (Sender): Converts the DataFrame to an Arrow IPC stream. It sees the size is $> 1MB$, so it uploads the bytes to the HTTP fileserver. It then publishes a NATS message with transport: "link" and the URL.JS (Receiver): Receives the URL, fetches the data via fetch(), and uses tableFromIPC() to load the data into memory with zero-copy.Project Requirement Met: Handling massive datasets that exceed NATS message limits while maintaining data integrity across languages.
-Scenario 3: Live Audio/Signal Processing (Multimedia & Metadata)Focus: Raw binary, bi-directional streaming, NATS Headers.The Action: The JS client captures a 2-second "chunk" of microphone audio. It needs Julia to perform a Fast Fourier Transform (FFT) or AI transcription.The Flow:JS (Sender): Sends the raw binary WAV/PCM data. It uses NATS Headers to store the metadata ($fs = 44.1kHz$, $channels = 1$) to keep the payload purely binary.Julia (Receiver): Processes the audio and sends back a JSON result (the transcription) and an Arrow Table (the frequency spectrum data).Project Requirement Met: Bi-directional flow involving mixed media (Audio) and technical results (Arrow).
-Scenario 4: The "Catch-Up" (Persistence & JetStream)Focus: NATS JetStream, late-joining consumers, state sync.The Action: Julia is constantly publishing "System Health" updates. The JS dashboard is closed for 10 minutes. When the user re-opens the dashboard, they need to see the last 10 minutes of history.The Flow:NATS (Server): Uses a JetStream with a Limits retention policy.JS (Consumer): Connects and requests a "Replay" from the last 10 minutes. It receives a mix of direct (small updates) and link (historical snapshots) messages.Project Requirement Met: Temporal decoupling—consumers can receive data that was sent while they were offline.
-
-Role: Principal Systems Architect & Lead Software Engineer.Objective: Implement a high-performance, bi-directional data bridge between a Julia service and a JavaScript (Node.js) service using NATS (Core & JetStream).⚠️ STRICT ARCHITECTURAL CONSTRAINTS (Non-Negotiable)Transport Strategy (Claim-Check Pattern):Direct Path: If payload is < 1MB, send data directly via NATS inside the message envelope (Base64 encoded).Link Path: If payload is > 1MB, upload to a shared HTTP fileserver/store. The NATS message must only contain the metadata and the download URL.Tabular Data Format: * MUST use Apache Arrow IPC Stream for all tables/DataFrames. No CSV or standard JSON-serialization of tables allowed.System Symmetry: * Both services must function as Producers AND Consumers.Modular Elegance: * Implementation must be abstracted into a SmartSend function and a SmartReceive handler. The developer calling these functions should not need to care if the data is going via NATS direct or HTTP link.Technical Stack & Use CasesJulia: NATS.jl, Arrow.jl, JSON3.jl, HTTP.jl.Node.js: nats.js, apache-arrow.Scenarios to Support: * Large Data: Sending a 500MB Arrow table from Julia $\rightarrow$ JS.Media: Sending a 5MB WAV file from JS $\rightarrow$ Julia.Signals: Sending small JSON control commands ($< 10KB$) directly via NATS.Implementation Requirements1. Unified JSON Envelope:Define a schema containing: correlation_id (UUID), type (table/binary/json), transport (direct/link), payload (if direct), and url (if link).2. The Julia Module:Implement SmartSend(subject, data, type): Handles Arrow serialization to an IOBuffer, checks size, and manages HTTP uploads for large blobs.Implement SmartReceive(msg): Parses envelope, handles the HTTP fetch with Exponential Backoff (to avoid race conditions), and restores the DataFrame.Include a basic HTTP.listen server to serve as the temporary storage.3. The JavaScript Module:Implement a symmetric SmartSend using nats.js and apache-arrow.Implement a JetStream Pull Consumer for SmartReceive to ensure backpressure and memory safety.4. Performance & Reliability:Demonstrate "Zero-Copy" reading of the Arrow IPC stream on the JS side.Log the correlation_id at every stage for distributed tracing.
-
-
-
-
-
-
-
-Create a walkthrough for Julia service-A service sending a mix-content chat message to Julia service-B. the chat message must includes 
-
-
-
-
-
-I updated the following:
-- NATSBridge.jl. Essentially I add NATS_connection keyword and new publish_message function to support the keyword. 
-Use them and ONLY them as ground truth.
-Then update the following files accordingly:
-- architecture.md
-- implementation.md
-
-All API should be semantically consistent and naming should be consistent across the board.
-
-
-
-
-
-
-
-
-
-Task: Update NATSBridge.js to reflect recent changes in NATSBridge.jl and docs
-Context: NATSBridge.jl and docs has been updated.
-Requirements:
-Source of Truth: Treat the updated NATSBridge.jl and docs as the definitive source.
-API Consistency: Ensure the Main Package API (e.g., smartsend(), publish_message()) uses consistent naming across all three supported languages.
-Ecosystem Variance: Low-level native functions (e.g., NATS.connect(), JSON.read()) should follow the conventions of the specific language ecosystem and do not require cross-language consistency.
-
-
-
-
-
-
-
-I'm expanding this Julia package (NATSBridge) into a cross-platform project by adding a JavaScript and Python/MicroPython implementation. To ensure accuracy, the Julia src directory will serve as the ground truth, as the documentation may be outdated.
-
-My goal is to maintain interface parity at the high-level API for a consistent user experience, while ensuring the low-level implementation adheres strictly to the idiomatic conventions of each respective language (e.g., multiple dispatch in Julia vs. asynchronous, prototype, or class-based patterns in JS and Python/MicroPython)
-
-Now, help me do the following:
-1) check architecture.md for any mistake.
-
-
-
-
-Help me expands this Julia package (NATSBridge) into a cross-platform project by adding a JavaScript and Python/MicroPython implementation. To ensure accuracy,  NATSBridge.jl will serve as the ground truth, as the documentation may be outdated.
-
-My goal is to maintain interface parity at the high-level API for a consistent user experience, while ensuring the low-level implementation adheres strictly to the idiomatic conventions of each respective language (e.g., multiple dispatch in Julia vs. asynchronous, prototype, or class-based patterns in JS and Python/MicroPython)
-
-Now do the following:
-1) check docs to see if there is any mistake.
-
-
-
-
-
-I'm expanding this Julia package (NATSBridge) into a cross-platform project by adding 
-a JavaScript, Python and MicroPython implementation. 
-The following will serve as the ground truth:
-- test_julia_mix_payloads_sender.jl
-- NATSBridge.jl
-- test_julia_mix_payloads_receiver.jl
-- architecture.md
-
-My goal is to maintain interface parity at the high-level API for a consistent user experience, 
-while ensuring the low-level implementation adheres strictly to the idiomatic conventions of each 
-respective language (e.g., multiple dispatch in Julia vs. asynchronous, prototype, or class-based 
-patterns in JS, Python and MicroPython)
-
-Now, help me do the following:
-1) Check whether natsbridge.js needs update or it already up to date.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

Project.toml

@@ -1,6 +1,6 @@
 name = "NATSBridge"
 uuid = "f2724d33-f338-4a57-b9f8-1be882570d10"
-version = "0.5.4"
+version = "0.5.6"
 authors = ["narawat <narawat@gmail.com>"]
 
 [deps]

README.md

@@ -1,6 +1,6 @@
 # NATSBridge - Cross-Platform Bi-Directional Data Bridge
 
-A high-performance, bi-directional data bridge for **Julia, JavaScript, Python, and MicroPython** applications using NATS (Core & JetStream), implementing the Claim-Check pattern for large payloads.
+A high-performance, bi-directional data bridge for **Julia**, **JavaScript**, **Python**, and **MicroPython** applications using NATS (Core & JetStream), implementing the Claim-Check pattern for large payloads.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![NATS](https://img.shields.io/badge/NATS-Enabled-green.svg)](https://nats.io)
@@ -28,8 +28,8 @@ NATSBridge enables seamless communication across multiple platforms through NATS
 
 | Transport | Payload Size | Method |
 |-----------|--------------|--------|
-| **Direct** | < 1MB | Sent directly via NATS (Base64 encoded) |
+| **Direct** | < 500KB | Sent directly via NATS (Base64 encoded) |
-| **Link** | >= 1MB | Uploaded to HTTP file server, URL sent via NATS |
+| **Link** | ≥ 500KB | Uploaded to HTTP file server, URL sent via NATS |
 
 ### Use Cases
 
@@ -45,9 +45,9 @@ NATSBridge enables seamless communication across multiple platforms through NATS
 | Platform | Implementation | Features |
 |----------|----------------|----------|
 | **Julia** | [`src/NATSBridge.jl`](src/NATSBridge.jl) | Full feature set, Arrow IPC, multiple dispatch |
-| **JavaScript** | [`src/natsbridge.js`](src/natsbridge.js) | Node.js, async/await |
+| **JavaScript (Node.js)** | [`src/natsbridge_ssr.js`](src/natsbridge_ssr.js) | Node.js, async/await, Arrow IPC |
-| **JavaScript (Browser)** | [`src/natsbridge_csr.js`](src/natsbridge_csr.js) | Browser, WebSocket NATS, async/await |
+| **JavaScript (Browser)** | [`src/natsbridge_csr.js`](src/natsbridge_csr.js) | Browser, WebSocket NATS, async/await, JSON table only |
-| **Python** | [`src/natsbridge.py`](src/natsbridge.py) | Desktop Python, asyncio, type hints |
+| **Python** | [`src/natsbridge.py`](src/natsbridge.py) | Desktop Python, asyncio, type hints, Arrow IPC |
 | **MicroPython** | [`src/natsbridge_mpy.py`](src/natsbridge_mpy.py) | Memory-constrained, synchronous API |
 
 ### Platform Comparison
@@ -57,7 +57,8 @@ NATSBridge enables seamless communication across multiple platforms through NATS
 | Multiple Dispatch | ✅ Native | ❌ | ❌ | ❌ | ❌ |
 | Async/Await | ❌ | ✅ Native | ✅ Native | ✅ Native | ⚠️ (uasyncio) |
 | Type Safety | ✅ Strong | ⚠️ (TypeScript) | ⚠️ (TypeScript) | ✅ (Type hints) | ❌ |
-| Arrow IPC | ✅ Native | ✅ | ✅ | ✅ | ❌ |
+| Arrow IPC | ✅ Native | ✅ Native | ❌ (Browser incompatible) | ✅ Native | ❌ |
+| JSON Table | ✅ | ✅ | ✅ (Only table type) | ✅ | ⚠️ (Limited) |
 | Direct Transport | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Link Transport | ✅ | ✅ | ✅ | ✅ | ⚠️ (Limited) |
 | Handler Functions | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -72,8 +73,9 @@ NATSBridge enables seamless communication across multiple platforms through NATS
 - ✅ **Bi-directional messaging** with request-reply patterns
 - ✅ **Multi-payload support** - send multiple payloads with different types in one message
 - ✅ **Automatic transport selection** - direct vs link based on payload size
-- ✅ **Claim-Check pattern** for payloads > 1MB
+- ✅ **Claim-Check pattern** for payloads ≥ 500KB
-- ✅ **Apache Arrow IPC** support for tabular data (zero-copy reading)
+- ✅ **Apache Arrow IPC** support for tabular data (Desktop: Julia/Python/Node.js)
+- ✅ **JSON Table** support for tabular data (All platforms including Browser)
 - ✅ **Exponential backoff** for reliable file server downloads
 - ✅ **Correlation ID tracking** for message tracing
 - ✅ **Reply-to support** for request-response patterns
@@ -83,23 +85,24 @@ NATSBridge enables seamless communication across multiple platforms through NATS
 
 ## Quick Start
 
-### Step 1: Start NATS Server
+### Prerequisites
 
-```bash
+1. **NATS Server** - Install and run a NATS server:
-docker run -p 4222:4222 nats:latest
+   ```bash
-```
+   docker run -p 4222:4222 nats:latest
+   ```
 
-### Step 2: Start HTTP File Server (Optional)
+2. **HTTP File Server** (optional, for large payloads) - Install and run a file server:
+   ```bash
+   # Using Plik
+   docker run -p 8080:8080 -v /tmp/fileserver:/var/lib/plik -e PLIK_ADMIN_PASSWORD=admin plik/plik
    
-```bash
+   # OR using simple Python HTTP server
-# Create a directory for file uploads
+   mkdir -p /tmp/fileserver
-mkdir -p /tmp/fileserver
+   python3 -m http.server 8080 --directory /tmp/fileserver
+   ```
 
-# Start HTTP file server
+### Send Your First Message
-python3 -m http.server 8080 --directory /tmp/fileserver
-```
-
-### Step 3: Send Your First Message
 
 #### Julia
 
@@ -107,14 +110,14 @@ python3 -m http.server 8080 --directory /tmp/fileserver
 using NATSBridge
 
 data = [("message", "Hello World", "text")]
-env, env_json_str = smartsend("/chat/room1", data, broker_url="nats://localhost:4222")
+env, env_json_str = smartsend("/chat/room1", data; broker_url="nats://localhost:4222")
 println("Message sent!")
 ```
 
-#### JavaScript
+#### JavaScript (Node.js)
 
 ```javascript
-const NATSBridge = require('./src/natsbridge.js');
+import NATSBridge from './src/natsbridge_ssr.js';
 
 const data = [["message", "Hello World", "text"]];
 const [env, env_json_str] = await NATSBridge.smartsend(
@@ -125,6 +128,20 @@ const [env, env_json_str] = await NATSBridge.smartsend(
 console.log("Message sent!");
 ```
 
+#### JavaScript (Browser)
+
+```javascript
+import NATSBridge from './src/natsbridge_csr.js';
+
+const data = [["message", "Hello World", "text"]];
+const [env, env_json_str] = await NATSBridge.smartsend(
+    "/chat/room1",
+    data,
+    { broker_url: "ws://localhost:4222" }
+);
+console.log("Message sent!");
+```
+
 #### Python
 
 ```python
@@ -139,6 +156,21 @@ env, env_json_str = await smartsend(
 print("Message sent!")
 ```
 
+#### MicroPython
+
+```python
+from natsbridge import smartsend
+
+data = [("message", "Hello World", "text")]
+env, env_json_str = smartsend(
+    "/chat/room1",
+    data,
+    broker_url="nats://localhost:4222",
+    size_threshold=100000  # 100KB for MicroPython
+)
+print("Message sent!")
+```
+
 ---
 
 ## API Reference
@@ -147,13 +179,13 @@ print("Message sent!")
 
 All platforms use the same input/output format for payloads:
 
-**Input format for smartsend:**
+**Input format for `smartsend`:**
 ```
 [(dataname1, data1, type1), (dataname2, data2, type2), ...]
 ```
 
-**Output format for smartreceive:**
+**Output format for `smartreceive`:**
-```
+```json
 {
   "correlation_id": "...",
   "msg_id": "...",
@@ -187,7 +219,7 @@ env, env_json_str = NATSBridge.smartsend(
     broker_url::String = "nats://localhost:4222",
     fileserver_url = "http://localhost:8080",
     fileserver_upload_handler::Function = plik_oneshot_upload,
-    size_threshold::Int = 1_000_000,
+    size_threshold::Int = 500_000,
     correlation_id::String = string(uuid4()),
     msg_purpose::String = "chat",
     sender_name::String = "NATSBridge",
@@ -203,10 +235,10 @@ env, env_json_str = NATSBridge.smartsend(
 # Returns: ::Tuple{msg_envelope_v1, String}
 ```
 
-#### JavaScript
+#### JavaScript (Node.js)
 
 ```javascript
-const NATSBridge = require('natsbridge');
+import NATSBridge from './src/natsbridge_ssr.js';
 
 const [env, env_json_str] = await NATSBridge.smartsend(
     subject,
@@ -215,7 +247,36 @@ const [env, env_json_str] = await NATSBridge.smartsend(
         broker_url: 'nats://localhost:4222',
         fileserver_url: 'http://localhost:8080',
         fileserver_upload_handler: NATSBridge.plikOneshotUpload,
-        size_threshold: 1_000_000,
+        size_threshold: 500_000,
+        correlation_id: uuidv4(),
+        msg_purpose: 'chat',
+        sender_name: 'NATSBridge',
+        receiver_name: '',
+        receiver_id: '',
+        reply_to: '',
+        reply_to_msg_id: '',
+        is_publish: true,
+        nats_connection: null,
+        msg_id: uuidv4(),
+        sender_id: uuidv4()
+    }
+);
+// Returns: Promise<[env, env_json_str]>
+```
+
+#### JavaScript (Browser)
+
+```javascript
+import NATSBridge from './src/natsbridge_csr.js';
+
+const [env, env_json_str] = await NATSBridge.smartsend(
+    subject,
+    data,
+    {
+        broker_url: 'ws://localhost:4222',
+        fileserver_url: 'http://localhost:8080',
+        fileserver_upload_handler: NATSBridge.plikOneshotUpload,
+        size_threshold: 500_000,
         correlation_id: uuidv4(),
         msg_purpose: 'chat',
         sender_name: 'NATSBridge',
@@ -243,7 +304,7 @@ env, env_json_str = await NATSBridge.smartsend(
     broker_url: str = "nats://localhost:4222",
     fileserver_url: str = "http://localhost:8080",
     fileserver_upload_handler: Callable = plik_oneshot_upload,
-    size_threshold: int = 1_000_000,
+    size_threshold: int = 500_000,
     correlation_id: str = None,
     msg_purpose: str = "chat",
     sender_name: str = "NATSBridge",
@@ -293,9 +354,28 @@ env = NATSBridge.smartreceive(
 # Returns: ::JSON.Object{String, Any}
 ```
 
-#### JavaScript
+#### JavaScript (Node.js)
 
 ```javascript
+import NATSBridge from './src/natsbridge_ssr.js';
+
+const env = await NATSBridge.smartreceive(
+    msg,
+    {
+        fileserver_download_handler: NATSBridge.fetchWithBackoff,
+        max_retries: 5,
+        base_delay: 100,
+        max_delay: 5000
+    }
+);
+// Returns: Promise<env_object>
+```
+
+#### JavaScript (Browser)
+
+```javascript
+import NATSBridge from './src/natsbridge_csr.js';
+
 const env = await NATSBridge.smartreceive(
     msg,
     {
@@ -311,6 +391,8 @@ const env = await NATSBridge.smartreceive(
 #### Python
 
 ```python
+from natsbridge import NATSBridge
+
 env = await NATSBridge.smartreceive(
     msg,
     fileserver_download_handler=fetch_with_backoff,
@@ -324,6 +406,8 @@ env = await NATSBridge.smartreceive(
 #### MicroPython
 
 ```python
+from natsbridge import NATSBridge
+
 env = NATSBridge.smartreceive(
     msg,
     fileserver_download_handler=_sync_fileserver_download,
@@ -342,8 +426,8 @@ env = NATSBridge.smartreceive(
 |------|-------|------------|--------|-------------|-------------|
 | `text` | `String` | `string` | `str` | `str` | Plain text strings |
 | `dictionary` | `Dict`, `NamedTuple` | `Object`, `Array` | `dict`, `list` | `dict` | JSON-serializable dictionaries |
-| `arrowtable` | `DataFrame`, `Arrow.Table` | `Array<Object>` | `pandas.DataFrame` | ❌ | Tabular data (Arrow IPC) |
+| `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser), ✅ (Node.js) | `pandas.DataFrame` | ❌ | Tabular data (Arrow IPC) |
-| `jsontable` | `Vector{NamedTuple}` | `Array<Object>` | `list[dict]` | ❌ | Tabular data (JSON) |
+| `jsontable` | `DataFrame`, `Vector{NamedTuple}` | `Array<Object>` | `list[dict]` | ⚠️ | Tabular data (JSON) - **Only table type in Browser** |
 | `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Image data (PNG, JPG) |
 | `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Audio data (WAV, MP3) |
 | `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Video data (MP4, AVI) |
@@ -368,13 +452,13 @@ data = [
     ("large_document", large_file_data, "binary")
 ]
 
-env, env_json_str = NATSBridge.smartsend("/chat/room1", data; fileserver_url="http://localhost:8080")
+env, env_json_str = smartsend("/chat/room1", data; fileserver_url="http://localhost:8080")
 ```
 
-#### JavaScript
+#### JavaScript (Node.js)
 
 ```javascript
-const NATSBridge = require('natsbridge');
+import NATSBridge from './src/natsbridge_ssr.js';
 
 const data = [
     ["message_text", "Hello!", "text"],
@@ -389,6 +473,24 @@ const [env, env_json_str] = await NATSBridge.smartsend(
 );
 ```
 
+#### JavaScript (Browser)
+
+```javascript
+import NATSBridge from './src/natsbridge_csr.js';
+
+const data = [
+    ["message_text", "Hello!", "text"],
+    ["user_avatar", imageData, "image"],
+    ["large_document", largeFileData, "binary"]
+];
+
+const [env, env_json_str] = await NATSBridge.smartsend(
+    "/chat/room1",
+    data,
+    { broker_url: 'ws://localhost:4222', fileserver_url: 'http://localhost:8080' }
+);
+```
+
 #### Python
 
 ```python
@@ -423,13 +525,13 @@ config = Dict(
 )
 
 data = [("config", config, "dictionary")]
-env, env_json_str = NATSBridge.smartsend("/device/config", data)
+env, env_json_str = smartsend("/device/config", data)
 ```
 
-#### JavaScript
+#### JavaScript (Node.js)
 
 ```javascript
-const NATSBridge = require('natsbridge');
+import NATSBridge from './src/natsbridge_ssr.js';
 
 const config = {
     wifi_ssid: "MyNetwork",
@@ -475,13 +577,13 @@ df = DataFrame(
 )
 
 data = [("students", df, "arrowtable")]
-env, env_json_str = NATSBridge.smartsend("/data/analysis", data)
+env, env_json_str = smartsend("/data/analysis", data)
 ```
 
-#### JavaScript
+#### JavaScript (Node.js)
 
 ```javascript
-const NATSBridge = require('natsbridge');
+import NATSBridge from './src/natsbridge_ssr.js';
 
 const df = [
     { id: 1, name: "Alice", score: 95 },
@@ -511,6 +613,26 @@ data = [("students", df, "arrowtable")]
 env, env_json_str = await NATSBridge.smartsend("/data/analysis", data)
 ```
 
+#### JavaScript (Browser)
+
+```javascript
+import NATSBridge from './src/natsbridge_csr.js';
+
+// Browser uses jsontable (JSON array of objects) instead of arrowtable
+// Apache Arrow is not compatible with browsers
+const df = [
+    { id: 1, name: "Alice", score: 95 },
+    { id: 2, name: "Bob", score: 88 },
+    { id: 3, name: "Charlie", score: 92 }
+];
+
+const [env, env_json_str] = await NATSBridge.smartsend(
+    "/data/analysis",
+    [["students", df, "jsontable"]],  // Use jsontable for browser
+    { broker_url: 'ws://localhost:4222' }
+);
+```
+
 ### Example 4: Request-Response Pattern
 
 Bi-directional communication with reply-to support.
@@ -521,18 +643,29 @@ Bi-directional communication with reply-to support.
 using NATSBridge
 
 # Requester
-env, env_json_str = NATSBridge.smartsend(
+env, env_json_str = smartsend(
     "/device/command",
     [("command", Dict("action" => "read_sensor"), "dictionary")];
     broker_url="nats://localhost:4222",
     reply_to="/device/response"
 )
+
+# Receiver (in separate application)
+msg = NATS.subscription.next()
+env = smartreceive(msg)
+# Process request and send response
+response_env, response_json = smartsend(
+    "/device/response",
+    [("result", Dict("value" => 42), "dictionary")],
+    reply_to="/device/command",
+    reply_to_msg_id=env["msg_id"]
+)
 ```
 
-#### JavaScript
+#### JavaScript (Node.js)
 
 ```javascript
-const NATSBridge = require('natsbridge');
+import NATSBridge from './src/natsbridge_ssr.js';
 
 // Requester
 const [env, env_json_str] = await NATSBridge.smartsend(
@@ -540,6 +673,16 @@ const [env, env_json_str] = await NATSBridge.smartsend(
     [["command", { action: "read_sensor" }, "dictionary"]],
     { broker_url: 'nats://localhost:4222', reply_to: '/device/response' }
 );
+
+// Receiver (in separate application)
+// const msg = await natsConsumer.next();
+// const env = await NATSBridge.smartreceive(msg);
+// Process request and send response
+// const response_env, response_json = await NATSBridge.smartsend(
+//     "/device/response",
+//     [["result", { value: 42 }, "dictionary"]],
+//     { reply_to: '/device/command', reply_to_msg_id: env.msg_id }
+// );
 ```
 
 #### Python
@@ -554,6 +697,17 @@ env, env_json_str = await NATSBridge.smartsend(
     broker_url="nats://localhost:4222",
     reply_to="/device/response"
 )
+
+# Receiver (in separate application)
+# msg = await nats_consumer.next()
+# env = await NATSBridge.smartreceive(msg)
+# Process request and send response
+# response_env, response_json = await NATSBridge.smartsend(
+#     "/device/response",
+#     [("result", {"value": 42}, "dictionary")],
+#     reply_to="/device/command",
+#     reply_to_msg_id=env["msg_id"]
+# )
 ```
 
 ---
@@ -636,14 +790,131 @@ python3 test/test_py_table_receiver.py
 
 ---
 
+## Browser Deployment
+
+### Using with Node.js Build Tools
+
+The browser implementation (`src/natsbridge_csr.js`) can be bundled for production deployment using modern JavaScript build tools.
+
+#### Prerequisites
+
+```bash
+# Install the browser-compatible NATS client
+npm install nats.ws
+```
+
+#### Vite (Recommended)
+
+```bash
+npm create vite@latest my-app -- --template vanilla
+cd my-app
+npm install nats.ws
+```
+
+In `vite.config.js`:
+```javascript
+import { defineConfig } from 'vite';
+export default defineConfig({
+  resolve: {
+    alias: {
+      'nats.ws': 'nats.ws/dist/esm/browser.js'
+    }
+  }
+});
+```
+
+Build command:
+```bash
+npm run build  # Outputs to dist/ folder
+```
+
+#### Webpack
+
+```bash
+npm install webpack webpack-cli --save-dev
+npm install nats.ws
+```
+
+In `webpack.config.js`:
+```javascript
+module.exports = {
+  entry: './src/index.js',
+  output: {
+    filename: 'bundle.js',
+    path: __dirname + '/dist'
+  },
+  resolve: {
+    alias: {
+      'nats.ws': 'nats.ws/dist/esm/browser.js'
+    }
+  }
+};
+```
+
+Build command:
+```bash
+npx webpack
+```
+
+#### esbuild (Simple & Fast)
+
+```bash
+npm install esbuild nats.ws --save-dev
+```
+
+Create `build.js`:
+```javascript
+import esbuild from 'esbuild';
+
+esbuild.buildSync({
+  entryPoints: ['src/natsbridge_csr.js'],
+  bundle: true,
+  outfile: 'dist/natsbridge-csr-bundle.js',
+  format: 'esm',
+  platform: 'browser',
+  target: 'es2020'
+});
+```
+
+Build command:
+```bash
+node build.js
+```
+
+### Using in Your HTML
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My App</title>
+</head>
+<body>
+  <script type="module" src="dist/natsbridge-csr-bundle.js"></script>
+  <script type="module">
+    import NATSBridgeCSR from './dist/natsbridge-csr-bundle.js';
+    
+    // Use the library
+    const [env, envJson] = await NATSBridgeCSR.smartsend(
+      "/chat/user/v1/message",
+      [["msg", "Hello", "text"]],
+      { broker_url: "wss://nats.example.com" }
+    );
+  </script>
+</body>
+</html>
+```
+
+---
+
 ## Documentation
 
 For detailed architecture and implementation information, see:
 
-- [Architecture Documentation](docs/architecture_updated.md) - Cross-platform architecture, API parity, platform-specific patterns
+- [`docs/architecture.md`](docs/architecture.md) - Cross-platform architecture, API parity, platform-specific patterns
-- [Implementation Guide](docs/implementation_updated.md) - Detailed implementation for each platform, handler functions, testing
+- [`docs/requirements.md`](docs/requirements.md) - Business requirements and user stories
-- [Tutorial](docs/tutorial_updated.md) - Step-by-step getting started guide
+- [`docs/spec.md`](docs/spec.md) - Technical specification and contracts
-- [Walkthrough](docs/walkthrough_updated.md) - Real-world application building guides
+- [`docs/walkthrough.md`](docs/walkthrough.md) - Real-world application building guides
 
 ---
 

docs/SDD_FRAMEWORK.md

@@ -0,0 +1,402 @@
+# SDD + GitOps Documentation Framework
+
+This document defines the documentation framework for the NATSBridge project. It establishes a structured approach to creating, maintaining, and evolving technical documentation in alignment with GitOps principles—ensuring that documentation is versioned, auditable, and continuously validated alongside the codebase.
+
+---
+
+## The SDD Framework: Seven Pillars of Documentation
+
+| Document | Purpose (Rationale) | Primary Audience | Format / Content | Example (SaaS Context) | Measurement (KPI) |
+|----------|---------------------|-----------------|------------------|------------------------|-------------------|
+| **Requirements** | Capture the **business intent** — why we're building this and what success looks like. Defines boundaries and user-visible outcomes. | Stakeholders, Product Owners, Lead Developers | User stories, PRDs, acceptance criteria, non-functional constraints. | "System must process tabular data from Julia to SvelteKit UI with <200ms latency for 5-member teams." | 95% of requests complete <200ms (synthetic monitoring). |
+| **Specification** | The **technical contract** — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test. | Developers, QA Engineers, CI/CD pipelines | OpenAPI, Protobuf, AsyncAPI. Endpoint definitions, schemas, error codes. | `contract.yaml` defining a NATS subject that accepts Arrow streams with snake_case headers. | 100% of messages validated against spec (CI block rate). |
+| **Architecture** | The **blueprint** — how components fit together, interact, and scale. Guides system structure and trade-offs. | Architects, Senior Developers, DevOps | C4 diagrams, Mermaid.js, component/network/storage models. | Diagram showing 6-node cluster routing traffic via Caddy → Node.js API → Julia pods. | 100% of major decisions logged with trade-off analysis. |
+| **Walkthrough** | The **story of flow** — shows how pieces connect end-to-end and why steps are sequenced. Builds intuition for new devs. | New Developers, Team Members | TOUR.md, Loom videos, sequence diagrams. Step-by-step traces with rationale. | "UI sends JSON → Node.js wraps Claim-Check → Julia pulls Arrow data (prevents NATS overflow)." | New developers ship feature in <2 days (PR timeline). |
+| **Implementation** | The **real code** — business logic, helpers, tests, configs. Where design becomes executable. | Developers, Code Reviewers | Source code, README.md, unit tests, setup scripts. | Julia function for matrix calculation + SvelteKit component rendering table. | >80% unit test coverage, <5% drift from spec. |
+| **Validation** | The **enforcer** — ensures implementation matches the spec. Blocks drift and human error. | Automation servers, QA, Lead Developers | CI jobs, contract tests, linting, integration checks. | CI job rejects PR with camelCase field not allowed by YAML spec. | <1% of PRs bypass validation gates. |
+| **Runbook** | The **operational manual** — how the system lives in production, scales, and recovers. Guides on-call engineers. | DevOps, SREs, On-call Developers | K8s manifests, Helm charts, Markdown guides. Deployment, scaling, backup/restore, troubleshooting. | GitOps manifest ensuring 6 Julia replicas restart if memory >80%. | MTTR <15 minutes for P1 incidents. |
+
+---
+
+## Detailed Document Descriptions
+
+### 1. Requirements
+
+**Purpose**: Capture the *business intent* — why we're building this and what success looks like. Defines boundaries and user-visible outcomes.
+
+**Why It Matters**:
+- Aligns engineering efforts with business goals
+- Provides a north star for feature development
+- Establishes acceptance criteria before implementation begins
+- Creates a contract between product and engineering
+
+**Content Guidelines**:
+- User stories with clear acceptance criteria (As a X, I want Y so that Z)
+- Product Requirements Documents (PRDs) with success metrics
+- Non-functional requirements (performance, security, scalability)
+- Boundary definitions (what's in scope vs. out of scope)
+
+**Best Practices**:
+- Link each requirement to a measurable KPI
+- Keep requirements testable and verifiable
+- Maintain backward compatibility with existing requirements
+- Review and update requirements as business context changes
+
+---
+
+### 2. Specification
+
+**Purpose**: The *technical contract* — precise rules for inputs, outputs, and data shape. Ensures consistency across dev and test.
+
+**Why It Matters**:
+- Prevents implementation drift between components
+- Enables contract testing in CI/CD pipelines
+- Provides a single source of truth for data structures
+- Facilitates integration between teams
+
+**Content Guidelines**:
+- API endpoint definitions (methods, paths, parameters)
+- Request/response schemas (JSON, XML, Protobuf, AsyncAPI)
+- Error codes and their meanings
+- Data validation rules and constraints
+- Rate limiting and quota definitions
+
+**Best Practices**:
+- Use formal specification languages (OpenAPI 3.0+, AsyncAPI)
+- Version specifications alongside code
+- Generate client SDKs from specifications
+- Block CI on specification violations
+- Document edge cases and error scenarios
+
+---
+
+### 3. Architecture
+
+**Purpose**: The *blueprint* — how components fit together, interact, and scale. Guides system structure and trade-offs.
+
+**Why It Matters**:
+- Provides a mental model for system design
+- Guides technical decision-making and trade-off analysis
+- Facilitates onboarding of new architects and senior developers
+- Documents scaling and performance considerations
+
+**Content Guidelines**:
+- C4 diagrams (Context, Container, Component levels)
+- Mermaid.js flowcharts for sequence diagrams
+- Component interaction diagrams
+- Network topology and data flow
+- Storage and caching strategies
+- Scaling and resilience patterns
+
+**Best Practices**:
+- Use diagrams that are easy to update (Mermaid.js over static images)
+- Document trade-off decisions with Rationale Documents
+- Include scaling considerations for each component
+- Document failure modes and recovery strategies
+- Keep architecture diagrams versioned with code
+
+---
+
+### 4. Walkthrough
+
+**Purpose**: The *story of flow* — shows how pieces connect end-to-end and why steps are sequenced. Builds intuition for new devs.
+
+**Why It Matters**:
+- Reduces onboarding time for new developers
+- Provides context that code comments alone cannot convey
+- Explains the "why" behind architectural decisions
+- Helps identify gaps in the system design
+
+**Content Guidelines**:
+- Step-by-step flow descriptions with rationale
+- Sequence diagrams showing request/response patterns
+- "Tour of the codebase" guides
+- Video walkthroughs (Loom, internal recordings)
+- Debugging and tracing examples
+
+**Best Practices**:
+- Walk through real user journeys, not just technical flows
+- Include "what could go wrong" scenarios
+- Link walkthroughs to relevant code locations
+- Keep walkthroughs updated with architecture changes
+- Make walkthroughs interactive where possible
+
+---
+
+### 5. Implementation
+
+**Purpose**: The *real code* — business logic, helpers, tests, configs. Where design becomes executable.
+
+**Why It Matters**:
+- This is the actual artifact that runs in production
+- Code is the ultimate source of truth (when it matches spec)
+- Tests validate correctness and prevent regressions
+- Configuration files define runtime behavior
+
+**Content Guidelines**:
+- Business logic implementation
+- Helper functions and utilities
+- Unit and integration tests
+- Configuration files (YAML, JSON, environment)
+- Setup and development scripts
+- Code organization and module structure
+
+**Best Practices**:
+- Follow consistent code style and conventions
+- Write tests before or alongside implementation (TDD/BDD)
+- Document complex logic with inline comments
+- Keep configuration externalized and versioned
+- Use type annotations where applicable
+
+---
+
+### 6. Validation
+
+**Purpose**: The *enforcer* — ensures implementation matches the spec. Blocks drift and human error.
+
+**Why It Matters**:
+- Prevents breaking changes from reaching production
+- Catches specification violations early in the CI pipeline
+- Maintains data integrity and API consistency
+- Reduces manual QA effort through automation
+
+**Content Guidelines**:
+- CI/CD pipeline configurations
+- Contract testing scripts
+- Linting rules and configurations
+- Integration test suites
+- Schema validation jobs
+- Security scanning and audit jobs
+
+**Best Practices**:
+- Fail CI on specification violations
+- Run validation jobs on every commit and PR
+- Use automated code review tools
+- Maintain validation job health dashboard
+- Document validation failure remediation steps
+
+---
+
+### 7. Runbook
+
+**Purpose**: The *operational manual* — how the system lives in production, scales, and recovers. Guides on-call engineers.
+
+**Why It Matters**:
+- Reduces Mean Time To Recovery (MTTR) for incidents
+- Provides step-by-step guidance for common issues
+- Documents scaling and deployment procedures
+- Ensures operational knowledge is not siloed
+
+**Content Guidelines**:
+- Deployment procedures (manual and automated)
+- Scaling instructions (horizontal/vertical)
+- Backup and restore procedures
+- Troubleshooting guides for common issues
+- Runbook entries for specific error codes
+- Contact information and escalation paths
+
+**Best Practices**:
+- Write runbooks for every P1/P2 incident
+- Include exact commands and configuration snippets
+- Test runbooks periodically (chaos engineering)
+- Link runbook entries to relevant documentation
+- Keep runbooks updated when system changes
+
+---
+
+## How to Use This Approach Effectively
+
+### 1. Start with Requirements
+
+Before writing any code or documentation, establish clear requirements. Ask:
+- What business problem are we solving?
+- How will we measure success?
+- What are the non-negotiable constraints?
+
+**Action**: Create a `docs/requirements/` directory and start with `PRD.md` and `KPIs.md`.
+
+### 2. Define the Specification First
+
+Once requirements are stable, define the technical specification. This becomes the contract for implementation.
+
+**Action**: Create `docs/specification/` with `contract.yaml` (or appropriate format) and `error-codes.md`.
+
+### 3. Design the Architecture
+
+With requirements and specification in place, design the architecture. Document trade-off decisions explicitly.
+
+**Action**: Create `docs/architecture/` with Mermaid diagrams and `trade-offs.md`.
+
+### 4. Create Walkthroughs Early
+
+As soon as the architecture is defined, create walkthroughs. This helps identify gaps and provides onboarding material.
+
+**Action**: Create `docs/walkthrough/` with `TOUR.md` and sequence diagrams.
+
+### 5. Implement with Validation in Mind
+
+Write implementation code that adheres to the specification. Build validation into the CI pipeline from day one.
+
+**Action**: Ensure test files are co-located with implementation and run on every commit.
+
+### 6. Automate Validation
+
+Build automated validation that runs in CI/CD. This ensures spec compliance and prevents drift.
+
+**Action**: Configure CI jobs to validate against specification and block PRs on violations.
+
+### 7. Document Operations from Day One
+
+Create runbook entries as soon as deployment procedures are established. Update them when incidents occur.
+
+**Action**: Create `docs/runbook/` with entries for deployment, scaling, and common issues.
+
+---
+
+## GitOps Integration
+
+This documentation framework aligns with GitOps principles:
+
+| GitOps Principle | Documentation Alignment |
+|-----------------|------------------------|
+| **Versioned** | All documentation lives in git, with history and audit trail |
+| ** declarative** | Specifications and architecture are declarative contracts |
+| **Automated** | Validation jobs automate spec compliance checks |
+| **Self-Service** | Walkthroughs and runbooks enable self-service onboarding and operations |
+| **Observability** | KPIs and metrics are defined for each documentation artifact |
+
+**Git Structure**:
+```
+docs/
+├── requirements/       # PRDs, user stories, KPIs
+├── specification/      # OpenAPI, Protobuf, AsyncAPI specs
+├── architecture/       # C4 diagrams, Mermaid, trade-off docs
+├── walkthrough/        # TOUR.md, sequence diagrams
+├── implementation/     # Source code (in src/)
+├── validation/         # CI configs, test suites
+└── runbook/            # Deployment, scaling, troubleshooting
+```
+
+---
+
+## Metrics and Continuous Improvement
+
+Each documentation artifact has associated KPIs. Track these to ensure quality:
+
+| Document | KPI | Target |
+|----------|-----|--------|
+| Requirements | Requirement coverage | 100% of features have associated requirements |
+| Specification | Spec compliance rate | 100% of messages validate against spec |
+| Architecture | Decision documentation | 100% of major decisions logged with trade-offs |
+| Walkthrough | New dev time-to-first-PR | <2 days from onboarding to first contribution |
+| Implementation | Test coverage | >80% unit test coverage |
+| Validation | Bypass rate | <1% of PRs bypass validation gates |
+| Runbook | MTTR | <15 minutes for P1 incidents |
+
+**Review Cadence**:
+- Weekly: Review KPI dashboards and documentation gaps
+- Monthly: Update documentation based on incident learnings
+- Quarterly: Full framework review and improvement
+
+---
+
+## Template Examples
+
+### Requirements Template
+```markdown
+# PRD: Feature Name
+
+## Business Goal
+[What problem are we solving?]
+
+## Success Metrics
+- [Metric 1]: Target [value]
+- [Metric 2]: Target [value]
+
+## User Stories
+- As a [role], I want [feature] so that [benefit]
+  - Acceptance Criteria: [details]
+
+## Non-Functional Requirements
+- Performance: [details]
+- Security: [details]
+- Scalability: [details]
+
+## Out of Scope
+- [What's explicitly excluded]
+```
+
+### Specification Template
+```yaml
+# contract.yaml
+openapi: 3.0.0
+info:
+  title: NATSBridge API
+  version: 1.0.0
+paths:
+  /api/v1/endpoint:
+    post:
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Response'
+```
+
+### Architecture Template
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#3b82f6'}}}%%
+flowchart TD
+    A[Client] --> B[Caddy]
+    B --> C[Node.js API]
+    C --> D[Julia Worker]
+    D --> E[NATS Cluster]
+    E --> F[Storage]
+    
+    style A fill:#f9f9f9,stroke:#333
+    style E fill:#e0e7ff,stroke:#3b82f6
+```
+
+### Runbook Template
+```markdown
+# Runbook: Service Restart
+
+**Severity**: P2
+**Estimated Time**: 5 minutes
+
+## Symptoms
+- Service is unresponsive
+- Health checks are failing
+
+## Steps
+1. SSH to the host
+2. Run: `kubectl rollout restart deployment/natsbridge`
+3. Monitor: `kubectl get pods -l app=natsbridge -w`
+
+## Rollback
+- Run: `kubectl rollout undo deployment/natsbridge`
+
+## Post-Incident
+- [ ] Review logs for root cause
+- [ ] Update runbook if needed
+```
+
+---
+
+## Conclusion
+
+This SDD + GitOps Documentation Framework ensures that documentation is:
+- **Structured**: Seven distinct artifacts with clear purposes
+- **Automated**: Validation and CI/CD integration
+- **Versioned**: All documentation in git with history
+- **Measurable**: KPIs for quality and effectiveness
+- **Actionable**: Practical templates and examples
+
+Use this framework as a living document—update it as your team's needs evolve.

docs/requirements.md

@@ -0,0 +1,423 @@
+# Requirements Document: NATSBridge
+
+**Version**: 1.0.0  
+**Date**: 2026-03-13  
+**Status**: Active  
+**Ground Truth**: [`src/NATSBridge.jl`](../src/NATSBridge.jl)
+
+---
+
+## Executive Summary
+
+NATSBridge is a cross-platform, bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, and **MicroPython** applications using NATS as the message bus. The system implements the **Claim-Check pattern** for efficient handling of large payloads (>0.5MB) by uploading them to an HTTP file server instead of sending raw binary data over NATS.
+
+---
+
+## Business Goals
+
+### Primary Objectives
+
+1. **Cross-Platform Interoperability**: Enable seamless data exchange between Julia, JavaScript (for both Server-Side rendering and Client-Side rendering webapp), Python, and MicroPython applications without platform-specific barriers.
+
+2. **Efficient Large Payload Handling**: Implement intelligent transport selection based on payload size:
+   - **Direct Transport**: Small payloads (<0.5MB) sent directly via NATS
+   - **Link Transport**: Large payloads (≥0.5MB) uploaded to HTTP file server, URL sent via NATS
+
+3. **Unified API Across Platforms**: Provide consistent `smartsend()` and `smartreceive()` functions across all supported platforms while maintaining idiomatic implementations.
+
+4. **Developer Productivity**: Reduce onboarding time and simplify integration through comprehensive documentation and test examples.
+
+### Success Metrics
+
+| Metric | Target | Measurement Method |
+|--------|--------|-------------------|
+| 95% of messages complete within 200ms | 95% | Synthetic monitoring |
+| <2 days from onboarding to first PR | 2 days | PR timeline tracking |
+| 100% of messages validate against spec | 100% | CI block rate |
+| >80% unit test coverage | 80% | Test coverage tools |
+| <1% of PRs bypass validation gates | 1% | CI gate analysis |
+| MTTR <15 minutes for P1 incidents | 15 minutes | Incident tracking |
+
+---
+
+## User Stories
+
+### Core Functionality
+
+| Story | Priority | Acceptance Criteria |
+|-------|----------|---------------------|
+| **As a Julia developer**, I want to send text messages to JavaScript applications that lives on a server and also on a browser  | P1 | Text messages are serialized, encoded, and received correctly across platforms |
+| **As a Python developer**, I want to send tabular data to Julia applications | P1 | DataFrame exchange works with both Arrow IPC and JSON formats |
+| **As a JavaScript developer**, I want to send large files (>0.5MB) from JavaScript applications that lives on a server and also on a browser to other applications | P1 | Large files are automatically uploaded to file server and URLs are sent via NATS |
+| **As a MicroPython developer**, I want to send sensor data with minimal memory usage | P1 | Direct transport works for payloads <100KB on memory-constrained devices |
+
+### Multi-Payload Support
+
+| Story | Priority | Acceptance Criteria |
+|-------|----------|---------------------|
+| **As a developer**, I want to send mixed-content messages (text + image + file) | P1 | NATSBridge accepts list of (dataname, data, type) tuples and handles each payload appropriately |
+| **As a developer**, I want to receive multi-payload messages | P1 | NATSBridge returns payloads as list of tuples with correct types preserved |
+
+### File Server Integration
+
+| Story | Priority | Acceptance Criteria |
+|-------|----------|---------------------|
+| **As a developer**, I want to use Plik as the file server | P2 | Plik one-shot upload mode is supported with upload ID and token handling |
+| **As a developer**, I want to use custom HTTP file servers | P2 | Handler function abstraction allows plugging in AWS S3 or custom implementations |
+
+### Reliability Features
+
+| Story | Priority | Acceptance Criteria |
+|-------|----------|---------------------|
+| **As a developer**, I want automatic retry on file server download failures | P1 | Exponential backoff with configurable retries (default: 5, base_delay: 100ms, max_delay: 5000ms) |
+| **As a developer**, I want message tracing across distributed systems | P1 | Correlation ID is propagated through all message processing steps |
+
+---
+
+## Non-Functional Requirements
+
+### Performance Requirements
+
+| Requirement | Specification | Test Method |
+|-------------|---------------|-------------|
+| Message serialization overhead | <50ms for 10KB payload | Benchmark tests |
+| Message deserialization overhead | <50ms for 10KB payload | Benchmark tests |
+| NATS connection establishment | <100ms | Connection pool benchmarks |
+| File upload latency | <1s for 0.5MB file | Integration tests |
+| File download latency | <1s for 0.5MB file | Integration tests |
+
+### Scalability Requirements
+
+| Requirement | Specification |
+|-------------|---------------|
+| Concurrent connections | Support 100+ simultaneous NATS connections |
+| Message throughput | Handle 1000+ messages/second per instance |
+| File server scalability | Support horizontal scaling of file server backend |
+
+### Reliability Requirements
+
+| Requirement | Specification |
+|-------------|---------------|
+| Message delivery | At-least-once delivery semantics via NATS |
+| File server availability | Graceful degradation when file server is unavailable |
+| Connection recovery | Auto-reconnect on NATS connection failure |
+
+### Security Requirements
+
+| Requirement | Specification |
+|-------------|---------------|
+| Payload integrity | SHA-256 checksum support via metadata |
+| Transport security | TLS support for NATS connections |
+| File server security | Authentication token for file uploads |
+
+### Compatibility Requirements
+
+| Platform | Minimum Version | Notes |
+|----------|-----------------|-------|
+| Julia | 1.7+ | Arrow.jl required for arrowtable support |
+| Node.js | 16+ | nats.js required, Arrow IPC supported |
+| Python | 3.8+ | pyarrow required for arrowtable support |
+| Browser | Latest | No Arrow IPC (uses jsontable only) |
+| MicroPython | 1.19+ | Limited to direct transport |
+
+---
+
+## Out of Scope
+
+### Phase 1 (Current Implementation)
+
+| Feature | Reason |
+|---------|--------|
+| NATS JetStream support | Core NATS sufficient for current use cases |
+| Message compression | Compression adds complexity without clear benefit |
+| Message encryption | Payload encryption is application-layer concern |
+| Persistent message queues | NATS request-reply pattern sufficient |
+| Advanced routing rules | Simple NATS subject matching sufficient |
+
+### Future Considerations
+
+| Feature | Future Phase |
+|---------|--------------|
+| JetStream streams and consumers | Phase 2 |
+| Message TTL and dead-letter queues | Phase 3 |
+| Message tracing with OpenTelemetry | Phase 3 |
+| Rate limiting and quota management | Phase 4 |
+
+---
+
+## Boundary Definitions
+
+### What NATSBridge Handles
+
+| Function | Description |
+|----------|-------------|
+| Message serialization | Converts data types to binary format |
+| Message encoding | Base64, JSON, Arrow IPC encoding |
+| Transport selection | Direct vs link based on size threshold |
+| NATS publishing | Publishes messages to NATS subjects |
+| NATS subscription | Receives and processes NATS messages |
+| File server upload | Uploads large payloads to HTTP server |
+| File server download | Downloads payloads from HTTP server with retry |
+| Correlation ID generation | Creates and propagates UUIDs |
+| Data deserialization | Converts binary format back to native types |
+
+### What NATSBridge Does NOT Handle
+
+| Function | Handled By |
+|----------|------------|
+| NATS server management | External NATS deployment |
+| File server management | External HTTP server deployment |
+| Application business logic | Application code using NATSBridge |
+| Message encryption | Application layer |
+| Message compression | Application layer |
+| Authentication/Authorization | NATS server configuration |
+
+---
+
+## Payload Type Requirements
+
+### Supported Payload Types
+
+| Type | Julia | JavaScript | Python | MicroPython | Description |
+|------|-------|------------|--------|-------------|-------------|
+| `text` | `String` | `string` | `str` | `str` | Plain text strings |
+| `dictionary` | `Dict`, `NamedTuple` | `Object`, `Array` | `dict`, `list` | `dict` | JSON-serializable data |
+| `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser), ✅ (Node.js) | `pandas.DataFrame` | ❌ | Tabular data (Arrow IPC) |
+| `jsontable` | `Vector{NamedTuple}` | `Array<Object>` | `list[dict]` | ⚠️ | Tabular data (JSON) - **Only table type in Browser** |
+| `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Image binary data |
+| `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Audio binary data |
+| `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytearray` | Video binary data |
+| `binary` | `Vector{UInt8}`, `IOBuffer` | `Uint8Array`, `Buffer` | `bytes`, `bytearray` | `bytearray` | Generic binary data |
+
+### Encoding Requirements
+
+| Payload Type | Encoding Method | Notes |
+|--------------|-----------------|-------|
+| `text` | UTF-8 → Base64 | Text must be String type |
+| `dictionary` | JSON → Base64 | JSON.jl for Julia |
+| `arrowtable` | Arrow IPC → Base64 | Requires Arrow.jl/pyarrow (Desktop only) |
+| `jsontable` | JSON → Base64 | Human-readable format - **Browser uses this only** |
+| `image`/`audio`/`video`/`binary` | Direct → Base64 | Binary data preserved |
+
+---
+
+## Size Threshold Requirements
+
+### Direct Transport Threshold
+
+| Platform | Threshold | Notes |
+|----------|-----------|-------|
+| Desktop (Julia/JS/Python) | 0.5MB | Default size threshold |
+| MicroPython | 100KB | Lower threshold for memory constraints |
+
+### Maximum Payload Size
+
+| Platform | Maximum | Notes |
+|----------|---------|-------|
+| Desktop | Unlimited | Limited by NATS server configuration |
+| MicroPython | 50KB | Hard limit due to 256KB-1MB memory |
+
+---
+
+## Message Envelope Requirements
+
+### Required Fields
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `correlation_id` | String (UUID) | Track message flow across systems |
+| `msg_id` | String (UUID) | Unique message identifier |
+| `timestamp` | String (ISO 8601) | Message publication timestamp |
+| `send_to` | String | NATS subject to publish to |
+| `msg_purpose` | String | ACK, NACK, updateStatus, shutdown, chat |
+| `sender_name` | String | Sender application name |
+| `sender_id` | String (UUID) | Sender unique identifier |
+| `receiver_name` | String | Receiver application name (empty = broadcast) |
+| `receiver_id` | String (UUID) | Receiver unique identifier (empty = broadcast) |
+| `reply_to` | String | Topic for reply messages |
+| `reply_to_msg_id` | String | Message ID being replied to |
+| `broker_url` | String | NATS server URL |
+| `metadata` | Dict | Message-level metadata |
+| `payloads` | Array | List of payload objects |
+
+### Payload Fields
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `id` | String (UUID) | Unique payload identifier |
+| `dataname` | String | Name of the payload |
+| `payload_type` | String | Type: text, dictionary, arrowtable, etc. |
+| `transport` | String | direct or link |
+| `encoding` | String | none, json, base64, arrow-ipc |
+| `size` | Integer | Payload size in bytes |
+| `data` | Any | Base64 string or URL |
+| `metadata` | Dict | Payload-level metadata |
+
+---
+
+## Error Handling Requirements
+
+### Error Codes
+
+| Error | Condition | Response |
+|-------|-----------|----------|
+| `Unknown payload_type` | Unsupported type | Throw error |
+| `Failed to upload` | File server error | Throw error |
+| `Failed to fetch` | File server unavailable | Retry with exponential backoff |
+| `Unknown transport` | Invalid transport type | Throw error |
+| `NATS connection failed` | NATS unavailable | Throw error |
+
+### Exception Handling
+
+| Scenario | Handler |
+|----------|---------|
+| File server unavailable | Retry up to 5 times with exponential backoff |
+| NATS publish failure | Connection auto-reconnect |
+| Deserialization error | Log correlation ID and throw error |
+| Memory overflow (MicroPython) | Reject payloads >50KB |
+
+---
+
+## Testing Requirements
+
+### Unit Tests
+
+| Test Category | Coverage | Files |
+|---------------|----------|-------|
+| Serialization | All payload types | `test/test_*_sender.*` |
+| Deserialization | All payload types | `test/test_*_receiver.*` |
+| Transport selection | Direct vs link | `test/test_*_mix_payloads.*` |
+| File server upload | Plik integration | Platform-specific |
+| File server download | Exponential backoff | Platform-specific |
+
+### Integration Tests
+
+| Test Scenario | Success Criteria |
+|-------------|-----------------|
+| Cross-platform text message | Julia ↔ JavaScript ↔ Python |
+| Cross-platform tabular data (Desktop) | Arrow IPC round-trip |
+| Cross-platform tabular data (Browser) | JSON table round-trip |
+| Large file transfer | File server upload/download |
+| Multi-payload mixed content | All payload types in one message |
+
+---
+
+## API Contract
+
+### smartsend Signature
+
+```julia
+function smartsend(
+    subject::String,
+    data::AbstractArray{Tuple{String, Any, String}};
+    broker_url::String = "nats://localhost:4222",
+    fileserver_url::String = "http://localhost:8080",
+    fileserver_upload_handler::Function = plik_oneshot_upload,
+    size_threshold::Int = 1_000_000,
+    correlation_id::String = string(uuid4()),
+    msg_purpose::String = "chat",
+    sender_name::String = "NATSBridge",
+    receiver_name::String = "",
+    receiver_id::String = "",
+    reply_to::String = "",
+    reply_to_msg_id::String = "",
+    is_publish::Bool = true,
+    NATS_connection::Union{NATS.Connection, Nothing} = nothing,
+    msg_id::String = string(uuid4()),
+    sender_id::String = string(uuid4())
+)::Tuple{msg_envelope_v1, String}
+```
+
+### smartreceive Signature
+
+```julia
+function smartreceive(
+    msg::NATS.Msg;
+    fileserver_download_handler::Function = _fetch_with_backoff,
+    max_retries::Int = 5,
+    base_delay::Int = 100,
+    max_delay::Int = 5000
+)::JSON.Object{String, Any}
+```
+
+---
+
+## Dependencies
+
+### Required Dependencies
+
+| Platform | Package | Version |
+|----------|---------|---------|
+| Julia | NATS.jl | Latest stable |
+| Julia | JSON.jl | Latest stable |
+| Julia | Arrow.jl | Latest stable |
+| Julia | HTTP.jl | Latest stable |
+| Julia | UUIDs.jl | Latest stable |
+| Node.js | nats | Latest stable |
+| Node.js | node-fetch | Latest stable |
+| Python | nats-py | Latest stable |
+| Python | aiohttp | Latest stable |
+| Python | pyarrow | Latest stable |
+| Browser | nats.ws | Latest stable |
+
+### Optional Dependencies
+
+| Platform | Package | Use Case |
+|----------|---------|----------|
+| Julia | DataFrames.jl | DataFrame support for arrowtable |
+| Python | pandas | DataFrame support for arrowtable |
+
+---
+
+## Deployment Requirements
+
+### Minimum Infrastructure
+
+| Component | Minimum | Notes |
+|-----------|---------|-------|
+| NATS Server | 1 instance | Single node for development |
+| File Server | 1 instance | HTTP server for large payloads |
+| Client Memory | 50MB | Desktop platforms |
+| Client Memory | 256KB | MicroPython devices |
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NATS_URL` | `nats://localhost:4222` | NATS server URL |
+| `FILESERVER_URL` | `http://localhost:8080` | HTTP file server URL |
+| `SIZE_THRESHOLD` | `1000000` | Size threshold in bytes |
+
+---
+
+## Versioning
+
+### Current Version
+
+- **Major**: 1 (Breaking changes require major version bump)
+- **Minor**: 0 (Feature additions)
+- **Patch**: 0 (Bug fixes)
+
+### Version Compatibility
+
+| Version | Supported Platforms |
+|---------|---------------------|
+| v1.0.x | Julia 1.7+, Node.js 16+, Python 3.8+, Browser (latest), MicroPython 1.19+ |
+
+---
+
+## Change Log
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2026-03-13 | 1.0.0 | Initial requirements document |
+
+---
+
+## References
+
+- [`src/NATSBridge.jl`](../src/NATSBridge.jl) - Ground truth implementation
+- [`README.md`](../README.md) - Project overview
+- [`docs/architecture.md`](./architecture.md) - Architecture documentation
+- [`docs/implementation.md`](./implementation.md) - Implementation details
+- [`docs/walkthrough.md`](./walkthrough.md) - Usage examples

docs/tutorial.md

@@ -1,741 +0,0 @@
-# Cross-Platform NATSBridge Tutorial
-
-A step-by-step guide to get started with NATSBridge across **Julia**, **JavaScript**, and **Python/MicroPython**.
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Prerequisites](#prerequisites)
-3. [Installation](#installation)
-4. [Quick Start](#quick-start)
-5. [Basic Examples](#basic-examples)
-6. [Advanced Usage](#advanced-usage)
-
----
-
-## Overview
-
-NATSBridge enables seamless communication across platforms through NATS, with automatic transport selection based on payload size:
-
-- **Direct Transport**: Payloads < 1MB are sent directly via NATS (Base64 encoded)
-- **Link Transport**: Payloads >= 1MB are uploaded to an HTTP file server and referenced via URL
-
-### Cross-Platform API Parity
-
-All three platforms use the same high-level API:
-
-```
-# Input format
-smartsend(subject, [(dataname, data, type), ...], options)
-
-# Output format
-(env, env_json_str) = smartsend(...)
-env = smartreceive(msg, options)
-```
-
-**Important Platform Differences:**
-
-1. **Encoding field:** Julia and JavaScript preserve the original serialization format in the encoding field (`"base64"`, `"json"`, or `"arrow-ipc"`), while Python and MicroPython always use `"base64"` for all direct transport payloads.
-
-2. **Async vs Sync:** JavaScript and Python desktop use async/await, while MicroPython uses synchronous API.
-
-### Supported Payload Types
-
-| Type | Julia | JavaScript | Python | MicroPython |
-|------|-------|------------|--------|-------------|
-| `text` | `String` | `string` | `str` | `str` |
-| `dictionary` | `Dict` | `Object` | `dict` | `dict` |
-| `arrowtable` | `DataFrame` | `Array<Object>` | `pandas.DataFrame` | ❌ |
-| `jsontable` | `Vector{NamedTuple}` | `Array<Object>` | `list[dict]` | ❌ |
-| `table` | ❌ | ❌ | `pandas.DataFrame` | ❌ |
-| `image` | `Vector{UInt8}` | `Uint8Array` | `bytes` | `bytearray` |
-| `audio` | `Vector{UInt8}` | `Uint8Array` | `bytes` | `bytearray` |
-| `video` | `Vector{UInt8}` | `Uint8Array` | `bytes` | `bytearray` |
-| `binary` | `Vector{UInt8}` | `Uint8Array` | `bytes` | `bytearray` |
-
-**Note on MicroPython:** MicroPython does not support table types (`arrowtable`, `jsontable`, or `table`) due to memory constraints. Use `dictionary` or `binary` instead.
-
----
-
-## Prerequisites
-
-Before you begin, ensure you have:
-
-1. **NATS Server** running (or accessible)
-2. **HTTP File Server** (optional, for large payloads > 1MB)
-3. **Platform-specific packages** installed
-
----
-
-## Installation
-
-### Julia
-
-```julia
-using Pkg
-Pkg.add("NATS")
-Pkg.add("Arrow")
-Pkg.add("JSON3")
-Pkg.add("HTTP")
-Pkg.add("UUIDs")
-Pkg.add("Dates")
-```
-
-### JavaScript (Node.js)
-
-```bash
-npm install nats uuid apache-arrow node-fetch
-```
-
-### JavaScript (Browser)
-
-```html
-<script src="https://unpkg.com/nats-js/dist/bundle/nats.min.js"></script>
-<script src="https://unpkg.com/apache-arrow/arrow.min.js"></script>
-```
-
-### Python (Desktop)
-
-```bash
-pip install nats-py aiohttp pyarrow pandas
-```
-
-### MicroPython
-
-Uses built-in modules: `network`, `socket`, `time`, `json`, `base64`
-
----
-
-## Quick Start
-
-### Step 1: Start NATS Server
-
-```bash
-docker run -p 4222:4222 nats:latest
-```
-
-### Step 2: Start HTTP File Server (Optional)
-
-```bash
-mkdir -p /tmp/fileserver
-python3 -m http.server 8080 --directory /tmp/fileserver
-```
-
-### Step 3: Send Your First Message
-
-#### Julia
-
-```julia
-using NATSBridge
-
-# Send a text message
-data = [("message", "Hello World", "text")]
-env, env_json_str = smartsend("/chat/room1", data, broker_url="nats://localhost:4222")
-# env: msg_envelope_v1 struct with all metadata and payloads
-# env_json_str: JSON string representation of the envelope for publishing
-println("Message sent!")
-
-# Or use is_publish=false to get envelope and JSON without publishing
-env, env_json_str = smartsend("/chat/room1", data, broker_url="nats://localhost:4222", is_publish=false)
-# env: msg_envelope_v1 struct
-# env_json_str: JSON string for publishing to NATS
-```
-
-#### JavaScript
-
-```javascript
-const NATSBridge = require('./src/natsbridge.js');
-
-// Send a text message
-const data = [["message", "Hello World", "text"]];
-const [env, env_json_str] = await NATSBridge.smartsend(
-    "/chat/room1",
-    data,
-    { broker_url: "nats://localhost:4222" }
-);
-// env: Object with all metadata and payloads
-// env_json_str: JSON string for publishing
-console.log("Message sent!");
-
-// Or use is_publish=false
-const [env, env_json_str] = await NATSBridge.smartsend(
-    "/chat/room1",
-    data,
-    { broker_url: "nats://localhost:4222", is_publish: false }
-);
-```
-
-#### Python
-
-```python
-from natsbridge import smartsend
-
-# Send a text message
-data = [("message", "Hello World", "text")]
-env, env_json_str = await smartsend(
-    "/chat/room1",
-    data,
-    broker_url="nats://localhost:4222"
-)
-# env: Dict with all metadata and payloads
-# env_json_str: JSON string for publishing
-print("Message sent!")
-
-# Or use is_publish=False
-env, env_json_str = await smartsend(
-    "/chat/room1",
-    data,
-    broker_url="nats://localhost:4222",
-    is_publish=False
-)
-# env: Dict with all metadata and payloads
-# env_json_str: JSON string for publishing to NATS
-```
-
-#### MicroPython
-
-```python
-from natsbridge_mpy import NATSBridge
-
-bridge = NATSBridge()
-
-# Send a text message (limited to small payloads)
-data = [("message", "Hello World", "text")]
-env, env_json_str = bridge.smartsend(
-    "/chat/room1",
-    data,
-    size_threshold=100000  # Lower threshold for MicroPython
-)
-print("Message sent!")
-```
-
-### Step 4: Receive Messages
-
-#### Julia
-
-```julia
-using NATSBridge
-
-# Receive and process message
-env = smartreceive(msg; fileserver_download_handler=_fetch_with_backoff)
-# Returns: ::JSON.Object{String, Any} with "payloads" field containing Vector{Tuple{String, Any, String}}
-# Access payloads: for (dataname, data, type) in env["payloads"]
-for (dataname, data, type) in env["payloads"]
-    println("Received $dataname: $data")
-end
-```
-
-#### JavaScript
-
-```javascript
-const NATSBridge = require('./src/natsbridge.js');
-
-// Receive and process message
-const env = await NATSBridge.smartreceive(msg, {
-    fileserver_download_handler: NATSBridge.fetchWithBackoff
-});
-// env.payloads = [[dataname, data, type], ...]
-for (const [dataname, data, type] of env.payloads) {
-    console.log(`Received ${dataname}:`, data);
-}
-```
-
-#### Python
-
-```python
-from natsbridge import smartreceive, fetch_with_backoff
-
-# Receive and process message
-env = await smartreceive(
-    msg,
-    fileserver_download_handler=fetch_with_backoff
-)
-# env["payloads"] = [(dataname, data, type), ...]
-for dataname, data, type_ in env["payloads"]:
-    print(f"Received {dataname}: {data}")
-```
-
----
-
-## Basic Examples
-
-### Example 1: Sending a Dictionary
-
-#### Julia
-
-```julia
-using NATSBridge
-
-config = Dict(
-    "wifi_ssid" => "MyNetwork",
-    "wifi_password" => "password123",
-    "update_interval" => 60
-)
-
-data = [("config", config, "dictionary")]
-env, env_json_str = smartsend("/device/config", data, broker_url="nats://localhost:4222")
-```
-
-#### JavaScript
-
-```javascript
-const NATSBridge = require('./src/natsbridge.js');
-
-const config = {
-    wifi_ssid: "MyNetwork",
-    wifi_password: "password123",
-    update_interval: 60
-};
-
-const data = [["config", config, "dictionary"]];
-const [env, env_json_str] = await NATSBridge.smartsend(
-    "/device/config",
-    data,
-    { broker_url: "nats://localhost:4222" }
-);
-```
-
-#### Python
-
-```python
-from natsbridge import smartsend
-
-config = {
-    "wifi_ssid": "MyNetwork",
-    "wifi_password": "password123",
-    "update_interval": 60
-}
-
-data = [("config", config, "dictionary")]
-env, env_json_str = await smartsend(
-    "/device/config",
-    data,
-    broker_url="nats://localhost:4222"
-)
-```
-
-#### MicroPython
-
-```python
-from natsbridge_mpy import NATSBridge
-
-bridge = NATSBridge()
-
-config = {
-    "wifi_ssid": "MyNetwork",
-    "wifi_password": "password123",
-    "update_interval": 60
-}
-
-data = [("config", config, "dictionary")]
-env, env_json_str = bridge.smartsend(
-    "/device/config",
-    data,
-    size_threshold=100000
-)
-```
-
-### Example 2: Sending Binary Data (Image)
-
-#### Julia
-
-```julia
-using NATSBridge
-
-# Read image file
-image_data = read("image.png")
-
-data = [("user_image", image_data, "binary")]
-env, env_json_str = smartsend("/chat/image", data, broker_url="nats://localhost:4222")
-```
-
-#### JavaScript
-
-```javascript
-const NATSBridge = require('./src/natsbridge.js');
-const fs = require('fs');
-
-// Read image file
-const image_data = fs.readFileSync('image.png');
-
-const data = [["user_image", image_data, "binary"]];
-const [env, env_json_str] = await NATSBridge.smartsend(
-    "/chat/image",
-    data,
-    { broker_url: "nats://localhost:4222" }
-);
-```
-
-#### Python
-
-```python
-from natsbridge import smartsend
-
-# Read image file
-with open("image.png", "rb") as f:
-    image_data = f.read()
-
-data = [("user_image", image_data, "binary")]
-env, env_json_str = await smartsend(
-    "/chat/image",
-    data,
-    broker_url="nats://localhost:4222"
-)
-```
-
-#### MicroPython
-
-```python
-from natsbridge_mpy import NATSBridge
-
-bridge = NATSBridge()
-
-# Read image file
-with open("image.png", "rb") as f:
-    image_data = f.read()
-
-data = [("user_image", image_data, "binary")]
-env, env_json_str = bridge.smartsend(
-    "/chat/image",
-    data,
-    size_threshold=100000
-)
-```
-
-### Example 3: Request-Response Pattern
-
-#### Julia (Requester)
-
-```julia
-using NATSBridge
-
-# Send command with reply-to
-data = [("command", Dict("action" => "read_sensor"), "dictionary")]
-env, env_json_str = smartsend(
-    "/device/command",
-    data,
-    broker_url="nats://localhost:4222",
-    reply_to="/device/response",
-    reply_to_msg_id="cmd-001"
-)
-```
-
-#### JavaScript (Requester)
-
-```javascript
-const NATSBridge = require('./src/natsbridge.js');
-
-// Send command with reply-to
-const data = [["command", { action: "read_sensor" }, "dictionary"]];
-const [env, env_json_str] = await NATSBridge.smartsend(
-    "/device/command",
-    data,
-    {
-        broker_url: "nats://localhost:4222",
-        reply_to: "/device/response",
-        reply_to_msg_id: "cmd-001"
-    }
-);
-```
-
-#### Python (Requester)
-
-```python
-from natsbridge import smartsend
-
-# Send command with reply-to
-data = [("command", {"action": "read_sensor"}, "dictionary")]
-env, env_json_str = await smartsend(
-    "/device/command",
-    data,
-    broker_url="nats://localhost:4222",
-    reply_to="/device/response",
-    reply_to_msg_id="cmd-001"
-)
-```
-
-#### Julia (Responder)
-
-```julia
-using NATSBridge, NATS
-
-const SUBJECT = "/device/command"
-const NATS_URL = "nats://localhost:4222"
-
-function test_responder()
-    conn = NATS.connect(NATS_URL)
-    NATS.subscribe(conn, SUBJECT) do msg
-        env = smartreceive(msg, fileserver_download_handler=_fetch_with_backoff)
-        
-        reply_to = env["reply_to"]
-        
-        for (dataname, data, type) in env["payloads"]
-            if dataname == "command" && data["action"] == "read_sensor"
-                response = Dict("sensor_id" => "sensor-001", "value" => 42.5)
-                if !isempty(reply_to)
-                    smartsend(reply_to, [("data", response, "dictionary")])
-                end
-            end
-        end
-    end
-    
-    sleep(120)
-    NATS.drain(conn)
-end
-
-test_responder()
-```
-
----
-
-## Advanced Usage
-
-### Example 4: Large Payloads (File Server)
-
-For payloads larger than 1MB, NATSBridge automatically uses the file server:
-
-#### Julia
-
-```julia
-using NATSBridge
-
-# Create large data (> 1MB)
-large_data = rand(UInt8, 2_000_000)
-
-env, env_json_str = smartsend(
-    "/data/large",
-    [("large_file", large_data, "binary")],
-    broker_url="nats://localhost:4222",
-    fileserver_url="http://localhost:8080"
-)
-
-println("File uploaded to: $(env.payloads[1].data)")
-# Note: For link transport, data field contains the URL string
-```
-
-#### JavaScript
-
-```javascript
-const NATSBridge = require('./src/natsbridge.js');
-
-// Create large data (> 1MB)
-const large_data = Buffer.alloc(2_000_000);
-for (let i = 0; i < large_data.length; i++) {
-    large_data[i] = Math.floor(Math.random() * 256);
-}
-
-const [env, env_json_str] = await NATSBridge.smartsend(
-    "/data/large",
-    [["large_file", large_data, "binary"]],
-    {
-        broker_url: "nats://localhost:4222",
-        fileserver_url: "http://localhost:8080"
-    }
-);
-
-console.log("File uploaded to:", env.payloads[0].data);
-// Note: For link transport, data field contains the URL string
-```
-
-#### Python
-
-```python
-from natsbridge import smartsend
-
-# Create large data (> 1MB)
-import os
-large_data = os.urandom(2_000_000)
-
-env, env_json_str = await smartsend(
-    "/data/large",
-    [("large_file", large_data, "binary")],
-    broker_url="nats://localhost:4222",
-    fileserver_url="http://localhost:8080"
-)
-
-print(f"File uploaded to: {env['payloads'][0]['data']}")
-# Note: For link transport, data field contains the URL string
-```
-
-#### MicroPython
-
-MicroPython enforces a hard limit of 50KB per payload:
-
-```python
-from natsbridge_mpy import NATSBridge
-
-bridge = NATSBridge()
-
-# MicroPython has a hard limit of 50KB per payload
-# Use streaming or chunking for larger data
-small_data = bytes(1000)  # 1KB
-
-data = [("small_file", small_data, "binary")]
-env, env_json_str = bridge.smartsend(
-    "/data/small",
-    data,
-    size_threshold=100000  # Enforced max: 50000 bytes
-)
-```
-
-### Example 5: Mixed Content (Chat with Text + Image)
-
-NATSBridge supports sending multiple payloads with different types in a single message:
-
-#### Julia
-
-```julia
-using NATSBridge
-
-image_data = read("avatar.png")
-
-data = [
-    ("message_text", "Hello with image!", "text"),
-    ("user_avatar", image_data, "image")
-]
-
-env, env_json_str = smartsend("/chat/mixed", data, broker_url="nats://localhost:4222")
-```
-
-#### JavaScript
-
-```javascript
-const NATSBridge = require('./src/natsbridge.js');
-const fs = require('fs');
-
-const image_data = fs.readFileSync('avatar.png');
-
-const data = [
-    ["message_text", "Hello with image!", "text"],
-    ["user_avatar", image_data, "image"]
-];
-
-const [env, env_json_str] = await NATSBridge.smartsend(
-    "/chat/mixed",
-    data,
-    { broker_url: "nats://localhost:4222" }
-);
-```
-
-#### Python
-
-```python
-from natsbridge import smartsend
-
-with open("avatar.png", "rb") as f:
-    image_data = f.read()
-
-data = [
-    ("message_text", "Hello with image!", "text"),
-    ("user_avatar", image_data, "image")
-]
-
-env, env_json_str = await smartsend(
-    "/chat/mixed",
-    data,
-    broker_url="nats://localhost:4222"
-)
-# env: Dict with all metadata and payloads
-```
-
-### Example 6: Table Data (Arrow IPC)
-
-For tabular data, NATSBridge uses Apache Arrow IPC format:
-
-#### Julia
-
-```julia
-using NATSBridge
-using DataFrames
-
-# Create DataFrame
-df = DataFrame(
-    id = [1, 2, 3],
-    name = ["Alice", "Bob", "Charlie"],
-    score = [95, 88, 92]
-)
-
-data = [("students", df, "arrowtable")]
-env, env_json_str = smartsend("/data/students", data, broker_url="nats://localhost:4222")
-```
-
-#### JavaScript
-
-```javascript
-const NATSBridge = require('./src/natsbridge.js');
-
-// Create table data (array of objects)
-const table_data = [
-    { id: 1, name: "Alice", score: 95 },
-    { id: 2, name: "Bob", score: 88 },
-    { id: 3, name: "Charlie", score: 92 }
-];
-
-const data = [["students", table_data, "arrowtable"]];
-const [env, env_json_str] = await NATSBridge.smartsend(
-    "/data/students",
-    data,
-    { broker_url: "nats://localhost:4222" }
-);
-```
-
-#### Python
-
-```python
-from natsbridge import smartsend
-import pandas as pd
-
-# Create DataFrame
-df = pd.DataFrame({
-    'id': [1, 2, 3],
-    'name': ['Alice', 'Bob', 'Charlie'],
-    'score': [95, 88, 92]
-})
-
-data = [("students", df, "table")]
-env, env_json_str = await smartsend(
-    "/data/students",
-    data,
-    broker_url="nats://localhost:4222"
-)
-```
-
-#### MicroPython
-
-MicroPython does not support table type due to memory constraints. Use dictionary or binary instead.
-
----
-
-## Next Steps
-
-1. **Explore the test directory** for more examples
-2. **Check the documentation** for advanced configuration options
-3. **Read the walkthrough** for building real-world applications
-
----
-
-## Troubleshooting
-
-### Connection Issues
-
-- Ensure NATS server is running: `docker ps | grep nats`
-- Check firewall settings
-- Verify NATS URL configuration
-
-### File Server Issues
-
-- Ensure file server is running and accessible
-- Check upload permissions
-- Verify file server URL configuration
-
-### Serialization Errors
-
-- Verify data type matches the specified type
-- Check that binary data is in the correct format
-- MicroPython: Ensure payload size < 50KB
-
----
-
-## License
-
-MIT

src/natsbridge_csr.js

@@ -6,7 +6,15 @@
  * using NATS as the message bus, with support for both direct payload transport and
  * URL-based transport for larger payloads.
  * 
- * Supported payload types: "text", "dictionary", "arrowtable", "jsontable", "image", "audio", "video", "binary"
+ * Supported payload types: "text", "dictionary", "jsontable", "image", "audio", "video", "binary"
+ * Note: Browser version does NOT support Apache Arrow IPC (arrowtable) due to browser compatibility constraints.
+ * Use "jsontable" for tabular data in browser applications.
+ * 
+ * Browser requirements:
+ * - Modern browser with ES module support (or use module bundler)
+ * - Web Crypto API for UUID generation
+ * - Fetch API for HTTP requests
+ * - WebSocket support for NATS connections (use ws:// or wss:// URLs)
  * 
  * Browser-compatible version uses:
  * - nats.ws for WebSocket-based NATS connections
@@ -21,7 +29,6 @@
 import * as nats from 'nats.ws';
 
 // Use native fetch available in browsers
-import { tableFromArrays, tableToIPC } from 'apache-arrow/browser';
 
 // ---------------------------------------------- Constants ---------------------------------------------- //
 
@@ -49,10 +56,7 @@ const DEFAULT_FILESERVER_URL = 'http://localhost:8080';
  */
 function bufferToBase64(data) {
     const bytes = new Uint8Array(data);
-    let binary = '';
+    const binary = String.fromCharCode(...bytes);
-    for (let i = 0; i < bytes.length; i++) {
-        binary += String.fromCharCode(bytes[i]);
-    }
     return btoa(binary);
 }
 
@@ -71,6 +75,34 @@ function base64ToBuffer(base64) {
     return bytes;
 }
 
+/**
+ * Convert Uint8Array to Base64 string (Unicode-safe version)
+ * Uses TextEncoder/TextDecoder for proper Unicode handling
+ * @param {Uint8Array} data - Data to encode
+ * @returns {string} Base64 encoded string
+ */
+function bufferToBase64UnicodeSafe(data) {
+    const bytes = new Uint8Array(data);
+    // Use TextDecoder to properly handle the bytes as text
+    const binary = String.fromCharCode(...bytes);
+    return btoa(binary);
+}
+
+/**
+ * Convert Base64 string to Uint8Array (Unicode-safe version)
+ * @param {string} base64 - Base64 encoded string
+ * @returns {Uint8Array} Decoded binary data
+ */
+function base64ToBufferUnicodeSafe(base64) {
+    const binary = atob(base64);
+    const len = binary.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+
 /**
  * Generate UUID v4 using Web Crypto API
  * @returns {string} UUID string
@@ -98,7 +130,7 @@ function logTrace(correlationId, message) {
 /**
  * Serialize data according to specified format
  * @param {any} data - Data to serialize
- * @param {string} payloadType - Target format: "text", "dictionary", "arrowtable", "jsontable", "image", "audio", "video", "binary"
+ * @param {string} payloadType - Target format: "text", "dictionary", "jsontable", "image", "audio", "video", "binary"
  * @returns {Uint8Array} Binary representation of the serialized data
  */
 async function serializeData(data, payloadType) {
@@ -111,13 +143,6 @@ async function serializeData(data, payloadType) {
     } else if (payloadType === 'dictionary') {
         const jsonStr = JSON.stringify(data);
         return new Uint8Array(new TextEncoder().encode(jsonStr));
-    } else if (payloadType === 'arrowtable') {
-        // Convert array of objects to Arrow IPC format
-        if (!Array.isArray(data) || data.length === 0) {
-            throw new Error('Arrow table data must be a non-empty array of objects');
-        }
-        
-        return serializeArrowTable(data);
     } else if (payloadType === 'jsontable') {
         // Serialize array of objects to JSON format
         if (!Array.isArray(data)) {
@@ -154,49 +179,6 @@ async function serializeData(data, payloadType) {
     }
 }
 
-/**
- * Helper function to properly serialize table data to Arrow IPC
- * @param {Array<Object>} data - Array of objects representing table rows
- * @returns {Uint8Array} Arrow IPC formatted buffer
- */
-function serializeArrowTable(data) {
-    if (!Array.isArray(data) || data.length === 0) {
-        throw new Error('Table data must be a non-empty array of objects');
-    }
-    
-    logTrace('serializeArrowTable', `Serializing table with ${data.length} rows`);
-    
-    // Convert array of objects to a key-value format expected by tableFromArrays
-    const columns = {};
-    const keys = Object.keys(data[0]);
-    for (const key of keys) {
-        columns[key] = data.map(row => row[key]);
-    }
-    
-    logTrace('serializeArrowTable', `Columns: ${Object.keys(columns).join(', ')}`);
-    
-    const table = tableFromArrays(columns);
-    
-    logTrace('serializeArrowTable', `Arrow table created with ${table.numRows} rows, ${table.numCols} cols`);
-    
-    // Convert to IPC format
-    const ipcBuffer = tableToIPC(table);
-    
-    logTrace('serializeArrowTable', `IPC buffer type: ${typeof ipcBuffer}, byteLength: ${ipcBuffer.byteLength}`);
-    
-    const resultBuffer = new Uint8Array(ipcBuffer);
-    logTrace('serializeArrowTable', `Result buffer: ${resultBuffer.length} bytes`);
-    
-    // Debug: Show first 20 bytes in hex
-    const hexPreview = [];
-    for (let i = 0; i < Math.min(20, resultBuffer.length); i++) {
-        hexPreview.push(resultBuffer[i].toString(16).padStart(2, '0'));
-    }
-    logTrace('serializeArrowTable', `First 20 bytes (hex): ${hexPreview.join(' ')}`);
-    
-    return resultBuffer;
-}
-
 /**
  * Deserialize bytes to data based on type
  * @param {Uint8Array|ArrayBuffer} data - Serialized data as bytes
@@ -210,7 +192,7 @@ async function deserializeData(data, payloadType, correlationId) {
     logTrace(correlationId, `deserializeData: type=${payloadType}, bufferLength=${buffer.length}`);
     
     // Debug: Show first 20 bytes in hex for binary data
-    if (payloadType === 'arrowtable' || payloadType === 'jsontable' || payloadType === 'image' || payloadType === 'binary') {
+    if (payloadType === 'jsontable' || payloadType === 'image' || payloadType === 'binary') {
         const hexPreview = [];
         for (let i = 0; i < Math.min(20, buffer.length); i++) {
             hexPreview.push(buffer[i].toString(16).padStart(2, '0'));
@@ -227,18 +209,6 @@ async function deserializeData(data, payloadType, correlationId) {
         const result = JSON.parse(jsonStr);
         logTrace(correlationId, `deserializeData: dictionary keys=${Object.keys(result).join(', ')}`);
         return result;
-    } else if (payloadType === 'arrowtable') {
-        logTrace(correlationId, `deserializeData: Attempting Arrow table deserialization`);
-        
-        try {
-            // Try tableFromIPC (browser API)
-            const table = tableFromIPC(buffer);
-            logTrace(correlationId, `deserializeData: Arrow table from IPC - rows=${table.numRows}, cols=${table.numCols}`);
-            return table;
-        } catch (e) {
-            logTrace(correlationId, `deserializeData: tableFromIPC failed: ${e.message}`);
-            throw new Error(`Unable to deserialize Arrow table: ${e.message}`);
-        }
     } else if (payloadType === 'jsontable') {
         const jsonStr = new TextDecoder().decode(buffer);
         const result = JSON.parse(jsonStr);
@@ -357,15 +327,18 @@ async function fetchWithBackoff(url, maxRetries, baseDelay, maxDelay, correlatio
 
 /**
  * NATS client wrapper for connection management
+ * Supports both single-use and persistent connection modes
  */
 class NATSClient {
     /**
      * Create a new NATS client
      * @param {string} url - NATS server URL (ws:// or wss://)
+     * @param {boolean} [keepAlive=false] - Keep connection open for multiple publishes
      */
-    constructor(url) {
+    constructor(url, keepAlive = false) {
         this.url = url;
         this.connection = null;
+        this.keepAlive = keepAlive;
     }
 
     /**
@@ -373,6 +346,9 @@ class NATSClient {
      * @returns {Promise<NATS.Connection>}
      */
     async connect() {
+        if (this.connection) {
+            return this.connection;
+        }
         this.connection = await nats.connect({ servers: this.url });
         return this.connection;
     }
@@ -397,8 +373,94 @@ class NATSClient {
     async close() {
         if (this.connection) {
             this.connection.close();
+            this.connection = null;
         }
     }
+
+    /**
+     * Get the current connection (for external use)
+     * @returns {NATS.Connection|null}
+     */
+    getConnection() {
+        return this.connection;
+    }
+
+    /**
+     * Check if connected
+     * @returns {boolean}
+     */
+    isConnected() {
+        return this.connection !== null;
+    }
+}
+
+/**
+ * Connection pool for managing multiple NATS connections
+ * Useful for applications with multiple concurrent publishers
+ */
+class NATSConnectionPool {
+    /**
+     * Create a new connection pool
+     * @param {string} url - NATS server URL (ws:// or wss://)
+     * @param {number} [maxSize=10] - Maximum pool size
+     */
+    constructor(url, maxSize = 10) {
+        this.url = url;
+        this.maxSize = maxSize;
+        this.connections = new Map();
+        this.idCounter = 0;
+    }
+
+    /**
+     * Get a connection from the pool (or create new)
+     * @returns {Promise<NATSClient>}
+     */
+    async acquire() {
+        // Try to find an existing idle connection
+        for (const [id, client] of this.connections) {
+            if (client.isConnected()) {
+                return client;
+            }
+        }
+
+        // Create new connection if under limit
+        if (this.connections.size < this.maxSize) {
+            const id = `conn_${++this.idCounter}`;
+            const client = new NATSClient(this.url, true);
+            await client.connect();
+            this.connections.set(id, client);
+            return client;
+        }
+
+        // Pool exhausted - create new connection (caller should close when done)
+        const client = new NATSClient(this.url, false);
+        await client.connect();
+        return client;
+    }
+
+    /**
+     * Return a connection to the pool
+     * @param {NATSClient} client - Connection to return
+     */
+    release(client) {
+        // Only return persistent connections
+        if (client.keepAlive && client.isConnected()) {
+            // Connection already in pool, do nothing
+            return;
+        }
+        // Non-persistent connection - close it
+        client.close();
+    }
+
+    /**
+     * Close all connections in the pool
+     */
+    async closeAll() {
+        for (const [id, client] of this.connections) {
+            await client.close();
+        }
+        this.connections.clear();
+    }
 }
 
 // ---------------------------------------------- Core Functions ---------------------------------------------- //
@@ -409,9 +471,11 @@ class NATSClient {
  * @param {string} subject - NATS subject to publish to
  * @param {string} message - JSON message to publish
  * @param {string} correlationId - Correlation ID for tracing
+ * @param {boolean} [closeConnection=true] - Close connection after publish (set false for persistent connections)
  */
-async function publishMessage(brokerUrlOrClient, subject, message, correlationId) {
+async function publishMessage(brokerUrlOrClient, subject, message, correlationId, closeConnection = true) {
     let conn;
+    let shouldClose = false;
     
     if (brokerUrlOrClient instanceof NATSClient) {
         conn = brokerUrlOrClient;
@@ -425,15 +489,18 @@ async function publishMessage(brokerUrlOrClient, subject, message, correlationId
                 await brokerUrlOrClient.close();
             }
         };
+        shouldClose = true;
     } else {
         // String URL - create new client
         const client = new NATSClient(brokerUrlOrClient);
         conn = client;
+        shouldClose = true;
     }
     
     await conn.publish(subject, message, correlationId);
     
-    if (conn instanceof NATSClient) {
+    // Only close if explicitly requested and it's a short-lived client
+    if (shouldClose && closeConnection && conn instanceof NATSClient) {
         await conn.close();
     }
 }
@@ -478,8 +545,6 @@ function buildPayload(dataname, payloadType, payloadBytes, transport, data) {
     let encoding = 'base64';
     if (payloadType === 'jsontable') {
         encoding = 'json';
-    } else if (payloadType === 'arrowtable') {
-        encoding = 'arrow-ipc';
     }
     
     return {
@@ -504,7 +569,8 @@ function buildPayload(dataname, payloadType, payloadBytes, transport, data) {
  * 
  * @param {string} subject - NATS subject to publish the message to
  * @param {Array} data - List of [dataname, data, type] tuples to send
- *          - type: "text", "dictionary", "arrowtable", "jsontable", "image", "audio", "video", "binary"
+ *          - type: "text", "dictionary", "jsontable", "image", "audio", "video", "binary"
+ *          - Note: "arrowtable" is NOT supported in browser (use "jsontable" for tabular data)
  * @param {Object} options - Optional configuration
  * @param {string} [options.broker_url=DEFAULT_BROKER_URL] - URL of the NATS server (WebSocket)
  * @param {string} [options.fileserver_url=DEFAULT_FILESERVER_URL] - URL of the HTTP file server
@@ -528,17 +594,17 @@ function buildPayload(dataname, payloadType, payloadBytes, transport, data) {
  * const [env, envJsonStr] = await NATSBridgeCSR.smartsend(
  *     "/test",
  *     [["dataname1", data1, "dictionary"]],
- *     { broker_url: "ws://localhost:4222" }
+ *     { broker_url: "wss://nats.example.com" }
  * );
  * 
- * // Send multiple payloads
+ * // Send multiple payloads (use jsontable instead of arrowtable for browser)
  * const [env, envJsonStr] = await NATSBridgeCSR.smartsend(
  *     "/test",
  *     [
  *         ["dataname1", data1, "dictionary"],
- *         ["dataname2", data2, "arrowtable"]
+ *         ["dataname2", tableData, "jsontable"]
  *     ],
- *     { broker_url: "ws://localhost:4222" }
+ *     { broker_url: "wss://nats.example.com" }
  * );
  */
 async function smartsend(subject, data, options = {}) {
@@ -774,9 +840,37 @@ async function smartreceive(msg, options = {}) {
 const NATSBridgeCSR = {
     /**
      * NATS client class for connection management
+     * Supports both single-use and persistent connection modes
+     * 
+     * @example
+     * // Single-use connection (closes after publish)
+     * const client = new NATSBridgeCSR.NATSClient("wss://nats.example.com");
+     * await NATSBridgeCSR.smartsend("/test", [["msg", "Hello", "text"]], { nats_connection: client });
+     * await client.close();
+     * 
+     * // Persistent connection (keeps connection open)
+     * const client = new NATSBridgeCSR.NATSClient("wss://nats.example.com", true);
+     * await client.connect();
+     * await NATSBridgeCSR.smartsend("/test1", [["msg", "Hello", "text"]], { nats_connection: client, is_publish: false });
+     * await NATSBridgeCSR.publishMessage(client, "/test2", JSON.stringify({msg: "World"}), "trace-id");
+     * // Connection remains open for more publishes
+     * await client.close();
      */
     NATSClient,
 
+    /**
+     * Connection pool for managing multiple NATS connections
+     * Useful for applications with multiple concurrent publishers
+     * 
+     * @example
+     * const pool = new NATSBridgeCSR.NATSConnectionPool("wss://nats.example.com", 10);
+     * const client = await pool.acquire();
+     * await NATSBridgeCSR.smartsend("/test", [["msg", "Hello", "text"]], { nats_connection: client });
+     * pool.release(client);
+     * await pool.closeAll();
+     */
+    NATSConnectionPool,
+
     /**
      * Send data via NATS with automatic transport selection
      */
@@ -787,6 +881,19 @@ const NATSBridgeCSR = {
      */
     smartreceive,
 
+    /**
+     * Publish message to NATS
+     * 
+     * @example
+     * // Using a persistent connection
+     * const client = new NATSBridgeCSR.NATSClient("wss://nats.example.com", true);
+     * await client.connect();
+     * await NATSBridgeCSR.publishMessage(client, "/subject", JSON.stringify({msg: "Hello"}), "trace-id", false);
+     * // Connection stays open for more publishes
+     * await client.close();
+     */
+    publishMessage,
+
     /**
      * Upload data to plik server in one-shot mode
      */

src/natsbridge_ssr.js

@@ -1,6 +1,6 @@
 /**
  * NATSBridge - Cross-Platform Bi-Directional Data Bridge
- * JavaScript/Node.js Implementation (Client-Side Rendering)
+ * JavaScript/Node.js Implementation (Desktop/Server-Side)
  * 
  * This module provides functionality for sending and receiving data across network boundaries
  * using NATS as the message bus, with support for both direct payload transport and
@@ -8,6 +8,12 @@
  * 
  * Supported payload types: "text", "dictionary", "arrowtable", "jsontable", "image", "audio", "video", "binary"
  * 
+ * Node.js-specific features:
+ * - Apache Arrow IPC support via apache-arrow
+ * - TCP NATS connections (nats:// or tls:// URLs)
+ * - Buffer for binary data handling
+ * - Connection pooling for high-throughput scenarios
+ * 
  * @module NATSBridge
  */
 
@@ -342,15 +348,18 @@ async function fetchWithBackoff(url, maxRetries, baseDelay, maxDelay, correlatio
 
 /**
  * NATS client wrapper for connection management
+ * Supports both single-use and persistent connection modes
  */
 class NATSClient {
     /**
      * Create a new NATS client
-     * @param {string} url - NATS server URL
+     * @param {string} url - NATS server URL (nats:// or tls://)
+     * @param {boolean} [keepAlive=false] - Keep connection open for multiple publishes
      */
-    constructor(url) {
+    constructor(url, keepAlive = false) {
         this.url = url;
         this.connection = null;
+        this.keepAlive = keepAlive;
     }
 
     /**
@@ -358,6 +367,9 @@ class NATSClient {
      * @returns {Promise<NATS.Connection>}
      */
     async connect() {
+        if (this.connection) {
+            return this.connection;
+        }
         this.connection = await nats.connect({ servers: this.url });
         return this.connection;
     }
@@ -382,8 +394,94 @@ class NATSClient {
     async close() {
         if (this.connection) {
             this.connection.close();
+            this.connection = null;
         }
     }
+
+    /**
+     * Get the current connection (for external use)
+     * @returns {NATS.Connection|null}
+     */
+    getConnection() {
+        return this.connection;
+    }
+
+    /**
+     * Check if connected
+     * @returns {boolean}
+     */
+    isConnected() {
+        return this.connection !== null;
+    }
+}
+
+/**
+ * Connection pool for managing multiple NATS connections
+ * Useful for applications with multiple concurrent publishers
+ */
+class NATSConnectionPool {
+    /**
+     * Create a new connection pool
+     * @param {string} url - NATS server URL (nats:// or tls://)
+     * @param {number} [maxSize=10] - Maximum pool size
+     */
+    constructor(url, maxSize = 10) {
+        this.url = url;
+        this.maxSize = maxSize;
+        this.connections = new Map();
+        this.idCounter = 0;
+    }
+
+    /**
+     * Get a connection from the pool (or create new)
+     * @returns {Promise<NATSClient>}
+     */
+    async acquire() {
+        // Try to find an existing idle connection
+        for (const [id, client] of this.connections) {
+            if (client.isConnected()) {
+                return client;
+            }
+        }
+
+        // Create new connection if under limit
+        if (this.connections.size < this.maxSize) {
+            const id = `conn_${++this.idCounter}`;
+            const client = new NATSClient(this.url, true);
+            await client.connect();
+            this.connections.set(id, client);
+            return client;
+        }
+
+        // Pool exhausted - create new connection (caller should close when done)
+        const client = new NATSClient(this.url, false);
+        await client.connect();
+        return client;
+    }
+
+    /**
+     * Return a connection to the pool
+     * @param {NATSClient} client - Connection to return
+     */
+    release(client) {
+        // Only return persistent connections
+        if (client.keepAlive && client.isConnected()) {
+            // Connection already in pool, do nothing
+            return;
+        }
+        // Non-persistent connection - close it
+        client.close();
+    }
+
+    /**
+     * Close all connections in the pool
+     */
+    async closeAll() {
+        for (const [id, client] of this.connections) {
+            await client.close();
+        }
+        this.connections.clear();
+    }
 }
 
 // ---------------------------------------------- Core Functions ---------------------------------------------- //
@@ -394,9 +492,11 @@ class NATSClient {
  * @param {string} subject - NATS subject to publish to
  * @param {string} message - JSON message to publish
  * @param {string} correlationId - Correlation ID for tracing
+ * @param {boolean} [closeConnection=true] - Close connection after publish (set false for persistent connections)
  */
-async function publishMessage(brokerUrlOrClient, subject, message, correlationId) {
+async function publishMessage(brokerUrlOrClient, subject, message, correlationId, closeConnection = true) {
     let conn;
+    let shouldClose = false;
     
     if (brokerUrlOrClient instanceof NATSClient) {
         conn = brokerUrlOrClient;
@@ -410,15 +510,18 @@ async function publishMessage(brokerUrlOrClient, subject, message, correlationId
                 await brokerUrlOrClient.close();
             }
         };
+        shouldClose = true;
     } else {
         // String URL - create new client
         const client = new NATSClient(brokerUrlOrClient);
         conn = client;
+        shouldClose = true;
     }
     
     await conn.publish(subject, message, correlationId);
     
-    if (conn instanceof NATSClient) {
+    // Only close if explicitly requested and it's a short-lived client
+    if (shouldClose && closeConnection && conn instanceof NATSClient) {
         await conn.close();
     }
 }
@@ -764,9 +867,37 @@ async function smartreceive(msg, options = {}) {
 const NATSBridge = {
     /**
      * NATS client class for connection management
+     * Supports both single-use and persistent connection modes
+     * 
+     * @example
+     * // Single-use connection (closes after publish)
+     * const client = new NATSBridge.NATSClient("nats://localhost:4222");
+     * await NATSBridge.smartsend("/test", [["msg", "Hello", "text"]], { nats_connection: client });
+     * await client.close();
+     * 
+     * // Persistent connection (keeps connection open)
+     * const client = new NATSBridge.NATSClient("nats://localhost:4222", true);
+     * await client.connect();
+     * await NATSBridge.smartsend("/test1", [["msg", "Hello", "text"]], { nats_connection: client, is_publish: false });
+     * await NATSBridge.publishMessage(client, "/test2", JSON.stringify({msg: "World"}), "trace-id");
+     * // Connection remains open for more publishes
+     * await client.close();
      */
     NATSClient,
 
+    /**
+     * Connection pool for managing multiple NATS connections
+     * Useful for applications with multiple concurrent publishers
+     * 
+     * @example
+     * const pool = new NATSBridge.NATSConnectionPool("nats://localhost:4222", 10);
+     * const client = await pool.acquire();
+     * await NATSBridge.smartsend("/test", [["msg", "Hello", "text"]], { nats_connection: client });
+     * pool.release(client);
+     * await pool.closeAll();
+     */
+    NATSConnectionPool,
+
     /**
      * Send data via NATS with automatic transport selection
      */
@@ -777,6 +908,19 @@ const NATSBridge = {
      */
     smartreceive,
 
+    /**
+     * Publish message to NATS
+     * 
+     * @example
+     * // Using a persistent connection
+     * const client = new NATSBridge.NATSClient("nats://localhost:4222", true);
+     * await client.connect();
+     * await NATSBridge.publishMessage(client, "/subject", JSON.stringify({msg: "Hello"}), "trace-id", false);
+     * // Connection stays open for more publishes
+     * await client.close();
+     */
+    publishMessage,
+
     /**
      * Upload data to plik server in one-shot mode
      */