@tycoworks/tycoslide 0.8.0 → 0.10.0

package/README.md

@@ -1,14 +1,14 @@
 # tycoslide
 
-Let AI agents build slides from existing PowerPoint (`.pptx`) templates.
+Create editable, on-brand PowerPoint slides from markdown.
 
 > **Early release** — tycoslide is under active development.
 
 ## How it works
 
-1. **tycoslide wraps your PowerPoint file as an agent skill.**
-2. **Your agents use the skill to write slides in markdown.**
-3. **tycoslide builds a finished PowerPoint file from the markdown.**
+1. **tycoslide wraps existing PowerPoint files as reusable templates.**
+2. **You (or an agent) write slides in markdown.**
+3. **tycoslide builds new PowerPoint files.**
 
 ## Quick Start
 
@@ -42,16 +42,15 @@ title: Highlights
 Build:
 
 ```bash
-tycoslide build deck.md                   # → deck.pptx
+npx tycoslide build deck.md               # → deck.pptx
 ```
 
 ## CLI
 
 ```bash
-tycoslide build deck.md       # markdown → PPTX (theme resolved from deck frontmatter)
-tycoslide build deck.md --no-notes   # omit speaker notes from the output
-tycoslide plugin              # generate AI agent plugin package
-tycoslide manifest            # print layout + asset catalog to stdout
+npx tycoslide build deck.md       # markdown → PPTX (theme resolved from deck frontmatter)
+npx tycoslide build deck.md --no-notes   # omit speaker notes from the output
+npx tycoslide package             # generate the Agent Skill (skill.md, syntax.md, manifest.json at the theme root) + an uploadable <package-name>.zip
 ```
 
 ## Theme Structure
@@ -65,6 +64,10 @@ my-theme/
   assets/icons/
   theme.json
   package.json
+  skill.md          # generated by `tycoslide package`
+  syntax.md         # generated by `tycoslide package`
+  manifest.json     # generated by `tycoslide package`
+  <package-name>.zip  # uploadable Agent Skill bundle
 ```
 
 **Template** — the PPTX file with named shapes that tycoslide fills.

package/SKILL.md

@@ -1,17 +1,15 @@
 ---
 name: slides
 description: >
-  Use this skill any time the user wants to create branded slides, presentations,
-  pitch decks, or sales collateral as a .pptx. Trigger whenever the user mentions "deck," "slides,"
-  "presentation," "pitch," or .pptx output. Also trigger when the user says "build me a deck,"
-  "make slides about X," or "turn this into a presentation."
+  Build branded slides, presentations, pitch decks, or sales collateral as a .pptx.
+  Trigger on "deck," "slides," "presentation," "pitch," ".pptx," or "build me a deck."
 ---
 
 # slides
 
 ## Setup
 
-Before first use, install dependencies from the plugin root:
+Before first use, install dependencies from the theme root:
 
 ```bash
 npm install
@@ -48,7 +46,7 @@ A layout's inputs split two ways (see [syntax.md](syntax.md) for details):
 
 A single physical slide may back multiple layouts. When two manifest entries share the same `slideNumber`, they render into the same underlying PPTX shapes but declare their fill differently -- e.g. one layout exposing the fill as an `image` parameter and a sibling exposing it as a `mermaid` slot. Pick between them by naming the layout you want in frontmatter (`layout: Full bleed diagram` vs `layout: Full bleed image`); the declaration is unambiguous per layout, so the compiler always knows how to interpret the content you provide.
 
-Study each layout's `whenToUse` and `limit`s before writing any slides. These are your primary guide for matching content to layouts.
+Study each layout's `slots` and `limit`s before writing any slides.
 
 ---
 
@@ -131,7 +129,7 @@ The deck is written to your current working directory (not inside the skill).
 
 ### For Each Slide
 
-**Every slide communicates one idea.** If you're writing more than 5 bullets or 3 paragraphs, split into two slides.
+**Every slide communicates one idea.** If you're writing more than 5 bullets or 3 paragraphs, split into two slides. Put the takeaway in the headline, then support it.
 
 Check each layout's `limit` in the manifest for content density constraints. When content overflows, split across slides.
 
@@ -143,6 +141,7 @@ Check each layout's `limit` in the manifest for content density constraints. Whe
 - **Don't open with a body/content layout** -- use the Title layout for impact
 - **Don't skip section dividers** -- for decks over 5 slides, use Section title layouts to group sections
 - **Don't restyle the layout** -- the theme owns all design; you only fill slots
+- **Don't use an image that's wrong for the slot** -- a small slot wants a simple icon, not a dense illustration; if the build warns an image shrank to a small %, swap it for a simpler one
 - **Don't invent layout or asset names** -- only use what exists in the manifest
 - **Don't leave required parameters or slots empty** -- and don't leave a placeholder logo or dummy text in an image parameter you care about
 - **Don't mix dark and light** -- keep one variant across the deck

package/dist/cli.js

@@ -1,31 +1,21 @@
-import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { buildDeck } from "./index.js";
 import { generateManifest } from "./manifest.js";
-import { compileDeck, parseSlideDocument, RESERVED_KEY, } from "./markdown/index.js";
+import { compileDeck, loadThemeConfig, parseSlideDocument, RESERVED_KEY } from "./markdown/index.js";
+import { renameSkill, zipSkill } from "./skillZip.js";
 const DEFAULT_CONFIG = "theme.json";
-const SKILL_DIR = "skills/slides";
-const PLUGIN_DIR = ".claude-plugin";
-const PLUGIN_FILE = "plugin.json";
 const MANIFEST_FILE = "manifest.json";
-const SKILL_FILE = "SKILL.md";
+// The theme skill is written as lowercase skill.md (copied from tycoslide's own
+// SKILL.md), so the skill folder can live at the theme repo root.
+const SKILL_FILE = "skill.md";
 const SYNTAX_FILE = "syntax.md";
 const BUILD_COMMAND = "npx tycoslide build";
 const sdkDir = dirname(fileURLToPath(import.meta.url));
-const skillMdPath = resolve(sdkDir, "..", SKILL_FILE);
+const skillMdPath = resolve(sdkDir, "..", "SKILL.md");
 const syntaxMdPath = resolve(sdkDir, "..", SYNTAX_FILE);
-function loadConfig(absPath) {
-    let raw;
-    try {
-        raw = JSON.parse(readFileSync(absPath, "utf-8"));
-    }
-    catch {
-        throw new Error(`Config file not found or invalid JSON: ${absPath}`);
-    }
-    return { ...raw, rootDir: dirname(absPath) };
-}
 const pkg = JSON.parse(readFileSync(resolve(sdkDir, "..", "package.json"), "utf-8"));
 const program = new Command().name("tycoslide").description("PPTX template engine CLI").version(pkg.version);
 program
@@ -53,56 +43,46 @@ program
     if (!absConfigPath) {
         throw new Error(`${basename(deckPath)}: missing required "${RESERVED_KEY.THEME}" in global frontmatter`);
     }
-    const config = loadConfig(absConfigPath);
-    const deck = compileDeck(doc, config.layouts, config.rootDir, config.assets);
+    const config = loadThemeConfig(absConfigPath);
+    const deck = await compileDeck(doc, config);
     if (!deck.output)
         deck.output = basename(deckPath).replace(/\.md$/, ".pptx");
     await buildDeck(deck, config, { excludeNotes: !opts.notes });
 });
 program
-    .command("manifest")
-    .description("Generate manifest.json from theme config")
+    .command("package")
+    .description("Generate the Agent Skill (manifest.json, SKILL.md, syntax.md) for AI agents")
     .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
-    .option(`-o, --out <file>`, "write to file instead of stdout")
     .action(async (opts) => {
-    const config = loadConfig(resolve(process.cwd(), opts.config));
-    const json = generateManifest(config, { build: { command: BUILD_COMMAND } });
-    if (opts.out) {
-        writeFileSync(resolve(process.cwd(), opts.out), `${json}\n`);
-        console.log(`WROTE ${opts.out}`);
+    const config = loadThemeConfig(resolve(process.cwd(), opts.config));
+    const themePkg = JSON.parse(readFileSync(resolve(process.cwd(), "package.json"), "utf-8"));
+    if (!themePkg.name) {
+        throw new Error('Cannot name the skill: the theme\'s package.json has no "name" field.');
+    }
+    // basename drops any npm scope, e.g. "@acme/mz-slides" -> "mz-slides".
+    const skillName = basename(themePkg.name);
+    const manifestJson = `${generateManifest(config, { build: { command: BUILD_COMMAND } })}\n`;
+    writeFileSync(resolve(process.cwd(), MANIFEST_FILE), manifestJson);
+    console.log(`WROTE ${MANIFEST_FILE}`);
+    let skillMd;
+    try {
+        skillMd = renameSkill(readFileSync(skillMdPath, "utf-8"), skillName);
     }
-    else {
-        process.stdout.write(`${json}\n`);
+    catch (err) {
+        throw new Error(`${skillMdPath}: ${err.message}`);
     }
-});
-program
-    .command("plugin")
-    .description("Generate plugin package (plugin.json, manifest.json, SKILL.md, syntax.md) for AI agents")
-    .option(`-c, --config <path>`, "path to theme config file", DEFAULT_CONFIG)
-    .action(async (opts) => {
-    const config = loadConfig(resolve(process.cwd(), opts.config));
-    const cwd = process.cwd();
-    const pkg = JSON.parse(readFileSync(resolve(cwd, "package.json"), "utf-8"));
-    const pluginMeta = {
-        name: pkg.name,
-        version: pkg.version,
-        description: pkg.description ?? "",
-        skills: "./skills",
-    };
-    if (pkg.author)
-        pluginMeta.author = pkg.author;
-    const pluginDir = resolve(cwd, PLUGIN_DIR);
-    mkdirSync(pluginDir, { recursive: true });
-    writeFileSync(resolve(pluginDir, PLUGIN_FILE), `${JSON.stringify(pluginMeta, null, 2)}\n`);
-    console.log(`WROTE ${PLUGIN_DIR}/${PLUGIN_FILE}`);
-    const skillDir = resolve(cwd, SKILL_DIR);
-    mkdirSync(skillDir, { recursive: true });
-    const json = generateManifest(config, { build: { command: BUILD_COMMAND } });
-    writeFileSync(resolve(skillDir, MANIFEST_FILE), `${json}\n`);
-    console.log(`WROTE ${SKILL_DIR}/${MANIFEST_FILE}`);
-    copyFileSync(skillMdPath, resolve(skillDir, SKILL_FILE));
-    console.log(`WROTE ${SKILL_DIR}/${SKILL_FILE}`);
-    copyFileSync(syntaxMdPath, resolve(skillDir, SYNTAX_FILE));
-    console.log(`WROTE ${SKILL_DIR}/${SYNTAX_FILE}`);
+    writeFileSync(resolve(process.cwd(), SKILL_FILE), skillMd);
+    console.log(`WROTE ${SKILL_FILE}`);
+    const syntaxMd = readFileSync(syntaxMdPath, "utf-8");
+    writeFileSync(resolve(process.cwd(), SYNTAX_FILE), syntaxMd);
+    console.log(`WROTE ${SYNTAX_FILE}`);
+    const zipFile = `${skillName}.zip`;
+    const zipBuf = await zipSkill(skillName, [
+        { name: SKILL_FILE, content: skillMd },
+        { name: SYNTAX_FILE, content: syntaxMd },
+        { name: MANIFEST_FILE, content: manifestJson },
+    ]);
+    writeFileSync(resolve(process.cwd(), zipFile), zipBuf);
+    console.log(`WROTE ${zipFile}`);
 });
 await program.parseAsync(process.argv);

package/dist/engine/fillers/filler.d.ts

@@ -1,22 +1,30 @@
 /**
  * The `Filler` strategy registry — one plain-object strategy per SlotType, each
- * pairing a value discriminator with a slide-level fill. The record key IS the
- * slot type, so a strategy carries no redundant `type` field. `generate()`
- * consults `FILLERS[slot.type]` once per (slot, value): `matches` validates the
- * value shape, then `fill` applies it to the slide.
+ * pairing a value discriminator with the element-level modify callbacks that
+ * apply it. The record key IS the slot type, so a strategy carries no redundant
+ * `type` field.
  *
- * Element-level geometry lives in the `fillX` primitives; slide-level concerns
- * (media pre-swap for images, relation access for body hyperlinks, column
- * validation for tables) live in the strategy wrappers here.
+ * `callbacks(value, target)` returns the `(element, relation)` callbacks that
+ * fill one shape. They are deliberately shape-name-agnostic beyond the `target`
+ * so they can be applied two ways: `slide.modifyElement(name, callbacks)` for a
+ * shape already on the cloned base slide, or `slide.addElement(alias, n, name,
+ * callbacks)` for a shape transplanted from another slide — pptx-automizer runs
+ * an appended shape's callbacks against the imported element itself, so the same
+ * callbacks refill a transplant.
+ *
+ * Element-level geometry lives in the `fillX` primitives; cross-shape concerns
+ * (media pre-swap for images) live in the callbacks here.
  */
-import { type Slot, SlotType } from "../types.js";
-export type FillContext = {
-    layoutName: string;
+import { SlotType } from "../types.js";
+/** The shape a filler targets, plus its slot-level options (startAt for text). */
+export type FillTarget = {
+    shapeName: string;
+    startAt?: number;
 };
+/** A pptx-automizer element-modify callback: `(element, relation) => void`. */
+export type ShapeCallback = (element: any, relation: any) => unknown;
 export interface Filler<T> {
     matches(v: unknown): v is T;
-    /** Human name for the mismatch error — no magic string at the throw site. */
-    label: string;
-    fill(slide: any, slot: Slot, value: T, ctx: FillContext): void;
+    callbacks(value: T, target: FillTarget): ShapeCallback[];
 }
 export declare const FILLERS: Record<SlotType, Filler<any>>;

package/dist/engine/fillers/filler.js

@@ -1,13 +1,19 @@
 /**
  * The `Filler` strategy registry — one plain-object strategy per SlotType, each
- * pairing a value discriminator with a slide-level fill. The record key IS the
- * slot type, so a strategy carries no redundant `type` field. `generate()`
- * consults `FILLERS[slot.type]` once per (slot, value): `matches` validates the
- * value shape, then `fill` applies it to the slide.
+ * pairing a value discriminator with the element-level modify callbacks that
+ * apply it. The record key IS the slot type, so a strategy carries no redundant
+ * `type` field.
  *
- * Element-level geometry lives in the `fillX` primitives; slide-level concerns
- * (media pre-swap for images, relation access for body hyperlinks, column
- * validation for tables) live in the strategy wrappers here.
+ * `callbacks(value, target)` returns the `(element, relation)` callbacks that
+ * fill one shape. They are deliberately shape-name-agnostic beyond the `target`
+ * so they can be applied two ways: `slide.modifyElement(name, callbacks)` for a
+ * shape already on the cloned base slide, or `slide.addElement(alias, n, name,
+ * callbacks)` for a shape transplanted from another slide — pptx-automizer runs
+ * an appended shape's callbacks against the imported element itself, so the same
+ * callbacks refill a transplant.
+ *
+ * Element-level geometry lives in the `fillX` primitives; cross-shape concerns
+ * (media pre-swap for images) live in the callbacks here.
  */
 import { basename } from "node:path";
 import { ModifyImageHelper } from "pptx-automizer";
@@ -19,32 +25,23 @@ import { fillText, isTextFill } from "./text.js";
 export const FILLERS = {
     [SlotType.Template]: {
         matches: isTemplateFill,
-        label: "TemplateFill",
-        fill: (slide, slot, v) => slide.modifyElement(slot.shapeName, [(el) => fillTemplate(el, v, slot.shapeName)]),
+        callbacks: (v, t) => [(el) => fillTemplate(el, v, t.shapeName)],
     },
     [SlotType.Text]: {
         matches: isTextFill,
-        label: "TextFill",
-        fill: (slide, slot, v) => {
-            const startAt = slot.startAt ?? 0;
-            slide.modifyElement(slot.shapeName, [
-                (el, relation) => fillText(el, v, { startAt, relation, shapeName: slot.shapeName }),
-            ]);
-        },
+        callbacks: (v, t) => [
+            (el, relation) => fillText(el, v, { startAt: t.startAt ?? 0, relation, shapeName: t.shapeName }),
+        ],
     },
     [SlotType.Table]: {
         matches: isTableFill,
-        label: "TableFill",
-        fill: (slide, slot, v) => {
-            slide.modifyElement(slot.shapeName, [(el) => fillTable(el, v, slot.shapeName)]);
-        },
+        callbacks: (v, t) => [(el) => fillTable(el, v, t.shapeName)],
     },
     [SlotType.Image]: {
         matches: isImageFill,
-        label: "ImageFill",
-        fill: (slide, slot, v) => slide.modifyElement(slot.shapeName, [
+        callbacks: (v, t) => [
             ModifyImageHelper.setRelationTarget(basename(v.path)),
-            (el) => fillImage(el, v, slot.shapeName),
-        ]),
+            (el) => fillImage(el, v, t.shapeName),
+        ],
     },
 };

package/dist/engine/generate.d.ts

@@ -18,11 +18,15 @@
  *     file (registered by generate(), swapped by the ImageFiller) and adjusts
  *     geometry for the chosen fit. See fillers/image.ts.
  *
- * generate() loads the template, registers media, and for each DeckStep walks
- * the unified `layout.slots`. Each value in `step.content` is dispatched by the
- * slot's type via `FILLERS[slot.type]` (required, no default).
+ * generate() loads the template, registers media, and for each DeckStep clones
+ * the layout's base slide and calls `fillSlide`. Each value in `step.content`
+ * selects, by its own shape, the `Block` in the slot's `accepts` whose type it
+ * matches: a base-slide block fills in place; any other block is transplanted
+ * from its source slide onto the clone, then filled with the same callbacks.
+ *
+ * `generate()` is first below; its helpers follow (function declarations hoist).
  */
-import type { Config, Deck, Slot } from "./types.js";
+import type { Config, Deck, DeckStep, Layout } from "./types.js";
 /** Options for `generate` / `buildDeck`. */
 export type GenerateOptions = {
     /**
@@ -40,22 +44,24 @@ export type GenerateOptions = {
  *   1. Load the template; register it twice (as root and under an alias).
  *   2. Pre-register every image's media buffer with pptx-automizer, walking
  *      the unified `step.content` for ImageFill values.
- *   3. For each deck step, clone the layout's source slide, then within the
- *      addSlide callback walk `layout.slots` once and dispatch by slot.type
- *      via `FILLERS[slot.type]`.
+ *   3. For each deck step, clone the layout's base slide, then within the
+ *      addSlide callback call `fillSlide` to dispatch each content value to the
+ *      matching `Block` (fill in place, or transplant + fill).
  *   4. Write the output PPTX.
  */
 export declare function generate(deck: Deck, config: Config, options?: GenerateOptions): Promise<void>;
 /**
- * Validate that every required slot on a layout is supplied. Type/shape
- * validation happens in the compiler now — this is a thin required-only
- * checker kept for tests and defensive callers.
+ * Fill one cloned slide. Per slot the step supplies a value for: resolve WHICH
+ * shape realizes it (`resolveBlock`), build WHAT to write (`FILLERS[…].callbacks`),
+ * and place it WHERE/HOW (`applyBlock`). Every ambiguity fails fast, naming layout
+ * + slot.
  *
- * Exported for tests; not part of the public engine surface (index.ts).
+ * Exported for tests; `generate()` calls it inside the `addSlide` callback.
+ */
+export declare function fillSlide(slide: any, layout: Layout, step: DeckStep, sourceAlias: string): void;
+/**
+ * Reject a slot whose `accepts` lists two blocks of the same type — the
+ * value→block lookup would silently pick the first. Called once per layout at
+ * build start.
  */
-export declare function validateContentSlots(step: {
-    layout: string;
-    content?: Record<string, unknown>;
-}, tpl: {
-    slots: Slot[];
-}): void;
+export declare function assertSlotsWellFormed(layout: Layout): void;