@charisol/plexo-sdk 2.0.27 → 2.0.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +301 -0
  2. package/dist/{InlineColorPicker-BYcOgLVc.js → InlineColorPicker-XesBzRsU.js} +362 -114
  3. package/dist/{v1-Dm9rxrfa.js → blank-BEl6CY5C.js} +4657 -10897
  4. package/dist/brandGuide-Dd4fqVjS.js +33 -0
  5. package/dist/{client-DUSU8g5z.js → client-CWui0-3q.js} +1 -1
  6. package/dist/codeEditor-Cux0ud2j.js +205 -0
  7. package/dist/files-Df6FY0HK.js +2182 -0
  8. package/dist/id-CR6Y8qD6.js +8 -0
  9. package/dist/index.js +12786 -13034
  10. package/dist/{brandGuide-DgoZ7spo.js → lint-CV3DmM0X.js} +78 -109
  11. package/dist/pdfImport-BOev0Pc1.js +262 -0
  12. package/dist/plexo-sdk.css +1 -1
  13. package/dist/v1-Cn7SGvZk.js +6253 -0
  14. package/dist/v2/CanvasEditor.d.ts +25 -0
  15. package/dist/v2/V2Editor.d.ts +15 -20
  16. package/dist/v2/compile/build.d.ts +5 -0
  17. package/dist/v2/components/properties/PropertiesPanel.d.ts +1 -0
  18. package/dist/v2/files/aiPicture.d.ts +85 -0
  19. package/dist/v2/files/build.d.ts +49 -0
  20. package/dist/v2/files/capture.d.ts +52 -0
  21. package/dist/v2/files/convert.d.ts +24 -0
  22. package/dist/v2/files/docx.d.ts +1 -0
  23. package/dist/v2/files/engine.d.ts +2 -0
  24. package/dist/v2/files/export.d.ts +97 -0
  25. package/dist/v2/files/import.d.ts +34 -0
  26. package/dist/v2/files/index.d.ts +16 -0
  27. package/dist/v2/files/pdf.d.ts +15 -0
  28. package/dist/v2/files/pdfImport.d.ts +28 -0
  29. package/dist/v2/files/sheet.d.ts +16 -0
  30. package/dist/v2/files/text.d.ts +8 -0
  31. package/dist/v2/files/types.d.ts +96 -0
  32. package/dist/v2/files/ui/ExportDock.d.ts +11 -0
  33. package/dist/v2/files/ui/ExportMenu.d.ts +5 -0
  34. package/dist/v2/files/ui/ExportPanel.d.ts +17 -0
  35. package/dist/v2/files/ui/FileEditor.d.ts +14 -0
  36. package/dist/v2/files/ui/HtmlWorkbench.d.ts +15 -0
  37. package/dist/v2/files/ui/codeEditor.d.ts +12 -0
  38. package/dist/v2/files/ui/editors.d.ts +28 -0
  39. package/dist/v2/files/vector.d.ts +19 -0
  40. package/dist/v2/files/zip.d.ts +10 -0
  41. package/dist/v2/host/HostContext.d.ts +6 -3
  42. package/dist/v2/index.d.ts +5 -1
  43. package/dist/v2-compile.js +17 -16
  44. package/dist/v2-files.js +3 -0
  45. package/dist/v2-strata.js +2 -2
  46. package/dist/v2.js +5805 -4038
  47. package/package.json +18 -3
package/README.md CHANGED
@@ -14,6 +14,7 @@
14
14
  - 🤖 **AI content generation** — edit a single element, edit the whole layout, or generate a fresh layout from a prompt, with support for OpenAI, Gemini, and Claude
15
15
  - 🔒 **Server-proxied AI, no exposed keys** — your provider API key is never sent to or stored in the browser; every AI request is authenticated with your Plexo API key and resolved against your account's server-side configuration
16
16
  - 💬 **Claude-Code-style AI feedback** — a loading bubble followed by a one-line summary of what changed, for both the per-element editor and the layout prompt bar
17
+ - 📁 **File editor & export** — open or create designs, HTML (with a code editor), documents, text, Markdown, spreadsheets, PDFs and pictures; export to PNG, JPG, PDF, SVG, DOCX, XLSX and more, including a Figma-style export from the landing-page canvas (see [File editor & export](#file-editor--export-v2))
17
18
  - 🖼️ **Stock image search** — Unsplash, Pexels, Pixabay integrations
18
19
  - 🎨 **Design token system** — Strata token support for consistent brand theming
19
20
  - 📦 **ESM-only, pure client-side component** — nothing to self-host; the SDK talks directly to Plexo's hosted API for AI/publish/compile using your Plexo API key
@@ -319,6 +320,305 @@ The previous V2 (`V2Canvas`, `useCanvasStore`, `compilePageToReact(nodes, pageOr
319
320
 
320
321
  ---
321
322
 
323
+ ## File editor & export (v2)
324
+
325
+ Everything in this section ships in `@charisol/plexo-sdk/v2` (the editor) and `@charisol/plexo-sdk/v2/files` (the same engine without any UI).
326
+
327
+ ### Quick start
328
+
329
+ ```bash
330
+ npm install @charisol/plexo-sdk # one package; the PDF reader and code editor are included and load only when needed
331
+ ```
332
+
333
+ ```tsx
334
+ 'use client'; // the editor runs in the browser (in Next.js, load it with next/dynamic and ssr: false)
335
+ import { V2Editor } from '@charisol/plexo-sdk/v2';
336
+ import '@charisol/plexo-sdk/dist/plexo-sdk.css';
337
+
338
+ export default function Files() {
339
+ return (
340
+ <div style={{ height: '100vh' }}> {/* the editor fills its container, so give the parent a height */}
341
+ <V2Editor mode="file" /> {/* that's it: start screen, editors, preview and Export all work with no other props */}
342
+ </div>
343
+ );
344
+ }
345
+ ```
346
+
347
+ With no other props, people can create or open files and **Export** them (downloads). Add what your app needs:
348
+
349
+ | You want to… | Pass |
350
+ |---|---|
351
+ | Get the finished file back in your app (upload it, store it) | `files={{ onSaveFile }}` → shows **Save** |
352
+ | Choose what they make yourself, or open a given file | `files={{ kind }}` or `files={{ file }}` (see "Using your own screens") |
353
+ | Store pictures the editor makes on your storage instead of embedding them | `onUpload={(file) => url}` |
354
+ | Turn pictures into editable designs with AI | nothing inside the Plexo dashboard; elsewhere `files={{ imageAi }}` |
355
+ | Match your brand | `theme={{ accent, background, text }}` |
356
+ | Only export from the landing-page / email canvas | nothing — it's already there (section 1) |
357
+
358
+ Things that are **not** needed: an API key (only for the AI inside the Plexo dashboard), a server, or any build configuration.
359
+
360
+ ### 1. Export from the landing-page / email canvas
361
+
362
+ Nothing to set up — every `V2Editor` has it. Click an element (or several, or nothing for the whole page) and use the **Export** section under the right-hand panel (shortcut ⇧⌘E / Ctrl+Shift+E), or the Export button in the top bar.
363
+
364
+ | You get | How |
365
+ |---|---|
366
+ | PNG, JPG, PDF, SVG | One or more rows of *size + format* (1x–4x), then **Export**. Several rows download as one zip. |
367
+ | Just part of a page | The selection is cut out like Figma does: one element, or several together as one picture. Nothing selected = the whole page at the current screen size (desktop / tablet / phone). |
368
+ | PDF | One long page, or split into A4 pages. |
369
+ | SVG | **Editable shapes and text** (default; opens in Figma / Illustrator) or **Exact look** (the browser's own drawing wrapped in an SVG). Rotation, gradients (linear, radial, conic), shadows (several, inset, text), gradient text, filters, tiled backgrounds, form fields and list bullets are all drawn. Embedded videos/maps from other sites appear as a grey play-mark box, and frosted-glass blur isn't possible in SVG; the owner is told when either is present. |
370
+ | Emails | Exported whole, as they will be sent. |
371
+
372
+ Hide the top-bar button with `features={{ exportMenu: false }}` (the panel stays). Pictures hosted on another site must allow copying (CORS) to be included; the owner sees a plain-words warning when one can't be.
373
+
374
+ ### 2. The file editor — `mode="file"` and `mode="hybrid"`
375
+
376
+ Pass a flag and the editor opens as a **file editor** instead of the page builder, the same way `mode="email"` switches it to emails:
377
+
378
+ ```tsx
379
+ import { V2Editor } from '@charisol/plexo-sdk/v2';
380
+
381
+ <V2Editor
382
+ mode="file" // or "hybrid"
383
+ apiKey="workspace-internal" // inside the Plexo dashboard — turns the built-in AI on (see below)
384
+ onUpload={uploadImage} // optional: where pictures made by the editor are stored (else they're embedded)
385
+ files={{
386
+ file, // optional: a File/Blob to open, or a FileSource you saved before
387
+ kind: 'design', // optional: start a new file of this kind
388
+ onSaveFile: async (r) => { // optional: shows Save; called with the finished file
389
+ await upload(r.blob, r.filename); // r.blob is in the format the person chose
390
+ await db.save(r.source); // r.source reopens it later: files={{ file: r.source }}
391
+ },
392
+ onClose: () => router.back(), // optional: shows a Back button
393
+ }}
394
+ />
395
+ ```
396
+
397
+ - **`mode="file"`** — Design (a single-page visual canvas), **HTML** (a web page as code), Document, Text, Markdown and Sheet.
398
+ - **`mode="hybrid"`** — the same, plus Email, and the design view keeps your full page tooling (page list, branding, library; pass `pageSource`, `features` etc. as usual).
399
+ - With no `file` or `kind` the person sees a start screen: pick a type, or drop in a file.
400
+
401
+ **What the person can do**
402
+
403
+ - **Switch type** with the toggle at the top: the content is converted (and Undo is offered). **Text** is plain text only: no design tools, no preview.
404
+ - **HTML files** open exactly as written (nothing stripped or rewritten) in a code editor with syntax colours for HTML, CSS and JavaScript, auto-closing tags, indent, folding and search, with the page live beside it (computer / tablet / phone width). Paste a whole page or a fragment, edit it, then Export or Save as PNG, PDF, SVG and more; what's exported is what the preview shows (scripts don't run). The editor engine (CodeMirror) loads only when an HTML file is opened. A design's HTML tab has **Edit this as HTML** to turn it into a code file.
405
+ - **Switch view**: Visual / HTML / Preview. Preview is the picture an export would make. A Document's HTML is editable.
406
+ - **Open** PDF, pictures (PNG, JPG, WebP, GIF, SVG), `.docx`, `.xlsx`, `.csv`, `.html` (as code), `.md`, `.txt`.
407
+ - **Export** (downloads) and **Save** (sends to your app via `onSaveFile`) in: PNG, JPG, PDF, SVG, HTML, TXT, MD, DOCX, CSV, XLSX. The formats offered depend on the type; limit them with `files.saveFormats`.
408
+ - **Spreadsheets** have a grid with formulas (`=SUM(A1:A5)`, `+ − × ÷`, `AVERAGE MIN MAX COUNT ROUND ABS SQRT`), paste from Excel/Sheets, and `.xlsx` / `.csv` export.
409
+
410
+ **What a saved file looks like**
411
+
412
+ ```ts
413
+ // What onSaveFile receives
414
+ interface FileSaveResult {
415
+ kind: FileKind; // 'design' | 'email' | 'html' | 'document' | 'text' | 'markdown' | 'sheet'
416
+ name: string; // without extension
417
+ format: ExportFormat; // what they chose: 'png' | 'jpeg' | 'pdf' | 'svg' | 'html' | 'txt' | 'md' | 'docx' | 'csv' | 'xlsx'
418
+ filename: string; // "Quarterly report.pdf"
419
+ blob: Blob; // the finished file: upload this
420
+ source: FileSource; // the editable version: store this, reopen it later with files={{ file: source }}
421
+ warnings: string[]; // plain-words notes for the person (e.g. a picture that couldn't be included)
422
+ }
423
+
424
+ // FileSource is plain JSON, safe to keep in your database
425
+ type FileSource =
426
+ | { kind: 'design' | 'email'; name: string; content: PageDefinition[] } // pages from the visual canvas
427
+ | { kind: 'html' | 'document' | 'text' | 'markdown'; name: string; content: string }
428
+ | { kind: 'sheet'; name: string; content: string[][] }; // rows of cells ("=SUM(A1:A3)" for formulas)
429
+ ```
430
+
431
+ **`files` options**
432
+
433
+ | Option | What it does |
434
+ |---|---|
435
+ | `file` | `File` / `Blob` to open (type detected from its name), or a `FileSource` returned earlier by `onSaveFile`. |
436
+ | `fileName` | Name to use when `file` is an unnamed Blob. |
437
+ | `kind` | Start a new file of `'design' \| 'email' \| 'html' \| 'document' \| 'text' \| 'markdown' \| 'sheet'`. |
438
+ | `kinds` | Which types to offer. |
439
+ | `saveFormats` | Formats under "Save as". |
440
+ | `onSaveFile(result)` | Save button. `result` = `{ kind, name, format, filename, blob, source, warnings }`. |
441
+ | `onClose` | Back button. |
442
+ | `onConvertImage`, `imageAi`, `aiConversion` | AI picture conversion — see below. |
443
+
444
+ ### Using your own screens (you choose, we edit)
445
+
446
+ You don't have to use our "What would you like to make?" screen. Decide in your own UI, then hand the editor the result; it handles everything after that (the editing screens, preview, export, save) in your colours.
447
+
448
+ ```tsx
449
+ import { V2Editor, type V2EditorHandle } from '@charisol/plexo-sdk/v2';
450
+ const ref = useRef<V2EditorHandle>(null);
451
+
452
+ // 1. Your chooser decided: open straight into it. No start screen, and no type switch if the type shouldn't change.
453
+ <V2Editor ref={ref} mode="file" theme={{ accent: '#7c3aed', background: '#ffffff', text: '#111827' }}
454
+ files={{ kind: 'html', showTypeSwitcher: false, onSaveFile: save }} />
455
+
456
+ // 2. Or hand it a file the person picked or you stored (File/Blob of any supported type, or a FileSource).
457
+ <V2Editor mode="file" files={{ file: pickedFile, showTypeSwitcher: false }} />
458
+
459
+ // 3. Or keep one mounted editor and drive it: switching is also just a prop change (`files.kind` / `files.file`).
460
+ await ref.current.open(file); // open a file, replacing what is open
461
+ ref.current.create('sheet', 'Budget'); // a new empty file
462
+ const source = ref.current.getSource(); // store this; reopen later with files={{ file: source }}
463
+ const png = await ref.current.exportAs('png', { scale: 2 }); // { blob, filename, warnings }, nothing saved anywhere
464
+ await ref.current.save('pdf'); // through your onSaveFile
465
+ ```
466
+
467
+ | Option | What it does |
468
+ |---|---|
469
+ | `files.startScreen: false` | Never show our chooser. With nothing given, a new file of the first of `kinds` opens. |
470
+ | `files.kind` / `files.file` | What to open. Followed as they change, not read once. |
471
+ | `files.showTypeSwitcher: false` | Hide the Design / HTML / Document… switch. |
472
+ | `files.kinds` | Which types exist (also limits the switch). |
473
+ | `headerLeft` / `headerRight` | Your own controls in the editor's top bar. |
474
+ | `theme` | `{ accent, background, text }`: every shade (panels, borders, hover, muted text) is mixed from these, and a light background works as well as a dark one. |
475
+
476
+ ### 3. Opening a PDF for editing
477
+
478
+ A PDF opens as a multi-page design (up to 30 pages): each page is drawn as a picture with its words wiped out, and the words are placed on top as **real, movable, editable text** (position, size, colour, bold/italic and font family are carried over). **Export → PDF** writes every page back. A **scanned** PDF has no words to read, so each page goes through the AI picture conversion below (up to 10 pages), or is placed as a picture when AI isn't available. Password-protected PDFs are refused with a plain message. The PDF reader (`pdfjs-dist`) is loaded only when a PDF is opened. Your bundler must be able to resolve it (it is a dependency of this package; with Next.js nothing extra is needed).
479
+
480
+ ### 4. Turning a picture into an editable design (AI)
481
+
482
+ When someone opens a picture (or a scanned PDF page), a vision model describes its parts — text, boxes, photos with positions — and the editor rebuilds them as real elements. Photos are cut out of the original, never redrawn. The person can **Skip** while it works and **Undo** afterwards to get the original picture on the canvas.
483
+
484
+ - **Inside the Plexo dashboard** (`apiKey="workspace-internal"`): built in. It calls `POST /api/v1/ai/image-to-design` on plexo-web, which uses the account's AI credits/keys. Nothing to pass.
485
+ - **Elsewhere**, give the editor a way to reach a vision model — the simplest is `imageAi`, which only sends the picture and returns the model's JSON:
486
+
487
+ ```tsx
488
+ import { IMAGE_TO_DESIGN_PROMPT } from '@charisol/plexo-sdk/v2/files';
489
+
490
+ <V2Editor
491
+ mode="file"
492
+ files={{
493
+ imageAi: async ({ image, width, height }) => {
494
+ // `image` is a JPEG data URL, at most 1600px. Send it to YOUR server, which calls a vision model with
495
+ // IMAGE_TO_DESIGN_PROMPT (replace {width}/{height}) as the system prompt, and return the parsed JSON.
496
+ const res = await fetch('/my-api/rebuild', { method: 'POST', body: JSON.stringify({ image, width, height }) });
497
+ return (await res.json()).spec;
498
+ },
499
+ }}
500
+ />
501
+ ```
502
+
503
+ The SDK validates the answer (colours, sizes and counts are checked; anything unusable is dropped), so the model's output is never trusted. For full control pass `onConvertImage(input) => Promise<PageDefinition[]>` instead.
504
+ - **Without AI** a picture is placed on the canvas as one image the person can crop, resize and put text over. Turn the AI off with `aiConversion: false`.
505
+
506
+ ### 5. Use the engine without the editor
507
+
508
+ ```ts
509
+ import { exportSource, downloadResult, openFile, convertContent } from '@charisol/plexo-sdk/v2/files';
510
+
511
+ // Export a landing page, or just one element of it
512
+ const png = await exportSource({ kind: 'design', page, nodeIds: [heroId] }, { format: 'png', scale: 2 });
513
+ downloadResult(png); // { blob, filename, mime, warnings }
514
+
515
+ // Every page of a multi-page design as one PDF
516
+ await exportSource({ kind: 'design', page: pages[0], pages }, { format: 'pdf' });
517
+
518
+ // Documents, text, Markdown and spreadsheets
519
+ await exportSource({ kind: 'html', name: 'Notes', body: '<h1>Hi</h1>' }, { format: 'docx' });
520
+ // A whole web page, drawn exactly as the browser shows it
521
+ await exportSource({ kind: 'rawhtml', name: 'Landing', html: pastedHtml, width: 1200 }, { format: 'png' });
522
+ await exportSource({ kind: 'sheet', name: 'Budget', grid: [['a', 'b'], ['1', '=A2*2']] }, { format: 'xlsx' });
523
+
524
+ // Open any supported file
525
+ const opened = await openFile(file); // → source | image | pdf
526
+ ```
527
+
528
+ `ExportOptions`: `format`, `scale` (1–4), `background` (`null` = see-through), `quality`, `svgMode` (`'vector' \| 'exact'`), `pdfPaging` (`'single' \| 'a4'`), `filename`. Everything here runs **in the browser** (pages are drawn with the browser's own engine) and returns a plain `Blob`.
529
+
530
+ ### 6. A complete host integration, end to end
531
+
532
+ [`examples/host-integration`](examples/host-integration) is a small, runnable host app ("Acme Studio") with its own backend. It is tested end to end in a real browser: the host's own chooser, create, edit, Save to the host's storage, list, download, reopen from the saved source, re-save without duplicating, and picture upload / AI. Run it:
533
+
534
+ ```bash
535
+ npm install && npm run build # once
536
+ ANTHROPIC_API_KEY=sk-ant-… npm run example # key is optional: without it the picture rebuild shows a plain "not set up" message
537
+ # web app on http://localhost:5181, backend on :5180
538
+ ```
539
+
540
+ What the host builds is four small pieces. Everything else (the editors, preview, export, formats, theming) is the SDK's.
541
+
542
+ **1. Its own screens, then hand over to the editor**
543
+
544
+ ```tsx
545
+ // "My files" + a chooser are YOUR screens. When someone picks, mount the editor with the answer:
546
+ <V2Editor
547
+ mode="file"
548
+ theme={{ accent: '#7c3aed', background: '#ffffff', text: '#1f2937' }} // your brand: three colours
549
+ onUpload={uploadPicture} // 2. your storage for pictures the editor makes
550
+ files={{
551
+ kind: 'html', // new file of this type… or file: savedSource / aFile to open one
552
+ startScreen: false, // you have your own chooser
553
+ showTypeSwitcher: false, // the type was chosen on your screen
554
+ imageAi: describePicture, // 3. your AI
555
+ onSaveFile: (r) => save(r, existingId), // 4. your save
556
+ defaultSaveFormat: 'png', // optional: keep saving in the format this file was saved in
557
+ onClose: () => showMyFiles(), // Back button
558
+ }}
559
+ />
560
+ ```
561
+
562
+ **2. Storage for pictures the editor makes** (cut-out photos, PDF pages). Return where you stored each:
563
+
564
+ ```ts
565
+ const uploadPicture = async (file: File) => {
566
+ const body = new FormData(); body.append('file', file);
567
+ const res = await fetch('/api/upload', { method: 'POST', body });
568
+ if (!res.ok) throw new Error('The picture could not be uploaded.'); // shown to the person
569
+ return (await res.json()).url;
570
+ };
571
+ // Without onUpload, small pictures are embedded in the design instead (fine for trying it out).
572
+ ```
573
+
574
+ **3. AI for pictures** (optional). The editor sends a picture; your server asks a vision model with the prompt the SDK ships and returns its JSON:
575
+
576
+ ```ts
577
+ // client
578
+ const describePicture = async ({ image, width, height, signal }) => {
579
+ const res = await fetch('/api/rebuild-picture', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ image, width, height }), signal });
580
+ const out = await res.json();
581
+ if (!res.ok) throw new Error(out.error); // plain words: the person sees this, and their picture is placed on the canvas instead
582
+ return out.spec;
583
+ };
584
+
585
+ // server (Node; any language works: it only needs to call a vision model)
586
+ import { IMAGE_TO_DESIGN_PROMPT } from '@charisol/plexo-sdk/v2/files';
587
+ const r = await fetch('https://api.anthropic.com/v1/messages', {
588
+ method: 'POST',
589
+ headers: { 'content-type': 'application/json', 'x-api-key': process.env.ANTHROPIC_API_KEY, 'anthropic-version': '2023-06-01' },
590
+ body: JSON.stringify({
591
+ model: 'claude-sonnet-5-5', max_tokens: 8000,
592
+ system: IMAGE_TO_DESIGN_PROMPT.replaceAll('{width}', String(width)).replaceAll('{height}', String(height)),
593
+ messages: [{ role: 'user', content: [{ type: 'image', source: { type: 'base64', media_type: 'image/jpeg', data } }, { type: 'text', text: 'Describe this picture as the JSON object.' }] }],
594
+ }),
595
+ });
596
+ // …parse the text of the reply as JSON and return it as { spec }. The SDK validates it; you don't have to.
597
+ ```
598
+
599
+ **4. Save** — `result.blob` is the finished file in the format they chose; `result.source` is the editable version. Store both:
600
+
601
+ ```ts
602
+ async function save(result: FileSaveResult, existingId?: string) {
603
+ const body = new FormData();
604
+ body.append('file', result.blob, result.filename); // upload this (S3, disk, …)
605
+ body.append('source', JSON.stringify(result.source)); // keep this in your database
606
+ body.append('meta', JSON.stringify({ id: existingId, name: result.name, kind: result.kind, format: result.format }));
607
+ const res = await fetch('/api/files', { method: 'POST', body });
608
+ if (!res.ok) throw new Error('Saving failed. Please try again.'); // shown to the person; they can retry
609
+ }
610
+
611
+ // Reopen later: fetch the stored source and pass it back
612
+ <V2Editor mode="file" files={{ file: storedSource, defaultSaveFormat: row.format, showTypeSwitcher: false, onSaveFile: … }} />
613
+ ```
614
+
615
+ A few things worth knowing when you build the real thing:
616
+ - **Errors are for people.** Whatever `uploadPicture`, `imageAi` or `onSaveFile` throws is shown as its message, so write them as plain sentences. A failed AI call never blocks anything: the picture is placed on the canvas and they carry on.
617
+ - **Large files:** `result.blob` can be several MB (a 2x PNG of a long page, a many-page PDF). Send it as multipart (as above) or upload straight to storage with a presigned URL; don't base64 it into JSON.
618
+ - **Pictures hosted elsewhere** must allow cross-origin reading (CORS) to be included in PNG/PDF exports; the person gets a warning when one can't be. Pictures you store with `onUpload` are fine if served from your own origin.
619
+ - **Reopening is lossless** because `source` is the editor's own data (page JSON, HTML, text, or cells), not the exported file. Don't reopen a saved PNG/PDF to edit it: store `source` next to it.
620
+ - **Security:** treat what you load as untrusted if people can share files: HTML files run in a sandbox with scripts off, and the AI answer is validated by the SDK before it is used.
621
+
322
622
  ## Framework Notes
323
623
 
324
624
  ### Vite
@@ -363,6 +663,7 @@ const PlexoBuilder = lazy(() =>
363
663
  - Every row/column/element wrapper now carries a `data-plexo-node-type="row"|"column"|"element"` attribute alongside its existing `id` (already the node's stable JSON id).
364
664
 
365
665
  ### Unreleased
666
+ - **File editor & export (v2):** `mode="file"` / `"hybrid"`; Figma-style PNG / JPG / PDF / SVG export from the canvas; HTML files with a code editor and live preview; PDF editing; AI picture-to-design; host-driven screens (`files.kind`, `files.file`, `startScreen`, `showTypeSwitcher`, a ref); new entry `@charisol/plexo-sdk/v2/files`; new compile option `nodeIds`; new `features.exportMenu`. New dependencies: `pdfjs-dist` and CodeMirror (both loaded only when used).
366
667
  - **Breaking:** Removed the `aiApiKey` prop. AI generation now runs server-side — your provider key is configured once against your Plexo account (encrypted at rest) instead of being passed to the browser on every render.
367
668
  - **Breaking:** `TemplateJSON.body.aiConfig` no longer accepts `apiKey`/`provider` — only `useAi`/`tier` remain, for the same reason (a template's JSON is loaded client-side, so it can't hold a secret safely).
368
669
  - `aiProvider` is now display/label-only; the effective provider comes from your account configuration, not this prop.