fika-editor 3.0.18 → 3.0.20

package/docs/EMBED.md

@@ -1,408 +1,408 @@
-# Embedding Fika in sciobot-next (React)
-
-Fika ships as an **ESM library** (`fika-editor/embed`), not an iframe. React and React DOM are **peer dependencies** (`>19.2`) — the host must install them and the embed imports the host copy. The standalone demo app bundles its own React.
-
-## Build the embed bundle
-
-```bash
-cd Fika
-npm install
-npm run build:embed
-```
-
-Outputs:
-
-| File | Purpose |
-|------|---------|
-| `dist/embed/fika-embed.js` | ESM entry — `mountFika`, `unmountFika` |
-| `dist/embed/fika-embed.css` | All styles (load via `<link>` from `assetBaseUrl`, not bundled in React) |
-| `dist/embed/mocks/`, `fonts/` | Optional demo mocks and runtime fonts |
-
-## React usage
-
-```tsx
-import { useEffect, useRef } from 'react'
-import { mountFika, type FikaController } from 'fika-editor/embed'
-
-const assetBase = import.meta.env.VITE_FIKA_ASSET_BASE ?? '/fika-assets'
-
-export function FikaEditor({ locale }: { locale: 'cs' | 'en' | 'sk' | 'pl' }) {
-  const hostRef = useRef<HTMLDivElement>(null)
-  const controllerRef = useRef<FikaController | null>(null)
-
-  useEffect(() => {
-    const link = document.createElement('link')
-    link.rel = 'stylesheet'
-    link.href = `${assetBase}/fika-embed.css`
-    document.head.appendChild(link)
-    return () => link.remove()
-  }, [])
-
-  useEffect(() => {
-    const el = hostRef.current
-    if (!el) return
-
-    let cancelled = false
-
-    void mountFika(el, {
-      locale,
-      loadMockOnEmpty: true,
-      assetBaseUrl: import.meta.env.VITE_FIKA_ASSET_BASE ?? '/fika-assets',
-      onChange: (doc) => console.log('deck changed', doc.title),
-      onPresentationModeChange: (active) => console.log('presentation mode', active),
-    }).then(({ controller }) => {
-      if (cancelled) {
-        controller.destroy()
-        return
-      }
-      controllerRef.current = controller
-    })
-
-    return () => {
-      cancelled = true
-      controllerRef.current?.destroy()
-      controllerRef.current = null
-    }
-  }, [locale])
-
-  return <div ref={hostRef} className="h-full min-h-0 w-full" />
-}
-```
-
-## Imperative API (`FikaController`)
-
-| Method | Description |
-|--------|-------------|
-| `getDocument()` | `{ title, slides, theme, viewport }` JSON snapshot |
-| `setDocument(doc)` | Replace deck (applies `viewport` when present) |
-| `setTitle(title)` | Update title only |
-| `setLocale(locale)` | `cs` / `en` / `sk` / `pl` + reload i18n namespaces |
-| `enterPresentation()` | Full-screen slide show |
-| `exitPresentation()` | Back to editor |
-| `export.json()` | Serializable `{ title, slides, theme }` snapshot for agent/host persistence |
-| `importPptx(data, options?)` | Parse a `.pptx` file into the editor. Default: replace, no confirm. `{ mode: 'append' }` inserts; `{ confirm: true }` asks before replacing a multi-slide deck. |
-| `destroy()` | Unmount the editor and clear the host |
-
-The controller also exposes the agentic bridge documented in [`AGENTIC_BRIDGE.md`](./AGENTIC_BRIDGE.md). Use the legacy document methods for whole-deck load/save boundaries, and use the bridge for sciobot agent edits inside an already-mounted editor.
-
-### Agent command execution
-
-`controller.execute()` accepts a typed `domain.action` command. This is useful when the agent runtime stores commands as JSON or streams tool calls from sciobot:
-
-```ts
-const result = await controller.execute({
-  id: crypto.randomUUID(),
-  type: 'slides.create',
-  payload: {
-    select: true,
-    slide: {
-      elements: [],
-      background: { type: 'solid', color: '#fff' },
-    },
-  },
-  meta: { source: 'agent', label: 'Create generated slide' },
-})
-
-if (!result.ok) {
-  throw new Error(result.errors?.map(error => error.message).join('\n') || 'Fika command failed')
-}
-```
-
-### Domain API helpers
-
-For React code that is already coupled to `FikaController`, prefer the domain helpers. They keep command payloads typed while returning the same `FikaCommandResult` shape:
-
-```ts
-const createSlide = await controller.slides.create({
-  select: true,
-  slide: {
-    elements: [],
-    background: { type: 'solid', color: '#fff' },
-  },
-}, { source: 'agent', label: 'Create lesson slide' })
-
-if (!createSlide.ok || !createSlide.data) return
-
-await controller.deck.setTitle('Generated sciobot presentation')
-
-const createTitle = await controller.elements.create({
-  slideId: createSlide.data.id,
-  element: {
-    type: 'text',
-    left: 80,
-    top: 80,
-    width: 640,
-    height: 96,
-    rotate: 0,
-    content: '<p>Generated by sciobot</p>',
-    defaultFontName: '',
-    defaultColor: '#111',
-  },
-})
-
-if (createTitle.ok && createTitle.data) {
-  await controller.links.set(createTitle.data.id, { type: 'web', target: 'https://sciobot.app' })
-  await controller.elements.select(createTitle.data.id)
-}
-
-await controller.slides.setRemark(createSlide.data.id, '<p>Teacher notes from the sciobot agent</p>')
-```
-
-### Bridge subscriptions
-
-Subscribe once when the controller is mounted, then unsubscribe before replacing or destroying it. `documentChanged` is the best signal for persistence, while `commandFailed` is the best signal for agent telemetry:
-
-```tsx
-useEffect(() => {
-  const controller = controllerRef.current
-  if (!controller) return
-
-  return controller.subscribe(event => {
-    if (event.type === 'documentChanged') {
-      void savePresentationDraft(event.data)
-    }
-
-    if (event.type === 'commandFailed') {
-      console.warn('Fika command failed', event.command, event.result?.errors)
-    }
-  })
-}, [controllerRef.current])
-```
-
-### Batch edits
-
-For agent workflows, prefer `executeBatch()` when multiple edits should be one undo step. Batch commands run with intermediate `commit: false` and commit once at the end unless `{ commit: false }` is passed:
-
-```ts
-const slideId = controller.slides.get()?.id
-if (!slideId) return
-
-const results = await controller.executeBatch([
-  { type: 'slides.select', payload: { slideIdOrIndex: slideId } },
-  {
-    type: 'elements.create',
-    payload: {
-      slideId,
-      element: {
-        type: 'text',
-        left: 80,
-        top: 80,
-        width: 520,
-        height: 96,
-        rotate: 0,
-        content: '<p>Agent summary</p>',
-        defaultFontName: '',
-        defaultColor: '#111',
-      },
-      select: true,
-    },
-  },
-  { type: 'slides.setRemark', payload: { slideId, remark: '<p>Notes</p>' } },
-], { atomic: true })
-
-const failed = results.find(result => !result.ok)
-if (failed) console.error(failed.errors)
-```
-
-Speaker remarks are stored as HTML strings. Use `controller.slides.getRemark(slideId)` or the `slides.getRemark` command to read them, and `controller.slides.setRemark(slideId, html)` or `slides.setRemark` to write them; successful writes return the updated slide in `result.data`.
-
-### Export Boundary
-
-The embed controller exposes JSON export only:
-
-```ts
-const document = controller.export.json()
-const result = await controller.execute<FikaDocument>({ type: 'export.json' })
-```
-
-`export.json()` and the `export.json` command return the serializable `FikaDocument` model and do not require the editor DOM. PPTX export depends on pptxgenjs and in-browser media inlining, so it stays on the editor export dialog rather than the agentic bridge. Hosts that need a PPTX file should drive Fika's export UI in a browser context or add a dedicated DOM-aware integration boundary.
-
-### Export dialog formats
-
-The export dialog offers native PPTX and JSON only. Hosts can hide either format via `exportTabs`; omitted keys stay enabled.
-
-```ts
-await mountFika(host, {
-  exportTabs: {
-    pptx: true,
-    json: false,
-  },
-})
-```
-
-When only one format is enabled, the dialog shows a single download card for that format.
-
-### Locale switcher
-
-The editor header's right cluster can show a locale button (`EN` / `CS` / `SK` / `PL`). It is **off by default** — embedding hosts usually drive locale via `mountFika({ locale })` or `controller.setLocale()`. Pass `showLocaleSwitcher: true` to enable it. The standalone demo turns it on from `App.tsx`.
-
-```ts
-await mountFika(host, {
-  locale: 'cs',
-  showLocaleSwitcher: true,
-})
-```
-
-### Export media resolver (CORS)
-
-Third-party image hosts often allow `<img>` display but block browser `fetch`/XHR (no `Access-Control-Allow-Origin`). PPTX export needs the bytes, so hosts can pass `exportMediaResolver` — typically a same-origin proxy that returns a `data:` URL:
-
-```ts
-await mountFika(host, {
-  exportMediaResolver: async (url) => {
-    const res = await fetch('/functions/v1/media-fetch', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', /* auth */ },
-      body: JSON.stringify({ url }),
-    })
-    if (!res.ok) return null
-    // … blob → data URL
-    return dataUrl
-  },
-})
-```
-
-Direct fetch is tried first; the resolver runs only on failure.
-
-### Media uploads
-
-The toolbar **Media** action (images, video, and audio) opens a local-file picker. Pexels / remote galleries are not used. Without a host `upload` callback, images become data URLs and audio/video become blob URLs — fine for demos, not for persistence.
-
-Pass `media` to `mountFika()` for production:
-
-```ts
-import { mountFika, createFikaMediaUploader } from 'fika-editor/embed'
-
-await mountFika(host, {
-  media: {
-    constraints: {
-      maxFiles: 12,
-      maxFileSize: {
-        image: 20 * 1024 * 1024,
-        audio: 50 * 1024 * 1024,
-        video: 200 * 1024 * 1024,
-      },
-      kinds: ['image', 'video', 'audio'],
-      // Optional extra allowlists:
-      // mimeTypes: ['image/png', 'image/jpeg', 'video/mp4'],
-      // extensions: ['png', 'jpg', 'jpeg', 'mp4', 'mp3'],
-      // accept: 'image/*,video/*,audio/*',
-    },
-    concurrency: 3,
-    upload: createFikaMediaUploader({
-      url: '/api/media',
-      fieldName: 'file',
-      headers: () => ({ Authorization: `Bearer ${token}` }),
-      // Default parser accepts `{ url }`, `{ src }`, or `{ data: { url } }`.
-    }),
-  },
-})
-```
-
-`upload` can also be a custom function if you need signed URLs or a non-FormData protocol:
-
-```ts
-media: {
-  upload: async ({ file, kind, signal, onProgress }) => {
-    // … PUT to a signed URL, call onProgress({ loaded, total })
-    return { src: 'https://cdn.example.com/slide-asset.mp4', ext: 'mp4' }
-  },
-}
-```
-
-## sciobot-next wiring
-
-1. **package.json** — `"fika-editor": "^2.0.0"` after the package is published. During local development, sciobot's Vite config can fall back to the sibling `../Fika/dist/embed` build.
-2. After changing Fika locally, run `npm run build:embed` in Fika, then restart or refresh sciobot.
-3. **VITE_FIKA_ASSET_BASE** — URL prefix for `fika-embed.css`, `mocks/`, and `imgs/`:
-   - Dev: proxy `/fika-assets` → Fika `dist/embed` or `public/`
-   - Prod: copy `dist/embed/{fika-embed.css,mocks,imgs}` into sciobot `public/fika-assets/`
-4. **Locale** — pass sciobot `Locales`; same union as typesafe-i18n in both apps.
-5. **Vite** — do not pre-bundle `fika-editor/embed` into the host app (keep the embed as its own chunk):
-
-```ts
-// vite.config.ts (sciobot-next)
-resolve: {
-  alias: {
-    'fika-editor/embed': path.resolve(__dirname, '../Fika/dist/embed/fika-embed.js'),
-  },
-},
-optimizeDeps: {
-  exclude: ['fika-editor/embed'],
-},
-```
-
-### CSS asset loading constraints
-
-Load `fika-embed.css` as a plain asset from the same `assetBaseUrl` used for mocks and images:
-
-```tsx
-useEffect(() => {
-  const href = `${assetBase}/fika-embed.css`
-  if (document.querySelector(`link[data-fika-embed-css][href="${href}"]`)) return
-
-  const link = document.createElement('link')
-  link.rel = 'stylesheet'
-  link.href = href
-  link.dataset.fikaEmbedCss = 'true'
-  document.head.appendChild(link)
-
-  return () => {
-    document.querySelector(`link[data-fika-embed-css][href="${href}"]`)?.remove()
-  }
-}, [])
-```
-
-Do not `import 'fika-editor/embed.css'` in React. The CSS is large and should not enter the host PostCSS/Tailwind pipeline.
-
-### Migrating legacy document calls
-
-Existing save/load code can keep using `getDocument()` and `setDocument()` at persistence boundaries:
-
-```ts
-await savePresentation(controller.getDocument())
-
-const document = await loadPresentation(id)
-controller.setDocument(document)
-```
-
-Agent edits should migrate to bridge commands so sciobot can observe command results, failures, and undo snapshots:
-
-```ts
-// Legacy: replace the whole document to add a slide.
-const document = controller.getDocument()
-controller.setDocument({
-  ...document,
-  slides: [...document.slides, generatedSlide],
-})
-
-// Agentic: create the slide through the bridge.
-await controller.slides.create({
-  slide: {
-    ...generatedSlide,
-    id: undefined,
-  },
-  select: true,
-})
-```
-
-Use `controller.export.json()`, `controller.import.json(document)`, or `controller.execute({ type: 'import.json', payload: { document } })` when the persistence layer wants command results for whole-document operations. Pass `{ mode: 'append' }` on import meta/payload to insert slides instead of replacing; `{ confirm: false }` skips the replace dialog (the default on the controller).
-
-## Host CSS
-
-Load `fika-embed.css` as a standalone `<link>` (do not bundle it through the host toolchain). The embed root resets inherited host preflight — especially Tailwind's `html { line-height: 1.5 }` and `img { max-width: 100% }` — so slide text and media match the standalone demo.
-
-Persist `document.viewport` from `onChange` / `getDocument()` and pass it back on `mount` / `setDocument`. Without it, imported decks fall back to 1000×16:9 and elements overflow the slide box.
-
-## Why not iframe?
-
-- Shared imperative API for save/load with Supabase
-- Locale driven by sciobot zustand without postMessage
-- Single CSP / auth surface when both apps are same origin
-- Heavier initial JS, but one integrated surface for teachers
-
-## Future
-
-- `postMessage` optional bridge for cross-origin CDN hosting
-- Persist `FikaDocument` in `linked_materials` + `presentation` kind in workspace tabs
-- Split chunk / lazy `import('fika-editor/embed')` on first open of presentation tab
+# Embedding Fika in sciobot-next (React)
+
+Fika ships as an **ESM library** (`fika-editor/embed`), not an iframe. React and React DOM are **peer dependencies** (`>19.2`) — the host must install them and the embed imports the host copy. The standalone demo app bundles its own React.
+
+## Build the embed bundle
+
+```bash
+cd Fika
+npm install
+npm run build:embed
+```
+
+Outputs:
+
+| File | Purpose |
+|------|---------|
+| `dist/embed/fika-embed.js` | ESM entry — `mountFika`, `unmountFika` |
+| `dist/embed/fika-embed.css` | All styles (load via `<link>` from `assetBaseUrl`, not bundled in React) |
+| `dist/embed/mocks/`, `fonts/` | Optional demo mocks and runtime fonts |
+
+## React usage
+
+```tsx
+import { useEffect, useRef } from 'react'
+import { mountFika, type FikaController } from 'fika-editor/embed'
+
+const assetBase = import.meta.env.VITE_FIKA_ASSET_BASE ?? '/fika-assets'
+
+export function FikaEditor({ locale }: { locale: 'cs' | 'en' | 'sk' | 'pl' }) {
+  const hostRef = useRef<HTMLDivElement>(null)
+  const controllerRef = useRef<FikaController | null>(null)
+
+  useEffect(() => {
+    const link = document.createElement('link')
+    link.rel = 'stylesheet'
+    link.href = `${assetBase}/fika-embed.css`
+    document.head.appendChild(link)
+    return () => link.remove()
+  }, [])
+
+  useEffect(() => {
+    const el = hostRef.current
+    if (!el) return
+
+    let cancelled = false
+
+    void mountFika(el, {
+      locale,
+      loadMockOnEmpty: true,
+      assetBaseUrl: import.meta.env.VITE_FIKA_ASSET_BASE ?? '/fika-assets',
+      onChange: (doc) => console.log('deck changed', doc.title),
+      onPresentationModeChange: (active) => console.log('presentation mode', active),
+    }).then(({ controller }) => {
+      if (cancelled) {
+        controller.destroy()
+        return
+      }
+      controllerRef.current = controller
+    })
+
+    return () => {
+      cancelled = true
+      controllerRef.current?.destroy()
+      controllerRef.current = null
+    }
+  }, [locale])
+
+  return <div ref={hostRef} className="h-full min-h-0 w-full" />
+}
+```
+
+## Imperative API (`FikaController`)
+
+| Method | Description |
+|--------|-------------|
+| `getDocument()` | `{ title, slides, theme, viewport }` JSON snapshot |
+| `setDocument(doc)` | Replace deck (applies `viewport` when present) |
+| `setTitle(title)` | Update title only |
+| `setLocale(locale)` | `cs` / `en` / `sk` / `pl` + reload i18n namespaces |
+| `enterPresentation()` | Full-screen slide show |
+| `exitPresentation()` | Back to editor |
+| `export.json()` | Serializable `{ title, slides, theme }` snapshot for agent/host persistence |
+| `importPptx(data, options?)` | Parse a `.pptx` file into the editor. Default: replace, no confirm. `{ mode: 'append' }` inserts; `{ confirm: true }` asks before replacing a multi-slide deck. |
+| `destroy()` | Unmount the editor and clear the host |
+
+The controller also exposes the agentic bridge documented in [`AGENTIC_BRIDGE.md`](./AGENTIC_BRIDGE.md). Use the legacy document methods for whole-deck load/save boundaries, and use the bridge for sciobot agent edits inside an already-mounted editor.
+
+### Agent command execution
+
+`controller.execute()` accepts a typed `domain.action` command. This is useful when the agent runtime stores commands as JSON or streams tool calls from sciobot:
+
+```ts
+const result = await controller.execute({
+  id: crypto.randomUUID(),
+  type: 'slides.create',
+  payload: {
+    select: true,
+    slide: {
+      elements: [],
+      background: { type: 'solid', color: '#fff' },
+    },
+  },
+  meta: { source: 'agent', label: 'Create generated slide' },
+})
+
+if (!result.ok) {
+  throw new Error(result.errors?.map(error => error.message).join('\n') || 'Fika command failed')
+}
+```
+
+### Domain API helpers
+
+For React code that is already coupled to `FikaController`, prefer the domain helpers. They keep command payloads typed while returning the same `FikaCommandResult` shape:
+
+```ts
+const createSlide = await controller.slides.create({
+  select: true,
+  slide: {
+    elements: [],
+    background: { type: 'solid', color: '#fff' },
+  },
+}, { source: 'agent', label: 'Create lesson slide' })
+
+if (!createSlide.ok || !createSlide.data) return
+
+await controller.deck.setTitle('Generated sciobot presentation')
+
+const createTitle = await controller.elements.create({
+  slideId: createSlide.data.id,
+  element: {
+    type: 'text',
+    left: 80,
+    top: 80,
+    width: 640,
+    height: 96,
+    rotate: 0,
+    content: '<p>Generated by sciobot</p>',
+    defaultFontName: '',
+    defaultColor: '#111',
+  },
+})
+
+if (createTitle.ok && createTitle.data) {
+  await controller.links.set(createTitle.data.id, { type: 'web', target: 'https://sciobot.app' })
+  await controller.elements.select(createTitle.data.id)
+}
+
+await controller.slides.setRemark(createSlide.data.id, '<p>Teacher notes from the sciobot agent</p>')
+```
+
+### Bridge subscriptions
+
+Subscribe once when the controller is mounted, then unsubscribe before replacing or destroying it. `documentChanged` is the best signal for persistence, while `commandFailed` is the best signal for agent telemetry:
+
+```tsx
+useEffect(() => {
+  const controller = controllerRef.current
+  if (!controller) return
+
+  return controller.subscribe(event => {
+    if (event.type === 'documentChanged') {
+      void savePresentationDraft(event.data)
+    }
+
+    if (event.type === 'commandFailed') {
+      console.warn('Fika command failed', event.command, event.result?.errors)
+    }
+  })
+}, [controllerRef.current])
+```
+
+### Batch edits
+
+For agent workflows, prefer `executeBatch()` when multiple edits should be one undo step. Batch commands run with intermediate `commit: false` and commit once at the end unless `{ commit: false }` is passed:
+
+```ts
+const slideId = controller.slides.get()?.id
+if (!slideId) return
+
+const results = await controller.executeBatch([
+  { type: 'slides.select', payload: { slideIdOrIndex: slideId } },
+  {
+    type: 'elements.create',
+    payload: {
+      slideId,
+      element: {
+        type: 'text',
+        left: 80,
+        top: 80,
+        width: 520,
+        height: 96,
+        rotate: 0,
+        content: '<p>Agent summary</p>',
+        defaultFontName: '',
+        defaultColor: '#111',
+      },
+      select: true,
+    },
+  },
+  { type: 'slides.setRemark', payload: { slideId, remark: '<p>Notes</p>' } },
+], { atomic: true })
+
+const failed = results.find(result => !result.ok)
+if (failed) console.error(failed.errors)
+```
+
+Speaker remarks are stored as HTML strings. Use `controller.slides.getRemark(slideId)` or the `slides.getRemark` command to read them, and `controller.slides.setRemark(slideId, html)` or `slides.setRemark` to write them; successful writes return the updated slide in `result.data`.
+
+### Export Boundary
+
+The embed controller exposes JSON export only:
+
+```ts
+const document = controller.export.json()
+const result = await controller.execute<FikaDocument>({ type: 'export.json' })
+```
+
+`export.json()` and the `export.json` command return the serializable `FikaDocument` model and do not require the editor DOM. PPTX export depends on pptxgenjs and in-browser media inlining, so it stays on the editor export dialog rather than the agentic bridge. Hosts that need a PPTX file should drive Fika's export UI in a browser context or add a dedicated DOM-aware integration boundary.
+
+### Export dialog formats
+
+The export dialog offers native PPTX and JSON only. Hosts can hide either format via `exportTabs`; omitted keys stay enabled.
+
+```ts
+await mountFika(host, {
+  exportTabs: {
+    pptx: true,
+    json: false,
+  },
+})
+```
+
+When only one format is enabled, the dialog shows a single download card for that format.
+
+### Locale switcher
+
+The editor header's right cluster can show a locale button (`EN` / `CS` / `SK` / `PL`). It is **off by default** — embedding hosts usually drive locale via `mountFika({ locale })` or `controller.setLocale()`. Pass `showLocaleSwitcher: true` to enable it. The standalone demo turns it on from `App.tsx`.
+
+```ts
+await mountFika(host, {
+  locale: 'cs',
+  showLocaleSwitcher: true,
+})
+```
+
+### Export media resolver (CORS)
+
+Third-party image hosts often allow `<img>` display but block browser `fetch`/XHR (no `Access-Control-Allow-Origin`). PPTX export needs the bytes, so hosts can pass `exportMediaResolver` — typically a same-origin proxy that returns a `data:` URL:
+
+```ts
+await mountFika(host, {
+  exportMediaResolver: async (url) => {
+    const res = await fetch('/functions/v1/media-fetch', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', /* auth */ },
+      body: JSON.stringify({ url }),
+    })
+    if (!res.ok) return null
+    // … blob → data URL
+    return dataUrl
+  },
+})
+```
+
+Direct fetch is tried first; the resolver runs only on failure.
+
+### Media uploads
+
+The toolbar **Media** action (images, video, and audio) opens a local-file picker. Pexels / remote galleries are not used. Without a host `upload` callback, images become data URLs and audio/video become blob URLs — fine for demos, not for persistence.
+
+Pass `media` to `mountFika()` for production:
+
+```ts
+import { mountFika, createFikaMediaUploader } from 'fika-editor/embed'
+
+await mountFika(host, {
+  media: {
+    constraints: {
+      maxFiles: 12,
+      maxFileSize: {
+        image: 20 * 1024 * 1024,
+        audio: 50 * 1024 * 1024,
+        video: 200 * 1024 * 1024,
+      },
+      kinds: ['image', 'video', 'audio'],
+      // Optional extra allowlists:
+      // mimeTypes: ['image/png', 'image/jpeg', 'video/mp4'],
+      // extensions: ['png', 'jpg', 'jpeg', 'mp4', 'mp3'],
+      // accept: 'image/*,video/*,audio/*',
+    },
+    concurrency: 3,
+    upload: createFikaMediaUploader({
+      url: '/api/media',
+      fieldName: 'file',
+      headers: () => ({ Authorization: `Bearer ${token}` }),
+      // Default parser accepts `{ url }`, `{ src }`, or `{ data: { url } }`.
+    }),
+  },
+})
+```
+
+`upload` can also be a custom function if you need signed URLs or a non-FormData protocol:
+
+```ts
+media: {
+  upload: async ({ file, kind, signal, onProgress }) => {
+    // … PUT to a signed URL, call onProgress({ loaded, total })
+    return { src: 'https://cdn.example.com/slide-asset.mp4', ext: 'mp4' }
+  },
+}
+```
+
+## sciobot-next wiring
+
+1. **package.json** — `"fika-editor": "^2.0.0"` after the package is published. During local development, sciobot's Vite config can fall back to the sibling `../Fika/dist/embed` build.
+2. After changing Fika locally, run `npm run build:embed` in Fika, then restart or refresh sciobot.
+3. **VITE_FIKA_ASSET_BASE** — URL prefix for `fika-embed.css`, `mocks/`, and `imgs/`:
+   - Dev: proxy `/fika-assets` → Fika `dist/embed` or `public/`
+   - Prod: copy `dist/embed/{fika-embed.css,mocks,imgs}` into sciobot `public/fika-assets/`
+4. **Locale** — pass sciobot `Locales`; same union as typesafe-i18n in both apps.
+5. **Vite** — do not pre-bundle `fika-editor/embed` into the host app (keep the embed as its own chunk):
+
+```ts
+// vite.config.ts (sciobot-next)
+resolve: {
+  alias: {
+    'fika-editor/embed': path.resolve(__dirname, '../Fika/dist/embed/fika-embed.js'),
+  },
+},
+optimizeDeps: {
+  exclude: ['fika-editor/embed'],
+},
+```
+
+### CSS asset loading constraints
+
+Load `fika-embed.css` as a plain asset from the same `assetBaseUrl` used for mocks and images:
+
+```tsx
+useEffect(() => {
+  const href = `${assetBase}/fika-embed.css`
+  if (document.querySelector(`link[data-fika-embed-css][href="${href}"]`)) return
+
+  const link = document.createElement('link')
+  link.rel = 'stylesheet'
+  link.href = href
+  link.dataset.fikaEmbedCss = 'true'
+  document.head.appendChild(link)
+
+  return () => {
+    document.querySelector(`link[data-fika-embed-css][href="${href}"]`)?.remove()
+  }
+}, [])
+```
+
+Do not `import 'fika-editor/embed.css'` in React. The CSS is large and should not enter the host PostCSS/Tailwind pipeline.
+
+### Migrating legacy document calls
+
+Existing save/load code can keep using `getDocument()` and `setDocument()` at persistence boundaries:
+
+```ts
+await savePresentation(controller.getDocument())
+
+const document = await loadPresentation(id)
+controller.setDocument(document)
+```
+
+Agent edits should migrate to bridge commands so sciobot can observe command results, failures, and undo snapshots:
+
+```ts
+// Legacy: replace the whole document to add a slide.
+const document = controller.getDocument()
+controller.setDocument({
+  ...document,
+  slides: [...document.slides, generatedSlide],
+})
+
+// Agentic: create the slide through the bridge.
+await controller.slides.create({
+  slide: {
+    ...generatedSlide,
+    id: undefined,
+  },
+  select: true,
+})
+```
+
+Use `controller.export.json()`, `controller.import.json(document)`, or `controller.execute({ type: 'import.json', payload: { document } })` when the persistence layer wants command results for whole-document operations. Pass `{ mode: 'append' }` on import meta/payload to insert slides instead of replacing; `{ confirm: false }` skips the replace dialog (the default on the controller).
+
+## Host CSS
+
+Load `fika-embed.css` as a standalone `<link>` (do not bundle it through the host toolchain). The embed root resets inherited host preflight — especially Tailwind's `html { line-height: 1.5 }` and `img { max-width: 100% }` — so slide text and media match the standalone demo.
+
+Persist `document.viewport` from `onChange` / `getDocument()` and pass it back on `mount` / `setDocument`. Without it, imported decks fall back to 1000×16:9 and elements overflow the slide box.
+
+## Why not iframe?
+
+- Shared imperative API for save/load with Supabase
+- Locale driven by sciobot zustand without postMessage
+- Single CSP / auth surface when both apps are same origin
+- Heavier initial JS, but one integrated surface for teachers
+
+## Future
+
+- `postMessage` optional bridge for cross-origin CDN hosting
+- Persist `FikaDocument` in `linked_materials` + `presentation` kind in workspace tabs
+- Split chunk / lazy `import('fika-editor/embed')` on first open of presentation tab