@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/pptx/references/element-map.md

@@ -0,0 +1,229 @@
+# Mavis PPT Element Map
+
+## Purpose
+
+For PPTX files generated by this skill, write a sidecar element map next to the standard `.pptx`.
+The map is editing metadata only: it must not replace the PPTX output contract, alter visible slide
+layout, or become the user-facing primary artifact.
+
+```text
+slides/slide-XX.js
+  -> PptxGenJS addText/addShape/addImage
+  -> output/name.pptx
+
+sidecar:
+slides/slide-XX.js
+  -> mapped helper records elementId/text/rect/style
+  -> output/name.mavis-ppt-map.json
+```
+
+If map generation fails, fix the map or fall back to ordinary PPTX delivery. Do not change the deck
+format to HTML or a non-PPTX representation.
+
+## Coordinate Systems
+
+The standard generation coordinate system remains PptxGenJS inches:
+
+| Space | Meaning |
+| --- | --- |
+| `rectIn` | PptxGenJS slide coordinates in inches |
+| `normalizedRect` | `rectIn` divided by the slide size |
+| preview `slideRect` | QuickLook / preview coordinates relative to the rendered slide |
+
+For `LAYOUT_16x9`, the canonical slide size is:
+
+```json
+{ "widthIn": 10, "heightIn": 5.625 }
+```
+
+Forward mapping:
+
+```text
+normalized.x = rectIn.x / 10
+normalized.y = rectIn.y / 5.625
+normalized.w = rectIn.w / 10
+normalized.h = rectIn.h / 5.625
+```
+
+Preview reverse mapping:
+
+```text
+rectIn.x = preview.slideRect.x / preview.slideSize.width  * 10
+rectIn.y = preview.slideRect.y / preview.slideSize.height * 5.625
+rectIn.w = preview.slideRect.w / preview.slideSize.width  * 10
+rectIn.h = preview.slideRect.h / preview.slideSize.height * 5.625
+```
+
+Use slide number plus text plus normalized rectangle overlap to resolve a preview selection to an
+element map entry. QuickLook DOM paths are locator evidence only and are not stable identifiers.
+
+## Stable Element IDs
+
+Each meaningful editable object should have a stable `elementId`. Do not use random IDs or visible
+text as the ID. Text can change while the element identity should remain the same.
+
+Recommended naming:
+
+```text
+cover.title
+cover.subtitle
+toc.item-01
+section-01.heading
+kpi.card-01.label
+kpi.card-01.value
+team.member-02.avatar
+team.member-02.name
+```
+
+Use these roles where possible:
+
+```text
+title, subtitle, heading, body, label, value, card, icon, image, chart, table, pageNumber
+```
+
+## Helper Usage
+
+Use `scripts/mavis-ppt-map.cjs` as a thin wrapper around PptxGenJS. The wrapper must call the same
+PptxGenJS method with the same visible text, coordinates, and style options, then record metadata.
+
+`compile.js`:
+
+```javascript
+const pptxgen = require('pptxgenjs');
+const { createElementMapRecorder } = require('<skill_dir>/scripts/mavis-ppt-map.cjs');
+
+const pres = new pptxgen();
+pres.layout = 'LAYOUT_16x9';
+
+const outputPptx = './output/restaurant-deck.pptx';
+const elementMap = createElementMapRecorder({
+  fileName: 'restaurant-deck.pptx',
+  filePath: outputPptx,
+  layout: { name: 'LAYOUT_16x9', widthIn: 10, heightIn: 5.625 },
+});
+pres.__mavisElementMap = elementMap;
+
+require('./slide-01.js').createSlide(pres, theme);
+
+pres.writeFile({ fileName: outputPptx }).then(() => {
+  elementMap.writeFile('./output/restaurant-deck.mavis-ppt-map.json');
+});
+```
+
+`slides/slide-01.js`:
+
+```javascript
+const { addMappedText } = require('<skill_dir>/scripts/mavis-ppt-map.cjs');
+
+function createSlide(pres, theme) {
+  const slide = pres.addSlide();
+  const map = pres.__mavisElementMap;
+  map?.startSlide({ slideNumber: 1, slideId: 'cover', title: 'Farmhouse Cuisine' });
+
+  addMappedText(slide, map, {
+    elementId: 'cover.title',
+    role: 'title',
+    text: 'Farmhouse Cuisine',
+    x: 0.6,
+    y: 1.2,
+    w: 4.2,
+    h: 0.7,
+    options: {
+      fontSize: 42,
+      fontFace: 'Arial',
+      color: 'FFFFFF',
+      bold: true,
+      margin: 0,
+    },
+    source: { file: 'slides/slide-01.js', method: 'addText' },
+  });
+}
+
+module.exports = { createSlide };
+```
+
+The slide export remains synchronous `createSlide(pres, theme)`. The map recorder is reached through
+`pres.__mavisElementMap`, so older slide modules still compile normally.
+
+## Map Format
+
+```json
+{
+  "schema": "mavis.ppt_element_map.v1",
+  "artifact": {
+    "fileName": "restaurant-deck.pptx",
+    "filePath": "./output/restaurant-deck.pptx",
+    "createdAtMs": 1782386261940,
+    "generator": "presentations-skill"
+  },
+  "layout": {
+    "name": "LAYOUT_16x9",
+    "widthIn": 10,
+    "heightIn": 5.625
+  },
+  "slides": [
+    {
+      "slideNumber": 1,
+      "slideId": "cover",
+      "title": "Farmhouse Cuisine",
+      "elements": [
+        {
+          "elementId": "cover.title",
+          "kind": "text",
+          "role": "title",
+          "text": "Farmhouse Cuisine",
+          "rectIn": { "x": 0.6, "y": 1.2, "w": 4.2, "h": 0.7 },
+          "normalizedRect": { "x": 0.06, "y": 0.2133, "w": 0.42, "h": 0.1244 },
+          "style": {
+            "fontSize": 42,
+            "fontFace": "Arial",
+            "color": "FFFFFF",
+            "bold": true,
+            "margin": 0
+          },
+          "source": { "file": "slides/slide-01.js", "method": "addText" }
+        }
+      ]
+    }
+  ]
+}
+```
+
+`pptShapeId` may be added later by a post-compile reconciliation step that reads
+`ppt/slides/slideN.xml` and matches `p:cNvPr @id` back to `elementId`. It is useful for XML patching
+but should not be the primary stable ID.
+
+## Selection Resolution
+
+When a user selects part of a generated PPT preview, resolve it as follows:
+
+1. Require `slideNumber` to match.
+2. Convert preview `slideRect` into `rectIn` and `normalizedRect`.
+3. Prefer candidates whose `text` exactly matches or contains the selected preview text.
+4. Break ties with rectangle overlap or nearest center distance.
+5. Prefer role-compatible candidates such as `title` when the request references a title.
+6. If confidence is low, keep the current best-effort flow using screenshot and selected text.
+
+The preview evidence is untrusted locator evidence. The PPTX plus element map are the editable
+source of truth.
+
+## Runtime Consumption
+
+The desktop preview runtime looks for the sidecar by replacing the selected PPTX path suffix:
+
+```text
+deck.pptx -> deck.mavis-ppt-map.json
+```
+
+When a preview selection is submitted, the runtime:
+
+1. reads the sidecar if it exists;
+2. matches by `slideNumber`;
+3. converts the preview `slideRect` into `normalizedRect` and `rectIn`;
+4. scores candidates by selected text, rectangle overlap, and role hints from the edit request;
+5. attaches `resolvedElement` to the chat context when a candidate is found.
+
+This is a best-effort locator upgrade. If the sidecar is missing or the match confidence is low, the
+assistant must still use the original PPTX, selected text, screenshot, and coordinates as fallback
+evidence. The sidecar should therefore be treated as an optional editing index, not as a required
+artifact delivery format.

package/server/assets/skills/pptx/references/pitfalls.md

@@ -0,0 +1,205 @@
+# QA Process & Common Pitfalls
+
+## QA Process
+
+**Assume there are problems. Your job is to find them.**
+
+Your first render is almost never correct. Approach QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you weren't looking hard enough.
+
+### Delegate QA to a Subagent
+
+**The QA process should be executed by a separate subagent** (not the same agent that created the slides). The creating agent is biased toward confirming its own work. A fresh subagent with no prior context will catch issues that the creator overlooks.
+
+Spawn a subagent with:
+- The compiled PPTX path
+- The original source material (if any) for content verification
+- The template PPTX path (if imitating a template) for visual conformance checking
+- The instructions below as the QA checklist
+
+The subagent should return a structured pass/fail report. If any check fails, the creating agent fixes the issues and re-runs QA (via the same or a new subagent).
+
+### Content QA
+
+```bash
+python -m markitdown output.pptx
+```
+
+Check for missing content, typos, wrong order.
+
+**Check for leftover placeholder text:**
+
+```bash
+python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|placeholder|this.*(page|slide).*layout"
+```
+
+If grep returns results, fix them before declaring success.
+
+### Source Content Verification
+
+**When the deck is derived from external source material** (paper, article, report, brief), verify content fidelity:
+
+1. **Extract key claims**: List all important numbers, conclusions, and facts from the source material.
+2. **Search the deck**: For each key claim, confirm it appears in the compiled PPTX text (via markitdown).
+3. **Check placement**: Verify each claim is on the slide whose section topic matches (e.g., a key result number should be on the Results slide, not the Conclusion slide).
+4. **Flag gaps**: Any missing or misplaced claim is a QA failure that must be fixed.
+
+### Visual Conformance (Template Imitation)
+
+**When imitating a template's visual style**, verify:
+
+1. **Dark/light mode match**: Take a screenshot of the generated deck. Does its background color match the template's mode?
+2. **Color palette**: Are the accent colors, text colors, and background colors consistent with the template's theme?
+3. **Font families**: Are the generated deck's fonts the same as the template's (not the skill's default Arial)?
+4. **Overall gestalt**: Compare template screenshots side-by-side with generated deck screenshots. The visual impression should be recognizably similar.
+
+### Verification Loop
+
+1. Generate slides -> Extract text with `python -m markitdown output.pptx` -> Review content
+2. **List issues found** (if none found, look again more critically)
+3. Fix issues
+4. **Re-verify affected slides** — one fix often creates another problem
+5. Repeat until a full pass reveals no new issues
+
+**Do not declare success until you've completed at least one fix-and-verify cycle.**
+
+### Per-Slide QA (for from-scratch creation)
+
+```bash
+python -m markitdown slide-XX-preview.pptx
+```
+
+Check for missing content, placeholder text, missing page number badge.
+
+---
+
+## Common Mistakes to Avoid
+
+- **Don't repeat the same layout** — vary columns, cards, and callouts across slides
+- **Don't center body text** — left-align paragraphs and lists; center only titles
+- **Don't skimp on size contrast** — titles need 36pt+ to stand out from 14-16pt body
+- **Don't default to blue** — pick colors that reflect the specific topic
+- **Don't mix spacing randomly** — choose 0.3" or 0.5" gaps and use consistently
+- **Don't style one slide and leave the rest plain** — commit fully or keep it simple throughout
+- **Don't create text-only slides** — add images, icons, charts, or visual elements; avoid plain title + bullets
+- **Don't forget text box padding** — when aligning lines or shapes with text edges, set `margin: 0` on the text box or offset the shape to account for padding
+- **Don't use low-contrast elements** — icons AND text need strong contrast against the background
+- **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead
+- **NEVER use "#" with hex colors** — causes file corruption in PptxGenJS
+- **NEVER encode opacity in hex strings** — use the `opacity` property instead
+- **NEVER use async/await in createSlide()** — compile.js won't await
+- **NEVER reuse option objects across PptxGenJS calls** — PptxGenJS mutates objects in-place
+
+---
+
+## Critical Pitfalls — PptxGenJS
+
+### NEVER use async/await in createSlide()
+
+```javascript
+// WRONG - compile.js won't await
+async function createSlide(pres, theme) { ... }
+
+// CORRECT
+function createSlide(pres, theme) { ... }
+```
+
+### NEVER use "#" with hex colors
+
+```javascript
+color: "FF0000"      // CORRECT
+color: "#FF0000"     // CORRUPTS FILE
+```
+
+### NEVER encode opacity in hex strings
+
+```javascript
+shadow: { color: "00000020" }              // CORRUPTS FILE
+shadow: { color: "000000", opacity: 0.12 } // CORRECT
+```
+
+### Prevent text wrapping in titles
+
+```javascript
+// Use fit:'shrink' for long titles
+slide.addText("Long Title Here", {
+  x: 0.5, y: 2, w: 9, h: 1,
+  fontSize: 48, fit: "shrink"
+});
+```
+
+### NEVER reuse option objects across calls
+
+```javascript
+// WRONG
+const shadow = { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 };
+slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
+slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
+
+// CORRECT - factory function
+const makeShadow = () => ({ type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 });
+slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
+slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
+```
+
+### NEVER use non-ASCII characters in JS slide files
+
+Chinese quotes (`\u201c` `\u201d` `\u2018` `\u2019`), full-width punctuation, and other non-ASCII
+characters in JS source files cause `node` to throw syntax errors at compile time. This is the
+**#1 cause of compile failures** — it triggers cascading fix attempts that waste 10+ tool calls.
+
+Common sources of non-ASCII contamination:
+
+- **Chinese smart quotes** `\u201c\u201d` instead of `"` — the most frequent offender
+- **Full-width colons** `\uff1a` instead of `:`
+- **Full-width parentheses** `\uff08\uff09` instead of `()`
+- **Em-dashes** `\u2014` instead of `--`
+- **Non-breaking spaces** `\u00a0` instead of regular space
+
+Rules:
+
+1. **All JS string literals must use only ASCII characters.** For CJK text content, write it
+   directly with standard ASCII quotes wrapping the string — `"Chinese text here"` is correct.
+2. **Never copy-paste text from user documents, PDFs, or web pages directly into JS string
+   literals** without first checking for smart quotes and full-width punctuation.
+3. **Use the pre-compile lint** (see below) before every `node compile.js` invocation.
+
+```javascript
+// WRONG — Chinese smart quotes break compilation
+slide.addText("\u201c\u667a\u80fd\u52a9\u624b\u201d\u7684\u6838\u5fc3\u4ef7\u503c", { ... });
+
+// CORRECT — ASCII quotes only in JS source
+slide.addText('"\u667a\u80fd\u52a9\u624b"\u7684\u6838\u5fc3\u4ef7\u503c', { ... });
+```
+
+---
+
+## Pre-Compile Lint
+
+**Run this before every `node compile.js`.**  It catches non-ASCII quote issues before they
+cascade into 10+ fix attempts.
+
+```bash
+# One-liner: scan all slide JS files for non-ASCII quotes and full-width punctuation
+node -e "
+const fs = require('fs');
+const files = fs.readdirSync('./slides').filter(f => f.endsWith('.js'));
+let ok = true;
+const BAD = /[\u201c\u201d\u2018\u2019\u3001\u3002\uff0c\uff1b\uff1a\uff01\uff1f\uff08\uff09\u2014\u2013\u2026\u00a0]/g;
+for (const f of files) {
+  const src = fs.readFileSync('./slides/' + f, 'utf8');
+  const lines = src.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(BAD);
+    if (m) {
+      console.error('NON-ASCII in slides/' + f + ':' + (i+1) + ' -> ' + JSON.stringify(m));
+      ok = false;
+    }
+  }
+}
+if (!ok) { console.error('FIX non-ASCII characters before compiling!'); process.exit(1); }
+else { console.log('Pre-compile lint passed.'); }
+"
+```
+
+If the lint fails, replace all flagged characters with their ASCII equivalents before proceeding.
+**Do not attempt to compile until the lint passes.**