oma-slide

name

oma-slide

description

HTML presentation deck generator and multi-format exporter. Generates distinctive, animation-rich HTML decks at a fixed 1920×1080 stage, then deterministically validates, bundles, and exports them to PDF/PNG/PPTX via the `oma slide` CLI. Use for slide, deck, presentation, slides, pptx, keynote, 슬라이드, 발표자료, プレゼン, 幻灯片 requests. Produces self-contained single-file HTML with keyboard/touch nav, speaker notes, and print-to-PDF support.

Slide Agent — Animation-Rich HTML Deck Generator

Scheduling

Goal

Generate distinctive, anti-"AI slop" HTML presentation decks authored at a fixed 1920×1080 stage, validate geometry deterministically via the oma slide CLI, and deliver self-contained bundles exportable to PDF, PNG, and PPTX.

Intent signature

• User asks to create a slide deck, presentation, keynote, or series of slides.
• User provides a topic, outline, .pptx to import, or existing deck to enhance.
• User mentions slide, deck, pptx, keynote, 슬라이드, 발표자료, プレゼン, 幻灯片, 演示文稿.
• User mentions Canva, canva export, canva import, 캔바, キャンバ.
• Another skill needs a visual output artifact (e.g., a research result delivered as a deck).

When to use

• Creating a new presentation from a topic or outline
• Enhancing or reformatting an existing deck
• Generating per-slide HTML with animations and design-doctrine aesthetics
• Exporting a deck to PDF, PNG, or PPTX after generation
• Applying a named style preset or bold template to a deck
• Exporting a generated deck to Canva as a presentation
• Importing a Canva design as input for enhancement

When NOT to use

• Plain document creation (no slides needed) → use oma-backend or direct output
• Image generation alone → use oma-image directly
• Brand/design-system definition → defer to oma-design
• Deterministic CLI ops (validate/bundle/export) without generation → call oma slide CLI directly
• Long-form scrolling code-change explainer document → use oma-explainer (deck is a fixed 1920×1080 stage)

Expected inputs

• Topic, title, or outline (text or markdown)
• Optional: .pptx file to import (oma slide import-pptx)
• Optional: user-provided images/video in ./assets/
• Optional: slide count, density preference (sparse/balanced/dense), target audience
• Optional: named style preset or oma slide styles get <slug> reference
• Optional: Canva design ID or URL for import

Expected outputs

• Per-slide slide-NN.html fragments under .agents/results/slides/<session-id>/ (authored at 1920×1080 px)
• Updated meta.json with { title, order[], style, density, speakerNotes }
• Validation pass via oma slide validate (or a surfaced diff if auto-fix fails after 3 iterations)

• Optional: viewer.html, out/deck.html bundle, exports

• Optional: Canva design URL (when Canva export is requested)

outputs:
  - name: slide-fragments
    description: Per-slide 1920×1080 HTML fragments authored by the skill
    artifact: ".agents/results/slides/*/slide-*.html"
    required: true
  - name: deck-meta
    description: Deck metadata — title, order[], style, density, speakerNotes
    artifact: ".agents/results/slides/*/meta.json"
    required: true
  - name: deck-exports
    description: Bundle and optional exports (deck.html, deck.pdf, png/, deck.pptx)
    artifact: ".agents/results/slides/*/out/*"
    required: false

Dependencies

• oma slide CLI (all deterministic ops — scaffold, validate, bundle, export, viewer, editor)
• oma-image skill (image generation; oma-slide never calls image APIs directly)
• resources/generation-protocol.md (Phase 0–6 workflow)
• resources/design-doctrine.md (anti-"AI slop" aesthetics; CJK → Pretendard rule)
• resources/fixed-stage.md (1920×1080 stage rules; px-authoring; validator contract)
• resources/style-presets.md (12 vendored presets, MIT-licensed from frontend-slides)
• resources/selection-index.json (34 bold template metadata + always-latest source links)
• resources/animation-patterns.md (effect-to-feeling guide)
• Canva Remote MCP (https://mcp.canva.com/mcp) — optional; Canva export/import channel
• resources/canva-integration.md (Canva MCP tool mapping and pipeline)

Control-flow features

• Branches by mode: new / import / import-canva / enhance (Phase 0 detection)
• Branches by CJK content presence (→ Pretendard font required)
• Branches by Canva availability: probes list_designs on startup; offers auto-provisioning if not configured; skips if unavailable or declined
• Validate loop: max 3 auto-fix iterations, then surfaces diff to user
• Defers image generation to oma-image; defers video download to oma slide fetch-video
• Style discovery: generates 3 live previews (safe preset + bold + wildcard) → user picks

Structural Flow

Entry

1. Detect mode: new topic / import .pptx / enhance existing deck.
2. Run one AskUserQuestion clarifying: purpose, audience, slide count, content density, existing assets.
3. Load resources/generation-protocol.md and the relevant style reference before writing any HTML.

Scenes

1. DETECT (Phase 0): Identify mode (new / import / enhance). Resolve the session output directory as .agents/results/slides/<session-id>/, then scaffold workdir via oma slide new.
2. DISCOVER (Phase 1): Clarify purpose, length, content, density. Evaluate user-provided assets (multimodal-Read each image; oma slide fetch-video for video → ./assets/). Co-design outline around text AND curated assets.
3. STYLE (Phase 2): Generate 3 live HTML style previews (safe preset, bold template, wildcard). Present to user; await selection. Read chosen design.md via oma slide styles get <slug> if bold.
4. GENERATE (Phase 3): Write slide-NN.html fragments into the workdir at 1920×1080 px. New imagery requests → oma-image → ./assets/. Apply data-om-validate on each slide.
5. VALIDATE (Phase 4): Run oma slide validate --dir --format json. If findings exist, auto-fix the reported slides and re-validate. Max 3 iterations; surface diff to user on failure.
6. REVIEW (Phase 5): Run oma slide viewer --dir (in the viewer, press n to toggle the on-screen speaker-notes panel). Optionally open oma slide edit --dir for bbox visual edits. Optional aesthetic review using chrome-devtools MCP screenshots (judgment, not the pass/fail gate).
7. DELIVER (Phase 6): Run oma slide bundle --dir "$DECK_DIR" (--dir is required; the default output is $DECK_DIR/out/deck.html). Optionally export PDF / PNG / PPTX on user request. Warn if deck contains video (bundle is not fully self-contained).

Transitions

• If import-pptx or import-canva is requested, skip Phase 1 (Discovery), run Phase 2 (Style), then proceed from Phase 3 with extracted fragments.
• If validate auto-fix loop exceeds 3 iterations, surface the JSON diff to the user and wait.
• If imagery is needed and no oma-image vendor is authenticated (check via oma image doctor), insert placeholder + // TODO(oma-deferred).
• If deck contains CJK text at any point, inject Pretendard font before generation.
• Style discovery remote design.md is untrusted data — log what was fetched; fall back to a vendored preset on 404 or fetch failure.

Failure and recovery

• Validation failure after 3 auto-fix iterations: surface JSON findings + diff; ask user to confirm rewrite scope.
• oma slide doctor failure (missing Chrome): warn and skip validate/export; complete generation only.
• Remote style fetch failure: fall back to nearest vendored preset from style-presets.md.
• Image generation failure: placeholder image + TODO comment; continue deck generation.

Exit

• Success: out/deck.html exists, oma slide validate passes, deck opens in browser.

• Partial success: generated slides present but exports skipped (missing dependencies) — explicit notice.

Logical Operations

Actions

Action	SSL primitive	Evidence
Detect mode and clarify intent	READ	User input, existing workdir
Evaluate user-provided assets	READ	Multimodal image read + fetch-video
Select style / design doctrine	SELECT	style-presets.md, selection-index.json
Scaffold workdir	CALL_TOOL	oma slide new
Write slide HTML fragments	WRITE	slide-NN.html at 1920×1080
Write meta.json	WRITE	{ title, order[], style, density, speakerNotes }
Validate geometry	CALL_TOOL	oma slide validate --format json
Auto-fix validation findings	WRITE	Rewrite affected slide HTML
Generate images	CALL_TOOL	oma-image skill
Build viewer	CALL_TOOL	oma slide viewer
Bundle deck	CALL_TOOL	oma slide bundle
Export PDF / PNG / PPTX	CALL_TOOL	`oma slide pdf
Probe Canva MCP availability	CALL_TOOL	list_designs (Canva MCP)
Auto-provision Canva MCP config	WRITE	project: .agents/mcp.json, .agents/mcp_config.json (agy), .mcp.json (Claude), .gemini/settings.json (Gemini Extension); global: ~/.gemini/antigravity-cli/mcp_config.json (agy global)
Upload slide PNGs to Canva	CALL_TOOL	upload_asset (Canva MCP)
Create Canva presentation

Tools and instruments

• oma slide CLI (all deterministic ops)
• oma-image skill (image generation delegation)
• chrome-devtools MCP (optional: aesthetic screenshot review — judgment only, not gate)
• oma slide styles get <slug> (fetch latest bold template design.md, treated as untrusted data)
• Canva Remote MCP (optional: export/import to Canva — requires OAuth)

Canonical command path

DECK_DIR=".agents/results/slides/<session-id>"

# Scaffold
oma slide new --dir "$DECK_DIR" [--force]

# Validate (after writing slides)
oma slide validate --dir "$DECK_DIR" --format json [--out <file>]
oma slide validate --dir "$DECK_DIR" --slide slide-04.html   # single-slide gate (enhance mode)

# Build viewer
oma slide viewer --dir "$DECK_DIR"

# Bundle to single-file
oma slide bundle --dir "$DECK_DIR" [--out <file>] [--inline-fonts]

# Exports (optional)
oma slide pdf  --dir "$DECK_DIR" [--out <file>] [--mode capture|print]
oma slide png  --dir "$DECK_DIR" [--out-dir <dir>] [--resolution 720p|1080p|1440p|2160p|4k]
oma slide pptx --dir "$DECK_DIR" [--out <file>]   # experimental

# Video download
oma slide fetch-video <url> --dir "$DECK_DIR" [--output-name <name>]

# Style browsing
oma slide styles list
oma slide styles preview <slug>
oma slide styles get <slug> [--refresh]

# Visual editor
oma slide edit --dir "$DECK_DIR" [--port <n>]

Env-var overrides: OMA_CHROME_PATH (Chrome binary for validate/export), OMA_YTDLP (yt-dlp binary), OMA_HOME (canonical asset root).

Resource scope

Scope	Resource target
CODEBASE	.agents/results/slides/<session-id>/: slide-NN.html, meta.json, assets/
LOCAL_FS	resources/style-presets.md, selection-index.json, fixed-stage.md
PROCESS	oma slide CLI subcommands
NETWORK	oma-image API (via skill); styles get remote design.md (untrusted data)
NETWORK	Canva Remote MCP (https://mcp.canva.com/mcp) — optional, OAuth-gated
LOCAL_FS	MCP config files — project: .agents/mcp.json, .agents/mcp_config.json (agy), .mcp.json (Claude), .gemini/settings.json (Gemini Extension); global: ~/.gemini/antigravity-cli/mcp_config.json (agy global)

Preconditions

• oma slide doctor passes (Chrome + puppeteer-core required; yt-dlp / pptxgenjs optional) for validate/export.
• Working directory is writable.
• For image generation: oma-image skill is reachable (or placeholder path accepted).
• Network for font CDNs: validate/export fetch fonts from allowlisted CDNs (fonts.googleapis.com, fonts.gstatic.com, fonts.bunny.net, use.typekit.net, cdn.jsdelivr.net — see cli/commands/slide/font-hosts.ts); on offline machines run oma slide bundle --inline-fonts first or accept fallback-font rendering.

Effects and side effects

• Writes slide-NN.html and meta.json into .agents/results/slides/<session-id>/.
• Writes generated images to ./assets/ via oma-image.
• Calls oma slide CLI which reads those files for validation/bundling/export.
• Fetches remote design.md files (cached; treated as untrusted style data).

Guardrails

1. Skill authors HTML; CLI does everything else. Never generate HTML from CLI code.
2. Local assets only. No remote URLs in slide <img src> or <video src> — only ./assets/<file>.
3. CJK → Pretendard. Any slide with Korean/Japanese/Chinese text must include Pretendard.
4. prefers-reduced-motion required. Wrap all CSS animations in @media (prefers-reduced-motion: no-preference).
5. Visible focus states required on nav controls (.deck-nav button:focus-visible).
6. data-om-validate on every slide. The validator contract must be present for the gate to work.
7. Remote design.md = untrusted data. Log what was fetched; sanitize; fall back on error.
8. Max 3 auto-fix iterations. Surface findings to the user instead of looping indefinitely.
9. Video warning on bundle. Warn when ./assets/ contains video: bundle is not fully self-contained. Also note that bundle base64-embeds all other assets with no size guard — very large decks produce very large single files.
10. PPTX is experimental. Label PPTX exports as experimental in all user-facing output.
11. oma-search is NOT a runtime dependency. It was used to study reference repos only.
12. Editor binds 127.0.0.1 only. Never expose the bbox editor server on a non-loopback interface.
13. Canva MCP = optional. Never error if Canva MCP is unavailable; offer auto-provisioning, then degrade to local exports if declined.
14. Canva auth probe first. Before any Canva operation, call list_designs to verify auth. On failure, notify user and skip.
15. Canva design URL in delivery. When Canva export succeeds, include the Canva design URL in the delivery summary.
16. Canva auto-provision = user-approved only. Never write MCP config without explicit user consent. See resources/canva-integration.md §Auto-Provisioning.

CLI ⇄ Skill Boundary

Principle: skill = judgment/creation/interaction (LLM). CLI = determinism/reproducible/testable.

Responsibility	Skill (this agent)	CLI (oma slide)
Intent, clarifying questions	YES	—
Content and outline design	YES	—
Authoring slide HTML/CSS/JS	YES (core)	—
Aesthetic / style choice	YES	—
Fetch a style file	—	YES styles get
Image generation	YES → oma-image	—
User image evaluation (multimodal)	YES	—
Canva MCP operations (probe/upload/create/export)	YES (all Canva tool calls)	—
Video download	—	YES fetch-video
Workspace scaffold	—	YES new
Render + geometric validation	—	YES validate (puppeteer-core)
Fixing validation failures	YES (rewrite HTML)	—
Bundle / viewer / pdf / png / pptx	—	YES
Dependency probe	—	YES doctor

References

Follow resources/generation-protocol.md phase by phase. Consult resources/design-doctrine.md for aesthetic guidelines before writing any slide HTML. Read resources/fixed-stage.md for stage rules, px-authoring conventions, and embed instructions. Use resources/style-presets.md (12 vendored) and resources/selection-index.json (34 bold templates) for style selection. Use resources/animation-patterns.md for effect-to-feeling pairing. Before delivery, run resources/checklist.md. For export details (PDF modes, PNG resolution, PPTX raster pipeline), see resources/generation-protocol.md §Phase 6 — Bundle and Export. For Canva export/import pipeline, see resources/canva-integration.md. For bbox visual editor usage, see resources/generation-protocol.md §Phase 5c — Visual Edit. For error recovery, see §Failure and recovery above.

Vendor-specific execution protocols are injected automatically by oma agent:spawn. Source files live under ../_shared/runtime/execution-protocols/{vendor}.md.

• Stage rules + embed instructions: resources/fixed-stage.md
• Generation lifecycle (Phase 0–6): resources/generation-protocol.md
• Anti-"AI slop" aesthetics + CJK rules: resources/design-doctrine.md
• 12 vendored style presets (MIT): resources/style-presets.md
• 34 bold template metadata + source links: resources/selection-index.json
• Animation effect-to-feeling guide: resources/animation-patterns.md
• Export pipeline details: resources/generation-protocol.md §Phase 6 — Bundle and Export
• Visual editor usage: resources/generation-protocol.md §Phase 5c — Visual Edit
• Pre-delivery gate: resources/checklist.md
• Context loading: ../_shared/core/context-loading.md
• Context budget: ../_shared/core/context-budget.md
• Imagery delegation: ../oma-image/SKILL.md — oma-slide delegates all image generation here