@atom-forge/brickee 0.0.0-stage → 0.0.1

package/docs/hu/getting-started.md

@@ -0,0 +1,81 @@
+# Első lépések
+
+[Tartalom](index.md) · [Következő →](editor-and-preview.md)
+
+## Mi a Brickee
+
+A Brickee blokkszerkesztő: a dokumentum blokkok listája, mindegyik a saját sorában szerkeszthető, húzással átrendezhető, és a fogantyújáról más típusúvá alakítható. A magban lévő blokkok markdown blokkok — bekezdések, hat címsorszint, felsorolás, számozott lista és teendőlista, idézetek, kód és elválasztók —, így egy pluginok nélküli dokumentum sima markdownként olvasható és másolható.
+
+Minden más plugin. A plugin egy egyszerű objektum (`BlockPlugin`), amely megnevez egy blokktípust, és a következőket adja hozzá:
+
+- egy **nézetet** — a szerkesztőben megjelenő Svelte-komponenst;
+- egy **előnézetet** — a blokkot az oldalon megjelenítő Svelte-komponenst;
+- **mezőket** — a blokk tetején megjelenő beállításokat (szöveg, szín, választó, csúszka, kép…);
+- opcionálisan egy **markdown alakot**, amelyet a dokumentum markdownként való másolásakor vagy exportálásakor használ.
+
+A csomag négy általános plugint is tartalmaz — táblázat, YouTube-videó, térkép és térköz —, de ezek is ugyanolyan pluginok, mint bármelyik más: a magban semmi sem függ tőlük, és csak azokat adod át, amelyeket szeretnél. A képblokkokat, dobozokat és más, az oldalra jellemző blokkokat te írod meg pluginként.
+
+## Telepítés
+
+```sh
+bun add @atom-forge/brickee @atom-forge/ui @lucide/svelte
+```
+
+| Peer dependency | Miért |
+|---|---|
+| `svelte` `^5.0.0` | A szerkesztő, az előnézet és a pluginok Svelte 5 komponensek. |
+| `@atom-forge/ui` `>=0.0.37` | A felugró ablakok (linkbekérő, képválasztó) és a blokkmezők űrlapvezérlői. |
+| `@lucide/svelte` `>=1.0.0` | A blokkok ikonjai. |
+| `zod` `^4.0.0` (opcionális) | Csak az `@atom-forge/brickee/schema` szerveroldali sémájához. |
+
+## A befogadó alkalmazás beállítása
+
+A blokkmezők és a felugró ablakok `@atom-forge/ui` komponensek, ezért az alkalmazást úgy kell beállítani, ahogy az `@atom-forge/ui` megköveteli:
+
+- Tailwind CSS 4, importált `@atom-forge/ui` téma-CSS-sel, a `dist` mappáját pedig add hozzá Tailwind `@source`-ként;
+- az alkalmazás az `@atom-forge/ui` `Root` komponense alatt renderelődjön, amely a témát és az overlay-kontextusokat biztosítja.
+
+A legfelső szintű `Editor` saját felugróablak-kezelőt hoz létre, és saját felugróablak-tárolót renderel; a pluginblokkokba ágyazott szerkesztők ezt használják közösen.
+
+> **Hiányzó téma**
+>
+> Az `@atom-forge/ui` téma-CSS nélkül a szerkesztő továbbra is működik, de a blokkmezők, a színválasztó, a csúszka és a felugró ablakok stílus nélkül jelennek meg.
+
+Az előnézet csak azt a kevés stílust adja hozzá, amelyre saját magának szüksége van (teendő-jelölőnégyzetek, képszélességek, körbefuttatás). A címsorok, bekezdések és listák tipográfiája az előnézetet megjelenítő oldalról jön.
+
+## Egy első szerkesztő
+
+```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>
+```
+
+- A `value` a dokumentum JSON-ként (`StoredBlock[]`). A szerkesztő minden változáskor visszaírja; mentsd el úgy, ahogy van.
+- A `plugins` felsorolja azokat a pluginblokkokat, amelyeket a szerkesztő megjeleníthet és felkínálhat. Ha elhagyod, egyszerű markdown-szerkesztőt kapsz.
+- A `Preview` ugyanazt a dokumentumot ugyanazokkal a pluginokkal rendereli, úgy, ahogy az oldal megjeleníti.
+
+Üres sorban gépelj `/` jelet a blokkmenü megnyitásához.
+
+## Belépési pontok
+
+| Import | Tartalom |
+|---|---|
+| `@atom-forge/brickee` | `Editor`, `Preview`, a kit (`Frame`, `Empty`, segédfüggvények), a tárolt alak, a markdown-átalakítások, a kontextusok, a paletta, a típusok. |
+| `@atom-forge/brickee/plugins` | A mellékelt pluginok (`table`, `youtube`, `map`, `gap`), a mind a négyet tartalmazó `PLUGINS` és a segédfüggvényeik. |
+| `@atom-forge/brickee/schema` | `blocksSchema` és `blocksSchemaFor` (zod), szerveroldali validáláshoz. |
+| `@atom-forge/brickee/model` | A tárolt alak Svelte nélkül: `StoredBlock`, `MD`, `isMd`, `acceptsId`, `blocksToPlainText`… |
+| `@atom-forge/brickee/locales/hu` | `hu`: a magyar felületi szövegek. |
+
+> **Csak az kerül a bundle-be, amit importálsz**
+>
+> A mellékelt pluginok saját belépési ponton érhetők el. Az az alkalmazás, amely csak az `@atom-forge/brickee`-t importálja, a markdown-szerkesztőt kapja, pluginkód nélkül.

package/docs/hu/host-contexts.md

@@ -0,0 +1,275 @@
+# Az alkalmazás kontextusai
+
+[← Előző](writing-plugins.md) · [Tartalom](index.md) · [Következő →](server-side.md)
+
+A szerkesztőnek nincsenek propjai az alkalmazás fogalmaihoz. Amit a befogadó alkalmazás tud — a képeit, az éppen mutatott oldalszélességet, a nyelvét —, az három Svelte-kontextuson keresztül jut el a pluginokhoz. Mindegyikhez tartozik egy `provide…` függvény, amelyet a szerkesztő vagy az előnézet fölötti komponens inicializálásakor hívsz meg, és egy `use…` függvény a plugin-komponensek számára.
+
+| Kontextus | Megadás | Olvasás | Mit hordoz |
+|---|---|---|---|
+| Média | `media` prop, vagy `provideMedia(() => list)` | `useMedia()` | A képek, amelyek közül a blokkok választhatnak. |
+| Nézet | `provideView(() => key)` | `useView()` | A nézet, amelyet a nézetenkénti mezők szerkesztenek. |
+| Szöveg | `messages` prop, vagy `provideText(() => messages)` | `useText()` | Felületi szövegek az alkalmazás nyelvén. |
+
+A beágyazott szerkesztők és előnézetek mindhármat a szülőjüktől öröklik.
+
+## Média
+
+A blokkok soha nem tárolnak kép-URL-t. A képmező egy `MediaItem` **azonosítóját** tárolja, a szerkesztő, az előnézet és a pluginok pedig a dokumentum médiájában keresik ki az elemet:
+
+```ts
+interface MediaItem {
+	id: string; // a blokk propsában tárolva
+	name: string; // fájlnév vagy cím, a választóban jelenik meg
+	url: string; // a kép címe
+	group?: string; // címsor a választóban (pl. a melléklet kategóriája)
+}
+```
+
+A mellékelt pluginok nem használnak képeket; a képblokkokat neked kell megírnod, mert az elrendezésük az oldalé. Egy minimális `photo` plugin — képmező, alternatív szöveg és magasságcsúszka:
+
+```svelte
+<!-- PhotoView.svelte -->
+<script lang="ts" module>
+	export interface PhotoProps extends Record<string, unknown> {
+		/** Egy MediaItem azonosítója. */
+		image: string;
+		alt: string;
+		/** A magasság a szélesség %-ában (20–150), vagy beállítatlan a kép saját alakjához. */
+		ratio?: unknown;
+	}
+
+	/** CSS aspect-ratio egy tárolt magasságból, vagy 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
+};
+```
+
+A szerkesztőnek és az előnézetnek ugyanazt a médiát add:
+
+```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} />
+```
+
+Plugin-komponensben a listát a `useMedia()`-val olvasd ki — függvényt ad vissza, így a lista mindig friss marad —, egy elemet pedig a `findMedia(list, id)`-vel keress meg, ahogy a photo nézete és előnézete is teszi.
+
+> **Bélyegképek a szerkesztőben**
+>
+> A szerkesztőnek csak kis képekre van szüksége. Mivel a blokkok azonosítókat tárolnak, a szerkesztőnek adhatsz egy bélyegkép-URL-ekből álló listát, az oldalon lévő előnézetnek pedig egy teljes méretű URL-ekből állót, ugyanazokkal az azonosítókkal.
+
+Tipikus forrás egy oldal feltöltött mellékletei vagy egy médiatár. Minden képnek, amelyre egy dokumentum hivatkozik, szerepelnie kell a listában, különben a blokkja semmit sem renderel.
+
+## Nézetenkénti értékek
+
+Egyes beállítások attól függnek, hogyan jelenik meg az oldal: egy képnek telefonon más képarány kellhet, mint széles képernyőn. A `views` beállítással rendelkező `slider` mező nézetenként tárol értéket:
+
+```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' }
+];
+
+/** Ugyanaz a plugin, az egyik mezője nézetenként állítva. */
+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')];
+```
+
+Hogy milyen nézetek léteznek, és melyik látszik éppen, az az alkalmazás dolga. Az alkalmazás a `provideView`-val közli a szerkesztővel az aktuális nézetet, jellemzően egy szerkesztő melletti szélességváltóból:
+
+```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} />
+```
+
+Hogyan viselkednek az értékek:
+
+- Az első nézet az **alap**. Minden további nézet, amíg nincs saját értéke, az előtte lévő nézet értékét veszi át; a mező ilyenkor örököltként jelölve mutatja az értéket.
+- A mező az aktuális nézet értékét szerkeszti, és a saját címkéje mellett a nézet címkéjét is mutatja. `provideView` nélkül, vagy ha a kulcs nem szerepel a `views`-ban, az alapértéket szerkeszti.
+- Tárolás: ha csak alapérték van → önmagában, egyszerű értékként tárolódik (`"ratio": "56"`); ha más nézeteknek saját értékük van → nézet szerint kulcsolt objektumként (`"ratio": { "desktop": "56", "phone": "100" }`). Azok a dokumentumok, amelyek még azelőtt íródtak, hogy egy mező nézetenkéntivé vált, érvényesek maradnak.
+
+Az előnézet a `viewValues(value, keys)`-szel olvassa ki őket — minden nézet értékét, az öröklést alkalmazva —, vagy csak az alapértéket a `baseValue(value)`-val. A photo előnézetének ez a változata CSS-változókon keresztül szélességenként egy-egy képarányt ad a böngészőnek:
+
+```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: mindegyikhez egy CSS aspect-ratio ('auto': a kép saját alakja)
+	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>
+```
+
+> **Csak csúszkák**
+>
+> A `views` a `slider` mezőkön támogatott. A többi mezőfajta figyelmen kívül hagyja.
+
+## Felületi szövegek
+
+A szerkesztő és a pluginok angolul íródtak, és az angol szöveg a fordításának kulcsa. Add át a `messages`-t — egy objektumot, amely az angol szövegeket a te nyelvedre képezi le — a legfelső szintű szerkesztőnek és előnézetnek:
+
+```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} />
+```
+
+Az `@atom-forge/brickee/locales/hu` a `hu`-t exportálja: a szerkesztő és az összes mellékelt plugin magyar szövegeit. Bővítsd ki a saját pluginjaid és mezőid szövegeivel:
+
+```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'
+};
+```
+
+Amit a szerkesztő magától lefordít:
+
+- a beépített blokkok és a pluginok `label`, `hint` és `keys` értékeit (a perjeles menü az angol és a lefordított szavak között is keres);
+- egy plugin `tag`-jének részeit, ` · `-nál darabolva;
+- a mezők címkéit, helyőrzőit, az opciók címkéit, a `none` címkéket és a nézetcímkéket;
+- az `Empty` szövegét és a szerkesztő saját felületét.
+
+Azt a szöveget, amelyet egy plugin maga renderel — a nézetében vagy az előnézetében —, a `useText()`-en keresztül add ki:
+
+```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>
+```
+
+A `{name}` helyőrzőket a második argumentum tölti ki. Komponenseken kívül a `translator(messages)` ugyanilyen függvényt ad vissza. A `messages`-ből hiányzó szöveg angol marad.

package/docs/hu/index.md

@@ -0,0 +1,38 @@
+# Brickee
+
+Az `@atom-forge/brickee` blokkszerkesztő Svelte 5-höz. A magja egy markdown blokkszerkesztő — bekezdések, címsorok, listák, teendők, idézetek, kód, elválasztók —, minden más blokk pedig **plugin**: egy blokk, amelynek van szerkesztőnézete, oldali előnézete, vannak mezői, és opcionálisan markdown alakja. A dokumentumok JSON-ként tárolódnak.
+
+Ezek az oldalak a [Brickee könyv](https://books.atom-forge.eu) alapján készültek, és angol nyelvű változatuk, a [`../en/index.md`](../en/index.md) fordításai; eltérés esetén az angol változat a mérvadó. Kódoló ágenseknek tömör referencia a [`README-AI.md`](../../README-AI.md).
+
+A csomag három rétegből épül fel:
+
+```mermaid
+flowchart TB
+  core["Mag: markdown blokkok, Editor, Preview, tárolt alak, kit"]
+  bundled["Mellékelt pluginok: táblázat, YouTube, térkép, térköz"]
+  own["Saját pluginok: ugyanaz a BlockPlugin alak"]
+  core --> bundled
+  core --> own
+```
+
+- **Mag** (`@atom-forge/brickee`) — a markdown blokkok, az `Editor` és a `Preview`, a tárolt alak és annak markdown-átalakításai, valamint a **kit**, amellyel a pluginok készülnek. Pluginok nélkül egyszerű markdown blokkszerkesztő.
+- **Mellékelt pluginok** (`@atom-forge/brickee/plugins`) — ugyanolyan pluginok, mint bármelyik más, és csak abból készültek, amit a mag exportál. Csak azokat kapcsolod be, amelyekre szükséged van.
+- **A saját pluginjaid** — ugyanaz a `BlockPlugin` alak, az alkalmazásodban.
+
+Maga a szerkesztő semmit sem tud az alkalmazásodról. Amire egy alkalmazásnak szüksége van — a képei, az oldalszélességei, a nyelve —, az **kontextusokon** (média, nézet, szöveg) vagy a pluginok **mezőin** keresztül jut el a pluginokhoz, soha nem külön szerkesztő-propokon át.
+
+## Tartalom
+
+1. [Első lépések](getting-started.md) — a három réteg, telepítés, a befogadó alkalmazás beállítása, és egy első szerkesztő az előnézetével.
+2. [A szerkesztő és az előnézet](editor-and-preview.md) — az `Editor` és a `Preview` propjai, a paletta, a szerkesztési funkciók és a görgetés-szinkron.
+3. [Dokumentumok és markdown](documents-and-markdown.md) — a tárolt alak (`StoredBlock`), a beépített blokkok, valamint az átalakítás markdownból és markdownba.
+4. [Mellékelt pluginok](bundled-plugins.md) — mit tartalmaz az `@atom-forge/brickee/plugins`, és hogyan írhatsz felül egy előnézetet vagy adhatsz hozzá mezőket.
+5. [Pluginok írása](writing-plugins.md) — a `BlockPlugin` felépítése, mezők, nézetek és előnézetek, tárolók, markdown alakok és a kit.
+6. [Az alkalmazás kontextusai](host-contexts.md) — média, nézetenkénti értékek és felületi szövegek.
+7. [A szerveren](server-side.md) — sémavalidálás, sima szöveg és védett tartalom.
+8. [Receptek és buktatók](recipes-and-pitfalls.md) — teljes minták és az elkerülendő hibák.
+9. [Frissítés](upgrading.md) — mit kell módosítanod a kódodban, amikor újabb verzióra váltasz.
+
+A könyvben van egy AI Notes fejezet is: utasítások, amelyeket a csomagot használó projekt ágens-utasításfájljába másolhatsz.
+
+A Svelte-példák teljes komponensek, hacsak másként nem jelzik. Az alkalmazásbeli értékek, például a képek listája vagy az aktuális oldalszélesség, azt jelölik, amit az alkalmazásod biztosít.

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

@@ -0,0 +1,122 @@
+# Receptek és buktatók
+
+[← Előző](server-side.md) · [Tartalom](index.md) · [Következő →](upgrading.md)
+
+## Egy hely a blokkbeállításoknak
+
+Egy alkalmazás pluginjait, palettáit és szövegeit tartsd egyetlen modulban, a szerkesztőt pedig csomagold be egy saját komponensbe. Az oldalak ezután a csomagolót használják, és soha nem ismétlik meg a beállítást.
+
+```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
+];
+
+/** A teljes paletta, az oldal saját lapjainak szerkesztőihez. */
+export const PAGE_PALETTE = ['md:p', 'md:h2', 'md:h3', 'md:ul', 'md:ol', 'md:quote', 'md:hr', ...plugins.map((p) => p.type)];
+
+/** Egy kisebb, a felhasználói hozzászólásokhoz. */
+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} />
+```
+
+A közzétett oldalt a `<Preview blocks={doc} {plugins} {media} {messages} />`-val és ugyanazokkal a `plugins`-szal rendereld, így egy blokk ugyanúgy néz ki a szerkesztő előnézetében és az oldalon.
+
+## A teljes dokumentum másolása markdownként
+
+A kijelölt blokkok másolása már most is markdownt tesz a vágólapra. Egy, a teljes dokumentumot másoló „Copy as markdown” gombhoz:
+
+```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();
+
+	// Kattintáskezelőben fut, így a csak böngészőben működő toMarkdown itt biztonságos.
+	const copy = () => navigator.clipboard.writeText(toMarkdown(doc.map(fromStored), { plugins, media }));
+</script>
+
+<button type="button" onclick={copy}>Copy as markdown</button>
+```
+
+## Dokumentum indítása markdownból
+
+```ts
+import { fromMarkdown, toStored, type StoredBlock } from '@atom-forge/brickee';
+
+// Böngészőben: a toStored a DOM-on keresztül olvassa be a soron belüli HTML-t.
+export const fromText = (text: string): StoredBlock[] => fromMarkdown(text).map(toStored);
+```
+
+Ne feledd, hogy minden nem üres sorból külön blokk lesz.
+
+## Fejlesztés helyi másolattal
+
+Ha a csomag egy helyi checkoutját linkeled be egy alkalmazásba (`bun link`), a linkelt mappa a saját `node_modules`-át hozza magával. Vedd rá a Vite-ot, hogy a közös csomagokból az alkalmazás egyetlen példányát használja, különben a Svelte-kontextusok — a popupkezelő, a téma — nem találhatók meg a két példány között:
+
+```ts
+// az alkalmazás vite.config.ts-e
+export default defineConfig({
+	plugins: [sveltekit()],
+	resolve: {
+		dedupe: ['svelte', '@atom-forge/ui', '@lucide/svelte', 'zod']
+	}
+});
+```
+
+Az alkalmazás a csomag lefordított `dist/` mappáját olvassa, ezért minden változtatás után buildeld újra a csomagot.
+
+## Buktatók
+
+| Tünet | Ok | Megoldás |
+|---|---|---|
+| A blokkmezők és a popupok stílus nélkülinek tűnnek | Hiányzik az `@atom-forge/ui` téma CSS-e vagy a Tailwind `@source`-a | Állítsd be az `@atom-forge/ui`-t a dokumentációja szerint, és az alkalmazást a `Root`-ja alatt rendereld. |
+| A popupok nem nyílnak meg, vagy „context not found” hibák linkelt csomaggal | A `svelte` vagy az `@atom-forge/ui` két példányban van jelen | Vedd fel őket a Vite `resolve.dedupe` listájába. |
+| Egy plugin blokkja „Unknown block” feliratot mutat | A pluginja hiányzik a `plugins`-ból | Egy dokumentumtípus minden szerkesztőjének és előnézetének ugyanazokat a pluginokat add át. |
+| Egy blokk hiányzik a `Preview`-ból | A pluginjának nincs `preview`-ja | Adj a pluginnak `preview`-t (a mellékelt pluginoknak van alapértelmezett), vagy rendereld a blokkot a saját megjelenítőddel. |
+| Egy plugin blokkja hiányzik az oldalról | Az előnézet más `plugins`-t kapott, vagy a kép azonosítója nincs a `media`-ban | Ugyanazt a pluginlistát és médiát használd a szerkesztőhöz és az előnézethez. |
+| Egy doboz nem tehető egy másik dobozba | A beágyazott szerkesztők egy szint mélyek | A tárolókat tartalomblokkok befogadására tervezd, ne más tárolókéra. |
+| Egy blokk nem érhető el egy tárolón belül | Az `accepts` vagy az alkalmazás `palette`-je kihagyja | Vedd fel a palettaazonosítót az `accepts`-be (vagy használd az `'md:*'`-ot az összes beépítetthez). |
+| Egy egyedi blokk kétszer jelenik meg | A séma nem kényszeríti ki a `unique`-ot | Ellenőrizd a szerveren, ha az alkalmazásod számít rá. |
+| A védett tartalom mindenkinek látszik | A `gate` csak megjelöli a blokkokat | Renderelés előtt vágd meg a dokumentumot a szerveren. |
+| `document is not defined` | A `toMarkdown` vagy a `toStored` SSR közben futott | Csak a böngészőben hívd őket. |
+| Egy propsból jövő szín vagy link elrontja az oldalt | A props felhasználói bemenet | Használd a `safeColor`-t, ellenőrizd a linkeket, és propsszal soha ne használj `{@html}`-t. |
+| Egy felülírt plugin elveszíti a blokkjait | Megváltozott a `type`-ja | Egy plugin szétterítésekor tartsd meg a `type`-ot. |
+| `bind:blocks` hiba egy saját nézetben | A `props` vagy a `blocks` nincs bindable-ként deklarálva | Deklaráld mindkettőt `$bindable()`-lel. |
+| Az érték soha nem üres tömb | A szerkesztő üres dokumentumnál egy üres bekezdést mutat (és ír) | Az olyan dokumentumot, amelyben csak üres bekezdések vannak, kezeld üresként, például a `blocksToPlainText(doc).trim() === ''` segítségével. |
+| Az előnézet nem követi a szerkesztő görgetését | Az actionök nem a görgethető dobozokon vannak | A `use:sync.source` / `use:sync.target` közvetlenül az `overflow` dobozokra kerüljön. |

package/docs/hu/server-side.md

@@ -0,0 +1,95 @@
+# A szerveren
+
+[← Előző](host-contexts.md) · [Tartalom](index.md) · [Következő →](recipes-and-pitfalls.md)
+
+A tárolt dokumentum a böngésző által küldött JSON, ezért a szervernek mentés előtt ellenőriznie kell. Két belépési pontnak nincs Svelte-függősége, ezek szerveroldali kódhoz készültek:
+
+- `@atom-forge/brickee/model` — `StoredBlock`, `MD`, `MAX_INDENT`, `MAX_DEPTH`, `isMd`, `acceptsId`, `inlineToPlainText`, `blocksToPlainText`;
+- `@atom-forge/brickee/schema` — `blocksSchema` és `blocksSchemaFor`, `zod`-dal építve (opcionális peer dependency: telepítsd, ha ezt a belépési pontot használod).
+
+## Dokumentum validálása
+
+```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[]
+}
+```
+
+A `blocksSchema` bármely dokumentum alakját ellenőrzi; a `blocksSchemaFor(plugins)` ehhez hozzáveszi a tárolók `accepts` listáit. Minden pluginból csak a `type` és az `accepts` kell neki, így az a szerver, amely nem akarja importálni a plugin-komponenseket, csak ezeket is átadhatja:
+
+```ts
+const contentSchema = blocksSchemaFor([
+	{ type: 'note', accepts: ['md:*', 'youtube'] },
+	{ type: 'youtube' }
+]);
+```
+
+Amit a séma ellenőriz:
+
+| Szabály | Korlát |
+|---|---|
+| Blokkkulcsok | Csak `type`, `indent`, `text`, `props`, `blocks` (szigorú objektumok). |
+| `type` | `^[a-z][a-z0-9:-]{0,39}$` |
+| `indent` | Egész szám, 0–6. |
+| `text` | Legfeljebb 100 000 karakter. |
+| `props` | Legfeljebb 60 karakteres kulcsok, JSON-értékek. |
+| `blocks` | Tárolónként legfeljebb 500 beágyazott blokk, csak egy szint mélyen. |
+| Dokumentum | Legfeljebb 2000 legfelső szintű blokk és JSON-ként 1 000 000 karakter. |
+| `accepts` (`blocksSchemaFor`) | Minden beágyazott blokkot befogad a tárolója. |
+
+Amit **nem** ellenőriz: hogy egy típus ismert-e, hogy egy egyedi blokk csak egyszer fordul-e elő, és hogy mit tartalmaz a props. Az alkalmazásod által megkövetelt szabályokhoz adj hozzá saját finomításokat – például az ismeretlen blokktípusok elutasításához:
+
+```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.');
+```
+
+> **Alak, nem biztonság**
+>
+> A séma szabályos és korlátos méretű dokumentumokat biztosít; a propsokat viszont nem teszi biztonságosan renderelhetővé. A renderelők minden szöveget escape-elnek, és a hivatkozásokat biztonságos sémákra korlátozzák, a saját propsait pedig minden plugin-előnézetnek magának kell megtisztítania (lásd [Pluginok írása](writing-plugins.md)).
+
+## Egyszerű szöveg
+
+A `blocksToPlainText(blocks)` sorrendben összegyűjti egy dokumentum minden szövegét, üres sorokkal elválasztva: a blokkszövegeket jelölések és hivatkozáscélok nélkül, a szóközt tartalmazó szöveges propsokat (címek, képaláírások – azonosítók és színek nem), a táblázatsorokat és a beágyazott blokkokat. Keresőindexekhez, leadekhez és meta descriptionökhöz használd. Az `inlineToPlainText(md)` ugyanezt teszi egyetlen inline markdown szöveggel.
+
+```ts
+import { blocksToPlainText, type StoredBlock } from '@atom-forge/brickee/model';
+
+export const description = (doc: StoredBlock[]) => blocksToPlainText(doc).slice(0, 160);
+```
+
+## Renderelés
+
+A `Preview` hagyományos Svelte-komponens, és szerveren is renderelhető; a mag renderelője és a mellékelt előnézetek nem használnak böngésző-API-kat. Csak a markdown-export útvonalnak (`toMarkdown`, `toStored`) kell a böngésző.
+
+## Védett tartalom
+
+Egy kapus blokk (egy `gate: true` beállítású plugin, például egy csak támogatóknak szóló elválasztó) csak annyit tesz, hogy az előnézet megjelöli az utána következő blokkokat. Hogy a védett részt elzárd azoktól az olvasóktól, akik nem láthatják, vágd el a dokumentumot a szerveren, mielőtt az oldalhoz érne:
+
+```ts
+import type { StoredBlock } from '@atom-forge/brickee/model';
+
+/** A dokumentum az első kapus blokkig, azt is beleértve, hozzáférés nélküli olvasóknak. */
+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);
+}
+```
+
+Hívd meg a kapus pluginjaid típusaival (például `['paywall']`) és az olvasó hozzáférésével. A hozzáférés nélküli olvasók a kapus blokkig látják a tartalmat, az előzetesével együtt; a hozzáféréssel rendelkezők a teljes dokumentumot kapják, és az előnézet megjelöli számukra a védett részt.