@tycoworks/tycoslide 0.8.0 → 0.9.0

package/dist/markdown/types.d.ts

@@ -1,5 +1,6 @@
-import { type ImageFill, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
-import type { MermaidConfig } from "./resolvers/mermaidTheme.js";
+import type { RootContent } from "mdast";
+import { type Frame, type ImageFill, type TableFill, type TemplateFill, type TextFill } from "../engine/index.js";
+import type { MermaidConfig } from "./blocks/mermaidTheme.js";
 /**
  * An asset's scaling/cropping tolerance, declared in the theme catalog. The
  * compiler maps it to the engine's object-fit `fit`. `icon`: never enlarge,
@@ -26,18 +27,6 @@ export type AssetEntry = {
 };
 /** Two-level catalog: `{ category: { name: AssetEntry } }`. */
 export type AssetCatalog = Record<string, Record<string, AssetEntry>>;
-/**
- * Discriminator strings for the compiler-internal fence shapes produced by
- * deckCompiler.ts. `Code` and `Mermaid` are resolved away entirely (syntax
- * highlighting → TextFill, PNG rendering → ImageFill), so neither reaches the
- * engine. Prose has no FenceType: it becomes a `TextFill` (`{ paragraphs }`),
- * one of the engine's own fill shapes.
- */
-export declare const FenceType: {
-    readonly Code: "code";
-    readonly Mermaid: "mermaid";
-};
-export type FenceType = (typeof FenceType)[keyof typeof FenceType];
 /**
  * Discriminator for a layout's frontmatter *parameters* — inputs the author
  * writes as a single `key: value` line. Two kinds: `Template` (fills a styled
@@ -51,60 +40,84 @@ export declare const ParameterType: {
 };
 export type ParameterType = (typeof ParameterType)[keyof typeof ParameterType];
 /**
- * Compiler-facing slot type for a layout's *slots* — multi-line body regions
- * (the default body region, or a `::name::` region). Narrowed to four kinds;
- * `Template` and `Image` left this list to become parameters. `Code` and `Mermaid`
- * are compiler-only, resolved (syntax highlighting, mermaid PNG rendering)
- * before the engine sees the deck. Required on every CompilerSlot — no silent
- * default.
+ * The engine content types a slot may `accept`. A subset of the engine's
+ * `SlotType`: `Template` is parameter-only, never a body block. There is no
+ * `code` / `mermaid` accept type — a code fence folds into a `Text`-accepting
+ * slot (syntax highlighting → TextFill) and a mermaid fence into an
+ * `Image`-accepting slot (PNG render → ImageFill), the same fold the engine
+ * already performs. The author's markdown shape selects which accepted type a
+ * region routes to.
  */
-export declare const CompilerSlotType: {
+export declare const AcceptType: {
     readonly Text: "text";
     readonly Table: "table";
-    readonly Code: "code";
-    readonly Mermaid: "mermaid";
+    readonly Image: "image";
 };
-export type CompilerSlotType = (typeof CompilerSlotType)[keyof typeof CompilerSlotType];
+export type AcceptType = (typeof AcceptType)[keyof typeof AcceptType];
 /**
- * A fenced code block awaiting syntax highlighting. Produced by deckCompiler,
- * consumed by CodeResolver. Never crosses the engine boundary.
+ * The four engine content shapes a slot's compiled content can be — the value
+ * `compile` produces and the engine fills. ImageFill carries a `.type`
+ * discriminator; the other three — TextFill, TableFill, TemplateFill — are
+ * identified structurally by their signature field.
  */
-export type CodeFence = {
-    type: typeof FenceType.Code;
-    language: string;
-    source: string;
-};
+export type EngineFill = TextFill | TableFill | ImageFill | TemplateFill;
+/**
+ * The three engine content shapes a block handler can produce. A subset of
+ * `EngineFill` — `TemplateFill` is parameter-only (`AcceptType` excludes
+ * `Template`), so no block handler ever compiles one.
+ */
+export type BlockFill = TextFill | TableFill | ImageFill;
 /**
- * A mermaid code fence awaiting rendering. Produced by deckCompiler, consumed
- * by MermaidResolver — the resulting PNG is wrapped as an ImageFill in
- * step.content, so the engine never learns mermaid exists.
+ * Everything a block handler needs to compile a node into its engine fill: the
+ * asset resolver, the diagnostic context to name the offending layout/slide/slot
+ * when a region's markdown shape is illegal (a stray standalone block mixed into
+ * prose), and the theme-level `config` — from which code/mermaid compile read
+ * their one-per-theme style (`codeTheme`, `mermaid`, `mermaidVariant`,
+ * `outputDir`), not the slot.
+ *
+ * Lives in types.ts (not in `blocks/registry.ts`, which re-exports it) so a
+ * per-kind block file can import it without importing the registry — the registry
+ * imports the per-kind handlers, so the reverse would cycle.
  */
-export type MermaidFence = {
-    type: typeof FenceType.Mermaid;
-    definition: string;
+export type BlockContext = {
+    resolveAssetRef: (ref: string) => ImageFill;
+    layoutName: string;
+    slideIdx: number;
+    source: string;
+    config: CompilerConfig;
 };
 /**
- * The full set of value shapes a slot may hold during compilation, before code
- * fences are highlighted (→ TextFill) and mermaid fences are rendered
- * (→ ImageFill). CodeFence, MermaidFence, and ImageFill carry a `.type`
- * discriminator; the three engine fills without one — TextFill, TableFill,
- * TemplateFill — are identified structurally by their signature field.
+ * A block handler recognizes one content kind at the region's top level, folds
+ * it to the engine `AcceptType` it fills, and compiles the node straight into the
+ * matching engine fill — highlighting a code fence to a TextFill, rendering a
+ * mermaid fence to an ImageFill. Recognition (`match`), type (`acceptType`), and
+ * build (`compile`) live together — a new content kind is one file, one registry
+ * row. Non-generic like the engine's `Filler`: the array can't correlate a
+ * per-element type guard with `compile`'s param, so each handler narrows the node
+ * internally with a single-hop cast. Mirrors the old sdk's `SyntaxHandler`.
  */
-export type MarkdownBlock = TextFill | TableFill | CodeFence | MermaidFence | ImageFill | TemplateFill;
+export type BlockHandler = {
+    match(node: RootContent): boolean;
+    acceptType: AcceptType;
+    compile(node: RootContent, ctx: BlockContext): Promise<BlockFill>;
+};
 /**
- * A DeckStep as compileDeck produces it — content values may still be
- * unresolved (CodeFence, MermaidFence) at this point. `resolveFences` narrows
- * these into StyledParagraph[] / ImageFill before the engine sees the deck.
+ * A DeckStep as the compiler produces it. Content is already engine-shaped —
+ * code fences highlighted to TextFill and mermaid fences rendered to ImageFill
+ * during `compile` — so this is structurally equivalent to the engine's DeckStep
+ * and needs no further resolution.
  */
 export type CompilerDeckStep = {
     layout: string;
-    content?: Record<string, MarkdownBlock>;
+    content?: Record<string, EngineFill>;
     /** Slide-level speaker notes, stripped from frontmatter. Plain text. */
     notes?: string;
 };
 /**
- * The intermediate deck shape produced by compileDeck. buildDeck runs the
- * resolvers and hands the resulting engine-shaped Deck to generate().
+ * The deck shape the compiler produces. `output` may be unset until a caller
+ * (the CLI, or a programmatic caller) assigns one; `buildDeck` fails fast if it
+ * is still missing. Once `output` is present this is structurally equivalent to
+ * the engine's Deck, so `generate` consumes it without any cast.
  */
 export type CompilerDeck = {
     theme: string;
@@ -112,52 +125,15 @@ export type CompilerDeck = {
     steps: CompilerDeckStep[];
 };
 /**
- * A DeckStep whose content values have been narrowed post-resolution — no
- * CodeFence or MermaidFence remains, only shapes the engine understands.
- * Structurally equivalent to the engine's DeckStep.
- */
-export type ResolvedCompilerDeckStep = {
-    layout: string;
-    content?: Record<string, TextFill | TableFill | ImageFill | TemplateFill>;
-    /** Slide-level speaker notes, threaded through to the engine. Plain text. */
-    notes?: string;
-};
-/**
- * A CompilerDeck whose steps have been passed through the resolvers via
- * `resolveFences`. Structurally equivalent to the engine's Deck — deck
- * resolution returns this shape so `generate` can consume it without any cast.
+ * Markdown-flavored measurement hints on a slot or template parameter: caps on
+ * expanded run text, line count, or list items. All optional — a missing cap is
+ * "no limit." Advisory metadata surfaced in the manifest; the fill never enforces
+ * it.
  */
-export type ResolvedCompilerDeck = {
-    theme: string;
-    output: string;
-    steps: ResolvedCompilerDeckStep[];
-};
-/**
- * Fields common to every text shape, image parameter, and slot. A text shape is
- * addressed by `shapeName` and owns a `template` (its placeholders are the
- * fillable keys); image parameters and slots additionally carry a single `key`.
- */
-type CompilerShapeBase = {
-    shapeName: string;
-    limit?: {
-        maxChars?: number;
-        maxLines?: number;
-        maxItems?: number;
-    };
-    /**
-     * Whether the parameter/slot may be omitted from a slide. Optional (defaults
-     * to false): a required one with no value causes the compiler to throw with
-     * layout + key names.
-     */
-    required?: boolean;
-};
-/**
- * Shape base plus a single `key` — the addressing model for image parameters
- * and every slot. Template parameters do NOT extend this: their fillable keys are
- * the placeholders in their `template`, not a single top-level key.
- */
-type CompilerSlotBase = CompilerShapeBase & {
-    key: string;
+export type Limit = {
+    maxChars?: number;
+    maxLines?: number;
+    maxItems?: number;
 };
 /**
  * Template parameter: a styled text shape filled by expanding a `template` into the
@@ -167,14 +143,31 @@ type CompilerSlotBase = CompilerShapeBase & {
  * placeholders in its template. The shape carries no top-level `key`; its
  * placeholders are the keys the author fills in frontmatter.
  */
-export type CompilerTemplateParameter = CompilerShapeBase & {
+export type CompilerTemplateParameter = {
+    shapeName: string;
+    limit?: Limit;
+    /**
+     * Whether the parameter may be omitted from a slide. Optional (defaults to
+     * false): a required one with no value causes the compiler to throw with
+     * layout + key names.
+     */
+    required?: boolean;
     type: typeof ParameterType.Template;
     /** The shape's text as one template with `{key}` placeholders; newlines are line breaks. */
     template: string;
 };
 /** Image parameter: one frontmatter path filled by fillImage. Sizing/crop
- * behaviour comes from the resolved asset's `type`, not the slot. */
-export type CompilerImageParameter = CompilerSlotBase & {
+ * behaviour comes from the resolved asset's `type`, not the slot. Carries no
+ * `limit` — measuring an image path against char/line caps is meaningless. */
+export type CompilerImageParameter = {
+    shapeName: string;
+    /**
+     * Whether the parameter may be omitted from a slide. Optional (defaults to
+     * false): a required one with no value causes the compiler to throw with
+     * layout + key names.
+     */
+    required?: boolean;
+    key: string;
     type: typeof ParameterType.Image;
 };
 /**
@@ -182,58 +175,85 @@ export type CompilerImageParameter = CompilerSlotBase & {
  * single `key: value` line, resolved against the layout's `parameters` list.
  */
 export type CompilerParameter = CompilerTemplateParameter | CompilerImageParameter;
-/** Multi-paragraph body filled by fillText (specimen-style rebuild). */
-export type CompilerTextSlot = CompilerSlotBase & {
-    type: typeof CompilerSlotType.Text;
-    /** Leave the first N specimen paragraphs untouched. */
-    startAt?: number;
-};
-/** Table shape backed by an `<a:tbl>` with header + data specimen rows. */
-export type CompilerTableSlot = CompilerSlotBase & {
-    type: typeof CompilerSlotType.Table;
-};
 /**
- * Text slot that consumes a fenced code block. The resolver (`CodeResolver`)
- * uses `codeTheme` to Shiki-highlight the source into StyledParagraph[]; the
- * engine sees the projected Text slot.
+ * Reserved keys in a deck's frontmatter — global (theme, output) and per-slide
+ * (layout, body). Exported so callers (e.g. cli.ts) reference the constants
+ * instead of literal strings.
  */
-export type CompilerCodeSlot = CompilerSlotBase & {
-    type: typeof CompilerSlotType.Code;
-    /** Shiki theme id (required — no silent default). */
-    codeTheme: string;
+export declare const RESERVED_KEY: {
+    readonly LAYOUT: "layout";
+    readonly BODY: "body";
+    readonly OUTPUT: "output";
+    readonly THEME: "theme";
+    readonly NOTES: "notes";
 };
 /**
- * Slot that consumes a mermaid code fence. The resolver (`MermaidResolver`)
- * uses `mermaidVariant` to select colors and renders a PNG; the engine sees the
- * projected Image slot with `contain` fit. Mermaid slots do NOT declare `fit` —
- * mermaid diagrams are always contained.
+ * A kind of content a slot accepts, and the real template shape that realizes
+ * it — the compiler mirror of the engine's `Block`. `type` is an engine content
+ * type (`text` | `table` | `image`); `shapeName` names the shape on
+ * `sourceSlide` carrying the specimen styling. When `sourceSlide` equals the
+ * layout's `slideNumber` the shape is already on the cloned slide (fill in
+ * place); otherwise it is transplanted into the slot's `frame`. `startAt` is a
+ * text-specimen concern (leave the first N specimen paragraphs untouched), only
+ * meaningful on a text block. Named `CompilerBlock` to stay distinct from the
+ * engine's `Block` and the compiler's `BlockHandler`.
  */
-export type CompilerMermaidSlot = CompilerSlotBase & {
-    type: typeof CompilerSlotType.Mermaid;
-    /** Name of the mermaid variant (required — no silent default). */
-    mermaidVariant: string;
+export type CompilerBlock = {
+    type: AcceptType;
+    sourceSlide: number;
+    shapeName: string;
+    startAt?: number;
 };
 /**
- * Compiler-facing slot. Discriminated union on `type` — each variant declares
- * ONLY the fields legal for that slot type. A layout's body regions (the
- * default region, or a `::name::` region), resolved against the layout's
- * `slots` list. Adds markdown-flavored concepts (limit hints, code-fence theme
- * selection, mermaid variant naming) on top of the engine's minimal Slot.
- * Compiler-only types (Code, Mermaid) are projected down to engine types (Text,
- * Image) at the engine boundary before the engine sees the layout.
+ * Compiler-facing slot. A layout's body region (the default region, or a
+ * `::name::` region), no longer welded to one shape+type: it `accepts` a set of
+ * `CompilerBlock`s and owns a `frame` (real observed EMU coordinates, never
+ * computed). The author's markdown shape selects which accepted block a region
+ * routes to; a type the slot does not accept fails fast. `frame` is required
+ * only when a slot has a transplant block (a block whose `sourceSlide` differs
+ * from the layout's `slideNumber`); a base-only slot fills in place and needs
+ * none. Adds markdown-flavored `limit` hints on top of the engine's minimal
+ * Slot; per-slot `codeTheme` / `mermaidVariant` moved to the theme level.
  */
-export type CompilerSlot = CompilerTextSlot | CompilerTableSlot | CompilerCodeSlot | CompilerMermaidSlot;
+export type CompilerSlot = {
+    key: string;
+    accepts: CompilerBlock[];
+    frame?: Frame;
+    limit?: Limit;
+    /**
+     * Whether the slot may be omitted from a slide. Optional (defaults to false):
+     * a required slot with no content throws with layout + key names.
+     */
+    required?: boolean;
+};
 export type CompilerLayout = {
     name: string;
     slideNumber: number;
-    description: string;
-    whenToUse: string;
-    whenNotToUse: string;
+    /** Optional prose — a layout is a shape, not a purpose (agent-guidance descoped). */
+    description?: string;
+    whenToUse?: string;
+    whenNotToUse?: string;
     /** Frontmatter inputs (template, image) — one value per `key: value` line. */
     parameters: CompilerParameter[];
-    /** Body regions (text, table, code, mermaid) — the body or `::name::` regions. */
+    /** Body regions — the default body or `::name::` regions; each `accepts` blocks. */
     slots: CompilerSlot[];
 };
+/**
+ * A brand font the theme hands the compiler for HTML-based rendering (currently
+ * mermaid). Purely compiler-facing — the engine fills PPTX shapes, whose fonts
+ * live in the template, and never sees this. `path` is a module specifier
+ * (`@fontsource/inter/files/inter-latin-400-normal.woff2`) resolved from the
+ * theme's directory, or a `./`- / `/`-prefixed filesystem path resolved against
+ * `rootDir`; `family` is the CSS `font-family` name the mermaid variant's
+ * `fontFamily` must match. Register weight 400 + 700 to avoid synthetic bold on
+ * node labels. The mechanism is generic — the theme names its own fonts.
+ */
+export type ThemeFont = {
+    family: string;
+    path: string;
+    /** OpenType weight (default 400). */
+    weight?: number;
+};
 /**
  * Compiler-facing theme configuration. Mirrors the engine's ThemeConfig but
  * carries markdown-flavored fields (mermaid variants) that live outside the
@@ -246,8 +266,21 @@ export type CompilerThemeConfig = {
     template: string;
     outputDir?: string;
     mermaid?: MermaidConfig;
+    /**
+     * Brand fonts injected as `@font-face` when rendering mermaid, so diagram text
+     * uses the theme font instead of a Chromium fallback. Optional — with none
+     * declared, mermaid renders in whatever the OS substitutes.
+     */
+    fonts?: ThemeFont[];
+    /**
+     * Theme-level defaults for the two content types the compiler resolves before
+     * the engine sees them. One code style and one mermaid style per theme (the
+     * design-system framing) — they can't sit on a multi-type slot. `codeTheme` is
+     * a Shiki theme id; `mermaidVariant` names an entry in `mermaid`.
+     */
+    codeTheme?: string;
+    mermaidVariant?: string;
 };
 export type CompilerConfig = CompilerThemeConfig & {
     rootDir: string;
 };
-export {};

package/dist/markdown/types.js

@@ -1,4 +1,4 @@
-import { SlotType } from "../engine/index.js";
+import { SlotType, } from "../engine/index.js";
 // ── Asset catalog (compiler / theme-metadata only) ───────────────────────────
 /**
  * An asset's scaling/cropping tolerance, declared in the theme catalog. The
@@ -10,18 +10,6 @@ export const AssetType = {
     Image: "image",
     Background: "background",
 };
-// ── FenceType discriminator ───────────────────────────────────────────────────
-/**
- * Discriminator strings for the compiler-internal fence shapes produced by
- * deckCompiler.ts. `Code` and `Mermaid` are resolved away entirely (syntax
- * highlighting → TextFill, PNG rendering → ImageFill), so neither reaches the
- * engine. Prose has no FenceType: it becomes a `TextFill` (`{ paragraphs }`),
- * one of the engine's own fill shapes.
- */
-export const FenceType = {
-    Code: "code",
-    Mermaid: "mermaid",
-};
 // ── ParameterType discriminator (frontmatter, one value) ──────────────────────
 /**
  * Discriminator for a layout's frontmatter *parameters* — inputs the author
@@ -34,18 +22,30 @@ export const ParameterType = {
     Template: SlotType.Template,
     Image: SlotType.Image,
 };
-// ── CompilerSlotType discriminator (body region, multi-line) ──────────────────
+// ── AcceptType discriminator (what a slot accepts) ────────────────────────────
 /**
- * Compiler-facing slot type for a layout's *slots* — multi-line body regions
- * (the default body region, or a `::name::` region). Narrowed to four kinds;
- * `Template` and `Image` left this list to become parameters. `Code` and `Mermaid`
- * are compiler-only, resolved (syntax highlighting, mermaid PNG rendering)
- * before the engine sees the deck. Required on every CompilerSlot — no silent
- * default.
+ * The engine content types a slot may `accept`. A subset of the engine's
+ * `SlotType`: `Template` is parameter-only, never a body block. There is no
+ * `code` / `mermaid` accept type — a code fence folds into a `Text`-accepting
+ * slot (syntax highlighting → TextFill) and a mermaid fence into an
+ * `Image`-accepting slot (PNG render → ImageFill), the same fold the engine
+ * already performs. The author's markdown shape selects which accepted type a
+ * region routes to.
  */
-export const CompilerSlotType = {
+export const AcceptType = {
     Text: SlotType.Text,
     Table: SlotType.Table,
-    Code: FenceType.Code,
-    Mermaid: FenceType.Mermaid,
+    Image: SlotType.Image,
+};
+/**
+ * Reserved keys in a deck's frontmatter — global (theme, output) and per-slide
+ * (layout, body). Exported so callers (e.g. cli.ts) reference the constants
+ * instead of literal strings.
+ */
+export const RESERVED_KEY = {
+    LAYOUT: "layout",
+    BODY: "body",
+    OUTPUT: "output",
+    THEME: "theme",
+    NOTES: "notes",
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tycoworks/tycoslide",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,21 +22,24 @@
     "format": "biome format --write ."
   },
   "dependencies": {
-    "@mermaid-js/mermaid-cli": "^11.15.0",
     "@xmldom/xmldom": "^0.9.10",
     "commander": "^15.0.0",
     "image-size": "^2.0.2",
+    "mermaid": "^11.16.1",
+    "playwright": "^1.58.2",
     "pptx-automizer": "^0.8.2",
     "remark-gfm": "^4.0.1",
     "remark-ins": "^1.2.5",
     "remark-parse": "^11.0.0",
     "shiki": "^4.3.0",
     "unified": "^11.0.0",
-    "yaml": "^2.0.0"
+    "yaml": "^2.0.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.1",
     "@types/node": "^22.20.0",
+    "jszip": "^3.10.1",
     "typescript": "^5.8.0"
   }
 }

package/dist/markdown/parsers.d.ts

@@ -1,32 +0,0 @@
-import type { StyledParagraph, TableFill, TextRun } from "../engine/index.js";
-/**
- * Parse inline markdown formatting in a single line of text into TextRun arrays.
- * Handles **bold**, *italic*, ***bold italic***, ~~strikethrough~~, ++underline++,
- * [link](url), and `inline code`.
- */
-export declare function parseInlineRuns(text: string): TextRun[];
-/**
- * Parse a raw prose line into a StyledParagraph with bullet detection and inline
- * formatting. The caller provides the raw line including leading whitespace and
- * bullet markers.
- */
-export declare function parseStyledParagraph(raw: string): StyledParagraph;
-/**
- * Parse a single line of prose into its structural components.
- *
- * Lines beginning with `- ` or `* ` (optionally preceded by spaces) are
- * recognized as bullet items. Every 2 spaces of leading indent on a bullet
- * line increase its level by 1. A leading dash without a trailing space is
- * NOT a bullet (e.g. `-foo`).
- */
-export declare function parseProseLine(raw: string): {
-    text: string;
-    bullet: boolean;
-    level: number;
-};
-/**
- * Parse a GFM table into TableFill (StyledParagraph[] cells). Returns null
- * for non-table text. Cells carry rich runs so inline formatting works
- * inside tables for free.
- */
-export declare function parseGfmTable(text: string): TableFill | null;