# Luxaura

Intent-driven full-stack web framework for building complete web apps with `.lux` files.

Luxaura is designed to let you describe frontend structure, backend actions, styling, and composition in a compact format while still generating real HTML, CSS, JavaScript, and server-side vault code.

## Why Luxaura

- Build frontend UI with readable `.lux` files instead of spreading one feature across many files.
- Keep backend-only logic in `vault` blocks so sensitive code stays off the client.
- Get responsive layout primitives like `Scene`, `Strip`, `Stack`, `Mosaic`, and `Ribbon` out of the box.
- Generate static-first HTML shells for faster first paint and stronger LCP.
- Ship with an integrated CLI for scaffolding, development, formatting, security checks, and benchmarking.

## Install

```bash
npm install -g luxaura
```

## Quick Start

```bash
luxaura release my-app
cd my-app
luxaura ignite
```

Create a scene in `scenes/index.lux`:

```lux
receive
    title: String = "My Luxaura App"

signal
    count: 0

paint
    self
        breathe: 8
    Headline
        size: titan
        weight: heavy
    Trigger
        curve: pill
        glow: soft

canvas
    Scene
        Stack
            Headline "<<title>>"
            Body "Clicked <<count>> times"
            Trigger "Click me"
                when click:
                    count = count + 1
```

Then run:

```bash
luxaura forge
```

## The `.lux` Model

Luxaura files are built from five blocks:

- `receive`: external inputs passed into a component
- `signal`: reactive state that triggers re-rendering
- `vault`: server-only logic that never ships to the browser
- `paint`: styling rules using Luxaura paint tokens
- `canvas`: UI composition tree

### Frontend Example

```lux
receive
    title: String = "Portfolio"

signal
    tab: "projects"

paint
    self
        breathe: 8
    Headline
        size: titan
        weight: heavy
    Trigger
        curve: pill

canvas
    Scene
        Stack
            Headline "<<title>>"
            Strip
                Trigger "Projects"
                    when click:
                        tab = "projects"
                Trigger "About"
                    when click:
                        tab = "about"
            if tab == "projects":
                Body "Project content here"
            else:
                Body "About content here"
```

### Backend Example With `vault`

```lux
signal
    status: "Send a message"

vault
    action contact(name, email, message):
        if (!name || !email || !message) {
            return "Please fill every field."
        }
        return `Message received from ${name}`

canvas
    Scene
        Stack
            Field placeholder:"Your Name" bind:"name"
            Field placeholder:"Your Email" kind:"email" bind:"email"
            Field placeholder:"Message" kind:"textarea" bind:"message"
            Trigger "Send"
                when click:
                    status = await vault.contact(name, email, message)
            Body "<<status>>"
```

## Core Nodes

Common Luxaura nodes include:

- `Scene`: centered page wrapper
- `Stack`: vertical flex layout
- `Strip`: horizontal flex layout
- `Mosaic`: responsive auto-fit grid
- `Ribbon`: navigation bar with mobile collapse support
- `Plate`: card surface
- `Headline`, `Body`, `Mark`: text and label primitives
- `Picture`: responsive image node
- `Field`, `Toggle`, `Trigger`, `Vessel`: form and interaction nodes
- `Anchor`, `Drawer`, `Popup`, `Curtain`: layout and overlay helpers

## Paint Tokens

Luxaura styling is handled through `paint` tokens instead of large raw CSS blocks.

```lux
paint
    self
        breathe: 6
        fill: #0f172a
        curve: round
        glow: soft
    Headline
        size: titan
        weight: heavy
        ink: #ffffff
    Trigger
        fill: #ffbf2c
        ink: #111827
        curve: pill
```

Useful tokens include:

- `breathe`, `push`, `gap`
- `fill`, `ink`, `border`
- `size`, `weight`
- `curve`, `glow`
- `wide`, `tall`, `flow`, `wrap`, `align`, `justify`

## CLI Commands

- `luxaura release <name>`: create a new project
- `luxaura ignite`: start dev server with live reload
- `luxaura forge`: build production output into `depot/public` and `depot/vault`
- `luxaura benchmark`: measure parser, compiler, and forge performance
- `luxaura component <name>`: scaffold a craft component
- `luxaura service <name>`: scaffold a server-side service
- `luxaura module <name>`: scaffold a shared module
- `luxaura polish`: auto-format `.lux` files
- `luxaura shield`: run built-in security checks
- `luxaura help_me`: print the built-in guide

## Features

- Static-first generated HTML for faster initial rendering
- Responsive defaults for layout primitives and mobile nav behavior
- Backend vault isolation to keep secrets out of client bundles
- Reactive `signal` updates without bringing a large frontend runtime
- Component composition with parent `receive` inputs
- CLI scaffolding for scenes, components, services, and modules
- Security-oriented tooling with `shield`
- Performance visibility with `benchmark`

## Why Teams Might Choose Luxaura

Luxaura is a good fit when you want:

- a more compact authoring model than splitting the same feature across multiple files
- stronger backend/frontend separation than purely client-side UI frameworks
- generated HTML instead of an empty shell that paints late
- readable domain-specific syntax for product pages, dashboards, portfolios, and internal tools
- a smaller conceptual surface for solo builders and fast-moving teams

No framework is universally better for every use case, but Luxaura aims to be stronger where clarity, speed of composition, and full-stack simplicity matter most.

## npm Package SEO Keywords

This package is published for users searching terms such as:

`luxaura`, `web framework`, `full stack framework`, `frontend framework`, `backend framework`, `responsive framework`, `lux files`, `nodejs framework`, `component framework`, `static site framework`, `server rendered`, and `developer tools`.

## Full HTML Tutorial

A longer tutorial page is included here:

- [docs/luxaura-tutorial.html](docs/luxaura-tutorial.html)

## License

MIT