npm install arianna
# or scaffold a new project
npx arianna new my-app                    # browser
npx arianna new my-app --template tauri   # Tauri desktop

arianna/
├── core/                 // Core, Real, Virtual, Observable, State,
│                         // Rule, Sheet, Stylesheet, Namespace,
│                         // Context, Directive, Component
├── additionals/          // Domain modules
│   ├── AI.ts             // Tensor, Layers, Transformer, Tokenizer, MarkovChain
│   ├── Animation.ts      // Tween, Timeline, easings
│   ├── Audio.ts          // AudioEngine, Oscillator, effects
│   ├── Data.ts           // FSM, DAG, Trie, PriorityQueue, LRUCache
│   ├── Docs.ts           // In-repo doc-page generator
│   ├── Finance.ts        // BlackScholes, Bachelier, Heston, MonteCarlo,
│   │                     //   Indicators, Portfolio, Backtest
│   ├── Geometry.ts       // AABB, Ray, intersections, hulls
│   ├── IO.ts             // FileIO, Http, SSE, WebSocketIO, LocalStore
│   ├── Latex.ts          // LaTeX → SVG / MathML
│   ├── Math.ts           // Vectors, matrices, noise
│   ├── Network.ts        // Fetch wrappers, retry/backoff
│   ├── SSR.ts            // renderToString, renderToStream, hydrate
│   ├── Three.ts          // 3D scene graph, WebGL renderer
│   ├── Two.ts            // 2D scene graph, SVG/Canvas renderer
│   ├── Video.ts          // VideoPlayer, GIFEncoder
│   └── Workers.ts        // WorkerPool, message passing
├── components/
│   ├── inputs/           // Button, Checkbox, ColorPicker, DatePicker,
│   │                     //   Dropdown, FileUpload, Radio, RangeSlider,
│   │                     //   Rating, SearchBar, Switch, TextField, ...
│   ├── display/          // Avatar, Badge, Banner, Card, Chip, Divider,
│   │                     //   Icon, Modal, ProgressBar, Skeleton, Tooltip, ...
│   ├── layout/           // Accordion, Drawer, Header, Panel, Splitter,
│   │                     //   Stepper, Tabs, Tag, List, Sidebar
│   ├── navigation/       // Breadcrumb, Menu, NavRail, Pagination
│   ├── charts/           // BarChart, LineChart, PieChart
│   ├── data/             // Table, TreeView
│   ├── finance/          // CandlestickChart, LineChart, DepthChart,
│   │                     //   HeatmapChart, PortfolioDonut, PnLChart,
│   │                     //   RiskGauge, OrderBook, Screener,
│   │                     //   Sparkline, AlertBadge
│   └── modifiers/
│       ├── 2D/           // Resizer, Rotator, Skewer, Rounder, Reflector, Mover
│       └── 3D/           // Subdivision, Decimate, Bevel, Mirror, Array,
│                         //   Bend, Twist, Wave, Inflate, Smooth, Drag,
│                         //   Snap, LOD, Fade, Billboard
├── cli/                  // `arianna` command (new, generate, serve, build)
├── projects/             // Browser / Tauri / iOS / Android templates
├── release/              // Built bundles (arianna.js, arianna.min.js)
└── types/                // Shared type declarations + jsx-runtime

// Bundle entry point — recommended
import { Core, Real, State, signal, effect, computed, batch } from 'arianna';

// Domain additionals
import { Finance, BlackScholes }   from 'arianna/additionals/Finance.ts';
import { AI, MarkovChain }        from 'arianna/additionals/AI.ts';
import { Two, Vec2D, Circle }     from 'arianna/additionals/Two.ts';

// UI controls — tree-shakeable per-file imports
import { Button }                 from 'arianna/components/inputs/Button.ts';
import { Table, TreeView }        from 'arianna/components/data';

// Finance components
import { CandlestickChart, RiskGauge } from 'arianna/components/finance';

// Modifiers
import { Resizer, Rotator }       from 'arianna/components/modifiers/2D';
import { BendModifier }            from 'arianna/components/modifiers/3D';

{
  "compilerOptions": {
    "target":            "ES2022",
    "module":            "ESNext",
    "moduleResolution":  "bundler",
    "jsx":               "react-jsx",
    "jsxImportSource":   "arianna",
    "strict":            true
  }
}

const count = signal(0);
const doubled = computed(() => count.get() * 2);

effect(() => console.log('doubled is', doubled.get()));
// → "doubled is 0"

count.set(5);
// → "doubled is 10"  (synchronous, single dependency walk)

batch(() => {
  count.set(10);
  count.set(20);
});
// → "doubled is 40"  (one effect run, not two)

const name = signal('Arianna');

new Real('div')
  .child(new Real('h1').text('Hello'))            // static — compiled once
  .child(new Real('span').text(() => name.get()))   // dynamic — sink installed
  .child(new Real('p').text('How are you?'))         // static — compiled once
  .append(document.body);

name.set('World');   // → only the <span> TextNode mutates. h1 and p are untouched.

import { Real, signal } from 'arianna';
import { Finance }       from 'arianna/addons/Finance';

const price = Finance.BlackScholes.price(100, 105, 0.25, 0.05, 0.20, 'call');

async function openTradingPanel() {
  const { Finance } = await import('arianna/addons/Finance');
  const { CandlestickChart } = await import('arianna/components/finance/CandlestickChart');
  // ... build the panel
}

import { Core } from 'arianna';
import { Finance } from 'arianna/addons/Finance';

Core.use({
  name: 'finance',
  install(core) { (core as any).Finance = Finance; },
});

Core.plugins(); // → ['finance', ...]

// my-addon.ts
export const MyAddon = {
  greet(name: string) { return `hello, ${name}`; },
};

if (typeof window !== 'undefined')
  Object.defineProperty(window, 'MyAddon', {
    value: MyAddon, writable: false, configurable: false, enumerable: false,
  });

export default MyAddon;

Core.version              // → { major: 1, minor: 2, patch: 0 } — frozen
Core.use(myPlugin)
Core.plugins()            // → ['my-plugin']
window.Core === Core      // → true, always

// Plugin interface
interface CorePlugin {
  name    : string;
  install : (core: typeof Core, opts?: unknown) => void;
}

Core.use({
  name   : 'my-plugin',
  install: (core) => { (core as any).myFeature = () => {}; }
});
Core.plugins();           // → ['my-plugin']
Core.use(myPlugin);       // second call → no-op (idempotent)
Core.version.major;       // → 1

Core.version
// → { major: 1, minor: 2, patch: 0 }

// Compare versions
if (Core.version.major >= 1 && Core.version.minor >= 2) {
  // safe to use signalMono / sinkText
}

// Frozen — these all fail silently or throw
Core.version.major = 99;          // no-op (or TypeError in strict)
delete Core.version.patch;       // no-op
Object.isFrozen(Core.version);    // → true

Core.Namespaces.HTML
// → 'http://www.w3.org/1999/xhtml'

Core.Namespaces.SVG
// → 'http://www.w3.org/2000/svg'

Core.Namespaces.MathML
// → 'http://www.w3.org/1998/Math/MathML'

Core.Namespaces.XLink
// → 'http://www.w3.org/1999/xlink'

// Used internally — Real picks the namespace by tag
new Real('svg')         // → SVG namespace
  .child(new Real('circle').attr('r', '40'));

// Register your own
Core.Namespaces.MyXML = 'https://example.com/ns/v1';
new Real('my-tag', { namespace: 'MyXML' });

Core.Scopes.public
// → { writable: true,  enumerable: true,  configurable: true  }

Core.Scopes.protected
// → { writable: true,  enumerable: false, configurable: true  }

Core.Scopes.private
// → { writable: true,  enumerable: false, configurable: false }

Core.Scopes.static
// → { writable: false, enumerable: true,  configurable: false }

// Apply a scope when defining a property
Object.defineProperty(target, 'apiKey', {
  ...Core.Scopes.private,        // hidden + locked
  value: 'sk-...',
});

// Same pattern Core itself uses to register itself on window:
Object.defineProperty(window, 'Core', {
  ...Core.Scopes.static,         // read-only public global
  value: Core,
});

import { signal, effect, computed, batch } from 'arianna';

const count = signal(0);
const doubled = computed(() => count.get() * 2);

effect(() => {
  console.log(`count=\${count.get()}, doubled=\${doubled.get()}`);
});

count.set(5);   // logs: count=5, doubled=10
count.set(10);  // logs: count=10, doubled=20

// batch — single flush
batch(() => {
  count.set(100);
  count.set(200);
}); // only one effect run: count=200

// peek — read without tracking dependency
effect(() => {
  const curr = count.get();  // tracked
  const prev = count.peek(); // NOT tracked — won't re-run
});

import { Real, signal } from 'arianna';

const name    = signal('AriannA');
const loading = signal(false);
const color   = signal('#e40c88');

const el = new Real('div')
  // TextNode Sink — only the text node updates
  .text(() => `Hello, \${name.get()}!`)
  // Attribute Sink — updates disabled attr
  .attr('disabled', () => loading.get() ? '' : null)
  // Class Sink — toggles CSS class
  .cls('loading', () => loading.get())
  // Style Sink — updates inline style
  .style('color', () => color.get())
  // Property Sink — sets .value on input
  .prop('dataset.label', () => name.get())
  .append(document.body);

name.set('World');  // only the TextNode updates — nothing else re-renders

import { signalMono, sinkText } from 'arianna';

const label = signalMono('Initial');

// Wire signal directly to a TextNode — no wrapper allocation
const node = document.createTextNode(label.peek());
document.body.appendChild(node);
sinkText(label, node);

// Updates the TextNode's nodeValue directly — zero overhead
label.set('Updated');  // → node.nodeValue = 'Updated'

// Via Real.textMono() — creates + wires in one call
const price = signalMono('€ 0.00');
new Real('span').textMono(price).append(document.body);
price.set('€ 1.99');  // direct node.nodeValue write

import { Real, signal } from 'arianna';

const val = signal('');

// .bind(getter, setter) — two-way
const input = new Real('input')
  .bind(() => val.get(), (v) => val.set(v))
  .append(document.body);

// Mirror elsewhere — auto-updates on every keystroke
new Real('p').text(() => `You typed: \${val.get()}`).append(document.body);

import { Observable } from 'arianna';

const bus = new Observable();

bus.on('data-ready', (e) => console.log(e));
bus.fire({ Type: 'data-ready', payload: [1, 2, 3] });

// DOM bus (static) — cross-component events
Observable.On(document, 'theme-changed', (e) => applyTheme(e.detail));

import State from './arianna-ts/State.ts';

const state = new State({ count: 0, name: 'AriannA' });

const unsub = state.subscribe((key, value) => {
  console.log(key, '→', value);
});

state.State.count = 1;        // triggers subscriber

state.computed('doubled', s => s.count * 2);
state.State.doubled;              // → 2

state.batch(() => {
  state.State.count = 10;      // single notification for both
  state.State.name  = 'New';
});

unsub();                          // stop listening

import { State } from 'arianna';

const store = new State({
  user: {
    name: 'Riccardo',
    addresses: [
      { city: 'Zurich',  primary: true  },
      { city: 'Roma',    primary: false },
    ],
  },
  cart: {
    items: [
      { sku: 'A1', qty: 2, meta: { gift: false } },
      { sku: 'B2', qty: 1, meta: { gift: true  } },
    ],
    totals: { subtotal: 0, tax: 0 },
  },
});

store.subscribe((path, value) => console.log(path, '→', value));

// (1) Mutate a deep scalar — single notification with the full path
store.State.user.addresses[1].primary = true;
// → "user.addresses.1.primary" → true

// (2) Mutate inside a nested object inside an array
store.State.cart.items[0].meta.gift = true;
// → "cart.items.0.meta.gift" → true

// (3) Array methods are intercepted — push/splice/pop all notify
store.State.cart.items.push({ sku: 'C3', qty: 5, meta: { gift: false } });
// → "cart.items.2"      → { sku: 'C3', qty: 5, meta: {…} }
// → "cart.items.length" → 3

store.State.cart.items.splice(0, 1);
// → "cart.items.0"      → { sku: 'B2', … }   (shift)
// → "cart.items.1"      → { sku: 'C3', … }
// → "cart.items.length" → 2

// (4) Reassign an entire subtree — children are re-wrapped lazily
store.State.user.addresses = [{ city: 'Milan', primary: true }];
// → "user.addresses"     → [{ city: 'Milan', primary: true }]
store.State.user.addresses[0].city = 'Genoa';       // still reactive
// → "user.addresses.0.city" → "Genoa"

// (5) Path-targeted subscription — listen only to one branch
const off = store.subscribePath('cart.items', (path, value) => {
  console.log('cart changed:', path, value);
});

// (6) Computed over deep data — recomputes only when its deps change
store.computed('cart.totals.subtotal', s =>
  s.cart.items.reduce((acc, it) => acc + it.qty, 0)
);
store.State.cart.totals.subtotal;   // → 6
store.State.cart.items[0].qty = 10;
store.State.cart.totals.subtotal;   // → 15  (auto-recomputed)

// Wrapper mode — no new
Real('div')                  // tag class wrapper
Real('#my-id')              // querySelector → Real of that element
Real(HTMLButtonElement)        // interface wrapper
Real(existingNode)             // wrap existing DOM node

// Instance mode — creates element
new Real('button')                          // <button>
new Real('button', {{ css: {{ color: 'red' }} }}) // with styles
new Real(HTMLButtonElement)                   // from interface
new Real(myVirtualNode)                       // from Virtual node

// Define custom element
Real('my-tag', MyConstructor, HTMLButtonElement);

// WRAPPER mode — no new (like Real)
Virtual('div')                   // → Virtual.Create('div')
Virtual('#my-id')              // → wraps existing DOM element
Virtual(domElement)             // → wraps live DOM element
Virtual(myRealInstance)         // → wraps Real's element
Virtual(existingVirtualNode)    // → returns the node itself

// INSTANCE mode — with new (identical behaviour)
new Virtual('div')                // → new VirtualNode('div')
new Virtual('div', {{ class: 'card' }}) // → with attrs
new Virtual('#my-id')           // → shadow existing element
new Virtual(domElement)          // → wrap live element
new Virtual(myRealInstance)      // → wrap Real's element

import { Virtual } from './arianna-ts/Virtual.ts';

const card  = Virtual.Create('div', {{ class: 'card' }});
const title = Virtual.Create('h2'); title.set('textContent', 'Hello');
card.add(title);

Virtual.Mount(card, document.body);
// later:
card.unmount();
card.set('class', 'card card--active'); // syncs if mounted

card.on('VNode-Changed', e => console.log(e));
card.fire({{ Type: 'VNode-Changed', node: card }});

import Rule from './arianna-ts/Rule.ts';

const rule = new Rule('.btn', {{ color: 'red', fontSize: '14px' }});
rule.selector;   // → '.btn'
rule.css;        // → { color: 'red', fontSize: '14px' }
rule.toString(); // → '.btn { color: red; font-size: 14px; }'

import {{ Sheet }} from './arianna-ts/Stylesheet.ts';

const sheet = new Sheet(
  new Rule('.btn',       {{ padding: '8px 16px' }}),
  new Rule('.btn:hover', {{ opacity: '0.8' }}),
);
sheet.add(new Rule('.btn:active', {{ transform: 'scale(.98)' }}));
sheet.add(new Rule('.btn-primary', {{ background: 'blue' }}), 0); // insert at index 0
sheet.inject(document.head);

import Namespace from './arianna-ts/Namespace.ts';

Namespace.HTML.div;               // → HTMLDivElement constructor
Namespace.HTML.button;            // → HTMLButtonElement
Namespace.HTML.HTMLAnchorElement; // → by interface name
Namespace.SVG.circle;             // → SVGCircleElement
Namespace.SVG.path;

import Context from './arianna-ts/Context.ts';

const ThemeCtx = Context.create({{ theme: 'dark' }});
ThemeCtx.provide({{ theme: 'light' }});

const {{ theme }} = ThemeCtx.consume();
console.log(theme); // → 'light'

let loggedIn = false;

const update = Directive.if(
  document.getElementById('auth-area'),
  () => loggedIn,
  '<div class="welcome">Welcome back! <button id="logout">Logout</button></div>',
  '<div class="login"><input placeholder="email"><button id="login">Login</button></div>'
);

// Toggle and re-render
document.getElementById('login')?.addEventListener('click', () => { loggedIn = true;  update(); });
document.getElementById('logout')?.addEventListener('click', () => { loggedIn = false; update(); });

// document.getElementById and Real('#id') are identical — use either
const update1 = Directive.if(
  document.getElementById('auth-area'),   // ← native DOM
  () => loggedIn, thenHtml, elseHtml
);
const update2 = Directive.if(
  Real('#auth-area'),                     // ← Real wrapper — same element
  () => loggedIn, thenHtml, elseHtml
);
// Both work — Real('#id') calls querySelector internally

// With State (auto-update)
const state = new State({ visible: false });
const upd   = Directive.if(Real('#panel'), () => state.State.visible,
  '<p>Shown!</p>', '<p>Hidden</p>');
state.subscribe(() => upd());

/* @jsxImportSource arianna */
function AuthArea() {
  const [loggedIn, setLoggedIn] = useState(false);
  return loggedIn
    ? <div className="welcome">
        Welcome back! <button onClick={() => setLoggedIn(false)}>Logout</button>
      </div>
    : <div className="login">
        <input placeholder="email"/>
        <button onClick={() => setLoggedIn(true)}>Login</button>
      </div>;
}

<!-- In your HTML -->
<div id="app">

  <!-- a-if: shown when scope.loggedIn is truthy -->
  <div a-if="loggedIn">
    Welcome back, {{ username }}!
    <button a-on="click:logout">Logout</button>
  </div>

  <!-- a-if with else via a-else sibling (same parent, next element) -->
  <div a-if="loggedIn">✓ Authenticated</div>
  <div a-else>✗ Please log in</div>

</div>

// In your script — one call wires everything
const scope = {
  loggedIn : false,
  username : 'Riccardo',
  logout   : () => { scope.loggedIn = false; Directive.bootstrap(app, scope); },
};
Directive.bootstrap(document.getElementById('app'), scope);

let planets = ['Mercury', 'Venus', 'Earth', 'Mars'];

// Native DOM or Real wrapper — identical result
const update = Directive.for(
  document.getElementById('planet-list'),   // native
  () => planets,
  (item, i) => `<li data-i="${i}">${i + 1}. ${item}</li>`
);
// equivalent with Real:
const update = Directive.for(
  Real('#planet-list'),                     // Real wrapper
  () => planets,
  (item, i) => `<li data-i="${i}">${i + 1}. ${item}</li>`
);

// Add an item and re-render
planets.push('Jupiter');
update();

// Remove an item and re-render
planets = planets.filter(p => p !== 'Venus');
update();

function PlanetList() {
  const [planets, setPlanets] = useState(['Mercury', 'Venus', 'Earth']);
  const add    = () => setPlanets([...planets, 'Planet ' + (planets.length + 1)]);
  const remove = () => setPlanets(planets.slice(0, -1));
  return (
    <ul>
      {planets.map((p, i) => <li key={i}>{i + 1}. {p}</li>)}
    </ul>
  );
}

<!-- a-for: renders the element once per item -->
<ul id="app">
  <li a-for="planet in planets">
    {{ planet }}
  </li>
</ul>

// Script
Directive.bootstrap(document.getElementById('app'), {
  planets: ['Mercury', 'Venus', 'Earth', 'Mars'],
});

<!-- With index -->
<li a-for="item, i in items">{{ i }}. {{ item.name }}</li>

<!-- Nested -->
<div a-for="user in users">
  <h3>{{ user.name }}</h3>
  <ul><li a-for="tag in user.tags">{{ tag }}</li></ul>
</div>

const scores = { Alice: 95, Bob: 87, Carol: 92, Dan: 78 };

Directive.foreach(
  document.getElementById('score-list'),
  () => scores,
  (name, score) => `<li><strong>${name}</strong>: ${score}/100</li>`
);

// Equivalent to the Golem template:
// <ol a-foreach="var name in scores"><li>{{ name }}: {{ scores[name] }}</li></ol>

let tab = 'home';

// document.getElementById ←→ Real('#id') — pick your style
const update = Directive.switch(
  document.getElementById('tab-content'),  // or: Real('#tab-content')
  () => tab,
  {
    home    : '<div><h3>🏠 Home</h3><p>Welcome to AriannA.</p></div>',
    docs    : '<div><h3>📖 Docs</h3><p>Read the documentation.</p></div>',
    settings: '<div><h3>⚙️ Settings</h3><p>Configure your app.</p></div>',
    default : '<div><h3>404</h3><p>Page not found.</p></div>',
  }
);

// Navigate to a tab
tab = 'docs'; update();

function TabContent({ tab }: { tab: string }) {
  const pages: Record<string, JSX.Element> = {
    home    : <div><h3>🏠 Home</h3><p>Welcome to AriannA.</p></div>,
    docs    : <div><h3>📖 Docs</h3><p>Read the docs.</p></div>,
    settings: <div><h3>⚙️ Settings</h3><p>Configure app.</p></div>,
  };
  return pages[tab] ?? <div>404</div>;
}

<!-- a-switch on the container, a-case on each branch -->
<div a-switch="currentPage">

  <div a-case="home">
    <h2>🏠 Home</h2><p>Welcome!</p>
  </div>

  <div a-case="about">
    <h2>ℹ️ About</h2><p>About us.</p>
  </div>

  <div a-case="default">
    <h2>404</h2>
  </div>

</div>

<<!-- Nav buttons -->>
<button a-on="click:goHome">Home</button>
<button a-on="click:goAbout">About</button>

// Script
const scope = {
  currentPage : 'home',
  goHome      : () => { scope.currentPage = 'home';  reboot(); },
  goAbout     : () => { scope.currentPage = 'about'; reboot(); },
};
const reboot = () => Directive.bootstrap(document.getElementById('app'), scope);
reboot();

let n = 5;

Directive.while(
  document.getElementById('fib-list'),
  () => n > 0,
  (() => {
    let [a, b, count] = [0, 1, 0];
    return () => {
      const val = a; [a, b] = [b, a + b]; count++; n--;
      return `<li>fib(${count}) = ${val}</li>`;
    };
  })()
);
// Renders: fib(1)=0, fib(2)=1, fib(3)=1, fib(4)=2, fib(5)=3

<!-- a-while: renders the template while count > 0 -->
<ol id="app">
  <li a-while="count > 0">
    Item {{ count-- }}
  </li>
</ol>

// Script — scope variables are read-write during iteration
Directive.bootstrap(document.getElementById('app'), { count: 5 });
// → renders: Item 5, Item 4, Item 3, Item 2, Item 1

const state = new State({ username: 'Riccardo', score: 0 });

// document.getElementById and Real('#id') are the same — use either
const upd = Directive.bind(
  document.getElementById('name-display'),  // native getElementById
  'textContent',
  () => state.State.username
);

// Same with Real wrapper — querySelector under the hood
const upd2 = Directive.bind(
  Real('#score-display'),                   // Real('#id') wrapper
  'innerHTML',
  () => `Score: <strong>${state.State.score}</strong>`
);

state.subscribe(() => { upd(); upd2(); });
state.State.username = 'Arianna';  // → both spans update

<!-- a-bind="property:scopeKey" — one-way: element ← scope -->
<div id="app">

  <span  a-bind="textContent:username"></span>
  <img   a-bind="src:avatarUrl"    alt="Avatar">
  <input a-bind="value:email"      placeholder="Email">
  <div   a-bind="className:cssClass">Styled</div>
  <div   a-bind="innerHTML:richHtml"></div>

</div>

// Script
Directive.bootstrap(document.getElementById('app'), {
  username  : 'Riccardo',
  avatarUrl : '/img/avatar.png',
  email     : 'r@example.com',
  cssClass  : 'card active',
  richHtml  : 'Score: <strong>42</strong>',
});

const state = new State({ name: '', age: '', color: '#e40c88' });

// Mix freely — both target the same DOM element
Directive.model(document.getElementById('inp-name'),  state, 'name');  // native
Directive.model(Real('#inp-age'),                    state, 'age');   // Real
Directive.model(Real('#inp-color'),                   state, 'color'); // Real

// Real('#id') === document.querySelector('#id') — same element, zero overhead
state.subscribe((key, val) => console.log(key, '→', val));
state.State.name = 'Arianna';  // programmatic write updates the input too

<!-- a-model: two-way binding — input ↔ scope property -->
<div id="app">

  <input    a-model="user.name"     placeholder="Name">
  <input    a-model="user.age"      type="number">
  <input    a-model="theme.color"   type="color">
  <select   a-model="settings.lang">
    <option value="en">English</option>
    <option value="it">Italiano</option>
  </select>
  <textarea a-model="post.body"></textarea>

  <!-- Live preview — updates as user types -->
  <p>Hello, <span a-bind="textContent:user.name"></span>!</p>

</div>

// Script
Directive.bootstrap(document.getElementById('app'), {
  user     : { name: '', age: '' },
  theme    : { color: '#e40c88' },
  settings : { lang: 'en' },
  post     : { body: '' },
});

let open = false;
// Both lines target the same element — use what reads better
const panel  = document.getElementById('side-panel');  // native
const toggle = Real('#toggle-btn');                      // Real wrapper

const update = Directive.show(panel, () => open);

Real('#toggle-btn').on('click', () => { open = !open; update(); });
// or: toggle.addEventListener('click', ...) — same thing

// Directive.show vs Directive.if:
//   .show → display toggle — element stays in DOM, state preserved
//   .if   → innerHTML swap — content recreated on each change

<!-- a-show: toggles display, element stays in DOM -->
<div id="app">

  <button a-on="click:toggleMenu">☰ Menu</button>

  <nav a-show="menuOpen">
    <a href="/">Home</a>
    <a href="/docs">Docs</a>
  </nav>

  <!-- a-show vs a-if:
    a-show → display:none   (element kept, state preserved)
    a-if   → innerHTML swap (element recreated on change)  -->

</div>

// Script
const scope = {
  menuOpen   : false,
  toggleMenu : () => { scope.menuOpen = !scope.menuOpen; reboot(); },
};
const reboot = () => Directive.bootstrap(document.getElementById('app'), scope);
reboot();

// document.getElementById or Real('#id') — identical
Directive.on(document.getElementById('save-btn'), 'click', e => save());   // native
Directive.on(Real('#save-btn'),                   'click', e => save());   // Real

// Real shines for chaining — attach listener and append in one expression
Real('#save-btn').on('click', save).on('mouseenter', highlight);

// Multiple events space-separated
Directive.on(Real('#search'), 'focus blur', e => highlight(e.type === 'focus'));

// With options (passive scroll)
Directive.on(Real('#list'), 'scroll', onScroll, { passive: true });

// Equivalent HTML attribute (via bootstrap):
// <button a-on="click:handleClick">Click me</button>

<!-- a-on="event:handler" — attach DOM listener -->
<div id="app">

  <button a-on="click:handleClick">Click me</button>
  <button a-on="click:save">Save</button>

  <!-- Multiple events space-separated -->
  <input a-on="focus blur:handleFocus" placeholder="Focus me">

  <!-- Keyboard shortcuts -->
  <div  a-on="keydown:handleKey" tabindex="0">Press a key</div>

</div>

// Script
Directive.bootstrap(document.getElementById('app'), {
  handleClick : (e) => console.log('clicked', e.target),
  save        : ()  => alert('Saved!'),
  handleFocus : (e) => console.log(e.type),   // 'focus' or 'blur'
  handleKey   : (e) => console.log(e.key),
});

const scope = {
  username : 'Arianna',
  score    : 42,
  planet   : 'Earth',
  planets  : { Earth: '3rd from the Sun' },
};

// native getElementById
Directive.template(document.getElementById('tpl-output'), scope);

// Real wrapper — same result, shorter on repeated use
Directive.template(Real('#tpl-output'), scope);

// Real('#id') === querySelector('#id') — zero difference in output
// Bracket notation:  {{ planets[planet] }}  → "3rd from the Sun"
// Dot notation:      {{ planets.Earth }}     → "3rd from the Sun"

<!-- {{ }} interpolation — works anywhere in innerHTML -->
<div id="app">

  <h1>Hello, {{ username }}!</h1>
  <p>Score: {{ score }} / {{ maxScore }}</p>
  <p>Planet: {{ planets[selected] }}</p>
  <p>Nested: {{ user.address.city }}</p>
  <p>Expr:    {{ score > 50 ? 'pass' : 'fail' }}</p>

</div>

// Script
Directive.bootstrap(document.getElementById('app'), {
  username  : 'Arianna',
  score     : 72,
  maxScore  : 100,
  selected  : 2,
  planets   : ['Mercury', 'Venus', 'Earth'],
  user      : { address: { city: 'Zürich' } },
});

// Register a tooltip directive
Directive.register('tooltip', {
  mounted(el, value)   { el.title = value; el.style.cursor = 'help'; },
  unmounted(el)        { el.title = ''; },
});

// Register a highlight directive
Directive.register('highlight', {
  mounted(el, color = '#fff3cd') { el.style.background = color; },
  unmounted(el)                   { el.style.background = ''; },
});

// Apply programmatically
Directive.apply('tooltip',   myButton, 'Save the document');
Directive.apply('highlight', myInput,  '#ffd6e8');

// Apply via HTML attributes (after bootstrap):
// <button data-directive="tooltip" data-tooltip="Save">Save</button>

<!-- In your HTML -->
<div a-if="user.loggedIn">Welcome, {{ user.name }}!</div>
<ul  a-for="item in cart"><li>{{ item.name }} — €{{ item.price }}</li></ul>
<div a-show="cart.length > 0">Checkout</div>
<input a-model="user.name" placeholder="Your name">
<span a-bind="textContent:user.name"></span>
<button a-on="click:addToCart">Add</button>

// In your script — one call wires everything
const scope = { user, cart, addToCart };

// Identical — choose what reads better in context
Directive.bootstrap(document.getElementById('app'), scope);  // native
Directive.bootstrap(Real('#app'), scope);                    // Real wrapper

// Real('#app') calls querySelector('#app') internally — same element
// Rule of thumb: use Real() when you're already in an AriannA codebase
//               use getElementById() when integrating with plain DOM code

import {{ Component, Prop, Watch, Emit, Ref }} from './arianna-ts/index.ts';

@Component({{ tag: 'user-card' }})
class UserCard extends HTMLElement {{
  @Prop() name = '';
  @Prop() role = '';
  @Ref()  nameEl!: HTMLSpanElement;

  @Watch('name')
  onNameChange(next: string) {{
    if (this.nameEl) this.nameEl.textContent = next;
  }}

  @Emit('card-click')
  handleClick() {{ return {{ name: this.name }}; }}

  render() {{
    return `<div><span data-ref="nameEl">${'{'}this.name{'}'}</span> — ${'{'}this.role{'}'}</div>`;
  }}
}}

{
  "compilerOptions": {
    "jsx"             : "react-jsx",
    "jsxImportSource" : "arianna"
  }
}

// Real mode (default) — every element is a Real instance
import { Real, signal } from 'arianna';

const count = signal(0);

function App() {
  return (
    <div id="app">
      <h1 class="title">AriannA</h1>
      <p>Count: <span>{count.get()}</span></p>
      <button onClick={() => count.set(count.get() + 1)}>
        Increment
      </button>
    </div>
  );
}

// Virtual mode — per-file pragma at top
/* @dom-render: virtual */
function SVGIcon() {
  return (
    <svg width="40" height="40" viewBox="0 0 40 40">
      <circle cx="20" cy="20" r="18" fill="#e40c88" />
    </svg>
  );
}

// Both are equivalent — $ takes precedence if both present
<button $click={fn}>Dollar syntax</button>
<button onClick={fn}>On-prefix syntax</button>

// Any event name works
<input $input={(e) => val.set(e.target.value)} />
<div $mouseenter={show} $mouseleave={hide}>Hover me</div>

// <>...</> — Real mode: DocumentFragment | Virtual mode: Fragment
function Pair() {
  return (
    <>
      <span>First</span>
      <span>Second</span>
    </>
  );
}

// PascalCase → kebab-case tag resolution via Core.GetDescriptor()
import { MyButton } from './MyButton.ts';

const el = <MyButton label="Click me" $click={handleClick} />;
// → new Real('my-button').set('label','Click me').on('click',handleClick)

import { setDefaultRuntime } from 'arianna/jsx-runtime';

// Set globally at app bootstrap
setDefaultRuntime('virtual');  // all JSX → VirtualNode
setDefaultRuntime('real');     // back to default

import { h, Fragment } from 'arianna/jsx-runtime';

// Without JSX transform
const btn = h('button', { class: 'primary', '$click': fn }, 'Click');
const frag = h(Fragment, null, btn, h('span', null, 'text'));

// tsconfig for dev mode
{
  "compilerOptions": {
    "jsx"             : "react-jsxdev",
    "jsxImportSource" : "arianna"
  }
}
// Resolved to: arianna/jsx-dev-runtime → jsxDEV()
// Same behavior as jsx() — extra debug args are ignored

// Every control follows the same pattern:
const ctrl = new ControlName('#container', options);
ctrl.propertyName = value;       // setter → schedules re-render via rAF
ctrl.on('event', handler);      // typed event bus
ctrl.destroy();                  // remove DOM + cleanup all listeners

// Example:
const btn = new Button('#root', {{ variant: 'primary' }});
btn.label   = 'Save';           // reactive setter
btn.loading = true;             // disables + shows spinner
btn.on('click', () => save());

import {{ Theme }} from './arianna-controls/core/Theme.ts';

Theme.apply('dark');               // set tokens on :root
Theme.apply('light', container);    // scoped to element
Theme.apply('auto');               // prefers-color-scheme
Theme.extend({{ '--ar-primary': '#ff6b6b' }});
Theme.inject();                     // inject base CSS (once)

import { Math, MathConstants, Fraction, Vector3, Statistics } from 'arianna/additionals';

// Fractions
const f = new Fraction(3, 4);
f.Sum(new Fraction(1, 4)).toString();  // "1/1"

// 3D Vectors
const v = new Vector3(1, 2, 3);
const u = new Vector3(4, 5, 6);
v.dot(u);     // 32
v.cross(u);   // Vector3(-3, 6, -3)
v.length();   // √14 ≈ 3.742

// Constants
MathConstants.PI;    // 3.14159…
MathConstants.Phi;   // golden ratio 1.618…
MathConstants.c;     // speed of light 299792458 m/s

// Statistics
const data = [2, 4, 4, 4, 5, 5, 7, 9];
Statistics.mean(data);      // 5
Statistics.variance(data);  // 4
Statistics.stdDev(data);    // 2

// Matrix4 — perspective projection
const m = Matrix4.perspective(MathConstants.PI / 4, 16/9, 0.1, 1000);

import { Geometry, Point, Circle, AABB } from 'arianna/additionals';

const p1 = new Point(0, 0);
const p2 = new Point(3, 4);
p1.distanceTo(p2);   // 5

const c = new Circle(p1, 10);
c.area();            // π × 100 ≈ 314.16
c.contains(p2);     // true (dist=5 < r=10)

const box = new AABB(p1, new Point(100, 100));
box.intersects(new AABB(new Point(50,50), new Point(150,150)));  // true

import { Animation } from 'arianna/additionals';
Core.use(Animation);

// Animate an element with WAAPI
Animation.animate(el, [
  { opacity: 0, transform: 'translateY(20px)' },
  { opacity: 1, transform: 'translateY(0)'    },
], { duration: 300, easing: 'ease-out', fill: 'forwards' });

// Stagger multiple elements
Animation.stagger(document.querySelectorAll('.card'),
  { opacity: [0, 1], transform: ['translateY(12px)', 'none'] },
  { duration: 250, delay: 40 }  // 40ms between each
);

import { Network } from 'arianna/additionals';
Core.use(Network);

// Typed fetch with auto-JSON parse
const data = await Network.get<{ name: string }[]>('/api/users');

// SSE stream → Signal
const price = signal(0);
Network.sse('/api/prices', (e) => price.set(JSON.parse(e.data)));
// Any effect reading price() now auto-updates
effect(() => priceEl.text(() => `€\${price.get().toFixed(2)}`));

import { Audio } from 'arianna/additionals';
Core.use(Audio);

// Oscillator — uses shared AudioEngine, no manual context needed
const osc = new Audio.Oscillator(440, 'sine');
osc.start(0.5);                // volume 0–1
setTimeout(() => osc.stop(), 1000);

// Effects chain — Reverb, Delay, Filter all share the engine
const reverb = new Audio.Reverb({ duration: 2.5, decay: 2.0 });
const delay  = new Audio.Delay({ time: 0.3, feedback: 0.4 });

// Analyser — real-time FFT for visualizers
const ana = new Audio.Analyser({ fftSize: 2048 });
const bins = ana.getFrequencyData();   // Uint8Array

// Sequencer — step sequencer with callback per step
const seq = new Audio.Sequencer(120, 16);  // 120 BPM, 16 steps
seq.on((step, time) => { /* trigger sample at step */ });
seq.start();

// MIDI input — listen for note/CC messages
const midi = new Audio.MIDIEngine();
await midi.connect();
midi.on(msg => console.log(msg.type, msg.note, msg.velocity));

import { Video } from 'arianna/additionals';
Core.use(Video);

// Camera — request user media and attach to a video element
const cam = new Video.CameraCapture();
const stream = await cam.start({ width: 1280, height: 720, audio: false });
document.querySelector('video').srcObject = stream;

// Screen capture — getDisplayMedia wrapper
const screen = new Video.ScreenCapture();
await screen.start();
screen.stop();

// VideoPlayer — controlled HTMLVideoElement with events
const player = new Video.VideoPlayer(document.querySelector('#wrap'));
player.load('/movie.mp4');
player.on('timeupdate', () => console.log(player.currentTime));

// VideoCompositor — overlay multiple sources on a canvas
const comp = new Video.VideoCompositor(1920, 1080);
comp.addLayer({ source: stream, x: 0, y: 0 });
comp.addLayer({ source: '/logo.png', x: 20, y: 20, w: 120, h: 40 });
comp.start();   // composite is comp.canvas

// GIFEncoder — record canvas frames into an animated GIF
const enc = new Video.GIFEncoder({ width: 320, height: 240, fps: 12 });
for (let i = 0; i < 24; i++) {
  enc.addFrame(canvas);
}
const bytes = enc.encode();   // Uint8Array → save as .gif

import { IO } from 'arianna/additionals';
Core.use(IO);

// Drag-drop zone → Signal
const dropped = signal<File | null>(null);
IO.dropZone(document.getElementById('drop')!, (files) => {
  dropped.set(files[0] ?? null);
});

// Save file
await IO.save('export.json', JSON.stringify(data, null, 2));

import { Latex } from 'arianna/additionals';
Core.use(Latex);

// Render LaTeX to MathML string
const ml = Latex.render('\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}');
document.getElementById('math')!.innerHTML = ml;

import { Three } from 'arianna/additionals';
Core.use(Three);

const app = Three.scene(document.querySelector('canvas')!);
app.scene.add(new THREE.Mesh(
  new THREE.BoxGeometry(),
  new THREE.MeshStandardMaterial({ color: '#e40c88' })
));
app.start();  // requestAnimationFrame loop

import {{ TreeView, TreeViewCSS }} from './arianna-controls/TreeView.ts';

const s = document.createElement('style');
s.textContent = TreeViewCSS; document.head.appendChild(s);

const tree = new TreeView('#sidebar', {{
  selectable : 'single',  // 'none' | 'single' | 'multi'
  icons      : true,
  checkboxes : false,
  keyboard   : true,
  draggable  : false,
}});

tree.nodes = [
  {{ id: '1', label: 'Root', icon: '📁', children: [
    {{ id: '1.1', label: 'Child A', icon: '📄' }},
    {{ id: '1.2', label: 'Child B', lazy: true }},  // lazy
  ]}},
];

tree.on('select', ({{ node }}) => console.log(node.label));
tree.on('load',   ({{ node, resolve }}) => fetchChildren(node.id).then(resolve));
tree.expand('1');
tree.search('child');

// Client-side with Web Worker
const table = new Table('#root', {{
  columns: [
    {{ key: 'name',   label: 'Name',   sortable: true, width: 200 }},
    {{ key: 'role',   label: 'Role',   sortable: true }},
    {{ key: 'status', label: 'Status',
      render: (v) => `<span style="color:${'{'}v==='active'?'green':'gray'{'}'}">${'{'}v{'}'}</span>` }},
  ],
  pageSize  : 25,
  selectable: 'multi',
  worker    : true,
  exportCsv : true,
}});
table.rows = myData;

// Server-side with cache
const table = new Table('#root', {{
  columns,
  cache: true,
  fetch: async ({{ page, pageSize, sort, filter }}) => {{
    const r = await api.get(`/data?page=${'{'}page{'}'}&size=${'{'}pageSize{'}'}`);
    return {{ rows: r.data, total: r.total }};
  }},
}});

const table = new Table('#root', {
  columns: [
    { key: 'name',   label: 'Name',   sortable: true },
    { key: 'capital', label: 'Capital' },
    { key: 'region',  label: 'Region' },
  ],

  // ── Expandable rows ─────────────────────────────────────
  expandable  : true,
  expandSingle: true,   // collapse others when one opens

  // Async — called when user clicks ▶ on a row
  rowContent: async (row) => {
    const res  = await fetch(`/api/provinces/${'{'}row.id{'}'}`);
    const data = await res.json();
    return `<div style="padding:10px 0 10px 32px;border-left:2px solid var(--ar-primary)">
      <strong>Provinces of ${'{'}row.name{'}'}</strong>
      <ul>${'{'}data.map(p => `<li>${'{'}p.name{'}'}</li>`).join(''){'}'}</ul>
    </div>`;
  },
});

table.rows = myData;

// Programmatic control
table.expandRow(0);    // expand row at index 0
table.collapseRow(0);  // collapse
table.collapseAll();    // collapse all

table.on('expand',   ({ row, index }) => console.log('opened:', row));
table.on('collapse', ({ row, index }) => {{}});

const acc = new Accordion('#root', {{ multiple: false }});
acc.items = [
  {{ id: '1', label: 'Panel 1', content: '<p>Content A</p>', open: true }},
  {{ id: '2', label: 'Panel 2', content: '<p>Content B</p>' }},
];
acc.on('change', ({{ id, open }}) => console.log(id, open));

const tabs = new Tabs('#root', {{ variant: 'line' }});
tabs.items = [
  {{ id: 'a', label: 'Tab A', content: '...' }},
  {{ id: 'b', label: 'Tab B', content: '...', badge: 3 }},
];
tabs.on('change', ({{ id }}) => console.log(id));

const modal = new Modal({{ size: 'md' }});
modal.title   = 'Confirm';
modal.content = '<p>Are you sure?</p>';
modal.open();
modal.on('close', () => {{}});

const bc = new Breadcrumb('#root');
bc.items = [{{ label: 'Home', href: '/' }}, {{ label: 'Products', href: '/p' }}, {{ label: 'Laptop' }}];
bc.on('click', ({{ item }}) => navigate(item.href));

const stepper = new Stepper('#root');
stepper.steps   = ['Account', 'Profile', 'Review', 'Done'];
stepper.current = 1;
stepper.next();                   // advance
stepper.on('change', ({{ step }}) => {{}});

const pager = new Pagination('#root', {{ total: 200, pageSize: 20 }});
pager.on('change', ({{ page }}) => loadPage(page));

const menu = new Menu();
menu.items = [{{ id: 'edit', label: 'Edit', icon: '✏️' }}, {{ id: 'del', label: 'Delete', danger: true }}];
menu.openBelow(myButton);
menu.on('select', ({{ id }}) => {{}});

const btn = new Button('#r', {{ variant: 'primary' }});
btn.label   = 'Save';
btn.loading = true;
btn.on('click', () => save());

const tf = new TextField('#r', {{ label: 'Email', type: 'email' }});
tf.value = '[email protected]';
tf.error = 'Invalid format';
tf.on('change', ({{ value }}) => validate(value));

const sw = new Switch('#r', {{ label: 'Dark mode' }});
sw.checked = true;
sw.on('change', ({{ checked }}) => applyTheme(checked));

const dd = new Dropdown('#r', {{ searchable: true }});
dd.options = [{{ value: 'ch', label: 'Switzerland' }}];
dd.value   = 'ch';
dd.on('change', ({{ value }}) => {{}});

const badge = new Badge('#r', {{ variant: 'success' }});
badge.label = 'Active';

const av = new Avatar('#r', {{ size: 40, shape: 'circle' }});
av.name   = 'Riccardo Angeli'; // → 'RA'
av.status = 'online';

const pb = new ProgressBar('#r', {{ label: 'Upload', showValue: true }});
pb.value          = 65;
pb.indeterminate  = true;    // animated

Snackbar.show('File saved!', {{ variant: 'success', duration: 3000 }});

const bar = new BarChart('#root', {{ label: 'Monthly Sales' }});
bar.data = [{{ label: 'Jan', value: 120 }}, {{ label: 'Feb', value: 95 }}];
bar.on('click', ({{ bar }}) => console.log(bar.label));

const line = new LineChart('#root', {{ area: true, smooth: true }});
line.data = [{{ label: '00:00', value: 12 }}, {{ label: '01:00', value: 34 }}];

const pie = new PieChart('#root', {{ donut: true, legend: true }});
pie.data = [{{ label: 'EU', value: 42 }}, {{ label: 'US', value: 35 }}, {{ label: 'APAC', value: 23 }}];
pie.on('click', ({{ slice }}) => {{}});

import { Sidebar, SidebarCSS } from './arianna-controls/Sidebar.ts';

const style = document.createElement('style');
style.textContent = SidebarCSS;
document.head.appendChild(style);

const sidebar = new Sidebar('#shell', {
  orientation   : 'left',   // 'left' | 'right'
  width         : 260,
  minWidth      : 160,
  maxWidth      : 480,
  resizable     : true,
  collapsible   : true,
  collapsed     : false,
  collapsedWidth: 48,
  searchable    : true,
  showToggle    : true,
  persist       : true,
  storageKey    : 'my-app-nav',
});

sidebar.sections = [
  {
    id: 'core', label: 'Core Modules', open: true,
    items: [
      { id: 'real',    label: 'Real',    icon: '🌐' },
      { id: 'virtual', label: 'Virtual', icon: '🧩', badge: 'new' },
      { id: 'state',   label: 'State',   icon: '⚡', disabled: false },
    ],
  },
];
sidebar.active = 'real';

import Two from './additionals/Two.ts';

const two = Two.createRenderer('#app', { mode: 'svg', width: 600, height: 400 });
const stage = two.stage;

const c = new Two.Circle({ cx: 100, cy: 100, r: 60, style: { fill: '#e40c88' } });
stage.add(c);
two.render();

// Animate
new Two.Tween(c, { r: 100 }, 600).easing('easeOutBounce').start();
const loop = new Two.AnimationLoop(dt => two.render()).start();

import Three from './additionals/Three.ts';

const renderer = new Three.WebGPURenderer(canvas);
await renderer.init();

const scene  = new Three.Scene();
const camera = new Three.PerspectiveCamera(60, canvas.width/canvas.height, 0.1, 1000);
camera.position.set(0, 1, 3);

const mesh = new Three.Mesh(
  new Three.Box(1, 1, 1),
  new Three.PBRMaterial({ color: '#e40c88', roughness: 0.3 })
);
scene.add(mesh);

const orbit = new Three.OrbitControls(camera, canvas);
new Three.AnimationLoop(dt => {
  mesh.rotation.y += dt * 0.001;
  renderer.render(scene, camera);
}).start();

import AI from './additionals/AI.ts';

// Tensor operations
const a = AI.Tensor.randn([64, 128]);
const b = AI.Tensor.randn([128, 64]);
const c = await a.matmulGPU(b); // WebGPU compute shader

// Sequential model
const model = new AI.Sequential()
  .add(new AI.Dense(64,  { activation: 'relu', inputDim: 10 }))
  .add(new AI.Dense(32,  { activation: 'relu' }))
  .add(new AI.Dense(1,   { activation: 'sigmoid' }));
model.compile({ loss: 'binaryCrossEntropy', optimizer: 'adam', lr: 0.001 });

const losses = await model.fit(xTrain, yTrain, { epochs: 20, batchSize: 32, verbose: true });

import Finance from './additionals/Finance.ts';

// Technical indicators
const prices  = [100, 102, 98, 105, 110, 108, 115];
const sma14   = Finance.Indicators.sma(prices, 14);
const rsi14   = Finance.Indicators.rsi(prices, 14);
const { macd, signal, histogram } = Finance.Indicators.macd(prices);

// Black-Scholes
const price  = Finance.BlackScholes.price(100, 105, 0.25, 0.05, 0.2, 'call');
const greeks = Finance.BlackScholes.greeks(100, 105, 0.25, 0.05, 0.2);

// GPU Monte Carlo (1M paths)
const { price: mcPrice, stdError } =
  await Finance.MonteCarlo.optionGPU(100, 105, 0.25, 0.05, 0.2, 1_000_000);

import Data from './additionals/Data.ts';

// DAG
const dag = new Data.DAG<string>();
dag.addEdge('A', 'B').addEdge('B', 'C').addEdge('A', 'C');
console.log(dag.topoSort()); // ['A','B','C']

// FSM
const fsm = new Data.FSM('idle', [
  { from: 'idle', event: 'start', to: 'running' },
  { from: 'running', event: 'pause', to: 'paused' },
  { from: 'paused', event: 'resume', to: 'running' },
  { from: '*', event: 'stop', to: 'idle' },
]);
fsm.send('start'); console.log(fsm.state); // 'running'

// Trie
const trie = new Data.Trie<number>();
['apple','application','apply','banana'].forEach((w,i) => trie.insert(w,i));
console.log(trie.autocomplete('app')); // ['apple','application','apply']

// Priority Queue
const pq = new Data.PriorityQueue<number>();
[5,1,3,2,4].forEach(n => pq.push(n));
console.log(pq.pop()); // 1  (min-heap)

// Individual (tree-shakeable)
import { CandlestickChart } from './components/finance/CandlestickChart.ts';

// Bundle
import FinanceComponents from './components/finance/index.ts';
const { CandlestickChart, OrderBook, RiskGauge } = FinanceComponents;

const chart = new CandlestickChart('#container', {
  width: 700, height: 400, showVolume: true,
  bullColor: '#26a69a', bearColor: '#ef5350'
});
chart.render(bars); // Bar[] = { open, high, low, close, volume }

const chart = new LineChart('#container', { width: 600, height: 300 });
chart.render([
  { name: 'AAPL', data: [150, 158, 155, 162] },
  { name: 'MSFT', data: [280, 290, 285, 295] },
]);

const chart = new DepthChart('#container', { width: 600, height: 300 });
chart.render(
  bids, // [price, size][]  — sorted descending by price
  asks  // [price, size][]  — sorted ascending  by price
);

const chart = new HeatmapChart('#container', { width: 600, height: 400 });
chart.render(
  ['AAPL', 'MSFT', 'GOOG', 'AMZN'],
  // NxN correlation matrix (-1..1)
  [
    [1.0,  0.7,  0.6,  0.5],
    [0.7,  1.0,  0.8,  0.6],
    [0.6,  0.8,  1.0,  0.7],
    [0.5,  0.6,  0.7,  1.0],
  ]
);

const donut = new PortfolioDonut('#container', { size: 300 });
donut.render([
  { label: 'Equities',    value: 45 },
  { label: 'Bonds',       value: 25 },
  { label: 'Real Estate', value: 15 },
  { label: 'Commodities', value: 10 },
  { label: 'Cash',        value: 5  },
]);

const pnl = new PnLChart('#container', { width: 500, height: 250 });
pnl.render([
  { label: 'Q1', pnl:  12500 },
  { label: 'Q2', pnl:  -3800 },
  { label: 'Q3', pnl:   8200 },
  { label: 'Q4', pnl:  15700 },
]);

const gauge = new RiskGauge('#container', { size: 200 });
gauge.render(
  25,                  // value
  0, 100,             // min, max
  'Volatility'         // label
);
// Auto color: green <33% · amber 33-66% · red >66%

const book = new OrderBook('#container');
book.render(
  bids,         // [price, size][] — descending
  asks,         // [price, size][] — ascending
  10            // depth (rows per side)
);

const screen = new Screener('#container');
screen.render(
  [
    { symbol: 'AAPL', price: 175.32, change:  2.4,  volume: 52_300_000 },
    { symbol: 'MSFT', price: 412.10, change: -0.8,  volume: 28_700_000 },
    { symbol: 'GOOG', price: 142.80, change:  1.1,  volume: 19_400_000 },
  ],
  ['symbol', 'price', 'change', 'volume']  // optional column order
);

const spark = new Sparkline('#container');
spark.render(
  [100, 102, 98, 105, 110, 108, 115],
  { width: 100, height: 30 }
);
// Auto-colored: green if last >= first, red otherwise.
// Override with opts.color: '#e40c88'.

const badge = new AlertBadge('#container');

badge.render('AAPL +2.4%',    'info');
badge.render('TSLA -8.1%',    'danger',  'stop-loss');
badge.render('BTC volatility','warning', 'high');
badge.render('Market closed', 'neutral');

// Levels: 'neutral' | 'info' | 'warning' | 'danger'

import { Resizer, Rotator, Rounder, Mover } from './components/modifiers/2D/index.ts';

const r = new Resizer('#my-box', { minWidth: 80, handleColor: '#e40c88' });
r.onResize((el, w, h) => console.log(w, h));

const t = new Rotator('#my-box', { snap: 15 }); // snap to 15°
t.onRotate((el, angle) => console.log(angle));

// Rounder: per-corner mode
const ro = new Rounder('#my-box', { topLeft: 20, bottomRight: 40 });
ro.onRound((el, radius, corner) => console.log(corner, radius));

// Mover: drag with snap to 10×10 grid, bounded to parent
const mv = new Mover('#my-box', { snapX: 10, snapY: 10, bounds: 'parent' });
mv.onMove((el, x, y) => console.log(x, y));

import { SubdivisionModifier, WaveModifier } from './components/modifiers/3D/index.ts';

new SubdivisionModifier(mesh, 2).apply(); // 2 iterations

const wave = new WaveModifier(mesh, { amplitude: 0.3, frequency: 3 });
let t = 0;
loop(() => { wave.apply(t += 0.016); }); // animate

interface PianoRollNote {
  pitch:    number;   // MIDI 0-127 (C-1 to G9)
  start:    number;   // in beats (1 beat = quarter note)
  duration: number;   // in beats
  velocity: number;   // 0-127
  channel?: number;   // MIDI channel 1-16
}

interface ExportedSequence {
  bpm:     number;
  bars:    number;
  timeSig: [number, number];
  notes:   PianoRollNote[];
}

import { PianoRoll } from 'ariannajs/components/audio/PianoRoll';

const pr = new PianoRoll('#root', {
  bpm:       120,
  bars:      8,
  pitchLow:  36,    // C2
  pitchHigh: 96,    // C7
  snap:      0.25,  // 1/16th
});

// Listen to MIDI events during playback — connect to your synth here
pr.on('midi', evt => {
  // evt = { type: 'note-on'|'note-off', pitch, velocity, channel, time }
  mySynth.send(evt);
});

// Programmatic note creation
pr.addNote(60, 0, 1, 100);   // C4 at beat 0, 1 beat long
pr.addNote(64, 1, 1, 100);   // E4
pr.addNote(67, 2, 2, 90);    // G4 longer, softer

pr.play();

// Round-trippable JSON
const json = pr.export();
pr.load(json);

import { AudioPlayer } from 'ariannajs/components/audio';

const p = new AudioPlayer('#root', {
  src:      'song.mp3',
  loop:     false,
  volume:   0.8,
  autoplay: false,
});

// Listen to playback events
p.on('timeupdate', e => console.log(e.time, e.duration));
p.on('ended',      ()  => console.log('done'));

// Web Audio routing — chain into a ChannelStrip or any AudioNode
p.connect(strip);

// Programmatic control
p.play();
p.pause();
p.seek(30);                 // jump to 30s
p.setVolume(0.5);

import { VideoPlayer } from 'ariannajs/components/video';

const v = new VideoPlayer('#root', {
  src:         'movie.mp4',
  poster:      'poster.jpg',
  loop:        false,
  aspectRatio: '16/9',
});

// Listen to events
v.on('loaded',     e => console.log(e.width, e.height));
v.on('timeupdate', e => updateSubtitles(e.time));

// Web Audio routing on the audio track
v.connect(strip);

// Fullscreen
v.fullscreen();

input → gain → EQ low → EQ mid → EQ high → pan → fader → output (analyser)

import { ChannelStrip } from 'ariannajs/components/audio';

const strip = new ChannelStrip('#strip', {
  name:  'Lead Vox',
  color: '#e40c88',
  fader: 0,             // dB
  pan:   0,             // -1..+1
});

// Route audio through it
somePlayer.connect(strip);
strip.connect(masterStrip);
masterStrip.connect(AudioComponent.context.destination);

// Programmatic control
strip.setEQ('low',  { gain: 3, freq: 100 });
strip.setEQ('mid',  { gain: -2, freq: 1500, q: 2 });
strip.setEQ('high', { gain: 1.5, freq: 8000 });
strip.setFader(-6);
strip.setMute(true);

strip.on('change', e => console.log(e.kind, e.value));

import { AudioEditor } from 'ariannajs/components/audio';

const ed = new AudioEditor('#root');

// Load a buffer
const buf = await ed.loadFile(file);   // File or URL
ed.setBuffer(buf);

// Edit operations (all push undo)
ed.setSelectionTime(1.5, 3.0);
ed.fadeIn();                       // linear fade on selection
ed.normalize(-3);                  // peak to -3 dBFS
ed.gain(2);                        // +2 dB on selection
ed.cut();
ed.paste();

// Get the post-edit AudioBuffer
const out = ed.getBuffer();

ed.on('change',    e => console.log(e.kind));
ed.on('selection', e => console.log(e.start, e.end));

import { AudioTrackEditor } from 'ariannajs/components/audio';

const ed = new AudioTrackEditor('#root', {
  tracks: 4,
  bpm:    120,
});

// Add a clip from a buffer
const buf = await ed.loadFile('vocals.wav');
ed.addClip('t1', { buffer: buf, start: 0, name: 'Take 1' });

// Programmatic split
ed.splitClip(clipId, 5.5);     // split at 5.5s on timeline

// Track management
ed.addTrack({ id: 'fx', name: 'FX', color: '#3b82f6' });
ed.removeTrack('t3');

// Playback honors mute/solo state per track
ed.play();
ed.pause();

ed.on('change', e => console.log(e.kind));

import { VideoTrackEditor } from 'ariannajs/components/video';

const ed = new VideoTrackEditor('#root', { tracks: 3 });

// Load a source — generates thumbnails automatically
const src = await ed.loadSource('clip.mp4');
ed.addClip('v1', {
  source:   src,
  start:    0,            // timeline position in seconds
  sourceIn: 0,            // in-point inside source
  duration: 5,
});

// Split, trim, move
ed.splitClip(clipId, 2.5);

// Serialize the project (sources, tracks, clips)
const project = ed.export();
fs.writeFileSync('project.json', JSON.stringify(project, null, 2));

ed.on('change', e => console.log(e.kind));

// Frontend
import { invoke } from '@tauri-apps/api/tauri';
const project = ed.export();
const outFile = await invoke('render_project', { project });

import { NodeEditor } from 'ariannajs/components/composite/NodeEditor';

const editor = new NodeEditor('#root', {
  schemas: [
    {
      type: 'source.timer',
      name: 'Timer',
      category: 'Source',
      color: '#3b82f6', icon: '⏱',
      inputs:  [],
      outputs: [{ id: 'tick', type: 'number', label: 'tick' }],
    },
    {
      type: 'ai.llm',
      name: 'LLM Agent',
      category: 'AI',
      color: '#10b981', icon: '🧠',
      inputs:  [
        { id: 'prompt', type: 'string', label: 'prompt' },
        { id: 'ctx',    type: 'json',   label: 'context' },
      ],
      outputs: [
        { id: 'reply', type: 'string', label: 'reply' },
        { id: 'usage', type: 'json',   label: 'usage' },
      ],
    },
    {
      type: 'sink.log',
      name: 'Console',
      category: 'Sink',
      color: '#64748b', icon: '▣',
      inputs:  [{ id: 'in', type: 'any', label: 'in' }],
      outputs: [],
    },
  ],
});

editor.on('graph-change', () => {
  console.log('graph:', editor.export());
});

# Global install
npm install -g arianna

# Or use without installing
npx arianna <command>

arianna new my-app
# Creates:
#   my-app/
#   ├── index.html
#   ├── src/main.ts
#   └── tsconfig.json

cd my-app
arianna serve      # http://localhost:3000

arianna new my-tauri-app --template tauri
# Creates browser scaffold + src-tauri/ with Cargo.toml and tauri.conf.json

cd my-tauri-app
cargo tauri dev

arianna generate component MyCard
# → src/components/MyCard.ts
# Exports: class MyCard with el, signal, destroy()

arianna generate state AppState
# → src/AppState.ts
# Exports: AppState with signal(), computed(), reset()

arianna generate test MyCard
# → src/tests/MyCard.ts
# Basic test scaffold

arianna build --minify
# → dist/arianna.js  (ESM bundle, minified)
# Uses esbuild — install separately: npm i -D esbuild

# In your HTML:
<script type="module">
  import { Real, signal } from './dist/arianna.js';
</script>

node arianna-cli.mjs component <ComponentName> [--dir <dir>]

# Examples
node arianna-cli.mjs component MyButton
node arianna-cli.mjs component UserCard    --dir src/ui/components
node arianna-cli.mjs component DataWidget  --dir src/features/dashboard

src/components/MyButton/
├── MyButton.ts        ← component (Decorators + commented Real/Virtual/JSX)
├── MyButton.css.ts    ← CSS-in-JS via Rule/Sheet
├── MyButton.test.ts   ← test file (AriannA test pattern)
└── index.ts           ← barrel export

import {{ Component, Prop, Watch, Emit }} from '../arianna-ts/index.ts';

@Component({{ tag: 'my-button' }})
export class MyButton extends HTMLElement {{
  @Prop() label    = 'MyButton';
  @Prop() disabled = false;

  @Watch('label')
  onLabelChange(next: string) {{
    const el = this.querySelector('.my-button__label');
    if (el) el.textContent = next;
  }}

  @Emit('my-button-click')
  handleClick() {{ return {{ label: this.label }}; }}

  connectedCallback() {{
    this.innerHTML = `
      <div class="my-button">
        <span class="my-button__label">\${{this.label}}</span>
      </div>
    `;
    if (!this.disabled)
      this.addEventListener('click', () => this.handleClick());
  }}
}}

// Use: <my-button label="Save"></my-button>

import {{ Rule, Sheet }} from '../arianna-ts/index.ts';

export const MyButtonSheet = new Sheet(
  new Rule('.my-button', {{ padding: '8px 16px', borderRadius: '5px', cursor: 'pointer' }}),
  new Rule('.my-button:hover', {{ background: 'var(--ar-bg4)' }}),
  new Rule('.my-button--disabled', {{ opacity: '0.45', cursor: 'not-allowed' }}),
);
export function injectMyButtonStyles() {{ MyButtonSheet.inject(document.head); }}

# Node.js ≥ 20, npm or pnpm
node arianna-cli.mjs create browser my-site

cd arianna-projects/my-site
npm install
npm run dev      # → http://localhost:3000 (Vite HMR)
npm run build    # → dist/ (ES modules bundle)
npm run check    # TypeScript check

my-site/
├── index.html          ← entry point
├── src/
│   ├── main.ts         ← AriannA app entry
│   └── app.ts          ← components
├── tsconfig.json
├── vite.config.ts
└── package.json

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Tauri CLI
cargo install tauri-cli

# Create project
node arianna-cli.mjs create tauri-macos my-desktop

cd arianna-projects/my-desktop
npm install
npm run dev      # Tauri dev window (hot reload)
npm run build    # → src-tauri/target/release/bundle/
                 #   dmg/ → macOS disk image
                 #   app/ → .app bundle

my-desktop/
├── index.html
├── src/main.ts         ← AriannA frontend
├── src-tauri/
│   ├── src/lib.rs      ← #[tauri::command] handlers
│   ├── src/main.rs     ← entry point
│   ├── Cargo.toml
│   ├── tauri.conf.json ← bundle config, signingIdentity
│   └── capabilities/   ← permissions
└── vite.config.ts

# Add iOS Rust targets
rustup target add aarch64-apple-ios x86_64-apple-ios

# Install Tauri CLI
cargo install tauri-cli

# Create project
node arianna-cli.mjs create tauri-ios my-iphone-app

cd arianna-projects/my-iphone-app
npm install
npm run sim      # iOS Simulator
npm run dev      # Connected iPhone (USB debugging)
npm run build    # → .ipa

my-iphone-app/
├── index.html          ← viewport-fit=cover (notch + home indicator)
├── src/main.ts         ← AriannA UI
├── src-tauri/
│   ├── src/lib.rs      ← Tauri commands
│   ├── Cargo.toml      ← iOS target deps
│   └── tauri.conf.json
└── vite.config.ts      ← Safari 16 target

# Install Rust on Windows
winget install Rustlang.Rustup
rustup toolchain install stable

# Install WiX Toolset (for MSI)
winget install WixToolset.WixToolset

# Install Tauri CLI
cargo install tauri-cli

node arianna-cli.mjs create windows my-win-app

cd arianna-projects/my-win-app
npm install
npm run dev      # Dev window with HMR
npm run build    # → src-tauri/target/release/bundle/
                 #   msi/  → Windows Installer
                 #   nsis/ → NSIS installer

my-win-app/
├── index.html
├── src/main.ts          ← AriannA frontend (auto dark/light)
├── src-tauri/
│   ├── src/lib.rs       ← Tauri commands
│   ├── src/main.rs      ← windows_subsystem = "windows"
│   ├── Cargo.toml
│   └── tauri.conf.json  ← bundle.targets: [msi, nsis]
└── vite.config.ts       ← chrome105 target

# Add Android Rust targets
rustup target add aarch64-linux-android armv7-linux-androideabi
rustup target add x86_64-linux-android i686-linux-android

# Set environment variables
export ANDROID_HOME=~/Android/Sdk
export NDK_HOME=$ANDROID_HOME/ndk/26.x.x

# Install Tauri CLI
cargo install tauri-cli

node arianna-cli.mjs create android my-android-app

cd arianna-projects/my-android-app
npm install
npm run emulator   # Android Emulator
npm run dev        # Connected device (USB debugging)
npm run apk        # Debug APK
npm run build      # Signed AAB → Play Store

my-android-app/
├── index.html          ← viewport user-scalable=no, safe-area
├── src/main.ts         ← AriannA UI (touch optimized)
├── src-tauri/
│   ├── src/lib.rs      ← #[tauri::command] handlers
│   ├── Cargo.toml      ← Android target deps (API 24+)
│   └── tauri.conf.json ← minSdkVersion: 24
└── vite.config.ts      ← chrome114 target (Android WebView)

import { TransportBar } from 'arianna/components/composite';

const bar = new TransportBar('#mount', {
  bpm           : 120,
  timeSignature : '4/4',
  framerate     : 30,
  mode          : 'bars',    // or 'smpte'
});
bar.on('play',  () => engine.start());
bar.on('pause', () => engine.pause());
bar.on('stop',  () => engine.stop());

import { Chat } from 'arianna/components/composite';

const chat = new Chat('#mount', {
  me   : { id: 'u1', name: 'Riccardo', avatar: '/me.png' },
  peers: [{ id: 'u2', name: 'Arianna' }],
  messages: [
    { id: 'm1', from: 'u2', text: 'Hey!', at: Date.now() - 3600e3 },
    { id: 'm2', from: 'u1', text: 'Doing great 🎉', at: Date.now(), status: 'read' },
  ],
  features: { reactions: true, threads: true, typing: true },
});
chat.on('send',    e => api.send(e.message));
chat.on('react',   e => api.react(e.messageId, e.emoji));