@xom11/whiteboard 0.24.2 → 0.27.0

package/dist/types-zc_Pa0mp.d.ts

@@ -0,0 +1,418 @@
+import { z } from 'zod';
+import { ReactNode, ComponentType, RefAttributes } from 'react';
+import { ExcalidrawElement } from '@excalidraw/excalidraw/element/types';
+
+declare const NameZ: z.ZodString;
+
+type Name = z.infer<typeof NameZ>;
+type DslDistanceSpec = {
+    kind: 'circleRadius';
+    circle: Name;
+    scale?: number;
+    offset?: number;
+} | {
+    kind: 'segmentLength';
+    p1: Name;
+    p2: Name;
+    scale?: number;
+    offset?: number;
+} | {
+    kind: 'literal';
+    value: number;
+    scale?: number;
+    offset?: number;
+};
+type DslPointT = {
+    name: Name;
+    kind: 'free';
+    x: number;
+    y: number;
+} | {
+    name: Name;
+    kind: 'midpoint';
+    p1: Name;
+    p2: Name;
+    visible?: boolean;
+} | {
+    name: Name;
+    kind: 'onSegment';
+    segmentId: Name;
+    t: number;
+} | {
+    name: Name;
+    kind: 'onLine';
+    lineId: Name;
+    t: number;
+} | {
+    name: Name;
+    kind: 'onCircle';
+    circleId: Name;
+    theta: number;
+} | {
+    name: Name;
+    kind: 'perpFoot';
+    from: Name;
+    onLine: Name;
+} | {
+    name: Name;
+    kind: 'circumcenter';
+    vertices: [Name, Name, Name];
+} | {
+    name: Name;
+    kind: 'incenter';
+    vertices: [Name, Name, Name];
+} | {
+    name: Name;
+    kind: 'centroid';
+    vertices: [Name, Name, Name];
+} | {
+    name: Name;
+    kind: 'orthocenter';
+    vertices: [Name, Name, Name];
+} | {
+    name: Name;
+    kind: 'intersection';
+    ref1: Name;
+    ref2: Name;
+    branch?: 0 | 1;
+} | {
+    name: Name;
+    kind: 'secondIntersection';
+    line: Name;
+    circle: Name;
+    other: Name;
+} | {
+    name: Name;
+    kind: 'circleIntersection';
+    c1: Name;
+    c2: Name;
+    which: 0 | 1;
+} | {
+    name: Name;
+    kind: 'circleSecondIntersection';
+    c1: Name;
+    c2: Name;
+    exclude: Name;
+} | {
+    name: Name;
+    kind: 'tangencyPoint';
+    circle: Name;
+    onLine: Name;
+} | {
+    name: Name;
+    kind: 'tangentPointExt';
+    from: Name;
+    circle: Name;
+    which: 0 | 1;
+} | {
+    name: Name;
+    kind: 'arcMidpoint';
+    circle: Name;
+    a: Name;
+    b: Name;
+    notContaining: Name;
+} | {
+    name: Name;
+    kind: 'excenter';
+    vertices: [Name, Name, Name];
+    opposite: Name;
+} | {
+    name: Name;
+    kind: 'reflectPoint';
+    of: Name;
+    through: Name;
+} | {
+    name: Name;
+    kind: 'reflectLine';
+    of: Name;
+    through: Name;
+} | {
+    name: Name;
+    kind: 'pointAtDistance';
+    from: Name;
+    through: Name;
+    distance: DslDistanceSpec;
+};
+type DslShapeT = {
+    name: Name;
+    kind: 'segment';
+    p1: Name;
+    p2: Name;
+} | {
+    name: Name;
+    kind: 'line';
+    p1: Name;
+    p2: Name;
+} | {
+    name: Name;
+    kind: 'ray';
+    origin: Name;
+    through: Name;
+} | {
+    name: Name;
+    kind: 'polygon';
+    vertices: Name[];
+} | {
+    name: Name;
+    kind: 'perpendicular';
+    throughPoint: Name;
+    toLine: Name;
+} | {
+    name: Name;
+    kind: 'parallel';
+    throughPoint: Name;
+    toLine: Name;
+} | {
+    name: Name;
+    kind: 'perpBisector';
+    p1: Name;
+    p2: Name;
+} | {
+    name: Name;
+    kind: 'angleBisector';
+    p1: Name;
+    vertex: Name;
+    p2: Name;
+} | {
+    name: Name;
+    kind: 'lineThrough';
+    points: Name[];
+} | {
+    name: Name;
+    kind: 'radicalAxis';
+    circle1: Name;
+    circle2: Name;
+} | {
+    name: Name;
+    kind: 'tangent';
+    throughPoint: Name;
+    toCircle: Name;
+    branch?: 0 | 1 | 'on';
+} | {
+    name: Name;
+    kind: 'circleCP';
+    center: Name;
+    surfacePoint: Name;
+    visible?: boolean;
+} | {
+    name: Name;
+    kind: 'circle3';
+    p1: Name;
+    p2: Name;
+    p3: Name;
+} | {
+    name: Name;
+    kind: 'circleDiameter';
+    p1: Name;
+    p2: Name;
+    visible?: boolean;
+} | {
+    name: Name;
+    kind: 'circleCR';
+    center: Name;
+    radius: number;
+} | {
+    name: Name;
+    kind: 'incircle';
+    vertices: [Name, Name, Name];
+} | {
+    name: Name;
+    kind: 'excircle';
+    vertices: [Name, Name, Name];
+    opposite: Name;
+};
+type DslInputT = {
+    version: 1;
+    points: DslPointT[];
+    shapes: DslShapeT[];
+};
+
+type SceneObject<A = Record<string, unknown>> = {
+    id: string;
+    kind: string;
+    label: string;
+    visible: boolean;
+    locked: boolean;
+    layer: string;
+    schemaVersion: number;
+    attrs: A;
+};
+type View2D = {
+    readonly bbox: readonly [number, number, number, number];
+    readonly showAxis: boolean;
+    readonly showGrid: boolean;
+};
+type View3D = {
+    readonly bbox3D: readonly [number, number, number, number, number, number];
+    readonly azimuth: number;
+    readonly elevation: number;
+};
+type ViewGraph2D = {
+    readonly xMin: number;
+    readonly xMax: number;
+    readonly yMin: number;
+    readonly yMax: number;
+    readonly showAxis: boolean;
+    readonly showGrid: boolean;
+};
+type StateMeta = {
+    readonly domain: '2d';
+    readonly version: number;
+    readonly view: View2D;
+} | {
+    readonly domain: '3d';
+    readonly version: number;
+    readonly view: View3D;
+} | {
+    readonly domain: 'graph2d';
+    readonly version: number;
+    readonly view: ViewGraph2D;
+};
+type State = {
+    readonly objects: Readonly<Record<string, SceneObject>>;
+    readonly order: readonly string[];
+    readonly counter: number;
+    readonly meta: StateMeta;
+};
+
+/** Minimal client-safe response required by the geometry AI editor. */
+type AiFigureUiResult = {
+    ok: true;
+    state: State;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Progress event emitted bởi streaming generator. Số token output đã sinh.
+ * Editor dùng để hiển thị "Đang nhận N token..." realtime.
+ */
+interface AiFigureProgress {
+    /** Số token output đã sinh tính đến lúc emit. */
+    tokens: number;
+}
+/**
+ * Consumer-provided bridge to a server-side `generateFigure()` call.
+ * Implementations must keep API credentials outside the browser bundle.
+ *
+ * `onProgress` là optional: nếu consumer dùng streaming endpoint (SSE),
+ * forward chunk events vào đây. Non-streaming impl bỏ qua.
+ *
+ * `currentDsl` (MỚI cho multi-step refine): khi caller có hình hiện tại
+ * (state.order.length > 0) và muốn AI sửa/thêm → pass currentDsl. Consumer
+ * branch sang refine endpoint. Không pass → build endpoint cũ.
+ */
+type GenerateGeometryFigure = (problem: string, options: {
+    signal: AbortSignal;
+    onProgress?: (info: AiFigureProgress) => void;
+    currentDsl?: DslInputT;
+}) => Promise<AiFigureUiResult>;
+/**
+ * Kết quả trả về từ `restoreFileFromCustomData`. Chứa đủ thông tin để
+ * consumer gọi `api.addFiles(...)`.
+ */
+interface RestoredStampFile {
+    fileId: string;
+    dataURL: string;
+    mimeType: 'image/svg+xml' | 'image/png';
+}
+/**
+ * Tối thiểu mọi custom data của stamp cần có. Các stamp cụ thể (geometry,
+ * latex, ...) extend interface này với fields riêng.
+ */
+interface BaseStampCustomData {
+    kind: string;
+    version: number;
+}
+/**
+ * Props mà mỗi StampHost nhận từ Whiteboard. Host component tự
+ * quản lý state nội bộ (panel ref, undo stack, displayMode...) — main view
+ * chỉ điều phối show/hide.
+ */
+interface StampHostProps {
+    api: any;
+    /**
+     * Element đang re-edit (double-click) hoặc null nếu đang tạo mới.
+     * Host tự parse customData để load state ban đầu.
+     */
+    editingElement: {
+        id: string;
+        customData: unknown;
+    } | null;
+    /** Đóng stamp panel (gọi sau khi insert hoặc khi user huỷ). */
+    onClose: () => void;
+    /** Dark theme flag. */
+    isDark: boolean;
+    /** Optional client-safe bridge for the geometry-2d AI prompt editor. */
+    generateGeometryFigure?: GenerateGeometryFigure;
+}
+/**
+ * Imperative API mà main view truy cập qua ref:
+ *   - tryInsert(): khi user click ra ngoài → auto-commit nếu valid.
+ *     Trả về true nếu chèn thành công, false nếu chưa có nội dung.
+ *   - hasContent(): có nội dung để chèn không.
+ */
+interface StampHostHandle {
+    tryInsert(): boolean;
+    hasContent(): boolean;
+}
+/**
+ * Component contract của Host. Chấp nhận cả `forwardRef` thông thường lẫn
+ * `React.lazy(() => import('./host'))` (LazyExoticComponent forwards ref).
+ */
+type StampHostComponent = ComponentType<StampHostProps & RefAttributes<StampHostHandle>>;
+/**
+ * Định nghĩa 1 loại stamp. Mỗi stamp khai báo:
+ *   - kind: unique string (khớp với customData.kind)
+ *   - phím tắt + UI toolbar
+ *   - cách nhận biết customData thuộc về stamp này (matchesCustomData)
+ *   - cách re-render SVG từ customData (cho restore sau reload)
+ *   - Host component: bọc trọn editor + left panel + insert logic
+ *
+ * Main view dispatch generic: `<stamp.Host ... />` — không cần biết kind.
+ */
+interface StampType<TCustomData extends BaseStampCustomData = BaseStampCustomData> {
+    /** Unique kind. VD: 'geometry', 'latex'. Phải khớp với customData.kind. */
+    kind: string;
+    /** Phím tắt mở/đóng stamp (lowercase, 1 ký tự). VD: 'g', 'l'. */
+    shortcutKey: string;
+    /** Chữ hiển thị overlay góc dưới nút toolbar (e.g. "G"). */
+    toolbarLabel: string;
+    /** Tooltip + aria-label của nút toolbar. */
+    toolbarTitle: string;
+    /** Icon SVG (ReactNode) trong nút toolbar. */
+    toolbarIcon: ReactNode;
+    /** Test data-testid cho nút toolbar (optional). */
+    toolbarTestId?: string;
+    /** Type guard: customData có thuộc về stamp này không. */
+    matchesCustomData(data: unknown): data is TCustomData;
+    /**
+     * Re-render SVG từ customData. Dùng khi restore math-stamp file sau reload
+     * page (Excalidraw không persist binary file payload, chỉ giữ fileId trong
+     * element). SVG render với light palette (nét đậm) — Excalidraw tự đảo
+     * màu trong dark mode qua CSS filter.
+     */
+    renderSvgFromCustomData(data: TCustomData): Promise<string>;
+    /**
+     * Regenerate file SVG/PNG cho element thuộc stamp này khi reload từ persisted
+     * snapshot. Trả về `RestoredStampFile` để consumer gọi `api.addFiles`, hoặc
+     * `null` nếu element không cần file (vd stamp chỉ là text overlay).
+     *
+     * Khi method này có mặt, `restoreMissingStampFiles` sẽ ưu tiên gọi method
+     * này thay vì dùng `renderSvgFromCustomData`. Stamp tự chịu trách nhiệm lấy
+     * `fileId` từ element và render file.
+     */
+    restoreFileFromCustomData?: (element: ExcalidrawElement) => Promise<RestoredStampFile | null>;
+    /**
+     * Host component bọc toàn bộ UI editing (panel + left panel + insert
+     * handler). Whiteboard mount Host khi activeStamp khớp kind.
+     */
+    Host: StampHostComponent;
+    /**
+     * Đánh dấu stamp chưa production-ready. Consumer mặc định bỏ qua
+     * (xem `DEFAULT_STAMPS` chỉ gồm stamp không `experimental`).
+     */
+    experimental?: boolean;
+}
+
+export type { AiFigureProgress as A, BaseStampCustomData as B, DslInputT as D, GenerateGeometryFigure as G, StampType as S, AiFigureUiResult as a, State as b };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xom11/whiteboard",
-  "version": "0.24.2",
+  "version": "0.27.0",
   "private": false,
   "description": "Excalidraw + JSXGraph + KaTeX whiteboard component (drawing, geometry stamps, LaTeX stamps).",
   "repository": {
@@ -73,6 +73,7 @@
     "demo": "vite --config scripts/demo/vite.config.ts",
     "ai:eval": "tsx scripts/eval-ai.ts",
     "ai:smoke": "tsx scripts/smoke-ai.ts",
+    "check:matrix": "tsx scripts/check-construct-matrix.ts",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "peerDependencies": {
@@ -97,6 +98,7 @@
     "@typescript-eslint/eslint-plugin": "^8.59.4",
     "@typescript-eslint/parser": "^8.59.4",
     "@vitejs/plugin-react": "^6.0.2",
+    "dotenv": "^17.4.2",
     "eslint": "^9.39.4",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
@@ -116,10 +118,17 @@
     "vite": "^8.0.13"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.161",
     "@anthropic-ai/sdk": "^0.98.0",
     "immer": "^10.2.0",
     "pdfjs-dist": "^5.7.284",
+    "tesseract.js": "^7.0.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.25.2"
+  },
+  "overrides": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "zod": "$zod"
+    }
   }
 }

package/dist/ExcalidrawWithMenus-WENZRYYE.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/ExcalidrawWithMenus.tsx"],"names":[],"mappings":";;;AAiBO,SAAS,oBAAoB,KAAA,EAAwB;AAC1D,EAAA,MAAM,EAAE,QAAA,EAAU,GAAG,IAAA,EAAK,GAAI,KAAA;AAC9B,EAAA,uBACE,IAAA,CAAC,UAAA,EAAA,EAAY,GAAG,IAAA,EAEd,QAAA,EAAA;AAAA,oBAAA,IAAA,CAAC,QAAA,EAAA,EACC,QAAA,EAAA;AAAA,sBAAA,GAAA,CAAC,QAAA,CAAS,YAAA,CAAa,SAAA,EAAtB,EAAgC,CAAA;AAAA,sBACjC,GAAA,CAAC,QAAA,CAAS,YAAA,CAAa,WAAA,EAAtB,EAAkC,CAAA;AAAA,sBACnC,GAAA,CAAC,QAAA,CAAS,YAAA,CAAa,WAAA,EAAtB,EAAkC,CAAA;AAAA,sBACnC,GAAA,CAAC,QAAA,CAAS,YAAA,CAAa,WAAA,EAAtB,EAAkC;AAAA,KAAA,EACrC,CAAA;AAAA,oBAEA,GAAA,CAAC,MAAA,EAAA,EACC,QAAA,kBAAA,GAAA,CAAC,MAAA,EAAA,EAAK,CAAA,EACR,CAAA;AAAA,oBAGA,GAAA,CAAC,aAAA,EAAA,EACC,QAAA,kBAAA,GAAA,CAAC,MAAA,EAAA,EAAK,CAAA,EACR,CAAA;AAAA,IACC;AAAA,GAAA,EACH,CAAA;AAEJ","file":"ExcalidrawWithMenus-WENZRYYE.mjs","sourcesContent":["'use client';\n\n// Client-only wrapper around Excalidraw that lets us reach for static helpers\n// like `MainMenu.DefaultItems.*`. Whiteboard dynamic-imports this\n// file so SSR never evaluates @excalidraw/excalidraw, while inside this file we\n// can use plain static imports (the entire module loads on the client).\n\nimport React from 'react';\nimport {\n  Excalidraw,\n  MainMenu,\n  Footer,\n  WelcomeScreen,\n} from '@excalidraw/excalidraw';\n \ntype ExcalidrawProps = any;\n\nexport function ExcalidrawWithMenus(props: ExcalidrawProps) {\n  const { children, ...rest } = props;\n  return (\n    <Excalidraw {...rest}>\n      {/* Replace default menu with curated items — no socials/help/branding */}\n      <MainMenu>\n        <MainMenu.DefaultItems.LoadScene />\n        <MainMenu.DefaultItems.SaveAsImage />\n        <MainMenu.DefaultItems.ClearCanvas />\n        <MainMenu.DefaultItems.ToggleTheme />\n      </MainMenu>\n      {/* Footer slot with no content suppresses default \"Made with Excalidraw\" link */}\n      <Footer>\n        <span />\n      </Footer>\n      {/* WelcomeScreen slot (empty) prevents the default Excalidraw welcome panel\n       *  (which includes the Excalidraw logo and social links) from appearing. */}\n      <WelcomeScreen>\n        <span />\n      </WelcomeScreen>\n      {children}\n    </Excalidraw>\n  );\n}\n"]}