@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/content/distributions.tsx

@@ -0,0 +1,271 @@
+// THE DISTRIBUTIONS the project's blocks come from (ADR-0059): a card each — its cover, icon,
+// title, what it brings and where its source lives — and, opened, its blocks as a wall of LIVE
+// previews in the manner of Pinterest: each card shows the block as its editor facet declares it
+// (the same `preview` the picker's bubble shows), mounted only once the card comes into sight.
+// A block's card opens the block's own page (blockPage.tsx, ADR-0060): its playground and variants.
+//
+// The workbench's list page shows this at `/workbench/distributions`; the distribution opened is
+// the address's `?palette=`, the block `&block=` — shallow moves, Back goes back up.
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useServerAction } from '@mosetta/react/server-action';
+import { useComponent } from '@mosetta/react';
+import { compareVersions } from '@mosetta/content';
+import type { ICatalogEntry, IDistributionEntry } from '@mosetta/content';
+import { listComponentsToken } from './contentCommon';
+import { useDisabledDistributions } from './disconnected';
+import { usePreviewPlan } from './componentPreview';
+import { STAGE_WIDTH, useScaledStage, useSeen } from './scaledStage';
+import { BlockPage } from './blockPage';
+import { catalogVersions } from './catalogVersions';
+import './distributions.css';
+
+const NO_ENTRIES: readonly ICatalogEntry[] = [];
+const NO_DISTRIBUTIONS: readonly IDistributionEntry[] = [];
+
+/** the address parameters naming the tile palette opened, its version, and the block */
+export const DISTRIBUTION_PARAM = 'palette';
+export const VERSION_PARAM = 'version';
+export const BLOCK_PARAM = 'block';
+
+interface IOpened {
+  readonly distribution: string | null;
+  /** a version other than the latest, or null — the latest */
+  readonly version?: string | null;
+  readonly block: string | null;
+}
+
+const readOpened = (): IOpened => {
+  if (typeof window === 'undefined') return { distribution: null, version: null, block: null };
+  const search = new URLSearchParams(window.location.search);
+  return { distribution: search.get(DISTRIBUTION_PARAM), version: search.get(VERSION_PARAM), block: search.get(BLOCK_PARAM) };
+};
+
+/** what is opened, kept in the address — Back and a shared link find it again */
+function useOpened(): [IOpened, (next: IOpened) => void] {
+  const [opened, setOpened] = useState<IOpened>(readOpened);
+  useEffect(() => {
+    const follow = () => setOpened(readOpened());
+    window.addEventListener('popstate', follow);
+    return () => window.removeEventListener('popstate', follow);
+  }, []);
+  const open = (next: IOpened) => {
+    const url = new URL(window.location.href);
+    for (const [param, value] of [[DISTRIBUTION_PARAM, next.distribution], [VERSION_PARAM, next.version ?? null], [BLOCK_PARAM, next.block]] as const) {
+      if (value) url.searchParams.set(param, value);
+      else url.searchParams.delete(param);
+    }
+    window.history.pushState(window.history.state, '', url);
+    setOpened(next);
+  };
+  return [opened, open];
+}
+
+/** the blocks a distribution offers authors — no page roots, no tools' own */
+const blocksOf = (components: readonly ICatalogEntry[], d: IDistributionEntry) => components
+  .filter((c) => c.reference.namespace === d.namespace && c.reference.version === d.version && !c.isRoot && !c.internal)
+  .sort((a, b) => a.reference.name.localeCompare(b.reference.name));
+
+/** a link to the source, quiet, never the card's own click */
+function SourceLink({ href }: { href: string }) {
+  return (
+    <a className="distributions__source"
+       href={href}
+       target="_blank"
+       rel="noreferrer"
+       data-test-id="distribution-source"
+       onClick={(e) => e.stopPropagation()}>Repository ↗</a>
+  );
+}
+
+function DistributionCard({ distribution, blocks, onOpen }: { distribution: IDistributionEntry; blocks: number; onOpen: () => void }) {
+  return (
+    <button type="button"
+            className="distributions__card"
+            data-test-id="distribution-card"
+            data-distribution={distribution.namespace}
+            onClick={onOpen}>
+      <span className="distributions__cover">
+        {distribution.coverUrl ? <img src={distribution.coverUrl}
+                                      alt=""
+                                      draggable={false} /> : null}
+      </span>
+      <span className="distributions__card-body">
+        <span className="distributions__card-head">
+          {distribution.iconUrl ? <img className="distributions__icon"
+                                       src={distribution.iconUrl}
+                                       alt=""
+                                       draggable={false} /> : null}
+          <span className="distributions__title">{distribution.title}</span>
+        </span>
+        {distribution.description ? <span className="distributions__description">{distribution.description}</span> : null}
+        <span className="distributions__meta">
+          <span>{`${blocks} ${blocks === 1 ? 'block' : 'blocks'} · ${distribution.namespace}@${distribution.version}`}</span>
+          {distribution.source ? <SourceLink href={distribution.source} /> : null}
+        </span>
+      </span>
+    </button>
+  );
+}
+
+/**
+ * One block, shown live: its declared preview mounted once the card is in sight, laid out at a
+ * stage width and scaled to the card's. The card opens the block's page.
+ */
+function SpecimenCard({ component, libraryRoot, onOpen }: { component: ICatalogEntry; libraryRoot: string | undefined; onOpen: () => void }) {
+  const self = useComponent().reference;
+  const cardRef = useRef<HTMLDivElement>(null);
+  const seen = useSeen(cardRef);
+  const [target] = useState(() => ({ reference: component.id, hasEditor: component.hasEditor, libraryRoot, anchor: { top: 0, left: 0, right: 0 } }));
+  const plan = usePreviewPlan(seen ? target : null, self);
+  const { stage, failed, scale, height } = useScaledStage(cardRef, plan.status === 'ready' ? plan.spec : null);
+  const none = plan.status === 'none' || plan.status === 'failed' || (plan.status === 'ready' && failed);
+  // a card, not a <button>: the block inside renders buttons and links of its own
+  return (
+    <div ref={cardRef}
+         className="distributions__specimen"
+         role="link"
+         tabIndex={0}
+         data-test-id="distribution-block"
+         data-component={component.id}
+         data-specimen={plan.status}
+         onClick={onOpen}
+         onKeyDown={(e) => {
+           if (e.key === 'Enter' || e.key === ' ') {
+             e.preventDefault();
+             onOpen();
+           }
+         }}>
+      <div className="distributions__specimen-head">
+        {component.iconUrl ? <img className="distributions__block-icon"
+                                  src={component.iconUrl}
+                                  alt=""
+                                  draggable={false} /> : null}
+        <span className="distributions__block-name">{component.reference.name}</span>
+        <span className="distributions__specimen-open"
+              aria-hidden="true">Open ›</span>
+      </div>
+      <div className="distributions__specimen-view"
+           style={{ height: none ? undefined : `${Math.max(48, height)}px` }}>
+        {none ? <div className="distributions__no-preview">No preview declared</div> : null}
+        <div ref={stage}
+             className="distributions__stage"
+             style={{ width: `${STAGE_WIDTH}px`, transform: `scale(${scale})` }} />
+      </div>
+    </div>
+  );
+}
+
+export function DistributionsView() {
+  const catalog = useServerAction({ token: listComponentsToken, input: {} });
+  const [opened, open] = useOpened();
+  const disabled = useDisabledDistributions();
+  const components: readonly ICatalogEntry[] = catalog.isSuccess() && catalog.serverData.ok ? catalog.serverData.components : NO_ENTRIES;
+  const every: readonly IDistributionEntry[] = catalog.isSuccess() && catalog.serverData.ok ? catalog.serverData.distributions ?? NO_DISTRIBUTIONS : NO_DISTRIBUTIONS;
+  // every version deployed stays in the catalog (ADR-0061): a card per distribution, at its latest
+  const versions = useMemo(() => catalogVersions(components, every), [components, every]);
+  const latestOf = (d: IDistributionEntry) => compareVersions(d.version, versions.latest(d.namespace) ?? d.version) === 0;
+  // a disconnected distribution is not this site's any more: no card
+  const distributions = every
+    .filter((d) => !d.internal && !disabled.includes(d.namespace) && latestOf(d) && blocksOf(components, d).length > 0);
+  const libraryRootOf = (d: IDistributionEntry) => components.find((c) => c.isRoot
+    && c.reference.namespace === d.namespace && c.reference.version === d.version)?.id;
+
+  if (catalog.isLoading()) {
+    return <div className="distributions distributions--note">Loading the tile palettes…</div>;
+  }
+  if (catalog.isError() || (catalog.isSuccess() && !catalog.serverData.ok)) {
+    return <div className="distributions distributions--note">Could not read the tile palettes</div>;
+  }
+  // the distribution opened — at the version the address names, or its latest
+  const card = opened.distribution ? distributions.find((d) => d.namespace === opened.distribution) : undefined;
+  const shown = card && opened.version ? versions.distribution(card.namespace, opened.version) ?? card : card;
+  // the latest is the address without a version
+  const atVersion = (version: string) => (card && compareVersions(version, card.version) !== 0 ? version : null);
+  const block = shown && opened.block ? blocksOf(components, shown).find((c) => c.reference.name === opened.block) : undefined;
+  if (shown && block) {
+    return (
+      <BlockPage key={block.id}
+                 component={block}
+                 distribution={shown}
+                 components={components}
+                 libraryRoot={libraryRootOf(shown)}
+                 onBack={() => open({ distribution: shown.namespace, version: atVersion(shown.version), block: null })} />
+    );
+  }
+  if (shown) {
+    const blocks = blocksOf(components, shown);
+    const deployed = versions.versions(shown.namespace);
+    return (
+      <div className="distributions"
+           data-test-id="distributions"
+           data-opened={shown.namespace}>
+        <div className="distributions__header">
+          <button type="button"
+                  className="distributions__back"
+                  data-test-id="distributions-back"
+                  onClick={() => open({ distribution: null, block: null })}>← All tile palettes</button>
+          <div className="distributions__header-main">
+            {shown.iconUrl ? <img className="distributions__icon distributions__icon--large"
+                                  src={shown.iconUrl}
+                                  alt=""
+                                  draggable={false} /> : null}
+            <div>
+              <h1 className="distributions__heading">{shown.title}</h1>
+              {shown.description ? <p className="distributions__lead">{shown.description}</p> : null}
+              <p className="distributions__meta">
+                <span>{`${blocks.length} ${blocks.length === 1 ? 'block' : 'blocks'} · ${shown.namespace}`}</span>
+                {deployed.length > 1 ? (
+                  <select className="distributions__version"
+                          data-test-id="distribution-version"
+                          aria-label={`The version of ${shown.title} to show`}
+                          value={shown.version}
+                          onChange={(e) => open({ distribution: shown.namespace, version: atVersion(e.target.value), block: null })}>
+                    {deployed.map((version, i) => (
+                      <option key={version}
+                              value={version}>
+                        {i === 0 ? `${version} · latest` : version}
+                      </option>
+                    ))}
+                  </select>
+                ) : <span>{shown.version}</span>}
+                {shown.source ? <SourceLink href={shown.source} /> : null}
+              </p>
+              {shown.changes ? (
+                <details className="distributions__changes"
+                         data-test-id="distribution-changes">
+                  <summary>{`What changed in ${shown.version}`}</summary>
+                  <pre>{shown.changes}</pre>
+                </details>
+              ) : null}
+            </div>
+          </div>
+        </div>
+        <div className="distributions__wall">
+          {blocks.map((c) => (
+            <SpecimenCard key={c.id}
+                          component={c}
+                          libraryRoot={libraryRootOf(shown)}
+                          onOpen={() => open({ distribution: shown.namespace, version: atVersion(shown.version), block: c.reference.name })} />
+          ))}
+        </div>
+      </div>
+    );
+  }
+  return (
+    <div className="distributions"
+         data-test-id="distributions">
+      <div className="distributions__header">
+        <h1 className="distributions__heading">Tile palettes</h1>
+        <p className="distributions__lead">Where this site's blocks come from — open one to see its blocks.</p>
+      </div>
+      <div className="distributions__cards">
+        {distributions.map((d) => (
+          <DistributionCard key={d.id}
+                            distribution={d}
+                            blocks={blocksOf(components, d).length}
+                            onOpen={() => open({ distribution: d.namespace, block: null })} />
+        ))}
+      </div>
+    </div>
+  );
+}

package/tiles/content/editingAutosave.ts

@@ -0,0 +1,125 @@
+// Keeping the DRAFT ON DISK close to the session — a service of the workbench, not of a panel.
+//
+// It used to be an effect inside the tree panel, which made persistence a property of a piece of
+// UI: closing that tab took the layout's panel out of the tree, unmounted the module, and the
+// draft quietly stopped being written. The session is shared through DI precisely because it
+// belongs to no panel — whoever renders first brings it into being and everyone else pokes at it —
+// and what keeps it on disk belongs at the same level.
+//
+// Written against the DI surface of server actions rather than the react hook: a mutation handle
+// (`createManual`) is a plain subscribe/snapshot pair, and cache invalidation rides along exactly
+// as it does for a panel's own mutation.
+import { DiContainer, SingleDiToken } from '@mosetta/di';
+import { ContentKind, EditingSession, IPageDoc } from '@mosetta/content';
+import { fullServerTileId } from '@mosetta/server-action/core';
+import {
+  ensureServerActionClient,
+  IServerDataHandle,
+  SERVER_DATA_MANAGER,
+} from '@mosetta/server-action/client';
+import type { ITileReference } from '@mosetta/core';
+import { ContentActionResult, savePageDraftToken } from './contentCommon';
+
+/** how long the session has to stay still before the draft is worth writing */
+const LULL_MS = 1000;
+
+type TSaveInput = { name: string; draftId: string; page: IPageDoc; kind?: ContentKind };
+type TSaveOutput = ContentActionResult<{ warnings: string[] }>;
+
+export class EditingAutosave {
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  /** the document the request in flight is carrying — only IT can be called saved when it lands */
+  private sent: IPageDoc | null = null;
+
+  /** the seq the in-flight write was stamped with — what the session's chain advances to */
+  private sentSeq = 0;
+
+  /**
+   * The SESSION the in-flight write belongs to, captured as its bound settle pair. The service
+   * holds the hub's ACTIVE facade, which routes at property-access time — so a canvas switch
+   * while the request is in the air must not land the answer (and the seq advance) in the other
+   * canvas's session.
+   */
+  private sentSettle: { markSaved: EditingSession['markSaved']; markSaveFailed: EditingSession['markSaveFailed'] } | null = null;
+
+  constructor(
+    private readonly session: EditingSession,
+    private readonly handle: IServerDataHandle<TSaveOutput, TSaveInput>,
+  ) {
+    this.session.subscribe(this.onSessionChanged);
+    this.handle.subscribe(this.onSaveSettled);
+  }
+
+  /**
+   * Every change re-arms the timer, so a burst of keystrokes costs ONE write, a second after the
+   * last of them. A save already in flight is left alone: whatever came after it keeps the session
+   * dirty, and the landing re-arms.
+   */
+  private readonly onSessionChanged = (): void => {
+    const state = this.session.snapshot();
+    if (!state.dirty || !state.doc || this.sent) return;
+    // a broken write chain (someone else saved this draft) cannot be retried into submission —
+    // saving stays parked until the conflict is resolved (fork or rollback re-opens the page)
+    if (state.saveFailure === 'CONFLICT') return;
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = setTimeout(this.save, LULL_MS);
+  };
+
+  private readonly save = (): void => {
+    this.timer = null;
+    const { doc, kind, pageName, draftId, seq, dirty } = this.session.snapshot();
+    if (!dirty || !doc || pageName === null || draftId === null) return;
+    this.sent = doc;
+    // the wire copy carries the NEXT link of the draft's write chain; the working doc itself is
+    // untouched (its identity is how markSaved knows what landed). A refused chain = CONFLICT.
+    this.sentSeq = seq + 1;
+    // capturing the bound pair NOW pins the answer to the session that sent the request
+    this.sentSettle = {
+      markSaved: this.session.markSaved.bind(this.session),
+      markSaveFailed: this.session.markSaveFailed.bind(this.session),
+    };
+    this.handle.snapshot().start!({ name: pageName, draftId, page: { ...doc, seq: this.sentSeq }, kind });
+  };
+
+  private readonly onSaveSettled = (): void => {
+    const data = this.handle.snapshot();
+    if (data.isLoading() || !this.sent || !this.sentSettle) return;
+    const sent = this.sent;
+    const settle = this.sentSettle;
+    this.sent = null;
+    this.sentSettle = null;
+    if (data.isError()) settle.markSaveFailed(data.serverError.code);
+    else if (data.isSuccess() && !data.serverData.ok) settle.markSaveFailed(data.serverData.code);
+    // …and only the document that was actually written counts as saved: the session may well have
+    // moved on while the request was in the air
+    else if (data.isSuccess()) settle.markSaved(sent, this.sentSeq);
+    // whatever the session holds now is either newer than what landed or was never written —
+    // either way the next write is scheduled by the same rule as any other change
+    this.onSessionChanged();
+  };
+}
+
+export const EDITING_AUTOSAVE_TOKEN = new SingleDiToken<EditingAutosave>('EDITING_AUTOSAVE_TOKEN');
+
+/**
+ * Bring the autosave into being on first use, the way the session itself is brought into being:
+ * any widget that touches the session arms it, and none of them owns it. `reference` is the
+ * caller's own module name — the namespace and version of the server module live there, which is
+ * the one thing about a server action that a container cannot know by itself.
+ */
+export function ensureEditingAutosave(di: DiContainer, session: EditingSession, reference: ITileReference): void {
+  if (di.hasByToken(EDITING_AUTOSAVE_TOKEN)) return;
+  ensureServerActionClient(di);
+  const manager = di.getByToken(SERVER_DATA_MANAGER);
+  const handle = manager.createManual<TSaveInput, TSaveOutput>({
+    fullId: fullServerTileId({
+      namespace: reference.namespace,
+      version: reference.version,
+      name: savePageDraftToken.serverModuleName ?? reference.name,
+    }),
+    actionName: savePageDraftToken.actionName,
+    invalidates: savePageDraftToken.invalidates ?? [],
+  });
+  di.registerValueOfToken(EDITING_AUTOSAVE_TOKEN, new EditingAutosave(session, handle));
+}

package/tiles/content/editingClipboard.ts

@@ -0,0 +1,185 @@
+// Copy/paste of tree structure THROUGH THE OS CLIPBOARD — which is what makes it work between
+// tabs (and between pages): what travels is a text/plain JSON envelope with a marker, so a paste
+// recognises its own kind and leaves anybody else's text alone.
+//
+// Two doors, one meaning. The keyboard goes through the NATIVE copy/paste events — their
+// clipboardData is synchronous and needs no permission; the toolbar buttons cannot raise those,
+// so they go through navigator.clipboard (see canvas). Both end in the same session methods:
+// copySelection() builds the picked forest, pasteNodes() inserts it as ONE undoable step.
+//
+// A service of the workbench, brought into being the way the session, the autosave and the
+// hotkeys are — and armed only in the real workbench (a palette specimen shares the window).
+import { DiContainer, SingleDiToken } from '@mosetta/di';
+import { CANONICAL_REFERENCE_RE, EditingSession, IBlueprintNodeDoc } from '@mosetta/content';
+import { PREVIEW_TYPE_TOKEN } from '@mosetta/runtime/client';
+import { fieldOwnsEvent } from './editingHotkeys';
+import { blocksLabel, EditingNotices, noticesOf } from './editingNotices';
+import { vocabularyFromDoc, vocabularyOf } from './blockVocabulary';
+import { blocksFromText, hasText } from './pasteText';
+import { isVariantSource } from './blockVariants';
+
+const CLIPBOARD_MARK = 'mosetta:blocks';
+
+/** guards against depth bombs — ours AND every recursive walk downstream of a paste */
+const MAX_BLOCK_DEPTH = 64;
+
+/** …and against sheer size: nobody pastes two thousand blocks on purpose */
+const MAX_BLOCK_NODES = 2000;
+
+/** settings keys that would land as magic properties in naive consumers — never let them in */
+const POISON_KEYS = ['__proto__', 'constructor', 'prototype'];
+
+export function serializeBlocks(blocks: readonly IBlueprintNodeDoc[]): string {
+  return JSON.stringify({ mosetta: CLIPBOARD_MARK, version: 1, blocks });
+}
+
+/**
+ * Rebuild one arriving node from its KNOWN fields alone, or refuse it. The clipboard is a TRUST
+ * BOUNDARY — any program can write it, and the marker only says "shaped like ours", not "sane".
+ * The invariant this enforces: whatever a paste admits must also pass the server's zod on the
+ * next autosave — a paste that bricks the saving of the draft is worse than no paste at all.
+ * So: canonical reference, typed fields, junk keys dropped, depth and node budgets enforced.
+ */
+function sanitizeNode(node: unknown, depth: number, budget: { left: number }): IBlueprintNodeDoc | null {
+  if (depth > MAX_BLOCK_DEPTH || budget.left <= 0) return null;
+  budget.left -= 1;
+  if (typeof node !== 'object' || node === null || Array.isArray(node)) return null;
+  const shape = node as {
+    id?: unknown; reference?: unknown; children?: unknown;
+    slot?: unknown; settings?: unknown; ssr?: unknown;
+  };
+  if (typeof shape.id !== 'string' || !shape.id) return null;
+  if (typeof shape.reference !== 'string' || !CANONICAL_REFERENCE_RE.test(shape.reference)) return null;
+  if (!Array.isArray(shape.children)) return null;
+  if (shape.slot !== undefined && (typeof shape.slot !== 'string' || !shape.slot)) return null;
+  if (shape.settings !== undefined
+    && (typeof shape.settings !== 'object' || shape.settings === null || Array.isArray(shape.settings))) return null;
+  if (shape.ssr !== undefined && typeof shape.ssr !== 'boolean') return null;
+  const children: IBlueprintNodeDoc[] = [];
+  for (const child of shape.children) {
+    const clean = sanitizeNode(child, depth + 1, budget);
+    if (!clean) return null;
+    children.push(clean);
+  }
+  const settings = shape.settings === undefined
+    ? undefined
+    : Object.fromEntries(Object.entries(shape.settings).filter(([key]) => !POISON_KEYS.includes(key)));
+  return {
+    id: shape.id,
+    reference: shape.reference,
+    children,
+    ...(shape.slot !== undefined ? { slot: shape.slot } : {}),
+    ...(settings !== undefined ? { settings } : {}),
+    ...(shape.ssr !== undefined ? { ssr: shape.ssr } : {}),
+  };
+}
+
+/**
+ * The blocks inside a clipboard text, or null for anything that is not our envelope — or IS our
+ * envelope with anything rotten inside: one bad node refuses the whole paste (all or nothing;
+ * half a structure appearing on the page would be the confusing outcome).
+ */
+export function parseBlocks(text: string): IBlueprintNodeDoc[] | null {
+  try {
+    const envelope = JSON.parse(text) as { mosetta?: unknown; blocks?: unknown };
+    if (envelope?.mosetta !== CLIPBOARD_MARK || !Array.isArray(envelope.blocks) || !envelope.blocks.length) {
+      return null;
+    }
+    const budget = { left: MAX_BLOCK_NODES };
+    const blocks: IBlueprintNodeDoc[] = [];
+    for (const raw of envelope.blocks) {
+      const clean = sanitizeNode(raw, 1, budget);
+      if (!clean) return null;
+      blocks.push(clean);
+    }
+    return blocks;
+  } catch {
+    return null;
+  }
+}
+
+export class EditingClipboard {
+  constructor(
+    private readonly session: EditingSession,
+    private readonly notices: EditingNotices | null,
+    private readonly di: DiContainer | null = null,
+  ) {
+    window.addEventListener('copy', this.onCopy);
+    window.addEventListener('cut', this.onCut);
+    window.addEventListener('paste', this.onPaste);
+  }
+
+  /** nothing of ours to copy → the native copy proceeds untouched (text selection stays usable) */
+  private readonly onCopy = (event: ClipboardEvent): void => {
+    if (fieldOwnsEvent(event.target)) return;
+    const blocks = this.session.copySelection();
+    if (!blocks.length || !event.clipboardData) return;
+    event.preventDefault();
+    event.clipboardData.setData('text/plain', serializeBlocks(blocks));
+    this.notices?.show('copy', blocksLabel('Copied', blocks.length));
+  };
+
+  /** a cut is the same envelope — written FIRST, then the picked regions leave the page whole */
+  private readonly onCut = (event: ClipboardEvent): void => {
+    if (fieldOwnsEvent(event.target)) return;
+    const blocks = this.session.copySelection();
+    if (!blocks.length || !event.clipboardData) return;
+    event.preventDefault();
+    event.clipboardData.setData('text/plain', serializeBlocks(blocks));
+    this.session.removeSelection();
+    this.notices?.show('cut', blocksLabel('Cut', blocks.length));
+  };
+
+  /**
+   * Two kinds of paste, one door: our envelope lands as the blocks it carries; any other TEXT
+   * becomes blocks by the writing splitter (paragraphs, headings, lists, quotes) — the way an
+   * article written elsewhere enters the page. A field keeps its own paste (text goes INTO it).
+   */
+  private readonly onPaste = (event: ClipboardEvent): void => {
+    if (fieldOwnsEvent(event.target)) return;
+    const text = event.clipboardData?.getData('text/plain') ?? '';
+    const blocks = text ? parseBlocks(text) : null;
+    if (blocks) {
+      event.preventDefault();
+      this.session.pasteNodes(blocks);
+      this.notices?.show('paste', blocksLabel('Pasted', blocks.length));
+      return;
+    }
+    if (!hasText(text) || !this.session.snapshot().doc) return;
+    // a block's VARIANT (its page's "Copy as JSON") is for an editor facet, not words for a page:
+    // say where the block itself is copied instead of pasting a paragraph of braces
+    if (isVariantSource(text)) {
+      event.preventDefault();
+      this.notices?.show('refuse', 'That is a block’s variant as JSON, for its .editor.tsx — “Copy block” copies the block itself');
+      return;
+    }
+    const vocab = this.textVocabulary();
+    if (!vocab) {
+      // nothing to build with: say so instead of silently swallowing a paste
+      this.notices?.show('paste', 'Open the Palette once — then text pastes as blocks');
+      return;
+    }
+    const built = blocksFromText(text, vocab);
+    if (!built.length) return;
+    event.preventDefault();
+    this.session.pasteNodes(built);
+    this.notices?.show('paste', `${blocksLabel('Pasted', built.length)} from text`);
+  };
+
+  /** the catalog's word first (the palette registers it), the page's own blocks otherwise */
+  private textVocabulary() {
+    const fromDi = this.di ? vocabularyOf(this.di) : null;
+    if (fromDi) return fromDi;
+    const doc = this.session.snapshot().doc;
+    return doc ? vocabularyFromDoc(doc) : null;
+  }
+}
+
+export const EDITING_CLIPBOARD_TOKEN = new SingleDiToken<EditingClipboard>('EDITING_CLIPBOARD_TOKEN');
+
+export function ensureEditingClipboard(di: DiContainer, session: EditingSession): void {
+  if (typeof window === 'undefined') return; // ssr render has no clipboard to listen for
+  if (di.hasByToken(EDITING_CLIPBOARD_TOKEN)) return;
+  if (di.hasByToken(PREVIEW_TYPE_TOKEN) && di.getByToken(PREVIEW_TYPE_TOKEN) !== null) return;
+  di.registerValueOfToken(EDITING_CLIPBOARD_TOKEN, new EditingClipboard(session, noticesOf(di), di));
+}