@aduptive/strapi-blockscene 2.0.0-alpha.5 → 2.0.0-alpha.7

package/README.md

@@ -45,9 +45,43 @@ module.exports = {
 ```
 
 Rebuild/restart the admin. Open a content type with a Dynamic Zone. The
-editor panel provides one gallery button per editable, non-full zone. Zones
-that already have blocks get "Open all blocks" / "Close all blocks" icon
-buttons right beside the native zone label ("blocks (3)").
+native "Add a component to <zone>" button of each editable, non-full zone opens
+the gallery instead of Strapi's category picker; a full zone keeps its native
+button.
+
+### Zone bar
+
+Right beside the native zone label ("blocks (3)") each zone gets a short bar:
+
+- **Expand all / Collapse all**: one button with text. It reads the rows' own
+  state: "Expand all" while any block of the zone is collapsed, "Collapse all"
+  when every block is open (a header opened or closed by hand counts too), and
+  exposes it as `aria-expanded`. Blocks open or close a few at a time around the
+  viewport first (long pages stay responsive). Rows of a folded layout group
+  are left alone (see [Groups in the form](#groups-in-the-form)). Options `showOpenAll` /
+  `showCloseAll`: with both on (the default) the button toggles; with only one
+  on it offers that action alone, disabled while there is nothing to do; with
+  both off there is no button.
+- **Undo and Redo** (Strapi 5, first zone only): icon and text, the shortcut in
+  the tooltip. See [Undo and redo](#undo-and-redo).
+- **Editing mode** (Strapi 5, first zone only, when a preview route exists): a
+  menu with Fields, Fields + page and Visual editor. Without a preview route the
+  menu is not shown; Settings, Blockscene says why.
+- **"…" (More actions)**: Select blocks, and "Paste N blocks" while the
+  clipboard holds blocks this zone allows (see [Row actions](#row-actions)).
+  No entries, no menu.
+
+"Select blocks" swaps the bar for a selection bar: a select-all box with the
+count ("2 selected"; indeterminate while only some are selected, a click then
+selects none), Copy (disabled until a block is selected) and Done; Esc leaves
+too. Each row gets a checkbox at the start of its header.
+
+An empty zone has no label row: its bar (Paste, and on the first zone Undo,
+Redo and the mode) sits right after its native add button.
+
+The plugin adds no side panel of its own for any of this. The Blockscene side
+panel appears only for what has no place in the form: version history (when
+enabled) and layout group problems. With neither, there is no panel.
 
 ## Gallery
 
@@ -152,14 +186,14 @@ Each block header gets a few icons right before Strapi's own delete button
   nested components, new row key, media kept, relations kept (Strapi 5 reads
   the source row's relations from the server and adds its unsaved changes).
   A group OPEN duplicates with its whole range. Option `duplicate`.
-- **Copy / Paste** across pages. The copy icon copies one block; the select
-  icon in the zone label shows a checkbox per row, then "Copy selected". The
+- **Copy / Paste** across pages. The copy icon copies one block; "Select
+  blocks" in the zone bar's "…" menu shows a checkbox per row, then Copy. The
   blocks are stored in this browser's localStorage (`blockscene:clipboard:v1`,
-  with the source content type and locale). "Paste" appears in the zone label
-  (under the gallery button for an empty zone) and in the page preview seams.
-  Paste is all or nothing: every block must be allowed in the target zone, fit
-  its maximum, and groups must be whole; otherwise a notice explains why and the
-  form is not changed. Media and relations are kept by id/documentId, so paste
+  with the source content type and locale). "Paste N blocks" appears in the
+  zone bar's "…" menu of every zone that allows all the copied components, and
+  in the page preview seams. Paste is all or nothing: every block must be
+  allowed in the target zone, fit its maximum, and groups must be whole;
+  otherwise a notice explains why and the form is not changed. Media and relations are kept by id/documentId, so paste
   within the same install. Option `clipboard`.
 - **Confirm delete**. The native delete asks "Delete block …?" first;
   confirming runs Strapi's own removal. On a group marker the dialog says only
@@ -172,10 +206,14 @@ block).
 
 **The hidden attribute is a database column.** At register time the plugin adds
 a boolean attribute (like i18n adds `locale`) to every component used in a
-Dynamic Zone: `{ type: 'boolean', default: false, visible: false,
-configurable: false }`, so Strapi's schema sync creates a `bs_hidden` column in
-each of those component tables on the next start (existing rows read as not
-hidden). It is hidden from the edit view. Rename it with the plugin config
+Dynamic Zone: `{ type: 'boolean', default: false, configurable: false }`, so
+Strapi's schema sync creates a `bs_hidden` column in each of those component
+tables on the next start (existing rows read as not hidden). It is never shown
+as an input: the plugin removes it from the components' edit layouts through
+the Content Manager's layout hook (it may be listed in "Configure the view" of
+a component; leave it out of the layout). It is not marked `visible: false`,
+because before Strapi 5.45 the edit view crashes on a value whose attribute the
+admin does not know. Rename it with the plugin config
 `hiddenAttribute: 'myName'`, or set `hiddenAttribute: false` to add nothing (no
 eye, nothing stripped). A component that already has an attribute of that name
 with another type is skipped with a warning. Removing the plugin (or setting
@@ -218,10 +256,12 @@ needed for the gallery to pick them up. Reading requires the
   typology ("Automatic" shows the guess) and tags (comma separated).
 - Editor preferences: enhancements on/off, visibility of each collective
   button, initial accordion state and the initial block mode.
+- Version history (Strapi 5): module switch, covered content types, retention
+  (see "Version history").
 - Content types: every project type with a Dynamic Zone, each with on/off
   (off leaves its edit view fully native) and, on Strapi 5, the mode its edit
-  views open in ("Default" follows the global preview mode) and its visual
-  editor sidebar (see below).
+  views open in ("Default" follows the global preview mode), its visual
+  editor sidebar and optionally its own page preview toolbar (see below).
 - "Restore project defaults" (or "Reset to defaults" when the project has no
   code defaults), after a confirmation, deletes what was saved here
   (`DELETE /blockscene/settings`, same permission as saving).
@@ -253,7 +293,12 @@ module.exports = {
 The effective settings are the built-in defaults, then the code `settings`,
 then what was saved on the page:
 
-- `palette` and `editor`: a saved key wins over the code key by key.
+- `palette` and `editor`: a saved key wins over the code key by key, except
+  an empty `previewUrl` or `blockPreviewUrl`, which means "not set": the code
+  value applies. Clearing either field on the page therefore falls back to the
+  project default (there is no saved "off" for a URL the code provides; remove
+  it from the code settings, or set `previewMode` per content type, to keep a
+  type out of the page preview).
 - `components` and `contentTypes`: a saved entry replaces the code entry for
   that uid as a whole (a saved `api::page.page` entry replaces its code
   sidebar too); other uids keep their code values.
@@ -271,8 +316,8 @@ ignored (boot continues). `GET /blockscene/settings` returns them as
 | Option | Values | Default |
 | --- | --- | --- |
 | Editor enhancements enabled | on/off | on |
-| Show "Open all blocks" | yes/no | yes |
-| Show "Close all blocks" | yes/no | yes |
+| Show "Expand all" (`showOpenAll`) | yes/no | yes |
+| Show "Collapse all" (`showCloseAll`) | yes/no | yes |
 | Show block thumbnails in the rows (`showRowThumbnails`) | yes/no | yes |
 | Initial accordion state | all closed / all open / remember | all closed |
 | Load rich-text editors on demand (`lazyEditors`, Strapi 5) | yes/no | yes |
@@ -284,13 +329,18 @@ ignored (boot continues). `GET /blockscene/settings` returns them as
 | Duplicate on each block (`duplicate`) | yes/no | yes |
 | Copy and Paste (`clipboard`) | yes/no | yes |
 | Blocks hidden on the site (`hiddenBlocks`) | `strip` / `flag` / `off` | `strip` |
+| Friendly field labels (`friendlyLabels`, see [Field labels](#field-labels)) | yes/no | yes |
+| Page preview toolbar (`previewToolbar`, Strapi 5, see [Pane toolbar](#pane-toolbar)) | ordered list of `modes`, `history`, `devices`, `status`, `actions` | all five |
+| Page widths (`previewDevices`, Strapi 5) | 1 to 8 of `fit`, `mobile`, `tablet`, `desktop`, `{ label, width }` | the four built-in |
 
 Every edit view opens in its content type's mode, else the initial preview
 mode. Editors can switch while they edit; the switch is not remembered.
 
 The initial state is applied once per document/locale after the blocks
-render; edits, reorders and newly inserted blocks are not re-applied. Hiding a
-button only hides it; native accordion headers keep working.
+render; edits, reorders and newly inserted blocks are not re-applied.
+`showOpenAll` and `showCloseAll` shape the zone bar's single toggle (both: it
+toggles; one: only that action; none: no button). Hiding it only hides it;
+native accordion headers keep working.
 
 Lazy editors: a custom field listed in `lazyFields` first shows a read-only
 preview of its HTML (same label, hint and error; scripts, frames, styles, event
@@ -302,7 +352,7 @@ registered custom field at boot and passes the others straight through; until
 the catalog loads, and when the plugin or the content type is off, every field
 is native.
 
-"Remember" stores only the last explicit open all / close all click, as
+"Remember" stores only the last explicit Expand all / Collapse all click, as
 `open`/`closed` in the browser's localStorage, keyed by admin URL, user id,
 content type and zone. Another user in the same browser does not inherit it.
 Blocked storage or an invalid value falls back to all closed. No sync between
@@ -314,9 +364,10 @@ the two supported versions only.
 
 ## Whole-page preview (Strapi 5)
 
-The Strapi 5 distribution adds a "Page preview" panel with three modes: form,
-side by side (resizable pane, native actions moved to a bar above the form) and
-preview. The panel posts the live values of the first Dynamic Zone to a page
+The Strapi 5 distribution adds a page preview with three modes, chosen from the
+first zone's bar and from the pane toolbar: Fields (form), Fields + page (side
+by side: resizable pane, native actions moved to a bar above the form) and
+Visual editor. It posts the live values of the first Dynamic Zone to a page
 your frontend serves; the page renders them with its own components and styles
 and can ask the admin to open a block, edit a field or pick media. Nothing is
 saved or published by the preview.
@@ -386,7 +437,7 @@ Minimal configuration:
    Use the same host name the frontend dev server was started for
    (`localhost` vs `127.0.0.1`): Next 16 refuses its dev WebSocket for the
    other one and the page then never hydrates, so `ready` never arrives and
-   the panel reports the preview as unavailable with no error in either console.
+   the pane reports the preview as unavailable with no error in either console.
 
 The bridge only exposes what the schema allows: attributes marked `private`
 are never projected, focused or edited; media URLs are passed through for any
@@ -404,15 +455,91 @@ page updates while you type; Done, Esc or the backdrop put the block back. Side
 by side focuses the field in the form on the left instead. Media
 fields open the native Media Library. Everything is validated against the schema
 and the zone's edit permission; a published page never receives unsaved values
-by itself. Strapi 4 does not have this panel yet (see `docs/BACKLOG.md`).
+by itself. Strapi 4 does not have the page preview yet (see `docs/BACKLOG.md`).
+
+### Pane toolbar
+
+Which controls the toolbar shows, and in which order, is `previewToolbar`:
+`modes` (Fields, Fields + page, Visual editor), `history` (Undo, Redo),
+`devices` (the width menu), `status` (Draft/Modified/Published and the unsaved
+hint) and `actions` (Save, Publish). A missing id is hidden; `status` and
+`actions` stay one group on the right, placed where the first of them is
+listed. The preview's loading or error notice always shows. Without `modes` the
+pane stays in the mode the edit view opened in (for example a visual editor
+only view with `previewMode: 'preview'`); the form's zone bar keeps its own
+Undo, Redo and mode menu.
+
+`previewDevices` lists the width menu's entries in order; the first is used
+until an editor picks another. Besides the four names, `{ label, width }` adds
+a custom width (label up to 24 characters, width a whole number from 240 to
+3840 px; no name or width twice; up to 8 entries). With a single entry the menu
+is hidden.
+
+```js
+// Settings, Blockscene (Editor preferences, or per content type), PUT /blockscene/settings, or the code `settings`:
+editor: {
+  previewToolbar: ['modes', 'devices', 'actions'],
+  previewDevices: ['fit', 'mobile', { label: 'Laptop', width: 1280 }, 'desktop'],
+},
+contentTypes: {
+  'api::landing.landing': { previewToolbar: ['actions'], previewDevices: ['desktop'] },
+}
+```
+
+A content type's value replaces the global one. The Settings page edits both as
+checklists (check to show, arrows to order, "Add a width" for custom widths);
+"Own page preview toolbar" under a content type starts as a copy of the global
+choice, and turning it off goes back to the global one.
+
+### Custom sidebar panels
+
+A project (in its `src/admin/app.tsx`) or another plugin can add its own panel
+to the visual editor sidebar. Registered panels come after the configured field
+items, in registration order; the rail shows in the Visual editor mode as soon
+as there is one item.
+
+```tsx
+// src/admin/app.tsx
+const Notes = ({ values, onChange, disabled, close }) => (
+  <textarea value={values.notes ?? ''} disabled={disabled}
+    onChange={(e) => onChange('notes', e.target.value)} />
+)
+export default {
+  bootstrap(app) {
+    app.getPlugin('blockscene')?.apis.registerPanel({
+      id: 'notes', // 1 to 40 letters, digits, _ or -; the same id again replaces the panel
+      label: 'Notes', // 1 to 40 characters
+      icon: 'info', // optional: an icon name (the sidebar icons above, for example) or a React element
+      open: 'drawer', // 'drawer' (default) or 'modal'
+      contentTypes: ['api::page.page'], // optional: only these types (default: every type)
+      Component: Notes,
+    })
+  },
+}
+```
+
+`Component` receives `model` (content type uid), `documentId` (undefined while
+creating), `locale`, `values` (the live form values), `onChange(name, value)`
+(the form's own setter: the change is unsaved, goes through undo and redo, and
+Save or Publish store it with the usual permission checks), `disabled` (the form
+is read-only) and `close()`. It renders inside the Content Manager edit view, so
+it can also use the admin's hooks (`useForm`, `useFetchClient`...). Strapi runs
+every plugin's `register` before any `bootstrap`, then the host's `bootstrap`:
+calling `registerPanel` from either bootstrap works. An invalid panel is logged
+(`[blockscene] registerPanel: ...`) and ignored; `registerPanel` returns `true`
+or `false`. A panel that throws while rendering shows the plugin's error notice
+in its drawer; the editor keeps working. Strapi 5 only (the Strapi 4 package has
+no visual editor).
 
 ### Undo and redo
 
-The Blockscene panel and the pane toolbar have Undo and Redo buttons (Strapi 5).
+The first zone's bar and the pane toolbar have Undo and Redo buttons (Strapi 5),
+on one shared history (the shortcuts use it too).
 They step through the whole edit view: blocks inserted, removed or moved from the
 gallery, the page, groups or the native actions, and any field edit. Changes
 within 400 ms of each other are one step, so a burst of typing undoes at once;
-up to 100 steps. Shortcuts: Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z and Ctrl+Y, only while
+a block dragged with the mouse is one step however long the drag lasts; up to
+100 steps. Shortcuts: Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z and Ctrl+Y, only while
 the focus is outside a text field, select or rich text editor (those keep their
 own undo).
 
@@ -460,7 +587,7 @@ With a valid map:
   groups may nest; a CLOSE right after its OPEN is a valid empty group. Errors
   are `closeBeforeOpen` (CLOSE with no open group), `mismatch` (CLOSE is not the
   one expected by the innermost open group) and `unclosed` (OPEN never closed).
-- Nothing is repaired on read: the panel lists the problems (row, marker) and
+- Nothing is repaired on read: the Blockscene side panel lists the problems (row, marker) and
   the stray rows stay visible so the editor can fix them. Drafts save normally.
 - Publishing is refused server-side while a configured pair is unbalanced.
   Strapi 5: a document-service middleware intercepts every facade path that
@@ -484,6 +611,272 @@ With a valid map:
 Configured groups are stored exactly as before: the flat list of components in
 the zone. Removing the config only removes the group tools and the guard.
 
+### Groups in the form
+
+The edit view draws the same structure over Strapi's native rows (Strapi 5 and
+4; data attributes on the rows, nothing of the Content Manager is patched):
+
+- The rows between an OPEN and its CLOSE are indented under it with a guide line
+  in the admin's primary colour, one level (and one line) per nested group.
+- The CLOSE row reads as the group's end: compact, dimmed, without a drag handle
+  (it cannot be dragged on its own; its delete stays, with the marker notice).
+- Each closed group's OPEN header gets a chevron before its title. It folds the
+  group: its rows and CLOSE are hidden and the header shows "N blocks" (every
+  row inside, nested ones too, CLOSE markers excluded). Folding is kept in memory
+  for the session, per document, zone and group; a reload shows every group open.
+  A validation error inside a folded group (on Save or Publish) unfolds it.
+  Expand all / Collapse all act on the visible block accordions only: they never
+  open the forms of a folded group's rows, and a group keeps its own chevron.
+- Moving an OPEN moves its group. Nothing intercepts Strapi's drag and drop:
+  after any change of the zone, if the only thing that changed is one OPEN
+  moving, its members as they were (children and CLOSE) are put back right after
+  it, in the same unsaved form change. This covers the mouse (settled on drop:
+  Strapi moves the row on every hover), the keyboard (Space, arrows, Space on the
+  drag handle) and the move arrows of small screens. An OPEN dropped among its
+  own rows (a single keyboard or arrow step down) moves the group one row down
+  instead. The whole drag and the correction are one undo step (Strapi 5).
+- Everything else keeps the flat-list meaning: a child dragged out of the range
+  is an ordinary block from then on, a block dropped inside becomes a child, and
+  an OPEN dropped inside another group is nested there with its rows. A CLOSE
+  moved by other means (the small-screen arrows) ends the group where it lands.
+  Unclosed groups and stray markers are indented as the page preview shows them
+  but have no chevron and are never moved (the diagnostics list them).
+
+## Field labels
+
+The Content Manager shows each field under its "Configure the view" label, which
+defaults to the raw attribute name (`mobileColumnsCount`). Blockscene rewrites
+the edit view labels, hints and placeholders through the Content Manager's own
+`Admin/CM/pages/EditView/mutate-edit-view-layout` hook (Strapi 5 and 4, the
+same hook the i18n plugin uses), so nothing in the DOM is patched and the
+saved view configuration is never changed. Per field, the first that applies:
+
+1. **Project texts** from the plugin config `fields` (below);
+2. **a label set in "Configure the view"** (anything other than the attribute name);
+3. **the humanized name** when "Friendly field labels" is on: `mobileColumnsCount`
+   reads "Mobile columns count", `page_seo` "Page seo", acronym runs stay
+   (`pageSEO` "Page SEO", `ctaURL` "Cta URL").
+
+Description (the hint under the field) and placeholder change only when the
+project texts have them. Texts follow the admin user's interface language
+(`strapi-admin-language`, else English), resolved as: exact locale, then its
+language (`pt-BR` → `pt`), then any variant of that language, then `en`, then
+the first value.
+
+```js
+// config/plugins.js
+blockscene: { config: { fields: {
+  'api::page.page': {
+    pageSeo: { label: { en: 'Search engine settings', 'pt-BR': 'Configurações de SEO' },
+      description: { en: 'Title and description shown on Google', 'pt-BR': 'Título e descrição no Google' } },
+  },
+  'shared.seo': { metaTitle: { placeholder: 'Up to 60 characters' },
+    metaDescription: { help: { en: 'Shown under the title in search results. Google cuts it around 155 characters; write for people, not keywords.' } } },
+} } },
+```
+
+Keys are content type or component uids, then attribute names; each of
+`label` (up to 80 characters), `description` (300), `placeholder` (120) and
+`help` (500) is a string or `{ "<locale>": string }`.
+
+`description` stays the line under the input. `help` is for the longer
+explanation that would stretch the form: on Strapi 5 it becomes an "i" icon next
+to the label, in the Content Manager's own label action slot (where the i18n
+plugin puts its globe; both icons show on localized fields), with the text in a
+tooltip on hover and on keyboard focus (the button is reachable with Tab and
+named "More information"). A field can have both. On Strapi 4 the Content
+Manager gives component fields, where blocks live, no label action, so `help`
+is appended to the description under the input instead. The map is validated at boot: an unknown
+key, an empty or too long text, or a malformed locale code logs a warning
+naming it and the whole `fields` config is ignored (labels fall back to the two
+other steps). Entries for a uid or attribute the schema no longer has (a
+renamed or removed field) are skipped with one warning listing them; the rest
+keep working. It is code only, versioned with the
+project; the Settings page has the on/off switch but does not edit texts.
+
+To start the file, generate every field of a project with its humanized English
+label from a clone of this repository, then keep what you want to change:
+
+```bash
+node scripts/fields-skeleton.mjs ../my-project/backend > ../my-project/backend/config/blockscene-fields.json
+# config/plugins.js: fields: require('./blockscene-fields.json')
+```
+
+Limits: the hook runs synchronously and reads the last catalog the admin
+loaded. The first edit or list view of a session starts that request and shows
+native labels; the next layout computed (another document, list → edit, a
+locale switch) has them. Strapi 5 gives the hook no content type uid, so the
+layout is matched by display name and field names; two content types that
+share both are left untouched (component fields always work: they are keyed by
+uid). The switch "Editor enhancements enabled", `BLOCKSCENE_DISABLED` and a
+content type turned off all leave the native labels; any error leaves the
+layout untouched. Changing the interface language applies from the next edit
+view.
+
+## Version history (Strapi 5)
+
+Off by default. Turn it on in Settings, Blockscene, "Version history" (or from
+code, `settings.history`, see below). Strapi Community has no content history
+(it is a Growth feature); this module records one event per content change and
+keeps a snapshot of the content, so an editor can see what changed and load an
+earlier version back into the form.
+
+**What it captures.** Every create, save, publish, unpublish, discard draft and
+delete of the covered content types (all `api::` types by default, or a list)
+made through Strapi's document service: the admin (single and bulk actions),
+the REST and GraphQL APIs, and any plugin or custom code that uses
+`strapi.documents`. One event per affected locale, with who (admin user, API
+token, Users & Permissions user, or `system`), when, the action and a summary
+(blocks added, removed and changed per Dynamic Zone, top-level fields changed)
+against the previous snapshot of the same locale. The snapshot is the stored
+entry with components and Dynamic Zones in full, relations as documentIds and
+media as file ids (a 34-block page is a few KB; the capture adds a few
+milliseconds to a save). A snapshot identical to the previous one is not stored
+again (the event is, with the same hash).
+
+**What it does not see.** Writes that bypass the document service: raw
+`strapi.db.query`, knex or SQL, imports that write the database directly. This
+is content activity for editors, not a security audit log.
+
+**Failure policy.** A failed capture never blocks a save or a publish: the
+change goes through, the error is logged and the event is marked "Not
+recorded". A failed capture fails a delete: the delete runs in one transaction
+with its events, so nothing is deleted without its last version (a bulk delete
+is rolled back whole). `BLOCKSCENE_DISABLED=true` or the module switch off stop
+all capture. The plugin never records its own content types.
+
+**In the edit view.** The Blockscene side panel gets a History section (saved
+documents of covered types, also on types without a Dynamic Zone): the
+versions of the document in the current locale, newest first. Selecting one
+shows a block-level diff against the form (relations are not compared) and
+"Load this version", which puts the version into the form the way undo does:
+nothing is written until the editor saves, so validation, permissions and
+lifecycles apply as for any edit, and undo reverts the load. Components and
+blocks come back as new rows; relations become the connect/disconnect change
+from what the document has now; fields the editor may not update, fields the
+schema no longer has, blocks whose component is no longer allowed, and media or
+related entries that no longer exist are left out and listed.
+
+**Permission.** `Blockscene: Read version history` (`history.read`), plus read
+access to the content type in the Content Manager. Snapshots hold removed and
+unpublished text, so the section is hidden without it. Admin API:
+`GET /blockscene/history/:uid/:documentId?locale=` (the latest 100 events, no
+snapshots) and `GET /blockscene/history-events/:id` (one event, its snapshot and
+the media and relation targets that still exist).
+
+**Retention.** Snapshots are kept `retentionDays` (90) and at most
+`maxSnapshots` (100) per document, newest first; events without a snapshot are
+kept `eventDays` (365, at least `retentionDays`). A cron job added by the plugin
+runs nightly at 03:00 server time, in batches of 500; it only empties snapshots
+and deletes events, never media files, and running it on several instances is
+harmless.
+
+```js
+// config/plugins.js
+blockscene: { config: { settings: { history: { enabled: true, contentTypes: ['api::page.page', 'api::post.post'],
+  retentionDays: 90, maxSnapshots: 100, eventDays: 365, trashDays: 90 } } } }
+```
+
+Events live in the `blockscene_events` table (content type
+`plugin::blockscene.event`, hidden from the Content Manager and the Content-Type
+Builder). Removing the plugin, or installing a Blockscene version older than
+the one that added history, lets Strapi drop that table and every recorded
+version on the next start: back up `blockscene_events` first if you need it.
+
+### Trash (Strapi 5)
+
+Part of the version history module: on with it, for the same content types.
+Strapi has no trash in any plan; here a delete made through the document service
+(the admin's Delete, bulk delete and "Delete locale", the APIs, plugins) also
+writes one trash entry per document, in the same transaction as the delete.
+
+**What an entry keeps.** Every deleted locale, draft and published rows (they
+can differ), as snapshots like the history's; the document's title (its Content
+Manager main field); who deleted it and when; and the links other documents and
+blocks had to it. Strapi removes those links with the document, and the
+document's own snapshot does not hold them when the relation is unidirectional
+(declared only on the other side, like a menu listing pages or a block linking
+to a page), so they are captured before the delete: owner, field, locale and the
+position in the owner's list. A delete without a locale removes the default
+locale only (Strapi's rule), `'*'` every locale; the entry has exactly what was
+deleted. If the capture fails, nothing is deleted.
+
+**Restore.** From the Trash page, which first shows what the restore would do
+and writes nothing if something blocks it:
+
+- Blocking: the content type is gone; a unique field (`unique: true` or a uid
+  field, such as a slug) is now used by another document in that locale; the
+  document has that locale again; a single type has a document again; none of
+  its locales is configured any more.
+- Reported, then restored anyway: a published version existed (see below);
+  required fields are empty under the current schema (drafts may be, Strapi
+  checks them on publish); fields the schema no longer has, blocks whose
+  component the zone no longer allows, media files and related documents that no
+  longer exist (left out); locales no longer configured (skipped); links whose
+  owner is gone or now points elsewhere.
+
+The document comes back as a **draft with its draft content**: the draft is the
+latest work, and publishing is the editor's decision (the site may have moved
+on). The published snapshot stays in the entry and in the preview. Every locale
+is restored under one documentId, the default locale first, through the
+document service (validation and the project's lifecycles run). A document that
+is gone gets a new documentId, since Strapi's create does not take one; a locale
+deleted from a document that still exists goes back into that document. The
+captured links are put back where they were (same position in the owner's
+list) when the owner still exists; links from published versions come back
+when those owners are published again after this document is. A restore is one
+transaction and is idempotent: the entry is claimed first, so a second restore
+(a double click, another editor, another instance) returns the first one's
+document. The history gets a `restore` event per locale.
+
+**Delete forever** removes one entry (recorded as a `purge` event in the
+activity). The nightly job deletes entries past their expiry, restored ones too,
+in batches; neither ever deletes media files.
+
+**Retention.** `trashDays` (90, 1 to 3650) in the same settings; each entry's
+expiry is fixed when the document is deleted, so a later change applies to later
+deletes.
+
+```js
+blockscene: { config: { settings: { history: { enabled: true, trashDays: 30 } } } }
+```
+
+Entries live in `blockscene_trash` (`plugin::blockscene.trash`, hidden from the
+Content Manager and the Content-Type Builder); the same backup note as for
+`blockscene_events` applies.
+
+### Activity and Trash pages (Strapi 5)
+
+A main menu link, "Activity and trash", opens one page with a tab each (the
+pages are tools for editors, not configuration, so they are not under
+Settings). **Activity** lists every recorded event, newest first, 25 per page,
+filtered by person, content type, action, date range and title (documents whose
+main field contains the text now, or whose trash entry's title does); each row
+links to the document's edit view while that locale exists and shows the
+summary. **Trash** lists the entries (title, type, locales, who, when, when it
+is deleted for good), filtered by content type, with restored entries on a
+switch; Preview shows the fields and blocks of each deleted locale, read-only;
+Restore shows the pre-check report and asks to confirm; Delete forever asks
+first.
+
+**Permissions.** `Read content activity` (`activity.read`), `Read the trash`
+(`trash.read`), `Restore from the trash` (`trash.restore`), `Delete from the
+trash forever` (`trash.purge`), none granted to non-super-admin roles by
+default. On top of them, every list shows only content types the user may read
+in the Content Manager (an entry of another type answers 404), restoring needs
+create there and deleting forever needs delete. Admin API: `GET /blockscene/activity`
+(`actor`, `contentType`, `action`, `from`, `to` as ISO dates, `q`, `page`,
+`pageSize` up to 100), `GET /blockscene/trash` (`contentType`, `status`
+trashed or restored, `page`, `pageSize`), `GET /blockscene/trash/:id` (the
+preview), `GET /blockscene/trash/:id/check` (the pre-check),
+`POST /blockscene/trash/:id/restore` (409 with the report when blocked) and
+`DELETE /blockscene/trash/:id`. Lists never load snapshots.
+
+**Coverage boundary**, the same as the history's: the document service only.
+A raw `strapi.db.query` delete, SQL or a database restore leaves no trash
+entry; deleting a content type (Content-Type Builder) drops its data without
+one. The trash is a safety net for editors, not a backup: keep database backups.
+
 ## Languages
 
 All plugin chrome (gallery, settings, page preview, editor dialogs, diagnostics)
@@ -497,15 +890,15 @@ component display names are never translated by the plugin.
 
 ## Turning the editor enhancements off
 
-- **From the panel**: switch "Editor enhancements enabled" off. The gallery
-  button, controls and initial-state logic disappear and the native picker and
+- **From the settings page**: switch "Editor enhancements enabled" off. The
+  gallery, the zone bars and the initial-state logic disappear and the native picker and
   accordions remain. Content, config, media and unsaved edits are preserved; the
   form is not reloaded. The settings page stays available to turn it back on.
-- **Emergency, outside the panel**: start the server with
+- **Emergency, outside the admin**: start the server with
   `BLOCKSCENE_DISABLED=true` (or set `config.disabled: true`). It is read at
   boot and reported by the catalog, wins over the saved settings and cannot be
   undone from the client. Changing it requires a restart.
-- **If the catalog request fails**, the panel renders nothing and the native
+- **If the catalog request fails**, the plugin renders nothing and the native
   editor is used, so a plugin outage does not block editing.
 - **Completely**: set `'blockscene': { enabled: false }` in `config/plugins.js`
   and rebuild/restart. This is the only way out of an import/build failure; a
@@ -563,10 +956,10 @@ installs without overrides, not a promise for every minor in between. Strapi
 - Authenticated admin catalog endpoint exposes only supported metadata, resolved
   override URLs, palette and editor preferences; never the whole config.
 - Top-level Dynamic Zones only. Conditional fields are omitted conservatively.
-- "Open all" / "Close all" drive the native accordions without touching the
-  whole list at once: open all opens the rows in and near the visible area, a
-  few per frame, and the others as they approach while scrolling (until Close
-  all or leaving the document); close all closes the visible rows at once and
+- "Expand all" / "Collapse all" drive the native accordions without touching the
+  whole list at once: expanding opens the rows in and near the visible area, a
+  few per frame, and the others as they approach while scrolling (until Collapse
+  all or leaving the document); collapsing closes the visible rows at once and
   the rest in idle time. With lazy editors, on a 34-block page with CKEditor
   fields (Strapi 5.31) the longest pause went from about 2.9 s to 0.14 s on
   open all and from 1.6 s to 0.14 s on close all.
@@ -584,7 +977,7 @@ uploads share an origin.
 ## Development
 
 - `admin/`: shared gallery, settings page, wireframes and version-specific adapters.
-- `server/`: settings store, validation, permissions, the catalog endpoint and the layout-group publish guard (`groups.js` is shared with the admin).
+- `server/`: settings store, validation, permissions, the catalog endpoint and the layout-group publish guard (`groups.js` is shared with the admin); `history.js` and `diff.js` for version history (`diff.js` is shared with the admin).
 - `admin/translations/`: one flat catalogue per admin locale (English is the source of truth).
 - `scripts/capture-previews.mjs`: local thumbnail capture.
 - `packages/strapi4`, `packages/strapi5`: independently installable distributions.