[IMP] documentation: update documentation about plugin differences

Task: 6428159

Author: pro-odoo

CLAUDE.md

@@ -25,12 +25,14 @@ Two layers: **Model** (headless data + logic) and **UI** (Owl components + canva
 ### Model: CQS via commands, getters, plugins
 
 - `Model` (`src/model.ts`) is the entry point. Mutate via `model.dispatch("CMD_NAME", payload)`; read via `model.getters.someGetter(...)`. All command types are in `src/types/commands.ts`. Commands run through a chain (`allowDispatch` → `beforeHandle` → `handle` → `finalize`) on every registered plugin.
-- **Plugins** (`src/plugins/`) own slices of state and expose getters. Categories:
-  - `core/` — persistent business data (cells, sheets, ranges, charts, pivots, conditional formats, tables, figures, named ranges…). One plugin per data structure. Participate in import/export.
-  - `evaluation/` — derived state computed from core (cell evaluation, computed style, chart runtime, dynamic tables, custom colors…).
-  - `ui_stateful/` — UI-only state (active sheet, selection, viewport, edition…).
-  - `ui_feature/` — high-level features expressible as lower-level command sequences (sort, autofill, find/replace, clipboard handlers, etc.).
-    Registries in `src/plugins/plugin_registries.ts` declare which plugins are loaded.
+- **Plugins** (`src/plugins/`) own slices of state and expose getters. Three base classes, four categories:
+  - `CorePlugin` → `core/` — persistent business data (cells, sheets, ranges, charts, pivots, conditional formats, tables, figures, named ranges…). One plugin per data structure. Participate in import/export.
+  - `EvaluationPlugin` → `evaluation/` — derived state computed from core (cell evaluation, computed style, chart runtime, dynamic tables, filter/subtotal evaluation, custom colors…).
+  - `UIPlugin` → `ui_stateful/` — UI-only state (selection, clipboard, header positions, figures…).
+  - `UIPlugin` → `ui_feature/` — high-level features expressible as lower-level command sequences (sort, format, insert pivot, local history…).
+    Registries in `src/plugins/plugin_registries.ts` declare which plugins are loaded. They are `PluginRegistry` instances that check at `add()`/`replace()` time that the plugin extends the expected base class, so a plugin cannot be registered in the wrong category.
+- **Getter scopes** (`src/types/getters.ts`): `CoreGetters` ⊂ `EvaluationGetters` ⊂ `RenderingGetters` ⊂ `Getters`. Each plugin only receives the scope of its category — a core plugin cannot read evaluation getters, and an evaluation plugin cannot read UI getters.
+- **Evaluation commands** (`EVALUATE_CELLS`, `EVALUATE_CHARTS`, see `evaluationCommandTypes`/`isEvaluationCommand` in `src/types/commands.ts`) are a distinct dispatch path: they skip `allowDispatch`, an `EvaluationPlugin` may dispatch them (and nothing else), and no non-evaluation command may be dispatched while a top-level evaluation command is being handled. Both violations throw.
 - **Range / cell coordinates** flow through `range.ts` plugin; never store `A1` strings directly in plugin state.
 - **History**: `src/history/` provides undo/redo by recording inverse commands; plugins use `this.history.update(...)` to make mutations trackable.
 - **Collaborative**: `src/collaborative/` synchronizes commands across clients; `state_observer.ts` and command transforms keep concurrent edits consistent.
@@ -46,7 +48,7 @@ Two layers: **Model** (headless data + logic) and **UI** (Owl components + canva
 ### UI
 
 - `src/components/` — Owl components (sidepanels, top bar, bottom bar, composer, popovers, figures, charts wrappers, etc.).
-- `src/components/grid/` and renderer plugins draw the grid on `<canvas>` (`renderer` family in `evaluation`). The DOM only hosts overlays, composer, figures, popovers.
+- `src/components/grid/` draws the grid on `<canvas>`. Draw layers come from `UIPlugin.drawLayer` (`ui_stateful/selection`, `ui_stateful/clipboard`, `ui_feature/collaborative`) and from stores extending `SpreadsheetStore`; `EvaluationPlugin` cannot draw. The DOM only hosts overlays, composer, figures, popovers.
 - `src/stores/` + `src/store_engine/` — Owl-store-style reactive stores for UI state that doesn't belong in the Model (notifications, sidepanels, hovered link, etc.). Components access them via the store engine, not directly.
 - `src/registries/` — extension points (menus, side panels, autofill rules, clipboard handlers, topbar components, cell popovers…). Adding a feature usually means registering in one of these plus a plugin.
 - `src/selection_stream/` — keyboard/mouse selection state machine, observed by composer, find-and-replace, etc.

doc/add_function.md

@@ -454,13 +454,13 @@ The `compute` function inside the function definition can use external dependenc
 
 To adhere to the o-spreadsheet's architecture, we'll use a dedicated [plugin](./extending/architecture.md#plugins) for this purpose. The `compute` function can access relevant data using its getters.
 
-First, let's create the `CurrencyPlugin` class that extends `UIPlugin` and registers the necessary getters:
+First, let's create the `CurrencyPlugin` class that extends `EvaluationPlugin` and registers the necessary getters. It has to be an evaluation plugin (or a core plugin): the `compute` function only receives `EvaluationGetters`, so a getter defined on a `UIPlugin` would not be reachable from a spreadsheet function.
 
 ```ts
-const { uiPluginRegistry } = o_spreadsheet.registries;
-const { UIPlugin } = o_spreadsheet;
+const { evaluationPluginRegistry } = o_spreadsheet.registries;
+const { EvaluationPlugin } = o_spreadsheet;
 
-class CurrencyPlugin extends UIPlugin {
+class CurrencyPlugin extends EvaluationPlugin {
   static getters = ["getCurrencyRate"];
 
   constructor(config) {
@@ -472,7 +472,7 @@ class CurrencyPlugin extends UIPlugin {
   }
 }
 
-uiPluginRegistry.add("currencyPlugin", CurrencyPlugin);
+evaluationPluginRegistry.add("currencyPlugin", CurrencyPlugin);
 ```
 
 Next, we need to update the `compute` function to use the `getCurrencyRate` getter:
@@ -496,7 +496,7 @@ To handle this requirement and enable caching of API results, we'll introduce a
 The `getCurrencyRate` function reads from the cache and returns the status. If the status is `"missing"`, the `fetch` method handles data fetching and updates the cache. The `getFromCache` and `fetch` methods are described below:
 
 ```ts
-class CurrencyPlugin extends UIPlugin {
+class CurrencyPlugin extends EvaluationPlugin {
   static getters = ["getCurrencyRate"];
 
   constructor(config) {
@@ -526,7 +526,7 @@ class CurrencyPlugin extends UIPlugin {
 Let's explore a possible implementation of the `getFromCache` and `fetch` methods:
 
 ```ts
-class CurrencyPlugin extends UIPlugin {
+class CurrencyPlugin extends EvaluationPlugin {
   // ...
 
   private getFromCache(from: string, to: string) {
@@ -570,7 +570,7 @@ class CurrencyPlugin extends UIPlugin {
 Instead of using the native `fetch` method, you can inject your own service through the configuration:
 
 ```ts
-class CurrencyPlugin extends UIPlugin {
+class CurrencyPlugin extends EvaluationPlugin {
   constructor(config) {
     super(config);
     /**

doc/extending/architecture.md

@@ -55,18 +55,21 @@ A plugin can:
 - introduce new getters to make parts of its state available for other plugins or the user interface.
 - react to any dispatched command
 
-Plugins are decomposed in two parts: core and UI.
+Plugins are decomposed in three parts, each with its own base class: core (`CorePlugin`), evaluation (`EvaluationPlugin`) and UI (`UIPlugin`).
 
-Core plugins are responsible to manage the data persistence and all associated business rules (cell content, user-defined style, chart definitions, ...). Each plugin is responsible of one data structure.
+Core plugins are responsible to manage the data persistence and all associated business rules (cell content, user-defined style, chart definitions, ...) — `src/plugins/core/`. Each plugin is responsible of one data structure.
 
-UI plugins are separated in three different categories, with the following responsibility:
+Evaluation plugins manage the state derived from the core part (cell evaluation, computed style, chart runtime, ...) — `src/plugins/evaluation/`. They never own a source of truth: their state is entirely recomputed from core data, which is why it is never persisted nor transmitted to other collaborators.
 
-- Manage the derived state from the core part (cell evaluation, computed style, ...) — `src/plugins/evaluation/`
-- Manage the ui state (active sheet, current selection, ...) — `src/plugins/ui_stateful/`
+UI plugins are separated in two different categories, with the following responsibility:
+
+- Manage the ui state (current selection, clipboard, ...) — `src/plugins/ui_stateful/`
 - Handle high-level features that could be described with lower-level features (Sort a zone can be described with different cell updates) — `src/plugins/ui_feature/`
 
 Each UI plugin is responsible of one feature.
 
+Each category also defines what a plugin is allowed to read: core plugins receive `CoreGetters`, evaluation plugins receive `EvaluationGetters` (core + evaluation) and UI plugins receive the full `Getters` (see `src/types/getters.ts`).
+
 More details about plugins here: [Adding a new feature](./business_feature.md)
 
 Not sure whether your new code belongs in a core plugin, a UI plugin, or a store? See [Where should this code live?](./where_to_put_code.md).

doc/extending/business_feature.md

@@ -9,10 +9,11 @@ in all cells which contains the content `party`.
 
 ## Plugin creation
 
-A plugin should extend either `CorePlugin` or `UIPlugin` depending on its role.
-The plugin should also be register in the registry of plugins, in order to load
-it at the model startup. (`corePluginRegistry` or `uiPluginRegistry`). Mode details
-about plugins can be found in the [plugin section]("plugin.md)
+A plugin should extend `CorePlugin`, `EvaluationPlugin` or `UIPlugin` depending on its role.
+The plugin should also be registered in the registry matching its base class, in order to load
+it at the model startup (`corePluginRegistry`, `evaluationPluginRegistry`, `statefulUIPluginRegistry`
+or `featurePluginRegistry` — registering a plugin in a registry expecting another base class throws).
+More details about plugins can be found in the [plugin section](plugin.md)
 
 In our example, we will create two plugins, a new `CorePlugin` which will manage
 wether the party mode is active, and a new `UIPlugin` that will be responsible
@@ -25,9 +26,9 @@ class PartyPlugin extends CorePlugin {}
 
 class PartyDrawerPlugin extends UIPlugin {}
 
-// Register the plugins in order to load it at the model startup
+// Register the plugins in order to load them at the model startup
 corePluginRegistry.add("party_plugin", PartyPlugin);
-uiPluginRegistry.add("party_drawer_plugin", PartyDrawerPlugin);
+statefulUIPluginRegistry.add("party_drawer_plugin", PartyDrawerPlugin);
 ```
 
 ## Adding an internal state

doc/extending/command.md

@@ -1,7 +1,7 @@
 # Commands
 
 Commands are essential for modifying the spreadsheet state. They are dispatched to the model, which in turn relays them to each plugin.
-There are two types of commands: `CoreCommand` and `LocalCommand`.
+There are two types of commands: `CoreCommand` and `LocalCommand`. Among the local commands, the _evaluation commands_ form a special subset with its own dispatch rules (see below).
 
 ## Types of Commands
 
@@ -19,10 +19,19 @@ There are two types of commands: `CoreCommand` and `LocalCommand`.
 - **Sub-Commands**: Can dispatch sub-commands, which can be either core or local commands.
 - **Collaboration**: Not broadcast to other connected users (but sub-core commands are).
 
+### EvaluationCommand
+
+- **Purpose**: Trigger the (re)computation of a derived state. Currently `EVALUATE_CELLS` and `EVALUATE_CHARTS`, listed in `evaluationCommandTypes` (`src/types/commands.ts`).
+- **Handling**: Handled by evaluation plugins and UI plugins. Core plugins never handle them (`CorePlugin.handle` only accepts a `CoreCommand`).
+- **Dispatch**: They bypass `allowDispatch` entirely — an evaluation command can never be refused. When dispatched by an evaluation plugin, they are relayed to evaluation and UI plugins only.
+- **Sub-Commands**: This is the only kind of command an `EvaluationPlugin` may dispatch. Dispatching anything else from an evaluation plugin throws (`An evaluation plugin cannot dispatch non-evaluation commands`), and so does dispatching a non-evaluation command from any plugin while a top-level evaluation command is being handled (`A top level evaluation command cannot dispatch non-evaluation commands`).
+- **Collaboration**: Not broadcast — each client re-evaluates on its own.
+
 ### Example
 
 - `RESIZE_COLUMNS_ROWS`: A `CoreCommand` handled by a core plugin to adjust the size of rows or columns.
 - `AUTORESIZE_COLUMNS`: A `LocalCommand` handled by a UI plugin, which dispatches the sub-command `RESIZE_COLUMNS_ROWS` based on the current cell content.
+- `EVALUATE_CELLS`: An `EvaluationCommand` handled by `CellEvaluationPlugin` to evaluate the cells that were invalidated.
 
 ### Device Agnosticism
 

doc/extending/plugin.md

@@ -19,29 +19,38 @@ A plugin can :
   functions
 - react to any existing command
 
-Plugins are divided into two main categories: CorePlugin and UIPlugin, with each category featuring two specific types.
+Plugins are divided into three base classes: `CorePlugin`, `EvaluationPlugin` and `UIPlugin`. Each base class is tied to a registry in `src/plugins/plugin_registries.ts`, and these registries refuse a plugin that does not extend the expected base class:
+
+| Base class         | Registry                   | Folder                     | Getters it receives                     |
+| ------------------ | -------------------------- | -------------------------- | --------------------------------------- |
+| `CorePlugin`       | `corePluginRegistry`       | `src/plugins/core/`        | `CoreGetters`                           |
+| `EvaluationPlugin` | `evaluationPluginRegistry` | `src/plugins/evaluation/`  | `EvaluationGetters` (core + evaluation) |
+| `UIPlugin`         | `statefulUIPluginRegistry` | `src/plugins/ui_stateful/` | `Getters` (everything)                  |
+| `UIPlugin`         | `featurePluginRegistry`    | `src/plugins/ui_feature/`  | `Getters` (everything)                  |
 
 ### I. CorePlugin
 
 - manages data that is persistent
 - can make changes to its state using the history interface (allowing `undo` and `redo`)
 - import and export its state to be stored in the o-spreadsheet file
+- can only dispatch core commands
 
-Core plugins include:
+### II. EvaluationPlugin
 
-1. Core Plugins: manage data persistence
-2. Evaluation Plugins: have a derived state from core data
+- has a state entirely derived from core data (cell evaluation, computed styles, chart runtime, ...)
+- never persisted, never transmitted to other collaborators: every client recomputes it from the same replayed core commands
+- cannot change the model data: it can only dispatch _evaluation_ commands (see [Commands](./command.md))
 
-### II. UIPlugin
+### III. UIPlugin
 
-- manages transient state, user specific state and everything that is needed to display the spreadsheet without changing the persistent data (like evaluation)
+- manages transient state, user specific state and everything that is needed to display the spreadsheet without changing the persistent data
 
 UI plugins include:
 
 1. Stateful Plugins: have a state, but which should not be shared in collaborative
 2. Feature Plugins: handle a specific feature, without handling any core commands
 
-Unsure which of the four plugin types (or which store) your feature belongs in? See [Where should this code live?](./where_to_put_code.md).
+Unsure which of the four plugin categories (or which store) your feature belongs in? See [Where should this code live?](./where_to_put_code.md).
 
 ## Plugin skeleton
 
@@ -92,10 +101,11 @@ class MyPlugin extends CorePlugin {
 // makes the function getSomething accessible from anywhere that has a reference to model.getters
 MyPlugin.getters = ["getSomething"];
 
-// add the new "MyPlugin" to the plugin registry.
+// add the new "MyPlugin" to the registry matching its base class
+// (corePluginRegistry, evaluationPluginRegistry, statefulUIPluginRegistry or featurePluginRegistry).
 // It will be automatically instantiated by o-spreadsheet when you mount the spreadsheet component or when you create a new Model()
-const pluginRegistry = spreadsheet.registries.pluginRegistry;
-pluginRegistry.add("MyPlugin", MyPlugin);
+const { corePluginRegistry } = o_spreadsheet.registries;
+corePluginRegistry.add("MyPlugin", MyPlugin);
 ```
 
 ## Dispatch lifecycle and methods