@domternal/pm 1.2.0 → 1.3.0

package/README.md

@@ -3,83 +3,53 @@
 [![Version](https://img.shields.io/npm/v/@domternal/pm.svg)](https://www.npmjs.com/package/@domternal/pm)
 [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/domternal/domternal/blob/main/LICENSE)
 
-The ProseMirror dependency layer for the [Domternal](https://domternal.dev) editor. It
-re-exports the underlying `prosemirror-*` libraries under stable `@domternal/pm/*`
-subpaths so every Domternal package imports ProseMirror from one place. Because the
-`prosemirror-*` packages are declared here once, as ordinary dependencies of this package,
-your package manager dedupes them to a single copy across `@domternal/core` and every
-extension. You rarely install it yourself: it ships transitively with `@domternal/core`.
-
-## Links
-
-<u>[Website](https://domternal.dev)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[Documentation](https://domternal.dev/v1/packages)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[Live examples](https://domternal.dev/examples)</u>
+Shared ProseMirror dependencies for [Domternal](https://domternal.dev). Each
+`@domternal/pm/*` subpath re-exports the corresponding `prosemirror-*` package,
+including its TypeScript types. Domternal packages use these entry points to share
+the same ProseMirror classes and plugins.
 
 ## Install
 
-Install it explicitly when you import ProseMirror primitives in your own code, or when a
-strict peer resolver asks for it: every `@domternal/extension-*` package declares
-`@domternal/pm` as a peer dependency with the same minor floor and next-major ceiling as
-`@domternal/core`. For the 1.2.0 release, both ranges remain `>=1.2.0 <2.0.0`;
-upgrade core, pm, and the extensions together to 1.2.0.
+`@domternal/core` already depends on this package. Add it directly when your own
+code imports from `@domternal/pm/*`, or when an extension's peer dependencies
+require it:
 
 ```bash
 pnpm add @domternal/pm
 ```
 
-`@domternal/pm` itself has no peer dependencies: the `prosemirror-*` libraries are its own
-dependencies.
-
-## One copy, always
-
-ProseMirror compares by identity, not by shape. Two copies of `prosemirror-model` make
-`Fragment.from` reject a fragment the editor itself produced ("Can not convert <> to a
-Fragment"), two copies of `prosemirror-state` collide on a keyed plugin. That is a crash,
-not a few extra kilobytes, and nothing warns at install time.
-
-Declaring the libraries here once is what normally prevents it. It stops being enough when
-another library in your app declares the same packages as **peer dependencies** and takes
-whatever your application root offers: `y-prosemirror` is the common case, and the one
-that reaches Domternal Pro's collaboration. The two resolutions can then differ with
-nothing warning at install or build time.
-
-Domternal detects it at runtime and names both packages and the fix. The dedupe recipe per
-package manager and bundler:
-https://domternal.dev/v1/guides/single-prosemirror-copy/
-
-### Why these are dependencies and not peers
-
-Declaring them as peer dependencies would make a second copy impossible, since there would be
-nothing here to bring. It is not worth what it costs: peers are installed automatically by npm 7
-and later, by pnpm and by Bun, but by neither version of Yarn, so every Yarn user would have to
-install twelve ProseMirror packages by hand. An install that fails outright is a worse first day
-than a duplicate that is rare, loud when it happens, and fixed by one block of JSON.
-
-What is done instead: the ranges declared here are checked in CI against those of every library
-that shares ProseMirror with this one, so a release cannot make the two impossible to reconcile,
-and a duplicate that does form is reported by name at runtime.
+The package declares Node.js 22 or later for tooling and has no peer dependencies. Keep installed Domternal packages on the
+same release; the Free 1.3.0 extensions require `@domternal/core` and
+`@domternal/pm` in the range `>=1.3.0 <2.0.0`.
 
 ## Usage
 
-Import from a subpath matching the ProseMirror package you need. Each subpath
-re-exports the full API of its `prosemirror-*` counterpart. There is no root export, so
-`import { Plugin } from '@domternal/pm'` does not resolve.
+Always import a subpath. There is no `@domternal/pm` root export.
 
 ```ts
 import { Plugin, PluginKey } from '@domternal/pm/state';
-import type { EditorView } from '@domternal/pm/view';
 
-const myPlugin = new Plugin({
-  key: new PluginKey('my-plugin'),
-  view: (view: EditorView) => ({ destroy: () => {} }),
+export const documentChangeLogger = new Plugin({
+  key: new PluginKey('documentChangeLogger'),
+  view: () => ({
+    update(view, previousState) {
+      if (!view.state.doc.eq(previousState.doc)) {
+        console.log(view.state.doc.toJSON());
+      }
+    },
+  }),
 });
-
-// Every `@domternal/pm/*` subpath re-exports its `prosemirror-*`
-// counterpart unchanged.
 ```
 
-## Subpaths
+Register a plugin through an extension's `addProseMirrorPlugins()` hook or
+`editor.registerPlugin()`. See [custom extensions](https://domternal.dev/v1/guides/configuration/#add-prosemirror-plugins)
+and [dynamic plugins](https://domternal.dev/v1/guides/editor-api/#dynamic-plugin-management).
+
+## Entry points
+
+Every subpath supports ESM, CommonJS, and TypeScript:
 
-| Subpath | Re-exports |
+| Import | Re-exports |
 | --- | --- |
 | `@domternal/pm/commands` | `prosemirror-commands` |
 | `@domternal/pm/dropcursor` | `prosemirror-dropcursor` |
@@ -93,3 +63,14 @@ const myPlugin = new Plugin({
 | `@domternal/pm/tables` | `prosemirror-tables` |
 | `@domternal/pm/transform` | `prosemirror-transform` |
 | `@domternal/pm/view` | `prosemirror-view` |
+
+## Avoid duplicate ProseMirror copies
+
+ProseMirror compares objects by identity. Loading two copies can cause fragment
+conversion errors, keyed-plugin collisions, and broken selections. Prefer these
+subpaths over direct `prosemirror-*` imports in code that interacts with Domternal.
+
+Other dependencies and linked workspaces can still introduce duplicates.
+The [single-copy guide](https://domternal.dev/v1/guides/single-prosemirror-copy/)
+explains runtime diagnostics and the package-manager and bundler fixes, including
+collaboration integrations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domternal/pm",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "ProseMirror package re-exports for Domternal",
   "author": "https://github.com/ThomasNowHere",
   "license": "MIT",