@tycoworks/tycoslide 0.13.1 → 0.13.3

package/README.md

@@ -72,6 +72,7 @@ my-theme/
   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
 ```
 
@@ -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.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.

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";
-// 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.
-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,22 @@
+/**
+ * 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. Zip format, deliberately NOT named .zip: the
+ * upload host rejects nested .zip entries by extension while accepting .pptx,
+ * which is also a zip -- so the archive travels under a neutral name.
+ */
+export declare const ASSETS_ARCHIVE = "assets.dat";
+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,25 @@
+/**
+ * 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. Zip format, deliberately NOT named .zip: the
+ * upload host rejects nested .zip entries by extension while accepting .pptx,
+ * which is also a zip -- so the archive travels under a neutral name.
+ */
+export const ASSETS_ARCHIVE = "assets.dat";
+// 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,4 +1,18 @@
 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.

package/dist/skillZip.js

@@ -1,7 +1,59 @@
-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;
 /**
@@ -18,8 +70,6 @@ export function renameSkill(md, name) {
         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,17 +105,29 @@ 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
@@ -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.1",
+  "version": "0.13.3",
   "description": "Create editable, on-brand PowerPoint slides from markdown.",
   "type": "module",
   "main": "dist/index.js",