@particle-academy/fancy-slides 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties } from 'react';
-import { i as Slide$1, p as Theme, k as SlideElement, D as Deck, d as DeckOp, h as ShapeKind, m as SlideTransition, j as SlideBackground, l as SlideLayout, E as ElementAnimation, n as TextElement, I as ImageElement, g as ShapeElement } from './types-2yYMJPhi.cjs';
-export { A as AnimationEffect, a as AnimationTrigger, C as ChartElement, b as CodeElement, c as DeckActivity, e as ElementBase, f as EmbedElement, S as SCHEMA_VERSION, T as TableElement, o as TextStyle, q as ThemeColors, r as ThemeFonts, s as TransitionKind } from './types-2yYMJPhi.cjs';
+import { i as Slide$1, p as Theme, k as SlideElement, D as Deck, d as DeckOp, h as ShapeKind, m as SlideTransition, j as SlideBackground, l as SlideLayout, E as ElementAnimation, n as TextElement, I as ImageElement, g as ShapeElement } from './types-C3w37g3A.cjs';
+export { A as AnimationEffect, a as AnimationTrigger, C as ChartElement, b as CodeElement, c as DeckActivity, e as ElementBase, f as EmbedElement, S as SCHEMA_VERSION, T as TableElement, o as TextStyle, q as ThemeColors, r as ThemeFonts, s as TransitionKind } from './types-C3w37g3A.cjs';
 import { EditorAction } from '@particle-academy/react-fancy';
 
 interface SlideProps {
@@ -594,6 +594,8 @@ interface DeckStateApi {
     /** Deck-level helpers. */
     setTitle: (title: string) => void;
     applyTheme: (theme: Theme) => void;
+    /** Replace the entire deck — stream a full presentation in atomically. */
+    setDeck: (deck: Deck) => void;
     /** Slide-level helpers. */
     addSlide: (index?: number, partial?: Partial<Slide$1>) => string;
     duplicateSlide: (id: string) => string;
@@ -673,4 +675,43 @@ type ChartKind = "bar" | "line" | "pie" | "area" | "scatter";
 type Option = Record<string, unknown>;
 declare function chartStarterOption(kind: ChartKind): Option;
 
-export { type Build, type BuildStep, type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, EditorToolbar, type EditorToolbarProps, ElementAnimation, ElementInspector, type ElementInspectorProps, ImageElement, ImageElementRenderer, type ImageElementRendererProps, PRESENTATION_EDITOR_ACTIONS, type ParaReveal, PresenterView, type PresenterViewProps, ShapeElement, ShapeElementRenderer, type ShapeElementRendererProps, ShapeKind, Slide, SlideBackground, type SlideContextValue, Slide$1 as SlideData, SlideElement, type SlideKeyboardOptions, SlideLayout, type SlideProps, SlideRail, type SlideRailProps, SlideThumbnail, type SlideThumbnailProps, SlideTransition, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, buildSteps, buildsForStep, builtinThemes, chartStarterOption, collectBuilds, darkTheme, deckId, defaultTheme, defineTheme, elementId, isByParagraph, nextId, normalizeSlideMarkdown, paragraphReveals, reduce as reduceDeck, resolveTheme, slideId, splitParagraphs, stepDelays, totalBuildSteps, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, visibleElementIds, vividTheme };
+/**
+ * Stream a full presentation in and out. The `Deck` is already plain JSON
+ * (no functions, no React children), so "serialize" is mostly `JSON.stringify`
+ * — these helpers add the schema-version stamp, a forgiving structural
+ * validation, and a forward-migration shim so a host can persist a deck, hand
+ * it to an agent, and load it back safely.
+ *
+ * Streaming OUT: read `value` / `onChange` from the controlled editor, or call
+ * `serializeDeck(deck)`.
+ * Streaming IN: `parseDeck(json)` → feed to `DeckEditor`'s `value`, or apply a
+ * `{ kind: "deck_set", deck }` op (also exposed as the bridge's `deck_set` tool).
+ */
+
+interface DeckValidation {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Structurally validate a deck. Forgiving by design — it checks the shape an
+ * editor / writer relies on (ids, slides array, element types + 0..1 geometry),
+ * not every optional field. Returns all problems found rather than throwing.
+ */
+declare function validateDeck(deck: unknown): DeckValidation;
+/**
+ * Migrate a deck authored against an older schema version forward to the
+ * current one. Today it only stamps the version (no breaking changes yet); the
+ * `switch` is where future migrations slot in, each bumping `version` by one.
+ */
+declare function migrateDeck(deck: Deck): Deck;
+/** Serialize a deck to a JSON string, stamping the current schema version. */
+declare function serializeDeck(deck: Deck, pretty?: boolean): string;
+/**
+ * Parse a deck from a JSON string (or an already-parsed object), migrating it
+ * forward and validating its structure. Throws a descriptive error when the
+ * JSON is malformed or the structure is invalid — callers streaming untrusted
+ * input should try/catch.
+ */
+declare function parseDeck(input: string | unknown): Deck;
+
+export { type Build, type BuildStep, type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, type DeckValidation, EditorToolbar, type EditorToolbarProps, ElementAnimation, ElementInspector, type ElementInspectorProps, ImageElement, ImageElementRenderer, type ImageElementRendererProps, PRESENTATION_EDITOR_ACTIONS, type ParaReveal, PresenterView, type PresenterViewProps, ShapeElement, ShapeElementRenderer, type ShapeElementRendererProps, ShapeKind, Slide, SlideBackground, type SlideContextValue, Slide$1 as SlideData, SlideElement, type SlideKeyboardOptions, SlideLayout, type SlideProps, SlideRail, type SlideRailProps, SlideThumbnail, type SlideThumbnailProps, SlideTransition, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, buildSteps, buildsForStep, builtinThemes, chartStarterOption, collectBuilds, darkTheme, deckId, defaultTheme, defineTheme, elementId, isByParagraph, migrateDeck, nextId, normalizeSlideMarkdown, paragraphReveals, parseDeck, reduce as reduceDeck, resolveTheme, serializeDeck, slideId, splitParagraphs, stepDelays, totalBuildSteps, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, validateDeck, visibleElementIds, vividTheme };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties } from 'react';
-import { i as Slide$1, p as Theme, k as SlideElement, D as Deck, d as DeckOp, h as ShapeKind, m as SlideTransition, j as SlideBackground, l as SlideLayout, E as ElementAnimation, n as TextElement, I as ImageElement, g as ShapeElement } from './types-2yYMJPhi.js';
-export { A as AnimationEffect, a as AnimationTrigger, C as ChartElement, b as CodeElement, c as DeckActivity, e as ElementBase, f as EmbedElement, S as SCHEMA_VERSION, T as TableElement, o as TextStyle, q as ThemeColors, r as ThemeFonts, s as TransitionKind } from './types-2yYMJPhi.js';
+import { i as Slide$1, p as Theme, k as SlideElement, D as Deck, d as DeckOp, h as ShapeKind, m as SlideTransition, j as SlideBackground, l as SlideLayout, E as ElementAnimation, n as TextElement, I as ImageElement, g as ShapeElement } from './types-C3w37g3A.js';
+export { A as AnimationEffect, a as AnimationTrigger, C as ChartElement, b as CodeElement, c as DeckActivity, e as ElementBase, f as EmbedElement, S as SCHEMA_VERSION, T as TableElement, o as TextStyle, q as ThemeColors, r as ThemeFonts, s as TransitionKind } from './types-C3w37g3A.js';
 import { EditorAction } from '@particle-academy/react-fancy';
 
 interface SlideProps {
@@ -594,6 +594,8 @@ interface DeckStateApi {
     /** Deck-level helpers. */
     setTitle: (title: string) => void;
     applyTheme: (theme: Theme) => void;
+    /** Replace the entire deck — stream a full presentation in atomically. */
+    setDeck: (deck: Deck) => void;
     /** Slide-level helpers. */
     addSlide: (index?: number, partial?: Partial<Slide$1>) => string;
     duplicateSlide: (id: string) => string;
@@ -673,4 +675,43 @@ type ChartKind = "bar" | "line" | "pie" | "area" | "scatter";
 type Option = Record<string, unknown>;
 declare function chartStarterOption(kind: ChartKind): Option;
 
-export { type Build, type BuildStep, type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, EditorToolbar, type EditorToolbarProps, ElementAnimation, ElementInspector, type ElementInspectorProps, ImageElement, ImageElementRenderer, type ImageElementRendererProps, PRESENTATION_EDITOR_ACTIONS, type ParaReveal, PresenterView, type PresenterViewProps, ShapeElement, ShapeElementRenderer, type ShapeElementRendererProps, ShapeKind, Slide, SlideBackground, type SlideContextValue, Slide$1 as SlideData, SlideElement, type SlideKeyboardOptions, SlideLayout, type SlideProps, SlideRail, type SlideRailProps, SlideThumbnail, type SlideThumbnailProps, SlideTransition, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, buildSteps, buildsForStep, builtinThemes, chartStarterOption, collectBuilds, darkTheme, deckId, defaultTheme, defineTheme, elementId, isByParagraph, nextId, normalizeSlideMarkdown, paragraphReveals, reduce as reduceDeck, resolveTheme, slideId, splitParagraphs, stepDelays, totalBuildSteps, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, visibleElementIds, vividTheme };
+/**
+ * Stream a full presentation in and out. The `Deck` is already plain JSON
+ * (no functions, no React children), so "serialize" is mostly `JSON.stringify`
+ * — these helpers add the schema-version stamp, a forgiving structural
+ * validation, and a forward-migration shim so a host can persist a deck, hand
+ * it to an agent, and load it back safely.
+ *
+ * Streaming OUT: read `value` / `onChange` from the controlled editor, or call
+ * `serializeDeck(deck)`.
+ * Streaming IN: `parseDeck(json)` → feed to `DeckEditor`'s `value`, or apply a
+ * `{ kind: "deck_set", deck }` op (also exposed as the bridge's `deck_set` tool).
+ */
+
+interface DeckValidation {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Structurally validate a deck. Forgiving by design — it checks the shape an
+ * editor / writer relies on (ids, slides array, element types + 0..1 geometry),
+ * not every optional field. Returns all problems found rather than throwing.
+ */
+declare function validateDeck(deck: unknown): DeckValidation;
+/**
+ * Migrate a deck authored against an older schema version forward to the
+ * current one. Today it only stamps the version (no breaking changes yet); the
+ * `switch` is where future migrations slot in, each bumping `version` by one.
+ */
+declare function migrateDeck(deck: Deck): Deck;
+/** Serialize a deck to a JSON string, stamping the current schema version. */
+declare function serializeDeck(deck: Deck, pretty?: boolean): string;
+/**
+ * Parse a deck from a JSON string (or an already-parsed object), migrating it
+ * forward and validating its structure. Throws a descriptive error when the
+ * JSON is malformed or the structure is invalid — callers streaming untrusted
+ * input should try/catch.
+ */
+declare function parseDeck(input: string | unknown): Deck;
+
+export { type Build, type BuildStep, type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, type DeckValidation, EditorToolbar, type EditorToolbarProps, ElementAnimation, ElementInspector, type ElementInspectorProps, ImageElement, ImageElementRenderer, type ImageElementRendererProps, PRESENTATION_EDITOR_ACTIONS, type ParaReveal, PresenterView, type PresenterViewProps, ShapeElement, ShapeElementRenderer, type ShapeElementRendererProps, ShapeKind, Slide, SlideBackground, type SlideContextValue, Slide$1 as SlideData, SlideElement, type SlideKeyboardOptions, SlideLayout, type SlideProps, SlideRail, type SlideRailProps, SlideThumbnail, type SlideThumbnailProps, SlideTransition, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, buildSteps, buildsForStep, builtinThemes, chartStarterOption, collectBuilds, darkTheme, deckId, defaultTheme, defineTheme, elementId, isByParagraph, migrateDeck, nextId, normalizeSlideMarkdown, paragraphReveals, parseDeck, reduce as reduceDeck, resolveTheme, serializeDeck, slideId, splitParagraphs, stepDelays, totalBuildSteps, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, validateDeck, visibleElementIds, vividTheme };

package/dist/index.js

@@ -1542,6 +1542,7 @@ function useDeckState({ value, onChange, onOp }) {
       apply,
       setTitle: (title) => apply({ kind: "deck_set_title", title }),
       applyTheme: (theme) => apply({ kind: "deck_apply_theme", theme }),
+      setDeck: (deck) => apply({ kind: "deck_set", deck }),
       addSlide: (index, partial) => {
         const id = partial?.id ?? slideId();
         const slide = {
@@ -1596,6 +1597,8 @@ function reduce(deck, op) {
       return { ...deck, title: op.title };
     case "deck_apply_theme":
       return { ...deck, theme: op.theme };
+    case "deck_set":
+      return op.deck;
     case "slide_add": {
       const slides = [...deck.slides];
       slides.splice(Math.max(0, Math.min(slides.length, op.index)), 0, op.slide);
@@ -3106,6 +3109,74 @@ function DeckEditor({
 // src/types.ts
 var SCHEMA_VERSION = 1;
 
-export { DeckEditor, EditorToolbar, ElementInspector, ImageElementRenderer, PRESENTATION_EDITOR_ACTIONS, PresenterView, SCHEMA_VERSION, ShapeElementRenderer, Slide, SlideRail, SlideThumbnail, SlideViewer, SpeakerNotes, TextElementRenderer, buildSteps, buildsForStep, builtinThemes, chartStarterOption, collectBuilds, darkTheme, deckId, defaultTheme, defineTheme, elementId, isByParagraph, nextId, normalizeSlideMarkdown, paragraphReveals, reduce as reduceDeck, resolveTheme, slideId, splitParagraphs, stepDelays, totalBuildSteps, useDeckState, useSlideKeyboard, visibleElementIds, vividTheme };
+// src/utils/serialize.ts
+var ELEMENT_TYPES = ["text", "image", "chart", "code", "table", "shape", "embed"];
+function validateDeck(deck) {
+  const errors = [];
+  const d = deck;
+  if (!d || typeof d !== "object") {
+    return { ok: false, errors: ["deck is not an object"] };
+  }
+  if (typeof d.id !== "string" || !d.id) errors.push("deck.id must be a non-empty string");
+  if (typeof d.title !== "string") errors.push("deck.title must be a string");
+  if (!d.theme || typeof d.theme !== "object") errors.push("deck.theme must be an object");
+  if (!Array.isArray(d.slides)) {
+    errors.push("deck.slides must be an array");
+    return { ok: errors.length === 0, errors };
+  }
+  d.slides.forEach((slide, si) => {
+    if (!slide || typeof slide !== "object") {
+      errors.push(`slides[${si}] is not an object`);
+      return;
+    }
+    if (typeof slide.id !== "string" || !slide.id) errors.push(`slides[${si}].id must be a non-empty string`);
+    if (!Array.isArray(slide.elements)) {
+      errors.push(`slides[${si}].elements must be an array`);
+      return;
+    }
+    slide.elements.forEach((el, ei) => {
+      const where = `slides[${si}].elements[${ei}]`;
+      if (!el || typeof el !== "object") {
+        errors.push(`${where} is not an object`);
+        return;
+      }
+      if (typeof el.id !== "string" || !el.id) errors.push(`${where}.id must be a non-empty string`);
+      if (!ELEMENT_TYPES.includes(el.type)) errors.push(`${where}.type "${el.type}" is not a known element type`);
+      for (const k of ["x", "y", "w", "h"]) {
+        const v = el[k];
+        if (typeof v !== "number" || v < 0 || v > 1) errors.push(`${where}.${k} must be a number in 0..1`);
+      }
+    });
+  });
+  return { ok: errors.length === 0, errors };
+}
+function migrateDeck(deck) {
+  let d = deck;
+  d.version ?? 1;
+  return d.version === SCHEMA_VERSION ? d : { ...d, version: SCHEMA_VERSION };
+}
+function serializeDeck(deck, pretty = false) {
+  const stamped = deck.version === SCHEMA_VERSION ? deck : { ...deck, version: SCHEMA_VERSION };
+  return JSON.stringify(stamped, null, pretty ? 2 : void 0);
+}
+function parseDeck(input) {
+  let raw;
+  if (typeof input === "string") {
+    try {
+      raw = JSON.parse(input);
+    } catch (e) {
+      throw new Error(`parseDeck: invalid JSON \u2014 ${e.message}`);
+    }
+  } else {
+    raw = input;
+  }
+  const result = validateDeck(raw);
+  if (!result.ok) {
+    throw new Error(`parseDeck: invalid deck \u2014 ${result.errors.join("; ")}`);
+  }
+  return migrateDeck(raw);
+}
+
+export { DeckEditor, EditorToolbar, ElementInspector, ImageElementRenderer, PRESENTATION_EDITOR_ACTIONS, PresenterView, SCHEMA_VERSION, ShapeElementRenderer, Slide, SlideRail, SlideThumbnail, SlideViewer, SpeakerNotes, TextElementRenderer, buildSteps, buildsForStep, builtinThemes, chartStarterOption, collectBuilds, darkTheme, deckId, defaultTheme, defineTheme, elementId, isByParagraph, migrateDeck, nextId, normalizeSlideMarkdown, paragraphReveals, parseDeck, reduce as reduceDeck, resolveTheme, serializeDeck, slideId, splitParagraphs, stepDelays, totalBuildSteps, useDeckState, useSlideKeyboard, validateDeck, visibleElementIds, vividTheme };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map