Metadata-Version: 2.4
Name: tinpyui-ff
Version: 1.7.1
Summary: The official compiler and CLI for the TinUI framework, featuring a Pythonic, indentation-based syntax powered by WebAssembly and WebGL.
Home-page: https://github.com/barathanandh-coder/tinui
Author: Barathanandh
Project-URL: Homepage, https://github.com/barathanandh-coder/tinui
Project-URL: Documentation, https://github.com/barathanandh-coder/tinui#readme
Project-URL: Repository, https://github.com/barathanandh-coder/tinui
Project-URL: Bug Tracker, https://github.com/barathanandh-coder/tinui/issues
Keywords: tinui,tinpyui,zero-dom,python-gui,python-ui-framework,streamlit-alternative,flet-alternative,reflex-alternative,webassembly,rust-wasm,webgl-ui,hardware-accelerated,120fps-gui,cross-platform,android-gui,ios-gui,indentation-syntax-compiler
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-python
Dynamic: summary

# ⚡ TinPyUI Framework v1.7.0
### *Hardware-Accelerated Omni-Platform UI Engine & Vector Graphics Pipeline*

[![CI](https://github.com/barathanandh-coder/TinUi/actions/workflows/ci.yml/badge.svg)](https://github.com/barathanandh-coder/TinUi/actions/workflows/ci.yml)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
[![Good First Issues](https://img.shields.io/github/issues/barathanandh-coder/TinUi/good%20first%20issue?color=7057ff&label=Good%20First%20Issues&style=flat-square)](https://github.com/barathanandh-coder/TinUi/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
[![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg?style=flat-square)](CODE_OF_CONDUCT.md)
[![npm](https://img.shields.io/badge/npm-tinpyui-v1.7.0-00f2fe?style=flat-square&logo=npm)](https://www.npmjs.com/package/tinpyui)
[![pypi](https://img.shields.io/badge/pypi-tinpyui--ff-v1.7.0-9b51e0?style=flat-square&logo=pypi)](https://pypi.org/project/tinpyui-ff/)

**TinPyUI** is an ultra-high-performance, memory-safe, zero-dependency, hardware-accelerated UI application framework. It unites a **Native C-FFI Sub-Millisecond Vector Surface Engine** for Desktop (**Windows DirectX 12, macOS Apple Metal, Linux GTK4/Wayland**) and Mobile (**Android Touch Haptics, Apple iOS Retina**) with a **Hybrid Semantic DOM + WebGL 2.0 / WebGPU Shader Layer** compiled via Go to WebAssembly (`tinui_engine.wasm`).

> 📖 **Comprehensive Technical Manual**: For deep internal architecture, compiler AST specs, and memory diagrams, consult [tinpyui-docs.md](tinpyui-docs.md) and [DATABASE_AND_CONNECTIONS_GUIDE.md](DATABASE_AND_CONNECTIONS_GUIDE.md).

---

## 📑 Table of Contents

1. [✨ Genuine Technical Facts & Highlights](#-genuine-technical-facts--highlights)
2. [🏛️ Architectural Reality](#-architectural-reality)
3. [📊 Deep Architectural Comparison](#-deep-architectural-comparison)
4. [🚀 Quickstart: 3 Clean Commands](#-quickstart-3-clean-commands)
5. [💻 Universal Cross-Platform Native Runtime](#-universal-cross-platform-native-runtime)
6. [⚡ Pure Python Declarative UI Framework (`tinpyui`)](#-pure-python-declarative-ui-framework-tinpyui)
7. [📖 Declarative `.tin` Indentation-Based Syntax](#-declarative-tin-indentation-based-syntax)
8. [🧱 Complete Component API Catalog & Enterprise Suite](#-complete-component-api-catalog--enterprise-suite)
9. [⚡ Reactive State Signals & Symplectic Spring Physics (120 FPS)](#-reactive-state-signals--symplectic-spring-physics-120-fps)
10. [📜 High-Volume Spatial Virtualization (`VirtualStack` & `VirtualList`)](#-high-volume-spatial-virtualization-virtualstack--virtuallist)
11. [🗄️ Universal Reactive Database Suite (`tin.connect`)](#-universal-reactive-database-suite-tinconnect)
    - [PostgreSQL Relational SQL](#1-postgresql-relational-sql)
    - [MongoDB Document NoSQL](#2-mongodb-document-nosql)
    - [SQLite & Ephemeral In-Memory Storage](#3-sqlite--ephemeral-in-memory-storage)
    - [Redis Key-Value & Reactive Pub/Sub Signals](#4-redis-key-value--reactive-pubsub-signals)
    - [DuckDB & ClickHouse Vectorized Analytics](#5-duckdb--clickhouse-vectorized-analytics)
    - [Reactive Live Queries (`LiveQuery`)](#6-reactive-live-queries-livequery)
    - [Persistent Key-Value Store (`tin.use_store`)](#7-persistent-key-value-store-tinuse_store)
    - [Active Record Declarative Models (`@tin.model`)](#8-active-record-declarative-models-tinmodel)
12. [🪄 Enterprise UI & Low-Code Declarative Suite (`DataGrid`, `AIChat`, `LiveDataTable` & `AutoCRUD`)](#-enterprise-ui--low-code-declarative-suite-datagrid-aichat-livedatatable--autocrud)
13. [🎨 Extended Hardware GPU Shader Library](#-extended-hardware-gpu-shader-library)
14. [📡 Real-Time Streams & Sockets (`use_socket` & `use_sse`)](#-real-time-streams--sockets-use_socket--use_sse)
15. [📱 Omni-Platform Packaging & Touch Gestures (Android, iOS, Desktop)](#-omni-platform-packaging--touch-gestures-android-ios-desktop)
16. [🔒 Enterprise Security & Hardware Telemetry Suite](#-enterprise-security--hardware-telemetry-suite)
17. [🧠 Intermediate Representation (IR) Compiler & Dynamic Export (`app.export_ir`)](#-intermediate-representation-ir-compiler--dynamic-export-appexport_ir)
18. [🖥️ How to Compile `.tin` Code on Every OS (Windows, macOS, Linux)](#-how-to-compile-tin-code-on-every-os-windows-macos-linux)
19. [🛠️ CLI Workflows, Interactive REPL & Live Reload](#-cli-workflows-interactive-repl--live-reload)
20. [🚀 Production Deployment & Backend Integration](#-production-deployment--backend-integration)
21. [🌟 Full-Stack Production Master Blueprint](#-full-stack-production-master-blueprint)
22. [🤝 Contributing to TinPyUI](#-contributing-to-tinpyui)
23. [📄 License](#-license)

---

## ✨ Genuine Technical Facts & Highlights

- 🪶 **100% Zero External PIP Dependencies**: The entire Python core (`tinpyui-ff`) runs on Python 3.7+ standard library modules (`ctypes`, `mmap`, `json`, `threading`, `socketserver`, `http.server`). No external wheels or heavy runtime installs required.
- ⚡ **Zero-Copy Shared RAM IPC**: Uses an anonymous 4MB operating system memory map (`mmap`) to exchange 16-byte packed C-structs directly between Python and the native C++ window host, completely bypassing JSON serialization latency.
- 🚀 **Ahead-of-Time (AOT) Static Compilation**: `tinpyui build app.tin --dist ./dist --target webgl` compiles indentation layouts down to compact binary bytecode matrices (`TINB`) and static web deployment bundles with zero runtime parsing overhead.
- ⚡ **Zero-Copy WebAssembly Linear Memory Bridge**: Maps node transforms and shader uniforms into a fixed 48-byte linear memory stride directly readable by WebGL vertex attributes.
- 🔥 **Sub-Millisecond Indentation HMR**: Incremental AST diffing updates uniforms and node parameters live without remounting the WebGL canvas.
- 🧩 **Official VS Code Extension & LSP**: Includes TextMate syntax grammar, real-time indentation diagnostics, and tag autocompletion (`vscode-tinpyui/`).
- 📦 **Compact ~2.8 MB Standalone Native Executable**: Built upon lightweight native webview hosts (`webview2` on Windows DirectX 12, `WKWebView` on macOS Metal, `WebKitGTK` on Linux) instead of bundling 150MB+ Chromium binaries.
- 🛡️ **Defeats the "Black Screen of Death"**: Explicitly interrogates the GPU after compilation and linking (`glGetShaderiv` / `getShaderParameter` checking `COMPILE_STATUS` & `LINK_STATUS`). Syntax errors immediately trigger an interactive diagnostic crash overlay with exact line numbers.
- 🏛️ **Hybrid Semantic DOM + WebGL GPU Engine**: Renders standard HTML elements for crystal-clear typography, accessibility (a11y), and selection, while offloading visual effects to an isolated 60/120 FPS WebGL shader canvas.
- ⚡ **Granular Reactive State Signals**: O(1) state cells (`tin.Signal`) trigger direct node updates with zero Virtual DOM tree diffing overhead.
- 🚀 **Unified 3-Command Toolchain**: One single CLI (`tinpyui`, aliased to `tinui`) with only 3 clean commands: `new`, `run`, and `build`.

---

## 🏛️ Architectural Reality

TinPyUI rejects the raw canvas-only approach (e.g., Flutter Web CanvasKit) which destroys browser copy-paste, breaks accessibility (a11y), and impairs search engine indexing (SEO).

Instead, TinPyUI employs a **Hybrid Semantic DOM + WebGL Hardware Acceleration Architecture**:

```
+-----------------------------------------------------------------------------------+
|                        TINPYUI DUAL-ENGINE ARCHITECTURE                           |
+-----------------------------------------------------------------------------------+
|  [ .tin Source Code ]  ──▶  [ Go AOT Compiler ]  ──▶  [ Intermediate Rep (IR) ]   |
+-----------------------------------------------------------------------------------+
                                          │
                                          ▼
+-----------------------------------------------------------------------------------+
|                     WASM RUNTIME KERNEL (tinui_engine.wasm)                       |
+-----------------------------------------+-----------------------------------------+
|          LAYER A: DOM ENGINE            |       LAYER B: HARDWARE GPU SHADER      |
|  - Semantic HTML5 Elements              |  - WebGL 2.0 / WebGPU Surfaces          |
|  - Flexbox & Dynamic CSS Tokens         |  - Custom GLSL Fragment Shaders         |
|  - Reactive State & Input Bindings      |  - 120 FPS Cyber Waves & Particle Dust  |
|  - Native A11y & SEO Hydration Shell    |  - Zero CPU Layout Interruptions        |
+-----------------------------------------+-----------------------------------------+
```

---

## 📊 Deep Architectural Comparison

| Feature / Metric | **TinPyUI v1.6** | **React / Next.js** | **Flutter Web (CanvasKit)** | **PyScript / Pyodide** | **Streamlit / Flet** | **Tauri / Electron** |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **Language DSL** | Pythonic (`.tin`) & Pure Python | JSX / XML | Dart Widgets | Pure Python (CPython) | Python Backend | JS / TS / HTML |
| **Execution** | Go WebAssembly + IR Engine | JS V-DOM Diffing | Skia/Impeller Canvas | 25MB CPython Wasm | Server WebSocket IPC | Native Webview / Node |
| **DOM Strategy** | Direct Semantic DOM + WebGL | Virtual DOM Diffing | Canvas Only (No DOM) | JS Proxy DOM | Server-driven DOM | Native Webview DOM |
| **Accessibility & SEO** | Native DOM + SEO Shell | Native DOM | ❌ None (Raw pixels) | Partial | ❌ None (Dynamic) | Native Desktop |
| **Client Latency** | 0 ms (Local WASM) | 0 ms (Local JS) | 0 ms (Local WASM) | High startup lag | 50-200 ms network lag | 0 ms (Local IPC) |
| **GPU Shader Engine** | Built-in GLSL & WebGL | Requires Three.js | Canvas 2D API | Canvas library | Not supported | WebGL library |
| **Binary Size** | ~2 MB Native Shell | N/A (Web bundle) | 20 MB - 35 MB | 25 MB - 40 MB | Full Python Server | 2 MB (Tauri) / 150 MB (Electron) |
| **PIP Dependencies** | **0 External Packages** | N/A | N/A | Requires Pyodide | Heavy pip dependencies | Heavy npm packages |


---

## 🚀 Quickstart: 3 Clean Commands

TinPyUI simplifies application development down to **3 simple, unified commands**:

```
 ┌──────────────┐     ┌──────────────┐     ┌────────────────┐
 │ 1. CREATE    │ ──▶ │ 2. RUN       │ ──▶ │ 3. BUILD       │
 │ tinpyui new  │     │ tinpyui run  │     │ tinpyui build  │
 └──────────────┘     └──────────────┘     └────────────────┘
```


### 1. 📥 Install
```bash
pip install tinpyui-ff
```
> **Genuine Fact**: Zero external Python packages required. Runs on pure Python 3.7+ standard library (`ctypes`, `mmap`, `json`, `threading`, `http.server`).

---

### 2. 📁 Create Your Project
```bash
tinpyui new my_app
cd my_app
```
Scaffolds a beginner-friendly project structure:
- `main.tin` — Your main screen layout and reactive logic
- `scenes/` — Multi-page scenes and views
- `shaders/background.frag` — Hardware GPU shader effects
- `public/` — Web browser assets (`index.html`, `tin-runtime.js`, `tinui_engine.wasm`)
- `tinpy.toml` — App title and window settings

---

### 3. ⚡ Run & Develop
Choose how you want to run and develop your application:

- **Desktop Window (Sub-Millisecond Shared RAM)**:
  ```bash
  tinpyui run main.tin
  # Or shorthand:
  tinpyui main.tin
  ```
  *(Maps 4MB shared memory, hands Thread 0 to native OS engine, and boots instantly)*

- **Browser Live Dev Server (with Hot GLSL Reloading)**:
  ```bash
  tinpyui run main.tin --web
  # Or alias:
  tinpyui dev
  ```
  *(Starts dev server on `http://localhost:8080` with auto-reload and GPU error overlay)*


- **Interactive Debug Shell & REPL**:
  ```bash
  tinpyui repl
  # Or alias:
  tinpyui shell
  ```
  *(Boots interactive Python shell with `tin`, `db`, and reactive `Signal` preloaded for live experimentation)*

---

### 4. 📦 Build & Deploy
- **Static Web Bundle (Ready for CDNs)**:
  ```bash
  tinpyui build --web
  ```
  *(Packages static assets into `dist/` ready to host on Cloudflare Pages, Netlify, Vercel, or AWS S3)*

- **Standalone Native Desktop Executable**:
  ```bash
  tinpyui build --desktop
  ```
  *(Compiles a compact ~2.8 MB standalone `.exe` / native binary into `build/desktop/`)*

- **Standalone Apple iOS Native Xcode Project**:
  ```bash
  tinpyui build --ios --app-name "CyberApp" --bundle-id "com.corp.cyberapp"
  ```
  *(Generates production-ready Xcode project in `build/mobile/ios/` with `WKWebView`, Swift haptic bridge, and Retina scaling)*

- **Standalone Native Android Package (APK / Gradle)**:
  ```bash
  tinpyui build --mobile --app-name "CyberApp" --package "com.corp.cyberapp" --apk
  # Or explicit syntax:
  tinui export mobile main.tin
  ```
  *(Generates standalone Android Gradle project in `build/mobile/android/` with hardware-accelerated WebGL + Touch Haptics & auto-compiles APK if Gradle is present)*

---


---

## 💻 Universal Cross-Platform Native Runtime

TinPyUI embeds lightweight C/C++ host window bindings (`engine_core.cc`) compiling down to a **~2 MB standalone native desktop binary** without bundling Chromium:

```
+-----------------------------------------------------------------------------------+
|                         NATIVE HARDWARE OS ACCELERATION                           |
+-----------------------------------------------------------------------------------+
|  🍎 macOS (Apple Silicon & Intel)  ──▶  Cocoa API + WKWebView (Apple Metal GPU)   |
|  🐧 Linux (Ubuntu, Fedora, Arch)   ──▶  GTK3/GTK4 + WebKitGTK (Wayland / X11)     |
|  🪟 Windows (10 & 11)              ──▶  Win32 HWND + Edge WebView2 (DirectX 12)   |
|  📱 Mobile (Android & iOS)         ──▶  Touch Engine + Haptic Hardware Channels   |
+-----------------------------------------------------------------------------------+
```

### Zero-Bloat Native Compilation Pipeline:
```bash
# macOS (Clang / Metal)
c++ native/engine_core.cc -std=c++11 -framework WebKit -framework Cocoa -o tinui_mac

# Linux (GCC / GTK)
g++ native/engine_core.cc `pkg-config --cflags --libs gtk+-3.0 webkit2gtk-4.0` -o tinui_linux

# Windows (MinGW / DirectX)
g++ native/engine_core.cc -mwindows -ladvapi32 -lole32 -lshell32 -lshlwapi -luser32 -lversion -o tinui_win.exe
```

---

## ⚡ Pure Python Declarative UI Framework (`tinpyui`)

You can build full desktop and web applications directly in pure Python using declarative context managers:

```python
import tinpyui as tin

class CyberDashboard(tin.App):
    def __init__(self):
        super().__init__(title="TinPyUI Cyber Hub", width=1200, height=800)
        self.counter = tin.Signal(0)
        self.status = tin.Signal("Hardware Online (120 FPS)")

    def increment(self):
        self.counter.update(lambda c: c + 1)
        self.status.set(f"Signal mutated to {self.counter.value}")

    def build(self):
        with tin.Window(title="TinPyUI Native Desktop App"):
            with tin.Section(padding=24, align="center"):
                tin.GradientText("Hardware-Accelerated TinPyUI Engine", gradient=["#00f2fe", "#9b51e0"], size="hero")
                tin.Text(text=lambda: f"● {self.status.value}", color="muted")
                tin.Spacer(height=20)
                
                with tin.Card(bg="#141218", radius=16, shadow="cyan", padding=24):
                    tin.Heading("Reactive Telemetry", size="h2")
                    tin.Text(text=lambda: f"Counter Signal: {self.counter.value}", color="#ffffff", size="large")
                    tin.Spacer(height=12)
                    with tin.Row(gap=12):
                        tin.Button("⚡ Increment Signal", on_click=self.increment, variant="primary")
                        tin.Button("📳 Haptic Pulse", on_click=lambda: tin.haptics.vibrate(50), variant="outline")

if __name__ == "__main__":
    CyberDashboard().run()
```

---

## 📖 Declarative `.tin` Indentation-Based Syntax

TinPyUI provides an indentation-based DSL that compiles directly to WebAssembly IR:

### Syntax Rules:
1. **Component Root**: Every file begins with `component Main():` or custom component definitions.
2. **Indentation**: 4 spaces following a colon (`:`). No curly braces `{}` or closing tags.
3. **Typed Props**: Key-value pairs (`key="string"`, `number=20`, `flag=true`, `list=["a", "b"]`).
4. **Data Binding**: Interpolate reactive variables via `{variable_name}` inside strings.

```tin
component Main():
    AnimatedBackground(effect="cyber-wave", primaryColor="neon-purple", secondaryColor="neon-cyan"):
        
        Navbar(padding=20, blur=true):
            Row(align="center", justify="space-between", width="full"):
                Text(text="TinPyUI Cloud Console", color="neon-cyan", weight="bold")
                Row(gap=30, color="white"):
                    NavLink(text="Dashboard", route="/")
                    NavLink(text="Telemetry", route="/telemetry")

        Section(align="center", paddingY=80, maxWidth=900, justify="center"):
            GradientText(text="The Zero-DOM WebAssembly Engine", gradient=["neon-cyan", "neon-purple"], size="hero")
            Text(text="Build high-performance native & web applications with pure Pythonic syntax.", size="large", color="white", marginTop=20)
            
            Spacer(height=30)
            Row(gap=20, align="center", justify="center"):
                Button(text="Launch Cluster", variant="solid", glow="neon-cyan", radius="pill")
                Button(text="System Documentation", variant="outline", radius="pill")
```

---

## 🧱 Complete Component API Catalog & Enterprise Suite

### 1. Structural & Layout Containers
| Component | Primary Properties | Description |
| :--- | :--- | :--- |
| `Section` | `align`, `justify`, `padding`, `paddingY`, `maxWidth`, `minHeight`, `bg`, `radius` | Primary layout block isolating horizontal regions |
| `Container` | `align`, `justify`, `width`, `padding`, `gap`, `animation`, `duration` | General-purpose flexbox container with animation triggers |
| `Row` | `align`, `justify`, `gap`, `width`, `wrap`, `marginTop`, `color` | Horizontal flex row aligning children |
| `Column` | `align`, `justify`, `gap`, `padding`, `bg`, `border`, `radius`, `minWidth`, `maxWidth` | Vertical layout column stack |
| `Card` | `maxWidth`, `padding`, `bg`/`background`, `border`, `radius`, `shadow` | Glassmorphism or solid container card |
| `Grid` | `cols`, `gap`, `width`, `padding` | Multi-column responsive grid layout |
| `Spacer` | `height`, `width` | Fixed dimensional spacing element |
| `Divider` | `color`, `margin` | Visual horizontal rule separator |
| `Surface` | `width`, `height`, `background` | Canvas drawing / shader surface |

### 2. Typography & Visual Badges
| Component | Primary Properties | Description |
| :--- | :--- | :--- |
| `Heading` | `text`, `size` (`"hero"`, `"h1"`, `"h2"`, `"h3"`, `"small"`), `color`, `weight` | Semantic heading element |
| `Text` | `text`, `size` (`"small"`, `"normal"`, `"large"`), `color`, `weight`, `align`, `dataBind` | Paragraph text with dynamic `{state}` interpolation or lambda bindings |
| `GradientText` | `text`, `gradient` (`["#00f2fe", "#9b51e0"]`), `size` | Vibrant linear gradient typography |
| `Badge` | `text`, `variant` (`"neon-cyan"`, `"neon-pink"`), `color` | Compact status tag or telemetry pill |
| `Span` | `text` | Inline text span element |

### 3. Interactive Controls & Forms
| Component | Primary Properties | Description |
| :--- | :--- | :--- |
| `Button` | `text`, `variant` (`"solid"`, `"outline"`, `"primary"`), `glow`, `radius` (`"pill"`, `8`), `on_click`, `action` | Interactive button supporting click animations & glow states |
| `Input` | `placeholder`, `value`, `dataBind`, `width`, `padding`, `bg`, `border`, `radius`, `color` | Two-way data-bound input field |
| `Textarea` | `placeholder`, `value`, `dataBind`, `rows`, `width` | Multiline text entry |
| `Form` | `gap` | Semantic form wrapper |
| `NavLink` | `text`, `route`/`target`, `href` | Cinematic scene transition link |

### 4. Advanced Hardware Shaders & Media
| Component | Primary Properties | Description |
| :--- | :--- | :--- |
| `AnimatedBackground` | `effect` (`"cyber-wave"`, `"particles"`, `"quantum-vortex"`), `primaryColor`, `secondaryColor`, `speed` | Full-screen hardware WebGL canvas effect |
| `Navbar` | `padding`, `blur` (bool), `fixed` (bool), `borderBottom` | Glassmorphic navigation header with backdrop blur |
| `CustomShader` | `fragment_code`, `uniforms` | Raw inline GLSL fragment shader with compile-time validation |
| `Marquee` | `direction`, `speed` | Continuous hardware-accelerated scrolling ticker |
| `Icon` | `name`, `color` | Native vector SVG icon element |
| `Image` | `src`, `url`, `assetPriority` | Optimized image element |

### 5. v1.7.0 Enterprise Components, Charts & AI Tools
| Component | Primary Properties | Description |
| :--- | :--- | :--- |
| `DataGrid` | `columns`, `data`, `page_size`, `searchable`, `sortable`, `selectable`, `exportable` | Enterprise virtualized grid with column sorting, live query search filtering, pagination, and 1-click CSV/JSON export |
| `AIChat` | `messages`, `model_name`, `avatar`, `user_avatar`, `placeholder`, `on_send` | Streaming token LLM conversation UI with markdown code blocks, syntax styling, and copy buttons |
| `ColorPicker` | `value`, `presets`, `show_alpha`, `on_change` | Interactive Hex/RGB/HSL picker with opacity slider and palette swatches |
| `DatePicker` | `value`, `placeholder`, `date_format`, `min_date`, `max_date`, `on_change` | Input field with animated Calendar popup and date format validation |
| `Calendar` | `year`, `month`, `selected_date`, `on_select` | Interactive monthly calendar matrix with month/year navigation controls |
| `LineChart` | `data`, `labels`, `width`, `height`, `colors` | Vector SVG smooth curve chart with gradients and reactive Signal bindings |
| `BarChart` | `data`, `labels`, `width`, `height`, `colors` | Vector SVG column bar chart with dynamic scaling |
| `DonutChart` | `data`, `labels`, `width`, `height`, `colors` | Vector SVG circular proportion chart with stroke offsets |
| `Sparkline` | `data`, `colors`, `height` | Compact micro-trend visualization for financial and telemetry feeds |
| `TreeView` | `nodes`, `selected_id`, `on_select` | Hierarchical collapsible tree node viewer for file structures and categories |
| `TreeNode` | `id`, `label`, `icon`, `children`, `expanded`, `data` | TreeView node element supporting recursive nesting |

---

## ⚡ Reactive State Signals & Symplectic Spring Physics (120 FPS)


TinPyUI features an $O(1)$ reactive state graph coupled with a **Symplectic Euler differential solver** for physics animations:

```python
import tinpyui as tin

# 1. Reactive Signals (O(1) updates)
count = tin.Signal(0)
count.subscribe(lambda val: print(f"Counter changed: {val}"))
count.update(lambda c: c + 1)

# 2. Symplectic Euler Spring Physics (Hooke's Law: F = -kx - cv)
spring = tin.Spring(tension=180.0, friction=20.0)
spring.target = 250.0  # Set target displacement in pixels

# Step the differential solver (e.g. inside a 120 FPS frame loop)
current_pos = spring.step(delta_time=1.0 / 120.0)
print(f"Spring Position: {current_pos:.2f}px | Velocity: {spring.velocity:.2f}")
```

---

## 📜 High-Volume Spatial Virtualization (`VirtualStack` & `VirtualList`)

TinPyUI v1.6 introduces **Spatial Index Windowing** capable of rendering **100,000+ items** with sub-millisecond scrolling latency and zero garbage collection allocations:

### In `.tin` DSL:
```tin
component VirtualFeed():
    Section(padding=20):
        Heading(text="High-Volume Virtual Feed (100k Rows)", size="h2")
        VirtualStack(itemHeight=52, totalCount=100000):
            Card(padding=12, bg="rgba(20, 20, 30, 0.8)", border="neon-cyan"):
                Text(text="Dynamic Virtual Row Item", color="white")
```

### In Pure Python:
```python
import tinpyui as tin

items = [f"Server Node #{i} - Status: ACTIVE" for i in range(50000)]

with tin.Window(title="Virtualized Cluster View"):
    tin.Heading("50,000 Telemetry Nodes (120 FPS)", size="h1")
    # Only visible nodes within the viewport rect are rendered to the hardware surface
    tin.VirtualList(items=items, item_height=48.0)
```

---

## 🗄️ Universal Reactive Database Suite (`tin.connect`)

TinPyUI provides a unified multi-engine database layer that automatically binds mutations to the 120 FPS UI signal graph:

```
+-----------------------------------------------------------------------------------+
|                        TINPYUI REACTIVE DATA PIPELINE                             |
+-----------------------------------------------------------------------------------+
|  [ Database Mutation ]  ──▶  [ Table / Collection Listener ]                      |
|  (insert / update / delete)                 │                                     |
|                                             ▼                                     |
|  [ UI Render (120 FPS) ] ◀── [ LiveQuery / Reactive Signal ] ◀── [ O(1) Graph ]  |
+-----------------------------------------------------------------------------------+
```

### 1. PostgreSQL Relational SQL
```python
pg_db = tin.connect("postgres://admin:secret@localhost:5432/production_db")
events = pg_db.table("analytics_events")

# Single insert with auto-schema evolution (creates columns dynamically)
row_id = events.insert(event="user_login", user_id="usr_42", duration_ms=18.5, is_active=True)

# Bulk ACID transaction
events.insert_many([
    {"event": "page_view", "user_id": "usr_42", "duration_ms": 12.0},
    {"event": "checkout",  "user_id": "usr_43", "duration_ms": 190.0}
])

# Fluent query building
active_users = (events.where(user_id="usr_42")
                      .gt("duration_ms", 10.0)
                      .order_by("duration_ms", desc=True)
                      .limit(10)
                      .all())
```

### 2. MongoDB Document NoSQL
```python
mongo_db = tin.connect("mongodb://localhost:27017/fleet_db")
devices = mongo_db.collection("devices")

# Insert document
devices.insert_one({
    "name": "Edge-Gateway-01",
    "specs": {"cpu_cores": 16, "ram_gb": 64},
    "tags": ["edge", "gateway", "active"]
})

# Nested dot-notation and operator query
results = devices.find({
    "specs.ram_gb": {"$gte": 32},
    "tags": {"$in": ["gateway"]}
})
```

### 3. SQLite & Ephemeral In-Memory Storage
```python
# Disk SQLite
sqlite_db = tin.connect("sqlite:///fleet_data.db")

# Zero-disk Ephemeral RAM database (Ideal for unit tests & WASM runtime)
ram_db = tin.connect(":memory:")
```

### 4. Redis Key-Value & Reactive Pub/Sub Signals
```python
redis = tin.connect("redis://localhost:6379/0")

# Key-Value caching with TTL (seconds)
redis.set("user:session", {"id": 101, "role": "admin"}, ex=3600)
session = redis.get("user:session")

# Atomic counters & hash maps
redis.incr("page:views", 1)
redis.hset("device:cfg", "firmware", "v1.7.0")

# Reactive Signals: UI updates automatically on key or channel changes
theme_signal = redis.signal("user:theme", default="cyberpunk")
telemetry_stream = redis.pubsub_signal("telemetry:stream")

# Publish messages from anywhere
redis.publish("telemetry:stream", {"status": "ACTIVE", "fps": 120})
```

### 5. DuckDB & ClickHouse Vectorized Analytics
```python
# High-performance analytical columnar store
analytics = tin.connect("duckdb://metrics.db")

# Run vectorized SQL & insert metrics
analytics.execute("CREATE TABLE IF NOT EXISTS telemetry (timestamp TIMESTAMP, cpu REAL, ram REAL)")
analytics.table("telemetry").insert(cpu=88.4, ram=64.0)

# Reactive background live query (refreshes every 1.0s)
live_metrics = analytics.live_query("SELECT AVG(cpu) as avg_cpu FROM telemetry", interval=1.0)
```

### 6. Reactive Live Queries (`LiveQuery`)

Live queries re-evaluate automatically on any table mutation, updating subscribed UI widgets at 120 FPS with zero manual refresh loops:
```python
orders = pg_db.table("orders")

# Create LiveQuery Signal
active_orders = orders.live_query(status="pending")

# Bind directly to UI
with tin.Window(title="Live Order Queue"):
    tin.VirtualList(items=active_orders, item_height=50.0)
    tin.Button("Add Order", on_click=lambda: orders.insert(status="pending", item="Cyber Deck"))
```

### 7. Persistent Key-Value Store (`tin.use_store`)
Thread-safe disk-backed key-value store with reactive signal synchronization:
```python
store = tin.use_store("app_config.db", table="preferences")
store.set("theme", "cyber-dark")

# Mutating the signal automatically persists value to disk!
theme_signal = store.signal("theme", default="cyber-dark")
theme_signal.value = "neon-matrix"
```

### 8. Active Record Declarative Models (`@tin.model`)
```python
@tin.model
class DeviceNode:
    name: str
    platform: str
    fps_target: int = 120
    is_online: bool = True

node = DeviceNode.create(name="MacBook-Pro-M3", platform="macOS (Metal)")
all_online = DeviceNode.where(is_online=True).all()
live_nodes = DeviceNode.live_query(is_online=True)
```

---

## 🪄 Enterprise UI & Low-Code Declarative Suite (`DataGrid`, `AIChat`, `LiveDataTable` & `AutoCRUD`)

TinPyUI v1.7.0 brings a production-grade enterprise component suite to build mission-critical dashboards, AI applications, and data analytics tools in pure Python with zero external JavaScript dependencies.

### 1. Enterprise `DataGrid` (Virtualization, Sorting, Search & Export)
High-performance virtualized tabular grid with column sorting, real-time live search filtering, pagination, row selection, and 1-click CSV/JSON export:
```python
import tinpyui as tin

devices = [
    {"id": "SRV-01", "name": "Compute Node Alpha", "region": "us-east-1", "load": 42.1, "status": "ONLINE"},
    {"id": "SRV-02", "name": "Storage Gateway Beta", "region": "eu-central-1", "load": 88.5, "status": "WARN"},
    {"id": "SRV-03", "name": "Inference Pod Gamma", "region": "ap-northeast-1", "load": 15.0, "status": "ONLINE"},
    {"id": "SRV-04", "name": "Edge Relay Delta", "region": "us-west-2", "load": 95.2, "status": "CRITICAL"},
]

with tin.Window(title="Cluster Fleet Manager"):
    tin.Heading("Fleet Infrastructure Grid", size="h2")
    tin.DataGrid(
        columns=["id", "name", "region", "load", "status"],
        data=devices,
        page_size=10,
        searchable=True,
        sortable=True,
        selectable=True,
        exportable=True
    )
```

### 2. Streaming `AIChat` LLM Interface
Complete conversational AI interface with streaming token rendering, Markdown syntax highlighting, and copy buttons:
```python
import tinpyui as tin

chat_history = [
    {"role": "assistant", "content": "Welcome to **TinPyUI Engine**! How can I assist with your shaders today?"}
]

def on_user_prompt(user_text):
    # Process user query and stream LLM response
    chat_history.append({"role": "user", "content": user_text})
    chat_history.append({"role": "assistant", "content": f"Analyzing: `{user_text}`...\n```python\n# 120 FPS Native Canvas\ntin.run()\n```"})

with tin.Window(title="AI Assistant"):
    tin.AIChat(
        messages=chat_history,
        model_name="Tin-LLM v1.7",
        placeholder="Type a prompt or code question...",
        on_send=on_user_prompt
    )
```

### 3. Interactive `ColorPicker`, `DatePicker` & `Calendar`
Rich input widgets with reactive signal bindings:
```python
import tinpyui as tin

active_color = tin.Signal("#00f2fe")
active_date = tin.Signal("2026-09-16")

with tin.Window(title="Settings & Date Controls"):
    with tin.Row(gap=24):
        with tin.Column(gap=12):
            tin.Heading("Color Theme Picker", size="small")
            tin.ColorPicker(
                value=active_color,
                presets=["#00f2fe", "#9b51e0", "#ff007f", "#00ff88", "#121218"],
                show_alpha=True,
                on_change=lambda c: active_color.set(c)
            )

        with tin.Column(gap=12):
            tin.Heading("Event Date Selection", size="small")
            tin.DatePicker(
                value=active_date,
                placeholder="YYYY-MM-DD",
                date_format="YYYY-MM-DD",
                on_change=lambda d: active_date.set(d)
            )
            tin.Calendar(
                year=2026,
                month=9,
                selected_date="2026-09-16",
                on_select=lambda d: active_date.set(d)
            )
```

### 4. Declarative Vector `Chart` Suite (`LineChart`, `BarChart`, `DonutChart`, `Sparkline`)
Hardware-rendered vector SVG charts with vibrant gradients, reactive data bindings, and tooltips:
```python
import tinpyui as tin

# Telemetry data feeds
fps_feed = [118, 120, 119, 120, 117, 120, 120, 121]
revenue_quarters = [3400, 5200, 7800, 9400]
resource_split = [45, 30, 25]

with tin.Window(title="Real-Time Analytics"):
    with tin.Grid(cols=2, gap=20):
        # 1. Smooth Bezier Curve Line Chart
        tin.LineChart(data=fps_feed, labels=["0s", "1s", "2s", "3s", "4s", "5s", "6s", "7s"], height="220px")

        # 2. Dynamic Bar Chart
        tin.BarChart(data=revenue_quarters, labels=["Q1", "Q2", "Q3", "Q4"], height="220px")

        # 3. Donut Proportion Chart
        tin.DonutChart(data=resource_split, labels=["GPU", "RAM", "CPU"], colors=["#00f2fe", "#9b51e0", "#ff007f"])

        # 4. Compact Micro-Trend Sparkline
        tin.Sparkline(data=[10, 25, 18, 42, 60, 55, 80], colors=["#00ff88"], height="40px")
```

### 5. Hierarchical `TreeView` & `TreeNode`
Collapsible nested tree nodes for file systems, scene hierarchies, and categorised data:
```python
import tinpyui as tin

project_tree = [
    tin.TreeNode("src", "src/", icon="folder", expanded=True, children=[
        tin.TreeNode("core", "core/", icon="folder", children=[
            tin.TreeNode("engine", "engine.py", icon="file"),
            tin.TreeNode("signals", "signals.py", icon="file"),
        ]),
        tin.TreeNode("main", "main.tin", icon="file"),
    ]),
    tin.TreeNode("shaders", "shaders/", icon="folder", children=[
        tin.TreeNode("bloom", "bloom.frag", icon="shader"),
        tin.TreeNode("fog", "volumetric_fog.frag", icon="shader"),
    ]),
    tin.TreeNode("config", "tinpy.toml", icon="config")
]

with tin.Window(title="Project Explorer"):
    tin.TreeView(nodes=project_tree, on_select=lambda node: print(f"Selected: {node.label}"))
```

### 6. Low-Code `tin.LiveDataTable` & `tin.AutoCRUD`
Auto-discovers schema headers and binds directly to real-time database queries:
```python
# 1-Line Reactive Table
tin.LiveDataTable(pg_db.table("analytics_events"))

# 1-Line Complete Management Dashboard (Search, Add, Table, Delete)
tin.AutoCRUD(sqlite_db.table("devices"), title="Fleet Device Management Dashboard")
```

---

## 🎨 Extended Hardware GPU Shader Library

TinPyUI v1.7.0 includes an expanded suite of production-ready GLSL fragment shaders located in `shaders/`, validated at compile-time and hot-reloadable in real-time:

| Shader File | Visual Effect | Technique |
| :--- | :--- | :--- |
| `shaders/bloom.frag` | Luminescence Bloom & HDR Glow | Threshold isolation, dual-pass Gaussian blur sampling, additive composite blending |
| `shaders/cyber_mesh.frag` | Retro Cyberpunk Wireframe Matrix | Perspective 3D grid projection with sinusoidal vertex displacement & neon glow |
| `shaders/volumetric_fog.frag` | Cinematic Atmospheric Fog | Raymarched exponential light scattering with dynamic light extinction |
| `shaders/fluid_particles.frag` | Swirling Fluidic Particle Dust | Velocity vector field simulation with curling dissipation & chromatic aberration |
| `shaders/sdf_ui_box.frag` | Anti-Aliased Glassmorphism Card | Exact Signed Distance Field (SDF) evaluation with rounded corners and border glow |
| `shaders/uber_shader.frag` | Unified Multi-Pass Surface | Full PBR material pipeline with diffuse, roughness, and normal maps |

```python
# Load any built-in or custom GLSL shader into your background canvas
with tin.AnimatedBackground(effect="cyber_mesh", speed=1.2, primaryColor="#00f2fe", secondaryColor="#9b51e0"):
    tin.Heading("Hardware Shader Active", size="hero")
```

---

## 📡 Real-Time Streams & Sockets (`use_socket` & `use_sse`)

```python
import tinpyui as tin

# 1. Bi-directional WebSockets with reactive status & message signals
socket = tin.use_socket("wss://stream.telemetry.io/v1")

with tin.Window(title="Real-Time Stream"):
    tin.Text(text=lambda: f"Socket Status: {socket.status.value.upper()}")
    tin.Text(text=lambda: f"Telemetry Packet: {socket.message.value}", color="neon-cyan")
    tin.Button("Send Ping", on_click=lambda: socket.send("PING_HEARTBEAT"))

# 2. Server-Sent Events (SSE) Stream
stream_signal = tin.use_sse("https://events.example.com/live_feed")
tin.Text(text=stream_signal, color="neon-pink")
```

---

## 📱 Omni-Platform Packaging & Touch Gestures (Android, iOS, Desktop)

TinPyUI provides zero-copy C-FFI channels into native host OS dialogs, clipboard, hardware haptics, multi-touch gestures, and one-command standalone project exporters:

### 15.1 Native OS Platform Channels (`PlatformBridge`)
```python
import tinpyui as tin

# 1. Native File Dialogs
selected_file = tin.PlatformBridge.open_file_dialog()
save_destination = tin.PlatformBridge.save_file_dialog()

# 2. Desktop System Toast Notifications
tin.PlatformBridge.show_notification(title="Cluster Build", message="Compilation finished in 1.2ms")

# 3. Mobile / Touch Device Haptics
tin.PlatformBridge.vibrate(pattern_ms=60)
tin.haptics.vibrate(60)

# 4. OS Clipboard Sync
tin.PlatformBridge.copy_clipboard("tinpyui_v17_auth_token_8892")

# 5. System Theme Query
current_theme = tin.PlatformBridge.get_system_theme() # "dark" | "light"
```

### 15.2 Mobile Touch & Gesture Recognizers
TinPyUI's runtime includes built-in high-frequency touch recognizers:
- **Pinch-to-Zoom (`tin:pinch`)**: Tracks 2-finger pinch interactions with scale factor and focal center.
- **Directional Swipe (`tin:swipe`)**: Dispatches directional swipe vectors (`left`, `right`, `up`, `down`).
- **Pull-to-Refresh (`tin:pullrefresh`)**: Rubber-band pull resistance with animated glow and haptic pulse.

```javascript
// Listening to native gestures in custom JavaScript or components:
window.addEventListener("tin:swipe", (e) => {
    console.log("Swiped:", e.detail.direction, "Distance:", e.detail.distance);
});

window.addEventListener("tin:pinch", (e) => {
    console.log("Pinch scale factor:", e.detail.scale);
});

window.addEventListener("tin:pullrefresh", (e) => {
    console.log("Pull to refresh triggered!");
});
```

### 15.3 Apple iOS Native Xcode Packaging Pipeline
Generate a production-ready Apple iOS Xcode project complete with `WKWebView`, Swift haptic feedback bridge, retina display scaling, and safe-area insets:
```bash
# Via CLI:
tinpyui build --ios --app-name "CyberApp" --bundle-id "com.corp.cyberapp"

# Or directly in Python:
tin.export_ios(app_name="CyberApp", bundle_id="com.corp.cyberapp")
```
This produces:
- `CyberApp.xcodeproj/project.pbxproj` (valid Xcode bundle)
- `AppDelegate.swift`, `SceneDelegate.swift`, `ViewController.swift`
- `Info.plist` with required bundle permissions
- `www/` directory with embedded WebAssembly engine and compiled IR

### 15.4 Android Standalone Gradle & APK Export
```bash
# Export Android Gradle project and optionally compile debug APK:
tinpyui build --mobile --app-name "CyberApp" --package "com.corp.cyberapp" --apk

# Or directly in Python:
tin.export_android(app_name="CyberApp", package_name="com.corp.cyberapp")
```

### 15.5 Standalone Native Desktop Bundling
```bash
# Package standalone desktop executable bundle (Windows .exe, macOS, Linux):
tinpyui build --desktop --app-name "CyberApp"
```

---


## 🔒 Enterprise Security & Hardware Telemetry Suite

TinPyUI is engineered with security-first constraints:

1. **In-Memory RAM Masking**: `tin.RAMMaskedState` and `tin.EncryptedState` protect sensitive passwords and API tokens in RAM against memory scraping.
2. **Session Binding Guard**: High-entropy HMAC-SHA256 signatures validate session authenticity against replay attacks.
3. **Decoy Network Traffic**: `tin.HoneypotAPI.start_decoy_traffic()` generates synthetic background traffic to confound network inspection.
4. **Hardware Fingerprinting**: `tin.Security.get_device_fingerprint()` generates unique hardware identification hashes.
5. **Live Performance Telemetry**: `tin.PerformanceMonitor` measures 120 FPS frame latency, render bottlenecks, and memory usage.
6. **Compile-Time GLSL Validator**: `glsl_validator.go` scans shader ASTs ahead-of-time to prevent GPU memory crashes and infinite loops.
7. **Panic-Proof WASM Boundary**: The WebAssembly runtime wraps rendering in panic-recovery middleware, guaranteeing that runtime errors never crash the host web page.

---

## 🧠 Intermediate Representation (IR) Compiler & Dynamic Export (`app.export_ir`)

### Dynamic Python to WebAssembly Export
Compile pure Python UI trees directly into static Intermediate Representation JSON (`app.ir.json`) for serverless CDN hosting:

```python
import tinpyui as tin

app = tin.Window(title="WASM Edge Application", width=1280, height=800)
with app:
    with tin.Section(padding=24):
        tin.Heading("Compiled Edge App", size="hero")
        tin.GradientText("Hardware-Accelerated WebAssembly", gradient=["#00f2fe", "#9b51e0"])
        tin.Button("Launch Cluster", variant="primary")

# Exports deterministic IR blueprint to public/ distribution folder
app.export_ir("public/app.ir.json")
```

### Generated `app.ir.json` Schema:
```json
{
  "title": "WASM Edge Application",
  "width": 1280,
  "height": 800,
  "bg_color": "#0D0D10",
  "root": {
    "tag": "Window",
    "props": {"title": "WASM Edge Application"},
    "children": [
      {
        "tag": "Section",
        "props": {"padding": 24},
        "children": [
          {"tag": "Heading", "props": {"text": "Compiled Edge App", "size": "hero"}, "children": []},
          {"tag": "GradientText", "props": {"text": "Hardware-Accelerated WebAssembly"}, "children": []},
          {"tag": "Button", "props": {"text": "Launch Cluster", "variant": "primary"}, "children": []}
        ]
      }
    ]
  }
}
```

## 🖥️ How to Compile `.tin` Code on Every OS (Windows, macOS, Linux)

TinPyUI source files (`.tin`) compile into a deterministic Intermediate Representation (`.ir.json`) and optional pre-rendered static HTML hydration shells (`.html`).

```
+-----------------------------------------------------------------------------------+
|                        CROSS-PLATFORM COMPILATION PIPELINE                        |
+-----------------------------------------------------------------------------------+
|  [ index.tin Source ]                                                             |
|           │                                                                       |
|           ▼                                                                       |
|  [ TinPyUI Go / NPM Compiler ] ──(Windows / macOS / Linux)                        |
|           │                                                                       |
|           ├──▶ [ index.ir.json / app.ir.json ]  ──▶ Consumed by tinui_engine.wasm |
|           └──▶ [ index.html ] (with --hydrate) ──▶ SEO Static Pre-Rendered DOM    |
+-----------------------------------------------------------------------------------+
```

---

### 🪟 1. Compiling on Windows (10 & 11)

Open **PowerShell**, **Command Prompt (CMD)**, or **Windows Terminal**:

#### Option A: Using the Compiled Binary (`tinui.exe`)
```powershell
# Standard compilation -> outputs index.ir.json
.\tinui.exe compile index.tin

# Compilation with static SEO HTML hydration -> outputs index.ir.json & index.html
.\tinui.exe compile index.tin --hydrate

# Live Dev Server with Hot Reload on http://localhost:8080
.\tinui.exe dev index.tin
```

#### Option B: Using Go Directly from Source
```powershell
go run main.go compile index.tin
go run main.go compile index.tin --hydrate
go run main.go dev index.tin
```

#### Option C: Using the Global NPM CLI
```powershell
npm install -g tinpyui
tinpyui compile index.tin
tinpyui compile index.tin --hydrate
```

#### Building the Windows Compiler Binary from Source:
```powershell
go build -o tinui.exe .
```

---

### 🍎 2. Compiling on macOS (Apple Silicon M1/M2/M3/M4 & Intel)

Open **Terminal** (Zsh or Bash):

#### Option A: Using the Standalone Binary (`tinui`)
```bash
# Ensure execution permissions
chmod +x ./tinui

# Standard compilation -> outputs index.ir.json
./tinui compile index.tin

# Compilation with static SEO HTML hydration -> outputs index.ir.json & index.html
./tinui compile index.tin --hydrate

# Live Dev Server with Hot Reload on http://localhost:8080
./tinui dev index.tin
```

#### Option B: Using Go Directly from Source
```bash
go run main.go compile index.tin
go run main.go compile index.tin --hydrate
go run main.go dev index.tin
```

#### Option C: Using the Global NPM CLI
```bash
npm install -g tinpyui
tinpyui compile index.tin
tinpyui compile index.tin --hydrate
```

#### Building the macOS Compiler Binary from Source:
```bash
go build -o tinui .
chmod +x tinui
```

---

### 🐧 3. Compiling on Linux (Ubuntu, Debian, Fedora, Arch, Alpine)

Open your preferred Linux **terminal**:

#### Option A: Using the Standalone Binary (`tinui`)
```bash
# Ensure execution permissions
chmod +x ./tinui

# Standard compilation -> outputs index.ir.json
./tinui compile index.tin

# Compilation with static SEO HTML hydration -> outputs index.ir.json & index.html
./tinui compile index.tin --hydrate

# Live Dev Server with Hot Reload on http://localhost:8080
./tinui dev index.tin
```

#### Option B: Using Go Directly from Source
```bash
go run main.go compile index.tin
go run main.go compile index.tin --hydrate
go run main.go dev index.tin
```

#### Option C: Using the Global NPM CLI
```bash
npm install -g tinpyui
tinpyui compile index.tin
tinpyui compile index.tin --hydrate
```

#### Building the Linux Compiler Binary from Source:
```bash
go build -o tinui .
chmod +x tinui
```

---

### 🌐 4. Compiling the WebAssembly Engine (`tinui_engine.wasm`) on Any OS

To rebuild the core WebAssembly runtime from Go source:

#### On Windows (PowerShell):
```powershell
$env:GOOS="js"; $env:GOARCH="wasm"; go build -ldflags="-s -w" -o tinui_engine.wasm ./wasm_engine
```

#### On macOS & Linux (Bash / Zsh):
```bash
GOOS=js GOARCH=wasm go build -ldflags="-s -w" -o tinui_engine.wasm ./wasm_engine
```

---

### ⚙️ 5. Unified CLI Reference

| What You Want to Do | The One Command | Genuine Technical Action |
| :--- | :--- | :--- |
| **Create Project** | `tinpyui new <app>` | Scaffolds beginner-friendly project structure (`main.tin`, `scenes/`, `shaders/`, `public/`, `tinpy.toml`). |
| **Interactive REPL** | `tinpyui repl` | Boots interactive Python shell with `tin`, `db`, `Signal`, and `State` preloaded for live debugging and testing. *(Alias: `tinpyui shell`)* |
| **Run Desktop App** | `tinpyui run main.tin` | Mmaps 4MB anonymous shared memory, packs 16-byte structs, and executes native C++ desktop host. *(Shorthand: `tinpyui main.tin`)* |
| **Run Live Web Server** | `tinpyui run main.tin --web` | Spawns local dev server on `http://localhost:8080` with SSE file watching, Hot GLSL Reloading & crash overlay. *(Alias: `tinpyui dev`)* |
| **Export Android App** | `tinpyui build --mobile` | Generates standalone Android Studio / Gradle project with WebGL & Haptics into `build/mobile/android/` (alias: `tinui export mobile`). |
| **Export Apple iOS App** | `tinpyui build --ios` | Generates standalone Apple iOS Xcode project (`.xcodeproj`, `WKWebView`, Swift haptic bridge) into `build/mobile/ios/`. |
| **Build Desktop App** | `tinpyui build --desktop` | Compiles or stages a standalone native desktop distribution bundle into `build/desktop/`. |
| **Build Web Bundle** | `tinpyui build --web` | Compiles static production bundle into `dist/` ready for CDN hosting (Netlify, Vercel, S3, Cloudflare Pages). |

---

## 🛠️ CLI Workflows, Interactive REPL & Live Reload

```bash
# 1. Scaffold a new application with friendly interactive wizard
tinpyui new my_app
cd my_app

# 2. Launch interactive Python REPL & State Inspector
tinpyui repl

# 3. Run instant native desktop window (sub-millisecond shared memory)
tinpyui run main.tin

# 4. Or launch live dev server with SSE Hot Reloading on http://localhost:8080
tinpyui run main.tin --web

# 5. Export standalone Apple iOS Xcode project
tinpyui build --ios --app-name "CyberApp" --bundle-id "com.corp.cyberapp"

# 6. Export standalone Android Gradle project & compile debug APK
tinpyui build --mobile --app-name "CyberApp" --package "com.corp.cyberapp" --apk

# 7. Build standalone native desktop executable bundle
tinpyui build --desktop --app-name "CyberApp"

# 8. Build static production WebAssembly bundle for CDN hosting
tinpyui build --web
```




---

## 🚀 Production Deployment & Backend Integration

### 1. Python Flask / FastAPI Integration
TinPyUI apps compile into static assets (`index.html`, `tin-runtime.js`, `wasm_exec.js`, `tinui_engine.wasm`, `app.ir.json`) that can be hosted on any web server:

```python
from flask import Flask, send_from_directory

app = Flask(__name__, static_folder='public')

@app.route('/')
def index():
    return send_from_directory(app.static_folder, 'index.html')

@app.route('/<path:path>')
def static_files(path):
    return send_from_directory(app.static_folder, path)

if __name__ == '__main__':
    print("[TinPyUI] Serving on http://localhost:5000")
    app.run(port=5000)
```

### 2. Static CDN Hosting (Vercel, Cloudflare Pages, Netlify, AWS S3)
Deploy the `public/` directory directly to any static web host. Ensure that your web server serves `.wasm` files with the `Content-Type: application/wasm` MIME type header.

---

## 🌟 Full-Stack Production Master Blueprint

Below is an end-to-end production script combining **PostgreSQL/MongoDB connectivity**, **WebSocket streams**, **Spring physics**, **1-Line AutoCRUD**, and **Hardware Haptics**:

```python
import tinpyui as tin

# 1. Connect to Database with dynamic schema creation
db = tin.connect("sqlite:///production_fleet.db")
devices = db.table("devices")

# 2. Real-Time Telemetry Socket
telemetry_ws = tin.use_socket("wss://echo.websocket.events")

# 3. Persistent Settings Store
settings = tin.use_store("user_settings.db")
theme_signal = settings.signal("theme", default="cyber-dark")

# 4. Symplectic Euler Spring Solver (120 FPS)
spring = tin.Spring(tension=180.0, friction=20.0)
spring_pos = tin.Signal(0.0)

def step_physics():
    spring.target = 150.0 if spring.target == 0.0 else 0.0
    spring_pos.set(round(spring.step(1.0 / 120.0), 2))
    tin.PlatformBridge.vibrate(40)

# 5. Declarative UI Window
app = tin.Window(title="Omni-Platform Enterprise Console", width=1400, height=880)
with app:
    with tin.Row(padding=20, gap=20):
        # Left Panel: Telemetry & Controls
        with tin.Column(width=420, gap=16):
            tin.GradientText("CYBER TELEMETRY", gradient=["neon-cyan", "neon-purple"], size="h2")
            
            with tin.Card(padding=16, bg="rgba(18, 22, 34, 0.8)", radius=12):
                tin.Text(text=lambda: f"● Socket Status: {telemetry_ws.status.value.upper()}", color="neon-cyan")
                tin.Text(text=lambda: f"Feed: {telemetry_ws.message.value or 'Awaiting stream...'}")
                tin.Spacer(height=10)
                tin.Button("Send Heartbeat", on_click=lambda: telemetry_ws.send("PING_TELEMETRY"))

            with tin.Card(padding=16, bg="rgba(24, 20, 32, 0.8)", radius=12):
                tin.Heading("Spring Physics Simulator (120 FPS)", size="small")
                tin.Text(text=lambda: f"Displacement: {spring_pos.value} px", color="neon-pink")
                tin.Spacer(height=8)
                tin.Button("🚀 Trigger Spring Step", on_click=step_physics, variant="primary")

        # Right Panel: 1-Line Reactive AutoCRUD Dashboard
        with tin.Column(width="flex", gap=16):
            tin.AutoCRUD(devices, title="Live Fleet Device Management")

if __name__ == "__main__":
    tin.run(app)
```

---

## 🤝 Contributing to TinPyUI

We welcome contributions from developers worldwide! Whether you're building new UI components, writing WebGPU/WebGL shaders, optimizing compiler AST passes, improving documentation, or adding database adapters, you are invited to participate.

### 🌟 Quickstart for Contributors

```bash
# 1. Clone your fork
git clone https://github.com/<your-username>/TinUi.git
cd TinUi

# 2. Verify local environment & run test suite
# On Windows:
dev.bat test

# On Linux / macOS / Git Bash:
make test
```

### 📚 Contributor Resources & Guides

| Document | Purpose |
| :--- | :--- |
| 📘 **[CONTRIBUTING.md](CONTRIBUTING.md)** | Full guide on dev setup, code style, Conventional Commits, and PR submission |
| 📜 **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** | Contributor Covenant v2.1 community standards |
| 🗺️ **[ROADMAP.md](ROADMAP.md)** | Active milestones, planned features, and Good First Issues |
| 🏛️ **[GOVERNANCE.md](GOVERNANCE.md)** | Project roles, maintainer pathways, and RFC proposal lifecycle |
| 🛡️ **[SECURITY.md](SECURITY.md)** | Vulnerability reporting procedure and supported versions |

---

## 📄 License

MIT License © 2026 Barathanandh

