edytor 1.0.0 → 2.0.0

package/README.md

@@ -17,11 +17,11 @@
 
 Edytor aims to be for Svelte what Slate.js is for React: a heavily customizable editor with an API to build any kind of collaborative rich text editor.
 
-> **1.0.** Edytor `1.0.0` is on npm as `edytor`: its API follows semantic versioning, and every change is listed in the changelog. It has no production track record yet: read the [limitations](https://edytor.dev/docs/reference/limitations) before you build on it. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
+> **2.0.** Edytor `2.0.0` is on npm as `edytor`: its API follows semantic versioning, and every change is listed in the changelog. It has no production track record yet: read the [limitations](https://edytor.dev/docs/reference/limitations) before you build on it. Issues and PRs are welcome: when you report a bug, include the document's JSON value.
 
 ## Features
 
-- **Notion-style editing out of the box.** `<Edytor />` alone is a rich text editor with images and block handles: headings, toggle headings, lists, to-dos, toggles, callouts, quotes, dividers, ten marks and Notion's hotkeys. Add the Notion theme, a block menu (block colours; drag one block, or every block the selection covers), a slash menu, a selection toolbar, markdown shortcuts (`createMarkdownShortcutsPlugin()`) and code blocks.
+- **Notion-style editing out of the box.** `<Edytor />` alone is a rich text editor with block handles: headings, toggle headings, lists, to-dos, toggles, callouts, quotes, dividers, ten marks and Notion's hotkeys. Add the Notion theme, a block menu (block colours; drag one block, or every block the selection covers), a slash menu, a selection toolbar, markdown shortcuts (`createMarkdownShortcutsPlugin()`) code blocks and images (`createImagePlugin({ upload })`).
 - **Pages and a table of contents, opt-in.** `createPagePlugin` links a block to another document (a page per room, opened and named by your app), and `createTocPlugin()` lists the headings live ([Page](https://edytor.dev/docs/plugins/page), [Table of contents](https://edytor.dev/docs/plugins/table-of-contents)).
 - **Columns, opt-in.** List `createColumnsPlugin()` for Notion's multi-column layouts: drag a block to the edge of another to put them side by side, or pick "2 columns" to "5 columns"; drag the gap to resize. Layouts converge across collaborators and the room ([Columns](https://edytor.dev/docs/plugins/columns)).
 - **Tables, opt-in.** List `createTablePlugin()` for Notion's simple table: cells of text, <kbd>Tab</kbd> between them, rows and columns added, moved and deleted from the table's edges and grips, resizable columns, header row and column, HTML tables pasted and copied. Concurrent row and column edits converge on every replica ([Table](https://edytor.dev/docs/plugins/table)).
@@ -29,7 +29,7 @@ Edytor aims to be for Svelte what Slate.js is for React: a heavily customizable
 - **Comments, opt-in.** `createCommentsPlugin` adds Notion's comment threads: select text, press Comment, and the thread shows in a sidebar beside it with replies, Resolve and Re-open. The room keeps the threads beside the document and sends each change live; the anchor follows the text through edits and is not copied ([Comments](https://edytor.dev/docs/plugins/comments)).
 - **Your markup.** Blocks, marks and inline atoms render through your Svelte snippets; the slash menu, toolbar, block menu and handles take a snippet and keep their behavior.
 - **Your language.** Every word the package shows or says, slash keywords included, comes from one labels dictionary the view takes (`<Edytor labels>`); your chrome's words are your markup's; English by default ([Localization](https://edytor.dev/docs/customization/localization)).
-- **Synced properties.** `block.data`, `atom.data` and `edytor.data` read like plain objects, and `edytor.patchData(id, [{ path, value }])` writes them; each property and each array item syncs on its own, so concurrent edits of different properties, or of different items of one array, merge.
+- **Synced properties.** `block.data`, `atom.data` and `edytor.data` are plain Svelte state at any depth (`block.data.meta.author = 'Ada'`, `block.data.tags.push('x')`, `delete block.data.draft`), each write an undoable operation; each property and each array item syncs on its own, so concurrent edits of different properties, or of different items of one array, merge.
 - **AI suggestions.** `edytor.suggestions.add(position, content)` proposes text, paragraphs, lists, to-dos or images after, before or inside a block, at the end of its text, or in place of the selection; it streams in, shows only on your screen, and becomes one undo step when accepted ([Suggestions](https://edytor.dev/docs/editor/suggestions)).
 - **Plugins that can veto anything.** Every command is prepared before it writes; plugins see the command and each planned step and can refuse or replace it.
 - **Real-time collaboration.** One `EdytorDocument` shared by any number of views, or none (headless). Presence cursors, identity-preserving moves, splits and merges, and undo that only takes back your own edits.
@@ -49,83 +49,25 @@ pnpm add edytor
 
 ## Quick start
 
-The package draws no menu, toolbar or block handle: each is a snippet you pass its plugin. Without them the editor works but shows none. The demo's ready-made, Notion-style ones are one copy away: copy [`src/routes/chrome`](https://github.com/beynar/edytor/tree/master/src/routes/chrome) into your app, make its imports name the package, and pass its plugins ([quick start](https://edytor.dev/docs/getting-started/quick-start#the-ready-made-menus-and-handles)):
-
-```bash
-npx degit beynar/edytor/src/routes/chrome src/lib/chrome
-sed -i.bak 's#\$lib/index\.js#edytor#' src/lib/chrome/*.ts src/lib/chrome/*.svelte && rm src/lib/chrome/*.bak
-```
-
-Take the folder of the version you install, by its tag (`beynar/edytor/src/routes/chrome#v1.0.0`): without one you get `master`'s, which follows the next release.
-
 ```svelte
 <script lang="ts">
-	import { Edytor } from 'edytor';
-	import 'edytor/themes/notion.css';
-	import {
-		slashMenuPlugin,
-		toolbarPlugin,
-		blockHandlesPlugin,
-		blockMenuPlugin,
-		codePlugin
-	} from '$lib/chrome/plugins';
-</script>
-
-<div class="edytor-notion">
-	<Edytor
-		plugins={[slashMenuPlugin, toolbarPlugin, blockHandlesPlugin, blockMenuPlugin, codePlugin]}
-	/>
-</div>
-```
-
-Or draw a menu yourself: your snippet draws it, the plugin gives it its keys and ARIA.
+	import { Edytor, createCodePlugin, type JSONDoc } from 'edytor';
 
-```svelte
-<script lang="ts">
-	import {
-		Edytor,
-		createCodePlugin,
-		createSlashMenuPlugin,
-		createMarkdownShortcutsPlugin,
-		richTextPlaceholder,
-		type JSONDoc,
-		type SlashMenuController
-	} from 'edytor';
-	import 'edytor/themes/notion.css';
-
-	const value: JSONDoc = {
+	let value = $state<JSONDoc>({
 		children: [{ type: 'paragraph', content: [{ text: 'Hello, World!' }] }]
-	};
-	const plugins = [
-		// Notion's hints in empty blocks.
-		() => ({ placeholder: richTextPlaceholder }),
-		createCodePlugin(),
-		createMarkdownShortcutsPlugin(),
-		createSlashMenuPlugin({ menu })
-	];
+	});
 </script>
 
-<!-- Your snippet draws the menu; the plugin's attachments give it its keys and ARIA. -->
-{#snippet menu(slash: SlashMenuController)}
-	<ul {@attach slash.popup}>
-		{#each slash.commands as command, index (command.id)}
-			<li
-				data-selected={slash.index === index}
-				{@attach slash.option(index)}
-				onclick={() => void slash.run(command)}
-			>
-				{command.label}
-			</li>
-		{/each}
-	</ul>
-{/snippet}
-
-<div class="edytor-notion">
-	<Edytor {value} {plugins} onChange={(root) => console.log(root)} />
-</div>
+<Edytor {value} plugins={[createCodePlugin()]} onChange={(next) => (value = next)} />
+
+<p>{value.children?.length ?? 0} blocks</p>
 ```
 
-An editable editor is client-only: in SvelteKit, mount it once the page has hydrated ([quick start](https://edytor.dev/docs/getting-started/quick-start#mount-it-in-a-page)). `<Edytor>` adds the rich text, image, arrow-move and suggestions plugins after yours. Every menu, toolbar, handle and panel is drawn by a snippet, yours or the demo's ([menus and handles](https://edytor.dev/docs/customization/menus)). To collaborate, name a room and a server running the [`edytor/cloudflare` room](https://edytor.dev/docs/server/quick-start):
+`<Edytor>` renders on the server and hydrates, so it works in any route. It includes rich text; each other block kind, block moves from the keyboard (`createArrowMovePlugin()`), and file drops (a media plugin given an `upload`) is a plugin you add, here code blocks; nesting blocks (<kbd>Tab</kbd>, drops inside a block) is the `allowNesting` option, off by default. `onChange` hands you the document after every change ([quick start](https://edytor.dev/docs/getting-started/quick-start)).
+
+The package draws no menu, toolbar or block handle: each is a snippet you pass its plugin ([menus and handles](https://edytor.dev/docs/customization/menus)). The demo's Notion-style ones are in [`src/routes/chrome`](https://github.com/beynar/edytor/tree/master/src/routes/chrome), ready to copy into your app ([ready-made menus](https://edytor.dev/docs/customization/ready-made-menus)).
+
+To collaborate, name a room and a server running the [`edytor/cloudflare` room](https://edytor.dev/docs/server/quick-start):
 
 ```svelte
 <Edytor

package/dist/block/block.svelte.d.ts

@@ -31,11 +31,13 @@ export declare class Block {
     get content(): (Text | InlineBlock)[];
     get type(): string;
     /**
-     * The block's `data`, read-your-writes; a reactive reader depends on the
-     * block's cell. The root's is the document's data (`edytor.data`). Write
-     * it with `edytor.patchData(block.id, patches)`.
+     * The block's `data` as plain state: reactive at any depth (through the
+     * block's cell), and writable (`block.data.color = 'red'`,
+     * `block.data.tags.push('x')`, `delete block.data.color`). Each write is
+     * the `patchData` operation, dispatched (`session/props`). The root's is
+     * the document's data (`edytor.data`).
      */
-    get data(): Readonly<Record<string, any>>;
+    get data(): Record<string, any>;
     get definition(): BlockDefinition;
     get selected(): boolean;
     get focused(): boolean;

package/dist/block/block.svelte.js

@@ -76,14 +76,20 @@ export class Block {
         return this.edytor.facade.blockTypeOf(this.id) ?? '';
     }
     #data;
+    #props;
     /**
-     * The block's `data`, read-your-writes; a reactive reader depends on the
-     * block's cell. The root's is the document's data (`edytor.data`). Write
-     * it with `edytor.patchData(block.id, patches)`.
+     * The block's `data` as plain state: reactive at any depth (through the
+     * block's cell), and writable (`block.data.color = 'red'`,
+     * `block.data.tags.push('x')`, `delete block.data.color`). Each write is
+     * the `patchData` operation, dispatched (`session/props`). The root's is
+     * the document's data (`edytor.data`).
      */
     get data() {
         if (this.isRoot)
-            return this.edytor.docData();
+            return this.edytor.data;
+        return (this.#props ??= this.edytor.dataWrites.proxy(this.id, () => this.#current()));
+    }
+    #current() {
         const { facade, cells } = this.edytor;
         cells?.get(this.id);
         const version = facade.version;

package/dist/block/inlineBlock.svelte.d.ts

@@ -22,8 +22,12 @@ export declare class InlineBlock {
     get parent(): Block;
     get selected(): boolean;
     get type(): string;
-    /** The atom's `data`; a reactive reader depends on its block's cell. */
-    get data(): Readonly<Record<string, any>>;
+    /**
+     * The atom's `data` as plain state: reactive at any depth (through its
+     * block's cell), and writable; each write is its `patchData` operation
+     * (`session/props`).
+     */
+    get data(): Record<string, any>;
     get definition(): InlineBlockDefinition;
     /** Position among the block's content parts. */
     get index(): number;

package/dist/block/inlineBlock.svelte.js

@@ -37,9 +37,14 @@ export class InlineBlock {
     get type() {
         return this.#item?.type ?? '';
     }
-    /** The atom's `data`; a reactive reader depends on its block's cell. */
+    #props;
+    /**
+     * The atom's `data` as plain state: reactive at any depth (through its
+     * block's cell), and writable; each write is its `patchData` operation
+     * (`session/props`).
+     */
     get data() {
-        return this.#item?.data ?? {};
+        return (this.#props ??= this.edytor.dataWrites.proxy({ block: this.blockId, atom: this.id }, () => this.#item?.data ?? {}));
     }
     get definition() {
         return this.edytor.inlineBlocks.get(this.type) ?? {};

package/dist/cloudflare/room/context.d.ts

@@ -233,6 +233,12 @@ export declare const crdt: {
             blockDataOf: (id: string) => Record<string, unknown> | undefined;
             docData: () => import("../../crdt/doc/types.js").JsonObj;
             dataItemIds: (target: import("../../index.js").DataTarget, path: readonly string[]) => string[];
+            dataPreview: (target: import("../../index.js").DataTarget, pending: readonly import("../../index.js").DataPatch[]) => {
+                data: {
+                    [x: string]: unknown;
+                };
+                ids: (path: readonly string[]) => string[];
+            } | null;
             blockAttribution: (id: string) => import("../../index.js").BlockAttribution | undefined;
             crdtId: (id: string) => string | null;
             resolveBlock: (id: string) => E.EngineNode | null;

package/dist/collaboration/awarenessSelection.d.ts

@@ -56,6 +56,20 @@ export type AwarenessLike = {
     getLocalState: () => Record<string, unknown> | null;
     setLocalState: (state: Record<string, unknown> | null) => void;
 };
+/**
+ * The awareness a view's presence writer reads and writes: its own state,
+ * every client's state, and the `change` event (the real `Awareness`).
+ */
+export type PresenceSource = AwarenessLike & {
+    clientID: number;
+    getStates: () => Map<number, Record<string, unknown>>;
+    on: (name: 'change', listener: () => void) => void;
+    off: (name: 'change', listener: () => void) => void;
+};
+/** Another person online: their client id and the fields of their `user` state (`name`, `color`, …), the document's actor name and colour when `user` has none. */
+export type PresencePeer = EdytorAwarenessUser & Record<string, unknown> & {
+    clientId: number;
+};
 /** A client-local presence key, minted once by the view that owns the entry. */
 export declare const mintPresenceKey: () => string;
 /**
@@ -90,9 +104,16 @@ export declare class PresenceWriter {
     private readonly awareness;
     private readonly key;
     throttle: number;
-    constructor(awareness: AwarenessLike, key: string, { share, throttle }?: PresenceOptions);
+    constructor(awareness: PresenceSource, key: string, { share, throttle }?: PresenceOptions);
     get share(): PresenceShare;
     set share(share: PresenceShare);
+    /**
+     * The other people online: every client but this one, by client id,
+     * each `{ clientId, name?, color?, …user }`. Reactive: read in markup or
+     * an effect, it updates when someone joins, leaves or changes their
+     * state; the awareness listener exists only while something reads it.
+     */
+    get peers(): PresencePeer[];
     /** Publish `payload` (the full selection; `focus`: the block holding its focus) as this view shares it, within the throttle. */
     write(payload: PresenceSelection | null, focus?: string | null): void;
     /** Remove this view's entry and drop a held write (the view's teardown). */

package/dist/collaboration/awarenessSelection.js

@@ -1,4 +1,19 @@
 import { isRecord, jsonEquals } from '../utils/json.js';
+import { createSubscriber } from 'svelte/reactivity';
+/** Every client but this one, by client id. */
+const readPeers = (awareness) => [...awareness.getStates()]
+    .filter(([clientId]) => clientId !== awareness.clientID)
+    .sort(([a], [b]) => a - b)
+    .map(([clientId, state]) => {
+    const actor = isRecord(state.actor) ? state.actor : {};
+    const user = isRecord(state.user) ? state.user : {};
+    const peer = { ...user, clientId };
+    if (peer.name === undefined && typeof actor.name === 'string')
+        peer.name = actor.name;
+    if (peer.color === undefined && typeof actor.color === 'string')
+        peer.color = actor.color;
+    return peer;
+});
 let presenceKeys = 0;
 /** A client-local presence key, minted once by the view that owns the entry. */
 export const mintPresenceKey = () => `view-${++presenceKeys}`;
@@ -50,6 +65,21 @@ export class PresenceWriter {
     #held;
     /** The last payload and focused block handed in, kept so a share change republishes at once. */
     #latest = [null, null];
+    /** The peers while someone reads them reactively (`undefined`: recompute). */
+    #peers;
+    #watched = false;
+    #subscribe = createSubscriber((update) => {
+        const changed = () => {
+            this.#peers = undefined;
+            update();
+        };
+        this.#watched = true;
+        this.awareness.on('change', changed);
+        return () => {
+            this.awareness.off('change', changed);
+            [this.#watched, this.#peers] = [false, undefined];
+        };
+    });
     constructor(awareness, key, { share = 'caret', throttle = DEFAULT_PRESENCE_THROTTLE } = {}) {
         this.awareness = awareness;
         this.key = key;
@@ -65,6 +95,18 @@ export class PresenceWriter {
         this.#share = share;
         this.write(...this.#latest);
     }
+    /**
+     * The other people online: every client but this one, by client id,
+     * each `{ clientId, name?, color?, …user }`. Reactive: read in markup or
+     * an effect, it updates when someone joins, leaves or changes their
+     * state; the awareness listener exists only while something reads it.
+     */
+    get peers() {
+        this.#subscribe();
+        if (!this.#watched)
+            return readPeers(this.awareness);
+        return (this.#peers ??= readPeers(this.awareness));
+    }
     /** Publish `payload` (the full selection; `focus`: the block holding its focus) as this view shares it, within the throttle. */
     write(payload, focus = null) {
         this.#latest = [payload, focus];

package/dist/components/Block.svelte

@@ -35,7 +35,9 @@
 	const previewViewOf = (cell: PreviewCell): BlockView => ({
 		id: cell.id,
 		type: cell.type,
-		data: cell.data ?? {},
+		get data() {
+			return structuredClone(cell.data ?? {});
+		},
 		selected: false,
 		focused: false,
 		handle: undefined,

package/dist/components/Edytor.svelte

@@ -23,21 +23,15 @@
 	import { brandOf } from '../plugins/brand.js';
 	import type { PartialLabels } from '../labels.js';
 	import { createRichTextPlugin } from '../plugins/richtext/RichTextPlugin.svelte';
-	import { createArrowMovePlugin } from '../plugins/arrowMove/arrowMove.js';
-	import { createImagePlugin } from '../plugins/image/ImagePlugin.svelte';
 	import { createSuggestionsPlugin } from '../plugins/suggestions/suggestionsPlugin.js';
 
 	/**
 	 * The plugins every view has unless it lists one of their kind (or sets
 	 * `defaultPlugins={false}`), after the app's so its kinds and keys win:
-	 * block moves, the suggestion UI, the image kind, then rich text.
+	 * the suggestion UI, then rich text (an app lists `createArrowMovePlugin()`
+	 * for block moves and `createImagePlugin({ upload })` for images itself).
 	 */
-	const DEFAULTS = [
-		createArrowMovePlugin(),
-		createSuggestionsPlugin(),
-		createImagePlugin(),
-		createRichTextPlugin()
-	];
+	const DEFAULTS = [createSuggestionsPlugin(), createRichTextPlugin()];
 	const withDefaults = (plugins: Plugin[] = []): Plugin[] => {
 		const listed = new Set(plugins.map(brandOf));
 		return [...plugins, ...DEFAULTS.filter((plugin) => !listed.has(brandOf(plugin)))];
@@ -67,7 +61,7 @@
 
 	export type EdytorProps = {
 		plugins?: Plugin[];
-		/** Add rich text, arrow moves, the suggestion UI and images unless `plugins` lists them (default `true`). */
+		/** Add rich text and the suggestion UI unless `plugins` lists them (default `true`). */
 		defaultPlugins?: boolean;
 		class?: string;
 		/** The root textbox's accessible name (or name it with `aria-labelledby`). */
@@ -96,6 +90,13 @@
 		 * the connection.
 		 */
 		readonly?: boolean;
+		/**
+		 * Let users nest blocks (default `false`): Tab and Shift+Tab nest and
+		 * unnest, drops and handle keys may place a block inside another. Off,
+		 * Tab is left to the browser and no gesture nests; containers keep their
+		 * bodies. Read once.
+		 */
+		allowNesting?: boolean;
 		/** Chords (`mod+s`, `shift+alt+enter`) the view binds before plugins and built-ins. Read once. */
 		hotkeys?: Partial<Record<HotKeyCombination, HotKey>>;
 		/** After every commit that changed the visible document: a `JSONDoc`, the type `value` takes. */
@@ -188,6 +189,7 @@
 		document: edytorDocument,
 		doc,
 		readonly = false,
+		allowNesting = false,
 		value = defaultValue,
 		hotkeys,
 		sync,
@@ -216,6 +218,7 @@
 
 	const initialEdytorOptions = untrack(() => ({
 		readonly,
+		allowNesting,
 		plugins: defaultPlugins ? withDefaults(userPlugins) : userPlugins,
 		document: edytorDocument,
 		doc,
@@ -408,6 +411,29 @@
 {/if}
 
 <style>
+	/* Where a drag lands, a block handle's or files' from outside (`DropIndicator`):
+	 * the bar (4px) and the nest backdrop, placed in the overlay and shown
+	 * (`data-shown`) by the drag; their look is a theme's (`edytor/themes/notion.css`). */
+	:global([data-edytor-drop-indicator]),
+	:global([data-edytor-drop-backdrop]) {
+		position: absolute;
+		pointer-events: none;
+	}
+
+	:global([data-edytor-drop-indicator]) {
+		z-index: 100;
+		box-sizing: border-box;
+		height: 4px;
+	}
+
+	:global([data-edytor-drop-backdrop]) {
+		z-index: 99;
+	}
+
+	:global([data-edytor-drop-backdrop]:not([data-shown='true'])) {
+		visibility: hidden;
+	}
+
 	/*
 	 * Room below the last block, where a press puts the caret in a trailing
 	 * paragraph (`nav.trailing.press`): `--edytor-trailing-space`. No

package/dist/components/Edytor.svelte.d.ts

@@ -7,7 +7,7 @@ import type { Plugin } from '../plugins.js';
 import type { PartialLabels } from '../labels.js';
 export type EdytorProps = {
     plugins?: Plugin[];
-    /** Add rich text, arrow moves, the suggestion UI and images unless `plugins` lists them (default `true`). */
+    /** Add rich text and the suggestion UI unless `plugins` lists them (default `true`). */
     defaultPlugins?: boolean;
     class?: string;
     /** The root textbox's accessible name (or name it with `aria-labelledby`). */
@@ -36,6 +36,13 @@ export type EdytorProps = {
      * the connection.
      */
     readonly?: boolean;
+    /**
+     * Let users nest blocks (default `false`): Tab and Shift+Tab nest and
+     * unnest, drops and handle keys may place a block inside another. Off,
+     * Tab is left to the browser and no gesture nests; containers keep their
+     * bodies. Read once.
+     */
+    allowNesting?: boolean;
     /** Chords (`mod+s`, `shift+alt+enter`) the view binds before plugins and built-ins. Read once. */
     hotkeys?: Partial<Record<HotKeyCombination, HotKey>>;
     /** After every commit that changed the visible document: a `JSONDoc`, the type `value` takes. */

package/dist/components/InlineBlock.svelte

@@ -28,7 +28,7 @@
 			return part.type;
 		},
 		get data() {
-			return block ? block.data : (part.data ?? {});
+			return block ? block.data : structuredClone(part.data ?? {});
 		},
 		get selected() {
 			return block?.selected ?? false;

package/dist/crdt/data.d.ts

@@ -73,6 +73,16 @@ export declare const readData: (node: EngineNode) => JsonObj | undefined;
  * in `node`'s data, in order; `[]` where no array is.
  */
 export declare const itemIds: (node: EngineNode, path: readonly string[]) => string[];
+/**
+ * `node`'s data as it reads once `patches` are applied (nothing written),
+ * with the ids of the array items at a path (`itemIds`): an item a patch
+ * makes has no id yet (`''`), so a later patch names it by index.
+ * `null` when a patch fits no value.
+ */
+export declare const previewData: (node: EngineNode | undefined, patches: readonly DataPatch[]) => {
+    data: JsonObj;
+    ids: (path: readonly string[]) => string[];
+} | null;
 /** `data` with `patches` applied in order, as a fresh value (a root patch replaces it); `null` when one fits no value. */
 export declare const applyPatch: (data: JsonObj, patches: readonly DataPatch[]) => JsonObj | null;
 /**

package/dist/crdt/data.js

@@ -354,8 +354,9 @@ export const readData = (node) => valueOf(treeOf(leavesOf(node)));
  * The ids of the items of the array at `path` (keys, item indexes or ids)
  * in `node`'s data, in order; `[]` where no array is.
  */
-export const itemIds = (node, path) => {
-    let t = treeOf(leavesOf(node));
+export const itemIds = (node, path) => idsAt(treeOf(leavesOf(node)), path);
+const idsAt = (root, path) => {
+    let t = root;
     for (const k of path)
         if (t && isArr(open(t))) {
             const item = itemAt(itemsOf(t), k);
@@ -365,6 +366,23 @@ export const itemIds = (node, path) => {
             t = itemish(k) ? undefined : t?.k.get(enc(segmentKey(k)));
     return t ? itemsOf(open(t)).map(({ id }) => id) : [];
 };
+/**
+ * `node`'s data as it reads once `patches` are applied (nothing written),
+ * with the ids of the array items at a path (`itemIds`): an item a patch
+ * makes has no id yet (`''`), so a later patch names it by index.
+ * `null` when a patch fits no value.
+ */
+export const previewData = (node, patches) => {
+    const base = node ? leavesOf(node) : new Map();
+    const root = treeOf(base);
+    if (!patches.every((p) => edits().apply(root, p)))
+        return null;
+    const known = new Set([...base.keys()].flatMap((key) => key.split('/')));
+    return {
+        data: valueOf(root) ?? {},
+        ids: (path) => idsAt(root, path).map((id) => (known.has(`${id}#`) ? id : ''))
+    };
+};
 /** `data` with `patches` applied in order, as a fresh value (a root patch replaces it); `null` when one fits no value. */
 export const applyPatch = (data, patches) => {
     const root = treeOf(dataLeaves(data));

package/dist/crdt/doc/reads.d.ts

@@ -1,6 +1,7 @@
 import type { EngineApi, EngineDoc, EngineNode } from '../engine-api.js';
 import { type BlockId, type ContentItem, type Destination, type ModelView } from '../placement/model.js';
 import type { DisplayRoles, RunView } from '../text/runs.js';
+import { type DataPatch } from '../data.js';
 import { type JSONBlock } from '../../utils/json.js';
 import type { BlockRole, DataTarget, JsonObj, OrderPolicy } from './types.js';
 /** What every part of a document facade is built over: one doc, its engine layers, its index and its roles. */
@@ -25,6 +26,12 @@ export declare const docReads: (c: DocBase) => {
     blockDataOf: (id: BlockId) => Record<string, unknown> | undefined;
     docData: () => JsonObj;
     dataItemIds: (target: DataTarget, path: readonly string[]) => string[];
+    dataPreview: (target: DataTarget, pending: readonly DataPatch[]) => {
+        data: {
+            [x: string]: unknown;
+        };
+        ids: (path: readonly string[]) => string[];
+    } | null;
     childrenIds: (parent: BlockId | null) => BlockId[];
     positionOf: (id: BlockId) => Destination | null;
     pathOf: (id: BlockId) => number[] | null;

package/dist/crdt/doc/reads.js

@@ -9,7 +9,7 @@ import { DOC_DATA_ROOT, TYPE } from '../schema.js';
 import { blockNodeOf, displayParentOf, displaySlotOf, isLive, isLiveIn, positionInView, positionOf as modelPositionOf } from '../placement/model.js';
 import { DEAD, findAtom, ownedLength } from '../text/model.js';
 import { holdsPending } from '../structs.js';
-import { itemIds, readData } from '../data.js';
+import { itemIds, previewData, readData } from '../data.js';
 import { columnIds, listedColumns, unlistedOrder } from '../tables.js';
 import { cloneJsonSafe } from '../../utils/json.js';
 import { ref } from './plan.js';
@@ -69,6 +69,15 @@ export const docReads = (c) => {
         const node = dataNode(id && ref(id), atom && ref(atom));
         return node && Array.isArray(path) ? itemIds(node, path) : [];
     };
+    /**
+     * A block's, an atom's or the document's data once `pending` patches are
+     * applied, without writing them, and its array items' ids (`previewData`):
+     * what a view reads of its data writes not yet dispatched.
+     */
+    const dataPreview = (target, pending) => {
+        const [id, atom] = typeof target === 'object' && target ? [target.block, target.atom] : [target ?? undefined];
+        return previewData(dataNode(id && ref(id), atom && ref(atom)), pending);
+    };
     /** Ordered visible children of `parent` (`null` = root) — canonical read. */
     const childrenIds = (parent) => (view().kids.get(parent) ?? []).map((k) => k.id);
     const positionOf = (id) => modelPositionOf(doc, id);
@@ -302,6 +311,7 @@ export const docReads = (c) => {
         blockDataOf,
         docData,
         dataItemIds,
+        dataPreview,
         childrenIds,
         positionOf,
         pathOf,

package/dist/crdt/document.d.ts

@@ -353,6 +353,14 @@ export declare class EdytorDocument {
     private _destroyed;
     /** {@link DocumentOptions.requireHydration}: an empty document waits for a provider's `synced`. */
     readonly requireHydration: boolean;
+    /**
+     * The document's properties as a live object (`crdt/props`): a read
+     * follows the document, and a write at any depth (`document.data.title
+     * = 'Notes'`, `document.data.tags.push('x')`, `delete …`) is the raw
+     * `patchData` operation at once, as `document.patchData(null, …)`. Not
+     * reactive by itself: a view's `edytor.data` is, and dispatches.
+     */
+    get data(): Record<string, any>;
     /** The replica id (`doc.clientID`) — identifies the replica, not the actor. */
     get clientID(): number;
     /**

package/dist/crdt/document.js

@@ -2,6 +2,7 @@ import { DEV } from 'esm-env';
 import { Y } from './engine.js';
 import { asEngineDoc } from './structs.js';
 import { DOCUMENT_OPERATIONS } from './operations.js';
+import { propsProxy } from './props.js';
 import { bindAttribution } from './attribution/index.js';
 import { profileOf } from './attribution/attribution.js';
 import { docFacade, DEFAULT_HISTORY_LIMIT, isInitialized } from './edytor-doc.js';
@@ -237,6 +238,17 @@ export class EdytorDocument {
         else if (DEV)
             advertise(this.awareness, this.#capability.config, this.#defaultType);
     }
+    #data;
+    /**
+     * The document's properties as a live object (`crdt/props`): a read
+     * follows the document, and a write at any depth (`document.data.title
+     * = 'Notes'`, `document.data.tags.push('x')`, `delete …`) is the raw
+     * `patchData` operation at once, as `document.patchData(null, …)`. Not
+     * reactive by itself: a view's `edytor.data` is, and dispatches.
+     */
+    get data() {
+        return (this.#data ??= propsProxy(() => this.facade.docData(), (patches) => void this.facade.apply(this.facade.prepare.patchData(null, patches)), (path) => this.facade.dataItemIds(null, path)));
+    }
     /** The replica id (`doc.clientID`) — identifies the replica, not the actor. */
     get clientID() {
         return this.doc.clientID;

package/dist/crdt/edytor-doc.d.ts

@@ -168,6 +168,12 @@ export declare const docFacade: <L extends Layers>(Y: EngineApi, layers: L) => (
     blockDataOf: (id: string) => Record<string, unknown> | undefined;
     docData: () => JsonObj;
     dataItemIds: (target: DataTarget, path: readonly string[]) => string[];
+    dataPreview: (target: DataTarget, pending: readonly DataPatch[]) => {
+        data: {
+            [x: string]: unknown;
+        };
+        ids: (path: readonly string[]) => string[];
+    } | null;
     /**
      * Compact per-block attribution (`{createdBy, contributors,
      * lastChangedBy}`), or `undefined` for unauthored/system blocks.
@@ -482,6 +488,12 @@ export declare const bindDocModel: (Y: EngineApi) => {
         blockDataOf: (id: string) => Record<string, unknown> | undefined;
         docData: () => JsonObj;
         dataItemIds: (target: DataTarget, path: readonly string[]) => string[];
+        dataPreview: (target: DataTarget, pending: readonly DataPatch[]) => {
+            data: {
+                [x: string]: unknown;
+            };
+            ids: (path: readonly string[]) => string[];
+        } | null;
         /**
          * Compact per-block attribution (`{createdBy, contributors,
          * lastChangedBy}`), or `undefined` for unauthored/system blocks.
@@ -882,6 +894,12 @@ export declare const bindEdytorDoc: (Y: EngineApi) => {
         blockDataOf: (id: string) => Record<string, unknown> | undefined;
         docData: () => JsonObj;
         dataItemIds: (target: DataTarget, path: readonly string[]) => string[];
+        dataPreview: (target: DataTarget, pending: readonly DataPatch[]) => {
+            data: {
+                [x: string]: unknown;
+            };
+            ids: (path: readonly string[]) => string[];
+        } | null;
         /**
          * Compact per-block attribution (`{createdBy, contributors,
          * lastChangedBy}`), or `undefined` for unauthored/system blocks.