Skip to main content
skill CX Codex

moonframe — Claude Code skill for Luau UI work

A skill for Claude Code that helps build and adjust Moonframe interfaces. It activates for layout changes, styling, reusable components, mods, and providers.

MIT ★ 124 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add moonframehq/moonframe --skill moonframe -a claude-code
Open on GitHub

What moonframe does

The skill guides Luau changes to Moonframe’s interface, from panels and overlays to styles, components, mods, and providers. It also covers requests based on an Inspect Element selection and customising an installed app in ~/.config/moonframe.

For repository changes, edit files under app/; installed-app customisations go in ~/.config/moonframe. Luau edits reload as files change, so they do not need a Rust build. A native provider or a new element type does require Rust changes and an app restart.

What it helps with

  • Add a panel or overlay to a Moonframe window
  • Adjust colors, fonts, and spacing in style.luau
  • Extract a repeated interface element into a component
  • Create a mod or provider for the app

Example prompts for the agent

  • Add a side panel to Moonframe using Luau.
  • Restyle the window through style.luau.
  • Build a component that mods can reuse.

How to install moonframe

1Skills CLI (Vercel)

npx skills add moonframehq/moonframe --skill moonframe -a claude-code

2Manually: put the files in place

~/.claude/skills/moonframe/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/moonframe/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about moonframe

How do I install moonframe in Claude Code?

Run npx skills add moonframehq/moonframe --skill moonframe -a claude-code. The skill file is placed at ~/.claude/skills/moonframe/SKILL.md.

What does moonframe do?

It guides Luau work on Moonframe’s interface, including layout and styling changes, reusable components, mods, and providers. It also covers customising an installed app.

Do Luau interface changes require a Rust build?

No. The window reloads when Luau files change. Native providers and new element types require Rust changes and an app restart.

Source text

SKILL.md · MIT
---
name: moonframe
description: Build anything in Moonframe, a starter app whose window is laid out entirely by Luau. Covers panels, side panels, splits, toolbars, status bars, popovers, overlays (dialogs, command palettes, sheets, toasts) and their keys, mods and extensions, reusable components (`use`), live terminals (`ui.terminal`, kept by herdr-core or tmux across launches), state kept across launches (saved on its own, in herdr-core or SQLite), providers (Wasm, process, or native Rust built into the app, such as git, which also commits and pushes for a mod and answers it), icons, and styling through style.luau (colors, fonts, terminal fonts and Nerd Font icons, corners, shadows, spacing, animations). Also covers acting on the user's Inspect Element selection ("add X here"). Use whenever the task is to add, move, restyle or experiment with any UI in moonframe, to build a widget, component, provider or extension, or to customise the installed app in ~/.config/moonframe. The window reloads live as files change, so no Rust build is needed for Luau work.
---

# Moonframe

Luau describes every part of the window. Rust only checks the trees the
scripts return and draws them with GPUI. To change the UI, edit Luau under
`app/`, never Rust, unless the task needs a new element type (see "Extending
the host" below).

```text
app/
  main.luau              the shell: lays out the whole window
  style.luau             the stylesheet: colors, corners, fonts, rules (optional)
  mods/<name>/main.luau  a mod; the shell places it by region or by name
  components/<name>.luau a ready-made piece of view mods `use` (see below)
  providers/<name>/      a provider: data Luau can't produce (see below)
```

**Two folders, laid over each other.** The window loads the built-in app
(`app/` in this repository; `Contents/Resources/app` in an installed
bundle), then the user's folder, `~/.config/moonframe` (or
`$XDG_CONFIG_HOME/moonframe`), on top. Both have the layout above.
- A mod or provider in the user's folder replaces the built-in one of the
  same name, whole. A new name adds one.
- A user `main.luau` replaces the shell.
- A user `style.luau` is merged over the built-in one: each color and speed
  replaces the one of its name, each `mono` key replaces the app's
  (`mono = { size = 14 }` keeps its family), each rule's properties replace
  those of the same rule (`panel = { radius = 4 }` keeps the app's panel
  background), and any other key replaces the app's.
- Where to write: when working on this repository, edit `app/`. When the
  user wants to customise the app they use (or it is installed), write to
  `~/.config/moonframe` and never into the bundle, which is signed and
  replaced by each update. To change one built-in file, copy it to the same
  path there and edit the copy: it wins over the app's at once, and removing
  it brings the app's back. `moonframe doctor` names what in the folder breaks
  the app, `--fix` moves it to `.broken/`, and `--rollback` goes back to the
  newest snapshot that loads, a linked app's source included.
- The window watches both folders, so either kind of edit reloads live.
- **Packages** go between the two: mods others publish as git repositories,
  installed with `moonframe mod install` (see "Sharing mods"). A package
  never replaces the shell, and the user's folder goes over packages.

Layout and look are separate. Modules decide *what* goes *where*;
`style.luau` decides how it looks. Prefer a stylesheet rule or class over
repeating `style = { ... }` on many elements.

## Building something: where it goes

Pick the lowest layer that can do the job:

| The task needs | Build | Where | Rust build? |
| --- | --- | --- | --- |
| something on screen, from data Luau already has | a **mod** (or edit one) | `mods/<name>/main.luau` | no |
| the same piece of UI in several places | a **component** | `components/<name>.luau` | no |
| a shell or command line in the window | `ui.terminal` or `use "terminal"` | in a mod | no |
| tabs the user opens and closes, remembered | `use "tabbed"`, and a `tab` entry on what they show | in a mod | no |
| a widget with memory of its own, reusable | a component with `update` (an instance) | `components/<name>.luau` | no |
| several modules sharing a value | a topic: publish to `topic:<name>`, `subscribe` to it | in the mods | no |
| a web page in the window | `ui.browser` | in a mod | no |
| a text field, search box, prompt or text area | `ui.input` or `use "search-field"` | in a mod | no |
| data from the machine, files, network or a CLI | a **provider** feeding `app.<name>` | `providers/<name>/` | no (the host builds Wasm providers itself) |
| state that survives quitting the app (open panels, tabs, a choice) | nothing to add: every mod's state is saved; shape what comes back in `init` | the mod's `init` | no |
| git status, a file's diff, commit or push | read `app.git`; send `provider:git` a message | in a mod | no (git is built in) |
| markdown shown, or a project file read and saved | `ui.markdown` or `use "markdown"`; `use "markdown-editor"`, which reads and saves through `provider:docs` | in a mod | no (docs is built in) |
| a coding agent doing a task (Claude, Codex, Gemini...) | send `provider:acp` `{ start = ... }`; show the run with `use "agent-run"` | in a mod | no (acp is built in) |
| talking instead of typing (a prompt, a note) | `use "dictation"` beside the field; list the mod in `providers/speech`'s `recorders` | in a mod | no (speech is built in) |
| AI plan usage (Claude, Codex, Copilot limits, resets, pace) | read `app.usage`; draw each window with `use "usage-bar"` | in a mod | no (usage is built in) |
| a provider that needs a Rust library or answers actions | a **native provider** | `crates/` + `providers/<name>/provider.toml` | yes, and the app restarts |
| a look change | a rule in `style.luau`, or the mod's `styles` | | no |
| a new kind of element (tree, chart, image) | a host element | `crates/` | yes, and the app restarts |

Prefer what already exists. Check `app/components/` before writing a widget,
and the element table before asking for a host change. Live-reloaded Luau
keeps the user's window running; Rust changes don't.

### Recipes

**"Show me some ideas first."** When the user wants options or mockups
before a change, use the **moonframe-mockups** skill
(`.claude/skills/moonframe-mockups`): variants written as one Luau file on
the app's components, checked and shown by `moonframe mockup` (PNGs in a
Sheprd tab, or live in a Mockups tab), applied only once the user picks one.

**"Add X here."** Read `~/.cache/moonframe/selection.md`
(see "Here: the user's selection"). Open the file at the line it gives,
use a component if one fits, `just check`, and tell the user what you added
and where.

**A new panel in a side area.** Create `mods/<name>/main.luau` with
`region = "left"` (or `right`, `main`, `bottom`, `status`, `status-right`)
and a `view` returning `ui.panel { title = ..., grow = true, ... }`. It
appears without touching the shell.

**A status bar widget.** A mod with `region = "status-right"` (or
`status`) and `order` to place it. The view is a small `ui.row { align =
"center", gap = "small", ... }`, for example from `use "stat"`. Give
changing numbers a fixed width. For CPU and memory, `app.system` is
`{ cpu, cpu_history, memory, memory_used, memory_total, received,
transmitted }` (`cpu` and `memory` from 0 to 1, `memory_used` and
`memory_total` in bytes, the network in bytes a second); draw `cpu_history` with `use
"sparkline"` rather than keeping samples yourself. If you do keep samples
in state, see "Data that is really there".

**A widget with live data.** Read `app.<provider>`, and draw a placeholder
while it is nil. Read only fields its provider publishes (the provider
tables below, or its source), each tested for its type before use. If no
provider has the data, write one (see "Providers"). Never invent the data
in Luau unless it is labelled demo data.

**Something clickable that opens a sheet.** `ui.popover` around the
widget, with `open` in the mod's state (see "Sheets and menus").

**A dialog, command palette, side sheet or toast.** `ui.overlay` with
`open` in the mod's state, a `place`, and `keys` for Escape, Enter and the
arrows (see "Dialogs, palettes, sheets and toasts").

**A reusable piece.** A component with a good `example`, so it previews
in the Components window, then `use` it from the mod.

**Markdown.** To show it: `local markdown = use "markdown"`, then
`markdown { text = state.notes, grow = true, scroll = true, link =
"open-link" }` (or `ui.markdown`); a link click sends `{ msg = "open-link",
url = ... }` and opens nothing by itself, and pictures are not loaded. To
edit a project file: `local markdown_editor = use "markdown-editor"`, then
`markdown_editor { id = "readme", path = "README.md" }` in a growing
container; it reads and saves through the `docs` provider (see "Built-in
providers"), which takes saves only from its `writers` (`editor` as
shipped; add yours there as for git). In the starter, a markdown file
picked in the explorer opens in a main tab of this kind.

**A web page.** With browser chrome (back, forward, reload, an address
bar that navigates, the title): `local browser = use "browser"`, then
`browser { id = "docs", url = state.url, page = state.page, navigate =
{ navigated = true } }` and `state.page = msg` in `update`
(`app/components/demos/browser.luau` is the whole mod). A bare page:
`ui.browser { id = "docs", url = "https://example.com" }` inside a
container with `grow = true`, with buttons sending
`command = "browser-back", browser = "docs"` (see "Browsers").

**A terminal.** `local terminal = use "terminal"` and
`terminal { id = "main", cwd = "~/code" }` inside a container with
`grow = true` (see "Terminals").

**A search field.** Keep the query in state, pass it back as `value`, and
filter on it (`use "search-field"` wraps this; `mods/explorer` uses it):

```lua
update = function(state, msg)
	if msg.msg == "query" then state.query = msg.value          -- each edit
	elseif msg.msg == "clear" then state.query = ""              -- Esc empties it
	elseif msg.msg == "open" then return state, { { to = "editor", msg = { open = msg.value } } }
	end
end,
view = function(state)
	return ui.column {
		ui.input { id = "query", value = state.query, placeholder = "Search…",
			change = "query", submit = "open", keys = { escape = "clear" } },
		-- ...the rows that match state.query
	}
end,
```

For a palette, add `keys = { up = "prev", down = "next" }` and
`focus = state.open`.

**Mods that talk.** Send `msg = ..., to = "other"` from a control, or
return sends from `update`. Messages to `provider:<name>` go to a provider.

**Remember something across launches.** Every mod's state is saved on its
own and comes back to `init` as `previous` next launch (see "State that
outlives the app"). Keep from `previous` only what the user would expect
back (open panels, the tab they were on), and reset transient keys
(`loading`, `hover`, errors, an action still running) in `init`.

**Ask a provider to act, and show the answer.** Native providers answer
actions in the asking mod's `update` (a `Reply`, see "Built-in providers"):

```lua
-- in update
if msg == "commit" and not state.running then
	state.running = "commit"
	return state, { { to = "provider:git", msg = { commit = state.message, id = "mine" } } }
elseif type(msg) == "table" and msg.reply == "mine" then
	state.running = nil                                   -- show msg.message or msg.error
	state.result = { ok = msg.ok, text = msg.message or msg.error }
end
```

Show a spinner while `running` (a push may wait on the user's hardware
key), disable the button meanwhile, and show `error` as the user's next
step. git only takes writes from mods in `providers/git`'s
`[settings] writers` (as shipped, `status`). For a new mod, copy
`app/providers/git/` to `~/.config/moonframe/providers/git/` and add its
name to `writers` there (in this repository, edit `app/providers/git`
itself); otherwise it is refused with a reply saying so. `mods/status` is the full example (a commit sheet on the branch).

**Have a coding agent do something.** The `acp` provider runs Claude,
Codex, Gemini, OpenCode or Copilot over the Agent Client Protocol in the
app's repository and publishes each run as `app.acp.runs`; draw one with
`use "agent-run"` (status, plan, tool calls, its permission question, its
answer), whose buttons talk to the provider directly:

```lua
-- in update (the mod must be in providers/acp's `starters`)
return state, { { to = "provider:acp", msg = {
	start = state.text, id = "mine", agent = "claude",
	instructions = "How to do it, from the mod.",   -- before the user's words
	context = { main_tab = state.tab },             -- fenced as data, never instructions
	thread = previous.id,                           -- optional: a follow-up, shown with the run it continues
	app = true,                                     -- optional: the run changes this app (see below)
} } }
-- answered as { reply = "mine", action = "start", ok, run | error },
-- and when it ends { reply = "mine", action = "finished", ok, run, status, message | error }
-- in view
for _, run in (app.acp and app.acp.runs) or {} do
	if run.owner == "mine" then ... agent_run { run = run } ... end
end
```

Every tool the agent wants waits on the user in `agent-run`, unless the
user set the mod in `providers/acp`'s `[settings] allow`: `"read"` lets
tools that only look go without asking, `"app"` those plus edits inside the
app's own folder (never its `providers/`, `moonframe.toml` or
`packages.toml`) and the app's check command, `"all"` every tool, each
allowed once, never always. A mod can't ask for more; leave that setting
to the user (as shipped, `feedback = "app"`). Like git's
`writers`, a new mod goes in `starters` of a copy of `app/providers/acp`.

`app = true` marks a run that changes the app itself, as Make it yours
(`mods/feedback`) does. The window says which app that is (any app: the
starter, a profile, an installed one, or an app on the library whose
sources are in another repository), so the provider adds to the prompt
what the agent needs and nothing of this repository's tools: the folders
the window runs on, the one to write in, the exact command that checks the
app (its own executable with `--check`, about a second), a short guide
(crates/moonframe-acp/src/guide.md) and an index of the app's files with
their lengths. The app is checked as the run starts and after it ends, and
a run that added problems is undone, with a `warning` saying why. A host
adds its own notes with `Moonframe::agent_guide` and replaces the check
with `Moonframe::agent_check`. Send `{ warm = true, agent? }` when the
user opens what starts runs: the agent starts while they write, and the
next run takes it.

**Customising the installed app.** Write to `~/.config/moonframe`
(same layout as `app/`). Copy a built-in mod's folder there to change it.
Personal mods belong there, never in this repository. `just install` puts
the current build in `/Applications` so you can try them against it.

Then always: `just check`, `just types`, and if the user's window is open,
it has already reloaded.

## "Here": the user's selection

The user picks elements in the window with **View > Inspect Element**
(⌥⌘I), like a browser's developer tools. The pick is saved to
`~/.cache/moonframe/selection.md` (`$XDG_CACHE_HOME` if set), and the
user can copy the same text with **Copy for agent**:

```text
Selected in Moonframe (View > Inspect Element):
- element: button "Push"
- mod: status, drawn by /…/app/mods/status/main.luau:41
- inside: mod shell > column > … > region "status-right" > mod status > row > button "Push"
- drawn at 1412,876, 58×22 px
- a click sends { push = true, } to its mod's update
- state of status, as it is now:
  {
    menu = false,
    pushing = false,
  }
- reads from app (key = value now):
  app.git = { ahead = 2, branch = "main", dirty = 29, }
```

Besides where the element was built, the report holds what the window is
showing now: what a click on the element (or typing in an input) sends, the
state of the mod that drew it, the props it was drawn with when it is an
instance, each key of `app` its view read with its value (a provider's data
as the view saw it), and any problem the mod has. Values are Luau, cut to
fit (`-- 12 more`, `--[[ 300 more chars ]]`). The file is written again
while the element stays selected, whenever any of that changes, so read it
when you need it rather than relying on an old copy. Use the state and the
`app` values to write a change that fits the data it will meet, and to
explain what the user sees.

In an installed app the report has a `- read-only:` line when that file
ships in the signed bundle: copy it where it says and change the copy.

The pointer finds the deepest element under it. While picking, **↑**
targets the element around that one instead (a cell's row, the row's
`ui.list`, the list's panel) and **↓** steps back in; Enter or a click picks
the target. A level chosen with ↑ stays while the pointer moves over elements
of the same kind, so moving down a list keeps picking rows. The card lists
every element around the selection as an indented tree, with those inside it
down to what was under the pointer: hovering a row outlines that element in
the window, and clicking it selects it instead. So a selection may be a row
or panel the user chose on purpose, not just the leaf under the pointer.

**View > Developer Tools** (⌥⌘J, Developer Mode) shows the pick in a dock
on the right of the window (drawn around the shell, so no layout makes room
for it) or in a window of its own (drag the dock's grip out): the element and
its trail, its mod's Luau in a code editor (⌘S saves and the window reloads),
the mod's state, and agent sessions (the feedback mod's runs) that stay open.
It is `mods/devtools`; only it may send `app:devtools`. Every app has it,
profiles and library hosts alike, whatever their `keep`; the Agent tab
shows when the app also keeps `feedback`.

When the user says "here", "this", "the selected element" or "add X there"
without saying where, read that file first. The `file:line` is the `ui` call
that built the element. For an element a component built, it is the line in
the mod that used the component. Change or add next to that line. "Inside"
lists every element around it, outermost first, so "add a list here" on a
row means adding a child to that row; on a text, add a sibling. If the file
is missing, nothing is selected: ask, or pick a sensible place and say which.

**A mod can ask for a pick.** A button with `command = "inspect"` starts
picking for the mod that drew it. The card opens on the pick, so the user can
choose a level, with **Use this element** (or Enter) in place of Copy for
agent. That mod hears it on the
topic `app/inspect` (subscribe to it): `{ asker, picking = true }` as it
starts (hide a dialog then), and `{ asker, picking = false, picked, element?,
mod?, at?, report? }` when the user uses the element (`picked = true`;
`report` is the text above) or presses Escape. Only the mod that asked
hears it; if another mod starts a pick meanwhile, the first hears
`picked = false`. `mods/feedback` attaches the pick to a request this way, and the Copy button
beside its chip puts `report` on the clipboard for the user's own agent. The app's
quick inspect shortcut (`secondary-shift-x`; `inspect_shortcut` in
`settings.toml` names another, `""` none, followed live) starts the same
pick for `feedback` with the dialog closed, and using the pick opens it.
`app/` topics are the app's: a mod can't publish them, nor send another mod
a message passing for `app/` or `provider/` topic news.

"Copy for agent" copies that text and closes the card, but the file stays,
so the selection is still there for you. "Clear" (or Esc) deletes it. The
Components window's "Copy for agent" copies a request to add that component
at the current selection, with its usage. Treat either as the user's
instruction.

## Components: ready-made pieces

`components/<name>.luau` (in `app/` or `~/.config/moonframe`, which
wins by name) holds a component: a function from props to elements, plus
what the Components gallery shows. The user browses them, by category, in
their own window with **View > Components…** (⇧⌘K, Developer Mode). Each
gets its icon, a live preview of `example`, and its usage; **Copy for
agent** asks you to add it at the selection. Adding or editing a component
file updates the gallery live.

Use one in a mod with `use`, and call it wherever an element goes:

```lua
local stat = use "stat"
local list = use "list"

return mod {
	view = function(state, app)
		return ui.column {
			stat { icon = "cpu", label = "CPU", value = "12%", width = 32 },
			list { rows = state.rows, selected = state.selected },
		}
	end,
}
```

Before writing a widget, read the **moonframe-components** skill
(`.claude/skills/moonframe-components/SKILL.md`): the full catalogue of host
elements and components, with when to use each, their props, the classes
they style, and how to call them. `just check` lists the names too. After
adding or changing a component, run `just components` to regenerate that
catalogue (`just ci` fails when it is stale).

A new component looks like this:

```lua
return component {
	title = "Stat",                 -- the gallery name
	category = "Status bar",        -- its heading in the gallery
	icon = "cpu",                   -- beside its title in the browser
	description = "One line on what it is for.",
	-- For the catalogue: when to use it, and what to use instead.
	when = "One labelled value in a status bar. For a fraction use `meter`.",
	props = { value = "the text shown" },
	-- Default rules for its classes. They apply wherever it is used, under
	-- the mod's own styles and style.luau, which can restyle it.
	styles = {
		[".stat"] = { padding = { 2, 6 }, radius = 6 },
		[".stat:hover"] = { background = "accent/10" },
	},
	example = { value = "12%" },    -- props for the preview
	-- usage = [[...]],             -- Luau to show, when `example` holds elements
	build = function(props)
		return ui.row { class = "stat", ui.text { props.value } }
	end,
}
```

- `build` runs in the sandbox of the mod that uses it and returns elements
  like a `view`. Clicks it builds go to that mod's `update`.
- Without `usage`, the gallery shows `local x = use "name"` and a call
  with `example`. Give `usage` when the example has elements or children.
- Write components to work anywhere: their look goes in their own
  `styles` under classes named after them (`.tabs`, `.tabs-tab`,
  `.tabs-tab:selected`), in theme colors, so `style.luau` can restyle every
  part. Avoid inline `style` except for values computed from props (a
  meter's width). Nothing a mod must set up.
- Always give `when` and `props`; `just components` refuses a component
  without `when`.
- The preview is drawn from `example`, and a broken component shows its
  error in the gallery and in `just check`. Previews never start anything:
  a terminal shows a placeholder.
- A component can `use` another; one that uses itself is an error.
- **Demos.** The browser's preview is live: it runs a demo, a whole mod
  that uses the component, and shows that file as the code to copy. Write
  `components/demos/<name>.luau` (`return mod { init, update, view }`) for
  any component with clicks or state, so the user can play with it: a
  segmented control that switches, a dialog a button opens, a tree that
  folds. Keep it short, realistic and commented. Without one, the preview
  is a mod made from `example`, unless the component gives `usage`: then
  the preview is a still picture whose controls do nothing, so a component
  with `usage` and clicks needs a demo file. A demo runs in the gallery
  only: its messages reach only its own `update`, app commands do nothing,
  and its text fields edit (outside a demo they only show their text).
- Name it after what it is (`branch-list`, not `widget2`); the file name
  is the name `use` takes.
- Types: the definition file's type names (`IconName`, `Tone`, `Style`)
  are not visible to scripts, so annotate props with `string` or `any`,
  and cast where a `ui` field wants a union (`name = props.icon :: any`).

## Terminals

`ui.terminal` (or the `terminal` and `ghostty-terminal` components) shows a
live shell. The host runs it, so it can't be written in Luau:

- **What runs:** always the user's login shell. A mod chooses `cwd`, never
  a command, so the sandbox still can't run programs on its own.
- **Lifetime:** the host keeps one shell per mod and `id`. It survives
  reloads and hidden panes; with herdr-core or tmux it survives quitting
  the app too, and the next launch attaches to it again. It ends when the
  shell exits (Enter starts another). Two `id`s are two shells.
- **Backends:** `backend = "auto"` (default) runs it on herdr-core (`hc`)
  when installed (starting its server if needed), else tmux (a session per
  terminal on the app's own server: `tmux -L moonframe ls`, `tmux -L
  moonframe-<profile> ls` for a profile, `tmux -L <name> ls` for an app on
  the library; herdr-core labels each app's apart), else a local
  pty that ends with the app. `"herdr-core"`, `"tmux"` or `"pty"` asks for
  one; one that is missing falls back to the next. A faint label in the
  terminal's bottom-right corner names the backend in use.
- **What the shell does:** `shell = <msg>` sends the mod that message, with
  `event` added, as things happen: `"prompt"`, `"started"` (`command?`),
  `"finished"` (`command?`, `status?`, `took_ms`), `"folder"` (`path`,
  `host?`, which names the other machine in an `ssh` session), `"title"`
  (`title`), `"notice"` (`title?`, `body`: a program asking to tell the user
  something, as agents do when they wait). Only the mod that asked hears it,
  since a command line can hold a secret. Any program can print these
  sequences, even `cat` of a file: show them or notify, and never run
  anything because of one. zsh and fish report commands and folders by
  themselves; bash needs `[ -n "$MOONFRAME_SHELL_INTEGRATION" ] && .
  "$MOONFRAME_SHELL_INTEGRATION/moonframe.bash"` in `~/.bashrc`, and 4.4 or
  later to report commands (macOS's own 3.2 reports only its folder).
  `MOONFRAME_SHELL_INTEGRATION=0` in the app's environment turns it off, and
  shells already running under herdr-core or tmux get it once restarted. A
  tab from `tabbed` uses this itself: it takes its shell's folder or title
  as its name, and posts a notification for a notice, or for a command of
  10 s or more ending in a tab not on show. A tab not on show has a spinner
  while a command runs, and a dot once a program needs the user or a command
  ended, until it is shown. An agent reaches that dot by printing a notice
  (OSC 9 or 777).
- **Engines:** `engine = "alacritty"` (default, pure Rust) or `"ghostty"`
  (libghostty-vt). Both are cargo features of the `moonframe` crate; the
  starter builds both, an app on the library opts into `ghostty`.
  A build without one shows why in the element's place.
- **Sizing:** it grows to fill its container (give the container `grow`),
  and the shell is resized to match. Style it with a `terminal` rule or
  `style`: `background` and `color` set its default colors.
- **Font:** the stylesheet's `mono` sets it for every terminal: family,
  size, weight, line height, fallbacks, ligatures (see "Fonts" under
  "Stylesheet"). Icons showing as boxes in vim, starship or tmux status
  lines mean a missing Nerd Font; fix it there, not in the mod.
- **Input:** click to focus. While it has focus every key goes to the
  shell before the app's shortcuts: Tab (completion), Esc, Ctrl keys,
  arrows. ⌘V pastes (control characters are dropped from pastes, so they
  can't escape bracketed paste); other ⌘ shortcuts stay the app's. The
  scroll wheel moves through the scrollback.
- **Limits:** `id` is 1 to 64 of `a-z A-Z 0-9 - _`. A mod can have 8
  terminals and the app 32; past that the element shows why. Don't make
  ids from data (one per list row): each is a process.
- **In the component browser** a terminal shows a placeholder and starts
  no shell.

## Browsers

`ui.browser` shows a web page in a native web view the host runs (WebKit
on macOS, WebView2 on Windows). A mod gives it an address and reads back
where it went; it can't run scripts in the page.

```lua
ui.browser {
	id = "docs",                      -- one page per mod and id
	url = state.url,                  -- http, https or file
	navigate = { navigated = true },  -- arrives as { navigated = true, url, title, loading, back, forward }
	loading = "loading",              -- arrives as { msg = "loading", loading = true|false, url = ... }
	zoom = 1.25,                      -- 0.25 to 5
}
ui.button { "Back", command = "browser-back", browser = "docs" }
ui.input { id = "docs-address", value = state.page.url, browser = "docs" }  -- its address bar
```

- **Lifetime:** the host keeps one page per mod and `id`, like a terminal.
  It survives reloads and hidden panes (hidden, it keeps its place and
  history) and ends with the app.
- **`url`:** the page goes there when the mod passes an address different
  from the last one it passed. Links the user follows stand until then.
  To load the same address again, use `browser-reload`. Only `http://`,
  `https://` and `file://` addresses are read; anything else is an error
  that fails the mod's whole view, so never pass text the user typed as
  `url`: make the field an address bar (below), which also loads the
  address already shown, which a `url` the mod sets again cannot.
  The page itself may follow links only to those (and `about:blank`); a
  link that opens a new window opens in the same page, and downloads are
  refused.
- **Address bar:** `ui.input { browser = "<id>" }` (with `to = "mod"` for
  another mod's) drives the page itse...

© moonframehq · MIT · moonframehq/moonframe

Similar skills

All skills for Frontend and UI →

From the same set4

Project sponsors

Companies that keep this analytics open