@lydt/geogebra-studio 0.0.0-stage → 0.4.0-rc.2

package/dist/utils/geogebra-instance.d.ts

@@ -0,0 +1,252 @@
+import { GeoGebraConfig, GeoGebraAPI, GeoGebraCommandResult, GeoGebraObject } from '../types/geogebra';
+export declare class GeoGebraInstance implements GeoGebraAPI {
+    private browser?;
+    private page?;
+    private isInitialized;
+    private lastActivity;
+    readonly id: string;
+    readonly config: GeoGebraConfig;
+    constructor(config?: GeoGebraConfig);
+    /**
+     * Initialize the GeoGebra instance
+     */
+    initialize(headless?: boolean, browserArgs?: string[]): Promise<void>;
+    /**
+     * Load GeoGebra applet in the browser
+     */
+    private loadGeoGebra;
+    /**
+     * Generate HTML content with GeoGebra applet
+     */
+    private generateAppletHTML;
+    /**
+     * Wait for GeoGebra to be ready
+     */
+    private waitForReady;
+    /**
+     * Execute a GeoGebra command
+     */
+    evalCommand(command: string): Promise<GeoGebraCommandResult>;
+    /**
+     * Execute command and get labels of created objects
+     */
+    evalCommandGetLabels(command: string): Promise<string[]>;
+    /** Invoke a documented GeoGebra Apps API method against the live applet. */
+    callAppsApi(method: string, args?: unknown[], options?: {
+        waitForCallbackIndex?: number;
+        callbackTimeoutMs?: number;
+        callbacks?: Array<{
+            argumentIndex: number;
+            id: string;
+        }>;
+    }): Promise<unknown>;
+    readAppsApiCallbackEvents(id: string, clear?: boolean): Promise<unknown[][]>;
+    /** Enumerate callable methods exposed by the currently loaded official applet API. */
+    listAppsApiMethods(): Promise<string[]>;
+    /**
+     * Delete an object
+     */
+    deleteObject(objName: string): Promise<boolean>;
+    /**
+     * Check if object exists
+     */
+    exists(objName: string): Promise<boolean>;
+    /**
+     * Check if object is defined
+     */
+    isDefined(objName: string): Promise<boolean>;
+    /**
+     * Get all object names
+     */
+    getAllObjectNames(type?: string): Promise<string[]>;
+    /**
+     * Set each object's caption to LaTeX name form ($name$) and show caption label mode.
+     */
+    applyLatexCaptionDefaults(objectNames: string[], showLabel?: boolean): Promise<void>;
+    /**
+     * Apply default visual style settings to objects.
+     * - Point-like objects: point size
+     * - Line-like objects: line thickness
+     */
+    applyDefaultStyleSettings(objectNames: string[], pointSize: number, lineThickness: number): Promise<void>;
+    /**
+     * Get object information
+     */
+    getObjectInfo(objName: string): Promise<GeoGebraObject | null>;
+    /**
+     * Get X coordinate of object
+     */
+    getXcoord(objName: string): Promise<number>;
+    /**
+     * Get Y coordinate of object
+     */
+    getYcoord(objName: string): Promise<number>;
+    /**
+     * Get Z coordinate of object
+     */
+    getZcoord(objName: string): Promise<number>;
+    /**
+     * Get value of object
+     */
+    getValue(objName: string): Promise<number>;
+    /**
+     * Get value string of object
+     */
+    getValueString(objName: string): Promise<string>;
+    /**
+     * Clear construction
+     */
+    newConstruction(): Promise<void>;
+    /**
+     * Reset construction
+     */
+    reset(): Promise<void>;
+    /**
+     * Refresh views
+     */
+    refreshViews(): Promise<void>;
+    /**
+     * Set coordinate system bounds
+     */
+    setCoordSystem(xmin: number, xmax: number, ymin: number, ymax: number): Promise<void>;
+    /**
+     * Set axes visibility
+     */
+    setAxesVisible(xAxis: boolean, yAxis: boolean): Promise<void>;
+    /**
+     * Set grid visibility
+     */
+    setGridVisible(visible: boolean): Promise<void>;
+    /**
+     * Check if GeoGebra is ready
+     */
+    isReady(): Promise<boolean>;
+    /**
+     * Export construction as PNG (base64) with enhanced parameters
+     * GEB-17: Enhanced with validation, retry logic, and better error handling
+     */
+    exportPNG(scale?: number, transparent?: boolean, dpi?: number, width?: number, height?: number): Promise<string>;
+    /**
+     * Export construction as SVG
+     * GEB-17: Enhanced with better validation and error handling, no more placeholder responses
+     */
+    /** Raw PGF is internal input to the mandatory Gikz pipeline. */
+    exportNativeTikZ(): Promise<string>;
+    exportSVG(): Promise<string>;
+    exportPDF(): Promise<string>;
+    exportGGB(): Promise<string>;
+    private nativeExport;
+    /** Load a generated viewer and wait for its native applet and responsive layout. */
+    renderHtml(html: string): Promise<void>;
+    capturePreview(): Promise<Uint8Array>;
+    getConstructionXML(): Promise<string>;
+    /**
+     * Validate that a file path is within the workspace directory to prevent path traversal attacks
+     * @param filePath - The file path to validate
+     * @param workspaceDir - The workspace directory
+     * @returns The validated absolute path
+     * @throws Error if path is outside workspace
+     */
+    validateFilePath(filePath: string, workspaceDir: string): string;
+    /**
+     * Calculate optimal view coordinates to fit all visible objects
+     * @param padding - Padding percentage around objects (default: 0.2 for 20% margin)
+     * @param minRange - Minimum range for each axis (default: 2)
+     * @returns View coordinates {xmin, xmax, ymin, ymax} or null if no visible points
+     */
+    calculateAutoZoomCoordinates(padding?: number, minRange?: number): Promise<{
+        xmin: number;
+        xmax: number;
+        ymin: number;
+        ymax: number;
+    } | null>;
+    /**
+     * Apply auto-zoom to fit all visible objects
+     * @param padding - Padding percentage around objects (default: 0.2 for 20% margin)
+     * @param minRange - Minimum range for each axis (default: 2)
+     * @returns true if auto-zoom was applied, false if no visible points
+     */
+    applyAutoZoom(padding?: number, minRange?: number): Promise<boolean>;
+    /**
+     * Load a GeoGebra construction from a .ggb file
+     * @param ggbBase64OrPath - Either base64-encoded .ggb content or file path
+     */
+    loadGGB(ggbBase64OrPath: string): Promise<void>;
+    /**
+     * Export animation as GIF or video frames
+     * GEB-17: Enhanced with comprehensive applet availability checks
+     */
+    exportAnimation(options?: {
+        duration?: number;
+        frameRate?: number;
+        format?: 'gif' | 'frames';
+        width?: number;
+        height?: number;
+    }): Promise<string | string[]>;
+    /**
+     * Cleanup resources
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get instance state
+     */
+    getState(): {
+        id: string;
+        isReady: boolean;
+        lastActivity: Date;
+        config: GeoGebraConfig;
+    };
+    /**
+     * GEB-17: Enhanced diagnostic method to check applet health
+     */
+    checkAppletHealth(): Promise<{
+        isHealthy: boolean;
+        issues: string[];
+        capabilities: {
+            hasApplet: boolean;
+            hasEvalCommand: boolean;
+            hasExportMethods: boolean;
+            hasAnimationMethods: boolean;
+        };
+        exportAvailability: {
+            png: boolean;
+            svg: boolean;
+            pdf: boolean;
+        };
+    }>;
+    /**
+     * GEB-17: Enhanced method to validate export readiness before attempting export
+     */
+    validateExportReadiness(exportType: 'png' | 'svg' | 'pdf' | 'animation'): Promise<{
+        ready: boolean;
+        issues: string[];
+        recommendations: string[];
+    }>;
+    /**
+     * GEB-17: Retry mechanism for failed operations
+     */
+    private retryOperation;
+    /**
+     * Execute code in the browser context for debugging
+     */
+    debugEvaluate<T>(code: string | Function): Promise<T>;
+    /**
+     * Update last activity timestamp
+     */
+    private updateActivity;
+    /**
+     * Ensure instance is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Animation Methods
+     */
+    setAnimating(objName: string, animate: boolean): Promise<void>;
+    setAnimationSpeed(objName: string, speed: number): Promise<void>;
+    startAnimation(): Promise<void>;
+    stopAnimation(): Promise<void>;
+    isAnimationRunning(): Promise<boolean>;
+    setTrace(objName: string, flag: boolean): Promise<void>;
+    setValue(objName: string, value: number): Promise<void>;
+}
+//# sourceMappingURL=geogebra-instance.d.ts.map

package/dist/utils/geogebra-instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geogebra-instance.d.ts","sourceRoot":"","sources":["../../src/utils/geogebra-instance.ts"],"names":[],"mappings":"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"}