@llmnative/react 2.4.0 → 3.0.0

package/llms-full.txt

@@ -1,1657 +1,1690 @@
-# @llmnative/react — Riferimento completo
-
-Framework React AI-first per generazione deterministica di UI. Data-driven di default, schema-driven opzionale.
-Versione 1.0.0 — Apache-2.0
-
-```bash
-npm install @llmnative/react
-import '@llmnative/react/dist/index.css'
-```
-
----
-
-## Regole fondamentali
-
-- Tutti gli import da `'@llmnative/react'` — mai da sottodirectory
-- I provider sono iniettati via `<App providers={...}>` — mai importati direttamente nei componenti
-- Usare `useDataProvider()`, `useAuthProvider()`, ecc. nei componenti, non istanze dirette
-- TypeScript strict: no `any` — usare `unknown`, `Record<string, unknown>`, tipi specifici
-- Naming props: `view` (presentazione contenuto), `appearance` (guscio visuale), `layout` (disposizione spaziale), `mode` (comportamento operativo), `variant` (tono semantico), `position` (ancoraggio), `size` (scala)
-
----
-
-## App — Entry point
-
-```tsx
-<App
-  providers={{
-    firebase: {                        // FirebaseConfig — tutte le chiavi flat
-      apiKey, authDomain, databaseURL, projectId,
-      storageBucket, messagingSenderId, appId,
-    },
-    supabase: { url, anonKey },
-    google: { clientId, scope },       // flat — NON { oAuth2: { clientId } }
-    dropbox: { clientId },             // DropboxConfig
-    mock: { data: mockData },
-    ai: {                              // AIConfig — NON una prop separata di <App>
-      openaiApiKey, geminiApiKey, anthropicApiKey,
-      deepSeekApiKey, mistralApiKey, openRouterApiKey,
-      groqApiKey,
-      cloudflare: { apiToken, accountId }, // Cloudflare Workers AI
-    },
-    proxy: { enable: true, route: '/api/proxy' },
-    custom: { data: { myAdapter: new MyDataProvider() } },
-    services: {
-      data:        'dbRealtime',      // DataDriverName
-      storage:     'firestorage',     // StorageDriverName | null
-      auth:        'googleAuth',      // AuthDriverName | null
-      email:       'gmail',           // EmailDriverName | null
-      ai:          'openai',          // AIDriverName | null
-      credentials: 'googleServiceAccount',
-    },
-  }}
-  iconProvider="lucide"              // 'lucide' | 'phosphor' | AppIconProviderConfig
-  themeProvider="default"            // 'default' | 'flat' | 'cyber' | AppThemeProviderConfig
-  menuConfig={menuConfig}
-  importPage={(path) => import(path)}
-  LayoutDefault={MyLayout}           // layout wrapper custom (opzionale): avvolge ogni voce di menuConfig senza `layout`
-  appName="MyApp"                    // nome app (opzionale)
-  i18n={{ locale: 'it', translations: { ... } }}
-  contextProviders={MyContextProvider}
-  errorReportUrl="/api/errors"
-  debug={import.meta.env.DEV}
-/>
-```
-
-### Testi dei componenti (i18n)
-
-I testi fissi dei componenti vengono da `I18nDict` e seguono `i18n.locale` (en, it, de, ru, ar, zh
-inclusi): un testo si cambia con `i18n.translations`, non nel codice. Namespace dei componenti:
-`notifications` (`markAllRead`, `empty`, `emptyHint`), `errorBoundary` (schermata d'errore; fuori da
-`<I18nProvider>`, come l'`ErrorBoundary` radice di `<App>`, resta in inglese), `themeSwitcher`,
-`imageField` (anche i dialoghi immagine di `RichText`), `richText`, `tabDynamic` (`addTab`),
-`breadcrumbs` (`label`, l'`aria-label` del `nav`), `grid` (`tableView`, `galleryView`, `columns`,
-`fields`), `prompt` (anche `Chatbot`: `role`, `language`, `voice`, `style`, `temperature`, `stop`),
-`chat` (`ChatReasoning` e `ChatQuestions`: `reasoning`, `reasoningFor`, `other`, `review`, `submit`, …;
-il codice di `ChatMarkdown` usa `code`).
-
-```tsx
-<App i18n={{ locale: 'it', translations: { it: { notifications: { emptyHint: 'Niente di nuovo' } } } }} />
-```
-
-### AppThemeProviderConfig
-```ts
-{
-  mode?: 'light' | 'dark' | 'system';
-  theme: string;
-  themes?: Record<string, {
-    preset?: { colors?: ColorScale; radius?: number; font?: string };
-    motion?: MotionRegistry;
-    components?: Record<string, Partial<ThemeComponent>>;
-  }>;
-  themeOverride?: Record<string, Partial<ThemeComponent>>;
-}
-```
-
-Built-in themes: `default`, `flat`, `cyber`, `vscode-dark-modern`, `vscode-light-modern`, `vscode-dark-plus`, `vscode-light-plus`, `tokyo-night`, `tokyo-night-light`.
-The VS Code and Tokyo Night themes are compiled from the original VS Code theme JSON (`scripts/themes/vscode`), filling the keys a theme does not list with VS Code's color registry defaults; each one has both modes (`vscode-dark-*` starts dark, `vscode-light-*` light). Status colors (destructive/success/warning/info) stay the framework's.
-
-`ColorScale` tokens: `background`, `foreground`, `canvas` (page floor behind cards and panels, `bg-canvas`; falls back to `background`), `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `success`, `warning`, `info` (each with its `*Foreground`), `border`, `input` (border of form fields), `ring`. A consumer bridging the tokens in its own `@theme inline` adds `--color-canvas: hsl(var(--rf-canvas, var(--rf-background)));`.
-
-**The frame of the app** (CR-126), as the title bar, side bar and status bar of the IDE: `header`, `headerForeground`, `headerBorder`, `sidebar`, `sidebarForeground`, `sidebarBorder`, `sidebarAccent` (the selected entry), `sidebarAccentForeground`, `footer`, `footerForeground`, `footerBorder`. The IDE themes carry them (VS Code Light+: gray title bar, blue status bar); a theme without them falls back to the base tokens (header and footer on `background`, sidebar on `card`, borders on `border`). Utilities: `bg-header text-header-foreground border-header-border`, `bg-sidebar …`, `bg-footer …`. `SideNav` draws itself with the sidebar tokens. The top bar and status bar of a layout:
-
-```tsx
-<header className="flex h-14 shrink-0 items-center gap-3 border-b border-header-border bg-header px-4 text-header-foreground">…</header>
-<footer className="shrink-0 border-t border-footer-border bg-footer px-4 py-1.5 text-xs text-footer-foreground">…</footer>
-```
-
-A border without a color class (`border`, `border-b`) is the theme's `border`, not the text color. The scaffold (`npx @llmnative/react create`) starts in `vscode-light-modern` and bridges all these tokens in `src/styles/globals.css`; a consumer scaffolded before adds the `--color-header…`/`--color-sidebar…`/`--color-footer…` lines of `src/globals.css` to its own `@theme inline`.
-
----
-
-## Provider System
-
-### Matrix completa
-
-| Servizio | Interfaccia | Driver | Config key | Obbligatorio |
-|---|---|---|---|---|
-| data | `DataProviderAdapter` | `mock`, `dbRealtime`, `firestoreDb`, `supabaseDb` | `providers.mock/firebase/supabase` | sì (fallback: mock) |
-| storage | `StorageProviderAdapter` | `firestorage`, `supabaseStorage` | `providers.firebase/supabase` | no |
-| auth | `AuthProviderAdapter` | `googleAuth`, `firebaseAuth`, `supabaseAuth`, `dropboxAuth`, `githubAuth` | `providers.google/firebase/supabase/dropbox/github` | sì (fallback: googleAuth) |
-| email | `EmailProviderAdapter` | `gmail` | `providers.google` | no |
-| ai | `AIProviderAdapter` | `openai`, `gemini`, `anthropic`, `deepseek`, `mistral`, `openrouter`, `opencode`, `opencode-go`, `cloudflare`, `groq` | `Config.tsx AIConfig` | no |
-| credentials | `CredentialsAdapter` | `googleServiceAccount` | `providers.google.serviceAccount` | no |
-
-### Firebase: quale app usano auth, dati e storage
-
-- `providers.firebase` inizializza l'app Firebase **di default** dell'SDK (`[DEFAULT]`). `firestoreDb` e `firestorage` la
-  usano, e il driver `firebaseAuth` (`services.auth: 'firebaseAuth'`) fa login su quella stessa app: login, Firestore
-  e Storage condividono la sessione.
-- Un'app che chiama già `initializeApp(config)` per conto suo condivide l'app di default con il framework solo se ha lo
-  **stesso `appId`**. Con un `appId` diverso il framework chiude quell'app e la reinizializza con la propria config, e
-  la sessione dell'app cade. Per questo il client Firebase si crea una volta sola: o `providers.firebase`, o il codice
-  dell'app con la stessa config.
-- Una sessione separata, che non deve cadere quando l'app di default cambia (cambio di tenant): istanziare
-  `new FirebaseAuthProvider({ config, appName: 'control-plane' })`. `appName` è un'app con un nome suo; senza
-  `config` usa un'app già inizializzata con quel nome.
-- Le Cloud Functions callable: `callFirebaseFunction(name, data, appName?, region?)`, sull'app di default se non si
-  passa `appName`. Il token della sessione lo aggiunge l'SDK.
-
-### Layout per voce di menu
-
-Ogni voce di `menuConfig` è una route. Viene avvolta da `item.layout` se presente, altrimenti da `LayoutDefault` di
-`<App>`, altrimenti da `LayoutEmpty`. Una pagina con un guscio diverso, per esempio l'accesso a tutta pagina senza
-sidebar, dichiara `layout` sulla sua voce:
-
-```tsx
-export const menuConfig: MenuConfig = {
-  main: [
-    { path: '/', title: 'Home', icon: 'home', page: HomePage },          // LayoutDefault
-  ],
-  public: [
-    { path: '/login', page: LoginPage, layout: AccessLayout },           // senza header né sidebar
-  ],
-};
-```
-
-La home va dichiarata con `path: '/'`: senza quella voce, `/` mostra "Missing Page".
-
-### Voci di menu e rotte
-
-`SideNav menuKey="main"` e `Menu menuKey="main"` mostrano solo le **voci**: le route di quella chiave con `title`,
-senza `hidden: true`, senza parametri (`:token`) e senza `*`. Le altre sono rotte e basta (CR-126). Ogni voce
-mostrata ha `title` **e** `icon`. Una pagina raggiunta da un link (accesso, invito, impostazioni dal menu utente)
-sta in una chiave che nessun menu mostra, oppure ha `hidden: true`:
-
-```tsx
-export const menuConfig: MenuConfig = {
-  main: [
-    { path: '/', title: 'Dashboard', icon: 'layout-dashboard', page: HomePage },
-    { path: '/contacts', title: 'Contatti', icon: 'users', page: ContactsPage },
-    { path: '/settings', title: 'Impostazioni', icon: 'settings', page: SettingsPage, hidden: true },
-  ],
-  routes: [
-    { path: '/invite/:token', page: InvitePage, layout: AccessLayout },
-    { path: '*', page: NotFoundPage },
-  ],
-};
-```
-
-### Hooks
-
-```ts
-const data    = useDataProvider()           // DataProviderAdapter | null
-const storage = useStorageProvider()        // StorageProviderAdapter | null
-const auth    = useAuthProvider()           // AuthProviderAdapter | null
-const email   = useEmailProvider()          // EmailProviderAdapter | null
-const ai      = useAIProvider()             // AIProviderAdapter | null
-const creds   = useCredentialsProvider()    // CredentialsAdapter | null
-
-// Named provider (multi-provider setup)
-const supabase = useDataProvider('supabase')
-```
-
-### GitHub (`githubAuth`, sessione sul server dell'app)
-
-GitHub richiede il client secret per scambiare il codice: scambio, token e sessione stanno sul server
-dell'app, il browser vede solo il profilo. Config `providers.github = { sessionUrl: '/api/auth/github' }`,
-driver `auth: 'githubAuth'`; funziona con `AuthButton` (pulsante e `aspect="avatar"`) e
-`useAuthProvider('githubAuth')`. Il server espone sotto `sessionUrl`:
-
-| Rotta | Risposta |
-|---|---|
-| `GET /login?returnTo=<path>[&scope=…]` | redirect a GitHub, poi di nuovo a `<path>` |
-| `GET /me` | `{ login, name, avatarUrl, email }`, 401 senza sessione |
-| `POST /logout` | chiude la sessione |
-
-Lato server, da `@llmnative/react/server`:
-
-```ts
-const oauth = createGitHubOAuth({ clientId, clientSecret, scopes: ['read:org'] })
-oauth.authorizeUrl({ state, redirectUri, codeChallenge })   // PKCE S256
-const { accessToken } = await oauth.exchangeCode({ code, redirectUri, codeVerifier })  // GitHubOAuthError se rifiutato
-await oauth.getUser(accessToken)            // { login, name, avatarUrl, email }
-await oauth.getOrganizations(accessToken)   // [{ login, avatarUrl, role: 'admin' | 'member' }]
-```
-
-### Interfacce principali
-
-```ts
-// DataProviderAdapter
-read(path, { where?, order?, limit?, toArray?, exception? }) / set(path, data, exception?) / update(path, data, exception?) / remove(path, exception?)
-subscribe(path, callback: (records: RecordArray) => void, { where?, order?, limit?, fieldMap?, onLoad?, onError? }): () => void
-count?(path): Promise<number>
-
-// StorageProviderAdapter
-upload(file, path): Promise<string|undefined>
-getURL(path) / download(path): Promise<Blob|undefined> / delete(path): Promise<boolean>
-
-// AuthProviderAdapter
-signIn(intent?, options?) / signOut() / getUser(): UserProfile|null
-onAuthChange(callback) / getAccessToken(): Promise<string|null>
-```
-
-### Auth sign-in methods
-
-| method | Firebase | Supabase | Google |
-|---|---|---|---|
-| `password` | ✅ | ✅ | — |
-| `anonymous` | ✅ | ✅ | — |
-| `magic_link` | — | ✅ | — |
-| `oauth` (github, apple…) | ✅ | ✅ | — |
-| GIS + scoped token | — | — | ✅ |
-
-```ts
-await auth.signIn({ method: 'password', email: '...', password: '...' })
-await auth.signIn({ method: 'oauth', provider: 'github' })
-// Google: token per API scope
-const token = await auth.getAccessToken('https://www.googleapis.com/auth/gmail.send')
-```
-
-### Schermate di accesso e gate senza redirect (CR-127)
-
-Le schermate sono pronte: non scriverne a mano. Non conoscono il backend: ricevono le funzioni da
-chiamare (una promessa) e mostrano l'errore lanciato tradotto, mai il testo grezzo del servizio
-(`authErrorMessage`: codici di Firebase e Supabase, `AuthFlowError(reason)` per le funzioni tue).
-Testi nel namespace `access` delle 6 lingue. Ognuna ha `brand`, `toolbar`, `footer`, `bare` (solo il
-contenuto, in una modale), `errorMessage(error)`.
-
-| Componente | Cosa fa | Funzioni |
-|---|---|---|
-| `SignIn` | provider esterni, email + password, codice via email, in qualsiasi combinazione | `onPasswordSignIn({email,password})`, `onRequestCode(email)` + `onVerifyCode(email,code)`, `providers` + `onProviderSignIn(id)` |
-| `SignUp` | nome, email, password con i requisiti mentre si scrive, termini; poi "controlla la tua email" | `onSignUp({name,email,password})` → `{ needsEmailVerification }`, `onResendVerification(email)` |
-| `ForgotPassword` | email → stessa risposta con o senza account, nuovo invio dopo un'attesa | `onSendReset(email)` |
-| `ResetPassword` | nuova password dal link dell'email; link scaduto | `onResetPassword(password)`, `invalidLink` |
-| `VerifyEmail` | attivazione: con `code` verifica subito, senza aspetta la conferma | `onVerify(code)`, `onResend()`, `onContinue()` |
-| `VerifyCode` | codice di N cifre in caselle, inviato a codice completo | `onVerify(code)`, `onResend()`, `onChangeEmail()` |
-| `OneTimeCodeInput` | le caselle da sole (incolla, avanti/indietro, `one-time-code`) | `value`, `onChange`, `onComplete` |
-| `AuthLayout` | la cornice di una schermata (marchio, card, titolo, piè di pagina) | — |
-| `AuthGate` | la pagina solo con la sessione; senza, `fallback` al suo posto | `allow(user)`, `denied`, `loading` |
-
-```tsx
-import { App, SignIn, AuthFlowError } from '@llmnative/react';
-
-// Tutta l'app riservata: senza sessione ogni pagina mostra l'accesso al suo posto, l'indirizzo
-// resta quello aperto e dopo l'accesso compare la pagina. Nessuna pagina /login, nessun redirect.
-<App
-  menuConfig={{ main: [...], access: [{ path: '/invito/:token', page: InvitePage, public: true }] }}
-  authGate={{
-    fallback: <SignIn providers={['google', 'apple']} onProviderSignIn={enter}
-                      onRequestCode={sendCode} onVerifyCode={checkCode} appName="CRM" />,
-    allow: async (user) => (await isMember(user)),   // altrimenti "Accesso non consentito"
-  }}
-/>
-
-// Una funzione tua che rifiuta: la schermata dice "Il codice non è corretto o è scaduto."
-async function checkCode(email: string, code: string) {
-  const { token } = await callFunction('verifyLoginCode', { email, code }).catch(() => {
-    throw new AuthFlowError('invalidCode');
-  });
-  await signInWithCustomToken(token);
-}
-```
-
-Con gli adapter del framework `useAuthFlows(provider?, { verifyEmailPath, resetPasswordPath })` dà le
-funzioni pronte (`<SignIn {...flows.signIn} />`, `flows.signUp`, `flows.forgotPassword`,
-`flows.resetPassword(linkCode())`, `flows.verifyEmail`). Metodi opzionali di `AuthProviderAdapter`:
-
-| Metodo | Firebase | Supabase | `mockAuth` |
-|---|---|---|---|
-| `whenReady` (il gate aspetta la sessione) | ✅ | ✅ | ✅ (anche `githubAuth`) |
-| `signUp`, `sendPasswordReset`, `confirmPasswordReset` | ✅ | ✅ | ✅ |
-| `sendEmailVerification`, `verifyEmail` | ✅ | ✅ | ✅ |
-| `requestEmailCode`, `verifyEmailCode` | — (serve una funzione tua) | ✅ | ✅ |
-
-`useAuthSession(provider?)` dà `{ user, ready, signOut }`. `linkCode()` legge il codice del link
-(`oobCode`, `token_hash`, `code`). `mockAuth` (`providers.mock.auth: true`) è solo per demo e test:
-qualsiasi email e password, codice `123456`; con `accounts` rifiuta le credenziali sbagliate.
-Link delle email: in Firebase imposta l'URL di azione sulle tue pagine (`/reset-password`,
-`/verify-email`); in Supabase usa `{{ .TokenHash }}` nei template delle email.
-
-### CredentialsAdapter (Google Service Account)
-```tsx
-// Chiama Google APIs lato browser senza Node.js
-<App providers={{ google: { serviceAccount: { clientEmail, privateKey } }, services: { credentials: 'googleServiceAccount' } }} />
-
-const creds = useCredentialsProvider()
-const token = await creds.getToken('https://www.googleapis.com/auth/solar')
-```
-
-### Letture: filtri, `limit`, errori (CR-129)
-
-Gli stessi operatori e lo stesso contratto su ogni provider (`firestoreDb`, `supabaseDb`, `dbRealtime`, `mock`):
-l'adapter li traduce nei comandi del database, o li applica nel browser dove il database non li ha.
-
-| `where` | Significato | Firestore | Supabase | Realtime DB / Mock |
-|---|---|---|---|---|
-| `{ f: 'x' }` / `{ f: { eq } }` | uguale | `==` | `eq` | server sul campo di `order`, altrimenti browser |
-| `lt` `lte` `gt` `gte` | confronto | `<` … `>=` | `lt` … `gte` | idem |
-| `{ f: ['a','b'] }` / `in`, `nin` | uno dei valori / nessuno | `in` (≤30), `not-in` (≤10) | `in`, `not.in` | browser |
-| `contains: v` | il campo lista contiene `v` | `array-contains` | `contains` | browser |
-| `containsAny: [..]` | contiene almeno uno | `array-contains-any` (≤30) | `overlaps` | browser |
-
-`limit: n` (in `read` e `subscribe`) tiene i primi `n` dopo `where` e `order`: Firestore `limit()`, Supabase
-`.limit()`, Realtime Database `limitToFirst`/`limitToLast` (nel browser se restano filtri da applicare lì).
-
-Un'iscrizione che il database rifiuta (regole, sessione, indice mancante, rete) arriva a `onError` come
-`DataProviderError` con `code`: `permission-denied` | `unauthenticated` | `invalid-query` | `unavailable` |
-`unknown` (l'errore originale in `cause`). Senza `onError` il provider la scrive in console come prima.
-Un percorso di record (`/users/u1`) segue quel record su ogni provider.
-
-```ts
-const { records, loading, error } = useDataSubscription('/registro', { order: { at: 'desc' }, limit: 50 })
-// error?.code === 'permission-denied' → la pagina dice che non può leggere, invece di restare in caricamento
-db.subscribe('/posts', setRecords, { where: { tags: { contains: 'news' } }, limit: 20, onError: (e) => show(e.code) })
-```
-
-`Grid` con `path` mostra `common.loadError` al posto delle righe quando la lettura fallisce.
-
-### Provider custom
-```ts
-import { DataProviderAdapter, RecordArray } from '@llmnative/react'
-
-export class RestDataProvider implements DataProviderAdapter {
-  async read(path: string): Promise<unknown> { ... }
-  async set(path: string, data: object): Promise<void> { ... }
-  async update(path: string, data: object): Promise<void> { ... }
-  async remove(path: string): Promise<void> { ... }
-  subscribe(path: string | undefined, callback: (records: RecordArray) => void): () => void {
-    return () => undefined
-  }
-}
-```
-
----
-
-## Grid — CRUD table/gallery
-
-```tsx
-<Grid
-  path="/users"               // DataProvider-backed — oppure records={array} per in-memory
-  columns={[
-    { key: 'name',  label: 'Nome',   sortable: true },
-    { key: 'email', label: 'Email' },
-    { key: 'role',  label: 'Ruolo',  render: ({ value }) => <Badge>{value}</Badge> },
-    { key: 'date',  label: 'Data',   render: 'date' },
-  ]}
-  actions={['add', 'edit', 'delete']}   // oppure Record<string, GridAction>
-  view="table"                          // 'table' | 'gallery'
-  pagination={{ limit: 20 }}
-  groupBy="status"
-  sortable={{ field: 'name', dir: 'asc' }}
-  form={<FormFields />}
-  onSave={async ({ record, action }) => record._key}
-  onComplete={async ({ record, action }) => true}
-  selection={{ mode: 'multiple', onChange: (sel) => {} }}
-  reorderable
-  onReorder={(records, meta) => {}}
-  header={(ctx) => <div>{ctx.title}</div>}
-  footer={(ctx) => <div>{ctx.records.length} records</div>}
-/>
-```
-
-| Prop | Tipo | Note |
-|---|---|---|---|
-| `path` | `string \| "fromUrl"` | Path provider-backed |
-| `records` | `RecordArray` | Dati in memoria (alternativa a path) |
-| `columns` | `GridColumn[]` | `{ key, label, sortable?, render?, className? }` |
-| `actions` | `Array<'add'\|'edit'\|'delete'> \| Record<string, GridAction>` | |
-| `view` | `'table' \| 'gallery'` | |
-| `groupBy` | `string \| string[]` | |
-| `pagination` | `PaginationParams` | `{ limit, page?, maxPageButtons?, align?, sticky? }` |
-| `sortable` | `boolean \| OrderConfig` | |
-| `selection` | `false \| 'single' \| 'multiple' \| GridSelectionConfig` | |
-| `form` | `ReactElement \| ((ctx) => ReactNode)` | Form condiviso per CRUD |
-| `onSave` | `GridMutationSaveHandler` | `async ({ record, action }) => string` |
-| `onDelete` | `GridMutationDeleteHandler` | `async ({ record }) => string` |
-| `onComplete` | `GridAfterActionHandler` | `async ({ record, action }) => boolean` |
-| `onRowClick` | `(record) => void` | |
-| `reorderable` | `boolean` | Abilita drag & drop righe |
-| `onReorder` | `GridReorderHandler` | `(records, meta) => void` |
-| `onLoad` | `(records) => TRecord[]` | Trasforma records dopo il fetch |
-| `editDeepLink` | `boolean` | Sincronizza modal edit con URL |
-| `audit` | `boolean` | Logga mutazioni |
-| `sticky` | `'top' \| 'bottom'` | Header/footer sticky |
-| `wrapperClassName` | `string` | CSS wrapper esterno |
-| `loading` | `boolean` | Stato loading override |
-| `title` | `ReactNode` | Titolo header grid |
-| `before` / `after` | `ReactNode` | Slot prima/dopo il contenuto |
-| `header` / `footer` | `ReactNode \| ((ctx) => ReactNode)` | Header/footer custom |
-| `searchable` | `boolean \| GridSearchConfig` | Search box nell'header default — `{ fields?, placeholder? }` |
-| `filters` | `GridFilterConfig[]` | Checkbox toggle nell'header default, applicati PRIMA di `searchable` — `{ key, label, defaultValue?, predicate(record, value) }` |
-
-**GridAction kind:** `'modal'` (default), `'route'`, `'external'`, `'inline'`, `'delete'`
-
----
-
-## Form — form CRUD con lifecycle
-
-```tsx
-<Form
-  path="/products"
-  appearance="card"           // 'card' | 'empty'
-  showBack
-  defaultValues={{ status: 'draft' }}
-  keyGenerator={() => `prod_${Date.now()}`}
-  onLoad={(data) => { /* side-effect hook, non trasforma */ }}
-  onSave={async ({ record, action }) => { /* return storagePath or undefined */ }}
-  onDelete={async ({ record }) => { /* confirm */ }}
-  onComplete={async ({ action }) => { if (action === 'save') navigate('/products') }}
->
-  <Input name="title" label="Titolo" required />
-  <Input name="price" label="Prezzo" type="number" />
-  <Input name="address.city" label="Città" />      {/* oggetto annidato */}
-  <Repeat name="tags" defaultLength={1}>
-    {(i) => <Input name={`tags.${i}`} label={`Tag ${i+1}`} />}
-  </Repeat>
-</Form>
-```
-
-| Prop | Tipo | Note |
-|---|---|---|---|
-| `path` | `string` | Path provider-backed |
-| `appearance` | `'card' \| 'empty'` | Guscio visuale |
-| `controller` | `FormController` | Controller condiviso per bottoni custom esterni |
-| `showBack` | `boolean` | Pulsante Back nel footer |
-| `defaultValues` | `RecordProps` | Valori iniziali per nuovo record |
-| `keyGenerator` | `(record) => string` | Generatore chiave primaria custom |
-| `draftBucket` | `string` | Bucket stabile che isola la bozza locale; omettilo per disabilitare la persistenza |
-| `noticeAnchorRef` | `React.RefObject<HTMLElement>` | Ancoraggio sticky per notifiche |
-| `showNotice` | `boolean` | Mostra notifiche save/delete (default `true`) |
-| `onSubmit` | `FormSubmitHandler` | `async ({ record }) => void`. **Form d'azione** (CR-125): non legge e non scrive nulla; invia anche senza modifiche e con Invio in un campo; niente pulsante Salva né "Salvato" (il pulsante è tuo: `useFormController().save()`); l'errore lanciato appare nel suo avviso; restituire `false` = è fallito e la pagina dice già perché (nessun avviso né `onComplete`). Esclude `path`, `onSave`, `onDelete`, `keyGenerator` (errore di tipo e a runtime). Sostituisce `requireChanges={false}` della 1.x |
-| `children` | `ReactNode \| ((fields) => ReactNode) \| (({ record }) => ReactNode)` | Contenuto form |
-| `header` | `ReactNode` | Contenuto header custom |
-| `footer` | `ReactNode` | Contenuto footer custom |
-| `wrapperClassName` | `string` | CSS wrapper esterno |
-| `headerClassName` | `string` | CSS header |
-| `className` | `string` | CSS body form |
-| `footerClassName` | `string` | CSS footer |
-| `log` | `boolean` | Logga ogni modifica su console |
-| `onLoad` | `(record) => void` | Side-effect dopo il caricamento (non trasforma) |
-| `onRecordChange` | `(record) => void` | Cambio campo in tempo reale |
-| `onSave` | `FormSaveHandler` | `async ({ record, prevRecord?, storagePath?, action }) => string \| undefined`. Form che **salva un record**, solo se un campo è cambiato: restituisce il path dove scriverlo, `undefined` = il `path` del Form (senza `path` non scrive), `false` = è fallito e la pagina dice già perché (non scrive, nessun avviso, `save()` dà `false`). Per un'azione (chiamare un comando) usa `onSubmit`. L'errore lanciato appare nell'avviso del Form |
-| `onDelete` | `FormDeleteHandler` | `async ({ record }) => string \| undefined` |
-| `onComplete` | `FormFinallyHandler` | `async ({ record, action }) => boolean`; `action` è `'create' \| 'update' \| 'delete' \| 'submit'` |
-
-**Form controller** — stato e azioni native del form accessibili da qualsiasi punto della pagina.
-
-Due hook:
-
-| Hook | Dove usarlo | Cosa restituisce |
-|---|---|---|
-| `useFormController(controller?)` | Ovunque (anche fuori dal form) | Crea o si aggancia a un `FormController`. Senza argomenti ne crea uno locale stabile. Con un `controller` esistente ci si aggancia. |
-| `useFormActions()` | Solo dentro `<Form>` (legge dal context) | Restituisce lo stesso `FormController` del form genitore. Lancia errore se usato fuori. |
-
-Esempio — bottone custom fuori dal form:
-```tsx
-const form = useFormController();
-
-<ActionButton disabled={form.saveDisabled} onClick={() => { void form.save(); }} />
-<Form controller={form} draftBucket="workspace/acme" onSave={...} />
-```
-
-Esempio — form d'azione: chiama un comando, non salva nulla (CR-125):
-```tsx
-const form = useFormController();
-
-<Form controller={form} appearance="empty" onSubmit={({ record }) => call('verifyLoginCode', record)}>
-  <Input name="email" type="email" label="Email" required />
-  <Input name="code" label="Codice" required inputMode="numeric" maxLength={6} pattern="[0-9]{6}" autoComplete="one-time-code" />
-</Form>
-<LoadingButton label="Entra con il codice" loading={form.isSaving} onClick={() => form.save()} />
-```
-Con valori proposti (avviare una release con la versione proposta) si inviano anche senza modificarli:
-`<Form controller={form} appearance="empty" defaultValues={{ version: '1.4.0' }} onSubmit={({ record }) => start(record)}>`.
-
-Esempio — uso dentro il form (senza passare controller):
-```tsx
-function MySaveButton() {
-  const form = useFormActions();
-  return <LoadingButton disabled={form.saveDisabled} loading={form.isSaving} onClick={form.save} />;
-}
-```
-
-Stato esposto dal controller: `record`, `isNewRecord`, `isDirty`, `canSave`, `canDelete`, `isSaving`, `isDeleting`, `saveDisabled`, `deleteDisabled`, `hasDraft`, `draftStatus`, `errors`, `hasErrors`.
-
-Azioni: `save()`, `delete()`, `reset()`, `restoreDraft()`, `discardDraft()`.
-
----
-
-## Campi form
-
-### Input
-```tsx
-<Input name="x" label="..." required />                          // text (default)
-<Input name="price" type="number" min={0} max={100} step={0.01} />
-<Input name="email" type="email" />
-<Input name="phone" type="tel" autoComplete="tel" />                 // o <Tel name="phone" />
-<Input name="code" inputMode="numeric" maxLength={6} pattern="[0-9]{6}" autoComplete="one-time-code" />  // un codice monouso
-<Input name="pwd"   type="password" />
-<Input name="date"  type="date" />
-<Input name="color" type="color" />
-<TextArea name="bio" minHeight={96} />
-<Checkbox name="active" valueChecked="yes" />
-<Switch name="gate" label="Passa dalla CI" disabled title="L'agente non committa" />   // CR-116: disabled (non cambia né con il clic né da tastiera), title anche sull'etichetta: il motivo al passaggio del mouse
-```
-`Input` props: `name`(req) `label` `type` `required` `disabled` `placeholder` `min` `max` `step` `inputMode` `maxLength` `pattern` `autoComplete` `validator:(v)=>string|undefined`
-`type`: `'text' | 'number' | 'email' | 'tel' | 'password' | 'color' | 'date' | 'time' | 'datetime-local' | 'week' | 'month' | 'range' | 'checkbox' | 'radio' | 'url'`
-
-**NOTA**: il tipo HTML si passa con `type`. `inputType` e i sotto-componenti `Input.Number`/`Input.Email`/`Input.Date` non esistono.
-
-**Label come nodo**: `label` di tutti i campi di inserimento (`Input`, `TextArea`, `Checkbox`, `Select`, `Autocomplete`, `Checklist`, `Upload*`, `ImageField`, `CodeEditor`, `RichText`, `AddressAutocomplete`, `UploadCSV`, `Prompt`) accetta una stringa o un nodo React (tipo `FieldLabel`), disegnato dentro la `<label>` prima dell'asterisco di obbligatorio. Dove serve un testo (messaggio "obbligatorio", `aria-label`) si usa il testo del nodo, ricavabile anche con `labelText(node)`.
-```tsx
-<Select name="skill" required options={skills} label={<>Skill <ActionButton icon="info" ariaLabel="Apri la skill" variant="link" onClick={openSkill} /></>} />
-```
-
-### Select / Autocomplete / Checklist
-```tsx
-<Select name="role" options={[{ label: 'Admin', value: 'admin' }]} />
-<Select name="categoryId" optionsSource={{ path: '/categories', labelField: 'name', valueField: '_key' }} />
-<Autocomplete name="userId" optionsSource={{ path: '/users', labelField: 'email' }} maxItems={1} />
-<Checklist name="tags" options={['a', 'b', 'c']} />
-```
-
-| Prop | Tipo | Note |
-|---|---|---|
-| `options` | `Option[] \| string[] \| number[]` | |
-| `optionsSource` | `{ path, labelField, valueField?, where?, order?, fieldMap?, onLoad? }` | Carica da provider |
-| `order` | `{ field: 'label' \| 'value', dir: 'asc' \| 'desc' }` | |
-| `placeholderOption` | `Option` | Solo Select |
-| `placeholder` | `string` | Solo Autocomplete |
-| `creatable` | `boolean` | Solo Autocomplete — crea nuovi valori |
-| `onCreate` | `(value) => void \| boolean \| Promise<void \| boolean>` | Solo Autocomplete — restituire `false` per non selezionare il valore creato (es. aprire un modulo di creazione) |
-| `listClassName` / `optionClassName` | `string` | Solo Autocomplete — classi della lista e delle voci (anche da tema `Autocomplete.listClassName` / `optionClassName`) |
-| `minItems` / `maxItems` | `number` | Solo Autocomplete |
-| `itemClassName` | `string` | Solo Checklist |
-| `validator` | `(value) => string \| undefined` | Tutte le varianti |
-| `readOnlyAfterSet` | `boolean` | readonly dopo primo valore |
-| `disabled` | `boolean` | |
-| `title` | `string` | |
-| `feedback` | `string` | Messaggio di errore/suggerimento |
-
-`Autocomplete` è una combobox accessibile: la lista (in un portal, larga quanto il campo, stile popover del tema) mostra solo le label e filtra per label/value senza distinzione di maiuscole e accenti; i chip mostrano la label; tastiera: frecce, Invio, Esc (chiude solo la lista, non il `Modal`), Tab, Backspace su campo vuoto rimuove l'ultimo valore. Con `creatable` compare la voce "Crea «testo»". Il valore salvato è sempre l'array dei `value`. `Autocomplete` e `Checklist` sono export nominati: `Select.Autocomplete`/`Select.Checklist` non esistono.
-
-### UploadImage / UploadDocument / UploadCSV
-```tsx
-<UploadImage name="cover" label="Copertina" />    {/* con crop editor */}
-<UploadDocument name="pdf" label="PDF" />
-<UploadCSV name="data" label="Importa CSV" />      {/* con preview tabellare */}
-```
-
-**UploadImageProps** (eredita FormFieldProps):
-| Prop | Tipo | Note |
-|---|---|---|
-| `name` | `string` (required) | |
-| `uploadPath` | `string` | Path storage per upload automatico |
-| `accept` | `string` | MIME types accettati |
-| `editable` | `boolean` | Abilita crop editor |
-| `multiple` | `boolean` | Multipla selezione |
-| `max` | `number` | Numero massimo file |
-| `feedback` | `string` | Testo placeholder drop zone |
-| `srcsetWidths` | `number[]` | Larghezze varianti responsive |
-| `previewHeight` / `previewWidth` | `number` | Dimensioni preview |
-
-**UploadDocumentProps** (eredita FormFieldProps): `name`, `uploadPath`, `accept`, `editable`, `multiple`, `max`
-
-### UploadCSV
-```tsx
-<UploadCSV name="data" label="Importa CSV" />
-```
-| Prop | Tipo |
-|---|---|
-| `name` | `string` (required) |
-| `onDataLoaded` | `(data: UploadCSVData) => void` |
-| `onParseField` | `([key, value]) => [key, value] \| undefined` |
-| `normalizeKeys` | `boolean` |
-| `removeEmptyFields` | `boolean` |
-| `delimiter` | `string` |
-| `label` / `icon` | Opzionali |
-
-### ImageField
-```tsx
-<ImageField
-  name="hero"
-  label="Hero image"
-  defaultValue={{ src: 'https://example.com/hero.jpg', alt: 'Hero shot' }}
-  srcsetWidths={[400, 800]}
-  uploadPath="/content/images"
-/>
-```
-
-Gestisce un oggetto `{ src, alt, srcset?, sizes? }`, preview inline, crop editor e generazione opzionale di varianti responsive.
-
-### CropImage
-```tsx
-<CropImage img={imageObj} title="Ritaglia" scales={{ '1:1': 1, '4:3': 1.33 }} />
-```
-Componente di ritaglio indipendente. `img` ha tipo `{ fileName, variants }` dove ogni variante è `{ fileName, type, scale, top, left, width, height, base64? }`. Usato internamente da `UploadImage` e `ImageField`, ma esportato pubblicamente per uso standalone.
-
-### CodeEditor
-```tsx
-<CodeEditor
-  name="code"
-  label="Template"
-  language="html"
-  placeholder="Scrivi HTML..."
-  minHeight={200}
-  maxHeight={600}
-  disabled={false}
-  required
-  validateSyntax
-  commands={[{ name: 'wrap-section', handler: ({ value }) => `<section>\n${value}\n</section>` }]}
-  commandsTrigger="/"
-/>
-```
-Editor basato su CodeMirror con syntax highlighting e validazione. Linguaggi: `liquid`, `html`, `json`, `js`, `ts`, `css`.
-Quando `commands` e presente, `CodeEditor` apre internamente `ContextMenu` sul trigger configurato.
-
-| Prop extra | Tipo |
-|---|---|
-| `language` | `CodeEditorLanguage` |
-| `placeholder` | `string` |
-| `minHeight` / `maxHeight` | `number` |
-| `validateSyntax` | `boolean` |
-| `validator` | `(value) => string \| undefined \| Promise<string \| undefined>` |
-| `extensions` | `unknown[]` |
-
-### RichText
-```tsx
-<RichText
-  name="body"
-  label="Article body"
-  placeholder="Scrivi..."
-  toolbar="fixed"                    // 'fixed' | 'floating' | false
-  toolbarCommands={['bold', 'italic', 'heading1', '|', 'bulletList', 'link']}
-  outputFormat="html"                // 'html' | 'json' | 'text'
-  statusBar={{ tagBreadcrumb: true, wordCount: true }}
-  minHeight={200}
-  maxHeight={800}
-  imageUpload={{ path: '/content/images', srcsetWidths: [400, 800] }}
-  commands={[{ name: 'summary', icon: 'sparkles' }]}
-  commandsTrigger="/"
-/>
-```
-
-| Prop extra | Tipo |
-|---|---|
-| `placeholder` | `string` |
-| `disabled` | `boolean` |
-| `feedback` | `string` |
-| `toolbar` | `'fixed' \| 'floating' \| false` |
-| `toolbarCommands` | `ToolbarCommand[]` |
-| `outputFormat` | `'html' \| 'json' \| 'text'` |
-| `statusBar` | `boolean \| StatusBarConfig` |
-| `minHeight` / `maxHeight` | `number` |
-| `imageUpload` | `RichTextImageUploadConfig` |
-| `documentUpload` | `RichTextDocumentUploadConfig` |
-| `validator` | `(value) => string \| undefined` |
-
-### Repeat — array dinamici
-```tsx
-<Repeat name="items" defaultLength={3} minItems={1} maxItems={10} label="Elementi" layout="vertical" readOnly>
-  {({ index, record, records, remove }) => (
-    <>
-      <Input name={`items.${index}.name`} label="Nome" />
-      <UploadImage name={`items.${index}.photo`} label="Foto" />
-    </>
-  )}
-</Repeat>
-```
-
-| Prop | Tipo | Note |
-|---|---|---|
-| `name` | `string` (required) | |
-| `children` | `ReactNode \| ((args) => ReactNode)` | Render prop con `{ index, record, records, remove }` |
-| `defaultLength` | `number` | Righe iniziali |
-| `minItems` / `maxItems` | `number` | Min/max righe |
-| `layout` | `'vertical' \| 'horizontal' \| 'inline'` | |
-| `label` | `string` | Etichetta gruppo |
-| `labelPosition` | `'top' \| 'bottom'` | |
-| `hideRemoveButton` | `boolean` | Nascondi rimozione |
-| `readOnly` | `boolean` | Sola lettura |
-| `onChange` | `FieldOnChange` | |
-| `onAdd` / `onRemove` | `(records) => void` | Callback aggiunta/rimozione |
-
-### Prompt — campo AI-potenziato
-```tsx
-<Prompt
-  name="summary"
-  mode="run"                  // 'edit' | 'run'
-  onRunPrompt={async (prompt, options) => AI.fetch(prompt)}
-  commands={[{ name: 'translate', icon: 'languages', handler: (v) => `Translate:\n${v}` }]}
-  commandsTrigger="/"         // default automatico quando commands e presente
-  attachments
-  statusItems={['tokensIn', 'tokensOut', 'contextPercent', 'duration']}
-/>
-```
-
-Quando `commands` e presente in `mode="run"`, `Prompt` monta internamente `ContextMenu` sulla textarea del risultato. Il trigger di default e `"/"`; `commandsTrigger` permette di cambiarlo. Il menu diventa searchable automaticamente sopra una soglia interna di comandi.
-
-`renderFallback`: quando l'AI non e configurata, `Prompt` monta un fallback testuale; passa `renderFallback` per personalizzarlo (riceve `{ name, label, required, onChange }`).
-
----
-
-## UI Primitives
-
-### Alert
-```tsx
-<Alert variant="success">Salvato!</Alert>
-<Alert variant="warning" icon placement="fixed" timeout={3000}>Attenzione</Alert>
-```
-`variant`: `'info' | 'success' | 'warning' | 'danger' | 'primary' | 'secondary' | 'light' | 'dark'`
-`appearance`: `'default' | 'text'`
-`placement`: `'inline' | 'fixed'`
-
-### Badge
-```tsx
-<Badge variant="success">Attivo</Badge>
-```
-`variant`: stessi valori di Alert
-
-### Button variants
-```tsx
-<ActionButton variant="primary" label="Salva" icon="save" onClick={handleSave} />
-<LoadingButton variant="primary" label="Invia" onClick={async (e, setMsg) => { await save(); setMsg('Salvato!') }} />
-<BackLink label="Indietro" />
-<GoSite href="https://..." label="Visita" />
-```
-
-**IButton props:** `variant`, `label`, `icon`, `badge`, `disabled`, `ariaLabel`, `title`, `iconClassName`, `onClick`
-**LoadingButton aggiunge:** `loading`, `loadingLabel` — `onClick` riceve `(e, setMessage?) => Promise<unknown>`
-
-### Card
-```tsx
-<Card title="Titolo" header={<Actions />} footer={<Pagination />} loading={isLoading}>
-  {children}
-</Card>
-```
-
-### Modal
-```tsx
-<Modal title="Conferma" size="md" position="center" onClose={() => {}} onSave={handleSave} onDelete={handleDelete} motion="fade" allowFullscreen stackedBehind>
-  {content}
-</Modal>
-<ModalYesNo title="Sicuro?" onClose={() => {}} onYes={async () => true}>Eliminare il record?</ModalYesNo>
-// Un'azione che non si annulla: nominala e mettila in rosso (CR-128); "Annulla" viene per primo.
-<ModalYesNo title="Revocare l'invito?" danger yesLabel="Revoca" noLabel="Annulla" onYes={revoke} onNo={async () => true}>La persona non potrà più usare il link.</ModalYesNo>
-<ModalOk title="Completato!" onClose={() => {}}>Salvato.</ModalOk>
-```
-`size`: `'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'fullscreen'`
-`position`: `'center' | 'top' | 'left' | 'right' | 'bottom'`
-`ModalYesNo` e `ModalOk` sono export separati: `Modal.YesNo` e `Modal.Ok` non esistono.
-Tastiera: Esc chiude il modal in cima alla pila (`closeOnEscape`, default `true`).
-Accessibilità: il dialog ha `role="dialog"`, `aria-modal="true"` (non con `stackedBehind`) e `aria-labelledby` verso `title` (o `header` stringa) — nei test si trova con `getByRole('dialog', { name })`.
-
-| Prop | Tipo | Note |
-|---|---|---|
-| `children` | `ReactNode` (required) | |
-| `title` | `ReactNode` | |
-| `header` / `footer` | `ReactNode \| false` | Custom header/footer |
-| `size` / `position` | Come sopra | |
-| `onClose` | `() => void` | |
-| `onSave` / `onDelete` | `(e) => Promise<boolean>` | |
-| `allowFullscreen` | `boolean` | Toggle fullscreen |
-| `showCancel` | `boolean` | Default `true` |
-| `stackedBehind` | `boolean` | Modale sotto un'altra (stile Google Tag Manager): un velo la scurisce, il suo backdrop resta com'è (quello della modale sopra entra sopra, così la pagina si scurisce di un gradino per modale) e non riceve il puntatore. I pannelli laterali aperti sullo stesso lato si impilano da soli: quello in cima prende la larghezza con cui si è aperto il primo, ognuno sotto è largo il 10% in più di quello sopra (100%, 110%, 121%…), così ne sporge una striscia. Solo la larghezza cambia, con la transizione dello slide, in entrata e in uscita |
-| `closeOnBackdrop` | `boolean` | Default `true` |
-| `closeOnEscape` | `boolean` | Default `true` — solo il modal in cima reagisce |
-| `zIndex` | `number` | |
-| `motion` | `MotionReference` | Preset animazione |
-| Classi CSS header/title/subtitle/body/footer | `string` | |
-
-### Table
-```tsx
-<Table
-  columns={[{ key: 'name', label: 'Nome', sort: true }]}
-  records={records}
-  onRowClick={(record) => {}}
-  selection="multiple"
-  sortable={{ field: 'name', dir: 'asc' }}
-  pagination={{ limit: 20 }}
-  onReorder={(records, meta) => {}}
-  onSelectionChange={(sel) => {}}
-  groupBy="status"
-  renderCell={(record, key, index) => <CustomCell />}
-/>
-```
-
-| Prop | Tipo |
-|---|---|
-| `columns` | `TableHeaderProp[]` |
-| `records` | `RecordArray` |
-| `sortable` | `boolean \| OrderConfig` |
-| `pagination` | `PaginationParams` |
-| `selection` | `'single' \| 'multiple'` |
-| `onRowClick` | `(record) => void` |
-| `onReorder` | `(records, meta) => void` |
-| `onSelectionChange` | `(selection) => void` |
-| `renderCell` | `(record, key, index) => ReactNode` |
-| `groupBy` | `string \| string[]` |
-| `activeKey` | `string \| null` |
-| `selectedKeys` | `string[]` |
-| `header` / `footer` | `ReactNode` |
-| `headerClassName` / `bodyClassName` / `footerClassName` / `scrollClassName` / `selectedClassName` / `heightClassName` | `string` |
-
-### Gallery
-```tsx
-<Gallery
-  records={records}
-  overlays={[{ position: 'topRight', badge: { variant: 'success', children: 'New' } }]}
-  columns={3}
-  gap={2}
-  sortable={{ field: 'name', dir: 'asc' }}
-  pagination={{ limit: 20 }}
-  onRowClick={(record) => {}}
-  onSelectionChange={(sel) => {}}
-  header="Titolo"
-  groupBy="status"
-/>
-```
-
-`position`: `'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'middleLeft' | 'middleRight'`
-
-| Prop | Tipo |
-|---|---|
-| `records` | `GalleryRecord[]` (`{ img?, thumbnail?, name?, width?, height? }`) |
-| `columns` | `1 \| 2 \| 3 \| 4 \| 6` |
-| `gap` | `0 \| 1 \| 2 \| 3 \| 4 \| 5` |
-| `overlays` | `GalleryOverlay[]` |
-| `sortable` | `boolean \| OrderConfig` |
-| `pagination` | `PaginationParams` |
-| `onRowClick` | `(record) => void` |
-| `onSelectionChange` | `(selection) => void` |
-| `groupBy` | `string \| string[]` |
-| `selectedKeys` | `string[]` |
-| `header` / `footer` | `ReactNode` |
-| Classi CSS: `headerClassName`, `bodyClassName`, `footerClassName`, `scrollClassName`, `selectedClassName` | `string` |
-
-### Tab
-```tsx
-import { Tab, TabItem } from '@llmnative/react'
-
-<Tab defaultIndex={0} layout="top">
-  <TabItem label="Generale">{content1}</TabItem>
-  <TabItem label="SEO">{content2}</TabItem>
-</Tab>
-```
-`layout`: `'default' | 'top' | 'left' | 'right' | 'bottom'`
-Le schede sono `<TabItem>`, export separato: `Tab.Item` non esiste.
-
-### Image
-```tsx
-<Image src="..." fit="cover" position="center" width={400} height={300} />
-```
-`fit`: `'cover' | 'contain' | 'fill' | 'scale-down' | 'none'`
-
-### Pagination (standalone)
-```tsx
-<Pagination records={items} limit={20}>
-  {(pageRecords, offset) => pageRecords.map(r => <Row key={r._key} record={r} />)}
-</Pagination>
-```
-
-### Percentage
-```tsx
-<Percentage value={75} appearance="bar" variant="success" showText />
-<Percentage value={0.75} appearance="circle" size={60} />
-```
-
-| Prop | Tipo | Default |
-|---|---|---|
-| `value` | `number` | — |
-| `max` | `number` | `100` |
-| `min` | `number` | — |
-| `appearance` | `'bar' \| 'circle'` | `'bar'` |
-| `variant` | `ColorType` | — |
-| `trackVariant` | `ColorType` | — |
-| `thickness` | `number` | — (px) |
-| `showText` | `boolean` | — |
-| `size` | `number` | Diametro in modalità `'circle'` (px) |
-| `fontSize` | `number` | — |
-| `label` | `string` | — |
-
-### DescriptionList
-Coppie etichetta → valore in sola lettura (profilo, dati di un record, riepiloghi), rese come `<dl>`/`<dt>`/`<dd>`. Da usare al posto di markup `<dl>` scritto a mano; per dati modificabili usare i campi di `<Form>`, per molti record `<Table>`/`<Grid>`.
-```tsx
-<DescriptionList items={[{ label: 'Email', value: 'a@b.it' }, { label: 'Telefono', value: null }]} />
-<DescriptionList layout="stacked" columns={4} truncate items={[{ label: 'Stato', value: <Badge variant="success">Spedito</Badge> }]} />
-```
-
-| Prop | Tipo | Default |
-|---|---|---|
-| `items` | `DescriptionListItem[]` — `{ key?, label, value?, title? }` | — |
-| `layout` | `'horizontal' \| 'stacked'` | `'horizontal'` (etichette a sinistra, impilate su mobile) |
-| `columns` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` (solo `stacked`, dal breakpoint `lg`) |
-| `labelWidth` | `string` (lunghezza CSS) | `'12rem'` (solo `horizontal`) |
-| `emptyValue` | `ReactNode` | `'—'` per `null` / `undefined` / `''` (lo `0` resta) |
-| `truncate` | `boolean` | `false`; un valore testuale diventa il suo `title` |
-| Classi | `wrapperClassName`, `className`, `itemClassName`, `labelClassName`, `valueClassName` | tema `DescriptionList` |
-
-### Tree
-Albero accessibile di nodi (cartelle e file, gerarchie): pattern WAI-ARIA tree, un solo tab stop, frecce per muoversi, → / ← per aprire e chiudere, Invio o Spazio per selezionare. Le cartelle si aprono al click, le foglie si selezionano.
-```tsx
-<Tree nodes={treeFromPaths(paths)} defaultExpanded selectedId={path} onSelect={(node) => setPath(node.id)} ariaLabel="File" />
-<Tree nodes={[{ id: 'a', label: 'Docs', children: [{ id: 'a/1', label: 'README.md', badge: <Badge>new</Badge> }] }]} />
-```
-| Prop | Tipo | Note |
-|---|---|---|
-| `nodes` | `TreeNode[]` — `{ id, label, icon?, badge?, description?, children?, disabled? }` | `id` unico; con `children` è una cartella |
-| `selectedId` + `onSelect` / `defaultSelectedId` | `string \| null` | selezione controllata o no |
-| `expanded` + `onExpandedChange` / `defaultExpanded` | `string[]`; `defaultExpanded` anche `true` (tutto aperto) | apertura controllata o no |
-| `selectableBranches` | `boolean` (default `false`) | anche le cartelle si selezionano |
-| `ariaLabel` | `string` | nome accessibile |
-| Classi | `wrapperClassName`, `className`, `itemClassName`, `selectedClassName` | tema `Tree` |
-
-`treeFromPaths(paths, leaf?)` costruisce l'albero da percorsi `a/b/c`: cartelle prima dei file, ordinati; l'id di un file è il percorso, quello di una cartella `percorso/`; `leaf(path)` decora le foglie (label, icona, descrizione…).
-
-### Dropdown
-```tsx
-<Dropdown trigger={<Icon name="menu" />} position="end">
-  <DropdownItem label="Modifica" icon="edit" onClick={() => {}} />
-  <DropdownItem label="Elimina" icon="trash" variant="danger" />
-  <DropdownDivider />
-  <DropdownHeader label="Azioni rapide" />
-</Dropdown>
-```
-
-Azioni secondarie di una voce (CR-107): `actions` mostra icone in fondo alla riga, al passaggio
-del mouse o al focus (sempre sui dispositivi touch). Non selezionano la voce e lasciano il menu aperto
-salvo `closeOnClick`.
-
-```tsx
-<DropdownItem icon="messages-square" onClick={() => open(chat)}
-  actions={[{ icon: 'archive', label: 'Archivia', onClick: () => archive(chat) }]}>
-  {chat.title}
-</DropdownItem>
-```
-
-Per elenchi caricati dinamicamente usare `AsyncDropdown`: gestisce ricerca con debounce,
-cancellazione delle richieste precedenti tramite `AbortSignal` e stati loading/empty/error.
-
-```tsx
-<AsyncDropdown
-  trigger={<ActionButton label="Select user" />}
-  loadItems={(query, signal) => users.search(query, { signal })}
-  getItemId={user => user.id}
-  renderItem={user => user.name}
-  onSelect={user => setUser(user)}
-  selectedId={user?.id}
-/>
-```
-
-### ContextMenu
-```tsx
-<ContextMenu trigger="/" searchable>
-  <ContextMenu.Heading>Comandi</ContextMenu.Heading>
-  <ContextMenu.Item label="Titolo" value="# " icon="heading" />
-  <ContextMenu.Separator />
-  <ContextMenu.Item label="Bold" value="**bold**" icon="bold" />
-</ContextMenu>
-```
-Funziona su qualsiasi `<textarea>` / `<input>` figlio. Trigger custom (`/`, `@`, `{`), filtro searchable, navigazione tastiera, floating positioning.
-`ContextMenu.Item` accetta `description` (opzionale): seconda riga attenuata (`text-muted-foreground`)
-sotto la label, troncata; il menu è largo al massimo 28rem e il testo completo resta nel `title`
-della voce. Il filtro cerca nel testo digitato dopo il trigger su label, value e description (CR-111).
-
-```tsx
-<ContextMenu.Item label="/plan" value="plan" icon="list" description="Scrive il piano della release" />
-```
-
-| Prop | Tipo | Note |
-|---|---|---|
-| `trigger` | `string` (required) | Es. `"/"`, `"@"`, `"{"` |
-| `searchable` | `boolean` | Filtro testuale |
-| `controlled` | `ContextMenuControlledState` | Stato controllato esterno |
-| `onSelect` | `(item, context) => void` | |
-
-**EditorCommand** (usato da `commands` prop su `Chatbot`, `Prompt`, `RichText`, `CodeEditor`):
-```ts
-{
-  name: string;
-  description?: string;
-  icon?: string;
-  group?: string;
-  consumeSuffix?: string;
-  handler?: (context: TextCommandContext) => string | Promise<string>;
-}
-```
-
-`description` compare sotto `/name` nel menu dei comandi di tutti e quattro i consumer e il filtro
-la usa (digitare `/release` trova un comando descritto come "…release…"). Un comando senza `handler`
-sostituisce il trigger con `/name ` (spazio finale) e il testo resta tale: in `Chatbot`/`Prompt` il
-messaggio inviato è letteralmente `"/name …"`, da interpretare a cura di chi lo riceve.
-
-`consumeSuffix` elimina una chiusura automatica adiacente durante la sostituzione del trigger,
-utile quando un comando cambia famiglia sintattica (per esempio da `{{ ... }}` a `{% ... %}`).
-
-### Altre primitive
-```tsx
-<Icon name="user" size={20} />           // usa provider icone configurato
-<ImageAvatar src="..." title="Mario" alt="Mario" width={40} height={40} />
-<Identicon value="acme/app" size={32} title="acme/app" />   // icona generata dal valore, stile GitHub
-<Loader show={isLoading}>{content}</Loader> // indicatore al posto dei figli finché show è true
-<Loader show>{null}</Loader>             // solo indicatore (es. pagina in caricamento)
-<Code language="tsx">{snippet}</Code>   // syntax highlight
-<GridSystem.Row><GridSystem.Col xs={12} md={6}>...</GridSystem.Col></GridSystem.Row>
-<LocaleSwitcher locales={[{ code: 'it', label: 'Italiano' }]} />
-<ThemeSwitcher />
-<ProviderSwitcher />
-<LayoutBuilder components={...} />
-```
-
-### Charts (CR-112)
-Grafici SVG senza dipendenze, dal modulo `charts`. Colori come token del tema: `color` è uno slot della
-palette categoriale (`1…8` → `--rf-chart-N`, definiti in `globals.css` con la variante scura e
-sovrascrivibili dal consumer) o un token (`'--rf-success'`); le serie senza colore prendono lo slot
-della loro posizione. Larghezza dal contenitore (ResizeObserver), animazioni spente con
-`prefers-reduced-motion`, tooltip che segue il puntatore e la tastiera (le aree prendono il focus
-finché sono al massimo 40), tabella dei dati `sr-only` con `ariaLabel` come didascalia, stato vuoto
-`charts.noData`. `format` è facoltativo: di default il numero nella locale dell'app.
-
-```tsx
-<ColumnChart ariaLabel="CR chiuse al giorno" columns={[{ label: 'lun', value: 4 }]} markers={[{ position: 3.5, label: 'mediana', dashed: true }]} onColumnClick={(column) => {}} />
-<StackedColumnChart ariaLabel="Ore per agente" labels={days} labelEvery={2} format={(v) => `${v} h`}
-  series={[{ id: 'dev', label: 'Developer', values: dev }, { id: 'qa', label: 'Tester', values: qa, color: 3 }]}
-  comparison={previousTotals} comparisonLabel="periodo precedente" />
-<MeasureBarList ariaLabel="Agenti"   // CR-115: barre raggruppate, ogni agente una volta, una barra per misura (colore in legenda), ognuna sulla sua scala
-  columns={[{ id: 'time', label: 'Ore', format: (v) => `${v} h` }, { id: 'cost', label: 'Costo' },
-    { id: 'tokens', label: 'Token', parts: [{ id: 'in', label: 'Input' }, { id: 'out', label: 'Output' }] }]}   // parts: la barra divisa in proporzione
-  rows={[{ id: 'dev', label: 'Developer', values: { time: 18, cost: 4.27, tokens: [2400000, 190000] }, trailing: { text: '18 back', tone: 'bad' } }]} />
-<SequenceColumnChart ariaLabel="Turni per CR" format={(v) => `${v} min`}   // CR-114: ogni colonna nel suo ordine, una serie può tornare
-  series={[{ id: 'dev', label: 'Developer' }, { id: 'rev', label: 'Reviewer' }]}
-  columns={[{ label: '#34', title: 'CR #34', segments: [{ series: 'dev', value: 18 }, { series: 'rev', value: 6 }, { series: 'dev', value: 11 }] }]}
-  onColumnClick={(column) => {}} />
-<LineChart ariaLabel="Lead time" labels={days} threshold={{ value: 6.5, label: 'obiettivo' }} baseline={0} domain={[0, 10]}
-  series={[{ id: 'now', label: 'Ora', values: [3, null, 5], area: true, band: { min, max } }, { id: 'before', label: 'Prima', values: prev, dashed: true }]} />
-<AreaChart ariaLabel="Flusso cumulativo" labels={days} stacked series={[{ id: 'closed', label: 'Chiuse', values: closed }]} />
-<ScatterChart ariaLabel="Costo contro rework" xLabel="Costo" yLabel="Rework" sizeLabel="Turni"
-  series={[{ id: 'sonnet', label: 'Sonnet' }]} points={[{ id: '1', label: 'Developer', x: 0.04, y: 0.3, size: 30, series: 'sonnet' }]} onPointClick={(point) => {}} />
-<DivergingBarChart ariaLabel="Valore e costo" upLabel="Valore" downLabel="Costo" bars={[{ label: 'lun', up: 120, down: null }]} />
-<BarList ariaLabel="Costo per agente" rows={[{ id: 'dev', label: 'Developer', value: 1.84, trailing: { text: '+12%', tone: 'bad' } }]} />
-<Heatmap ariaLabel="Turni per ora" rowLabels={agents} columnLabels={hours} columnLabelEvery={2} values={matrix} />
-<CalendarHeatmap ariaLabel="Turni per giorno" days={[{ date: '2026-11-02', value: 4 }, { date: '2026-11-03', value: null }]} />
-<Sparkline values={[1, 3, null, 2]} ariaLabel="Andamento" />   // senza ariaLabel è decorativa
-<AnimatedNumber value={3.85} format={(v) => `$${v.toFixed(2)}`} />
-```
-
-Parti comuni per grafici propri: `useChartTooltip()` (`show`, `showAt`, `hide`, `element`), `ChartLegend`,
-`ChartDataTable`, `useChartWidth(fallback)`, `useAnimatedValues(values)`, `useReveal(key)`,
-`useChartFormat(format?)`, `chartToken(color)`, `chartFill(token, alpha?)`, `niceMax`, `ticks`.
-
----
-
-## Blocks
-
-```tsx
-// Senza trail: dall'indirizzo, ogni pezzo col titolo della sua rotta nel menu ('/impostazioni' → 'Impostazioni'),
-// altrimenti leggibile ('lead-fermi' → 'Lead fermi'); un id resta com'è.
-<Breadcrumbs />
-<Breadcrumbs trail={[{ label: 'Home', href: '/' }, { label: 'Utenti' }]} separator="/" jsonLd />
-<Brand url="/" label="MyApp" logo="/logo.svg" width={120} />
-<Search onQueryChange={(e) => setQ(e.target.value)} />
-<Notifications items={[...]} seeAllUrl="/notifications" onMarkAllRead={() => {}} onItemClick={(item) => markRead(item.id)} />
-<Notifications items={[{ id: 'a', title: 'Fonte senza Action', description: 'crm · sources/notes/a.md', url: '/projects/crm', time: 'ora', icon: 'file', actions: [{ label: "Apri l'Action", icon: 'play', onClick: openAction, variant: 'primary' }] }]} />
-<Carousel images={[...]} />
-<Toolbar items={[...]}>
-  {children}
-</Toolbar>
-<SideNav />
-<ListCard records={records} onRowClick={(r) => {}} />
-```
-
-**Brand:**
-| Prop | Tipo |
-|---|---|
-| `url` | `string` |
-| `label` | `string` |
-| `logo` | `string` |
-| `width` / `height` | `number` |
-| `wrapperClassName` / `className` / `logoClassName` / `labelClassName` | `string` |
-
-**SideNav:**
-| Prop | Tipo |
-|---|---|
-| `items` | `SideNavItemDef[]` (in alternativa a `menuKey`) |
-| `menuKey` | `string` — voci dal menu registrato in `<App>` |
-| `bottomItems` | `SideNavItemDef[]` — voci fissate in fondo, sopra il footer e fuori dalla lista scorrevole (es. Impostazioni) |
-| `header` / `footer` | `ReactNode` |
-| `collapsed` + `onCollapsedChange` / `defaultCollapsed` | `boolean` — compressione controllata o no |
-| `showIcons` / `showCollapseButton` | `boolean` (default `true`) |
-| `embedded` | `boolean` — solo le voci, senza guscio (drawer, pannelli); `bottomItems` seguono le voci principali |
-
-`SideNavItemDef`: `{ path, title?, icon?, group?, end?, badge?, children? }`. La voce attiva ha
-`aria-current="page"`.
-
-```tsx
-<SideNav
-  items={[{ path: '/dashboard', title: 'Dashboard', icon: 'home' }]}
-  bottomItems={[{ path: '/settings', title: 'Impostazioni', icon: 'settings' }]}
-/>
-```
-
-**ImageAvatar:**
-| Prop | Tipo |
-|---|---|
-| `src` | `string` (obbligatoria) |
-| `width` / `height` | `number` |
-| `title` / `alt` | `string` |
-| `fit` | `AvatarFit` |
-| `badge` | `BadgeDescriptor` |
-| `feedback` | `ReactNode` |
-
-**Identicon:** l'icona di un'entità senza immagine (repository, tenant, utente senza foto), come quelle di
-GitHub: griglia 5×5 simmetrica, celle e tinta da un hash di `value`. Lo stesso valore dà sempre la stessa
-icona; niente rete né storage. Default: `rounded-md bg-muted` (tema `Identicon.className`).
-`identiconPattern(value)` restituisce celle e tinta, per chi la disegna altrove.
-| Prop | Tipo |
-|---|---|
-| `value` | `string` (obbligatoria) |
-| `size` | `number` (px, default 40) |
-| `title` | `string`: nome accessibile (`role="img"`); senza, `aria-hidden` |
-| `before` / `after` / `className` / `wrapperClassName` | come le altre primitive |
-
-**Search:**
-| Prop | Tipo |
-|---|---|
-| `onQueryChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` |
-
-**Notifications:**
-| Prop | Tipo |
-|---|---|
-| `items` | `NotificationItem[]` |
-| `badge` | `BadgeProps` |
-| `seeAllUrl` | `string` |
-| `onMarkAllRead` | `() => void` |
-| `onItemClick` | `(item, index) => void` — una voce aperta (es. per segnarla letta); il menu si chiude |
-| `motion` | `MotionReference` |
-
-`NotificationItem`: `{ id?, title, description?, url?, external?, time, icon, read?, actions? }`. `description` è la
-riga sotto il titolo; senza `url` la voce si mostra e basta; con `external` l'`url` è un indirizzo aperto
-in una nuova scheda (`<a target="_blank">`), altrimenti una rotta (`Link`). `actions`
-(`NotificationAction[]`: `{ label, icon?, onClick, variant?: 'primary' | 'default', closeOnClick? }`) sono
-pulsanti sotto la voce: non la aprono, mostrano il caricamento finché la promessa di `onClick` è in corso
-e lasciano il menu aperto salvo `closeOnClick`.
-
-**ListCard:**
-| Prop | Tipo |
-|---|---|
-| `title` / `description` / `meta` | `ReactNode` |
-| `badge` | `ReactNode` |
-| `icon` | `string \| ReactNode` |
-| `trailing` / `footer` / `children` | `ReactNode` |
-| `href` | `string` |
-| `external` / `active` / `disabled` / `dashed` / `compact` | `boolean` |
-| `align` | `'start' \| 'center'` |
-| `onClick` | `(e) => void` |
-| Classi CSS: `titleClassName`, `descriptionClassName`, `metaClassName`, `badgeClassName`, `leadingClassName`, `bodyClassName`, `headerClassName`, `trailingClassName`, `footerClassName` | `string` |
-
-**SortableList (CR-120):** card compatte (ListCard) in un ordine che la persona sceglie: le trascina per la
-maniglia, o con le frecce su/giù sulla maniglia; l'annuncio della nuova posizione va agli screen reader.
-```tsx
-<SortableList
-  items={accounts}
-  getKey={(a) => a.id}
-  label="Account"
-  numbered
-  onReorder={(next, { fromIndex, toIndex, item }) => setAccounts(next)}
-  renderItem={(a) => ({ title: a.email, meta: a.added, badge: <Badge variant="success">Disponibile</Badge>, trailing: <ActionButton icon="trash-2" … /> })}
-  emptyState={<p>Nessun account</p>}
-/>
-moveItem(['a', 'b', 'c'], 0, 2)   // ['b', 'c', 'a']
-```
-| Prop | Tipo |
-|---|---|
-| `items` / `getKey` | `TItem[]` / `(item) => string` |
-| `renderItem` | `(item, index) => SortableListCard` (`title`, `description`, `meta`, `badge`, `icon`, `trailing`, `active`, `disabled` di ListCard) |
-| `onReorder` | `(items, { fromIndex, toIndex, item }) => void`; senza, nessuna maniglia |
-| `label` / `numbered` / `disabled` / `emptyState` | `string` / `boolean` / `boolean` / `ReactNode` |
-| Classi CSS: `className`, `itemClassName`, `cardClassName` | `string` |
-
-**Dropdown:**
-| Prop | Tipo |
-|---|---|
-| `trigger` | `string \| ReactNode \| DropdownTogglerProps` |
-| `badge` | `BadgeProps` |
-| `header` / `footer` | `ReactNode` |
-| `defaultOpen` / `open` | `boolean` |
-| `onOpenChange` | `(open) => void` |
-| `position` | `'start' \| 'end'` |
-| `placement` | `'auto' \| 'top' \| 'bottom'` |
-| `strategy` | `'fixed' \| 'absolute'` |
-
-// Menu — renderizza una sezione del menuConfig passato ad <App>
-<Menu menuKey="main" />            // 'main' o qualsiasi chiave definita in MenuConfig
-<Menu menuKey="topbar" className="nav flex-row gap-2" />
-// NON usare context= — la prop si chiama menuKey
-
-// AuthButton — login/logout con il provider auth configurato
-<AuthButton />
-```
-
----
-
-## Widgets
-
-### MarkdownReader
-```tsx
-<MarkdownReader
-  content={markdownString}
-  onInternalLinkClick={(href, e) => { e.preventDefault(); navigate(href) }}
-  wrapperClassName="prose"
-/>
-```
-
-### Messaggi di chat: ChatMarkdown, ChatReasoning, ChatQuestions (CR-109), ChatActivity (CR-123)
-
-Parti di un messaggio di un modello, da comporre nel proprio thread (anche accanto a `Chatbot`).
-
-```tsx
-// Markdown GFM del messaggio: tabelle (scorrono dentro di sé in un pannello stretto), elenchi,
-// titoli, citazioni, task list, codice con evidenziazione (Prism, lazy) e pulsante Copia, link a
-// indirizzi in una nuova scheda (noopener). Sanitizzato: niente HTML grezzo, niente javascript:.
-// streaming: chiude ciò che la fine del testo lascia aperto (fence, intestazione di tabella,
-// **grassetto**, `codice`, link) così il layout non salta mentre arriva. Off per un messaggio finito.
-<ChatMarkdown content={text} streaming={running} onLinkClick={(href) => navigate(href)} />
-// tone="muted", highlight={false}, components (come react-markdown), className,
-// classNames={{ root, paragraph, heading, list, blockquote, tableWrapper, table, th, td, codeBlock, codeHeader, code, inlineCode, link }}
-// repairStreamingMarkdown(text) è la stessa riparazione, pura.
-
-// Ragionamento: chiuso dietro "Ragionamento" / "Ha ragionato per 12 s"; aperto mentre arriva
-// (se l'utente non lo chiude) e richiuso alla fine. Contenuto con ChatMarkdown, tono attenuato.
-<ChatReasoning content={reasoning} streaming={thinking} duration={12} />
-// defaultOpen, open + onOpenChange (controllato), label, icon ('brain'), className, classNames={{ root, trigger, content }}
-
-// Domande interattive (formato dello strumento `question` di opencode / elicitation MCP):
-<ChatQuestions
-  questions={[
-    { id: 'db', header: 'Database', question: 'Quale database?', recommended: 0,
-      options: [{ label: 'Postgres', description: 'Relazionale' }, { label: 'SQLite' }] },
-    { id: 'features', header: 'Funzioni', question: 'Quali funzioni?', multiple: true,
-      options: [{ label: 'Auth' }, { label: 'Ricerca' }] },
-  ]}
-  onSubmit={async (answers) => send(answers)}   // [{ id, header, values: string[] }] in ordine
-/>
-// Una scheda per domanda (header) + Riepilogo e un solo Invia; opzioni numerate 1-2-3 o A-B-C
-// (numbering, altrimenti dedotto da etichette "A) …" / "1. …", che vengono tolte); consigliata
-// (recommended: indice da 0 o etichetta; anche il suffisso "(Recommended)"); multiple; "Altro" con
-// testo libero (allowOther, default true; per domanda `custom`); senza options è a testo libero.
-// Il testo libero è una textarea (CR-110) di 2 righe che cresce col testo fino a ~160px e poi
-// scorre; ridimensionabile in verticale. Lì Invio va a capo, Ctrl/Cmd+Invio prosegue o invia
-// (suggerimento `chat.textKeyboardHint` nel piè mentre si scrive).
-// Tastiera: numeri (o lettere con A-B-C) scelgono, frecce sinistra/destra tra le schede, su/giù tra
-// le opzioni, Spazio seleziona, Invio prosegue o invia (su una scelta singola prima la sceglie;
-// nel testo libero serve Ctrl/Cmd+Invio).
-// Ruoli tablist/tab/tabpanel, radiogroup/radio o group/checkbox.
-// Scelta singola: il click sceglie e passa alla domanda dopo. onSubmit che rifiuta lascia il form.
-// answers={[…]} mostra un insieme già risposto (sola lettura); disabled, autoFocus, submitLabel,
-// classNames={{ root, tabs, tab, panel, question, option, optionSelected, footer, summary }}
-
-// Il lavoro di un agente (CR-123), come negli assistenti AI: gruppi di passi (icona, label, quanti,
-// dettagli brevi: query, file, comandi; quanti falliti) con le righe sotto aperte da "Comandi";
-// le parole dell'agente in Markdown; come è finito; i file cambiati con "Vedi le modifiche";
-// il registro grezzo a un clic. Il consumer traduce il suo log negli item.
-<ChatActivity
-  items={[
-    { type: 'steps', icon: 'search', label: 'Esplora il repository', count: 3, detail: ['git status'], lines: ['git status --short'] },
-    { type: 'text', text: 'Aggiungo il comando e il suo test.' },
-    { type: 'end', ok: true, text: 'success · 9 steps' },
-  ]}
-  files={['functions/src/catalog/index.js']} onShowChanges={() => openDiff()} log={rawLines}
-/>
-// className, classNames={{ root, step, text, files, log }}
-```
-
-### ImageEditor
-```tsx
-<ImageEditor src="..." onSave={(dataUrl) => save(dataUrl)} />
-```
-
-`ImageEditor` e un singolo componente pubblico. La libreria pesante `tui-image-editor` viene importata lazy a runtime dentro il componente, quindi non viene scaricata finche l'editor non viene effettivamente montato.
-
-### TabDynamic
-Tab con lazy loading dei contenuti — gestione dinamica aggiunta/rimozione tab.
-
----
-
-## AI Integration
-
-```ts
-import { useAIProvider, getAIModelCatalog, createAIProviderRegistry } from '@llmnative/react'
-
-// Hooks
-const provider  = useAIProvider()           // provider di default
-const registry  = useAIProviderRegistry()   // tutti i provider AI registrati
-const catalog   = getAIModelCatalog()       // modelli disponibili
-// ogni modello: { id, provider, model, label, pricing? } — pricing in USD per 1M token
-// { input, output, currency: 'USD', source: 'provider' | 'models.dev' }; assente = prezzo
-// non trovato (il modello resta in lista). isFreeAIModel(m) → input e output a 0.
-// Il model picker di Prompt/Chatbot mostra "$in / $out", evidenzia i free, segnala i mancanti,
-// e raggruppa per provider (ChatbotModelOption.group = providerLabel) con header sticky.
-// CR-121: il pulsante mostra la `label` del modello scelto (non il suo valore); `groupBadge: { label, variant? }`
-// su un'opzione mette un Badge a destra nell'header del suo gruppo (es. Abbonamento / A consumo).
-
-// Provider adapter restituito da useAIProvider()
-const text  = await provider.fetch("Scrivi un titolo per: {keyword}", { keyword: "React" })
-const json  = await provider.json("Lista di 5 categorie per blog tech")
-const arr   = await provider.array("5 tag per: machine learning")
-
-// Provider custom
-class MyAIProvider implements AIProviderAdapter {
-  async fetch(prompt: string, options?: AIRequestOptions): Promise<string> { ... }
-  async json<T>(prompt: string, options?: AIRequestOptions): Promise<T> { ... }
-  async array(prompt: string, options?: AIRequestOptions): Promise<string[]> { ... }
-}
-
-// Quanto ragiona il modello (CR-122): `reasoning: 'low' | 'medium' | 'high' | 'max'` (AIReasoningLevel) su
-// una richiesta. Anthropic: `output_config.effort` sui Claude 4.6 e successivi (+ thinking adaptive su Opus
-// 4.6-4.8 e Sonnet 4.6); OpenAI e compatibili (OpenCode, DeepSeek, Groq…): `reasoning_effort` solo sui modelli
-// di ragionamento di OpenAI (serie o, GPT-5; max = high); OpenRouter: `reasoning.effort` su ogni modello.
-// Altrove (modelli più vecchi, Gemini) non si manda nulla: il default del modello.
-await ai.complete({ prompt: 'Rivedi questo piano', model: 'claude-opus-5-5', reasoning: 'high' })
-
-// Factory per registri esterni
-const registry = createAIProviderRegistry(definitions)
-// Azioni di Chatbot (CR-107): con `content` aprono un menu; senza, sono pulsanti con `onClick`.
-// <Chatbot actions={[{ key: 'finish', icon: 'git-pull-request', label: 'Concludi', showLabel: true,
-//   disabled: running, onClick: finish }]} … />
-// Allegati di Chatbot (`attachments`): file scelti, trascinati o incollati con Ctrl+V (uno screenshot diventa
-// `pasted-<data>.png`, CR-124); il testo incollato resta testo. Arrivano in `onSubmit` come `files`.
-// Comandi "/" di Chatbot: `commands` (EditorCommand[]) + `commandsTrigger` (default "/").
-// Il menu mostra `/name` e sotto la `description`; il filtro cerca in entrambi (CR-111).
-// Senza `handler` la scelta inserisce "/name " e l'invio manda il testo così com'è.
-// Tastiera: Invio invia a menu chiuso e sceglie il comando evidenziato a menu aperto;
-// Maiusc+Invio (e Invio durante la composizione IME) va a capo.
-// <Chatbot commands={[{ name: 'plan', icon: 'list', description: 'Scrive il piano' }]} … />
-```
-
-### Identità dei modelli indipendente dal provider (CR-103)
-
-```ts
-const index = await loadModelIdentityIndex()          // models.dev, un fetch per sessione
-canonicalModelName('DeepSeek V4.1 Flash (Alibaba Cloud)')   // 'deepseek v4.1 flash'
-index.models['deepseek v4.1 flash']                   // { key, name, family?, providers: { openrouter: [{ id, name }], … } }
-resolveModel(index, 'DeepSeek V4.1 Flash', ['openrouter', 'deepseek'])
-// → { provider: 'openrouter', model: 'deepseek/deepseek-v4.1-flash', ref: 'openrouter/deepseek/deepseek-v4.1-flash' }
-modelOffers(index, 'DeepSeek V4.1 Flash', ['openrouter', 'deepseek'])   // CR-119: tutti quelli che lo servono
-// → [{ provider: 'openrouter', model, ref, cost: { input: 0.15, output: 0.3 } }, { provider: 'deepseek', … }]
-//   senza `providers`: tutto il catalogo, per chiave del provider. `cost` in USD per 1M token, assente se models.dev non lo dà
-```
-
-Il nome canonico toglie data, Free, Latest e host o regione tra parentesi; una modalità
-("(Thinking)", "(Reasoning)", "(Fast)") resta. Per ogni provider l'id preferito è quello stabile (non
-alias `~`, non free tier, non datato). I provider sono le chiavi di models.dev, le stesse di opencode.
-Puro: anche da `@llmnative/react/server`.
-
-### Chiavi tenute dal server (CR-102)
-
-Per un'app che non mette mai le chiavi dei provider nel browser. Il browser conosce solo quali
-provider sono collegati; il proxy dell'app mette la chiave.
-
-```ts
-// Browser: gli stessi adapter, con un segnaposto dove andrebbe la chiave. Serve il proxy attivo.
-const registry = createServerCredentialAIRegistry(
-  [{ id: 'anthropic' }, { id: 'cloudflare', accountId }, { id: 'openai-compatible', baseUrl }],
-  { scope: companyId },   // lettere, cifre, - e _
-)
-Object.entries(registry).forEach(([id, adapter]) => setProvider('ai', id, adapter))
-
-// Server (Node, nessuna dipendenza da React): nel proxy, prima di inoltrare.
-import { resolveServerCredentials } from '@llmnative/react/server'
-const resolved = await resolveServerCredentials({ url: target, headers },
-  (scope, provider) => keysOf(scope)[provider])   // { id, apiKey, accountId?, baseUrl? } | undefined
-if (!resolved.ok) return reply(resolved.status, resolved.error)   // 404 non collegato, 403 host estraneo
-await fetch(resolved.url, { headers: resolved.headers, ... })
-```
-
-La chiave va solo agli host del provider (`AI_PROVIDER_HOSTS`, il `baseUrl` di openai-compatible,
-l'account di Cloudflare): una destinazione diversa è rifiutata. `createProxyPlugin(route, log,
-lookup)` fa lo stesso nel proxy di sviluppo di Vite. Senza proxy, `proxyFetch` rifiuta di inviare
-un segnaposto. `createAIProviderRegistry` (chiavi nel browser) resta com'è.
-
-Configurazione API key in `Config.tsx`: `geminiApiKey`, `openaiApiKey`, `anthropicApiKey`, `deepSeekApiKey`, `mistralApiKey`, `openRouterApiKey`, `groqApiKey`, `cloudflare: { apiToken, accountId }` (Cloudflare Workers AI: l'account id fa parte dell'URL; discovery via `ai/models/search`, modelli Workers Paid esclusi salvo `includePaidModels`).
-
----
-
-## Theme e icone
-
-```tsx
-const theme = useThemeController()
-theme.applyTheme('flat')     // BuiltInThemeId ('default' | 'flat' | 'cyber' | 'vscode-dark-modern' | …) | custom
-theme.setMode('dark')        // 'light' | 'dark' | 'system'
-
-const icons = useIconController()
-icons.setProvider('phosphor')   // 'lucide' | 'phosphor' | custom
-```
-
----
-
-## Head (SEO)
-
-```ts
-useHead({
-  title: 'Pagina',
-  description: '...',
-  robots: 'noindex',
-  canonical: 'https://...',
-  og: { title: '...', image: '...' }
-})
-```
-
----
-
-## Global state (localStorage)
-
-```ts
-const vars = useGlobalVars()
-getGlobalVars('key')
-setGlobalVars({ key: 'value' })
-removeGlobalVars('key')
-```
-
----
-
-## Hooks completi
-
-| Hook | Ritorna |
-|---|---|
-| `useDataProvider(name?)` | `DataProviderAdapter \| null` |
-| `useStorageProvider(name?)` | `StorageProviderAdapter \| null` |
-| `useAuthProvider(name?)` | `AuthProviderAdapter \| null` |
-| `useEmailProvider(name?)` | `EmailProviderAdapter \| null` |
-| `useAIProvider(name?)` | `AIProviderAdapter \| null` |
-| `useAIProviderRegistry()` | `Record<string, AIProviderAdapter>` |
-| `useCredentialsProvider()` | `CredentialsAdapter \| null` |
-| `useTheme()` | `Theme \| undefined` |
-| `useThemeController()` | `ThemeController` |
-| `useIconController()` | `IconController` |
-| `useAccessToken(clientID, renew?)` | `boolean` | Ottiene token per servizio esterno (true = ok) |
-| `useGlobalVars()` | `Record<string, unknown>` |
-| `useHead()` | `HeadController` |
-| `useDocumentHead()` | `HeadController` |
-| `useAssetsHead(title?)` | `void` |
-| `useLanguageHead(lang?)` | `void` |
-| `useSocialHead(config)` | `void` |
-| `usePaginationHead(config)` | `void` |
-| `usePwaHead(config)` | `void` |
-| `useSchemaOrgHead(config)` | `void` |
-| `useHeadLinks(links)` | `void` |
-| `useProxy()` | `(url, init?) => Promise<Response>` |
-| `useImage()` | `UseImageResult` |
-| `useI18n()` | `I18nController` |
-| `useMenu()` | Menu hook |
-| `useFormController(controller?)` | `FormController` |
-| `useFormActions()` | `FormController` |
-| `useApiProvider(pathname?)` | `ApiProviderAdapter \| null` |
-| `useSetProvider(service, driver?)` | `void` |
-| `useProvider(name)` | `ProviderConfigurationState` |
-| `useProviderSession()` | `ProviderSession` |
-| `useDropBoxConnect(config?)` | `DropBoxConnectResult` |
-| `useEnterMotion(baseStyle?, ref?, fallback?)` | `CSSProperties` |
-| `useMotionState(active, ref?, fallback?, baseStyle?)` | `CSSProperties` |
-| `useMotionEffect(ref?, fallback?)` | `ResolvedMotionEffect` |
-| `usePressMotion(hovered, baseStyle?, ref?, fallback?)` | `{ style, pressHandlers }` |
-| `useIconProvider()` | `IconProvider` |
-
----
-
-## Tipi chiave
-
-```ts
-type RecordProps  = Record<string, FieldValue>
-type FieldValue   = string | number | boolean | null | undefined | Record<string, unknown> | unknown[]
-type RecordArray  = RecordProps[]
-
-type OrderConfig  = { field: string; dir: 'asc' | 'desc' }
-type Condition    = { eq?, lt?, lte?, gt?, gte?, in?: list, nin?: list, contains?: scalar, containsAny?: list }
-type WhereClause  = { [field: string]: Condition | scalar | list }   // scalar = eq, list = in
-type OrderClause  = { [field: string]: 'asc' | 'desc' }
-class DataProviderError extends Error { code: 'permission-denied' | 'unauthenticated' | 'invalid-query' | 'unavailable' | 'unknown'; path?: string; cause?: unknown }
-
-interface UIProps {
-  before?: React.ReactNode
-  after?: React.ReactNode
-  wrapperClassName?: string
-  className?: string
-}
-
-type UserProfile = { uid?: string; email?: string; displayName?: string; photoURL?: string; [key: string]: unknown }
-```
-
----
-
-## Utilities
-
-```ts
-import { cn, converter, Sanitizer, Order, path, fetchJson, fetchRest, fetchWithRetry } from '@llmnative/react'
-import { getKeywordIdeas, getGoogleTrendsData, getGoogleTrendsRelated } from '@llmnative/react'
-
-cn('base', condition && 'extra', className)     // tailwind-merge classname
-new Sanitizer().sanitize(html)                  // XSS sanitizer (non usare dangerouslySetInnerHTML)
-new Order().order(records, { field: 'name', dir: 'asc' })  // ordina record array
-fetchJson(url, init?)                           // fetch + JSON parse + error handling
-fetchRest(path, init?)                          // fetch REST con auth
-getKeywordIdeas(keyword)                        // Google Ads Keyword Ideas
-getGoogleTrendsData(keyword)                    // Google Trends interest over time
-getGoogleTrendsRelated(keyword)                 // Google Trends related queries
-```
-
----
-
-## Scaffold (npx create)
-
-```bash
-npx @llmnative/react create
-npx @llmnative/react create --yes --provider=mock --template=admin
-```
-
-Flag disponibili: `--name` `--provider=firebase|supabase|mock|custom` `--ai-provider` `--icon-provider` `--theme` `--template=blank|admin|crm|inventory|project`
-
-**5 template disponibili:**
-| Template | Pagine incluse | Uso tipico |
-|---|---|---|
-| `blank` | home | App vuota — massima libertà |
-| `admin` | home, users, roles, settings | Dashboard admin/backoffice |
-| `crm` | home, companies, contacts, deals | CRM |
-| `inventory` | home + gestione inventario | Magazzino |
-| `project` | home + gestione progetti | PM tool |
-
-**Struttura generata in-place nella current directory:**
-```
-src/
-  index.tsx          ← App entry
-  vite-env.d.ts
-  conf/
-    app.ts           ← providers config letta da .env (VITE_PROVIDER, VITE_AI_PROVIDER...)
-    menu.ts          ← MenuConfig con path, title, icon, page (layout opzionale: c'è LayoutDefault)
-    access.tsx       ← rotte pubbliche delle pagine di accesso (CR-127)
-  data/
-    mockData.ts      ← dati fake per MockDataProvider
-  layouts/
-    Default.tsx      ← layout wrapper (header + sidebar + main + footer)
-  sections/
-    Header.tsx / Sidebar.tsx / PageHeader.tsx / Footer.tsx   ← solo componenti pubblici (SideNav, AuthButton, ActionButton, Brand, Breadcrumbs)
-  pages/
-    home/HomePage.tsx
-    access/          ← SignInPage (il fallback del gate), SignUp, ForgotPassword, ResetPassword, VerifyEmail
-    [altre pagine dal template scelto]
-  styles/
-    globals.css      ← @import '@llmnative/react/dist/index.css' + Tailwind override
-.env                 ← VITE_PROVIDER, VITE_THEME, chiavi API (non committare)
-.env.example         ← stessa struttura, valori vuoti (committare)
-vite.config.ts / tsconfig.json / postcss.config.js / index.html
-```
-
-**Pattern conf/app.ts** (auto-generato, leggere per capire come funziona):
-```ts
-import type { AppProvidersConfig } from '@llmnative/react'
-import { mockData } from '../data/mockData'
-const env = import.meta.env
-
-export const providers: AppProvidersConfig = {
-  mock: { data: mockData },
-  ai: { openaiApiKey: env.VITE_OPENAI_API_KEY ?? '' },  // AI dentro providers, non prop <App>
-  mock: { data: mockData, auth: true },               // mockAuth: accesso di prova
-  services: { data: 'mock', auth: 'mockAuth' },
-}
-```
-
-Driver per `VITE_PROVIDER`: `firebase` → `firestoreDb` + `firestorage` + `firebaseAuth`; `supabase` → `supabaseDb` + `supabaseStorage` + `supabaseAuth`; `mock` → `mock` + `mockAuth`. `index.tsx` passa `LayoutDefault={Default}`, le traduzioni del framework (`translations: { ...locales }`) e `authGate={{ fallback: <SignInPage /> }}`: senza sessione ogni pagina mostra l'accesso al suo posto. Le pagine di accesso (`pages/access/`: SignInPage, SignUpPage, ForgotPasswordPage, ResetPasswordPage, VerifyEmailPage) e le loro rotte pubbliche (`conf/access.tsx`) sono uguali per ogni template; per un'app aperta a tutti togli `authGate`.
-
----
-
-## Gotchas — pitfall frequenti
-
-| Errore | Causa | Fix |
-|---|---|---|
-| `aiConfig` prop non esiste su `<App>` | La config AI va dentro `providers.ai`, NON come prop separata | `providers={{ ai: { openaiApiKey } }}` |
-| `inputType` o `Input.Number`/`Input.Email` non esistono | Il tipo HTML è la prop `type` | `<Input type="number">`, `<Input type="email">`, `<Input type="date">` |
-| `Menu context=` non esiste | La prop si chiama `menuKey` | `<Menu menuKey="main" />` |
-| `SignInButton` non esiste | Rinominato | `<AuthButton />` |
-| Pagina `/login` con redirect, form di accesso fatti a mano | Le schermate e il gate ci sono (CR-127) | `<App authGate={{ fallback: <SignIn … /> }}>`, rotte aperte con `public: true` |
-| `firebase: { config: ... }` errato | FirebaseConfig è flat | `firebase: { apiKey, authDomain, databaseURL, ... }` |
-| `google: { oAuth2: { clientId } }` errato | GoogleProviderConfig è flat | `google: { clientId, scope }` |
-| `children` su `Grid` | Grid non accetta children | Usa `form={<Fields />}` per il form inline |
-| `recordId` su `Form` | Prop non esiste | La chiave del record viene da URL automaticamente |
-| `MenuConfig` non importabile | Era type interno | Ora esportato: `import type { MenuConfig } from '@llmnative/react'` |
-| `GridCellContext` non importabile | Mancava dall'index | Ora esportato: `import type { GridCellContext } from '@llmnative/react'` |
-
----
-
-## Dove cercare nel codice sorgente
-
-| Cosa | File |
-|---|---|
-| Form | `src/components/widgets/Form.tsx` |
-| Grid | `src/components/widgets/Grid.tsx` |
-| Prompt | `src/components/widgets/Prompt.tsx` |
-| Campi form | `src/components/ui/fields/` |
-| Blocks (Menu, Toolbar, Notifications, Dropdown…) | `src/components/blocks/` |
-| Provider data Firebase (RTDB) | `src/providers/data/firebase.ts` |
-| Provider data Firestore | `src/providers/data/firestore.ts` |
-| Provider data Supabase | `src/providers/data/supabase.ts` |
-| Provider storage Firebase | `src/providers/storage/firebase.ts` |
-| Provider storage Supabase | `src/providers/storage/supabase.ts` |
-| Provider auth Firebase | `src/providers/auth/firebase/FirebaseAuthProvider.ts` |
-| Provider auth Supabase | `src/providers/auth/supabase/` |
-| Provider auth Google | `src/providers/auth/google/` |
-| Provider auth Dropbox | `src/providers/auth/dropbox/` |
-| Provider email Gmail | `src/providers/email/google/GmailEmailProvider.ts` |
-| Provider AI definitions | `src/providers/ai/` |
-| Provider credenziali | `src/providers/credentials/` |
-| Provider session | `src/providers/ProviderSession.ts` |
-| Proxy CORS | `src/providers/proxy.ts` |
-| Motion system | `src/motion.ts` |
-| I18n | `src/I18n.tsx` |
-| Dropbox integration | `src/providers/dropbox/` |
-| Interfaccia DataProvider | `src/providers/data/DataProvider.ts` |
-| Interfaccia StorageProvider | `src/providers/storage/StorageProvider.ts` |
-| Interfaccia AuthProvider | `src/providers/auth/AuthProvider.ts` |
-| Interfaccia EmailProvider | `src/providers/email/EmailProvider.ts` |
-| Interfaccia AIProvider | `src/providers/ai/AIProvider.ts` |
-| Registry provider | `src/providers/manifest.ts` |
-| Config provider | `src/providers/ProviderConfiguration.ts` |
-| SEO / Google Trends | `src/providers/seo/google/` |
-| Sistema tema | `src/Theme.tsx` |
-| Config runtime | `src/Config.tsx` |
-| Tipi TypeScript | `src/types/` |
-| Utilities pure | `src/libs/` |
+# @llmnative/react — Riferimento completo
+
+Framework React AI-first per generazione deterministica di UI. Data-driven di default, schema-driven opzionale.
+Versione 1.0.0 — Apache-2.0
+
+```bash
+npm install @llmnative/react
+import '@llmnative/react/dist/index.css'
+```
+
+---
+
+## Regole fondamentali
+
+- Tutti gli import da `'@llmnative/react'` — mai da sottodirectory
+- I provider sono iniettati via `<App providers={...}>` — mai importati direttamente nei componenti
+- Usare `useDataProvider()`, `useAuthProvider()`, ecc. nei componenti, non istanze dirette
+- TypeScript strict: no `any` — usare `unknown`, `Record<string, unknown>`, tipi specifici
+- Naming props: `view` (presentazione contenuto), `appearance` (guscio visuale), `layout` (disposizione spaziale), `mode` (comportamento operativo), `variant` (tono semantico), `position` (ancoraggio), `size` (scala)
+
+---
+
+## App — Entry point
+
+```tsx
+<App
+  providers={{
+    firebase: {                        // FirebaseConfig — tutte le chiavi flat
+      apiKey, authDomain, databaseURL, projectId,
+      storageBucket, messagingSenderId, appId,
+    },
+    supabase: { url, anonKey },
+    google: { clientId, scope },       // flat — NON { oAuth2: { clientId } }
+    dropbox: { clientId },             // DropboxConfig
+    mock: { data: mockData },
+    ai: {                              // AIConfig — NON una prop separata di <App>
+      openaiApiKey, geminiApiKey, anthropicApiKey,
+      deepSeekApiKey, mistralApiKey, openRouterApiKey,
+      groqApiKey,
+      cloudflare: { apiToken, accountId }, // Cloudflare Workers AI
+    },
+    proxy: { enable: true, route: '/api/proxy' },
+    custom: { data: { myAdapter: new MyDataProvider() } },
+    services: {
+      data:        'dbRealtime',      // DataDriverName
+      storage:     'firestorage',     // StorageDriverName | null
+      auth:        'googleAuth',      // AuthDriverName | null
+      emailSend:   'gmail',           // EmailSendDriverName | null
+      emailRead:   'imap',            // un adapter registrato in custom.emailRead
+      ai:          'openai',          // AIDriverName | null
+      credentials: 'googleServiceAccount',
+    },
+  }}
+  iconProvider="lucide"              // 'lucide' | 'phosphor' | AppIconProviderConfig
+  themeProvider="default"            // 'default' | 'flat' | 'cyber' | AppThemeProviderConfig
+  menuConfig={menuConfig}
+  importPage={(path) => import(path)}
+  LayoutDefault={MyLayout}           // layout wrapper custom (opzionale): avvolge ogni voce di menuConfig senza `layout`
+  appName="MyApp"                    // nome app (opzionale)
+  i18n={{ locale: 'it', translations: { ... } }}
+  contextProviders={MyContextProvider}
+  errorReportUrl="/api/errors"
+  debug={import.meta.env.DEV}
+/>
+```
+
+### Testi dei componenti (i18n)
+
+I testi fissi dei componenti vengono da `I18nDict` e seguono `i18n.locale` (en, it, de, ru, ar, zh
+inclusi): un testo si cambia con `i18n.translations`, non nel codice. Namespace dei componenti:
+`notifications` (`markAllRead`, `empty`, `emptyHint`), `errorBoundary` (schermata d'errore; fuori da
+`<I18nProvider>`, come l'`ErrorBoundary` radice di `<App>`, resta in inglese), `themeSwitcher`,
+`imageField` (anche i dialoghi immagine di `RichText`), `richText`, `tabDynamic` (`addTab`),
+`breadcrumbs` (`label`, l'`aria-label` del `nav`), `grid` (`tableView`, `galleryView`, `columns`,
+`fields`), `prompt` (anche `Chatbot`: `role`, `language`, `voice`, `style`, `temperature`, `stop`),
+`chat` (`ChatReasoning` e `ChatQuestions`: `reasoning`, `reasoningFor`, `other`, `review`, `submit`, …;
+il codice di `ChatMarkdown` usa `code`).
+
+```tsx
+<App i18n={{ locale: 'it', translations: { it: { notifications: { emptyHint: 'Niente di nuovo' } } } }} />
+```
+
+### AppThemeProviderConfig
+```ts
+{
+  mode?: 'light' | 'dark' | 'system';
+  theme: string;
+  themes?: Record<string, {
+    preset?: { colors?: ColorScale; radius?: number; font?: string };
+    motion?: MotionRegistry;
+    components?: Record<string, Partial<ThemeComponent>>;
+  }>;
+  themeOverride?: Record<string, Partial<ThemeComponent>>;
+}
+```
+
+Built-in themes: `default`, `flat`, `cyber`, `vscode-dark-modern`, `vscode-light-modern`, `vscode-dark-plus`, `vscode-light-plus`, `tokyo-night`, `tokyo-night-light`.
+The VS Code and Tokyo Night themes are compiled from the original VS Code theme JSON (`scripts/themes/vscode`), filling the keys a theme does not list with VS Code's color registry defaults; each one has both modes (`vscode-dark-*` starts dark, `vscode-light-*` light). Status colors (destructive/success/warning/info) stay the framework's.
+
+`ColorScale` tokens: `background`, `foreground`, `canvas` (page floor behind cards and panels, `bg-canvas`; falls back to `background`), `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `success`, `warning`, `info` (each with its `*Foreground`), `border`, `input` (border of form fields), `ring`. A consumer bridging the tokens in its own `@theme inline` adds `--color-canvas: hsl(var(--rf-canvas, var(--rf-background)));`.
+
+**The frame of the app** (CR-126), as the title bar, side bar and status bar of the IDE: `header`, `headerForeground`, `headerBorder`, `sidebar`, `sidebarForeground`, `sidebarBorder`, `sidebarAccent` (the selected entry), `sidebarAccentForeground`, `footer`, `footerForeground`, `footerBorder`. The IDE themes carry them (VS Code Light+: gray title bar, blue status bar); a theme without them falls back to the base tokens (header and footer on `background`, sidebar on `card`, borders on `border`). Utilities: `bg-header text-header-foreground border-header-border`, `bg-sidebar …`, `bg-footer …`. `SideNav` draws itself with the sidebar tokens. The top bar and status bar of a layout:
+
+```tsx
+<header className="flex h-14 shrink-0 items-center gap-3 border-b border-header-border bg-header px-4 text-header-foreground">…</header>
+<footer className="shrink-0 border-t border-footer-border bg-footer px-4 py-1.5 text-xs text-footer-foreground">…</footer>
+```
+
+A border without a color class (`border`, `border-b`) is the theme's `border`, not the text color. The scaffold (`npx @llmnative/react create`) starts in `vscode-light-modern` and bridges all these tokens in `src/styles/globals.css`; a consumer scaffolded before adds the `--color-header…`/`--color-sidebar…`/`--color-footer…` lines of `src/globals.css` to its own `@theme inline`.
+
+---
+
+## Provider System
+
+### Matrix completa
+
+| Servizio | Interfaccia | Driver | Config key | Obbligatorio |
+|---|---|---|---|---|
+| data | `DataProviderAdapter` | `mock`, `dbRealtime`, `firestoreDb`, `supabaseDb` | `providers.mock/firebase/supabase` | sì (fallback: mock) |
+| storage | `StorageProviderAdapter` | `firestorage`, `supabaseStorage` | `providers.firebase/supabase` | no |
+| auth | `AuthProviderAdapter` | `googleAuth`, `firebaseAuth`, `supabaseAuth`, `dropboxAuth`, `githubAuth` | `providers.google/firebase/supabase/dropbox/github` | sì (fallback: googleAuth) |
+| emailSend | `EmailSendAdapter` | `gmail` (+ `ResendEmailSender`, `BrevoEmailSender`, `GmailEmailSender` in `custom`) | `providers.google` / `custom.emailSend` | no |
+| emailRead | `EmailReadAdapter` | — (`GmailEmailReader`, `ImapEmailReader` in `custom`) | `custom.emailRead` | no |
+| ai | `AIProviderAdapter` | `openai`, `gemini`, `anthropic`, `deepseek`, `mistral`, `openrouter`, `opencode`, `opencode-go`, `cloudflare`, `groq` | `Config.tsx AIConfig` | no |
+| credentials | `CredentialsAdapter` | `googleServiceAccount` | `providers.google.serviceAccount` | no |
+
+### Firebase: quale app usano auth, dati e storage
+
+- `providers.firebase` inizializza l'app Firebase **di default** dell'SDK (`[DEFAULT]`). `firestoreDb` e `firestorage` la
+  usano, e il driver `firebaseAuth` (`services.auth: 'firebaseAuth'`) fa login su quella stessa app: login, Firestore
+  e Storage condividono la sessione.
+- Un'app che chiama già `initializeApp(config)` per conto suo condivide l'app di default con il framework solo se ha lo
+  **stesso `appId`**. Con un `appId` diverso il framework chiude quell'app e la reinizializza con la propria config, e
+  la sessione dell'app cade. Per questo il client Firebase si crea una volta sola: o `providers.firebase`, o il codice
+  dell'app con la stessa config.
+- Una sessione separata, che non deve cadere quando l'app di default cambia (cambio di tenant): istanziare
+  `new FirebaseAuthProvider({ config, appName: 'control-plane' })`. `appName` è un'app con un nome suo; senza
+  `config` usa un'app già inizializzata con quel nome.
+- Le Cloud Functions callable: `callFirebaseFunction(name, data, appName?, region?)`, sull'app di default se non si
+  passa `appName`. Il token della sessione lo aggiunge l'SDK.
+
+### Layout per voce di menu
+
+Ogni voce di `menuConfig` è una route. Viene avvolta da `item.layout` se presente, altrimenti da `LayoutDefault` di
+`<App>`, altrimenti da `LayoutEmpty`. Una pagina con un guscio diverso, per esempio l'accesso a tutta pagina senza
+sidebar, dichiara `layout` sulla sua voce:
+
+```tsx
+export const menuConfig: MenuConfig = {
+  main: [
+    { path: '/', title: 'Home', icon: 'home', page: HomePage },          // LayoutDefault
+  ],
+  public: [
+    { path: '/login', page: LoginPage, layout: AccessLayout },           // senza header né sidebar
+  ],
+};
+```
+
+La home va dichiarata con `path: '/'`: senza quella voce, `/` mostra "Missing Page".
+
+### Voci di menu e rotte
+
+`SideNav menuKey="main"` e `Menu menuKey="main"` mostrano solo le **voci**: le route di quella chiave con `title`,
+senza `hidden: true`, senza parametri (`:token`) e senza `*`. Le altre sono rotte e basta (CR-126). Ogni voce
+mostrata ha `title` **e** `icon`. Una pagina raggiunta da un link (accesso, invito, impostazioni dal menu utente)
+sta in una chiave che nessun menu mostra, oppure ha `hidden: true`:
+
+```tsx
+export const menuConfig: MenuConfig = {
+  main: [
+    { path: '/', title: 'Dashboard', icon: 'layout-dashboard', page: HomePage },
+    { path: '/contacts', title: 'Contatti', icon: 'users', page: ContactsPage },
+    { path: '/settings', title: 'Impostazioni', icon: 'settings', page: SettingsPage, hidden: true },
+  ],
+  routes: [
+    { path: '/invite/:token', page: InvitePage, layout: AccessLayout },
+    { path: '*', page: NotFoundPage },
+  ],
+};
+```
+
+### Hooks
+
+```ts
+const data    = useDataProvider()           // DataProviderAdapter | null
+const storage = useStorageProvider()        // StorageProviderAdapter | null
+const auth    = useAuthProvider()           // AuthProviderAdapter | null
+const send    = useEmailSendProvider()      // EmailSendAdapter | null
+const read    = useEmailReadProvider()      // EmailReadAdapter | null
+const ai      = useAIProvider()             // AIProviderAdapter | null
+const creds   = useCredentialsProvider()    // CredentialsAdapter | null
+
+// Named provider (multi-provider setup)
+const supabase = useDataProvider('supabase')
+```
+
+### Email (`emailSend`, `emailRead`)
+
+Due categorie: `emailSend` spedisce, `emailRead` legge le mail nuove da un cursore che l'app conserva. Gli
+adapter con chiavi, token o password girano sul server, da `@llmnative/react/server` (senza React).
+
+```ts
+import { ResendEmailSender, BrevoEmailSender, GmailEmailSender, GmailEmailReader, ImapEmailReader,
+  createGmailOAuth, decodeGmailPushNotification, GMAIL_SCOPES, EmailProviderError } from '@llmnative/react/server'
+
+const mail = new BrevoEmailSender({ apiKey, from: { email: 'noreply@acme.it', name: 'Acme' } })  // o ResendEmailSender
+await mail.send({ to, cc, bcc, replyTo, subject, html, text })   // → { id, threadId? }; to/cc/bcc: stringa, { email, name } o lista
+new GmailEmailSender({ auth: { clientId, clientSecret, refreshToken }, from? })  // send con threadId per restare nella conversazione
+
+const reader = new GmailEmailReader({ auth: { clientId, clientSecret, refreshToken }, topic: 'projects/p/topics/gmail' })
+// o new ImapEmailReader({ host, port: 993, secure: true, user, password })  — peer opzionali imapflow + mailparser
+const { cursor, expiresAt } = await reader.start()    // da adesso; Gmail: watch su Pub/Sub, rinnovare prima di expiresAt
+const batch = await reader.read(cursor, { limit: 50 }) // { messages: EmailMessage[], cursor } — cursore scaduto: riparte da adesso
+decodeGmailPushNotification(pubsubData)                // { emailAddress, historyId } | null
+createGmailOAuth({ clientId, clientSecret, redirectUri })  // authorizationUrl({ state, scopes }), exchangeCode(code) → { email, refreshToken }
+```
+
+`EmailMessage`: `{ id, threadId, from, to, subject, date (ISO), text, direction: 'inbound' | 'outbound', cursor }` — `cursor` è dove riprendere dopo quel messaggio (se un gestore fallisce, si salva il cursore dell'ultimo gestito).
+Errori: `EmailProviderError` con `code` (`not-configured`, `invalid-message`, `unauthorized`, `rejected`,
+`rate-limited`, `unavailable`, `unknown`), `provider`, `status`; il messaggio non contiene mai chiavi.
+Schede per una UI di collegamento: `EMAIL_SEND_PROVIDER_DEFINITIONS`, `EMAIL_READ_PROVIDER_DEFINITIONS`.
+Nel browser il provider `google` registra il driver `gmail` di `emailSend` (utente con Google);
+`useEmailSendProvider(name?)`, `useEmailReadProvider(name?)`. La categoria `email` e `useEmailProvider` non
+esistono più (3.0.0).
+
+### GitHub (`githubAuth`, sessione sul server dell'app)
+
+GitHub richiede il client secret per scambiare il codice: scambio, token e sessione stanno sul server
+dell'app, il browser vede solo il profilo. Config `providers.github = { sessionUrl: '/api/auth/github' }`,
+driver `auth: 'githubAuth'`; funziona con `AuthButton` (pulsante e `aspect="avatar"`) e
+`useAuthProvider('githubAuth')`. Il server espone sotto `sessionUrl`:
+
+| Rotta | Risposta |
+|---|---|
+| `GET /login?returnTo=<path>[&scope=…]` | redirect a GitHub, poi di nuovo a `<path>` |
+| `GET /me` | `{ login, name, avatarUrl, email }`, 401 senza sessione |
+| `POST /logout` | chiude la sessione |
+
+Lato server, da `@llmnative/react/server`:
+
+```ts
+const oauth = createGitHubOAuth({ clientId, clientSecret, scopes: ['read:org'] })
+oauth.authorizeUrl({ state, redirectUri, codeChallenge })   // PKCE S256
+const { accessToken } = await oauth.exchangeCode({ code, redirectUri, codeVerifier })  // GitHubOAuthError se rifiutato
+await oauth.getUser(accessToken)            // { login, name, avatarUrl, email }
+await oauth.getOrganizations(accessToken)   // [{ login, avatarUrl, role: 'admin' | 'member' }]
+```
+
+### Interfacce principali
+
+```ts
+// DataProviderAdapter
+read(path, { where?, order?, limit?, toArray?, exception? }) / set(path, data, exception?) / update(path, data, exception?) / remove(path, exception?)
+subscribe(path, callback: (records: RecordArray) => void, { where?, order?, limit?, fieldMap?, onLoad?, onError? }): () => void
+count?(path): Promise<number>
+
+// StorageProviderAdapter
+upload(file, path): Promise<string|undefined>
+getURL(path) / download(path): Promise<Blob|undefined> / delete(path): Promise<boolean>
+
+// AuthProviderAdapter
+signIn(intent?, options?) / signOut() / getUser(): UserProfile|null
+onAuthChange(callback) / getAccessToken(): Promise<string|null>
+```
+
+### Auth sign-in methods
+
+| method | Firebase | Supabase | Google |
+|---|---|---|---|
+| `password` | ✅ | ✅ | — |
+| `anonymous` | ✅ | ✅ | — |
+| `magic_link` | — | ✅ | — |
+| `oauth` (github, apple…) | ✅ | ✅ | — |
+| GIS + scoped token | — | — | ✅ |
+
+```ts
+await auth.signIn({ method: 'password', email: '...', password: '...' })
+await auth.signIn({ method: 'oauth', provider: 'github' })
+// Google: token per API scope
+const token = await auth.getAccessToken('https://www.googleapis.com/auth/gmail.send')
+```
+
+### Schermate di accesso e gate senza redirect (CR-127)
+
+Le schermate sono pronte: non scriverne a mano. Non conoscono il backend: ricevono le funzioni da
+chiamare (una promessa) e mostrano l'errore lanciato tradotto, mai il testo grezzo del servizio
+(`authErrorMessage`: codici di Firebase e Supabase, `AuthFlowError(reason)` per le funzioni tue).
+Testi nel namespace `access` delle 6 lingue. Ognuna ha `brand`, `toolbar`, `footer`, `bare` (solo il
+contenuto, in una modale), `errorMessage(error)`.
+
+| Componente | Cosa fa | Funzioni |
+|---|---|---|
+| `SignIn` | provider esterni, email + password, codice via email, in qualsiasi combinazione | `onPasswordSignIn({email,password})`, `onRequestCode(email)` + `onVerifyCode(email,code)`, `providers` + `onProviderSignIn(id)` |
+| `SignUp` | nome, email, password con i requisiti mentre si scrive, termini; poi "controlla la tua email" | `onSignUp({name,email,password})` → `{ needsEmailVerification }`, `onResendVerification(email)` |
+| `ForgotPassword` | email → stessa risposta con o senza account, nuovo invio dopo un'attesa | `onSendReset(email)` |
+| `ResetPassword` | nuova password dal link dell'email; link scaduto | `onResetPassword(password)`, `invalidLink` |
+| `VerifyEmail` | attivazione: con `code` verifica subito, senza aspetta la conferma | `onVerify(code)`, `onResend()`, `onContinue()` |
+| `VerifyCode` | codice di N cifre in caselle, inviato a codice completo | `onVerify(code)`, `onResend()`, `onChangeEmail()` |
+| `OneTimeCodeInput` | le caselle da sole (incolla, avanti/indietro, `one-time-code`) | `value`, `onChange`, `onComplete` |
+| `AuthLayout` | la cornice di una schermata (marchio, card, titolo, piè di pagina) | — |
+| `AuthGate` | la pagina solo con la sessione; senza, `fallback` al suo posto | `allow(user)`, `denied`, `loading` |
+
+```tsx
+import { App, SignIn, AuthFlowError } from '@llmnative/react';
+
+// Tutta l'app riservata: senza sessione ogni pagina mostra l'accesso al suo posto, l'indirizzo
+// resta quello aperto e dopo l'accesso compare la pagina. Nessuna pagina /login, nessun redirect.
+<App
+  menuConfig={{ main: [...], access: [{ path: '/invito/:token', page: InvitePage, public: true }] }}
+  authGate={{
+    fallback: <SignIn providers={['google', 'apple']} onProviderSignIn={enter}
+                      onRequestCode={sendCode} onVerifyCode={checkCode} appName="CRM" />,
+    allow: async (user) => (await isMember(user)),   // altrimenti "Accesso non consentito"
+  }}
+/>
+
+// Una funzione tua che rifiuta: la schermata dice "Il codice non è corretto o è scaduto."
+async function checkCode(email: string, code: string) {
+  const { token } = await callFunction('verifyLoginCode', { email, code }).catch(() => {
+    throw new AuthFlowError('invalidCode');
+  });
+  await signInWithCustomToken(token);
+}
+```
+
+Con gli adapter del framework `useAuthFlows(provider?, { verifyEmailPath, resetPasswordPath })` dà le
+funzioni pronte (`<SignIn {...flows.signIn} />`, `flows.signUp`, `flows.forgotPassword`,
+`flows.resetPassword(linkCode())`, `flows.verifyEmail`). Metodi opzionali di `AuthProviderAdapter`:
+
+| Metodo | Firebase | Supabase | `mockAuth` |
+|---|---|---|---|
+| `whenReady` (il gate aspetta la sessione) | ✅ | ✅ | ✅ (anche `githubAuth`) |
+| `signUp`, `sendPasswordReset`, `confirmPasswordReset` | ✅ | ✅ | ✅ |
+| `sendEmailVerification`, `verifyEmail` | ✅ | ✅ | ✅ |
+| `requestEmailCode`, `verifyEmailCode` | — (serve una funzione tua) | ✅ | ✅ |
+
+`useAuthSession(provider?)` dà `{ user, ready, signOut }`. `linkCode()` legge il codice del link
+(`oobCode`, `token_hash`, `code`). `mockAuth` (`providers.mock.auth: true`) è solo per demo e test:
+qualsiasi email e password, codice `123456`; con `accounts` rifiuta le credenziali sbagliate.
+Link delle email: in Firebase imposta l'URL di azione sulle tue pagine (`/reset-password`,
+`/verify-email`); in Supabase usa `{{ .TokenHash }}` nei template delle email.
+
+### CredentialsAdapter (Google Service Account)
+```tsx
+// Chiama Google APIs lato browser senza Node.js
+<App providers={{ google: { serviceAccount: { clientEmail, privateKey } }, services: { credentials: 'googleServiceAccount' } }} />
+
+const creds = useCredentialsProvider()
+const token = await creds.getToken('https://www.googleapis.com/auth/solar')
+```
+
+### Letture: filtri, `limit`, errori (CR-129)
+
+Gli stessi operatori e lo stesso contratto su ogni provider (`firestoreDb`, `supabaseDb`, `dbRealtime`, `mock`):
+l'adapter li traduce nei comandi del database, o li applica nel browser dove il database non li ha.
+
+| `where` | Significato | Firestore | Supabase | Realtime DB / Mock |
+|---|---|---|---|---|
+| `{ f: 'x' }` / `{ f: { eq } }` | uguale | `==` | `eq` | server sul campo di `order`, altrimenti browser |
+| `lt` `lte` `gt` `gte` | confronto | `<` … `>=` | `lt` … `gte` | idem |
+| `{ f: ['a','b'] }` / `in`, `nin` | uno dei valori / nessuno | `in` (≤30), `not-in` (≤10) | `in`, `not.in` | browser |
+| `contains: v` | il campo lista contiene `v` | `array-contains` | `contains` | browser |
+| `containsAny: [..]` | contiene almeno uno | `array-contains-any` (≤30) | `overlaps` | browser |
+
+`limit: n` (in `read` e `subscribe`) tiene i primi `n` dopo `where` e `order`: Firestore `limit()`, Supabase
+`.limit()`, Realtime Database `limitToFirst`/`limitToLast` (nel browser se restano filtri da applicare lì).
+
+Un'iscrizione che il database rifiuta (regole, sessione, indice mancante, rete) arriva a `onError` come
+`DataProviderError` con `code`: `permission-denied` | `unauthenticated` | `invalid-query` | `unavailable` |
+`unknown` (l'errore originale in `cause`). Senza `onError` il provider la scrive in console come prima.
+Un percorso di record (`/users/u1`) segue quel record su ogni provider.
+
+```ts
+const { records, loading, error } = useDataSubscription('/registro', { order: { at: 'desc' }, limit: 50 })
+// error?.code === 'permission-denied' → la pagina dice che non può leggere, invece di restare in caricamento
+db.subscribe('/posts', setRecords, { where: { tags: { contains: 'news' } }, limit: 20, onError: (e) => show(e.code) })
+```
+
+`Grid` con `path` mostra `common.loadError` al posto delle righe quando la lettura fallisce.
+
+### Provider custom
+```ts
+import { DataProviderAdapter, RecordArray } from '@llmnative/react'
+
+export class RestDataProvider implements DataProviderAdapter {
+  async read(path: string): Promise<unknown> { ... }
+  async set(path: string, data: object): Promise<void> { ... }
+  async update(path: string, data: object): Promise<void> { ... }
+  async remove(path: string): Promise<void> { ... }
+  subscribe(path: string | undefined, callback: (records: RecordArray) => void): () => void {
+    return () => undefined
+  }
+}
+```
+
+---
+
+## Grid — CRUD table/gallery
+
+```tsx
+<Grid
+  path="/users"               // DataProvider-backed — oppure records={array} per in-memory
+  columns={[
+    { key: 'name',  label: 'Nome',   sortable: true },
+    { key: 'email', label: 'Email' },
+    { key: 'role',  label: 'Ruolo',  render: ({ value }) => <Badge>{value}</Badge> },
+    { key: 'date',  label: 'Data',   render: 'date' },
+  ]}
+  actions={['add', 'edit', 'delete']}   // oppure Record<string, GridAction>
+  view="table"                          // 'table' | 'gallery'
+  pagination={{ limit: 20 }}
+  groupBy="status"
+  sortable={{ field: 'name', dir: 'asc' }}
+  form={<FormFields />}
+  onSave={async ({ record, action }) => record._key}
+  onComplete={async ({ record, action }) => true}
+  selection={{ mode: 'multiple', onChange: (sel) => {} }}
+  reorderable
+  onReorder={(records, meta) => {}}
+  header={(ctx) => <div>{ctx.title}</div>}
+  footer={(ctx) => <div>{ctx.records.length} records</div>}
+/>
+```
+
+| Prop | Tipo | Note |
+|---|---|---|---|
+| `path` | `string \| "fromUrl"` | Path provider-backed |
+| `records` | `RecordArray` | Dati in memoria (alternativa a path) |
+| `columns` | `GridColumn[]` | `{ key, label, sortable?, render?, className? }` |
+| `actions` | `Array<'add'\|'edit'\|'delete'> \| Record<string, GridAction>` | |
+| `view` | `'table' \| 'gallery'` | |
+| `groupBy` | `string \| string[]` | |
+| `pagination` | `PaginationParams` | `{ limit, page?, maxPageButtons?, align?, sticky? }` |
+| `sortable` | `boolean \| OrderConfig` | |
+| `selection` | `false \| 'single' \| 'multiple' \| GridSelectionConfig` | |
+| `form` | `ReactElement \| ((ctx) => ReactNode)` | Form condiviso per CRUD |
+| `onSave` | `GridMutationSaveHandler` | `async ({ record, action }) => string` |
+| `onDelete` | `GridMutationDeleteHandler` | `async ({ record }) => string` |
+| `onComplete` | `GridAfterActionHandler` | `async ({ record, action }) => boolean` |
+| `onRowClick` | `(record) => void` | |
+| `reorderable` | `boolean` | Abilita drag & drop righe |
+| `onReorder` | `GridReorderHandler` | `(records, meta) => void` |
+| `onLoad` | `(records) => TRecord[]` | Trasforma records dopo il fetch |
+| `editDeepLink` | `boolean` | Sincronizza modal edit con URL |
+| `audit` | `boolean` | Logga mutazioni |
+| `sticky` | `'top' \| 'bottom'` | Header/footer sticky |
+| `wrapperClassName` | `string` | CSS wrapper esterno |
+| `loading` | `boolean` | Stato loading override |
+| `title` | `ReactNode` | Titolo header grid |
+| `before` / `after` | `ReactNode` | Slot prima/dopo il contenuto |
+| `header` / `footer` | `ReactNode \| ((ctx) => ReactNode)` | Header/footer custom |
+| `searchable` | `boolean \| GridSearchConfig` | Search box nell'header default — `{ fields?, placeholder? }` |
+| `filters` | `GridFilterConfig[]` | Checkbox toggle nell'header default, applicati PRIMA di `searchable` — `{ key, label, defaultValue?, predicate(record, value) }` |
+
+**GridAction kind:** `'modal'` (default), `'route'`, `'external'`, `'inline'`, `'delete'`
+
+---
+
+## Form — form CRUD con lifecycle
+
+```tsx
+<Form
+  path="/products"
+  appearance="card"           // 'card' | 'empty'
+  showBack
+  defaultValues={{ status: 'draft' }}
+  keyGenerator={() => `prod_${Date.now()}`}
+  onLoad={(data) => { /* side-effect hook, non trasforma */ }}
+  onSave={async ({ record, action }) => { /* return storagePath or undefined */ }}
+  onDelete={async ({ record }) => { /* confirm */ }}
+  onComplete={async ({ action }) => { if (action === 'save') navigate('/products') }}
+>
+  <Input name="title" label="Titolo" required />
+  <Input name="price" label="Prezzo" type="number" />
+  <Input name="address.city" label="Città" />      {/* oggetto annidato */}
+  <Repeat name="tags" defaultLength={1}>
+    {(i) => <Input name={`tags.${i}`} label={`Tag ${i+1}`} />}
+  </Repeat>
+</Form>
+```
+
+| Prop | Tipo | Note |
+|---|---|---|---|
+| `path` | `string` | Path provider-backed |
+| `appearance` | `'card' \| 'empty'` | Guscio visuale |
+| `controller` | `FormController` | Controller condiviso per bottoni custom esterni |
+| `showBack` | `boolean` | Pulsante Back nel footer |
+| `defaultValues` | `RecordProps` | Valori iniziali per nuovo record |
+| `keyGenerator` | `(record) => string` | Generatore chiave primaria custom |
+| `draftBucket` | `string` | Bucket stabile che isola la bozza locale; omettilo per disabilitare la persistenza |
+| `noticeAnchorRef` | `React.RefObject<HTMLElement>` | Ancoraggio sticky per notifiche |
+| `showNotice` | `boolean` | Mostra notifiche save/delete (default `true`) |
+| `onSubmit` | `FormSubmitHandler` | `async ({ record }) => void`. **Form d'azione** (CR-125): non legge e non scrive nulla; invia anche senza modifiche e con Invio in un campo; niente pulsante Salva né "Salvato" (il pulsante è tuo: `useFormController().save()`); l'errore lanciato appare nel suo avviso; restituire `false` = è fallito e la pagina dice già perché (nessun avviso né `onComplete`). Esclude `path`, `onSave`, `onDelete`, `keyGenerator` (errore di tipo e a runtime). Sostituisce `requireChanges={false}` della 1.x |
+| `children` | `ReactNode \| ((fields) => ReactNode) \| (({ record }) => ReactNode)` | Contenuto form |
+| `header` | `ReactNode` | Contenuto header custom |
+| `footer` | `ReactNode` | Contenuto footer custom |
+| `wrapperClassName` | `string` | CSS wrapper esterno |
+| `headerClassName` | `string` | CSS header |
+| `className` | `string` | CSS body form |
+| `footerClassName` | `string` | CSS footer |
+| `log` | `boolean` | Logga ogni modifica su console |
+| `onLoad` | `(record) => void` | Side-effect dopo il caricamento (non trasforma) |
+| `onRecordChange` | `(record) => void` | Cambio campo in tempo reale |
+| `onSave` | `FormSaveHandler` | `async ({ record, prevRecord?, storagePath?, action }) => string \| undefined`. Form che **salva un record**, solo se un campo è cambiato: restituisce il path dove scriverlo, `undefined` = il `path` del Form (senza `path` non scrive), `false` = è fallito e la pagina dice già perché (non scrive, nessun avviso, `save()` dà `false`). Per un'azione (chiamare un comando) usa `onSubmit`. L'errore lanciato appare nell'avviso del Form |
+| `onDelete` | `FormDeleteHandler` | `async ({ record }) => string \| undefined` |
+| `onComplete` | `FormFinallyHandler` | `async ({ record, action }) => boolean`; `action` è `'create' \| 'update' \| 'delete' \| 'submit'` |
+
+**Form controller** — stato e azioni native del form accessibili da qualsiasi punto della pagina.
+
+Due hook:
+
+| Hook | Dove usarlo | Cosa restituisce |
+|---|---|---|
+| `useFormController(controller?)` | Ovunque (anche fuori dal form) | Crea o si aggancia a un `FormController`. Senza argomenti ne crea uno locale stabile. Con un `controller` esistente ci si aggancia. |
+| `useFormActions()` | Solo dentro `<Form>` (legge dal context) | Restituisce lo stesso `FormController` del form genitore. Lancia errore se usato fuori. |
+
+Esempio — bottone custom fuori dal form:
+```tsx
+const form = useFormController();
+
+<ActionButton disabled={form.saveDisabled} onClick={() => { void form.save(); }} />
+<Form controller={form} draftBucket="workspace/acme" onSave={...} />
+```
+
+Esempio — form d'azione: chiama un comando, non salva nulla (CR-125):
+```tsx
+const form = useFormController();
+
+<Form controller={form} appearance="empty" onSubmit={({ record }) => call('verifyLoginCode', record)}>
+  <Input name="email" type="email" label="Email" required />
+  <Input name="code" label="Codice" required inputMode="numeric" maxLength={6} pattern="[0-9]{6}" autoComplete="one-time-code" />
+</Form>
+<LoadingButton label="Entra con il codice" loading={form.isSaving} onClick={() => form.save()} />
+```
+Con valori proposti (avviare una release con la versione proposta) si inviano anche senza modificarli:
+`<Form controller={form} appearance="empty" defaultValues={{ version: '1.4.0' }} onSubmit={({ record }) => start(record)}>`.
+
+Esempio — uso dentro il form (senza passare controller):
+```tsx
+function MySaveButton() {
+  const form = useFormActions();
+  return <LoadingButton disabled={form.saveDisabled} loading={form.isSaving} onClick={form.save} />;
+}
+```
+
+Stato esposto dal controller: `record`, `isNewRecord`, `isDirty`, `canSave`, `canDelete`, `isSaving`, `isDeleting`, `saveDisabled`, `deleteDisabled`, `hasDraft`, `draftStatus`, `errors`, `hasErrors`.
+
+Azioni: `save()`, `delete()`, `reset()`, `restoreDraft()`, `discardDraft()`.
+
+---
+
+## Campi form
+
+### Input
+```tsx
+<Input name="x" label="..." required />                          // text (default)
+<Input name="price" type="number" min={0} max={100} step={0.01} />
+<Input name="email" type="email" />
+<Input name="phone" type="tel" autoComplete="tel" />                 // o <Tel name="phone" />
+<Input name="code" inputMode="numeric" maxLength={6} pattern="[0-9]{6}" autoComplete="one-time-code" />  // un codice monouso
+<Input name="pwd"   type="password" />
+<Input name="date"  type="date" />
+<Input name="color" type="color" />
+<TextArea name="bio" minHeight={96} />
+<Checkbox name="active" valueChecked="yes" />
+<Switch name="gate" label="Passa dalla CI" disabled title="L'agente non committa" />   // CR-116: disabled (non cambia né con il clic né da tastiera), title anche sull'etichetta: il motivo al passaggio del mouse
+```
+`Input` props: `name`(req) `label` `type` `required` `disabled` `placeholder` `min` `max` `step` `inputMode` `maxLength` `pattern` `autoComplete` `validator:(v)=>string|undefined`
+`type`: `'text' | 'number' | 'email' | 'tel' | 'password' | 'color' | 'date' | 'time' | 'datetime-local' | 'week' | 'month' | 'range' | 'checkbox' | 'radio' | 'url'`
+
+**NOTA**: il tipo HTML si passa con `type`. `inputType` e i sotto-componenti `Input.Number`/`Input.Email`/`Input.Date` non esistono.
+
+**Label come nodo**: `label` di tutti i campi di inserimento (`Input`, `TextArea`, `Checkbox`, `Select`, `Autocomplete`, `Checklist`, `Upload*`, `ImageField`, `CodeEditor`, `RichText`, `AddressAutocomplete`, `UploadCSV`, `Prompt`) accetta una stringa o un nodo React (tipo `FieldLabel`), disegnato dentro la `<label>` prima dell'asterisco di obbligatorio. Dove serve un testo (messaggio "obbligatorio", `aria-label`) si usa il testo del nodo, ricavabile anche con `labelText(node)`.
+```tsx
+<Select name="skill" required options={skills} label={<>Skill <ActionButton icon="info" ariaLabel="Apri la skill" variant="link" onClick={openSkill} /></>} />
+```
+
+### Select / Autocomplete / Checklist
+```tsx
+<Select name="role" options={[{ label: 'Admin', value: 'admin' }]} />
+<Select name="categoryId" optionsSource={{ path: '/categories', labelField: 'name', valueField: '_key' }} />
+<Autocomplete name="userId" optionsSource={{ path: '/users', labelField: 'email' }} maxItems={1} />
+<Checklist name="tags" options={['a', 'b', 'c']} />
+```
+
+| Prop | Tipo | Note |
+|---|---|---|
+| `options` | `Option[] \| string[] \| number[]` | |
+| `optionsSource` | `{ path, labelField, valueField?, where?, order?, fieldMap?, onLoad? }` | Carica da provider |
+| `order` | `{ field: 'label' \| 'value', dir: 'asc' \| 'desc' }` | |
+| `placeholderOption` | `Option` | Solo Select |
+| `placeholder` | `string` | Solo Autocomplete |
+| `creatable` | `boolean` | Solo Autocomplete — crea nuovi valori |
+| `onCreate` | `(value) => void \| boolean \| Promise<void \| boolean>` | Solo Autocomplete — restituire `false` per non selezionare il valore creato (es. aprire un modulo di creazione) |
+| `listClassName` / `optionClassName` | `string` | Solo Autocomplete — classi della lista e delle voci (anche da tema `Autocomplete.listClassName` / `optionClassName`) |
+| `minItems` / `maxItems` | `number` | Solo Autocomplete |
+| `itemClassName` | `string` | Solo Checklist |
+| `validator` | `(value) => string \| undefined` | Tutte le varianti |
+| `readOnlyAfterSet` | `boolean` | readonly dopo primo valore |
+| `disabled` | `boolean` | |
+| `title` | `string` | |
+| `feedback` | `string` | Messaggio di errore/suggerimento |
+
+`Autocomplete` è una combobox accessibile: la lista (in un portal, larga quanto il campo, stile popover del tema) mostra solo le label e filtra per label/value senza distinzione di maiuscole e accenti; i chip mostrano la label; tastiera: frecce, Invio, Esc (chiude solo la lista, non il `Modal`), Tab, Backspace su campo vuoto rimuove l'ultimo valore. Con `creatable` compare la voce "Crea «testo»". Il valore salvato è sempre l'array dei `value`. `Autocomplete` e `Checklist` sono export nominati: `Select.Autocomplete`/`Select.Checklist` non esistono.
+
+### UploadImage / UploadDocument / UploadCSV
+```tsx
+<UploadImage name="cover" label="Copertina" />    {/* con crop editor */}
+<UploadDocument name="pdf" label="PDF" />
+<UploadCSV name="data" label="Importa CSV" />      {/* con preview tabellare */}
+```
+
+**UploadImageProps** (eredita FormFieldProps):
+| Prop | Tipo | Note |
+|---|---|---|
+| `name` | `string` (required) | |
+| `uploadPath` | `string` | Path storage per upload automatico |
+| `accept` | `string` | MIME types accettati |
+| `editable` | `boolean` | Abilita crop editor |
+| `multiple` | `boolean` | Multipla selezione |
+| `max` | `number` | Numero massimo file |
+| `feedback` | `string` | Testo placeholder drop zone |
+| `srcsetWidths` | `number[]` | Larghezze varianti responsive |
+| `previewHeight` / `previewWidth` | `number` | Dimensioni preview |
+
+**UploadDocumentProps** (eredita FormFieldProps): `name`, `uploadPath`, `accept`, `editable`, `multiple`, `max`
+
+### UploadCSV
+```tsx
+<UploadCSV name="data" label="Importa CSV" />
+```
+| Prop | Tipo |
+|---|---|
+| `name` | `string` (required) |
+| `onDataLoaded` | `(data: UploadCSVData) => void` |
+| `onParseField` | `([key, value]) => [key, value] \| undefined` |
+| `normalizeKeys` | `boolean` |
+| `removeEmptyFields` | `boolean` |
+| `delimiter` | `string` |
+| `label` / `icon` | Opzionali |
+
+### ImageField
+```tsx
+<ImageField
+  name="hero"
+  label="Hero image"
+  defaultValue={{ src: 'https://example.com/hero.jpg', alt: 'Hero shot' }}
+  srcsetWidths={[400, 800]}
+  uploadPath="/content/images"
+/>
+```
+
+Gestisce un oggetto `{ src, alt, srcset?, sizes? }`, preview inline, crop editor e generazione opzionale di varianti responsive.
+
+### CropImage
+```tsx
+<CropImage img={imageObj} title="Ritaglia" scales={{ '1:1': 1, '4:3': 1.33 }} />
+```
+Componente di ritaglio indipendente. `img` ha tipo `{ fileName, variants }` dove ogni variante è `{ fileName, type, scale, top, left, width, height, base64? }`. Usato internamente da `UploadImage` e `ImageField`, ma esportato pubblicamente per uso standalone.
+
+### CodeEditor
+```tsx
+<CodeEditor
+  name="code"
+  label="Template"
+  language="html"
+  placeholder="Scrivi HTML..."
+  minHeight={200}
+  maxHeight={600}
+  disabled={false}
+  required
+  validateSyntax
+  commands={[{ name: 'wrap-section', handler: ({ value }) => `<section>\n${value}\n</section>` }]}
+  commandsTrigger="/"
+/>
+```
+Editor basato su CodeMirror con syntax highlighting e validazione. Linguaggi: `liquid`, `html`, `json`, `js`, `ts`, `css`.
+Quando `commands` e presente, `CodeEditor` apre internamente `ContextMenu` sul trigger configurato.
+
+| Prop extra | Tipo |
+|---|---|
+| `language` | `CodeEditorLanguage` |
+| `placeholder` | `string` |
+| `minHeight` / `maxHeight` | `number` |
+| `validateSyntax` | `boolean` |
+| `validator` | `(value) => string \| undefined \| Promise<string \| undefined>` |
+| `extensions` | `unknown[]` |
+
+### RichText
+```tsx
+<RichText
+  name="body"
+  label="Article body"
+  placeholder="Scrivi..."
+  toolbar="fixed"                    // 'fixed' | 'floating' | false
+  toolbarCommands={['bold', 'italic', 'heading1', '|', 'bulletList', 'link']}
+  outputFormat="html"                // 'html' | 'json' | 'text'
+  statusBar={{ tagBreadcrumb: true, wordCount: true }}
+  minHeight={200}
+  maxHeight={800}
+  imageUpload={{ path: '/content/images', srcsetWidths: [400, 800] }}
+  commands={[{ name: 'summary', icon: 'sparkles' }]}
+  commandsTrigger="/"
+/>
+```
+
+| Prop extra | Tipo |
+|---|---|
+| `placeholder` | `string` |
+| `disabled` | `boolean` |
+| `feedback` | `string` |
+| `toolbar` | `'fixed' \| 'floating' \| false` |
+| `toolbarCommands` | `ToolbarCommand[]` |
+| `outputFormat` | `'html' \| 'json' \| 'text'` |
+| `statusBar` | `boolean \| StatusBarConfig` |
+| `minHeight` / `maxHeight` | `number` |
+| `imageUpload` | `RichTextImageUploadConfig` |
+| `documentUpload` | `RichTextDocumentUploadConfig` |
+| `validator` | `(value) => string \| undefined` |
+
+### Repeat — array dinamici
+```tsx
+<Repeat name="items" defaultLength={3} minItems={1} maxItems={10} label="Elementi" layout="vertical" readOnly>
+  {({ index, record, records, remove }) => (
+    <>
+      <Input name={`items.${index}.name`} label="Nome" />
+      <UploadImage name={`items.${index}.photo`} label="Foto" />
+    </>
+  )}
+</Repeat>
+```
+
+| Prop | Tipo | Note |
+|---|---|---|
+| `name` | `string` (required) | |
+| `children` | `ReactNode \| ((args) => ReactNode)` | Render prop con `{ index, record, records, remove }` |
+| `defaultLength` | `number` | Righe iniziali |
+| `minItems` / `maxItems` | `number` | Min/max righe |
+| `layout` | `'vertical' \| 'horizontal' \| 'inline'` | |
+| `label` | `string` | Etichetta gruppo |
+| `labelPosition` | `'top' \| 'bottom'` | |
+| `hideRemoveButton` | `boolean` | Nascondi rimozione |
+| `readOnly` | `boolean` | Sola lettura |
+| `onChange` | `FieldOnChange` | |
+| `onAdd` / `onRemove` | `(records) => void` | Callback aggiunta/rimozione |
+
+### Prompt — campo AI-potenziato
+```tsx
+<Prompt
+  name="summary"
+  mode="run"                  // 'edit' | 'run'
+  onRunPrompt={async (prompt, options) => AI.fetch(prompt)}
+  commands={[{ name: 'translate', icon: 'languages', handler: (v) => `Translate:\n${v}` }]}
+  commandsTrigger="/"         // default automatico quando commands e presente
+  attachments
+  statusItems={['tokensIn', 'tokensOut', 'contextPercent', 'duration']}
+/>
+```
+
+Quando `commands` e presente in `mode="run"`, `Prompt` monta internamente `ContextMenu` sulla textarea del risultato. Il trigger di default e `"/"`; `commandsTrigger` permette di cambiarlo. Il menu diventa searchable automaticamente sopra una soglia interna di comandi.
+
+`renderFallback`: quando l'AI non e configurata, `Prompt` monta un fallback testuale; passa `renderFallback` per personalizzarlo (riceve `{ name, label, required, onChange }`).
+
+---
+
+## UI Primitives
+
+### Alert
+```tsx
+<Alert variant="success">Salvato!</Alert>
+<Alert variant="warning" icon placement="fixed" timeout={3000}>Attenzione</Alert>
+```
+`variant`: `'info' | 'success' | 'warning' | 'danger' | 'primary' | 'secondary' | 'light' | 'dark'`
+`appearance`: `'default' | 'text'`
+`placement`: `'inline' | 'fixed'`
+
+### Badge
+```tsx
+<Badge variant="success">Attivo</Badge>
+```
+`variant`: stessi valori di Alert
+
+### Button variants
+```tsx
+<ActionButton variant="primary" label="Salva" icon="save" onClick={handleSave} />
+<LoadingButton variant="primary" label="Invia" onClick={async (e, setMsg) => { await save(); setMsg('Salvato!') }} />
+<BackLink label="Indietro" />
+<GoSite href="https://..." label="Visita" />
+```
+
+**IButton props:** `variant`, `label`, `icon`, `badge`, `disabled`, `ariaLabel`, `title`, `iconClassName`, `onClick`
+**LoadingButton aggiunge:** `loading`, `loadingLabel` — `onClick` riceve `(e, setMessage?) => Promise<unknown>`
+
+### Card
+```tsx
+<Card title="Titolo" header={<Actions />} footer={<Pagination />} loading={isLoading}>
+  {children}
+</Card>
+```
+
+### Modal
+```tsx
+<Modal title="Conferma" size="md" position="center" onClose={() => {}} onSave={handleSave} onDelete={handleDelete} motion="fade" allowFullscreen stackedBehind>
+  {content}
+</Modal>
+<ModalYesNo title="Sicuro?" onClose={() => {}} onYes={async () => true}>Eliminare il record?</ModalYesNo>
+// Un'azione che non si annulla: nominala e mettila in rosso (CR-128); "Annulla" viene per primo.
+<ModalYesNo title="Revocare l'invito?" danger yesLabel="Revoca" noLabel="Annulla" onYes={revoke} onNo={async () => true}>La persona non potrà più usare il link.</ModalYesNo>
+<ModalOk title="Completato!" onClose={() => {}}>Salvato.</ModalOk>
+```
+`size`: `'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'fullscreen'`
+`position`: `'center' | 'top' | 'left' | 'right' | 'bottom'`
+`ModalYesNo` e `ModalOk` sono export separati: `Modal.YesNo` e `Modal.Ok` non esistono.
+Tastiera: Esc chiude il modal in cima alla pila (`closeOnEscape`, default `true`).
+Accessibilità: il dialog ha `role="dialog"`, `aria-modal="true"` (non con `stackedBehind`) e `aria-labelledby` verso `title` (o `header` stringa) — nei test si trova con `getByRole('dialog', { name })`.
+
+| Prop | Tipo | Note |
+|---|---|---|
+| `children` | `ReactNode` (required) | |
+| `title` | `ReactNode` | |
+| `header` / `footer` | `ReactNode \| false` | Custom header/footer |
+| `size` / `position` | Come sopra | |
+| `onClose` | `() => void` | |
+| `onSave` / `onDelete` | `(e) => Promise<boolean>` | |
+| `allowFullscreen` | `boolean` | Toggle fullscreen |
+| `showCancel` | `boolean` | Default `true` |
+| `stackedBehind` | `boolean` | Modale sotto un'altra (stile Google Tag Manager): un velo la scurisce, il suo backdrop resta com'è (quello della modale sopra entra sopra, così la pagina si scurisce di un gradino per modale) e non riceve il puntatore. I pannelli laterali aperti sullo stesso lato si impilano da soli: quello in cima prende la larghezza con cui si è aperto il primo, ognuno sotto è largo il 10% in più di quello sopra (100%, 110%, 121%…), così ne sporge una striscia. Solo la larghezza cambia, con la transizione dello slide, in entrata e in uscita |
+| `closeOnBackdrop` | `boolean` | Default `true` |
+| `closeOnEscape` | `boolean` | Default `true` — solo il modal in cima reagisce |
+| `zIndex` | `number` | |
+| `motion` | `MotionReference` | Preset animazione |
+| Classi CSS header/title/subtitle/body/footer | `string` | |
+
+### Table
+```tsx
+<Table
+  columns={[{ key: 'name', label: 'Nome', sort: true }]}
+  records={records}
+  onRowClick={(record) => {}}
+  selection="multiple"
+  sortable={{ field: 'name', dir: 'asc' }}
+  pagination={{ limit: 20 }}
+  onReorder={(records, meta) => {}}
+  onSelectionChange={(sel) => {}}
+  groupBy="status"
+  renderCell={(record, key, index) => <CustomCell />}
+/>
+```
+
+| Prop | Tipo |
+|---|---|
+| `columns` | `TableHeaderProp[]` |
+| `records` | `RecordArray` |
+| `sortable` | `boolean \| OrderConfig` |
+| `pagination` | `PaginationParams` |
+| `selection` | `'single' \| 'multiple'` |
+| `onRowClick` | `(record) => void` |
+| `onReorder` | `(records, meta) => void` |
+| `onSelectionChange` | `(selection) => void` |
+| `renderCell` | `(record, key, index) => ReactNode` |
+| `groupBy` | `string \| string[]` |
+| `activeKey` | `string \| null` |
+| `selectedKeys` | `string[]` |
+| `header` / `footer` | `ReactNode` |
+| `headerClassName` / `bodyClassName` / `footerClassName` / `scrollClassName` / `selectedClassName` / `heightClassName` | `string` |
+
+### Gallery
+```tsx
+<Gallery
+  records={records}
+  overlays={[{ position: 'topRight', badge: { variant: 'success', children: 'New' } }]}
+  columns={3}
+  gap={2}
+  sortable={{ field: 'name', dir: 'asc' }}
+  pagination={{ limit: 20 }}
+  onRowClick={(record) => {}}
+  onSelectionChange={(sel) => {}}
+  header="Titolo"
+  groupBy="status"
+/>
+```
+
+`position`: `'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'middleLeft' | 'middleRight'`
+
+| Prop | Tipo |
+|---|---|
+| `records` | `GalleryRecord[]` (`{ img?, thumbnail?, name?, width?, height? }`) |
+| `columns` | `1 \| 2 \| 3 \| 4 \| 6` |
+| `gap` | `0 \| 1 \| 2 \| 3 \| 4 \| 5` |
+| `overlays` | `GalleryOverlay[]` |
+| `sortable` | `boolean \| OrderConfig` |
+| `pagination` | `PaginationParams` |
+| `onRowClick` | `(record) => void` |
+| `onSelectionChange` | `(selection) => void` |
+| `groupBy` | `string \| string[]` |
+| `selectedKeys` | `string[]` |
+| `header` / `footer` | `ReactNode` |
+| Classi CSS: `headerClassName`, `bodyClassName`, `footerClassName`, `scrollClassName`, `selectedClassName` | `string` |
+
+### Tab
+```tsx
+import { Tab, TabItem } from '@llmnative/react'
+
+<Tab defaultIndex={0} layout="top">
+  <TabItem label="Generale">{content1}</TabItem>
+  <TabItem label="SEO">{content2}</TabItem>
+</Tab>
+```
+`layout`: `'default' | 'top' | 'left' | 'right' | 'bottom'`
+Le schede sono `<TabItem>`, export separato: `Tab.Item` non esiste.
+
+### Image
+```tsx
+<Image src="..." fit="cover" position="center" width={400} height={300} />
+```
+`fit`: `'cover' | 'contain' | 'fill' | 'scale-down' | 'none'`
+
+### Pagination (standalone)
+```tsx
+<Pagination records={items} limit={20}>
+  {(pageRecords, offset) => pageRecords.map(r => <Row key={r._key} record={r} />)}
+</Pagination>
+```
+
+### Percentage
+```tsx
+<Percentage value={75} appearance="bar" variant="success" showText />
+<Percentage value={0.75} appearance="circle" size={60} />
+```
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `value` | `number` | — |
+| `max` | `number` | `100` |
+| `min` | `number` | — |
+| `appearance` | `'bar' \| 'circle'` | `'bar'` |
+| `variant` | `ColorType` | — |
+| `trackVariant` | `ColorType` | — |
+| `thickness` | `number` | — (px) |
+| `showText` | `boolean` | — |
+| `size` | `number` | Diametro in modalità `'circle'` (px) |
+| `fontSize` | `number` | — |
+| `label` | `string` | — |
+
+### DescriptionList
+Coppie etichetta → valore in sola lettura (profilo, dati di un record, riepiloghi), rese come `<dl>`/`<dt>`/`<dd>`. Da usare al posto di markup `<dl>` scritto a mano; per dati modificabili usare i campi di `<Form>`, per molti record `<Table>`/`<Grid>`.
+```tsx
+<DescriptionList items={[{ label: 'Email', value: 'a@b.it' }, { label: 'Telefono', value: null }]} />
+<DescriptionList layout="stacked" columns={4} truncate items={[{ label: 'Stato', value: <Badge variant="success">Spedito</Badge> }]} />
+```
+
+| Prop | Tipo | Default |
+|---|---|---|
+| `items` | `DescriptionListItem[]` — `{ key?, label, value?, title? }` | — |
+| `layout` | `'horizontal' \| 'stacked'` | `'horizontal'` (etichette a sinistra, impilate su mobile) |
+| `columns` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` (solo `stacked`, dal breakpoint `lg`) |
+| `labelWidth` | `string` (lunghezza CSS) | `'12rem'` (solo `horizontal`) |
+| `emptyValue` | `ReactNode` | `'—'` per `null` / `undefined` / `''` (lo `0` resta) |
+| `truncate` | `boolean` | `false`; un valore testuale diventa il suo `title` |
+| Classi | `wrapperClassName`, `className`, `itemClassName`, `labelClassName`, `valueClassName` | tema `DescriptionList` |
+
+### Tree
+Albero accessibile di nodi (cartelle e file, gerarchie): pattern WAI-ARIA tree, un solo tab stop, frecce per muoversi, → / ← per aprire e chiudere, Invio o Spazio per selezionare. Le cartelle si aprono al click, le foglie si selezionano.
+```tsx
+<Tree nodes={treeFromPaths(paths)} defaultExpanded selectedId={path} onSelect={(node) => setPath(node.id)} ariaLabel="File" />
+<Tree nodes={[{ id: 'a', label: 'Docs', children: [{ id: 'a/1', label: 'README.md', badge: <Badge>new</Badge> }] }]} />
+```
+| Prop | Tipo | Note |
+|---|---|---|
+| `nodes` | `TreeNode[]` — `{ id, label, icon?, badge?, description?, children?, disabled? }` | `id` unico; con `children` è una cartella |
+| `selectedId` + `onSelect` / `defaultSelectedId` | `string \| null` | selezione controllata o no |
+| `expanded` + `onExpandedChange` / `defaultExpanded` | `string[]`; `defaultExpanded` anche `true` (tutto aperto) | apertura controllata o no |
+| `selectableBranches` | `boolean` (default `false`) | anche le cartelle si selezionano |
+| `ariaLabel` | `string` | nome accessibile |
+| Classi | `wrapperClassName`, `className`, `itemClassName`, `selectedClassName` | tema `Tree` |
+
+`treeFromPaths(paths, leaf?)` costruisce l'albero da percorsi `a/b/c`: cartelle prima dei file, ordinati; l'id di un file è il percorso, quello di una cartella `percorso/`; `leaf(path)` decora le foglie (label, icona, descrizione…).
+
+### Dropdown
+```tsx
+<Dropdown trigger={<Icon name="menu" />} position="end">
+  <DropdownItem label="Modifica" icon="edit" onClick={() => {}} />
+  <DropdownItem label="Elimina" icon="trash" variant="danger" />
+  <DropdownDivider />
+  <DropdownHeader label="Azioni rapide" />
+</Dropdown>
+```
+
+Azioni secondarie di una voce (CR-107): `actions` mostra icone in fondo alla riga, al passaggio
+del mouse o al focus (sempre sui dispositivi touch). Non selezionano la voce e lasciano il menu aperto
+salvo `closeOnClick`.
+
+```tsx
+<DropdownItem icon="messages-square" onClick={() => open(chat)}
+  actions={[{ icon: 'archive', label: 'Archivia', onClick: () => archive(chat) }]}>
+  {chat.title}
+</DropdownItem>
+```
+
+Per elenchi caricati dinamicamente usare `AsyncDropdown`: gestisce ricerca con debounce,
+cancellazione delle richieste precedenti tramite `AbortSignal` e stati loading/empty/error.
+
+```tsx
+<AsyncDropdown
+  trigger={<ActionButton label="Select user" />}
+  loadItems={(query, signal) => users.search(query, { signal })}
+  getItemId={user => user.id}
+  renderItem={user => user.name}
+  onSelect={user => setUser(user)}
+  selectedId={user?.id}
+/>
+```
+
+### ContextMenu
+```tsx
+<ContextMenu trigger="/" searchable>
+  <ContextMenu.Heading>Comandi</ContextMenu.Heading>
+  <ContextMenu.Item label="Titolo" value="# " icon="heading" />
+  <ContextMenu.Separator />
+  <ContextMenu.Item label="Bold" value="**bold**" icon="bold" />
+</ContextMenu>
+```
+Funziona su qualsiasi `<textarea>` / `<input>` figlio. Trigger custom (`/`, `@`, `{`), filtro searchable, navigazione tastiera, floating positioning.
+`ContextMenu.Item` accetta `description` (opzionale): seconda riga attenuata (`text-muted-foreground`)
+sotto la label, troncata; il menu è largo al massimo 28rem e il testo completo resta nel `title`
+della voce. Il filtro cerca nel testo digitato dopo il trigger su label, value e description (CR-111).
+
+```tsx
+<ContextMenu.Item label="/plan" value="plan" icon="list" description="Scrive il piano della release" />
+```
+
+| Prop | Tipo | Note |
+|---|---|---|
+| `trigger` | `string` (required) | Es. `"/"`, `"@"`, `"{"` |
+| `searchable` | `boolean` | Filtro testuale |
+| `controlled` | `ContextMenuControlledState` | Stato controllato esterno |
+| `onSelect` | `(item, context) => void` | |
+
+**EditorCommand** (usato da `commands` prop su `Chatbot`, `Prompt`, `RichText`, `CodeEditor`):
+```ts
+{
+  name: string;
+  description?: string;
+  icon?: string;
+  group?: string;
+  consumeSuffix?: string;
+  handler?: (context: TextCommandContext) => string | Promise<string>;
+}
+```
+
+`description` compare sotto `/name` nel menu dei comandi di tutti e quattro i consumer e il filtro
+la usa (digitare `/release` trova un comando descritto come "…release…"). Un comando senza `handler`
+sostituisce il trigger con `/name ` (spazio finale) e il testo resta tale: in `Chatbot`/`Prompt` il
+messaggio inviato è letteralmente `"/name …"`, da interpretare a cura di chi lo riceve.
+
+`consumeSuffix` elimina una chiusura automatica adiacente durante la sostituzione del trigger,
+utile quando un comando cambia famiglia sintattica (per esempio da `{{ ... }}` a `{% ... %}`).
+
+### Altre primitive
+```tsx
+<Icon name="user" size={20} />           // usa provider icone configurato
+<ImageAvatar src="..." title="Mario" alt="Mario" width={40} height={40} />
+<Identicon value="acme/app" size={32} title="acme/app" />   // icona generata dal valore, stile GitHub
+<Loader show={isLoading}>{content}</Loader> // indicatore al posto dei figli finché show è true
+<Loader show>{null}</Loader>             // solo indicatore (es. pagina in caricamento)
+<Code language="tsx">{snippet}</Code>   // syntax highlight
+<GridSystem.Row><GridSystem.Col xs={12} md={6}>...</GridSystem.Col></GridSystem.Row>
+<LocaleSwitcher locales={[{ code: 'it', label: 'Italiano' }]} />
+<ThemeSwitcher />
+<ProviderSwitcher />
+<LayoutBuilder components={...} />
+```
+
+### Charts (CR-112)
+Grafici SVG senza dipendenze, dal modulo `charts`. Colori come token del tema: `color` è uno slot della
+palette categoriale (`1…8` → `--rf-chart-N`, definiti in `globals.css` con la variante scura e
+sovrascrivibili dal consumer) o un token (`'--rf-success'`); le serie senza colore prendono lo slot
+della loro posizione. Larghezza dal contenitore (ResizeObserver), animazioni spente con
+`prefers-reduced-motion`, tooltip che segue il puntatore e la tastiera (le aree prendono il focus
+finché sono al massimo 40), tabella dei dati `sr-only` con `ariaLabel` come didascalia, stato vuoto
+`charts.noData`. `format` è facoltativo: di default il numero nella locale dell'app.
+
+```tsx
+<ColumnChart ariaLabel="CR chiuse al giorno" columns={[{ label: 'lun', value: 4 }]} markers={[{ position: 3.5, label: 'mediana', dashed: true }]} onColumnClick={(column) => {}} />
+<StackedColumnChart ariaLabel="Ore per agente" labels={days} labelEvery={2} format={(v) => `${v} h`}
+  series={[{ id: 'dev', label: 'Developer', values: dev }, { id: 'qa', label: 'Tester', values: qa, color: 3 }]}
+  comparison={previousTotals} comparisonLabel="periodo precedente" />
+<MeasureBarList ariaLabel="Agenti"   // CR-115: barre raggruppate, ogni agente una volta, una barra per misura (colore in legenda), ognuna sulla sua scala
+  columns={[{ id: 'time', label: 'Ore', format: (v) => `${v} h` }, { id: 'cost', label: 'Costo' },
+    { id: 'tokens', label: 'Token', parts: [{ id: 'in', label: 'Input' }, { id: 'out', label: 'Output' }] }]}   // parts: la barra divisa in proporzione
+  rows={[{ id: 'dev', label: 'Developer', values: { time: 18, cost: 4.27, tokens: [2400000, 190000] }, trailing: { text: '18 back', tone: 'bad' } }]} />
+<SequenceColumnChart ariaLabel="Turni per CR" format={(v) => `${v} min`}   // CR-114: ogni colonna nel suo ordine, una serie può tornare
+  series={[{ id: 'dev', label: 'Developer' }, { id: 'rev', label: 'Reviewer' }]}
+  columns={[{ label: '#34', title: 'CR #34', segments: [{ series: 'dev', value: 18 }, { series: 'rev', value: 6 }, { series: 'dev', value: 11 }] }]}
+  onColumnClick={(column) => {}} />
+<LineChart ariaLabel="Lead time" labels={days} threshold={{ value: 6.5, label: 'obiettivo' }} baseline={0} domain={[0, 10]}
+  series={[{ id: 'now', label: 'Ora', values: [3, null, 5], area: true, band: { min, max } }, { id: 'before', label: 'Prima', values: prev, dashed: true }]} />
+<AreaChart ariaLabel="Flusso cumulativo" labels={days} stacked series={[{ id: 'closed', label: 'Chiuse', values: closed }]} />
+<ScatterChart ariaLabel="Costo contro rework" xLabel="Costo" yLabel="Rework" sizeLabel="Turni"
+  series={[{ id: 'sonnet', label: 'Sonnet' }]} points={[{ id: '1', label: 'Developer', x: 0.04, y: 0.3, size: 30, series: 'sonnet' }]} onPointClick={(point) => {}} />
+<DivergingBarChart ariaLabel="Valore e costo" upLabel="Valore" downLabel="Costo" bars={[{ label: 'lun', up: 120, down: null }]} />
+<BarList ariaLabel="Costo per agente" rows={[{ id: 'dev', label: 'Developer', value: 1.84, trailing: { text: '+12%', tone: 'bad' } }]} />
+<Heatmap ariaLabel="Turni per ora" rowLabels={agents} columnLabels={hours} columnLabelEvery={2} values={matrix} />
+<CalendarHeatmap ariaLabel="Turni per giorno" days={[{ date: '2026-11-02', value: 4 }, { date: '2026-11-03', value: null }]} />
+<Sparkline values={[1, 3, null, 2]} ariaLabel="Andamento" />   // senza ariaLabel è decorativa
+<AnimatedNumber value={3.85} format={(v) => `$${v.toFixed(2)}`} />
+```
+
+Parti comuni per grafici propri: `useChartTooltip()` (`show`, `showAt`, `hide`, `element`), `ChartLegend`,
+`ChartDataTable`, `useChartWidth(fallback)`, `useAnimatedValues(values)`, `useReveal(key)`,
+`useChartFormat(format?)`, `chartToken(color)`, `chartFill(token, alpha?)`, `niceMax`, `ticks`.
+
+---
+
+## Blocks
+
+```tsx
+// Senza trail: dall'indirizzo, ogni pezzo col titolo della sua rotta nel menu ('/impostazioni' → 'Impostazioni'),
+// altrimenti leggibile ('lead-fermi' → 'Lead fermi'); un id resta com'è.
+<Breadcrumbs />
+<Breadcrumbs trail={[{ label: 'Home', href: '/' }, { label: 'Utenti' }]} separator="/" jsonLd />
+<Brand url="/" label="MyApp" logo="/logo.svg" width={120} />
+<Search onQueryChange={(e) => setQ(e.target.value)} />
+<Notifications items={[...]} seeAllUrl="/notifications" onMarkAllRead={() => {}} onItemClick={(item) => markRead(item.id)} />
+<Notifications items={[{ id: 'a', title: 'Fonte senza Action', description: 'crm · sources/notes/a.md', url: '/projects/crm', time: 'ora', icon: 'file', actions: [{ label: "Apri l'Action", icon: 'play', onClick: openAction, variant: 'primary' }] }]} />
+<Carousel images={[...]} />
+<Toolbar items={[...]}>
+  {children}
+</Toolbar>
+<SideNav />
+<ListCard records={records} onRowClick={(r) => {}} />
+```
+
+**Brand:**
+| Prop | Tipo |
+|---|---|
+| `url` | `string` |
+| `label` | `string` |
+| `logo` | `string` |
+| `width` / `height` | `number` |
+| `wrapperClassName` / `className` / `logoClassName` / `labelClassName` | `string` |
+
+**SideNav:**
+| Prop | Tipo |
+|---|---|
+| `items` | `SideNavItemDef[]` (in alternativa a `menuKey`) |
+| `menuKey` | `string` — voci dal menu registrato in `<App>` |
+| `bottomItems` | `SideNavItemDef[]` — voci fissate in fondo, sopra il footer e fuori dalla lista scorrevole (es. Impostazioni) |
+| `header` / `footer` | `ReactNode` |
+| `collapsed` + `onCollapsedChange` / `defaultCollapsed` | `boolean` — compressione controllata o no |
+| `showIcons` / `showCollapseButton` | `boolean` (default `true`) |
+| `embedded` | `boolean` — solo le voci, senza guscio (drawer, pannelli); `bottomItems` seguono le voci principali |
+
+`SideNavItemDef`: `{ path, title?, icon?, group?, end?, badge?, children? }`. La voce attiva ha
+`aria-current="page"`.
+
+```tsx
+<SideNav
+  items={[{ path: '/dashboard', title: 'Dashboard', icon: 'home' }]}
+  bottomItems={[{ path: '/settings', title: 'Impostazioni', icon: 'settings' }]}
+/>
+```
+
+**ImageAvatar:**
+| Prop | Tipo |
+|---|---|
+| `src` | `string` (obbligatoria) |
+| `width` / `height` | `number` |
+| `title` / `alt` | `string` |
+| `fit` | `AvatarFit` |
+| `badge` | `BadgeDescriptor` |
+| `feedback` | `ReactNode` |
+
+**Identicon:** l'icona di un'entità senza immagine (repository, tenant, utente senza foto), come quelle di
+GitHub: griglia 5×5 simmetrica, celle e tinta da un hash di `value`. Lo stesso valore dà sempre la stessa
+icona; niente rete né storage. Default: `rounded-md bg-muted` (tema `Identicon.className`).
+`identiconPattern(value)` restituisce celle e tinta, per chi la disegna altrove.
+| Prop | Tipo |
+|---|---|
+| `value` | `string` (obbligatoria) |
+| `size` | `number` (px, default 40) |
+| `title` | `string`: nome accessibile (`role="img"`); senza, `aria-hidden` |
+| `before` / `after` / `className` / `wrapperClassName` | come le altre primitive |
+
+**Search:**
+| Prop | Tipo |
+|---|---|
+| `onQueryChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` |
+
+**Notifications:**
+| Prop | Tipo |
+|---|---|
+| `items` | `NotificationItem[]` |
+| `badge` | `BadgeProps` |
+| `seeAllUrl` | `string` |
+| `onMarkAllRead` | `() => void` |
+| `onItemClick` | `(item, index) => void` — una voce aperta (es. per segnarla letta); il menu si chiude |
+| `motion` | `MotionReference` |
+
+`NotificationItem`: `{ id?, title, description?, url?, external?, time, icon, read?, actions? }`. `description` è la
+riga sotto il titolo; senza `url` la voce si mostra e basta; con `external` l'`url` è un indirizzo aperto
+in una nuova scheda (`<a target="_blank">`), altrimenti una rotta (`Link`). `actions`
+(`NotificationAction[]`: `{ label, icon?, onClick, variant?: 'primary' | 'default', closeOnClick? }`) sono
+pulsanti sotto la voce: non la aprono, mostrano il caricamento finché la promessa di `onClick` è in corso
+e lasciano il menu aperto salvo `closeOnClick`.
+
+**ListCard:**
+| Prop | Tipo |
+|---|---|
+| `title` / `description` / `meta` | `ReactNode` |
+| `badge` | `ReactNode` |
+| `icon` | `string \| ReactNode` |
+| `trailing` / `footer` / `children` | `ReactNode` |
+| `href` | `string` |
+| `external` / `active` / `disabled` / `dashed` / `compact` | `boolean` |
+| `align` | `'start' \| 'center'` |
+| `onClick` | `(e) => void` |
+| Classi CSS: `titleClassName`, `descriptionClassName`, `metaClassName`, `badgeClassName`, `leadingClassName`, `bodyClassName`, `headerClassName`, `trailingClassName`, `footerClassName` | `string` |
+
+**SortableList (CR-120):** card compatte (ListCard) in un ordine che la persona sceglie: le trascina per la
+maniglia, o con le frecce su/giù sulla maniglia; l'annuncio della nuova posizione va agli screen reader.
+```tsx
+<SortableList
+  items={accounts}
+  getKey={(a) => a.id}
+  label="Account"
+  numbered
+  onReorder={(next, { fromIndex, toIndex, item }) => setAccounts(next)}
+  renderItem={(a) => ({ title: a.email, meta: a.added, badge: <Badge variant="success">Disponibile</Badge>, trailing: <ActionButton icon="trash-2" … /> })}
+  emptyState={<p>Nessun account</p>}
+/>
+moveItem(['a', 'b', 'c'], 0, 2)   // ['b', 'c', 'a']
+```
+| Prop | Tipo |
+|---|---|
+| `items` / `getKey` | `TItem[]` / `(item) => string` |
+| `renderItem` | `(item, index) => SortableListCard` (`title`, `description`, `meta`, `badge`, `icon`, `trailing`, `active`, `disabled` di ListCard) |
+| `onReorder` | `(items, { fromIndex, toIndex, item }) => void`; senza, nessuna maniglia |
+| `label` / `numbered` / `disabled` / `emptyState` | `string` / `boolean` / `boolean` / `ReactNode` |
+| Classi CSS: `className`, `itemClassName`, `cardClassName` | `string` |
+
+**Dropdown:**
+| Prop | Tipo |
+|---|---|
+| `trigger` | `string \| ReactNode \| DropdownTogglerProps` |
+| `badge` | `BadgeProps` |
+| `header` / `footer` | `ReactNode` |
+| `defaultOpen` / `open` | `boolean` |
+| `onOpenChange` | `(open) => void` |
+| `position` | `'start' \| 'end'` |
+| `placement` | `'auto' \| 'top' \| 'bottom'` |
+| `strategy` | `'fixed' \| 'absolute'` |
+
+// Menu — renderizza una sezione del menuConfig passato ad <App>
+<Menu menuKey="main" />            // 'main' o qualsiasi chiave definita in MenuConfig
+<Menu menuKey="topbar" className="nav flex-row gap-2" />
+// NON usare context= — la prop si chiama menuKey
+
+// AuthButton — login/logout con il provider auth configurato
+<AuthButton />
+```
+
+---
+
+## Widgets
+
+### MarkdownReader
+```tsx
+<MarkdownReader
+  content={markdownString}
+  onInternalLinkClick={(href, e) => { e.preventDefault(); navigate(href) }}
+  wrapperClassName="prose"
+/>
+```
+
+### Messaggi di chat: ChatMarkdown, ChatReasoning, ChatQuestions (CR-109), ChatActivity (CR-123)
+
+Parti di un messaggio di un modello, da comporre nel proprio thread (anche accanto a `Chatbot`).
+
+```tsx
+// Markdown GFM del messaggio: tabelle (scorrono dentro di sé in un pannello stretto), elenchi,
+// titoli, citazioni, task list, codice con evidenziazione (Prism, lazy) e pulsante Copia, link a
+// indirizzi in una nuova scheda (noopener). Sanitizzato: niente HTML grezzo, niente javascript:.
+// streaming: chiude ciò che la fine del testo lascia aperto (fence, intestazione di tabella,
+// **grassetto**, `codice`, link) così il layout non salta mentre arriva. Off per un messaggio finito.
+<ChatMarkdown content={text} streaming={running} onLinkClick={(href) => navigate(href)} />
+// tone="muted", highlight={false}, components (come react-markdown), className,
+// classNames={{ root, paragraph, heading, list, blockquote, tableWrapper, table, th, td, codeBlock, codeHeader, code, inlineCode, link }}
+// repairStreamingMarkdown(text) è la stessa riparazione, pura.
+
+// Ragionamento: chiuso dietro "Ragionamento" / "Ha ragionato per 12 s"; aperto mentre arriva
+// (se l'utente non lo chiude) e richiuso alla fine. Contenuto con ChatMarkdown, tono attenuato.
+<ChatReasoning content={reasoning} streaming={thinking} duration={12} />
+// defaultOpen, open + onOpenChange (controllato), label, icon ('brain'), className, classNames={{ root, trigger, content }}
+
+// Domande interattive (formato dello strumento `question` di opencode / elicitation MCP):
+<ChatQuestions
+  questions={[
+    { id: 'db', header: 'Database', question: 'Quale database?', recommended: 0,
+      options: [{ label: 'Postgres', description: 'Relazionale' }, { label: 'SQLite' }] },
+    { id: 'features', header: 'Funzioni', question: 'Quali funzioni?', multiple: true,
+      options: [{ label: 'Auth' }, { label: 'Ricerca' }] },
+  ]}
+  onSubmit={async (answers) => send(answers)}   // [{ id, header, values: string[] }] in ordine
+/>
+// Una scheda per domanda (header) + Riepilogo e un solo Invia; opzioni numerate 1-2-3 o A-B-C
+// (numbering, altrimenti dedotto da etichette "A) …" / "1. …", che vengono tolte); consigliata
+// (recommended: indice da 0 o etichetta; anche il suffisso "(Recommended)"); multiple; "Altro" con
+// testo libero (allowOther, default true; per domanda `custom`); senza options è a testo libero.
+// Il testo libero è una textarea (CR-110) di 2 righe che cresce col testo fino a ~160px e poi
+// scorre; ridimensionabile in verticale. Lì Invio va a capo, Ctrl/Cmd+Invio prosegue o invia
+// (suggerimento `chat.textKeyboardHint` nel piè mentre si scrive).
+// Tastiera: numeri (o lettere con A-B-C) scelgono, frecce sinistra/destra tra le schede, su/giù tra
+// le opzioni, Spazio seleziona, Invio prosegue o invia (su una scelta singola prima la sceglie;
+// nel testo libero serve Ctrl/Cmd+Invio).
+// Ruoli tablist/tab/tabpanel, radiogroup/radio o group/checkbox.
+// Scelta singola: il click sceglie e passa alla domanda dopo. onSubmit che rifiuta lascia il form.
+// answers={[…]} mostra un insieme già risposto (sola lettura); disabled, autoFocus, submitLabel,
+// classNames={{ root, tabs, tab, panel, question, option, optionSelected, footer, summary }}
+
+// Il lavoro di un agente (CR-123), come negli assistenti AI: gruppi di passi (icona, label, quanti,
+// dettagli brevi: query, file, comandi; quanti falliti) con le righe sotto aperte da "Comandi";
+// le parole dell'agente in Markdown; come è finito; i file cambiati con "Vedi le modifiche";
+// il registro grezzo a un clic. Il consumer traduce il suo log negli item.
+<ChatActivity
+  items={[
+    { type: 'steps', icon: 'search', label: 'Esplora il repository', count: 3, detail: ['git status'], lines: ['git status --short'] },
+    { type: 'text', text: 'Aggiungo il comando e il suo test.' },
+    { type: 'end', ok: true, text: 'success · 9 steps' },
+  ]}
+  files={['functions/src/catalog/index.js']} onShowChanges={() => openDiff()} log={rawLines}
+/>
+// className, classNames={{ root, step, text, files, log }}
+```
+
+### ImageEditor
+```tsx
+<ImageEditor src="..." onSave={(dataUrl) => save(dataUrl)} />
+```
+
+`ImageEditor` e un singolo componente pubblico. La libreria pesante `tui-image-editor` viene importata lazy a runtime dentro il componente, quindi non viene scaricata finche l'editor non viene effettivamente montato.
+
+### TabDynamic
+Tab con lazy loading dei contenuti — gestione dinamica aggiunta/rimozione tab.
+
+---
+
+## AI Integration
+
+```ts
+import { useAIProvider, getAIModelCatalog, createAIProviderRegistry } from '@llmnative/react'
+
+// Hooks
+const provider  = useAIProvider()           // provider di default
+const registry  = useAIProviderRegistry()   // tutti i provider AI registrati
+const catalog   = getAIModelCatalog()       // modelli disponibili
+// ogni modello: { id, provider, model, label, pricing? } — pricing in USD per 1M token
+// { input, output, currency: 'USD', source: 'provider' | 'models.dev' }; assente = prezzo
+// non trovato (il modello resta in lista). isFreeAIModel(m) → input e output a 0.
+// Il model picker di Prompt/Chatbot mostra "$in / $out", evidenzia i free, segnala i mancanti,
+// e raggruppa per provider (ChatbotModelOption.group = providerLabel) con header sticky.
+// CR-121: il pulsante mostra la `label` del modello scelto (non il suo valore); `groupBadge: { label, variant? }`
+// su un'opzione mette un Badge a destra nell'header del suo gruppo (es. Abbonamento / A consumo).
+
+// Provider adapter restituito da useAIProvider()
+const text  = await provider.fetch("Scrivi un titolo per: {keyword}", { keyword: "React" })
+const json  = await provider.json("Lista di 5 categorie per blog tech")
+const arr   = await provider.array("5 tag per: machine learning")
+
+// Provider custom
+class MyAIProvider implements AIProviderAdapter {
+  async fetch(prompt: string, options?: AIRequestOptions): Promise<string> { ... }
+  async json<T>(prompt: string, options?: AIRequestOptions): Promise<T> { ... }
+  async array(prompt: string, options?: AIRequestOptions): Promise<string[]> { ... }
+}
+
+// Quanto ragiona il modello (CR-122): `reasoning: 'low' | 'medium' | 'high' | 'max'` (AIReasoningLevel) su
+// una richiesta. Anthropic: `output_config.effort` sui Claude 4.6 e successivi (+ thinking adaptive su Opus
+// 4.6-4.8 e Sonnet 4.6); OpenAI e compatibili (OpenCode, DeepSeek, Groq…): `reasoning_effort` solo sui modelli
+// di ragionamento di OpenAI (serie o, GPT-5; max = high); OpenRouter: `reasoning.effort` su ogni modello.
+// Altrove (modelli più vecchi, Gemini) non si manda nulla: il default del modello.
+await ai.complete({ prompt: 'Rivedi questo piano', model: 'claude-opus-5-5', reasoning: 'high' })
+
+// Factory per registri esterni
+const registry = createAIProviderRegistry(definitions)
+// Azioni di Chatbot (CR-107): con `content` aprono un menu; senza, sono pulsanti con `onClick`.
+// <Chatbot actions={[{ key: 'finish', icon: 'git-pull-request', label: 'Concludi', showLabel: true,
+//   disabled: running, onClick: finish }]} … />
+// Allegati di Chatbot (`attachments`): file scelti, trascinati o incollati con Ctrl+V (uno screenshot diventa
+// `pasted-<data>.png`, CR-124); il testo incollato resta testo. Arrivano in `onSubmit` come `files`.
+// Comandi "/" di Chatbot: `commands` (EditorCommand[]) + `commandsTrigger` (default "/").
+// Il menu mostra `/name` e sotto la `description`; il filtro cerca in entrambi (CR-111).
+// Senza `handler` la scelta inserisce "/name " e l'invio manda il testo così com'è.
+// Tastiera: Invio invia a menu chiuso e sceglie il comando evidenziato a menu aperto;
+// Maiusc+Invio (e Invio durante la composizione IME) va a capo.
+// <Chatbot commands={[{ name: 'plan', icon: 'list', description: 'Scrive il piano' }]} … />
+```
+
+### Identità dei modelli indipendente dal provider (CR-103)
+
+```ts
+const index = await loadModelIdentityIndex()          // models.dev, un fetch per sessione
+canonicalModelName('DeepSeek V4.1 Flash (Alibaba Cloud)')   // 'deepseek v4.1 flash'
+index.models['deepseek v4.1 flash']                   // { key, name, family?, providers: { openrouter: [{ id, name }], … } }
+resolveModel(index, 'DeepSeek V4.1 Flash', ['openrouter', 'deepseek'])
+// → { provider: 'openrouter', model: 'deepseek/deepseek-v4.1-flash', ref: 'openrouter/deepseek/deepseek-v4.1-flash' }
+modelOffers(index, 'DeepSeek V4.1 Flash', ['openrouter', 'deepseek'])   // CR-119: tutti quelli che lo servono
+// → [{ provider: 'openrouter', model, ref, cost: { input: 0.15, output: 0.3 } }, { provider: 'deepseek', … }]
+//   senza `providers`: tutto il catalogo, per chiave del provider. `cost` in USD per 1M token, assente se models.dev non lo dà
+```
+
+Il nome canonico toglie data, Free, Latest e host o regione tra parentesi; una modalità
+("(Thinking)", "(Reasoning)", "(Fast)") resta. Per ogni provider l'id preferito è quello stabile (non
+alias `~`, non free tier, non datato). I provider sono le chiavi di models.dev, le stesse di opencode.
+Puro: anche da `@llmnative/react/server`.
+
+### Chiavi tenute dal server (CR-102)
+
+Per un'app che non mette mai le chiavi dei provider nel browser. Il browser conosce solo quali
+provider sono collegati; il proxy dell'app mette la chiave.
+
+```ts
+// Browser: gli stessi adapter, con un segnaposto dove andrebbe la chiave. Serve il proxy attivo.
+const registry = createServerCredentialAIRegistry(
+  [{ id: 'anthropic' }, { id: 'cloudflare', accountId }, { id: 'openai-compatible', baseUrl }],
+  { scope: companyId },   // lettere, cifre, - e _
+)
+Object.entries(registry).forEach(([id, adapter]) => setProvider('ai', id, adapter))
+
+// Server (Node, nessuna dipendenza da React): nel proxy, prima di inoltrare.
+import { resolveServerCredentials } from '@llmnative/react/server'
+const resolved = await resolveServerCredentials({ url: target, headers },
+  (scope, provider) => keysOf(scope)[provider])   // { id, apiKey, accountId?, baseUrl? } | undefined
+if (!resolved.ok) return reply(resolved.status, resolved.error)   // 404 non collegato, 403 host estraneo
+await fetch(resolved.url, { headers: resolved.headers, ... })
+```
+
+La chiave va solo agli host del provider (`AI_PROVIDER_HOSTS`, il `baseUrl` di openai-compatible,
+l'account di Cloudflare): una destinazione diversa è rifiutata. `createProxyPlugin(route, log,
+lookup)` fa lo stesso nel proxy di sviluppo di Vite. Senza proxy, `proxyFetch` rifiuta di inviare
+un segnaposto. `createAIProviderRegistry` (chiavi nel browser) resta com'è.
+
+Configurazione API key in `Config.tsx`: `geminiApiKey`, `openaiApiKey`, `anthropicApiKey`, `deepSeekApiKey`, `mistralApiKey`, `openRouterApiKey`, `groqApiKey`, `cloudflare: { apiToken, accountId }` (Cloudflare Workers AI: l'account id fa parte dell'URL; discovery via `ai/models/search`, modelli Workers Paid esclusi salvo `includePaidModels`).
+
+---
+
+## Theme e icone
+
+```tsx
+const theme = useThemeController()
+theme.applyTheme('flat')     // BuiltInThemeId ('default' | 'flat' | 'cyber' | 'vscode-dark-modern' | …) | custom
+theme.setMode('dark')        // 'light' | 'dark' | 'system'
+
+const icons = useIconController()
+icons.setProvider('phosphor')   // 'lucide' | 'phosphor' | custom
+```
+
+---
+
+## Head (SEO)
+
+```ts
+useHead({
+  title: 'Pagina',
+  description: '...',
+  robots: 'noindex',
+  canonical: 'https://...',
+  og: { title: '...', image: '...' }
+})
+```
+
+---
+
+## Global state (localStorage)
+
+```ts
+const vars = useGlobalVars()
+getGlobalVars('key')
+setGlobalVars({ key: 'value' })
+removeGlobalVars('key')
+```
+
+---
+
+## Hooks completi
+
+| Hook | Ritorna |
+|---|---|
+| `useDataProvider(name?)` | `DataProviderAdapter \| null` |
+| `useStorageProvider(name?)` | `StorageProviderAdapter \| null` |
+| `useAuthProvider(name?)` | `AuthProviderAdapter \| null` |
+| `useEmailSendProvider(name?)` | `EmailSendAdapter \| null` |
+| `useEmailReadProvider(name?)` | `EmailReadAdapter \| null` |
+| `useAIProvider(name?)` | `AIProviderAdapter \| null` |
+| `useAIProviderRegistry()` | `Record<string, AIProviderAdapter>` |
+| `useCredentialsProvider()` | `CredentialsAdapter \| null` |
+| `useTheme()` | `Theme \| undefined` |
+| `useThemeController()` | `ThemeController` |
+| `useIconController()` | `IconController` |
+| `useAccessToken(clientID, renew?)` | `boolean` | Ottiene token per servizio esterno (true = ok) |
+| `useGlobalVars()` | `Record<string, unknown>` |
+| `useHead()` | `HeadController` |
+| `useDocumentHead()` | `HeadController` |
+| `useAssetsHead(title?)` | `void` |
+| `useLanguageHead(lang?)` | `void` |
+| `useSocialHead(config)` | `void` |
+| `usePaginationHead(config)` | `void` |
+| `usePwaHead(config)` | `void` |
+| `useSchemaOrgHead(config)` | `void` |
+| `useHeadLinks(links)` | `void` |
+| `useProxy()` | `(url, init?) => Promise<Response>` |
+| `useImage()` | `UseImageResult` |
+| `useI18n()` | `I18nController` |
+| `useMenu()` | Menu hook |
+| `useFormController(controller?)` | `FormController` |
+| `useFormActions()` | `FormController` |
+| `useApiProvider(pathname?)` | `ApiProviderAdapter \| null` |
+| `useSetProvider(service, driver?)` | `void` |
+| `useProvider(name)` | `ProviderConfigurationState` |
+| `useProviderSession()` | `ProviderSession` |
+| `useDropBoxConnect(config?)` | `DropBoxConnectResult` |
+| `useEnterMotion(baseStyle?, ref?, fallback?)` | `CSSProperties` |
+| `useMotionState(active, ref?, fallback?, baseStyle?)` | `CSSProperties` |
+| `useMotionEffect(ref?, fallback?)` | `ResolvedMotionEffect` |
+| `usePressMotion(hovered, baseStyle?, ref?, fallback?)` | `{ style, pressHandlers }` |
+| `useIconProvider()` | `IconProvider` |
+
+---
+
+## Tipi chiave
+
+```ts
+type RecordProps  = Record<string, FieldValue>
+type FieldValue   = string | number | boolean | null | undefined | Record<string, unknown> | unknown[]
+type RecordArray  = RecordProps[]
+
+type OrderConfig  = { field: string; dir: 'asc' | 'desc' }
+type Condition    = { eq?, lt?, lte?, gt?, gte?, in?: list, nin?: list, contains?: scalar, containsAny?: list }
+type WhereClause  = { [field: string]: Condition | scalar | list }   // scalar = eq, list = in
+type OrderClause  = { [field: string]: 'asc' | 'desc' }
+class DataProviderError extends Error { code: 'permission-denied' | 'unauthenticated' | 'invalid-query' | 'unavailable' | 'unknown'; path?: string; cause?: unknown }
+
+interface UIProps {
+  before?: React.ReactNode
+  after?: React.ReactNode
+  wrapperClassName?: string
+  className?: string
+}
+
+type UserProfile = { uid?: string; email?: string; displayName?: string; photoURL?: string; [key: string]: unknown }
+```
+
+---
+
+## Utilities
+
+```ts
+import { cn, converter, Sanitizer, Order, path, fetchJson, fetchRest, fetchWithRetry } from '@llmnative/react'
+import { getKeywordIdeas, getGoogleTrendsData, getGoogleTrendsRelated } from '@llmnative/react'
+
+cn('base', condition && 'extra', className)     // tailwind-merge classname
+new Sanitizer().sanitize(html)                  // XSS sanitizer (non usare dangerouslySetInnerHTML)
+new Order().order(records, { field: 'name', dir: 'asc' })  // ordina record array
+fetchJson(url, init?)                           // fetch + JSON parse + error handling
+fetchRest(path, init?)                          // fetch REST con auth
+getKeywordIdeas(keyword)                        // Google Ads Keyword Ideas
+getGoogleTrendsData(keyword)                    // Google Trends interest over time
+getGoogleTrendsRelated(keyword)                 // Google Trends related queries
+```
+
+---
+
+## Scaffold (npx create)
+
+```bash
+npx @llmnative/react create
+npx @llmnative/react create --yes --provider=mock --template=admin
+```
+
+Flag disponibili: `--name` `--provider=firebase|supabase|mock|custom` `--ai-provider` `--icon-provider` `--theme` `--template=blank|admin|crm|inventory|project`
+
+**5 template disponibili:**
+| Template | Pagine incluse | Uso tipico |
+|---|---|---|
+| `blank` | home | App vuota — massima libertà |
+| `admin` | home, users, roles, settings | Dashboard admin/backoffice |
+| `crm` | home, companies, contacts, deals | CRM |
+| `inventory` | home + gestione inventario | Magazzino |
+| `project` | home + gestione progetti | PM tool |
+
+**Struttura generata in-place nella current directory:**
+```
+src/
+  index.tsx          ← App entry
+  vite-env.d.ts
+  conf/
+    app.ts           ← providers config letta da .env (VITE_PROVIDER, VITE_AI_PROVIDER...)
+    menu.ts          ← MenuConfig con path, title, icon, page (layout opzionale: c'è LayoutDefault)
+    access.tsx       ← rotte pubbliche delle pagine di accesso (CR-127)
+  data/
+    mockData.ts      ← dati fake per MockDataProvider
+  layouts/
+    Default.tsx      ← layout wrapper (header + sidebar + main + footer)
+  sections/
+    Header.tsx / Sidebar.tsx / PageHeader.tsx / Footer.tsx   ← solo componenti pubblici (SideNav, AuthButton, ActionButton, Brand, Breadcrumbs)
+  pages/
+    home/HomePage.tsx
+    access/          ← SignInPage (il fallback del gate), SignUp, ForgotPassword, ResetPassword, VerifyEmail
+    [altre pagine dal template scelto]
+  styles/
+    globals.css      ← @import '@llmnative/react/dist/index.css' + Tailwind override
+.env                 ← VITE_PROVIDER, VITE_THEME, chiavi API (non committare)
+.env.example         ← stessa struttura, valori vuoti (committare)
+vite.config.ts / tsconfig.json / postcss.config.js / index.html
+```
+
+**Pattern conf/app.ts** (auto-generato, leggere per capire come funziona):
+```ts
+import type { AppProvidersConfig } from '@llmnative/react'
+import { mockData } from '../data/mockData'
+const env = import.meta.env
+
+export const providers: AppProvidersConfig = {
+  mock: { data: mockData },
+  ai: { openaiApiKey: env.VITE_OPENAI_API_KEY ?? '' },  // AI dentro providers, non prop <App>
+  mock: { data: mockData, auth: true },               // mockAuth: accesso di prova
+  services: { data: 'mock', auth: 'mockAuth' },
+}
+```
+
+Driver per `VITE_PROVIDER`: `firebase` → `firestoreDb` + `firestorage` + `firebaseAuth`; `supabase` → `supabaseDb` + `supabaseStorage` + `supabaseAuth`; `mock` → `mock` + `mockAuth`. `index.tsx` passa `LayoutDefault={Default}`, le traduzioni del framework (`translations: { ...locales }`) e `authGate={{ fallback: <SignInPage /> }}`: senza sessione ogni pagina mostra l'accesso al suo posto. Le pagine di accesso (`pages/access/`: SignInPage, SignUpPage, ForgotPasswordPage, ResetPasswordPage, VerifyEmailPage) e le loro rotte pubbliche (`conf/access.tsx`) sono uguali per ogni template; per un'app aperta a tutti togli `authGate`.
+
+---
+
+## Gotchas — pitfall frequenti
+
+| Errore | Causa | Fix |
+|---|---|---|
+| `aiConfig` prop non esiste su `<App>` | La config AI va dentro `providers.ai`, NON come prop separata | `providers={{ ai: { openaiApiKey } }}` |
+| `inputType` o `Input.Number`/`Input.Email` non esistono | Il tipo HTML è la prop `type` | `<Input type="number">`, `<Input type="email">`, `<Input type="date">` |
+| `Menu context=` non esiste | La prop si chiama `menuKey` | `<Menu menuKey="main" />` |
+| `SignInButton` non esiste | Rinominato | `<AuthButton />` |
+| Pagina `/login` con redirect, form di accesso fatti a mano | Le schermate e il gate ci sono (CR-127) | `<App authGate={{ fallback: <SignIn … /> }}>`, rotte aperte con `public: true` |
+| `firebase: { config: ... }` errato | FirebaseConfig è flat | `firebase: { apiKey, authDomain, databaseURL, ... }` |
+| `google: { oAuth2: { clientId } }` errato | GoogleProviderConfig è flat | `google: { clientId, scope }` |
+| `children` su `Grid` | Grid non accetta children | Usa `form={<Fields />}` per il form inline |
+| `recordId` su `Form` | Prop non esiste | La chiave del record viene da URL automaticamente |
+| `MenuConfig` non importabile | Era type interno | Ora esportato: `import type { MenuConfig } from '@llmnative/react'` |
+| `GridCellContext` non importabile | Mancava dall'index | Ora esportato: `import type { GridCellContext } from '@llmnative/react'` |
+
+---
+
+## Dove cercare nel codice sorgente
+
+| Cosa | File |
+|---|---|
+| Form | `src/components/widgets/Form.tsx` |
+| Grid | `src/components/widgets/Grid.tsx` |
+| Prompt | `src/components/widgets/Prompt.tsx` |
+| Campi form | `src/components/ui/fields/` |
+| Blocks (Menu, Toolbar, Notifications, Dropdown…) | `src/components/blocks/` |
+| Provider data Firebase (RTDB) | `src/providers/data/firebase.ts` |
+| Provider data Firestore | `src/providers/data/firestore.ts` |
+| Provider data Supabase | `src/providers/data/supabase.ts` |
+| Provider storage Firebase | `src/providers/storage/firebase.ts` |
+| Provider storage Supabase | `src/providers/storage/supabase.ts` |
+| Provider auth Firebase | `src/providers/auth/firebase/FirebaseAuthProvider.ts` |
+| Provider auth Supabase | `src/providers/auth/supabase/` |
+| Provider auth Google | `src/providers/auth/google/` |
+| Provider auth Dropbox | `src/providers/auth/dropbox/` |
+| Provider email (Resend, Brevo, Gmail, IMAP) | `src/providers/email/` |
+| Provider AI definitions | `src/providers/ai/` |
+| Provider credenziali | `src/providers/credentials/` |
+| Provider session | `src/providers/ProviderSession.ts` |
+| Proxy CORS | `src/providers/proxy.ts` |
+| Motion system | `src/motion.ts` |
+| I18n | `src/I18n.tsx` |
+| Dropbox integration | `src/providers/dropbox/` |
+| Interfaccia DataProvider | `src/providers/data/DataProvider.ts` |
+| Interfaccia StorageProvider | `src/providers/storage/StorageProvider.ts` |
+| Interfaccia AuthProvider | `src/providers/auth/AuthProvider.ts` |
+| Interfacce email | `src/providers/email/EmailSend.ts`, `src/providers/email/EmailRead.ts` |
+| Interfaccia AIProvider | `src/providers/ai/AIProvider.ts` |
+| Registry provider | `src/providers/manifest.ts` |
+| Config provider | `src/providers/ProviderConfiguration.ts` |
+| SEO / Google Trends | `src/providers/seo/google/` |
+| Sistema tema | `src/Theme.tsx` |
+| Config runtime | `src/Config.tsx` |
+| Tipi TypeScript | `src/types/` |
+| Utilities pure | `src/libs/` |