@tycoworks/tycoslide 0.13.0 → 0.13.2

package/README.md

@@ -68,10 +68,11 @@ my-theme/
   assets/icons/
   theme.json
   package.json
-  skill.md          # generated by `tycoslide package`
+  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.zip        # generated by `tycoslide package` -- every declared asset, in one file
   <package-name>.zip  # uploadable Agent Skill bundle
 ```
 
@@ -81,6 +82,8 @@ my-theme/
 **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.zip`. `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.

package/SKILL.md

@@ -37,7 +37,7 @@ This skill builds on-brand decks from a markdown deck file. The theme provides s
 
 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`. Parameters carry a `type`, slots carry `accepts`, and either may be `required`.
 
-Pictures live in `assets.json`: every logo, illustration and icon the theme offers, keyed by category and name. **Search it, do not read it whole** -- an icon set alone can run to thousands of entries. Grep for the concept you want (`grep -i "arrow" assets.json`) and use the `$category.name` you find.
+Pictures live in `assets.json`: every logo, illustration and icon the theme offers, keyed by category and name. **Search it, do not read it whole** -- an icon set alone can run to thousands of entries. Grep for it and use the `$category.name` you find -- but **search for what the icon depicts, not what you mean by it**: a catalog is indexed by picture, so "freshness" finds nothing while `grep -i "clock" assets.json` and `grep -i "bolt"` find the icon you wanted.
 
 A layout's inputs split two ways (see [syntax.md](syntax.md) for details):
 - **parameters** -- one value on a frontmatter line. Fill by putting a value under the parameter's key in the slide frontmatter.
@@ -89,7 +89,7 @@ A deck file has three parts:
 
 ### Slide frontmatter
 
-Every slide must have a `layout:` key. All other frontmatter keys map 1:1 to the layout's **parameters**.
+Every slide must have a `layout:` key. All other frontmatter keys map 1:1 to the layout's **parameters**. A value containing a colon-then-space must be quoted -- `title: "The change: compute on the difference"` -- or YAML reads it as a second key and the build fails.
 
 ```yaml
 ---
@@ -141,7 +141,7 @@ Keep each slot's content to what its region comfortably holds. When content over
 - **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.
+- **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 invent layout or asset names** -- only use layouts from `manifest.json` and assets from `assets.json`
 - **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
 

package/dist/cli.js

@@ -2,18 +2,13 @@ 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 { buildDeck } from "./index.js";
-import { ASSETS_FILE, generateAssetCatalog, generateManifest } from "./manifest.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 DEFAULT_CONFIG = "theme.json";
-const MANIFEST_FILE = "manifest.json";
-// 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 sdkDir = dirname(fileURLToPath(import.meta.url));
-const skillMdPath = resolve(sdkDir, "..", "SKILL.md");
+const skillMdPath = resolve(sdkDir, "..", SKILL_FILE);
 const syntaxMdPath = resolve(sdkDir, "..", 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);
@@ -53,7 +48,7 @@ program
 program
     .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(`-c, --config <path>`, "path to theme config file", THEME_CONFIG)
     .action(async (opts) => {
     const config = loadThemeConfig(resolve(process.cwd(), opts.config));
     const themePkg = JSON.parse(readFileSync(resolve(process.cwd(), "package.json"), "utf-8"));

package/dist/files.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The file names of a packaged theme (Agent Skill), in one place so the layout
+ * of a skill reads on one screen. The engine's TEMPLATE_DIR is not here: it is
+ * an engine concern, and the engine stays product-generic.
+ */
+export declare const THEME_CONFIG = "theme.json";
+/** The layouts document: read whole, so it carries no open-ended list. */
+export declare const MANIFEST_FILE = "manifest.json";
+/** The searchable asset catalog, named by the manifest that points at it. */
+export declare const ASSETS_FILE = "assets.json";
+/**
+ * The one archive a packaged theme's declared assets ship inside. Entries are
+ * stored at theme-relative POSIX paths and never rewritten: packaging writes
+ * them, building expands them.
+ */
+export declare const ASSETS_ARCHIVE = "assets.zip";
+export declare const SKILL_FILE = "SKILL.md";
+export declare const SYNTAX_FILE = "syntax.md";
+/** The manifest a packaged skill installs from, authored rather than copied. */
+export declare const PACKAGE_JSON = "package.json";

package/dist/files.js

@@ -0,0 +1,23 @@
+/**
+ * The file names of a packaged theme (Agent Skill), in one place so the layout
+ * of a skill reads on one screen. The engine's TEMPLATE_DIR is not here: it is
+ * an engine concern, and the engine stays product-generic.
+ */
+export const THEME_CONFIG = "theme.json";
+/** The layouts document: read whole, so it carries no open-ended list. */
+export const MANIFEST_FILE = "manifest.json";
+/** The searchable asset catalog, named by the manifest that points at it. */
+export const ASSETS_FILE = "assets.json";
+/**
+ * The one archive a packaged theme's declared assets ship inside. Entries are
+ * stored at theme-relative POSIX paths and never rewritten: packaging writes
+ * them, building expands them.
+ */
+export const ASSETS_ARCHIVE = "assets.zip";
+// SKILL.md, uppercase: the Agent Skills format requires that exact filename at
+// the root of a skill folder, and a case-sensitive filesystem will not find any
+// other.
+export const SKILL_FILE = "SKILL.md";
+export const SYNTAX_FILE = "syntax.md";
+/** The manifest a packaged skill installs from, authored rather than copied. */
+export const PACKAGE_JSON = "package.json";

package/dist/index.d.ts

@@ -34,6 +34,8 @@ export declare function toEngineConfig(config: CompilerConfig): Config;
 export declare function buildDeck(deck: CompilerDeck, config: CompilerConfig, options?: GenerateOptions): Promise<void>;
 export type { Config, Deck, DeckStep, GenerateOptions, ImageFill, Layout, Slot, StyledParagraph, TableFill, TextFill, TextRun, ThemeConfig, } from "./engine/index.js";
 export { fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
-export { ASSETS_FILE, generateAssetCatalog, generateManifest } from "./manifest.js";
+export { ASSETS_ARCHIVE, ASSETS_FILE } from "./files.js";
+export { generateAssetCatalog, generateManifest } from "./manifest.js";
 export type { AssetCatalog, AssetEntry, CompilerBlock, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, EngineFill, MermaidConfig, MermaidVariant, ParsedDocument, RawSlide, } from "./markdown/index.js";
 export { AcceptType, compileMarkdownDeck, loadThemeConfig, parseThemeConfig } from "./markdown/index.js";
+export { expandAssets } from "./skillZip.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 import { generate, SlotType, } from "./engine/index.js";
 import { AcceptType, } from "./markdown/types.js";
+import { expandAssets } from "./skillZip.js";
 /**
  * A frontmatter parameter always fills one physical shape on the layout's own
  * slide, so it projects to a single base `Block` (`sourceSlide === baseSlide`)
@@ -112,12 +113,18 @@ export async function buildDeck(deck, config, options = {}) {
     if (deck.output === undefined) {
         throw new Error('buildDeck: deck.output is not set. Set it (e.g. "deck.pptx") before calling buildDeck.');
     }
+    // A packaged theme ships its assets as one archive, because hosts cap how many
+    // files a skill may contain. Expand it here rather than at compile: the catalog
+    // is what an author reads, and only filling needs the bytes.
+    await expandAssets(config.rootDir);
     const engineDeck = { theme: deck.theme, output: deck.output, steps: deck.steps };
     await generate(engineDeck, toEngineConfig(config), options);
 }
 // Engine — primitives-only public surface.
 export { fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.js";
+export { ASSETS_ARCHIVE, ASSETS_FILE } from "./files.js";
 // Authoring
-export { ASSETS_FILE, generateAssetCatalog, generateManifest } from "./manifest.js";
+export { generateAssetCatalog, generateManifest } from "./manifest.js";
 // Markdown / Compiler
 export { AcceptType, compileMarkdownDeck, loadThemeConfig, parseThemeConfig } from "./markdown/index.js";
+export { expandAssets } from "./skillZip.js";

package/dist/manifest.d.ts

@@ -1,6 +1,4 @@
 import type { CompilerConfig } from "./markdown/types.js";
-/** Filename of the searchable asset catalog, named by the manifest that points at it. */
-export declare const ASSETS_FILE = "assets.json";
 /** The layouts document: read whole, so it carries no open-ended list. */
 export declare function generateManifest(config: CompilerConfig): string;
 /** The catalog document: searched by name, never read whole. */

package/dist/manifest.js

@@ -1,3 +1,4 @@
+import { ASSETS_FILE } from "./files.js";
 import { templateKeys } from "./markdown/textTemplate.js";
 /**
  * Flatten a compiler parameter to the manifest entries advertised to AI authors.
@@ -18,8 +19,6 @@ function stripSlot(slot) {
         result.required = true;
     return result;
 }
-/** Filename of the searchable asset catalog, named by the manifest that points at it. */
-export const ASSETS_FILE = "assets.json";
 /** The layouts document: read whole, so it carries no open-ended list. */
 export function generateManifest(config) {
     const layouts = config.layouts.map((layout) => {

package/dist/skillZip.d.ts

@@ -1,6 +1,20 @@
 import type { CompilerThemeConfig } from "./markdown/types.js";
 /**
- * Rewrite the `name:` value in a skill.md's leading YAML frontmatter so the
+ * 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.
@@ -28,7 +42,7 @@ export declare function skillPackageJson(theme: Record<string, unknown>, engine:
  * 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
+ * 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.
  */

package/dist/skillZip.js

@@ -1,11 +1,63 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+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
+ * 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.
@@ -13,13 +65,11 @@ const NAME_LINE = /^name:[ \t]*.*$/m;
 export function renameSkill(md, name) {
     const block = md.match(FRONTMATTER);
     if (!block)
-        throw new Error("skill.md has no YAML frontmatter 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');
+        throw new Error('SKILL.md frontmatter has no "name:" line');
     return md.replace(block[0], block[0].replace(NAME_LINE, `name: ${name}`));
 }
-/** The manifest a packaged skill installs from, authored rather than copied. */
-const PACKAGE_JSON = "package.json";
 /**
  * Files a packaged skill needs beyond the theme's own declarations. Only the
  * lockfile: `package.json` is authored by `skillPackageJson` rather than taken
@@ -55,23 +105,35 @@ export function skillPackageJson(theme, engine) {
     return `${JSON.stringify(skill, null, 2)}\n`;
 }
 /**
- * Every path a packaged theme needs, relative to `rootDir` and POSIX-separated.
+ * 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: they resolve from node_modules, which `npm install` restores.
+ * 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 assets = Object.values(config.assets).flatMap((category) => Object.values(category).map((entry) => entry.path));
-    return [...SUPPORT_FILES, ...generated, `${TEMPLATE_DIR}/${config.template}`, ...assets];
+    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
+ * 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.
  */
@@ -81,19 +143,35 @@ export async function zipDir(rootDir, folderName, config, generated, packageJson
     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;
-    for (const rel of skillPaths(config, generated)) {
+    // `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)) {
-            if (optional.has(rel))
-                continue;
-            throw new Error(`Theme declares "${rel}", but no such file exists`);
-        }
-        folder.file(rel, readFileSync(abs));
+        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" });
+    return zip.generateAsync({ type: "nodebuffer", compression: "STORE" });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Create editable, on-brand PowerPoint slides from markdown.",
   "type": "module",
   "main": "dist/index.js",