@alpsckr/unitycli 0.4.0

package/extensions/probuilder/unitypkg/Editor/ProBuilder/ProBuilderFaceExtrudeCompletionProof.cs

@@ -0,0 +1,283 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using UnityEngine;
+using UnityEngine.ProBuilder;
+
+namespace UnityCli.ProBuilder
+{
+    /// <summary>仅接受一个独立三角面，逐句复演 ProBuilder 5.2.4 face extrusion 的可证明终态。</summary>
+    internal static class ProBuilderFaceExtrudeCompletionProof
+    {
+        private const int SmoothingNone = 0;
+        private const int SmoothRangeMax = 24;
+        private const int HardRangeMax = 42;
+
+        internal sealed class Plan
+        {
+            internal CanonicalMeshSnapshot Before;
+            internal Face[] FrozenFaces;
+            internal ExtrudeMethod Method;
+            internal float Distance;
+            internal int[] BoundaryRaw;
+            internal Vector3 Delta;
+        }
+
+        /// <summary>effect 前冻结 identity、完整 canonical snapshot、typed Face[] 和唯一的 face.edges 顺序。</summary>
+        internal static Plan TryCreate(GameObject go, ProBuilderMesh mesh, int[] requestedOccurrences, string method, float distance)
+        {
+            if (go == null || mesh == null || requestedOccurrences == null || requestedOccurrences.Length != 1 || requestedOccurrences[0] != 0
+                || !Finite(distance) || distance == 0f || !TryMethod(method, out var extrudeMethod)) return null;
+            var before = CanonicalMeshSnapshot.Capture(go, requestedOccurrences);
+            if (before == null || before.Faces.Length != 1 || before.RawVertices.Length != 3 || before.SharedVertices.Length != 3
+                || !before.HasSharedTextures || before.Faces[0].DirectedRawTriangleStream.Length != 3) return null;
+            var face = before.Faces[0]; var stream = face.DirectedRawTriangleStream;
+            var renderer = go.GetComponent<Renderer>(); var materials = renderer == null ? null : renderer.sharedMaterials;
+            if (materials == null || materials.Length != 1 || materials[0] == null || face.SubmeshIndex != 0
+                || stream.Distinct().Count() != 3 || face.DirectedSharedTriangleStream.Distinct().Count() != 3 || before.RawVertices.Any(raw => !Finite(raw.LocalPosition))
+                || before.RawVertices.Select(raw => raw.LocalPosition).Distinct().Count() != 3 || before.SharedVertices.Any(group => group.MemberRawIndexes.Length != 1)
+                || face.Boundary.Length != 3 || !stream.OrderBy(raw => raw).SequenceEqual(new[] { 0, 1, 2 }) || !HasFiniteNonDegenerateUv(before)) return null;
+            var typedFaces = mesh.faces;
+            if (typedFaces == null || typedFaces.Count != 1 || typedFaces[0] == null) return null;
+            var typedFace = typedFaces[0]; var typedIndexes = typedFace.indexes.ToArray();
+            if (!typedIndexes.SequenceEqual(stream)) return null;
+            var edges = typedFace.edges.ToArray();
+            if (edges == null || edges.Length != 3 || edges.Any(edge => edge.a < 0 || edge.b < 0)) return null;
+            // group path 的 HashSet perimeter 遍历在单面时仍须证明为 face.edges 的唯一顺序，不能自行猜测。
+            var boundary = edges.SelectMany(edge => new[] { edge.a, edge.b }).ToArray();
+            if (!BoundaryExactlyMatchesTriangle(boundary, stream)) return null;
+            var normal = UnityEngine.ProBuilder.Math.Normal(mesh, typedFaces[0]);
+            if (!Finite(normal) || normal.sqrMagnitude == 0f) return null;
+            var delta = normal * distance;
+            if (extrudeMethod != ExtrudeMethod.IndividualFaces)
+            {
+                var direction = normal;
+                direction.Normalize();
+                var modifier = extrudeMethod == ExtrudeMethod.FaceNormal
+                    ? UnityEngine.ProBuilder.Math.Secant(Vector3.Angle(direction, normal) * Mathf.Deg2Rad)
+                    : 1f;
+                direction.x *= distance * modifier;
+                direction.y *= distance * modifier;
+                direction.z *= distance * modifier;
+                delta = direction;
+            }
+            if (!FiniteExtrudedGeometry(before, boundary, delta)) return null;
+            return new Plan { Before = before, FrozenFaces = new[] { typedFace }, Method = extrudeMethod, Distance = distance, BoundaryRaw = boundary, Delta = delta };
+        }
+
+        /// <summary>逐顶点和逐 side triangle 证明预测终态有限，避免有限输入在 effect 后溢出。</summary>
+        private static bool FiniteExtrudedGeometry(CanonicalMeshSnapshot before, int[] boundary, Vector3 delta)
+        {
+            if (before == null || boundary == null || boundary.Length != 6 || !Finite(delta)) return false;
+            if (before.RawVertices.Any(raw => !Finite(raw.LocalPosition + delta)
+                || !Finite(before.LocalToWorldMatrix.MultiplyPoint3x4(raw.LocalPosition + delta)))) return false;
+            var capPositions = before.RawVertices.Select(raw => raw.LocalPosition + delta).ToArray();
+            if (!CanonicalMeshSnapshot.RefreshArithmeticFinite(capPositions, before.RawVertices.Select(raw => raw.Uvs[0]).ToArray(), before.Faces.Select(face => face.DirectedRawTriangleStream), before.Faces.Select(face => face.SmoothingGroup))) return false;
+            for (var edge = 0; edge < 3; edge++)
+            {
+                var x = boundary[edge * 2]; var y = boundary[edge * 2 + 1];
+                if (x < 0 || y < 0 || x >= before.RawVertices.Length || y >= before.RawVertices.Length) return false;
+                var a = before.RawVertices[x].LocalPosition; var b = before.RawVertices[y].LocalPosition; var c = a + delta; var d = b + delta;
+                var first = UnityEngine.ProBuilder.Math.Normal(a, b, c); var second = UnityEngine.ProBuilder.Math.Normal(b, d, c);
+                if (!Finite(first) || !Finite(second) || first.sqrMagnitude == 0f || second.sqrMagnitude == 0f
+                    || !CanonicalMeshSnapshot.RefreshArithmeticFinite(
+                        new[] { a, b, c, d },
+                        new[] { new CanonicalMeshSnapshot.ChannelValue(true, new Vector2(0f, 0f)), new CanonicalMeshSnapshot.ChannelValue(true, new Vector2(1f, 0f)), new CanonicalMeshSnapshot.ChannelValue(true, new Vector2(0f, 1f)), new CanonicalMeshSnapshot.ChannelValue(true, new Vector2(1f, 1f)) },
+                        new[] { new[] { 0, 1, 2, 1, 3, 2 } }, new[] { 0 })) return false;
+            }
+            return true;
+        }
+
+        internal static bool Matches(Plan plan, string target)
+        {
+            if (plan == null || plan.Before == null || plan.FrozenFaces == null || plan.FrozenFaces.Length != 1) return false;
+            var freshMesh = CanonicalMeshSnapshot.ResolveFreshMesh(target, plan.Before.Identity);
+            var after = freshMesh == null ? null : CanonicalMeshSnapshot.Capture(freshMesh.gameObject);
+            if (after == null || !IdentityAndTransformEqual(plan.Before, after) || after.RawVertices.Length != 15 || after.Faces.Length != 4 || !after.HasSharedTextures) return false;
+            if (!RawPositionsAndPayloadExactly(plan, after) || !FacesExactly(plan, after) || !SharedPartitionExactly(plan, after)
+                || !SharedTexturesExactly(plan, after) || !DerivedNormalsAndTangentsMatch(after)) return false;
+            return AllRawReferenced(after);
+        }
+
+        private static bool RawPositionsAndPayloadExactly(Plan plan, CanonicalMeshSnapshot after)
+        {
+            var before = plan.Before; var expectedPosition = new Vector3[15]; var source = new int[15];
+            for (var raw = 0; raw < 3; raw++) { expectedPosition[raw] = before.RawVertices[raw].LocalPosition + plan.Delta; source[raw] = raw; }
+            for (var edge = 0; edge < 3; edge++)
+            {
+                var offset = 3 + edge * 4; var x = plan.BoundaryRaw[edge * 2]; var y = plan.BoundaryRaw[edge * 2 + 1];
+                expectedPosition[offset] = before.RawVertices[x].LocalPosition; expectedPosition[offset + 1] = before.RawVertices[y].LocalPosition;
+                expectedPosition[offset + 2] = before.RawVertices[x].LocalPosition + plan.Delta; expectedPosition[offset + 3] = before.RawVertices[y].LocalPosition + plan.Delta;
+                source[offset] = source[offset + 2] = x; source[offset + 1] = source[offset + 3] = y;
+            }
+            for (var raw = 0; raw < 15; raw++)
+            {
+                if (!CanonicalMeshSnapshot.ExactEquals(after.RawVertices[raw].LocalPosition, expectedPosition[raw])) return false;
+                if (raw < 3 ? !ClonePayloadEquals(before.RawVertices[source[raw]], after.RawVertices[raw])
+                    : !SidePayloadEquals(before.RawVertices[source[raw]], after.RawVertices[raw], (raw - 3) % 4)) return false;
+            }
+            return true;
+        }
+
+        private static bool FacesExactly(Plan plan, CanonicalMeshSnapshot after)
+        {
+            var beforeFace = plan.Before.Faces[0]; var cap = after.Faces[0];
+            var expectedSmoothing = plan.Method == ExtrudeMethod.IndividualFaces ? 0 : beforeFace.SmoothingGroup;
+            if (!FaceEquals(cap, beforeFace, beforeFace.DirectedRawTriangleStream, expectedSmoothing, -1, beforeFace.ElementGroup, beforeFace.ManualUv, beforeFace.Uv)) return false;
+            for (var edge = 0; edge < 3; edge++)
+            {
+                var offset = 3 + edge * 4;
+                if (!FaceEquals(after.Faces[edge + 1], beforeFace, new[] { offset, offset + 1, offset + 2, offset + 1, offset + 3, offset + 2 }, 0, -1, -1, true, beforeFace.Uv, CanonicalMeshSnapshot.WithSerializedFaceMaterial(beforeFace.Material, null))) return false;
+            }
+            return true;
+        }
+
+        private static bool SharedPartitionExactly(Plan plan, CanonicalMeshSnapshot after)
+        {
+            // 初始 lookup key 先按原 shared group/member 顺序枚举，因此所有 outer group 先确定 handle。
+            var expected = new List<List<int>>(); var outerByRaw = new Dictionary<int, List<int>>();
+            foreach (var sourceGroup in plan.Before.SharedVertices)
+            {
+                if (sourceGroup.MemberRawIndexes.Length != 1) return false;
+                var raw = sourceGroup.MemberRawIndexes[0];
+                if (outerByRaw.ContainsKey(raw)) return false;
+                var outer = new List<int> { raw }; outerByRaw.Add(raw, outer); expected.Add(outer);
+            }
+
+            // side raw key 随 boundary 顺序追加；old group 在 base clone 首遇时才获得 terminal handle。
+            var oldByRaw = new Dictionary<int, List<int>>();
+            for (var edge = 0; edge < 3; edge++)
+            {
+                var offset = 3 + edge * 4; var x = plan.BoundaryRaw[edge * 2]; var y = plan.BoundaryRaw[edge * 2 + 1];
+                if (!outerByRaw.TryGetValue(x, out var outerX) || !outerByRaw.TryGetValue(y, out var outerY)) return false;
+                if (!oldByRaw.TryGetValue(x, out var oldX)) { oldX = new List<int>(); oldByRaw.Add(x, oldX); expected.Add(oldX); }
+                oldX.Add(offset);
+                if (!oldByRaw.TryGetValue(y, out var oldY)) { oldY = new List<int>(); oldByRaw.Add(y, oldY); expected.Add(oldY); }
+                oldY.Add(offset + 1);
+                outerX.Add(offset + 2); outerY.Add(offset + 3);
+            }
+            return OrderedPartitionEquals(expected, after.SharedVertices.Select(group => group.MemberRawIndexes));
+        }
+
+        private static bool SharedTexturesExactly(Plan plan, CanonicalMeshSnapshot after)
+        {
+            var expected = plan.Before.SharedTextures.Select(group => group.MemberRawIndexes.Where(raw => raw >= 3).ToArray()).Where(group => group.Length > 0);
+            return PartitionEquals(expected, after.SharedTextures.Select(group => group.MemberRawIndexes));
+        }
+
+        /// <summary>按 5.2.4 Normals.CalculateNormals 的 hard-normal 与 shared/smoothing 分支复演，不将 Refresh 缓存当作未经验证的事实。</summary>
+        private static bool DerivedNormalsAndTangentsMatch(CanonicalMeshSnapshot snapshot)
+        {
+            var raw = snapshot.RawVertices; var normals = new Vector3[raw.Length]; var counts = new int[raw.Length];
+            foreach (var face in snapshot.Faces)
+            {
+                var stream = face.DirectedRawTriangleStream;
+                for (var index = 0; index < stream.Length; index += 3)
+                {
+                    var a = stream[index]; var b = stream[index + 1]; var c = stream[index + 2];
+                    var cross = UnityEngine.ProBuilder.Math.Normal(raw[a].LocalPosition, raw[b].LocalPosition, raw[c].LocalPosition);
+                    cross.Normalize();
+                    normals[a] += cross; normals[b] += cross; normals[c] += cross;
+                    counts[a]++; counts[b]++; counts[c]++;
+                }
+            }
+            if (counts.Any(count => count == 0)) return false;
+            for (var index = 0; index < normals.Length; index++) normals[index] /= counts[index];
+            foreach (var group in snapshot.SharedVertices)
+            foreach (var smoothing in snapshot.Faces.Select(face => face.SmoothingGroup).Where(value => value > SmoothingNone && (value <= SmoothRangeMax || value >= HardRangeMax)).Distinct())
+            {
+                var members = group.MemberRawIndexes.Where(index => SmoothingAt(snapshot, index) == smoothing).ToArray();
+                if (members.Length == 0) continue;
+                var average = Vector3.zero; foreach (var member in members) average += normals[member]; average /= members.Length; average = EnsureUnitVector(average);
+                foreach (var member in members) normals[member] = average;
+            }
+            for (var index = 0; index < raw.Length; index++)
+            {
+                var actual = new Vector3(raw[index].LocalNormal.Value.x, raw[index].LocalNormal.Value.y, raw[index].LocalNormal.Value.z);
+                if (!raw[index].LocalNormal.IsPresent || !Finite(normals[index]) || !Finite(actual) || !CanonicalMeshSnapshot.ExactEquals(actual, normals[index])) return false;
+            }
+            return TangentsMatch(snapshot, normals);
+        }
+
+        /// <summary>按 5.2.4 Normals.CalculateTangents 复演；无 UV0 或奇异 UV 映射无法形成精确有限终态，预检已拒绝。</summary>
+        private static bool TangentsMatch(CanonicalMeshSnapshot snapshot, Vector3[] normals)
+        {
+            var raw = snapshot.RawVertices;
+            if (raw.Any(vertex => !vertex.Uvs[0].IsPresent || !vertex.Tangent.IsPresent)) return false;
+            var tan1 = new Vector3[raw.Length]; var tan2 = new Vector3[raw.Length];
+            foreach (var face in snapshot.Faces)
+            {
+                var stream = face.DirectedRawTriangleStream;
+                for (var index = 0; index < stream.Length; index += 3)
+                {
+                    var a = stream[index]; var b = stream[index + 1]; var c = stream[index + 2];
+                    var v1 = raw[a].LocalPosition; var v2 = raw[b].LocalPosition; var v3 = raw[c].LocalPosition;
+                    var w1 = raw[a].Uvs[0].Value; var w2 = raw[b].Uvs[0].Value; var w3 = raw[c].Uvs[0].Value;
+                    float x1 = v2.x - v1.x; float x2 = v3.x - v1.x; float y1 = v2.y - v1.y; float y2 = v3.y - v1.y; float z1 = v2.z - v1.z; float z2 = v3.z - v1.z;
+                    float s1 = w2.x - w1.x; float s2 = w3.x - w1.x; float t1 = w2.y - w1.y; float t2 = w3.y - w1.y;
+                    float r = 1.0f / (s1 * t2 - s2 * t1);
+                    Vector3 sdir = new Vector3((t2 * x1 - t1 * x2) * r, (t2 * y1 - t1 * y2) * r, (t2 * z1 - t1 * z2) * r);
+                    Vector3 tdir = new Vector3((s1 * x2 - s2 * x1) * r, (s1 * y2 - s2 * y1) * r, (s1 * z2 - s2 * z1) * r);
+                    tan1[a] += sdir; tan1[b] += sdir; tan1[c] += sdir;
+                    tan2[a] += tdir; tan2[b] += tdir; tan2[c] += tdir;
+                }
+            }
+            for (var index = 0; index < raw.Length; index++)
+            {
+                var normal = normals[index]; var tangent = EnsureUnitVector(tan1[index]); Vector3.OrthoNormalize(ref normal, ref tangent);
+                var expected = new Vector4(tangent.x, tangent.y, tangent.z, Vector3.Dot(Vector3.Cross(normal, tangent), tan2[index]) < 0f ? -1f : 1f);
+                if (!Finite(expected) || !Finite(raw[index].Tangent.Value) || !CanonicalMeshSnapshot.ExactEquals(raw[index].Tangent.Value, expected)) return false;
+            }
+            return true;
+        }
+
+        private static bool HasFiniteNonDegenerateUv(CanonicalMeshSnapshot snapshot) => CanonicalMeshSnapshot.RefreshArithmeticFinite(snapshot);
+        private static int SmoothingAt(CanonicalMeshSnapshot snapshot, int raw) => snapshot.Faces.First(face => face.DirectedRawTriangleStream.Contains(raw)).SmoothingGroup;
+        /// <summary>ToMesh 清除 mesh.uv2；其余 authoritative UV/color 必须逐 raw 保持 source payload。</summary>
+        private static bool ClonePayloadEquals(CanonicalMeshSnapshot.RawVertex source, CanonicalMeshSnapshot.RawVertex actual)
+        {
+            if (!CanonicalMeshSnapshot.ChannelValueEquals(source.Color, actual.Color)) return false;
+            var sourceUvs = source.Uvs; var actualUvs = actual.Uvs;
+            return !actualUvs[1].IsPresent && new[] { 0, 2, 3 }.All(channel => CanonicalMeshSnapshot.ChannelValueEquals(sourceUvs[channel], actualUvs[channel]));
+        }
+        private static bool SidePayloadEquals(CanonicalMeshSnapshot.RawVertex source, CanonicalMeshSnapshot.RawVertex actual, int quadRawIndex)
+        {
+            if (!CanonicalMeshSnapshot.ChannelValueEquals(source.Color, actual.Color)) return false;
+            var sourceUvs = source.Uvs; var actualUvs = actual.Uvs;
+            return actualUvs[0].IsPresent && CanonicalMeshSnapshot.ExactEquals(actualUvs[0].Value, SideUv(quadRawIndex))
+                && !actualUvs[1].IsPresent && new[] { 2, 3 }.All(channel => CanonicalMeshSnapshot.ChannelValueEquals(sourceUvs[channel], actualUvs[channel]));
+        }
+        private static Vector4 SideUv(int raw) => raw == 0 ? new Vector4(0f, 0f, 0f, 0f) : raw == 1 ? new Vector4(1f, 0f, 0f, 0f) : raw == 2 ? new Vector4(0f, 1f, 0f, 0f) : new Vector4(1f, 1f, 0f, 0f);
+        private static bool FaceEquals(CanonicalMeshSnapshot.FaceOccurrence actual, CanonicalMeshSnapshot.FaceOccurrence source, int[] stream, int smoothing, int texture, int element, bool manual, AutoUnwrapSettings uv, CanonicalMeshSnapshot.MaterialClaim expectedMaterial = null) => actual != null && actual.SubmeshIndex == source.SubmeshIndex && actual.SmoothingGroup == smoothing && actual.TextureGroup == texture && actual.ElementGroup == element && actual.ManualUv == manual && CanonicalMeshSnapshot.MaterialValueEquals(actual.Material, expectedMaterial ?? source.Material) && CanonicalMeshSnapshot.UvValueEquals(actual.Uv, uv) && actual.DirectedRawTriangleStream.SequenceEqual(stream);
+        private static bool BoundaryExactlyMatchesTriangle(int[] edges, int[] stream) => edges.Length == 6 && edges[0] == stream[0] && edges[1] == stream[1] && edges[2] == stream[1] && edges[3] == stream[2] && edges[4] == stream[2] && edges[5] == stream[0];
+        private static bool AllRawReferenced(CanonicalMeshSnapshot snapshot) => snapshot.RawVertices.All(raw => snapshot.Faces.Any(face => face.DirectedRawTriangleStream.Contains(raw.RawIndex)));
+        private static bool IdentityAndTransformEqual(CanonicalMeshSnapshot before, CanonicalMeshSnapshot after) => CanonicalMeshSnapshot.IdentityAndTransformEqual(before, after);
+        /// <summary>shared handle 与 first-member 都是后续操作语义，必须逐组逐成员保持 package 顺序。</summary>
+        private static bool OrderedPartitionEquals(IEnumerable<IEnumerable<int>> expected, IEnumerable<IEnumerable<int>> actual)
+        {
+            var left = expected.Select(group => group.ToArray()).ToArray(); var right = actual.Select(group => group.ToArray()).ToArray();
+            return left.Length == right.Length && left.Select((members, index) => members.SequenceEqual(right[index])).All(equal => equal);
+        }
+        private static bool PartitionEquals(IEnumerable<IEnumerable<int>> expected, IEnumerable<IEnumerable<int>> actual)
+        {
+            var left = expected.Select(group => group.OrderBy(raw => raw).ToArray()).ToList(); var right = actual.Select(group => group.OrderBy(raw => raw).ToArray()).ToList();
+            if (left.Count != right.Count) return false;
+            foreach (var group in left) { var index = right.FindIndex(candidate => group.SequenceEqual(candidate)); if (index < 0) return false; right.RemoveAt(index); }
+            return right.Count == 0;
+        }
+        private static bool TryMethod(string value, out ExtrudeMethod method)
+        {
+            method = ExtrudeMethod.VertexNormal;
+            if (value == "individual") { method = ExtrudeMethod.IndividualFaces; return true; }
+            if (value == "vertexNormal") { method = ExtrudeMethod.VertexNormal; return true; }
+            if (value == "faceNormal") { method = ExtrudeMethod.FaceNormal; return true; }
+            return false;
+        }
+        private static bool Finite(float value) => !float.IsNaN(value) && !float.IsInfinity(value);
+        private static bool Finite(Vector3 value) => Finite(value.x) && Finite(value.y) && Finite(value.z);
+        private static bool Finite(Vector4 value) => Finite(value.x) && Finite(value.y) && Finite(value.z) && Finite(value.w);
+        private static Vector3 EnsureUnitVector(Vector3 value) => Mathf.Abs(value.sqrMagnitude) < float.Epsilon ? Vector3.up : value.normalized;
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/ProBuilderFlipCompletionProof.cs

@@ -0,0 +1,170 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using UnityEngine;
+using UnityEngine.ProBuilder;
+
+namespace UnityCli.ProBuilder
+{
+    /// <summary>flip-normals 与 duplicate-and-flip 的请求专属终态证明；planner 只读取 barrier 前快照。</summary>
+    internal static class ProBuilderFlipCompletionProof
+    {
+        private const int SmoothingNone = 0;
+        private const int SmoothRangeMax = 24;
+        private const int HardRangeMax = 42;
+
+        internal sealed class Plan
+        {
+            internal readonly CanonicalMeshSnapshot Before;
+            internal readonly Face[] FrozenFaces;
+            internal readonly RawPlan[] Raw;
+            internal readonly FacePlan[] Faces;
+            internal readonly int[][] Shared;
+            internal readonly int[][] SharedTextures;
+            internal readonly bool HasSharedTextures;
+            internal Plan(CanonicalMeshSnapshot before, Face[] frozen, IEnumerable<RawPlan> raw, IEnumerable<FacePlan> faces, IEnumerable<int[]> shared, bool hasTextures, IEnumerable<int[]> textures)
+            { Before = before; FrozenFaces = frozen.ToArray(); Raw = raw.ToArray(); Faces = faces.ToArray(); Shared = shared.Select(x => x.ToArray()).ToArray(); HasSharedTextures = hasTextures; SharedTextures = textures.Select(x => x.ToArray()).ToArray(); }
+        }
+        internal sealed class RawPlan
+        {
+            internal readonly Vector3 Position;
+            internal CanonicalMeshSnapshot.ChannelValue Normal, Tangent;
+            internal readonly CanonicalMeshSnapshot.ChannelValue Color;
+            internal readonly CanonicalMeshSnapshot.ChannelValue[] Uvs;
+            internal RawPlan(CanonicalMeshSnapshot.RawVertex raw) { Position = raw.LocalPosition; Normal = raw.LocalNormal; Tangent = raw.Tangent; Color = raw.Color; Uvs = raw.Uvs; }
+        }
+        internal sealed class FacePlan
+        {
+            internal readonly CanonicalMeshSnapshot.FaceOccurrence Source;
+            internal readonly int[] Stream;
+            internal FacePlan(CanonicalMeshSnapshot.FaceOccurrence source, IEnumerable<int> stream) { Source = source; Stream = stream.ToArray(); }
+        }
+
+        /// <summary>冻结 Face[] 与完整 canonical 状态；selected occurrence 必须去重且与 typed Face 引用一一对应。</summary>
+        internal static Plan CaptureFlip(GameObject target, Face[] faces, int[] occurrences)
+        {
+            var before = Capture(target, faces, occurrences);
+            if (before == null) return null;
+            var selected = new HashSet<int>(occurrences);
+            var raw = before.RawVertices.Select(x => new RawPlan(x)).ToArray();
+            var terminal = before.Faces.Select(face => new FacePlan(face, selected.Contains(face.OccurrenceIndex) ? face.DirectedRawTriangleStream.Reverse() : face.DirectedRawTriangleStream)).ToArray();
+            ClearUnityMeshUv2(raw);
+            if (!RefreshArithmeticFinite(raw, terminal) || !CalculateNormalsAndTangents(raw, terminal, before.SharedVertices.Select(x => x.MemberRawIndexes))) return null;
+            return new Plan(before, faces, raw, terminal, before.SharedVertices.Select(x => x.MemberRawIndexes), before.HasSharedTextures, before.SharedTextures.Select(x => x.MemberRawIndexes));
+        }
+
+        /// <summary>逐句镜像 5.2.4 DuplicateAndFlip：按冻结请求顺序及 raw 首遇顺序复制顶点，再用反向 mapped stream 重建 Face。</summary>
+        internal static Plan CaptureDuplicateAndFlip(GameObject target, Face[] faces, int[] occurrences)
+        {
+            var before = Capture(target, faces, occurrences);
+            if (before == null) return null;
+            var raw = before.RawVertices.Select(x => new RawPlan(x)).ToList();
+            var shared = before.SharedVertices.Select(x => x.MemberRawIndexes.ToList()).ToList();
+            var terminal = before.Faces.Select(face => new FacePlan(face, face.DirectedRawTriangleStream)).ToList();
+            foreach (var occurrence in occurrences)
+            {
+                // 5.2.4 在每个 FaceRebuildData group 内新建 map；共享 raw 被不同 selected face 各自独立复制。
+                var map = new Dictionary<int, int>();
+                var source = before.Faces.Single(face => face.OccurrenceIndex == occurrence);
+                foreach (var oldRaw in source.DirectedRawTriangleStream)
+                {
+                    if (map.ContainsKey(oldRaw)) continue;
+                    var newRaw = raw.Count; map.Add(oldRaw, newRaw); raw.Add(new RawPlan(before.RawVertices[oldRaw]));
+                    shared[before.RawVertices[oldRaw].SharedHandle].Add(newRaw);
+                }
+                // FaceRebuildData.Apply 将每个 request group 的 raw 与其 duplicate face 依次 append；Face attrs 原样复制。
+                terminal.Add(new FacePlan(source, source.DirectedRawTriangleStream.Reverse().Select(oldRaw => map[oldRaw])));
+            }
+            ClearUnityMeshUv2(raw);
+            if (!RefreshArithmeticFinite(raw, terminal) || !CalculateNormalsAndTangents(raw, terminal, shared)) return null;
+            // SetSharedTextures 即使原值为 null 也会写入 non-null 分区；新 raw 不加入旧 texture group。
+            return new Plan(before, faces, raw, terminal, shared.Select(x => x.ToArray()), true, before.SharedTextures.Select(x => x.MemberRawIndexes));
+        }
+
+        private static bool RefreshArithmeticFinite(IEnumerable<RawPlan> raw, IEnumerable<FacePlan> faces)
+        {
+            var vertices = raw.ToArray(); var terminal = faces.ToArray();
+            return CanonicalMeshSnapshot.RefreshArithmeticFinite(vertices.Select(value => value.Position).ToArray(), vertices.Select(value => value.Uvs[0]).ToArray(), terminal.Select(face => face.Stream), terminal.Select(face => face.Source.SmoothingGroup), true);
+        }
+
+        /// <summary>effect 后只允许用 effect 前 identity fresh-resolve；逐 raw、逐 face、逐 partition 比较完整 terminal state。</summary>
+        internal static bool FlipMatches(Plan plan, string target) => Matches(plan, target);
+        internal static bool DuplicateAndFlipMatches(Plan plan, string target) => Matches(plan, target);
+        private static bool Matches(Plan plan, string target)
+        {
+            if (plan == null) return false;
+            var fresh = CanonicalMeshSnapshot.ResolveFreshMesh(target, plan.Before.Identity);
+            var after = fresh == null ? null : CanonicalMeshSnapshot.Capture(fresh.gameObject, Array.Empty<int>());
+            if (after == null || !Stable(plan.Before, after) || after.RawVertices.Length != plan.Raw.Length || after.Faces.Length != plan.Faces.Length || after.HasSharedTextures != plan.HasSharedTextures) return false;
+            for (var i = 0; i < plan.Raw.Length; i++) if (!RawEquals(after.RawVertices[i], plan.Raw[i])) return false;
+            for (var i = 0; i < plan.Faces.Length; i++) if (!FaceEquals(after.Faces[i], plan.Faces[i])) return false;
+            return PartitionsEqual(after.SharedVertices.Select(x => x.MemberRawIndexes), plan.Shared) && PartitionsEqual(after.SharedTextures.Select(x => x.MemberRawIndexes), plan.SharedTextures);
+        }
+
+        private static CanonicalMeshSnapshot Capture(GameObject target, Face[] faces, int[] occurrences)
+        {
+            if (target == null || faces == null || occurrences == null || faces.Length == 0 || faces.Length != occurrences.Length || occurrences.Distinct().Count() != occurrences.Length) return null;
+            var before = CanonicalMeshSnapshot.Capture(target, occurrences);
+            if (before == null || before.Faces.Length == 0 || !MaterialSlotsStable(target, before)) return null;
+            for (var i = 0; i < occurrences.Length; i++) if (occurrences[i] < 0 || occurrences[i] >= before.Faces.Length || !ReferenceEquals(faces[i], target.GetComponent<ProBuilderMesh>().faces[occurrences[i]])) return null;
+            return before;
+        }
+        /// <summary>ToMesh 会压缩空 submesh；只有所有 material slot 被一个合法 face 使用时，slot/material 对应关系才可完整证明。</summary>
+        private static bool MaterialSlotsStable(GameObject target, CanonicalMeshSnapshot before)
+        {
+            var renderer = target.GetComponent<Renderer>(); var materials = renderer == null ? null : renderer.sharedMaterials;
+            if (materials == null || materials.Length == 0) return false;
+            var used = new HashSet<int>();
+            foreach (var face in before.Faces)
+            {
+                if (face.SubmeshIndex < 0 || face.SubmeshIndex >= materials.Length) return false;
+                used.Add(face.SubmeshIndex);
+            }
+            return used.SetEquals(Enumerable.Range(0, materials.Length));
+        }
+        /// <summary>RefreshMeshPreservingVertexPayload 仍经 ToMesh，Unity Mesh 的 uv2 会被无条件清除。</summary>
+        private static void ClearUnityMeshUv2(IEnumerable<RawPlan> raw)
+        {
+            foreach (var vertex in raw) vertex.Uvs[1] = new CanonicalMeshSnapshot.ChannelValue(false, Vector4.zero);
+        }
+        private static bool Stable(CanonicalMeshSnapshot a, CanonicalMeshSnapshot b) => CanonicalMeshSnapshot.IdentityAndTransformEqual(a, b);
+        private static bool RawEquals(CanonicalMeshSnapshot.RawVertex actual, RawPlan expected) => CanonicalMeshSnapshot.ExactEquals(actual.LocalPosition, expected.Position) && CanonicalMeshSnapshot.ChannelValueEquals(actual.LocalNormal, expected.Normal) && CanonicalMeshSnapshot.ChannelValueEquals(actual.Tangent, expected.Tangent) && CanonicalMeshSnapshot.ChannelValueEquals(actual.Color, expected.Color) && actual.Uvs.Zip(expected.Uvs, CanonicalMeshSnapshot.ChannelValueEquals).All(x => x);
+        private static bool FaceEquals(CanonicalMeshSnapshot.FaceOccurrence actual, FacePlan expected) => actual.DirectedRawTriangleStream.SequenceEqual(expected.Stream) && actual.SubmeshIndex == expected.Source.SubmeshIndex && actual.SmoothingGroup == expected.Source.SmoothingGroup && actual.TextureGroup == expected.Source.TextureGroup && actual.ElementGroup == expected.Source.ElementGroup && actual.ManualUv == expected.Source.ManualUv && CanonicalMeshSnapshot.UvValueEquals(actual.Uv, expected.Source.Uv) && CanonicalMeshSnapshot.MaterialValueEquals(actual.Material, expected.Source.Material);
+        /// <summary>raw index 在此终态保持稳定；shared/sharedTexture 的每个 handle 与成员流均逐项精确比较。</summary>
+        private static bool PartitionsEqual(IEnumerable<IEnumerable<int>> actual, IEnumerable<IEnumerable<int>> expected)
+        {
+            var left = actual.Select(x => x.ToArray()).ToArray(); var right = expected.Select(x => x.ToArray()).ToArray();
+            return left.Length == right.Length && left.Select((members, index) => members.SequenceEqual(right[index])).All(value => value);
+        }
+
+        /// <summary>纯 5.2.4 Normals/CalculateTangents replay；先重建 normal，再由终态 position 与 UV0 得到 tangent。</summary>
+        private static bool CalculateNormalsAndTangents(IList<RawPlan> raw, IList<FacePlan> faces, IEnumerable<IEnumerable<int>> shared)
+        {
+            var normals = new Vector3[raw.Count]; var counts = new int[raw.Count];
+            foreach (var face in faces) for (var i = 0; i < face.Stream.Length; i += 3)
+            {
+                var a = face.Stream[i]; var b = face.Stream[i + 1]; var c = face.Stream[i + 2]; var normal = UnityEngine.ProBuilder.Math.Normal(raw[a].Position, raw[b].Position, raw[c].Position); normal.Normalize();
+                normals[a] += normal; normals[b] += normal; normals[c] += normal; counts[a]++; counts[b]++; counts[c]++;
+            }
+            if (counts.Any(x => x == 0)) return false;
+            for (var i = 0; i < raw.Count; i++) normals[i] /= counts[i];
+            var smoothing = new int[raw.Count]; var maximum = SmoothRangeMax;
+            foreach (var face in faces) foreach (var index in face.Stream.Distinct()) { smoothing[index] = face.Source.SmoothingGroup; if (smoothing[index] >= maximum) maximum = smoothing[index] + 1; }
+            foreach (var members in shared) { var sums = new Vector3[maximum]; var groupCounts = new float[maximum]; foreach (var i in members) { var group = smoothing[i]; if (group <= SmoothingNone || group > SmoothRangeMax && group < HardRangeMax) continue; sums[group] += normals[i]; groupCounts[group]++; } foreach (var i in members) { var group = smoothing[i]; if (group <= SmoothingNone || group > SmoothRangeMax && group < HardRangeMax) continue; normals[i] = EnsureUnitVector(sums[group] / groupCounts[group]); } }
+            for (var i = 0; i < raw.Count; i++) raw[i].Normal = new CanonicalMeshSnapshot.ChannelValue(true, normals[i]);
+            if (raw.Any(x => !x.Uvs[0].IsPresent)) { for (var i = 0; i < raw.Count; i++) raw[i].Tangent = new CanonicalMeshSnapshot.ChannelValue(true, Vector4.zero); return Finite(raw); }
+            var tan1 = new Vector3[raw.Count]; var tan2 = new Vector3[raw.Count];
+            foreach (var face in faces) for (var i = 0; i < face.Stream.Length; i += 3)
+            {
+                var a = face.Stream[i]; var b = face.Stream[i + 1]; var c = face.Stream[i + 2]; var p1 = raw[a].Position; var p2 = raw[b].Position; var p3 = raw[c].Position; var uv1 = raw[a].Uvs[0].Value; var uv2 = raw[b].Uvs[0].Value; var uv3 = raw[c].Uvs[0].Value; var r = 1f / ((uv2.x - uv1.x) * (uv3.y - uv1.y) - (uv3.x - uv1.x) * (uv2.y - uv1.y)); var s = new Vector3(((uv3.y-uv1.y)*(p2.x-p1.x)-(uv2.y-uv1.y)*(p3.x-p1.x))*r, ((uv3.y-uv1.y)*(p2.y-p1.y)-(uv2.y-uv1.y)*(p3.y-p1.y))*r, ((uv3.y-uv1.y)*(p2.z-p1.z)-(uv2.y-uv1.y)*(p3.z-p1.z))*r); var t = new Vector3(((uv2.x-uv1.x)*(p3.x-p1.x)-(uv3.x-uv1.x)*(p2.x-p1.x))*r, ((uv2.x-uv1.x)*(p3.y-p1.y)-(uv3.x-uv1.x)*(p2.y-p1.y))*r, ((uv2.x-uv1.x)*(p3.z-p1.z)-(uv3.x-uv1.x)*(p2.z-p1.z))*r); foreach (var x in new[] { a, b, c }) { tan1[x] += s; tan2[x] += t; }
+            }
+            for (var i = 0; i < raw.Count; i++) { var n = normals[i]; var t = EnsureUnitVector(tan1[i]); Vector3.OrthoNormalize(ref n, ref t); raw[i].Tangent = new CanonicalMeshSnapshot.ChannelValue(true, new Vector4(t.x, t.y, t.z, Vector3.Dot(Vector3.Cross(n, t), tan2[i]) < 0f ? -1f : 1f)); }
+            return Finite(raw);
+        }
+        private static bool Finite(IEnumerable<RawPlan> raw) => raw.All(x => Finite(x.Normal.Value) && Finite(x.Tangent.Value));
+        private static bool Finite(Vector4 x) => !float.IsNaN(x.x) && !float.IsInfinity(x.x) && !float.IsNaN(x.y) && !float.IsInfinity(x.y) && !float.IsNaN(x.z) && !float.IsInfinity(x.z) && !float.IsNaN(x.w) && !float.IsInfinity(x.w);
+        private static Vector3 EnsureUnitVector(Vector3 value) => Mathf.Abs(value.sqrMagnitude) < float.Epsilon ? Vector3.up : value.normalized;
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/ProBuilderInput.cs

@@ -0,0 +1,85 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli.ProBuilder
+{
+    /// <summary>
+    /// ProBuilder Tool 的场景对象解析 helper。
+    /// </summary>
+    internal static class ProBuilderInput
+    {
+        /// <summary>
+        /// 由两个顶点索引表示的边。
+        /// </summary>
+        public struct EdgePair
+        {
+            public int a;
+            public int b;
+        }
+
+        /// <summary>
+        /// 按 instance id、完整层级路径或名称唯一解析目标；存在多个同名候选时拒绝猜测。
+        /// </summary>
+        public static GameObject ResolveTarget(string target)
+        {
+            if (string.IsNullOrWhiteSpace(target)) return null;
+
+            int instanceId;
+            if (int.TryParse(target, NumberStyles.Integer, CultureInfo.InvariantCulture, out instanceId))
+                return EditorUtility.InstanceIDToObject(instanceId) as GameObject;
+
+            var candidates = new List<GameObject>();
+            foreach (var go in EnumerateLoadedObjects())
+            {
+                if (target.IndexOf('/') >= 0 ? HierarchyPath(go) == target.Trim('/') : go.name == target)
+                    candidates.Add(go);
+            }
+            return candidates.Count == 1 ? candidates[0] : null;
+        }
+
+        /// <summary>
+        /// 批量解析必须全部唯一且互不重复；任何失败都不返回部分结果，并保持请求顺序。
+        /// </summary>
+        public static GameObject[] ResolveTargets(IEnumerable<string> targets)
+        {
+            if (targets == null) return new GameObject[0];
+
+            var results = new List<GameObject>();
+            var seen = new HashSet<int>();
+            foreach (var target in targets)
+            {
+                var go = ResolveTarget(target);
+                if (go == null || !seen.Add(go.GetInstanceID())) return new GameObject[0];
+                results.Add(go);
+            }
+            return results.ToArray();
+        }
+
+        private static IEnumerable<GameObject> EnumerateLoadedObjects()
+        {
+            for (var i = 0; i < UnityEngine.SceneManagement.SceneManager.sceneCount; i++)
+            {
+                var scene = UnityEngine.SceneManagement.SceneManager.GetSceneAt(i);
+                if (!scene.isLoaded) continue;
+                foreach (var root in scene.GetRootGameObjects())
+                {
+                    yield return root;
+                    foreach (var child in root.GetComponentsInChildren<Transform>(true))
+                        if (child != root.transform) yield return child.gameObject;
+                }
+            }
+        }
+
+        private static string HierarchyPath(GameObject go)
+        {
+            var names = new Stack<string>();
+            for (var current = go.transform; current != null; current = current.parent)
+                names.Push(current.name);
+            return string.Join("/", names.ToArray());
+        }
+    }
+}
+#endif