@tycoworks/tycoslide 0.17.0 → 0.17.1

package/dist/agents/commands.js

@@ -4,7 +4,7 @@ import { loadThemeConfig } from "../index.js";
 import { extractTemplate, summarizeExtraction } from "./extract.js";
 import { ASSETS_DIR, ASSETS_FILE, MANIFEST_FILE, PACKAGE_JSON, SKILL_FILE, SKILL_TEMPLATE_FILE, SKILL_ZIP_EXT, TEMPLATE_FILE, THEME_CONFIG, THEME_PACKAGE_DIR, } from "./files.js";
 import { generateManifest } from "./manifest.js";
-import { loadAssetCatalog, renameSkill, skillPackageJson, zipDir } from "./skill.js";
+import { loadAssetCatalog, personalizeSkill, skillPackageJson, zipDir } from "./skill.js";
 /** The CLI's line for something written, with an optional note on what it holds. */
 function wrote(target, detail) {
     console.log(detail ? `WROTE ${target}  ${detail}` : `WROTE ${target}`);
@@ -27,7 +27,7 @@ export function registerAgentCommands(program, tool) {
         const skillName = basename(themePkg.name);
         let skillMd;
         try {
-            skillMd = renameSkill(readFileSync(skillMdPath, "utf-8"), skillName);
+            skillMd = personalizeSkill(readFileSync(skillMdPath, "utf-8"), skillName, themePkg.description);
         }
         catch (err) {
             throw new Error(`${skillMdPath}: ${err.message}`);

package/dist/agents/inventory.d.ts

@@ -52,8 +52,8 @@ export type InventoryShape = {
     rows?: number;
     cols?: number;
     /**
-     * The start of the shape's text, with `¶` between paragraphs and `↵` for line
-     * breaks: where a parameter template puts `\n`.
+     * The shape's text, with `¶` between paragraphs and `↵` for line breaks,
+     * either of which a parameter template writes as `\n`.
      */
     text: string;
 };

package/dist/agents/inventory.js

@@ -300,7 +300,6 @@ const SHAPE_ELEMENTS = new Set([
 const GROUP_SEPARATOR = "/";
 const PARAGRAPH_MARK = "¶";
 const LINE_BREAK_MARK = "↵";
-const TEXT_PREVIEW_CHARS = 80;
 const TEXT_BOX_ON = "1";
 /** A placeholder with no `type` is a body placeholder. */
 const DEFAULT_PLACEHOLDER_TYPE = "body";
@@ -327,14 +326,14 @@ async function readShapes(presentation, parts) {
             }
         }
     }
-    // Set fields only, in a fixed order, and the text cut to a preview.
+    // Set fields only, in a fixed order.
     return found.map(({ shape: { name, kind, frame, frameFrom, rows, cols, text } }) => ({
         name,
         kind,
         ...(frame && { frame }),
         ...(frameFrom && { frameFrom }),
         ...(rows !== undefined && { rows, cols }),
-        text: Array.from(text).slice(0, TEXT_PREVIEW_CHARS).join(""),
+        text,
     }));
 }
 function walkShapes(container, prefix) {
@@ -373,13 +372,17 @@ function shapeKind(el, table) {
             return ShapeKind.Other;
     }
 }
-/** The shape's text, `¶` between paragraphs and `↵` for line breaks, whitespace collapsed. */
+/**
+ * The shape's text, `¶` between paragraphs and `↵` for line breaks, whitespace
+ * collapsed. Runs join as PowerPoint shows them, with no space added between: a
+ * run is a stretch of one style, not a word.
+ */
 function shapeText(el) {
     const paragraphs = collectElements(el, Tag.PARAGRAPH).map((paragraph) => elementChildren(paragraph)
         .flatMap((child) => child.tagName === Tag.LINE_BREAK
-        ? [LINE_BREAK_MARK]
+        ? [` ${LINE_BREAK_MARK} `]
         : collectElements(child, Tag.TEXT).map((text) => text.textContent ?? ""))
-        .join(" ")
+        .join("")
         .split(/\s+/)
         .filter(Boolean)
         .join(" "));

package/dist/agents/skill.d.ts

@@ -18,12 +18,14 @@ export declare function loadAssetCatalog(themeDir: string): AssetCatalog;
  */
 export declare function packAssets(paths: string[], read: (rel: string) => Buffer): Promise<Buffer>;
 /**
- * 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.
+ * Make the skill template the theme's own: its frontmatter `name:` and its title
+ * heading become the theme's name, and the theme's `description`, when it has
+ * one, leads the skill's description, so an agent with several theme skills can
+ * tell them apart. The rest of the body is left byte-for-byte. Throws if there is
+ * no frontmatter, no `name:` line, or no folded description to lead — the caller
+ * names the file.
  */
-export declare function renameSkill(md: string, name: string): string;
+export declare function personalizeSkill(md: string, name: string, description?: 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 may carry scripts,

package/dist/agents/skill.js

@@ -47,19 +47,32 @@ export async function packAssets(paths, read) {
 }
 const FRONTMATTER = /^---\n([\s\S]*?)\n---/;
 const NAME_LINE = /^name:[ \t]*.*$/m;
+/** The folded `description: >` opener; the description's lines follow it, indented. */
+const FOLDED_DESCRIPTION_LINE = /^description:[ \t]*>[ \t]*$/m;
+const DESCRIPTION_INDENT = "  ";
+const TITLE_HEADING = /^# .*$/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.
+ * Make the skill template the theme's own: its frontmatter `name:` and its title
+ * heading become the theme's name, and the theme's `description`, when it has
+ * one, leads the skill's description, so an agent with several theme skills can
+ * tell them apart. The rest of the body is left byte-for-byte. Throws if there is
+ * no frontmatter, no `name:` line, or no folded description to lead — the caller
+ * names the file.
  */
-export function renameSkill(md, name) {
+export function personalizeSkill(md, name, description) {
     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}`));
+    let frontmatter = block[0].replace(NAME_LINE, `name: ${name}`);
+    if (description) {
+        if (!FOLDED_DESCRIPTION_LINE.test(frontmatter)) {
+            throw new Error('SKILL.md frontmatter has no folded "description: >" to lead');
+        }
+        frontmatter = frontmatter.replace(FOLDED_DESCRIPTION_LINE, (line) => `${line}\n${DESCRIPTION_INDENT}${description}`);
+    }
+    return frontmatter + md.slice(block[0].length).replace(TITLE_HEADING, `# ${name}`);
 }
 /**
  * Files a packaged skill needs beyond the theme's own declarations. Only the

package/dist/markdown/slideParser.js

@@ -136,7 +136,7 @@ function buildSlide(index, fmString, rawContent) {
 export class FrontmatterParseError extends Error {
     constructor(slideIndex, yamlSource, cause) {
         const preview = yamlSource.length > 80 ? `${yamlSource.slice(0, 80)}...` : yamlSource;
-        super(`Invalid YAML in slide ${slideIndex} frontmatter:\n${preview}`);
+        super(`Slide ${slideIndex + 1}: invalid YAML in frontmatter:\n${preview}`);
         this.name = "FrontmatterParseError";
         this.cause = cause;
     }

package/docs/markdown.md

@@ -2,7 +2,7 @@
 
 This document covers the detailed syntax for writing slide content in tycoslide deck files.
 
-> **Every layout, parameter, and slot name in the examples below is a placeholder.** Your theme's real names live in `theme.json` — read it first, and never assume a name shown here (`Body`, `TwoColumn`, `hero`, `::left::`, etc.) exists in your theme.
+> **Every layout, parameter, and slot name in the examples below is a placeholder.** Your theme's real names live in its `theme.json`, and in `manifest.json` when the theme is packaged as a skill — read it first, and never assume a name shown here (`Body`, `TwoColumn`, `hero`, `::left::`, etc.) exists in your theme.
 
 ---
 
@@ -216,7 +216,7 @@ The theme owns all styling. These directives are rejected at build time:
 Each parameter or slot in the layout definition may declare:
 - **`accepts`** (slots, required) -- an array of `text`, `table`, `image`.
 - **`required: true`** -- the slide has no usable default and the build fails if the parameter/slot has no value.
-- **optional (the default)** -- a parameter or slot you leave unfilled is dropped from the slide (its shape is removed), so a layout with numbered slots (e.g. up to six sections, up to four stats) renders only the ones you fill.
+- **optional (the default)** -- a parameter or slot you leave unfilled is dropped from the slide (its shape is removed), so a layout with numbered slots (e.g. up to six sections, up to four stats) renders only the ones you fill. A shape the theme doesn't map, such as a card drawn behind a stat, stays, so an unfilled one can leave an empty card.
 
 Each layout also declares a `slideNumber` pointing at the physical slide in the theme's template -- unique per layout (one layout maps to one physical slide).
 
@@ -268,7 +268,7 @@ Common errors and fixes:
 
 | Error | Fix |
 |-------|-----|
-| `unknown layout "xyz"` | Check layout names in `theme.json` |
+| `unknown layout "xyz"` | Check layout names in `theme.json` (or `manifest.json`) |
 | A parameter or slot didn't fill | Use the key names the layout declares -- parameters in frontmatter, slots as body regions |
 | YAML parse error | Fix the YAML syntax in the slide's frontmatter |
 | `image "…" not found at …` | Check the path; it is relative to the deck file |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Create editable PowerPoint slides from markdown, using your existing .pptx templates.",
   "type": "module",
   "main": "dist/index.js",

package/theme-package/SKILL.template.md

@@ -39,7 +39,7 @@ This skill builds decks from a markdown deck file. The theme provides slide layo
 
 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 slot that accepts an image also shows its `fit`. A `cover` slot crops the image to fill the slot, a `contain` slot shows the whole image, and a `scale-down` slot shows the whole image without ever enlarging it.
 
-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.
+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. A card or panel drawn behind an unfilled one stays, so choose a layout with no more of them than you can fill.
 
 Study each layout's `slots` before writing any slides.
 
@@ -63,7 +63,7 @@ If your deck is in the theme folder, the file is already there, so skip the copy
 
 ## 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.
+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. The deck's `theme:` is the path from the deck to this folder's `theme.json`: `./theme.json` when the deck sits in this folder, and the full path to it when the deck is anywhere else.
 
 ---