@atom-forge/brickee 0.0.0-stage → 0.0.2

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

@@ -0,0 +1,114 @@
+# Documents and markdown
+
+[← Previous](editor-and-preview.md) · [Contents](index.md) · [Next →](bundled-plugins.md)
+
+## The stored form
+
+A document is an array of `StoredBlock` objects — plain JSON you can save in a database column as it is:
+
+```ts
+interface StoredBlock {
+	type: string; // 'md:p', 'md:h2'… for built-in blocks; the plugin's type for plugin blocks
+	indent: number; // 0–6
+	text?: string; // built-in blocks: inline markdown (raw text for md:code)
+	props?: Record<string, unknown>; // plugin settings; md:todo { checked }, md:code { lang }
+	blocks?: StoredBlock[]; // plugins with nested blocks: their inner document
+}
+```
+
+A short document with a paragraph, a list, a video and a box (the `note` container from [Writing plugins](writing-plugins.md#containers)):
+
+```json
+[
+	{ "type": "md:h2", "indent": 0, "text": "Getting there" },
+	{ "type": "md:p", "indent": 0, "text": "Take the **night train** or see the [timetable](https://example.com/trains)." },
+	{ "type": "md:ul", "indent": 0, "text": "Tickets online" },
+	{ "type": "md:ul", "indent": 1, "text": "Students get *20%* off" },
+	{ "type": "youtube", "indent": 0, "props": { "id": "aqz-KE-bpKQ", "title": "The route by night" } },
+	{
+		"type": "note",
+		"indent": 0,
+		"props": { "title": "Good to know" },
+		"blocks": [{ "type": "md:p", "indent": 0, "text": "Trains are cancelled on public holidays." }]
+	}
+]
+```
+
+- Built-in types carry the `md:` prefix (`MD` constant, `isMd(block)` test); everything else is a plugin type.
+- Plugin blocks keep only `type`, `indent`, `props` and, for containers, `blocks`. What the props mean is up to the plugin.
+- Nested blocks go one level deep: a block inside a box cannot hold blocks itself (`MAX_DEPTH` is 2).
+- The editor's own working form (`Block`, with an `id` and inline HTML) is never stored; `toStored` and `fromStored` convert between the two.
+
+## Built-in blocks
+
+| Type | Stored text | Props | Markdown |
+|---|---|---|---|
+| `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: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.
+
+### Inline markdown
+
+The text of a built-in block is a small, safe subset of markdown:
+
+| Mark | Stored as |
+|---|---|
+| bold | `**text**` |
+| italic | `*text*` |
+| 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 |
+
+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.
+
+## Markdown in and out
+
+Markdown is a first-class format: the clipboard carries it, and a host can import and export it.
+
+| Function | From → to | Runs |
+|---|---|---|
+| `fromStored(block)` | `StoredBlock` → `Block` | anywhere |
+| `toStored(block)` | `Block` → `StoredBlock` | browser only |
+| `fromMarkdown(text)` | markdown → `Block[]` | anywhere |
+| `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 StoredBlock } from '@atom-forge/brickee';
+import { PLUGINS } from '@atom-forge/brickee/plugins';
+
+// Stored document -> markdown (browser only).
+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);
+```
+
+> **Browser only**
+>
+> `toMarkdown` and `toStored` read the editor's inline HTML through the DOM, so they need `document`. Call them in the browser (an event handler, an effect), not during server-side rendering. For server-side text, use `blocksToPlainText` (see [On the server](server-side.md)).
+
+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).
+
+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 })`, 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

@@ -0,0 +1,139 @@
+# The editor and the preview
+
+[← Previous](getting-started.md) · [Contents](index.md) · [Next →](documents-and-markdown.md)
+
+## Editor props
+
+| Prop | Type | Default | Meaning |
+|---|---|---|---|
+| `value` | `StoredBlock[]` (bindable) | `[]` | The document. Written back on every change; a document replaced from outside is loaded again. |
+| `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). |
+| `messages` | `Messages` | — | UI text in the host's language: English text → translation. |
+| `readonly` | `boolean` | `false` | Shows the document without editing; plugin fields are hidden. |
+| `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. |
+
+An empty document is shown as one empty paragraph, so the value the editor writes back is never an empty array once it has been mounted: it is at least `[{ type: 'md:p', indent: 0, text: '' }]`. The preview skips empty paragraphs.
+
+## Preview props
+
+| Prop | Type | Default | Meaning |
+|---|---|---|---|
+| `blocks` | `StoredBlock[]` | — | The document to render. |
+| `plugins` | `BlockPlugin[]` | — | The plugins whose previews render the plugin blocks. |
+| `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.
+
+`messages` given to the top-level editor or preview are inherited by every nested editor, nested preview and plugin component below it.
+
+## The palette
+
+The `palette` is a list of **palette ids**: `md:p`, `md:h1`…`md:h6`, `md:ul`, `md:ol`, `md:todo`, `md:quote`, `md:code`, `md:hr` for the built-in blocks, and a plugin's `type` for a plugin. It decides:
+
+- which blocks the slash menu and the Turn-into menu offer, and in which order;
+- which markdown shortcuts work (typing `## ` turns a paragraph into a heading only if `md:h2` is in the palette);
+- what pasted markdown may become: a pasted block of a type outside the palette becomes a paragraph, and a divider is dropped.
+
+A plain paragraph (`md:p`) is always allowed as the fallback.
+
+```svelte
+<script lang="ts">
+	import { Editor, type StoredBlock } from '@atom-forge/brickee';
+	import { map, table, youtube } from '@atom-forge/brickee/plugins';
+
+	const plugins = [table, youtube, map];
+	// No h1 (the page title is one) and no code blocks.
+	const palette = ['md:p', 'md:h2', 'md:h3', 'md:ul', 'md:ol', 'md:quote', 'md:hr', ...plugins.map((p) => p.type)];
+
+	let value = $state<StoredBlock[]>([]);
+</script>
+
+<Editor bind:value {plugins} {palette} />
+```
+
+`PALETTE_ITEMS` lists the built-in blocks with their labels, hints and icons; `BUILT_IN_IDS` is just their ids in the default order.
+
+> **The palette limits offering, not loading**
+>
+> A document that already holds a block outside the palette still shows it. A plugin block whose plugin is missing from `plugins` is kept as it is and shown as an unknown block that can only be deleted. To reject such documents, validate them on the server (see [On the server](server-side.md)).
+
+## Editing
+
+| Action | How |
+|---|---|
+| Insert a block | `/` opens the slash menu (searchable by label, hint, keywords and their translations); the `+` button adds a block below. |
+| Markdown shortcuts | At the start of a paragraph: `# `…`###### `, `- ` / `* ` / `+ `, `1. `, `[] `, `> `. |
+| 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). |
+| Paste | Multi-line text is read as markdown and becomes blocks. |
+| Undo, redo | `Ctrl/Cmd+Z`, `Ctrl/Cmd+Shift+Z` or `Ctrl/Cmd+Y`. |
+
+What a block can turn into depends on what it holds (its `content`):
+
+- text blocks turn into each other and keep their formatting; turning text into code keeps only the letters;
+- a block without content (divider, video, map) only replaces empty blocks or other blocks without content;
+- a block with nested blocks (a box) can wrap the selected blocks, if it accepts all of them; **Unwrap** moves a box's blocks out; a box can turn into another box-like type, and the props with the same names carry over.
+
+## Scroll sync
+
+A host that shows the editor and the preview side by side can make the preview follow the editor's scrolling. `scrollSync()` returns two Svelte actions and a function:
+
+```svelte
+<script lang="ts">
+	import { Editor, Preview, scrollSync, type StoredBlock } from '@atom-forge/brickee';
+	import { PLUGINS } from '@atom-forge/brickee/plugins';
+
+	let value = $state<StoredBlock[]>([]);
+	const sync = scrollSync();
+</script>
+
+<div class="split">
+	<div class="pane" use:sync.source>
+		<Editor bind:value plugins={PLUGINS} />
+	</div>
+	<div class="pane" use:sync.target>
+		<Preview blocks={value} plugins={PLUGINS} />
+	</div>
+</div>
+
+<style>
+	.split {
+		display: grid;
+		grid-template-columns: 1fr 1fr;
+		height: 100vh;
+	}
+	.pane {
+		overflow-y: auto;
+	}
+</style>
+```
+
+- `use:sync.source` goes on the editor's scrolling box, `use:sync.target` on the preview's. The target is scrolled to the same fraction (0…1) of its scroll range as the source. The sync is one way: scrolling the preview moves nothing else.
+- It re-syncs once per animation frame when the source scrolls, and when the target box or its children change size. `sync.align()` re-syncs on demand, for example after the preview's width changed.
+- `use:sync.target={on}` takes a boolean (default `true`), for a host that switches the target between two boxes, such as a desktop pane and a phone frame: turn on the visible one.
+- The sync is proportional only: both boxes show roughly the same place, not exactly the same block. This is deliberate — it needs no markup and works with any preview.
+
+`scrollFraction(box)` reads how far a box is scrolled (0…1; 0 when it does not scroll), and `setScrollFraction(box, f)` scrolls it there — for example to keep the place when the preview changes width while it is shown alone:
+
+```ts
+import { scrollFraction, setScrollFraction } from '@atom-forge/brickee';
+import { tick } from 'svelte';
+
+export async function keepPlace(box: HTMLElement, change: () => void) {
+	const f = scrollFraction(box);
+	change(); // e.g. switch the preview width
+	await tick();
+	setScrollFraction(box, f);
+}
+```

package/docs/en/getting-started.md

@@ -0,0 +1,85 @@
+# Getting started
+
+[Contents](index.md) · [Next →](editor-and-preview.md)
+
+## What Brickee is
+
+Brickee is a block editor: a document is a list of blocks, each edited on its own row, reordered by dragging, and turned into another type from its handle. The core blocks are markdown — paragraphs, six heading levels, bulleted, numbered and to-do lists, quotes, code and dividers — so a document without plugins reads and copies as plain markdown.
+
+Everything else is a plugin. A plugin is a plain object (`BlockPlugin`) that names a block type and gives it:
+
+- 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…);
+- 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.
+
+## Installation
+
+```sh
+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) 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`. |
+
+## Host setup
+
+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 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.
+
+The preview adds only the little styling it needs itself (to-do checkboxes, image widths, floats). The typography of headings, paragraphs and lists comes from the page that shows the preview.
+
+## A first editor
+
+```svelte
+<script lang="ts">
+	import { Editor, Preview, type StoredBlock } from '@atom-forge/brickee';
+	import { PLUGINS } from '@atom-forge/brickee/plugins';
+
+	let value = $state<StoredBlock[]>([]);
+</script>
+
+<Editor bind:value plugins={PLUGINS} />
+
+<article>
+	<Preview blocks={value} plugins={PLUGINS} />
+</article>
+```
+
+- `value` is the document as JSON (`StoredBlock[]`). The editor writes it back on every change; save it as it is.
+- `plugins` lists the plugin blocks the editor can show and offer. Leave it out and you have a plain markdown editor.
+- `Preview` renders the same document with the same plugins, the way the site shows it.
+
+Type `/` in an empty line to open the block menu.
+
+## Entry points
+
+| Import | Contents |
+|---|---|
+| `@atom-forge/brickee` | `Editor`, `Preview`, the kit (`Frame`, `Empty`, helpers), the stored form, the markdown conversions, the contexts, the palette, the types. |
+| `@atom-forge/brickee/plugins` | The bundled plugins (`table`, `youtube`, `map`, `gap`), `PLUGINS` with all four, and their helpers. |
+| `@atom-forge/brickee/schema` | `blocksSchema` and `blocksSchemaFor` (zod), for server-side validation. |
+| `@atom-forge/brickee/model` | The stored form without Svelte: `StoredBlock`, `MD`, `isMd`, `acceptsId`, `blocksToPlainText`… |
+| `@atom-forge/brickee/locales/hu` | `hu`: the Hungarian UI text. |
+
+> **Only what you import is bundled**
+>
+> The bundled plugins live in their own entry point. An application that imports only `@atom-forge/brickee` gets the markdown editor without any plugin code.

package/docs/en/host-contexts.md

@@ -0,0 +1,169 @@
+# Host contexts
+
+[← Previous](writing-plugins.md) · [Contents](index.md) · [Next →](server-side.md)
+
+The editor has no props for application concepts. What a host knows — the page width it is showing, the code languages it highlights, its language — reaches the plugins through three Svelte contexts. Each has a `provide…` function, called in a component's initialization above the editor or preview, and a `use…` function for plugin components.
+
+| Context | Provide | Read | Carries |
+|---|---|---|---|
+| View | `provideView(() => key)` | `useView()` | The view per-view fields edit. |
+| Code languages | `provideCodeLanguages(() => list)` | `useCodeLanguages()` | The languages a code block offers. |
+| Text | `messages` prop, or `provideText(() => messages)` | `useText()` | UI text in the host's language. |
+
+Nested editors and previews inherit all three from their parent.
+
+Images are not a context: what an image block stores and where its pictures come from is decided by the app's own plugin (see [Images](writing-plugins.md#images)).
+
+## Per-view values
+
+Some settings depend on how the page is shown: an image may need a different aspect ratio on a phone than on a wide screen. A `slider` field with `views` stores a value per view. Here it is the height of the `photo` plugin from [Writing plugins](writing-plugins.md#images) and the bundled `gap`:
+
+```ts
+import type { BlockPlugin } from '@atom-forge/brickee';
+import { gap } from '@atom-forge/brickee/plugins';
+import { photo } from './photo';
+
+export const VIEWS = [
+	{ key: 'desktop', label: 'Desktop' },
+	{ key: 'tablet', label: 'Tablet' },
+	{ key: 'phone', label: 'Phone' }
+];
+
+/** The same plugin, with one of its fields set per view. */
+const perView = (plugin: BlockPlugin, key: string): BlockPlugin => ({
+	...plugin,
+	fields: plugin.fields?.map((f) => (f.key === key ? { ...f, views: VIEWS } : f))
+});
+
+export const plugins = [perView(photo, 'ratio'), perView(gap, 'lines')];
+```
+
+Which views exist and which one is shown is the host's business. The host tells the editor the current view with `provideView`, typically from a width switch beside the editor:
+
+```svelte
+<script lang="ts">
+	import { Editor, provideView, type StoredBlock } from '@atom-forge/brickee';
+	import { plugins } from './blocks';
+
+	let { value = $bindable(), view }: { value: StoredBlock[]; view: string } = $props();
+	provideView(() => view);
+</script>
+
+<Editor bind:value {plugins} />
+```
+
+How the values behave:
+
+- The first view is the **base**. Each other view, while it has no value of its own, takes the value of the view before it; the field then shows the value marked as inherited.
+- The field edits the value of the current view and shows that view's label beside its own. Without `provideView`, or with a key that is not in `views`, it edits the base value.
+- Stored: only a base value → stored alone, as a plain value (`"ratio": "56"`); own values for other views → an object keyed by view (`"ratio": { "desktop": "56", "phone": "100" }`). Documents written before a field became per-view stay valid.
+
+A preview reads them with `viewValues(value, keys)` — the value for each view, inheritance applied — or just the base with `baseValue(value)`. This version of the photo preview gives the browser one aspect ratio per width through CSS variables:
+
+```svelte
+<script lang="ts">
+	import { viewValues, type PluginPreviewProps } from '@atom-forge/brickee';
+	import { aspect, imageSrc, type PhotoProps } from './PhotoView.svelte';
+
+	let { props }: PluginPreviewProps<PhotoProps> = $props();
+	const src = $derived(imageSrc(props.url));
+	// desktop, tablet, phone: a CSS aspect-ratio each ('auto': the image's own shape)
+	const r = $derived(viewValues(props.ratio, ['desktop', 'tablet', 'phone']).map((v) => aspect(v) ?? 'auto'));
+</script>
+
+{#if src}
+	<img {src} alt={props.alt ?? ''} style:--r-desktop={r[0]} style:--r-tablet={r[1]} style:--r-phone={r[2]} />
+{/if}
+
+<style>
+	img {
+		width: 100%;
+		object-fit: cover;
+		aspect-ratio: var(--r-phone);
+	}
+	@media (min-width: 640px) {
+		img {
+			aspect-ratio: var(--r-tablet);
+		}
+	}
+	@media (min-width: 1024px) {
+		img {
+			aspect-ratio: var(--r-desktop);
+		}
+	}
+</style>
+```
+
+> **Sliders only**
+>
+> `views` is supported on `slider` fields. Other field kinds ignore it.
+
+## Code languages
+
+A code block's language (`props.lang`, the info string of its markdown fence) is free text by default. When the host knows which languages its site can highlight, it gives the list, and the field in the code block's fields bar becomes a dropdown of them, with *None* first:
+
+```svelte
+<script lang="ts">
+	import { Editor, provideCodeLanguages, type StoredBlock } from '@atom-forge/brickee';
+
+	let { value = $bindable() }: { value: StoredBlock[] } = $props();
+	provideCodeLanguages(() => [{ value: 'ts', label: 'TypeScript' }, { value: 'svelte', label: 'Svelte' }, 'css', 'bash']);
+</script>
+
+<Editor bind:value />
+```
+
+An item is a string or `{ value, label? }`; the value is what is stored. Nested editors inherit the list. A stored language missing from the list stays an option, so opening an older document loses nothing.
+
+## UI text
+
+The editor and the plugins are written in English, and the English text is the key of its translation. Pass `messages` — an object from English text to your language — to the top-level editor and preview:
+
+```svelte
+<script lang="ts">
+	import { Editor, type StoredBlock } from '@atom-forge/brickee';
+	import { PLUGINS } from '@atom-forge/brickee/plugins';
+	import { hu } from '@atom-forge/brickee/locales/hu';
+
+	let value = $state<StoredBlock[]>([]);
+</script>
+
+<Editor bind:value plugins={PLUGINS} messages={hu} />
+```
+
+`@atom-forge/brickee/locales/hu` exports `hu`, the Hungarian text of the editor and of every bundled plugin. Extend it with the text of your own plugins and fields:
+
+```ts
+import type { Messages } from '@atom-forge/brickee';
+import { hu } from '@atom-forge/brickee/locales/hu';
+
+export const messages: Messages = {
+	...hu,
+	Button: 'Gomb',
+	'A link as a button': 'Egy link gombként',
+	Desktop: 'Asztali',
+	Phone: 'Telefon'
+};
+```
+
+What the editor translates by itself:
+
+- the built-in and plugin `label`, `hint` and `keys` (the slash menu searches the English and the translated words);
+- the parts of a plugin's `tag`, split at ` · `;
+- field labels, placeholders, option labels, `none` labels and view labels;
+- the text of `Empty`, and the editor's own interface.
+
+Text a plugin renders itself — in its view or preview — goes through `useText()`:
+
+```svelte
+<script lang="ts">
+	import { useText, type PluginPreviewProps } from '@atom-forge/brickee';
+
+	let { props }: PluginPreviewProps = $props();
+	const tr = useText();
+</script>
+
+<p>{tr('Map: {place}', { place: String(props.q ?? '') })}</p>
+```
+
+`{name}` placeholders are filled from the second argument. Outside components, `translator(messages)` returns the same kind of function. A text missing from `messages` stays English.

package/docs/en/index.md

@@ -0,0 +1,38 @@
+# Brickee
+
+`@atom-forge/brickee` is a block editor for Svelte 5. Its core is a markdown block editor — paragraphs, headings, lists, to-dos, quotes, code, dividers — and every other block is a **plugin**: a block with an editor view, a site preview, its fields, and optionally a markdown form. Documents are stored as JSON.
+
+These pages are derived from the [Brickee book](https://books.atom-forge.eu), which is the source of truth. A Hungarian translation is in [`../hu/index.md`](../hu/index.md); a compact reference for coding agents is in [`README-AI.md`](../../README-AI.md).
+
+The package is built in three layers:
+
+```mermaid
+flowchart TB
+  core["Core: markdown blocks, Editor, Preview, stored form, kit"]
+  bundled["Bundled plugins: table, YouTube, map, gap"]
+  own["Your plugins: the same BlockPlugin shape"]
+  core --> bundled
+  core --> own
+```
+
+- **Core** (`@atom-forge/brickee`) — the markdown blocks, the `Editor` and the `Preview`, the stored form and its markdown conversions, and the **kit** plugins are written with. Without plugins it is a plain markdown block editor.
+- **Bundled plugins** (`@atom-forge/brickee/plugins`) — plugins like any other, written only with what the core exports. You opt in to the ones you need.
+- **Your plugins** — the same `BlockPlugin` shape, living in your application.
+
+The editor itself knows nothing about your application. Whatever an app needs — its page widths, its code languages, its language — reaches the plugins through **contexts** (view, code languages, text) or through plugin **fields**, never through special editor props. Images are no exception: an image block is a plugin of your own, which stores, picks and resolves its images the way your application does.
+
+## Contents
+
+1. [Getting started](getting-started.md) — the three layers, installation, host setup, and a first editor with its preview.
+2. [The editor and the preview](editor-and-preview.md) — the `Editor` and `Preview` props, the palette, the editing features, and scroll sync.
+3. [Documents and markdown](documents-and-markdown.md) — the stored form (`StoredBlock`), the built-in blocks, and converting from and to markdown.
+4. [Bundled plugins](bundled-plugins.md) — what `@atom-forge/brickee/plugins` contains, and how to override a preview or add fields.
+5. [Writing plugins](writing-plugins.md) — the `BlockPlugin` anatomy, fields, views and previews, containers, markdown forms, image blocks, and the kit.
+6. [Host contexts](host-contexts.md) — per-view values, code languages, and UI text.
+7. [On the server](server-side.md) — schema validation, plain text, and gated content.
+8. [Recipes and pitfalls](recipes-and-pitfalls.md) — complete patterns and the mistakes to avoid.
+9. [Upgrading](upgrading.md) — what to change in your code when you move to a newer version.
+
+The book also has an AI Notes chapter: instructions to copy into the agent instruction file of a project that uses the package.
+
+Svelte examples are complete components unless they say otherwise. Application values such as the current page width stand for whatever your application provides.