@xom11/whiteboard 0.11.0 → 0.24.1

package/README.md

@@ -61,6 +61,55 @@ export function ClassroomBoard() {
 }
 ```
 
+### AI dựng hình học 2D (opt-in)
+
+Textarea AI chỉ xuất hiện khi truyền `generateGeometryFigure`. Callback này chạy từ client nên phải gọi một server boundary của ứng dụng; không đưa `ANTHROPIC_API_KEY` vào component hoặc biến môi trường public.
+
+```tsx
+'use client';
+
+import { Whiteboard, type GenerateGeometryFigure } from '@xom11/whiteboard';
+
+const generateGeometryFigure: GenerateGeometryFigure = async (problem, { signal }) => {
+  const response = await fetch('/api/geometry/ai', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ problem }),
+    signal,
+  });
+  return response.json();
+};
+
+export function ClassroomBoard() {
+  return <Whiteboard generateGeometryFigure={generateGeometryFigure} />;
+}
+```
+
+Ví dụ route phía server trong Next.js:
+
+```ts
+import { generateFigure } from '@xom11/whiteboard';
+
+export async function POST(request: Request) {
+  const { problem } = await request.json();
+  const result = await generateFigure(problem, {
+    apiKey: process.env.ANTHROPIC_API_KEY ?? '',
+  });
+  return Response.json(
+    result.ok
+      ? { ok: true, state: result.state }
+      : { ok: false, message: result.message },
+  );
+}
+```
+
+Trong repo package, chạy smoke/eval với API key chỉ ở local shell:
+
+```bash
+ANTHROPIC_API_KEY=... npm run ai:smoke
+ANTHROPIC_API_KEY=... npm run ai:eval -- --limit 5
+```
+
 ## Migration to v0.8.0 (geometry-3d redesign)
 
 `geometry3dStamp` được viết lại theo UX của GeoGebra 3D Calculator:
@@ -110,6 +159,24 @@ import { latexStamp } from '@xom11/whiteboard/latex';
 
 `next` không còn là peer dependency. Whiteboard dùng `React.lazy + Suspense` thuần. Consumer cần Next.js App Router vẫn hoạt động (dist có sẵn `'use client'` directive).
 
+## Extending — thêm stamp mới
+
+Fork repo + viết stamp mới trong ~30 phút. Tham khảo:
+
+- **Howto:** [`docs/superpowers/specs/add-new-stamp-howto.md`](./docs/superpowers/specs/add-new-stamp-howto.md) — 6 bước có sẵn lệnh.
+- **Template:** [`examples/stamp-template/`](./examples/stamp-template/) — skeleton "color-swatch" stamp, copy + đổi `kind`.
+- **Contract test:** mỗi stamp PHẢI pass `runStampContract` (xem [`src/stamps/shared/__tests__/stamp-contract.ts`](./src/stamps/shared/__tests__/stamp-contract.ts)) để đảm bảo `matchesCustomData` / `renderSvgFromCustomData` / roundtrip restore không break.
+- **Catalog:** thêm entry vào [`src/stamps/shared/catalog.ts`](./src/stamps/shared/catalog.ts). Bundle size tự tính qua `scripts/build-catalog.mjs` khi `npm run build`.
+
+```tsx
+import { STAMP_CATALOG, findCatalogEntry } from '@xom11/whiteboard';
+
+// Render admin UI từ catalog
+STAMP_CATALOG.forEach((entry) => {
+  console.log(entry.id, entry.title, entry.bundleSize.js + 'KB gzip');
+});
+```
+
 ## Development
 
 ```bash

package/dist/{ExcalidrawWithMenus-EAVPOPJZ.mjs → ExcalidrawWithMenus-WENZRYYE.mjs}

@@ -1,5 +1,4 @@
 "use client";
-import './chunk-BJTO5JO5.mjs';
 import { Excalidraw, MainMenu, Footer, WelcomeScreen } from '@excalidraw/excalidraw';
 import { jsxs, jsx } from 'react/jsx-runtime';
 
@@ -19,5 +18,5 @@ function ExcalidrawWithMenus(props) {
 }
 
 export { ExcalidrawWithMenus };
-//# sourceMappingURL=ExcalidrawWithMenus-EAVPOPJZ.mjs.map
-//# sourceMappingURL=ExcalidrawWithMenus-EAVPOPJZ.mjs.map
+//# sourceMappingURL=ExcalidrawWithMenus-WENZRYYE.mjs.map
+//# sourceMappingURL=ExcalidrawWithMenus-WENZRYYE.mjs.map

package/dist/ExcalidrawWithMenus-WENZRYYE.mjs.map

@@ -0,0 +1 @@
+{"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"]}

package/dist/catalog.json

@@ -0,0 +1,57 @@
+{
+  "generatedAt": "2026-05-26T06:25:42.573Z",
+  "entries": [
+    {
+      "id": "geometry",
+      "title": "Hình học 2D (JSXGraph)",
+      "version": 1,
+      "experimental": false,
+      "runtimeDeps": [
+        "jsxgraph"
+      ],
+      "bundleSize": {
+        "js": 60.33,
+        "css": 0
+      }
+    },
+    {
+      "id": "latex",
+      "title": "Công thức LaTeX (KaTeX)",
+      "version": 1,
+      "experimental": false,
+      "runtimeDeps": [
+        "katex"
+      ],
+      "bundleSize": {
+        "js": 8.93,
+        "css": 0
+      }
+    },
+    {
+      "id": "geometry3d",
+      "title": "Hình học 3D (JSXGraph view3d)",
+      "version": 2,
+      "experimental": true,
+      "runtimeDeps": [
+        "jsxgraph"
+      ],
+      "bundleSize": {
+        "js": 50.73,
+        "css": 0
+      }
+    },
+    {
+      "id": "graph2d",
+      "title": "Đồ thị hàm số 2D (JSXGraph)",
+      "version": 2,
+      "experimental": true,
+      "runtimeDeps": [
+        "jsxgraph"
+      ],
+      "bundleSize": {
+        "js": 42.91,
+        "css": 0
+      }
+    }
+  ]
+}