slides-grab 1.0.0

package/skills/ppt-pptx-skill/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: ppt-pptx-skill
+description: Stage 3 conversion skill for Codex. Convert approved HTML slides to PPTX/PDF and validate artifacts.
+metadata:
+  short-description: Convert slides and run conversion checks
+---
+
+# PPTX Conversion Skill (Codex)
+
+Use this only after the user approves design output.
+
+## Goal
+Convert reviewed slide HTML into PPTX (and optional PDF) reliably.
+
+## Inputs
+- Approved `<slides-dir>/slide-*.html`
+- Optional output path settings
+
+## Outputs
+- Presentation artifact (`.pptx` or `.pdf`)
+
+## Workflow
+1. Confirm user approval for conversion.
+2. Run conversion command:
+   - `node .claude/skills/pptx-skill/scripts/html2pptx.js`
+   - or `slides-grab convert --slides-dir <path>`
+3. If requested, run PDF conversion:
+   - `slides-grab pdf --slides-dir <path>`
+4. Report success/failure with actionable errors.
+
+## Rules
+- Do not modify slide content during conversion stage unless explicitly requested.
+- If conversion fails, diagnose and fix root causes in source HTML/CSS.
+
+## Reference
+For detailed conversion behavior and tools, use:
+- `.claude/skills/pptx-skill/SKILL.md`

package/skills/ppt-presentation-skill/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: ppt-presentation-skill
+description: End-to-end presentation workflow for Codex. Use when making a full presentation from scratch — planning, designing slides, editing, and exporting.
+metadata:
+  short-description: Full pipeline from topic to PPTX/PDF
+---
+
+# Presentation Skill (Codex) - Full Workflow Orchestrator
+
+Guides you through the complete presentation pipeline from topic to exported file.
+
+---
+
+## Workflow
+
+### Stage 1 — Plan
+
+Use **ppt-plan-skill** (`skills/ppt-plan-skill/SKILL.md`).
+
+1. Take user's topic, audience, and tone.
+2. Create `slide-outline.md`.
+3. Present outline to user.
+4. Revise until user explicitly approves.
+
+**Do not proceed to Stage 2 without approval.**
+
+### Stage 2 — Design
+
+Use **ppt-design-skill** (`skills/ppt-design-skill/SKILL.md`).
+
+1. Read approved `slide-outline.md`.
+2. Generate `slide-*.html` files in the slides workspace (default: `slides/`).
+3. Build the viewer: `node scripts/build-viewer.js --slides-dir <path>`
+4. Present viewer to user for review.
+5. Revise individual slides based on feedback.
+6. Optionally launch the visual editor: `slides-grab edit --slides-dir <path>`
+
+**Do not proceed to Stage 3 without approval.**
+
+### Stage 3 — Export
+
+Use **ppt-pptx-skill** (`skills/ppt-pptx-skill/SKILL.md`).
+
+1. Confirm user wants conversion.
+2. Export to PPTX: `slides-grab convert --slides-dir <path> --output <name>.pptx`
+3. Export to PDF (if requested): `slides-grab pdf --slides-dir <path> --output <name>.pdf`
+4. Report results.
+
+---
+
+## Rules
+
+1. **Always follow the stage order**: Plan → Design → Export.
+2. **Get explicit user approval** before advancing to the next stage.
+3. **Read each stage's SKILL.md** for detailed rules — this skill only orchestrates.
+4. **Use `decks/<deck-name>/`** as the slides workspace for multi-deck projects.
+5. For full design constraints, refer to `.claude/skills/design-skill/SKILL.md`.

package/src/editor/codex-edit.js

@@ -0,0 +1,213 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import sharp from 'sharp';
+
+export const SLIDE_SIZE = { width: 960, height: 540 };
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function toFiniteNumber(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return parsed;
+}
+
+export function normalizeSelection(rawSelection, slideSize = SLIDE_SIZE) {
+  if (!rawSelection || typeof rawSelection !== 'object') {
+    throw new Error('Selection is required.');
+  }
+
+  const maxWidth = slideSize.width;
+  const maxHeight = slideSize.height;
+
+  const x1 = clamp(Math.round(toFiniteNumber(rawSelection.x, 0)), 0, maxWidth);
+  const y1 = clamp(Math.round(toFiniteNumber(rawSelection.y, 0)), 0, maxHeight);
+  const w = Math.max(1, Math.round(toFiniteNumber(rawSelection.width, 1)));
+  const h = Math.max(1, Math.round(toFiniteNumber(rawSelection.height, 1)));
+
+  const x2 = clamp(x1 + w, 0, maxWidth);
+  const y2 = clamp(y1 + h, 0, maxHeight);
+
+  return {
+    x: x1,
+    y: y1,
+    width: Math.max(1, x2 - x1),
+    height: Math.max(1, y2 - y1),
+  };
+}
+
+export function scaleSelectionToScreenshot(selection, sourceSize, targetSize) {
+  const sourceWidth = sourceSize?.width ?? SLIDE_SIZE.width;
+  const sourceHeight = sourceSize?.height ?? SLIDE_SIZE.height;
+  const targetWidth = targetSize?.width;
+  const targetHeight = targetSize?.height;
+
+  if (!Number.isFinite(targetWidth) || !Number.isFinite(targetHeight)) {
+    throw new Error('Target size must include width and height.');
+  }
+
+  const sx = targetWidth / sourceWidth;
+  const sy = targetHeight / sourceHeight;
+
+  return {
+    x: Math.max(0, Math.round(selection.x * sx)),
+    y: Math.max(0, Math.round(selection.y * sy)),
+    width: Math.max(1, Math.round(selection.width * sx)),
+    height: Math.max(1, Math.round(selection.height * sy)),
+  };
+}
+
+function formatTargets(targets) {
+  if (!Array.isArray(targets) || targets.length === 0) {
+    return ['  - (No XPath targets were detected for this region.)'];
+  }
+
+  return targets.slice(0, 12).flatMap((target, index) => {
+    const text = typeof target.text === 'string' && target.text.trim() !== ''
+      ? target.text.trim().replace(/\s+/g, ' ').slice(0, 140)
+      : '(no text)';
+    return [
+      `  - Target ${index + 1}`,
+      `    - XPath: ${target.xpath}`,
+      `    - Tag: ${target.tag || 'unknown'}`,
+      `    - Text: ${text}`,
+    ];
+  });
+}
+
+export function buildCodexEditPrompt({ slideFile, slidePath, userPrompt, selections = [] }) {
+  const sanitizedPrompt = typeof userPrompt === 'string' ? userPrompt.trim() : '';
+  if (!sanitizedPrompt) {
+    throw new Error('Prompt must be a non-empty string.');
+  }
+
+  const normalizedSlidePath = typeof slidePath === 'string' && slidePath.trim() !== ''
+    ? slidePath.trim()
+    : (typeof slideFile === 'string' && slideFile.trim() !== '' ? `slides/${slideFile.trim()}` : '');
+  if (!normalizedSlidePath) throw new Error('Slide path is required.');
+
+  if (!Array.isArray(selections) || selections.length === 0) {
+    throw new Error('At least one selection is required.');
+  }
+
+  const selectionLines = selections.flatMap((selection, index) => {
+    const bbox = selection.bbox ?? selection;
+    return [
+      `Region ${index + 1}`,
+      `- Bounding box: x=${bbox.x}, y=${bbox.y}, width=${bbox.width}, height=${bbox.height}`,
+      '- XPath targets:',
+      ...formatTargets(selection.targets),
+      '',
+    ];
+  });
+
+  return [
+    `Edit ${normalizedSlidePath} only.`,
+    '',
+    'User edit request:',
+    sanitizedPrompt,
+    '',
+    'Selected regions on slide (960x540 coordinate space):',
+    ...selectionLines,
+    'Rules:',
+    '- Modify only the requested slide file.',
+    '- Keep existing structure/content unless the request requires a change.',
+    '- Keep slide dimensions at 720pt x 405pt.',
+    '- Keep text in semantic tags (<p>, <h1>-<h6>, <ul>, <ol>, <li>).',
+    '- Return after applying the change.',
+  ].join('\n');
+}
+
+export function buildCodexExecArgs({ prompt, imagePath, model }) {
+  const args = [
+    '--dangerously-bypass-approvals-and-sandbox',
+    'exec',
+    '--color',
+    'never',
+  ];
+
+  if (typeof model === 'string' && model.trim() !== '') {
+    args.push('--model', model.trim());
+  }
+
+  if (typeof imagePath === 'string' && imagePath.trim() !== '') {
+    args.push('--image', imagePath.trim());
+  }
+
+  args.push('--', prompt);
+  return args;
+}
+
+export const CLAUDE_MODELS = ['claude-opus-4-6', 'claude-sonnet-4-6'];
+
+export function isClaudeModel(model) {
+  return typeof model === 'string' && CLAUDE_MODELS.includes(model.trim());
+}
+
+export function buildClaudeExecArgs({ prompt, imagePath, model }) {
+  const args = [
+    '-p',
+    '--dangerously-skip-permissions',
+    '--model', model.trim(),
+    '--max-turns', '30',
+    '--verbose',
+  ];
+
+  let fullPrompt = prompt;
+  if (typeof imagePath === 'string' && imagePath.trim() !== '') {
+    fullPrompt = `First, read the annotated screenshot at "${imagePath.trim()}" to see the visual context of the bbox regions highlighted on the slide.\n\n${prompt}`;
+  }
+
+  args.push(fullPrompt);
+  return args;
+}
+
+function buildAnnotationSvg(width, height, bbox) {
+  const boxes = Array.isArray(bbox) ? bbox : [bbox];
+
+  const overlayItems = boxes.flatMap((item, index) => {
+    const x = item.x;
+    const y = item.y;
+    const w = item.width;
+    const h = item.height;
+    const labelY = Math.max(18, y - 6);
+    return [
+      `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="rgba(239,68,68,0.12)"/>`,
+      `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="none" stroke="#EF4444" stroke-width="4" filter="url(#shadow)"/>`,
+      `<rect x="${x}" y="${Math.max(0, labelY - 16)}" width="22" height="18" fill="#EF4444"/>`,
+      `<text x="${x + 11}" y="${labelY - 3}" text-anchor="middle" font-size="12" font-family="Arial, sans-serif" fill="#FFFFFF">${index + 1}</text>`,
+    ];
+  });
+
+  return [
+    `<svg width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg">`,
+    '<defs>',
+    '<filter id="shadow"><feDropShadow dx="0" dy="0" stdDeviation="2" flood-opacity="0.8"/></filter>',
+    '</defs>',
+    ...overlayItems,
+    '</svg>',
+  ].join('');
+}
+
+export async function writeAnnotatedScreenshot(inputImagePath, outputImagePath, bbox) {
+  await mkdir(dirname(outputImagePath), { recursive: true });
+
+  const image = sharp(inputImagePath);
+  const metadata = await image.metadata();
+  const width = metadata.width;
+  const height = metadata.height;
+
+  if (!width || !height) {
+    throw new Error('Could not read screenshot dimensions.');
+  }
+
+  const svg = buildAnnotationSvg(width, height, bbox);
+  const svgBuffer = Buffer.from(svg, 'utf8');
+
+  await image
+    .composite([{ input: svgBuffer, top: 0, left: 0 }])
+    .png()
+    .toFile(outputImagePath);
+}