@druxt-contrib/node-preview 0.0.0-stage → 0.1.0-dev.20261030024907

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0-dev.20261030024907
+
+### Minor Changes
+
+- 6b39690: Add the DruxtNodePreview module. It renders an unsaved Drupal node in a Druxt site, in Consumer Node Preview's Frontend tab, from the JSON:API Node Preview document.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DruxtJS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,312 @@
-# Temporary Holding Version
+<!-- vale off -->
+<!-- The alt text describes what the banner shows: the @druxt-contrib/node-preview mark, name and description. The name-colon-description form trips ColonUsage. -->
+<a href="https://druxtjs.org">
+  <img src="https://raw.githubusercontent.com/druxt-contrib/druxt-node-preview/0.x/.github/banner.svg" alt="@druxt-contrib/node-preview: Node Preview module for Druxt">
+</a>
+<!-- vale on -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @druxt-contrib/node-preview
+
+[![npm](https://img.shields.io/npm/v/@druxt-contrib/node-preview)](https://www.npmjs.com/package/@druxt-contrib/node-preview)
+[![npm@dev](https://img.shields.io/npm/v/@druxt-contrib/node-preview/dev)](https://www.npmjs.com/package/@druxt-contrib/node-preview/v/dev)
+[![CI](https://github.com/druxt-contrib/druxt-node-preview/actions/workflows/ci.yml/badge.svg?branch=0.x)](https://github.com/druxt-contrib/druxt-node-preview/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/druxt-contrib/druxt-node-preview/branch/0.x/graph/badge.svg)](https://codecov.io/gh/druxt-contrib/druxt-node-preview)
+[![Known Vulnerabilities](https://snyk.io/test/github/druxt-contrib/druxt-node-preview/badge.svg?targetFile=package.json)](https://snyk.io/test/github/druxt-contrib/druxt-node-preview?targetFile=package.json)
+[![Discord](https://img.shields.io/discord/753866667590680587?label=discord&logo=discord&logoColor=white)](https://discord.druxtjs.org)
+
+> Node Preview module for Druxt
+
+Shows an unsaved Drupal node in your [Druxt](https://druxtjs.org) frontend.
+The editor presses Preview in Drupal and sees the node as the live site will
+show it, paragraphs included.
+
+![The Frontend tab of a Drupal preview, showing an unsaved node rendered by the Druxt frontend](https://raw.githubusercontent.com/druxt-contrib/druxt-node-preview/0.x/.github/preview.png)
+
+It works with two Drupal modules:
+
+- [JSON:API Node Preview](https://www.drupal.org/project/jsonapi_node_preview)
+  serves the unsaved node over JSON:API.
+- [Consumer Node Preview](https://www.drupal.org/project/consumer_node_preview)
+  adds Frontend, Drupal and JSON:API tabs to Drupal's preview. The Frontend tab
+  shows this module's page.
+
+## Links
+
+- [DruxtJS](https://druxtjs.org)
+- [Community Discord server](https://discord.druxtjs.org)
+
+## Requirements
+
+The frontend needs:
+
+- Druxt 0.25 and Druxt Entity 0.29 or later, through `druxt-site` 0.15.
+- Node 16 for the build. Druxt's schema build fails on newer Node.
+
+Drupal needs:
+
+- Consumer Node Preview and JSON:API Node Preview.
+- The fixes from <https://www.drupal.org/i/3367724> for JSON:API Node Preview.
+  Version 1.0.0-beta5 and earlier show stale or missing paragraphs without
+  them. The [example's
+  `composer.json`](https://github.com/druxt-contrib/druxt-node-preview/blob/0.x/example/drupal/composer.json)
+  applies them with composer-patches.
+
+Both need one parent domain, such as `www.example.com` for the frontend and
+`cms.example.com` for Drupal. The editor's Drupal session cookie does not
+reach a frontend on another domain.
+
+## Install
+
+```sh
+npm install druxt-site @druxt-contrib/node-preview
+```
+
+```js
+// nuxt.config.js
+export default {
+  modules: ['@druxt-contrib/node-preview', 'druxt-site'],
+  druxt: {
+    baseUrl: 'https://cms.example.com',
+    nodePreview: {
+      include: { 'node--page': ['field_content.field_media'] },
+      origins: ['https://cms.example.com'],
+      layouts: ['default', 'preview'],
+    },
+  },
+}
+```
+
+A site without `druxt-site` lists `druxt-entity` in `modules` instead.
+
+## Options
+
+All options are optional.
+
+| Option                      | Type                | Default                 | Description                                                                |
+| --------------------------- | ------------------- | ----------------------- | -------------------------------------------------------------------------- |
+| `druxt.nodePreview.path`    | `string`            | `'/druxt/node/preview'` | The preview page's path.                                                   |
+| `druxt.nodePreview.include` | `array` or `object` | `[]`                    | Relationships to add to the preview request.                               |
+| `druxt.nodePreview.origins` | `array`             | `[]`                    | More origins the preview may come from. Each is a full URL.                |
+| `druxt.nodePreview.layouts` | `array`             | `[]`                    | Nuxt layouts the preview may use. See [Preview layouts](#preview-layouts). |
+
+**include.** Consumer Node Preview already includes a node's paragraphs. Add
+what the paragraphs reference, such as `field_content.field_media`. JSON:API
+refuses a path that the previewed type does not have. Key a path by type when
+only some bundles have it, as in the example above.
+
+**origins.** Any link can put an endpoint in the page's URL. So the page only
+fetches from this site, from `druxt.baseUrl`, and from `origins`. The editor's
+session cookie goes with each request to those origins.
+
+A value the module cannot use shows a warning in the build output, and the
+module ignores it. The page's route name is `druxt-node-preview`.
+
+## Drupal setup
+
+1. Install Consumer Node Preview and JSON:API Node Preview, with the fixes
+   from [Requirements](#requirements).
+2. Go to **Administration > Configuration > Web services > Consumers** and
+   edit the frontend's consumer. Under **Preview targets**, add a label and
+   this URL template, with your frontend's host:
+
+   ```text
+   https://www.example.com/druxt/node/preview?vm=[view_mode]&layout=[layout]#[jsonapi_node_preview]
+   ```
+
+   Drupal fills in the parts in square brackets when the editor presses
+   Preview. Keep them as they are.
+
+3. Optional: under **Preview layouts**, add one layout name in each box. Put
+   `default` first, because the preview opens in the first one. See
+   [Preview layouts](#preview-layouts).
+4. In the site's `services.yml`, such as `sites/default/services.yml`, allow
+   the frontend's origin with credentials. Name the origin. Do not use `'*'`.
+
+   ```yaml
+   parameters:
+     cors.config:
+       enabled: true
+       allowedHeaders: ['*']
+       allowedMethods: ['GET']
+       allowedOrigins: ['https://www.example.com']
+       supportsCredentials: true
+   ```
+
+   Then rebuild the caches with `drush cr`.
+
+5. Let the frontend show in Drupal's frame. Remove any `X-Frame-Options`
+   header from the frontend's responses. If the frontend sends a
+   `frame-ancestors` rule, add Drupal's origin to it. Name only Drupal's
+   origin, so other sites cannot frame the preview.
+
+To check it, edit a node, change something and press Preview. The Frontend
+tab shows the change.
+
+[Consumer Node Preview's
+README](https://www.drupal.org/project/consumer_node_preview) lists the other
+URL tokens, and how to set targets in `settings.php`.
+
+## How it works
+
+1. The editor presses Preview in Drupal. The Frontend tab opens this module's
+   page in a frame.
+2. The page reads the preview's JSON:API address from the part of its URL
+   after the `#`. Browsers do not send that part to the frontend's server.
+3. The page fetches the preview with the editor's Drupal session. It puts the
+   document in the Druxt store.
+4. `DruxtEntity` renders the node from the store, inside a `DruxtNodePreview`
+   wrapper. The unsaved content goes through the same components as the live
+   site.
+
+## Preview layouts
+
+The page uses the layout that `?layout=` names, but only if `layouts` lists
+it. If not, the page uses the default layout. A preview URL cannot pick any
+other layout.
+
+Each listed layout must be a file in the site's `layouts/` folder that renders
+`<Nuxt />`. A bare layout suits content that sits inside other pages. It has
+the site's type and spacing, but no header or footer.
+
+A site that picks layouts somewhere else can call
+`$druxtNodePreview.layout(name)`. It makes the same check.
+
+## Theming the preview
+
+A live page often adds a title or a container around the node. The preview
+gets the same from a wrapper component, picked like any Druxt wrapper. For a
+`node--doc_page` previewed in `full`, the page uses the first of these that
+exists:
+
+1. `DruxtNodePreviewDocPageFull`
+2. `DruxtNodePreviewDocPage`
+3. `DruxtNodePreviewDefault`
+
+If none of them exists, the node renders in Druxt's plain wrapper.
+
+A wrapper gets any of these props that it declares:
+
+- `document`: the whole JSON:API preview document.
+- `entity`: the previewed resource, with `attributes` such as the title.
+- `mode`, `type` and `uuid`.
+
+Its default slot renders the node with `DruxtEntity`:
+
+```vue
+<!-- components/druxt/node-preview/DocPageFull.vue -->
+<template>
+  <article class="prose">
+    <h1>{{ entity.attributes.title }}</h1>
+    <slot />
+  </article>
+</template>
+
+<script>
+export default {
+  // The props it does not declare would otherwise land on <article>.
+  inheritAttrs: false,
+  props: {
+    entity: { type: Object, required: true },
+  },
+}
+</script>
+```
+
+A wrapper named by bundle alone, such as `DruxtNodePreviewDocPage`, applies to
+every view mode. Put page parts such as a title in the `<Bundle>Full` wrapper,
+as above, or check the `mode` prop.
+
+## Components that fetch their own data
+
+A component that reads the Druxt store shows the unsaved data. A component
+that fetches its data again, such as paragraphs at a revision, shows the saved
+content instead. Skip that fetch while a preview is active:
+
+```js
+if ((this.$store.state.druxtNodePreview || {}).active) return
+```
+
+When the editor leaves the preview, the module removes the preview data from
+the store. The next page loads the saved content.
+
+The module stores the data under the route's `langcode` meta. `DruxtEntity`
+reads it there when it has no `langcode` prop.
+
+## The preview request
+
+The page fetches through the Druxt client, `$druxt.axios`, with credentials.
+The site's request interceptors apply, such as one that adds a workspace
+header. Without the Druxt client, the page uses `window.fetch`.
+
+A preview address that is a path stays a path. The Druxt client resolves it
+against its own base URL, and interceptors that match by path still match it.
+This suits a frontend that reaches Drupal through a proxy on its own origin.
+The editor must then sign in through that proxy too, because the session
+cookie belongs to the host the editor signed in on. Druxt's
+`proxy: { api: true }` forwards the API but not Drupal's sign-in pages, so it
+is not enough on its own.
+
+Without a proxy, the request goes to Drupal's origin. Drupal then needs the
+CORS settings from [Drupal setup](#drupal-setup). The session cookie is
+`SameSite=Lax`, so the frontend and Drupal need one parent domain.
+
+The page only fetches a node preview, from an address that ends in
+`/{uuid}/preview`. The response must be `application/vnd.api+json`, and each
+resource in it must have a JSON:API type and a UUID. If a check fails, the
+page shows an error and puts nothing in the store.
+
+## Server rendering and static sites
+
+The page only works in the browser. A server render shows "Loading
+preview..." and the browser fills it in. A statically generated page has the
+default layout, so the page switches to the listed layout in the browser.
+
+## Troubleshooting
+
+The page shows "Preview unavailable" and a message.
+
+- **HTTP 404.** Drupal has no preview of this node for the editor. Check, in
+  this order:
+  1. The editor pressed Preview, and can view the node.
+  2. The frontend and Drupal share a parent domain. On your own computer,
+     use one host name for both: `localhost` and `127.0.0.1` count as
+     different.
+  3. The CORS settings in `services.yml` name the frontend's origin.
+- **"The preview endpoint is not on this site or its Drupal site".** Add the
+  preview's origin to the `origins` option.
+- **"The URL fragment has no preview endpoint".** The preview target's URL
+  template has no `#[jsonapi_node_preview]` at the end.
+- **HTTP 400.** An `include` path that the previewed type does not have. Key
+  that path by type.
+
+If `DruxtEntity` reports a missing schema:
+
+1. Check that the content type has a display for the previewed view mode, on
+   its **Manage display** tab.
+2. Make sure Drupal is up, then restart the frontend. Nuxt builds the schema
+   when it starts, and `.nuxt` can hold an old one.
+
+The [end to end troubleshooting
+notes](https://github.com/druxt-contrib/druxt-node-preview/blob/0.x/test/e2e/TROUBLESHOOTING.md)
+cover the test stack.
+
+## Writing another frontend
+
+[Consumer Node Preview's
+README](https://www.drupal.org/project/consumer_node_preview) shows how a
+frontend reads the preview address from the URL, including the `https:/`
+repair that some routers need. Before it renders anything, a frontend makes
+the same checks as this module. See [The preview request](#the-preview-request).
+
+This module reads `[view_mode]` and `[layout]` from the `vm` and `layout`
+query parameters. They change only how the preview looks. The JSON:API
+document is the same for each.
+
+## Example
+
+See the [example](https://github.com/druxt-contrib/druxt-node-preview/tree/0.x/example)
+for a paired Drupal and Nuxt setup.
+
+## Licence
+
+MIT.

package/dist/index.esm.js

@@ -0,0 +1,117 @@
+import { resolve } from 'path';
+
+const toOrigin = (url) => {
+  try {
+    const { origin, protocol } = new URL(url);
+    return ["http:", "https:"].includes(protocol) ? origin : null;
+  } catch (e) {
+    return null;
+  }
+};
+const warn = (message) => console.warn("[druxt-node-preview] " + message);
+const toInclude = (value) => {
+  const paths = (list, where) => {
+    if (!Array.isArray(list)) {
+      warn(
+        `Ignored the include option${where}. Use a list of paths, such as ['field_content.field_media'].`
+      );
+      return [];
+    }
+    return list.filter((path) => {
+      if (typeof path === "string" && /^[A-Za-z0-9_.-]+$/.test(path))
+        return true;
+      warn(
+        `Ignored the include path ${JSON.stringify(path)}${where}. Use field names joined by dots, such as "field_content.field_media".`
+      );
+      return false;
+    });
+  };
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return Object.fromEntries(
+      Object.entries(value).filter(([type]) => {
+        if (/^[A-Za-z0-9_]+--[A-Za-z0-9_]+$/.test(type)) return true;
+        warn(
+          `Ignored the include key "${type}". Key paths by JSON:API type, such as "node--page".`
+        );
+        return false;
+      }).map(([type, list]) => [type, paths(list, ` for ${type}`)])
+    );
+  }
+  return paths(value, "");
+};
+const toLayouts = (value) => {
+  if (!Array.isArray(value)) {
+    warn(
+      "Ignored the layouts option. Use a list of layout names, such as ['preview']."
+    );
+    return [];
+  }
+  return value.filter((name) => {
+    if (typeof name === "string" && /^[A-Za-z0-9_-]+$/.test(name)) return true;
+    warn(
+      `Ignored the layout ${JSON.stringify(name)}. Use the name of a file in layouts/, such as "preview". A layout in a subfolder cannot be listed.`
+    );
+    return false;
+  });
+};
+const NuxtModule = function(moduleOptions = {}) {
+  const druxt = (this.options || {}).druxt || {};
+  const options = {
+    path: "/druxt/node/preview",
+    include: [],
+    origins: [],
+    layouts: [],
+    ...druxt.nodePreview || {},
+    ...moduleOptions
+  };
+  this.options.store = true;
+  this.addTemplate({
+    src: resolve(__dirname, "../templates/DruxtNodePreview.vue"),
+    fileName: "components/druxt-node-preview.vue"
+  });
+  const { dst } = this.addTemplate({
+    src: resolve(__dirname, "../templates/DruxtNodePreviewPage.vue"),
+    fileName: "components/druxt-node-preview-page.vue"
+  });
+  this.extendRoutes((routes, resolveRoute) => {
+    routes.unshift({
+      name: "druxt-node-preview",
+      path: options.path,
+      component: resolveRoute(this.options.buildDir, dst)
+    });
+  });
+  if (!Array.isArray(options.origins)) {
+    warn(
+      "Ignored the origins option. Use a list of full http(s) URLs, such as ['https://cms.example.com']."
+    );
+  }
+  const listed = (Array.isArray(options.origins) ? options.origins : []).filter(
+    (url) => {
+      if (toOrigin(url)) return true;
+      warn(
+        `Ignored the origin "${url}". Use a full http(s) URL, such as "https://cms.example.com".`
+      );
+      return false;
+    }
+  );
+  const pluginOptions = {
+    include: toInclude(options.include),
+    origins: [],
+    layouts: toLayouts(options.layouts)
+  };
+  const setOrigins = () => {
+    const baseUrl = ((this.options || {}).druxt || {}).baseUrl;
+    pluginOptions.origins = [
+      ...new Set([baseUrl, ...listed].map(toOrigin).filter(Boolean))
+    ];
+  };
+  setOrigins();
+  if (this.nuxt) this.nuxt.hook("modules:done", setOrigins);
+  this.addPlugin({
+    src: resolve(__dirname, "../templates/plugin.js"),
+    fileName: "druxt-node-preview.js",
+    options: pluginOptions
+  });
+};
+
+export { NuxtModule as default };

package/dist/index.ssr.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const path = require('path');
+
+const toOrigin = (url) => {
+  try {
+    const { origin, protocol } = new URL(url);
+    return ["http:", "https:"].includes(protocol) ? origin : null;
+  } catch (e) {
+    return null;
+  }
+};
+const warn = (message) => console.warn("[druxt-node-preview] " + message);
+const toInclude = (value) => {
+  const paths = (list, where) => {
+    if (!Array.isArray(list)) {
+      warn(
+        `Ignored the include option${where}. Use a list of paths, such as ['field_content.field_media'].`
+      );
+      return [];
+    }
+    return list.filter((path) => {
+      if (typeof path === "string" && /^[A-Za-z0-9_.-]+$/.test(path))
+        return true;
+      warn(
+        `Ignored the include path ${JSON.stringify(path)}${where}. Use field names joined by dots, such as "field_content.field_media".`
+      );
+      return false;
+    });
+  };
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return Object.fromEntries(
+      Object.entries(value).filter(([type]) => {
+        if (/^[A-Za-z0-9_]+--[A-Za-z0-9_]+$/.test(type)) return true;
+        warn(
+          `Ignored the include key "${type}". Key paths by JSON:API type, such as "node--page".`
+        );
+        return false;
+      }).map(([type, list]) => [type, paths(list, ` for ${type}`)])
+    );
+  }
+  return paths(value, "");
+};
+const toLayouts = (value) => {
+  if (!Array.isArray(value)) {
+    warn(
+      "Ignored the layouts option. Use a list of layout names, such as ['preview']."
+    );
+    return [];
+  }
+  return value.filter((name) => {
+    if (typeof name === "string" && /^[A-Za-z0-9_-]+$/.test(name)) return true;
+    warn(
+      `Ignored the layout ${JSON.stringify(name)}. Use the name of a file in layouts/, such as "preview". A layout in a subfolder cannot be listed.`
+    );
+    return false;
+  });
+};
+const NuxtModule = function(moduleOptions = {}) {
+  const druxt = (this.options || {}).druxt || {};
+  const options = {
+    path: "/druxt/node/preview",
+    include: [],
+    origins: [],
+    layouts: [],
+    ...druxt.nodePreview || {},
+    ...moduleOptions
+  };
+  this.options.store = true;
+  this.addTemplate({
+    src: path.resolve(__dirname, "../templates/DruxtNodePreview.vue"),
+    fileName: "components/druxt-node-preview.vue"
+  });
+  const { dst } = this.addTemplate({
+    src: path.resolve(__dirname, "../templates/DruxtNodePreviewPage.vue"),
+    fileName: "components/druxt-node-preview-page.vue"
+  });
+  this.extendRoutes((routes, resolveRoute) => {
+    routes.unshift({
+      name: "druxt-node-preview",
+      path: options.path,
+      component: resolveRoute(this.options.buildDir, dst)
+    });
+  });
+  if (!Array.isArray(options.origins)) {
+    warn(
+      "Ignored the origins option. Use a list of full http(s) URLs, such as ['https://cms.example.com']."
+    );
+  }
+  const listed = (Array.isArray(options.origins) ? options.origins : []).filter(
+    (url) => {
+      if (toOrigin(url)) return true;
+      warn(
+        `Ignored the origin "${url}". Use a full http(s) URL, such as "https://cms.example.com".`
+      );
+      return false;
+    }
+  );
+  const pluginOptions = {
+    include: toInclude(options.include),
+    origins: [],
+    layouts: toLayouts(options.layouts)
+  };
+  const setOrigins = () => {
+    const baseUrl = ((this.options || {}).druxt || {}).baseUrl;
+    pluginOptions.origins = [
+      ...new Set([baseUrl, ...listed].map(toOrigin).filter(Boolean))
+    ];
+  };
+  setOrigins();
+  if (this.nuxt) this.nuxt.hook("modules:done", setOrigins);
+  this.addPlugin({
+    src: path.resolve(__dirname, "../templates/plugin.js"),
+    fileName: "druxt-node-preview.js",
+    options: pluginOptions
+  });
+};
+
+module.exports = NuxtModule;

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@druxt-contrib/node-preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-dev.20261030024907",
+  "description": "Renders Drupal node previews in a Druxt frontend, fed by JSON:API Node Preview and Consumer Node Preview.",
+  "keywords": [
+    "decoupled",
+    "drupal",
+    "druxt",
+    "jsonapi",
+    "json:api",
+    "module",
+    "node preview",
+    "nuxt",
+    "preview"
+  ],
+  "homepage": "https://github.com/druxt-contrib/druxt-node-preview#readme",
+  "bugs": "https://github.com/druxt-contrib/druxt-node-preview/issues",
+  "repository": "github:druxt-contrib/druxt-node-preview",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "require": "./dist/index.ssr.js",
+      "import": "./dist/index.ssr.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "dist/index.ssr.js",
+  "module": "dist/index.esm.js",
+  "files": [
+    "dist",
+    "templates",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "siroc build",
+    "build:watch": "siroc build --watch",
+    "changeset": "changeset",
+    "hooks:install": "git config core.hooksPath .githooks",
+    "lint": "npm run lint:js && npm run lint:format && npm run lint:md && npm run lint:cspell && npm run lint:private && npm run lint:attribution && npm run lint:knip",
+    "lint:attribution": "bash .gitlab/scripts/check-attribution.sh",
+    "lint:audit": "npm audit --omit=dev --audit-level=high",
+    "lint:commit": "commitlint",
+    "lint:cspell": "cspell lint --no-progress --no-must-find-files --gitignore --dot \"**/*.{js,mjs,vue,json,jsonc,md,yml,yaml}\"",
+    "lint:format": "prettier --check \"**/*.{js,mjs,vue,json,jsonc,md,yml,yaml}\"",
+    "lint:format:fix": "prettier --write \"**/*.{js,mjs,vue,json,jsonc,md,yml,yaml}\"",
+    "lint:js": "eslint --ext .js,.mjs,.vue src templates test scripts",
+    "lint:knip": "knip --include dependencies,unlisted --no-config-hints",
+    "lint:md": "markdownlint-cli2 \"**/*.md\"",
+    "lint:private": "node scripts/lint-private-refs.mjs",
+    "lint:prose": "PROSE_LINT_GLOB='!{.changeset,example/drupal}/**' bash .gitlab/scripts/lint-prose.sh --all",
+    "lint:prose:install": "bash .gitlab/scripts/install-vale.sh .vale/bin .vale/styles",
+    "prepack": "npm run build",
+    "prepare": "node scripts/postinstall.mjs",
+    "test": "jest",
+    "test:e2e": "playwright test",
+    "test:e2e:stack": "test/e2e/run.sh",
+    "test:watch": "jest --watch"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.0",
+    "@babel/preset-env": "^7.26.0",
+    "@changesets/cli": "2.25.2",
+    "@commitlint/cli": "17.8.1",
+    "@commitlint/config-conventional": "17.8.1",
+    "@playwright/test": "^1.49.0",
+    "babel-core": "7.0.0-bridge.0",
+    "cspell": "7.3.9",
+    "druxt": "0.25.0",
+    "druxt-entity": "0.29.0",
+    "esbuild-jest": "0.5.0",
+    "eslint": "8.28.0",
+    "eslint-config-prettier": "8.10.0",
+    "eslint-plugin-nuxt": "3.2.0",
+    "eslint-plugin-vue": "8.7.1",
+    "jest": "27.5.1",
+    "jest-environment-jsdom": "27.5.1",
+    "jest-junit": "^15.0.0",
+    "knip": "2.43.0",
+    "markdownlint-cli2": "0.10.0",
+    "prettier": "3.3.3",
+    "siroc": "0.16.0",
+    "vue": "2.7.14",
+    "vue-jest": "3.0.7",
+    "vue-template-compiler": "2.7.14"
+  },
+  "peerDependencies": {
+    "druxt": ">=0.25.0 <1",
+    "druxt-entity": ">=0.29.0 <1",
+    "vue": "^2.7.14"
+  },
+  "packageManager": "npm@8.19.4",
+  "engines": {
+    "node": ">=16.20.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "jest-junit": {
+    "outputDirectory": "reports/junit",
+    "outputName": "junit.xml"
+  }
+}

package/templates/DruxtNodePreview.vue

@@ -0,0 +1,81 @@
+<script>
+import DruxtModule from 'druxt/dist/components/DruxtModule.vue'
+
+/**
+ * Renders a seeded node preview through a themeable wrapper.
+ *
+ * The wrapper is picked by the node's bundle and view mode, like every Druxt
+ * module, so a site can wrap the preview in the same page chrome as the live
+ * route. For a `node--page` previewed in `full`, the first of these that
+ * exists is used:
+ *
+ * - `DruxtNodePreviewPageFull`
+ * - `DruxtNodePreviewPage`
+ * - `DruxtNodePreviewDefault`
+ *
+ * A wrapper receives whichever of these props it declares: `document` (the
+ * whole JSON:API preview document), `entity` (its main resource), `mode`,
+ * `type` and `uuid`. Its default slot renders the node with `DruxtEntity`.
+ */
+export default {
+  name: 'DruxtNodePreview',
+
+  extends: DruxtModule,
+
+  props: {
+    /**
+     * The JSON:API preview document, already seeded into the store.
+     *
+     * @type {object}
+     */
+    document: {
+      type: Object,
+      required: true,
+    },
+
+    /**
+     * The view mode being previewed.
+     *
+     * @type {string}
+     */
+    mode: {
+      type: String,
+      default: 'full',
+    },
+  },
+
+  computed: {
+    /** The previewed resource. */
+    entity: ({ document }) => (document || {}).data || {},
+
+    /** The bundle, from a JSON:API type like `node--page`. */
+    bundle: ({ entity }) => (entity.type || '').split('--').slice(1).join('--'),
+  },
+
+  druxt: {
+    componentOptions: ({ bundle, mode }) => [[bundle, mode], ['default']],
+
+    propsData: ({ document, entity, mode }) => ({
+      document,
+      entity,
+      mode,
+      type: entity.type,
+      uuid: entity.id,
+    }),
+
+    slots(h) {
+      return {
+        default: () =>
+          h('DruxtEntity', {
+            key: this.entity.id,
+            props: {
+              mode: this.mode,
+              type: this.entity.type,
+              uuid: this.entity.id,
+            },
+          }),
+      }
+    },
+  },
+}
+</script>

package/templates/DruxtNodePreviewPage.vue

@@ -0,0 +1,162 @@
+<template>
+  <div
+    class="druxt-node-preview"
+    :data-view-mode="viewMode"
+    :data-entity-type="entity && entity.type"
+    :data-entity-uuid="entity && entity.id"
+  >
+    <div v-if="error" class="druxt-node-preview-error">
+      <h1>Preview unavailable</h1>
+      <p>{{ error }}</p>
+    </div>
+
+    <DruxtNodePreview
+      v-else-if="document"
+      :key="entity.id"
+      :document="document"
+      :mode="viewMode"
+    />
+
+    <p v-else>Loading preview...</p>
+  </div>
+</template>
+
+<script>
+import DruxtNodePreview from './druxt-node-preview.vue'
+
+/**
+ * Renders a Drupal node preview.
+ *
+ * This page only works in the browser. The preview endpoint arrives in the
+ * URL fragment, which never reaches the server, and the fetch uses the
+ * editor's Drupal session cookie. A server render shows "Loading preview...".
+ */
+export default {
+  name: 'DruxtNodePreviewPage',
+
+  components: { DruxtNodePreview },
+
+  /**
+   * The layout named by `?layout=`, when the `layouts` option lists it.
+   *
+   * @param {object} context - The Nuxt context.
+   *
+   * @returns {string|undefined} The layout, or undefined for the default.
+   */
+  layout: ({ $druxtNodePreview, route }) =>
+    $druxtNodePreview.layout(route.query.layout),
+
+  data: () => ({
+    document: null,
+    entity: null,
+    error: null,
+  }),
+
+  computed: {
+    // The view mode comes from the query, which any link can set, so only a
+    // machine name is used.
+    viewMode() {
+      const { vm } = this.$route.query
+      return typeof vm === 'string' && /^[A-Za-z0-9_]+$/.test(vm) ? vm : 'full'
+    },
+  },
+
+  async mounted() {
+    // A statically generated site renders this page once, with no query, and
+    // Nuxt keeps that layout in the browser. So the listed layout is set here
+    // as well, where the query is known.
+    const layout = this.$druxtNodePreview.layout(this.$route.query.layout)
+    if (layout && this.$nuxt && this.$nuxt.layoutName !== layout) {
+      const previous = this.$nuxt.layoutName
+      // A layout chunk can fail to download. Then the preview shows in the
+      // layout the page already has. Webpack names that a ChunkLoadError, or
+      // says "Loading chunk" in the message. Any other error is a fault in
+      // the layout, so it goes to the console too.
+      const report = (error) => {
+        if (
+          !/chunk/i.test(`${error && error.name} ${error && error.message}`)
+        ) {
+          console.error('DruxtNodePreview could not load the layout:', error)
+        }
+      }
+      const state = this.$nuxt.nuxt || {}
+      const before = state.err
+      try {
+        await this.$nuxt.loadLayout(layout)
+        if (state.err && state.err !== before) {
+          // Nuxt 2 does not reject a failed layout. It calls error() and
+          // resolves, and its error page would replace the preview. So the
+          // error is cleared. Nuxt's error handler can still change the
+          // layout, so the page waits for it before the check below.
+          report(state.err)
+          this.$nuxt.error(null)
+          await new Promise((done) => setTimeout(done))
+        } else {
+          this.$nuxt.setLayout(layout)
+        }
+      } catch (error) {
+        report(error)
+      }
+      // A new layout mounts a new page, which loads the preview. If this one
+      // loaded it too, the two would seed the same document twice. Nuxt falls
+      // back to the default layout for one the site does not have, and then
+      // nothing new mounts, so this page loads the preview itself.
+      if (this.$nuxt.layoutName !== previous) return
+    }
+
+    return this.load()
+  },
+
+  // A site can keep pages alive. Leaving the preview flushes the seeded
+  // resources, so a page that comes back loads its preview again. Vue also
+  // calls activated after the first mount, and that call loads nothing.
+  activated() {
+    if (!this.left) return
+    this.left = false
+    return this.load()
+  },
+
+  deactivated() {
+    this.left = true
+  },
+
+  beforeDestroy() {
+    this.gone = true
+  },
+
+  methods: {
+    /**
+     * Fetches the preview and seeds the Druxt store with it.
+     */
+    async load() {
+      this.run = (this.run || 0) + 1
+      const run = this.run
+      // A reload starts clean. The old preview's resources are flushed, and
+      // an old error would hide a preview that now loads.
+      this.document = null
+      this.entity = null
+      this.error = null
+      try {
+        const endpoint = this.$druxtNodePreview.endpoint()
+        if (!endpoint) {
+          this.error = 'The URL fragment has no preview endpoint.'
+          return
+        }
+        const document = await this.$druxtNodePreview.fetch(endpoint)
+        // The editor can open another preview before this fetch ends. A page
+        // that is gone, kept alive or loading again seeds nothing, so this
+        // document cannot replace a newer one.
+        if (this.gone || this.left || run !== this.run) return
+        // seed() returns null once the editor is leaving. This page can still
+        // be mounted then, and a document without an entity would not render.
+        const entity = this.$druxtNodePreview.seed(document)
+        if (!entity) return
+        this.entity = entity
+        this.document = document
+      } catch (error) {
+        if (run === this.run) this.error = error.message
+      }
+    },
+  },
+}
+</script>

package/templates/plugin.js

@@ -0,0 +1,345 @@
+/**
+ * The $druxtNodePreview plugin.
+ *
+ * Fetches a JSON:API Node Preview document with the editor's Drupal session,
+ * and seeds the Druxt store with it so DruxtEntity renders the unsaved data.
+ *
+ * It also registers the `druxtNodePreview` store module. Its `active` state is
+ * true while a preview is seeded, so a site component that refetches its data
+ * (for example paragraphs at a revision) can skip that and read the store.
+ *
+ * Leaving the preview route flushes the seeded resources from the Druxt store
+ * and clears `active`, so the next page renders the saved content.
+ */
+export default ({ app, store }, inject) => {
+  const include = JSON.parse('<%= JSON.stringify(options.include) %>')
+  const layouts = JSON.parse('<%= JSON.stringify(options.layouts) %>')
+  // Origins the preview may come from, besides this site's own.
+  const origins = JSON.parse('<%= JSON.stringify(options.origins) %>')
+
+  // Drupal gives every JSON:API resource a UUID, and a JSON:API Node Preview
+  // URL ends in /{uuid}/preview.
+  const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+  const PREVIEW_PATH =
+    /\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/preview$/
+
+  /**
+   * Returns the node's UUID from a preview endpoint, or throws.
+   *
+   * The endpoint comes from the URL fragment, which any link can set. So it
+   * must be on this site or an allowed origin, and it must be a node preview.
+   * Without these checks, a crafted link could make the page fetch other JSON
+   * with the editor's credentials, such as an uploaded file, and render it.
+   *
+   * @param {string} endpoint - The endpoint, a URL or a path.
+   *
+   * @returns {string} The previewed node's UUID.
+   */
+  const checkEndpoint = (endpoint) => {
+    const { origin, pathname } = new URL(endpoint, window.location.origin)
+    if (origin !== window.location.origin && !origins.includes(origin)) {
+      throw new Error(
+        'The preview endpoint is not on this site or its Drupal site: ' + origin
+      )
+    }
+    const match = pathname.match(PREVIEW_PATH)
+    if (!match) {
+      throw new Error('The preview endpoint is not a node preview: ' + pathname)
+    }
+    return match[1]
+  }
+
+  /**
+   * Throws unless a response's content type is JSON:API.
+   *
+   * @param {*} type - The Content-Type header.
+   */
+  const checkType = (type) => {
+    if (!String(type || '').includes('application/vnd.api+json')) {
+      throw new Error('The preview response is not a JSON:API document.')
+    }
+  }
+
+  /**
+   * Throws unless the document is safe to put in the Druxt store.
+   *
+   * Every resource needs a JSON:API type and a UUID. The store keys resources
+   * by type and id, so a name such as `__proto__` would write to the object
+   * prototype.
+   *
+   * @param {*} doc - The response.
+   * @param {string} [uuid] - The UUID the main resource must have.
+   */
+  const checkDocument = (doc, uuid) => {
+    const safe = (key) =>
+      typeof key === 'string' &&
+      /^[A-Za-z0-9_-]+$/.test(key) &&
+      !(key in Object.prototype)
+    const included = (doc || {}).included
+    const resources =
+      doc &&
+      typeof doc === 'object' &&
+      doc.data &&
+      typeof doc.data === 'object' &&
+      (included === undefined || Array.isArray(included))
+        ? [doc.data, ...(included || [])]
+        : []
+    if (
+      !resources.length ||
+      !resources.every(
+        (resource) => resource && safe(resource.type) && UUID.test(resource.id)
+      )
+    ) {
+      throw new Error('The preview response is not a node preview document.')
+    }
+    if (uuid && doc.data.id !== uuid) {
+      throw new Error('The preview response is not a preview of ' + uuid + '.')
+    }
+  }
+
+  /**
+   * Returns whether a route is the preview route.
+   *
+   * nuxt-i18n adds a language suffix to route names, such as
+   * `druxt-node-preview___en`.
+   *
+   * @param {object} route - A route.
+   *
+   * @returns {boolean} True for the preview route.
+   */
+  const isPreview = (route) =>
+    /^druxt-node-preview(___[A-Za-z0-9_-]+)?$/.test((route || {}).name || '')
+
+  // The type and id of every resource the preview put in the Druxt store.
+  const seeded = []
+
+  if (!store.hasModule('druxtNodePreview')) {
+    store.registerModule(
+      'druxtNodePreview',
+      {
+        namespaced: true,
+        state: () => ({ active: false, uuid: null }),
+        mutations: {
+          start(state, uuid) {
+            state.active = true
+            state.uuid = uuid
+          },
+          stop(state) {
+            state.active = false
+            state.uuid = null
+          },
+        },
+      },
+      { preserveState: !!(store.state || {}).druxtNodePreview }
+    )
+  }
+
+  // True from when the editor leaves the preview route until a preview route
+  // opens again. vue-router changes currentRoute only after the next route's
+  // code loads, so a fetch that ends meanwhile still sees the preview route.
+  // When that code fails to download, Nuxt reloads the page, which resets
+  // this. A site guard that cancels the leave with next(false) leaves it set
+  // until the next navigation, because vue-router has no hook for that.
+  let left = false
+
+  // Before the next route loads, so none of its components read a seeded
+  // resource. Druxt then fetches the saved one.
+  if (app.router) {
+    app.router.beforeEach((to, from, next) => {
+      if (isPreview(from) && !isPreview(to)) {
+        left = true
+        if (seeded.length) {
+          for (const { type, id } of seeded.splice(0)) {
+            store.commit('druxt/flushResource', { type, id })
+          }
+          store.commit('druxtNodePreview/stop')
+        }
+      } else if (isPreview(to)) {
+        left = false
+      }
+      next()
+    })
+  }
+
+  /**
+   * Adds the configured includes to the include the URL already has.
+   *
+   * Consumer Node Preview already includes a node's paragraphs. A site adds
+   * what those paragraphs reference, such as their media.
+   *
+   * @param {string} url - The endpoint.
+   *
+   * @returns {string} The URL to request.
+   */
+  const withInclude = (url) => {
+    const configured = includeFor(url)
+    if (!configured.length) return url
+    const [base, query = ''] = url.split('?')
+    const params = query
+      .split('&')
+      .filter((param) => param && !param.startsWith('include='))
+    const current = (
+      query.split('&').find((param) => param.startsWith('include=')) ||
+      'include='
+    )
+      .slice('include='.length)
+      .split(',')
+      .filter(Boolean)
+    const merged = [...new Set([...current, ...configured])]
+    return base + '?' + [...params, 'include=' + merged.join(',')].join('&')
+  }
+
+  /**
+   * Returns the configured include paths for an endpoint.
+   *
+   * The option is a list for every previewed type, or an object of lists
+   * keyed by JSON:API type, such as `node--page`. JSON:API rejects a path
+   * that the type does not have, so a path only some bundles have goes in
+   * the object form.
+   *
+   * @param {string} url - The endpoint, from Consumer Node Preview:
+   *   `.../{entity type}/{bundle}/{uuid}/preview`.
+   *
+   * @returns {string[]} The include paths.
+   */
+  function includeFor(url) {
+    if (Array.isArray(include)) return include
+    const match = url
+      .split('?')[0]
+      .match(/\/([^/]+)\/([^/]+)\/[0-9a-f-]{36}\/preview$/)
+    return (match && include[match[1] + '--' + match[2]]) || []
+  }
+
+  /**
+   * Builds an error that carries the status and the start of the body.
+   *
+   * @param {string} url - The requested URL.
+   * @param {number} status - The HTTP status.
+   * @param {string} body - The response body.
+   *
+   * @returns {Error} The error.
+   */
+  const failure = (url, status, body) =>
+    new Error(
+      'Preview request failed with HTTP ' +
+        status +
+        ' for ' +
+        url +
+        (body ? ': ' + String(body).slice(0, 300) : '')
+    )
+
+  const plugin = {
+    /**
+     * Returns the Nuxt layout for a requested layout name.
+     *
+     * Only a name in the `layouts` option is used, so a preview URL cannot
+     * put the page in any other layout of the site.
+     *
+     * @param {*} name - The requested name, usually from `?layout=`.
+     *
+     * @returns {string|undefined} The layout, or undefined for the default.
+     */
+    layout: (name) =>
+      typeof name === 'string' && layouts.includes(name) ? name : undefined,
+
+    /**
+     * Returns the preview endpoint from the URL fragment.
+     *
+     * The fragment never reaches any server, so the preview URL stays out of
+     * request logs. It is only readable in the browser.
+     *
+     * @returns {string|null} The endpoint, or null when there is none.
+     */
+    endpoint: () => {
+      const hash = (window.location.hash || '').slice(1)
+      if (!hash) return null
+      // vue-router normalises the URL, which collapses the double slash after
+      // the scheme inside the fragment. Repair it.
+      return decodeURIComponent(hash).replace(/^(https?):\/(?!\/)/, '$1://')
+    },
+
+    /**
+     * Fetches the preview document with the editor's session.
+     *
+     * The request goes through the Druxt client, with credentials. The site's
+     * request interceptors apply, and the editor's session cookie goes with
+     * it. A path stays a path. The client resolves it against its own base
+     * URL, and interceptors that decide by path still see it.
+     *
+     * @param {string} endpoint - The JSON:API Node Preview endpoint.
+     *
+     * @returns {object} The JSON:API document.
+     */
+    fetch: async (endpoint) => {
+      const uuid = checkEndpoint(endpoint)
+      const url = withInclude(endpoint)
+      const headers = { Accept: 'application/vnd.api+json' }
+      const client = (app.$druxt || {}).axios
+      if (client) {
+        let response
+        try {
+          response = await client.get(url, { headers, withCredentials: true })
+        } catch (error) {
+          const failed = error.response || {}
+          if (!failed.status) throw error
+          const body =
+            typeof failed.data === 'string'
+              ? failed.data
+              : JSON.stringify(failed.data || '')
+          throw failure(url, failed.status, body)
+        }
+        checkType((response.headers || {})['content-type'])
+        checkDocument(response.data, uuid)
+        return response.data
+      }
+      const response = await window.fetch(url, {
+        credentials: 'include',
+        headers,
+      })
+      if (!response.ok) {
+        throw failure(
+          url,
+          response.status,
+          await response.text().catch(() => '')
+        )
+      }
+      checkType(response.headers && response.headers.get('content-type'))
+      const doc = await response.json()
+      checkDocument(doc, uuid)
+      return doc
+    },
+
+    /**
+     * Seeds the Druxt store with the preview document.
+     *
+     * The main resource and every included resource are stored, so a
+     * DruxtEntity render finds the unsaved preview data instead of fetching
+     * the saved data from the API.
+     *
+     * @param {object} doc - The JSON:API document.
+     *
+     * @returns {object|null} The type and id of the previewed resource, or null
+     *   when the editor has left the preview.
+     */
+    seed: (doc) => {
+      // A fetch can end after the editor has left the preview. Then nothing
+      // is seeded, so nothing unsaved reaches the next page.
+      if (left) return null
+      if (app.router && !isPreview(app.router.currentRoute)) return null
+      checkDocument(doc)
+      // DruxtEntity reads a resource under its language: its langcode prop,
+      // else the route's langcode meta. The preview's DruxtEntity has no
+      // langcode prop, so the resources go under the route's.
+      const prefix = (((app.router || {}).currentRoute || {}).meta || {})
+        .langcode
+      for (const data of [doc.data, ...(doc.included || [])]) {
+        store.commit('druxt/addResource', { prefix, resource: { data } })
+        seeded.push({ type: data.type, id: data.id })
+      }
+      store.commit('druxtNodePreview/start', doc.data.id)
+      return { type: doc.data.type, id: doc.data.id }
+    },
+  }
+
+  inject('druxtNodePreview', plugin)
+}