luxaura 1.0.0 → 1.0.2

package/README.md

@@ -1,37 +1,64 @@
 # Luxaura Framework
 
-> **Intent-Based Full-Stack Web Framework** — build complete apps with `.lux` files.
+> **The Intent-Driven Full-Stack Web Framework.**
+> Not React. Not Vue. Not Angular. Not Next.js. Just Luxaura.
 
-[![Version](https://img.shields.io/badge/version-1.0.0-6c63ff)](#)
+[![Version](https://img.shields.io/badge/version-2.0.0-6c63ff)](#)
+[![Tests](https://img.shields.io/badge/tests-109%20passing-brightgreen)](#)
 [![License](https://img.shields.io/badge/license-MIT-green)](#)
-[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](#)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-blue)](#)
 
 ---
 
-## What is Luxaura?
-
-Luxaura is a full-stack web framework where you describe **what** you want — not how to build it. A single `.lux` file contains your UI, state, styles, and backend logic. The compiler handles the rest.
-
-```yaml
-# counter.lux
-
-state
-    count: 0
-
-style
-    self
-        padding: 8
-    Action
-        radius: medium
-        background: #6c63ff
-
-view
-    Box
-        Title "Counter: {count}"
-        Action "Increment"
-            on click:
-                count = count + 1
-```
+## Why Luxaura is Different
+
+Every concept, every keyword, every folder name was designed from scratch.
+
+| Concept | React / Vue / Next | Luxaura |
+|---|---|---|
+| Create project | `npm create vite` / `ng new` | `luxaura release` |
+| Start dev server | `npm run dev` / `ng serve` | `luxaura ignite` |
+| Production build | `npm run build` | `luxaura forge` |
+| Add a library | `npm install` | `luxaura bring` |
+| Make a component | `ng generate component` | `luxaura component` |
+| Route files live in | `/pages` (Next.js) | `/scenes` |
+| Components live in | `/components` | `/craft/<Name>/` |
+| Server logic lives in | `/api` / `.server.js` | `/services/` |
+| Static files | `/public` | `/media` |
+| Build output | `/dist` | `/depot` |
+| Reactive data | `state` / `data()` | `signal` |
+| External inputs | `props` | `receive` |
+| Server code block | `server` | `vault` |
+| Styles block | `style` | `paint` |
+| UI template | `template` / `view` | `canvas` |
+| Binding syntax | `{var}` / `{{ var }}` | `<<var>>` |
+| Event syntax | `@click` / `on:click` | `when click:` |
+| Button element | `<button>` / `Action` | `Trigger` |
+| Text input | `<input>` / `Input` | `Field` |
+| Paragraph | `<p>` / `Text` | `Body` |
+| Heading | `<h1>` / `Title` | `Headline` |
+| Image | `<img>` / `Image` | `Picture` |
+| Nav bar | `<nav>` / `Nav` | `Ribbon` |
+| Sidebar | `<aside>` / `Sidebar` | `Drawer` |
+| Footer | `<footer>` / `Footer` | `Anchor` |
+| Card container | `Card` | `Plate` |
+| List | `<ul>` / `List` | `Roster` |
+| List item | `<li>` / `ListItem` | `Entry` |
+| Badge/tag | `Badge` | `Mark` |
+| Box-shadow style | `shadow: soft` | `glow: soft` |
+| Padding style | `padding: 4` | `breathe: 4` |
+| Margin style | `margin: 4` | `push: 4` |
+| Border radius | `radius: large` | `curve: round` |
+| Text color | `color: #fff` | `ink: #fff` |
+| Background | `background: #000` | `fill: #000` |
+| Font size | `fontSize: xl` | `size: xlarge` |
+| Font weight | `fontWeight: bold` | `weight: strong` |
+| Notification | toast | `flash` |
+| Storage wrapper | `localStorage` | `stash` |
+| HTTP helper | `fetch` / `axios` | `reach` |
+| Auth helper | `auth` | `gate` |
+| Mount component | `.mount()` | `.launch()` |
+| CSS utilities | `lux-` prefix | `lx-` prefix |
 
 ---
 
@@ -41,299 +68,429 @@ view
 npm install -g luxaura
 ```
 
-Or use it as a project dependency:
-
-```bash
-npm install luxaura
-```
-
 ---
 
 ## Quick Start
 
 ```bash
-# 1. Create a new project
-luxaura new my-app
-
-# 2. Enter the project
+luxaura release my-app
 cd my-app
-
-# 3. Start the dev server (HMR enabled)
-luxaura run
+luxaura ignite
 ```
 
-Open `http://localhost:3000` — your app is live.
+Open `http://localhost:3000` — your start scene loads with a full how-to guide built in.
+
+---
+
+## Project Structure
+
+```
+my-app/
+├── luxaura.config          ← app config (identity, theme, db, mode)
+├── scenes/                 ← route entry points  (NOT "pages")
+│   └── index.lux           ← home scene
+├── craft/                  ← all components      (NOT "components" or "modules")
+│   └── Ribbon/
+│       ├── Ribbon.lux
+│       ├── Ribbon.paint.css
+│       └── index.js
+├── services/               ← vault-only logic    (NOT "api" or "server")
+│   └── index.js
+├── media/                  ← static files        (NOT "public" or "assets")
+└── depot/                  ← build output        (NOT "dist")
+    ├── public/             ← client assets
+    └── vault/              ← server modules (NEVER publicly served)
+```
 
 ---
 
 ## CLI Reference
 
-| Command | Description |
-|---|---|
-| `luxaura new <name>` | Create a new project with the full folder structure |
-| `luxaura run` | Start the dev server with Hot Module Replacement |
-| `luxaura build` | Compile for production (splits client/server code) |
-| `luxaura install <lib>` | Install a CSS/JS library (e.g. Tailwind, Bootstrap) |
-| `luxaura generate <type> <name>` | Scaffold a `component`, `page`, or `api` |
-| `luxaura format` | Auto-fix `.lux` file indentation |
-| `luxaura secure` | Scan for XSS, SQL injection, and server-leak risks |
+```bash
+luxaura release <n>        # Bootstrap a new project
+luxaura ignite                # Start dev server + live reload
+luxaura ignite --port 8080    # Custom port
+luxaura forge                 # Build for production
+luxaura component <n>      # Create a component  → craft/<n>/
+luxaura service <n>        # Create a vault service → services/
+luxaura module <n>         # Create a shared module → craft/<n>/
+luxaura bring <lib>           # Add an external library
+luxaura polish                # Auto-format all .lux files
+luxaura shield                # Security scan (XSS, SQL injection, vault leaks)
+luxaura help_me               # Full interactive CLI guide
+```
 
 ---
 
-## .lux File Anatomy
+## The .lux File
 
-Every `.lux` file has five blocks:
+Every `.lux` file has five blocks. All block names are unique to Luxaura:
 
 ```yaml
-# 1. PROPS — inputs from parent components
-props
-    title: String
+# MyScene.lux
+
+# 1. receive — inputs from outside  (NOT "props")
+receive
+    title: String = "Hello"
     count: Number = 0
 
-# 2. STATE — reactive internal data
-state
+# 2. signal — reactive internal data  (NOT "state" or "data")
+signal
+    clicks: 0
     name: "World"
-    active: false
 
-# 3. SERVER — backend logic (Node.js). NEVER sent to browser.
-server
-    import db from "luxaura/db"
-    def saveUser(name):
-        return db.insert("users", { name })
+# 3. vault — server-only logic  (NOT "server" block)
+vault
+    pull db from "luxaura/db"
+
+    action saveClick(n):
+        return db.insert("clicks", { n, ts: "NOW()" })
 
-# 4. STYLE — smart properties + CSS
-style
+# 4. paint — smart styling  (NOT "style")
+paint
     self
-        padding: 6
-        shadow: soft
-    Title
-        fontSize: 2xl
-        fontWeight: bold
-
-# 5. VIEW — UI component tree
-view
-    Container
-        Title "{title}"
-        Text "Hello, {name}!"
-        Action "Save"
-            on click:
-                await server.saveUser(name)
+        breathe: 8
+        fill: #0d0d1a
+    Headline
+        size: titan
+        weight: heavy
+        ink: #ffffff
+    Trigger
+        curve: pill
+        glow: soft
+
+# 5. canvas — UI composition  (NOT "view" or "template")
+canvas
+    Scene
+        Stack
+            Headline "<<title>>"
+            Body "Hello, <<name>>!"
+            Trigger "Click me"
+                when click:
+                    await vault.saveClick(clicks)
+            Body "Clicks: <<clicks>>"
 ```
 
 ---
 
-## Semantic Components
+## Canvas Node Vocabulary
+
+No HTML tags. No generic names. Every node has a Luxaura-specific name:
 
-No HTML tags. Use intent-based components:
+### Layout
+| Node | Purpose |
+|---|---|
+| `Frame` | Generic block wrapper |
+| `Strip` | Horizontal flex row |
+| `Stack` | Vertical flex column |
+| `Mosaic` | Auto-responsive grid |
+| `Scene` | Max-width centered wrapper |
+
+### Navigation
+| Node | Purpose |
+|---|---|
+| `Ribbon` | Top navigation bar |
+| `Drawer` | Side panel |
+| `Anchor` | Footer bar |
+| `Crown` | Page header |
+| `Chapter` | Content section |
+
+### Content
+| Node | Purpose |
+|---|---|
+| `Headline` | Heading (auto-selects h1–h6 by nesting depth) |
+| `Body` | Paragraph text |
+| `Picture` | Image (auto-lazy loaded) |
+| `Glyph` | Icon holder |
+| `Mark` | Badge / tag |
+| `Plate` | Card surface |
+| `Snippet` | Inline code |
+| `Block` | Code block |
+
+### Interaction
+| Node | Purpose |
+|---|---|
+| `Trigger` | Button / clickable action |
+| `Field` | Text input |
+| `Vessel` | Form wrapper |
+| `Toggle` | Checkbox / switch |
+| `Pathway` | Navigation link |
+
+### Data
+| Node | Purpose |
+|---|---|
+| `Grid` | Data table |
+| `Roster` | List |
+| `Entry` | List item |
+| `Splitter` | Horizontal divider |
 
-| Category | Components |
+### Overlay
+| Node | Purpose |
 |---|---|
-| **Layout** | `Box`, `Row`, `Column`, `Grid`, `Container` |
-| **Navigation** | `Nav`, `Sidebar`, `Footer`, `Header` |
-| **Content** | `Title`, `Text`, `Image`, `Icon`, `Badge` |
-| **Interaction** | `Action`, `Input`, `Form`, `Switch`, `Link` |
-| **Data** | `Table`, `List`, `ListItem` |
-| **Overlay** | `Modal`, `Overlay`, `Card` |
+| `Curtain` | Modal overlay |
+| `Popup` | Modal content |
 
 ---
 
-## Smart Style Properties
+## Paint Smart Tokens
+
+Luxaura's styling system uses intent-based tokens — no CSS property names exposed:
 
 ```yaml
-style
+paint
     self
-        padding: 4          # → padding: 16px (4 × 4px base)
-        shadow: soft        # → box-shadow: 0 2px 12px rgba(...)
-        radius: large       # → border-radius: 16px
-        fontSize: xl        # → font-size: 1.5rem
-        fontWeight: bold    # → font-weight: 700
+        breathe: 6       # padding: 24px  (6 × 4px)
+        push: 4          # margin: 16px
+        gap: 4           # gap: 16px between children
+        fill: #0d0d1a    # background color
+        ink: #ffffff     # text color
+        glow: soft       # box-shadow (whisper/soft/loud/neon)
+        curve: round     # border-radius (gentle/smooth/round/pill)
+        size: titan      # font-size (tiny/small/base/large/xlarge/huge/titan/mega)
+        weight: heavy    # font-weight (feather/light/normal/firm/strong/heavy)
+        wide: 400        # width: 400px
+        tall: 200        # height: 200px
+        pointer: true    # cursor: pointer
 ```
 
-Available tokens:
-- **shadow**: `none`, `soft`, `medium`, `hard`
-- **radius**: `none`, `small`, `medium`, `large`, `full`
-- **fontSize**: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`
-- **fontWeight**: `thin`, `light`, `normal`, `medium`, `bold`, `black`
+### Glow tokens
+| Token | Result |
+|---|---|
+| `glow: whisper` | `box-shadow: 0 2px 10px rgba(0,0,0,0.07)` |
+| `glow: soft` | `box-shadow: 0 4px 20px rgba(0,0,0,0.11)` |
+| `glow: loud` | `box-shadow: 0 8px 32px rgba(0,0,0,0.22)` |
+| `glow: neon` | `box-shadow: 0 0 28px rgba(108,99,255,0.5)` |
+
+### Curve tokens
+| Token | Result |
+|---|---|
+| `curve: gentle` | `border-radius: 4px` |
+| `curve: smooth` | `border-radius: 8px` |
+| `curve: round` | `border-radius: 16px` |
+| `curve: pill` | `border-radius: 9999px` |
+
+### Size tokens
+`tiny` · `small` · `base` · `large` · `xlarge` · `huge` · `titan` · `mega`
+
+### Weight tokens
+`feather` · `light` · `normal` · `firm` · `strong` · `heavy`
 
 ---
 
-## The Vault (Backend Security)
+## The Vault (Server Security)
 
-Code in the `server` block runs **exclusively on the server**. The compiler strips it completely from the client bundle.
+`vault` blocks run exclusively on the server. The compiler performs **code stripping** — zero vault code reaches the browser.
 
 ```yaml
-server
-    import db from "luxaura/db"
+vault
+    pull db from "luxaura/db"
 
-    def getUser(id):
-        # This code NEVER reaches the browser
+    action getUser(id):
         return db.query("SELECT * FROM users WHERE id = ?", [id])
 ```
 
-Frontend calls it naturally:
+Call it from canvas:
 
 ```yaml
-view
-    Action "Load User"
-        on click:
-            result = await server.getUser(userId)
+canvas
+    Trigger "Load User"
+        when click:
+            result = await vault.getUser(userId)
 ```
 
-Features:
-- **Auto-CSRF**: Every RPC request is signed with a rotating token
-- **Auto-Sanitization**: String inputs are sanitized before processing
-- **Code Stripping**: Build verifiably excludes server code from `dist/client`
+Security features:
+- **Auto-token**: Every vault request is signed with a rotating session token
+- **Auto-sanitize**: String inputs are sanitized before processing
+- **Code stripping**: The build verifiably excludes vault code from `depot/public`
+- **Shield scan**: `luxaura shield` detects vault leaks, XSS, and SQL injection patterns
 
 ---
 
-## The Physics Engine (Auto-Responsiveness)
-
-Layouts adapt automatically without media queries:
-
-- `Row` → stacks to `Column` on mobile
-- Buttons/inputs auto-enlarge to 44px touch targets on mobile
-- `Image` with `responsive: true` never overflows its container
-- `Nav` auto-collapses on small screens
-
----
+## Component Structure
 
-## Utility Classes
+Every component gets its own folder — not a single file:
 
-```html
-<!-- In your .lux view or class: attributes -->
-class: "lux-flex lux-center lux-gap-4"
-class: "lux-text-xl lux-font-bold lux-text-primary"
-class: "lux-card lux-shadow-lg lux-rounded-lg"
+```
+craft/
+└── UserCard/
+    ├── UserCard.lux        ← the canvas (UI)
+    ├── UserCard.paint.css  ← scoped styles
+    └── index.js            ← optional JS bridge / exports
 ```
 
-Full class list available in `luxaura.min.css`.
-
----
+Create one with: `luxaura component UserCard`
 
-## Modules (Built-in API)
+The generated `.lux` file has a styled big title by default:
 
 ```yaml
-server
-    import db      from "luxaura/db"      # Database queries
-    import router  from "luxaura/router"  # Navigation
-    import http    from "luxaura/http"    # External API calls
-    import auth    from "luxaura/auth"    # Authentication
-    import storage from "luxaura/storage" # localStorage wrapper
+canvas
+    Frame
+        Stack
+            Headline "I'm UserCard component !!"
+            Body "I live in craft/UserCard/UserCard.lux — edit me!"
 ```
 
 ---
 
-## Headless Mode
+## Vault Services
 
-Use Luxaura as a frontend-only framework, proxying to any backend:
+Services are server-only modules. They live in `/services/` and are called from vault blocks:
 
-```
-# luxaura.config
-mode: headless
-proxy: http://localhost:8080
+```javascript
+// services/User.service.js
+async function getUser(id) { ... }
+async function createUser(data) { ... }
+module.exports = { getUser, createUser };
 ```
 
-API requests are automatically forwarded to your existing backend.
+Create one with: `luxaura service User`
 
 ---
 
-## Plugin System
+## Binding Syntax: `<<varName>>`
 
-```bash
-luxaura install tailwindcss
-luxaura install bootstrap
+Luxaura uses double angle brackets — not `{var}` (Angular/Svelte), not `{{ var }}` (Vue/Handlebars):
+
+```yaml
+canvas
+    Headline "<<pageTitle>>"
+    Body "Welcome, <<userName>>!"
+    Mark "<<status>>"
 ```
 
-Then use classes directly in your `.lux` views:
+---
+
+## Event Syntax: `when <event>:`
+
+Not `@click` (Vue), not `on:click` (Svelte), not `onClick` (React):
 
 ```yaml
-view
-    Box
-        Action "Submit"
-            class: "bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
+canvas
+    Trigger "Save"
+        when click:
+            await vault.save(formData)
+
+    Field kind:"email"
+        when input:
+            email = this.value
 ```
 
 ---
 
-## Project Structure
+## Vault Block Syntax
 
-```
-my-app/
-├── luxaura.config        # Global config (theme, db, mode)
-├── assets/               # Images, fonts (auto-optimized)
-├── pages/                # Route entry points (index.lux, about.lux)
-├── modules/              # Reusable components (Navbar.lux, Card.lux)
-├── server/               # Shared server utilities
-└── dist/
-    ├── client/           # Public assets (HTML, JS, CSS)
-    └── server/           # Secure server modules (Vault)
+Not `def` (Python-style), not `export async function`:
+
+```yaml
+vault
+    pull db from "luxaura/db"       # (not "import db from")
+
+    action getItems(userId):         # (not "def" or "function")
+        return db.query("SELECT * FROM items WHERE user_id = ?", [userId])
+
+    action createItem(data):
+        return db.insert("items", data)
 ```
 
 ---
 
-## Programmatic API
+## Runtime API
 
 ```javascript
-const luxaura = require('luxaura');
+// Launch a scene (not "mount")
+window.__Lux__.launch('MyScene', '#lux-stage');
+
+// Flash notifications (not "toast")
+__Lux__.flash.ok('Saved!');
+__Lux__.flash.fail('Something went wrong');
+__Lux__.flash.warn('Check your input');
+__Lux__.flash.info('Loading...');
+
+// Theme
+__Lux__.theme.set('dark');
+__Lux__.theme.toggle();
+
+// Navigate
+__Lux__.navigate('/about');
+
+// Reach (HTTP requests — not "fetch" or "axios")
+const data = await __Lux__.reach.fetch('https://api.example.com/items');
+await __Lux__.reach.send('https://api.example.com/items', { name: 'New item' });
+
+// Stash (storage — not "localStorage" directly)
+__Lux__.stash.local.write('key', 'value');
+__Lux__.stash.local.read('key');
+__Lux__.stash.session.write('key', 'value');
+
+// Gate (auth — not "auth")
+await __Lux__.gate.enter({ email, password });
+await __Lux__.gate.leave();
+const user = await __Lux__.gate.whoami();
+```
 
-// Parse a .lux file
-const ast = luxaura.parse(source, 'MyComponent.lux');
+---
 
-// Compile AST to JS/CSS/HTML
-const output = luxaura.compile(ast, { componentName: 'MyComponent' });
+## CSS Utility Classes
 
-console.log(output.clientJS);  // Client bundle
-console.log(output.serverJS);  // Server vault module
-console.log(output.css);       // Component styles
-console.log(output.html);      // HTML shell
+All utility classes use the `lx-` prefix (not `lux-`, which is reserved for node base classes):
 
-// One-shot transform
-const output2 = luxaura.transform(source, 'MyComponent.lux');
+```html
+class: "lx-flex lx-center lx-gap4"
+class: "lx-titan lx-heavy lx-ink-pulse"
+class: "lx-curve-round lx-glow-soft lx-fill-pulse"
+class: "lx-w-full lx-min-screen"
 ```
 
 ---
 
-## Runtime JavaScript API
+## Headless Mode
 
-```javascript
-// Mount a component
-const ctx = window.__Lux__.mount('MyApp', '#root', { title: 'Hello' });
+Use Luxaura as a frontend layer over any backend:
 
-// Toast notifications
-__Lux__.toast.success('Saved!');
-__Lux__.toast.error('Something went wrong');
-__Lux__.toast.info('Loading...');
+```
+# luxaura.config
+mode: headless
+proxy.target: http://localhost:8080
+```
 
-// Theme switching
-__Lux__.setTheme('dark');
-__Lux__.setTheme('light');
+All `/api/*` requests are proxied to your existing Java, Python, PHP, or Go backend.
 
-// Navigation
-__Lux__.router.navigate('/about');
+---
 
-// HTTP requests
-const data = await __Lux__.http.get('https://api.example.com/data');
+## luxaura.config
 
-// Storage
-__Lux__.storage.local.set('key', 'value');
-__Lux__.storage.local.get('key');
+```
+identity.name:    my-app
+identity.version: 1.0.0
+theme:            light
+mode:             full
+port:             3000
+# db.engine:      postgres
+# db.link:        postgresql://localhost:5432/my-app
+# proxy.target:   http://localhost:8080
 ```
 
 ---
 
-## Security
+## Programmatic API
+
+```javascript
+const luxaura = require('luxaura');
 
-Run the built-in security scanner before deploying:
+// Parse a .lux file → AST
+const ast = luxaura.parse(source, 'MyScene.lux');
+// ast.receive / ast.signal / ast.vault / ast.paint / ast.canvas
 
-```bash
-luxaura secure
-```
+// Compile AST → outputs
+const out = luxaura.compile(ast, { componentName: 'MyScene' });
+// out.clientJS  — client bundle
+// out.vaultJS   — server vault module (NEVER serve publicly)
+// out.paintCSS  — resolved CSS
+// out.html      — HTML shell
 
-Detects:
-- XSS risks (`innerHTML`, `eval`, `document.write`)
-- SQL injection patterns (string concatenation in queries)
-- Accidental server code outside `server` blocks
-- Sensitive environment variable exposure
+// One-shot
+const out2 = luxaura.transform(source, 'MyScene.lux');
+```
 
 ---