@atom-forge/brickee 0.0.1 → 0.0.3

package/dist/plugins/TablePreview.svelte

@@ -32,31 +32,31 @@
 	</div>
 {/if}
 
-<style>
-	/* Wide tables scroll on their own instead of the page. */
-	.wrap {
-		margin: 0 0 1em;
-		overflow-x: auto;
-	}
-	table {
-		width: 100%;
-		border-collapse: collapse;
-		font: 15px/1.5 system-ui, sans-serif;
-	}
-	th,
-	td {
-		padding: 0.45em 0.7em;
-		border-bottom: 1px solid #e5e5ea;
-		text-align: left;
-		vertical-align: top;
-	}
-	th {
-		font-weight: 600;
-	}
-	th.top {
-		border-bottom-width: 2px;
-	}
-	th.bottom {
-		border-top: 2px solid #e5e5ea;
-	}
-</style>
+<style>.wrap {
+  margin: 0 0 1em;
+  overflow-x: auto;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  font: 15px/1.5 system-ui, sans-serif;
+}
+
+th,
+td {
+  padding: 0.45em 0.7em;
+  border-bottom: 1px solid color-mix(in srgb, currentColor 15%, transparent);
+  text-align: left;
+  vertical-align: top;
+}
+
+th {
+  font-weight: 600;
+}
+th.top {
+  border-bottom-width: 2px;
+}
+th.bottom {
+  border-top: 2px solid color-mix(in srgb, currentColor 22%, transparent);
+}</style>

package/dist/plugins/YouTube.svelte

@@ -15,38 +15,10 @@
 </script>
 
 {#if id}
-	<div class="yt">
-		<img src="https://i.ytimg.com/vi/{id}/hqdefault.jpg" alt={props.title} draggable="false" />
-		<span class="play"><Play size={22} /></span>
+	<div class="relative overflow-hidden rounded-[10px] bg-black">
+		<img class="block aspect-video w-full object-cover opacity-85" src="https://i.ytimg.com/vi/{id}/hqdefault.jpg" alt={props.title} draggable="false" />
+		<span class="absolute inset-0 m-auto grid h-10 w-14 place-items-center rounded-[10px] bg-red-600 text-white"><Play size={22} /></span>
 	</div>
 {:else}
 	<Empty icon={SquarePlay} text="Paste a YouTube link above" />
 {/if}
-
-<style>
-	.yt {
-		position: relative;
-		border-radius: 10px;
-		overflow: hidden;
-		background: #000;
-	}
-	img {
-		display: block;
-		width: 100%;
-		aspect-ratio: 16 / 9;
-		object-fit: cover;
-		opacity: 0.85;
-	}
-	.play {
-		position: absolute;
-		inset: 0;
-		margin: auto;
-		width: 56px;
-		height: 40px;
-		display: grid;
-		place-items: center;
-		border-radius: 10px;
-		background: #dc2626;
-		color: #fff;
-	}
-</style>

package/dist/plugins/YouTubePreview.svelte

@@ -31,46 +31,48 @@
 	</figure>
 {/if}
 
-<style>
-	.yt {
-		margin: 0 0 1em;
-	}
-	iframe,
-	button {
-		display: block;
-		width: 100%;
-		aspect-ratio: 16 / 9;
-		border: 0;
-		border-radius: 8px;
-	}
-	button {
-		position: relative;
-		padding: 0;
-		overflow: hidden;
-		background: #000;
-		cursor: pointer;
-	}
-	img {
-		width: 100%;
-		height: 100%;
-		object-fit: cover;
-	}
-	.play {
-		position: absolute;
-		inset: 0;
-		margin: auto;
-		width: 64px;
-		height: 44px;
-		display: grid;
-		place-items: center;
-		border-radius: 12px;
-		background: #dc2626;
-		color: #fff;
-		font-size: 20px;
-	}
-	figcaption {
-		margin-top: 0.4em;
-		color: #6b6b76;
-		font: 13px/1.4 system-ui, sans-serif;
-	}
-</style>
+<style>.yt {
+  margin: 0 0 1em;
+}
+
+iframe,
+button {
+  display: block;
+  width: 100%;
+  aspect-ratio: 16/9;
+  border: 0;
+  border-radius: 8px;
+}
+
+button {
+  position: relative;
+  padding: 0;
+  overflow: hidden;
+  background: #000;
+  cursor: pointer;
+}
+button img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.play {
+  position: absolute;
+  inset: 0;
+  margin: auto;
+  width: 64px;
+  height: 44px;
+  display: grid;
+  place-items: center;
+  border-radius: 12px;
+  background: #dc2626;
+  color: #fff;
+  font-size: 20px;
+}
+
+figcaption {
+  margin-top: 0.4em;
+  color: color-mix(in srgb, currentColor 65%, transparent);
+  font: 13px/1.4 system-ui, sans-serif;
+}</style>

package/dist/plugins/index.js

@@ -1,13 +1,13 @@
 // The bundled plugins: plugins like any other (written with the kit), an app picks the ones it wants. Only general
 // blocks live here (video, map, table, gap); anything an app gives its own meaning to belongs in the app.
-import { MapPin, SquarePlay, Table, UnfoldVertical } from '@lucide/svelte';
+import { MapPin, PanelBottom, PanelTop, SquarePlay, Table, UnfoldVertical } from '@lucide/svelte';
 import { mdText } from '../kit/util';
 import { youtubeId } from './util';
 import Gap, { GAP_LINES } from './Gap.svelte';
 import GapPreview from './GapPreview.svelte';
 import MapView, {} from './Map.svelte';
 import MapPreview from './MapPreview.svelte';
-import TableView, { tableHeads } from './Table.svelte';
+import TableView, { square, tableHeads } from './Table.svelte';
 import TablePreview from './TablePreview.svelte';
 import YouTube, {} from './YouTube.svelte';
 import YouTubePreview from './YouTubePreview.svelte';
@@ -42,8 +42,21 @@ export const table = {
     keys: 'table grid rows columns price list',
     icon: Table,
     props: () => ({ rows: [['', ''], ['', '']], heads: ['top'] }),
+    fields: [
+        {
+            key: 'heads',
+            label: 'Header and footer',
+            kind: 'toggles',
+            options: [
+                { value: 'top', label: 'Header row', icon: PanelTop },
+                { value: 'bottom', label: 'Footer row (e.g. sums)', icon: PanelBottom }
+            ]
+        }
+    ],
     tag: (p) => `table · ${p.rows?.length ?? 0}×${p.rows?.[0]?.length ?? 0}`,
     content: 'none',
+    // A pasted or imported GFM table: its first row is the header.
+    fromTable: ({ rows, align }) => ({ rows: square(rows), heads: ['top'], ...(align.some((a) => a !== 'left') ? { align } : {}) }),
     markdown: (p) => {
         const rows = p.rows ?? [];
         if (!rows.length)

package/dist/schema.js

@@ -1,5 +1,5 @@
 // Server-side validation of a stored document (zod). Only the shape is checked: the renderers escape every text,
-// keep links to http(s)/mailto/tel/site paths, take colours only as #hex and images only from the host's media.
+// keep links to http(s)/mailto/tel/site paths, take colours only as #hex.
 import { z } from 'zod';
 import { acceptsId, MAX_DEPTH, MAX_INDENT } from './model';
 const block = z.lazy(() => z.strictObject({

package/dist/types.d.ts

@@ -1,4 +1,3 @@
-import type { MediaItem } from './media';
 import type { Component } from 'svelte';
 import type { StoredBlock } from './model';
 import type { Icon } from './palette';
@@ -31,10 +30,11 @@ export interface PropField {
     key: string;
     label: string;
     /**
-     * 'image' picks one of the document's images (stores its id), 'images' several (an array of ids, in picking order).
+     * 'toggles' is a row of icon buttons, each switching one of `options` on or off; stored as the list of the ones on
+     * (in `options` order).
      * 'slider' steps through `options` in their order (e.g. heights), or, with `min` and `max`, sets a number freely.
      */
-    kind: 'text' | 'textarea' | 'color' | 'select' | 'slider' | 'image' | 'images';
+    kind: 'text' | 'textarea' | 'color' | 'select' | 'slider' | 'toggles';
     placeholder?: string;
     /** A number slider: its range, step (default 1) and unit shown after the value. */
     min?: number;
@@ -56,10 +56,11 @@ export interface PropField {
         key: string;
         label: string;
     }[];
-    /** For 'select' and 'slider'. */
+    /** For 'select', 'slider' and 'toggles' (where `icon` is the button and `label` its tooltip). */
     options?: {
         value: string;
         label: string;
+        icon?: Icon;
     }[];
     /** The field's text from the stored value; default: the value as a string. */
     format?: (value: unknown) => string;
@@ -82,12 +83,16 @@ export interface PluginPreviewProps<P extends Props = Props> {
     plugins: BlockPlugin[];
 }
 /** A custom block for the slash menu. */
+/** A GFM table read from markdown: the cells as inline markdown, row by row (the first row is the header), and the
+ * alignment of each column. */
+export interface MarkdownTable {
+    rows: string[][];
+    align: ('left' | 'center' | 'right')[];
+}
 /** What a plugin's `markdown` gets beside its props. */
 export interface MarkdownContext {
     /** The nested blocks as markdown ('' when it has none). */
     inner: string;
-    /** The media of the document, to turn an attachment id into its url. */
-    media: MediaItem[];
 }
 export interface BlockPlugin<P extends Props = Props> {
     /** Stored `type`; must not start with 'md:'. */
@@ -112,7 +117,7 @@ export interface BlockPlugin<P extends Props = Props> {
      */
     preview?: Component<PluginPreviewProps<any>>;
     /**
-     * For a plugin with nested blocks: the blocks it takes, as palette ids ('md:p', 'image'…); 'md:*' stands for every
+     * For a plugin with nested blocks: the blocks it takes, as palette ids ('md:p', 'youtube'…); 'md:*' stands for every
      * built-in block. Its nested editor offers the host's palette narrowed to these. Default: everything the host has.
      */
     accepts?: string[];
@@ -121,13 +126,25 @@ export interface BlockPlugin<P extends Props = Props> {
      * when it gives '', the block is left out of the markdown.
      */
     markdown?(props: P, ctx: MarkdownContext): string;
-    /** At most one per document, and only at the top level (e.g. the supporters-only divider). */
+    /**
+     * Takes a GFM table when markdown is pasted or imported (`fromMarkdown(src, { plugins })`): returns the block's props
+     * from the table's cells (inline markdown, the first row is the header) and its column alignments. The first plugin
+     * that has it gets the table; without one, the table stays text.
+     */
+    fromTable?(table: MarkdownTable): P;
+    /**
+     * Takes files pasted into the editor or dropped on it (an image, a PDF…): returns the new block's props, or null to
+     * leave them to the next plugin. Uploading and storing them is the plugin's own business; it may take its time (a
+     * promise). The first plugin the editor offers that takes them gets one block.
+     */
+    fromFiles?(files: File[]): P | null | Promise<P | null>;
+    /** At most one per document, and only at the top level (e.g. a table of contents). */
     unique?: boolean;
-    /** The blocks after it are gated (e.g. for supporters only): the preview marks them. Implies nothing about `unique`. */
-    gate?: boolean;
 }
 export { MAX_INDENT } from './model';
 export declare const uid: () => string;
 export declare const newBlock: (type?: BlockType, html?: string, extra?: Partial<Block>) => Block;
+/** The start number a numbered list's first item carries (`props.start`), or 1. */
+export declare const olStart: (props: Record<string, unknown> | undefined) => number;
 /** Ordinal for every `ol` block, restarting after interruptions and per indent level. */
 export declare function numbering(blocks: Block[]): Record<string, number>;

package/dist/types.js

@@ -25,14 +25,21 @@ export const newBlock = (type = 'p', html = '', extra = {}) => ({
     indent: 0,
     ...extra
 });
+/** The start number a numbered list's first item carries (`props.start`), or 1. */
+export const olStart = (props) => {
+    const n = Math.floor(Number(props?.start));
+    return n >= 0 && n < 1e9 ? n : 1;
+};
 /** Ordinal for every `ol` block, restarting after interruptions and per indent level. */
 export function numbering(blocks) {
     const out = {};
     const counters = [];
     for (const b of blocks) {
         if (b.type === 'ol') {
+            const fresh = counters[b.indent] === undefined;
             counters.length = b.indent + 1;
-            counters[b.indent] = (counters[b.indent] ?? 0) + 1;
+            // A list's first item may carry its start number (an imported "5. …").
+            counters[b.indent] = fresh ? olStart(b.props) : counters[b.indent] + 1;
             out[b.id] = counters[b.indent];
         }
         else {

package/dist/view.js

@@ -2,7 +2,7 @@
 // host's business (e.g. the width its preview shows): it gives the current one through the context. Without it, a
 // per-view field simply edits its base value.
 import { getContext, setContext } from 'svelte';
-const KEY = 'block-editor:view';
+const KEY = 'brickee:view';
 /** Call in a component's init (around the editor); the function returns the current view's key. */
 export function provideView(get) {
     setContext(KEY, get);

package/docs/en/bundled-plugins.md

@@ -13,7 +13,7 @@ import { table, youtube } from '@atom-forge/brickee/plugins'; // or some
 
 | Export | `type` | Fields | Markdown form | What it is |
 |---|---|---|---|---|
-| `table` | `table` | — (edited in place) | a GFM table | Rows and columns of inline-formatted cells; rows and columns are dragged by their grips. The first row can be a header, the last a footer. |
+| `table` | `table` | header and footer (the cells are edited in place) | a GFM table (a pasted GFM table becomes one) | Rows and columns of inline-formatted cells; click a cell for its row and column tools (insert, delete, align), drag rows and columns by their grips. A cell shows its text formatted; editing it shows the markdown, and `Ctrl/Cmd` + `B`, `I`, `E`, `Shift+X`, `K` mark the selected text. The first row can be a header, the last a footer. |
 | `youtube` | `youtube` | video link or id, title | a link | A YouTube video, loaded on click; any YouTube link is reduced to the video id. |
 | `map` | `map` | place or address, zoom slider | a link | A Google Maps embed of a place or an address. |
 | `gap` | `gap` | height slider | none | Empty space between blocks, 1–8 lines high. |

package/docs/en/documents-and-markdown.md

@@ -46,13 +46,13 @@ A short document with a paragraph, a list, a video and a box (the `note` contain
 | `md:p` | inline markdown | — | the text |
 | `md:h1` … `md:h6` | inline markdown | — | `#` … `######` |
 | `md:ul` | inline markdown | — | `- item` |
-| `md:ol` | inline markdown | — | `1. item` (numbered per run and indent level) |
+| `md:ol` | inline markdown | `{ start?: number }` on a list's first item | `1. item` (numbered per run and indent level, from `start` when given) |
 | `md:todo` | inline markdown | `{ checked: boolean }` | `- [x] item` |
 | `md:quote` | inline markdown | — | `> quote` |
 | `md:code` | raw text | `{ lang?: string }` | fenced block with the language |
 | `md:hr` | — | — | `---` |
 
-`indent` nests list items (consecutive list blocks become properly nested `ul`/`ol` elements in the preview) and indents paragraphs and quotes. Headings, code and dividers ignore it.
+`indent` nests list items (consecutive list blocks become properly nested `ul`/`ol` elements in the preview), puts paragraphs and code blocks under a list item, and nests quotes (`> > …`). Headings and dividers ignore it.
 
 ### Inline markdown
 
@@ -60,15 +60,15 @@ The text of a built-in block is a small, safe subset of markdown:
 
 | Mark | Stored as |
 |---|---|
-| bold | `**text**` |
-| italic | `*text*` |
+| bold | `**text**` (read also: `__text__`) |
+| italic | `*text*` (read also: `_text_`, not inside a word) |
 | underline, subscript, superscript | `<u>text</u>`, `<sub>text</sub>`, `<sup>text</sup>` |
 | strikethrough | `~~text~~` |
-| code | `` `text` `` |
-| link | `[text](url)` — only `http:`, `https:`, `mailto:`, `tel:` and site-relative `/…` targets become links |
-| line break | a newline |
+| code | `` `text` `` (a longer backtick run when the code holds backticks: ``` `` a`b `` ```) |
+| link | `[text](url)` — only `http:`, `https:`, `mailto:`, `tel:` and site-relative `/…` targets become links; parentheses in a target must be balanced. Read also: a title (dropped), `<https://…>` autolinks, and an image `![alt](url)` as a link |
+| line break | a newline (in markdown out: a backslash at the line's end) |
 
-Special characters in plain text are backslash-escaped, so they never turn into markup. `inline(md)` turns inline markdown into HTML: it escapes the text first and only then adds the tags above, so its output is safe to render with `{@html}` — this is what the preview does.
+Special characters in plain text are backslash-escaped, so they never turn into markup; any ASCII punctuation can be escaped. Reading stays linear on any input, with these limits: a marked span is at most 2000 characters, a link label has no brackets of its own and is at most 1000 characters, a link target at most 2000. When reading, inline HTML maps onto the marks (`<strong>`, `<em>`, `<del>`, `<br>`…), other tags are dropped with their text kept, and a footnote reference `[^1]` becomes a superscript. `inline(md)` turns inline markdown into HTML: it escapes the text first and only then adds the tags above, so its output is safe to render with `{@html}` — this is what the preview does.
 
 ## Markdown in and out
 
@@ -78,19 +78,19 @@ Markdown is a first-class format: the clipboard carries it, and a host can impor
 |---|---|---|
 | `fromStored(block)` | `StoredBlock` → `Block` | anywhere |
 | `toStored(block)` | `Block` → `StoredBlock` | browser only |
-| `fromMarkdown(text)` | markdown → `Block[]` | anywhere |
-| `toMarkdown(blocks, { plugins, media })` | `Block[]` → markdown | browser only |
+| `fromMarkdown(text, { plugins })` | markdown → `Block[]` | anywhere |
+| `fromHtml(html, { plugins })` | HTML (a formatted paste, a page) → `Block[]` | browser only |
+| `toMarkdown(blocks, { plugins })` | `Block[]` → markdown | browser only |
 | `inline(md)` | inline markdown → inline HTML | anywhere |
 
 The markdown functions work on the editor form (`Block[]`), so stored documents go through `fromStored` and `toStored`:
 
 ```ts
-import { fromMarkdown, fromStored, toMarkdown, toStored, type MediaItem, type StoredBlock } from '@atom-forge/brickee';
+import { fromMarkdown, fromStored, toMarkdown, toStored, type StoredBlock } from '@atom-forge/brickee';
 import { PLUGINS } from '@atom-forge/brickee/plugins';
 
 // Stored document -> markdown (browser only).
-export const exportMarkdown = (doc: StoredBlock[], media: MediaItem[]) =>
-	toMarkdown(doc.map(fromStored), { plugins: PLUGINS, media });
+export const exportMarkdown = (doc: StoredBlock[]) => toMarkdown(doc.map(fromStored), { plugins: PLUGINS });
 
 // Markdown -> stored document (browser only).
 export const importMarkdown = (text: string): StoredBlock[] => fromMarkdown(text).map(toStored);
@@ -102,14 +102,19 @@ export const importMarkdown = (text: string): StoredBlock[] => fromMarkdown(text
 
 What `fromMarkdown` reads:
 
-- headings, bulleted, numbered and to-do items, quotes, fenced code blocks with their language, dividers, and the inline marks above;
-- leading spaces as indentation (two spaces or one tab per level);
-- every non-empty line as its own block — it does not join wrapped lines into one paragraph, and it creates built-in blocks only (no tables, images or plugin blocks).
+- headings (also setext: a line underlined with `===` or `---`, and with closing `#`s), bulleted, numbered (with their start number) and to-do items, quotes (nested ones one level deeper), fenced code (backticks or tildes, any length, closed by a fence at least as long) and indented code, dividers, and the inline marks above;
+- list nesting by the items' markers: a line indented past an item's marker is inside the item (so `1. ` items nest with two, three or four spaces);
+- the lines of a paragraph, a list item or a quote as one block, with line breaks between them; a blank line, or `>` alone in a quote, starts a new one;
+- reference links (`[text][id]` with `[id]: url`) resolved, footnote definitions as a paragraph after their number;
+- a GFM table as a block of the first of `plugins` that takes tables (`fromTable`, see [Writing plugins](writing-plugins.md#taking-pasted-tables); the bundled `table` does), otherwise as text. The editor passes the plugins it offers, so a pasted table becomes a table block.
+
+What `fromHtml` reads — the editor uses it for a formatted paste from a web page, Google Docs or Word: headings, paragraphs, lists (nested, numbered with their start, to-dos from checkboxes), quotes, code (`pre`, with a `language-…` class), rules, tables (for a plugin that takes them), and the inline marks — also Google Docs' bold, italic and struck-through spans. Images become links (the package has no images), and scripts, styles and form controls are dropped. The HTML is only read: it goes through markdown and the same safe rendering as everything else.
 
 What `toMarkdown` writes:
 
-- consecutive list items on consecutive lines, every other block separated by a blank line;
-- list items and paragraphs indented by two spaces per level;
-- a plugin block through its plugin's `markdown(props, { inner, media })`, where `inner` is its nested blocks already converted; a plugin without a markdown form, or one returning `''`, is left out.
+- consecutive list items on consecutive lines, consecutive quotes as one quote (`>` between their paragraphs), every other block separated by a blank line;
+- nested items, and paragraphs and code under an item, indented to the item's content (two spaces under `- `, three under `1. `, four under `10. `);
+- code in a fence longer than any backtick run in it, and plain text escaped where markdown would read it as markup (`\_`, `1\.` at a line's start…);
+- a plugin block through its plugin's `markdown(props, { inner })`, where `inner` is its nested blocks already converted; a plugin without a markdown form, or one returning `''`, is left out.
 
 Writing a markdown form for your own plugin is covered in [Writing plugins](writing-plugins.md#markdown-form).

package/docs/en/editor-and-preview.md

@@ -6,12 +6,11 @@
 
 | Prop | Type | Default | Meaning |
 |---|---|---|---|
-| `value` | `StoredBlock[]` (bindable) | `[]` | The document. Written back on every change; a document replaced from outside is loaded again. |
+| `value` | `StoredBlock[]` (bindable) | `[]` | The document. Written back on every change (unchanged blocks keep their objects); a document replaced from outside — a new array, not one changed in place — is loaded again, unless it equals the current one. |
 | `plugins` | `BlockPlugin[]` | `[]` | The plugin blocks this editor can show and offer. |
 | `palette` | `string[]` | every built-in block, then every plugin | The block types the slash menu offers, in this order (see below). |
-| `media` | `MediaItem[]` | — | The images blocks can pick from (see [Host contexts](host-contexts.md)). |
 | `messages` | `Messages` | — | UI text in the host's language: English text → translation. |
-| `readonly` | `boolean` | `false` | Shows the document without editing; plugin fields are hidden. |
+| `readonly` | `boolean` | `false` | Shows the document without editing; plugin fields are hidden. A read-only editor never writes `value`. |
 | `placeholder` | `string` | `Write something, or press '/' for blocks…` | The hint of an empty block. |
 | `nested` | `boolean` | `false` | Set by plugins with nested blocks for their inner editor; a host never sets it. |
 
@@ -23,16 +22,14 @@ An empty document is shown as one empty paragraph, so the value the editor write
 |---|---|---|---|
 | `blocks` | `StoredBlock[]` | — | The document to render. |
 | `plugins` | `BlockPlugin[]` | — | The plugins whose previews render the plugin blocks. |
-| `media` | `MediaItem[]` | — | The images the blocks refer to by id. |
 | `messages` | `Messages` | — | UI text in the host's language. |
-| `markGated` | `boolean` | `true` | Marks the blocks after a gate block (see [Unique and gate blocks](writing-plugins.md#unique-and-gate-blocks)). |
 | `nested` | `boolean` | `false` | Set by plugin previews that render their nested blocks. |
 
 The preview renders built-in blocks as plain HTML (`p`, `h1`…`h6`, `ul`/`ol` with nested items, `blockquote`, `pre > code` with a `language-<lang>` class, `hr`) and each plugin block with its plugin's `preview`. A block whose type has no plugin in `plugins`, or whose plugin has no `preview`, is not rendered.
 
 Using `Preview` at all is your choice: the editor does not depend on it. An application with its own renderer can render the stored blocks itself, and its plugins can leave `preview` out.
 
-`media` and `messages` given to the top-level editor or preview are inherited by every nested editor, nested preview and plugin component below it.
+`messages` given to the top-level editor or preview are inherited by every nested editor, nested preview and plugin component below it.
 
 ## The palette
 
@@ -74,10 +71,10 @@ A plain paragraph (`md:p`) is always allowed as the fallback.
 | Inline formatting | Select text for the toolbar, or `Ctrl/Cmd` + `B` bold, `I` italic, `U` underline, `Shift+X` strikethrough, `E` code, `K` link, `\` remove formatting. Subscript and superscript are on the toolbar. |
 | Indent | `Tab` / `Shift+Tab` (at most 6 levels). |
 | Line break | `Shift+Enter`; in a code block `Enter` breaks the line and `Shift+Enter` or `Ctrl/Cmd+Enter` starts a new block. |
-| Select blocks | Click a block's handle, `Esc` in a block, `Shift+↑/↓` past the edge of a block, or drag a text selection across blocks. `Ctrl/Cmd+A` in an empty block selects every block. |
-| Move blocks | Drag the handle (also into and out of nested editors), or `Ctrl/Cmd+Shift+↑/↓`. |
-| Turn into | Click the handle of a block or a selection for the Turn-into menu. |
-| Copy, cut | Copying selected blocks puts their markdown on the clipboard (plugin blocks through their markdown form). |
+| Select blocks | Click (or tap) a block's handle, `Esc` in a block, `Shift+↑/↓` past the edge of a block, or drag a text selection across blocks. `Ctrl/Cmd+A` in an empty block selects every block. |
+| Move blocks | Drag the handle (also into and out of nested editors), `Ctrl/Cmd+Shift+↑/↓`, or *Move up* / *Move down* in the Turn-into menu (without dragging: touch screens, keyboard). |
+| Turn into | Click the handle of a block or a selection for the Turn-into menu; from the keyboard `/` (or `Ctrl/Cmd+/`, the menu key, `Shift+F10`) on selected blocks, or `Ctrl/Cmd+/` in a block's text. On a touch screen a tapped block shows its actions (add below, turn into, delete) beside its handle. |
+| Copy, cut, paste | Copying selected blocks puts their markdown on the clipboard (plugin blocks through their markdown form) and, beside it, the blocks themselves (`application/x-brickee+json`). Formatted text from elsewhere (a web page, Google Docs, Word) keeps its headings, lists, tables and marks (`fromHtml`); plain text is read as markdown. Pasted into a Brickee editor, copied blocks come back as they were; a plugin block that editor does not offer (or a second unique one) falls back to its markdown form. Pasted anywhere else, the markdown arrives. Pasting while blocks are selected puts the blocks after them. |
 | Paste | Multi-line text is read as markdown and becomes blocks. |
 | Undo, redo | `Ctrl/Cmd+Z`, `Ctrl/Cmd+Shift+Z` or `Ctrl/Cmd+Y`. |
 

package/docs/en/getting-started.md

@@ -10,7 +10,7 @@ Everything else is a plugin. A plugin is a plain object (`BlockPlugin`) that nam
 
 - a **view** — a Svelte component shown in the editor;
 - a **preview** — a Svelte component that renders the block on the site;
-- **fields** — the settings shown on the top of the block (text, colour, select, slider, image…);
+- **fields** — the settings shown on the top of the block (text, colour, select, slider…);
 - optionally a **markdown form**, used when the document is copied or exported as markdown.
 
 The package ships four general-purpose plugins — table, YouTube video, map and gap — but they are plugins like any other: nothing in the core depends on them, and you pass only the ones you want. Image blocks, boxes and other site-specific blocks are plugins you write yourself.
@@ -24,7 +24,7 @@ bun add @atom-forge/brickee @atom-forge/ui @lucide/svelte
 | Peer dependency | Why |
 |---|---|
 | `svelte` `^5.0.0` | The editor, the preview and the plugins are Svelte 5 components. |
-| `@atom-forge/ui` `>=0.0.37` | The popups (link prompt, image picker) and the form controls of the block fields. |
+| `@atom-forge/ui` `>=0.0.37` | The popups (link prompt) and the form controls of the block fields. |
 | `@lucide/svelte` `>=1.0.0` | The block icons. |
 | `zod` `^4.0.0` (optional) | Only for the server-side schema in `@atom-forge/brickee/schema`. |
 
@@ -33,10 +33,22 @@ bun add @atom-forge/brickee @atom-forge/ui @lucide/svelte
 The block fields and popups are `@atom-forge/ui` components, so the application must be set up the way `@atom-forge/ui` requires:
 
 - Tailwind CSS 4 with the `@atom-forge/ui` theme CSS imported and its `dist` folder added as a Tailwind `@source`;
+- the `dist` folder of `@atom-forge/brickee` added as a Tailwind `@source` too: the editor is styled with Tailwind classes and the `@atom-forge/ui` theme's colours, so Tailwind has to see them:
+
+  ```css
+  @source "../node_modules/@atom-forge/ui/dist";
+  @source "../node_modules/@atom-forge/brickee/dist";
+  ```
+
+  The preview needs neither: its few styles travel with its markup, so a public page without Tailwind can show documents;
 - the application rendered beneath the `@atom-forge/ui` `Root` component, which provides the theme and the overlay contexts.
 
 The top-level `Editor` creates its own popup manager and renders its own popup container; editors nested in plugin blocks share it.
 
+The editor takes its colours from the `@atom-forge/ui` theme tokens (`--color-surface`, `--color-frame`, `--color-muted-contrast`…), so it follows the host's light and dark mode. The preview's borders and captions are drawn from the text colour of the page.
+
+The block handles are drawn in a gutter **left of the editor's box**, about 22 px wide: give the element around the editor that much padding on the left, or the handles stick out of it.
+
 > **Missing theme**
 >
 > Without the `@atom-forge/ui` theme CSS the editor still works, but the block fields, the colour picker, the slider and the popups appear unstyled.