@pixel-normal-edit/mcp 2.0.5 → 2.0.7

package/domains/art-tree/perspective_lessons.js

@@ -0,0 +1,138 @@
+const shapes = require('./shapes');
+const perspShapes = require('./perspective_shapes');
+
+/**
+ * Lesson: 1-Point Perspective
+ */
+function lesson1PointPerspective(canvasSize = 32, color = '#2196f3') {
+  const commands = [];
+  const horizonY = Math.floor(canvasSize * 0.4);
+  const vpX = Math.floor(canvasSize * 0.5);
+  const vpY = horizonY;
+
+  // Horizon & VP
+  commands.push(...perspShapes.drawHorizon(canvasSize, horizonY));
+  commands.push(...perspShapes.drawVP(vpX, vpY));
+
+  // Box below horizon (seeing top face)
+  const w = Math.floor(canvasSize * 0.2);
+  const h = Math.floor(canvasSize * 0.15);
+  commands.push(...perspShapes.draw1PointBox(vpX, vpY, Math.floor(canvasSize * 0.2), horizonY + Math.floor(canvasSize * 0.2), w, h, 0.4, color));
+  
+  // Box above horizon (seeing bottom face)
+  commands.push(...perspShapes.draw1PointBox(vpX, vpY, Math.floor(canvasSize * 0.6), horizonY - Math.floor(canvasSize * 0.3), w, h, 0.4, '#e91e63'));
+
+  return commands;
+}
+
+/**
+ * Lesson: 2-Point Perspective
+ */
+function lesson2PointPerspective(canvasSize = 32, color = '#4caf50') {
+  const commands = [];
+  const horizonY = Math.floor(canvasSize * 0.5);
+  const vp1X = Math.floor(canvasSize * 0.1);
+  const vp2X = Math.floor(canvasSize * 0.9);
+  
+  // Horizon & VPs
+  commands.push(...perspShapes.drawHorizon(canvasSize, horizonY));
+  commands.push(...perspShapes.drawVP(vp1X, horizonY));
+  commands.push(...perspShapes.drawVP(vp2X, horizonY));
+
+  // 2-Point Box straddling the horizon
+  const startX = Math.floor(canvasSize * 0.4);
+  const startY = Math.floor(canvasSize * 0.3);
+  const h = Math.floor(canvasSize * 0.4);
+  
+  commands.push(...perspShapes.draw2PointBox(vp1X, horizonY, vp2X, horizonY, startX, startY, h, 0.3, 0.4, color));
+
+  return commands;
+}
+
+/**
+ * Lesson: 3-Point Perspective (Bird's eye view)
+ */
+function lesson3PointPerspective(canvasSize = 32, color = '#ff9800') {
+  const commands = [];
+  const horizonY = Math.floor(canvasSize * 0.2);
+  const vp1X = Math.floor(canvasSize * 0.1);
+  const vp2X = Math.floor(canvasSize * 0.9);
+  const vp3X = Math.floor(canvasSize * 0.5);
+  const vp3Y = Math.floor(canvasSize * 1.5); // VP3 far below (Bird's eye)
+  
+  // Horizon & VPs
+  commands.push(...perspShapes.drawHorizon(canvasSize, horizonY));
+  commands.push(...perspShapes.drawVP(vp1X, horizonY));
+  commands.push(...perspShapes.drawVP(vp2X, horizonY));
+  // VP3 is usually off-canvas, but we draw a line to it to show direction
+  
+  // We approximate a 3-point box by drawing converging vertical lines to VP3
+  const topY = Math.floor(canvasSize * 0.4);
+  const h = Math.floor(canvasSize * 0.4);
+  
+  // Center edge converging to VP3
+  commands.push(shapes.drawLine(vp3X, topY, vp3X, topY+h, color)); // simplified
+  commands.push(shapes.drawLine(vp3X, topY+h, vp3X, vp3Y, '#e0e0e0')); // Guide to VP3
+  
+  // Left and Right top edges to VP1, VP2
+  commands.push(shapes.drawLine(vp3X, topY, vp1X, horizonY, '#e0e0e0'));
+  commands.push(shapes.drawLine(vp3X, topY, vp2X, horizonY, '#e0e0e0'));
+  
+  // Draw the rest of the box structure to simulate 3-point
+  const lX = vp3X - Math.floor(canvasSize * 0.15);
+  const rX = vp3X + Math.floor(canvasSize * 0.2);
+  // Vertical edges also converge to VP3 slightly (foreshortening)
+  commands.push(shapes.drawLine(lX, topY + Math.floor(canvasSize * 0.1), lX + 2, topY + h, color));
+  commands.push(shapes.drawLine(rX, topY + Math.floor(canvasSize * 0.15), rX - 3, topY + h - 5, color));
+
+  return commands;
+}
+
+/**
+ * Lesson: Foreshortening (Sự rút ngắn theo chiều sâu)
+ * Drawing a cylinder pointing directly at the viewer
+ */
+function lessonForeshortening(canvasSize = 32, color = '#9c27b0') {
+  const commands = [];
+  const cx = Math.floor(canvasSize / 2);
+  const cy = Math.floor(canvasSize / 2);
+  
+  // Draw overlapping circles getting larger (coming towards viewer)
+  const numCircles = 5;
+  const maxR = Math.floor(canvasSize * 0.4);
+  const minR = Math.floor(canvasSize * 0.15);
+  
+  for(let i=0; i<numCircles; i++) {
+    const t = i / (numCircles - 1); // 0 to 1
+    // Radius grows exponentially to simulate perspective
+    const r = minR + (maxR - minR) * (t * t); 
+    // Y position shifts slightly to show overlap
+    const y = cy - Math.floor(canvasSize * 0.2) + Math.floor(canvasSize * 0.4 * t);
+    
+    // Draw the circle
+    commands.push(shapes.drawCircle(cx, y, Math.floor(r), color, false));
+  }
+  
+  // Draw bounding lines converging
+  commands.push(shapes.drawLine(cx - minR, cy - Math.floor(canvasSize * 0.2), cx - maxR, cy + Math.floor(canvasSize * 0.2), '#bdbdbd'));
+  commands.push(shapes.drawLine(cx + minR, cy - Math.floor(canvasSize * 0.2), cx + maxR, cy + Math.floor(canvasSize * 0.2), '#bdbdbd'));
+
+  return commands;
+}
+
+function getPerspectiveLessonCatalog() {
+  return [
+    { id: 'persp_1point', name: '1-Point Perspective', description: 'Horizon, 1 VP, Front vs Receding planes', fn: lesson1PointPerspective },
+    { id: 'persp_2point', name: '2-Point Perspective', description: 'Horizon, 2 VPs, Edges facing viewer', fn: lesson2PointPerspective },
+    { id: 'persp_3point', name: '3-Point Perspective', description: '3 VPs (Bird\'s eye view)', fn: lesson3PointPerspective },
+    { id: 'persp_foreshorten', name: 'Foreshortening', description: 'Cylinder pointing at viewer', fn: lessonForeshortening },
+  ];
+}
+
+module.exports = {
+  lesson1PointPerspective,
+  lesson2PointPerspective,
+  lesson3PointPerspective,
+  lessonForeshortening,
+  getPerspectiveLessonCatalog
+};

package/domains/art-tree/perspective_shapes.js

@@ -0,0 +1,96 @@
+const shapes = require('./shapes');
+
+function drawHorizon(canvasSize, yPos) {
+  const commands = [];
+  // Horizon line (Eye level)
+  commands.push(shapes.drawLine(0, yPos, canvasSize, yPos, '#9e9e9e'));
+  return commands;
+}
+
+function drawVP(x, y) {
+  // Red dot for vanishing point
+  return [shapes.drawCircle(x, y, 2, '#ff0000', true)];
+}
+
+function draw1PointBox(vpX, vpY, fX, fY, w, h, depthFactor, color) {
+  const commands = [];
+  // Front face (Front-facing plane)
+  commands.push(shapes.drawRectangle(fX, fY, w, h, color, false));
+  
+  // Orthogonal lines to VP (Depth lines)
+  const guideColor = '#e0e0e0';
+  commands.push(shapes.drawLine(fX, fY, vpX, vpY, guideColor));
+  commands.push(shapes.drawLine(fX+w, fY, vpX, vpY, guideColor));
+  commands.push(shapes.drawLine(fX, fY+h, vpX, vpY, guideColor));
+  commands.push(shapes.drawLine(fX+w, fY+h, vpX, vpY, guideColor));
+
+  // Back face (Receding plane calculation)
+  // Distance from front face to VP
+  const dTLx = vpX - fX;
+  const dTLy = vpY - fY;
+  
+  // Back face coordinates based on depth factor (0 to 1)
+  const bX = fX + Math.floor(dTLx * depthFactor);
+  const bY = fY + Math.floor(dTLy * depthFactor);
+  const bW = Math.floor(w * (1 - depthFactor));
+  const bH = Math.floor(h * (1 - depthFactor));
+  
+  commands.push(shapes.drawRectangle(bX, bY, bW, bH, color, false));
+  
+  // Connect corners
+  commands.push(shapes.drawLine(fX, fY, bX, bY, color));
+  commands.push(shapes.drawLine(fX+w, fY, bX+bW, bY, color));
+  commands.push(shapes.drawLine(fX, fY+h, bX, bY+bH, color));
+  commands.push(shapes.drawLine(fX+w, fY+h, bX+bW, bY+bH, color));
+
+  return commands;
+}
+
+function draw2PointBox(vp1X, vp1Y, vp2X, vp2Y, startX, startY, h, depth1, depth2, color) {
+  const commands = [];
+  const guideColor = '#e0e0e0';
+  
+  // Center vertical edge (faces viewer)
+  commands.push(shapes.drawLine(startX, startY, startX, startY + h, color));
+  
+  // Orthogonals to VP1 (Left)
+  commands.push(shapes.drawLine(startX, startY, vp1X, vp1Y, guideColor));
+  commands.push(shapes.drawLine(startX, startY + h, vp1X, vp1Y, guideColor));
+  
+  // Orthogonals to VP2 (Right)
+  commands.push(shapes.drawLine(startX, startY, vp2X, vp2Y, guideColor));
+  commands.push(shapes.drawLine(startX, startY + h, vp2X, vp2Y, guideColor));
+  
+  // Left vertical edge
+  const lX = startX + Math.floor((vp1X - startX) * depth1);
+  const lY1 = startY + Math.floor((vp1Y - startY) * depth1);
+  const lY2 = (startY + h) + Math.floor((vp1Y - (startY + h)) * depth1);
+  commands.push(shapes.drawLine(lX, lY1, lX, lY2, color));
+  commands.push(shapes.drawLine(startX, startY, lX, lY1, color));
+  commands.push(shapes.drawLine(startX, startY+h, lX, lY2, color));
+
+  // Right vertical edge
+  const rX = startX + Math.floor((vp2X - startX) * depth2);
+  const rY1 = startY + Math.floor((vp2Y - startY) * depth2);
+  const rY2 = (startY + h) + Math.floor((vp2Y - (startY + h)) * depth2);
+  commands.push(shapes.drawLine(rX, rY1, rX, rY2, color));
+  commands.push(shapes.drawLine(startX, startY, rX, rY1, color));
+  commands.push(shapes.drawLine(startX, startY+h, rX, rY2, color));
+
+  // Back vertical edge (intersection of lines from left/right edges to opposite VPs)
+  // For simplicity, we just draw the top and bottom back lines converging to VPs
+  commands.push(shapes.drawLine(lX, lY1, vp2X, vp2Y, guideColor));
+  commands.push(shapes.drawLine(rX, rY1, vp1X, vp1Y, guideColor));
+  
+  // Approximate intersection for top back corner
+  // (In a full implementation, we'd calculate line intersection, here we just show the structure)
+  
+  return commands;
+}
+
+module.exports = {
+  drawHorizon,
+  drawVP,
+  draw1PointBox,
+  draw2PointBox
+};

package/domains/art-tree/perspective_tools.js

@@ -0,0 +1,60 @@
+const { z } = require('zod');
+const { registerTool, sendCommand } = require('../../core/server');
+const perspLessons = require('./perspective_lessons');
+
+const hexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/).describe('Hex color e.g. #ff0000');
+
+/**
+ * Register all perspective tools on the MCP server.
+ * @param {McpServer} server
+ */
+function register(server) {
+  registerTool(server, 'art_tree_lesson_persp_1point',
+    'Lesson: Perspective - 1-Point Perspective (Horizon, 1 VP, Front vs Receding)',
+    { canvasSize: z.number().int().min(16).max(64).default(32), color: hexColor.default('#2196f3') },
+    async (p) => {
+      const commands = perspLessons.lesson1PointPerspective(p.canvasSize, p.color);
+      await Promise.all(commands.map(cmd => sendCommand(cmd)));
+      return { content: [{ type: 'text', text: `✓ 1-Point Perspective lesson completed` }] };
+    });
+
+  registerTool(server, 'art_tree_lesson_persp_2point',
+    'Lesson: Perspective - 2-Point Perspective (Horizon, 2 VPs)',
+    { canvasSize: z.number().int().min(16).max(64).default(32), color: hexColor.default('#4caf50') },
+    async (p) => {
+      const commands = perspLessons.lesson2PointPerspective(p.canvasSize, p.color);
+      await Promise.all(commands.map(cmd => sendCommand(cmd)));
+      return { content: [{ type: 'text', text: `✓ 2-Point Perspective lesson completed` }] };
+    });
+
+  registerTool(server, 'art_tree_lesson_persp_3point',
+    'Lesson: Perspective - 3-Point Perspective (Bird\'s eye view)',
+    { canvasSize: z.number().int().min(16).max(64).default(32), color: hexColor.default('#ff9800') },
+    async (p) => {
+      const commands = perspLessons.lesson3PointPerspective(p.canvasSize, p.color);
+      await Promise.all(commands.map(cmd => sendCommand(cmd)));
+      return { content: [{ type: 'text', text: `✓ 3-Point Perspective lesson completed` }] };
+    });
+
+  registerTool(server, 'art_tree_lesson_persp_foreshorten',
+    'Lesson: Perspective - Foreshortening (Rút ngắn theo chiều sâu)',
+    { canvasSize: z.number().int().min(16).max(64).default(32), color: hexColor.default('#9c27b0') },
+    async (p) => {
+      const commands = perspLessons.lessonForeshortening(p.canvasSize, p.color);
+      await Promise.all(commands.map(cmd => sendCommand(cmd)));
+      return { content: [{ type: 'text', text: `✓ Foreshortening lesson completed` }] };
+    });
+
+  registerTool(server, 'art_tree_lesson_persp_catalog',
+    'Get the catalog of all available Perspective lessons',
+    {},
+    () => {
+      const catalog = perspLessons.getPerspectiveLessonCatalog();
+      const text = catalog.map(l =>
+        `  • ${l.id}: ${l.name} — ${l.description}`
+      ).join('\n');
+      return { content: [{ type: 'text', text: `📚 Perspective Lessons:\n\n${text}` }] };
+    });
+}
+
+module.exports = { register };

package/domains/art-tree/shapes.js

@@ -182,9 +182,24 @@ function drawGrid(startX, startY, cols, rows, cellSize, color) {
   return commands;
 }
 
+/**
+ * Draw a continuous polyline from a list of points.
+ * @param {Array<{x: number, y: number}>} points - Array of vertices
+ * @param {string} color - Hex color
+ * @returns {Array<Object>} Array of Command payloads
+ */
+function drawPolyline(points, color) {
+  const commands = [];
+  for (let i = 0; i < points.length - 1; i++) {
+    commands.push(drawLine(points[i].x, points[i].y, points[i+1].x, points[i+1].y, color));
+  }
+  return commands;
+}
+
 module.exports = {
   PRIMITIVE_ACTIONS,
   drawLine,
+  drawPolyline,
   drawSquare,
   drawRectangle,
   drawCircle,

package/domains/art-tree/structure_lessons.js

@@ -0,0 +1,102 @@
+const shapes = require('./shapes');
+const structureShapes = require('./structure_shapes');
+const shapes3d = require('./3d_shapes');
+const ellipseShapes = require('./ellipse_shapes');
+
+/**
+ * Lesson: XYZ Axes (Vertical, Horizontal, Depth)
+ */
+function lessonXYZAxes(canvasSize = 32, color = '#2196f3') {
+  const commands = [];
+  const cx = Math.floor(canvasSize / 2);
+  const cy = Math.floor(canvasSize / 2);
+  const length = Math.floor(canvasSize * 0.4);
+
+  // Draw the axes
+  commands.push(...structureShapes.drawXYZAxes(cx, cy, length));
+  
+  // Draw a simple box aligned with these axes to show how objects follow them
+  const w = Math.floor(length * 0.5);
+  const h = Math.floor(length * 0.5);
+  const d = Math.floor(length * 0.5);
+  // Using a lighter color for the reference box
+  commands.push(...shapes3d.drawWireframeBox(cx + Math.floor(w/2), cy - Math.floor(h/2), w, h, d, '#e0e0e0'));
+
+  return commands;
+}
+
+/**
+ * Lesson: Complex Structure Analysis (e.g. A Bottle)
+ */
+function lessonComplexStructure(canvasSize = 32, color = '#9c27b0') {
+  const commands = [];
+  const cx = Math.floor(canvasSize / 2);
+  const cy = Math.floor(canvasSize / 2);
+  const totalHeight = Math.floor(canvasSize * 0.8);
+
+  // Draw bottle structure showing cross-sections and central axis
+  commands.push(...structureShapes.drawBottleAnatomy(cx, cy, totalHeight, color));
+
+  return commands;
+}
+
+/**
+ * Lesson: Axis Orientation (Object pointing along different axes)
+ */
+function lessonAxisOrientation(canvasSize = 32, color = '#00bcd4') {
+  const commands = [];
+  const r = Math.floor(canvasSize * 0.1);
+  const h = Math.floor(canvasSize * 0.25);
+  const midY = Math.floor(canvasSize / 2);
+
+  // 1. Standing Cylinder (Oriented along Y axis)
+  const q1 = Math.floor(canvasSize * 0.2);
+  // Draw vertical axis
+  commands.push(shapes.drawLine(q1, midY - h + 5, q1, midY + 5, '#4caf50'));
+  commands.push(shapes.drawEllipse(q1, midY, r, Math.floor(r * 0.3), color, false)); // Base
+  commands.push(shapes.drawEllipse(q1, midY - h, r, Math.floor(r * 0.3), color, false)); // Top
+  commands.push(shapes.drawLine(q1 - r, midY, q1 - r, midY - h, color));
+  commands.push(shapes.drawLine(q1 + r, midY, q1 + r, midY - h, color));
+
+  // 2. Lying Cylinder (Oriented along X axis)
+  const q2 = Math.floor(canvasSize * 0.5);
+  // Draw horizontal axis
+  commands.push(shapes.drawLine(q2 - 5, midY + h - r, q2 + h + 5, midY + h - r, '#f44336'));
+  commands.push(shapes.drawEllipse(q2, midY + h - r, Math.floor(r * 0.3), r, color, false)); // Left base
+  commands.push(shapes.drawEllipse(q2 + h, midY + h - r, Math.floor(r * 0.3), r, color, false)); // Right base
+  commands.push(shapes.drawLine(q2, midY + h - r - r, q2 + h, midY + h - r - r, color));
+  commands.push(shapes.drawLine(q2, midY + h - r + r, q2 + h, midY + h - r + r, color));
+
+  // 3. Tilted/Depth Cylinder (Oriented along an arbitrary angle / Z axis)
+  const q3 = Math.floor(canvasSize * 0.75);
+  const angle = Math.PI / 6; // 30 degrees tilt
+  // Draw tilted axis
+  const dx = Math.floor(h * Math.cos(angle));
+  const dy = Math.floor(h * Math.sin(angle));
+  commands.push(shapes.drawLine(q3 - dx/2 - 5, midY - dy/2 - 5, q3 + dx/2 + 5, midY + dy/2 + 5, '#2196f3'));
+  // Draw rotated ellipses for bases
+  commands.push(...ellipseShapes.drawRotatedEllipse(q3 - dx/2, midY - dy/2, Math.floor(r * 0.3), r, angle, color));
+  commands.push(...ellipseShapes.drawRotatedEllipse(q3 + dx/2, midY + dy/2, Math.floor(r * 0.3), r, angle, color));
+  // Tangent lines for tilted cylinder (approximate)
+  const tx = Math.floor(r * Math.sin(angle));
+  const ty = Math.floor(r * Math.cos(angle));
+  commands.push(shapes.drawLine(q3 - dx/2 - tx, midY - dy/2 + ty, q3 + dx/2 - tx, midY + dy/2 + ty, color));
+  commands.push(shapes.drawLine(q3 - dx/2 + tx, midY - dy/2 - ty, q3 + dx/2 + tx, midY + dy/2 - ty, color));
+
+  return commands;
+}
+
+function getStructureLessonCatalog() {
+  return [
+    { id: 'structure_xyz', name: 'XYZ Axes', description: 'Understanding 3D space directions (Vertical, Horizontal, Depth)', fn: lessonXYZAxes },
+    { id: 'structure_bottle', name: 'Complex Structure (Bottle)', description: 'Analyzing an object using a central axis and multiple cross-sections', fn: lessonComplexStructure },
+    { id: 'structure_orientation', name: 'Axis Orientation', description: 'Identifying which axis an object is oriented along', fn: lessonAxisOrientation },
+  ];
+}
+
+module.exports = {
+  lessonXYZAxes,
+  lessonComplexStructure,
+  lessonAxisOrientation,
+  getStructureLessonCatalog
+};

package/domains/art-tree/structure_shapes.js

@@ -0,0 +1,74 @@
+const shapes = require('./shapes');
+const ellipseShapes = require('./ellipse_shapes');
+
+/**
+ * Draw a 3D coordinate system (X, Y, Z axes) originating from a center point
+ */
+function drawXYZAxes(cx, cy, length) {
+  const commands = [];
+  
+  // Y-axis (Vertical) - Green
+  commands.push(shapes.drawLine(cx, cy, cx, cy - length, '#4caf50'));
+  
+  // X-axis (Horizontal) - Red
+  commands.push(shapes.drawLine(cx, cy, cx + length, cy, '#f44336'));
+  
+  // Z-axis (Depth - Oblique projection) - Blue
+  const dx = Math.floor(length * 0.7 * Math.cos(Math.PI / 6));
+  const dy = Math.floor(length * 0.7 * Math.sin(Math.PI / 6));
+  commands.push(shapes.drawLine(cx, cy, cx - dx, cy + dy, '#2196f3'));
+
+  // Center point
+  commands.push(shapes.drawCircle(cx, cy, 2, '#000000', true));
+
+  return commands;
+}
+
+/**
+ * Draw a complex bottle structure using cross-sections and central axis
+ */
+function drawBottleAnatomy(cx, cy, totalHeight, color) {
+  const commands = [];
+  
+  const bottomY = cy + Math.floor(totalHeight / 2);
+  const topY = cy - Math.floor(totalHeight / 2);
+  
+  // Central vertical axis
+  commands.push(shapes.drawLine(cx, topY - 10, cx, bottomY + 10, '#bdbdbd'));
+  
+  // Define cross sections (y position from bottom, radius)
+  const sections = [
+    { y: bottomY, r: Math.floor(totalHeight * 0.2) },                     // Base
+    { y: bottomY - Math.floor(totalHeight * 0.4), r: Math.floor(totalHeight * 0.2) },   // Body
+    { y: bottomY - Math.floor(totalHeight * 0.7), r: Math.floor(totalHeight * 0.08) },  // Neck start
+    { y: topY, r: Math.floor(totalHeight * 0.08) }                        // Mouth
+  ];
+  
+  // Draw cross section ellipses
+  for (const sec of sections) {
+    // ry is based on perspective (lower = wider perspective, but keep it simple here)
+    const ry = Math.floor(sec.r * 0.3);
+    commands.push(shapes.drawEllipse(cx, sec.y, sec.r, ry, color, false));
+    
+    // Cross point on the axis
+    commands.push(shapes.drawCircle(cx, sec.y, 1, '#ff0000', true));
+  }
+  
+  // Draw outer contour lines
+  for (let i = 0; i < sections.length - 1; i++) {
+    const s1 = sections[i];
+    const s2 = sections[i+1];
+    
+    // Left contour
+    commands.push(shapes.drawLine(cx - s1.r, s1.y, cx - s2.r, s2.y, color));
+    // Right contour
+    commands.push(shapes.drawLine(cx + s1.r, s1.y, cx + s2.r, s2.y, color));
+  }
+  
+  return commands;
+}
+
+module.exports = {
+  drawXYZAxes,
+  drawBottleAnatomy
+};

package/domains/art-tree/structure_tools.js

@@ -0,0 +1,51 @@
+const { z } = require('zod');
+const { registerTool, sendCommand } = require('../../core/server');
+const structureLessons = require('./structure_lessons');
+
+const hexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/).describe('Hex color e.g. #ff0000');
+
+/**
+ * Register all structure and axis tools on the MCP server.
+ * @param {McpServer} server
+ */
+function register(server) {
+  registerTool(server, 'art_tree_lesson_structure_xyz',
+    'Lesson: Structure - XYZ Axes (Vertical, Horizontal, Depth directions)',
+    { canvasSize: z.number().int().min(16).max(64).default(32), color: hexColor.default('#2196f3') },
+    async (p) => {
+      const commands = structureLessons.lessonXYZAxes(p.canvasSize, p.color);
+      await Promise.all(commands.map(cmd => sendCommand(cmd)));
+      return { content: [{ type: 'text', text: `✓ XYZ Axes lesson completed` }] };
+    });
+
+  registerTool(server, 'art_tree_lesson_structure_bottle',
+    'Lesson: Structure - Complex Analysis (Bottle with cross-sections)',
+    { canvasSize: z.number().int().min(16).max(64).default(32), color: hexColor.default('#9c27b0') },
+    async (p) => {
+      const commands = structureLessons.lessonComplexStructure(p.canvasSize, p.color);
+      await Promise.all(commands.map(cmd => sendCommand(cmd)));
+      return { content: [{ type: 'text', text: `✓ Complex Structure (Bottle) lesson completed` }] };
+    });
+
+  registerTool(server, 'art_tree_lesson_structure_orientation',
+    'Lesson: Structure - Axis Orientation (Which axis is it oriented along?)',
+    { canvasSize: z.number().int().min(16).max(64).default(32), color: hexColor.default('#00bcd4') },
+    async (p) => {
+      const commands = structureLessons.lessonAxisOrientation(p.canvasSize, p.color);
+      await Promise.all(commands.map(cmd => sendCommand(cmd)));
+      return { content: [{ type: 'text', text: `✓ Axis Orientation lesson completed` }] };
+    });
+
+  registerTool(server, 'art_tree_lesson_structure_catalog',
+    'Get the catalog of all available Structure lessons',
+    {},
+    () => {
+      const catalog = structureLessons.getStructureLessonCatalog();
+      const text = catalog.map(l =>
+        `  • ${l.id}: ${l.name} — ${l.description}`
+      ).join('\n');
+      return { content: [{ type: 'text', text: `📚 Structure Lessons:\n\n${text}` }] };
+    });
+}
+
+module.exports = { register };

package/domains/art-tree/surface_lessons.js

@@ -0,0 +1,112 @@
+const shapes = require('./shapes');
+const surfaceShapes = require('./surface_shapes');
+
+/**
+ * Lesson: Surface Types (Mặt phẳng, lồi, lõm)
+ */
+function lessonSurfaceTypes(canvasSize = 32, color = '#2196f3') {
+  const commands = [];
+  const midY = Math.floor(canvasSize / 2);
+  const qX = Math.floor(canvasSize / 4);
+  const r = Math.floor(canvasSize * 0.15);
+
+  // 1. Flat Plane (Mặt phẳng)
+  const w = Math.floor(canvasSize * 0.2);
+  commands.push(shapes.drawRectangle(qX - w/2, midY - w/2, w, w, '#4caf50', false));
+  // Add some grid lines to show it's flat
+  commands.push(shapes.drawLine(qX, midY - w/2, qX, midY + w/2, '#4caf50'));
+  commands.push(shapes.drawLine(qX - w/2, midY, qX + w/2, midY, '#4caf50'));
+
+  // 2. Convex Surface (Mặt lồi - e.g. Dome/Sphere)
+  // We use an ellipse that curves outwards (downwards)
+  commands.push(shapes.drawEllipse(qX * 2, midY, r, r, '#ff9800', false));
+  // Cross contour curving DOWN (convex towards viewer)
+  commands.push(shapes.drawEllipse(qX * 2, midY + Math.floor(r*0.2), r, Math.floor(r*0.3), '#ff9800', false));
+
+  // 3. Concave Surface (Mặt lõm - e.g. Bowl)
+  // Draw the top rim of a bowl
+  commands.push(shapes.drawEllipse(qX * 3, midY, r, Math.floor(r*0.3), '#9c27b0', false));
+  // Draw the bottom curve (the inside of the bowl)
+  const bowlPoints = [];
+  for(let i=0; i<=18; i++) {
+    const a = (i/18) * Math.PI; // 0 to 180 degrees (bottom half)
+    bowlPoints.push({ x: Math.round(qX * 3 + r * Math.cos(a)), y: Math.round(midY + r * Math.sin(a)) });
+  }
+  commands.push(shapes.drawPolyline(bowlPoints, '#9c27b0'));
+
+  return commands;
+}
+
+/**
+ * Lesson: Edge Types (Cạnh cứng vuông vức vs Cạnh mềm bo góc)
+ */
+function lessonEdgeTypes(canvasSize = 32, color = '#ff5722') {
+  const commands = [];
+  const qX1 = Math.floor(canvasSize * 0.3);
+  const qX2 = Math.floor(canvasSize * 0.7);
+  const midY = Math.floor(canvasSize / 2);
+  const w = Math.floor(canvasSize * 0.25);
+
+  // 1. Hard Edge (Cạnh cứng - Sharp corners)
+  commands.push(shapes.drawRectangle(qX1 - w/2, midY - w/2, w, w, '#e91e63', false));
+
+  // 2. Soft Edge / Transitional (Cạnh mềm / Mặt chuyển tiếp)
+  // Draw a box with rounded corners (fillet)
+  const r = Math.floor(w * 0.2); // Corner radius
+  const rx = qX2 - w/2;
+  const ry = midY - w/2;
+  
+  // Straight segments
+  commands.push(shapes.drawLine(rx + r, ry, rx + w - r, ry, '#00bcd4')); // Top
+  commands.push(shapes.drawLine(rx + w, ry + r, rx + w, ry + w - r, '#00bcd4')); // Right
+  commands.push(shapes.drawLine(rx + r, ry + w, rx + w - r, ry + w, '#00bcd4')); // Bottom
+  commands.push(shapes.drawLine(rx, ry + r, rx, ry + w - r, '#00bcd4')); // Left
+  
+  // Rounded corners (approximated with small circles for visual simplicity)
+  commands.push(shapes.drawCircle(rx + r, ry + r, r, '#00bcd4', false)); // TL
+  commands.push(shapes.drawCircle(rx + w - r, ry + r, r, '#00bcd4', false)); // TR
+  commands.push(shapes.drawCircle(rx + w - r, ry + w - r, r, '#00bcd4', false)); // BR
+  commands.push(shapes.drawCircle(rx + r, ry + w - r, r, '#00bcd4', false)); // BL
+
+  return commands;
+}
+
+/**
+ * Lesson: Cup Analysis (Analyzing surfaces of a cup)
+ */
+function lessonCupAnalysis(canvasSize = 32, color = '#607d8b') {
+  const cx = Math.floor(canvasSize / 2);
+  const cy = Math.floor(canvasSize / 2);
+  const r = Math.floor(canvasSize * 0.2);
+  const h = Math.floor(canvasSize * 0.4);
+
+  return surfaceShapes.drawCupAnalysis(cx, cy, r, h);
+}
+
+/**
+ * Lesson: Chair Analysis (Analyzing surfaces and edges of a chair)
+ */
+function lessonChairAnalysis(canvasSize = 32, color = '#795548') {
+  const cx = Math.floor(canvasSize / 2);
+  const cy = Math.floor(canvasSize / 2);
+  const w = Math.floor(canvasSize * 0.3);
+
+  return surfaceShapes.drawChairAnalysis(cx, cy, w);
+}
+
+function getSurfaceLessonCatalog() {
+  return [
+    { id: 'surface_types', name: 'Surface Types', description: 'Flat, Convex, Concave planes', fn: lessonSurfaceTypes },
+    { id: 'edge_types', name: 'Edge Types', description: 'Hard vs Soft (Transitional) edges', fn: lessonEdgeTypes },
+    { id: 'surface_cup', name: 'Cup Analysis', description: 'Real object: Convex/Concave walls, Rim, Tube handle', fn: lessonCupAnalysis },
+    { id: 'surface_chair', name: 'Chair Analysis', description: 'Real object: Flat planes, Hard edges, Cylindrical legs', fn: lessonChairAnalysis },
+  ];
+}
+
+module.exports = {
+  lessonSurfaceTypes,
+  lessonEdgeTypes,
+  lessonCupAnalysis,
+  lessonChairAnalysis,
+  getSurfaceLessonCatalog
+};