@atom-forge/brickee 0.0.0-stage → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.2] - 2026-11-10
+
+### Added
+
+- Showcase site in `src/routes` (`bun run dev`), styled like the `@atom-forge/ui` site: a playground (editor beside its preview, stored JSON and markdown), the guide (editor and preview, split view, markdown, stored form and schema), a page per bundled plugin, writing, nesting and overriding plugins, image blocks, and the host contexts (per-view values, code languages, localisation), each with live examples and their code. It resolves `@atom-forge/brickee` to the local source and prerenders to `build/` (`@sveltejs/adapter-static`); it is not part of the npm package.
+- A `toggles` field kind (`PropField`): a row of icon buttons, each switching one of `options` on or off (`options[].icon` is the button, `label` its tooltip), stored as the list of the ones on.
+- `provideCodeLanguages(() => list)` (with `useCodeLanguages` and the `CodeLanguage` type): a host context that turns a code block's language field into a dropdown of the given languages, with *None* first; without it the language stays free text. Nested editors inherit the list, and a stored language missing from it stays an option.
+
+### Changed
+
+- The fields bar is more compact: smaller controls and type, text fields show their label as the placeholder (with the field's own placeholder after it), the other fields a short label beside the control.
+- The table's header and footer rows are two icon toggles in its fields bar (a `toggles` field), like any plugin field; the toolbar above the table holds only the row and column tools of the cell being edited, and says to click a cell while none is. The info icon with the keyboard hint is gone.
+- The editor follows the host's light and dark mode: its colours (block fields, popups, frames, the table editor, the block actions) come from the `@atom-forge/ui` theme tokens with the former colours as fallbacks, and the props bar and the link prompt no longer force the light theme. The previews' table borders, video captions and the gap's stripes are drawn from the text colour.
+- A code block's language is edited in the same fields bar as a plugin's (its header shows `code · <language>`), instead of a small input in its corner; read-only, the corner still shows the language.
+- The block handles keep 1px free above and below, so the handles of neighbouring blocks do not touch.
+- The docs note that the block handles are drawn about 22 px left of the editor's box, so the element around it needs that much left padding.
+- Releases are configured with `ship-it init`: the publish workflow comes from Ship's template, `package.json` gains `pub-validate` and `publishConfig`, and npm Trusted Publishing lets CI publish the next versions.
+
+### Removed
+
+- **Breaking:** images and media are no longer the library's concept — whether a block stores a URL or an id, how the user picks an image and how it is resolved is the application's decision. Removed: the `image` and `images` field kinds with their picker, the `media` prop of `Editor` and `Preview`, `provideMedia`, `useMedia`, `findMedia`, the `MediaItem` type, `toMarkdown`'s `media` option and `MarkdownContext.media`. An image block is an app plugin that picks in its own view or dialog and resolves with the app's own data; stored documents are unaffected. See the upgrading chapter.
+
+## [0.0.1] - 2026-11-10
+
+### Added
+
+- The block editor, moved here from the gamer365 project (where it was the `block-editor` workspace package), as `@atom-forge/brickee`: the markdown core with the editor, the preview, the JSON stored form and the markdown conversions; the kit for writing plugins (`Frame`, `Empty`, block fields, media / view / text contexts, helpers); the bundled plugins in `@atom-forge/brickee/plugins` (general blocks only: YouTube, map, table, gap — the app-specific ones, such as boxes, callouts, images and the supporters-only divider, stay in the app that gave them their meaning); the zod schema in `@atom-forge/brickee/schema`; the Hungarian UI text in `@atom-forge/brickee/locales/hu`.
+- `BlockPlugin.preview` is optional: an app with its own renderer leaves it out, and `<Preview>` skips such blocks. The bundled plugins keep a default preview, which an app may use or replace.
+- An optional markdown form for plugins (`BlockPlugin.markdown`), used by `toMarkdown(blocks, { plugins, media })` and by copying in the editor; the bundled plugins have one where it makes sense (YouTube and map as a link, table as a GFM table).
+- Scroll sync: `scrollSync()` keeps a preview box scrolled to the same fraction as the editor's box (one way, also when the preview's content changes size; `use:sync.source` / `use:sync.target`, `align()`), with `scrollFraction` / `setScrollFraction` for keeping a position across a layout change. Proportional only: the two show roughly the same place, not the same block.
+- Repository frame following the AtomForge packages: agent instructions, book, English and Hungarian docs, `README-AI.md`, `TODO.md`, `notes/`, and a tag-triggered publish workflow with `@atom-forge/ship` 0.2.0 (installed from npm).
+
+---

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gergely Laborci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README-AI.md

@@ -0,0 +1,286 @@
+# @atom-forge/brickee — AI guide
+
+Compact reference for coding agents using `@atom-forge/brickee` in a Svelte 5 project. It is derived from [`docs/en/`](docs/en/index.md); where the two disagree, `docs/en/` is authoritative.
+
+Brickee is a block editor. Its core is a markdown block editor (`md:p`, `md:h1`…`md:h6`, `md:ul`, `md:ol`, `md:todo`, `md:quote`, `md:code`, `md:hr`) plus the kit plugins are written with; every other block is a plugin with an editor view, a site preview, fields and optionally a markdown form. Documents are stored as JSON (`StoredBlock[]`). The bundled plugins (`@atom-forge/brickee/plugins`) are plugins like any other, opt-in.
+
+## Rules
+
+- Peers: `svelte` 5, `@atom-forge/ui` (popups and field controls), `@lucide/svelte`; `zod` only for `@atom-forge/brickee/schema`. The app must set up `@atom-forge/ui` (Tailwind 4, its theme CSS and `@source`, the app beneath its `Root`).
+- Store the editor's `value` (`StoredBlock[]`) as it is. Built-in types start with `md:`; any other `type` is a plugin's. Never rename a plugin's `type`: stored documents refer to it.
+- Pass the same `plugins` to the `Editor` and the `Preview` of a document type. Restrict what an editor offers with `palette` (palette ids: `md:*` kinds and plugin types), not by dropping plugins.
+- The editor's colours come from the `@atom-forge/ui` theme tokens (light/dark follow the host). Its block handles sit ~22 px left of its box: leave that much left padding around it.
+- No app-specific editor props: app data reaches plugins through contexts (`provideView`, `provideCodeLanguages`, `messages` / `provideText`), plugin fields, or the app's own modules and contexts.
+- No image concept: no image field, picker or media list. An image block is an app plugin that stores what the app chooses (a URL, or an id of its own media library), picks it in its view or the app's own dialog, and resolves ids with the app's own data.
+- Plugin props are untrusted user input. Previews sanitize: `safeColor` for colours, check links and image addresses (`http(s)` or site-relative), clamp numbers, never `{@html}` with props.
+- A plugin view declares both `props` and `blocks` with `$bindable()`, even if unused.
+- Containers (`content: 'blocks'`) nest one level only; nested editors never offer containers or unique plugins. `accepts` narrows their content (`'md:*'` = every built-in).
+- `unique`: one per document, top level; not enforced by the schema. `gate`: the preview only *marks* blocks after it; hide gated content on the server.
+- `toMarkdown` and `toStored` use the DOM: browser only. `fromMarkdown`, `fromStored`, `inline`, the schema and `./model` run anywhere.
+- Validate saved documents on the server with `blocksSchemaFor(plugins)`; it checks shape and `accepts`, not known types, uniqueness or prop contents.
+- Scroll sync is proportional (same scroll fraction), one way, editor → preview; it needs no markup and shows roughly the same place, not the same block.
+- `<Preview>` is optional: the editor doesn't depend on it. An app with its own renderer can render `StoredBlock[]` itself and omit plugin `preview`s; bundled plugins ship a default preview you may use, replace (`{ ...youtube, preview: Mine }`) or ignore.
+- UI text: English source text is the key; pass `messages` (e.g. `hu` from `@atom-forge/brickee/locales/hu`, extended with your own keys) to the top editor/preview.
+
+## Public API
+
+```ts
+// @atom-forge/brickee — components
+// <Editor bind:value={StoredBlock[]} plugins?={BlockPlugin[]} palette?={string[]} messages?={Messages}
+//         readonly?={boolean} placeholder?={string} />   // `nested` is for Frame only
+// <Preview blocks={StoredBlock[]} plugins={BlockPlugin[]} messages?={Messages}
+//          markGated?={boolean /* default true */} nested?={boolean} />
+// <Frame bind:blocks {readonly} {palette} {plugins} heading?={string} empty?={string} image?={string} placeholder?={string} />
+// <Empty icon={Icon} text={string} />
+
+interface StoredBlock { type: string; indent: number; text?: string; props?: Record<string, unknown>; blocks?: StoredBlock[] }
+const MD = 'md:'; const MAX_INDENT = 6; const MAX_DEPTH = 2;
+function isMd(b: StoredBlock): boolean;
+function acceptsId(accepts: readonly string[] | undefined, id: string): boolean;
+function inlineToPlainText(md: string): string;
+function blocksToPlainText(blocks: StoredBlock[]): string;
+
+// markdown (Block = the editor's working form: { id, type, html, indent, checked?, props?, plugin?, blocks? })
+function inline(md: string): string;                 // inline markdown -> safe inline HTML
+function fromStored(s: StoredBlock): Block;
+function toStored(b: Block): StoredBlock;           // browser only
+function fromMarkdown(src: string): Block[];        // one block per non-empty line; built-in blocks only
+function toMarkdown(blocks: Block[], opts?: { plugins?: BlockPlugin[] }): string; // browser only
+
+// contexts (call provide* in component init, above the editor/preview; use* in plugin components)
+function provideView(get: () => string | undefined): void;
+function useView(): () => string | undefined;
+interface CodeLanguage { value: string; label?: string }      // value: stored as the code block's props.lang
+function provideCodeLanguages(own: () => (string | CodeLanguage)[] | undefined): void; // list: the language field is a dropdown
+function useCodeLanguages(): () => CodeLanguage[];             // empty: free text
+type Messages = Record<string, string>;
+type Translate = (text: string, vars?: Record<string, string | number>) => string; // fills {name}
+function provideText(own: () => Messages | undefined): void;
+function useText(): Translate;
+function translator(messages?: Messages): Translate;
+
+// scroll sync (editor -> preview, by scroll fraction)
+interface ScrollSync {
+	source: Action<HTMLElement>;                     // use:sync.source on the editor's scrolling box
+	target: Action<HTMLElement, boolean | undefined>; // use:sync.target={on} on the preview's (default on)
+	align(): void;                                   // re-sync now (e.g. after the preview width changed)
+}
+function scrollSync(): ScrollSync;
+function scrollFraction(box: HTMLElement): number;            // 0…1 (0 if it does not scroll)
+function setScrollFraction(box: HTMLElement, f: number): void;
+
+// palette
+interface PaletteItem { id: string; label: string; hint: string; keys: string; icon: Icon }
+const PALETTE_ITEMS: PaletteItem[]; const BUILT_IN_IDS: string[];
+function narrowPalette(palette: string[], accepts: readonly string[] | undefined): string[];
+
+// kit helpers
+function safeColor(c: unknown, fallback: string): string;   // #hex (3–8 digits) or fallback
+function lines(s: string): string[];                        // trimmed non-empty lines
+function baseValue(v: unknown): unknown;                    // base of a per-view prop
+function viewValues(v: unknown, keys: string[]): unknown[]; // per-view prop, inheritance applied
+function mdText(s: unknown): string;                        // plain text safe in markdown
+function mdJoin(...parts: (string | false | null | undefined)[]): string; // blank-line join, empties dropped
+function mdQuote(md: string): string;                       // '> ' every line
+
+// plugins
+interface BlockPlugin<P extends Props = Props> {
+	type: string;                // not 'md:'; schema: /^[a-z][a-z0-9:-]{0,39}$/
+	label: string; hint: string; keys: string; icon: Icon;
+	props: () => P;              // a new block's props
+	fields?: PropField[];
+	tag(props: P): string;       // mini label; ' · ' parts translated separately
+	content: 'none' | 'text' | 'plain' | 'blocks'; // plugins use 'none' or 'blocks'
+	view: Component<PluginViewProps<any>, {}, 'props' | 'blocks'>;
+	preview?: Component<PluginPreviewProps<any>>; // optional: without it <Preview> renders nothing for the block
+	accepts?: string[];          // container content as palette ids; 'md:*'
+	markdown?(props: P, ctx: MarkdownContext): string; // '' = left out
+	unique?: boolean;
+	gate?: boolean;
+}
+interface PluginViewProps<P> { props: P; blocks: StoredBlock[]; readonly: boolean; palette: string[]; plugins: BlockPlugin[] }
+interface PluginPreviewProps<P> { props: P; blocks: StoredBlock[]; plugins: BlockPlugin[] }
+interface MarkdownContext { inner: string }
+interface PropField {
+	key: string; label: string;
+	kind: 'text' | 'textarea' | 'color' | 'select' | 'slider' | 'toggles'; // toggles: icon buttons, stores the list of the ones on
+	placeholder?: string;
+	options?: { value: string; label: string; icon?: Icon }[]; // select; stepped slider (label may use {n}); toggles (icon + tooltip)
+	min?: number; max?: number; step?: number; unit?: string; // number slider (stored as string)
+	none?: string;                                // unset label (number slider notch, optional colour)
+	views?: { key: string; label: string }[];     // per-view slider values
+	format?: (value: unknown) => string;
+	parse?: (text: string) => unknown;            // '' / null removes the key
+}
+
+// @atom-forge/brickee/plugins
+// table, youtube, map, gap — the only bundled plugins (none holds nested blocks or images); PLUGINS = [table, youtube, map, gap]
+// types: TableProps, YouTubeProps, MapProps, GapProps, Head
+// helpers: youtubeId, mapSrc, gapLines, GAP_LINES, GAP_MAX, tableHeads, rowHead, HEADS, square
+// Image blocks, boxes and other containers are app plugins you write yourself (see docs/en/writing-plugins.md).
+
+// @atom-forge/brickee/schema (zod)
+const blocksSchema: ZodType<StoredBlock[]>;
+function blocksSchemaFor(plugins: readonly { type: string; accepts?: readonly string[] }[]): ZodType<StoredBlock[]>;
+
+// @atom-forge/brickee/model — StoredBlock, MD, MAX_INDENT, MAX_DEPTH, isMd, acceptsId, inlineToPlainText, blocksToPlainText
+// @atom-forge/brickee/locales/hu — hu: Messages
+```
+
+## Minimal example
+
+```svelte
+<script lang="ts">
+	import { Editor, Preview, 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} />
+<Preview blocks={value} plugins={PLUGINS} messages={hu} />
+```
+
+## Common extensions
+
+**Writing a plugin** — a props interface, a view, a preview, the object:
+
+```svelte
+<!-- ButtonView.svelte -->
+<script lang="ts" module>
+	export interface ButtonProps extends Record<string, unknown> { label: string; url: string; color: string }
+</script>
+<script lang="ts">
+	import { MousePointerClick } from '@lucide/svelte';
+	import { Empty, type PluginViewProps } from '@atom-forge/brickee';
+	let { props = $bindable(), blocks = $bindable() }: PluginViewProps<ButtonProps> = $props();
+</script>
+{#if props.label}<span>{props.label}</span>{:else}<Empty icon={MousePointerClick} text="Set the label and the link above" />{/if}
+```
+
+```svelte
+<!-- ButtonPreview.svelte -->
+<script lang="ts">
+	import { safeColor, type PluginPreviewProps } from '@atom-forge/brickee';
+	import type { ButtonProps } from './ButtonView.svelte';
+	let { props }: PluginPreviewProps<ButtonProps> = $props();
+	const href = $derived(/^(https?:|mailto:|\/(?!\/))/.test(String(props.url ?? '')) ? String(props.url) : '');
+</script>
+{#if href && props.label}<a {href} style:background={safeColor(props.color, '#2563eb')}>{props.label}</a>{/if}
+```
+
+```ts
+// button.ts
+import { MousePointerClick } from '@lucide/svelte';
+import { mdText, type BlockPlugin } from '@atom-forge/brickee';
+import ButtonView, { type ButtonProps } from './ButtonView.svelte';
+import ButtonPreview from './ButtonPreview.svelte';
+
+export const button: BlockPlugin<ButtonProps> = {
+	type: 'button', label: 'Button', hint: 'A link as a button', keys: 'button link cta', icon: MousePointerClick,
+	props: () => ({ label: '', url: '', color: '#2563eb' }),
+	fields: [
+		{ key: 'label', label: 'Label', kind: 'text' },
+		{ key: 'url', label: 'Link', kind: 'text', placeholder: 'https://…' },
+		{ key: 'color', label: 'Colour', kind: 'color' }
+	],
+	tag: () => 'button',
+	content: 'none',
+	markdown: (p) => (p.url ? `[${mdText(p.label)}](${p.url})` : ''),
+	view: ButtonView,
+	preview: ButtonPreview
+};
+```
+
+A **container** uses `content: 'blocks'`, `accepts`, `<Frame bind:blocks {readonly} {palette} {plugins} />` in its view and `<Preview {blocks} {plugins} nested />` in its preview; its `markdown` gets the inner blocks as `ctx.inner` (`mdQuote(mdJoin(title, inner))`).
+
+**Overriding a preview / adding fields** — spread the plugin, keep `type`:
+
+```ts
+import type { BlockPlugin } from '@atom-forge/brickee';
+import { map, youtube } from '@atom-forge/brickee/plugins';
+import SiteYouTube from './SiteYouTube.svelte'; // receives PluginPreviewProps<YouTubeProps>
+import SiteMap from './SiteMap.svelte';
+
+export const plugins: BlockPlugin[] = [
+	{ ...youtube, preview: SiteYouTube },
+	{
+		...map,
+		props: () => ({ ...map.props(), caption: '' }),
+		fields: [...(map.fields ?? []), { key: 'caption', label: 'Caption', kind: 'text' }],
+		preview: SiteMap
+	}
+];
+```
+
+**Markdown form and conversion** — `markdown(props, { inner })` returns markdown or `''`; use `mdText`, `mdJoin`, `mdQuote`. Whole document: `toMarkdown(doc.map(fromStored), { plugins })`; import: `fromMarkdown(text).map(toStored)` (both in the browser).
+
+**Per-view fields** — add `views` to a slider field and provide the current view:
+
+```ts
+import type { BlockPlugin } from '@atom-forge/brickee';
+
+const VIEWS = [{ key: 'desktop', label: 'Desktop' }, { key: 'phone', label: 'Phone' }];
+const perView = (p: BlockPlugin, key: string): BlockPlugin => ({ ...p, fields: p.fields?.map((f) => (f.key === key ? { ...f, views: VIEWS } : f)) });
+// host component around <Editor>: provideView(() => currentViewKey);
+// preview: const [desktop, phone] = viewValues(props.ratio, ['desktop', 'phone']);
+```
+
+Stored as the base value alone (`"56"`) or an object by view key (`{ "desktop": "56", "phone": "100" }`); a view without its own value inherits from the view before it.
+
+**Scroll sync (split view)** — one way, editor → preview, same scroll fraction; re-syncs on source scroll and target resize:
+
+```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 style="overflow-y: auto; height: 100vh" use:sync.source><Editor bind:value plugins={PLUGINS} /></div>
+<div style="overflow-y: auto; height: 100vh" use:sync.target><Preview blocks={value} plugins={PLUGINS} /></div>
+```
+
+Keep the place across a layout change: `const f = scrollFraction(box); change(); await tick(); setScrollFraction(box, f);`.
+
+**Server validation**:
+
+```ts
+import { blocksSchemaFor } from '@atom-forge/brickee/schema';
+const result = blocksSchemaFor(plugins).safeParse(input); // or pass [{ type, accepts }] only
+```
+
+## Pitfalls
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Fields and popups unstyled | `@atom-forge/ui` theme CSS / `@source` missing | Set up `@atom-forge/ui`; render beneath its `Root`. |
+| Block handles stick out on the left | Handles are drawn ~22 px left of the editor's box | Give the editor's container ~22 px left padding. |
+| Context errors with a linked local copy | Duplicate `svelte` / `@atom-forge/ui` | Vite `resolve.dedupe: ['svelte', '@atom-forge/ui', '@lucide/svelte', 'zod']`. |
+| A block is missing from `<Preview>` | Its plugin has no `preview` | Add one (bundled plugins have a default) or render it yourself. |
+| "Unknown block" in the editor, block missing on the site | Plugin missing from `plugins` | Same plugins for editor and preview. |
+| Image block renders nothing | Preview rejects the stored address, or the app's lookup lacks the id | Store `http(s)` / site-relative addresses; resolve ids from the same app data everywhere. |
+| `media` prop, `useMedia`, `findMedia`, `kind: 'image'` missing | Removed: images are the app's business | Own picking and lookup in the app's image plugin (see `docs/en/upgrading.md`). |
+| Box not offered inside a box | One nesting level | By design. |
+| Block not offered inside a container | `accepts` or host `palette` excludes it | Add its palette id (or `'md:*'`). |
+| Gated content visible to all | `gate` only marks | Cut the document on the server. |
+| `document is not defined` | `toMarkdown` / `toStored` during SSR | Call in the browser. |
+| Injected colour / link | Props rendered unchecked | `safeColor`, link checks, no `{@html}`. |
+| Override loses its blocks | `type` changed | Keep `type`. |
+| Bind error in a custom view | `props` / `blocks` not `$bindable()` | Declare both bindable. |
+| Value is never `[]` after mount | An empty document is one empty paragraph | Test emptiness with `blocksToPlainText(doc).trim() === ''`. |
+| Preview does not follow the editor | Actions not on the scrolling boxes | Put them on the `overflow` boxes. |
+| `image`, `callout`, `locked`… not exported from `/plugins` | Only `table`, `youtube`, `map`, `gap` are bundled | Keep app-owned copies with the same `type` (see `docs/en/upgrading.md`). |
+| `safeColor` import fails from `/plugins` | Kit helpers live in the core | Import from `@atom-forge/brickee`. |
+
+## Documentation map
+
+In the installed package (`node_modules/@atom-forge/brickee/`):
+
+- [`docs/en/index.md`](docs/en/index.md) — full English documentation, one page per chapter: [getting started](docs/en/getting-started.md), [editor and preview](docs/en/editor-and-preview.md), [documents and markdown](docs/en/documents-and-markdown.md), [bundled plugins](docs/en/bundled-plugins.md), [writing plugins](docs/en/writing-plugins.md), [host contexts](docs/en/host-contexts.md), [on the server](docs/en/server-side.md), [recipes and pitfalls](docs/en/recipes-and-pitfalls.md), [upgrading](docs/en/upgrading.md). Authoritative.
+- [`docs/hu/index.md`](docs/hu/index.md) — Hungarian translation.
+- [`CHANGELOG.md`](CHANGELOG.md) — release history.
+- `dist/index.d.ts`, `dist/plugins/index.d.ts` — the exported types of the installed version; `dist/plugins/` — the bundled plugins' source, useful as plugin examples.
+
+The book at https://books.atom-forge.eu is the source of these docs and adds the AI Notes chapter: instructions to copy into your project's agent instruction file. To develop the package itself, follow `AGENTS.md` in the repository.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# Brickee
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@atom-forge/brickee` is a block editor for Svelte 5. Its core is a markdown block editor — paragraphs, headings, lists, todos, quotes, code, rules — and everything else is a plugin: a block with an editor view, a site preview, its fields, and optionally a markdown form. Documents are stored as JSON.
+
+- **Core** — the markdown blocks and the kit plugins are written with. Without plugins it is a plain markdown block editor.
+- **Bundled plugins** (`@atom-forge/brickee/plugins`) — a few general blocks: YouTube, map, table, gap. Plugins like any other: pick the ones you need.
+- **Your plugins** — the same `BlockPlugin` shape, in your app.
+
+## Install
+
+```sh
+bun add @atom-forge/brickee @atom-forge/ui @lucide/svelte
+```
+
+`svelte` 5, `@atom-forge/ui` (popups and form controls; your app needs its theme CSS) and `@lucide/svelte` are peer dependencies; `zod` is an optional one for the server-side schema.
+
+## Example
+
+```svelte
+<script lang="ts">
+	import { Editor, Preview, 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} />
+<Preview blocks={value} plugins={PLUGINS} />
+```
+
+## Documentation
+
+- [The Brickee book](https://books.atom-forge.eu) — concepts, plugins, recipes, and pitfalls.
+- [English docs](docs/en/index.md) · [Magyar dokumentáció](docs/hu/index.md)
+- [README-AI.md](README-AI.md) — compact reference for coding agents.
+
+Developing Brickee itself starts in [AGENTS.md](AGENTS.md).
+
+## License
+
+MIT