@json-to-office/jto 0.3.0 → 0.3.3

package/dist/prompts/instructions-edit-document-docx.md

@@ -0,0 +1,54 @@
+## Current {{contentLabel}} ({{documentName}})
+The user already has this {{contentLabelLower}} open in the editor:
+```json
+{{documentText}}
+```
+
+IMPORTANT: This {{contentLabelLower}} already exists. You are EDITING it, not generating from scratch. Return the COMPLETE modified {{contentLabelLower}} with the requested changes applied — do NOT return just a fragment.
+
+### Rules for editing documents
+
+- **Preserve the existing Report/Section structure** unless the user asks to reorganize.
+- Place new content in the appropriate Section based on topic.
+- When adding sections, maintain the existing heading hierarchy (level 1 for title, level 2 for sections).
+- Keep Header/Footer intact unless explicitly asked to change them.
+
+### Example
+
+**Current document:**
+```json
+[
+  {
+    "name": "Report",
+    "props": { "title": "Status Report" },
+    "children": [
+      { "name": "Section", "props": {}, "children": [
+        { "name": "Heading", "props": { "text": "Status Report", "level": 1 } },
+        { "name": "Paragraph", "props": { "text": "Project is on track." } }
+      ]}
+    ]
+  }
+]
+```
+
+**User request:** "Add a risks section"
+
+**Correct output (full document with new section):**
+```json
+[
+  {
+    "name": "Report",
+    "props": { "title": "Status Report" },
+    "children": [
+      { "name": "Section", "props": {}, "children": [
+        { "name": "Heading", "props": { "text": "Status Report", "level": 1 } },
+        { "name": "Paragraph", "props": { "text": "Project is on track." } }
+      ]},
+      { "name": "Section", "props": {}, "children": [
+        { "name": "Heading", "props": { "text": "Risks", "level": 2 } },
+        { "name": "List", "props": { "items": ["Timeline delay if vendor is late", "Budget overrun on infrastructure"], "type": "bullet" } }
+      ]}
+    ]
+  }
+]
+```

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

@@ -0,0 +1,40 @@
+## Presentation: {{documentName}}
+
+### Available Templates (reference only — do not output these)
+{{templatesSummary}}
+
+### Current Slides
+```json
+{{slidesText}}
+```
+
+You are EDITING the slides of this presentation. Return ONLY the modified slides array:
+```json
+{
+  "children": [ ...all slides including unmodified ones... ]
+}
+```
+
+### Rules for slide-scoped editing
+
+- Output the COMPLETE `children` array — include ALL slides, not just changed ones.
+- Do NOT include `"name"` or `"props"` keys — templates and presentation settings are unchanged.
+- Reference existing template names from the list above.
+- New slides MUST reference existing templates — do not invent new templates.
+- Preserve unmodified slides exactly as they appear above.
+- When editing a slide, keep its `template` reference and only change `placeholders` content.
+- If the presentation uses templates, new slides should also use templates for consistency.
+
+### Example
+
+**User request:** "Add a slide about pricing"
+
+**Correct output (complete children array with new slide appended):**
+```json
+{
+  "children": [
+    { "name": "slide", "props": { "template": "CONTENT_TEMPLATE", "placeholders": { "heading": { "name": "text", "props": { "text": "Overview" } } } } },
+    { "name": "slide", "props": { "template": "CONTENT_TEMPLATE", "placeholders": { "heading": { "name": "text", "props": { "text": "Pricing" } } } } }
+  ]
+}
+```

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

@@ -0,0 +1,48 @@
+## Presentation: {{documentName}}
+
+### Current Templates
+```json
+{{templatesText}}
+```
+
+### Slides Using These Templates (reference only — do not output these)
+{{slidesSummary}}
+
+You are EDITING the template slides of this presentation. Output **only new or modified** templates:
+```json
+{
+  "templates": [ ...only new/changed templates... ]
+}
+```
+
+Unchanged templates are automatically preserved — do NOT echo them back.
+
+### Rules for template-scoped editing
+
+- Output ONLY templates you are adding or modifying. Omit unchanged templates entirely.
+- Do NOT include `"name"`, `"children"`, or other top-level keys — only `"templates"`.
+- When modifying a template, output the **complete** template object (all its placeholders, objects, background, etc.) — not just the changed fields.
+- Keep template names stable — slides reference them by name. Renaming a template breaks existing slides.
+- To DELETE a template, output: `{ "name": "TEMPLATE_NAME", "_delete": true }`
+- When adding a new template, use SCREAMING_SNAKE_CASE naming (e.g. `FULLSCREEN_IMAGE_TEMPLATE`).
+- Each template needs: `name`, `placeholders[]`, and optionally `background`, `objects[]`, `grid`.
+- For page numbers, add a text component with `"text": "{PAGE_NUMBER}"` inside `objects[]` — do NOT use a `slideNumber` key.
+
+### Example
+
+**User request:** "Add a divider bar to CONTENT_TEMPLATE"
+
+**Correct output (only the modified template):**
+```json
+{
+  "templates": [
+    {
+      "name": "CONTENT_TEMPLATE",
+      "placeholders": [{ "name": "heading" }, { "name": "body" }],
+      "objects": [
+        { "name": "shape", "props": { "type": "line", "x": "5%", "y": "20%", "w": "90%", "h": "0%", "line": { "color": "accent", "width": 1 } } }
+      ]
+    }
+  ]
+}
+```

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

@@ -0,0 +1,49 @@
+## Current {{contentLabel}} ({{documentName}})
+The user already has this {{contentLabelLower}} open in the editor:
+```json
+{{documentText}}
+```
+
+IMPORTANT: This {{contentLabelLower}} already exists. You are EDITING it, not generating from scratch. Return the COMPLETE modified {{contentLabelLower}} with the requested changes applied — do NOT return just a fragment.
+
+### Rules for editing presentations
+
+- **Preserve all existing templates** in `pptx.props.templates` unless explicitly asked to modify them.
+- When adding new slides, **reference existing template names** — do not invent new templates unless the user asks for a new layout.
+- When editing a slide, keep its `template` reference and only change the `placeholders` content.
+- If the presentation uses templates, new slides should also use templates for consistency.
+
+### Example
+
+**Current presentation (abbreviated):**
+```json
+{
+  "name": "pptx",
+  "props": {
+    "templates": [
+      { "name": "CONTENT_TEMPLATE", "placeholders": [{ "name": "heading", "type": "title" }, { "name": "body", "type": "body" }] }
+    ]
+  },
+  "children": [
+    { "name": "slide", "props": { "template": "CONTENT_TEMPLATE", "placeholders": { "heading": { "name": "text", "props": { "text": "Overview" } }, "body": { "name": "text", "props": { "text": "Content here." } } } } }
+  ]
+}
+```
+
+**User request:** "Add a slide about pricing"
+
+**Correct output (full document with new slide appended, using existing template):**
+```json
+{
+  "name": "pptx",
+  "props": {
+    "templates": [
+      { "name": "CONTENT_TEMPLATE", "placeholders": [{ "name": "heading", "type": "title" }, { "name": "body", "type": "body" }] }
+    ]
+  },
+  "children": [
+    { "name": "slide", "props": { "template": "CONTENT_TEMPLATE", "placeholders": { "heading": { "name": "text", "props": { "text": "Overview" } }, "body": { "name": "text", "props": { "text": "Content here." } } } } },
+    { "name": "slide", "props": { "template": "CONTENT_TEMPLATE", "placeholders": { "heading": { "name": "text", "props": { "text": "Pricing" } }, "body": { "name": "table", "props": { "rows": [["Plan", "Price"], ["Starter", "$9/mo"], ["Pro", "$29/mo"]], "grid": { "column": 0, "row": 2, "columnSpan": 12, "rowSpan": 3 } } } } } }
+  ]
+}
+```

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

@@ -0,0 +1,28 @@
+## Current {{contentLabel}} ({{documentName}})
+The user already has this {{contentLabelLower}} open in the editor:
+```json
+{{documentText}}
+```
+
+IMPORTANT: This {{contentLabelLower}} already exists. You are EDITING it, not generating from scratch. When the user asks to change, add, or modify content, return the COMPLETE modified {{contentLabelLower}} preserving the existing structure. Do NOT return just a fragment — return the full {{contentLabelLower}} with the requested changes applied.
+
+### Example
+
+**Current document:**
+```json
+[
+  { "name": "Heading", "props": { "text": "Old Title", "level": 1 } },
+  { "name": "Text", "props": { "text": "Some content here." } }
+]
+```
+
+**User request:** "Change the title to New Title and add a second paragraph"
+
+**Correct output (full document with changes applied):**
+```json
+[
+  { "name": "Heading", "props": { "text": "New Title", "level": 1 } },
+  { "name": "Text", "props": { "text": "Some content here." } },
+  { "name": "Text", "props": { "text": "Additional paragraph with new content." } }
+]
+```

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

@@ -0,0 +1,31 @@
+The user has selected a portion of their PPTX JSON document and wants you to edit it.
+
+**Document name:** {{documentName}}
+**JSON path:** {{jsonPath}}
+**Selected text:**
+```json
+{{selectedText}}
+```
+
+IMPORTANT: Produce ONLY the modified fragment that replaces the selected text above. Do NOT produce the entire document. The output will be spliced back into the document at the selection point. Wrap it in a ```json code block.
+
+### 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.
+
+### Example
+
+**Selected text:**
+```json
+{ "name": "text", "props": { "text": "Hello world", "fontSize": 14, "bold": false } }
+```
+
+**User request:** "Change to Welcome and make it bold"
+
+**Correct output** (omit fontSize if placeholder provides it):
+```json
+{ "name": "text", "props": { "text": "Welcome", "bold": true } }
+```

package/dist/prompts/instructions-edit.md

@@ -0,0 +1,24 @@
+The user has selected a portion of their JSON document and wants you to edit it.
+
+**Document name:** {{documentName}}
+**JSON path:** {{jsonPath}}
+**Selected text:**
+```json
+{{selectedText}}
+```
+
+IMPORTANT: Produce ONLY the modified fragment that replaces the selected text above. Do NOT produce the entire document. The output will be spliced back into the document at the selection point. Wrap it in a ```json code block.
+
+### Example
+
+**Selected text:**
+```json
+{ "name": "Text", "props": { "text": "Hello world", "bold": false } }
+```
+
+**User request:** "Make it bold and change to Welcome"
+
+**Correct output:**
+```json
+{ "name": "Text", "props": { "text": "Welcome", "bold": true } }
+```

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

@@ -0,0 +1,10 @@
+The user wants you to generate a complete document JSON from scratch.
+
+Produce a full DOCX JSON wrapped in a ```json code block:
+
+- Use a `Report` root with one or more `Section` children
+- Start with a level-1 `Heading` as the document title
+- Mix component types for visual interest: Headings, Paragraphs, Tables, Lists, Statistics
+- Include `Header` and `Footer` if appropriate for the document type
+- Use `Columns` for side-by-side comparisons or multi-column layouts
+- Aim for 3–6 sections with varied content

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

@@ -0,0 +1,24 @@
+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` (same `{ name, props }` component format as slide children)
+- 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
+
+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
+- [ ] Tables specify `rowH` (0.4–0.55") and `margin` ([3, 6, 3, 6])
+- [ ] Tables use `borderRadius` (0.1–0.2) for polished appearance
+- [ ] Cells with Unicode symbols (✓, —) use `fontFace: "Arial"`

package/dist/prompts/instructions-generate.md

@@ -0,0 +1,21 @@
+The user wants you to generate a complete {{contentType}} JSON from scratch.
+
+Produce a full {{contentType}} JSON wrapped in a ```json code block. Include all required fields.
+
+### Example
+
+A minimal document with a heading and paragraph:
+```json
+[
+  {
+    "name": "Heading",
+    "props": { "text": "Project Overview", "level": 1 }
+  },
+  {
+    "name": "Text",
+    "props": { "text": "This section introduces the key objectives and scope of the project." }
+  }
+]
+```
+
+Use this structure as a starting point — expand with additional components appropriate to the user's request.

package/dist/prompts/pptx-core.md

@@ -0,0 +1,180 @@
+# PPTX Presentation Guidelines
+
+## Architecture
+
+A PPTX presentation has this structure:
+
+```
+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
+```
+
+**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.
+
+## Template Slide Definition
+
+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:
+
+```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 } }
+  }
+}
+```
+
+Use the 12-column × 6-row grid instead of absolute x/y/w/h:
+
+```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
+
+## Filling Placeholders (Slide Level)
+
+Slides reference a template and fill each placeholder with a single component:
+
+```json
+{
+  "name": "slide",
+  "props": {
+    "template": "CONTENT_TEMPLATE",
+    "placeholders": {
+      "heading": { "name": "text", "props": { "text": "Slide Title" } },
+      "body": { "name": "text", "props": { "text": "Key insight here." } }
+    }
+  }
+}
+```
+
+Each placeholder maps to exactly one component (not an array). The component inherits the placeholder's position and `defaults` props.
+
+### Placeholder inheritance
+
+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.**
+
+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." } }
+```
+
+**Bad** — redundantly re-specifying what defaults already provides:
+```json
+{ "name": "text", "props": { "text": "Key insight here.", "fontSize": 14, "style": "body" } }
+```
+
+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.
+
+## Named Styles
+
+Themes define a `styles` map with predefined text style presets. Use `"style"` on text/shape components to apply formatting without repeating props.
+
+**Available style names:** `title`, `subtitle`, `heading1`, `heading2`, `heading3`, `body`, `caption`
+
+**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):**
+
+| Style    | fontSize | bold | italic | fontColor | align  |
+|----------|----------|------|--------|-----------|--------|
+| title    | 36       | yes  |        | text      | center |
+| subtitle | 20       |      | yes    | text2     | center |
+| heading1 | 28       | yes  |        | primary   |        |
+| heading2 | 22       | yes  |        | primary   |        |
+| heading3 | 18       | yes  |        | text      |        |
+| body     | 14       |      |        |           |        |
+| caption  | 10       |      | yes    | text2     |        |
+
+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
+
+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`
+- **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`