lecodes-cli 0.17.0 → 0.17.1

package/dist/index.js

@@ -120,7 +120,7 @@ var useColor, paint = (code, s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s, c,
   if (!answer)
     return fallback;
   return answer === "y" || answer === "yes";
-}, parseArgs = (argv) => {
+}, isNegativeNumber = (s) => /^-(\d|\.\d)/.test(s), isValue = (s) => !s.startsWith("-") || isNegativeNumber(s), parseArgs = (argv) => {
   const out = { _: [], flags: {} };
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
@@ -132,15 +132,15 @@ var useColor, paint = (code, s) => useColor ? `\x1B[${code}m${s}\x1B[0m` : s, c,
       }
       const key = arg.slice(2);
       const next = argv[i + 1];
-      if (next !== undefined && !next.startsWith("-")) {
+      if (next !== undefined && isValue(next)) {
         out.flags[key] = next;
         i++;
       } else
         out.flags[key] = true;
-    } else if (arg.startsWith("-") && arg.length > 1) {
+    } else if (arg.startsWith("-") && arg.length > 1 && !isNegativeNumber(arg)) {
       const key = arg.slice(1);
       const next = argv[i + 1];
-      if (next !== undefined && !next.startsWith("-")) {
+      if (next !== undefined && isValue(next)) {
         out.flags[key] = next;
         i++;
       } else
@@ -388,6 +388,34 @@ design/comments/
   const file = join3(root, ".lecodesignore");
   if (!existsSync2(file))
     writeFileSync3(file, DEFAULT_IGNORE_FILE);
+}, DEFAULT_GITIGNORE = `# LeCodes per-checkout state: generated IDE types + this machine's sync cursor
+# (.lecodes/manifest.json). Regenerate with \`lecodes types\` / re-attach with \`lecodes link\`.
+.lecodes/
+
+# Render / preview outputs and test failure frames
+screenshot.png
+shots/
+tests/.artifacts/
+
+node_modules/
+`, ensureGitignore = (root) => {
+  const file = join3(root, ".gitignore");
+  if (!existsSync2(file)) {
+    writeFileSync3(file, DEFAULT_GITIGNORE);
+    return "created";
+  }
+  const text = readFileSync3(file, "utf8");
+  const covered = text.split(/\r?\n/).some((l) => /^\/?\.lecodes\/?\s*$/.test(l.trim()));
+  if (covered)
+    return null;
+  const sep = text.length === 0 || text.endsWith(`
+`) ? "" : `
+`;
+  writeFileSync3(file, `${text}${sep}
+# LeCodes per-checkout state (generated types + sync cursor) — not source
+.lecodes/
+`);
+  return "updated";
 };
 var init_ignore = __esm(() => {
   BUILTIN_PATTERNS = ["node_modules/", ".git/", "_*", "*.log", ".DS_Store", ".artifacts/"];
@@ -84194,8 +84222,8 @@ ${lanes.join(`
         if (node === undefined || node.parent.kind !== 307 || !isInternalModuleImportEqualsDeclaration(node)) {
           return false;
         }
-        const isValue = isAliasResolvedToValue(getSymbolOfDeclaration(node));
-        return isValue && node.moduleReference && !nodeIsMissing(node.moduleReference);
+        const isValue2 = isAliasResolvedToValue(getSymbolOfDeclaration(node));
+        return isValue2 && node.moduleReference && !nodeIsMissing(node.moduleReference);
       }
       function isAliasResolvedToValue(symbol, excludeTypeOnlyValues) {
         if (!symbol) {
@@ -215816,7 +215844,7 @@ var require_main = __commonJS((exports, module) => {
 // package.json
 var package_default = {
   name: "lecodes-cli",
-  version: "0.17.0",
+  version: "0.17.1",
   dependencies: {
     "@letary/chisel": "^0.8.0",
     jimp: "^1.6.1"
@@ -215832,7 +215860,7 @@ var package_default = {
   },
   peerDependencies: {
     "lecodes-design": "^0.8.1",
-    "lecodes-renderer": "^0.8.5",
+    "lecodes-renderer": "^0.8.6",
     "lecodes-3d-editor": "^0.3.0",
     "lecodes-assets": "^0.1.0"
   },
@@ -220089,6 +220117,7 @@ var clone3 = async (args) => {
     writeTsconfig(root);
   }
   writeDefaultIgnore(root);
+  ensureGitignore(root);
   const commits = await getCommits(apiUrl, token, uuid);
   writeManifest(root, { uuid, apiUrl, name: project.name, baseHeadId: commits.headId, files });
   success(`Cloned ${c.bold(project.name)} into ${c.bold(dir)}/ (${Object.keys(files).length} files)`);
@@ -220183,7 +220212,8 @@ channel for game state that has no UI.
 
 ## SDK documentation
 
-\`.lecodes/types/\` is the exact API surface (signatures only). For semantics and examples,
+\`.lecodes/types/\` is the exact API surface (signatures only; generated and gitignored — run
+\`lecodes types\` if it's missing, never commit \`.lecodes/\`). For semantics and examples,
 fetch the docs — they are served as raw markdown for AI tools:
 
 - https://le.codes/llms.txt — the docs map; fetch it first to find the right page
@@ -221261,6 +221291,9 @@ lecodes app open             # open it in Xcode, build & run
 - \`assets/\` — images/fonts the app references (created on demand)
 - \`tsconfig.json\` + \`.lecodes/types/\` — generated IDE types (rewritten by the CLI; don't edit).
   They come from the SDK bundled in the CLI; \`lecodes types\` refreshes them from the platform.
+- \`.lecodes/\` is gitignored — per-checkout state (those types + \`manifest.json\`, this machine's
+  sync cursor once linked). After a fresh git clone: \`lecodes types\`, then
+  \`lecodes link --project <uuid>\` to re-attach.
 - \`.lecodesignore\` — files a future \`lecodes push\` would skip
 
 Full command list: \`lecodes --help\`.
@@ -221291,6 +221324,14 @@ var init2 = async (args) => {
   write(".claude/settings.json", CLAUDE_SETTINGS);
   write("tests/counter.flow.json", STARTER_FLOW);
   write(".lecodesignore", DEFAULT_IGNORE_FILE);
+  const gi = ensureGitignore(root);
+  if (gi === "created") {
+    log(`${c.green("created")}   .gitignore`);
+    created++;
+  } else if (gi === "updated")
+    log(`${c.green("updated")}   .gitignore  ${c.dim("(+ .lecodes/)")}`);
+  else
+    note("kept      .gitignore");
   const wroteTypes = materializeTypesLocal(root);
   writeTsconfig(root);
   log(`${c.green("written")}   tsconfig.json${wroteTypes ? ` + ${LECODES_DIR}/types/` : ""}  (IDE types)`);
@@ -221542,6 +221583,8 @@ var link = async (args) => {
     log(`${c.green("written")}   ${LECODES_DIR}/types/ + tsconfig.json  ${c.dim("(from the server)")}`);
   }
   writeDefaultIgnore(root);
+  if (ensureGitignore(root))
+    log(`${c.green("written")}   .gitignore  ${c.dim("(.lecodes/ is per-checkout state)")}`);
   if (flagBool(args, "push")) {
     log("");
     if (root !== process.cwd())
@@ -223503,7 +223546,22 @@ ${c.bold("Commands:")}
                                 FBX → LeCodes-ready GLB: meters/Y-up, textures embedded, clips from
                                   other FBX files merged by bone name (Mixamo: one FBX per animation);
                                   --fix/--ktx2 run the doctor passes (needs 'lecodes-assets')
-  assets probe <file.fbx|.glb>  Skeleton, clips, meshes, materials, textures, bind sanity
+                                  Unity .mat files next to the FBX are read for the real textures
+                                  (metallic/roughness/ORM/emission packed the glTF way); --no-unity
+                                  keeps the FBX references; --unity-index <unity-index.txt> resolves GUIDs
+                                  --list-nodes / --keep <node> … / --split [dir]: carve one variant out of a
+                                  multi-variant prop file, re-origined on the ground (or one GLB per node)
+                                  --merge-skins b.fbx …: modular character pieces onto ONE skeleton
+  assets unpack <pkg.unitypackage> [-o dir] [--only re …] [--list]
+                                Stream a .unitypackage to a folder: writes unity-index.txt (GUID → path,
+                                  what convert resolves textures with) and the matching assets + .meta
+  assets scene <map.unity> [-o level.json] [--filter re] [--group g] [--region x0,z0,x1,z1]
+                                Unity scene → placed prefabs / mesh objects with world TRS in LeCodes'
+                                  frame + a prefab table (FBX + --keep node per prefab)
+  assets probe <file.fbx|.glb> [--filmstrip [out.png]]
+                                Skeleton, clips (+ root motion / first-frame-vs-rest per clip), meshes,
+                                  materials, textures, bind sanity, duplicate names; --filmstrip renders
+                                  a CPU-skinned PNG strip per clip (no GPU)
   assets doctor <in.glb|dir> [--fix] [--ktx2] [--dump]
                                 Analyze / fix a GLB against engine limits (bone cap 256, texture
                                   formats/size, KTX2 via toktx)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "dependencies": {
     "@letary/chisel": "^0.8.0",
     "jimp": "^1.6.1"
@@ -16,7 +16,7 @@
   },
   "peerDependencies": {
     "lecodes-design": "^0.8.1",
-    "lecodes-renderer": "^0.8.5",
+    "lecodes-renderer": "^0.8.6",
     "lecodes-3d-editor": "^0.3.0",
     "lecodes-assets": "^0.1.0"
   },

package/runtime/sdk/gl/IK.ts

@@ -1,170 +1,174 @@
-// IK — precise character actions as late-phase aspects on BONES (docs/animation-plan.md §2.5).
-// They run after the animation wrote the pose (base anim or Animator) and before the skin is
-// flushed, so their bone writes land in the skin. Attach to the END bone of the chain; the chain is
-// walked up through parents — one instance per end effector, any Node hierarchy works.
-//
-//   const foot = hero.bone('LeftFoot')!
-//   foot.aspect(IK.TwoBone, { target: footTarget, pole: kneeHint })     // upLeg → leg → foot
-//   foot.ik.weight = grounded ? 1 : 0                                    // blend in/out
-//   hero.bone('Head')!.aspect(IK.LookAt, { target: camera, limit: 70 })  // head tracks the camera
-//
-// Pure SDK/JS: a handful of world-matrix reads + two quaternion writes per solve. A native solver can
-// slot in later behind the same API.
-
-import { Aspect } from "../core/Aspect"
-import { Vec3, type Vec3Like } from "../math/vec"
-import { Quat } from "../math/quat"
-import type { Node } from "./Node"
-
-type Target = Node | Vec3Like
-
-const targetPos = (t: Target | undefined): Vec3 | null => {
-  if (t === undefined || t === null) return null
-  const n = t as Node
-  if (typeof (n as { worldPosition?: unknown }).worldPosition === "object" && typeof n.id === "number") return n.worldPosition
-  return new Vec3(t as Vec3Like)
-}
-
-/** World rotation of a node (parent chain composed natively). */
-const worldRot = (n: Node): Quat => n.worldMatrix.rotation
-
-/** Write a WORLD rotation to a node by converting through the parent's world rotation. */
-const setWorldRot = (n: Node, q: Quat): void => {
-  const p = n.parent
-  n.quaternion = p ? worldRot(p).invert().mul(q).normalize() : q.normalize()
-}
-
-const clampAngle = (q: Quat, maxRad: number): Quat => {
-  // angle of a unit quaternion = 2·acos(|w|)
-  const w = Math.min(1, Math.abs(q.w))
-  const ang = 2 * Math.acos(w)
-  if (ang <= maxRad || ang < 1e-6) return q
-  const s = Math.sqrt(1 - w * w)
-  const axis = new Vec3(q.x / s, q.y / s, q.z / s)
-  return Quat.fromAxisAngle(axis, q.w < 0 ? -maxRad : maxRad)
-}
-
-/** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })`
- *  solves upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend
- *  (knee/elbow) — a Node or world point. */
-class TwoBone extends Aspect<"ik", Node> {
-  static readonly aspect = "ik"
-
-  /** Where the end bone should be (Node or world position). */
-  target?: Target
-  /** Bend hint — the mid joint is pulled toward it (Node or world position). */
-  pole?: Target
-  /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
-  weight = 1
-  /** Solve every frame (default). Set false to drive `solve()` yourself. */
-  enabled = true
-
-  update(): void {
-    if (this.enabled) this.solve()
-  }
-
-  /** One solve at the current pose. Safe to call manually (e.g. from a later-ordered aspect). */
-  solve(): void {
-    const t = targetPos(this.target)
-    if (!t || this.weight <= 0) return
-    const end = this.node
-    const mid = end.parent
-    const root = mid?.parent
-    if (!mid || !root) return
-
-    const w = Math.min(1, this.weight)
-    const midLocal0 = mid.quaternion
-    const rootLocal0 = root.quaternion
-
-    const a = root.worldPosition, b = mid.worldPosition, c = end.worldPosition
-    const l1 = a.distanceTo(b), l2 = b.distanceTo(c)
-    if (l1 < 1e-6 || l2 < 1e-6) return
-    const eps = 1e-4
-    const toT = t.sub(a)
-    const d = Math.min(Math.max(toT.length(), eps), l1 + l2 - eps)
-
-    // 1. bend the mid joint to the angle the target distance demands (law of cosines)
-    const ba = a.sub(b), bc = c.sub(b)
-    const cur = ba.angle(bc)
-    const want = Math.acos(Math.min(1, Math.max(-1, (l1 * l1 + l2 * l2 - d * d) / (2 * l1 * l2))))
-    let axis = bc.cross(ba)
-    if (axis.lengthSq() < 1e-10) {
-      // straight limb: bend toward the pole (or any perpendicular)
-      const p = targetPos(this.pole)
-      const ref = p ? p.sub(b) : new Vec3(0, 0, 1)
-      axis = ba.cross(ref)
-      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(0, 1, 0))
-      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(1, 0, 0))
-    }
-    axis = axis.normalize()
-    // rotating mid by (want - cur) about `axis` opens/closes the angle between ba and bc
-    const midWorld = worldRot(mid)
-    setWorldRot(mid, Quat.fromAxisAngle(axis, want - cur).mul(midWorld))
-
-    // 2. swing the root so the end lands on the target direction
-    const c2 = end.worldPosition
-    const rootWorld = worldRot(root)
-    setWorldRot(root, Quat.fromTo(c2.sub(a), toT).mul(rootWorld))
-
-    // 3. pole: spin the root about the root→target axis so the mid joint lies toward the pole
-    const p = targetPos(this.pole)
-    if (p) {
-      const dir = toT.normalize()
-      const b2 = mid.worldPosition
-      const midProj = b2.sub(a).sub(dir.scale(b2.sub(a).dot(dir)))
-      const poleProj = p.sub(a).sub(dir.scale(p.sub(a).dot(dir)))
-      if (midProj.lengthSq() > 1e-10 && poleProj.lengthSq() > 1e-10) {
-        setWorldRot(root, Quat.fromTo(midProj, poleProj).mul(worldRot(root)))
-      }
-    }
-
-    // 4. weight: blend from the animated pose to the solved one
-    if (w < 1) {
-      root.quaternion = rootLocal0.slerp(root.quaternion, w)
-      mid.quaternion = midLocal0.slerp(mid.quaternion, w)
-    }
-  }
-}
-
-/** Aim a bone at a target (head / eyes / turret). Attach to the bone itself:
- *  `head.aspect(IK.LookAt, { target: camera, limit: 70 })`. `axis` is the bone's LOCAL forward
- *  (the direction that should point at the target) — rigs differ; default −Z, Mixamo heads look
- *  along +Z of the head bone in most exports, so pass `axis: [0, 0, 1]` there if it faces backwards. */
-class LookAt extends Aspect<"lookAt", Node> {
-  static readonly aspect = "lookAt"
-
-  target?: Target
-  /** The bone's local axis that should point at the target. */
-  axis: Vec3Like = [ 0, 0, -1 ]
-  /** Max deflection from the animated direction, in degrees (default 80). */
-  limit = 80
-  /** 0–1 contribution. */
-  weight = 1
-  enabled = true
-
-  update(): void {
-    if (this.enabled) this.solve()
-  }
-
-  solve(): void {
-    const t = targetPos(this.target)
-    if (!t || this.weight <= 0) return
-    const bone = this.node
-    const w = Math.min(1, this.weight)
-    const local0 = bone.quaternion
-    const from = bone.worldPosition
-    const dir = t.sub(from)
-    if (dir.lengthSq() < 1e-10) return
-    const rot = worldRot(bone)
-    const current = new Vec3(this.axis).rotate(rot)
-    let delta = Quat.fromTo(current, dir)
-    delta = clampAngle(delta, (this.limit * Math.PI) / 180)
-    setWorldRot(bone, delta.mul(rot))
-    if (w < 1) bone.quaternion = local0.slerp(bone.quaternion, w)
-  }
-}
-
-/** Inverse kinematics aspects — attach to bones (see file header). */
-export const IK = { TwoBone, LookAt }
-export type IKTwoBone = TwoBone
-export type IKLookAt = LookAt
+// IK — precise character actions as late-phase aspects on BONES (docs/animation-plan.md §2.5).
+// They run after the animation wrote the pose (base anim or Animator) and before the skin is
+// flushed, so their bone writes land in the skin. Attach to the END bone of the chain; the chain is
+// walked up through parents — one instance per end effector, any Node hierarchy works.
+//
+//   const foot = hero.bone('LeftFoot')!
+//   foot.aspect(IK.TwoBone, { target: footTarget, pole: kneeHint })     // upLeg → leg → foot
+//   foot.ik.weight = grounded ? 1 : 0                                    // blend in/out
+//   hero.bone('Head')!.aspect(IK.LookAt, { target: camera, limit: 70 })  // head tracks the camera
+//
+// Pure SDK/JS: a handful of world-matrix reads + two quaternion writes per solve. A native solver can
+// slot in later behind the same API.
+
+import { Aspect } from "../core/Aspect"
+import { Vec3, type Vec3Like } from "../math/vec"
+import { Quat } from "../math/quat"
+import type { Node } from "./Node"
+
+type Target = Node | Vec3Like
+
+const targetPos = (t: Target | undefined): Vec3 | null => {
+  if (t === undefined || t === null) return null
+  const n = t as Node
+  if (typeof (n as { worldPosition?: unknown }).worldPosition === "object" && typeof n.id === "number") return n.worldPosition
+  return new Vec3(t as Vec3Like)
+}
+
+/** World rotation of a node (parent chain composed natively). */
+const worldRot = (n: Node): Quat => n.worldMatrix.rotation
+
+/** Write a WORLD rotation to a node by converting through the parent's world rotation. */
+const setWorldRot = (n: Node, q: Quat): void => {
+  const p = n.parent
+  n.quaternion = p ? worldRot(p).invert().mul(q).normalize() : q.normalize()
+}
+
+const clampAngle = (q: Quat, maxRad: number): Quat => {
+  // angle of a unit quaternion = 2·acos(|w|)
+  const w = Math.min(1, Math.abs(q.w))
+  const ang = 2 * Math.acos(w)
+  if (ang <= maxRad || ang < 1e-6) return q
+  const s = Math.sqrt(1 - w * w)
+  const axis = new Vec3(q.x / s, q.y / s, q.z / s)
+  return Quat.fromAxisAngle(axis, q.w < 0 ? -maxRad : maxRad)
+}
+
+/** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })`
+ *  solves upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend
+ *  (knee/elbow) — a Node or world point. */
+class TwoBone extends Aspect<"ik", Node> {
+  static readonly aspect = "ik"
+
+  /** Where the end bone should be (Node or world position). */
+  target?: Target
+  /** Bend hint — the mid joint is pulled toward it (Node or world position). */
+  pole?: Target
+  /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
+  weight = 1
+  /** Solve every frame (default). Set false to drive `solve()` yourself. */
+  enabled = true
+
+  update(): void {
+    if (this.enabled) this.solve()
+  }
+
+  /** One solve at the current pose. Safe to call manually (e.g. from a later-ordered aspect). */
+  solve(): void {
+    const t = targetPos(this.target)
+    if (!t || this.weight <= 0) return
+    const end = this.node
+    const mid = end.parent
+    const root = mid?.parent
+    if (!mid || !root) return
+
+    const w = Math.min(1, this.weight)
+    const midLocal0 = mid.quaternion
+    const rootLocal0 = root.quaternion
+
+    const a = root.worldPosition, b = mid.worldPosition, c = end.worldPosition
+    const l1 = a.distanceTo(b), l2 = b.distanceTo(c)
+    if (l1 < 1e-6 || l2 < 1e-6) return
+    const eps = 1e-4
+    const toT = t.sub(a)
+    const d = Math.min(Math.max(toT.length(), eps), l1 + l2 - eps)
+
+    // 1. bend the mid joint to the angle the target distance demands (law of cosines)
+    const ba = a.sub(b), bc = c.sub(b)
+    const cur = ba.angle(bc)
+    const want = Math.acos(Math.min(1, Math.max(-1, (l1 * l1 + l2 * l2 - d * d) / (2 * l1 * l2))))
+    // a positive rotation about ba × bc moves `bc` AWAY from `ba`, i.e. opens the joint — so rotating the
+    // mid bone by (want − cur) about it opens/closes exactly as needed. (bc × ba has the opposite sense:
+    // with it every already-bent limb — which is every animated limb — bends the wrong way; the straight
+    // case below picks its axis as ba × ref, the same sense as ba × bc for a limb barely bent toward ref.)
+    let axis = ba.cross(bc)
+    if (axis.lengthSq() < 1e-10) {
+      // straight limb: bend toward the pole (or any perpendicular)
+      const p = targetPos(this.pole)
+      const ref = p ? p.sub(b) : new Vec3(0, 0, 1)
+      axis = ba.cross(ref)
+      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(0, 1, 0))
+      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(1, 0, 0))
+    }
+    axis = axis.normalize()
+    // rotating mid by (want - cur) about `axis` opens/closes the angle between ba and bc
+    const midWorld = worldRot(mid)
+    setWorldRot(mid, Quat.fromAxisAngle(axis, want - cur).mul(midWorld))
+
+    // 2. swing the root so the end lands on the target direction
+    const c2 = end.worldPosition
+    const rootWorld = worldRot(root)
+    setWorldRot(root, Quat.fromTo(c2.sub(a), toT).mul(rootWorld))
+
+    // 3. pole: spin the root about the root→target axis so the mid joint lies toward the pole
+    const p = targetPos(this.pole)
+    if (p) {
+      const dir = toT.normalize()
+      const b2 = mid.worldPosition
+      const midProj = b2.sub(a).sub(dir.scale(b2.sub(a).dot(dir)))
+      const poleProj = p.sub(a).sub(dir.scale(p.sub(a).dot(dir)))
+      if (midProj.lengthSq() > 1e-10 && poleProj.lengthSq() > 1e-10) {
+        setWorldRot(root, Quat.fromTo(midProj, poleProj).mul(worldRot(root)))
+      }
+    }
+
+    // 4. weight: blend from the animated pose to the solved one
+    if (w < 1) {
+      root.quaternion = rootLocal0.slerp(root.quaternion, w)
+      mid.quaternion = midLocal0.slerp(mid.quaternion, w)
+    }
+  }
+}
+
+/** Aim a bone at a target (head / eyes / turret). Attach to the bone itself:
+ *  `head.aspect(IK.LookAt, { target: camera, limit: 70 })`. `axis` is the bone's LOCAL forward
+ *  (the direction that should point at the target) — rigs differ; default −Z, Mixamo heads look
+ *  along +Z of the head bone in most exports, so pass `axis: [0, 0, 1]` there if it faces backwards. */
+class LookAt extends Aspect<"lookAt", Node> {
+  static readonly aspect = "lookAt"
+
+  target?: Target
+  /** The bone's local axis that should point at the target. */
+  axis: Vec3Like = [ 0, 0, -1 ]
+  /** Max deflection from the animated direction, in degrees (default 80). */
+  limit = 80
+  /** 0–1 contribution. */
+  weight = 1
+  enabled = true
+
+  update(): void {
+    if (this.enabled) this.solve()
+  }
+
+  solve(): void {
+    const t = targetPos(this.target)
+    if (!t || this.weight <= 0) return
+    const bone = this.node
+    const w = Math.min(1, this.weight)
+    const local0 = bone.quaternion
+    const from = bone.worldPosition
+    const dir = t.sub(from)
+    if (dir.lengthSq() < 1e-10) return
+    const rot = worldRot(bone)
+    const current = new Vec3(this.axis).rotate(rot)
+    let delta = Quat.fromTo(current, dir)
+    delta = clampAngle(delta, (this.limit * Math.PI) / 180)
+    setWorldRot(bone, delta.mul(rot))
+    if (w < 1) bone.quaternion = local0.slerp(bone.quaternion, w)
+  }
+}
+
+/** Inverse kinematics aspects — attach to bones (see file header). */
+export const IK = { TwoBone, LookAt }
+export type IKTwoBone = TwoBone
+export type IKLookAt = LookAt