@tycoworks/tycoslide 0.14.0 → 0.15.0

package/README.md

@@ -2,67 +2,32 @@
 
 Create editable, on-brand PowerPoint slides from markdown, using your existing .pptx templates.
 
-> **Early release.** tycoslide is under active development.
-
 ## Getting started
 
 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.
+2. **Write slides in markdown.** GitHub-flavored markdown is supported; see [Markdown support](#markdown-support) below. tycoslide themes also include an agent skill, so an agent can write the slides for you.
 3. **Build.** `npx tycoslide build deck.md` compiles the markdown into an editable PowerPoint file.
 
-## Example
+## See it working
 
-[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:
+[how-it-works.md](https://github.com/tycoworks/tycoworks-theme/blob/main/how-it-works.md) is a deck about tycoslide, written against the [tycoworks-theme](https://github.com/tycoworks/tycoworks-theme). Clone the theme and build it:
 
 ```bash
 git clone https://github.com/tycoworks/tycoworks-theme && cd tycoworks-theme
 npm install
-npx tycoslide build showcase.md
+npx tycoslide build how-it-works.md
 ```
 
-A deck file against that theme looks like this (full syntax in [syntax.md](theme-package/syntax.md)):
-
-````markdown
----
-theme: ./theme.json
----
-
----
-layout: Title
-title: Quarterly Review
-name: Jane Doe
-jobTitle: Engineering
----
-
----
-layout: Image right
-title: How requests flow
----
-
-::body::
-
-- Every request is checked before it reaches the model
-- Rejected requests never leave the gateway
+## Markdown support
 
-::image::
+- Paragraphs, bullets and numbered lists, with bold, italic and links
+- Tables
+- Code, with [Shiki](https://shiki.style) syntax highlighting
+- [Mermaid](https://mermaid.js.org) diagrams
+- Images, from the theme's asset catalog or a file path
+- Speaker notes
 
-```mermaid
-flowchart TD
-  A[Client] --> B[Gateway] --> C[Model]
-```
-
----
-layout: Code
-title: Calling the API
----
-
-::code::
-
-```python
-client = Client(api_key)
-deck = client.build("deck.md")
-```
-````
+Full syntax in [syntax.md](theme-package/syntax.md).
 
 ## Requirements
 

package/dist/cli.js

@@ -38,7 +38,7 @@ program
     if (!absConfigPath) {
         throw new Error(`${basename(deckPath)}: missing required "${RESERVED_KEY.THEME}" in global frontmatter`);
     }
-    const config = { ...loadThemeConfig(absConfigPath), browserPath: opts.browserPath };
+    const config = { ...loadThemeConfig(absConfigPath), browserPath: opts.browserPath, deckDir: dirname(absDeckPath) };
     const deck = await compileDeck(doc, config);
     // Always write the .pptx next to the input deck, named after it.
     const outName = basename(deckPath).replace(/\.md$/, ".pptx");

package/dist/engine/dom.js

@@ -346,14 +346,11 @@ 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
-        // no modelled style (which renders in the app default colour, e.g. black on
-        // a dark slide whose real text colour lives only in the specimen's rPr).
+        // no modelled style (which renders in the app default color, e.g. black on
+        // a dark slide whose real text color lives only in the specimen's rPr).
         if (isBullet && bullets.size === 0) {
             throw new Error(`Shape "${shapeName}": received bulleted content, but its specimen has no bulleted paragraph to model — this slot accepts plain text only.`);
         }

package/dist/engine/fillers/image.d.ts

@@ -17,7 +17,7 @@ declare const Placement: {
     readonly Crop: "crop";
     readonly Fit: "fit";
 };
-/** Either a symmetric `<a:srcRect>` crop (fill/cover) or a resized+re-centred frame (fit/contain). */
+/** Either a symmetric `<a:srcRect>` crop (fill/cover) or a resized+re-centerd frame (fit/contain). */
 type FitGeometry = {
     placement: typeof Placement.Crop;
     left: number;
@@ -36,7 +36,7 @@ export type GeometryResult = {
 /**
  * Size a picture shape from its `ImageFit` (via `computeGeometry`): either write
  * `<a:srcRect>` insets to fill-and-crop, or shrink the frame to the image's
- * aspect ratio and re-centre (fit/letterbox). Advisory warnings from the
+ * aspect ratio and re-center (fit/letterbox). Advisory warnings from the
  * geometry pass go to `console.warn`.
  *
  * `image.path` is assumed absolute — the compiler / caller resolves it before the

package/dist/engine/fillers/image.js

@@ -24,7 +24,7 @@ const MIN_SCALE = 0.2;
 /**
  * Size a picture shape from its `ImageFit` (via `computeGeometry`): either write
  * `<a:srcRect>` insets to fill-and-crop, or shrink the frame to the image's
- * aspect ratio and re-centre (fit/letterbox). Advisory warnings from the
+ * aspect ratio and re-center (fit/letterbox). Advisory warnings from the
  * geometry pass go to `console.warn`.
  *
  * `image.path` is assumed absolute — the compiler / caller resolves it before the
@@ -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/types.d.ts

@@ -89,7 +89,7 @@ export type TableFill = {
 /**
  * How a picture is scaled into its frame — the engine's image-sizing directive,
  * mirroring CSS `object-fit`. `contain`: fit the whole image, scale both ways,
- * letterbox. `cover`: fill the frame, centre-crop the overflow. `scale-down`:
+ * letterbox. `cover`: fill the frame, center-crop the overflow. `scale-down`:
  * like contain but never enlarge past native (a small image sits at native size).
  */
 export declare const ImageFit: {

package/dist/engine/types.js

@@ -22,7 +22,7 @@ export const SlotType = {
 /**
  * How a picture is scaled into its frame — the engine's image-sizing directive,
  * mirroring CSS `object-fit`. `contain`: fit the whole image, scale both ways,
- * letterbox. `cover`: fill the frame, centre-crop the overflow. `scale-down`:
+ * letterbox. `cover`: fill the frame, center-crop the overflow. `scale-down`:
  * like contain but never enlarge past native (a small image sits at native size).
  */
 export const ImageFit = {

package/dist/index.d.ts

@@ -20,9 +20,9 @@ export declare function toEngineConfig(config: CompilerConfig): Config;
  * and hands the deck to the engine's primitives-only `generate()`. The deck is
  * structurally equivalent to the engine's `Deck` once `output` is present, so no
  * cast is required. `buildDeck` does not itself validate `config` — a
- * programmatic caller assembling a `CompilerConfig` by hand should load it
- * through `loadThemeConfig` (or `parseThemeConfig`) first to get the same
- * fail-fast structural checks the CLI gets.
+ * programmatic caller assembling a `CompilerConfig` by hand should load the
+ * theme through `loadThemeConfig` (or `parseThemeConfig`) first to get the same
+ * fail-fast structural checks the CLI gets, then add the deck's `deckDir`.
  *
  * Fails fast if `deck.output` is missing: `generate()` requires it, and the CLI
  * populates it before calling `buildDeck`; a programmatic caller that forgot to
@@ -36,6 +36,6 @@ export type { Config, Deck, DeckStep, GenerateOptions, ImageFill, Layout, Slot,
 export { fillImage, fillTable, fillTemplate, fillText, generate, SlotType } from "./engine/index.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 type { AssetCatalog, AssetEntry, CompilerBlock, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, EngineFill, LoadedTheme, 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

@@ -98,9 +98,9 @@ export function toEngineConfig(config) {
  * and hands the deck to the engine's primitives-only `generate()`. The deck is
  * structurally equivalent to the engine's `Deck` once `output` is present, so no
  * cast is required. `buildDeck` does not itself validate `config` — a
- * programmatic caller assembling a `CompilerConfig` by hand should load it
- * through `loadThemeConfig` (or `parseThemeConfig`) first to get the same
- * fail-fast structural checks the CLI gets.
+ * programmatic caller assembling a `CompilerConfig` by hand should load the
+ * theme through `loadThemeConfig` (or `parseThemeConfig`) first to get the same
+ * fail-fast structural checks the CLI gets, then add the deck's `deckDir`.
  *
  * Fails fast if `deck.output` is missing: `generate()` requires it, and the CLI
  * populates it before calling `buildDeck`; a programmatic caller that forgot to

package/dist/manifest.d.ts

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

package/dist/markdown/blocks/mermaid.js

@@ -143,7 +143,7 @@ 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. */
+/** Device pixels per CSS pixel when rasterizing a diagram. Sized for print density. */
 const MERMAID_RASTER_SCALE = 6;
 /**
  * Find a browser rather than ship one. tycoslide never downloads Chromium: the
@@ -247,7 +247,7 @@ ${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);
-        // Diagrams land in slide-sized frames, so they are rasterised well above CSS
+        // Diagrams land in slide-sized frames, so they are rasterized 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({

package/dist/markdown/deckCompiler.js

@@ -245,11 +245,12 @@ export async function compileDeck(doc, config) {
     assertUniqueSlideNumbers(layouts);
     for (const layout of layouts)
         validateLayout(layout);
-    // Resolve a `$category.name` reference against the theme's curated asset
-    // catalog. Anchored ⇒ the whole ref is the reference or it is nothing; a found
-    // entry wraps through `toImageFill`, which maps the asset's declared type to
-    // its ImageFit.
-    const resolveAssetRef = (ref) => {
+    // A body image names a picture one of two ways, and both end as an absolute
+    // path plus a fit: `$category.name` looks the picture up in the theme's
+    // catalog (which carries its declared type), while anything else is a file
+    // path relative to the deck (typed `image`, since nothing declares it). Only
+    // the lookup differs; the wrapping is shared.
+    const fromCatalog = (ref) => {
         const match = ASSET_REF_RE.exec(ref);
         if (!match) {
             throw new Error(`Asset reference "${ref}" must be in the form $category.name (e.g. $logos.primary).`);
@@ -271,7 +272,15 @@ export async function compileDeck(doc, config) {
                     .join(", ");
             throw new Error(`Unknown asset reference "${ref}". Available: ${available}`);
         }
-        return toImageFill(resolveImagePath(rootDir, entry.path), entry.type);
+        return { path: resolveImagePath(rootDir, entry.path), type: entry.type };
+    };
+    const fromDeck = (ref) => ({
+        path: resolveImagePath(config.deckDir, ref),
+        type: AssetType.Image,
+    });
+    const resolveAssetRef = (ref) => {
+        const { path, type } = ref.startsWith("$") ? fromCatalog(ref) : fromDeck(ref);
+        return toImageFill(path, type);
     };
     // Slides compile in order: a slide's structural errors (unknown layout/key,
     // bad asset ref, accept-type mismatch) fire before its own content is rendered.

package/dist/markdown/index.d.ts

@@ -9,5 +9,5 @@ export { parseRegion } from "./mdast.js";
 export { loadThemeConfig, parseThemeConfig, ThemeConfigSchema } from "./schema/themeConfigSchema.js";
 export type { ParsedDocument, RawSlide } from "./slideParser.js";
 export { parseSlideDocument } from "./slideParser.js";
-export type { AssetCatalog, AssetEntry, CompilerBlock, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, EngineFill, } from "./types.js";
+export type { AssetCatalog, AssetEntry, CompilerBlock, CompilerConfig, CompilerDeck, CompilerDeckStep, CompilerLayout, CompilerParameter, CompilerSlot, CompilerThemeConfig, EngineFill, LoadedTheme, } from "./types.js";
 export { AcceptType, AssetType, RESERVED_KEY } from "./types.js";

package/dist/markdown/schema/themeConfigSchema.d.ts

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import { type CompilerConfig, type CompilerThemeConfig } from "../types.js";
+import { type CompilerThemeConfig, type LoadedTheme } from "../types.js";
 export declare const ThemeConfigSchema: z.ZodObject<{
     layouts: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -43,8 +43,8 @@ export declare const ThemeConfigSchema: z.ZodObject<{
     assets: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
         path: z.ZodString;
         type: z.ZodEnum<{
-            image: "image";
             icon: "icon";
+            image: "image";
             background: "background";
         }>;
         description: z.ZodString;
@@ -82,10 +82,10 @@ export declare const ThemeConfigSchema: z.ZodObject<{
  */
 export declare function parseThemeConfig(raw: unknown, sourcePath: string): CompilerThemeConfig;
 /**
- * Read, validate, and root a `theme.json` at `absPath` into a `CompilerConfig`.
+ * Read, validate, and root a `theme.json` at `absPath` into a `LoadedTheme`.
  * The single loader the CLI and programmatic callers share: file read/JSON
  * failures fail fast with the path; structural failures go through
  * `parseThemeConfig`. `rootDir` (the config's directory) is attached AFTER
  * validation — it is not a JSON field.
  */
-export declare function loadThemeConfig(absPath: string): CompilerConfig;
+export declare function loadThemeConfig(absPath: string): LoadedTheme;

package/dist/markdown/schema/themeConfigSchema.js

@@ -129,7 +129,7 @@ export function parseThemeConfig(raw, sourcePath) {
     return r.data;
 }
 /**
- * Read, validate, and root a `theme.json` at `absPath` into a `CompilerConfig`.
+ * Read, validate, and root a `theme.json` at `absPath` into a `LoadedTheme`.
  * The single loader the CLI and programmatic callers share: file read/JSON
  * failures fail fast with the path; structural failures go through
  * `parseThemeConfig`. `rootDir` (the config's directory) is attached AFTER

package/dist/markdown/types.d.ts

@@ -274,8 +274,25 @@ export type CompilerThemeConfig = {
     };
     mermaidVariant?: string;
 };
-export type CompilerConfig = CompilerThemeConfig & {
+/**
+ * A theme as loaded from disk: its validated config plus the directory it
+ * lives in, which the catalog's relative asset paths resolve against.
+ */
+export type LoadedTheme = CompilerThemeConfig & {
     rootDir: string;
+};
+/**
+ * Everything one build needs: the loaded theme plus what this particular deck
+ * brings. Neither addition is a theme.json field; both are attached per
+ * invocation, the way `rootDir` is attached after load.
+ */
+export type CompilerConfig = LoadedTheme & {
+    /**
+     * The deck file's directory, which a body image written as a file path
+     * resolves against. The CLI takes it from the deck's location; a
+     * programmatic caller that compiles from a string supplies it.
+     */
+    deckDir: string;
     /**
      * Browser executable to render mermaid with, from `--browser-path`. Added
      * after load like `rootDir`: it is a per-invocation choice, not a theme's.

package/package.json

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

package/theme-package/syntax.md

@@ -134,13 +134,13 @@ Fill a slot by writing a `::key::` region in the body; the marker maps to the sl
   ````
   The language tag (e.g. `sql`, `python`, `typescript`) is required -- it drives syntax highlighting, using the theme's `codeTheme` (set once in `theme.json`, not per slot). Colors are applied as native text runs in the output, not images.
 - **table** (slots that accept `table`) -- a GFM table. Write it in the slot region between `|`-delimited headers and rows; cells inherit inline formatting (bold, italic, links).
-- **image** (slots that accept `image`) -- a picture from the theme's asset catalog, written as `![]($category.name)`:
+- **image** (slots that accept `image`) -- a picture, written as `![]($category.name)` for one from the theme's asset catalog, or `![](path/to/file.png)` for a file relative to the deck:
   ```markdown
   ::logo::
 
   ![]($brand.primaryDarkWordmark)
   ```
-  The categories and names are catalogued in `assets.json`. How the picture is scaled and cropped comes from the **asset's `type`** in the catalog: `icon` never enlarges past native and never crops, `image` fits the whole picture without cropping, `background` fills the frame and center-crops. A fenced `mermaid` block also fills an image slot, rendering to a themed PNG (see below).
+  The categories and names are cataloged in `assets.json`. How the picture is scaled and cropped comes from the **asset's `type`** in the catalog: `icon` never enlarges past native and never crops, `image` fits the whole picture without cropping, `background` fills the frame and center-crops. A file path has no catalog entry, so it is always fitted as `image`; put a picture in the catalog when it needs another fit or when agents should be able to find it. A fenced `mermaid` block also fills an image slot, rendering to a themed PNG (see below).
 
 ---