fika-editor 3.0.0 → 3.0.1

package/dist/types/embed/agentic/helpers.d.ts

@@ -0,0 +1,115 @@
+import type { Note, NoteReply, PPTAnimation, PPTAudioElement, PPTElement, PPTElementLink, PPTLatexElement, PPTLineElement, PPTShapeElement, PPTTableElement, Slide, SlideTheme, TableCell, TableCellStyle } from '../../types/slides';
+import type { FikaAudioElementPatch, FikaCommandIssue, FikaCommandType, FikaCreateAudioInput, FikaElementTransformPatch, FikaLatexElementInput, FikaMediaAsset, FikaMediaAssetInput, FikaMediaAssetKind, FikaNoteInput, FikaNotePatch, FikaNoteReplyInput, FikaTableElementPatch } from './types';
+export declare function clonePlain<T>(value: T): T;
+export declare function clonePatch<T extends object>(patch: T): T;
+export declare function createId(prefix: string): string;
+export declare function createIssue(code: string, message: string, path?: string, recoverable?: boolean): FikaCommandIssue;
+export declare function normalizeMediaExt(ext?: string): string | undefined;
+export declare function inferMediaExtFromMime(mimeType?: string): string | undefined;
+export declare function inferMediaMimeFromExt(ext?: string): string | undefined;
+export declare function inferMediaExtFromSrc(src: string, mimeType?: string): string | undefined;
+export declare function inferMediaMimeFromSrc(src: string, ext?: string): string | undefined;
+export declare function resolveMediaAsset(asset: FikaMediaAssetInput, kind?: FikaMediaAssetKind): FikaMediaAsset;
+export declare function isCanonicalCommandType(type: string): type is FikaCommandType;
+export type IdMap = Record<string, string>;
+export interface ElementCloneOptions {
+    animationIdMap?: IdMap;
+    elementIdMap?: IdMap;
+    groupIdMap?: IdMap;
+    offset?: number | {
+        left?: number;
+        top?: number;
+    };
+    preserveExternalSlideLinks?: boolean;
+    slideIdMap?: IdMap;
+}
+export interface ClonedElements {
+    elements: PPTElement[];
+    animations: PPTAnimation[];
+    elementIdMap: IdMap;
+    groupIdMap: IdMap;
+    animationIdMap: IdMap;
+}
+export interface ClonedSlides extends ClonedElements {
+    slides: Slide[];
+    slideIdMap: IdMap;
+}
+export declare function toIdList(id: string | string[]): string[];
+export declare function clampIndex(index: number, length: number): number;
+export declare function insertIndex(index: number | undefined, length: number): number;
+export declare function ensureSlide(slides: Slide[], slideId?: string, fallbackIndex?: number): {
+    slide: Slide;
+    index: number;
+};
+export declare function findElement(slides: Slide[], elementId: string, slideId?: string, fallbackIndex?: number): {
+    slide: Slide;
+    slideIndex: number;
+    element: PPTElement;
+    elementIndex: number;
+};
+export declare function ensureElementOnSlide(slide: Slide, elementId: string): void;
+export declare function createSlideIdMap(slides: Slide[]): IdMap;
+export declare function createElementIdMap(elements: PPTElement[]): {
+    elementIdMap: IdMap;
+    groupIdMap: IdMap;
+};
+export declare function normalizeElementLink(link: PPTElementLink | undefined, slides: Slide[]): PPTElementLink | undefined;
+export interface SlideLinkReference {
+    slideId: string;
+    elementId: string;
+    target: string;
+}
+export declare function findSlideLinkReferences(slides: Slide[], targetIds?: Set<string>): SlideLinkReference[];
+export declare function remapElementSlideLinks(elements: PPTElement[], slideIdMap: Map<string, string> | IdMap): number;
+export declare function cloneElementsWithRemappedIds(elements: PPTElement[], animations?: PPTAnimation[], options?: ElementCloneOptions): ClonedElements;
+export declare function cloneSlidesWithRemappedIds(slides: Slide[], options?: {
+    preserveExternalSlideLinks?: boolean;
+    slideIdMap?: IdMap;
+}): ClonedSlides;
+export declare function normalizeSlide(slide?: Partial<Slide>): Slide;
+export declare function normalizeElement(element: Partial<PPTElement> & {
+    type: PPTElement['type'];
+}, theme?: SlideTheme): PPTElement;
+export declare function flattenElementTransform<T extends object>(input: T & {
+    transform?: FikaElementTransformPatch;
+}): Omit<T, 'transform'> & FikaElementTransformPatch;
+export declare function normalizeAudioElement(input: FikaCreateAudioInput, defaultColor: string): PPTAudioElement;
+export declare function normalizeAudioPatch(patch: FikaAudioElementPatch): Partial<PPTAudioElement>;
+export declare function resolveShapeFormula(element: PPTShapeElement): PPTShapeElement;
+export declare function normalizeShapeElement(element?: Partial<PPTShapeElement>): PPTShapeElement;
+export declare function mergeShapeElement(base: PPTShapeElement, patch: Partial<PPTShapeElement>): PPTShapeElement;
+export interface LatexGeometry {
+    path: string;
+    viewBox: [number, number];
+    width: number;
+    height: number;
+}
+/**
+ * Render a LaTeX formula to its SVG path + intrinsic box via hfmath — the EXACT
+ * pipeline the interactive LaTeXEditor uses (`new hfmath(latex).pathd()/box()`).
+ *
+ * The agent supplies only the `latex` string; it cannot pre-compute the SVG
+ * `path`. Without a path the `<svg>` renders nothing, so a "latex" element from
+ * the agent shows up blank. Deriving the path here makes agent-authored formulas
+ * render identically to ones drawn through the editor UI.
+ */
+export declare function deriveLatexGeometry(latex: string): LatexGeometry;
+export declare function normalizeLatexElement(element: FikaLatexElementInput): PPTLatexElement;
+export declare function normalizeLineElement(element: Partial<PPTLineElement> & {
+    type?: 'line';
+}): PPTLineElement;
+export declare function updateLineElement(element: PPTLineElement, patch: Partial<PPTLineElement>): PPTLineElement;
+export declare function remapElementGroupIds(elements: PPTElement[]): PPTElement[];
+export declare function normalizeAnimation(animation: Partial<PPTAnimation> & {
+    elId: string;
+    effect: string;
+    type: PPTAnimation['type'];
+}): PPTAnimation;
+export declare function normalizeNote(note: FikaNoteInput): Note;
+export declare function normalizeNotePatch(patch: FikaNotePatch): Partial<Note>;
+export declare function normalizeReply(reply: FikaNoteReplyInput): NoteReply;
+export declare function createTableCell(text?: string, style?: TableCellStyle): TableCell;
+export declare function normalizeTableColWidths(colWidths: number[] | undefined, colCount: number): number[];
+export declare function normalizeTableElement(element?: Partial<PPTTableElement>, theme?: SlideTheme): PPTTableElement;
+export declare function normalizeTableElementPatch(table: PPTTableElement, patch: FikaTableElementPatch): Partial<PPTTableElement>;
+export declare function mergeTheme(theme: SlideTheme, patch: Partial<SlideTheme>): SlideTheme;

package/dist/types/embed/agentic/layouts.d.ts

@@ -0,0 +1,114 @@
+import type { PPTChartElement, PPTImageElement, PPTShapeElement, PPTTableElement, PPTTextElement, Slide } from '../../types/slides';
+import type { FikaStylePreset } from './styles';
+import type { CompositionAnchor } from './composition';
+/**
+ * Un-normalized element inputs the builder emits. Typed as a discriminated
+ * union of per-type partials so the engine's required fields are still checked,
+ * while letting the bridge's `normalizeElement` fill ids/defaults on insert.
+ */
+export type FikaLayoutElementInput = (Partial<PPTTextElement> & {
+    type: 'text';
+}) | (Partial<PPTShapeElement> & {
+    type: 'shape';
+}) | (Partial<PPTImageElement> & {
+    type: 'image';
+}) | (Partial<PPTChartElement> & {
+    type: 'chart';
+}) | (Partial<PPTTableElement> & {
+    type: 'table';
+});
+export type FikaLayoutBackgroundMode = 'auto' | 'feature' | 'plain';
+export interface FikaLayoutSlotDef {
+    name: string;
+    /** Coarse shape of the value the agent should pass for this slot. */
+    type: 'text' | 'bullets' | 'image' | 'chart' | 'stats' | 'rows' | 'cards' | 'steps';
+    required: boolean;
+    description: string;
+}
+/**
+ * One visual variant of a layout family. Variants of the same family accept
+ * the same slots but compose them differently (different anchor, background
+ * treatment, and motif placement), so a deck built from one style still varies
+ * slide-to-slide. `anchor` declares the variant's spatial center of gravity so
+ * the composition sequencer can plan a non-repeating rhythm.
+ */
+export interface FikaLayoutVariant {
+    id: string;
+    label: string;
+    /** Spatial center of gravity of this variant. */
+    anchor: CompositionAnchor;
+    /** What it looks like / when to pick it over the family's other variants. */
+    summary: string;
+}
+export interface FikaLayout {
+    id: string;
+    label: string;
+    /** One-line catalog description of the composition (what it looks like). */
+    summary: string;
+    /** When to reach for it. */
+    bestFor: string;
+    /** Whether it defaults to a feature (dark) background. */
+    feature: boolean;
+    slots: FikaLayoutSlotDef[];
+    /** The visual variants this family can build. The first is the default. */
+    variants: FikaLayoutVariant[];
+}
+/** Strip one or more leading bullet/number markers from a list item. */
+export declare function stripLeadingListMarkers(raw: string): string;
+type Slots = Record<string, unknown>;
+export declare const PPTX_LAYOUTS: FikaLayout[];
+export declare function listLayouts(): FikaLayout[];
+/**
+ * Whether a layout's job is to carry body content (bullets/columns/rows/cards/
+ * steps/stats/chart) beyond a title. Title/section/closing/quote/imageFull are
+ * legitimately sparse; content layouts are not. Drives the QA `contentEmpty`
+ * check that blocks a title-only slide (the "empty slide 3" bug).
+ */
+export declare function layoutExpectsBody(layoutId: string): boolean;
+/** Resolve a variant for a layout, warning (via return) on an unknown id. */
+export declare function resolveLayoutVariant(layout: FikaLayout, variantId?: string): {
+    variant: FikaLayoutVariant;
+    unknownRequested: boolean;
+};
+export interface FikaLayoutBuildResult {
+    slide: Partial<Slide>;
+    warnings: string[];
+    /** The variant actually built (id + anchor), so the caller can record it. */
+    variantId: string;
+    anchor: CompositionAnchor;
+}
+export interface SlotNormalization {
+    slots: Slots;
+    warnings: string[];
+}
+/**
+ * Validate + normalize the slots handed to a layout. Layers of defense against
+ * the "silent content drop" bug class:
+ *  1. ALIASES — map natural guessed names (leftColumn, columns, …) to canonical.
+ *  2. COERCION — reshape near-miss values (rows from objects, bullets from array).
+ *  3. IMAGE NEST — top-level sourceUrl/href next to an image slot becomes
+ *     `image: { src, sourceUrl }` (self-heal; soft advisory).
+ *  4. VALIDATION — any key that still isn't a real slot becomes a loud warning
+ *     with a fuzzy "did you mean X?" suggestion instead of being ignored.
+ * The slot definition list (`layout.slots`) is the single source of truth for
+ * what a layout consumes.
+ */
+export declare function normalizeLayoutSlots(layout: FikaLayout, rawSlots: Slots): SlotNormalization;
+/**
+ * Build a themed slide from a layout id + content slots. Pure and deterministic:
+ * returns a `Partial<Slide>` (background + un-normalized elements) plus any
+ * non-fatal warnings (e.g. a missing optional image). Text is auto-fit to each
+ * box via pretext, so content never overflows. Throws on missing required slots
+ * or an unknown layout.
+ *
+ * `variantId` selects the visual variant (from the layout's `variants` in the
+ * catalog); an unknown id falls back to the default variant with a warning.
+ *
+ * Async because slots may carry inline math; KaTeX is lazy-loaded up front (only
+ * when math is present) so the otherwise-synchronous builders can render it.
+ */
+export declare function buildLayoutSlide(layoutId: string, slots: Slots, preset: FikaStylePreset, viewport: {
+    width: number;
+    height: number;
+}, backgroundMode?: FikaLayoutBackgroundMode, variantId?: string): Promise<FikaLayoutBuildResult>;
+export {};

package/dist/types/embed/agentic/manifestDocs.d.ts

@@ -0,0 +1,73 @@
+export interface FikaDocParam {
+    name: string;
+    type?: string;
+    required?: boolean;
+    description?: string;
+}
+export interface FikaCommandDoc {
+    summary?: string;
+    details?: string;
+    params?: FikaDocParam[];
+    examples?: string[];
+    tips?: string[];
+    related?: string[];
+}
+export interface FikaDomainDoc {
+    title: string;
+    summary: string;
+    whenToUse?: string;
+}
+export interface FikaDesignGuide {
+    id: string;
+    title: string;
+    summary: string;
+    /** Body lines (join with "\n" to render). */
+    body: string[];
+}
+export interface FikaDesignSystem {
+    summary: string;
+    coordinateSystem: {
+        summary: string;
+        notes: string[];
+    };
+    tokens: {
+        summary?: string;
+        colors?: Record<string, string>;
+        fontFamily?: string;
+        fontSizePx?: Record<string, number>;
+        spacingPx?: Record<string, number>;
+    };
+}
+export interface FikaAgenticDocs {
+    version: number;
+    summary: string;
+    designSystem: FikaDesignSystem;
+    domains: Record<string, FikaDomainDoc>;
+    commands: Record<string, FikaCommandDoc>;
+    guides: FikaDesignGuide[];
+}
+/** A command description merged with live registry facts (registered? mutates?). */
+export interface FikaCommandDescription extends FikaCommandDoc {
+    name: string;
+    domain: string;
+    registered: boolean;
+    mutates: boolean;
+}
+/** A domain summary merged with the live registry command list. */
+export interface FikaDomainSummary {
+    id: string;
+    title: string;
+    summary: string;
+    whenToUse?: string;
+    commandCount: number;
+    commands: string[];
+}
+/** Minimal structural view of the command registry needed for introspection. */
+export type FikaCommandRegistryView = ReadonlyMap<string, {
+    mutates: boolean;
+}>;
+export declare const AGENTIC_DOCS: FikaAgenticDocs;
+/** Describe a single command: its doc annotation plus live registry facts. */
+export declare function describeAgenticCommand(registry: FikaCommandRegistryView, commandType: string): FikaCommandDescription | null;
+/** List domains (from the live registry + docs) with their command names. */
+export declare function listAgenticDomains(registry: FikaCommandRegistryView): FikaDomainSummary[];

package/dist/types/embed/agentic/qa.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Deterministic slide QA.
+ *
+ * After a slide is built, run cheap, geometry-and-text checks and return
+ * structured issues the agent can act on in the same turn (ppt-agent's
+ * "quality auto-retry" pattern). Checks cover the common ways generated decks
+ * look broken or lazy: elements overlapping outside the safe margin, text
+ * shrunk below a legibility floor, empty placeholder boxes, contrast that
+ * fails WCAG AA for the palette's role pairs, anchor monotony (same anchor as
+ * the previous slide), and density overload (too many bullets / over-long
+ * bullets).
+ *
+ * Everything here is pure: it inspects a built slide plus the active style and
+ * returns issues; it never mutates state.
+ */
+import type { Slide } from '../../types/slides';
+import type { FikaStylePreset } from './styles';
+import type { CompositionAnchor } from './composition';
+/** A single QA finding, with enough context for the agent to fix it. */
+export interface QaIssue {
+    /** Machine-readable check id. */
+    code: 'overlap' | 'contrast' | 'tooSmall' | 'emptyPlaceholder' | 'anchorRepeat' | 'density' | 'contentEmpty';
+    /** Human-readable explanation. */
+    message: string;
+    /** Severity — 'error' should block, 'warn' should prompt a fix. */
+    severity: 'error' | 'warn';
+    /** Element ids involved (when applicable). */
+    elementIds?: string[];
+}
+/**
+ * Validate a built slide. `previousAnchor` enables the monotony check; pass
+ * undefined for the first slide. Returns an array of issues (possibly empty).
+ */
+export declare function validateSlide(slide: Partial<Slide>, preset: FikaStylePreset, options?: {
+    anchor?: CompositionAnchor;
+    previousAnchor?: CompositionAnchor;
+    feature?: boolean;
+    /**
+     * When true, the slide was built from a layout whose job is to carry body
+     * content (bullets/columns/rows/cards/steps/stats), so a slide that renders
+     * only a title is a defect. Title/section/closing/quote/imageFull layouts
+     * legitimately render little body text and pass `false`.
+     */
+    expectsBody?: boolean;
+    /** Layout id, for a more actionable message. */
+    layoutId?: string;
+}): QaIssue[];

package/dist/types/embed/agentic/styles.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Style presets for the agentic bridge.
+ *
+ * A "style" is a small, curated bundle of design tokens — a color palette with
+ * named *roles* (background / title / body / accent / …), a heading+body font
+ * pairing, and a typographic size scale. Presets are hand-tuned so every
+ * role-pair clears WCAG AA contrast, which lets the agent build good-looking,
+ * legible slides without hand-picking colors or font sizes.
+ *
+ * The agent flow is:
+ *   1. `styles.catalog`  → see the available presets.
+ *   2. `deck.applyStyle` → pick ONE; it sets the deck theme + records `styleId`.
+ *   3. `slides.createFromLayout` → layouts read the active preset's role tokens
+ *      to place themed, contrast-safe elements.
+ *
+ * Only the preset *id* is persisted on the deck theme (`theme.styleId`); the
+ * rich token data lives here in code, so it always renders deterministically
+ * and survives document serialization without bloating the saved deck.
+ */
+import type { SlideTheme } from '../../types/slides';
+/** Named color roles. Every role pairs with a readable foreground/background. */
+export interface FikaStylePalette {
+    /** Default slide background (content slides). */
+    background: string;
+    /** Subtle panel/card fill that sits on `background`. */
+    surface: string;
+    /** Heading/title text on `background`/`surface`. */
+    title: string;
+    /** Body/paragraph text on `background`/`surface`. */
+    body: string;
+    /** De-emphasized text (captions, labels) on `background`/`surface`. */
+    muted: string;
+    /** Hairline rules, dividers, and thin borders. */
+    rule: string;
+    /** Primary accent (bars, highlights, key numbers). */
+    accent: string;
+    /** Secondary accent for variety (second series, alt highlight). */
+    accent2: string;
+    /** Tinted accent wash for soft panels/bands. */
+    accentSoft: string;
+    /** Readable foreground when placed on `accent`. */
+    onAccent: string;
+    /** Feature background for title/section/closing slides (usually dark). */
+    featureBackground: string;
+    /** Title text on `featureBackground`. */
+    featureTitle: string;
+    /** Body/subtitle text on `featureBackground`. */
+    featureBody: string;
+    /** Accent that pops on `featureBackground`. */
+    featureAccent: string;
+}
+/** Typographic size scale in px (canvas units), largest → smallest. */
+export interface FikaStyleScale {
+    /** Hero/cover title. */
+    display: number;
+    /** Standard slide title. */
+    title: number;
+    /** Section header / column heading. */
+    sectionHeader: number;
+    /** Body copy and bullets. */
+    body: number;
+    /** Eyebrow labels, kickers, tags. */
+    label: number;
+    /** Captions, footnotes, source lines. */
+    caption: number;
+}
+export interface FikaStyleFonts {
+    /** Heading/display font family. */
+    heading: string;
+    /** Body/paragraph font family. */
+    body: string;
+}
+/**
+ * The style's signature visual motif — ONE distinctive, repeatable element
+ * that ties a deck together and replaces the generic "accent rule under the
+ * title" slop tell. Layouts render this instead of a bare rectangle. The motif
+ * is described declaratively so every layout family can draw it consistently.
+ */
+export interface FikaStyleMotif {
+    /** Which accent slot the motif draws from. */
+    colorRole: 'accent' | 'accent2';
+    /** The geometric treatment. */
+    shape: 'doubleRule' | 'offsetBlock' | 'roundedChip' | 'hairline';
+    /** Approximate rendered size, in canvas px, for the primary placement. */
+    size: number;
+    /** One-line description surfaced in the style catalog so the agent can picture it. */
+    description: string;
+}
+export interface FikaStylePreset {
+    id: string;
+    /** Human label shown in the catalog. */
+    label: string;
+    /** One-line description of the look & best use. */
+    description: string;
+    fonts: FikaStyleFonts;
+    palette: FikaStylePalette;
+    scale: FikaStyleScale;
+    /** Ordered chart series colors derived from the palette. */
+    chartColors: string[];
+    /** The style's signature motif, drawn by layouts instead of a generic rule. */
+    motif: FikaStyleMotif;
+}
+/** Compact catalog entry (what `styles.catalog` returns to the agent). */
+export interface FikaStyleSummary {
+    id: string;
+    label: string;
+    description: string;
+    fonts: FikaStyleFonts;
+    /** A few representative colors so the agent can picture the look. */
+    preview: {
+        background: string;
+        title: string;
+        body: string;
+        accent: string;
+        featureBackground: string;
+    };
+    /** The style's signature motif description, so the agent knows the deck's throughline. */
+    motif: FikaStyleMotif;
+}
+export declare const DEFAULT_STYLE_ID = "academic";
+export declare const PPTX_STYLE_PRESETS: FikaStylePreset[];
+export declare function getStylePreset(id?: string | null): FikaStylePreset | undefined;
+/** Resolve a usable preset, falling back to the default when id is missing/unknown. */
+export declare function resolveStylePreset(id?: string | null): FikaStylePreset;
+export declare function listStylePresets(): FikaStyleSummary[];
+/**
+ * Build the deck-theme patch for a preset. Sets the inheritable defaults that
+ * manually-created elements pick up (`fontColor`, `fontName`, `backgroundColor`,
+ * `themeColors`) and records `styleId` so layouts can resolve the full preset.
+ */
+export declare function styleThemePatch(preset: FikaStylePreset): Partial<SlideTheme>;

package/dist/types/embed/agentic/templates.d.ts

@@ -0,0 +1,31 @@
+import { type TemplatePayload } from '../../configs/templates';
+import type { Slide, SlideTheme, SlideType } from '../../types/slides';
+export interface FikaTemplateSummary {
+    id: string;
+    name: string;
+    cover: string;
+    origin?: string;
+}
+export interface FikaTemplateSlideEntry {
+    /** Stable slug within this template, e.g. `cover_1`, `content_2`. */
+    slug: string;
+    type: SlideType;
+    description: string;
+    elementCount: number;
+}
+export type FikaTemplateSlidesCatalog = Record<SlideType, FikaTemplateSlideEntry[]>;
+export interface FikaTemplateSlidesCatalogResult {
+    templateId: string;
+    templateName: string;
+    slideCount: number;
+    byType: FikaTemplateSlidesCatalog;
+}
+export declare function listTemplateCatalog(): FikaTemplateSummary[];
+export declare function loadTemplatePayload(templateId: string): Promise<TemplatePayload>;
+export declare function buildTemplateSlidesCatalog(templateId: string): Promise<FikaTemplateSlidesCatalogResult>;
+export declare function resolveTemplateSlide(payload: TemplatePayload, slug: string): {
+    slide: Slide;
+    type: SlideType;
+};
+export declare function assertKnownTemplateId(templateId: string): void;
+export declare function templateThemePatch(payload: TemplatePayload): Partial<SlideTheme> | undefined;