@preset.nz/app-kit 0.1.2 → 0.1.4

package/README.md

@@ -49,9 +49,21 @@ tauri::Builder::default()
     ])
 ```
 
+- **Models (cargo feature `models`)**: `preset_app_kit::models::install(app.handle(), "nz.preset.myapp", "My App", REGISTRY)` in `setup` (separate from `AppKit::install`). Call it from the synchronous `setup`, never from async code: the downloader is reqwest's blocking client, which panics on a tokio worker thread. It manages the store, writes `.users/<bundle-id>.json`, sweeps stale `.part` files and emits `app-kit://models` (`{ id, status }`, at most four a second per download, plus every status change). It returns the `ModelStore`; `store.path("mobile_sam")` gives a sidecar its `model_dir`. Add the commands beside the others:
+
+  ```rust
+  preset_app_kit::app_kit_models_list,
+  preset_app_kit::app_kit_models_download,
+  preset_app_kit::app_kit_models_cancel,
+  preset_app_kit::app_kit_models_remove,
+  preset_app_kit::app_kit_models_path,
+  ```
+
+  `status` is a tagged object (`{ "kind": "downloading", "done": 1, "total": 2 }`). The list includes models this app never declared (from their manifests), and any of them can be removed. The webview never receives a URL.
+  In the Settings window of `@preset.nz/preferences` (app-kit depends on neither it nor facets, so these lines live in the app): `registerFieldRenderer("models", () => <ModelsSection />)`, then `<SettingsWindow extraGroups={[{ page: "general", group: { id: "models", title: "Models", rows: [{ kind: "models", id: "models" }] } }]} />` with the array at module scope. The recipe is in preferences' README.
 - **`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.
+- **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), 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**: the app starts on a fresh Untitled document; it does not reopen the last one (that is File > Open Recent's first entry). `.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` opens a document the Finder hands over (double-click, `open some.x`, the Dock). 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.
@@ -71,13 +83,13 @@ const { commands, run, shortcut } = useCommands(bindings) // bindings: Record<id
 - **`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.
+- **`useDocument`**: the live `DocumentState`.
 - **`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.
+The table arrives from Rust. Apps run only in their Tauri window; a plain browser tab is not a supported host.
 
 ## Consuming it
 

package/package.json

@@ -1,36 +1,38 @@
 {
   "name": "@preset.nz/app-kit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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"
+    "url": "git+https://github.com/preset-nz/packages.git",
+    "directory": "app-kit"
   },
   "type": "module",
   "sideEffects": false,
   "exports": {
     ".": "./src-ts/index.ts",
-    "./core": "./src-ts/core.ts"
+    "./core": "./src-ts/core.ts",
+    "./models": "./src-ts/models/index.ts"
   },
   "files": [
     "src-ts"
   ],
   "peerDependencies": {
-    "@preset.nz/ux-kit": "^0.1.0",
+    "@preset.nz/ux-kit": "^0.1.2",
     "@tauri-apps/api": "^2",
     "react": "^19"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.15",
-    "@preset.nz/ux-kit": "^0.1.0",
     "@tauri-apps/api": "^2.11.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "lefthook": "^2.1.17",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "typescript": "~5.9.3"
+    "typescript": "~7.0.2",
+    "@preset.nz/ux-kit": "^0.1.2"
   },
   "peerDependenciesMeta": {
     "@preset.nz/ux-kit": {

package/src-ts/document.ts

@@ -1,6 +1,6 @@
 import { invoke } from "@tauri-apps/api/core"
 import { listen } from "@tauri-apps/api/event"
-import { useEffect, useRef, useState } from "react"
+import { useEffect, useState } from "react"
 
 /** The document as Rust reports it (`DocumentState`): from `app_kit_document`, pushed as `app-kit://document`. */
 export interface DocumentState {
@@ -31,30 +31,7 @@ export function useDocument(): DocumentState | null {
 }
 
 /**
- * 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.
+ * Kept so apps built against 0.1 still compile: launch no longer reopens the last document, so
+ * there are no notes to show. Remove the call when convenient.
  */
-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) => {
-        if (live) for (const m of held) handler.current(m)
-      },
-      () => {},
-    )
-    return () => {
-      live = false
-      un.then((f) => f())
-    }
-  }, [])
-}
+export function useDocumentNotes(_onNote: (message: string) => void): void {}

package/src-ts/models/ModelPromptHost.tsx

@@ -0,0 +1,68 @@
+import { DownloadPrompt, formatBytes } from "@preset.nz/ux-kit"
+import { useEffect, useSyncExternalStore } from "react"
+
+import type { ModelsApi } from "./api"
+import { useModelsContext } from "./context"
+import { useModels } from "./useModels"
+
+type PromptState = "ask" | "downloading" | "failed"
+
+/**
+ * Renders the prompt `ensure` opens. Mount it once near the app root. The state comes from the
+ * model's status: not Ready and not asked is "ask"; asked and downloading is the bar; asked and
+ * failed is the reason with Retry; Ready resolves the `ensure`.
+ */
+export function ModelPromptHost({ api }: { api?: ModelsApi }) {
+  const { gate, api: contextApi } = useModelsContext()
+  const request = useSyncExternalStore(gate.subscribe, gate.snapshot)
+  const { models, download, cancel } = useModels(api ?? contextApi)
+  const info = request ? models.find((m) => m.id === request.id) : undefined
+  const ready = info?.status.kind === "ready"
+
+  useEffect(() => {
+    if (request && ready) gate.succeed()
+  }, [request, ready, gate])
+
+  let state: PromptState | null = null
+  if (request && info && !ready) {
+    const kind = info.status.kind
+    if (kind === "downloading") state = "downloading"
+    else if (!request.asked) state = "ask"
+    else state = kind === "failed" ? "failed" : "downloading"
+  }
+
+  const start = () => {
+    if (!request) return
+    gate.markAsked()
+    void download(request.id)
+  }
+  const decline = () => gate.decline()
+  const stop = () => {
+    if (request) void cancel(request.id)
+    gate.decline()
+  }
+
+  const status = info?.status
+  return (
+    <DownloadPrompt
+      state={state}
+      title={`${request?.tool ?? "This tool"} needs the ${info?.label ?? ""} model.`}
+      name={info?.label ?? ""}
+      facts={{
+        size: info && info.totalBytes > 0 ? formatBytes(info.totalBytes) : undefined,
+        licence: info?.licence || undefined,
+        host: info?.host || undefined,
+      }}
+      progress={
+        status?.kind === "downloading" && status.total > 0
+          ? { done: status.done, total: status.total }
+          : undefined
+      }
+      reason={status?.kind === "failed" ? status.reason : undefined}
+      onDownload={start}
+      onDismiss={decline}
+      onCancel={stop}
+      onRetry={start}
+    />
+  )
+}

package/src-ts/models/ModelsSection.tsx

@@ -0,0 +1,122 @@
+import { Button, ConfirmDialog, EmptyState, formatBytes, List, ListRow } from "@preset.nz/ux-kit"
+import { useState } from "react"
+
+import type { ModelInfo, ModelsApi } from "./api"
+import { useModels } from "./useModels"
+
+/** "Strata", "Strata and Shard", "Strata, Shard and Fault". */
+function joinNames(names: string[]): string {
+  if (names.length <= 1) return names.join("")
+  return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`
+}
+
+function sizeText(m: ModelInfo): string {
+  switch (m.status.kind) {
+    case "ready":
+      return `${formatBytes(m.bytesOnDisk)} on disk`
+    case "downloading":
+      return `${formatBytes(m.status.done)} of ${formatBytes(m.status.total)}`
+    case "damaged":
+      return "Damaged"
+    case "failed":
+      return m.status.reason
+    default:
+      return formatBytes(m.totalBytes)
+  }
+}
+
+const detailOf = (m: ModelInfo): string =>
+  [m.usedBy, m.licence, sizeText(m)].filter(Boolean).join(" · ")
+
+/**
+ * The Settings section: one row per model with its status, and the action that fits it. Remove
+ * asks first and names the other apps that use the model.
+ */
+export function ModelsSection({ api }: { api?: ModelsApi }) {
+  const { models, download, cancel, remove } = useModels(api)
+  const [removing, setRemoving] = useState<ModelInfo | null>(null)
+  const [open, setOpen] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const ask = (m: ModelInfo) => {
+    setError(null)
+    setRemoving(m)
+    setOpen(true)
+  }
+
+  const action = (m: ModelInfo) => {
+    switch (m.status.kind) {
+      case "ready":
+        return (
+          <Button size="sm" variant="outline" onClick={() => ask(m)}>
+            Remove
+          </Button>
+        )
+      case "downloading":
+        return (
+          <Button size="sm" variant="outline" onClick={() => void cancel(m.id)}>
+            Cancel
+          </Button>
+        )
+      case "damaged":
+      case "failed":
+        return (
+          <Button size="sm" variant="outline" onClick={() => void download(m.id)}>
+            Retry
+          </Button>
+        )
+      default:
+        return (
+          <Button size="sm" variant="outline" onClick={() => void download(m.id)}>
+            Download
+          </Button>
+        )
+    }
+  }
+
+  const onDisk = models.reduce((sum, m) => sum + m.bytesOnDisk, 0)
+  const others = removing?.otherApps ?? []
+
+  return (
+    <>
+      <List
+        aria-label="Models"
+        empty={
+          <EmptyState
+            title="No models"
+            description="A tool that needs a model asks before downloading it."
+          />
+        }
+        footer={`${formatBytes(onDisk)} on disk`}
+      >
+        {models.map((m) => (
+          <ListRow key={m.id} id={m.id} title={m.label} detail={detailOf(m)} trailing={action(m)} />
+        ))}
+      </List>
+      <ConfirmDialog
+        open={open}
+        onOpenChange={setOpen}
+        title={`Remove ${removing?.label ?? ""}?`}
+        confirmLabel="Remove"
+        destructive
+        onConfirm={async () => {
+          if (!removing) return
+          try {
+            await remove(removing.id)
+          } catch (e) {
+            setError(typeof e === "string" ? e : (e as Error).message)
+            throw e
+          }
+        }}
+      >
+        <p>{removing ? `${formatBytes(removing.bytesOnDisk)}. ` : ""}You can download it again.</p>
+        {others.length > 0 ? (
+          <p>
+            {joinNames(others)} {others.length === 1 ? "also uses" : "also use"} this model.
+          </p>
+        ) : null}
+        {error ? <p>{error}</p> : null}
+      </ConfirmDialog>
+    </>
+  )
+}

package/src-ts/models/api.ts

@@ -0,0 +1,61 @@
+import { invoke } from "@tauri-apps/api/core"
+import { listen } from "@tauri-apps/api/event"
+
+// The one file in `models/` that touches Tauri. The hooks and components take a `ModelsApi`, so
+// the ux-kit playground passes a fake and shows them without a window's backend.
+
+/** Where a model stands, mirroring Rust's `ModelStatus` (`#[serde(tag = "kind")]`). */
+export type ModelStatus =
+  | { kind: "notInstalled" }
+  | { kind: "downloading"; done: number; total: number }
+  | { kind: "ready" }
+  /** The manifest is there but a file is missing or the wrong size. */
+  | { kind: "damaged" }
+  /** The last download ended in this one plain line. */
+  | { kind: "failed"; reason: string }
+
+/** One model as `app_kit_models_list` reports it (Rust's `ModelInfo`, camelCase). */
+export interface ModelInfo {
+  id: string
+  label: string
+  /** The apps using it, as names; empty for a model this app never declared. */
+  usedBy: string
+  licence: string
+  host: string
+  status: ModelStatus
+  bytesOnDisk: number
+  totalBytes: number
+  /** Other apps that use the model, by name. */
+  otherApps: string[]
+}
+
+/** The payload of the `app-kit://models` event (Rust's `ModelChange`). */
+export interface ModelChange {
+  id: string
+  status: ModelStatus
+}
+
+/** What the models hooks and components need from the backend. */
+export interface ModelsApi {
+  list(): Promise<ModelInfo[]>
+  /** Starts the download and returns at once; progress arrives through `subscribe`. */
+  download(id: string): Promise<void>
+  cancel(id: string): Promise<void>
+  remove(id: string): Promise<void>
+  /** Calls `onChange` for every change. Returns the unsubscribe function. */
+  subscribe(onChange: (change: ModelChange) => void): () => void
+}
+
+/** The real thing: the five `app_kit_models_*` commands and the `app-kit://models` event. */
+export const tauriModelsApi: ModelsApi = {
+  list: () => invoke<ModelInfo[]>("app_kit_models_list"),
+  download: (id) => invoke<void>("app_kit_models_download", { id }),
+  cancel: (id) => invoke<void>("app_kit_models_cancel", { id }),
+  remove: (id) => invoke<void>("app_kit_models_remove", { id }),
+  subscribe(onChange) {
+    const un = listen<ModelChange>("app-kit://models", (e) => onChange(e.payload))
+    return () => {
+      un.then((f) => f())
+    }
+  },
+}

package/src-ts/models/context.ts

@@ -0,0 +1,32 @@
+import { createContext, createElement, type ReactNode, useContext, useMemo } from "react"
+
+import { type ModelsApi, tauriModelsApi } from "./api"
+import { ModelGate } from "./gate"
+
+interface ModelsContextValue {
+  api: ModelsApi
+  gate: ModelGate
+}
+
+let defaultValue: ModelsContextValue | undefined
+
+// Built on first use, so importing the module touches nothing.
+function fallback(): ModelsContextValue {
+  defaultValue ??= { api: tauriModelsApi, gate: new ModelGate(tauriModelsApi) }
+  return defaultValue
+}
+
+const ModelsContext = createContext<ModelsContextValue | null>(null)
+
+/**
+ * Gives the models hooks and components another `api` (the playground's fake) and the gate that
+ * goes with it. An app on the real backend doesn't need it.
+ */
+export function ModelsProvider({ api, children }: { api: ModelsApi; children: ReactNode }) {
+  const value = useMemo(() => ({ api, gate: new ModelGate(api) }), [api])
+  return createElement(ModelsContext.Provider, { value }, children)
+}
+
+export function useModelsContext(): ModelsContextValue {
+  return useContext(ModelsContext) ?? fallback()
+}

package/src-ts/models/gate.ts

@@ -0,0 +1,108 @@
+import type { ModelsApi } from "./api"
+
+/** `ensure` rejects with this when the person says no: Not now, Cancel or Close. */
+export class ModelDeclined extends Error {
+  modelId: string
+
+  constructor(modelId: string) {
+    super(`The ${modelId} model was declined`)
+    this.name = "ModelDeclined"
+    this.modelId = modelId
+  }
+}
+
+export interface EnsureOptions {
+  /** The tool that needs the model, for the prompt: "Smart Select". */
+  for?: string
+}
+
+/** The request the prompt is showing. Replaced, never mutated, so React can compare it. */
+export interface GateRequest {
+  id: string
+  tool: string | undefined
+  /** The person pressed Download in this session. */
+  asked: boolean
+}
+
+interface Waiting {
+  request: GateRequest
+  promise: Promise<void>
+  resolve: () => void
+  reject: (error: Error) => void
+}
+
+/**
+ * The queue behind `useModelGate` and `ModelPromptHost`. It keeps only what has been asked for
+ * and whether the person said yes; the prompt's state comes from the model's status.
+ */
+export class ModelGate {
+  private api: ModelsApi
+  private queue: Waiting[] = []
+  private listeners = new Set<() => void>()
+  private current: GateRequest | null = null
+
+  constructor(api: ModelsApi) {
+    this.api = api
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  /** The request being shown, or null. */
+  snapshot = (): GateRequest | null => this.current
+
+  /** Resolves at once for a Ready model; otherwise queues the prompt. One prompt at a time. */
+  ensure = async (id: string, options: EnsureOptions = {}): Promise<void> => {
+    const models = await this.api.list()
+    const info = models.find((m) => m.id === id)
+    if (!info) throw new Error(`Unknown model ${id}`)
+    if (info.status.kind === "ready") return
+    const waiting = this.queue.find((w) => w.request.id === id)
+    if (waiting) return waiting.promise
+    let resolve!: () => void
+    let reject!: (error: Error) => void
+    const promise = new Promise<void>((res, rej) => {
+      resolve = res
+      reject = rej
+    })
+    this.queue.push({
+      request: { id, tool: options.for, asked: false },
+      promise,
+      resolve,
+      reject,
+    })
+    this.publish()
+    return promise
+  }
+
+  /** The person pressed Download (or Retry). */
+  markAsked(): void {
+    const head = this.queue[0]
+    if (!head || head.request.asked) return
+    head.request = { ...head.request, asked: true }
+    this.publish()
+  }
+
+  /** The model is Ready: resolve the head and move to the next. */
+  succeed(): void {
+    const head = this.queue.shift()
+    head?.resolve()
+    this.publish()
+  }
+
+  /** The person said no: reject the head with `ModelDeclined` and move to the next. */
+  decline(): void {
+    const head = this.queue.shift()
+    head?.reject(new ModelDeclined(head.request.id))
+    this.publish()
+  }
+
+  private publish(): void {
+    this.current = this.queue[0]?.request ?? null
+    for (const l of this.listeners) l()
+  }
+}

package/src-ts/models/index.ts

@@ -0,0 +1,13 @@
+// `@preset.nz/app-kit/models`: the webview half of app-kit's models feature. It imports ux-kit
+// (the prompt, the list and the confirm dialog), so it is not part of `core`.
+
+export type { ModelChange, ModelInfo, ModelStatus, ModelsApi } from "./api"
+export { tauriModelsApi } from "./api"
+export { ModelsProvider } from "./context"
+export type { EnsureOptions } from "./gate"
+export { ModelPromptHost } from "./ModelPromptHost"
+export { ModelsSection } from "./ModelsSection"
+export type { ModelGate } from "./useModelGate"
+export { ModelDeclined, useModelGate } from "./useModelGate"
+export type { UseModels } from "./useModels"
+export { useModels } from "./useModels"

package/src-ts/models/useModelGate.ts

@@ -0,0 +1,20 @@
+import { useMemo } from "react"
+
+import { useModelsContext } from "./context"
+import type { EnsureOptions } from "./gate"
+
+export { ModelDeclined } from "./gate"
+
+export interface ModelGate {
+  /**
+   * Resolves when the model is Ready: at once if it is, otherwise after the person agrees and the
+   * download ends. Rejects with `ModelDeclined` on Not now, Cancel or Close, which a tool treats
+   * as "don't arm". A `<ModelPromptHost />` must be mounted for the prompt to show.
+   */
+  ensure(id: string, options?: EnsureOptions): Promise<void>
+}
+
+export function useModelGate(): ModelGate {
+  const { gate } = useModelsContext()
+  return useMemo(() => ({ ensure: gate.ensure }), [gate])
+}

package/src-ts/models/useModels.ts

@@ -0,0 +1,103 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+
+import type { ModelChange, ModelInfo, ModelStatus, ModelsApi } from "./api"
+import { useModelsContext } from "./context"
+
+export interface UseModels {
+  /** Declared models first, in registry order, then any other app's. Empty until the first read. */
+  models: ModelInfo[]
+  /** Starts the download. A refusal shows as the model's `failed` status, not a throw. */
+  download(id: string): Promise<void>
+  cancel(id: string): Promise<void>
+  /** Rejects when Rust refuses (the model is downloading). */
+  remove(id: string): Promise<void>
+}
+
+const reasonOf = (e: unknown): string => (typeof e === "string" ? e : (e as Error).message)
+
+function withStatus(models: ModelInfo[], id: string, status: ModelStatus): ModelInfo[] {
+  return models.map((m) => (m.id === id ? { ...m, status } : m))
+}
+
+/**
+ * The model list, kept current by `app-kit://models`. The list is the only state: it is read on
+ * mount, and every event replaces one row's status. A model that stops downloading, or one the
+ * list doesn't know, is read again, so sizes and the apps using it stay true.
+ */
+export function useModels(api?: ModelsApi): UseModels {
+  const context = useModelsContext()
+  const backend = api ?? context.api
+  const [models, setModels] = useState<ModelInfo[]>([])
+  const loaded = useRef(false)
+  const early = useRef(new Map<string, ModelStatus>())
+  const current = useRef(models)
+  current.current = models
+
+  const refresh = useCallback(async () => {
+    try {
+      setModels(await backend.list())
+    } catch {
+      // Keep what is shown; the next event reads again.
+    }
+  }, [backend])
+
+  useEffect(() => {
+    loaded.current = false
+    early.current.clear()
+    let live = true
+    const apply = (change: ModelChange) => {
+      if (!loaded.current) {
+        early.current.set(change.id, change.status)
+        return
+      }
+      const known = current.current.some((m) => m.id === change.id)
+      if (known) setModels((cur) => withStatus(cur, change.id, change.status))
+      if (!known || change.status.kind !== "downloading") void refresh()
+    }
+    // Subscribe first, so a change during the first read isn't lost.
+    const off = backend.subscribe(apply)
+    backend.list().then(
+      (list) => {
+        if (!live) return
+        loaded.current = true
+        setModels(list.map((m) => ({ ...m, status: early.current.get(m.id) ?? m.status })))
+        early.current.clear()
+      },
+      () => {},
+    )
+    return () => {
+      live = false
+      off()
+    }
+  }, [backend, refresh])
+
+  const download = useCallback(
+    async (id: string) => {
+      const before = current.current.find((m) => m.id === id)
+      if (before?.status.kind === "downloading") return
+      // Show it downloading before the command returns: its events can only come after this, and a
+      // quick failure then can't be overwritten by a stale row.
+      setModels((cur) =>
+        withStatus(cur, id, { kind: "downloading", done: 0, total: before?.totalBytes ?? 0 }),
+      )
+      try {
+        await backend.download(id)
+      } catch (e) {
+        setModels((cur) => withStatus(cur, id, { kind: "failed", reason: reasonOf(e) }))
+      }
+    },
+    [backend],
+  )
+
+  const cancel = useCallback((id: string) => backend.cancel(id).catch(() => {}), [backend])
+
+  const remove = useCallback(
+    async (id: string) => {
+      await backend.remove(id)
+      await refresh()
+    },
+    [backend, refresh],
+  )
+
+  return { models, download, cancel, remove }
+}