@atom-forge/brickee 0.0.1 → 0.0.3

package/docs/en/host-contexts.md

@@ -2,143 +2,21 @@
 
 [← Previous](writing-plugins.md) · [Contents](index.md) · [Next →](server-side.md)
 
-The editor has no props for application concepts. What a host knows — its images, the page width it is showing, its language — reaches the plugins through three Svelte contexts. Each has a `provide…` function, called in a component's initialization above the editor or preview, and a `use…` function for plugin components.
+The editor has no props for application concepts. What a host knows — the page width it is showing, the code languages it highlights, its language — reaches the plugins through three Svelte contexts. Each has a `provide…` function, called in a component's initialization above the editor or preview, and a `use…` function for plugin components.
 
 | Context | Provide | Read | Carries |
 |---|---|---|---|
-| Media | `media` prop, or `provideMedia(() => list)` | `useMedia()` | The images blocks can pick from. |
 | View | `provideView(() => key)` | `useView()` | The view per-view fields edit. |
+| Code languages | `provideCodeLanguages(() => list)` | `useCodeLanguages()` | The languages a code block offers. |
 | Text | `messages` prop, or `provideText(() => messages)` | `useText()` | UI text in the host's language. |
 
 Nested editors and previews inherit all three from their parent.
 
-## Media
-
-Blocks never store image URLs. An image field stores the **id** of a `MediaItem`, and the editor, the preview and the plugins look the item up in the document's media:
-
-```ts
-interface MediaItem {
-	id: string; // stored in the block's props
-	name: string; // file name or title, shown in the picker
-	url: string; // the image's address
-	group?: string; // a heading in the picker (e.g. the attachment category)
-}
-```
-
-The bundled plugins use no images; image blocks are yours to write, because their layout is the site's. A minimal `photo` plugin — an image field, alt text, and a height slider:
-
-```svelte
-<!-- PhotoView.svelte -->
-<script lang="ts" module>
-	export interface PhotoProps extends Record<string, unknown> {
-		/** A MediaItem id. */
-		image: string;
-		alt: string;
-		/** The height in % of the width (20–150), or unset for the image's own shape. */
-		ratio?: unknown;
-	}
-
-	/** A CSS aspect-ratio from a stored height, or undefined. */
-	export const aspect = (v: unknown) => {
-		const n = Number(v);
-		return n >= 20 && n <= 150 ? `100 / ${n}` : undefined;
-	};
-</script>
-
-<script lang="ts">
-	import { ImageIcon } from '@lucide/svelte';
-	import { Empty, findMedia, useMedia, type PluginViewProps } from '@atom-forge/brickee';
-
-	let { props = $bindable(), blocks = $bindable() }: PluginViewProps<PhotoProps> = $props();
-	const media = useMedia();
-	const item = $derived(findMedia(media(), props.image));
-</script>
-
-{#if item}
-	<img src={item.url} alt={props.alt} style="max-width: 100%" />
-{:else}
-	<Empty icon={ImageIcon} text="Pick an image above" />
-{/if}
-```
-
-```svelte
-<!-- PhotoPreview.svelte -->
-<script lang="ts">
-	import { baseValue, findMedia, useMedia, type PluginPreviewProps } from '@atom-forge/brickee';
-	import { aspect, type PhotoProps } from './PhotoView.svelte';
-
-	let { props }: PluginPreviewProps<PhotoProps> = $props();
-	const media = useMedia();
-	const item = $derived(findMedia(media(), props.image));
-</script>
-
-{#if item}
-	<img src={item.url} alt={props.alt ?? ''} style:aspect-ratio={aspect(baseValue(props.ratio))} />
-{/if}
-
-<style>
-	img {
-		width: 100%;
-		object-fit: cover;
-	}
-</style>
-```
-
-```ts
-// photo.ts
-import { ImageIcon } from '@lucide/svelte';
-import { findMedia, mdText, type BlockPlugin } from '@atom-forge/brickee';
-import PhotoView, { type PhotoProps } from './PhotoView.svelte';
-import PhotoPreview from './PhotoPreview.svelte';
-
-export const photo: BlockPlugin<PhotoProps> = {
-	type: 'photo',
-	label: 'Photo',
-	hint: 'One picked image',
-	keys: 'photo image picture',
-	icon: ImageIcon,
-	props: () => ({ image: '', alt: '' }),
-	fields: [
-		{ key: 'image', label: 'Image', kind: 'image' },
-		{ key: 'alt', label: 'Alt text', kind: 'text', placeholder: 'What the image shows' },
-		{ key: 'ratio', label: 'Height', kind: 'slider', min: 20, max: 150, unit: '%', none: 'Original' }
-	],
-	tag: () => 'photo',
-	content: 'none',
-	markdown: (p, { media }) => {
-		const url = findMedia(media, p.image)?.url;
-		return url ? `![${mdText(p.alt)}](${url})` : '';
-	},
-	view: PhotoView,
-	preview: PhotoPreview
-};
-```
-
-Give the editor and the preview the same media:
-
-```svelte
-<script lang="ts">
-	import { Editor, Preview, type MediaItem, type StoredBlock } from '@atom-forge/brickee';
-	import { photo } from './photo';
-
-	let { value = $bindable(), media }: { value: StoredBlock[]; media: MediaItem[] } = $props();
-</script>
-
-<Editor bind:value plugins={[photo]} {media} />
-<Preview blocks={value} plugins={[photo]} {media} />
-```
-
-In a plugin component, read the list with `useMedia()` — it returns a function, so the list stays current — and find an item with `findMedia(list, id)`, as the photo's view and preview do.
-
-> **Thumbnails in the editor**
->
-> The editor only needs small images. Because blocks store ids, you can give the editor a list of thumbnail URLs and the preview on the site a list of full-size URLs with the same ids.
-
-Typical sources are a page's uploaded attachments or a media library. Every image a document refers to must be in the list, or its block renders nothing.
+Images are not a context: what an image block stores and where its pictures come from is decided by the app's own plugin (see [Images](writing-plugins.md#images)).
 
 ## Per-view values
 
-Some settings depend on how the page is shown: an image may need a different aspect ratio on a phone than on a wide screen. A `slider` field with `views` stores a value per view:
+Some settings depend on how the page is shown: an image may need a different aspect ratio on a phone than on a wide screen. A `slider` field with `views` stores a value per view. Here it is the height of the `photo` plugin from [Writing plugins](writing-plugins.md#images) and the bundled `gap`:
 
 ```ts
 import type { BlockPlugin } from '@atom-forge/brickee';
@@ -184,18 +62,17 @@ A preview reads them with `viewValues(value, keys)` — the value for each view,
 
 ```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: a CSS aspect-ratio each ('auto': the image's own shape)
 	const r = $derived(viewValues(props.ratio, ['desktop', 'tablet', 'phone']).map((v) => aspect(v) ?? 'auto'));
 </script>
 
-{#if item}
-	<img src={item.url} alt={props.alt ?? ''} style:--r-desktop={r[0]} style:--r-tablet={r[1]} style:--r-phone={r[2]} />
+{#if 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 @@ A preview reads them with `viewValues(value, keys)` — the value for each view,
 >
 > `views` is supported on `slider` fields. Other field kinds ignore it.
 
+## Code languages
+
+A code block's language (`props.lang`, the info string of its markdown fence) is free text by default. When the host knows which languages its site can highlight, it gives the list, and the field in the code block's fields bar becomes a dropdown of them, with *None* first:
+
+```svelte
+<script lang="ts">
+	import { Editor, provideCodeLanguages, type StoredBlock } from '@atom-forge/brickee';
+
+	let { value = $bindable() }: { value: StoredBlock[] } = $props();
+	provideCodeLanguages(() => [{ value: 'ts', label: 'TypeScript' }, { value: 'svelte', label: 'Svelte' }, 'css', 'bash']);
+</script>
+
+<Editor bind:value />
+```
+
+An item is a string or `{ value, label? }`; the value is what is stored. Nested editors inherit the list. A stored language missing from the list stays an option, so opening an older document loses nothing.
+
 ## UI text
 
 The editor and the plugins are written in English, and the English text is the key of its translation. Pass `messages` — an object from English text to your language — to the top-level editor and preview:

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.
-7. [On the server](server-side.md) — schema validation, plain text, and gated content.
+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 and plain text.
 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>
@@ -83,7 +82,7 @@ import { fromMarkdown, toStored, type StoredBlock } from '@atom-forge/brickee';
 export const fromText = (text: string): StoredBlock[] => fromMarkdown(text).map(toStored);
 ```
 
-Remember that every non-empty line becomes its own block.
+A paragraph's lines stay one block, with line breaks between them; a blank line starts a new block.
 
 ## Developing against a local copy
 
@@ -105,15 +104,17 @@ The application reads the package's built `dist/`, so rebuild the package after
 
 | Symptom | Cause | Fix |
 |---|---|---|
+| The editor's rows, menus or table look unstyled or shrunk | The `@atom-forge/brickee` `dist` folder is not a Tailwind `@source` | Add `@source "../node_modules/@atom-forge/brickee/dist";` beside the `@atom-forge/ui` one. |
 | 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. |
-| Gated content visible to everyone | `gate` only marks the blocks | Cut the document on the server before rendering. |
 | `document is not defined` | `toMarkdown` or `toStored` ran during SSR | Call them in the browser only. |
 | A colour or link from props breaks the page | Props are user input | Use `safeColor`, check links, never use `{@html}` with props. |
 | Overridden plugin loses its blocks | Its `type` was changed | Keep `type` when spreading a plugin. |

package/docs/en/server-side.md

@@ -76,20 +76,3 @@ export const description = (doc: StoredBlock[]) => blocksToPlainText(doc).slice(
 ## Rendering
 
 `Preview` is an ordinary Svelte component and can be server-rendered; the core renderer and the bundled previews use no browser APIs. Only the markdown export path (`toMarkdown`, `toStored`) needs the browser.
-
-## Gated content
-
-A gate block (a plugin with `gate: true`, such as a supporters-only divider) only makes the preview mark the blocks after it. To keep the gated part from readers who may not see it, cut the document on the server before it reaches the page:
-
-```ts
-import type { StoredBlock } from '@atom-forge/brickee/model';
-
-/** The document up to and including the first gate block, for readers without access. */
-export function publicPart(doc: StoredBlock[], gateTypes: string[], canRead: boolean): StoredBlock[] {
-	if (canRead) return doc;
-	const at = doc.findIndex((b) => gateTypes.includes(b.type));
-	return at < 0 ? doc : doc.slice(0, at + 1);
-}
-```
-
-Call it with your gate plugin types (for example `['paywall']`) and the reader's access. Readers without access see the content up to the gate block and its teaser; readers with access get the whole document, and the preview marks the gated part for them.

package/docs/en/upgrading.md

@@ -6,11 +6,41 @@ 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.2 to 0.0.3
 
-## From the `block-editor` workspace package to Unreleased
+### The editor needs its `dist` folder as a Tailwind `@source`
+
+The editor's own styles moved from scoped CSS to Tailwind classes (with the `@atom-forge/ui` theme's colours) and SCSS. Tailwind 4 does not look into `node_modules`, so without a `@source` for the package the editor's rows, menus, fields bar and table lose their look. The preview is unaffected: its styles still travel with its markup.
+
+**What to do:** in the CSS file where you set up `@atom-forge/ui`, add `@source "../node_modules/@atom-forge/brickee/dist";` (with the path from that file) beside the `@atom-forge/ui` one. Nothing changes for pages that only show the `Preview`.
+
+### Gate blocks are gone
+
+Gating content (a supporters-only or paywall divider) is an application's concept, not the editor's. `BlockPlugin.gate`, the `Preview`'s `markGated` prop, its "For supporters only" section with the `.supporters` and `.supporters-label` classes, and the `For supporters only` text of the Hungarian locale are removed. The `Preview` now renders every block it gets. `unique` stays.
+
+**What to do:** remove `gate: true` from your plugin and `markGated` from your previews. Your divider stays an ordinary (unique) plugin block, so stored documents still load. Where you showed the gated part marked, render the document in two parts yourself — `const at = doc.findIndex((b) => b.type === 'divider')`, then `doc.slice(0, at + 1)` and `doc.slice(at + 1)` in two `<Preview>`s inside your own markup — and keep cutting the gated part for readers without access before it reaches the page. Add your own translation for any label you show.
+
+## From 0.0.1 to 0.0.2
+
+### 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

@@ -21,7 +21,6 @@ A plugin is a `BlockPlugin` object plus two Svelte components: a **view** for th
 | `accepts` | `string[]` | A container's allowed nested blocks, as palette ids; `'md:*'` is every built-in block. Default: everything the host offers. |
 | `markdown` | `(props: P, ctx: MarkdownContext) => string` | Its markdown form (optional). |
 | `unique` | `boolean` | At most one per document, top level only. |
-| `gate` | `boolean` | The blocks after it are gated; the preview marks them. |
 
 `P` is the props type of the plugin; declare it as an interface extending `Record<string, unknown>`.
 
@@ -141,7 +140,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 +150,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 +168,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 +187,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
 
@@ -262,23 +260,13 @@ How nesting works:
 - Wrapping blocks into a container from the Turn-into menu, and turning a container into another, is offered only when the container accepts every block going in.
 - `blocksSchemaFor(plugins)` checks `accepts` on the server (see [On the server](server-side.md)).
 
-## Unique and gate blocks
+## Unique blocks
 
-- **`unique: true`** — at most one per document, at the top level. Once the document has one, the plugin leaves the slash and Turn-into menus; nested editors never offer it.
-- **`gate: true`** — the blocks after the first top-level gate block are gated. The `Preview` renders them inside a section marked "For supporters only" with a dashed line; `markGated={false}` turns the marking off. Nested previews never split.
-
-A supporters-only divider is a typical example of both: one per document, with the gated content behind it.
-
-> **Gating only marks**
->
-> `gate` does not hide anything: the preview still renders every block, and the stored document still holds them. Deciding who may read the gated part — and leaving it out of the page for everyone else — is the host's job, on the server (see [Gated content](server-side.md#gated-content)). `unique` is not enforced by the schema either.
+**`unique: true`** — at most one per document, at the top level (a table of contents, for example). Once the document has one, the plugin leaves the slash and Turn-into menus, a second one pasted in falls back to its markdown form, and nested editors never offer it. The schema does not enforce it.
 
 ## 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 +276,145 @@ 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. |
 
+## Taking pasted tables
+
+When markdown with a GFM table is pasted into the editor, or imported with `fromMarkdown(text, { plugins })`, the table goes to the first plugin that has `fromTable`. It gets the table and returns the new block's props:
+
+```ts
+interface MarkdownTable {
+	rows: string[][]; // the cells as inline markdown, row by row; the first row is the header
+	align: ('left' | 'center' | 'right')[]; // per column, from the delimiter row (:--, :-:, --:)
+}
+
+fromTable?(table: MarkdownTable): P;
+```
+
+The bundled `table` has it (`fromTable: ({ rows, align }) => ({ rows, heads: ['top'], align })`), so a table pasted into an editor that offers it becomes a table block. Without such a plugin the table stays text.
+
+## Taking files
+
+When files are pasted into the editor (a copied image, a screenshot) or dropped on it from outside the page, the first plugin the editor offers that has `fromFiles` and returns props gets one block of its own:
+
+```ts
+fromFiles?(files: File[]): P | null | Promise<P | null>;
+```
+
+Return `null` to leave the files to the next plugin. Uploading and storing them is the plugin's business, so it may return a promise — upload, then return the props with the stored URL or id. A pasted file goes after the block with the caret (or in place of an empty one); a dropped one where the drop line shows.
+
+```ts
+fromFiles: async (files) => {
+	const file = files.find((f) => f.type.startsWith('image/'));
+	if (!file) return null;
+	const url = await uploadToMyStorage(file); // your app's upload
+	return { url, alt: file.name };
+},
+```
+
+## 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 +426,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 (egy beillesztett GFM-táblázatból ilyen lesz) | 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. A cella formázottan mutatja a szövegét; szerkesztéskor a markdown látszik, és a `Ctrl/Cmd` + `B`, `I`, `E`, `Shift+X`, `K` jelöli a kijelölt szöveget. 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. |