@usetheo/ui 0.13.0 → 0.13.1

package/dist/components/primitives/sheet/sheet.d.ts

@@ -0,0 +1,57 @@
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { type VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithoutRef, HTMLAttributes } from "react";
+/**
+ * Sheet — slide-in side panel built on Radix Dialog.
+ *
+ * Same Radix primitive as Dialog, but Content slides from an edge instead of
+ * fading from center. Used for: workspace overlays (Memory, Observability,
+ * Sub-agents), Settings, contextual filters.
+ *
+ * Composition:
+ *   <Sheet>
+ *     <Sheet.Trigger>Open</Sheet.Trigger>
+ *     <Sheet.Content side="right">
+ *       <Sheet.Header>
+ *         <Sheet.Title>Memory</Sheet.Title>
+ *         <Sheet.Description>Episodes and wiki pages</Sheet.Description>
+ *       </Sheet.Header>
+ *       <Sheet.Body>…</Sheet.Body>
+ *       <Sheet.Footer>…</Sheet.Footer>
+ *     </Sheet.Content>
+ *   </Sheet>
+ */
+declare const Overlay: import("react").ForwardRefExoticComponent<Omit<DialogPrimitive.DialogOverlayProps & import("react").RefAttributes<HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+declare const sheetVariants: (props?: ({
+    side?: "bottom" | "left" | "right" | "top" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+interface ContentProps extends ComponentPropsWithoutRef<typeof DialogPrimitive.Content>, VariantProps<typeof sheetVariants> {
+    hideCloseButton?: boolean;
+}
+declare const Content: import("react").ForwardRefExoticComponent<ContentProps & import("react").RefAttributes<HTMLDivElement>>;
+declare const Header: {
+    ({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+declare const Body: {
+    ({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+declare const Footer: {
+    ({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+declare const Title: import("react").ForwardRefExoticComponent<Omit<DialogPrimitive.DialogTitleProps & import("react").RefAttributes<HTMLHeadingElement>, "ref"> & import("react").RefAttributes<HTMLHeadingElement>>;
+declare const Description: import("react").ForwardRefExoticComponent<Omit<DialogPrimitive.DialogDescriptionProps & import("react").RefAttributes<HTMLParagraphElement>, "ref"> & import("react").RefAttributes<HTMLParagraphElement>>;
+declare const Sheet: typeof DialogPrimitive.Root & {
+    Trigger: typeof DialogPrimitive.Trigger;
+    Close: typeof DialogPrimitive.Close;
+    Content: typeof Content;
+    Overlay: typeof Overlay;
+    Header: typeof Header;
+    Body: typeof Body;
+    Footer: typeof Footer;
+    Title: typeof Title;
+    Description: typeof Description;
+};
+export { Sheet, sheetVariants };

package/dist/components/primitives/sidebar/index.d.ts

@@ -0,0 +1 @@
+export { Sidebar } from "./sidebar.js";

package/dist/components/primitives/sidebar/sidebar.d.ts

@@ -0,0 +1,18 @@
+import type { ButtonHTMLAttributes, ElementType, HTMLAttributes, ReactNode } from "react";
+interface SectionProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    title?: ReactNode;
+}
+interface ItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type"> {
+    icon?: ElementType;
+    active?: boolean;
+    count?: number | string;
+    as?: "button" | "a";
+    href?: string;
+}
+declare const Sidebar: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & import("react").RefAttributes<HTMLElement>> & {
+    Header: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & import("react").RefAttributes<HTMLDivElement>>;
+    Section: import("react").ForwardRefExoticComponent<SectionProps & import("react").RefAttributes<HTMLDivElement>>;
+    Item: import("react").ForwardRefExoticComponent<ItemProps & import("react").RefAttributes<HTMLElement>>;
+    Footer: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & import("react").RefAttributes<HTMLDivElement>>;
+};
+export { Sidebar };

package/dist/components/primitives/skeleton/index.d.ts

@@ -0,0 +1 @@
+export { Skeleton } from "./skeleton.js";

package/dist/components/primitives/skeleton/skeleton.d.ts

@@ -0,0 +1,21 @@
+import type { HTMLAttributes } from "react";
+/**
+ * Skeleton — placeholder block shown while content is loading.
+ *
+ * Uses --muted as base + a subtle shimmer that respects the violet theme.
+ * Compose multiple Skeletons to mirror your component layout while loading.
+ *
+ * Accessibility (LOW-004): the default `role="status"` + `aria-live="polite"`
+ * announces "Loading" to screen readers. In loops or grids where many
+ * Skeletons mount simultaneously, this can be noisy. Override per-instance
+ * with `aria-live="off"` and/or `aria-hidden` when only one container-level
+ * loading announcement is desired:
+ *
+ *   <div role="status" aria-live="polite" aria-label="Loading deployments">
+ *     {placeholders.map(id => (
+ *       <Skeleton key={id} aria-live="off" aria-hidden="true" className="h-8" />
+ *     ))}
+ *   </div>
+ */
+declare const Skeleton: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & import("react").RefAttributes<HTMLDivElement>>;
+export { Skeleton };

package/dist/components/primitives/skill-card/index.d.ts

@@ -0,0 +1 @@
+export { SkillCard, type Skill, type SkillSource, type SkillState } from "./skill-card.js";

package/dist/components/primitives/skill-card/skill-card.d.ts

@@ -0,0 +1,28 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { Mode } from "../../../types/mode.js";
+export type SkillSource = "builtin" | "project" | "user" | "plugin";
+export type SkillState = "enabled" | "disabled";
+export interface Skill {
+    id: string;
+    name: string;
+    description?: ReactNode;
+    /** Where the skill comes from. */
+    source: SkillSource;
+    /** Optional tools the skill is allowed to use (informational). */
+    allowedTools?: string[];
+    /** Optional trigger keywords / patterns for discovery. */
+    triggers?: string[];
+    state?: SkillState;
+    /** Modes this skill is visible in. Omit / empty = global (all modes). */
+    modes?: Mode[];
+}
+interface SkillCardProps extends Omit<HTMLAttributes<HTMLDivElement>, "onToggle"> {
+    skill: Skill;
+    onToggle?: (id: string, next: SkillState) => void;
+}
+/**
+ * SkillCard — single skill entry showing what it does, where it came from,
+ * and which tools it needs. Toggle to enable/disable for the current session.
+ */
+declare const SkillCard: import("react").ForwardRefExoticComponent<SkillCardProps & import("react").RefAttributes<HTMLDivElement>>;
+export { SkillCard };

package/dist/components/primitives/slide/alerts.d.ts

@@ -0,0 +1,31 @@
+/**
+ * GFM alerts post-processor — converts `> [!NOTE]` blockquotes into
+ * `<aside class="theo-slide-alert" data-theo-slide-alert-type="...">` (ADR D3 of
+ * the slide-rich-content plan).
+ *
+ * GitHub Flavored Markdown introduced this convention in 2023 for callouts.
+ * `remark-gfm` (already in our dep tree) parses the blockquote but does NOT
+ * distinguish alerts from regular blockquotes. We post-process the mdast tree
+ * to detect the canonical marker and annotate with `hName` + `hProperties` so
+ * `mdast-util-to-hast` emits the desired hast element.
+ *
+ * Five tag families are supported, mirroring GitHub:
+ *   - NOTE      (info / blue)
+ *   - TIP       (success / green)
+ *   - IMPORTANT (purple)
+ *   - WARNING   (yellow)
+ *   - CAUTION   (red)
+ *
+ * Case-insensitive. Marker is stripped from the rendered text. Regular
+ * blockquotes (without `[!TYPE]` prefix) are left untouched.
+ */
+import type { Root } from "mdast";
+/** Canonical alert types — used by CSS via `data-theo-slide-alert-type="..."`. */
+export declare const ALERT_TYPES: readonly ["note", "tip", "important", "warning", "caution"];
+export type AlertType = (typeof ALERT_TYPES)[number];
+/**
+ * Walk a mdast tree and mutate any blockquote that opens with `[!TYPE]` into
+ * an `<aside>` annotation. Mutation is in-place to keep the pipeline allocation
+ * profile flat; the same tree is returned for chainability.
+ */
+export declare function detectAlerts(tree: Root): Root;

package/dist/components/primitives/slide/frontmatter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Lightweight, dependency-free extractor that separates YAML frontmatter from
+ * the markdown body.
+ *
+ * Strips a leading BOM (``) before matching the regex — common when
+ * markdown is pasted from Word/Notion. See plan ADR D14 and edge-case EC-4.
+ *
+ * Returns `{ rawFrontmatter, body, tooLarge? }`:
+ *   - `rawFrontmatter`: the YAML string between the two `---` delimiters, or
+ *     `null` if no frontmatter is present.
+ *   - `body`: the markdown after the closing `---\n` (or the full input when
+ *     no frontmatter).
+ *   - `tooLarge`: `true` if `rawFrontmatter` exceeds `MAX_RAW_FRONTMATTER`
+ *     bytes — the caller turns this into `FRONTMATTER_TOO_LARGE`.
+ */
+/** Maximum size of the raw frontmatter string before YAML parsing. 10 KB cap. */
+export declare const MAX_RAW_FRONTMATTER = 10240;
+export interface ExtractFrontmatterResult {
+    rawFrontmatter: string | null;
+    body: string;
+    tooLarge?: boolean;
+}
+export declare function extractFrontmatter(md: string): ExtractFrontmatterResult;

package/dist/components/primitives/slide/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Public surface of `@theokit/ui/slide`. Subpath-isolated engine: this bundle
+ * is emitted separately from the barrel (see `tsup.config.ts`) and depends on
+ * the markdown stack via optional peer-deps.
+ */
+export { Slide } from "./slide.js";
+export type { SlideAspectRatio, SlideProps, SlideTheme, SlideValidationError, SlideValidationErrorCode, } from "./slide.js";
+export { parseSlide, parseBody, mdastToHast, sanitizeHast, hastToReact, type ParseSlideOptions, type ParsedSlide, } from "./parse.js";
+export { validateSlide, type ValidationResult } from "./validate.js";
+export { extractFrontmatter, MAX_RAW_FRONTMATTER, type ExtractFrontmatterResult, } from "./frontmatter.js";
+export { slideFrontmatter, slideInput, slideTheme, type SlideFrontmatter, type SlideInput, } from "./schema.js";
+export { isSlideTheme, slideThemes } from "./themes/index.js";
+export { useSlideFit, type UseSlideFitOptions } from "./use-slide-fit.js";
+export { collectTagCounts, getSlideSanitizeSchema } from "./sanitize.js";
+export { composePlugins, type SlidePlugin, type SlideSanitizeExtension, type MergedSanitizeExtensions, type PluginComposer, } from "./plugin.js";
+export { slideFrontmatterJsonSchema } from "./json-schema.js";

package/dist/components/primitives/slide/json-schema.d.ts

@@ -0,0 +1,9 @@
+interface JsonSchemaProperties {
+    [key: string]: Record<string, unknown>;
+}
+interface JsonSchemaWithProperties {
+    properties?: JsonSchemaProperties;
+    [key: string]: unknown;
+}
+export declare const slideFrontmatterJsonSchema: JsonSchemaWithProperties;
+export {};

package/dist/components/primitives/slide/marpit-bg.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Marpit-style `![bg](url)` background syntax detector.
+ *
+ * Marpit popularised the convention of declaring a slide background via a
+ * standalone image whose alt-text starts with `bg`:
+ *
+ *     ![bg](https://example.com/photo.jpg)
+ *     ![bg cover](url)   ![bg fit](url)   ![bg left](url)   ![bg right](url)
+ *
+ * LLMs trained on Marp output emit this naturally, so the slide primitive
+ * adopts the same surface — but in a STRICTLY safe way:
+ *
+ * 1. Only triggers when the paragraph contains a SINGLE image (avoids
+ *    collisions with inline images mixed with text).
+ * 2. First-bg-wins (multiple `![bg]` directives in one slide → only the first
+ *    is honoured; the others are also dropped from the tree to prevent
+ *    duplicate rendering).
+ * 3. The extracted result goes into `ParsedSlide.extractedBackground` (D18 /
+ *    EC-5) and the Slide component prefers an explicit `frontmatter.backgroundImage`
+ *    over the Marpit extraction.
+ * 4. URL sanitization happens at the caller (`parseSlide`) via `sanitizeBgUrl`.
+ */
+import type { Root } from "mdast";
+export interface ExtractedMarpitBackground {
+    url: string;
+    modifier?: "cover" | "fit" | "left" | "right";
+}
+/**
+ * Walk the mdast tree, extract the first `![bg](url)` directive, drop ALL
+ * matching paragraphs from the tree. Returns a new tree (children array
+ * is filtered; node identities are preserved otherwise).
+ */
+export declare function extractMarpitBackgrounds(tree: Root): {
+    tree: Root;
+    background?: ExtractedMarpitBackground;
+};

package/dist/components/primitives/slide/parse.d.ts

@@ -0,0 +1,59 @@
+import type { Root as HastRoot } from "hast";
+/**
+ * Markdown → React tree pipeline for the Slide primitive.
+ *
+ *   parseSlide(markdown)
+ *     ├─ validateSlide(markdown) → { frontmatter, body, errors? }
+ *     ├─ parseBody(body)        → mdast Root (micromark + GFM)
+ *     ├─ mdastToHast(mdastTree) → hast Root (allowDangerousHtml: false)
+ *     ├─ sanitizeHast(hastTree) → hast Root + BANNED_TAG diff (ADR D13)
+ *     └─ hastToReact(hastTree)  → React tree (jsx-runtime, no innerHTML)
+ *
+ * Every transform is composed of lazy-imported peer-deps so the slide bundle
+ * stays under budget and never vendors the markdown stack into the barrel
+ * (ADR D2 / D3 of the slide plan).
+ */
+import type { Root as MdastRoot } from "mdast";
+import type { ReactElement } from "react";
+import { type MergedSanitizeExtensions, type SlidePlugin } from "./plugin.js";
+import { type SlideFrontmatter, type SlideValidationError } from "./schema.js";
+export interface ParseSlideOptions {
+    /** Override individual element renderers (passed to hast-util-to-jsx-runtime). */
+    components?: Record<string, unknown>;
+    /** Rich-content plugins (Tier 2). Order matters — D13 / RFC 0004. */
+    plugins?: SlidePlugin[];
+}
+export interface ExtractedBackground {
+    /** Sanitized URL (http/https only). */
+    url: string;
+    /** Optional Marpit modifier: `cover` | `fit` | `left` | `right`. */
+    modifier?: "cover" | "fit" | "left" | "right";
+}
+export interface ParsedSlide {
+    frontmatter: SlideFrontmatter;
+    /** React element renderable as the body of a slide. Always defined (may be empty Fragment). */
+    tree: ReactElement;
+    /** Validation + sanitize errors collected during parsing. Empty on success. */
+    errors: SlideValidationError[];
+    /** True when the input contained a top-level thematic break and only the first slide was rendered. */
+    truncated: boolean;
+    /**
+     * Background image extracted from Marpit `![bg](url)` syntax (D18 / EC-5).
+     * Precedence: `frontmatter.backgroundImage` > `extractedBackground.url`.
+     */
+    extractedBackground?: ExtractedBackground;
+}
+export declare function parseBody(body: string): Promise<MdastRoot>;
+export declare function mdastToHast(tree: MdastRoot): Promise<HastRoot>;
+export declare function sanitizeHast(tree: HastRoot, extensions?: MergedSanitizeExtensions): Promise<{
+    tree: HastRoot;
+    bannedTags: string[];
+}>;
+export declare function hastToReact(tree: HastRoot, components?: Record<string, unknown>): Promise<ReactElement>;
+/**
+ * Public entry point. Validates → parses → sanitizes → returns a React tree.
+ *
+ * Never throws on input. Errors (validation, BANNED_TAG) are collected into
+ * `errors[]` so callers can show them via `onValidationError`.
+ */
+export declare function parseSlide(markdown: string, opts?: ParseSlideOptions): Promise<ParsedSlide>;

package/dist/components/primitives/slide/plugin.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Slide plugin contract — extension points for rich-content engines.
+ *
+ * Plugins are composable transformers applied during `parseSlide`. Each plugin
+ * may inspect/mutate the mdast tree (before HTML conversion), the hast tree
+ * (after HTML conversion, before sanitize), and override React component
+ * renderers (after sanitize). They may also declare sanitize-schema extensions
+ * so custom tags (e.g. Shiki spans, KaTeX MathML, Mermaid SVG) survive the
+ * security barrier.
+ *
+ * Design rules (ADRs in `.claude/knowledge-base/plans/slide-rich-content-plan.md`):
+ *   D1  — explicit `plugins` prop (no auto-detect).
+ *   D2  — plugin shape: { name, mdastTransform?, hastTransform?, components? }.
+ *   D13 — execution order: mdast → hast → sanitize (with merged extensions) → components.
+ *   D16 — plugin error isolation: each plugin call is try/catch wrapped; errors
+ *         are collected, not thrown.
+ *   D17 — sanitize-schema merge is OBLIGATORY for plugins emitting non-default
+ *         tags; without it, the sanitize step silently strips the content.
+ *
+ * Sanitize is the security barrier. Plugins NEVER bypass `hast-util-sanitize`.
+ */
+import type { Root as HastRoot } from "hast";
+import type { Root as MdastRoot } from "mdast";
+import type { FC } from "react";
+import type { SlideValidationError } from "./schema.js";
+/** Sanitize schema extension declared by a plugin. Merged with `defaultSchema` in `parseSlide`. */
+export interface SlideSanitizeExtension {
+    /** Additional element tag names allowed past the sanitizer. */
+    tagNames?: string[];
+    /** Additional attribute allow-list keyed by tag name (or `"*"` for all tags). */
+    attributes?: Record<string, string[]>;
+}
+/** A composable transformer + component-override unit. */
+export interface SlidePlugin {
+    /** Stable identifier used in PLUGIN_ERROR messages and dev logs. */
+    name: string;
+    /** Mutate the mdast tree before HTML conversion. Return value is forwarded. */
+    mdastTransform?: (tree: MdastRoot) => Promise<MdastRoot> | MdastRoot;
+    /** Mutate the hast tree after HTML conversion, before sanitize. */
+    hastTransform?: (tree: HastRoot) => Promise<HastRoot> | HastRoot;
+    /** React component overrides merged into the consumer's `components` map. */
+    components?: Record<string, FC<any>>;
+    /** Sanitize-schema extension. Required for plugins emitting non-default tags. */
+    sanitizeSchemaExtension?: SlideSanitizeExtension;
+}
+/** Merged sanitize-schema extensions from all plugins. */
+export interface MergedSanitizeExtensions {
+    tagNames: string[];
+    attributes: Record<string, string[]>;
+}
+/** Composer over a plugin array. Hooks orchestrate transformation + error isolation. */
+export interface PluginComposer {
+    /** Run all `mdastTransform` hooks in array order. Collects errors. */
+    runMdast(tree: MdastRoot, errors: SlideValidationError[]): Promise<MdastRoot>;
+    /** Run all `hastTransform` hooks in array order. Collects errors. */
+    runHast(tree: HastRoot, errors: SlideValidationError[]): Promise<HastRoot>;
+    /** Merge all plugin component overrides; later-plugin-wins on conflict. */
+    mergedComponents(): Record<string, FC<any>>;
+    /** Merge sanitize-schema extensions across all plugins (dedupes tag names). */
+    mergedSanitizeExtensions(): MergedSanitizeExtensions;
+}
+/**
+ * Build a composer over an array of plugins.
+ *
+ * Order semantics:
+ *   - mdast transforms run sequentially in array order.
+ *   - hast transforms run sequentially in array order.
+ *   - components merge: later plugin wins on conflict (Object.assign semantics).
+ *   - sanitize-schema extensions: union of tag names; union of attributes by tag.
+ *
+ * Error semantics (D16):
+ *   - Each plugin call is wrapped in try/catch.
+ *   - On throw, an error of code `PLUGIN_ERROR` is pushed to `errors[]` and the
+ *     pipeline continues with the **non-transformed** input from that plugin
+ *     (i.e. subsequent plugins see the tree that failed plugin received).
+ *   - The composer NEVER throws; `parseSlide` keeps its "never throws on input"
+ *     contract (RFC 0002 D9).
+ */
+export declare function composePlugins(plugins: SlidePlugin[]): PluginComposer;

package/dist/components/primitives/slide/plugins/emoji/index.d.ts

@@ -0,0 +1,8 @@
+import type { SlidePlugin } from "../../plugin.js";
+import { EMOJI_MAP } from "./map.js";
+export interface EmojiPluginOptions {
+    /** Override or extend the default emoji map. Merged on top of the built-in 100. */
+    extra?: Record<string, string>;
+}
+export declare function emojiPlugin(opts?: EmojiPluginOptions): SlidePlugin;
+export { EMOJI_MAP };

package/dist/components/primitives/slide/plugins/emoji/map.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 100 emoji shortcodes commonly used in tech presentations.
+ *
+ * Selection rationale: covers the top ~80% of GitHub markdown usage in code
+ * docs, release notes, slides. Unicode-native (no external font dependency)
+ * so the appearance follows the OS emoji font (Apple Color Emoji on macOS,
+ * Segoe UI Emoji on Windows, Noto Color Emoji on Linux/Android).
+ *
+ * Adding entries: keep keys lowercase, kebab/underscore allowed, single Unicode
+ * scalar value (sequences like 👨‍💻 are also OK).
+ *
+ * Twemoji variant: out of scope — `slide/plugins/emoji-twemoji` is a v0.5
+ * candidate if demand emerges.
+ */
+export declare const EMOJI_MAP: Record<string, string>;

package/dist/components/primitives/slide/plugins/math/index.d.ts

@@ -0,0 +1,6 @@
+import type { SlidePlugin } from "../../plugin.js";
+export interface MathPluginOptions {
+    /** KaTeX render options forwarded to `renderToString`. */
+    katexOptions?: Record<string, unknown>;
+}
+export declare function mathPlugin(opts?: MathPluginOptions): SlidePlugin;

package/dist/components/primitives/slide/plugins/mermaid/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Slide rich-content plugin — Mermaid diagrams.
+ *
+ * Peer-dep: `mermaid` (optional, ~370 KB raw — lazy + opt-in mandatory).
+ * Render is client-only because Mermaid measures DOM nodes during layout;
+ * SSR / static render emits a labelled placeholder + source-code fallback.
+ *
+ * Pipeline contribution (D11 of the rich-content plan):
+ *   - `hastTransform`: detect `<pre><code class="language-mermaid">…</code></pre>`
+ *     and replace with `<div class="theo-slide-mermaid-host" data-theo-mermaid-source="…">`.
+ *   - `components.div`: when div has `data-theo-mermaid-source`, render the
+ *     `<MermaidDiagram>` React component that lazy-imports `mermaid` and
+ *     injects the SVG via `dangerouslySetInnerHTML` after `mermaid.render()`.
+ *
+ * EC-4: complete SVG tag + attribute allow-list (~30 tags) so the rendered SVG
+ * survives sanitize. Critical: without these, sanitize strips the SVG entirely.
+ *
+ * EC-10: SSR placeholder is distinguishable from a render error. Error path
+ * surfaces the Mermaid source code in a `<pre>` so consumers can debug + the
+ * print path still shows the code (PDF cannot run dynamic Mermaid).
+ */
+import { type FC } from "react";
+import type { SlidePlugin } from "../../plugin.js";
+export interface MermaidPluginOptions {
+    /** Mermaid theme name. Defaults to `"default"`. */
+    theme?: "default" | "forest" | "dark" | "neutral" | "base";
+}
+/**
+ * React component that renders Mermaid lazily on mount.
+ *
+ * SSR / pre-load: renders the source as `<pre>` + `role="img"` for a11y.
+ * Client: lazy-loads `mermaid`, calls `mermaid.render()`, then injects the
+ *         resulting SVG via `dangerouslySetInnerHTML` so React owns the DOM
+ *         subtree (avoids reconciliation crashes when state flips back to the
+ *         placeholder — `ref.innerHTML` would mutate under React's feet).
+ *
+ * The Mermaid output is a TRUSTED string from the `mermaid` lib itself (not
+ * user-controlled markup) — the user-supplied source is the DSL, not raw HTML.
+ * Using dangerouslySetInnerHTML here is a controlled escape hatch.
+ *
+ * Peer-dep guard: if `import("mermaid")` fails, falls back to the same
+ * pre-formatted source view + an `aria-label` hint (EC-10).
+ */
+export declare const MermaidDiagram: FC<{
+    source: string;
+    theme?: string;
+}>;
+export declare function mermaidPlugin(opts?: MermaidPluginOptions): SlidePlugin;

package/dist/components/primitives/slide/plugins/shiki/index.d.ts

@@ -0,0 +1,11 @@
+import type { SlidePlugin } from "../../plugin.js";
+export interface ShikiPluginOptions {
+    /** Dual-theme map — light/dark Shiki theme names. Defaults to `github-light` / `github-dark`. */
+    themes?: {
+        light: string;
+        dark: string;
+    };
+    /** Languages to pre-load. Unknown languages pass-through. Defaults to a tech-stack baseline. */
+    langs?: string[];
+}
+export declare function shikiPlugin(opts?: ShikiPluginOptions): SlidePlugin;

package/dist/components/primitives/slide/sanitize.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Sanitize schema for slide body hast trees.
+ *
+ * ADR D8: `defaultSchema` from `hast-util-sanitize` is used WITHOUT extensions
+ * in v0.1. The default schema:
+ *   - Strips `<script>`, `<iframe>`, `<object>`, `<embed>`, `<form>`, `<input>`,
+ *     `<style>`, `<link>` and other dangerous tags.
+ *   - Keeps `clobberPrefix: "user-content-"` so user-supplied IDs cannot
+ *     clobber DOM lookups.
+ *   - Allows the standard CommonMark + GFM safe subset (h1-h6, p, ul, ol, li,
+ *     blockquote, code, pre, a[href], img[src/alt], table family, em, strong,
+ *     del, br, hr, etc.).
+ *
+ * A `looseSlideSanitizeSchema` (with `figure`/`figcaption`) is an explicit
+ * opt-in for v0.2 — gated by security review.
+ */
+import type { Element, Root } from "hast";
+import type { MergedSanitizeExtensions } from "./plugin.js";
+/**
+ * Lazy accessor for the sanitize schema.
+ *
+ * Always merges `defaultSchema` with the Tier 1 baseline (aside + className).
+ * When `extensions` is provided, plugin-declared tag names + attributes are
+ * unioned on top (D17 / EC-3). Plugins NEVER bypass sanitize — they declare
+ * what they need via `sanitizeSchemaExtension`.
+ *
+ * Implementation notes:
+ *   - The baseline schema (default + Tier 1) is cached.
+ *   - Plugin-merged schemas are NOT cached (depends on combination).
+ */
+export declare function getSlideSanitizeSchema(extensions?: MergedSanitizeExtensions): Promise<import("hast-util-sanitize").Schema>;
+/** Count elements by tagName in a hast tree. Used for BANNED_TAG detection (ADR D13). */
+export declare function collectTagCounts(tree: Root | Element): Map<string, number>;

package/dist/components/primitives/slide/schema.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Zod schema for the Slide YAML frontmatter (`SlideFrontmatter`) and the
+ * composed `SlideInput` (frontmatter + body).
+ *
+ * Design (see RFC 0002 and the plan in
+ * `.claude/knowledge-base/plans/slide-view-primitive-plan.md` §16.3 and ADRs D4 / D14):
+ *
+ * - **`.strict()`** on frontmatter — unknown keys produce `INVALID_FRONTMATTER`
+ *   with a precise path, so an LLM can self-correct.
+ * - Numeric values are `.finite()` to reject `NaN` / `Infinity`. (Currently no
+ *   numeric directives ship; keep the helper for future fields.)
+ * - String values capped to defensible sizes to reject DoS-shaped inputs.
+ * - `body` capped to 50 KB (≈30 slides' worth of text) per the sanity rule.
+ * - `theme` is the canonical enum of built-in themes. Custom themes are not
+ *   registered via frontmatter in v0.1 — caller wraps `<Slide>` with their
+ *   own CSS overrides.
+ */
+import { z } from "zod";
+/** Built-in slide themes. Adding a theme means landing a CSS file in `themes/`. */
+export declare const slideTheme: z.ZodEnum<{
+    default: "default";
+    "violet-forge": "violet-forge";
+}>;
+export type SlideTheme = z.infer<typeof slideTheme>;
+/** Built-in slide layouts (rich-content plan T2.1). */
+export declare const slideLayout: z.ZodEnum<{
+    section: "section";
+    title: "title";
+    default: "default";
+    "two-column": "two-column";
+    "image-right": "image-right";
+    "image-left": "image-left";
+    "code-output": "code-output";
+}>;
+export type SlideLayout = z.infer<typeof slideLayout>;
+/**
+ * Sanitize a `backgroundImage` URL.
+ *
+ * Allowed: `http(s)://...` URLs (validated via `URL` constructor).
+ * Rejected: `javascript:`, `vbscript:`, all `data:` URLs (EC-7 — perf + DoS).
+ * Accepts a bare URL or a `url(...)` wrapper. Returns the unwrapped URL on
+ * success, `null` on rejection.
+ */
+export declare function sanitizeBgUrl(input: string): string | null;
+/** YAML frontmatter accepted by `<Slide>`. */
+export declare const slideFrontmatter: z.ZodObject<{
+    theme: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        "violet-forge": "violet-forge";
+    }>>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        section: "section";
+        title: "title";
+        default: "default";
+        "two-column": "two-column";
+        "image-right": "image-right";
+        "image-left": "image-left";
+        "code-output": "code-output";
+    }>>;
+    backgroundImage: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+    backgroundGradient: z.ZodOptional<z.ZodString>;
+    header: z.ZodOptional<z.ZodString>;
+    footer: z.ZodOptional<z.ZodString>;
+    paginate: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"skip">, z.ZodLiteral<"hold">]>>;
+    lang: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
+    backgroundColor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SlideFrontmatter = z.infer<typeof slideFrontmatter>;
+/** Composed input: validated frontmatter object + raw markdown body string. */
+export declare const slideInput: z.ZodObject<{
+    frontmatter: z.ZodObject<{
+        theme: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "violet-forge": "violet-forge";
+        }>>;
+        layout: z.ZodOptional<z.ZodEnum<{
+            section: "section";
+            title: "title";
+            default: "default";
+            "two-column": "two-column";
+            "image-right": "image-right";
+            "image-left": "image-left";
+            "code-output": "code-output";
+        }>>;
+        backgroundImage: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string | undefined, string>>>;
+        backgroundGradient: z.ZodOptional<z.ZodString>;
+        header: z.ZodOptional<z.ZodString>;
+        footer: z.ZodOptional<z.ZodString>;
+        paginate: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"skip">, z.ZodLiteral<"hold">]>>;
+        lang: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        backgroundColor: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    body: z.ZodString;
+}, z.core.$strip>;
+export type SlideInput = z.infer<typeof slideInput>;
+/** Discrete validation-error codes — kept centralized so consumers can pattern-match safely. */
+export type SlideValidationErrorCode = "INVALID_FRONTMATTER" | "FRONTMATTER_TOO_LARGE" | "MULTIPLE_SLIDES" | "CONTENT_TOO_LARGE" | "BANNED_TAG" | "BANNED_ATTRIBUTE" | "INVALID_ASPECT_RATIO" | "PLUGIN_ERROR" | "PLUGIN_PEER_DEP_MISSING" | "MARPIT_BG_UNSAFE_URL";
+export interface SlideValidationError {
+    /** Path inside the input (frontmatter key, ['body'], or []). */
+    path: (string | number)[];
+    /** Human-readable explanation. */
+    message: string;
+    /** Discriminator for consumers. */
+    code: SlideValidationErrorCode;
+    /** Offending value when extractable from Zod's `received` or by walking the input. */
+    got?: unknown;
+}