@lofcz/pptist 2.0.0 → 2.0.2

package/docs/EMBED.md

@@ -1,307 +1,307 @@
-# Embedding PPTist in sciobot-next (React)
-
-PPTist ships as a **Vite library bundle** (Vue + Pinia + UI inside one ESM chunk), not an iframe. The React host loads the module and calls an **imperative controller API**.
-
-## Build the embed bundle
-
-```bash
-cd PPTist
-npm install
-npm run build:embed
-```
-
-Outputs:
-
-| File | Purpose |
-|------|---------|
-| `dist/embed/pptist-embed.js` | ESM entry — `mountPptist`, `unmountPptist` |
-| `dist/embed/pptist-embed.css` | All styles (load via `<link>` from `assetBaseUrl`, not bundled in React) |
-| `dist/embed/mocks/`, `imgs/` | Runtime assets for templates / demo deck |
-
-## React usage
-
-```tsx
-import { useEffect, useRef } from 'react'
-import { mountPptist, type PptistController } from '@lofcz/pptist/embed'
-
-const assetBase = import.meta.env.VITE_PPTIST_ASSET_BASE ?? '/pptist-assets'
-
-export function PptistEditor({ locale }: { locale: 'cs' | 'en' | 'sk' | 'pl' }) {
-  const hostRef = useRef<HTMLDivElement>(null)
-  const controllerRef = useRef<PptistController | null>(null)
-
-  useEffect(() => {
-    const link = document.createElement('link')
-    link.rel = 'stylesheet'
-    link.href = `${assetBase}/pptist-embed.css`
-    document.head.appendChild(link)
-    return () => link.remove()
-  }, [])
-
-  useEffect(() => {
-    const el = hostRef.current
-    if (!el) return
-
-    let cancelled = false
-
-    void mountPptist(el, {
-      locale,
-      loadMockOnEmpty: true,
-      assetBaseUrl: import.meta.env.VITE_PPTIST_ASSET_BASE ?? '/pptist-assets',
-      onChange: (doc) => console.log('deck changed', doc.title),
-    }).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 (`PptistController`)
-
-| Method | Description |
-|--------|-------------|
-| `getDocument()` | `{ title, slides, theme }` JSON snapshot |
-| `setDocument(doc)` | Replace deck |
-| `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 |
-| `destroy()` | `app.unmount()` and clear 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') || 'PPTist command failed')
-}
-```
-
-### Domain API helpers
-
-For React code that is already coupled to `PptistController`, prefer the domain helpers. They keep command payloads typed while returning the same `PptistCommandResult` 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('PPTist 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<PptistDocument>({ type: 'export.json' })
-```
-
-`export.json()` and the `export.json` command return the serializable `PptistDocument` model and do not require the editor DOM. PDF, PPTX, and image exports depend on rendered slide DOM, browser canvas/image loading, and the existing export dialogs/hooks, so they are intentionally outside the agentic bridge. Hosts that need those formats should drive PPTist's UI/export workflow in a browser context or add a dedicated DOM-aware integration boundary.
-
-## sciobot-next wiring
-
-1. **package.json** — `"@lofcz/pptist": "^2.0.0"` after the package is published. During local development, sciobot's Vite config can fall back to the sibling `../PPTist/dist/embed` build.
-2. After changing PPTist locally, run `npm run build:embed` in PPTist, then restart or refresh sciobot.
-3. **VITE_PPTIST_ASSET_BASE** — URL prefix for `pptist-embed.css`, `mocks/`, and `imgs/`:
-   - Dev: proxy `/pptist-assets` → PPTist `dist/embed` or `public/`
-   - Prod: copy `dist/embed/{pptist-embed.css,mocks,imgs}` into sciobot `public/pptist-assets/`
-4. **Locale** — pass sciobot `Locales`; same union as typesafe-i18n in both apps.
-5. **Vite** — do not pre-bundle `@lofcz/pptist/embed` into React (keep Vue inside the embed chunk):
-
-```ts
-// vite.config.ts (sciobot-next)
-resolve: {
-  alias: {
-    '@lofcz/pptist/embed': path.resolve(__dirname, '../PPTist/dist/embed/pptist-embed.js'),
-  },
-},
-optimizeDeps: {
-  exclude: ['@lofcz/pptist/embed'],
-},
-```
-
-### CSS asset loading constraints
-
-Load `pptist-embed.css` as a plain asset from the same `assetBaseUrl` used for mocks and images:
-
-```tsx
-useEffect(() => {
-  const href = `${assetBase}/pptist-embed.css`
-  if (document.querySelector(`link[data-pptist-embed-css][href="${href}"]`)) return
-
-  const link = document.createElement('link')
-  link.rel = 'stylesheet'
-  link.href = href
-  link.dataset.pptistEmbedCss = 'true'
-  document.head.appendChild(link)
-
-  return () => {
-    document.querySelector(`link[data-pptist-embed-css][href="${href}"]`)?.remove()
-  }
-}, [])
-```
-
-Do not `import '@lofcz/pptist/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.
-
-## 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 `PptistDocument` in `linked_materials` + `presentation` kind in workspace tabs
-- Split chunk / lazy `import('@lofcz/pptist/embed')` on first open of presentation tab
+# Embedding PPTist in sciobot-next (React)
+
+PPTist ships as a **Vite library bundle** (Vue + Pinia + UI inside one ESM chunk), not an iframe. The React host loads the module and calls an **imperative controller API**.
+
+## Build the embed bundle
+
+```bash
+cd PPTist
+npm install
+npm run build:embed
+```
+
+Outputs:
+
+| File | Purpose |
+|------|---------|
+| `dist/embed/pptist-embed.js` | ESM entry — `mountPptist`, `unmountPptist` |
+| `dist/embed/pptist-embed.css` | All styles (load via `<link>` from `assetBaseUrl`, not bundled in React) |
+| `dist/embed/mocks/`, `imgs/` | Runtime assets for templates / demo deck |
+
+## React usage
+
+```tsx
+import { useEffect, useRef } from 'react'
+import { mountPptist, type PptistController } from '@lofcz/pptist/embed'
+
+const assetBase = import.meta.env.VITE_PPTIST_ASSET_BASE ?? '/pptist-assets'
+
+export function PptistEditor({ locale }: { locale: 'cs' | 'en' | 'sk' | 'pl' }) {
+  const hostRef = useRef<HTMLDivElement>(null)
+  const controllerRef = useRef<PptistController | null>(null)
+
+  useEffect(() => {
+    const link = document.createElement('link')
+    link.rel = 'stylesheet'
+    link.href = `${assetBase}/pptist-embed.css`
+    document.head.appendChild(link)
+    return () => link.remove()
+  }, [])
+
+  useEffect(() => {
+    const el = hostRef.current
+    if (!el) return
+
+    let cancelled = false
+
+    void mountPptist(el, {
+      locale,
+      loadMockOnEmpty: true,
+      assetBaseUrl: import.meta.env.VITE_PPTIST_ASSET_BASE ?? '/pptist-assets',
+      onChange: (doc) => console.log('deck changed', doc.title),
+    }).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 (`PptistController`)
+
+| Method | Description |
+|--------|-------------|
+| `getDocument()` | `{ title, slides, theme }` JSON snapshot |
+| `setDocument(doc)` | Replace deck |
+| `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 |
+| `destroy()` | `app.unmount()` and clear 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') || 'PPTist command failed')
+}
+```
+
+### Domain API helpers
+
+For React code that is already coupled to `PptistController`, prefer the domain helpers. They keep command payloads typed while returning the same `PptistCommandResult` 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('PPTist 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<PptistDocument>({ type: 'export.json' })
+```
+
+`export.json()` and the `export.json` command return the serializable `PptistDocument` model and do not require the editor DOM. PDF, PPTX, and image exports depend on rendered slide DOM, browser canvas/image loading, and the existing export dialogs/hooks, so they are intentionally outside the agentic bridge. Hosts that need those formats should drive PPTist's UI/export workflow in a browser context or add a dedicated DOM-aware integration boundary.
+
+## sciobot-next wiring
+
+1. **package.json** — `"@lofcz/pptist": "^2.0.0"` after the package is published. During local development, sciobot's Vite config can fall back to the sibling `../PPTist/dist/embed` build.
+2. After changing PPTist locally, run `npm run build:embed` in PPTist, then restart or refresh sciobot.
+3. **VITE_PPTIST_ASSET_BASE** — URL prefix for `pptist-embed.css`, `mocks/`, and `imgs/`:
+   - Dev: proxy `/pptist-assets` → PPTist `dist/embed` or `public/`
+   - Prod: copy `dist/embed/{pptist-embed.css,mocks,imgs}` into sciobot `public/pptist-assets/`
+4. **Locale** — pass sciobot `Locales`; same union as typesafe-i18n in both apps.
+5. **Vite** — do not pre-bundle `@lofcz/pptist/embed` into React (keep Vue inside the embed chunk):
+
+```ts
+// vite.config.ts (sciobot-next)
+resolve: {
+  alias: {
+    '@lofcz/pptist/embed': path.resolve(__dirname, '../PPTist/dist/embed/pptist-embed.js'),
+  },
+},
+optimizeDeps: {
+  exclude: ['@lofcz/pptist/embed'],
+},
+```
+
+### CSS asset loading constraints
+
+Load `pptist-embed.css` as a plain asset from the same `assetBaseUrl` used for mocks and images:
+
+```tsx
+useEffect(() => {
+  const href = `${assetBase}/pptist-embed.css`
+  if (document.querySelector(`link[data-pptist-embed-css][href="${href}"]`)) return
+
+  const link = document.createElement('link')
+  link.rel = 'stylesheet'
+  link.href = href
+  link.dataset.pptistEmbedCss = 'true'
+  document.head.appendChild(link)
+
+  return () => {
+    document.querySelector(`link[data-pptist-embed-css][href="${href}"]`)?.remove()
+  }
+}, [])
+```
+
+Do not `import '@lofcz/pptist/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.
+
+## 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 `PptistDocument` in `linked_materials` + `presentation` kind in workspace tabs
+- Split chunk / lazy `import('@lofcz/pptist/embed')` on first open of presentation tab