@particle-academy/dark-slide 0.5.2

package/dist/index.d.ts

@@ -0,0 +1,379 @@
+/**
+ * Public deck types — mirror `@particle-academy/fancy-slides`. Inputs are loose
+ * agent JSON, so most fields are optional and extra keys are tolerated; the
+ * Validator is the gate.
+ */
+type ElementType = "text" | "image" | "chart" | "code" | "table" | "shape" | "embed";
+interface ThemeColors {
+    background?: string;
+    text?: string;
+    muted?: string;
+    accent?: string;
+    surface?: string;
+}
+interface ThemeFonts {
+    heading?: string;
+    body?: string;
+    mono?: string;
+}
+interface DeckTheme {
+    name: string;
+    aspectRatio?: number;
+    slideWidth?: number;
+    defaultTransition?: Transition;
+    colors?: ThemeColors;
+    fonts?: ThemeFonts;
+    [key: string]: unknown;
+}
+interface Transition {
+    kind: "none" | "fade" | "slide" | "zoom";
+    duration?: number;
+    direction?: "left" | "right" | "up" | "down";
+}
+interface Animation {
+    effect: "fade" | "fly-in" | "zoom" | "wipe";
+    trigger?: "on-click" | "with-prev" | "after-prev";
+    direction?: "left" | "right" | "up" | "down";
+    duration?: number;
+    delay?: number;
+    order?: number;
+    byParagraph?: boolean;
+}
+interface SlideElement {
+    id: string;
+    type: ElementType;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    rotation?: number;
+    z?: number;
+    locked?: boolean;
+    hidden?: boolean;
+    href?: string;
+    animation?: Animation;
+    content?: string;
+    format?: "markdown" | "html" | "plain";
+    style?: Record<string, unknown>;
+    src?: string;
+    alt?: string;
+    fit?: "fill" | "cover" | "contain" | "scale-down";
+    crop?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    shape?: "rect" | "rounded-rect" | "ellipse" | "triangle" | "line" | "arrow";
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    dashed?: boolean;
+    radius?: number;
+    code?: string;
+    language?: string;
+    codeTheme?: string;
+    columns?: {
+        key: string;
+        label: string;
+    }[];
+    rows?: Record<string, unknown>[];
+    option?: Record<string, unknown>;
+    chartTheme?: string;
+    image?: string;
+    [key: string]: unknown;
+}
+interface SlideBackground {
+    color?: string;
+    image?: string;
+    imageFit?: "contain" | "cover" | "fill";
+    gradient?: string;
+}
+interface Slide {
+    id: string;
+    layout?: string;
+    elements: SlideElement[];
+    background?: SlideBackground;
+    transition?: Transition;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Deck {
+    id: string;
+    title: string;
+    theme: DeckTheme;
+    slides: Slide[];
+    metadata?: Record<string, unknown>;
+}
+interface ValidationError {
+    path: string;
+    expected: string;
+    got: string;
+    value: unknown;
+    hint: string;
+}
+interface RepairResult {
+    ok: boolean;
+    schema: Record<string, unknown>;
+    errors: ValidationError[];
+}
+interface WriteResult {
+    path: string;
+    bytes: number;
+    slides: number;
+}
+interface WriteOptions {
+    tempDir?: string;
+    allowHttpImages?: boolean;
+}
+
+/**
+ * Agent — the structured-tool surface for DarkSlide. Mirrors PHP `Agent`.
+ * Universal methods are synchronous; file-touching methods (`write`) are async
+ * and Node-only (browsers have no sync FS).
+ */
+
+/** Feature-parity baseline with PHP dark-slide; bumped independently on npm. */
+declare const VERSION = "0.5.2";
+type Any$4 = any;
+declare const Agent: {
+    /** Validate a deck without writing. Empty array = valid. */
+    validate(deck: Any$4): ValidationError[];
+    /**
+     * Validate + apply heuristic repairs. Returns `{ ok, schema, errors }` where
+     * `ok` is true when the (possibly repaired) deck validates clean.
+     */
+    validateAndRepair(deck: Any$4): RepairResult;
+    /** PPTX bytes for a deck (no temp file). Universal. Throws SchemaException if invalid. */
+    toBytes(deck: Any$4, options?: WriteOptions): Uint8Array;
+    /** Write a deck to disk as a PPTX file (Node only). Throws SchemaException if invalid. */
+    write(deck: Any$4, path: string, options?: WriteOptions): Promise<WriteResult>;
+    /** Read PPTX bytes back into the Deck schema. Universal. */
+    read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
+    /** Alias for {@see read}. */
+    fromBytes(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
+    /** Plain-text summary of a deck. Mirrors PHP `Agent::describe`. */
+    describe(deck: Any$4): string;
+    /** JSON Schema export for LLM tool-use registration. */
+    jsonSchema(): Record<string, unknown>;
+    version(): string;
+};
+
+/**
+ * Top-level instance API mirroring PHP `DarkSlide`. Delegates to {@see Agent};
+ * exists so DI consumers can hold a configured instance (tempDir /
+ * allowHttpImages) with familiar instance semantics.
+ */
+
+type Any$3 = any;
+declare class DarkSlide {
+    private tempDir;
+    private allowHttpImages;
+    static readonly VERSION = "0.5.2";
+    constructor(tempDir?: string | null, allowHttpImages?: boolean);
+    validate(deck: Any$3): ValidationError[];
+    validateAndRepair(deck: Any$3): RepairResult;
+    write(deck: Any$3, path: string): Promise<WriteResult>;
+    toBytes(deck: Any$3): Uint8Array;
+    private throwIfInvalid;
+    read(input: Uint8Array | ArrayBuffer): Record<string, unknown>;
+    describe(deck: Any$3): string;
+    jsonSchema(): Record<string, unknown>;
+}
+
+/** Thrown by Agent.write/toBytes when the schema is invalid. Mirrors PHP `SchemaException`. */
+declare class SchemaException extends Error {
+    readonly errors: ValidationError[];
+    constructor(message: string, errors: ValidationError[]);
+}
+
+type Any$2 = any;
+/** Liberal schema validator. Mirrors PHP `Schema\Validator`. */
+declare class Validator {
+    validate(deck: Any$2): ValidationError[];
+    private validateSlide;
+    private validateElement;
+}
+
+type Any$1 = any;
+/** Heuristic deck repair. Mirrors PHP `Schema\Repairer`. Never mutates input. */
+declare class Repairer {
+    private idCounter;
+    repair(deckInput: Any$1): Record<string, unknown>;
+    private repairTheme;
+    private repairSlides;
+    private repairSlide;
+    private repairElements;
+    private repairElement;
+    private generateId;
+    private clamp;
+}
+
+/**
+ * Schema constants describing the Deck shape. Mirrors PHP `Schema\Schema`
+ * (and `@particle-academy/fancy-slides` types.ts).
+ */
+declare const Schema: {
+    VERSION: string;
+    ELEMENT_TYPES: readonly ["text", "image", "chart", "code", "table", "shape", "embed"];
+    SLIDE_LAYOUTS: readonly ["blank", "title", "title-content", "two-column", "section-divider", "image-text", "text-image", "quote"];
+    SHAPE_KINDS: readonly ["rect", "rounded-rect", "ellipse", "triangle", "line", "arrow"];
+    TEXT_FORMATS: readonly ["markdown", "html", "plain"];
+    SLIDE_TRANSITION_KINDS: readonly ["none", "fade", "slide", "zoom"];
+    SLIDE_TRANSITION_DIRECTIONS: readonly ["left", "right", "up", "down"];
+    ANIMATION_EFFECTS: readonly ["fade", "fly-in", "zoom", "wipe"];
+    ANIMATION_TRIGGERS: readonly ["on-click", "with-prev", "after-prev"];
+    ANIMATION_DIRECTIONS: readonly ["left", "right", "up", "down"];
+    ANIMATION_DEFAULT_DURATION_MS: number;
+    DEFAULT_SLIDE_WIDTH_EMU: number;
+    DEFAULT_SLIDE_HEIGHT_EMU: number;
+    DEFAULT_THEME_NAME: string;
+    deckRequiredKeys(): string[];
+    slideRequiredKeys(): string[];
+    elementRequiredKeys(): string[];
+    jsonSchema(): Record<string, unknown>;
+};
+
+/**
+ * PPTX (Office Open XML) writer. Faithful 1:1 port of PHP
+ * `DarkSlide\Writer\PptxWriter`. Builds the archive entirely in memory and
+ * returns its bytes via the vendored `zipSync`. Every emitted string mirrors
+ * the PHP writer byte-for-byte.
+ */
+type Any = any;
+declare class PptxWriter {
+    private tempDir;
+    private allowHttpImages;
+    private mediaCounter;
+    private chartCounter;
+    /** Ordered list of media files queued for the archive. */
+    private mediaFiles;
+    /** Ordered list of chart part XML queued for the archive. */
+    private chartFiles;
+    private themeAccent;
+    private tnId;
+    private pendingSlideRels;
+    constructor(tempDir?: string | null, allowHttpImages?: boolean);
+    write(): never;
+    toBytes(deck: Any): Uint8Array;
+    private buildContentTypes;
+    private buildTopRels;
+    private buildCoreProps;
+    private buildAppProps;
+    private buildPresentation;
+    private buildPresentationRels;
+    private buildTheme;
+    private buildSlideMaster;
+    private buildSlideLayoutIdLst;
+    private buildSlideMasterRels;
+    private layoutNumberFor;
+    private layoutTypeFor;
+    private buildSlideLayout;
+    private buildSlideLayoutRels;
+    private buildSlideXml;
+    private buildTransition;
+    private transitionSpeed;
+    private transitionDirection;
+    private buildTiming;
+    private buildTargetEl;
+    private buildStepPar;
+    private buildEffectPar;
+    private animationPresetId;
+    private buildVisibilitySet;
+    private buildFadeEffect;
+    private buildFlyInEffect;
+    private buildZoomEffect;
+    private buildWipeEffect;
+    private animationEffect;
+    private animationTrigger;
+    private animationDirection;
+    private animationDuration;
+    private animationDelay;
+    private buildBackground;
+    private parseGradient;
+    private splitTopLevelCommas;
+    private parseGradientDirection;
+    private buildElementXml;
+    private applyHyperlink;
+    private buildTextShape;
+    private buildImageShape;
+    private imageCropRect;
+    private coverSrcRect;
+    private containedRect;
+    private buildShape;
+    private buildCodeShape;
+    private buildHighlightedCodeBody;
+    private buildTable;
+    private buildTableCell;
+    private buildChart;
+    private chartPreRenderSrc;
+    private buildChartFrame;
+    private buildChartPart;
+    private buildBarChartXml;
+    private buildLineChartXml;
+    private buildPieChartXml;
+    private buildScatterChartXml;
+    private buildCatValAxes;
+    private chartSeriesName;
+    private chartSeriesFill;
+    private chartSeriesLine;
+    private chartCatRef;
+    private chartValRef;
+    private numLit;
+    private numStr;
+    private chartColor;
+    private buildChartPlaceholder;
+    private buildPlaceholder;
+    private buildTextBody;
+    private buildRun;
+    private weightToBold;
+    private alignToAlgn;
+    private xfrmFromFractions;
+    private stageMedia;
+    private loadImageBytes;
+    private extensionForMime;
+    private buildSlideRels;
+    private buildNotesSlideXml;
+    private buildNotesSlideRels;
+}
+
+/**
+ * Best-effort PPTX → Deck reader. Faithful 1:1 port of PHP
+ * `DarkSlide\Reader\PptxReader`. Uses the vendored zip + XML parser instead of
+ * ZipArchive / SimpleXML.
+ */
+declare class PptxReader {
+    private currentSlideRels;
+    private parts;
+    /** Read a PPTX file's bytes into a Deck schema object. */
+    read(bytes: Uint8Array): Record<string, unknown>;
+    fromBytes(bytes: Uint8Array): Record<string, unknown>;
+    private getPart;
+    private extract;
+    private parseSlideRels;
+    private resolveRelTarget;
+    private extractSlideTargets;
+    private readCoreTitle;
+    private readNotesFor;
+    private parseNotesText;
+    private parseSlide;
+    private parseBackground;
+    private gradFillToCss;
+    private readMediaAsDataUri;
+    private guessMimeFromArchivePath;
+    private parseShape;
+    private parsePic;
+    private parseGraphicFrame;
+    private cellText;
+    private paragraphToMarkdown;
+}
+
+interface ZipFile {
+    name: string;
+    data: Uint8Array;
+}
+declare function zipSync(files: ZipFile[]): Uint8Array;
+
+declare function unzipSync(data: Uint8Array): Record<string, Uint8Array>;
+
+export { Agent, type Animation, DarkSlide, type Deck, type DeckTheme, type ElementType, PptxReader, PptxWriter, type RepairResult, Repairer, Schema, SchemaException, type Slide, type SlideBackground, type SlideElement, type ThemeColors, type ThemeFonts, type Transition, VERSION, type ValidationError, Validator, type WriteOptions, type WriteResult, type ZipFile, unzipSync, zipSync };