@tycoworks/tycoslide 0.15.1 → 0.16.1

package/docs/theme.md

@@ -0,0 +1,144 @@
+# theme.json reference
+
+`theme.json` sits at the root of a theme package next to `template/`. It maps author-facing names onto shapes in the template `.pptx`: each layout names one slide, each parameter or slot names one shape on it. The template is never edited. At build time the engine clones the named slide, rewrites the named shapes, and removes any optional shape the author left unfilled. Every object is strict: an unknown key fails the load with `theme.json: invalid theme config` and `Unknown key(s): x. Valid keys: ...`.
+
+The one trap is `slideNumber`. It is the number in the file name `ppt/slides/slideN.xml`, not the slide's position in the deck. Reordering slides in PowerPoint changes positions but not file names. Always use the file number in `slideNumber` and `sourceSlide`.
+
+## `template`
+
+| Field | Meaning | Error when wrong |
+|---|---|---|
+| `template` | File name of the `.pptx`, resolved inside the theme's `template/` folder. Required. | `File not found: <path>` at build; `Theme declares "template/<name>", but no such file exists` at package. |
+
+## `layouts[]`
+
+One entry per slide the author may pick. Two layouts may not share a `slideNumber`; the load fails with `Layouts "A" and "B" share slideNumber N`. A slide with more than one arrangement becomes one layout with a multi-accept slot, never two layouts.
+
+| Field | Meaning | Error when wrong |
+|---|---|---|
+| `name` | The value authors write as `layout:` in slide frontmatter. Required, unique. | `unknown layout "xyz"` at deck compile, listing the valid names. |
+| `slideNumber` | File number of the slide to clone. Required. | Wrong slide is cloned; no error, wrong content. |
+| `description` | Neutral prose about the arrangement, shown to deck authors. Optional. | None. |
+| `variant` | `"light"` or `"dark"`: the surface the code panel sits on. Optional, required when `codeTheme` is a pair and the layout takes code. | `the theme's "codeTheme" is a { light, dark } pair, but this layout declares no "variant"`. |
+| `parameters` | Single-value text shapes filled from frontmatter. Required, may be `[]`. |  |
+| `slots` | Body regions filled from `::key::` markdown regions. Required, may be `[]`. |  |
+
+### `parameters[]`
+
+A parameter is a styled text shape whose text is rebuilt from a template string. The `{key}` placeholders are the frontmatter keys authors fill. There is no separate key field. A key may appear in only one parameter per layout: `key "title" (parameter "...") is declared twice`. Parameter shape names and slot keys share one namespace: `name "body" (slot) collides with another parameter or slot`.
+
+| Field | Meaning | Error when wrong |
+|---|---|---|
+| `shapeName` | Exact name of the text shape on the layout's slide. Required. | The build prints `Can't find element on slide N in source:` and leaves the placeholder text in place. |
+| `template` | The shape's full text with `{key}` placeholders; `\n` is a line break. Required. | `template has 2 lines but the shape has only 1 visual line(s)`; or `its styled sample text "..." does not fit the template` when styles inside a line do not match the placeholders. |
+| `required` | Whether the author must supply the keys. Optional, default `false`; an unfilled optional parameter has its shape removed. | `parameter "X" is marked required but its template has no keys to fill`; at compile, `requires parameter "X" (keys: ...); none provided`. |
+
+Keys match `[A-Za-z0-9_]+`. Write `{{` or `}}` for a literal brace. A shape with one line and one style is the safe case. A line that mixes styles must place a literal or style boundary between two placeholders, or the load fails with `variables "{a}" and "{b}" are adjacent with no separator`.
+
+### `slots[]`
+
+A slot is a body region. The author's markdown shape picks which accepted block fills it: prose or a code fence routes to `text`, a GFM table to `table`, an image reference or mermaid fence to `image`.
+
+| Field | Meaning | Error when wrong |
+|---|---|---|
+| `key` | The `::key::` region name. Required, unique within the layout. | `unknown slot "::x::" in layout "..."` at compile. |
+| `accepts` | The blocks this slot can become, at most one per `type`. Required. | `accepts two text blocks; each content type may appear once.` |
+| `frame` | `{x, y, cx, cy}` in EMU: the region a transplanted shape is positioned into. Required when any block's `sourceSlide` differs from `slideNumber`, otherwise optional. | `Layout "X" slot "y": a transplant block (sourceSlide ≠ N) requires a "frame"`. |
+| `required` | Whether the author must fill the region. Optional, default `false`; an unfilled optional slot has its shape removed. | `layout "X" requires slot "y"; none provided`. |
+
+### Blocks inside `accepts`
+
+Each block is discriminated by `type` and carries only its own option. A `bodyRows` on a text block or a `startAt` on a table block is an unknown key and fails the load.
+
+| Field | Meaning | Error when wrong |
+|---|---|---|
+| `type` | `"text"`, `"table"` or `"image"`. Required. | Schema error naming the invalid value. |
+| `sourceSlide` | File number of the slide carrying the specimen shape. Required. | Wrong shape cloned, or `Can't find element on slide N`. |
+| `shapeName` | Exact name of the specimen shape on `sourceSlide`. Required. | `Can't find element on slide N in source:` and the placeholder remains. |
+| `startAt` | Text only. Leave the first N specimen paragraphs untouched and rebuild from paragraph N. Optional, default 0. | `startAt 3 is past the last paragraph (shape has 2)`. |
+| `bodyRows` | Table only. `[start, end]`, 0-based inclusive: the rows that repeat for data. Required. Row 0 is always the header. Rows above `start` and below `end` render once, as fixed rows. | `bodyRows [s, e] is out of range; require 1 <= start <= end <= R-1 (row 0 is the header)`; `has no <a:tbl> element (is it actually a table?)`. |
+
+For an image block the shape must be a real picture: `is not a picture (missing <a:off>, <a:ext>, <p:blipFill>, or <p:cNvPr>)`.
+
+Transplants: a block whose `sourceSlide` differs from the layout's `slideNumber` is copied from that other slide onto the cloned slide, positioned into the slot's `frame`. The shape the slot replaces on the base slide is removed. This is how one slot accepts both text and a table when the styled table lives on a different slide, as the worked example's `Content` layout does with a table from slide 15. The frame is the observed `<a:xfrm>` of the shape being replaced, so a text block in the same slot fills in place and the table lands exactly where the text was. The transplanted shape is positioned and sized to the frame, so its own size on the source slide does not matter.
+
+## `fonts`
+
+Optional array of `@font-face` entries used only when rendering mermaid diagrams. PPTX text keeps the template's own fonts. Declare weights 400 and 700 for each family to avoid synthetic bold.
+
+| Field | Meaning | Error when wrong |
+|---|---|---|
+| `family` | CSS family name; must equal the mermaid variant's `fontFamily`. Required. | Warning `fontFamily "X" matches none of the declared theme fonts`, then a substitute font. |
+| `path` | A package specifier such as `@fontsource/inter/files/inter-latin-400-normal.woff2`, or a `./` or `/` file path. Required. | `could not resolve "path" from <rootDir>`; `file not found at ...`; `unsupported format ".otf"`. Supported: woff2, woff, ttf. |
+| `weight` | OpenType weight. Optional, default 400. | None. |
+
+## `codeTheme`
+
+Optional. A Shiki theme id such as `"github-light"`, or a pair `{ "light": "...", "dark": "..." }`. Required as soon as any deck uses a code fence: `deck contains a code fence but the theme declares no "codeTheme"`. A pair requires `variant` on every layout that takes code; each layout's `variant` picks the arm.
+
+## `mermaid`
+
+Optional record of named color variants. The record keys are free; every variant must carry all eleven fields. Colors are hex strings.
+
+| Key | Meaning |
+|---|---|
+| `primary` | Node fill color. |
+| `primaryContrast` | Text color on `primary` nodes. |
+| `text` | Default text, title and node label color. |
+| `line` | Edge and arrow color. |
+| `surface` | Subgraph, secondary node and edge-label background. |
+| `surfaceBorder` | Border color for nodes and subgraphs. |
+| `fontFamily` | CSS family name; match a `fonts` entry. |
+| `accents` | Array of colors assigned in order to `class` groups in a flowchart. |
+| `accentOpacity` | Percent, 0 to 100, applied to accent and subgraph fills. |
+| `accentTextColor` | Text color inside accent-classed nodes. |
+| `groupCornerRadius` | Subgraph corner radius in pixels; 0 for square. |
+
+A missing block fails with `theme has no "mermaid" block`.
+
+## `mermaidVariant`
+
+Optional string naming a key of `mermaid`. Required as soon as any deck has a mermaid fence: `declares no "mermaidVariant"`. A name that is not a key fails with `mermaid variant "x" not found in theme. Available variants: ...`. One variant per theme; pick the one matching most diagram layouts.
+
+## Minimal complete example
+
+```json
+{
+  "template": "composition.pptx",
+  "layouts": [
+    {
+      "name": "Composed",
+      "slideNumber": 1,
+      "description": "Title over one body region.",
+      "parameters": [
+        { "shapeName": "Title 1", "template": "{title}", "required": true }
+      ],
+      "slots": [
+        {
+          "key": "body",
+          "frame": { "x": 457200, "y": 1371600, "cx": 8229600, "cy": 2743200 },
+          "accepts": [
+            { "type": "text", "sourceSlide": 1, "shapeName": "Text 1" },
+            { "type": "table", "sourceSlide": 2, "shapeName": "Table 0", "bodyRows": [1, 1] },
+            { "type": "image", "sourceSlide": 3, "shapeName": "Image 0" }
+          ]
+        }
+      ]
+    },
+    {
+      "name": "TextOnly",
+      "slideNumber": 4,
+      "parameters": [],
+      "slots": [
+        { "key": "body", "accepts": [{ "type": "text", "sourceSlide": 4, "shapeName": "Text 1" }] }
+      ]
+    }
+  ]
+}
+```
+
+`TextOnly` has no `frame` because its only block lives on its own slide. `Composed` needs one because two blocks are transplants.
+
+## Full example
+
+The tycoworks theme is a complete 18-layout theme with a multi-accept slot, `variant`, a `codeTheme` pair, light and dark `mermaid` variants, and `fonts`: https://github.com/tycoworks/tycoworks-theme/blob/main/theme.json

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.15.1",
-  "description": "Create editable, on-brand PowerPoint slides from markdown, using your existing .pptx templates.",
+  "version": "0.16.1",
+  "description": "Create editable PowerPoint slides from markdown, using your existing .pptx templates.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "bin",
+    "docs",
     "theme-package"
   ],
   "engines": {
@@ -25,9 +26,9 @@
     "format": "biome format --write ."
   },
   "dependencies": {
-    "@xmldom/xmldom": "^0.9.10",
+    "@xmldom/xmldom": "^0.9.12",
     "commander": "^15.0.0",
-    "image-size": "^2.0.2",
+    "image-size": "^2.0.4",
     "jszip": "^3.10.1",
     "mermaid": "^11.16.1",
     "playwright-core": "^1.62.1",

package/theme-package/SKILL.template.md

@@ -0,0 +1,161 @@
+---
+name: slides
+description: >
+  Build branded slides, presentations, pitch decks, or sales collateral as a .pptx.
+  Trigger on "deck," "slides," "presentation," "pitch," ".pptx," or "build me a deck."
+compatibility: Needs Node 23.6+ and network access to npm on first use. LibreOffice (soffice) and poppler (pdftoppm) to preview slides. Chrome only if decks contain mermaid diagrams.
+---
+
+# slides
+
+## Setup
+
+Before first use, install dependencies from the theme root:
+
+```bash
+npm install
+unzip -nq assets.dat
+```
+
+This installs the tycoslide engine and its dependencies, and unpacks the theme's images so you can copy them into decks. You only need to do this once. If there is no `assets.dat`, skip the unzip. Run every `npx tycoslide` command from this folder too, since that is where the engine is installed and npx finds it nowhere else.
+
+
+## Overview
+
+This skill builds decks from a markdown deck file. The theme provides slide layouts that control design. Your job: pick the right layouts, fill them with content, and build. You never restyle the layout; the engine clones the real slides, so brand, layout, fonts, and chrome come for free.
+
+## Quick Reference
+
+| Task | Guide |
+|------|-------|
+| Discover layouts | Read `manifest.json` |
+| Find a logo, illustration or icon | Search `assets.json`, then copy it next to the deck (see [Images](#images)) |
+| Write a deck (structure, slots, assets) | See [Creating Slides](#creating-slides) below |
+| Fix build errors | See [QA](#qa-required) below |
+
+---
+
+## Layout Discovery
+
+Before writing anything, read `manifest.json`. It lists the theme's **layouts** -- for each: `name`, `description`, `parameters` (frontmatter inputs) and `slots` (body regions). A layout is identified by its `name`; every parameter and slot by its `key`. Slots carry `accepts`, and either may be `required`.
+
+A layout's inputs split two ways, parameters and slots; see [markdown.md](node_modules/@tycoworks/tycoslide/docs/markdown.md#parameters-and-slots) for how to fill each. Unfilled ones are dropped, so fill as many of a layout's numbered slots (sections, stats, columns) as you have content for.
+
+Study each layout's `slots` before writing any slides.
+
+### Images
+
+Images live in `assets.json`: every logo, illustration and icon the theme offers, keyed by category and name, each with a `path`, a `fit` and a `description`. **Search it, do not read it whole** -- an icon set alone can run to thousands of entries. **Search for what the icon depicts, not what you mean by it**: a catalog is indexed by image, so "freshness" finds nothing while `grep -i -B2 "clock" assets.json` and `grep -i -B2 "bolt" assets.json` find the icon you wanted, with its path and fit on the lines above.
+
+To use an image, copy it into your deck's folder at the same relative path, then write its `path` and `fit` in the image:
+
+```bash
+mkdir -p <deck dir>/assets && cp <theme dir>/assets/hub.png <deck dir>/assets/
+```
+
+```markdown
+![Central hub connecting three services](assets/hub.png "fit: scale-down")
+```
+
+If your deck is in the theme folder, the file is already there, so skip the copy. An image the user gives you also goes in the deck's folder; choose its fit by looking at it (`contain` unless it is full-bleed art that may crop). Write alt text for this slide, describing what the image shows here rather than repeating the catalog description.
+
+---
+
+## Creating Slides
+
+Write a deck file in markdown, as [markdown.md](node_modules/@tycoworks/tycoslide/docs/markdown.md) describes (see its [full example](node_modules/@tycoworks/tycoslide/docs/markdown.md#full-example)), and build it as its [Build](node_modules/@tycoworks/tycoslide/docs/markdown.md#build) section shows.
+
+---
+
+## Layout Selection
+
+**Don't create boring decks.** Repeating the same layout on every slide makes a forgettable presentation. Use variety and match content shape to the layout's slots.
+
+### Before Starting
+
+1. **Read the manifest thoroughly.** Each layout declares its `slots` (and the `accepts` types each one takes) -- the shape of what it can hold. Respect them.
+2. **Match content shape to the layout's slots.** A comparison fits a layout with two or three text columns; quantified proof fits one with stat slots; a customer voice fits a quote slot. The slots tell you what fits -- don't force content into the wrong shape.
+3. **Assign each idea to its best-fit layout** from the manifest. Some layouts come in more than one variant (e.g. a dark and a light version, shown in the name) — consider which suits the deck.
+
+### For Each Slide
+
+**Every slide communicates one idea.** Put the takeaway in the headline, then support it.
+
+Keep each slot's content to what its region comfortably holds. When content overflows, split it across slides.
+
+### Avoid (Common Mistakes)
+
+- **Don't repeat the same layout** -- vary layouts for visual rhythm
+- **Don't overstuff a slot** -- keep content to what its region comfortably holds; split across slides when there's too much
+- **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 you get a `shrunk to X%` warning, look at the rendered slide: if the image is now too small to make out, use a simpler one. A `leaves X% of the frame empty` warning is the opposite: the image is a different shape from the slot. Neither fails the build -- judge both from the rendered slide.
+- **Don't skip alt text** -- describe what a meaningful image shows and why it's there, not "image of". Leave it empty only for decoration, such as backgrounds and icons beside a heading.
+- **Don't crop what can't be cropped** -- copy the `fit` from `assets.json`. For your own images, never `fit: cover` a diagram, chart, screenshot or logo.
+- **Don't invent layout names or image paths** -- layouts come from `manifest.json`, and theme images from `assets.json`, copied next to the deck
+- **Don't leave required parameters or slots empty** -- and don't leave a placeholder logo or dummy text in an image slot you care about. If you don't have a suitable image, ask the user for one.
+
+---
+
+## QA (Required)
+
+**Assume the first build will fail. Your job is to fix it.**
+
+Your first draft almost never comes out clean. Approach QA as a debugging session, not a confirmation step. If you haven't run at least one build-fix cycle, you're not done.
+
+Build the deck again ([Build](node_modules/@tycoworks/tycoslide/docs/markdown.md#build)) and read the output carefully. Common errors and fixes are in [markdown.md](node_modules/@tycoworks/tycoslide/docs/markdown.md#build), and layout names are in `manifest.json`. Also:
+
+| Error | Fix |
+|-------|-----|
+| An image didn't swap / placeholder remains | Write a `::key::` region using the image slot's key, containing `![alt](path "fit: …")` with the path relative to the deck |
+| `image "…" not found at …` | For a theme image, copy it into the deck's folder at the path you wrote (search `assets.json`; did you unzip `assets.dat`?) |
+
+### Verification Loop
+
+1. Write the deck file &rarr; Build
+2. **Fix the error** -- the build stops at the first one, so expect several rounds
+3. Rebuild
+4. **If content overflows**: reduce content or split into two slides
+5. Repeat until the build exits cleanly
+
+**Do not declare success until you've completed at least one build-fix cycle.**
+
+### Visual Check
+
+After a clean build, render the `.pptx` to PNGs and inspect them:
+
+```bash
+soffice --headless --convert-to pdf --outdir . <deck>.pptx
+pdftoppm -png -r 96 <deck>.pdf <name>
+```
+
+LibreOffice substitutes any font it can't find, so line breaks in the images can differ slightly from PowerPoint's. Read each slide image and check for:
+
+- **Word wrapping** -- text that breaks mid-word or overflows its container
+- **Cramped text** -- content too dense for the slide area
+- **Leftover placeholders** -- dummy text ("Lorem ipsum", "Firstname Lastname") or a placeholder logo that should have been swapped
+- **Cut-off content** -- text or images clipped at slide edges
+
+If you spot issues, reduce content, switch layouts, or split into multiple slides. Rebuild and re-check.
+
+### Content Review (Use Subagents)
+
+**Use subagents for review** -- even for short decks. You've been staring at the content and will see what you expect, not what's there. Subagents have fresh eyes.
+
+After a successful build, spawn a subagent:
+
+```
+Review this deck. Assume there are issues -- find them.
+
+Check for:
+- Slides where content overflows its slot (more bullets/stats/rows than the region holds)
+- Same layout repeated multiple times with no variety
+- Content that doesn't match the layout's slots (check `accepts` in manifest.json)
+- Leftover placeholder logos or dummy text in the rendered images
+
+For each issue, suggest a specific fix.
+
+Read: /path/to/deck.md and the rendered PNGs in the working directory
+Also read: manifest.json (for layout documentation); search assets.json for images
+```
+
+If the subagent finds issues, fix them and rebuild.

package/dist/engine/rels.d.ts

@@ -1,18 +0,0 @@
-/**
- * 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

@@ -1,55 +0,0 @@
-/**
- * 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/manifest.d.ts

@@ -1,5 +0,0 @@
-import type { CompilerThemeConfig } from "./markdown/types.js";
-/** The layouts document: read whole, so it carries no open-ended list. */
-export declare function generateManifest(config: CompilerThemeConfig): string;
-/** The catalog document: searched by name, never read whole. */
-export declare function generateAssetCatalog(config: CompilerThemeConfig): string;

package/dist/skillZip.d.ts

@@ -1,49 +0,0 @@
-import type { CompilerThemeConfig } from "./markdown/types.js";
-/**
- * Pack `paths` (theme-relative, POSIX) into one archive, reading each through
- * `read`. Entries keep their declared paths, so expanding reproduces the layout
- * `theme.json` already refers to.
- */
-export declare function packAssets(paths: string[], read: (rel: string) => Buffer): Promise<Buffer>;
-/**
- * Expand a packaged theme's archive into its directory, so the files the catalog
- * names are on disk before anything fills with them. Idempotent per file; loose
- * files win, so a stale archive never overwrites a theme's real assets; the
- * archive itself stays put. A theme with no archive -- every theme under
- * development -- returns immediately.
- */
-export declare function expandAssets(rootDir: string): Promise<void>;
-/**
- * Rewrite the `name:` value in a SKILL.md's leading YAML frontmatter so the
- * packaged skill is named after the consuming theme, not the source template.
- * Only the leading `---`…`---` block is touched; the body is left byte-for-byte.
- * Throws if there is no frontmatter or no `name:` line — the caller names the file.
- */
-export declare function renameSkill(md: string, name: string): string;
-/**
- * The `package.json` a packaged skill installs from — deliberately NOT the theme's
- * own. A theme repo's manifest is a development document: it carries the script
- * that regenerates the skill, and lists the engine as a devDependency because the
- * repo builds with it rather than shipping it.
- *
- * Copying that verbatim breaks the consumer twice. The build script runs as a
- * postinstall inside their container, so anything it touches that is read-only
- * fails their whole `npm install`. And under `--omit=dev` the engine is never
- * installed, so neither the postinstall nor `npx tycoslide build` can find it.
- *
- * What ships instead declares only what the skill needs to RUN: the theme's own
- * dependencies plus the engine, as runtime dependencies, and no scripts at all.
- */
-export declare function skillPackageJson(theme: Record<string, unknown>, engine: {
-    name: string;
-    version: string;
-}): string;
-/**
- * Zip a theme into an uploadable Agent Skill archive whose entries all live
- * under a single root folder (e.g. `acme-slides/theme.json`), matching Anthropic's
- * custom-skill format. `generated` names the files the caller just wrote (the
- * config, manifest, SKILL.md, syntax.md); `packageJson` is the authored manifest
- * from `skillPackageJson`. Optional support files are skipped when absent;
- * anything the config declares but that is missing is an error.
- */
-export declare function zipDir(rootDir: string, folderName: string, config: CompilerThemeConfig, generated: string[], packageJson: string): Promise<Buffer>;

package/dist/skillZip.js

@@ -1,177 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import JSZip from "jszip";
-import { TEMPLATE_DIR } from "./engine/index.js";
-import { ASSETS_ARCHIVE, PACKAGE_JSON } from "./files.js";
-/** Entries are stored, not deflated: assets are already-compressed images. */
-const NO_COMPRESSION = { type: "nodebuffer", compression: "STORE" };
-/**
- * Pack `paths` (theme-relative, POSIX) into one archive, reading each through
- * `read`. Entries keep their declared paths, so expanding reproduces the layout
- * `theme.json` already refers to.
- */
-export async function packAssets(paths, read) {
-    const archive = new JSZip();
-    for (const rel of paths)
-        archive.file(rel, read(rel));
-    return archive.generateAsync(NO_COMPRESSION);
-}
-/**
- * Expand a packaged theme's archive into its directory, so the files the catalog
- * names are on disk before anything fills with them. Idempotent per file; loose
- * files win, so a stale archive never overwrites a theme's real assets; the
- * archive itself stays put. A theme with no archive -- every theme under
- * development -- returns immediately.
- */
-export async function expandAssets(rootDir) {
-    // An empty rootDir is a supported value elsewhere ("resolve nothing"), and it
-    // would expand into the process working directory. Refuse rather than guess.
-    if (!rootDir)
-        return;
-    const archivePath = join(rootDir, ASSETS_ARCHIVE);
-    if (!existsSync(archivePath))
-        return;
-    const archive = await JSZip.loadAsync(readFileSync(archivePath));
-    for (const [rel, entry] of Object.entries(archive.files)) {
-        if (entry.dir)
-            continue;
-        // JSZip collapses `..` and a leading `/` on load, but a backslash survives
-        // verbatim and traverses on Windows. We wrote this archive, so an entry that
-        // is not a plain theme-relative path means it was tampered with.
-        if (rel.includes("\\")) {
-            throw new Error(`${ASSETS_ARCHIVE} entry "${rel}" is not a theme-relative path`);
-        }
-        const abs = join(rootDir, ...rel.split("/"));
-        if (existsSync(abs))
-            continue;
-        mkdirSync(dirname(abs), { recursive: true });
-        // Write-then-rename. A plain write is not atomic: a build killed partway
-        // through 2,000 icons leaves a truncated file that `existsSync` then skips
-        // forever. Rename is atomic within a filesystem, so a reader sees a whole
-        // file or none, which also makes two concurrent builds in one directory safe.
-        const partial = `${abs}.${process.pid}.tmp`;
-        writeFileSync(partial, await entry.async("nodebuffer"));
-        renameSync(partial, abs);
-    }
-}
-const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
-const NAME_LINE = /^name:[ \t]*.*$/m;
-/**
- * Rewrite the `name:` value in a SKILL.md's leading YAML frontmatter so the
- * packaged skill is named after the consuming theme, not the source template.
- * Only the leading `---`…`---` block is touched; the body is left byte-for-byte.
- * Throws if there is no frontmatter or no `name:` line — the caller names the file.
- */
-export function renameSkill(md, name) {
-    const block = md.match(FRONTMATTER);
-    if (!block)
-        throw new Error("SKILL.md has no YAML frontmatter block");
-    if (!NAME_LINE.test(block[1]))
-        throw new Error('SKILL.md frontmatter has no "name:" line');
-    return md.replace(block[0], block[0].replace(NAME_LINE, `name: ${name}`));
-}
-/**
- * Files a packaged skill needs beyond the theme's own declarations. Only the
- * lockfile: `package.json` is authored by `skillPackageJson` rather than taken
- * from the theme directory.
- */
-const SUPPORT_FILES = ["package-lock.json"];
-/**
- * The `package.json` a packaged skill installs from — deliberately NOT the theme's
- * own. A theme repo's manifest is a development document: it carries the script
- * that regenerates the skill, and lists the engine as a devDependency because the
- * repo builds with it rather than shipping it.
- *
- * Copying that verbatim breaks the consumer twice. The build script runs as a
- * postinstall inside their container, so anything it touches that is read-only
- * fails their whole `npm install`. And under `--omit=dev` the engine is never
- * installed, so neither the postinstall nor `npx tycoslide build` can find it.
- *
- * What ships instead declares only what the skill needs to RUN: the theme's own
- * dependencies plus the engine, as runtime dependencies, and no scripts at all.
- */
-export function skillPackageJson(theme, engine) {
-    const dependencies = {
-        ...(theme.dependencies ?? {}),
-        [engine.name]: `^${engine.version}`,
-    };
-    const skill = {
-        name: theme.name,
-        version: theme.version,
-        description: theme.description,
-        private: true,
-        dependencies: Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b))),
-    };
-    return `${JSON.stringify(skill, null, 2)}\n`;
-}
-/**
- * Every path a packaged theme needs, relative to `rootDir` and POSIX-separated,
- * split by how it ships.
- *
- * Derived from the theme config rather than filtered out of a directory walk:
- * the config already declares its template and its whole asset catalog, so an
- * allowlist stays correct no matter what else sits in the working directory --
- * built decks, PDFs, slide PNGs, scratch files. Font paths are deliberately
- * absent when they name a package -- those resolve from node_modules, which
- * `npm install` restores -- but a `./`- or `/`-prefixed font path is a file the
- * theme owns, and mermaid reads it during COMPILE, before any archive is
- * expanded. Those ship plain.
- *
- * `archived` is the asset catalog, which collapses to one archive because hosts
- * cap how many FILES a skill may contain. `plain` is everything read before or
- * without an expansion, including the catalog itself.
- */
-function skillPaths(config, generated) {
-    const archived = Object.values(config.assets).flatMap((category) => Object.values(category).map((entry) => entry.path));
-    const localFonts = (config.fonts ?? []).map((f) => f.path).filter((p) => p.startsWith(".") || p.startsWith("/"));
-    return {
-        plain: [...SUPPORT_FILES, ...generated, `${TEMPLATE_DIR}/${config.template}`, ...localFonts],
-        archived,
-    };
-}
-/**
- * Zip a theme into an uploadable Agent Skill archive whose entries all live
- * under a single root folder (e.g. `acme-slides/theme.json`), matching Anthropic's
- * custom-skill format. `generated` names the files the caller just wrote (the
- * config, manifest, SKILL.md, syntax.md); `packageJson` is the authored manifest
- * from `skillPackageJson`. Optional support files are skipped when absent;
- * anything the config declares but that is missing is an error.
- */
-export async function zipDir(rootDir, folderName, config, generated, packageJson) {
-    const zip = new JSZip();
-    const folder = zip.folder(folderName);
-    if (!folder)
-        throw new Error(`Failed to create zip folder: ${folderName}`);
-    folder.file(PACKAGE_JSON, packageJson);
-    const { plain, archived } = skillPaths(config, generated);
-    const optional = new Set(SUPPORT_FILES);
-    let count = 1;
-    // `optional` is a plain-bucket concept (a lockfile a theme may not have). An
-    // asset the catalog declares is never optional, so the archived loop calls
-    // `required` and a missing one throws rather than silently vanishing.
-    const required = (rel) => {
-        const abs = join(rootDir, ...rel.split("/"));
-        if (existsSync(abs))
-            return readFileSync(abs);
-        throw new Error(`Theme declares "${rel}", but no such file exists`);
-    };
-    const read = (rel) => {
-        if (optional.has(rel) && !existsSync(join(rootDir, ...rel.split("/"))))
-            return null;
-        return required(rel);
-    };
-    for (const rel of plain) {
-        const content = read(rel);
-        if (content === null)
-            continue;
-        folder.file(rel, content);
-        count++;
-    }
-    if (archived.length > 0) {
-        folder.file(ASSETS_ARCHIVE, await packAssets(archived, required));
-        count++;
-    }
-    if (count === 0)
-        throw new Error(`No files to zip in directory: ${rootDir}`);
-    return zip.generateAsync({ type: "nodebuffer", compression: "STORE" });
-}