Le schede sono due pulsanti in fila. Il mod tiene traccia di quale sia attiva e disegna il contenuto di quella scheda sotto la fila.

{
"name": "hello-tabs",
"version": "0.1.0",
"description": "Opens a pane with two tabs and a counter",
"author": { "name": "Your Name" }
}

{
"modules": ["./register.js"]
}

// The pane's id, used to open the pane and to recognize it when drawing
const PANE = 'hello-tabs'

// What the pane shows: which tab is open, and the counter's value
let tab = 'one'
let count = 0

export function register(on) {
// Runs before your first prompt, and again after a reload
on('session.start', async ($, e, next) => {
await $.command.register({ name: 'hello-tabs', description: 'Open the hello-tabs pane' })
// Load the count an earlier session saved, if there is one
const saved = await $.store.get('count')
if (typeof saved === 'number') count = saved
return next(e)
})

// Runs when you type /hello-tabs
on('command.run', { command: 'hello-tabs' }, async ($) => {
// Open the pane, give it the keyboard, and let Esc close it
await $.ui.open({ id: PANE, title: 'Hello tabs', focus: true, closeOnEscape: true })
// Print nothing in the transcript
return {}
})

// Runs each time Claude Code draws a pane
on('ui.render', { component: 'Pane' }, async ($, e, next) => {
// Leave other mods' panes alone
if (e.requestId !== PANE) return next(e)
// Get the elements this app can draw
const { Box, Text, Button } = $.ui.resolve(e)
// Ask Claude Code to run this hook again
const redraw = () => $.ui.invalidate('ui.render')

// One tab: a button that switches to its tab when pressed
const tabButton = (name, label, hotkey) =>
Button({
key: 'tab-' + name,
label,
hotkey,
plain: true,
// Dim the tab that isn't open
dimColor: tab !== name,
onPress: () => {
tab = name
redraw()
},
})

// What goes under the tabs, depending on which one is open
const body =
tab === 'one'
? [Text({ children: ['This is the first tab.'] })]
: [
Box({
flexDirection: 'row',
columnGap: 2,
children: [
Button({
key: 'more',
label: 'Add one',
hotkey: 'a',
onPress: async () => {
count += 1
redraw()
// Save the count so it's there after a restart
await $.store.set('count', count)
},
}),
Text({ children: ['Count: ' + count] }),
],
}),
]

// The whole pane: the row of tabs, a blank line, then the body
return Box({
flexDirection: 'column',
children: [
Box({
flexDirection: 'row',
columnGap: 3,
children: [tabButton('one', 'One', '1'), tabButton('two', 'Two', '2')],
}),
Text({ children: [' '] }),
...body,
],
})
})
}

Scegli dove disegnare

Un hook ui.render viene eseguito per ogni punto di rendering, a meno che tu non lo limiti a quello in cui vuoi disegnare. Per scegliere il punto di rendering, passa un filtro, chiamato matcher, come secondo argomento di on. { component: 'Pane' } esegue l'hook solo per i pannelli. Nell'hook, e.component indica il punto, e.surface indica quale app sta disegnando e e.props contiene i dati propri del punto. Per un pannello, e.requestId è l'id con cui lo hai aperto.

Il pannello e la banda sono vuoti finché un mod non li riempie. Seleziona una scheda per vedere cos'è ciascuno e come disegnarci:

Modifica ciò che Claude Code già disegna

Claude Code disegna da sé la maggior parte della propria interfaccia: messaggi, righe delle chiamate agli strumenti, lo spinner e altro. Ognuna di queste parti è anch'essa un punto di rendering, quindi un mod può cambiarne lo stile o sostituirla. Per modificarne una, filtra il tuo hook ui.render sul suo nome preso da questa tabella:

In un punto che Claude Code già disegna, il tuo hook può modificare un dettaglio, sostituire il disegno o lasciarlo com'è. Seleziona una scheda per vedere ciascuna opzione applicata allo spinner. Gli esempi leggono una variabile calls che un altro hook incrementa, come nel mod del tutorial.

on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
// Keep Claude Code's spinner, and change the text after its word
return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
})

Thinking · tool calls: 2…

on('ui.render', { component: 'Spinner' }, async ($, e) => {
const { Text } = $.ui.resolve(e)
// No call to next, so this line is drawn in the spinner's place
return Text({ children: ['Claude has made ' + calls + ' tool calls'] })
})

Claude has made 2 tool calls

on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
// Nothing to show yet, so pass the event on unchanged
if (calls === 0) return next(e)
return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
})

Thinking…

In questi punti, next(e) restituisce un riferimento al disegno di Claude Code, { type: 'engine', ref }, a meno che un mod eseguito dopo il tuo non abbia restituito un proprio albero. Per modificare il contenuto di quel disegno, passa a next una copia dell'evento con prop diverse, come fa la scheda Modifica un dettaglio. Puoi restituire il riferimento così com'è, oppure inserirlo in un Box accanto a elementi tuoi:

on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
  const { Box, Text } = $.ui.resolve(e)
  const theirs = await next(e)
  return Box({ flexDirection: 'column', children: [theirs, Text({ children: ['under the spinner'] })] })
})

Mentre Claude lavora, lo spinner si anima come prima e under the spinner compare sotto di esso.

La richiesta di permesso non è un punto di rendering, quindi un mod non può modificare ciò che mostra. La finestra di dialogo delle domande, AskUserQuestion, lo è, quindi un mod può modificarla. Un albero per la finestra di dialogo deve contenere il riferimento esattamente una volta, con i tuoi elementi sopra di esso. In caso contrario, Claude Code disegna la propria finestra di dialogo.

Il terminale e l'app Desktop non generano tutti gli stessi punti. Pane, AbovePrompt, Spinner e i punti della trascrizione funzionano in entrambi. Alcune altre righe di stato vengono generate solo nel terminale. La tabella dei punti di rendering indica dove viene generato ciascuno.

Apri un pannello al momento giusto

Un pannello compare solo quando il tuo mod lo apre. Come e quando lo apri determina se riceve il focus della tastiera, quanto spazio richiede e se viene mostrato o meno in un terminale stretto.

Per aprire un pannello, chiama $.ui.open con un id a tua scelta. L'id è il nome del pannello: il tuo hook ui.render lo verifica, e lo passi di nuovo per chiudere il pannello.

await $.ui.open({ id: 'hello-tabs', title: 'Hello tabs', focus: true })

Per chiudere il pannello, chiama $.ui.close con l'id con cui lo hai aperto:

await $.ui.close({ id: 'hello-tabs' })

Oltre a id, $.ui.open accetta questi campi facoltativi:

focus, closeOnEscape e holdToasts sono facoltativi e accettano solo true. Per non usarne uno, omettilo. Passare false genera un errore come ui.open: focus is true or left out. Per impostarne uno in modo condizionale, aggiungi il campo solo quando la condizione è soddisfatta. Questa chiamata richiede il focus della tastiera solo quando items non è vuoto:

const pane = { id: 'hello-tabs', title: 'Hello tabs' }
await $.ui.open(items.length > 0 ? { ...pane, focus: true } : pane)

Per consentire a un comando di aprire il pannello mentre Claude sta lavorando, aggiungi immediate: true quando registri il comando. Senza di esso, un comando digitato durante un turno attende la fine del turno.

Quando un pannello attende un terminale più ampio

Un pannello che il tuo mod apre senza che gli sia stato chiesto non compare in un terminale stretto, così non può occupare uno schermo piccolo. Se compare o meno dipende da cosa lo ha aperto:

• Aperto da un'azione dell'utente, come un comando eseguito o un pulsante premuto, il pannello compare a qualsiasi larghezza
• Aperto dal tuo mod di propria iniziativa, ad esempio da un timer o da un hook turn.start, il pannello compare solo in un terminale largo almeno 144 colonne. Dopo che l'utente ha aperto quel pannello almeno una volta di persona, bastano 110 colonne.

Quando il pannello compare, $.ui.open si risolve in { isPlaced: true }. Quando il pannello è in attesa, isPlaced è false e reason è una stringa che ne spiega il motivo. Un pannello in attesa compare quando l'utente lo apre o allarga il terminale. Per segnalare che qualcosa è disponibile senza aprire un pannello, chiama $.ui.toast('Your message'), che mostra una notifica toast.

Creare un albero a partire dagli elementi

Ciò che un hook ui.render restituisce è un albero di elementi: una descrizione di cosa disegnare, composta da box, testo e controlli annidati l'uno nell'altro. Tu descrivi il disegno e Claude Code lo renderizza nel terminale o nell'app Desktop.

Per ottenere gli elementi, chiama $.ui.resolve(e) nel tuo hook, come in const { Box, Text, Button } = $.ui.resolve(e). Ogni elemento è una funzione. Le passi delle prop e inserisci in children gli elementi e le stringhe che vanno al suo interno.

Seleziona una scheda per vedere ciascuno degli elementi più comuni e come il terminale lo disegna:

Text({ children: ['This is the first tab.'] })

This is the first tab.

Box({
flexDirection: 'row',
columnGap: 2,
children: [
Button({ key: 'more', label: 'Add one', onPress: addOne }),
Text({ children: ['Count: 0'] }),
],
})

[ Add one ]  Count: 0

Button({ key: 'more', label: 'Add one', onPress: addOne })
Button({ key: 'tab-one', label: 'One', hotkey: '1', plain: true, onPress: showTabOne })

[ Add one ]
1: One

Input({
key: 'new-note',
label: 'Note',
placeholder: 'Type a note and press Enter',
value: '',
submitLabel: 'add',
onSubmit: addNote,
})

Note: Type a note and press Enter

La galleria dell'interfaccia contiene esempi e screenshot della maggior parte degli elementi. Questa tabella elenca tutti gli elementi:

Se il tuo modulo è un file .tsx o .jsx, puoi scrivere l'albero in JSX. Prima destruttura gli elementi da $.ui.resolve(e).

Se un albero usa un elemento che l'app non ha, una prop che un elemento non accetta o un figlio dove non è previsto, Claude Code disegna la propria versione di quel punto.

In una sessione avviata con --plugin-dir, una riga della trascrizione lo segnala, ad esempio ui.render (Pane) refused: Text prop "bogusProp" is not allowed; the engine drew its own. Il log di debug lo registra come ui.render (Pane): a hook returned a tree that does not validate con lo stesso motivo. Nient'altro compare nella sessione, quindi quando un disegno non viene visualizzato, controlla quella riga o il log.

Disegnare una griglia di celle colorate

Per una mappa di calore, una sparkline o un tabellone di gioco nel terminale, disegna un unico Raster e non un Box per ogni cella. Un Raster accetta una key, le sue dimensioni in columns e rows, e cells, una stringa base64 che racchiude tutte le celle. Ogni cella è composta da tre numeri: il code point del carattere, il suo colore e il suo colore di sfondo. Un colore è un valore RGB a 24 bit in esadecimale, come 0xc62828 per un rosso. Il valore 0x01000000, uno sopra quell'intervallo, indica il colore predefinito del terminale.

L'app Desktop non ha Raster, quindi controlla e.surface e lì disegna del testo. Questo corpo del pannello disegna una mappa di calore tre per due:

// The value that means "use the terminal's default color"
const DEFAULT_COLOR = 0x01000000

// Pack rows of [character, color] pairs into the one string a Raster takes
// One cell is three numbers: the character's code point, its color, and its background
function cellsOf(rows) {
  const numbers = rows.flat().flatMap(([char, color]) => [char.codePointAt(0), color, DEFAULT_COLOR])
  return new Uint8Array(Uint32Array.from(numbers).buffer).toBase64()
}

on('ui.render', { component: 'Pane' }, async ($, e, next) => {
  // Draw only in the pane opened with the id 'heat'
  if (e.requestId !== 'heat') return next(e)
  const { Box, Text, Raster } = $.ui.resolve(e)
  // Two rows of three cells, each a block character and its color
  const rows = [
    [['█', 0x2e7d32], ['█', 0xf9a825], ['█', 0xc62828]],
    [['█', 0x2e7d32], ['█', 0x2e7d32], ['█', 0xf9a825]],
  ]
  if (e.surface !== 'terminal') {
    return Text({ children: ['The heat map needs the terminal.'] })
  }
  return Box({
    flexDirection: 'column',
    children: [Raster({ key: 'grid', columns: 3, rows: 2, cells: cellsOf(rows) })],
  })
})

Nel terminale, il pannello mostra la griglia:

L'array rows è la parte da modificare, e cellsOf lo trasforma nella stringa compatta. L'hook disegna solo in un pannello il cui id è heat, quindi aprine uno con $.ui.open({ id: 'heat' }) da un comando, come l'esempio hello-tabs apre il suo pannello.

Ogni carattere deve essere largo una cella. Per animare un Raster già presente sullo schermo, chiama $.ui.blit con l'id del pannello come requestId, la key del Raster, le stesse dimensioni e le nuove celle. Per questo esempio, è $.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) }). Ridisegna solo quell'elemento senza eseguire di nuovo il tuo hook ui.render.

Rispondere a pressioni e digitazione

Quando l'utente preme un pulsante, digita in un campo o sceglie da un elenco disegnato dal tuo mod, Claude Code chiama la callback di quel controllo, che viene eseguita nel tuo modulo. Ogni controllo accetta le proprie callback:

• Button: accetta onPress(e), dove e.surface è l'app da cui proviene la pressione
• Input: accetta onSubmit(value) e onInput(value)
• Select: accetta onSelect(value) con le sue scelte in options, un elenco di almeno una scelta con valori univoci, come [{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]

Un test preme o digita in un controllo tramite la sua key, quindi assegnane una a ciascun controllo. Ogni uso di un controllo attiva anche ui.press, ui.input o ui.select con la key in e.element, e un altro mod può gestire quegli eventi. Il suo hook viene eseguito prima della tua callback, quindi vede ciò che l'utente digita nel tuo Input e può modificarlo o rispondere al posto della tua callback. L'API dei mod non ha alcun metodo che prema il pulsante di un altro mod.

Focus della tastiera e tasti di scelta rapida

Il tuo mod non legge mai direttamente la tastiera. L'utente preme un tasto, Claude Code decide a quale dei tuoi controlli è destinato e viene eseguita la callback di quel controllo. A parte un tasto di scelta rapida numerico sulla banda, questo accade solo mentre il tuo pannello o la tua banda ha il focus della tastiera. Il resto del tempo, i tasti vanno al prompt.

Come un pannello ottiene il focus della tastiera

Un pannello ottiene il focus della tastiera quando:

• Il tuo mod lo apre con focus: true da un comando o da una pressione
• L'utente preme Ctrl+X e poi Tab
• L'utente ci fa clic sopra

Claude Code concede focus: true solo mentre il prompt è vuoto e nient'altro ha il focus della tastiera. Un pannello che si apre mentre l'utente sta digitando non ne intercetta i tasti premuti.

Cosa fa ogni tasto

Questa tabella elenca cosa fa un tasto mentre il tuo pannello o la tua banda ha il focus della tastiera:

Un mod non può associare Tab o i tasti freccia a nient'altro, quindi un gioco si controlla con w, a, s e d.

Impostare un tasto di scelta rapida e il focus iniziale

Queste prop su un controllo decidono come la tastiera lo raggiunge:

• hotkey: per consentire all'utente di premere un Button con un solo tasto, assegnagli una hotkey composta da una cifra o da una lettera minuscola, come in hotkey: 'a'
• autoFocus: per scegliere quale controllo ha il focus all'apertura del pannello, aggiungi autoFocus: true a quel controllo. La prop accetta solo true, quindi omettila sugli altri controlli.

Il modo in cui viene mostrato un tasto di scelta rapida dipende dal pulsante e dall'app:

Nel terminale, indica il tasto nell'etichetta di un pulsante con parentesi quadre, oppure usa plain: true, in modo che l'utente possa vedere cosa premere. Il riferimento degli elementi contiene le altre regole di Button: action, i tasti di scelta rapida numerici sulla banda e due pulsanti sullo stesso tasto di scelta rapida.

Ricevere input digitato e disegnare una riga per ogni elemento

Molti pannelli sono un campo di testo con un elenco sotto. L'esempio in questa sezione è un pannello di note: digiti una nota e premi Invio per aggiungerla, e ogni nota ha un pulsante x che la elimina. Con due note aggiunte, il terminale disegna il pannello in questo modo:

╭──────────────────────────────────────────────────────────╮
│ Note: Type a note and press Enter ⏎ add                ✕ │
│ x buy milk │
│ x call bob │
╰──────────────────────────────────────────────────────────╯

L'esempio usa queste tecniche:

• Ricevere input digitato: un Input chiama onSubmit(value) con il testo del campo quando l'utente preme Invio, e onInput(value) a ogni modifica
• Disegnare un elenco: mappa i tuoi dati su una riga ciascuno e assegna al pulsante di ogni riga una propria key

Questo hook disegna il contenuto del pannello:

// The list the pane draws
let notes = []

on('ui.render', { component: 'Pane' }, async ($, e, next) => {
  // Draw only in the pane opened with the id 'notes'
  if (e.requestId !== 'notes') return next(e)
  const { Box, Text, Button, Input } = $.ui.resolve(e)
  const redraw = () => $.ui.invalidate('ui.render')

  return Box({
    flexDirection: 'column',
    children: [
      Input({
        key: 'new-note',
        label: 'Note',
        placeholder: 'Type a note and press Enter',
        // Draw the field empty each time, which clears it after a submit
        value: '',
        submitLabel: 'add',
        autoFocus: true,
        // Runs when you press Enter in the field
        onSubmit: async (value) => {
          // Ignore an empty line
          if (!value.trim()) return
          notes = [...notes, value.trim()]
          redraw()
          await $.store.set('notes', notes)
        },
      }),
      // One row for each note: a delete button, then the note's text
      ...notes.map((note, i) =>
        Box({
          flexDirection: 'row',
          columnGap: 1,
          children: [
            Button({
              // A key of its own, so each row's button can be told apart
              key: 'delete-' + i,
              label: 'x',
              plain: true,
              onPress: async () => {
                notes = notes.filter((_, j) => j !== i)
                redraw()
                await $.store.set('notes', notes)
              },
            }),
            Text({ children: [note] }),
          ],
        }),
      ),
    ],
  })
})

Per provare il pannello:

• Aggiungi una nota: digita una riga e premi Invio. La riga appare come una nuova riga dell'elenco e il campo si svuota.
• Elimina una nota: premi Tab finché il pulsante x della nota non ha il focus, poi premi Invio. La x è l'etichetta del pulsante e non un tasto di scelta rapida, quindi digitare la lettera non lo preme.

Ogni modifica segue lo stesso ciclo di rendering di hello-tabs: la callback modifica notes, chiama redraw e salva l'elenco in $.store.

Il campo si svuota dopo ogni invio grazie alla sua prop value. value è il testo che il campo contiene quando viene disegnato, e ciò che l'utente digita lo sostituisce finché il tuo hook non disegna di nuovo il campo. L'esempio disegna sempre il campo con ''.

L'esempio salva le note ma non le carica. Per ripristinarle nella sessione successiva, leggile in un hook session.start, nello stesso modo in cui hello-tabs legge count.

Queste prop compongono la riga del campo, Note: Type a note and press Enter ⏎ add:

L'invio di un Input non avvia un turno a meno che la tua callback non chiami $.prompt.submit.

Ridisegnare un sito

Un disegno è un'istantanea: mostra ciò che il tuo hook ui.render ha restituito l'ultima volta che l'hook è stato eseguito. Per mostrare qualcosa di nuovo, l'hook deve essere eseguito di nuovo. Claude Code lo riesegue per alcune modifiche, e il tuo mod lo richiede per le altre.

Quando Claude Code ridisegna senza che venga richiesto

Claude Code esegue di nuovo il tuo hook ui.render quando cambiano le prop del sito o quando cambia la larghezza del terminale. Non esegue l'hook in base a un timer, e non può sapere quando cambia una variabile nel tuo modulo.

Ridisegnare quando i tuoi dati cambiano

Per far ridisegnare i tuoi siti dopo che i tuoi dati sono cambiati, chiama $.ui.invalidate('ui.render'). Questo pannello conta le pressioni. La callback del pulsante modifica count, poi richiede un nuovo disegno:

let count = 0

on('ui.render', { component: 'Pane' }, async ($, e, next) => {
  if (e.requestId !== 'counter') return next(e)
  const { Box, Text, Button } = $.ui.resolve(e)
  return Box({
    flexDirection: 'row',
    columnGap: 2,
    children: [
      Button({
        key: 'more',
        label: 'Add one',
        onPress: () => {
          count += 1
          // The data changed, so ask Claude Code to draw the pane again
          $.ui.invalidate('ui.render')
        },
      }),
      Text({ children: ['Count: ' + count] }),
    ],
  })
})

Ogni pressione incrementa il numero nel pannello. L'esempio hello-tabs racchiude la stessa chiamata nella sua funzione redraw.

Un valore che conservi in $.state non ha bisogno della chiamata, perché scrivere il valore ridisegna i siti che lo leggono.

Ridisegnare in base a un timer

Per mantenere aggiornati un orologio, un conto alla rovescia o un valore esterno alla sessione, ridisegna secondo una pianificazione. Avvia un timer nell'hook session.start del modulo. Se il modulo ne ha già uno, come nel caso di hello-tabs, aggiungi a esso la riga $.clock.every:

on('session.start', async ($, e, next) => {
  // Every 1000 milliseconds, ask Claude Code to draw your sites again
  $.clock.every(1000, () => $.ui.invalidate('ui.render'))
  return next(e)
})

Ora Claude Code esegue il tuo hook ui.render una volta al secondo. Il timer si arresta quando il modulo viene ricaricato, e la nuova istanza del modulo avvia il proprio.

Con quale frequenza un sito può essere ridisegnato

Claude Code limita la frequenza dei ridisegni di un sito, quindi il tuo mod può chiamare $.ui.invalidate tutte le volte che i suoi dati cambiano. Per sapere con quale frequenza ciascun sito può essere ridisegnato, consulta la tabella dei limiti.

Le chiamate che arrivano più velocemente del limite vengono accorpate in un unico ridisegno. Quel ridisegno esegue il tuo hook una sola volta, e l'hook legge i tuoi dati così come sono in quel momento, quindi viene mostrato il valore più recente e non quelli intermedi. Un'animazione non può essere eseguita più velocemente del limite.

Mantenere lo stato

Il punto in cui un mod conserva un valore determina quanto a lungo il valore dura: fino al ricaricamento del modulo, fino alla fine della sessione, oppure da una sessione all'altra. Scegli in base a quanto a lungo il valore deve durare:

$.store.get(key) si risolve nel valore o in undefined, e $.store.set(key, value) accetta qualsiasi valore JSON.

Conservare un valore in `$.state`

$.state conserva i valori per la durata di una sessione e ridisegna al posto tuo. È uno stato reattivo: un hook ui.render che legge un valore si sottoscrive a esso, quindi Claude Code ridisegna quel punto ogni volta che scrivi il valore, e non devi chiamare $.ui.invalidate. Un valore in $.state sopravvive inoltre a un ricaricamento del modulo, cosa che una variabile non fa.

Per configurarlo, dichiara i tuoi valori, fai puntare il manifest alla dichiarazione, poi definisci e usa ciascun valore. Gli esempi spostano il count di hello-tabs in $.state.

Dichiarare i valori

Dichiara i valori in un file di dichiarazione dei tipi. La chiave esterna è il nome del tuo plugin, e ogni voce sotto di essa è un valore con il suo tipo. Salva questo come hello-tabs/types/index.d.ts:

declare module 'claude-code' {
  interface PluginState {
    'hello-tabs': {
      tab: 'one' | 'two'
      count: number
    }
  }
}

Far puntare il manifest alla dichiarazione

Per consentire a claude plugin validate di verificare il tuo codice rispetto a quel file, aggiungi al manifest un campo types con il suo percorso:

{
  "name": "hello-tabs",
  "version": "0.1.0",
  "description": "Opens a pane with two tabs and a counter",
  "author": { "name": "Your Name" },
  "types": "./types/index.d.ts"
}

Definire, leggere e scrivere un valore

Nel tuo modulo, definisci ciascun valore con un valore predefinito, leggilo durante il disegno e scrivilo da una callback. atom assegna un nome a un valore e al suo valore predefinito, read lo restituisce e update lo scrive. I tre helper chiamano $.state.get e $.state.set al posto tuo:

import { atom, read, update } from 'claude-code'

// At the top of the module: name the value and give its default
const count = atom({ plugin: 'hello-tabs', key: 'count' }, 0)

// In the ui.render hook: read the value to draw it
const n = await read($, count)

// In a Button: write a new value from the old one
onPress: () => update($, count, (value) => value + 1)

Poiché l'hook ui.render ha letto count, Claude Code esegue di nuovo l'hook ogni volta che il pulsante lo scrive.

Al codice si applicano queste regole:

• Scrivi plugin e key come stringhe letterali: claude plugin validate li legge dal tuo codice sorgente
• Dichiara ogni valore nel file di dichiarazione dei tipi: altrimenti la validazione fallisce con hello-tabs.count is not declared
• Scrivi da una callback o dall'hook di un altro evento: un hook ui.render può leggere lo stato ma non può scriverlo, quindi scrivi da onPress, onSubmit o da un hook per un altro evento

Modificare `hello-tabs` per usare `$.state`

Per spostare count di hello-tabs in $.state, modifica ogni riga che lo usa:

• In cima al modulo: aggiungi la riga import e sostituisci let count = 0 con la riga atom
• Nell'hook ui.render: aggiungi la riga read prima di tabButton e disegna 'Count: ' + n nel Text
• Nel pulsante Add one: sostituisci onPress con quello in Salvare da più di una sessione, che salva il conteggio oltre a scriverlo
• Nell'hook session.start: sostituisci le due righe che leggono saved con la chiamata a loadCount da Caricare di nuovo un valore salvato dopo /clear

Mantieni redraw per i pulsanti delle schede, perché tab è ancora una variabile.

Caricare di nuovo un valore salvato dopo `/clear`

Se il tuo mod copia un valore salvato da $.store in $.state a session.start, deve copiarlo di nuovo dopo /clear, /resume o /branch. Questi comandi reimpostano ogni valore di $.state al suo valore predefinito, e session.start non viene attivato di nuovo. classic.SessionStart invece viene attivato dopo ciascuno di essi, con e.source impostato su clear, resume o fork, quindi copia di nuovo il valore in un hook su di esso. Altrimenti il tuo disegno mostra il valore predefinito, e una callback che salva il valore di $.state scrive il valore predefinito sopra quello che avevi memorizzato.

Questo codice carica count da entrambi gli hook. Si basa sulla versione di hello-tabs con $.state, in cui count è un atom e update è importato. Metti loadCount sopra register e aggiungi la chiamata a loadCount all'hook session.start che hai già. classic.SessionStart viene attivato anche all'avvio e dopo la compattazione, che non reimposta $.state, quindi il filtro su source limita l'hook ai tre reset:

// Copy the saved count from $.store into $.state, or 0 if nothing is saved
async function loadCount($) {
  const saved = Number((await $.store.get('count')) ?? 0)
  await update($, count, () => saved)
}

// Runs before your first prompt, and again after a reload
on('session.start', async ($, e, next) => {
  await loadCount($)
  return next(e)
})

// Runs again after /clear, /resume, and /branch, which reports fork
on('classic.SessionStart', { source: ['clear', 'resume', 'fork'] }, async ($, e, next) => {
  await loadCount($)
  return next(e)
})

Con entrambi gli hook in posizione, il riquadro mostra il conteggio salvato dopo /clear e non 0, e la successiva pressione di Add one si aggiunge al conteggio salvato.

loadCount scrive il valore memorizzato sopra quello in $.state, e session.start viene attivato di nuovo ogni volta che il modulo si ricarica. Per evitare che lo store rimanga indietro, salva a ogni modifica, come fa il pulsante Add one.

Per verificare il ricaricamento senza una sessione, testa il disegno dopo /clear.

Salvare da più di una sessione

Ogni sessione sulla tua macchina che esegue il tuo mod condivide un unico $.store. Un get seguito da un set non è atomico. Quando due sessioni leggono ciascuna un valore, lo modificano e lo riscrivono, entrano in competizione, e la seconda scrittura sostituisce la prima.

Per renderlo meno probabile:

• Assegna a ogni elemento la propria chiave: un set modifica solo la propria chiave, quindi le sessioni che scrivono chiavi diverse non si sovrascrivono a vicenda
• Rileggi subito prima di scrivere: per un valore che più sessioni modificano, esegui get sulla chiave nella callback e costruisci il nuovo valore a partire da quello, non da una copia caricata a session.start. La scrittura di un'altra sessione va comunque persa se avviene tra il tuo get e il tuo set.

Questo pulsante aggiunge uno a qualunque valore lo store contenga in quel momento, poi aggiorna il disegno:

onPress: async () => {
  // Read what the store holds now, which another session may have changed
  const saved = Number((await $.store.get('count')) ?? 0)
  // Save the new count, then show it
  await $.store.set('count', saved + 1)
  await update($, count, () => saved + 1)
}

Se una seconda sessione ha premuto il proprio pulsante tre volte dall'avvio di questa sessione, questa pressione mostra e salva un conteggio che include quelle tre.

Passaggi successivi

• Reagire agli eventi: alimenta il tuo disegno dalle chiamate agli strumenti e dai turni
• Usare l'API dei mod: alimenta il tuo disegno da timer e chiamate al modello
• Testare un disegno: premi i tuoi pulsanti da un test, su più di una superficie
• Punti di rendering ed elementi: le prop di ciascun punto e le prop di ciascun elemento