@json-to-office/jto 2.4.0 → 3.0.0

package/dist/prompts/instructions-edit-pptx.md

@@ -11,21 +11,22 @@ IMPORTANT: Produce ONLY the modified fragment that replaces the selected text ab
 
 ### PPTX selection editing rules
 
-- This fragment lives inside a template-based slide. The template's placeholders already define default styling.
-- **Don't add props the placeholder already defines** — `fontSize`, `fontFace`, `color`, `bold`, `italic`, `align`, `valign`, `margin`, `charSpacing`, `lineSpacing`, `style`, and position are inherited automatically.
-- Grid positions are slide-relative, not placeholder-relative.
-- Keep components minimal — only include props that differ from placeholder defaults.
+- If the fragment is a block invocation (`"name": "block"`), keep its `ref` and change only the `slots`. An invocation takes no coordinates or styling — the definition owns them.
+- If the fragment is slot content (a chart, an image, a text placed in a component slot), it may carry its data and styling but never `x`, `y`, `w`, `h`, `position` or `grid`.
+- If the fragment is a block definition, keep every slot the document's invocations fill; bindings (`$slot`, `$theme` with a `default`, `$if`) stay valid.
+- If the fragment is a coordinate-authored component, keep its position unless asked to move it, and prefer named `style` values and theme color names over raw sizes and hex.
+- Keep components minimal; do not add props a style or a definition already provides.
 
 ### Example
 
 **Selected text:**
 ```json
-{ "name": "text", "props": { "text": "Hello world", "fontSize": 14, "bold": false } }
+{ "name": "block", "props": { "ref": "action-chart", "slots": { "title": "Revenue grew 18%", "chart": { "name": "chart", "props": { "type": "bar", "data": [{ "name": "Revenue", "labels": ["Q1", "Q2"], "values": [4.2, 4.6] }] } } } } }
 ```
 
-**User request:** "Change to Welcome and make it bold"
+**User request:** "Add a takeaway saying reliability drove the gain"
 
-**Correct output** (omit fontSize if placeholder provides it):
+**Correct output** (same ref, one more slot):
 ```json
-{ "name": "text", "props": { "text": "Welcome", "bold": true } }
+{ "name": "block", "props": { "ref": "action-chart", "slots": { "title": "Revenue grew 18%", "chart": { "name": "chart", "props": { "type": "bar", "data": [{ "name": "Revenue", "labels": ["Q1", "Q2"], "values": [4.2, 4.6] }] } }, "takeaway": "Reliability, not price, drove the gain." } } }
 ```

package/dist/prompts/instructions-generate-pptx.md

@@ -2,25 +2,21 @@ The user wants you to generate a complete presentation JSON from scratch.
 
 Produce a full PPTX JSON wrapped in a ```json code block:
 
-- Define 2–3 template slides (TITLE_TEMPLATE, CONTENT_TEMPLATE, and optionally TWO_COLUMN_TEMPLATE)
-- Templates should include header bars, footer bars, and branding text as `objects`
-- **Every component** (in `objects[]`, `placeholders`, `children[]`) MUST use `{ "name": "<type>", "props": { ... } }`. Never `{ "type": "...", ... }` with flat props
-- The presentation MUST include a `"grid"` prop on `pptx.props` (e.g. `"grid": { "columns": 12, "rows": 6, "margin": 0.5, "gutter": 0.2 }`)
-- Templates with header/footer bars MUST set `"grid": { "margin": { "top": <header-height + 0.2> } }` so row 0 starts below the header
-- Generate 5–8 slides that reference these templates and fill their placeholders
-- Mix component types: text, shapes, tables where appropriate
-- Include a title slide and a closing/thank-you slide
-- Use `charSpacing` on wordmarks, uppercase labels, and section identifiers for professional typography
-- For refined/elegant designs, use light font variants (e.g. `"Inter Light"`) via `fontFace` instead of relying on bold alone
+- Set `theme` (prefer `consulting`), `slideWidth: 13.333` and `slideHeight: 7.5` on `pptx.props`
+- Define the blocks the deck needs in `pptx.props.blocks`: copy the reference blocks you invoke verbatim, and define your own (a cover, a statement, a two-column comparison, a metric row) as percentage frames with type-role bindings and `$if` around optional slots
+- Generate 5–8 slides; every standard slide invokes a block with `{ "name": "block", "props": { "ref": "...", "slots": { ... } } }` and supplies content only — no coordinates on an invocation or in slot content
+- Include a cover slide and a closing slide
+- Coordinate-authored slides are for one-off layouts only
+- **Every component** (in a block `body`, a component slot, or `slide.children`) MUST use `{ "name": "<type>", "props": { ... } }`. Never `{ "type": "...", ... }` with flat props
+- Use `charSpacing` on wordmarks and uppercase labels; use theme color names, not hex
 
 Before finalizing, verify:
 
-- [ ] No two text/shape components share the same position
-- [ ] Headings fit their container (short text or reduced fontSize)
-- [ ] `slideNumber` is in the bottom-right, not overlapping content
-- [ ] All `ellipse` shapes intended as circles have equal `w` and `h`
-- [ ] Initials and short labels inside shapes have no `\n` line breaks
-- [ ] Every template with a header/footer bar sets `grid.margin` to push content clear
+- [ ] Every `ref` names a definition present in `props.blocks`
+- [ ] Every `required` slot of every invocation is filled; slot text respects `maxWords` and `oneLine`
+- [ ] No `templates`, `template`, `placeholders` or `layout` keys anywhere
+- [ ] Block bodies use percentage frames and `fit` on titles; theme bindings carry a `default`
+- [ ] Page numbers and trackers live in block bodies, not overlapping content
 - [ ] Tables specify `rowH` (0.4–0.55") and `margin` ([3, 6, 3, 6])
-- [ ] Tables use `borderRadius` (0.1–0.2) for polished appearance
+- [ ] `ellipse` shapes intended as circles have equal `w` and `h`
 - [ ] Cells with Unicode symbols (✓, —) use `fontFace: "Arial"`

package/dist/prompts/pptx-core.md

@@ -2,153 +2,133 @@
 
 ## Architecture
 
-A PPTX presentation has this structure:
+A PPTX presentation is one JSON tree:
 
 ```
-pptx.props.templates[]        → reusable slide layouts (defined once)
-pptx.children[].props.template → slide references a template by name
-pptx.children[].props.placeholders → slide fills template's named regions
+pptx.props                     → deck settings: title, theme, slideWidth/slideHeight, grid
+pptx.props.blocks              → reusable slide layouts, defined once as JSON (name → definition)
+pptx.children[]                → slides
+slide.children[]               → content: block invocations and/or positioned components
 ```
 
-**Template slides are the foundation of every presentation.** Every slide MUST reference a template. Templates enforce visual consistency, reduce repetition, and let placeholders carry default styling so slides stay minimal. Custom (templateless) slides are an absolute last resort.
+**Blocks are the foundation of every presentation.** A block definition owns a layout — every coordinate, every type role, every theme binding — and names the content it takes as `slots`. A slide invokes it with `{ "name": "block", "props": { "ref": "<name>", "slots": { ... } } }` and supplies only words and data. Define each standard layout once in `props.blocks` and invoke it on every slide that uses it; coordinate-authored slides are for one-off layouts only.
 
-## Template Slide Definition
+There are no slide templates, placeholders or a `layout` prop. Never emit `templates`, `template` or `placeholders` keys: they are rejected.
 
-Each template has:
-- `name` — unique identifier (SCREAMING_SNAKE_CASE)
-- `background` — optional, color or image
-- `objects[]` — fixed components (shapes, text, images) that appear on every slide using this template. Uses the same `{ name, props }` format as slide children
-- `placeholders[]` — named content regions that slides fill with components
-- `slideNumber` — optional, position and style of auto slide numbers
-- `grid` — optional grid override, merged with the presentation grid. Use this to shift the content area below header bars. Example: `"grid": { "margin": { "top": 1.1 } }` pushes row 0 below a 0.9" header.
-
-### Fixed objects in `objects[]`
-
-Template objects use the **same `{ name, props }` component format** as slide children. Any content component (shape, text, image, table, chart) can be used as a template object.
-
-**Important:** Fixed decorations (header bars, footer bars) should use absolute `x`/`y`/`w`/`h`, not grid — because the template's `grid` override shifts grid positions, and decorations shouldn't shift themselves.
-
-```json
-{ "name": "shape", "props": { "type": "rect", "x": 0, "y": 0, "w": 10, "h": 0.9, "fill": { "color": "primary" } } }
-{ "name": "shape", "props": { "type": "roundRect", "x": 0, "y": 0, "w": 10, "h": 0.9, "fill": { "color": "primary" }, "rectRadius": 0.15 } }
-{ "name": "text", "props": { "text": "COMPANY", "x": 0.6, "y": 0.15, "w": 4, "h": 0.6, "fontSize": 14, "bold": true, "color": "FFFFFF" } }
-{ "name": "shape", "props": { "type": "line", "x": 0.5, "y": 2, "w": 9, "h": 0, "line": { "color": "accent", "width": 1 } } }
-{ "name": "image", "props": { "path": "logo.png", "x": 8.5, "y": 0.15, "w": 1, "h": 0.6 } }
-```
-
-Template objects support all component props including `rectRadius`, `shadow`, `rotate`, `fill.transparency`, `line.dashType`, rich text segments, etc.
-
-### Placeholder definition
-
-```json
-{
-  "name": "body",
-  "grid": { "column": 0, "row": 2, "columnSpan": 12, "rowSpan": 3 },
-  "defaults": { "name": "text", "props": { "style": "body", "fontSize": 14 } }
-}
-```
-
-- `name` — key used in `slide.props.placeholders` to fill this region
-- Position via `grid` (preferred) or `x`/`y`/`w`/`h`
-- `defaults` — optional component stub (`{ name, props }`) whose props are inherited by the component placed in this placeholder. Supports any component type — text defaults for text placeholders, chart defaults for chart placeholders, etc.
-
-## Grid Positioning (preferred)
-
-Grid is a **presentation-level** prop (on `pptx.props`), not a theme-level setting:
+## Block definitions
 
 ```json
-{
-  "name": "pptx",
-  "props": {
-    "theme": "corporate",
-    "grid": { "columns": 12, "rows": 6, "margin": { "top": 0.75, "right": 0.6, "bottom": 0.5, "left": 0.6 }, "gutter": { "column": 0.2, "row": 0.15 } }
+"blocks": {
+  "statement": {
+    "description": "One sentence on an otherwise empty slide.",
+    "slots": {
+      "text": { "type": "string", "required": true, "maxWords": 30, "role": "actionTitle" },
+      "source": { "type": "string", "maxWords": 20, "role": "source" }
+    },
+    "body": [
+      {
+        "name": "text",
+        "props": {
+          "text": { "$slot": "/text" },
+          "style": "display",
+          "fontSize": { "$theme": "/styles/display/fontSize", "default": 28 },
+          "x": "3.75%", "y": "30%", "w": "92.5%", "h": "30%",
+          "valign": "middle",
+          "fit": { "maxLines": 3, "shrink": [24, 22] }
+        }
+      },
+      {
+        "$if": "/source",
+        "then": {
+          "name": "text",
+          "props": {
+            "text": { "$slot": "/source" },
+            "style": "source",
+            "fontSize": { "$theme": "/styles/source/fontSize", "default": 9 },
+            "x": "3.75%", "y": "94.5%", "w": "75%", "h": "5%"
+          }
+        }
+      }
+    ]
   }
 }
 ```
 
-Use the 12-column × 6-row grid instead of absolute x/y/w/h:
+- `slots` — named inputs: `type` (`string`, `number`, `integer`, `boolean`, `object`, `array`, `component`), `required`, `default`, `description`, constraints (`maxWords`, `oneLine`, `minItems`/`maxItems`, `enum`), and an optional `role` (`actionTitle`, `takeaway`, `source`, `tracker`, `footer`) so a quality profile can require or measure it.
+- `body` — ordinary slide content, expanded at the invocation. Bindings read inputs: `{ "$slot": "/title" }`, `{ "$theme": "/styles/display/fontSize", "default": 28 }` (always give theme bindings a `default`), `{ "$context": "/slide/width" }`, `{ "$if": "/source", "then": [...] , "else": [...] }` (an omitted optional slot collapses its region, decorations included), `{ "$each": "/items", "template": { ... } }` with `{ "$item": "/label" }`, `{ "$count": "/items" }`, `{ "$join": [...], "separator": " " }`, `{ "$measure": "width", "fraction": 0.5, "unit": "in" }`.
+- A component slot is placed with `{ "$slot": "/chart", "props": { "x": "0%", "y": "29%", "w": "68%", "h": "62%", ... } }`: the definition's props sit beneath the slot content's own. The content may not carry `x`, `y`, `w`, `h`, `position` or `grid`.
+- `slide` — optional `{ "background", "notes", "grid" }` the invoking slide inherits unless it states its own.
+- **Geometry as percentages of the slide** (`"x": "3.75%"`) so the definition lays out on every canvas; sizes bound to type roles with defaults so it renders on every theme.
 
-```json
-"grid": { "column": 0, "row": 1, "columnSpan": 6, "rowSpan": 2 }
-```
-
-- Columns: 0–11, Rows: 0–5
-- Grid respects presentation-level margins (default 0.5") and gutters (default 0.2")
-- Use `columnSpan`/`rowSpan` to size elements
-- Explicit `x`/`y`/`w`/`h` override grid when both are present
+### Engine operations inside a body
 
-## Filling Placeholders (Slide Level)
+- **Frame** — a `group` with `x`/`y`/`w`/`h` (or `grid`) is a nested coordinate system: children position relative to it; omitted `x`/`y` or `w`/`h` mean the frame's own.
+- **Distribution** — a `group` with `"direction": "row" | "column"`, optional `gap` and `weights`, gives each child an equal or weighted cell. An `$each` inside a row redistributes for two, three or four items; an `$if` child that collapsed is not counted.
+- **Bounded fit** — `text.fit: { "maxLines", "shrink": [24, 22] }` steps a title down through the declared sizes when it does not fit, then fails generation rather than spilling.
+- **Nested grid** — `group.gridConfig` for grid placements inside the group.
 
-Slides reference a template and fill each placeholder with a single component:
+## Invoking a block on a slide
 
 ```json
 {
   "name": "slide",
-  "props": {
-    "template": "CONTENT_TEMPLATE",
-    "placeholders": {
-      "heading": { "name": "text", "props": { "text": "Slide Title" } },
-      "body": { "name": "text", "props": { "text": "Key insight here." } }
+  "props": { "meta": { "title": "Revenue" } },
+  "children": [
+    {
+      "name": "block",
+      "props": {
+        "ref": "action-chart",
+        "slots": {
+          "title": "Revenue grew 18% as on-time delivery reached 94% of contracted work",
+          "tracker": "Performance",
+          "chart": {
+            "name": "chart",
+            "props": {
+              "type": "bar",
+              "valAxisTitle": "Revenue (€m)",
+              "data": [{ "name": "Revenue", "labels": ["Q1", "Q2", "Q3", "Q4"], "values": [4.2, 4.6, 5.1, 5.6] }]
+            }
+          },
+          "takeaway": "Reliability, not price, drove the gain.",
+          "source": "Source: quarterly operating review, 2026."
+        }
+      }
     }
-  }
+  ]
 }
 ```
 
-Each placeholder maps to exactly one component (not an array). The component inherits the placeholder's position and `defaults` props.
-
-### Placeholder inheritance
+- An invocation accepts only `ref` and `slots` — no coordinates, no styling. The `ref` must name a definition in this document's `props.blocks`; nothing is built in.
+- Fill every `required` slot; omit an optional slot and its region disappears.
+- Slot content honours the slot's constraints (`maxWords`, `oneLine`); a chart or image placed in a component slot carries its data, never its position.
+- Blocks and coordinate-authored components mix freely on one slide; a block with `slide` effects must be a direct child of the slide.
+- Label every slide with `"meta": { "title": "..." }` (authoring-only, never rendered) so editors show a navigable outline.
 
-Placeholders provide default props via `defaults`. The component placed in the placeholder inherits these — **do NOT re-specify a prop if `defaults` already defines it.**
+## Grid positioning (coordinate-authored content)
 
-Resolution order (most specific wins): `component props → defaults props → position from placeholder`
-
-This is a simple spread: `{ ...position, ...defaults.props, ...component.props }`.
-
-**Good** — defaults defines `fontSize: 14` and `style: "body"`, component omits them:
-```json
-{ "name": "text", "props": { "text": "Key insight here." } }
-```
+Grid is a **presentation-level** prop (on `pptx.props`), not a theme-level setting:
 
-**Bad** — redundantly re-specifying what defaults already provides:
 ```json
-{ "name": "text", "props": { "text": "Key insight here.", "fontSize": 14, "style": "body" } }
+{
+  "name": "pptx",
+  "props": {
+    "theme": "consulting",
+    "slideWidth": 13.333,
+    "slideHeight": 7.5,
+    "grid": { "columns": 12, "rows": 8, "margin": 0.5, "gutter": 0.2 }
+  }
+}
 ```
 
-Only override a defaults prop when you genuinely need a different value for that specific component.
-
-## Semantic Colors
-
-Use theme color names, not hex codes:
-- `primary`, `secondary`, `accent` — brand colors
-- `background`, `background2` — surface colors
-- `text`, `text2` — text colors
-- `accent4`, `accent5`, `accent6` — additional accents
-
-Only use hex (e.g. `"FFFFFF"`) for absolute white/black when needed.
+Use the grid instead of absolute x/y/w/h for one-off slides: `"grid": { "column": 0, "row": 1, "columnSpan": 6, "rowSpan": 2 }`. Columns 0–11, rows 0–(rows−1). Explicit `x`/`y`/`w`/`h` override grid when both are present. Always declare `slideWidth`/`slideHeight` (13.333 × 7.5 for 16:9); omitted, the deck falls back to 4:3.
 
-## Named Styles
+## Semantic colors
 
-Themes define a `styles` map with predefined text style presets. Use `"style"` on text/shape components to apply formatting without repeating props.
+Use theme color names, not hex codes: `primary`, `secondary`, `accent` (brand), `background`, `background2` (surfaces), `text`, `text2` (text), `accent4`, `accent5`, `accent6` (additional accents). Only use hex (e.g. `"FFFFFF"`) for absolute white/black when needed.
 
-**Available style names:** `title`, `subtitle`, `heading1`, `heading2`, `heading3`, `body`, `caption`
+## Named styles
 
-**Usage on components:**
-```json
-{ "name": "text", "props": { "text": "My Title", "style": "title" } }
-{ "name": "shape", "props": { "type": "roundRect", "text": "KPI", "style": "caption", "fill": { "color": "background2" } } }
-```
-
-**Usage on placeholder defaults:**
-```json
-{ "name": "heading", "grid": { "column": 0, "row": 0, "columnSpan": 12 }, "defaults": { "name": "text", "props": { "style": "heading1" } } }
-```
-
-**Resolution cascade (most specific wins):**
-`component props → component style → defaults props → defaults style → theme defaults`
-
-Explicit props always override style values. Example: `"style": "heading1", "fontSize": 32` → uses 32pt, not the style's fontSize.
-
-**Built-in defaults (all themes):**
+Themes define a `styles` map of text presets. Use `"style"` on text/shape components to apply formatting without repeating props: `title`, `subtitle`, `heading1`, `heading2`, `heading3`, `body`, `caption`, plus the type roles a theme declares (`display`, `eyebrow`, `stat`, `quote`, `label`, `footer`, `tracker`, `source`). Explicit props override style values; inside a block, bind the size to the role and give it a default: `"fontSize": { "$theme": "/styles/display/fontSize", "default": 28 }`.
 
 | Style    | fontSize | bold | italic | fontColor | align  |
 |----------|----------|------|--------|-----------|--------|
@@ -162,19 +142,16 @@ Explicit props always override style values. Example: `"style": "heading1", "fon
 
 Heading styles (`title`, `heading1-3`) auto-use `theme.fonts.heading`; others use `theme.fonts.body`.
 
-Themes can override styles in the `styles` key:
-```json
-"styles": {
-  "title": { "fontSize": 40, "bold": true, "fontColor": "accent", "align": "left" }
-}
-```
-
-## Available Components
+## Available components
 
-Use these inside `placeholders`, `children`, or template `objects`:
-- **text** — headings, paragraphs, bullets. Props: `text`, `fontSize`, `bold`, `italic`, `color`, `align`, `bullet`, `lineSpacing`, `charSpacing`, `paraSpaceAfter`
-- **shape** — rectangles, circles, arrows, etc. Props: `type` (rect, roundRect, ellipse, triangle, etc.), `fill`, `text` (string or `[{ text, fontSize?, color?, bold?, italic?, breakLine? }]` for rich text), `fontSize`, `fontColor`, `charSpacing`
+Use these inside `slide.children`, a block `body`, or a component slot:
+- **text** — headings, paragraphs, bullets. Props: `text`, `style`, `fontSize`, `bold`, `italic`, `color`, `align`, `valign`, `bullet`, `lineSpacing`, `charSpacing`, `paraSpaceAfter`, `fit`
+- **shape** — rectangles, circles, lines, arrows. Props: `type` (rect, roundRect, ellipse, line, triangle, …), `fill`, `line`, `text` (string or rich segments), `fontSize`, `fontColor`, `charSpacing`
 - **table** — data grids. Props: `rows` (2D array of strings or cell objects), `colW`, `rowH`, `border`, `fontSize`, `margin`, `borderRadius`
 - **image** — pictures. Props: `path` or `base64`, `sizing` ({ type: "cover"|"contain" })
-- **chart** — **DEFAULT for all charts.** Native PowerPoint chart — editable, no external server. Always use this unless the user explicitly asks for Highcharts. Title, legend, and axis label colors auto-default to the theme's `text` color for proper contrast on any background. Props: `type` (area, bar, bar3D, bubble, doughnut, line, pie, radar, scatter), `data` (array of `{ name?, labels?, values?, sizes? }`), `showLegend`, `showTitle`, `title`, `titleColor`, `chartColors` (hex or semantic), `legendPos`, `legendColor`, axis options (`catAxisTitle`, `valAxisTitle`, `valAxisMinVal`, `valAxisMaxVal`, `valAxisLabelFormatCode`, `catAxisLabelColor`, `valAxisLabelColor`), bar options (`barDir`, `barGrouping`, `barGapWidthPct`), line options (`lineSmooth`, `lineDataSymbol`, `lineSize`), pie/doughnut (`firstSliceAng`, `holeSize`), radar (`radarStyle`), data labels (`dataLabelColor`, `dataLabelFontSize`, `dataLabelPosition`)
-- **highcharts** — **ONLY use when the user explicitly requests Highcharts.** Renders charts via Highcharts as images (not editable in PowerPoint). Props: `chartOptions` (Highcharts options object), `width`, `height`
+- **chart** — **DEFAULT for all charts.** Native PowerPoint chart — editable, no external server. Props: `type` (area, bar, bar3D, bubble, doughnut, line, pie, radar, scatter), `data` (array of `{ name?, labels?, values?, sizes? }`), `showLegend`, `legendPos`, `chartColors` (semantic names), `title`, axis options (`catAxisTitle`, `valAxisTitle`, `valAxisMinVal`, `valAxisMaxVal`, `valAxisLabelFormatCode`), bar options (`barDir`, `barGrouping`), line options (`lineSmooth`, `lineDataSymbol`), pie/doughnut (`holeSize`), data labels (`dataLabelPosition`)
+- **highcharts** — **ONLY when the user explicitly requests Highcharts.** Renders as an image. Props: `chartOptions`, `width`, `height`
+- **group** — transparent container; a frame with `x`/`y`/`w`/`h`, a row or column with `direction`
+- **block** — invoke a definition from `props.blocks`
+
+Every component is `{ "name": "<type>", "props": { ... } }`. Never `{ "type": "...", ... }` with flat props. For page numbers, use a text component with `"text": "{PAGE_NUMBER} / {PAGE_COUNT}"`.