@xom11/whiteboard 0.31.0 → 0.33.0

package/dist/{chunk-JJ4FPCBE.mjs → chunk-4EXRNZRX.mjs}

@@ -1,6 +1,6 @@
 "use client";
 import { labelOpts, compile, validate } from './chunk-CH6SFONH.mjs';
-import { createEmptyState } from './chunk-73Q7ADVL.mjs';
+import { createEmptyState } from './chunk-MNHOFOM5.mjs';
 import { registerKind } from './chunk-B4NJJZFR.mjs';
 import * as React from 'react';
 
@@ -81,8 +81,377 @@ function constraintRefs(c) {
       return [c.polygonId];
     case "onSphere":
       return [c.sphereId];
-    default:
+    case "midpoint":
+      return [c.p1, c.p2];
+    case "centroid":
+      return [...c.vertices];
+    case "intersectionLines":
+      return [c.a1, c.b1, c.a2, c.b2];
+    case "intersectionLinePlane":
+      return [c.a, c.b, c.plane];
+    case "perpFootLine":
+      return [c.from, c.a, c.b];
+    case "perpFootPlane":
+      return [c.from, c.plane];
+    case "circumsphereCenter":
+      return [...c.vertices];
+    case "pyramidInsphereCenter":
+      return [c.apex, ...c.vertices];
+    case "faceCircumcenter":
+      return [...c.vertices];
+    case "pointAboveFace":
+      return [c.base, c.apex, ...c.vertices];
+    // Kind KHÔNG có ref scene-object (toạ độ literal): liệt kê TƯỜNG MINH để
+    // exhaustive never-guard bên dưới buộc khai báo khi thêm constraint kind mới
+    // (mô phỏng constraintRefs2D — quên case = cascade-delete/deps sai âm thầm).
+    case "free":
+    case "onGround":
+    case "onAxis":
+      return [];
+    default: {
       return [];
+    }
+  }
+}
+
+// src/core/scene/kinds/constraint3d-math.ts
+function sub(a, b) {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+}
+function add(a, b) {
+  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
+function scale(a, k) {
+  return [a[0] * k, a[1] * k, a[2] * k];
+}
+function dot(a, b) {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+function cross(a, b) {
+  return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function norm(a) {
+  return Math.sqrt(dot(a, a));
+}
+function normalize(a) {
+  const n = norm(a);
+  return n === 0 ? a : scale(a, 1 / n);
+}
+var MAX_REC_DEPTH = 512;
+var _recDepth = 0;
+function getPointWorld(id, state) {
+  const obj = state.objects[id];
+  if (!obj || obj.kind !== "point3d") {
+    throw new Error(`constraintMath: point ${id} not found`);
+  }
+  const attrs = obj.attrs;
+  return constraintToWorld(attrs.constraint, state);
+}
+function getPlaneBasis(planeObj, state) {
+  const a = planeObj.attrs;
+  let p1, p2, p3;
+  if (a.construction) {
+    const r = planeConstructionWorld(a.construction, state);
+    p1 = r.p1;
+    p2 = r.p2;
+    p3 = r.p3;
+  } else {
+    p1 = getPointWorld(a.p1, state);
+    p2 = getPointWorld(a.p2, state);
+    p3 = getPointWorld(a.p3, state);
+  }
+  const basis1 = sub(p2, p1);
+  const tmp = sub(p3, p1);
+  const normal = normalize(cross(basis1, tmp));
+  const basis2 = cross(normal, basis1);
+  return { origin: p1, basis1, basis2, normal };
+}
+function orthoBasisFromNormal(n) {
+  const seed = Math.abs(n[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0];
+  const basis1 = normalize(cross(n, seed));
+  const basis2 = cross(n, basis1);
+  return { basis1, basis2 };
+}
+function planeConstructionWorld(c, state) {
+  if (_recDepth >= MAX_REC_DEPTH) throw new Error("planeConstructionWorld: \u0111\u1EC7 quy qu\xE1 s\xE2u \u2014 chu tr\xECnh tham chi\u1EBFu m\u1EB7t?");
+  _recDepth++;
+  try {
+    return planeConstructionWorldInner(c, state);
+  } finally {
+    _recDepth--;
+  }
+}
+function planeConstructionWorldInner(c, state) {
+  switch (c.kind) {
+    case "planeParallelThrough": {
+      const P = getPointWorld(c.point, state);
+      const ref = state.objects[c.refPlane];
+      if (!ref || ref.kind !== "plane3d") throw new Error("planeParallelThrough: m\u1EB7t tham chi\u1EBFu thi\u1EBFu");
+      const { basis1, basis2 } = getPlaneBasis(ref, state);
+      if (norm(basis1) < 1e-12 || norm(basis2) < 1e-12) {
+        return { p1: P, p2: add(P, [1, 0, 0]), p3: add(P, [0, 1, 0]) };
+      }
+      return { p1: P, p2: add(P, basis1), p3: add(P, basis2) };
+    }
+    case "planePerpToLine": {
+      const P = getPointWorld(c.point, state);
+      const dir = sub(getPointWorld(c.lineB, state), getPointWorld(c.lineA, state));
+      const dn = norm(dir);
+      if (dn < 1e-12) return { p1: P, p2: add(P, [1, 0, 0]), p3: add(P, [0, 1, 0]) };
+      const { basis1, basis2 } = orthoBasisFromNormal(scale(dir, 1 / dn));
+      return { p1: P, p2: add(P, basis1), p3: add(P, basis2) };
+    }
+    default: {
+      throw new Error("planeConstructionWorld: kind kh\xF4ng h\u1ED7 tr\u1EE3");
+    }
+  }
+}
+function lineDefiningPointIds(line) {
+  if (line.kind === "line3d" || line.kind === "segment3d") {
+    const a = line.attrs;
+    return a.p1 && a.p2 ? [a.p1, a.p2] : null;
+  }
+  if (line.kind === "ray3d") {
+    const a = line.attrs;
+    return [a.origin, a.through];
+  }
+  if (line.kind === "vector3d") {
+    const a = line.attrs;
+    return [a.from, a.to];
+  }
+  return null;
+}
+function lineEndpointsWorld(lineId, state, ctx) {
+  const line = state.objects[lineId];
+  if (!line) throw new Error(`${ctx}: \u0111\u01B0\u1EDDng ${lineId} kh\xF4ng t\u1ED3n t\u1EA1i`);
+  const ids = lineDefiningPointIds(line);
+  if (!ids) throw new Error(`${ctx}: kind ${line.kind} kh\xF4ng ph\u1EA3i \u0111\u01B0\u1EDDng`);
+  return { a: getPointWorld(ids[0], state), b: getPointWorld(ids[1], state) };
+}
+function lineLineClosestMidpoint(A, B, C, D) {
+  const u = sub(B, A), v = sub(D, C), w0 = sub(A, C);
+  const a = dot(u, u), b = dot(u, v), cc = dot(v, v), d = dot(u, w0), e = dot(v, w0);
+  const denom = a * cc - b * b;
+  if (Math.abs(denom) < 1e-12) return scale(add(A, C), 0.5);
+  const sc = (b * e - cc * d) / denom;
+  const tc = (a * e - b * d) / denom;
+  return scale(add(add(A, scale(u, sc)), add(C, scale(v, tc))), 0.5);
+}
+function planeOriginNormal(planeId, state, ctx) {
+  const plane = state.objects[planeId];
+  if (!plane || plane.kind !== "plane3d") throw new Error(`${ctx}: m\u1EB7t ph\u1EB3ng ${planeId} thi\u1EBFu`);
+  const { origin, normal } = getPlaneBasis(plane, state);
+  return { origin, normal };
+}
+function lineConstructionWorld(c, state) {
+  switch (c.kind) {
+    case "planePlaneIntersection": {
+      const P1 = planeOriginNormal(c.plane1, state, "planePlaneIntersection");
+      const P2 = planeOriginNormal(c.plane2, state, "planePlaneIntersection");
+      const d = cross(P1.normal, P2.normal);
+      const dd = dot(d, d);
+      if (dd < 1e-12) {
+        return { a: P1.origin, b: add(P1.origin, P2.normal) };
+      }
+      const c1 = dot(P1.normal, P1.origin);
+      const c2 = dot(P2.normal, P2.origin);
+      const p0 = scale(add(scale(cross(P2.normal, d), c1), scale(cross(d, P1.normal), c2)), 1 / dd);
+      return { a: p0, b: add(p0, d) };
+    }
+    case "lineParallelThrough": {
+      const P = getPointWorld(c.point, state);
+      const dir = sub(getPointWorld(c.dirB, state), getPointWorld(c.dirA, state));
+      if (norm(dir) < 1e-12) return { a: P, b: add(P, [1, 0, 0]) };
+      return { a: P, b: add(P, dir) };
+    }
+    case "linePerpToPlane": {
+      const P = getPointWorld(c.point, state);
+      const { normal } = planeOriginNormal(c.plane, state, "linePerpToPlane");
+      return { a: P, b: add(P, normal) };
+    }
+    default: {
+      throw new Error("lineConstructionWorld: kind kh\xF4ng h\u1ED7 tr\u1EE3");
+    }
+  }
+}
+function solve3(M, b) {
+  const det3 = (m) => m[0][0] * (m[1][1] * m[2][2] - m[1][2] * m[2][1]) - m[0][1] * (m[1][0] * m[2][2] - m[1][2] * m[2][0]) + m[0][2] * (m[1][0] * m[2][1] - m[1][1] * m[2][0]);
+  const det = det3(M);
+  if (Math.abs(det) < 1e-9) return null;
+  const colDet = (j) => {
+    const A = M.map((r) => r.slice());
+    for (let i = 0; i < 3; i++) A[i][j] = b[i];
+    return det3(A);
+  };
+  return [colDet(0) / det, colDet(1) / det, colDet(2) / det];
+}
+function constraintToWorld(c, state) {
+  if (_recDepth >= MAX_REC_DEPTH) throw new Error("constraintToWorld: \u0111\u1EC7 quy qu\xE1 s\xE2u \u2014 chu tr\xECnh tham chi\u1EBFu?");
+  _recDepth++;
+  try {
+    return constraintToWorldInner(c, state);
+  } finally {
+    _recDepth--;
+  }
+}
+function constraintToWorldInner(c, state) {
+  switch (c.kind) {
+    case "free":
+      return [c.x, c.y, c.z];
+    case "onGround":
+      return [c.x, c.y, 0];
+    case "onAxis": {
+      if (c.axis === "x") return [c.t, 0, 0];
+      if (c.axis === "y") return [0, c.t, 0];
+      return [0, 0, c.t];
+    }
+    case "onPlane": {
+      const plane = state.objects[c.planeId];
+      if (!plane || plane.kind !== "plane3d") throw new Error("onPlane: plane missing");
+      const { origin, basis1, basis2 } = getPlaneBasis(plane, state);
+      return add(add(origin, scale(basis1, c.u)), scale(basis2, c.v));
+    }
+    case "onLine": {
+      const { a, b } = lineEndpointsWorld(c.lineId, state, "onLine");
+      return add(a, scale(sub(b, a), c.t));
+    }
+    case "onPolygon": {
+      const pg = state.objects[c.polygonId];
+      if (!pg || pg.kind !== "polygon3d") throw new Error("onPolygon: parent missing");
+      const v = pg.attrs.vertices;
+      if (v.length < 3) throw new Error("onPolygon: < 3 vertices");
+      const p1 = getPointWorld(v[0], state);
+      const p2 = getPointWorld(v[1], state);
+      const p3 = getPointWorld(v[2], state);
+      const basis1 = sub(p2, p1);
+      const tmp = sub(p3, p1);
+      const normal = normalize(cross(basis1, tmp));
+      const basis2 = cross(normal, basis1);
+      return add(add(p1, scale(basis1, c.u)), scale(basis2, c.v));
+    }
+    case "onSphere": {
+      const sph = state.objects[c.sphereId];
+      if (!sph || sph.kind !== "sphere3d") throw new Error("onSphere: parent missing");
+      const a = sph.attrs;
+      const center = getPointWorld(a.center, state);
+      const surface = getPointWorld(a.surfacePoint, state);
+      const radius = norm(sub(surface, center));
+      const x = center[0] + radius * Math.sin(c.phi) * Math.cos(c.theta);
+      const y = center[1] + radius * Math.sin(c.phi) * Math.sin(c.theta);
+      const z = center[2] + radius * Math.cos(c.phi);
+      return [x, y, z];
+    }
+    // ───── Điểm phái sinh (v1) ─────
+    case "midpoint": {
+      const p1 = getPointWorld(c.p1, state);
+      const p2 = getPointWorld(c.p2, state);
+      return scale(add(p1, p2), 0.5);
+    }
+    case "centroid": {
+      const n = c.vertices.length;
+      if (n === 0) return [0, 0, 0];
+      let acc = [0, 0, 0];
+      for (const id of c.vertices) acc = add(acc, getPointWorld(id, state));
+      return scale(acc, 1 / n);
+    }
+    case "circumsphereCenter": {
+      const P = c.vertices.map((id) => getPointWorld(id, state));
+      if (P.length < 4) return P.length ? P[0] : [0, 0, 0];
+      const p0 = P[0];
+      const M = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];
+      const rhs = [0, 0, 0];
+      for (let i = 1; i < P.length; i++) {
+        const r = [2 * (P[i][0] - p0[0]), 2 * (P[i][1] - p0[1]), 2 * (P[i][2] - p0[2])];
+        const bi = dot(P[i], P[i]) - dot(p0, p0);
+        for (let a = 0; a < 3; a++) {
+          for (let bcol = 0; bcol < 3; bcol++) M[a][bcol] += r[a] * r[bcol];
+          rhs[a] += r[a] * bi;
+        }
+      }
+      const sol = solve3(M, rhs);
+      if (sol) return sol;
+      let acc = [0, 0, 0];
+      for (const p of P) acc = add(acc, p);
+      return scale(acc, 1 / P.length);
+    }
+    case "pyramidInsphereCenter": {
+      const S = getPointWorld(c.apex, state);
+      const base = c.vertices.map((id) => getPointWorld(id, state));
+      const n = base.length;
+      if (n < 3) return S;
+      let G = [0, 0, 0];
+      for (const p of base) G = add(G, p);
+      G = scale(G, 1 / n);
+      let nb = normalize(cross(sub(base[1], base[0]), sub(base[2], base[0])));
+      if (dot(nb, sub(S, G)) < 0) nb = scale(nb, -1);
+      let m = normalize(cross(sub(base[0], S), sub(base[1], S)));
+      if (dot(m, sub(G, base[0])) < 0) m = scale(m, -1);
+      const denom = 1 - dot(m, nb);
+      const s = Math.abs(denom) < 1e-9 ? NaN : dot(m, sub(G, base[0])) / denom;
+      if (!Number.isFinite(s) || s <= 0) {
+        return scale(add(S, scale(G, n)), 1 / (n + 1));
+      }
+      return add(G, scale(nb, s));
+    }
+    case "faceCircumcenter": {
+      const P = c.vertices.map((id) => getPointWorld(id, state));
+      if (P.length < 3) return P.length ? P[0] : [0, 0, 0];
+      const [p0, p1, p2] = P;
+      const e1 = sub(p1, p0), e2 = sub(p2, p0);
+      const nrm = cross(e1, e2);
+      const M = [
+        [2 * e1[0], 2 * e1[1], 2 * e1[2]],
+        [2 * e2[0], 2 * e2[1], 2 * e2[2]],
+        [nrm[0], nrm[1], nrm[2]]
+      ];
+      const rhs = [dot(p1, p1) - dot(p0, p0), dot(p2, p2) - dot(p0, p0), dot(nrm, p0)];
+      const sol = solve3(M, rhs);
+      if (sol) return sol;
+      return scale(add(add(p0, p1), p2), 1 / 3);
+    }
+    case "pointAboveFace": {
+      const G = getPointWorld(c.base, state);
+      const P = c.vertices.map((id) => getPointWorld(id, state));
+      if (P.length < 3) return G;
+      let n = normalize(cross(sub(P[1], P[0]), sub(P[2], P[0])));
+      const S = getPointWorld(c.apex, state);
+      if (dot(n, sub(S, P[0])) < 0) n = scale(n, -1);
+      const h = dot(sub(S, P[0]), n);
+      if (!Number.isFinite(h) || h <= 1e-9) return G;
+      return add(G, scale(n, h));
+    }
+    case "intersectionLines": {
+      const A = getPointWorld(c.a1, state), B = getPointWorld(c.b1, state);
+      const C = getPointWorld(c.a2, state), D = getPointWorld(c.b2, state);
+      return lineLineClosestMidpoint(A, B, C, D);
+    }
+    case "intersectionLinePlane": {
+      const A = getPointWorld(c.a, state), B = getPointWorld(c.b, state);
+      const plane = state.objects[c.plane];
+      if (!plane || plane.kind !== "plane3d") throw new Error("intersectionLinePlane: m\u1EB7t ph\u1EB3ng thi\u1EBFu");
+      const { origin, normal } = getPlaneBasis(plane, state);
+      const dir = sub(B, A);
+      const dn = dot(dir, normal);
+      if (Math.abs(dn) < 1e-12) return A;
+      const t = dot(sub(origin, A), normal) / dn;
+      return add(A, scale(dir, t));
+    }
+    case "perpFootLine": {
+      const P = getPointWorld(c.from, state);
+      const A = getPointWorld(c.a, state), B = getPointWorld(c.b, state);
+      const u = sub(B, A);
+      const uu = dot(u, u);
+      const t = uu === 0 ? 0 : dot(sub(P, A), u) / uu;
+      return add(A, scale(u, t));
+    }
+    case "perpFootPlane": {
+      const P = getPointWorld(c.from, state);
+      const plane = state.objects[c.plane];
+      if (!plane || plane.kind !== "plane3d") throw new Error("perpFootPlane: m\u1EB7t ph\u1EB3ng thi\u1EBFu");
+      const { origin, normal } = getPlaneBasis(plane, state);
+      const dist2 = dot(sub(P, origin), normal);
+      return sub(P, scale(normal, dist2));
+    }
   }
 }
 
@@ -124,6 +493,15 @@ var def = {
     if (c.kind === "onLine") return `${obj.label} tr\xEAn \u0111\u01B0\u1EDDng ${c.lineId}`;
     if (c.kind === "onPolygon") return `${obj.label} tr\xEAn \u0111a gi\xE1c ${c.polygonId}`;
     if (c.kind === "onSphere") return `${obj.label} tr\xEAn m\u1EB7t c\u1EA7u ${c.sphereId}`;
+    if (c.kind === "midpoint") return `${obj.label} = trung \u0111i\u1EC3m ${c.p1}${c.p2}`;
+    if (c.kind === "centroid") return `${obj.label} = tr\u1ECDng t\xE2m ${c.vertices.join("")}`;
+    if (c.kind === "intersectionLines") return `${obj.label} = giao 2 \u0111\u01B0\u1EDDng (${c.a1}${c.b1}, ${c.a2}${c.b2})`;
+    if (c.kind === "intersectionLinePlane") return `${obj.label} = giao ${c.a}${c.b} \u2229 ${c.plane}`;
+    if (c.kind === "perpFootLine") return `${obj.label} = ch\xE2n \u22A5 t\u1EEB ${c.from} xu\u1ED1ng ${c.a}${c.b}`;
+    if (c.kind === "perpFootPlane") return `${obj.label} = ch\xE2n \u22A5 t\u1EEB ${c.from} xu\u1ED1ng ${c.plane}`;
+    if (c.kind === "pyramidInsphereCenter") return `${obj.label} = t\xE2m c\u1EA7u n\u1ED9i ti\u1EBFp ch\xF3p ${c.apex}.${c.vertices.join("")}`;
+    if (c.kind === "faceCircumcenter") return `${obj.label} = t\xE2m ngo\u1EA1i ti\u1EBFp ${c.vertices.join("")}`;
+    if (c.kind === "pointAboveFace") return `${obj.label} = \u0111\u1EC9nh tr\u1EE5c tr\u1EE5 \u22A5 m\u1EB7t ${c.vertices.join("")}`;
     return obj.label;
   },
   render: (obj, ctx) => {
@@ -173,6 +551,15 @@ var def = {
         () => sph.F(c.theta, c.phi)[2]
       ], opts);
     }
+    const getState = ctx.getState;
+    if (getState) {
+      const cw = () => constraintToWorld(c, getState());
+      return view.create("point3d", [
+        () => cw()[0],
+        () => cw()[1],
+        () => cw()[2]
+      ], { ...opts, needsRegularUpdate: true });
+    }
     return view.create("point3d", [0, 0, 0], opts);
   }
 };
@@ -221,28 +608,71 @@ var def2 = {
 registerKind(def2);
 
 // src/core/scene/kinds/line3d.ts
-registerKind({
+function line3dConstructionRefs(c) {
+  switch (c.kind) {
+    case "planePlaneIntersection":
+      return [c.plane1, c.plane2];
+    case "lineParallelThrough":
+      return [c.point, c.dirA, c.dirB];
+    case "linePerpToPlane":
+      return [c.point, c.plane];
+    default: {
+      return [];
+    }
+  }
+}
+var def3 = {
   type: "line3d",
   schemaVersion: 1,
   migrate: {},
   validate: (a) => {
-    if (!a?.p1 || !a?.p2) throw new Error("line3d: p1/p2 required");
+    if (a?.construction) return;
+    if (!a?.p1 || !a?.p2) throw new Error("line3d: p1/p2 required (ho\u1EB7c construction)");
+  },
+  dependsOn: (a) => a.construction ? line3dConstructionRefs(a.construction) : [a.p1, a.p2],
+  describe: (obj, state) => {
+    const c = obj.attrs.construction;
+    if (!c) return `\u0110\u01B0\u1EDDng ${obj.label} qua ${labelOf(obj.attrs.p1, state)}, ${labelOf(obj.attrs.p2, state)}`;
+    switch (c.kind) {
+      case "planePlaneIntersection":
+        return `Giao tuy\u1EBFn ${obj.label} = ${labelOf(c.plane1, state)} \u2229 ${labelOf(c.plane2, state)}`;
+      case "lineParallelThrough":
+        return `${obj.label} \u2225 ${labelOf(c.dirA, state)}${labelOf(c.dirB, state)} qua ${labelOf(c.point, state)}`;
+      case "linePerpToPlane":
+        return `${obj.label} \u22A5 ${labelOf(c.plane, state)} qua ${labelOf(c.point, state)}`;
+      default:
+        return obj.label;
+    }
   },
-  dependsOn: (a) => [a.p1, a.p2],
-  describe: (obj, state) => `\u0110\u01B0\u1EDDng ${obj.label} qua ${labelOf(obj.attrs.p1, state)}, ${labelOf(obj.attrs.p2, state)}`,
   render: (obj, ctx) => {
     const view = ctx.jxg;
+    const baseOpts = {
+      strokeColor: obj.attrs.color ?? "#0f172a",
+      strokeWidth: 2,
+      visible: obj.visible
+    };
+    const c = obj.attrs.construction;
+    if (c) {
+      const getState = ctx.getState;
+      if (!getState) throw new Error("line3d construction: c\u1EA7n ctx.getState");
+      const lc = () => lineConstructionWorld(c, getState());
+      return view.create("line3d", [() => lc().a, () => lc().b], {
+        ...baseOpts,
+        straightFirst: true,
+        straightLast: true,
+        needsRegularUpdate: true
+      });
+    }
     const pA = ctx.resolveRef(obj.attrs.p1);
     const pB = ctx.resolveRef(obj.attrs.p2);
     return view.create("line3d", [pA, pB], {
+      ...baseOpts,
       straightFirst: true,
-      straightLast: true,
-      strokeColor: obj.attrs.color ?? "#0f172a",
-      strokeWidth: 2,
-      visible: obj.visible
+      straightLast: true
     });
   }
-});
+};
+registerKind(def3);
 
 // src/core/scene/kinds/ray3d.ts
 registerKind({
@@ -294,29 +724,71 @@ registerKind({
 });
 
 // src/core/scene/kinds/plane3d.ts
-registerKind({
+function plane3dConstructionRefs(c) {
+  switch (c.kind) {
+    case "planeParallelThrough":
+      return [c.point, c.refPlane];
+    case "planePerpToLine":
+      return [c.point, c.lineA, c.lineB];
+    default: {
+      return [];
+    }
+  }
+}
+var def4 = {
   type: "plane3d",
   schemaVersion: 1,
   migrate: {},
   validate: (a) => {
-    if (!a?.p1 || !a?.p2 || !a?.p3) throw new Error("plane3d: c\u1EA7n 3 \u0111i\u1EC3m");
+    if (a?.construction) return;
+    if (!a?.p1 || !a?.p2 || !a?.p3) throw new Error("plane3d: c\u1EA7n 3 \u0111i\u1EC3m (ho\u1EB7c construction)");
+  },
+  dependsOn: (a) => a.construction ? plane3dConstructionRefs(a.construction) : [a.p1, a.p2, a.p3],
+  describe: (obj, state) => {
+    const c = obj.attrs.construction;
+    if (!c) {
+      return `M\u1EB7t ${obj.label} qua ${labelOf(obj.attrs.p1, state)}, ${labelOf(obj.attrs.p2, state)}, ${labelOf(obj.attrs.p3, state)}`;
+    }
+    switch (c.kind) {
+      case "planeParallelThrough":
+        return `${obj.label} \u2225 ${labelOf(c.refPlane, state)} qua ${labelOf(c.point, state)}`;
+      case "planePerpToLine":
+        return `${obj.label} \u22A5 ${labelOf(c.lineA, state)}${labelOf(c.lineB, state)} qua ${labelOf(c.point, state)}`;
+      default:
+        return obj.label;
+    }
   },
-  dependsOn: (a) => [a.p1, a.p2, a.p3],
-  describe: (obj, state) => `M\u1EB7t ${obj.label} qua ${labelOf(obj.attrs.p1, state)}, ${labelOf(obj.attrs.p2, state)}, ${labelOf(obj.attrs.p3, state)}`,
   render: (obj, ctx) => {
     const view = ctx.jxg;
-    return view.create("plane3d", [
-      ctx.resolveRef(obj.attrs.p1),
-      ctx.resolveRef(obj.attrs.p2),
-      ctx.resolveRef(obj.attrs.p3)
-    ], {
+    const opts = {
       fillOpacity: 0.15,
       fillColor: obj.attrs.color ?? "#60a5fa",
       strokeColor: obj.attrs.color ?? "#60a5fa",
       visible: obj.visible
-    });
+    };
+    const c = obj.attrs.construction;
+    if (c) {
+      const getState = ctx.getState;
+      if (!getState) throw new Error("plane3d construction: c\u1EA7n ctx.getState");
+      const pc = () => planeConstructionWorld(c, getState());
+      const diff = (which) => {
+        const r = pc();
+        const q = r[which];
+        return [q[0] - r.p1[0], q[1] - r.p1[1], q[2] - r.p1[2]];
+      };
+      return view.create("plane3d", [() => pc().p1, () => diff("p2"), () => diff("p3")], {
+        ...opts,
+        needsRegularUpdate: true
+      });
+    }
+    return view.create("plane3d", [
+      ctx.resolveRef(obj.attrs.p1),
+      ctx.resolveRef(obj.attrs.p2),
+      ctx.resolveRef(obj.attrs.p3)
+    ], opts);
   }
-});
+};
+registerKind(def4);
 
 // src/core/scene/kinds/polygon3d.ts
 registerKind({
@@ -396,6 +868,27 @@ registerKind({
   }
 });
 
+// src/core/scene/kinds/_ringBasis.ts
+function perpBasis(axis) {
+  const n = Math.hypot(axis[0], axis[1], axis[2]);
+  if (n < 1e-12) return [[1, 0, 0], [0, 1, 0]];
+  const a = [axis[0] / n, axis[1] / n, axis[2] / n];
+  const seed = Math.abs(a[2]) < 0.9 ? [0, 0, 1] : [1, 0, 0];
+  let u = [
+    seed[1] * a[2] - seed[2] * a[1],
+    seed[2] * a[0] - seed[0] * a[2],
+    seed[0] * a[1] - seed[1] * a[0]
+  ];
+  const un = Math.hypot(u[0], u[1], u[2]) || 1;
+  u = [u[0] / un, u[1] / un, u[2] / un];
+  const v = [
+    a[1] * u[2] - a[2] * u[1],
+    a[2] * u[0] - a[0] * u[2],
+    a[0] * u[1] - a[1] * u[0]
+  ];
+  return [u, v];
+}
+
 // src/core/scene/kinds/cylinder3d.ts
 var CURVED_SEGMENTS = 16;
 registerKind({
@@ -415,14 +908,17 @@ registerKind({
     const r = obj.attrs.radius;
     const ax = a.X?.() ?? 0, ay = a.Y?.() ?? 0, az = a.Z?.() ?? 0;
     const bx = b.X?.() ?? 0, by = b.Y?.() ?? 0, bz = b.Z?.() ?? 0;
+    const [u, v] = perpBasis([bx - ax, by - ay, bz - az]);
     const baseRing = [];
     const topRing = [];
     for (let i = 0; i < CURVED_SEGMENTS; i++) {
       const theta = i / CURVED_SEGMENTS * Math.PI * 2;
-      const dx = r * Math.cos(theta);
-      const dy = r * Math.sin(theta);
-      baseRing.push([ax + dx, ay + dy, az]);
-      topRing.push([bx + dx, by + dy, bz]);
+      const c = Math.cos(theta), s = Math.sin(theta);
+      const ox = r * (c * u[0] + s * v[0]);
+      const oy = r * (c * u[1] + s * v[1]);
+      const oz = r * (c * u[2] + s * v[2]);
+      baseRing.push([ax + ox, ay + oy, az + oz]);
+      topRing.push([bx + ox, by + oy, bz + oz]);
     }
     const vertices = [...baseRing, ...topRing];
     const faces = [];
@@ -433,7 +929,7 @@ registerKind({
       faces.push([i, next, CURVED_SEGMENTS + next, CURVED_SEGMENTS + i]);
     }
     const vertJxgs = vertices.map(
-      (v, i) => view.create("point3d", v, {
+      (v2, i) => view.create("point3d", v2, {
         id: `${obj.id}.v${i}`,
         visible: false,
         fixed: true,
@@ -477,10 +973,16 @@ registerKind({
       apexPt.Y?.() ?? 0,
       apexPt.Z?.() ?? 0
     ];
+    const [u, v] = perpBasis([apexCoords[0] - bx, apexCoords[1] - by, apexCoords[2] - bz]);
     const baseRing = [];
     for (let i = 0; i < CURVED_SEGMENTS2; i++) {
       const theta = i / CURVED_SEGMENTS2 * Math.PI * 2;
-      baseRing.push([bx + r * Math.cos(theta), by + r * Math.sin(theta), bz]);
+      const c = Math.cos(theta), s = Math.sin(theta);
+      baseRing.push([
+        bx + r * (c * u[0] + s * v[0]),
+        by + r * (c * u[1] + s * v[1]),
+        bz + r * (c * u[2] + s * v[2])
+      ]);
     }
     const apexIdx = baseRing.length;
     const vertices = [...baseRing, apexCoords];
@@ -489,7 +991,7 @@ registerKind({
       faces.push([i, (i + 1) % CURVED_SEGMENTS2, apexIdx]);
     }
     const vertJxgs = vertices.map(
-      (v, i) => view.create("point3d", v, {
+      (v2, i) => view.create("point3d", v2, {
         id: `${obj.id}.v${i}`,
         visible: false,
         fixed: true,
@@ -576,8 +1078,16 @@ function constraintRefs2D(c) {
     }
     case "excenter":
       return [c.vertices[0], c.vertices[1], c.vertices[2]];
-    default:
+    case "commonTangentPoint":
+      return [c.circles[0], c.circles[1]];
+    // Các kind KHÔNG có ref scene-object (toạ độ literal): liệt kê TƯỜNG MINH để
+    // exhaustive never-guard bên dưới buộc khai báo khi thêm constraint kind mới.
+    case "free":
+    case "onAxis":
       return [];
+    default: {
+      return [];
+    }
   }
 }
 
@@ -1000,19 +1510,19 @@ function buildJxgTransforms(board, ctx, t) {
   }
 }
 function makeDistanceFn(ctx, d) {
-  const scale = d.scale ?? 1;
+  const scale2 = d.scale ?? 1;
   const offset = d.offset ?? 0;
   if (d.kind === "literal") {
     const v = d.value;
-    return () => scale * v + offset;
+    return () => scale2 * v + offset;
   }
   if (d.kind === "segmentLength") {
     const p = ctx.resolveRef(d.p1);
     const q = ctx.resolveRef(d.p2);
-    return () => scale * Math.hypot(p.X() - q.X(), p.Y() - q.Y()) + offset;
+    return () => scale2 * Math.hypot(p.X() - q.X(), p.Y() - q.Y()) + offset;
   }
   const circle = ctx.resolveRef(d.circle);
-  return () => scale * circle.Radius() + offset;
+  return () => scale2 * circle.Radius() + offset;
 }
 function buildPointOpts(obj) {
   return {
@@ -1048,6 +1558,61 @@ var pointAtDistanceConstraint = definePointConstraint({
   }
 });
 
+// src/stamps/geometry-2d/geometry/commonTangent.ts
+var EPS = 1e-9;
+function computeCommonTangentPoint(O1, r1, O2, r2, on, variant, side) {
+  const dx = O2[0] - O1[0];
+  const dy = O2[1] - O1[1];
+  const d = Math.hypot(dx, dy);
+  if (d < EPS) return null;
+  const beta = Math.atan2(dy, dx);
+  const ratio = variant === "external" ? (r1 - r2) / d : (r1 + r2) / d;
+  if (Math.abs(ratio) > 1) return null;
+  const gamma = Math.acos(ratio);
+  const s = side === 0 ? 1 : -1;
+  const angle = beta + s * gamma;
+  const nx = Math.cos(angle);
+  const ny = Math.sin(angle);
+  if (on === 0) {
+    return [O1[0] + r1 * nx, O1[1] + r1 * ny];
+  }
+  if (variant === "external") {
+    return [O2[0] + r2 * nx, O2[1] + r2 * ny];
+  }
+  return [O2[0] - r2 * nx, O2[1] - r2 * ny];
+}
+
+// src/core/scene/kinds/point-constraints/commonTangentPoint.ts
+var commonTangentPointConstraint = definePointConstraint({
+  kind: "commonTangentPoint",
+  describe: (obj, state, c) => {
+    const c1 = state?.objects[c.circles[0]]?.label ?? c.circles[0];
+    const c2 = state?.objects[c.circles[1]]?.label ?? c.circles[1];
+    const v = c.variant === "internal" ? "trong" : "ngo\xE0i";
+    return `${obj.label} = ti\u1EBFp \u0111i\u1EC3m ti\u1EBFp tuy\u1EBFn chung ${v} ${c1},${c2} (tr\xEAn ${c.on === 0 ? c1 : c2})`;
+  },
+  render: (obj, ctx, c, opts) => {
+    const board = ctx.jxg;
+    const k1 = ctx.resolveRef(c.circles[0]);
+    const k2 = ctx.resolveRef(c.circles[1]);
+    const O1 = k1?.center ?? k1?.midpoint ?? k1;
+    const O2 = k2?.center ?? k2?.midpoint ?? k2;
+    const compute = () => {
+      const t = computeCommonTangentPoint(
+        [O1.X(), O1.Y()],
+        k1.Radius(),
+        [O2.X(), O2.Y()],
+        k2.Radius(),
+        c.on,
+        c.variant,
+        c.side
+      );
+      return t ?? [0, 0];
+    };
+    return board.create("point", [() => compute()[0], () => compute()[1]], opts);
+  }
+});
+
 // src/core/scene/kinds/point-constraints/circleIntersection.ts
 var circleIntersectionConstraint = definePointConstraint({
   kind: "circleIntersection",
@@ -1264,6 +1829,7 @@ var ALL = [
   excenterConstraint,
   mixtilinearPointConstraint,
   pointAtDistanceConstraint,
+  commonTangentPointConstraint,
   circleIntersectionConstraint,
   circleSecondIntersectionConstraint,
   secondIntersectionConstraint,
@@ -1278,7 +1844,7 @@ var ALL = [
 var POINT_CONSTRAINTS = new Map(ALL.map((m) => [m.kind, m]));
 
 // src/core/scene/kinds/point.ts
-var def3 = {
+var def5 = {
   type: "point",
   schemaVersion: 1,
   migrate: {},
@@ -1356,10 +1922,10 @@ var def3 = {
     throw new Error("point: constraint kind changed \u2014 recreate");
   }
 };
-registerKind(def3);
+registerKind(def5);
 
 // src/core/scene/kinds/segment.ts
-var def4 = {
+var def6 = {
   type: "segment",
   schemaVersion: 1,
   migrate: {},
@@ -1395,7 +1961,7 @@ var def4 = {
     });
   }
 };
-registerKind(def4);
+registerKind(def6);
 
 // src/core/scene/kinds/line.ts
 function stripBorderSuffix(id) {
@@ -1421,7 +1987,7 @@ function constructionRefs(c) {
       return [c.throughPoint, c.toCircle];
   }
 }
-var def5 = {
+var def7 = {
   type: "line",
   schemaVersion: 1,
   migrate: {},
@@ -1617,10 +2183,10 @@ var def5 = {
     }
   }
 };
-registerKind(def5);
+registerKind(def7);
 
 // src/core/scene/kinds/ray.ts
-var def6 = {
+var def8 = {
   type: "ray",
   schemaVersion: 1,
   migrate: {},
@@ -1645,10 +2211,10 @@ var def6 = {
     });
   }
 };
-registerKind(def6);
+registerKind(def8);
 
 // src/core/scene/kinds/vector.ts
-var def7 = {
+var def9 = {
   type: "vector",
   schemaVersion: 1,
   migrate: {},
@@ -1670,7 +2236,7 @@ var def7 = {
     });
   }
 };
-registerKind(def7);
+registerKind(def9);
 
 // src/core/scene/kinds/circle.ts
 function asConstruction(a) {
@@ -1698,7 +2264,7 @@ function constructionRefs2(c) {
       return [c.p1, c.p2];
   }
 }
-var def8 = {
+var def10 = {
   type: "circle",
   schemaVersion: 1,
   migrate: {},
@@ -1850,7 +2416,7 @@ var def8 = {
     return board.create("circle", [center, surface], baseOpts);
   }
 };
-registerKind(def8);
+registerKind(def10);
 
 // src/core/scene/kinds/arc.ts
 function constructionRefs3(c) {
@@ -1863,7 +2429,7 @@ function constructionRefs3(c) {
       return [c.p1, c.p2, c.p3];
   }
 }
-var def9 = {
+var def11 = {
   type: "arc",
   schemaVersion: 1,
   migrate: {},
@@ -1921,10 +2487,10 @@ var def9 = {
     return board.create("circumcirclearc", [A, B, C], baseOpts);
   }
 };
-registerKind(def9);
+registerKind(def11);
 
 // src/core/scene/kinds/sector.ts
-var def10 = {
+var def12 = {
   type: "sector",
   schemaVersion: 1,
   migrate: {},
@@ -1964,7 +2530,7 @@ var def10 = {
     });
   }
 };
-registerKind(def10);
+registerKind(def12);
 
 // src/core/scene/kinds/polygon.ts
 function regularPolygonName(n) {
@@ -2008,7 +2574,7 @@ function specialShapeName(kind) {
       return "";
   }
 }
-var def11 = {
+var def13 = {
   type: "polygon",
   schemaVersion: 1,
   migrate: {},
@@ -2195,10 +2761,10 @@ var def11 = {
     return poly;
   }
 };
-registerKind(def11);
+registerKind(def13);
 
 // src/core/scene/kinds/intersection.ts
-var def12 = {
+var def14 = {
   type: "intersection",
   schemaVersion: 1,
   migrate: {},
@@ -2273,10 +2839,10 @@ var def12 = {
     }
   }
 };
-registerKind(def12);
+registerKind(def14);
 
 // src/core/scene/kinds/angle.ts
-var def13 = {
+var def15 = {
   type: "angle",
   schemaVersion: 1,
   migrate: {},
@@ -2312,10 +2878,10 @@ var def13 = {
     });
   }
 };
-registerKind(def13);
+registerKind(def15);
 
 // src/core/scene/kinds/distance.ts
-var def14 = {
+var def16 = {
   type: "distance",
   schemaVersion: 1,
   migrate: {},
@@ -2344,10 +2910,10 @@ var def14 = {
     });
   }
 };
-registerKind(def14);
+registerKind(def16);
 
 // src/core/scene/kinds/function2d.ts
-var def15 = {
+var def17 = {
   type: "function2d",
   schemaVersion: 1,
   migrate: {},
@@ -2386,10 +2952,10 @@ var def15 = {
     });
   }
 };
-registerKind(def15);
+registerKind(def17);
 
 // src/core/scene/kinds/parameter.ts
-var def16 = {
+var def18 = {
   type: "parameter",
   schemaVersion: 1,
   migrate: {},
@@ -2407,10 +2973,10 @@ var def16 = {
   render: () => null
   // Không render lên board
 };
-registerKind(def16);
+registerKind(def18);
 
 // src/core/scene/kinds/pointOnCurve.ts
-var def17 = {
+var def19 = {
   type: "pointOnCurve",
   schemaVersion: 1,
   migrate: {},
@@ -2437,10 +3003,10 @@ var def17 = {
     });
   }
 };
-registerKind(def17);
+registerKind(def19);
 
 // src/core/scene/kinds/tangent2d.ts
-var def18 = {
+var def20 = {
   type: "tangent2d",
   schemaVersion: 1,
   migrate: {},
@@ -2463,7 +3029,7 @@ var def18 = {
     });
   }
 };
-registerKind(def18);
+registerKind(def20);
 
 // src/core/scene/expressions/evaluator.ts
 var DEFAULT_SAMPLES = 1e3;
@@ -2532,7 +3098,7 @@ function scanExtrema(fn, xMin, xMax, samples = DEFAULT_SAMPLES) {
 }
 
 // src/core/scene/kinds/extremum2d.ts
-var def19 = {
+var def21 = {
   type: "extremum2d",
   schemaVersion: 1,
   migrate: {},
@@ -2565,10 +3131,10 @@ var def19 = {
     }));
   }
 };
-registerKind(def19);
+registerKind(def21);
 
 // src/core/scene/kinds/root2d.ts
-var def20 = {
+var def22 = {
   type: "root2d",
   schemaVersion: 1,
   migrate: {},
@@ -2598,10 +3164,10 @@ var def20 = {
     }));
   }
 };
-registerKind(def20);
+registerKind(def22);
 
 // src/core/scene/kinds/slope2d.ts
-var def21 = {
+var def23 = {
   type: "slope2d",
   schemaVersion: 1,
   migrate: {},
@@ -2625,7 +3191,7 @@ var def21 = {
     });
   }
 };
-registerKind(def21);
+registerKind(def23);
 
 // src/stamps/shared/serializeScene.ts
 function serializeScene(state) {
@@ -2651,6 +3217,6 @@ function deserializeScene(domain, raw) {
   return createEmptyState(domain);
 }
 
-export { deserializeScene, listObjects, nextLabel, serializeScene, useEditorState };
-//# sourceMappingURL=chunk-JJ4FPCBE.mjs.map
-//# sourceMappingURL=chunk-JJ4FPCBE.mjs.map
+export { constraintToWorld, deserializeScene, listObjects, nextLabel, planeConstructionWorld, serializeScene, useEditorState };
+//# sourceMappingURL=chunk-4EXRNZRX.mjs.map
+//# sourceMappingURL=chunk-4EXRNZRX.mjs.map