@parallelworks/ui 0.44.0 → 0.45.0

package/README.md

@@ -6,7 +6,7 @@ so an application ships only what it imports:
 | Subpath | Contents |
 | --- | --- |
 | `.` | theme contract, primitives (buttons, inputs, tables, tooltips, modals, dropdowns, settings layouts, page header), `UIProvider` |
-| `./theme` | `deriveTheme`, presets, `applyTheme` |
+| `./theme` | theme seeds and presets, `generateTheme`, `applyTheme`, `fitSeed` |
 | `./icons` | the icon barrel |
 | `./list` | list pages, tables, row menus and list controls |
 | `./form` | `DynamicForm` and its field registry |
@@ -17,25 +17,164 @@ so an application ships only what it imports:
 | `./ai`, `./ai/openai`, `./ai/mock` | chat interface and adapters |
 | `./theme.css`, `./base.css`, `./fonts.css`, `./styles.css`, `./logviewer.css`, `./ai.css` | stylesheets |
 
-Hosts bind notifications, strings, navigation, data hooks and the workflow
-engine through `UIProvider`.
+Hosts bind strings, navigation, data hooks and the workflow engine through
+`UIProvider`, which also shows the package's toasts.
 
-## Theme contract
+## Which component?
+
+Each need has one component. Reach for it before styling markup by hand.
+
+| Need | Use |
+| --- | --- |
+| An action | `Button`; `IconButton` for an icon alone, named by its tooltip |
+| A link or another component's trigger that looks like a button | `buttonClasses()` |
+| A link out of the app | `ExternalLink` |
+| Work under way | `Loader`; `Skeleton` in a `LoadingRegion` for the shape of content still loading |
+| Nothing to show yet, or nothing matches | `EmptyState` |
+| A text field | `Input`, `Textarea`, or a control framed by `Field`, whose `actions` hold buttons that act on it |
+| A number, a date | `NumberInput`, `DatePicker` |
+| On or off | `Switch`; `Checkbox` in a list of things to tick, several of which may be on |
+| One of a few choices, all shown | `RadioGroup` in a form; `SegmentedControl` in a toolbar, or as a field's control in a `Field group` |
+| Narrowing what is shown by typing | `SearchInput`; `ListSearchControl` on a list page's toolbar |
+| A value from a list | `Select`, or `Combobox` when the list needs filtering |
+| Free text with suggestions, or tags | `Autocomplete`; `Combobox` with `multiple creatable` |
+| A range | `Slider` |
+| A titled part of a page or form | `Section` |
+| More detail under a line | `Disclosure` |
+| Views of one thing | `Tabs` |
+| A list of actions | `ActionMenu`; `useContextMenu` for a right-click or a row's menu |
+| A panel of controls anchored to a trigger | `Popover` |
+| A hint for a control | `Tooltip`; `InfoTip` for help everyone must reach |
+| A preview of what a link leads to | `HoverCard` |
+| A task that blocks the page | `Modal`; `ConfirmModal` to confirm one action |
+| A panel beside the page | `Drawer` |
+| A passing notice, or the progress of work in the background | `toast` |
+| How full something is, how far a task has come | `Meter`, `ProgressBar` |
+| Pages of a long list | `Pagination` |
+| A grouped page of settings | `SettingsCard` with `SettingRow`s |
+| A person | `Avatar` |
+| A status in words | `StatusBadge`, or `StatusDot` beside text that says it |
+| A run's, job's or step's status beside its name | `RunStatusIcon`; `StatusBadge` with `runStatusTone` to say it in words |
+| A copy action | `useCopy`, or `CopyToClipboard` for its button |
+| A live relative time or duration | `RelativeTime`, `Elapsed` |
+| Rendered Markdown | `Markdown` |
+| A value that survives a reload | `usePersistedState` |
+| Choosing the app's colors | `ThemeEditor`, applied with `useApplyTheme` |
+
+Some pairs look alike and are split on purpose:
+
+- **Section or Disclosure.** A `Section` is a titled part of a page or form: its
+  title is a heading in the page's outline, and folding it keeps its fields
+  mounted. A `Disclosure` is a line inside content that reveals detail beneath
+  it, such as a tool call's arguments, and adds nothing to the outline.
+- **Popover or HoverCard.** A `Popover` opens on a press and holds controls or a
+  list, so keyboard and touch reach it. A `HoverCard` opens on hover or focus
+  and only previews what its anchor already leads to; nothing in it may be
+  reachable only there.
+- **Menu or Popover.** A menu is a list of actions or choices that closes once
+  one is picked, with arrow-key navigation and type-ahead. Anything else
+  anchored to a trigger, such as a form or a filter panel, is a `Popover`.
+- **Tabs or SegmentedControl.** `Tabs` switch between views or pages of one
+  thing, each with its own panel or route. A `SegmentedControl` sets a value,
+  such as a time range, that changes what one view shows. `Tabs` with
+  `variant="segmented"` look the same, so the choice rests on what pressing does.
+- **SearchInput or ListSearchControl.** A `SearchInput` is a box that is
+  always shown and narrows what sits beside it, such as a panel's rows or a
+  log's lines. `ListSearchControl` belongs to a list page's toolbar: it folds to
+  a button, opens on ⌘F or `/`, and keeps terms as chips the list remembers.
+- **StatusBadge or RunStatusIcon.** A `StatusBadge` says a status in words in
+  its tone, for anything. A `RunStatusIcon` shows the status of something that
+  ran as an icon beside its name, and turns while it runs; `runStatusTone` gives
+  a badge for the same status the same tone.
+- **Select or Combobox.** A `Select` picks from a short list it shows in full.
+  A `Combobox` filters as you type, for a list long enough to search, and is the
+  one that takes several values, new ones, or free text (`Autocomplete`).
+
+## Themes
 
 Every color a component may use is one of the closed set of `--theme-*` CSS
-variables, and every token is computable from a tiny seed — accent +
-background + contrast — per surface (interface, and optionally sidebar).
-Presets are named seeds; a custom theme is the same seed exposed directly.
-Components consume only tokens and never branch on a light/dark flag.
+variables. Components read only those tokens and never branch on a light or dark
+flag. A theme is not the tokens but a few picked values, a seed, from which every
+token is generated:
+
+```ts
+import type { Theme } from '@parallelworks/ui/theme'
+
+const theme: Theme = {
+  version: 1,
+  light: { interface: { base: '#f3f4f6', accent: '#06354f', contrast: 30 }, sidebar: { base: '#06354f' } },
+  dark: { interface: { base: '#111418', accent: '#5b9ccf' } },
+  code: 'balanced',
+}
+```
+
+- **`base`** is the page background. Its lightness decides the mode, so a seed
+  is light or dark by what it looks like. A near-white base keeps panels pure
+  white.
+- **`accent`** is used exactly for the primary button and the selection; text on
+  it, links, focus rings and tints are solved from it.
+- **`contrast`** runs 0 to 100, 30 by default. It spreads the surfaces apart and
+  raises text toward the WCAG and APCA targets below. Even 0 meets WCAG AA.
+- **`sidebar`** takes its own `base` and `accent`; leave it out and the sidebar
+  follows the page.
+- **`light` and `dark`** are both optional: a missing mode is derived from the
+  other, so a theme with one scheme still follows the device.
+- **`code`** picks the syntax and terminal palette: `balanced`, `vivid`, `muted`
+  or `mono`.
+
+A theme is plain JSON. Store it as it is; `parseTheme` reads one back (a string
+or a parsed value) and returns `{ ok: false, error: { code, path } }` instead of
+throwing, so an import can say which field is wrong. `serializeTheme` writes one.
+
+### How tokens are generated
+
+Generation works in OKLCH. Neutrals take the base's hue with a faint tint toward
+the accent; surfaces step away from the base by an amount the contrast scales,
+with a knee at 30 so the upper half of the slider changes more gently. Dark text
+on a tinted light base carries several times the base's chroma, as hand-made
+slate and gray scales do, while light text on a dark base carries less. Each text
+color is then solved: a binary search on lightness, at its own hue and chroma,
+until it reaches its target against every surface it sits on.
+
+| Pair | WCAG at 0 / 30 / 100 | APCA Lc |
+| --- | --- | --- |
+| Body text | 4.5 / 7 / 12 | 75 / 90 / 105 |
+| Secondary text, links, status, syntax and terminal colors | 4.5 / 4.5 / 7 | 60 / 70 / 85 |
+| Placeholders | 3 / 3 / 4.5 | 45 / 50 / 65 |
+| Focus ring | 3 / 3 / 4.5 | |
+| Control borders | 1.6 / 2.2 / 3 | |
+| Text on the accent | 4.5 | |
+
+Status colors (success, error, warning, info, favorite) and terminal colors keep
+fixed hues, so red means the same thing in every theme. Syntax colors turn away
+from the accent's hue when they come within 30° of it, so a keyword never looks
+like a link.
+
+Every color is mapped into sRGB with the CSS Color 4 method, which lowers
+chroma at fixed lightness and hue. It is mapped into display-p3 too: where the
+wider color differs from sRGB by more than one just-noticeable difference
+(ΔEOK 0.02), it is emitted under `@media (color-gamut: p3)`. The contrast
+targets are checked in both gamuts.
+
+### Applying a theme
 
 ```ts
-import { deriveTheme, applyTheme, THEME_PRESETS } from '@parallelworks/ui/theme'
+import { applyTheme, generateTheme, schemeFor, resolveMode } from '@parallelworks/ui/theme'
 
-const vars = deriveTheme({ accent: '#06354f', background: '#f3f4f6' })
-applyTheme(document.documentElement, vars)
+const prefersDark = matchMedia('(prefers-color-scheme: dark)').matches
+const mode = resolveMode('system', prefersDark) // 'light' or 'dark'
+applyTheme(document.documentElement, generateTheme(schemeFor(theme, mode), { code: theme.code }))
 ```
 
-Import the stylesheet contract once in your app:
+In React, `useColorMode(preference)` follows the device while the preference is
+`system`, and `useApplyTheme(theme, mode)` applies the theme to the document
+root (or to an element you pass) and sets `color-scheme`. `applyTheme` sets the
+display-p3 values on a wide-gamut screen. To render a theme on the server,
+`themeStylesheet(selector, scheme)` returns a stylesheet with both blocks.
+`deriveTheme(scheme)` returns the sRGB tokens alone.
+
+`theme.css` defines the default theme's tokens, so a page renders before any
+script runs:
 
 ```css
 /* In a Tailwind v4 build: */
@@ -55,19 +194,178 @@ so its precedence does not depend on where it loads. It includes Tailwind's
 preflight reset; a host with its own Tailwind build should use the `@source`
 route instead to avoid a double preflight.
 
+### Editing a theme
+
+`ThemeEditor` is controlled: it takes `value` and `onChange`, with presets, a
+color picker and hex field for each seed, the contrast slider, a custom sidebar,
+the code palette, copy, import and reset. Pass `preference` and
+`onPreferenceChange` to show the light, dark and system choice. It shows a
+scoped preview of the theme beside the controls; with `preview={false}` and
+`useApplyTheme`, the whole app is the preview. Its strings are in
+`UIStrings.theme`.
+
+### Code
+
+Code blocks in `Markdown`, highlighted diffs, the Monaco editor and the log
+viewer's ANSI colors all read the `--theme-code-*` and `--theme-ansi-*` tokens,
+so they follow the theme without a light or dark switch. Monaco takes only
+hex, so it gets the sRGB colors and redefines its theme when the tokens change.
+
+### Moving a stored palette to a seed
+
+`fitSeed(colors)` takes the colors a theme stored as tokens (any of them) and
+returns the seed that comes closest, with a report:
+
+```ts
+const { scheme, report } = fitSeed({ '--theme-app-bg': '#f4f6f8', '--theme-accent': '#0b7a75' })
+report.verdict // 'faithful', 'close' or 'changed'
+report.worst   // the tokens furthest from what was stored
+```
+
+Each token's distance is ΔEOK × 100, so 2 is about one just-noticeable
+difference. A fit is `faithful` when the main tokens are within 2 and none is
+over 5, and `close` within 5 and 10. A stored color that failed WCAG AA is
+marked `correctedForContrast` and left out of the verdict, since the generated
+one is meant to differ.
+
+### Renamed tokens
+
+| Before | Now |
+| --- | --- |
+| `--theme-element` | `--theme-accent` |
+| `--theme-element-text` | `--theme-accent-text` |
+| `--theme-element-hover` | `--theme-accent-hover` |
+| `--theme-panel`, `--theme-hover-text` | `--theme-app` |
+| `--theme-muted-panel-color` | `--theme-muted-text-color` |
+| `--theme-card-bg` | `--theme-panel-bg` |
+| `--theme-card-hover` | `--theme-panel-hover` |
+| `--theme-card-border` | `--theme-border` |
+| `--theme-hover-overlay` | `--theme-hover` |
+| `--theme-input-disabled-text` | `--theme-placeholder` |
+| `--theme-input` | `--theme-focus` |
+| `--theme-auth-shadow` | `--theme-shadow-xl` |
+| `--theme-sidebar-hover-text` | `--theme-sidebar-text` |
+| `--theme-bg` | `--theme-sidebar-bg` |
+| `theme-element` (utility) | `theme-accent` |
+
+## Buttons and spinners
+
+Every pressable thing has one look, from `buttonClasses({ variant, size, iconOnly })`:
+
+| Variant | For |
+| --- | --- |
+| `primary` | the one action a view leads to |
+| `secondary` | actions beside it |
+| `outline`, `ghost` | toolbar and inline actions, bordered or not |
+| `danger` | confirming what can't be undone |
+
+Sizes are `xs`, `sm` and `md`. `Button` and `IconButton` apply it. An
+`IconButton` is named by its tooltip, and takes `pressed` for a toggle and
+`dot` for an indicator. Pass `buttonClasses()` to a host link or to another
+component's trigger rather than styling a button by hand. A pressed toggle
+(`aria-pressed`) and an open popup's trigger read as selected.
+
+`Loader` is the one spinner. Inside a button, or beside text that already
+says what is happening, use `<Loader inline decorative />`.
+
+## Toasts
+
+`toast` shows a notice from anywhere, a component or not. `UIProvider` renders
+them along the top of the window, above dialogs, where they clear a modal's
+panel and stay usable while it is open: pressing one doesn't close the dialog.
+A screen reader hears each one; errors interrupt, the rest wait for a pause.
+
+```ts
+import { toast } from '@parallelworks/ui'
+
+toast.success('Saved')
+toast.error('Could not save', { action: { label: 'Retry', onClick: save } })
+
+const id = toast.loading('Uploading…')
+toast.update(id, { tone: 'success', message: 'Uploaded' })
+
+await toast.promise(save(), { loading: 'Saving…', success: 'Saved', error: 'Could not save' })
+```
+
+Tones are `info`, `success`, `warning` and `error`. A toast closes itself after
+five seconds, eight for a warning or an error, pausing while the pointer or focus
+is on it; `timeout: false` keeps it. `loading` stays until an update settles it
+into a tone. Pass an `id` to replace a toast rather than stack another.
+
+## Host chrome
+
+Popups, dialogs and drawers portal to `<body>` and read the tokens from the
+document root. A host with fixed chrome tells overlays where it is, on the same
+root:
+
+| Variable            | Meaning                                                                 |
+| ------------------- | ----------------------------------------------------------------------- |
+| `--app-inset-top`   | The height of a fixed top bar. A drawer starts below it.                |
+| `--app-inset-start` | The width of a fixed sidebar on the start side. A drawer at its widest leaves that strip, and never less than 2.5rem. |
+
+```ts
+document.documentElement.style.setProperty('--app-inset-top', '56px')
+document.documentElement.style.setProperty('--app-inset-start', '220px')
+```
+
+Everything the package lays over the page stacks on one scale, set on the
+document root by `base.css`. Give the host's own fixed elements a place on it,
+such as `z-index: 100` for a top bar, rather than a z-index chosen to win:
+
+| Variable          | Default | For                                                    |
+| ----------------- | ------- | ------------------------------------------------------ |
+| `--layer-sticky`  | 10      | toolbars and tab strips that stick as the page scrolls |
+| `--layer-header`  | 20      | the page header, which sticks above them               |
+| `--layer-overlay` | 1000    | a panel over the page, such as a full-screen log       |
+| `--layer-drawer`  | 1100    | drawers                                                |
+| `--layer-modal`   | 1200    | modals                                                 |
+| `--layer-popover` | 1300    | menus, selects, popovers, hover cards and tooltips, so one opens over the dialog it belongs to |
+| `--layer-toast`   | 1400    | toasts                                                 |
+
+In Tailwind, `z-(--layer-modal)` reads one. Override a value on `:root` to move
+a layer; the defaults sit in a cascade layer, so the host's own rule wins.
+
 ## Icons
 
 ```tsx
-import { AddIcon, LoaderIcon, TrashIcon } from '@parallelworks/ui/icons'
-```
+import { AddIcon, TrashIcon } from '@parallelworks/ui/icons'
 
-The barrel re-exports a curated, stable set of icon names over `react-icons`
-so applications never depend on a specific icon pack directly.
+<Button><AddIcon /> Add</Button>
+<TrashIcon className="size-4 text-(--theme-error)" />
+```
 
-Each icon ships as its own module under `dist/icons/<set>/`, so an application
-bundles an icon only into the chunks that render it. Every module carries its
-icon's data, copied from its `react-icons` set at build time, and opens with that
-set's name and license.
+`@parallelworks/ui/icons` is the one import point for interface icons. Each
+name is a meaning, such as `RetryIcon` or `WarningIcon`, drawn from
+[Lucide](https://lucide.dev), so every icon shares one 24px grid and one 2px
+stroke. Don't import `lucide-react` directly: a name here keeps one glyph per
+meaning across the apps.
+
+- **Size and colour:** an icon is `1em` square in `currentColor`, so it follows
+  the text around it. A class such as `size-4` or `h-3 w-3` sets another size,
+  and `size` takes pixels.
+- **Accessibility:** an icon is decoration, hidden from assistive technology,
+  unless a `title` or `aria-label` names it. Name one only when nothing beside
+  it says what it means.
+- **Filled variants:** a filled glyph marks a state, such as `PinFilledIcon`
+  for pinned.
+- **One name per meaning:** pick the name for what the thing is, even where a
+  nearby name would look similar. For compute, `ClusterIcon` is a group of
+  nodes, `NodeIcon` one host or node in it, and `InstanceIcon` a VM or cloud
+  instance. `RemoveIcon` takes an item out of a list, while `CloseIcon` closes,
+  dismisses or clears; they share the X glyph, the convention for both.
+  `DestroyIcon` tears down what was provisioned, while `TrashIcon` deletes a
+  record.
+- **Adding an icon:** pick the [Lucide glyph](https://lucide.dev/icons) and add
+  `export const NameIcon = /* @__PURE__ */ icon(Glyph)` to `src/icons.tsx`,
+  named for what it means rather than what it shows. Reuse an existing name
+  when the meaning is the same.
+
+Logos of other companies' products, such as `GitHubIcon` or `UbuntuIcon`, are
+in `@parallelworks/ui/brand-icons`. They take the same props, are filled in the
+text's colour, and are only for naming the product. They come from Simple Icons
+(CC0) and Bootstrap Icons (MIT), and the file carries their notices.
+
+The `UI/Icons` story shows every icon and logo by name.
 
 ## Workflow engine
 
@@ -138,7 +436,6 @@ export function Chat() {
       adapter={createMockChatAdapter()}
       currentUser={{ id: 'u1', username: 'you', name: 'You' }}
       navigation={{ toConversation: id => {}, toNewChat: () => {}, toAttachments: () => {} }}
-      notify={{ success: console.log, error: console.error, info: console.log }}
     >
       <ChatLayout>
         <ChatThread />
@@ -191,13 +488,36 @@ const { isDirty } = useFormState({ control: form.control })
 
 `form.getValues()`, `form.reset()` and `formState.isDirty` then work as
 react-hook-form documents them. Without `form`, the form keeps its own;
-`onValuesChange` reports each change either way. `missingFields` marks fields
-as `required` errors.
+`onValuesChange` reports each change either way.
+
+## Validation
+
+A field with neither `optional` nor a `default` needs a value. A submit, or
+Next on a wizard page, checks the fields the form shows, says "Enter a value."
+under each empty one and holds until it is filled; once a field shows an
+error it checks again with each change. A hidden field, a disabled one and a
+boolean never hold the form.
+
+`serverErrors` shows what the server rejected, each under its field until the
+person changes it. A path may come in any convention: a workflow's
+`hosts[0].cpus`, a problem response's JSON Pointer `#/hosts/0/cpus`, or
+`hosts.0.cpus`. Without a message the field says to check its value. They
+never hold back Next or a submit, since the server checks again, and a wizard
+turns to the first page holding one. From a problem response:
+
+```tsx
+const fieldMessages = useFieldMessages() // @parallelworks/problem/react
+<DynamicForm serverErrors={save.error ? fieldMessages(save.error) : undefined} … />
+```
+
+A field component receives the form's message as `error`; `fieldFrame(props)`
+shows it through `Field`.
 
 Each field subscribes only to what it reads, so typing renders the edited
 field and whatever reads it, not the whole form. A host field component,
 passed through `fields` or `slots.formFields`, binds the same way: its own
-value with `useFieldValue(field.name)` (or `useController`), another input's
+value with `useFieldValue(field.name)`, which also gives the form the field's
+rules (a component's own `useController` would drop them), another input's
 with `useFieldAt(path)` or `useWatch`, and a pick from a list with
 `useChoiceField`, which applies `autoselect` and `secondaryField`.
 
@@ -249,7 +569,10 @@ clamped to the current grid's column count. `gap` accepts `none`, `sm`, `md`
 `$meta.labelPosition` still overrides them.
 
 A grid defaults to `align: independent`: its children start at the top and their
-contents flow independently. Set `align: rows` when every immediate child is a
+contents flow independently, except that fields side by side line up their
+controls. A label that wraps to two lines sits at the foot of a label row the
+fields in that row share, so its control stays level with its neighbors'.
+Set `align: rows` when every immediate child is a
 section. Adjacent sections then share a header row and one row per direct child.
 A description, help text, or validation message increases the shared row height,
 so the following rows stay aligned. A nested grid counts as one child row.

package/dist/ai/agent/diff.d.ts

@@ -1,3 +1,4 @@
+import { type ToolStrings } from './toolStrings.js';
 export declare const MAX_EDIT_DIFF_LINES = 100;
 export declare const MAX_WRITE_DIFF_LINES = 50;
 export interface EditToolArgs {
@@ -31,4 +32,4 @@ export interface WriteModel {
     truncated: boolean;
 }
 export declare function computeWriteRows(content: string): WriteModel;
-export declare function editSummary(toolName: string, argsJSON: string): string;
+export declare function editSummary(toolName: string, argsJSON: string, t?: ToolStrings): string;

package/dist/ai/agent/diff.js

@@ -1,3 +1,4 @@
+import { defaultToolStrings } from "./toolStrings.js";
 import { sanitizeLabel } from "./toolfmt.js";
 //#region src/ai/agent/diff.ts
 var MAX_EDIT_DIFF_LINES = 100;
@@ -201,23 +202,14 @@ function computeWriteRows(content) {
 		truncated: lines.length > 50
 	};
 }
-function editSummary(toolName, argsJSON) {
+function editSummary(toolName, argsJSON, t = defaultToolStrings) {
 	const a = parseEditArgs(argsJSON);
 	if (!a) return "";
-	const count = (n) => `${n} ${n === 1 ? "line" : "lines"}`;
 	if (toolName === "EditFile") {
 		const [added, removed] = lineDelta(splitLines(a.old_string ?? ""), splitLines(a.new_string ?? ""));
-		if (added > 0 && removed > 0) return `Added ${count(added)}, removed ${count(removed)}`;
-		if (added > 0) return `Added ${count(added)}`;
-		if (removed > 0) return `Removed ${count(removed)}`;
-		return "";
-	}
-	if (toolName === "WriteFile") {
-		if (a.content === void 0) return "";
-		let s = `Wrote ${count(splitLines(a.content).length)}`;
-		if (a.path) s += ` to ${sanitizeLabel(a.path)}`;
-		return s;
+		return t.edited(added, removed);
 	}
+	if (toolName === "WriteFile" && a.content !== void 0) return t.wrote(splitLines(a.content).length, a.path ? sanitizeLabel(a.path) : "");
 	return "";
 }
 //#endregion

package/dist/ai/agent/diffHighlight.d.ts

@@ -3,4 +3,4 @@ export interface DiffToken {
     color?: string;
 }
 export declare function languageForPath(path: string | undefined): string | null;
-export declare function tokenizeDiffLines(lines: string[], lang: string, isDark: boolean): Promise<DiffToken[][] | null>;
+export declare function tokenizeDiffLines(lines: string[], lang: string): Promise<DiffToken[][] | null>;

package/dist/ai/agent/diffHighlight.js

@@ -1,3 +1,4 @@
+import { CODE_THEME } from "../../components/codeTheme.js";
 //#region src/ai/agent/diffHighlight.ts
 var EXT_LANG = {
 	ts: "typescript",
@@ -72,7 +73,7 @@ function getHighlighter(lang) {
 			const [{ createHighlighter }, { createJavaScriptRegexEngine }] = await Promise.all([import("shiki"), import("shiki/engine/javascript")]);
 			return await createHighlighter({
 				langs: [lang],
-				themes: ["github-light", "github-dark"],
+				themes: [CODE_THEME],
 				engine: createJavaScriptRegexEngine({ forgiving: true })
 			});
 		})().catch(() => null);
@@ -80,13 +81,13 @@ function getHighlighter(lang) {
 	}
 	return p;
 }
-async function tokenizeDiffLines(lines, lang, isDark) {
+async function tokenizeDiffLines(lines, lang) {
 	const highlighter = await getHighlighter(lang);
 	if (!highlighter) return null;
 	try {
 		const tokens = highlighter.codeToTokensBase(lines.join("\n"), {
 			lang,
-			theme: isDark ? "github-dark" : "github-light"
+			theme: CODE_THEME.name
 		});
 		if (tokens.length !== lines.length) return null;
 		return tokens.map((line) => line.map((t) => ({

package/dist/ai/agent/index.d.ts

@@ -2,5 +2,6 @@ export { classifyPseudoUserMessage } from './classifier.js';
 export { computeEditDiff, computeWriteRows, type DiffRow, type EditDiffModel, type EditToolArgs, editSummary, isEditDiffTool, lineDelta, MAX_EDIT_DIFF_LINES, MAX_WRITE_DIFF_LINES, parseEditArgs, type WriteModel, wordEmphasisRanges, } from './diff.js';
 export { type DiffToken, languageForPath, tokenizeDiffLines, } from './diffHighlight.js';
 export { clampPermissionMode, DEFAULT_PERMISSION_MODE, isNamedPermissionMode, NAMED_PERMISSION_MODES, type NamedPermissionMode, type PermissionMode, permissionModesUpTo, } from './permissions.js';
-export { AGENT_COLOR_NAMES, agentColorHex, bashExitCode, clip, fullToolArgs, isGroupableTool, plural, resultFailed, rollupSentence, sanitizeLabel, sanitizePanelText, summarizeToolArgs, type ToolHeader, toolHeaderFor, toolSummary, } from './toolfmt.js';
+export { AGENT_COLOR_NAMES, agentColorHex, bashExitCode, clip, fullToolArgs, isGroupableTool, resultFailed, rollupSentence, sanitizeLabel, sanitizePanelText, summarizeToolArgs, type ToolHeader, type ToolSummaryOptions, toolHeaderFor, toolSummary, } from './toolfmt.js';
+export { defaultToolStrings, type ToolStrings } from './toolStrings.js';
 export { agentTypeLabel, askQuestionFromArgs, firstNonEmptyLine, hiddenTranscriptTool, INTERRUPTED_NOTICE, interruptionNotice, parseSubagentNotice, planFromArgs, type SubagentNotice, subagentDeliveryLine, taskCallFromArgs, thinkingHeading, } from './transcript.js';

package/dist/ai/agent/toolStrings.d.ts

@@ -0,0 +1,37 @@
+export interface ToolStrings {
+    /** A call that printed nothing. */
+    noOutput: string;
+    /** A result's first line, and how many lines follow it. */
+    firstLine: (line: string, moreLines: number) => string;
+    emptyFile: string;
+    readImage: string;
+    /** `more` counts the lines the read left out; 0 when it read them all. */
+    readLines: (lines: number, more: number) => string;
+    noMatches: string;
+    foundMatches: (matches: number, files: number) => string;
+    foundFiles: (files: number) => string;
+    noFilesMatched: string;
+    /** A search summary whose own output was capped. */
+    truncated: (summary: string) => string;
+    /** `lines` is 0 when the command printed nothing. */
+    exitCode: (code: number, lines: number) => string;
+    httpStatus: (status: number, lines: number) => string;
+    /** A summary whose result was cut down before it was recorded. */
+    outputTruncated: (summary: string) => string;
+    edited: (added: number, removed: number) => string;
+    /** `path` is empty when the call named none. */
+    wrote: (lines: number, path: string) => string;
+    /** One clause per kind of call in a run of quick calls, joined into a sentence. */
+    rollup: {
+        searched: (patterns: number) => string;
+        read: (files: number) => string;
+        ranCommands: (commands: number) => string;
+        fetched: (urls: number) => string;
+        loadedSkills: (skills: number) => string;
+        sentMessages: (messages: number) => string;
+        calledMcpTools: (tools: number) => string;
+        ranTools: (tools: number) => string;
+        sentence: (clauses: string[]) => string;
+    };
+}
+export declare const defaultToolStrings: ToolStrings;

package/dist/ai/agent/toolStrings.js

@@ -0,0 +1,35 @@
+//#region src/ai/agent/toolStrings.ts
+var count = (n, one, many) => `${n.toLocaleString()} ${n === 1 ? one : many}`;
+var defaultToolStrings = {
+	noOutput: "(no output)",
+	firstLine: (line, moreLines) => moreLines > 0 ? `${line}  (+${count(moreLines, "line", "lines")})` : line,
+	emptyFile: "Empty file",
+	readImage: "Read image",
+	readLines: (lines, more) => more > 0 ? `Read ${count(lines, "line", "lines")} (${more.toLocaleString()} more)` : `Read ${count(lines, "line", "lines")}`,
+	noMatches: "No matches",
+	foundMatches: (matches, files) => `Found ${count(matches, "match", "matches")} in ${count(files, "file", "files")}`,
+	foundFiles: (files) => `Found ${count(files, "file", "files")}`,
+	noFilesMatched: "No files matched",
+	truncated: (summary) => `${summary} (truncated)`,
+	exitCode: (code, lines) => lines > 0 ? `Exit ${code} · ${count(lines, "line", "lines")}` : `Exit ${code}`,
+	httpStatus: (status, lines) => `HTTP ${status} · ${count(lines, "line", "lines")}`,
+	outputTruncated: (summary) => `${summary} (output truncated)`,
+	edited: (added, removed) => added > 0 && removed > 0 ? `Added ${count(added, "line", "lines")}, removed ${count(removed, "line", "lines")}` : added > 0 ? `Added ${count(added, "line", "lines")}` : removed > 0 ? `Removed ${count(removed, "line", "lines")}` : "",
+	wrote: (lines, path) => path ? `Wrote ${count(lines, "line", "lines")} to ${path}` : `Wrote ${count(lines, "line", "lines")}`,
+	rollup: {
+		searched: (n) => `searched for ${count(n, "pattern", "patterns")}`,
+		read: (n) => `read ${count(n, "file", "files")}`,
+		ranCommands: (n) => `ran ${count(n, "shell command", "shell commands")}`,
+		fetched: (n) => `fetched ${count(n, "URL", "URLs")}`,
+		loadedSkills: (n) => `loaded ${count(n, "skill", "skills")}`,
+		sentMessages: (n) => `sent ${count(n, "message", "messages")}`,
+		calledMcpTools: (n) => `called ${count(n, "MCP tool", "MCP tools")}`,
+		ranTools: (n) => `ran ${count(n, "tool", "tools")}`,
+		sentence: (clauses) => {
+			const s = clauses.join(", ");
+			return s.charAt(0).toUpperCase() + s.slice(1);
+		}
+	}
+};
+//#endregion
+export { defaultToolStrings };

package/dist/ai/agent/toolfmt.d.ts

@@ -1,3 +1,4 @@
+import { type ToolStrings } from './toolStrings.js';
 export interface ToolHeader {
     label: string;
     arg?: string;
@@ -8,11 +9,15 @@ export declare function sanitizeLabel(s: string): string;
 export declare function sanitizePanelText(s: string): string;
 export declare function summarizeToolArgs(primary: string | undefined, argsJSON: string): string;
 export declare function fullToolArgs(primary: string | undefined, argsJSON: string): string;
-export declare function plural(n: number, noun: string): string;
 export declare function resultFailed(name: string, result: string): boolean;
 export declare function bashExitCode(body: string): [string, number, boolean];
-export declare function toolSummary(name: string, args: string, result: string, isError: boolean, editSummaryFn?: (toolName: string, argsJSON: string) => string): string;
+export interface ToolSummaryOptions {
+    /** The edit tools' own summary; passed in to keep this module free of the diff one. */
+    editSummary?: (toolName: string, argsJSON: string, strings: ToolStrings) => string;
+    strings?: ToolStrings;
+}
+export declare function toolSummary(name: string, args: string, result: string, isError: boolean, { editSummary, strings: t }?: ToolSummaryOptions): string;
 export declare function isGroupableTool(name: string): boolean;
-export declare function rollupSentence(names: string[]): string;
+export declare function rollupSentence(names: string[], t?: ToolStrings): string;
 export declare const AGENT_COLOR_NAMES: readonly ['blue', 'green', 'yellow', 'purple', 'cyan', 'orange', 'pink', 'red'];
 export declare function agentColorHex(name: string | undefined): string | null;