@aduptive/strapi-blockscene 1.0.0-alpha.10 → 1.0.0-alpha.11

package/README.md

@@ -29,6 +29,9 @@ module.exports = {
     config: {
       previewBaseUrl: '/block-previews',
       previewVersion: '2026-09-22', // optional cache buster appended as ?v=
+      // Optional: only these Strapi component folders get cards in Settings > Block gallery.
+      // Dynamic Zone insertion still follows each content type's own schema.
+      settingsComponentCategories: ['blocks'],
       components: {
         'blocks.hero': {
           label: 'Hero banner',
@@ -37,6 +40,7 @@ module.exports = {
           tags: ['Editorial'],
           keywords: 'heading introduction',
           image: '/block-previews/hero.png',
+          showRowThumbnail: false, // optional per-component row thumbnail
         },
       },
     },
@@ -65,7 +69,7 @@ Right beside the native zone label ("blocks (3)") each zone gets a short bar:
 - **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** (first zone only, when a preview route exists): a
-  menu with Fields, Fields + page and Visual editor. Without a preview route the
+  menu with Fields only, Fields + preview 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)).
@@ -97,7 +101,8 @@ The modal is a block browser (80vw wide):
   all"; the empty state offers a reset.
 - **Cards**, grouped by typology: facet badges (IMAGE, VIDEO, GALLERY, RICH
   TEXT, LIST, DYNAMIC, FORM), a star and an always-visible magnifying glass.
-  Clicking the card inserts it immediately; the magnifying glass opens its preview.
+  Clicking the card, or focusing it and pressing Enter, inserts it immediately;
+  the magnifying glass opens its preview.
 - The preview **magnifies** the block: the card grows into a large panel over the
   grid (sidebar and top bar stay usable, the grid dims underneath) and shrinks
   back into its card on close (close button, Esc or a click on the dimmed
@@ -106,8 +111,7 @@ The modal is a block browser (80vw wide):
   with Fit / Mobile / Tablet / Desktop widths (scaled to fit, as in the page
   preview) and a compact strip: label, uid, description, badges, fields (on
   demand), the variant choice (see [Insert variants](#insert-variants)), star
-  and Insert. Clicking or pressing Enter on a focused card inserts without it
-  (the first variant, when the block has variants).
+  and Insert. A direct card insert uses the first variant, when the block has variants.
 
 The magnified preview shows the card's thumbnail at once and fades the live
 page in over it once it has loaded. Live source, first match wins:
@@ -190,7 +194,7 @@ components: {
 - **Choosing**: with two or more variants the magnified block shows them as a
   row of buttons; the live preview follows the choice (`{variant}` in the
   block preview URL, or the variant's block sent through the bridge) and
-  Insert inserts it. Double click, "+" and Enter insert the first variant.
+  Insert inserts it. Clicking the card or pressing Enter inserts the first variant.
   The picker opened from a page preview insertion seam offers the same
   choice. A block without variants behaves as before; Settings, Blockscene
   lists each block's variants read-only.
@@ -215,6 +219,42 @@ components: {
   per variant and 256 KB for all of them. An invalid variant is left out with
   a warning naming the problem; the block keeps its valid ones.
 
+### Starter kits
+
+New entries can start from a named set of blocks instead of an empty Dynamic
+Zone. Kits live in project code, per content type. When every editable zone is
+empty, Blockscene opens the kit chooser once; choosing one only changes the
+unsaved form, so every placeholder remains editable and **Start blank** keeps
+the current behaviour.
+
+```js
+// config/plugins.js
+blockscene: { config: {
+  kits: {
+    'api::page.page': [{
+      id: 'landing',
+      label: { en: 'Landing page', 'pt-BR': 'Página de campanha' },
+      // Optional. A language code such as "pt" also matches "pt-BR".
+      locales: ['en', 'pt-BR'],
+      zones: { blocks: [
+        { __component: 'blocks.hero', title: 'Replace this headline' },
+        { __component: 'blocks.rich-text', text: 'Replace this text.' },
+      ] },
+    }],
+  },
+} }
+```
+
+Rows use the Content API shape and the same validated values as [insert
+variants](#insert-variants). Schema defaults are merged in, nested components
+work, and configured layout OPEN blocks receive their CLOSE automatically.
+Media and relations are omitted because their ids are installation-specific;
+required ones are called out in the server log and must be completed before
+publishing. Invalid kits, missing required scalar values and kits below or
+above a Dynamic Zone's bounds are ignored with a server warning. The chooser
+is remembered for the current new-entry browser history item, so re-rendering
+or reloading it does not apply or prompt twice.
+
 ## Row thumbnails
 
 Each added block shows its thumbnail at the left of the native accordion
@@ -223,8 +263,10 @@ opening or closing the row. The sources are the same as the gallery cards,
 minus the wireframe: a block with no image shows nothing, so nothing new is
 invented for blocks that were never captured. The thumbnail is inserted into
 Strapi's own header through the DOM (no Content Manager patch) and is
-restored when Strapi re-renders the list. Turn it off with the editor option
-`showRowThumbnails: false`.
+restored when Strapi re-renders the list. Configured OPEN and CLOSE group
+markers hide it by default. Override any component with
+`components[uid].showRowThumbnail` in code or on the Settings page, or turn all
+row thumbnails off with the editor option `showRowThumbnails: false`.
 
 ## Row actions
 
@@ -398,7 +440,7 @@ ignored (boot continues). `GET /blockscene/settings` returns them as
 | 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`, see [Pane toolbar](#pane-toolbar)) | ordered list of `modes`, `history`, `devices`, `status`, `actions` | all five |
+| Page preview toolbar (`previewToolbar`, see [Pane toolbar](#pane-toolbar)) | ordered list of `modes`, `history`, `versions`, `devices`, `status`, `actions` | all six (`versions`: Strapi 5) |
 | Page widths (`previewDevices`) | 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
@@ -433,7 +475,7 @@ the two supported versions only.
 ## Whole-page preview
 
 Both distributions add a page preview with three modes, chosen from the
-first zone's bar and from the pane toolbar: Fields (form), Fields + page (side
+first zone's bar and from the pane toolbar: Fields only (form), Fields + preview (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
@@ -496,6 +538,11 @@ Minimal configuration:
    blocks, 0 when none or not editable); while it is positive the page may show
    a Paste button in its seams that sends `{ type: 'paste', after }` (a block
    key, or `null` for the start). Both are optional.
+   `update-page` also carries the complete live `entry`, including unsaved
+   values, plus `contentType` metadata and the projected zone name. New schema
+   fields therefore reach the frontend automatically; the frontend decides how
+   each field affects its page. The normalized `blocks` array remains alongside
+   it for visual editing and block-level actions.
    Keep the origin check (`admin` query parameter or your own constant).
 2. Allow the admin origin to embed it (`Content-Security-Policy: frame-ancestors`)
    and allow the page origin in the Strapi admin CSP (`frame-src`).
@@ -507,12 +554,16 @@ Minimal configuration:
    other one and the page then never hydrates, so `ready` never arrives and
    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
-http(s) host (S3/CDN providers included) and same-origin paths; the zone shown
-is the first Dynamic Zone the user may read, and editing additionally needs the
-update permission on it. Pending dialogs are dropped when the document or
-locale changes.
+The bridge only exposes what the schema and the current user's read permissions
+allow. Attributes marked with Strapi's `private: true`, passwords, and
+attributes with `pluginOptions.blockscene.private: true` are never projected,
+focused or edited; the Blockscene option is useful for keeping a field out of
+the preview without changing its public API behavior. This privacy rule also
+applies inside components. Media URLs are passed through for any http(s) host
+(S3/CDN providers included) and same-origin paths; the zone shown is the first
+Dynamic Zone the user may read, and editing additionally needs the update
+permission on it. Pending dialogs are dropped when the document or locale
+changes.
 
 Editing from the page: plain-text areas the page explicitly maps
 (`data-block-field` + `contenteditable="plaintext-only"`) send `edit`. In the
@@ -551,7 +602,8 @@ blocks use the native insertion at a position. Differences:
 ### Pane toolbar
 
 Which controls the toolbar shows, and in which order, is `previewToolbar`:
-`modes` (Fields, Fields + page, Visual editor), `history` (Undo, Redo),
+`modes` (Fields only, Fields + preview, Visual editor), `history` (Undo, Redo),
+`versions` (the version history drawer, Strapi 5),
 `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
@@ -974,11 +1026,47 @@ 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.
 
+**Visual editor history (Phase 1).** The preview toolbar's `versions` control
+opens a drawer on the right. It is separate from `history` (Undo/Redo). If
+you already configured `previewToolbar`, add `versions` to that list or enable
+it in Settings. Versions are grouped by local calendar day, with local date
+and time, actor, action, and captured counts: total top-level Dynamic Zone rows
+(including group markers), added, removed and changed against the preceding
+snapshot in that locale. Older or unrecorded events show counts as unavailable;
+they are not retroactively counted as zero. The actor filter includes only
+people/tokens recorded for this document and locale. Lists use server pagination
+(25 per page) and mark events whose snapshots are no longer available.
+
+Selecting an event hydrates its retained snapshot into a separate, read-only
+preview. It never calls the form's `setValues`, saves, publishes or restores
+anything. The banner identifies the version and returns to the current draft,
+including unsaved changes. Fast selections, returning while a load is pending,
+and document/locale/permission changes invalidate old responses. The pre-existing
+side-panel "Load this version" action remains available; restoration and visual
+diff enhancements are separate phases.
+
+The parent rejects every mutation, selection, focus and hover message while
+viewing a version. Each version changes the iframe channel, so delayed messages
+cannot target the current draft after returning. The `update-page` message adds
+`readOnly: true`, sends no editable field/media descriptors and no clipboard.
+The reference bridge in `examples/page-preview` supports this flag, removes
+editing/insertion controls, and announces `capabilities: ['readOnly']` in `ready`.
+Custom bridges should do the same and refuse to queue or send edits when
+read-only. An older bridge can still render the snapshot, but the admin disables
+iframe interaction (including in-frame scrolling) and explains that it needs an
+update. Parent-side protection applies regardless of bridge support. The existing
+`hover` protocol highlights; it does not promise scroll-to-block behavior.
+
+The drawer button also explains whether history is disabled/not configured for
+the type, the entry needs its first save, or `history.read` is missing. Permission
+changes require an administrator; this control cannot grant access.
+
 **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
+`GET /blockscene/history/:uid/:documentId?locale=&page=1&pageSize=25&actor=`
+(no snapshots; `results`, `pagination`, scoped `actors` and resolved `locale`)
+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
@@ -987,6 +1075,10 @@ 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.
+These are configurable limits, not a guarantee that a version from a week ago
+still exists: frequent changes can exceed `maxSnapshots` earlier. The snapshot
+cap is per document across locales; event metadata may outlive its snapshot.
+Naming versions and protecting them from purge are not implemented in Phase 1.
 
 ```js
 // config/plugins.js
@@ -1201,6 +1293,7 @@ uploads share an origin.
 - `tests/`: runnable regression checks.
 - [Local integration tests](docs/LOCAL-TESTING.md).
 - [Release checklist](docs/RELEASE.md).
+- [Prioritized roadmap](docs/ROADMAP.md).
 
 This plugin does not require Image Optimization; both can be installed together.