feat(notes): 阶段三自由画布 OneNote 式核心墨迹（钢笔/荧光笔/橡皮擦 + SVG 平滑笔画 + 色板笔粗）

Author: Aparencia

client/src/features/notes/components/FreeCanvas.tsx

@@ -5,7 +5,10 @@ import { useCallback, useRef, useState, useEffect, useMemo } from 'react';
 import { Plus, Trash2, Copy, Eraser, CheckSquare } from 'lucide-react';
 import FreeTextBlock from './FreeTextBlock';
 import { FreeCanvasOverlays } from './FreeCanvasOverlays';
-import type { FreeCanvasData, FreeCanvasBlock } from '@/types/models';
+import { InkToolbar } from './canvas/InkToolbar';
+import { InkLayer } from './canvas/InkLayer';
+import { useInkDrawing, type InkTool } from '../lib/canvas/useInkDrawing';
+import type { FreeCanvasData, FreeCanvasBlock, InkStroke, InkPoint } from '@/types/models';
 
 interface FreeCanvasProps {
   content: FreeCanvasData | null;
@@ -44,6 +47,44 @@ export default function FreeCanvas({ content, onChange }: FreeCanvasProps) {
   const [selectedBlockIds, setSelectedBlockIds] = useState<Set<string>>(new Set());
   const [paletteOpen, setPaletteOpen] = useState(false);
 
+  // 阶段三：墨迹工具状态 / ink tool state
+  const [inkTool, setInkTool] = useState<InkTool>('select');
+  const [inkColor, setInkColor] = useState('#1e293b');
+  const [inkWidth, setInkWidth] = useState(4);
+  const innerCanvasRef = useRef<HTMLDivElement>(null);
+
+  // 阶段三：墨迹笔画数据与绘制 / ink strokes data & drawing
+  const strokes = data.strokes ?? [];
+
+  const getCanvasPoint = useCallback((clientX: number, clientY: number): InkPoint => {
+    const rect = innerCanvasRef.current?.getBoundingClientRect();
+    if (!rect) return { x: 0, y: 0 };
+    return { x: clientX - rect.left, y: clientY - rect.top };
+  }, []);
+
+  const handleCommitStroke = useCallback((stroke: InkStroke) => {
+    const current = dataRef.current;
+    emitChange({ ...current, strokes: [...(current.strokes ?? []), stroke] });
+  }, [emitChange]);
+
+  const handleErase = useCallback((predicate: (s: InkStroke) => boolean) => {
+    const current = dataRef.current;
+    const prev = current.strokes ?? [];
+    const remaining = prev.filter((s) => !predicate(s));
+    if (remaining.length !== prev.length) {
+      emitChange({ ...current, strokes: remaining });
+    }
+  }, [emitChange]);
+
+  const { currentStroke, handlePointerDown, handlePointerMove, handlePointerUp } = useInkDrawing({
+    tool: inkTool,
+    color: inkColor,
+    width: inkWidth,
+    getCanvasPoint,
+    onCommitStroke: handleCommitStroke,
+    onErase: handleErase,
+  });
+
   // 框选状态
   const [selectionBox, setSelectionBox] = useState<{x1: number; y1: number; x2: number; y2: number} | null>(null);
   const isSelectingRef = useRef(false);
@@ -125,6 +166,7 @@ export default function FreeCanvas({ content, onChange }: FreeCanvasProps) {
 
   // 双击空白区域添加文本块
   const handleCanvasDoubleClick = (e: React.MouseEvent) => {
+    if (inkTool !== 'select') return; // 绘制工具下不新建文本块
     const scrollContainer = scrollContainerRef.current;
     if (!scrollContainer) return;
 
@@ -489,6 +531,7 @@ export default function FreeCanvas({ content, onChange }: FreeCanvasProps) {
         onContextMenu={(e) => e.preventDefault()}
       >
         <div
+          ref={innerCanvasRef}
           style={{
             position: 'relative',
             width: data.canvasWidth,
@@ -511,6 +554,26 @@ export default function FreeCanvas({ content, onChange }: FreeCanvasProps) {
             />
           ))}
 
+          {/* 阶段三：墨迹渲染层 / ink rendering layer */}
+          <InkLayer
+            strokes={strokes}
+            currentStroke={currentStroke}
+            width={data.canvasWidth}
+            height={data.canvasHeight}
+          />
+
+          {/* 阶段三：绘制覆盖层（绘制工具激活时捕获指针事件） */}
+          {inkTool !== 'select' && (
+            <div
+              className="absolute inset-0"
+              style={{ zIndex: 8, cursor: inkTool === 'eraser' ? 'cell' : 'crosshair', touchAction: 'none' }}
+              onPointerDown={handlePointerDown}
+              onPointerMove={handlePointerMove}
+              onPointerUp={handlePointerUp}
+              onPointerLeave={handlePointerUp}
+            />
+          )}
+
           {/* 框选矩形 */}
           {selectionBox && (
             <div
@@ -534,6 +597,16 @@ export default function FreeCanvas({ content, onChange }: FreeCanvasProps) {
         actions={actions}
         onClosePalette={() => setPaletteOpen(false)}
       />
+
+      {/* 阶段三：墨迹工具栏 / ink toolbar */}
+      <InkToolbar
+        tool={inkTool}
+        color={inkColor}
+        width={inkWidth}
+        onToolChange={setInkTool}
+        onColorChange={setInkColor}
+        onWidthChange={setInkWidth}
+      />
     </div>
   );
 }

client/src/features/notes/components/canvas/InkLayer.tsx

@@ -0,0 +1,45 @@
+/**
+ * 墨迹渲染层（SVG）
+ * Ink rendering layer (SVG)
+ *
+ * @ai-context: 阶段三。将已提交笔画 + 进行中笔画渲染为 SVG path（pointsToSvgPath
+ * 平滑）。荧光笔半透明（strokeOpacity 0.4）。pointer-events-none，绘制事件由
+ * FreeCanvas 的绘制覆盖层处理。绝对定位覆盖整个画布（与文本块同坐标系）。
+ * @ai-context: Renders committed + in-progress strokes as smoothed SVG paths;
+ * highlighter is translucent. pointer-events-none (drawing handled by overlay).
+ */
+import { pointsToSvgPath } from '../../lib/canvas/inkGeometry';
+import type { InkStroke } from '@/types/models';
+
+interface InkLayerProps {
+  strokes: InkStroke[];
+  currentStroke: InkStroke | null;
+  width: number;
+  height: number;
+}
+
+export function InkLayer({ strokes, currentStroke, width, height }: InkLayerProps) {
+  const all = currentStroke ? [...strokes, currentStroke] : strokes;
+  if (all.length === 0) return null;
+  return (
+    <svg
+      width={width}
+      height={height}
+      className="absolute inset-0 pointer-events-none"
+      style={{ zIndex: 6 }}
+    >
+      {all.map((s) => (
+        <path
+          key={s.id}
+          d={pointsToSvgPath(s.points)}
+          stroke={s.color}
+          strokeWidth={s.width}
+          strokeOpacity={s.tool === 'highlighter' ? 0.4 : 1}
+          fill="none"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        />
+      ))}
+    </svg>
+  );
+}

client/src/features/notes/components/canvas/InkToolbar.tsx

@@ -0,0 +1,101 @@
+/**
+ * 墨迹工具栏（OneNote 式：选择/钢笔/荧光笔/橡皮 + 色板 + 笔粗）
+ * Ink toolbar (OneNote-style: select/pen/highlighter/eraser + palette + width)
+ *
+ * @ai-context: 阶段三。悬浮于画布顶部居中。钢笔/荧光笔显示色板与笔粗选择；
+ * 选择/橡皮工具隐藏颜色。当前工具高亮。工具/颜色/笔粗变更上抛父级。
+ * @ai-context: Floating top-center toolbar. Color palette & width shown only for
+ * pen/highlighter. Active tool highlighted; changes bubble up to parent.
+ */
+import { MousePointer2, Pen, Highlighter, Eraser } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import type { InkTool } from '../../lib/canvas/useInkDrawing';
+
+/** OneNote 式色板 / OneNote-style palette */
+const INK_COLORS = ['#1e293b', '#64748b', '#dc2626', '#ea580c', '#eab308', '#16a34a', '#2563eb', '#7c3aed'];
+/** 笔粗档位（px） / Width stops */
+const INK_WIDTHS = [2, 4, 7];
+
+interface ToolDef {
+  id: InkTool;
+  icon: React.ComponentType<React.SVGProps<SVGSVGElement> & { strokeWidth?: number | string }>;
+  label: string;
+}
+
+const TOOLS: ToolDef[] = [
+  { id: 'select', icon: MousePointer2, label: '选择（操作文本块）' },
+  { id: 'pen', icon: Pen, label: '钢笔' },
+  { id: 'highlighter', icon: Highlighter, label: '荧光笔' },
+  { id: 'eraser', icon: Eraser, label: '橡皮擦' },
+];
+
+interface InkToolbarProps {
+  tool: InkTool;
+  color: string;
+  width: number;
+  onToolChange: (t: InkTool) => void;
+  onColorChange: (c: string) => void;
+  onWidthChange: (w: number) => void;
+}
+
+export function InkToolbar({ tool, color, width, onToolChange, onColorChange, onWidthChange }: InkToolbarProps) {
+  const showInkOptions = tool === 'pen' || tool === 'highlighter';
+  return (
+    <div className="absolute top-3 left-1/2 -translate-x-1/2 z-20 flex items-center gap-2 px-3 py-2 rounded-kb-lg bg-bg-elevated/95 backdrop-blur border border-border/60 shadow-kb-md">
+      <div className="flex items-center gap-1">
+        {TOOLS.map((t) => {
+          const Icon = t.icon;
+          return (
+            <button
+              key={t.id}
+              onClick={() => onToolChange(t.id)}
+              title={t.label}
+              className={cn(
+                'p-1.5 rounded-kb-sm transition-colors',
+                tool === t.id ? 'bg-brand-500 text-white' : 'text-text-secondary hover:bg-bg-tertiary',
+              )}
+            >
+              <Icon className="w-4 h-4" strokeWidth={1.5} />
+            </button>
+          );
+        })}
+      </div>
+
+      {showInkOptions && (
+        <>
+          <div className="w-px h-5 bg-border/60" />
+          <div className="flex items-center gap-1">
+            {INK_COLORS.map((c) => (
+              <button
+                key={c}
+                onClick={() => onColorChange(c)}
+                title={c}
+                className={cn(
+                  'w-5 h-5 rounded-full border transition-transform',
+                  color === c ? 'border-brand-500 scale-110 ring-1 ring-brand-500/40' : 'border-border/60',
+                )}
+                style={{ backgroundColor: c }}
+              />
+            ))}
+          </div>
+          <div className="w-px h-5 bg-border/60" />
+          <div className="flex items-center gap-1">
+            {INK_WIDTHS.map((w) => (
+              <button
+                key={w}
+                onClick={() => onWidthChange(w)}
+                title={`${w}px`}
+                className={cn(
+                  'w-6 h-6 rounded-kb-sm flex items-center justify-center transition-colors',
+                  width === w ? 'bg-brand-50 text-brand-600' : 'text-text-secondary hover:bg-bg-tertiary',
+                )}
+              >
+                <span className="rounded-full bg-current" style={{ width: w + 1, height: w + 1 }} />
+              </button>
+            ))}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}

client/src/features/notes/lib/canvas/inkGeometry.test.ts

@@ -0,0 +1,70 @@
+/**
+ * inkGeometry 单测：墨迹几何纯函数
+ * Unit tests for ink geometry utilities
+ */
+import { describe, it, expect } from 'vitest';
+import { pointsToSvgPath, distanceToStroke, strokesInRegion } from './inkGeometry';
+import type { InkStroke } from '@/types/models';
+
+function stroke(id: string, points: Array<[number, number]>): InkStroke {
+  return { id, tool: 'pen', color: '#000', width: 2, points: points.map(([x, y]) => ({ x, y })) };
+}
+
+describe('pointsToSvgPath', () => {
+  it('空点返回空字符串', () => {
+    expect(pointsToSvgPath([])).toBe('');
+  });
+
+  it('单点返回极短线段', () => {
+    const d = pointsToSvgPath([{ x: 5, y: 5 }]);
+    expect(d).toContain('M 5 5');
+    expect(d).toContain('L');
+  });
+
+  it('多点生成 M/Q/L 平滑路径', () => {
+    const d = pointsToSvgPath([{ x: 0, y: 0 }, { x: 10, y: 10 }, { x: 20, y: 0 }]);
+    expect(d.startsWith('M 0 0')).toBe(true);
+    expect(d).toContain('Q');
+    expect(d).toContain('L 20 0');
+  });
+});
+
+describe('distanceToStroke', () => {
+  it('空笔画返回 Infinity', () => {
+    expect(distanceToStroke({ x: 0, y: 0 }, stroke('s', []))).toBe(Infinity);
+  });
+
+  it('点到水平线段距离', () => {
+    const s = stroke('s', [[0, 0], [10, 0]]);
+    expect(distanceToStroke({ x: 5, y: 3 }, s)).toBeCloseTo(3);
+  });
+
+  it('点在线段上距离为 0', () => {
+    const s = stroke('s', [[0, 0], [10, 0]]);
+    expect(distanceToStroke({ x: 5, y: 0 }, s)).toBeCloseTo(0);
+  });
+
+  it('取各线段最小距离', () => {
+    const s = stroke('s', [[0, 0], [10, 0], [10, 10]]);
+    expect(distanceToStroke({ x: 10, y: 5 }, s)).toBeCloseTo(0);
+  });
+});
+
+describe('strokesInRegion', () => {
+  it('选中点在区域内的笔画', () => {
+    const strokes = [stroke('in', [[5, 5]]), stroke('out', [[50, 50]])];
+    const ids = strokesInRegion(strokes, { minX: 0, minY: 0, maxX: 10, maxY: 10 });
+    expect(ids).toEqual(['in']);
+  });
+
+  it('笔画任意点在区域内即选中', () => {
+    const strokes = [stroke('cross', [[-5, 5], [5, 5]])];
+    const ids = strokesInRegion(strokes, { minX: 0, minY: 0, maxX: 10, maxY: 10 });
+    expect(ids).toEqual(['cross']);
+  });
+
+  it('无命中返回空', () => {
+    const strokes = [stroke('out', [[50, 50]])];
+    expect(strokesInRegion(strokes, { minX: 0, minY: 0, maxX: 10, maxY: 10 })).toEqual([]);
+  });
+});