@tycoworks/tycoslide 0.13.3 → 0.14.1

package/README.md

@@ -1,26 +1,28 @@
 # tycoslide
 
-Create editable, on-brand PowerPoint slides from markdown.
+Create editable, on-brand PowerPoint slides from markdown, using your existing .pptx templates.
 
-> **Early release** — tycoslide is under active development.
+> **Early release.** tycoslide is under active development.
 
-## How it works
+## Getting started
 
-1. **tycoslide wraps existing PowerPoint files as reusable templates.**
-2. **You (or an agent) write slides in markdown.**
-3. **tycoslide builds new PowerPoint files.**
+1. **Create a tycoslide theme.** Install the [create-theme](skills/create-theme) skill (`npx skills add tycoworks/tycoslide`) and give an agent such as Claude Code or Codex your `.pptx`. You'll get back an npm package of mapped layouts, colors, and visual assets, like the [tycoworks-theme](https://github.com/tycoworks/tycoworks-theme).
+2. **Write slides in markdown.** Bullets, tables, images, speaker notes, syntax-highlighted code and mermaid diagrams are all supported. Every theme comes with an agent skill, so an agent can write the markdown for you.
+3. **Build.** `npx tycoslide build deck.md` compiles the markdown into an editable PowerPoint file.
 
-## Quick Start
+## Example
+
+[tycoworks-theme](https://github.com/tycoworks/tycoworks-theme) is a finished theme wrapping `template/tycoworks-demo.pptx`. Clone it and build its showcase deck, 21 slides covering all 18 layouts:
 
 ```bash
-npm install @tycoworks/tycoslide
+git clone https://github.com/tycoworks/tycoworks-theme && cd tycoworks-theme
+npm install
+npx tycoslide build showcase.md
 ```
 
-Mermaid diagrams need Chrome on the machine. See [Diagrams](#diagrams).
-
-Create `deck.md`:
+A deck file against that theme looks like this (full syntax in [syntax.md](theme-package/syntax.md)):
 
-```markdown
+````markdown
 ---
 theme: ./theme.json
 ---
@@ -33,64 +35,35 @@ jobTitle: Engineering
 ---
 
 ---
-layout: Body
-title: Highlights
+layout: Image right
+title: How requests flow
 ---
 
 ::body::
 
-- Revenue up 12% quarter-over-quarter
-- Three major product launches completed
-```
-
-Build:
+- Every request is checked before it reaches the model
+- Rejected requests never leave the gateway
 
-```bash
-npx tycoslide build deck.md               # → deck.pptx
-```
+::image::
 
-## CLI
-
-```bash
-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             # regenerate the skill files + zip the theme into a self-contained <package-name>.zip
+```mermaid
+flowchart TD
+  A[Client] --> B[Gateway] --> C[Model]
 ```
 
-## Theme Structure
+---
+layout: Code
+title: Calling the API
+---
 
-A theme packages a PPTX template, design assets, and a config file into one directory.
+::code::
 
+```python
+client = Client(api_key)
+deck = client.build("deck.md")
 ```
-my-theme/
-  template/corp-template.pptx
-  assets/logos/
-  assets/icons/
-  theme.json
-  package.json
-  SKILL.md          # generated by `tycoslide package`
-  syntax.md         # generated by `tycoslide package`
-  manifest.json     # generated by `tycoslide package` -- the theme's layouts
-  assets.json       # generated by `tycoslide package` -- the theme's picture catalog
-  assets.dat        # generated by `tycoslide package` -- every declared asset, in one file
-  <package-name>.zip  # uploadable Agent Skill bundle
-```
-
-**Template** — the PPTX file with named shapes that tycoslide fills.
-**Layout** — a slide pattern in the template (Title, Body, Quote, etc.).
-**Theme** — the directory that bundles a template, assets, and config.
-**Manifest** — the machine-readable list of layouts, for an AI agent to read.
-**Catalog** — the machine-readable list of assets, for an AI agent to search.
-
-A packaged skill ships its assets as one `assets.dat` archive. `tycoslide build` expands it automatically before filling; the catalog stays a plain file.
-
-## Diagrams
-
-Mermaid blocks are rendered with a headless Chrome. tycoslide does not download one.
-It uses a browser you already have, in this order:
+````
 
-1. `--browser-path <path>`
-2. A system Chrome install
-3. `npx playwright install chromium-headless-shell`
+## Requirements
 
-Decks without diagrams need no browser.
+Node 23.6 or later. Mermaid diagrams need Chrome on the machine; tycoslide finds an installed one, or run `npx playwright install chromium-headless-shell`.

package/dist/cli.js

@@ -2,14 +2,14 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
-import { ASSETS_FILE, MANIFEST_FILE, SKILL_FILE, SYNTAX_FILE, THEME_CONFIG } from "./files.js";
+import { ASSETS_FILE, MANIFEST_FILE, SKILL_FILE, SYNTAX_FILE, THEME_CONFIG, THEME_PACKAGE_DIR } from "./files.js";
 import { buildDeck } from "./index.js";
 import { generateAssetCatalog, generateManifest } from "./manifest.js";
 import { compileDeck, loadThemeConfig, parseSlideDocument, RESERVED_KEY } from "./markdown/index.js";
 import { renameSkill, skillPackageJson, zipDir } from "./skillZip.js";
 const sdkDir = dirname(fileURLToPath(import.meta.url));
-const skillMdPath = resolve(sdkDir, "..", SKILL_FILE);
-const syntaxMdPath = resolve(sdkDir, "..", SYNTAX_FILE);
+const skillMdPath = resolve(sdkDir, "..", THEME_PACKAGE_DIR, SKILL_FILE);
+const syntaxMdPath = resolve(sdkDir, "..", THEME_PACKAGE_DIR, SYNTAX_FILE);
 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

package/dist/engine/dom.js

@@ -346,9 +346,6 @@ export function rebuildParagraphs(shape, paragraphs, startIndex, relation, shape
             continue;
         const isBullet = para.bullet !== undefined;
         const inLevel = para.bullet?.level ?? 0;
-        // Skip fully-empty text (matches previous fillText behavior).
-        if (para.runs.length === 1 && !para.runs[0].text)
-            continue;
         // Bulleted content needs a bulleted specimen to model on. A plain-only shape
         // (e.g. a designer "description" line, buNone) accepts plain text only, so
         // bulleting it is an authoring error — fail fast rather than emit a run with

package/dist/engine/fillers/image.js

@@ -83,7 +83,9 @@ export function computeGeometry(frame, imgW, imgH, fit) {
     if (scaleRatio > 1) {
         warnings.push(`enlarged to ${Math.round(scaleRatio * 100)}% of native — will look soft; supply a larger image`);
     }
-    else if (scaleRatio < MIN_SCALE) {
+    else if (scaleRatio < MIN_SCALE && fit !== ImageFit.ScaleDown) {
+        // An icon's contract is "never enlarge"; landing small in an icon well is
+        // its normal use, so only image and background warn about shrinking.
         warnings.push(`shrunk to ${Math.round(scaleRatio * 100)}% of native — the slot is far smaller than the image`);
     }
     const shownW = imgW * scale;

package/dist/engine/rels.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Post-write sweep of relationships whose target part no longer exists.
+ *
+ * pptx-automizer's `cleanup` removes media parts that no shape embeds any more,
+ * and `removeExistingSlides` drops the root template's original slide parts.
+ * Neither touches the `.rels` files that named them, so a filled picture leaves
+ * two dead entries behind (the template's placeholder image and automizer's
+ * copy of it) and every removed template slide leaves an orphan rels file.
+ * PowerPoint treats a relationship to a missing part as a damaged package.
+ *
+ * Runs on the written file: cleanup is the last thing automizer does during
+ * `write()`, and it offers no hook after it.
+ */
+export type PruneResult = {
+    removedEntries: number;
+    removedParts: number;
+};
+export declare function pruneDanglingRels(outputPath: string): Promise<PruneResult>;

package/dist/engine/rels.js

@@ -0,0 +1,55 @@
+/**
+ * Post-write sweep of relationships whose target part no longer exists.
+ *
+ * pptx-automizer's `cleanup` removes media parts that no shape embeds any more,
+ * and `removeExistingSlides` drops the root template's original slide parts.
+ * Neither touches the `.rels` files that named them, so a filled picture leaves
+ * two dead entries behind (the template's placeholder image and automizer's
+ * copy of it) and every removed template slide leaves an orphan rels file.
+ * PowerPoint treats a relationship to a missing part as a damaged package.
+ *
+ * Runs on the written file: cleanup is the last thing automizer does during
+ * `write()`, and it offers no hook after it.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { posix } from "node:path";
+import { DOMParser, XMLSerializer } from "@xmldom/xmldom";
+import JSZip from "jszip";
+import { Attr, Tag } from "./dom.js";
+const SLIDE_RELS = /^ppt\/slides\/_rels\/(slide\d+\.xml)\.rels$/;
+const SLIDES_DIR = "ppt/slides";
+export async function pruneDanglingRels(outputPath) {
+    const zip = await JSZip.loadAsync(readFileSync(outputPath));
+    const parts = new Set(Object.keys(zip.files).filter((name) => !zip.files[name].dir));
+    const result = { removedEntries: 0, removedParts: 0 };
+    for (const relsPart of [...parts]) {
+        const match = SLIDE_RELS.exec(relsPart);
+        if (!match)
+            continue;
+        if (!parts.has(`${SLIDES_DIR}/${match[1]}`)) {
+            zip.remove(relsPart);
+            result.removedParts++;
+            continue;
+        }
+        const doc = new DOMParser().parseFromString(await zip.file(relsPart).async("string"), "text/xml");
+        const rels = doc.getElementsByTagName(Tag.RELATIONSHIP);
+        const dead = [];
+        for (let i = 0; i < rels.length; i++) {
+            const target = rels[i].getAttribute(Attr.TARGET);
+            if (!target || rels[i].getAttribute("TargetMode") === "External")
+                continue;
+            if (!parts.has(posix.normalize(posix.join(SLIDES_DIR, target))))
+                dead.push(rels[i]);
+        }
+        if (dead.length === 0)
+            continue;
+        for (const rel of dead)
+            rel.parentNode?.removeChild(rel);
+        result.removedEntries += dead.length;
+        zip.file(relsPart, new XMLSerializer().serializeToString(doc));
+    }
+    if (result.removedEntries > 0 || result.removedParts > 0) {
+        writeFileSync(outputPath, await zip.generateAsync({ type: "nodebuffer", compression: "DEFLATE" }));
+    }
+    return result;
+}

package/dist/files.d.ts

@@ -18,5 +18,6 @@ export declare const ASSETS_FILE = "assets.json";
 export declare const ASSETS_ARCHIVE = "assets.dat";
 export declare const SKILL_FILE = "SKILL.md";
 export declare const SYNTAX_FILE = "syntax.md";
+export declare const THEME_PACKAGE_DIR = "theme-package";
 /** The manifest a packaged skill installs from, authored rather than copied. */
 export declare const PACKAGE_JSON = "package.json";

package/dist/files.js

@@ -21,5 +21,8 @@ export const ASSETS_ARCHIVE = "assets.dat";
 // other.
 export const SKILL_FILE = "SKILL.md";
 export const SYNTAX_FILE = "syntax.md";
+// The folder holding the SKILL.md template copied into each packaged theme, kept
+// out of the repo root so skill installers do not mistake it for this repo's own skill.
+export const THEME_PACKAGE_DIR = "theme-package";
 /** The manifest a packaged skill installs from, authored rather than copied. */
 export const PACKAGE_JSON = "package.json";

package/dist/markdown/blocks/mermaid.js

@@ -143,6 +143,8 @@ function fontFaceCss(fonts) {
         .join("\n");
 }
 const LAUNCH_ARGS = { headless: true, args: ["--no-sandbox"] };
+/** Device pixels per CSS pixel when rasterising a diagram. Sized for print density. */
+const MERMAID_RASTER_SCALE = 6;
 /**
  * Find a browser rather than ship one. tycoslide never downloads Chromium: the
  * binary comes from a CDN rather than the npm registry, so bundling it breaks
@@ -245,7 +247,13 @@ ${fontFaceCss(fonts)}
         // Written inside the try so the finally always cleans it up, even if launch throws.
         writeFileSync(htmlPath, html);
         browser = await launchChromium(chromium, browserPath);
-        const page = await browser.newPage({ viewport: { width: 800, height: 600 }, deviceScaleFactor: 2 });
+        // Diagrams land in slide-sized frames, so they are rasterised well above CSS
+        // scale: a typical flowchart is ~270 CSS px wide against a slot wanting
+        // ~1400 px at print density. 2x left them visibly pixelated.
+        const page = await browser.newPage({
+            viewport: { width: 800, height: 600 },
+            deviceScaleFactor: MERMAID_RASTER_SCALE,
+        });
         await page.goto(pathToFileURL(htmlPath).href, { waitUntil: "load" });
         await page.waitForSelector(`#output[${RENDER_SIGNAL_ATTR}="${RenderSignal.Done}"]`, { timeout: 30000 });
         const error = await page.getAttribute("#output", RENDER_ERROR_ATTR);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.13.3",
-  "description": "Create editable, on-brand PowerPoint slides from markdown.",
+  "version": "0.14.1",
+  "description": "Create editable, on-brand PowerPoint slides from markdown, using your existing .pptx templates.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,12 +11,14 @@
   "files": [
     "dist",
     "bin",
-    "SKILL.md",
-    "syntax.md"
+    "theme-package"
   ],
+  "engines": {
+    "node": ">=23.6"
+  },
   "scripts": {
     "build": "tsc --build",
-    "test": "tsc --build && tsc -p tsconfig.test.json && node --test --experimental-transform-types test/**/*.test.ts",
+    "test": "tsc --build && tsc -p tsconfig.test.json && node --test test/**/*.test.ts",
     "typecheck": "tsc --build && tsc -p tsconfig.test.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",