@lofcz/pptist 2.0.13 → 2.0.15

package/dist/embed/agentic-manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 2,
   "package": "@lofcz/pptist",
-  "packageVersion": "2.0.13",
-  "generatedAt": "2026-06-02T07:12:26.717Z",
-  "summary": "Authoring guidance for the PPTist agentic bridge. The fast, reliable way to build a deck: (1) pick ONE built-in presentation template (the same styles as the template picker — template_1 … template_8) with deck.applyTemplate, (2) read templates.slidesCatalog for that template's slide slugs grouped by type (cover, contents, transition, content, end), then (3) insert slides with slides.insertFromTemplate and edit text via text.setMarkdown. Do NOT build decks from blank slides.create or hand-placed elements unless no template slide fits. Content is Markdown or plain text — never hand-written HTML. Pair this with the machine schema (command payload/return types) in the same manifest.",
-  "commandCount": 173,
+  "packageVersion": "2.0.15",
+  "generatedAt": "2026-06-17T04:24:25.505Z",
+  "summary": "Authoring guidance for the PPTist agentic bridge. The recommended way to build a deck from scratch: (1) pick ONE visual identity with styles.catalog -> deck.applyStyle (academic | minimal | bold | playful), then (2) for each slide pick a recipe from layouts.catalog and add it with slides.createFromLayout({ layoutId, slots }) — the engine themes, positions AND auto-fits every text box (via responsive measurement) so content never overflows. Author slot content as Markdown/plain text or structured values (arrays for bullets, { labels, series } for charts) — never hand-written HTML. Alternative: for pixel-perfect branded decks, use the built-in templates flow (deck.applyTemplate + slides.insertFromTemplate). Avoid blank slides.create / hand-placed elements unless neither a layout nor a template slide fits. Pair this with the machine schema (command payload/return types) in the same manifest.",
+  "commandCount": 177,
   "designSystem": {
-    "summary": "PPTist lays elements out in a fixed pixel coordinate space, not inches. Prefer built-in templates (deck.applyTemplate + slides.insertFromTemplate) so colors, contrast, fonts and layout come from the official template library instead of being hand-picked. These tokens describe the *fallback* defaults for manual placement only.",
+    "summary": "PPTist lays elements out in a fixed pixel coordinate space, not inches. Prefer the styles + layouts flow (deck.applyStyle + slides.createFromLayout) or, for branded decks, built-in templates (deck.applyTemplate + slides.insertFromTemplate) so colors, contrast, fonts and layout are chosen for you instead of hand-picked. These tokens describe the *fallback* defaults for manual placement only.",
     "coordinateSystem": {
       "summary": "The default 16:9 canvas is 1000 x 562.5 px (viewport.size = 1000, viewport.ratio = 0.5625). Origin (0,0) is the top-left corner. Every element has left, top, width, height in px and rotate in degrees.",
       "notes": [
@@ -48,7 +48,7 @@
   "domains": [
     {
       "id": "deck",
-      "commandCount": 8,
+      "commandCount": 9,
       "title": "Deck",
       "summary": "Whole-document state: title, theme, viewport, templates, plus full get/set/patch.",
       "whenToUse": "Apply a template theme with deck.applyTemplate up front; set the viewport once; use whole-document import/export at persistence boundaries."
@@ -72,11 +72,25 @@
       "commandCount": 2,
       "title": "Templates",
       "summary": "Built-in presentation templates (template_1 … template_8 — same as the UI template picker). templates.catalog lists them; templates.slidesCatalog lists insertable slide slugs by type; deck.applyTemplate sets the deck theme.",
-      "whenToUse": "FIRST. Pick exactly one template style for the whole deck, apply its theme, then insert slides by slug. Never invent custom slide layouts when a template slide fits."
+      "whenToUse": "ALTERNATIVE to styles + layouts, for pixel-perfect branded decks. Pick exactly one template style for the whole deck, apply its theme, then insert slides by slug. Never invent custom slide layouts when a template slide fits."
+    },
+    {
+      "id": "styles",
+      "commandCount": 1,
+      "title": "Styles",
+      "summary": "Curated visual-identity presets (academic, minimal, bold, playful) — each a contrast-safe color palette with named roles + a heading/body font pairing + a type scale. styles.catalog lists them; deck.applyStyle picks ONE and records theme.styleId.",
+      "whenToUse": "FIRST, when building a deck from scratch. Pick one style for the whole deck so every layout inherits a coherent, legible look. Use this OR the templates flow — not both."
+    },
+    {
+      "id": "layouts",
+      "commandCount": 1,
+      "title": "Layouts",
+      "summary": "Compositional slide recipes (title, section, closing, bullets, twoColumn, imageText, bigStat, quote, chart, comparison). layouts.catalog lists each layout's content slots and what they expect; slides.createFromLayout builds a themed, positioned slide from a layout id + slots.",
+      "whenToUse": "After deck.applyStyle, once per slide. Pick the layout whose composition matches the slide's job and fill its slots with content. The engine themes, positions and auto-fits text to each box, so focus on clear, concise content rather than exact character counts."
     },
     {
       "id": "slides",
-      "commandCount": 18,
+      "commandCount": 19,
       "title": "Slides",
       "summary": "Insert slides from built-in templates (slides.insertFromTemplate); read, update, delete, duplicate, move, select; set background, transition and speaker remark.",
       "whenToUse": "Prefer slides.insertFromTemplate (one call per slide). After insert, use text.setMarkdown on the returned placeholderElementIds/textElementIds. Avoid slides.create for deck building."
@@ -365,6 +379,71 @@
         ]
       }
     },
+    {
+      "name": "styles.catalog",
+      "domain": "styles",
+      "payload": "undefined",
+      "returns": "PptistStyleSummary[]",
+      "doc": {
+        "summary": "List the visual-identity style presets (academic, minimal, bold, playful) with their fonts and a color preview.",
+        "details": "Read this first when building a deck from scratch. Each preset is a contrast-safe palette + heading/body font pairing + type scale. Pick exactly one whose tone fits the audience, then apply it with deck.applyStyle before adding any slides.",
+        "examples": [
+          "const styles = controller.styles.catalog() // -> [{ id:'academic', label:'Academic', fonts:{...}, preview:{ background, title, body, accent, featureBackground } }, ...]"
+        ],
+        "related": [
+          "deck.applyStyle",
+          "layouts.catalog",
+          "slides.createFromLayout"
+        ]
+      }
+    },
+    {
+      "name": "layouts.catalog",
+      "domain": "layouts",
+      "payload": "undefined",
+      "returns": "PptistLayout[]",
+      "doc": {
+        "summary": "List the compositional slide layouts and, for each, the content slots you fill (slot name, type, and whether it is required).",
+        "details": "Call before each slide. Pick the layout id whose composition matches the slide's purpose (e.g. 'title' for the cover, 'bullets' for a list, 'twoColumn' for compare/contrast, 'bigStat' for a headline metric, 'chart' for data, 'comparison' for a table, 'closing' for the sign-off). Then pass the matching slots to slides.createFromLayout.",
+        "examples": [
+          "const layouts = controller.layouts.catalog() // -> [{ id:'bullets', label:'Bulleted list', slots:[{ name:'title', type:'text', required:true }, { name:'bullets', type:'bullets', required:true }], ... }, ...]"
+        ],
+        "related": [
+          "slides.createFromLayout",
+          "styles.catalog"
+        ]
+      }
+    },
+    {
+      "name": "deck.applyStyle",
+      "domain": "deck",
+      "payload": "{ styleId: string }",
+      "returns": "PptistApplyStyleResult",
+      "optional": true,
+      "doc": {
+        "summary": "Apply ONE style preset as the deck's visual identity (palette, fonts, type scale). Records theme.styleId so every layout inherits it.",
+        "details": "Do this once, up front, before creating slides with slides.createFromLayout. An unknown id falls back to the default style and returns a recoverable warning — read valid ids from styles.catalog.",
+        "params": [
+          {
+            "name": "styleId",
+            "type": "string",
+            "required": true,
+            "description": "A preset id from styles.catalog ('academic' | 'minimal' | 'bold' | 'playful')."
+          }
+        ],
+        "examples": [
+          "await controller.deck.applyStyle('academic')"
+        ],
+        "tips": [
+          "Keep one style for the whole deck. Do not hand-pick colors or fonts on top of it — layouts read the preset's role tokens for you."
+        ],
+        "related": [
+          "styles.catalog",
+          "layouts.catalog",
+          "slides.createFromLayout"
+        ]
+      }
+    },
     {
       "name": "deck.setViewport",
       "domain": "deck",
@@ -458,6 +537,64 @@
         ]
       }
     },
+    {
+      "name": "slides.createFromLayout",
+      "domain": "slides",
+      "payload": "{ layoutId: string; slots?: Record<string, unknown>; index?: number; select?: boolean; backgroundMode?: PptistLayoutBackgroundMode }",
+      "returns": "PptistCreateFromLayoutResult",
+      "optional": true,
+      "doc": {
+        "summary": "Build + insert a themed slide from a layout id and content slots. The PREFERRED way to add a slide when building from scratch.",
+        "details": "The engine positions every element on the canvas, colors it from the active style preset (theme.styleId), and AUTO-FITS each text box's font size (responsive measurement) so text never overflows — you never pick coordinates, sizes, or colors. Author slot content as Markdown/plain text (titles, bullets, body) or structured values (arrays of strings for bullets; { labels, series, legends } for charts; rows for comparison). Returns the new slideId plus the created element ids.",
+        "params": [
+          {
+            "name": "layoutId",
+            "type": "string",
+            "required": true,
+            "description": "Layout id from layouts.catalog (e.g. 'title', 'bullets', 'twoColumn', 'chart')."
+          },
+          {
+            "name": "slots",
+            "type": "Record<string, unknown>",
+            "required": false,
+            "description": "Content slots for the layout (keys + shapes per layouts.catalog)."
+          },
+          {
+            "name": "index",
+            "type": "number",
+            "required": false,
+            "description": "Insert position; appends when omitted."
+          },
+          {
+            "name": "select",
+            "type": "boolean",
+            "required": false,
+            "description": "Select the new slide after insert (default true)."
+          },
+          {
+            "name": "backgroundMode",
+            "type": "'auto' | 'feature' | 'plain'",
+            "required": false,
+            "description": "Force a feature (dark) or plain background; defaults to the layout's own preference."
+          }
+        ],
+        "examples": [
+          "await controller.slides.createFromLayout({ layoutId:'title', slots:{ title:'Quarterly Review', subtitle:'Results and outlook', eyebrow:'2026 Q1' } })",
+          "await controller.slides.createFromLayout({ layoutId:'bullets', slots:{ title:'Key points', bullets:['First point','Second point','Third point'] } })",
+          "await controller.slides.createFromLayout({ layoutId:'chart', slots:{ title:'Revenue by region', chartType:'column', labels:['North','South','East'], series:[[12,28,41]] } })"
+        ],
+        "tips": [
+          "Apply a style once with deck.applyStyle before the first createFromLayout call.",
+          "Keep slot copy concise so the auto-fit keeps text at a comfortable size; after each slide, read the auto-screenshot to confirm the result.",
+          "Use 'title' for the first slide and 'closing' for the last; 'section' to divide a long deck."
+        ],
+        "related": [
+          "layouts.catalog",
+          "deck.applyStyle",
+          "text.setMarkdown"
+        ]
+      }
+    },
     {
       "name": "slides.insertFromTemplate",
       "domain": "slides",
@@ -1626,12 +1763,27 @@
     }
   ],
   "guides": [
+    {
+      "id": "styles-layouts-flow",
+      "title": "How to build a deck (styles + layouts)",
+      "summary": "The recommended flow for a fresh deck: pick one style, then build each slide from a layout by filling its content slots.",
+      "body": [
+        "1. Read styles.catalog and pick exactly ONE visual identity (academic, minimal, bold, playful) that fits the audience and topic.",
+        "2. Apply it once: deck.applyStyle({ styleId:'academic' }). This sets the deck theme and records theme.styleId; every layout then inherits its palette, fonts and type scale. Do not hand-pick colors or fonts after this.",
+        "3. Plan the slide flow (e.g. title -> section / bullets / chart / ... -> closing). Keep one todo per slide.",
+        "4. Read layouts.catalog and, for each slide, pick the layout id whose composition matches the slide's job. Note each slot's name, type and whether it is required.",
+        "5. Add the slide with slides.createFromLayout({ layoutId, slots }). Fill slots with Markdown/plain text (titles, bullets, body) or structured values (arrays for bullets; { labels, series } for charts; rows for comparison). The engine themes, positions and auto-fits text to every box — you never set coordinates, colors, or font sizes.",
+        "6. After each slide, look at the auto-screenshot to confirm the result. Text auto-fits its frame so it won't overflow; if the auto-fit made a box shrink uncomfortably small, that slide is overloaded — split it or trim the copy and rebuild.",
+        "7. Use 'title' for the cover and 'closing' for the sign-off; 'section' to divide a long deck.",
+        "8. Only drop to the templates flow (deck.applyTemplate + slides.insertFromTemplate) for pixel-perfect branded decks, or manual slides.create when neither a layout nor a template slide fits."
+      ]
+    },
     {
       "id": "templates-flow",
-      "title": "How to build a deck (built-in templates)",
-      "summary": "The recommended flow: pick one template style, apply its theme, insert slides by slug, then edit text.",
+      "title": "How to build a deck (alternative: built-in templates)",
+      "summary": "The branded-deck alternative to styles + layouts: pick one template style, apply its theme, insert slides by slug, then edit text.",
       "body": [
-        "1. Read templates.catalog and pick exactly ONE template (template_1 … template_8) whose tone fits the audience (e.g. template_1 Crimson landscape for bold keynotes, template_5 Minimal green for crisp lessons).",
+        "1. Read templates.catalog and pick exactly ONE template (template_1 … template_8) whose tone fits the audience (e.g. template_1 Crimson landscape for bold keynotes, template_5 Minimal green for crisp, understated decks).",
         "2. Apply it once: deck.applyTemplate({ templateId:'template_1' }). This sets the deck theme. Do not hand-pick colors or fonts after this.",
         "3. Read templates.slidesCatalog({ templateId }) — slides are grouped by type: cover, contents, transition, content, end. Each entry has a slug and description.",
         "4. For each slide in your outline, call slides.insertFromTemplate({ templateId, slug }) with the slug that best matches (e.g. cover_1 for title, contents_1 for agenda, content_2 for a text+image slide).",
@@ -1793,6 +1945,7 @@
     "PptistAnimationPreset": "export interface PptistAnimationPreset { name: string; value: string }",
     "PptistAnimationPresetGroup": "export interface PptistAnimationPresetGroup { type: string; name: string; children: PptistAnimationPreset[] }",
     "PptistAnimationSequenceStep": "export interface PptistAnimationSequenceStep { index: number; animations: PPTAnimation[]; autoNext: boolean }",
+    "PptistApplyStyleResult": "export interface PptistApplyStyleResult { styleId: string; theme: SlideTheme }",
     "PptistApplyTemplateResult": "export interface PptistApplyTemplateResult { templateId: string; theme: SlideTheme }",
     "PptistAudioElementPatch": "export type PptistAudioElementPatch = Partial<Pick<PPTAudioElement, 'src' | 'ext' | 'autoplay' | 'loop' | 'color' | 'fixedRatio' | 'link' | 'name' | 'lock' | 'groupId'>> & { transform?: PptistAudioTransformPatch }",
     "PptistAudioSourceInput": "export type PptistAudioSourceInput = PptistMediaAssetInput",
@@ -1801,6 +1954,7 @@
     "PptistChartElementPatch": "export interface PptistChartElementPatch { chartType?: ChartType; data?: ChartData; options?: ChartOptions; fill?: PPTChartElement['fill']; outline?: Partial<NonNullable<PPTChartElement['outline']>>; themeColors?: string[]; textColor?: string; lineColor?: string }",
     "PptistCreateAudioInput": "export interface PptistCreateAudioInput extends PptistAudioElementPatch { id?: string; source?: PptistAudioSourceInput; slideId?: string; index?: number; select?: boolean }",
     "PptistCreateChartInput": "export type PptistCreateChartInput = PptistChartElementPatch & Partial<Pick<PPTChartElement, 'id' | 'left' | 'top' | 'width' | 'height' | 'rotate'>> & { slideId?: string; index?: number; select?: boolean }",
+    "PptistCreateFromLayoutResult": "export interface PptistCreateFromLayoutResult { slideId: string; layoutId: string; elementIds: string[]; textElementIds: string[] }",
     "PptistCreateLatexElementInput": "export interface PptistCreateLatexElementInput { slideId?: string; index?: number; element: PptistLatexElementInput; select?: boolean }",
     "PptistCreateLineElementInput": "export interface PptistCreateLineElementInput { slideId?: string; index?: number; element: PptistLineElementInput; select?: boolean }",
     "PptistCreateTableInput": "export type PptistCreateTableInput = PptistTableElementPatch & { id?: string; slideId?: string; index?: number; select?: boolean; element?: Partial<PPTTableElement> }",
@@ -1826,9 +1980,12 @@
     "PptistInsertSlidesResult": "export interface PptistInsertSlidesResult { slides: Slide[]; remap: PptistIdRemap }",
     "PptistJsonPrimitive": "export type PptistJsonPrimitive = string | number | boolean | null",
     "PptistJsonValue": "export type PptistJsonValue = PptistJsonPrimitive | PptistJsonValue[] | { [key: string]: PptistJsonValue }",
-    "PptistLatexElementInput": "export type PptistLatexElementInput = PptistLatexElementSizing & Pick<PPTLatexElement, 'latex' | 'path'> & Partial<Pick<PPTLatexElement, 'id' | 'color' | 'strokeWidth' | 'viewBox' | 'fixedRatio' | 'link' | 'name' | 'lock' | 'groupId'>>",
+    "PptistLatexElementInput": "export type PptistLatexElementInput = PptistLatexElementSizing & Pick<PPTLatexElement, 'latex'> & Partial<Pick<PPTLatexElement, 'path' | 'id' | 'color' | 'strokeWidth' | 'viewBox' | 'fixedRatio' | 'link' | 'name' | 'lock' | 'groupId'>>",
     "PptistLatexElementPatch": "export type PptistLatexElementPatch = Partial<PptistLatexElementSizing & Pick<PPTLatexElement, 'latex' | 'path' | 'color' | 'strokeWidth' | 'viewBox' | 'fixedRatio' | 'link' | 'name' | 'lock' | 'groupId'>>",
     "PptistLatexElementSizing": "export interface PptistLatexElementSizing { left?: number; top?: number; width?: number; height?: number; rotate?: number }",
+    "PptistLayout": "export interface PptistLayout { id: string; label: string; summary: string; bestFor: string; feature: boolean; slots: PptistLayoutSlotDef[] }",
+    "PptistLayoutBackgroundMode": "export type PptistLayoutBackgroundMode = 'auto' | 'feature' | 'plain'",
+    "PptistLayoutSlotDef": "export interface PptistLayoutSlotDef { name: string; type: 'text' | 'bullets' | 'image' | 'chart' | 'stats' | 'rows'; required: boolean; description: string }",
     "PptistLineDirectionInput": "export type PptistLineDirectionInput = Broken2LineDirection | 'auto'",
     "PptistLineElementInput": "export type PptistLineElementInput = Partial<Pick<PPTLineElement, 'id' | 'left' | 'top' | 'width' | 'style' | 'color' | 'points' | 'shadow' | 'broken' | 'broken2' | 'broken2Direction' | 'curve' | 'cubic' | 'link' | 'name' | 'lock' | 'groupId'>> & Pick<PPTLineElement, 'start' | 'end'>",
     "PptistLineElementPatch": "export type PptistLineElementPatch = Partial<Pick<PPTLineElement, 'left' | 'top' | 'width' | 'start' | 'end' | 'style' | 'color' | 'points' | 'shadow' | 'broken' | 'broken2' | 'broken2Direction' | 'curve' | 'cubic' | 'link' | 'name' | 'lock' | 'groupId'>>",
@@ -1852,6 +2009,8 @@
     "PptistSlideReference": "export type PptistSlideReference = string | number",
     "PptistSlideThemePatch": "export type PptistSlideThemePatch = Omit<Partial<SlideTheme>, 'outline' | 'shadow'> & { outline?: Partial<SlideTheme['outline']>; shadow?: Partial<SlideTheme['shadow']> }",
     "PptistSlideTransition": "export interface PptistSlideTransition { slideId: string; turningMode?: TurningMode }",
+    "PptistStyleFonts": "export interface PptistStyleFonts { heading: string; body: string }",
+    "PptistStyleSummary": "export interface PptistStyleSummary { id: string; label: string; description: string; fonts: PptistStyleFonts; preview: { background: string; title: string; body: string; accent: string; featureBackground: string } }",
     "PptistTableElementPatch": "export type PptistTableElementPatch = Partial<Omit<PPTTableElement, 'type' | 'id' | 'outline' | 'theme'>> & { outline?: Partial<PPTTableElement['outline']>; theme?: Partial<NonNullable<PPTTableElement['theme']>> }",
     "PptistTemplateSlideEntry": "export interface PptistTemplateSlideEntry { slug: string; type: SlideType; description: string; elementCount: number }",
     "PptistTemplateSlidesCatalog": "export type PptistTemplateSlidesCatalog = Record<SlideType, PptistTemplateSlideEntry[]>",