@nocobase/app-skills 0.1.0-beta.56 → 0.1.0-beta.58

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nocobase/app-skills",
3
- "version": "0.1.0-beta.56",
3
+ "version": "0.1.0-beta.58",
4
4
  "description": "Agent Skills for developing applications and plugins, upgrading and deploying NocoBase applications.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -385,13 +385,16 @@ test('native roles complete a purchasing loop with scoped selectors, editable li
385
385
  await reviewer.keyboard.press('Escape');
386
386
  await expect(reviewer.getByRole('menu')).toHaveCount(0);
387
387
  await reviewer
388
- .getByRole('button', { name: 'Appearance', exact: true })
388
+ .getByRole('button', { name: 'Open account menu', exact: true })
389
389
  .hover();
390
390
  await reviewer
391
- .getByRole('radiogroup', { name: 'Color mode' })
392
- .getByText('Dark', { exact: true })
391
+ .getByRole('menuitem', { name: 'Theme', exact: true })
392
+ .hover();
393
+ await reviewer
394
+ .getByRole('menuitemradio', { name: 'Dark', exact: true })
393
395
  .click();
394
396
  await reviewer.keyboard.press('Escape');
397
+ await reviewer.keyboard.press('Escape');
395
398
  await reviewer.getByRole('link', { name: title, exact: true }).click();
396
399
  await reviewer.setViewportSize({ width: 390, height: 844 });
397
400
  await expect(reviewer.locator('html')).toHaveClass(/dark/);
@@ -172,6 +172,7 @@ This handbook's project endpoints are called like this (`id` is the record id, `
172
172
 
173
173
  - Encode every id with `encodeURIComponent` before putting it into `path`; ids are strings and may come from a URL parameter or user input.
174
174
  - A list takes `q` for search, `orderBy` for ordering, and `page` with `pageSize` (20 by default, at most 100), and answers `{ data, meta: { page, pageSize, total } }`, typed `ProjectList` in [`example/types.md`](example/types.md). A feed or log pages with `pageSize` and `pageToken` instead, and its `meta` carries `nextPageToken` until the last page.
175
+ - Read row summaries with the list response or one batch request for the visible ids, never a child-resource request from every row: client N+1 multiplies network and server work as the page grows. Right: render `row.linkCount` supplied by the list; wrong: each row calls `projects/{id}/links` just to count links. The server batches that summary as [server routes](../../server-routes.md#lists-and-statistics-a-fixed-number-of-queries) describes.
175
176
 
176
177
  ### Parameters and response bodies
177
178
 
@@ -312,7 +313,7 @@ Other points:
312
313
 
313
314
  When realtime events refresh what a page shows:
314
315
 
315
- - An event that names items refreshes those items: gather the ids of a burst (a few hundred milliseconds), read only those rows, keep one such request in flight, and merge the answer into what the page holds. Read the whole list again only when its membership changed (an item joined or left it, or moved between its groups) or the event names nothing.
316
+ - An event that names items refreshes those items: use its changed fields to select affected sections, gather the ids of a burst (a few hundred milliseconds), read only those rows, keep one such request in flight, and merge the answer into what the page holds. Right: a `name` change refreshes the named row but leaves a status chart alone; wrong: every event refreshes the row, history and every chart. Read the whole list again only when its membership changed (an item joined or left it, or moved between its groups) or the event names nothing.
316
317
  - Do not read a whole list or overview again on every event.
317
318
  - Recompute a chart's figures at most every few seconds while it is visible, and not at all while the page is hidden; or update only the figure the event affects.
318
319
  - Read nothing for a page that is not shown; read it when it is shown again.
@@ -323,7 +324,9 @@ When realtime events refresh what a page shows:
323
324
  - Keep request keys stable: build them from the parameters that decide the data, not from values that change on every render or tick, such as the current time, or each change starts a new request.
324
325
  - Be careful with data loaded by components mounted on every page, such as navigation or a header badge: they run on every page and in every open tab, so they usually read a small fact rather than a list.
325
326
 
326
- The server side of these reads is in [server routes](../../server-routes.md#lists-and-statistics-a-fixed-number-of-queries).
327
+ Test a complete event-driven refresh cycle with a request spy and an explicit completion signal, excluding the initial load: assert an upper bound on reads per event per open tab, including any follow-up read. Right: `expect(refreshRequests.length).toBeLessThanOrEqual(1)` after the cycle completes and the changed row is visible; wrong: asserting only that a request occurred or that the refresh finished quickly. Counts catch duplicate topics and per-row reads without depending on machine speed.
328
+
329
+ The server side of these reads is in [list and statistics rules](../../server-routes.md#lists-and-statistics-a-fixed-number-of-queries); normalized log measurements are in [frequently called endpoints](../../server-routes.md#frequently-called-endpoints).
327
330
 
328
331
  ## Error handling
329
332
 
@@ -16,10 +16,10 @@ The shell is `client/routing/` and `client/layouts/`, with the header, sidebar a
16
16
 
17
17
  The icon button area in the top-right corner of the page is in `client/layouts/components/header-actions.tsx` (the layout's header, not `PageHeader`'s `actions`). Choose the hover behavior by what the entry does:
18
18
 
19
- | What the entry does | On hover | Examples |
20
- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------ |
21
- | Navigates to another page | Show a short tooltip describing the destination or purpose | Help, Notifications |
22
- | Opens a menu or configuration panel on the current page | Open the panel on hover; close it once the pointer leaves the trigger and panel area. Do not add a tooltip as well | Appearance, account menu |
19
+ | What the entry does | On hover | Examples |
20
+ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------- |
21
+ | Navigates to another page | Show a short tooltip describing the destination or purpose | Help, Notifications |
22
+ | Opens a menu or configuration panel on the current page | Open the panel on hover; close it once the pointer leaves the trigger and panel area. Do not add a tooltip as well | Account menu |
23
23
 
24
24
  ### Navigation entries
25
25
 
@@ -68,7 +68,7 @@ export function HeaderActions(): ReactElement {
68
68
  }
69
69
  ```
70
70
 
71
- - Keep every header entry the same size and style (`ACTION_LINK_CLASS` above matches the Appearance and account triggers).
71
+ - Keep every header entry the same size and style (`ACTION_LINK_CLASS` above matches the account trigger).
72
72
  - Keep the hint to a few words, such as "Help" or "Notification center"; do not write sentences like "Click here to go to…". It also shows on keyboard focus (Base UI's Tooltip does this by default; do not turn it off).
73
73
  - Translate both the tooltip and the `aria-label`; an unread count can be added to the `aria-label`.
74
74
  - Do not also write a native `title` attribute, or a second browser tooltip appears. An icon-only trigger must keep an accessible name.
@@ -79,7 +79,7 @@ export function HeaderActions(): ReactElement {
79
79
  - When the pointer moves from the trigger to the panel, or between a menu and the submenu it opens, the controls must stay reachable. Leave this interaction region, positioning, focus, and dismissal to the component.
80
80
  - Keep opening by click and touch, keyboard navigation, and closing with Esc.
81
81
  - Keep the component's default distinction: a panel opened by hover closes when the pointer leaves; a panel opened by click stays open until an outside click or Esc. Do not use custom mouseleave handlers, coordinate checks, timers, or extra open state to force a click-opened panel to close like a hover-opened one. Prefer the component's existing public options over reimplementing them yourself.
82
- - When selecting an item completes the action, use the component's built-in dismissal: the language radio items in the account menu have `closeOnClick`, so the menu closes immediately after a selection (`language-switcher.tsx` in the same directory); by default, radio items do not close the menu on selection. The header's Appearance popover (`client/theme/theme-settings.tsx`) stays open after a selection so you can keep adjusting, and closes the way `Popover` does by default.
82
+ - When selecting an item completes the action, use the component's built-in dismissal: the language radio items in the account menu have `closeOnClick`, so the menu closes immediately after a selection (`language-switcher.tsx` in the same directory); by default, radio items do not close the menu on selection. The account menu's Theme submenu (`client/theme/theme-settings.tsx`) keeps `closeOnClick={false}` so you can keep adjusting; Escape closes the submenu before the account menu.
83
83
 
84
84
  ### Consistency
85
85
 
@@ -89,6 +89,57 @@ Use the page's actual translated labels and response shape. Node identity is use
89
89
 
90
90
  jsdom verifies DOM continuity and request behavior, not layout or visible animation. In the actual application browser, exercise the affected flow from its entry through loading, completion and closing, with controlled slow responses or failures where relevant. Observe layout, animation, focus and scroll throughout; inspect animation events or computed animation when checking entrance replay. A final screenshot or CSS class assertion is insufficient. Distinguish component or synthetic fixture checks from actual application checks, which also cover routing, permissions and business APIs. Follow the workflow's session rules and report unavailable browser checks as unverified.
91
91
 
92
+ ### Browser stability
93
+
94
+ Assert the final result a user sees with auto-retrying locators; do not wait for an uncontrolled intermediate state or sleep a fixed duration, because a fast response can skip that state and a slow one can outlast the sleep. Right: `await expect(page.getByText('Project saved')).toBeVisible()`; wrong: waiting for a brief spinner before asserting success, or `await page.waitForTimeout(1000)`. Controlled pending-state tests above deliberately hold the response, so their loading assertions are deterministic.
95
+
96
+ Retry geometry assertions with `expect.poll` or `toPass` until the intended layout settles; one `boundingBox()` snapshot can capture an animation frame. For example, with a `panel` locator and the expected content edge `contentRight`:
97
+
98
+ ```ts
99
+ // Right: re-read geometry on each attempt.
100
+ await expect
101
+ .poll(async () => (await panel.boundingBox())?.x)
102
+ .toBeGreaterThanOrEqual(contentRight);
103
+ // Wrong: const box = await panel.boundingBox(); expect(box!.x).toBe(600);
104
+ ```
105
+
106
+ After navigation or opening an overlay, wait for an existing control's interactive signal before clicking: visible markup or a changed URL can precede loaded controls and the end of an opening transition. Right: `await expect(saveButton).toBeEnabled(); await saveButton.click()` when Save is enabled after loading, or `await expect(nameInput).toBeFocused()` when focus is placed after opening; wrong: click immediately after `page.goto()` or seeing the dialog shell. Use the application's existing enabled state or focus behavior rather than adding a test-only ready marker or a fixed wait.
107
+
108
+ Register a request interceptor once per page-scoped test, let subsequent traffic through with `route.fallback()`, and release every held request in `finally`: failed assertions otherwise leave requests blocked and hang teardown. Do not call `unroute` or replace a handler while it is running. This schematic gate holds all matching requests; `appUrl` is the running application's entry URL:
109
+
110
+ ```ts
111
+ const gate = Promise.withResolvers<void>();
112
+ const handlers = new Set<Promise<void>>();
113
+ let holding = true;
114
+ await page.route('**/api/projects*', (route) => {
115
+ const done = (async () => {
116
+ if (holding) await gate.promise;
117
+ await route.fallback();
118
+ })();
119
+ handlers.add(done);
120
+ return done.finally(() => {
121
+ handlers.delete(done);
122
+ });
123
+ });
124
+ try {
125
+ await page.goto(appUrl);
126
+ // Exercise the controlled pending state, then allow final results.
127
+ holding = false;
128
+ gate.resolve();
129
+ await expect(page.getByRole('heading', { name: 'Projects' })).toBeVisible();
130
+ } finally {
131
+ holding = false;
132
+ gate.resolve();
133
+ await Promise.allSettled([...handlers]);
134
+ }
135
+ // Keep the fallback handler until the page fixture closes.
136
+ // Wrong: page.unroute(pattern) while its handler is still awaiting the gate.
137
+ ```
138
+
139
+ Use `Promise.allSettled` during cleanup so a fallback failure after the page closes does not replace the original assertion failure.
140
+
141
+ Investigate intermittent failures as possible product races first: if a late response overwrites the current record, fix response ownership in the product and keep a regression test. Right: reproduce with controlled response ordering and correct the product; wrong: add retries, increase timeouts or weaken the assertion so the race passes unnoticed.
142
+
92
143
  ## Running tests
93
144
 
94
145
  Run the related test files with the application's matching React configuration, then lint them. Inspect its tsconfig includes before claiming the tests were typechecked; many templates exclude Vitest tests from their build configs. The complete client example uses `--config vitest.client.config.ts`:
@@ -108,3 +159,19 @@ End-to-end tests run against a running application. `playwright.config.ts` sets
108
159
  ```bash
109
160
  pnpm test:e2e
110
161
  ```
162
+
163
+ Each case creates and cleans up its own records and can run alone or in any order; depending on an earlier test's data makes failures order-dependent. Right: create a uniquely named project in that case's fixture; wrong: edit the project created by the previous case. Parallel workers must not write a shared state file: use a per-worker path such as `storage/e2e/auth-${workerIndex}.json` for mutable authentication state. A single global setup may produce a read-only authentication snapshot shared by independent contexts; cases must not overwrite it or mutate shared account settings.
164
+
165
+ To find unstable cases, run the whole suite N times on the same runner, then use `--repeat-each` for suspects: isolated repetition alone misses interference from other cases. Keep each run's raw reporter output, including full `testId`, project, repeat index, retry and error/trace attachments; abbreviated titles lose the identity needed to compare failures. For example, with an authenticated application already running and `N` set to the desired suite count:
166
+
167
+ ```bash
168
+ mkdir -p storage/e2e/results
169
+ for run in $(seq 1 "$N"); do
170
+ PLAYWRIGHT_BLOB_OUTPUT_FILE="storage/e2e/results/suite-$run.zip" \
171
+ pnpm test:e2e --reporter=blob --retries=0
172
+ done
173
+ PLAYWRIGHT_BLOB_OUTPUT_FILE=storage/e2e/results/suspect.zip \
174
+ pnpm test:e2e tests/playwright/projects.test.ts --repeat-each=20 --reporter=blob --retries=0
175
+ ```
176
+
177
+ Right: retain all blob reports (which carry full test ids) and their failures, plus the tested commit and command; wrong: rerun until green and keep only a title-only summary. Repetition diagnoses failures; it is not a retry policy for accepting them.
@@ -14,7 +14,7 @@ The theming in the shadcn skill does not apply here: no `shadcn apply`, `shadcn
14
14
  | `client/styles.css` | Imported by `client/index.tsx`. Imports every preset (`default.css` first) and connects the variables to Tailwind: colors become `bg-*`, `text-*` and similar classes, `--radius` derives the `rounded-*` scale, and `@utility` adapters keep the shadow classes on the runtime variables |
15
15
  | `client/theme/theme-presets.ts` | The preset registry: `id` and `labelKey` per preset. The first entry is the fallback |
16
16
  | `appearance.themes.<id>` in `client/locales/*.ts` | Preset labels |
17
- | `client/theme/theme-settings.tsx` | The Appearance popover: color mode and theme |
17
+ | `client/theme/theme-settings.tsx` | The account menu’s Theme submenu: color mode and theme |
18
18
  | `client/theme/theme-provider.tsx`, `client/theme/theme-context.ts` | `AppThemeProvider`, which `client/react-providers.ts` mounts in the `root` layer, and `useThemePreset()` |
19
19
  | `client/theme/theme-preferences.ts` | Storage keys, configured defaults, and `initializeTheme()`, which `client/index.tsx` calls at startup |
20
20
  | `client.app.defaultColorScheme` and `client.app.defaultTheme` in `config.yml` | Application defaults, see [section 6](#6-application-defaults) |
@@ -22,7 +22,7 @@ The theming in the shadcn skill does not apply here: no `shadcn apply`, `shadcn
22
22
 
23
23
  How a preset takes effect:
24
24
 
25
- - A preset file sets CSS variables on `:root[data-theme='<id>']` for light and on `:root.dark[data-theme='<id>']` for dark, and the same values on `.theme-preview[data-theme='<id>']` for the thumbnails in the Appearance popover.
25
+ - A preset file sets CSS variables on `:root[data-theme='<id>']` for light and on `:root.dark[data-theme='<id>']` for dark, and the same values on `.theme-preview[data-theme='<id>']` for isolated theme previews.
26
26
  - The provider writes the chosen preset to the `data-theme` attribute of `<html>`, and `next-themes` sets the `light` or `dark` class and `color-scheme`. The `dark:` variant in `client/styles.css` is `&:is(.dark *)`, so it follows the same class.
27
27
  - Utilities read the variables at runtime: `bg-card` is `var(--card)` and `p-4` is `calc(var(--spacing) * 4)`. Switching the preset or the mode restyles every page without a rebuild.
28
28
 
@@ -200,7 +200,7 @@ Each adapter has this form:
200
200
  ### Scope of the rules
201
201
 
202
202
  - Each preset's light rule defines every color and every non-color token. Its dark rule defines every color and may override non-color values; anything it leaves out comes from the preset's light rule.
203
- - The same declarations go on the preview selectors `.theme-preview[data-theme='<id>']` and `:root.dark .theme-preview[data-theme='<id>']`, aliases included. A custom property inherits its resolved value, so an alias such as `--font-heading: var(--font-sans)` or `--sidebar: var(--card)` declared only for the page would carry the page's preset into another preset's thumbnail. Listing the preview selector in the same rule, as the template files do, keeps the two identical.
203
+ - The same declarations go on the preview selectors `.theme-preview[data-theme='<id>']` and `:root.dark .theme-preview[data-theme='<id>']`, aliases included. A custom property inherits its resolved value, so an alias such as `--font-heading: var(--font-sans)` or `--sidebar: var(--card)` declared only for the page would carry the page's preset into an isolated preview of another preset. Listing the preview selector in the same rule, as the template files do, keeps the two identical.
204
204
  - Do not reset whole Tailwind namespaces, and do not add per-page overrides to create a theme.
205
205
  - Extend the shared token contract only after design approval. An approved token needs a Tailwind mapping in `client/styles.css`, a value in every preset rule, and an entry in the token lists of `tests/client/theme-tokens.test.ts`. Do not change `components.json`, routes, component props or plugin APIs as a side effect of theme work.
206
206
 
@@ -210,11 +210,10 @@ Some values stay fixed on purpose. Know which ones, and keep your own explicit.
210
210
 
211
211
  - Arbitrary values (`text-[14px]`, `mt-[7px]`, `rounded-[…]`), container widths (`max-w-2xl`, `w-xs`), percentages and viewport units do not follow the theme, and neither do `rounded-xs`, `rounded-full` or `shadow-none`. Explicit line heights (`leading-*`, `text-sm/6`) replace the preset's line heights.
212
212
  - The template's own exceptions:
213
- - The Appearance popover panel is `w-xs max-w-[calc(100vw-2rem)]`, with a comment saying its width stays independent of density while its content uses tokens.
214
213
  - The small sizes of buttons, toggles and native selects cap their radius (see "Radius").
215
214
  - `index.html` sets `<meta name="theme-color" content="#171717">`, which colors the browser UI on some mobile browsers and does not follow the theme; change it by hand when a preset's page color changes noticeably.
216
215
  - `index.html` draws a loading indicator with literal colors that follow only `prefers-color-scheme`. It renders before the client restores the preferences, so it cannot use the tokens.
217
- - When a size must stay fixed, make it visible: a comment next to the value saying why, as `client/theme/theme-settings.tsx` does, and an entry in the design file, as guideline F7 in [`../ui-guidelines.md`](../ui-guidelines.md) requires. Colors, font sizes and spacing do not qualify.
216
+ - When a size must stay fixed, make it visible: a comment next to the value saying why, and an entry in the design file, as guideline F7 in [`../ui-guidelines.md`](../ui-guidelines.md) requires. Colors, font sizes and spacing do not qualify.
218
217
 
219
218
  ### Constraints from the token test
220
219
 
@@ -346,7 +345,7 @@ The steps below add a preset with the id `forest`.
346
345
 
347
346
  `ThemePresetId` is derived from the array, so the new id is accepted wherever a preset id is typed. `defaultThemePreset` does not decide the fallback, and no template code reads it; keep it equal to the first entry.
348
347
 
349
- 5. **Add the label** to `appearance.themes` in every application locale file, spreading the system group as [`i18n.md`](i18n.md) describes; removing or renaming a template preset rewords its key after the spread rather than editing `client/locales/system/`. `zh-CN.ts` is typed from `en-US.ts`, so the two must have the same keys or the type check fails; a label missing from both fails `tests/client/app-locale-coverage.test.ts`, which reads the registry's `labelKey` (without the label the popover would show the capitalized id). Give each preset a distinct label: it is the accessible name of the preset's radio option. Translation rules are in [`i18n.md`](i18n.md).
348
+ 5. **Add the label** to `appearance.themes` in every application locale file, spreading the system group as [`i18n.md`](i18n.md) describes; removing or renaming a template preset rewords its key after the spread rather than editing `client/locales/system/`. `zh-CN.ts` is typed from `en-US.ts`, so the two must have the same keys or the type check fails; a label missing from both fails `tests/client/app-locale-coverage.test.ts`, which reads the registry's `labelKey` (without the label the submenu would show the capitalized id). Give each preset a distinct label: it is the accessible name of the preset's radio option. Translation rules are in [`i18n.md`](i18n.md).
350
349
 
351
350
  ```ts
352
351
  // client/locales/en-US.ts
@@ -372,8 +371,8 @@ The steps below add a preset with the id `forest`.
372
371
  };
373
372
  ```
374
373
 
375
- 6. **Leave the popover alone.** The Appearance popover lists every registered preset in registry order, takes each label from the locale, and draws each thumbnail from the same CSS variables through `.theme-preview` and `data-theme`. Do not write a second palette in JavaScript. The presets sit in a two-column grid without search, so the popover suits a handful of presets.
376
- 7. **Check it.** Add the resources and the Chinese and system fallbacks for any new font. In light and dark, check body text, headings, code, long text, controls, navigation, charts where present, spacing, corners and shadows: text meets WCAG AA contrast (guideline A5; 4.5:1 for normal text), nothing is clipped, and keyboard focus is visible. The thumbnail shows colors, not typography or layout. Then run the checks in [section 7](#7-verify).
374
+ 6. **Reuse the Theme submenu.** The account menu lists every registered preset as a menu radio item in registry order and takes each label from the locale. Keep it inside the account menu; guest and optional pages inherit the saved theme without a separate appearance entry. Do not add a second theme selector or palette in JavaScript.
375
+ 7. **Check it.** Add the resources and the Chinese and system fallbacks for any new font. In light and dark, check body text, headings, code, long text, controls, navigation, charts where present, spacing, corners and shadows: text meets WCAG AA contrast (guideline A5; 4.5:1 for normal text), nothing is clipped, and keyboard focus is visible. Then run the checks in [section 7](#7-verify).
377
376
 
378
377
  ## 4. Change or remove a preset
379
378
 
@@ -390,7 +389,7 @@ The steps below add a preset with the id `forest`.
390
389
  A user makes two independent choices, each saved in the browser: the color mode (Light, Dark or System) and the preset.
391
390
 
392
391
  - `next-themes` owns the color mode: the `light` or `dark` class on `<html>` and its `color-scheme`. A preset only sets `data-theme`. Do not make a preset force a mode. Keep DOM changes in `client/theme/`.
393
- - The Appearance popover (`client/theme/theme-settings.tsx`) sits in the header of the App layout (`client/layouts/components/header-actions.tsx`) and in the top-right corner of guest and optional pages (`client/routing/standalone-page-layout.tsx`). It opens on hover, click or keyboard. A choice applies and is saved at once, the panel stays open for further changes, and Escape closes it and returns focus to the trigger. Its copy comes from `appearance.title`, `appearance.mode`, `appearance.preset`, `appearance.light`, `appearance.dark`, `appearance.system` and `appearance.themes.<id>`. The hover and dismissal rules for header entries are in [section 2 of `shell.md`](shell.md#2-header-icon-buttons).
392
+ - The Theme submenu (`client/theme/theme-settings.tsx`) lives inside the account menu (`client/layouts/components/user-menu.tsx`), whose avatar opens on hover, click or keyboard. A choice applies and is saved at once, and the submenu stays open for further changes. Escape first closes the submenu and returns focus to Theme, then closes the account menu and returns focus to the avatar. Guest and optional pages (`client/routing/standalone-page-layout.tsx`) inherit saved preferences without a theme entry. The submenu's copy comes from `appearance.title`, `appearance.mode`, `appearance.preset`, `appearance.light`, `appearance.dark`, `appearance.system` and `appearance.themes.<id>`.
394
393
  - Code that needs a choice reads it from the provider. `useTheme()` from `next-themes`, also re-exported by `client/theme/index.ts`, gives `theme` (`light`, `dark` or `system`), `resolvedTheme` (the mode actually applied) and `setTheme`. `useThemePreset()` from `client/theme/theme-context.ts` gives `preset` and `setPreset`. Both need `AppThemeProvider`, and `useThemePreset()` throws outside it. Do not read or write the storage keys or the `<html>` attributes yourself, and do not keep a copy of a choice in component state.
395
394
  - The storage keys come from `resolveAppBase()`, the deployment base path, not from the current route or the first path segment: `/crm/` becomes `crm`, `/team/crm/` becomes `team%2Fcrm`, and the root becomes `%2F`. The keys are `nocobase:<scope>:theme:color-scheme` and `nocobase:<scope>:theme:preset`. They are browser-local and per application, not synchronized with the account: two applications on the same origin keep separate choices, and tabs of the same application follow each other through `storage` events.
396
395
  - `client/index.tsx` calls `initializeTheme()` before the application starts. It applies the saved or default choices to `<html>` (class, `data-theme` and `color-scheme`) and removes an invalid saved mode before `next-themes` can read it. No script runs before the first paint; the loading indicator in `index.html` follows only `prefers-color-scheme`.
@@ -434,19 +433,19 @@ pnpm exec vitest run tests/client/theme-tokens.test.ts tests/client/theme-prefer
434
433
 
435
434
  - `theme-tokens.test.ts` checks that every registered preset defines all 32 colors and every non-color token in its light rule and every color in its dark rule, with the same declarations on the preview selectors; that Compact and Spacious differ only in dimensions, with Compact's spacing smaller; and, by compiling `client/styles.css` with Tailwind, that the color, font, size, line height, spacing, radius and shadow classes and the `body`, `h1` and `code` fonts still read the runtime variables.
436
435
  - `theme-preferences.test.ts` checks that Compact is first, the storage keys for each base path, restoring both choices at startup without reading another application's keys, and the fallbacks for invalid values, removed presets and unavailable storage.
437
- - `client-theme.test.tsx` checks the provider and the popover: labels in en-US and zh-CN, choosing and saving, configured defaults against saved choices, startup and provider agreeing, clearing and syncing across tabs, invalid values, and unavailable storage.
436
+ - `client-theme.test.tsx` checks the provider and the Theme submenu: labels in en-US and zh-CN, choosing and saving, configured defaults against saved choices, startup and provider agreeing, clearing and syncing across tabs, invalid values, and unavailable storage.
438
437
 
439
- Format the changed CSS and TypeScript files with Prettier, and lint only the TypeScript ones (ESLint has no CSS configuration; see ["Self-check before finishing" in `../frontend-dev.md`](../frontend-dev.md#self-check-before-finishing)). After changing the popover or its header entry, also run `pnpm exec vitest run tests/client/header-hover.test.tsx` (hover, keyboard and Escape). After changing the registry or a locale file, type-check the client with `pnpm exec tsc -p tsconfig.json --noEmit` and run `pnpm exec vitest run tests/client/app-locale-coverage.test.ts`.
438
+ Format the changed CSS and TypeScript files with Prettier, and lint only the TypeScript ones (ESLint has no CSS configuration; see ["Self-check before finishing" in `../frontend-dev.md`](../frontend-dev.md#self-check-before-finishing)). After changing the Theme submenu or its account-menu entry, also run `pnpm exec vitest run tests/client/header-hover.test.tsx` (hover, keyboard and Escape). After changing the registry or a locale file, type-check the client with `pnpm exec tsc -p tsconfig.json --noEmit` and run `pnpm exec vitest run tests/client/app-locale-coverage.test.ts`.
440
439
 
441
440
  A compiled CSS check cannot prove the layout. Check in a browser, scaled to the change:
442
441
 
443
442
  - **Any token change** (a color, font, size, spacing, radius or shadow):
444
- - With `pnpm dev` running, append `tests/fixtures/theme-tokens.html` to the `Local:` URL it prints, which already ends with the base path and a slash (`http://127.0.0.1:13000/main/tests/fixtures/theme-tokens.html`). The page renders the real sidebar, primitives and Appearance popover with sample headings, serif and code text, buttons, an input, a popover rendered in a portal, a card, the chart palette, and all seven radii and shadows, in mixed English and Chinese text. It mounts no translations, so the popover shows each preset's capitalized id (Default rather than Spacious); check labels in the application itself. It runs under the application's base path, so it shares the application's saved choices.
443
+ - With `pnpm dev` running, append `tests/fixtures/theme-tokens.html` to the `Local:` URL it prints, which already ends with the base path and a slash (`http://127.0.0.1:13000/main/tests/fixtures/theme-tokens.html`). The page renders the real sidebar, primitives and an account menu with the Theme submenu, plus sample headings, serif and code text, buttons, an input, a popover rendered in a portal, a card, the chart palette, and all seven radii and shadows, in mixed English and Chinese text. It mounts no translations, so the submenu shows each preset's capitalized id (Default rather than Spacious); check labels in the application itself. It runs under the application's base path, so it shares the application's saved choices.
445
444
  - Look at Light and Dark with each preset on a page that stacks panels and dividers, including at 375px wide (the screenshot tool's `colorScheme`, `theme` and `viewport` shots do this in one run; see [`../scripts/capture.md`](../scripts/capture.md)).
446
445
  - Measure contrast for every pair you changed, in both modes: body and muted text on `--background`, `--card` and `--popover`, `--primary-foreground` on `--primary`, and `--destructive` on the surfaces. In Chrome DevTools, inspect an element, click the color swatch of its `color` in the Styles pane: the picker shows the contrast ratio against the background and whether it passes AA (4.5:1 for normal text).
447
446
  - **A font, size, spacing or shadow change** additionally: temporarily set clearly different values and confirm the pages follow, since a token name existing does not prove it is used; revert afterwards. Look for fixed sizes, explicit line heights, constrained controls and portal content such as menus, dialogs and popovers.
448
- - **Adding, removing or renaming a preset, or changing the registry, the popover or the preference code** additionally:
449
- - Reload and confirm both choices are restored. Operate the popover with the keyboard: Tab into a group, arrow keys within it, Escape to close with focus back on the trigger.
447
+ - **Adding, removing or renaming a preset, or changing the registry, the Theme submenu or the preference code** additionally:
448
+ - Reload and confirm both choices are restored. Operate the account menu and Theme submenu with the keyboard: arrow keys navigate items, Enter selects an option, and Escape closes the submenu with focus back on Theme, then closes the account menu with focus back on the avatar.
450
449
  - Two tabs of the application stay in sync; an application under another base path on the same origin is unaffected.
451
450
  - Clearing site data restores the configured defaults; with storage blocked, switching still works; a saved id of a removed preset falls back.
452
451
  - Images, iframes, style-isolated third-party content and plugin content with literal colors do not follow the theme. Check them separately.
@@ -52,7 +52,7 @@ The one way to pick an agent: a trigger with the agent's avatar (availability do
52
52
 
53
53
  ### agent-chat
54
54
 
55
- The agents' chat: a side panel beside the content area, switching between the online agent and runner agents when both are configured, with the conversation, live steps, a composer with page-context chips and files to send (attach, paste, drop), the agent picker, the history, a full-page conversation view, and header, floating and Ask agent launchers. Use it to let people talk to agents from any page. Wired to the headless hooks of @nocobase/app-plugin-agents/client/chat.
55
+ A simple agent conversation panel with shared page/panel headers, history, composer and launchers. It has no association requirements. For related-work slots and conversation details, add agent-chat-details.
56
56
 
57
57
  - Kind: block
58
58
  - Install: `yes n | pnpm exec shadcn add @nocobase/agent-chat`
@@ -62,6 +62,18 @@ The agents' chat: a side panel beside the content area, switching between the on
62
62
  - Example: `@nocobase/agent-chat-demo` (`pnpm exec shadcn view @nocobase/agent-chat-demo`)
63
63
  - After installing: Requires the agents plugin (and the file plugin on the server for files sent in chat): wrap the routes in ChatProvider from @nocobase/app-plugin-agents/client/chat (pass memoryScope, the signed-in person's id, so a new conversation starts with the agent they used last; pass conversationPath when ChatConversationPage has a route such as /chat/:conversationId), optionally with ChatExtensionsContext for cards among the messages. Render ChatPanel as a sibling of <main> inside a `relative flex` row, ChatHeaderButton in the header and ChatFloatingButton anywhere; add the plugin's chatLinkRoutes(base) for links that open the panel; spread locales/ into client/locales/.
64
64
 
65
+ ### agent-chat-details
66
+
67
+ The agent chat workspace: the conversation list, one conversation and its details (linked work such as tasks, context usage, runtime and agent), laid out by its own width as one column, list beside conversation, or list, conversation and details. Mount it as a full page with the selection in the address, or in the side panel with LinkedChatPanel; both are the same component. Linked work uses generic ConversationLink sections; applications add their own through narrow slots. No task or project dependency.
68
+
69
+ - Kind: block
70
+ - Install: `yes n | pnpm exec shadcn add @nocobase/agent-chat-details`
71
+ - Installs to: `client/extensions/nocobase-agent-chat/`
72
+ - Plugin dependencies: none
73
+ - Also installs: `@nocobase/agent-chat`
74
+ - Example: `@nocobase/agent-chat-details-demo` (`pnpm exec shadcn view @nocobase/agent-chat-details-demo`)
75
+ - After installing: Mount ChatWorkspace on a page (selection in the address) and LinkedChatPanel under the same ChatProvider as the simple ChatPanel (selection in the panel store); both are the same workspace. Add application-specific parts through narrow slots: list.heading, list.row (extra, facts, status), list.filters/filter, renderBody, metadata, detailsMetadata and scope; slots[kind] renders a related-work section and renderSummary the summary row. Passive details reuse cached conversation and usage snapshots; no polling is added.
76
+
65
77
  ## Approval
66
78
 
67
79
  ### approval-ui
@@ -61,6 +61,8 @@ There are two pagination styles, and a list uses one of them:
61
61
 
62
62
  `pageSize` defaults to 20 and is capped at 100; a route that needs a larger cap keeps it and says why in a comment. Search is `q`, ordering is `orderBy`.
63
63
 
64
+ When a filter selects several values of the same field, accept them in one request and document and validate the encoding (for example, comma-separated enum values with OR semantics): splitting by value multiplies requests and makes pagination and totals inconsistent. Right: `GET /orders?status=open,closed`; wrong: separate `status=open` and `status=closed` requests merged in the client. Reject unknown values and bound the number of values through `apiValidator()` like any other input.
65
+
64
66
  A bounded configuration list, such as providers, roles, templates or catalogs, may skip paging, but it still answers `{ data, meta }` with at least `meta.total`. Every other list pages. `meta` may carry fields beyond the standard ones when a list has more to say about itself.
65
67
 
66
68
  Data formats:
@@ -240,12 +240,13 @@ A route that answers many rows or figures reads them with a fixed number of quer
240
240
  - Read each kind of data once for all rows: one query with `IN (...)` over the row ids, then join the results in memory. Never call a per-item function or Repository read inside a loop or a `Promise.all` over rows.
241
241
  - When per-item database work genuinely cannot be batched, bound its concurrency to a small number rather than starting one query per item at once: an unbounded `Promise.all` can exhaust the connection pool and stall every other request, not just this one.
242
242
  - A list row carries only what the row shows. Expensive per-item work — diagnostics, "why is this waiting", full histories — belongs to the item's own detail endpoint, which the client usually reads when a detail view opens. When you add a field to a list response, check how much it adds to the response size across a full page of rows.
243
+ - A detail endpoint computes only what its consumer displays. Put expensive optional sections behind a separate endpoint or an explicit, validated option, and do not compute them before checking the option: unused enrichment can dominate a frequently refreshed detail read. Right: `includeProgress ? await computeProgress(id) : undefined`; wrong: always computing progress and then dropping it from the browser response. A caller hint in a request log is not a permission or a substitute for the declared response contract.
243
244
  - A component that needs one small fact, such as whether the viewer follows an item, gets a small endpoint answering that fact rather than reading a whole list or overview.
244
245
  - Aggregate in the database: `COUNT`, `SUM`, `GROUP BY` through the Repository's `count`/`groupBy` or the query builder. Never load rows to count or sum them in JavaScript.
245
246
  - One chart is one request, so charts load, fail, refresh and cache on their own. Each chart's request computes its figures with a fixed number of aggregate queries: one `GROUP BY` day, not a query per day or per item.
246
247
  - Bound every statistic by a time range or a limit. A column a large table is filtered or grouped by needs an index — see [migrations](migrations.md).
247
248
  - An aggregate that is expensive and read often is cached briefly with the application's cache (`cachingToken` from `@nocobase/app-server/caching`) rather than recomputed per request.
248
- - Test it: the number of queries a list or statistics endpoint makes stays the same when the rows or groups grow. See [testing](testing.md#what-to-test-by-change).
249
+ - Test it with query-count upper bounds at small and large row/group counts, not elapsed time: machine speed can hide duplicated work. Right: `expect(queryCount).toBeLessThanOrEqual(3)` for both ten and a thousand rows; wrong: `expect(elapsedMs).toBeLessThan(100)`. See [testing](testing.md#what-to-test-by-change).
249
250
 
250
251
  The browser side — refreshing such a list or chart from realtime events — is in [client API requests](frontend/references/api.md#keeping-lists-and-charts-live).
251
252
 
@@ -256,6 +257,9 @@ An endpoint called on a timer — polling, a heartbeat, a status badge every ope
256
257
  - Usually keep it read-only, without writes or a transaction. Work that has to write, such as recording last-seen times or cleaning up, can often move to a less frequent place: a scheduled job (see [services and jobs](services-and-jobs.md#work-that-runs-on-a-schedule)), or a write only when the value actually changed.
257
258
  - Read-only code usually needs no transaction, here or anywhere else. A transaction holds a connection for its whole duration and can make reads cost more; use one only for writes that must succeed or fail together.
258
259
  - Prefer answering a small fact over a list or overview, as the section above describes, and consider caching it briefly when many clients ask the same question.
260
+ - Publish one realtime signal per domain change, with affected ids and changed fields (within the topic's authorization scope), rather than publishing the same change on several topics: a page subscribed to all of them otherwise multiplies its reads. Right: one `orders` event with `{ ids: [id], changed: ['status'] }`; wrong: that same change on `orders`, `orderDetails` and `orderStats`. Consumers use the payload as described in [client refresh rules](frontend/references/api.md#keeping-lists-and-charts-live).
261
+
262
+ Measure before and after with request logs on the same dataset and action sequence. Group completion entries by `req.method`, route template `req.path`, safe `req.query` and `req.caller` to separate filters and browser, CLI and runner traffic; caller labels are transport hints, not authenticated identities. Query logging omits unsafe values, so do not infer an absent filter or add raw URLs, secrets or free text to recover it. Compare queries per request and requests per event per open tab, accounting separately for initial loads and background polling: time-window totals change with tab count and activity. Right: 30 browser reads / 5 events / 2 subscribed tabs = 3 reads per event per tab; wrong: claiming an improvement because one minute had fewer total requests. Lock the resulting request bound in the [frontend tests](frontend/references/api.md#keeping-lists-and-charts-live).
259
263
 
260
264
  ## Keep the layers apart
261
265