slides-grab 1.1.3 → 1.1.5

package/README.md

@@ -31,16 +31,16 @@ Paste one of these into your coding agent:
 **Claude Code:**
 
 ```
-Read https://raw.githubusercontent.com/vkehfdl1/slides-grab/main/docs/prompts/setup-claude.md and follow every step.
+Read https://raw.githubusercontent.com/vkehfdl1/slides-grab/main/docs/installation/claude.md and follow every step.
 ```
 
 **Codex:**
 
 ```
-Read https://raw.githubusercontent.com/vkehfdl1/slides-grab/main/docs/prompts/setup-codex.md and follow every step.
+Read https://raw.githubusercontent.com/vkehfdl1/slides-grab/main/docs/installation/codex.md and follow every step.
 ```
 
-Or clone manually:
+Or use the repo directly if you want to develop on slides-grab itself:
 
 ```bash
 git clone https://github.com/vkehfdl1/slides-grab.git && cd slides-grab
@@ -49,6 +49,14 @@ npm ci && npx playwright install chromium
 
 > Requires **Node.js >= 18**.
 
+### No-clone install
+
+```bash
+npm install slides-grab
+npx playwright install chromium
+npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy
+```
+
 ## Why This Project?
 
 There are many AI tools that generate slide HTML. Almost none let you **visually point at what you want changed** and iterate in-place. slides-grab fills that gap:
@@ -118,19 +126,25 @@ This command reuses the HTML to PPTX pipeline and emits a `.pptx` deck intended
 
 ## Installation Guides
 
-- [Claude Code setup](docs/prompts/setup-claude.md)
-- [Codex setup](docs/prompts/setup-codex.md)
 - [Claude detailed guide](docs/installation/claude.md)
 - [Codex detailed guide](docs/installation/codex.md)
 
 ## npm Package
 
-Also available as an npm package for standalone CLI usage:
+Also available as an npm package for standalone CLI + skill usage:
 
 ```bash
 npm install slides-grab
 ```
 
+Install shared agent skills with Vercel Agent Skills:
+
+```bash
+npx skills add ./node_modules/slides-grab -g -a codex -a claude-code --yes --copy
+```
+
+This npm-install path is enough for normal usage. Clone the repo only when you want to modify or contribute to `slides-grab` itself.
+
 ## Project Structure
 
 ```
@@ -139,8 +153,7 @@ src/editor/       Visual editor (HTML + JS client modules)
 scripts/          Build, validate, convert, editor server
 templates/        Slide HTML templates (cover, content, chart, ...)
 themes/           Color themes (modern-dark, executive, sage, ...)
-.claude/skills/   Claude Code skill definitions
-skills/           Codex skill definitions
+skills/           Shared Vercel-installable agent skills + references
 docs/             Installation & usage guides
 ```
 

package/bin/ppt-agent.js

@@ -167,18 +167,6 @@ program
     await runCommand('scripts/editor-server.js', args);
   });
 
-program
-  .command('install-codex-skills')
-  .description('Install project Codex skills into $CODEX_HOME/skills (default: ~/.codex/skills)')
-  .option('--force', 'Overwrite existing skill directories')
-  .option('--dry-run', 'Preview what would be installed')
-  .action(async (options = {}) => {
-    const args = [];
-    if (options.force) args.push('--force');
-    if (options.dryRun) args.push('--dry-run');
-    await runCommand('scripts/install-codex-skills.js', args);
-  });
-
 // --- Template/theme discovery commands ---
 
 program

package/convert.cjs

@@ -1,239 +1,12 @@
-const PptxGenJS = require('pptxgenjs');
-const { chromium } = require('playwright');
-const path = require('path');
-const fs = require('fs');
-const sharp = require('sharp');
 const {
-  getResolutionChoices,
-  getResolutionSize,
-  normalizeResolutionPreset,
-} = require('./src/export-resolution.cjs');
-
-// Inline a simplified version that uses Playwright Chromium (not Chrome)
-const DEFAULT_SLIDES_DIR = 'slides';
-const DEFAULT_OUTPUT = 'output.pptx';
-const DEFAULT_RESOLUTION = '2160p';
-const DEFAULT_CAPTURE_VIEWPORT = { width: 960, height: 540 };
-const DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR = 2;
-const TARGET_RASTER_DPI = 150;
-const TARGET_SLIDE_SIZE_IN = { width: 13.33, height: 7.5 };
-
-function normalizeDimension(value, fallback) {
-  if (!Number.isFinite(value) || value <= 0) {
-    return fallback;
-  }
-  return Math.max(1, Math.round(value));
-}
-
-function buildPageOptions(resolution = '') {
-  const targetResolution = getResolutionSize(resolution);
-  return {
-    viewport: {
-      width: DEFAULT_CAPTURE_VIEWPORT.width,
-      height: DEFAULT_CAPTURE_VIEWPORT.height,
-    },
-    deviceScaleFactor: targetResolution
-      ? targetResolution.height / DEFAULT_CAPTURE_VIEWPORT.height
-      : DEFAULT_CAPTURE_DEVICE_SCALE_FACTOR,
-  };
-}
-
-function getTargetRasterSize(resolution = '') {
-  const targetResolution = getResolutionSize(resolution);
-  if (targetResolution) {
-    return targetResolution;
-  }
-
-  return {
-    width: Math.round(TARGET_SLIDE_SIZE_IN.width * TARGET_RASTER_DPI),
-    height: Math.round(TARGET_SLIDE_SIZE_IN.height * TARGET_RASTER_DPI),
-  };
-}
-
-function printUsage() {
-  process.stdout.write(
-    [
-      'Usage: node convert.cjs [options]',
-      '',
-      'Options:',
-      `  --slides-dir <path>  Slide directory (default: ${DEFAULT_SLIDES_DIR})`,
-      `  --output <path>      Output pptx path (default: ${DEFAULT_OUTPUT})`,
-      `  --resolution <preset> Raster size preset: ${getResolutionChoices().join('|')}|4k (default: ${DEFAULT_RESOLUTION})`,
-      '  -h, --help           Show this help message',
-    ].join('\n'),
-  );
-  process.stdout.write('\n');
-}
-
-function readOptionValue(args, index, optionName) {
-  const next = args[index + 1];
-  if (!next || next.startsWith('-')) {
-    throw new Error(`Missing value for ${optionName}.`);
-  }
-  return next;
-}
-
-function parseArgs(args) {
-  const options = {
-    slidesDir: DEFAULT_SLIDES_DIR,
-    output: DEFAULT_OUTPUT,
-    resolution: DEFAULT_RESOLUTION,
-    help: false,
-  };
-
-  for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (arg === '-h' || arg === '--help') {
-      options.help = true;
-      continue;
-    }
-
-    if (arg === '--slides-dir') {
-      options.slidesDir = readOptionValue(args, i, '--slides-dir');
-      i += 1;
-      continue;
-    }
-
-    if (arg.startsWith('--slides-dir=')) {
-      options.slidesDir = arg.slice('--slides-dir='.length);
-      continue;
-    }
-
-    if (arg === '--output') {
-      options.output = readOptionValue(args, i, '--output');
-      i += 1;
-      continue;
-    }
-
-    if (arg.startsWith('--output=')) {
-      options.output = arg.slice('--output='.length);
-      continue;
-    }
-
-    if (arg === '--resolution') {
-      options.resolution = normalizeResolutionPreset(readOptionValue(args, i, '--resolution'));
-      i += 1;
-      continue;
-    }
-
-    if (arg.startsWith('--resolution=')) {
-      options.resolution = normalizeResolutionPreset(arg.slice('--resolution='.length));
-      continue;
-    }
-
-    throw new Error(`Unknown option: ${arg}`);
-  }
-
-  if (typeof options.slidesDir !== 'string' || options.slidesDir.trim() === '') {
-    throw new Error('--slides-dir must be a non-empty string.');
-  }
-
-  if (typeof options.output !== 'string' || options.output.trim() === '') {
-    throw new Error('--output must be a non-empty string.');
-  }
-
-  options.slidesDir = options.slidesDir.trim();
-  options.output = options.output.trim();
-  options.resolution = normalizeResolutionPreset(options.resolution);
-  return options;
-}
-
-async function convertSlide(htmlFile, pres, browser, options = {}) {
-  const filePath = path.isAbsolute(htmlFile) ? htmlFile : path.join(process.cwd(), htmlFile);
-
-  const page = await browser.newPage(buildPageOptions(options.resolution));
-  await page.goto(`file://${filePath}`);
-
-  const bodyDimensions = await page.evaluate(() => {
-    const body = document.body;
-    const style = window.getComputedStyle(body);
-    return {
-      width: parseFloat(style.width),
-      height: parseFloat(style.height),
-    };
-  });
-
-  await page.setViewportSize({
-    width: normalizeDimension(bodyDimensions.width, DEFAULT_CAPTURE_VIEWPORT.width),
-    height: normalizeDimension(bodyDimensions.height, DEFAULT_CAPTURE_VIEWPORT.height)
-  });
-
-  // Take screenshot and add as full-slide image
-  const screenshot = await page.screenshot({ type: 'png' });
-  await page.close();
-
-  // Resize to exact slide dimensions (13.33" x 7.5" at 150 DPI)
-  const targetSize = getTargetRasterSize(options.resolution);
-
-  const resized = await sharp(screenshot)
-    .resize(targetSize.width, targetSize.height, { fit: 'fill' })
-    .png()
-    .toBuffer();
-
-  const tmpPath = path.join(process.env.TMPDIR || '/tmp', `slide-${Date.now()}-${Math.random().toString(36).slice(2)}.png`);
-  fs.writeFileSync(tmpPath, resized);
-
-  const slide = pres.addSlide();
-  slide.addImage({
-    path: tmpPath,
-    x: 0,
-    y: 0,
-    w: '100%',
-    h: '100%'
-  });
-
-  return tmpPath;
-}
-
-async function main() {
-  const options = parseArgs(process.argv.slice(2));
-  if (options.help) {
-    printUsage();
-    return;
-  }
-
-  const pres = new PptxGenJS();
-  pres.layout = 'LAYOUT_WIDE'; // 16:9
-
-  const slidesDir = path.resolve(process.cwd(), options.slidesDir);
-  const { ensureSlidesPassValidation } = await import('./scripts/validate-slides.js');
-  await ensureSlidesPassValidation(slidesDir, { exportLabel: 'PPTX export' });
-  const files = fs.readdirSync(slidesDir)
-    .filter(f => f.endsWith('.html'))
-    .sort();
-
-  console.log(`Converting ${files.length} slides...`);
-
-  // Launch Chromium (not Chrome)
-  const browser = await chromium.launch();
-  const tmpFiles = [];
-
-  for (const file of files) {
-    const filePath = path.join(slidesDir, file);
-    console.log(`  Processing: ${file}`);
-    try {
-      const tmpPath = await convertSlide(filePath, pres, browser, { resolution: options.resolution });
-      tmpFiles.push(tmpPath);
-      console.log(`    ✓ ${file} done`);
-    } catch (err) {
-      console.error(`    ✗ ${file} error: ${err.message}`);
-    }
-  }
-
-  await browser.close();
-
-  const outputFile = path.resolve(process.cwd(), options.output);
-  await pres.writeFile({ fileName: outputFile });
-  console.log(`\nSaved: ${outputFile}`);
-
-  // Cleanup tmp files
-  for (const f of tmpFiles) {
-    try { fs.unlinkSync(f); } catch {}
-  }
-}
+  buildPageOptions,
+  getTargetRasterSize,
+  main,
+  parseArgs,
+} = require('./src/pptx-raster-export.cjs');
 
 if (require.main === module) {
-  main().catch(err => {
+  main().catch((err) => {
     console.error('Fatal error:', err);
     process.exit(1);
   });
@@ -242,5 +15,6 @@ if (require.main === module) {
 module.exports = {
   buildPageOptions,
   getTargetRasterSize,
+  main,
   parseArgs,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slides-grab",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Agent-first presentation framework — plan, design, and visually edit HTML slides with Claude Code or Codex, then export to PDF or experimental/unstable PPTX/Figma formats",
   "license": "MIT",
   "author": "vkehfdl1",
@@ -38,7 +38,6 @@
     "scripts/figma-export.js",
     "scripts/html2pdf.js",
     "scripts/html2pptx.js",
-    "scripts/install-codex-skills.js",
     "scripts/validate-slides.js",
     "skills/",
     "src/",
@@ -52,8 +51,7 @@
     "build-viewer": "node scripts/build-viewer.js",
     "validate": "node scripts/validate-slides.js",
     "convert": "node convert.cjs",
-    "codex:install-skills": "node scripts/install-codex-skills.js --force",
-    "test": "node --test tests/editor/editor-codex-edit.test.js tests/pdf/html2pdf.test.js tests/pdf/html2pdf.e2e.test.js tests/figma/figma-export.test.js tests/image-contract/image-contract.test.js tests/validation/validate-slides.test.js",
+    "test": "node --test tests/editor/editor-codex-edit.test.js tests/pdf/html2pdf.test.js tests/pdf/html2pdf.e2e.test.js tests/figma/figma-export.test.js tests/image-contract/image-contract.test.js tests/validation/validate-slides.test.js tests/skills/installable-skills.test.js",
     "test:e2e": "node --test tests/editor/editor-ui.e2e.test.js tests/editor/editor-concurrency.e2e.test.js"
   },
   "dependencies": {

package/scripts/html2pdf.js

@@ -403,7 +403,6 @@ export async function normalizeBodyToSlideFrame(page, slideFrame) {
     const documentElement = document.documentElement;
 
     body.style.margin = '0';
-    body.style.padding = '0';
     body.style.width = `${width}px`;
     body.style.height = `${height}px`;
     body.style.minWidth = `${width}px`;

package/skills/slides-grab/SKILL.md

@@ -15,7 +15,7 @@ Guides you through the complete presentation pipeline from topic to exported fil
 
 ### Stage 1 — Plan
 
-Use **slides-grab-plan** (`skills/slides-grab-plan/SKILL.md`).
+Use the installed **slides-grab-plan** skill.
 
 1. Take user's topic, audience, and tone.
 2. Create `slide-outline.md`.
@@ -26,13 +26,13 @@ Use **slides-grab-plan** (`skills/slides-grab-plan/SKILL.md`).
 
 ### Stage 2 — Design
 
-Use **slides-grab-design** (`skills/slides-grab-design/SKILL.md`).
+Use the installed **slides-grab-design** skill.
 
 1. Read approved `slide-outline.md`.
 2. Generate `slide-*.html` files in the slides workspace (default: `slides/`).
 3. Run validation: `slides-grab validate --slides-dir <path>`
 4. If validation fails, automatically fix the slide HTML/CSS until validation passes.
-5. Build the viewer: `node scripts/build-viewer.js --slides-dir <path>`
+5. Build the viewer: `slides-grab build-viewer --slides-dir <path>`
 6. Present viewer to user for review.
 7. Revise individual slides based on feedback, then re-run validation and rebuild the viewer.
 8. Optionally launch the visual editor: `slides-grab edit --slides-dir <path>`
@@ -41,7 +41,7 @@ Use **slides-grab-design** (`skills/slides-grab-design/SKILL.md`).
 
 ### Stage 3 — Export
 
-Use **slides-grab-export** (`skills/slides-grab-export/SKILL.md`).
+Use the installed **slides-grab-export** skill.
 
 1. Confirm user wants conversion.
 2. Export to PPTX: `slides-grab convert --slides-dir <path> --output <name>.pptx` (**experimental / unstable**)
@@ -57,4 +57,7 @@ Use **slides-grab-export** (`skills/slides-grab-export/SKILL.md`).
 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. **Call out export risk clearly**: PPTX and Figma export are experimental / unstable and must be described as best-effort output.
-6. For full design constraints, refer to `.claude/skills/design-skill/SKILL.md`.
+6. Use the stage skills as the source of truth for plan, design, and export rules.
+
+## Reference
+- `references/presentation-workflow-reference.md` — archived end-to-end workflow guidance from the legacy skill set

package/skills/slides-grab/references/presentation-workflow-reference.md

@@ -0,0 +1,52 @@
+# Presentation Skill - Full Workflow Orchestrator
+
+Guides you through the complete presentation pipeline from topic to exported file.
+
+---
+
+## Workflow
+
+### Stage 1 — Plan
+
+Use **plan-skill** (`.claude/skills/plan-skill/SKILL.md`).
+
+1. Take user's topic, audience, and tone.
+2. Delegate outline creation to `organizer-agent`.
+3. Present `slide-outline.md` to user.
+4. Revise until user explicitly approves.
+
+**Do not proceed to Stage 2 without approval.**
+
+### Stage 2 — Design
+
+Use **design-skill** (`.claude/skills/design-skill/SKILL.md`).
+
+1. Read approved `slide-outline.md`.
+2. Generate `slide-*.html` files in the slides workspace (default: `slides/`).
+3. Run validation: `slides-grab validate --slides-dir <path>`
+4. If validation fails, automatically fix the slide HTML/CSS until validation passes.
+5. Build the viewer: `node scripts/build-viewer.js --slides-dir <path>`
+6. Present viewer to user for review.
+7. Revise individual slides based on feedback, then re-run validation and rebuild the viewer.
+8. Optionally launch the visual editor: `slides-grab edit --slides-dir <path>`
+
+**Do not proceed to Stage 3 without approval.**
+
+### Stage 3 — Export
+
+Use **pptx-skill** (`.claude/skills/pptx-skill/SKILL.md`).
+
+1. Confirm user wants conversion.
+2. Export to PPTX: `slides-grab convert --slides-dir <path> --output <name>.pptx` (**experimental / unstable**)
+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. **Call out export risk clearly**: PPTX and Figma export are experimental / unstable and should be described as best-effort output.

package/skills/slides-grab-design/SKILL.md

@@ -26,7 +26,7 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 2. Generate slide HTML files with 2-digit numbering in selected `--slides-dir`.
 3. Run `slides-grab validate --slides-dir <path>` after generation or edits.
 4. If validation fails, automatically fix the source slide HTML/CSS and re-run validation until it passes.
-5. Run `node scripts/build-viewer.js --slides-dir <path>` only after validation passes.
+5. Run `slides-grab build-viewer --slides-dir <path>` only after validation passes.
 6. Iterate on user feedback by editing only requested slide files, then re-run validation and rebuild the viewer.
 7. Keep revising until user approves conversion stage.
 
@@ -39,7 +39,10 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 - Prefer `<img>` for slide imagery and `data-image-placeholder` when no final asset exists.
 - Do not present slides for review until `slides-grab validate --slides-dir <path>` passes.
 - Do not start conversion before approval.
+- Use the packaged CLI and bundled references only; do not depend on unpublished agent-specific files.
 
 ## Reference
 For full constraints and style system, follow:
-- `.claude/skills/design-skill/SKILL.md`
+- `references/design-rules.md`
+- `references/detailed-design-rules.md`
+- `references/design-system-full.md` — archived full design system, templates, and advanced pattern guidance

package/skills/slides-grab-design/references/design-rules.md

@@ -0,0 +1,49 @@
+# slides-grab Design Reference
+
+These are the packaged design rules for installable `slides-grab` skills.
+
+## Package-first commands
+- Validate slides: `slides-grab validate --slides-dir <path>`
+- Build review viewer: `slides-grab build-viewer --slides-dir <path>`
+- Launch editor: `slides-grab edit --slides-dir <path>`
+
+## Slide spec
+- Slide size: `720pt x 405pt` (16:9)
+- Font: Pretendard
+- Semantic text tags only: `p`, `h1-h6`, `ul`, `ol`, `li`
+- CSS colors must include `#`
+- Avoid CSS gradients for PPTX-targeted decks
+
+## Asset rules
+- Store deck-local assets in `<slides-dir>/assets/`
+- Reference deck-local assets as `./assets/<file>`
+- Allow `data:` URLs only when the slide must be fully self-contained
+- Never use absolute filesystem paths
+
+## Package-published theme references
+- `themes/executive.css`
+- `themes/sage.css`
+- `themes/modern-dark.css`
+- `themes/corporate.css`
+- `themes/warm.css`
+
+## Package-published template references
+- `templates/cover.html`
+- `templates/contents.html`
+- `templates/section-divider.html`
+- `templates/content.html`
+- `templates/statistics.html`
+- `templates/split-layout.html`
+- `templates/team.html`
+- `templates/quote.html`
+- `templates/timeline.html`
+- `templates/closing.html`
+- `templates/chart.html`
+- `templates/diagram.html`
+- `templates/custom/`
+
+## Review loop
+- Generate or edit only the needed slide files.
+- Re-run validation after every generation/edit pass.
+- Rebuild the viewer only after validation passes.
+- Do not move to export until the user approves the reviewed deck.