@preset.nz/app-kit 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 preset.nz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# app-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The behaviour of a desktop app, shared across the preset.nz family: one command table feeding the native menu and the toolbar, Undo and Redo that say what they undo, Cmd+Z that never fights a text field, and a small selection store. [`ux-kit`](https://github.com/preset-nz/ux-kit) holds the look; app-kit holds how the app acts.
+
+An app declares its commands in Rust and plugs in its history. app-kit builds the menu bar, keeps Undo and Redo titled and gated, and hands the same table to the webview, so a label or an accelerator is written once.
+
+Two packages, one repo, one version:
+
+| Path | Package | What it is |
+|---|---|---|
+| `src/` | `preset-app-kit` (crate) | Command table, menu builder, `History` trait, Tauri commands |
+| `src-ts/` | `@preset.nz/app-kit` (npm) | `useCommands`, toolbar bridge, history hook, text-field undo, selection store |
+
+Pre-1.0: a minor version can break things, a patch never does. Crate and npm versions move together, and the TypeScript types mirror the serde shape by hand.
+
+The toolbar bridge renders ux-kit's `ToolbarItems`, so ux-kit is an optional peer; `@preset.nz/app-kit/core` needs none of it. ux-kit never depends on app-kit. Neither depends on rhizome: each app adapts its own history to the trait.
+
+## Rust
+
+```rust
+use preset_app_kit::{AppKit, Command, History, MenuName};
+
+impl History for Doc { /* undo_label, redo_label, undo_labels, redo_labels, undo, redo */ }
+
+tauri::Builder::default()
+    .manage(Doc::new())
+    .setup(|app| {
+        AppKit::<tauri::Wry>::new("My App")
+            .settings() // opt in: Settings… with Cmd+,
+            .commands([
+                Command::toggle("panel.left", "Show Outline")
+                    .accelerator("CmdOrCtrl+Alt+S")
+                    .toolbar_label("Outline")
+                    .menu(MenuName::View)
+                    .section(0),
+                Command::item("doc.reset", "Reset").accelerator("CmdOrCtrl+Alt+R").disabled(),
+            ])
+            .on_command(|app, id| match id { "app.settings" => { /* open it */ true } _ => false })
+            .install::<Doc>(app.handle())?; // Doc is the managed History
+        Ok(())
+    })
+    .invoke_handler(tauri::generate_handler![
+        preset_app_kit::app_kit_commands,
+        preset_app_kit::app_kit_menu_state,
+        preset_app_kit::app_kit_history,
+        preset_app_kit::app_kit_undo,
+        preset_app_kit::app_kit_redo,
+        preset_app_kit::app_kit_text_menu,
+    ])
+```
+
+- **`Command`**: id, menu label, optional toolbar label, Tauri accelerator, `MenuName` (App, File, Edit, View, Window, Help), `section` (items in a section sit together), item or toggle. Undo and Redo are built in; Settings is opt-in.
+- **File menu**: New, Open…, Open Recent ▸, Close, Save, Save As… and Revert to Saved… are built in, run against the app's `Document` behind the close guard. Revert is enabled only for an unsaved document with a file, and asks first, because reloading starts an empty history. Open Recent keeps ten documents, newest first, in `recent-documents.json` in the app's data directory; a file that has gone says so and leaves the list. `note_recent(app, path)` adds a document opened some other way (from the Finder, or by restore), and `recent_documents(app)[0]` is the last document. `.documents_folder(|app| …)` names where the Open and Save panels start for an Untitled document (`~/preset-nz/<App>/…`); the app supplies the lookup, so app-kit doesn't depend on app-folders.
+- **Relaunch**: `.plugin(preset_app_kit::window_state())` on the builder brings each window back at its size and position (`tauri-plugin-window-state`, not visibility). `on_run_event` reopens the last document at launch, the first entry of Open Recent, and opens a document the Finder hands over (double-click, `open some.x`, the Dock), which wins over the restored one. A last document that has gone, or won't load, becomes a note, not a dialog: register `app_kit_document_note` and show what `useDocumentNotes` hands you. For an app with documents, app-kit owns Finder opens, so don't add a second handler.
+- **Menu config**: `.menu_config(include_str!("../menu.toml"))` switches the built-in items on and off: `[file] new, open, open_recent, close, save, save_as, revert` and `[app] settings`. A missing key takes the default (on); an unknown key is an error, so add a test that calls `MenuConfig::parse` on your file. Labels, accelerators and positions stay the standard's. Design: guidance `projects/app-kit/design/menu-config.md`.
+- **Apps without documents**: `install_history::<H: History>` instead of `install::<H: Document>`, for a library such as Strata. The config must turn New, Open, Open Recent, Save, Save As and Revert off; with Close off too, Window gains Close Window on Cmd+W. No close guard, no window-title handling, and it doesn't register `tauri-plugin-dialog`, so the app keeps its own.
+- **`History`**: `undo_label`, `redo_label`, `undo_labels` (oldest first), `redo_labels` (next first), `undo`, `redo`. Implement it on the type you manage as Tauri state. The reads may lock, so call `refresh_history(app)` after a change and never while holding that lock.
+- **`edit_titles`**: the pure rule behind Edit > Undo: "Undo Set Opacity" when there is a step, plain and disabled when there is none, plain and enabled while a text field has focus.
+- **Events**: `command` (id, to the main window), `text-undo` (to the focused window), `app-kit://history` (a `HistoryState`), `app-kit://document` (a `DocumentState`), `app-kit://note` (a string).
+- Commands are plain Tauri commands, not a plugin, so no capability entries are needed.
+
+## TypeScript
+
+```tsx
+import { CommandToolbar, useCommands, nativeContextMenu } from "@preset.nz/app-kit"
+
+const { commands, run, shortcut } = useCommands(bindings) // bindings: Record<id, { icon, run, enabled, pressed, ... }>
+<CommandToolbar commands={commands} layout={{ leading: ["panel.left"], groups: [["edit.undo", "edit.redo"]] }} run={run} />
+```
+
+- **`useCommands(bindings)`**: loads the table from Rust, binds `run`, icon and gating by id, follows the history, routes text-field undo and keeps the menu's enabled and checked state in step. `edit.undo` and `edit.redo` need only an icon. `bindCommands`, `useCommandTable`, `useMenuSync`, `toItems` are the parts.
+- **`CommandToolbar`**: ux-kit's `ToolbarItems` fed from the commands.
+- **`@preset.nz/app-kit/core`**: everything except `CommandToolbar` and `toItems`, with no ux-kit import, for apps that use only the menu half. ux-kit is an optional peer.
+- **`useDocument`, `useDocumentNotes(onNote)`**: the live `DocumentState`, and notes about the document (a last document that wouldn't reopen), each delivered once. Show a note as a snackbar.
+- **`useHistory`, `undo`, `redo`**: the live `HistoryState`, and the same undo the menu takes. The Inspector's History list reads `undoLabels` and `redoLabels`.
+- **`useTextUndo`, `useTextFocus`, `isTextField`, `blurField`**: Cmd+Z undoes typing while a text field has focus, the document otherwise.
+- **`createSelection<T>(none)`**: single-select store with `get`, `use`, `select`, `clear`. **`createMultiSelection<T>(key)`**: the opt-in multi-select. **`createStore`, `useStore`**: the small store under both. Wrap them in your own narrow setters; there is no `setSelection`, and selection is not an undo step.
+- **`nativeContextMenu()`**: no WebKit context menu. Right-click in a text field pops up a short native menu (Undo, Redo, Cut, Copy, Paste, Select All; needs `app_kit_text_menu` registered); elsewhere nothing, and app-drawn menus still open.
+
+The table arrives from Rust, so a plain browser tab (`just dev-web` in the playground) has no commands and an empty toolbar.
+
+## Consuming it
+
+```toml
+# src-tauri/Cargo.toml
+preset-app-kit = "0.1"
+```
+
+```sh
+pnpm add @preset.nz/app-kit
+```
+
+`@preset.nz/app-kit/core` is everything except the toolbar, for an app that doesn't use ux-kit; ux-kit is an optional peer.
+
+In Vite, add `@preset.nz/app-kit` (with `react`, `react-dom`, `@tauri-apps/api`, `@preset.nz/ux-kit`) to `resolve.dedupe`; a second copy of React fails only in the window. app-kit ships no Tailwind classes, so it needs no `@source` line.
+
+## Development
+
+`just check` runs `cargo fmt --check`, clippy, `cargo test`, `tsc` and eslint. MIT.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@preset.nz/app-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "The behaviour of a preset.nz desktop app: command table, menu sync, Undo and Redo titles, text-field undo routing and a selection store, over the preset-app-kit Rust crate.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/preset-nz/app-kit.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src-ts/index.ts",
+    "./core": "./src-ts/core.ts"
+  },
+  "files": [
+    "src-ts"
+  ],
+  "peerDependencies": {
+    "@preset.nz/ux-kit": "^0.1.0",
+    "@tauri-apps/api": "^2",
+    "react": "^19"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@preset.nz/ux-kit": "^0.1.0",
+    "@tauri-apps/api": "^2.11.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.3",
+    "globals": "^16.5.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.61.1"
+  },
+  "peerDependenciesMeta": {
+    "@preset.nz/ux-kit": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src-ts/CommandToolbar.tsx

@@ -0,0 +1,25 @@
+import type { ComponentProps } from "react"
+import { ToolbarItems } from "@preset.nz/ux-kit"
+
+import type { Command } from "./commands"
+import { toItems, type ToolbarLayout } from "./toolbar"
+
+type Props = Omit<ComponentProps<typeof ToolbarItems>, "groups" | "leading" | "trailing" | "onCommand"> & {
+  commands: Command[]
+  layout: ToolbarLayout
+  /** From `useCommands`: runs the command the menu would. */
+  run: (id: string) => void
+}
+
+/** ux-kit's `ToolbarItems`, fed from the command table: same labels, shortcuts and gating as the menu. */
+export function CommandToolbar({ commands, layout, run, ...props }: Props) {
+  return (
+    <ToolbarItems
+      {...props}
+      leading={toItems(commands, layout.leading)}
+      groups={layout.groups.map((ids) => toItems(commands, ids))}
+      trailing={toItems(commands, layout.trailing)}
+      onCommand={run}
+    />
+  )
+}

package/src-ts/commands.ts

@@ -0,0 +1,138 @@
+import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react"
+import { invoke } from "@tauri-apps/api/core"
+
+import { redo, undo, useHistory, type HistoryState } from "./history"
+import { useTextUndo } from "./text"
+import { useMenuSync } from "./useMenuSync"
+
+/** A command as Rust declares it (`CommandInfo`): the one place ids, labels and accelerators live. */
+export interface CommandSpec {
+  id: string
+  /** Menu text. */
+  label: string
+  /** Toolbar text, when it differs from the menu's. */
+  toolbarLabel: string | null
+  /** Tauri accelerator string, `CmdOrCtrl+Alt+S`. */
+  accelerator: string | null
+  /** Display form for tooltips, `⌥⌘S`. */
+  shortcut: string | null
+  menu: "app" | "file" | "edit" | "view" | "domain" | "window" | "help"
+  /** The domain menu's title ("Effect"), for `menu: "domain"`. */
+  domain: string | null
+  /** The submenu of its section ("Add"), if any. */
+  submenu: string | null
+  /** The op's own category and tags, for the Add submenu, the library and the palette. */
+  category: string | null
+  tags: string[]
+  kind: "item" | "toggle"
+}
+
+/** What the app attaches to a command id: what it does, how it looks, when it is available. */
+export interface Binding {
+  icon?: ReactNode
+  /** Only for text that depends on state ("Light mode" / "Dark mode"). Otherwise the table's label shows. */
+  label?: string
+  /** Default true. */
+  enabled?: boolean
+  disabledReason?: string
+  /** For toggles. */
+  pressed?: boolean
+  run?: () => void
+}
+
+/** A command bound on both sides: the table's text and shortcut, the app's `run`, icon and gating. */
+export interface Command {
+  id: string
+  label: string
+  icon: ReactNode
+  shortcut?: string
+  enabled: boolean
+  disabledReason?: string
+  /** Present for toggles. */
+  pressed?: boolean
+  run: () => void
+}
+
+/** The command table from Rust. Null until it arrives (a few milliseconds; never in a plain browser tab). */
+export function useCommandTable(): CommandSpec[] | null {
+  const [table, setTable] = useState<CommandSpec[] | null>(null)
+  useEffect(() => {
+    invoke<CommandSpec[]>("app_kit_commands").then(setTable, () => {})
+  }, [])
+  return table
+}
+
+/** Undo and redo are built in: their text, gating and action come from the history. */
+function historyBindings(h: HistoryState | null): Record<string, Binding> {
+  return {
+    "edit.undo": {
+      label: h?.undoLabel ? `Undo ${h.undoLabel}` : "Undo",
+      enabled: h?.undoLabel != null,
+      disabledReason: "Nothing to undo",
+      run: () => void undo(),
+    },
+    "edit.redo": {
+      label: h?.redoLabel ? `Redo ${h.redoLabel}` : "Redo",
+      enabled: h?.redoLabel != null,
+      disabledReason: "Nothing to redo",
+      run: () => void redo(),
+    },
+  }
+}
+
+/**
+ * Bind the table to the app's behaviour by id. Commands with no binding (or no `run`) stay
+ * menu-only. For `edit.undo` and `edit.redo` a binding supplies just the icon; the rest is the history's.
+ */
+export function bindCommands(
+  table: CommandSpec[],
+  bindings: Record<string, Binding>,
+  history: HistoryState | null = null,
+): Command[] {
+  const builtin = historyBindings(history)
+  return table.flatMap((spec) => {
+    const b: Binding = { ...bindings[spec.id], ...builtin[spec.id] }
+    const bound = spec.id in bindings || spec.id in builtin
+    if (!bound || !b.run) return []
+    return [
+      {
+        id: spec.id,
+        label: b.label ?? spec.toolbarLabel ?? spec.label,
+        icon: b.icon ?? null,
+        shortcut: spec.shortcut ?? undefined,
+        enabled: b.enabled ?? true,
+        disabledReason: b.disabledReason,
+        pressed: spec.kind === "toggle" ? (b.pressed ?? false) : b.pressed,
+        run: b.run,
+      },
+    ]
+  })
+}
+
+/**
+ * The app's whole command wiring in one hook: loads the table, binds it, follows the history,
+ * routes text-field undo, and keeps the native menu's enabled and checked state in step.
+ * `bindings` should be memoised; the commands are rebuilt when it changes.
+ */
+export function useCommands(bindings: Record<string, Binding>) {
+  const table = useCommandTable()
+  const history = useHistory()
+  const textFocus = useTextUndo()
+  const commands = useMemo(
+    () => (table ? bindCommands(table, bindings, history) : []),
+    [table, bindings, history],
+  )
+  useMenuSync(commands, textFocus)
+
+  /** Run a command by id, as the menu does: only when enabled. */
+  const run = useCallback(
+    (id: string) => {
+      const c = commands.find((x) => x.id === id)
+      if (c?.enabled) c.run()
+    },
+    [commands],
+  )
+  /** A command's display shortcut, for anything that shows one (a panel header's tooltip). */
+  const shortcut = useCallback((id: string) => table?.find((s) => s.id === id)?.shortcut ?? undefined, [table])
+  return { commands, run, shortcut, history }
+}

package/src-ts/core.ts

@@ -0,0 +1,23 @@
+// The menu half of app-kit: commands, history, text-field undo, selection and stores, with
+// no dependency on ux-kit. `index.ts` adds the toolbar bridge on top.
+export {
+  bindCommands,
+  useCommands,
+  useCommandTable,
+  type Binding,
+  type Command,
+  type CommandSpec,
+} from "./commands"
+export { useDocument, useDocumentNotes, type DocumentState } from "./document"
+export { redo, undo, useHistory, type HistoryState } from "./history"
+export { nativeContextMenu } from "./nativeContextMenu"
+export {
+  createMultiSelection,
+  createSelection,
+  insertIndex,
+  type MultiSelection,
+  type Selection,
+} from "./selection"
+export { createStore, useStore, type Store } from "./store"
+export { blurField, isTextField, useTextFocus, useTextUndo } from "./text"
+export { useMenuSync } from "./useMenuSync"

package/src-ts/document.ts

@@ -0,0 +1,58 @@
+import { useEffect, useRef, useState } from "react"
+import { invoke } from "@tauri-apps/api/core"
+import { listen } from "@tauri-apps/api/event"
+
+/** The document as Rust reports it (`DocumentState`): from `app_kit_document`, pushed as `app-kit://document`. */
+export interface DocumentState {
+  /** `Untitled-1` or the file's name. */
+  name: string
+  path: string | null
+  unsaved: boolean
+  /** The window title: the name, then ` *` while unsaved. Rust sets it; shown here for reference. */
+  title: string
+}
+
+/** The live document state, or null until the first read. The status bar reads `unsaved`. */
+export function useDocument(): DocumentState | null {
+  const [state, setState] = useState<DocumentState | null>(null)
+  useEffect(() => {
+    let live = true
+    invoke<DocumentState>("app_kit_document").then(
+      (s) => live && setState((cur) => cur ?? s),
+      () => {},
+    )
+    const un = listen<DocumentState>("app-kit://document", (e) => setState(e.payload))
+    return () => {
+      live = false
+      un.then((f) => f())
+    }
+  }, [])
+  return state
+}
+
+/**
+ * Notes about the document for the app to show, such as a last document that wouldn't reopen
+ * at launch. Each arrives once: the ones held from before the webview listened, then any later
+ * `app-kit://note`. Show them as the app shows a passing message (a snackbar), never a dialog.
+ */
+export function useDocumentNotes(onNote: (message: string) => void): void {
+  const handler = useRef(onNote)
+  useEffect(() => {
+    handler.current = onNote
+  }, [onNote])
+  useEffect(() => {
+    let live = true
+    const un = listen<string>("app-kit://note", (e) => handler.current(e.payload))
+    // Ask only once listening, so nothing falls between the held notes and the event. And only
+    // while still mounted: taking them is once-only, so an unmounted effect (StrictMode mounts
+    // twice in dev) must leave them for the next.
+    un.then(() => (live ? invoke<string[]>("app_kit_document_note") : [])).then(
+      (held) => live && held.forEach((m) => handler.current(m)),
+      () => {},
+    )
+    return () => {
+      live = false
+      un.then((f) => f())
+    }
+  }, [])
+}

package/src-ts/history.ts

@@ -0,0 +1,46 @@
+import { useEffect, useState } from "react"
+import { invoke } from "@tauri-apps/api/core"
+import { listen } from "@tauri-apps/api/event"
+
+import { blurField } from "./text"
+
+/** The history as Rust reports it (`HistoryState`): from the `app_kit_history` command, pushed as `app-kit://history`. */
+export interface HistoryState {
+  undoLabel: string | null
+  redoLabel: string | null
+  /** Steps done. */
+  historyLen: number
+  /** Oldest first. */
+  undoLabels: string[]
+  /** Next first. */
+  redoLabels: string[]
+}
+
+/** The live history, or null until the first read. */
+export function useHistory(): HistoryState | null {
+  const [state, setState] = useState<HistoryState | null>(null)
+  useEffect(() => {
+    let live = true
+    invoke<HistoryState>("app_kit_history").then(
+      (s) => live && setState((cur) => cur ?? s),
+      () => {},
+    )
+    const un = listen<HistoryState>("app-kit://history", (e) => setState(e.payload))
+    return () => {
+      live = false
+      un.then((f) => f())
+    }
+  }, [])
+  return state
+}
+
+/** Undo one step, the one the menu item takes. Blurs a focused field first so its text commits as an edit. */
+export function undo(): Promise<void> {
+  blurField()
+  return invoke<void>("app_kit_undo")
+}
+
+export function redo(): Promise<void> {
+  blurField()
+  return invoke<void>("app_kit_redo")
+}

package/src-ts/index.ts

@@ -0,0 +1,5 @@
+// Everything: the core plus the ux-kit toolbar bridge. Apps without ux-kit import
+// "@preset.nz/app-kit/core" instead.
+export * from "./core"
+export { CommandToolbar } from "./CommandToolbar"
+export { toItems, type ToolbarLayout } from "./toolbar"

package/src-ts/nativeContextMenu.ts

@@ -0,0 +1,22 @@
+import { invoke } from "@tauri-apps/api/core"
+
+import { isTextField } from "./text"
+
+/**
+ * Native context menus only (native-apps.md): right-click opens an app-drawn menu, the short
+ * native text menu, or nothing, never WebKit's Look Up / Translate / Inspect Element.
+ *  - In an editable text field: WebKit's menu is prevented and `app_kit_text_menu` pops up a
+ *    native Undo / Redo / Cut / Copy / Paste / Select All at the pointer.
+ *  - Anywhere else: nothing.
+ *  - App-drawn menus (the kit's ContextMenu) call preventDefault themselves; this leaves them be.
+ * Returns the cleanup.
+ */
+export function nativeContextMenu(): () => void {
+  const onContextMenu = (e: MouseEvent) => {
+    if (e.defaultPrevented) return
+    e.preventDefault()
+    if (isTextField(e.target)) void invoke("app_kit_text_menu")
+  }
+  document.addEventListener("contextmenu", onContextMenu)
+  return () => document.removeEventListener("contextmenu", onContextMenu)
+}

package/src-ts/selection.ts

@@ -0,0 +1,81 @@
+// Interaction state, kept out of the document (guidance/design/interaction-state.md): small
+// stores, a discriminated union, narrow setters, no `setSelection`. Selection is not an undo
+// step: undo and redo leave it alone. A selection whose target is gone must read as none; the
+// app knows what exists, so it resolves the item against its document before using it.
+//
+// An app wraps these in its own narrow setters, `selectLayer = (id) => layer.select({ kind: "layer", id })`,
+// and exports those, never the store.
+
+import { createStore, useStore } from "./store"
+
+/** One selected item of type `T`, or `none`. `T` is usually a discriminated union with a `none` member. */
+export interface Selection<T> {
+  get(): T
+  /** Read from a component. */
+  use(): T
+  select(item: T): void
+  /** Back to `none`. */
+  clear(): void
+  subscribe(listener: () => void): () => void
+}
+
+/** A single-select store. `none` is the value that means nothing is selected. */
+export function createSelection<T>(none: T): Selection<T> {
+  const store = createStore<T>(none)
+  return {
+    get: store.get,
+    use: () => useStore(store),
+    select: (item) => store.set(item),
+    clear: () => store.set(none),
+    subscribe: store.subscribe,
+  }
+}
+
+/** Several selected items. Opt in where an app has multi-select; most do not. */
+export interface MultiSelection<T> {
+  get(): readonly T[]
+  use(): readonly T[]
+  has(item: T): boolean
+  /** Replace the selection with one item. */
+  select(item: T): void
+  /** Replace the selection with these items. */
+  selectMany(items: readonly T[]): void
+  /** Add the item, or remove it when already selected. */
+  toggle(item: T): void
+  add(item: T): void
+  remove(item: T): void
+  clear(): void
+  subscribe(listener: () => void): () => void
+}
+
+/** A multi-select store. `key` says when two items are the same item. Order is selection order. */
+export function createMultiSelection<T>(key: (item: T) => string): MultiSelection<T> {
+  const store = createStore<readonly T[]>([])
+  const has = (item: T) => store.get().some((x) => key(x) === key(item))
+  const without = (item: T) => store.get().filter((x) => key(x) !== key(item))
+  return {
+    get: store.get,
+    use: () => useStore(store),
+    has,
+    select: (item) => store.set([item]),
+    selectMany: (items) => store.set([...items]),
+    toggle: (item) => store.set(has(item) ? without(item) : [...store.get(), item]),
+    add: (item) => {
+      if (!has(item)) store.set([...store.get(), item])
+    },
+    remove: (item) => store.set(without(item)),
+    clear: () => store.set([]),
+    subscribe: store.subscribe,
+  }
+}
+
+/**
+ * Where a new item goes (`ux-patterns.md`, menu-standard decision 6): straight after the selected
+ * item, or at the end when nothing in `items` is selected. Returns the index to insert at.
+ */
+export function insertIndex<T>(items: readonly T[], isSelected: (item: T) => boolean): number {
+  for (let i = items.length - 1; i >= 0; i--) {
+    if (isSelected(items[i])) return i + 1
+  }
+  return items.length
+}

package/src-ts/store.ts

@@ -0,0 +1,29 @@
+import { useSyncExternalStore } from "react"
+
+/** A tiny external store: one value, subscribers, no setter wider than the owner chooses to export. */
+export interface Store<T> {
+  get(): T
+  set(next: T): void
+  subscribe(listener: () => void): () => void
+}
+
+export function createStore<T>(initial: T): Store<T> {
+  let state = initial
+  const listeners = new Set<() => void>()
+  return {
+    get: () => state,
+    set(next) {
+      if (Object.is(next, state)) return
+      state = next
+      listeners.forEach((l) => l())
+    },
+    subscribe(l) {
+      listeners.add(l)
+      return () => void listeners.delete(l)
+    },
+  }
+}
+
+/** Read a store from a component; it re-renders when the value changes. */
+export const useStore = <T>(store: Pick<Store<T>, "get" | "subscribe">): T =>
+  useSyncExternalStore(store.subscribe, store.get)

package/src-ts/text.ts

@@ -0,0 +1,77 @@
+import { useEffect, useState } from "react"
+import { getCurrentWebviewWindow } from "@tauri-apps/api/webviewWindow"
+
+const TEXT_INPUT_TYPES = new Set(["", "text", "search", "url", "email", "tel", "password", "number"])
+
+/** True for elements that have their own typing undo: text inputs, textareas, contenteditable. */
+export function isTextField(el: EventTarget | Element | null): boolean {
+  if (!(el instanceof HTMLElement)) return false
+  if (el instanceof HTMLTextAreaElement) return !el.readOnly && !el.disabled
+  if (el instanceof HTMLInputElement) return TEXT_INPUT_TYPES.has(el.type) && !el.readOnly && !el.disabled
+  return el.isContentEditable
+}
+
+/**
+ * Whether an editable text field has focus in this window. Checkbox, colour, range and other
+ * non-text inputs do not count.
+ */
+export function useTextFocus(): boolean {
+  const [focused, setFocused] = useState(() => isTextField(document.activeElement))
+  useEffect(() => {
+    const onIn = (e: FocusEvent) => setFocused(isTextField(e.target))
+    const onOut = (e: FocusEvent) => setFocused(isTextField(e.relatedTarget))
+    // The window losing focus keeps document.activeElement; the menu must not treat it as typing.
+    const onWinBlur = () => setFocused(false)
+    const onWinFocus = () => setFocused(isTextField(document.activeElement))
+    document.addEventListener("focusin", onIn)
+    document.addEventListener("focusout", onOut)
+    window.addEventListener("blur", onWinBlur)
+    window.addEventListener("focus", onWinFocus)
+    return () => {
+      document.removeEventListener("focusin", onIn)
+      document.removeEventListener("focusout", onOut)
+      window.removeEventListener("blur", onWinBlur)
+      window.removeEventListener("focus", onWinFocus)
+    }
+  }, [])
+  // WebKit fires no focusout when the focused field is removed from the page (a name field
+  // that unmounts on Enter), which would leave Undo stuck on the field. While a field has
+  // focus, recheck whenever nodes go away.
+  useEffect(() => {
+    if (!focused) return
+    const observer = new MutationObserver(() => {
+      if (!isTextField(document.activeElement)) setFocused(false)
+    })
+    observer.observe(document.body, { childList: true, subtree: true })
+    return () => observer.disconnect()
+  }, [focused])
+  return focused
+}
+
+/**
+ * Text fields keep their native typing undo. Edit > Undo and Redo are custom menu items, so
+ * the menu would swallow Cmd+Z; instead, while a text field has focus:
+ *   1. this hook reports `textFocus` (`useCommands` passes it to `useMenuSync`, which sends it);
+ *   2. Rust shows plain "Undo" and "Redo" and, on select, emits `text-undo` ("undo" | "redo")
+ *      to the focused window instead of touching the document;
+ *   3. this hook runs `document.execCommand` on the focused field.
+ * Fields commit on blur or Enter as one labelled edit, so the two undo scopes do not overlap.
+ * `execCommand` is deprecated but is the only way to drive WebKit's field undo stack.
+ */
+export function useTextUndo(): boolean {
+  const textFocus = useTextFocus()
+  useEffect(() => {
+    const un = getCurrentWebviewWindow().listen<"undo" | "redo">("text-undo", (e) => {
+      document.execCommand(e.payload)
+    })
+    return () => {
+      un.then((f) => f())
+    }
+  }, [])
+  return textFocus
+}
+
+/** Commit a focused field (its onBlur) before a document-level undo or redo from a button. */
+export function blurField() {
+  if (document.activeElement instanceof HTMLElement) document.activeElement.blur()
+}

package/src-ts/toolbar.ts

@@ -0,0 +1,31 @@
+import type { ToolbarItemSpec } from "@preset.nz/ux-kit"
+
+import type { Command } from "./commands"
+
+// The ux-kit half of the command wiring. Kept apart from `commands.ts` so the `./core` entry
+// never reaches ux-kit, for apps that only use the menu half (Strata, Fault).
+
+/** The toolbar is a subset of the commands: these ids, in this order, in these groups. */
+export interface ToolbarLayout {
+  leading?: string[]
+  groups: string[][]
+  trailing?: string[]
+}
+
+export function toItems(commands: Command[], ids: string[] = []): ToolbarItemSpec[] {
+  return ids.flatMap((id) => {
+    const c = commands.find((x) => x.id === id)
+    if (!c) return []
+    return [
+      {
+        id: c.id,
+        label: c.label,
+        icon: c.icon,
+        shortcut: c.shortcut,
+        enabled: c.enabled,
+        disabledReason: c.disabledReason,
+        pressed: c.pressed,
+      },
+    ]
+  })
+}

package/src-ts/useMenuSync.ts

@@ -0,0 +1,42 @@
+import { useEffect, useRef } from "react"
+import { invoke } from "@tauri-apps/api/core"
+import { getCurrentWebviewWindow } from "@tauri-apps/api/webviewWindow"
+
+import type { Command } from "./commands"
+
+/** Rust owns these: Undo and Redo follow the history, Revert to Saved… the document. */
+const RUST_GATED_IDS = new Set(["edit.undo", "edit.redo", "file.revert"])
+
+/**
+ * Connects the commands to the native menu: menu items arrive as `command` events carrying
+ * the command id, and enabled and checked state goes back through `app_kit_menu_state`.
+ * Undo and redo are not sent; Rust sets their titles from the history, or from `textFocus`
+ * (see text.ts) while a text field has focus.
+ */
+export function useMenuSync(commands: Command[], textFocus: boolean) {
+  const latest = useRef(commands)
+  // Declared before the effects below, so they see the commands of this render.
+  useEffect(() => {
+    latest.current = commands
+  })
+
+  useEffect(() => {
+    const un = getCurrentWebviewWindow().listen<string>("command", (e) => {
+      const c = latest.current.find((x) => x.id === e.payload)
+      if (c?.enabled) c.run()
+    })
+    return () => {
+      un.then((f) => f())
+    }
+  }, [])
+
+  const key = JSON.stringify(commands.map((c) => [c.id, c.enabled, c.pressed])) + textFocus
+  useEffect(() => {
+    const states = latest.current
+      .filter((c) => !RUST_GATED_IDS.has(c.id))
+      .map((c) => ({ id: c.id, enabled: c.enabled, checked: c.pressed }))
+    invoke("app_kit_menu_state", { states, textFocus }).catch(() => {})
+    // `key` stands for the commands' menu-relevant state; `latest` holds the commands.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key])
+}