ui.render event each time it’s about to draw a render site, and your hook for that event returns what to draw there.
This map shows where a mod can draw in a terminal session:
To look up one prop or limit, see the reference.
Build a pane with tabs
In this section you build a mod that adds a/hello-tabs command, and the command opens a pane. A pane is a sidebar beside the transcript in a wide fullscreen terminal, or a framed region above the prompt otherwise. This pane shows two tabs, and the second tab has a button that adds one to a counter. The count is still there after you restart Claude Code.
The finished mod looks like this. The recording opens the pane, switches to the second tab, presses the button a few times, and returns to the first tab:
1
Create the plugin
A mod is a plugin with a manifest, a Name your entry point in
hooks.json that points to your code, and the code file. Create a mod explains each one. Create a directory named hello-tabs with .claude-plugin and hooks directories inside it, then save the first two files.Save the manifest as hello-tabs/.claude-plugin/plugin.json:hello-tabs/.claude-plugin/plugin.json
hello-tabs/hooks/hooks.json:hello-tabs/hooks/hooks.json
2
Write the code
This list says what each hook does, in the order they appear in the code:Each hook also does something the code doesn’t make plain:
- Adds the
/hello-tabscommand, and loads the count an earlier session saved - Opens the pane when you run that command
- Draws the pane’s content: the row of tabs and the open tab’s body
tab and count, hold the pane’s state.Save this as hello-tabs/hooks/register.js:hello-tabs/hooks/register.js
session.startalso reads the saved count from$.store, a key-value store that persists between sessions.command.runonly tells Claude Code the pane exists. Opening a pane draws nothing by itself: Claude Code then firesui.renderto ask what goes in it.ui.renderreturns the element tree, aBoxthat holds other boxes, text, and buttons, and builds it again fromtabandcounteach time it runs.
onPress callback, which changes a variable and calls redraw. Claude Code then runs the ui.render hook again, and the hook builds a new tree from the new values. Every interactive drawing uses that render cycle: a callback changes state, and the hook renders again from the new state.3
Open the pane
In your shell, start Claude Code with
claude --plugin-dir ./hello-tabs. At the Claude Code prompt, run /hello-tabs. A pane opens with 1: One and 2: Two across the top. Press 2, then press a, the hotkey for Add one, a few times. The count rises.4
Check that the count was saved
Press Esc to close the pane, then exit the session. In your shell, start Claude Code again with the same
claude --plugin-dir ./hello-tabs command, and at the Claude Code prompt run /hello-tabs. The count is where you left it.To clear the count, have the mod call $.store.delete('count'). Keep state covers how long each kind of value lasts.Pick where to draw
To choose the render site aui.render hook draws in, pass a filter, called a matcher, as the second argument to on. { component: 'Pane' } runs the hook only for panes. In the hook, e.component names the site, e.surface says which app is drawing, and e.props holds the site’s own data. For a pane, e.requestId is the id you opened it with.
The pane and the band are empty until a mod fills them. Select a tab to see what each one is and how to draw in it:
- Pane
- Band above the prompt
A pane is a sidebar beside the transcript in a wide fullscreen terminal, or a framed region above the prompt otherwise. With several panes open, each gets a tab that shows its title.A pane appears when your mod calls
$.ui.open with an id you choose, as in $.ui.open({ id: 'hello-tabs' }). Open a pane at the right time covers the other fields and when a pane waits for a wider terminal.To draw in your pane, filter on { component: 'Pane' } and check that e.requestId is your id.Change what Claude Code already draws
Claude Code draws most of its interface itself: messages, tool call rows, the spinner, and more. Each of those parts is a render site too, so a mod can restyle or replace it. To change one, filter yourui.render hook on its name from this table:
Pane, AskUserQuestion, Spinner, UserMessage, AssistantMessage, and the tool call sites work in the terminal, the Desktop app, and the VS Code extension. The render sites table lists where each of the others is raised.
At a site Claude Code already draws, your hook can change a detail, replace the drawing, or leave it alone. Select a tab to see each one applied to the spinner. The examples read a calls variable that another hook counts, as in the tutorial mod.
- Change a detail
- Replace the drawing
- Leave it alone
To keep Claude Code’s drawing and change one part of it, pass The spinner keeps its animation and its word, and your text follows the word:
next a copy of the event with changed props. This hook changes the text after the spinner’s word:next(e) returns a reference to Claude Code’s drawing, { type: 'engine', ref }, unless a mod that runs after yours returned a tree of its own. To change what’s in that drawing, pass next a copy of the event with different props, as the Change a detail tab does. You can return the reference as it is, or place it in a Box beside elements of your own:
under the spinner appears below it.
The permission prompt isn’t a render site, so a mod can’t change what it shows. The question dialog, AskUserQuestion, is one, so a mod can change that dialog when Claude asks a question. A tree for the dialog has to hold the reference exactly once, with your elements above it. Otherwise, Claude Code draws its own dialog.
Open a pane at the right time
A pane appears only when your mod opens it. How and when you open it decides whether it takes keyboard focus, how much room it asks for, and whether it shows at all in a narrow terminal. To open a pane, call$.ui.open with an id you choose. The id is the pane’s name: your ui.render hook checks for it, and you pass it again to close the pane. If another mod has a pane open with that id, the call rejects.
$.ui.close with the id you opened it with:
id, $.ui.open takes these optional fields:
The VS Code extension ignores
rows and columns and sizes the pane itself.
focus, closeOnEscape, and holdToasts are optional and accept only true. To leave one off, omit it. Passing false throws an error such as ui.open: focus is true or left out. To set one of them conditionally, add the field only when the condition holds. This call asks for keyboard focus only when items isn’t empty:
immediate: true when you register the command. Without it, a command typed during a turn waits for the turn to end.
Hold toasts behind a dialog
PassholdToasts: true to $.ui.open when the pane is a dialog the user answers and leaves, so toasts don’t appear while they decide. In the terminal, the hold lasts while that pane is the one showing, and a toast raised in that time waits until the hold ends.
Claude Code holds other mods’ toasts and its own short-lived notifications as well as the ones your mod raises with $.ui.toast. Leave the field off a pane that stays open, so the user keeps seeing them.
When a pane waits for a wider terminal
A pane your mod opens without being asked doesn’t appear in a narrow terminal, so it can’t take over a small screen. Whether it appears depends on what opened it:- Opened by something the user did, such as a command they ran or a button they pressed, the pane appears at any width
- Opened by your mod acting by itself, such as from a timer or a
turn.starthook, the pane appears only in a terminal at least 144 columns wide. After the user has opened that pane once themselves, 110 columns is enough.
$.ui.open resolves to { isPlaced: true }. When the pane is waiting, isPlaced is false and reason is a string that says why. A waiting pane appears when the user opens it or widens the terminal. To say something is available without opening a pane, call $.ui.toast('Your message'), which shows a toast notification.
Draw in the VS Code extension
In the VS Code extension, what a mod draws appears in the chat panel with extension version 2.1.299 or later. A session that doesn’t fetch feature flags, such as one on Amazon Bedrock, needs 2.1.304 or later. In aui.render hook for the panel, e.surface is vscode. To check which sites and elements the panel draws, and which props it ignores, see the render sites and elements tables.
To make a mod work in the panel as well as the terminal, account for these differences:
- Panes: in a panel 800 pixels or wider, panes dock beside the conversation,
e.props.placementis'dock', ande.viewport.isFullscreenistrue. In a narrower panel, panes draw above the prompt box,placementis'inline', and a pane shows 12 rows before it scrolls. - Toasts and status lines: these sit in one stack directly above the prompt box, together with the panes when the panel is narrow, with one status line per mod. The stack is hidden while a permission request or a dialog shows.
- Labels: the panel frames what a mod draws or rewrites and labels it with the plugin’s name, as in From the token-chart plugin or Edited by the token-chart plugin.
- Keyboard: buttons have no hotkeys, so the user clicks a button or presses Enter on it once it has focus.
- Keyboard focus: the panel grants a pane’s
focus: truerequest only when the panel has focus, Claude is idle with no question waiting, and the prompt box is empty. - The question dialog: at
AskUserQuestion, the panel keeps its own question card and draws your elements above it. Props you pass tonextdon’t change the card. - Prompt suggestions:
$.prompt.suggestresolves withisShown: falseand shows nothing, because the panel keeps the prompt box’s dim suggestion text for Claude’s own suggestions. - Text limits: the panel cuts a status line at 200 characters or two rows, and a toast at 500 characters.
Place a row in the transcript
A row is a line your mod adds to the transcript in the terminal, after the latest message. It stays at that spot as the conversation goes on, and Claude doesn’t see it.$.ui.place requires Claude Code v2.1.314 or later.
1
Place the row
Call
$.ui.place with an id. The id is a name you make up for the row, such as build-status. It can be 1 to 64 letters, digits, _, or -, and each row your mod has in the transcript needs its own.2
Draw the row
Draw the row at the
Placed render site./build-status command. When the user runs the command, the mod adds a row that shows Build: passing. The text is fixed to keep the example short, so a real mod would draw its own result:
/build-status at the Claude Code prompt. Build: passing appears as a row at the end of the transcript.
The call doesn’t always show a row, and a row can go away later, so handle these cases in your mod:
- The result:
{ isPlaced: true, requestId }when the terminal draws the row. OtherwiseisPlacedisfalseandreasonsays why, as inno attached surface draws placed rows yet. One reason is the limit on rows a mod can have at one time. - A second call with the same
id: while the first row is still in the transcript, the call adds no row and resolves with that row’srequestId. To change what the row shows, redraw the row. - When the row goes away: when the conversation ends, when the user rewinds past the row, or, outside fullscreen rendering, when the conversation is compacted.
--resumedoesn’t bring the row back. To show the row again, call$.ui.placeagain.
Put a backdrop behind the conversation
$.theme.set and $.theme.clear replace $.ui.backdrop, which Claude Code v2.1.319 removed. Change $.ui.backdrop({ id: 'your-backdrop' }) to a $.theme.set call like the one in this section’s example, and $.ui.backdrop(undefined) to $.theme.clear(), which removes any mod’s backdrop.$.theme.set with a backdrop, then draw the backdrop at the Backdrop render site. To take the backdrop off, call $.theme.clear(). The terminal draws no backdrop. $.theme.set and $.theme.clear require Claude Code v2.1.319 or later.
This example requires Claude Code v2.1.323 or later, so check your version first. The mod sets a backdrop when the session starts, draws the backdrop, and adds a /plain command that takes the backdrop off:
Before v2.1.323, write
id in place of scene in the $.theme.set call and in e.props, and move overrideColorScheme into backdrop as colorScheme./plain at the Claude Code prompt. The transcript shows the theme is cleared after the mod’s name, as in night-sky: the theme is cleared for a mod named night-sky.
Check what backdrop takes, what the call’s result tells you, and what other mods can change:
- The
backdropfields:sceneis a name you choose for a backdrop your hook draws. For the other fields andoverrideColorScheme, see the types for your build. - Whether the backdrop is drawn:
$.theme.setresolves withisDrawn: truewhen a Desktop or mobile app connected to the session says it draws backdrops. OtherwiseisDrawnisfalseandreasonsays why. - One theme for each session: a mod that calls
$.theme.setreplaces the session’s backdrop and colors, and a mod that calls$.theme.clear()removes them, whichever mod set them. Call$.theme.clear()only when the user asks for it.
Change the colors of the Desktop app
To change the colors of the Desktop app’s Code tab with a mod, ask Claude for one or write one yourself. Both ways require Claude Code v2.1.324 or later in the Code tab, so check the version there first. Claude Code in the terminal keeps its own colors.Ask Claude for a colors mod
1
Describe the colors
Start a local session in the Code tab and tell Claude which colors you want. For example, enter
make a mod that makes the app cream in light mode and dark brown in dark mode. Claude writes the mod’s files.2
Approve the mod
Answer the questions Claude Code asks about the mod’s files and hot reloading. For what each answer does, see Ask Claude for a mod.
3
Check the colors
The Code tab changes color when the mod loads. To adjust a color, tell Claude what to change. If nothing changes, see Fix missing mod colors.
Write a colors mod yourself
makeColors is a function that builds a theme from a few hex colors. These steps create a mod named paper that uses it.
1
Have Claude copy makeColors
Start a local session in the Code tab, and enter
copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/. Check that both files are in that directory.2
Save the manifest and hooks.json
From Write a mod yourself, save
.claude-plugin/plugin.json and hooks/hooks.json in ~/.claude/skills/paper/, and change first-mod to paper in both files. A mod under ~/.claude/skills/ loads when you start a session.3
Write the code
Save this file as To use your own colors, replace the hex values with other six-digit hex colors.
~/.claude/skills/paper/hooks/register.js. When a session starts, the code calls $.theme.set with the colors for light mode and dark mode:4
Check the colors
Start a new local session in the Code tab. With the example’s values, the background is cream in light mode and dark brown in dark mode. If nothing changes, see Fix missing mod colors.
Fix missing mod colors in the Desktop app
If you use a third-party provider instead of a Claude account in Claude Desktop v5.11492.5 or earlier, the Code tab keeps its own colors, so skip these checks. Otherwise, if a mod’s colors don’t appear in the Code tab, or if they disappear, check for these causes:- Old version: update the Desktop app, restart it, and start a new local session in the Code tab. If Claude wrote the mod, ask for it again there.
- Mod not loaded: if Claude wrote the mod, see when it loads in Ask Claude for a mod. If you wrote it, compare your files and their paths with Write a colors mod yourself.
- Refused theme: ask Claude to run the mod’s
makeColorscall. If the call throws an error, or itsproblemslist has an entry that startsDesktop won't paint this theme, have Claude fix the theme. If you installed the mod, send what Claude finds to its author. - Another
$.themecall: when any mod in the session calls$.theme.setor$.theme.clear(), the colors and backdrop from an earlier call disappear. In your own mod, passcolorsandbackdropin the same$.theme.setcall. Use one mod at a time that sets a theme.
Remove mod colors from the Desktop app
To take a mod’s colors off the Code tab, turn off the mod first. A mod that’s still on can set its colors again.1
Turn off the mod
- Claude wrote the mod: move its directory out of the mods folder of the session where Claude wrote it.
- You put the mod under
~/.claude/skills/: move its directory, such as~/.claude/skills/paper/, to a place outside~/.claude/skills/. - You installed the mod: in the Desktop app, disable or uninstall its plugin from Manage plugins. If you don’t see Manage plugins and you have the CLI, you can disable or uninstall a marketplace plugin from your shell.
2
Start a new session
Start a new local session in the Code tab.
3
Remove colors that stay
If the colors are still there, open Settings from the Code tab, and search there for
code appearance. Open the result, and select Remove colors.Build a tree from elements
What aui.render hook returns is an element tree: a description of what to draw, made of boxes, text, and controls nested inside each other. You describe the drawing, and Claude Code renders it in whichever app the user has open: the terminal, the Desktop app, or the VS Code extension.
To get the elements, call $.ui.resolve(e) in your hook, as in const { Box, Text, Button } = $.ui.resolve(e). Each element is a function. You pass it props, and you put the elements and strings that go inside it in children.
Select a tab to see each of the most common elements and how the terminal draws it:
- Text
- Box
- Input
Text draws a string, with optional styling such as bold and color:
If your module is a
.tsx or .jsx file, you can write the tree as JSX. Destructure the elements from $.ui.resolve(e) first.
If your drawing doesn’t show up, check its tree for a prop an element doesn’t take or a child where none goes. A hook that returns such a tree fails, and a hook skipped line names your mod and the rule the tree broke. For a Text in a pane with a prop named bogusProp, that line reads:
Link in the Desktop app and VS Code
In the Desktop app and the VS Code extension, a Link draws as plain text unless its href meets these requirements:
- Scheme and host: an
https:URL, or anhttp://localhostURL such ashttp://localhost:3000 - No
@: write an@in the path or query as%40 - Spelling: what
new URL(href).hrefreturns, apart from a missing/after the host. That excludes an uppercase host, a space, and:443on anhttps:URL.
When a Client fails
In the terminal, when the file a Client runs fails, a dimmed line such as my-mod: Client client/spinner.js: boom takes the Client’s place, and the rest of your drawing still shows.
If your mod handles ui.fault, Claude Code then draws the site again.
Draw a grid of colored cells
For a heat map, a sparkline, or a game board in the terminal, draw oneRaster and not a Box for each cell. A Raster takes a key, its size in columns and rows, and cells, a base64 string that packs every cell. Each cell is three numbers: the character’s code point, its color, and its background color. A color is a 24-bit RGB value in hexadecimal, such as 0xc62828 for a red. The value 0x01000000, one above that range, means the terminal’s default.
Apps other than the terminal have no Raster, so check e.surface and draw text there. This pane body draws a three by two heat map:
rows array is the part you’d change, and cellsOf turns it into the packed string. The hook draws only in a pane whose id is heat, so open one with $.ui.open({ id: 'heat' }) from a command, as the hello-tabs example opens its pane.
Each character has to be one cell wide. To animate a Raster that’s already on screen, call $.ui.blit with the pane’s id as requestId, the Raster’s key, the same size, and new cells. For this example, that’s $.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) }). It repaints that one element without running your ui.render hook again.
Respond to presses and typing
When the user presses a button, types into a field, or picks from a list your mod drew, Claude Code calls that control’s callback, which runs in your module. Each control takes its own callbacks:Button: takesonPress(e), wheree.surfaceis the app the press came fromInput: takesonSubmit(value)andonInput(value)Select: takesonSelect(value)with its choices inoptions, a list of at least one choice with unique values, such as[{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]
Which controls need a key
Give every Input and Select a key prop, such as key: 'size'. A Button can go without a key when it has a label prop or a single string child. Its key is then the label value or that string.
Tests and other mods identify a control by its key:
- Tests: a test presses or types into a control by its key.
- Other mods: Claude Code fires
ui.press,ui.input, orui.selectwith the control’s key ine.elementbefore it runs the control’s callback. Another mod’s hook can also run for that event. That hook sees what the user typed into yourInputand can change that text or keep your callback from running. The mods API gives that mod no method to press your buttons.
needs a key or is drawn twice, find the cause by that message.
Keyboard focus and hotkeys
Your mod never reads the keyboard itself. The user presses a key, Claude Code decides which of your controls it’s for, and that control’s callback runs. Apart from a digit hotkey on the band or anaction binding, that happens only while your pane or band has keyboard focus. The rest of the time, keys go to the prompt.
In the VS Code extension, buttons have no hotkeys: the user clicks a button or presses Enter on it, and types into fields.
How a pane gets keyboard focus
A pane gets keyboard focus when:- Your mod opens it with
focus: truefrom a command or a press - The user presses Ctrl+X then Tab
- The user clicks it, which in the terminal needs fullscreen rendering
focus: true only while the prompt is empty and nothing else has keyboard focus. A pane that opens while the user is typing doesn’t take their keystrokes.
What each key does
This table lists what a key does while your pane or band has keyboard focus:
A mod can’t bind Tab or the arrow keys to anything else, so a game steers with
w, a, s, and d.
Set a hotkey and the first focus
hotkey: to let the user press aButtonwith one key, give it ahotkeyof one digit or one lowercase letter, as inhotkey: 'a'autoFocus: to choose which control has the focus when the pane opens, addautoFocus: trueto it. In the VS Code extension,autoFocusdoes nothing: the control draws as if you had left it out, and you don’t need to change anything. The prop accepts onlytrue, so omit it on the other controls.
In the terminal, name the key in a bracketed button’s label, or use
plain: true, so the user can see what to press. The elements reference has the other Button rules: action, digit hotkeys on the band, and two buttons on one hotkey.
When the user collapses the band
In the terminal, while a mod draws in the band, the user can collapse the band to one row to get it out of the way:- Click
[-]: while the band is expanded, Claude Code draws this mark at the right end of its first row. In fullscreen rendering, the user clicks it to collapse the band. - Press Ctrl+X then Ctrl+A: this works whether the prompt, the band, or a pane has keyboard focus. The user can bind other keys to it through the
abovePrompt:toggleaction.
action. If the band has keyboard focus when the user collapses it, the focus returns to the prompt, and Ctrl+X then Tab skips the band while it’s collapsed.
The band stays collapsed until the user expands it, even after /clear, and is expanded again the next time Claude Code starts. Your mod can’t expand it. Don’t make the band the only place your mod shows something the user has to answer. To show that elsewhere only while the band is collapsed, read e.props.isCollapsed in your ui.render hook, which keeps running. isCollapsed requires Claude Code v2.1.321 or later.
Take typed input and draw a row for each item
Many panes are a text field with a list under it. The example in this section is a notes pane: you type a note and press Enter to add it, and each note has anx button that deletes it. With two notes added, the terminal draws the pane this way:
✕ on the top border is Claude Code’s own mark for closing the pane.
The example uses these techniques:
- Take typed input: an
InputcallsonSubmit(value)with the field’s text when the user presses Enter, andonInput(value)on every change - Draw a list: map your data to one row each, and give every row’s button its own
key
- Add a note: type a line and press Enter. The line appears as a new row, and the field empties.
- Delete a note: press Tab until the note’s
xbutton has the focus, then press Enter. Thexis the button’s label and not a hotkey, so typing the letter doesn’t press it.
hello-tabs: the callback changes notes, calls redraw, and saves the list to $.store. If your hook draws the pane again while the user is typing a note, the field keeps their text as long as the hook passes the same value each time. To replace their text with your own, pass a different value.
The example saves the notes and doesn’t load them. To bring them back in the next session, read them in a session.start hook, the way hello-tabs reads count.
These props make up the field’s line, Note: Type a note and press Enter ⏎ add:
Submitting an
Input doesn’t start a turn unless your callback calls $.prompt.submit.
Redraw a site
A drawing is a snapshot: it shows what yourui.render hook returned the last time the hook ran. To show something new, the hook has to run again. Claude Code runs it again for some changes, and your mod asks for the rest.
When Claude Code redraws without being asked
Claude Code runs yourui.render hook again when the site’s props change or the terminal’s width changes. When a Client in the site fails and your mod handles ui.fault, Claude Code runs the hook once more after your ui.fault hooks return, so your ui.render hook can leave the Client out. It doesn’t run the hook on a timer, and it can’t tell when a variable in your module changes.
Redraw when your data changes
To have your sites drawn again after your own data changes, call$.ui.invalidate('ui.render'). This pane counts presses. The button’s callback changes count, then asks for a redraw:
hello-tabs example wraps the same call in its redraw function.
A value you keep in $.state doesn’t need the call, because writing the value redraws the sites that read it.
Redraw on a timer
To keep a clock, a countdown, or a value from outside the session current, redraw on a schedule. Start a timer in the module’ssession.start hook. If the module already has one, as hello-tabs does, add the $.clock.every line to it:
ui.render hook once a second. The timer stops after the module reloads, and the new instance of the module starts its own.
How often a site can redraw
Claude Code throttles redraws of a site, so your mod can call$.ui.invalidate as often as its data changes. For how often each site can redraw, see the limits table.
Calls that come faster than the limit are coalesced into one redraw. That redraw runs your hook once, and the hook reads your data as it is at that moment, so the latest value shows and the values in between don’t. An animation can’t run faster than the limit.
Keep state
Where a mod keeps a value decides how long the value lasts: until the module reloads, until the session ends, or from one session to the next. Choose by how long the value has to last:$.store.get(key) resolves to the value or undefined, and $.store.set(key, value) takes any JSON value.
Keep a value in $.state
$.state holds values for the length of a session, and it redraws for you. It’s reactive state: a ui.render hook that reads a value subscribes to it, so Claude Code redraws that site each time you write the value, and you don’t call $.ui.invalidate. A value in $.state also survives a reload of the module, which a variable doesn’t.
To set it up, declare your values, point your manifest at the declaration, then define and use each value. The examples move the count from hello-tabs into $.state.
Declare the values
Declare the values in a type declaration file. The outer key is your plugin’s name, and each entry under it is a value and its type. Save this ashello-tabs/types/index.d.ts:
hello-tabs/types/index.d.ts
Point the manifest at the declaration
To letclaude plugin validate check your code against that file, add a types field to the manifest with its path:
hello-tabs/.claude-plugin/plugin.json
Define, read, and write a value
In your module, define each value with a default, read it while drawing, and write it from a callback.atom names a value and its default, read returns it, and update writes it. The three helpers call $.state.get and $.state.set for you:
ui.render hook read count, Claude Code runs the hook again each time the button writes it.
These rules apply to the code:
- Write
pluginandkeyas string literals:claude plugin validatereads them from your source - Hold the result of each
atomcall in aconst: if you declarecountwithlet, validation fails withtakes a source the scan can read - Declare every value in the type declaration file: otherwise validation fails with
hello-tabs.count is not declared - Write from a callback or another event’s hook: a
ui.renderhook can read state and can’t write it, so write fromonPress,onSubmit, or a hook for another event
Change hello-tabs to use $.state
To move count in hello-tabs into $.state, change every line that uses it:
- At the top of the module: add the
importline, and replacelet count = 0with theatomline - In the
ui.renderhook: add thereadline beforetabButton, and draw'Count: ' + nin theText - In the Add one button: replace
onPresswith the one in Save from more than one session, which saves the count as well as writing it - In the
session.starthook: replace the two lines that readsavedwith theloadCountcall from Load a saved value again after/clear
redraw for the tab buttons, because tab is still a variable.
Load a saved value again after /clear
If your mod copies a saved value from $.store into $.state at session.start, it has to copy it again after /clear, /resume, or /branch. Those commands reset every $.state value to its default, and session.start doesn’t fire again. classic.SessionStart does fire after each of them, with e.source set to clear, resume, or fork, so copy the value again in a hook on it. Otherwise your drawing shows the default, and a callback that saves the $.state value writes the default over what you stored.
This code loads count from both hooks. It builds on the $.state version of hello-tabs, where count is an atom and update is imported. Put loadCount above register, and add the loadCount call to the session.start hook you already have. classic.SessionStart also fires at startup and after compaction, which doesn’t reset $.state, so the filter on source keeps the hook to the three resets:
/clear and not 0, and the next press of Add one adds to the saved count.
loadCount writes the stored value over the one in $.state, and session.start fires again each time the module reloads. To keep the store from falling behind, save on every change, as the Add one button does.
To check the reload without a session, test the drawing after /clear.
Save from more than one session
Every session on your machine that runs your mod shares one$.store. A get followed by a set isn’t atomic. When two sessions each read a value, change it, and write it back, they race, and the second write replaces the first.
To make that less likely:
- Give each item its own key: a
setchanges only its own key, so sessions that write different keys don’t overwrite each other - Read again right before you write: for a value that several sessions change,
getthe key in the callback and build the new value from that, not from a copy you loaded atsession.start. Another session’s write is still lost if it lands between yourgetand yourset.
Next steps
- React to events: feed your drawing from tool calls and turns
- Use the mods API: feed your drawing from timers and model calls
- Test a drawing: press your buttons from a test, on more than one surface
- Render sites and elements: each site’s props and each element’s props