@atom-forge/brickee 0.0.1 → 0.0.2

package/docs/en/index.md

@@ -19,7 +19,7 @@ flowchart TB
 - **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.
+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
 
@@ -27,12 +27,12 @@ The editor itself knows nothing about your application. Whatever an app needs
 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.
+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 list of images or the current page width stand for whatever your application provides.
+Svelte examples are complete components unless they say otherwise. Application values such as the current page width stand for whatever your application provides.

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

@@ -38,23 +38,22 @@ export const messages: Messages = { ...hu, Button: 'Gomb', 'A link as a button':
 ```svelte
 <!-- lib/BlockEditor.svelte -->
 <script lang="ts">
-	import { Editor, provideView, type MediaItem, type StoredBlock } from '@atom-forge/brickee';
+	import { Editor, provideView, 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();
+	}: { value: StoredBlock[]; palette?: string[]; view?: string } = $props();
 
 	provideView(() => view);
 </script>
 
-<Editor bind:value {plugins} {palette} {media} {messages} />
+<Editor bind:value {plugins} {palette} {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.
+Render the published page with `<Preview blocks={doc} {plugins} {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
 
@@ -62,13 +61,13 @@ Copying selected blocks already puts markdown on the clipboard. For a "Copy as m
 
 ```svelte
 <script lang="ts">
-	import { fromStored, toMarkdown, type MediaItem, type StoredBlock } from '@atom-forge/brickee';
+	import { fromStored, toMarkdown, type StoredBlock } from '@atom-forge/brickee';
 	import { plugins } from './blocks';
 
-	let { doc, media = [] }: { doc: StoredBlock[]; media?: MediaItem[] } = $props();
+	let { doc }: { doc: StoredBlock[] } = $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 }));
+	const copy = () => navigator.clipboard.writeText(toMarkdown(doc.map(fromStored), { plugins }));
 </script>
 
 <button type="button" onclick={copy}>Copy as markdown</button>
@@ -106,10 +105,12 @@ The application reads the package's built `dist/`, so rebuild the package after
 | 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`. |
+| Block handles stick out on the left | The handles are drawn left of the editor's box | Give the element around the editor about 22 px of left padding. |
 | 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 plugin block is missing from the site | The preview got other `plugins` | Use the same plugin list for the editor and the preview. |
+| An image block renders nothing | Its preview rejects the stored address, or the app's own lookup does not know the stored id | Store addresses the preview accepts (`http(s)` or site-relative); resolve ids from the same data in the editor and on the site. |
 | 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. |

package/docs/en/upgrading.md

@@ -6,11 +6,27 @@ This chapter lists the changes that may require action when you move to a newer
 
 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 0.0.1 to 0.0.2
 
-## From the `block-editor` workspace package to Unreleased
+### Images and media are no longer part of the package
+
+The package has no notion of images any more. Whether a block stores an image's URL or an id, how the user picks the image, and how the stored value becomes an address are decided by the application's own image plugin (see [Images](writing-plugins.md#images)).
+
+| Removed | Was |
+|---|---|
+| `kind: 'image'`, `kind: 'images'` | Field kinds that stored the id (or ids) of a picked media item, with the built-in image picker popup |
+| `media` prop of `Editor` and `Preview` | The images blocks could pick from and refer to |
+| `provideMedia`, `useMedia`, `findMedia`, `MediaItem` | The media context, its lookup and its type |
+| `media` option of `toMarkdown` | `toMarkdown(blocks, { plugins, media })` is now `toMarkdown(blocks, { plugins })` |
+| `ctx.media` in a plugin's `markdown(props, ctx)` | `MarkdownContext` is now `{ inner }` |
+
+`PropField['kind']` is now `'text' | 'textarea' | 'color' | 'select' | 'slider'`. Stored documents are unaffected: a block's props keep whatever they stored, ids included.
+
+**What to do:** in your image plugins, replace each `image` or `images` field with your own picking — a button in the plugin's view that opens your media dialog or an upload and writes the result into `props`, or a plain `text` field for a URL — and keep the prop keys, so stored documents still load. Remove the `media` prop from your editors and previews, and the `media` option from your `toMarkdown` calls. Where a view, a preview or a `markdown` form turned an id into an address with `useMedia`, `findMedia` or `ctx.media`, look it up in your application's own data instead: a module of your app, or a Svelte context of your own provided above the editor and the preview (`markdown` runs outside components, so it needs module data). Define a `MediaItem`-like type in your app if you still need one.
+
+## From the `block-editor` workspace package to 0.0.1
+
+This section is only for applications that used the editor before it became this package.
 
 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/docs/en/writing-plugins.md

@@ -141,7 +141,7 @@ Register it beside the others:
 
 > **Props come from users**
 >
-> A plugin's props are whatever was stored — typed by an editor, pasted, or sent to your API by anyone who can save a document. The schema only checks the shape. Every preview must treat props as untrusted: take colours through `safeColor`, check links, clamp numbers, and look images up in the media list instead of using stored URLs. Svelte escapes text in `{...}`; never put a prop into `{@html}`.
+> A plugin's props are whatever was stored — typed by an editor, pasted, or sent to your API by anyone who can save a document. The schema only checks the shape. Every preview must treat props as untrusted: take colours through `safeColor`, check links and image addresses, and clamp numbers. Svelte escapes text in `{...}`; never put a prop into `{@html}`.
 
 ## Fields
 
@@ -151,9 +151,9 @@ Each `PropField` is one setting on the top of the block. The editor draws them a
 |---|---|
 | `key` | The prop it edits. |
 | `label` | Its label (translated through `messages`). |
-| `kind` | `text`, `textarea`, `color`, `select`, `slider`, `image` or `images`. |
+| `kind` | `text`, `textarea`, `color`, `select`, `slider` or `toggles`. |
 | `placeholder` | Hint of an empty text field; for an optional colour, the colour a click on "none" starts from. |
-| `options` | `{ value, label }[]` for `select`, and for a `slider` that steps through values. An option label may use `{n}`, filled with its value. |
+| `options` | `{ value, label }[]` for `select`, and for a `slider` that steps through values. An option label may use `{n}`, filled with its value. For `toggles`, `{ value, label, icon }[]`: `icon` is the button, `label` its tooltip. |
 | `min`, `max`, `step`, `unit` | A number `slider`: its range, step (default 1) and the unit shown after the value. |
 | `none` | The label of the unset state: a number slider's notch left of `min`, or an optional colour's "none" button. |
 | `views` | Per-view values for a `slider` (see [Per-view values](host-contexts.md#per-view-values)). |
@@ -169,8 +169,7 @@ How each kind stores its value:
 | `slider` with `options` | The value of the option at the slider's position. |
 | `slider` with `min` and `max` | The number as a string (for example `'56'`); the `none` notch removes the key. |
 | `color` | A `#rrggbb` string; with `none`, clearing it removes the key. |
-| `image` | The picked media item's `id`; picking it again removes it. |
-| `images` | An array of ids, in picking order; picking a picked one takes it out. |
+| `toggles` | The list of the options switched on, in `options` order (`[]` when none); the bundled table's header and footer are one. |
 
 An empty value (`''`, `null` or `undefined`, also when returned by `parse`) removes the key from `props`, so a preview must always handle a missing prop. A field's `parse` is also a good place to normalize input: the bundled YouTube field accepts any YouTube link and stores only the video id.
 
@@ -189,7 +188,7 @@ Declare `props` and `blocks` with `$bindable()` even when the view does not use
 
 ## The preview
 
-The preview receives `PluginPreviewProps`: `props`, `blocks` and `plugins`. It is a plain Svelte component that renders the block for the site. Media, messages and the view are available through the contexts (`useMedia`, `useText`, `useView`; see [Host contexts](host-contexts.md)).
+The preview receives `PluginPreviewProps`: `props`, `blocks` and `plugins`. It is a plain Svelte component that renders the block for the site. Messages and the view are available through the contexts (`useText`, `useView`; see [Host contexts](host-contexts.md)); images are the plugin's own business (see [Images](#images)).
 
 ## Containers
 
@@ -275,10 +274,7 @@ A supporters-only divider is a typical example of both: one per document, with t
 
 ## Markdown form
 
-`markdown(props, { inner, media })` returns the block as markdown, used when blocks are copied in the editor and by `toMarkdown`:
-
-- `inner` — the nested blocks already as markdown (`''` without any);
-- `media` — the document's media, to turn an image id into its URL with `findMedia(media, id)?.url`.
+`markdown(props, { inner })` returns the block as markdown, used when blocks are copied in the editor and by `toMarkdown`. `inner` is the nested blocks already as markdown (`''` without any).
 
 Return `''` to leave the block out. Plugins whose output has no meaning as text (an ad slot, the bundled `gap`) simply have no markdown form. Three helpers keep the output well-formed:
 
@@ -288,6 +284,111 @@ Return `''` to leave the block out. Plugins whose output has no meaning as text
 | `mdJoin(...parts)` | Joins parts as separate blocks (blank line between), leaving out empty and falsy ones. |
 | `mdQuote(md)` | Prefixes every line with `> `, for a box rendered as a blockquote. |
 
+## Images
+
+The editor has no notion of images: no image field, no picker, no list of media. Whether a block stores an image's URL or the id of an image in the app's own media library, how the user picks it, and how the stored value becomes an address are the application's decisions, so an image block is an ordinary plugin of the app.
+
+A minimal `photo` plugin stores the image's address, typed into a text field, with alt text and a height slider:
+
+```svelte
+<!-- PhotoView.svelte -->
+<script lang="ts" module>
+	export interface PhotoProps extends Record<string, unknown> {
+		/** The image's address. */
+		url: string;
+		alt: string;
+		/** The height in % of the width (20–150), or unset for the image's own shape. */
+		ratio?: unknown;
+	}
+
+	/** The stored address if it is http(s) or site-relative, else ''. */
+	export const imageSrc = (u: unknown) => {
+		const s = String(u ?? '').trim();
+		return /^(https?:|\/(?!\/))/.test(s) ? s : '';
+	};
+
+	/** 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, type PluginViewProps } from '@atom-forge/brickee';
+
+	let { props = $bindable(), blocks = $bindable() }: PluginViewProps<PhotoProps> = $props();
+	const src = $derived(imageSrc(props.url));
+</script>
+
+{#if src}
+	<img {src} alt={props.alt} style="max-width: 100%" />
+{:else}
+	<Empty icon={ImageIcon} text="Set the image's address above" />
+{/if}
+```
+
+```svelte
+<!-- PhotoPreview.svelte -->
+<script lang="ts">
+	import { baseValue, 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));
+</script>
+
+{#if src}
+	<img {src} 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 { 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 image',
+	keys: 'photo image picture',
+	icon: ImageIcon,
+	props: () => ({ url: '', alt: '' }),
+	fields: [
+		{ key: 'url', label: 'Image', kind: 'text', placeholder: 'https://…', parse: (s) => s.trim() },
+		{ 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) => {
+		const src = imageSrc(p.url);
+		return src ? `![${mdText(p.alt)}](${src})` : '';
+	},
+	view: PhotoView,
+	preview: PhotoPreview
+};
+```
+
+The address is a prop like any other, so it is untrusted: the view and the preview render it only when it is an `http(s)` or site-relative address, as the button checks its link.
+
+Other apps choose differently, all within the plugin:
+
+- **A media library.** The block stores the id of an image in the app's library instead of a URL. The view, the preview and `markdown` turn the id into an address with the app's own lookup: a module of the app, or the app's own Svelte context provided above the editor and the preview (plugin components are rendered beneath them). `markdown` runs outside components, when blocks are copied and in `toMarkdown`, so it can only use module data.
+- **Picking.** Instead of a text field, the view can show its own picker — a button that opens the app's media dialog or an upload — and write the result into `props`, which is bindable.
+- **Several images.** A gallery stores a list (of URLs or ids) in one prop and edits it in its view the same way.
+
 ## The kit
 
 | Export | Kind | Use |
@@ -299,7 +400,6 @@ Return `''` to leave the block out. Plugins whose output has no meaning as text
 | `baseValue(value)` | function | The base value of a per-view prop. |
 | `viewValues(value, keys)` | function | A per-view prop's value for each view. |
 | `mdText`, `mdJoin`, `mdQuote` | functions | Markdown forms (above). |
-| `useMedia`, `findMedia` | functions | The document's images (see [Host contexts](host-contexts.md)). |
 | `useText` | function | Translates the plugin's own UI text. |
 | `useView` | function | The view the host is showing. |
 | `Preview` | component | Renders a container's nested blocks (with `nested`). |

package/docs/hu/bundled-plugins.md

@@ -13,7 +13,7 @@ import { table, youtube } from '@atom-forge/brickee/plugins'; // vagy néhány
 
 | Export | `type` | Mezők | Markdown alak | Mi ez |
 |---|---|---|---|---|
-| `table` | `table` | — (helyben szerkesztve) | GFM-táblázat | Inline formázott cellák sorai és oszlopai; a sorokat és az oszlopokat a fogantyújuknál fogva húzhatod. Az első sor lehet fejléc, az utolsó lábléc. |
+| `table` | `table` | fejléc és lábléc (a cellák helyben szerkeszthetők) | GFM-táblázat | Inline formázott cellák sorai és oszlopai; egy cellába kattintva megjelennek a sora és oszlopa eszközei (beszúrás, törlés, igazítás), a sorokat és az oszlopokat a fogantyújuknál fogva húzhatod. Az első sor lehet fejléc, az utolsó lábléc. |
 | `youtube` | `youtube` | videóhivatkozás vagy -azonosító, cím | hivatkozás | YouTube-videó, kattintásra betöltve; bármely YouTube-hivatkozásból csak a videó azonosítója marad meg. |
 | `map` | `map` | hely vagy cím, nagyításcsúszka | hivatkozás | Egy hely vagy cím beágyazott Google Maps-térképe. |
 | `gap` | `gap` | magasságcsúszka | nincs | Üres hely a blokkok között, 1–8 sor magas. |

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

@@ -79,18 +79,17 @@ A markdown teljes értékű formátum: a vágólap ezt hordozza, és a befogadó
 | `fromStored(block)` | `StoredBlock` → `Block` | bárhol |
 | `toStored(block)` | `Block` → `StoredBlock` | csak böngészőben |
 | `fromMarkdown(text)` | markdown → `Block[]` | bárhol |
-| `toMarkdown(blocks, { plugins, media })` | `Block[]` → markdown | csak böngészőben |
+| `toMarkdown(blocks, { plugins })` | `Block[]` → markdown | csak böngészőben |
 | `inline(md)` | inline markdown → inline HTML | bárhol |
 
 A markdown-függvények a szerkesztő alakján (`Block[]`) dolgoznak, ezért a tárolt dokumentumok a `fromStored` és a `toStored` függvényen mennek át:
 
 ```ts
-import { fromMarkdown, fromStored, toMarkdown, toStored, type MediaItem, type StoredBlock } from '@atom-forge/brickee';
+import { fromMarkdown, fromStored, toMarkdown, toStored, type StoredBlock } from '@atom-forge/brickee';
 import { PLUGINS } from '@atom-forge/brickee/plugins';
 
 // Tárolt dokumentum -> markdown (csak böngészőben).
-export const exportMarkdown = (doc: StoredBlock[], media: MediaItem[]) =>
-	toMarkdown(doc.map(fromStored), { plugins: PLUGINS, media });
+export const exportMarkdown = (doc: StoredBlock[]) => toMarkdown(doc.map(fromStored), { plugins: PLUGINS });
 
 // Markdown -> tárolt dokumentum (csak böngészőben).
 export const importMarkdown = (text: string): StoredBlock[] => fromMarkdown(text).map(toStored);
@@ -110,6 +109,6 @@ Amit a `toMarkdown` kiír:
 
 - az egymást követő listaelemeket egymást követő sorokba, minden más blokkot üres sorral elválasztva;
 - a listaelemeket és a bekezdéseket szintenként két szóközzel behúzva;
-- a plugin-blokkot a pluginja `markdown(props, { inner, media })` függvényével, ahol az `inner` a már átalakított beágyazott blokkjai; a markdown alak nélküli plugin, illetve az, amelyik `''`-t ad vissza, kimarad.
+- a plugin-blokkot a pluginja `markdown(props, { inner })` függvényével, ahol az `inner` a már átalakított beágyazott blokkjai; a markdown alak nélküli plugin, illetve az, amelyik `''`-t ad vissza, kimarad.
 
 Saját pluginod markdown alakjának megírásáról a [Pluginok írása](writing-plugins.md#markdown-alak) fejezet szól.

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

@@ -9,7 +9,6 @@
 | `value` | `StoredBlock[]` (bindable) | `[]` | A dokumentum. Minden változáskor visszaíródik; a kívülről lecserélt dokumentum újra betöltődik. |
 | `plugins` | `BlockPlugin[]` | `[]` | A pluginblokkok, amelyeket ez a szerkesztő megjeleníthet és felkínálhat. |
 | `palette` | `string[]` | minden beépített blokk, utána minden plugin | A perjeles menü által felkínált blokktípusok, ebben a sorrendben (lásd lent). |
-| `media` | `MediaItem[]` | — | A képek, amelyek közül a blokkok választhatnak (lásd [Az alkalmazás kontextusai](host-contexts.md)). |
 | `messages` | `Messages` | — | Felületi szövegek az alkalmazás nyelvén: angol szöveg → fordítás. |
 | `readonly` | `boolean` | `false` | Szerkesztés nélkül mutatja a dokumentumot; a pluginmezők rejtve vannak. |
 | `placeholder` | `string` | `Write something, or press '/' for blocks…` | Az üres blokk tippszövege. |
@@ -23,7 +22,6 @@ Az üres dokumentum egyetlen üres bekezdésként jelenik meg, így a szerkeszt
 |---|---|---|---|
 | `blocks` | `StoredBlock[]` | — | A megjelenítendő dokumentum. |
 | `plugins` | `BlockPlugin[]` | — | A pluginok, amelyek előnézetei a pluginblokkokat renderelik. |
-| `media` | `MediaItem[]` | — | A képek, amelyekre a blokkok azonosítóval hivatkoznak. |
 | `messages` | `Messages` | — | Felületi szövegek az alkalmazás nyelvén. |
 | `markGated` | `boolean` | `true` | Megjelöli a kapus blokk utáni blokkokat (lásd [Egyedi és kapus blokkok](writing-plugins.md#egyedi-és-kapus-blokkok)). |
 | `nested` | `boolean` | `false` | A beágyazott blokkjaikat renderelő plugin-előnézetek állítják be. |
@@ -32,7 +30,7 @@ Az előnézet a beépített blokkokat sima HTML-ként rendereli (`p`, `h1`…`h6
 
 Hogy használod-e egyáltalán a `Preview`-t, rajtad múlik: a szerkesztő nem függ tőle. Egy saját megjelenítővel dolgozó alkalmazás maga is renderelheti a tárolt blokkokat, és a pluginjai elhagyhatják a `preview`-t.
 
-A legfelső szintű szerkesztőnek vagy előnézetnek átadott `media` és `messages` öröklődik minden alatta lévő beágyazott szerkesztőre, beágyazott előnézetre és pluginkomponensre.
+A legfelső szintű szerkesztőnek vagy előnézetnek átadott `messages` öröklődik minden alatta lévő beágyazott szerkesztőre, beágyazott előnézetre és pluginkomponensre.
 
 ## A paletta
 

package/docs/hu/getting-started.md

@@ -10,7 +10,7 @@ Minden más plugin. A plugin egy egyszerű objektum (`BlockPlugin`), amely megne
 
 - 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…);
+- **mezőket** — a blokk tetején megjelenő beállításokat (szöveg, szín, választó, csúszka…);
 - 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.
@@ -24,7 +24,7 @@ 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. |
+| `@atom-forge/ui` `>=0.0.37` | A felugró ablakok (linkbekérő) é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. |
 
@@ -37,6 +37,10 @@ A blokkmezők és a felugró ablakok `@atom-forge/ui` komponensek, ezért az alk
 
 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.
 
+A szerkesztő a színeit az `@atom-forge/ui` téma tokenjeiből veszi (`--color-surface`, `--color-frame`, `--color-muted-contrast`…), így követi a befogadó alkalmazás világos és sötét módját. Az előnézet keretei és képaláírásai az oldal szövegszínéből számolódnak.
+
+A blokkok fogantyúi a **szerkesztő dobozától balra**, egy kb. 22 px széles sávban jelennek meg: a szerkesztőt körülvevő elemnek legyen ennyi bal oldali paddingje, különben a fogantyúk kilógnak belőle.
+
 > **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.

package/docs/hu/host-contexts.md

@@ -2,143 +2,21 @@
 
 [← 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.
+A szerkesztőnek nincsenek propjai az alkalmazás fogalmaihoz. Amit a befogadó alkalmazás tud — az éppen mutatott oldalszélességet, a kiemelhető kódnyelveket, 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. |
+| Kódnyelvek | `provideCodeLanguages(() => list)` | `useCodeLanguages()` | A nyelvek, amelyeket a kódblokk felkínál. |
 | 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.
+A képek nem kontextuson keresztül érkeznek: hogy egy képblokk mit tárol, és honnan veszi a képeit, azt az alkalmazás saját pluginja dönti el (lásd [Képek](writing-plugins.md#képek)).
 
 ## 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:
+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. Itt ez a [Pluginok írása](writing-plugins.md#képek) fejezet `photo` pluginjának magassága és a mellékelt `gap`:
 
 ```ts
 import type { BlockPlugin } from '@atom-forge/brickee';
@@ -184,18 +62,17 @@ Az előnézet a `viewValues(value, keys)`-szel olvassa ki őket — minden néze
 
 ```svelte
 <script lang="ts">
-	import { findMedia, useMedia, viewValues, type PluginPreviewProps } from '@atom-forge/brickee';
-	import { aspect, type PhotoProps } from './PhotoView.svelte';
+	import { viewValues, type PluginPreviewProps } from '@atom-forge/brickee';
+	import { aspect, imageSrc, type PhotoProps } from './PhotoView.svelte';
 
 	let { props }: PluginPreviewProps<PhotoProps> = $props();
-	const media = useMedia();
-	const item = $derived(findMedia(media(), props.image));
+	const src = $derived(imageSrc(props.url));
 	// 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 src}
+	<img {src} alt={props.alt ?? ''} style:--r-desktop={r[0]} style:--r-tablet={r[1]} style:--r-phone={r[2]} />
 {/if}
 
 <style>
@@ -221,6 +98,23 @@ Az előnézet a `viewValues(value, keys)`-szel olvassa ki őket — minden néze
 >
 > A `views` a `slider` mezőkön támogatott. A többi mezőfajta figyelmen kívül hagyja.
 
+## Kódnyelvek
+
+A kódblokk nyelve (`props.lang`, a markdown-kerítés info-szövege) alapból szabad szöveg. Ha az alkalmazás tudja, mely nyelveket tud kiemelni az oldala, megadja a listát, és a kódblokk mezősávjában a mező legördülő lista lesz, elején a *Nincs* opcióval:
+
+```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 />
+```
+
+Egy elem string vagy `{ value, label? }`; a `value` kerül tárolásra. A beágyazott szerkesztők öröklik a listát. Egy tárolt nyelv, amely nincs a listában, opció marad, így egy régebbi dokumentum megnyitásakor semmi sem vész el.
+
 ## 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:

package/docs/hu/index.md

@@ -19,7 +19,7 @@ flowchart TB
 - **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.
+Maga a szerkesztő semmit sem tud az alkalmazásodról. Amire egy alkalmazásnak szüksége van — az oldalszélességei, a kódnyelvei, a nyelve —, az **kontextusokon** (nézet, kódnyelvek, szöveg) vagy a pluginok **mezőin** keresztül jut el a pluginokhoz, soha nem külön szerkesztő-propokon át. A képek sem kivételek: a képblokk a saját pluginod, amely úgy tárolja, választja ki és oldja fel a képeit, ahogy az alkalmazásod teszi.
 
 ## Tartalom
 
@@ -27,12 +27,12 @@ Maga a szerkesztő semmit sem tud az alkalmazásodról. Amire egy alkalmazásnak
 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.
+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, képblokkok és a kit.
+6. [Az alkalmazás kontextusai](host-contexts.md) — nézetenkénti értékek, kódnyelvek é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.
+A Svelte-példák teljes komponensek, hacsak másként nem jelzik. Az alkalmazásbeli értékek, például az aktuális oldalszélesség, azt jelölik, amit az alkalmazásod biztosít.