@atom-forge/brickee 0.0.0-stage → 0.0.1

package/docs/en/host-contexts.md

@@ -0,0 +1,275 @@
+# 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 — its images, the page width it is showing, 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 |
+|---|---|---|---|
+| Media | `media` prop, or `provideMedia(() => list)` | `useMedia()` | The images blocks can pick from. |
+| View | `provideView(() => key)` | `useView()` | The view per-view fields edit. |
+| Text | `messages` prop, or `provideText(() => messages)` | `useText()` | UI text in the host's language. |
+
+Nested editors and previews inherit all three from their parent.
+
+## Media
+
+Blocks never store image URLs. An image field stores the **id** of a `MediaItem`, and the editor, the preview and the plugins look the item up in the document's media:
+
+```ts
+interface MediaItem {
+	id: string; // stored in the block's props
+	name: string; // file name or title, shown in the picker
+	url: string; // the image's address
+	group?: string; // a heading in the picker (e.g. the attachment category)
+}
+```
+
+The bundled plugins use no images; image blocks are yours to write, because their layout is the site's. A minimal `photo` plugin — an image field, alt text, and a height slider:
+
+```svelte
+<!-- PhotoView.svelte -->
+<script lang="ts" module>
+	export interface PhotoProps extends Record<string, unknown> {
+		/** A MediaItem id. */
+		image: string;
+		alt: string;
+		/** The height in % of the width (20–150), or unset for the image's own shape. */
+		ratio?: unknown;
+	}
+
+	/** A CSS aspect-ratio from a stored height, or undefined. */
+	export const aspect = (v: unknown) => {
+		const n = Number(v);
+		return n >= 20 && n <= 150 ? `100 / ${n}` : undefined;
+	};
+</script>
+
+<script lang="ts">
+	import { ImageIcon } from '@lucide/svelte';
+	import { Empty, findMedia, useMedia, type PluginViewProps } from '@atom-forge/brickee';
+
+	let { props = $bindable(), blocks = $bindable() }: PluginViewProps<PhotoProps> = $props();
+	const media = useMedia();
+	const item = $derived(findMedia(media(), props.image));
+</script>
+
+{#if item}
+	<img src={item.url} alt={props.alt} style="max-width: 100%" />
+{:else}
+	<Empty icon={ImageIcon} text="Pick an image above" />
+{/if}
+```
+
+```svelte
+<!-- PhotoPreview.svelte -->
+<script lang="ts">
+	import { baseValue, findMedia, useMedia, type PluginPreviewProps } from '@atom-forge/brickee';
+	import { aspect, type PhotoProps } from './PhotoView.svelte';
+
+	let { props }: PluginPreviewProps<PhotoProps> = $props();
+	const media = useMedia();
+	const item = $derived(findMedia(media(), props.image));
+</script>
+
+{#if item}
+	<img src={item.url} alt={props.alt ?? ''} style:aspect-ratio={aspect(baseValue(props.ratio))} />
+{/if}
+
+<style>
+	img {
+		width: 100%;
+		object-fit: cover;
+	}
+</style>
+```
+
+```ts
+// photo.ts
+import { ImageIcon } from '@lucide/svelte';
+import { findMedia, mdText, type BlockPlugin } from '@atom-forge/brickee';
+import PhotoView, { type PhotoProps } from './PhotoView.svelte';
+import PhotoPreview from './PhotoPreview.svelte';
+
+export const photo: BlockPlugin<PhotoProps> = {
+	type: 'photo',
+	label: 'Photo',
+	hint: 'One picked image',
+	keys: 'photo image picture',
+	icon: ImageIcon,
+	props: () => ({ image: '', alt: '' }),
+	fields: [
+		{ key: 'image', label: 'Image', kind: 'image' },
+		{ key: 'alt', label: 'Alt text', kind: 'text', placeholder: 'What the image shows' },
+		{ key: 'ratio', label: 'Height', kind: 'slider', min: 20, max: 150, unit: '%', none: 'Original' }
+	],
+	tag: () => 'photo',
+	content: 'none',
+	markdown: (p, { media }) => {
+		const url = findMedia(media, p.image)?.url;
+		return url ? `![${mdText(p.alt)}](${url})` : '';
+	},
+	view: PhotoView,
+	preview: PhotoPreview
+};
+```
+
+Give the editor and the preview the same media:
+
+```svelte
+<script lang="ts">
+	import { Editor, Preview, type MediaItem, type StoredBlock } from '@atom-forge/brickee';
+	import { photo } from './photo';
+
+	let { value = $bindable(), media }: { value: StoredBlock[]; media: MediaItem[] } = $props();
+</script>
+
+<Editor bind:value plugins={[photo]} {media} />
+<Preview blocks={value} plugins={[photo]} {media} />
+```
+
+In a plugin component, read the list with `useMedia()` — it returns a function, so the list stays current — and find an item with `findMedia(list, id)`, as the photo's view and preview do.
+
+> **Thumbnails in the editor**
+>
+> The editor only needs small images. Because blocks store ids, you can give the editor a list of thumbnail URLs and the preview on the site a list of full-size URLs with the same ids.
+
+Typical sources are a page's uploaded attachments or a media library. Every image a document refers to must be in the list, or its block renders nothing.
+
+## 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:
+
+```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 { findMedia, useMedia, viewValues, type PluginPreviewProps } from '@atom-forge/brickee';
+	import { aspect, type PhotoProps } from './PhotoView.svelte';
+
+	let { props }: PluginPreviewProps<PhotoProps> = $props();
+	const media = useMedia();
+	const item = $derived(findMedia(media(), props.image));
+	// 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 item}
+	<img src={item.url} 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.
+
+## 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 images, its page widths, its language — reaches the plugins through **contexts** (media, view, text) or through plugin **fields**, never through special editor props.
+
+## 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, and the kit.
+6. [Host contexts](host-contexts.md) — media, per-view values, 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 list of images or the current page width stand for whatever your application provides.

package/docs/en/recipes-and-pitfalls.md

@@ -0,0 +1,122 @@
+# Recipes and pitfalls
+
+[← Previous](server-side.md) · [Contents](index.md) · [Next →](upgrading.md)
+
+## One place for the block setup
+
+Keep the plugins, palettes and messages of an application in one module, and wrap the editor in a component of your own. Pages then use the wrapper and never repeat the setup.
+
+```ts
+// lib/blocks.ts
+import type { BlockPlugin, Messages } from '@atom-forge/brickee';
+import * as base from '@atom-forge/brickee/plugins';
+import { hu } from '@atom-forge/brickee/locales/hu';
+import SiteYouTube from './SiteYouTube.svelte';
+import { photo } from './photo';
+import { button } from './button';
+
+const withPreview = (plugin: BlockPlugin, preview: BlockPlugin['preview']): BlockPlugin => ({ ...plugin, preview });
+
+export const plugins: BlockPlugin[] = [
+	withPreview(base.youtube, SiteYouTube),
+	base.table,
+	base.map,
+	base.gap,
+	photo,
+	button
+];
+
+/** The full palette, for editors of the site's own pages. */
+export const PAGE_PALETTE = ['md:p', 'md:h2', 'md:h3', 'md:ul', 'md:ol', 'md:quote', 'md:hr', ...plugins.map((p) => p.type)];
+
+/** A smaller one, for user comments. */
+export const COMMENT_PALETTE = ['md:p', 'md:ul', 'md:ol', 'md:quote', 'photo'];
+
+export const messages: Messages = { ...hu, Button: 'Gomb', 'A link as a button': 'Egy link gombként' };
+```
+
+```svelte
+<!-- lib/BlockEditor.svelte -->
+<script lang="ts">
+	import { Editor, provideView, type MediaItem, type StoredBlock } from '@atom-forge/brickee';
+	import { messages, PAGE_PALETTE, plugins } from './blocks';
+
+	let {
+		value = $bindable(),
+		media = [],
+		palette = PAGE_PALETTE,
+		view
+	}: { value: StoredBlock[]; media?: MediaItem[]; palette?: string[]; view?: string } = $props();
+
+	provideView(() => view);
+</script>
+
+<Editor bind:value {plugins} {palette} {media} {messages} />
+```
+
+Render the published page with `<Preview blocks={doc} {plugins} {media} {messages} />` and the same `plugins`, so a block looks the same in the editor's preview and on the site.
+
+## Copying the whole document as markdown
+
+Copying selected blocks already puts markdown on the clipboard. For a "Copy as markdown" button for the whole document:
+
+```svelte
+<script lang="ts">
+	import { fromStored, toMarkdown, type MediaItem, type StoredBlock } from '@atom-forge/brickee';
+	import { plugins } from './blocks';
+
+	let { doc, media = [] }: { doc: StoredBlock[]; media?: MediaItem[] } = $props();
+
+	// Runs in a click handler, so the browser-only toMarkdown is safe here.
+	const copy = () => navigator.clipboard.writeText(toMarkdown(doc.map(fromStored), { plugins, media }));
+</script>
+
+<button type="button" onclick={copy}>Copy as markdown</button>
+```
+
+## Starting a document from markdown
+
+```ts
+import { fromMarkdown, toStored, type StoredBlock } from '@atom-forge/brickee';
+
+// In the browser: toStored reads the inline HTML through the DOM.
+export const fromText = (text: string): StoredBlock[] => fromMarkdown(text).map(toStored);
+```
+
+Remember that every non-empty line becomes its own block.
+
+## Developing against a local copy
+
+When you link a local checkout of the package into an application (`bun link`), the linked folder brings its own `node_modules`. Make Vite use the application's single copy of the shared packages, otherwise Svelte contexts — the popup manager, the theme — are not found across the two copies:
+
+```ts
+// vite.config.ts of the application
+export default defineConfig({
+	plugins: [sveltekit()],
+	resolve: {
+		dedupe: ['svelte', '@atom-forge/ui', '@lucide/svelte', 'zod']
+	}
+});
+```
+
+The application reads the package's built `dist/`, so rebuild the package after each change.
+
+## Pitfalls
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Block fields and popups look unstyled | The `@atom-forge/ui` theme CSS or its Tailwind `@source` is missing | Set up `@atom-forge/ui` as its documentation describes and render the app beneath its `Root`. |
+| Popups do not open, or "context not found" errors with a linked package | Two copies of `svelte` or `@atom-forge/ui` | Add them to Vite's `resolve.dedupe`. |
+| A plugin block shows "Unknown block" | Its plugin is missing from `plugins` | Pass the same plugins to every editor and preview of a document type. |
+| A block is missing from `Preview` | Its plugin has no `preview` | Give the plugin a `preview` (the bundled ones have a default), or render the block with your own renderer. |
+| A plugin block is missing from the site | The preview got other `plugins`, or the image id is not in `media` | Use the same plugin list and media for the editor and the preview. |
+| A box cannot be put inside another box | Nested editors go one level deep | Design containers to hold content blocks, not other containers. |
+| A block is not offered inside a container | Its `accepts` or the host `palette` leaves it out | Add the palette id to `accepts` (or use `'md:*'` for every built-in). |
+| A unique block appears twice | The schema does not enforce `unique` | Check it on the server if your application relies on it. |
+| Gated content visible to everyone | `gate` only marks the blocks | Cut the document on the server before rendering. |
+| `document is not defined` | `toMarkdown` or `toStored` ran during SSR | Call them in the browser only. |
+| A colour or link from props breaks the page | Props are user input | Use `safeColor`, check links, never use `{@html}` with props. |
+| Overridden plugin loses its blocks | Its `type` was changed | Keep `type` when spreading a plugin. |
+| `bind:blocks` error in a custom view | `props` or `blocks` not declared bindable | Declare both with `$bindable()`. |
+| The value is never an empty array | The editor shows (and writes) one empty paragraph for an empty document | Treat a document with only empty paragraphs as empty, for example with `blocksToPlainText(doc).trim() === ''`. |
+| The preview does not follow the editor's scrolling | The actions are not on the boxes that scroll | Put `use:sync.source` / `use:sync.target` on the `overflow` boxes themselves. |

package/docs/en/server-side.md

@@ -0,0 +1,95 @@
+# On the server
+
+[← Previous](host-contexts.md) · [Contents](index.md) · [Next →](recipes-and-pitfalls.md)
+
+A stored document is JSON sent by the browser, so the server must check it before saving. Two entry points have no Svelte dependency and are meant for server code:
+
+- `@atom-forge/brickee/model` — `StoredBlock`, `MD`, `MAX_INDENT`, `MAX_DEPTH`, `isMd`, `acceptsId`, `inlineToPlainText`, `blocksToPlainText`;
+- `@atom-forge/brickee/schema` — `blocksSchema` and `blocksSchemaFor`, built with `zod` (an optional peer dependency: install it to use this entry point).
+
+## Validating a document
+
+```ts
+// content.server.ts
+import { blocksSchemaFor } from '@atom-forge/brickee/schema';
+import { plugins } from '$lib/blocks';
+
+const contentSchema = blocksSchemaFor(plugins);
+
+export function parseContent(input: unknown) {
+	const result = contentSchema.safeParse(input);
+	if (!result.success) throw new Error('Invalid content');
+	return result.data; // StoredBlock[]
+}
+```
+
+`blocksSchema` checks the shape of any document; `blocksSchemaFor(plugins)` adds the containers' `accepts` lists. It needs only `type` and `accepts` of each plugin, so a server that does not want to import the plugin components can pass those alone:
+
+```ts
+const contentSchema = blocksSchemaFor([
+	{ type: 'note', accepts: ['md:*', 'youtube'] },
+	{ type: 'youtube' }
+]);
+```
+
+What the schema checks:
+
+| Rule | Limit |
+|---|---|
+| Block keys | `type`, `indent`, `text`, `props`, `blocks` only (strict objects). |
+| `type` | `^[a-z][a-z0-9:-]{0,39}$` |
+| `indent` | An integer, 0–6. |
+| `text` | At most 100 000 characters. |
+| `props` | Keys up to 60 characters, JSON values. |
+| `blocks` | At most 500 nested blocks per container, one level deep only. |
+| Document | At most 2000 top-level blocks and 1 000 000 characters as JSON. |
+| `accepts` (`blocksSchemaFor`) | Every nested block is one its container takes. |
+
+What it does **not** check: whether a type is known, whether a unique block appears once, and what the props contain. Add your own refinements for the rules your application relies on — for example, to reject unknown block types:
+
+```ts
+import type { StoredBlock } from '@atom-forge/brickee/model';
+import { blocksSchemaFor } from '@atom-forge/brickee/schema';
+import { plugins } from '$lib/blocks';
+
+const BUILT_IN = ['md:p', 'md:h1', 'md:h2', 'md:h3', 'md:h4', 'md:h5', 'md:h6', 'md:ul', 'md:ol', 'md:todo', 'md:quote', 'md:code', 'md:hr'];
+const known = new Set([...BUILT_IN, ...plugins.map((p) => p.type)]);
+const allKnown = (list: StoredBlock[]): boolean => list.every((b) => known.has(b.type) && allKnown(b.blocks ?? []));
+
+export const contentSchema = blocksSchemaFor(plugins).refine(allKnown, 'Unknown block type.');
+```
+
+> **Shape, not safety**
+>
+> The schema keeps documents well-formed and bounded; it does not make props safe to render. The renderers escape every text and keep links to safe schemes, and each plugin preview must sanitize its own props (see [Writing plugins](writing-plugins.md)).
+
+## Plain text
+
+`blocksToPlainText(blocks)` collects every text of a document in order, separated by blank lines: block texts with their marks and link targets removed, string props that contain whitespace (titles, captions — not ids or colours), table rows, and nested blocks. Use it for search indexes, leads and meta descriptions. `inlineToPlainText(md)` does the same for a single inline markdown string.
+
+```ts
+import { blocksToPlainText, type StoredBlock } from '@atom-forge/brickee/model';
+
+export const description = (doc: StoredBlock[]) => blocksToPlainText(doc).slice(0, 160);
+```
+
+## Rendering
+
+`Preview` is an ordinary Svelte component and can be server-rendered; the core renderer and the bundled previews use no browser APIs. Only the markdown export path (`toMarkdown`, `toStored`) needs the browser.
+
+## Gated content
+
+A gate block (a plugin with `gate: true`, such as a supporters-only divider) only makes the preview mark the blocks after it. To keep the gated part from readers who may not see it, cut the document on the server before it reaches the page:
+
+```ts
+import type { StoredBlock } from '@atom-forge/brickee/model';
+
+/** The document up to and including the first gate block, for readers without access. */
+export function publicPart(doc: StoredBlock[], gateTypes: string[], canRead: boolean): StoredBlock[] {
+	if (canRead) return doc;
+	const at = doc.findIndex((b) => gateTypes.includes(b.type));
+	return at < 0 ? doc : doc.slice(0, at + 1);
+}
+```
+
+Call it with your gate plugin types (for example `['paywall']`) and the reader's access. Readers without access see the content up to the gate block and its teaser; readers with access get the whole document, and the preview marks the gated part for them.

package/docs/en/upgrading.md

@@ -0,0 +1,55 @@
+# Upgrading
+
+[← Previous](recipes-and-pitfalls.md) · [Contents](index.md)
+
+This chapter lists the changes that may require action when you move to a newer version of `@atom-forge/brickee`. Each section covers one version step, newest first, and each change ends with a **What to do:** paragraph.
+
+Changes that need no action from you — new exports, fixes, documentation updates — are listed only in the changelog (`CHANGELOG.md`, shipped with the package).
+
+> **No migration needed yet**
+>
+> `@atom-forge/brickee` has not had a release that requires changes in code using it. The section below is only for applications that used the editor before it became this package.
+
+## From the `block-editor` workspace package to Unreleased
+
+The editor started as `block-editor`, a workspace package inside an application. It moved here as `@atom-forge/brickee` with the same stored form, so saved documents need no conversion. The import specifiers changed, the plugin kit moved from the plugins entry point into the core, and the site-specific plugins stayed with the application.
+
+### Package name and entry points
+
+| Before | After |
+|---|---|
+| `block-editor` | `@atom-forge/brickee` |
+| `block-editor/plugins` | `@atom-forge/brickee/plugins` |
+| `block-editor/locales/hu` | `@atom-forge/brickee/locales/hu` |
+
+**What to do:** replace the dependency (`"block-editor": "workspace:*"` → `"@atom-forge/brickee"`) and rename the imports. Install `@atom-forge/ui` and `@lucide/svelte` as dependencies of the application if they are not already, and `zod` if you use the schema.
+
+### The kit lives in the core
+
+`Frame`, `Empty` and the plugin helpers are exported from the core entry point. `safeColor`, `viewValues`, `baseValue` and `lines` are no longer exported from the plugins entry point.
+
+```ts
+// Before
+import { safeColor, viewValues } from 'block-editor/plugins';
+
+// After
+import { safeColor, viewValues } from '@atom-forge/brickee';
+```
+
+**What to do:** import `Frame`, `Empty`, `safeColor`, `viewValues`, `baseValue`, `lines`, `mdText`, `mdJoin` and `mdQuote` from `@atom-forge/brickee`. The helpers of the bundled plugins that remain (`youtubeId`, `mapSrc`, `gapLines`, `tableHeads`…) stay in `@atom-forge/brickee/plugins`.
+
+### Site-specific plugins are no longer in the package
+
+The package now bundles only four general-purpose plugins: `table`, `youtube`, `map` and `gap` (`PLUGINS` holds these four). The other plugins of `block-editor/plugins` and their helpers were application-specific and are not part of `@atom-forge/brickee`:
+
+| Removed | Kind |
+|---|---|
+| `richBox`, `feature`, `sideBox`, `callout`, `spoiler`, `faq`, `imageText` | container plugins |
+| `image`, `gallery`, `tweet`, `form`, `banner`, `locked` | plugins |
+| `CALLOUTS`, `calloutTone`, `CalloutTone`, `questions`, `formEmbed`, `formHeight` | their helpers |
+| `postId`, `userName`, `RATIO_MIN`, `RATIO_MAX`, `ratioPercent`, `ratio` | helpers of the former `plugins/util` |
+| `ImageProps`, `GalleryProps`, `CalloutProps` and the other props types of these plugins | types |
+
+The stored form is unchanged: documents that contain these block types stay valid, as long as the application still passes plugins with the same `type` values to the editor and the preview.
+
+**What to do:** if the application uses any of these plugins, keep its own copy of them (their views, previews and helpers) in the application, written against the core kit, and add them to its plugin list with the same `type`. Import the four remaining plugins and their helpers from `@atom-forge/brickee/plugins` as before. Add the UI text of the copied plugins to your `messages`: `@atom-forge/brickee/locales/hu` no longer contains it.