pi-revit 0.3.1 → 0.4.0

package/src/Revit/Tools/ManageViews.cs

@@ -0,0 +1,100 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ManageViews : ITool
+{
+    public string Name => "manage_views";
+    public string Label => "Manage Views";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Create a plan, isometric 3D view or section; duplicate or update an existing view. Resolve view-family-type IDs with get_element_types (of_class ViewFamilyType), and level IDs with get_elements. A section uses document internal axes and explicit length units, orthogonal viewing_direction/up vectors, origin, width/height/depth. Duplication options are duplicate, with_detailing or dependent. Optional name, scale and view_template_id apply in the same transaction; -1 removes a template. Incompatible templates or template-controlled scale changes fail without removing the template. preview=true commit-validates then rolls back; created preview IDs are temporary. Use delete_elements to remove views.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            action = new { type = "string", @enum = new[] { "create_plan", "create_3d", "create_section", "duplicate", "update" } },
+            view_id = new { type = "integer", description = "Existing view for duplicate/update." },
+            view_family_type_id = new { type = "integer", description = "Compatible ViewFamilyType for creation." },
+            level_id = new { type = "integer", description = "Level for create_plan." },
+            duplicate_option = new { type = "string", @enum = new[] { "duplicate", "with_detailing", "dependent" } },
+            name = new { type = "string", minLength = 1 }, scale = new { type = "integer", minimum = 1, maximum = 24000 },
+            view_template_id = new { type = "integer", description = "Compatible template ID, or -1 to remove." },
+            unit = ModelEditInputs.LengthUnitSchema,
+            origin = ModelEditInputs.VectorSchema("Section origin in document internal coordinates, in unit."),
+            viewing_direction = ModelEditInputs.VectorSchema("Section viewing direction, dimensionless nonzero vector."),
+            up = ModelEditInputs.VectorSchema("Section up vector, orthogonal to viewing_direction."),
+            width = new { type = "number", exclusiveMinimum = 0 }, height = new { type = "number", exclusiveMinimum = 0 }, depth = new { type = "number", exclusiveMinimum = 0 },
+            preview = ModelEditInputs.PreviewSchema,
+        }, required = new[] { "action" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        string action = JsonArgs.GetString(args, "action") ?? "";
+        if (action is not ("create_plan" or "create_3d" or "create_section" or "duplicate" or "update")) throw new ArgumentException("Unknown view action.");
+        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(new() { ["action"] = action }, () =>
+        {
+            ElementId Id(string key) => new(JsonArgs.GetLong(args, key) is long id && id > 0 ? id : throw new ArgumentException($"{key} must be a positive ID."));
+            View view;
+            object? before = null;
+            if (action is "duplicate" or "update")
+            {
+                view = doc.GetElement(Id("view_id")) as View ?? throw new ArgumentException("view_id is not a view.");
+                before = Describe(view);
+                if (action == "duplicate")
+                {
+                    var option = (JsonArgs.GetString(args, "duplicate_option") ?? "duplicate") switch
+                    {
+                        "duplicate" => ViewDuplicateOption.Duplicate, "with_detailing" => ViewDuplicateOption.WithDetailing,
+                        "dependent" => ViewDuplicateOption.AsDependent, _ => throw new ArgumentException("Invalid duplicate_option."),
+                    };
+                    if (!view.CanViewBeDuplicated(option)) throw new ArgumentException("This view cannot be duplicated with that option.");
+                    view = (View)doc.GetElement(view.Duplicate(option));
+                }
+            }
+            else if (action == "create_plan") view = ViewPlan.Create(doc, Id("view_family_type_id"), Id("level_id"));
+            else if (action == "create_3d") view = View3D.CreateIsometric(doc, Id("view_family_type_id"));
+            else
+            {
+                double factor = ModelEditInputs.LengthScale(args);
+                var origin = ModelEditInputs.Vector(args, "origin").Multiply(factor);
+                var direction = ModelEditInputs.Vector(args, "viewing_direction");
+                var up = ModelEditInputs.Vector(args, "up");
+                if (direction.GetLength() < 1e-12 || up.GetLength() < 1e-12) throw new ArgumentException("Section directions must be nonzero.");
+                direction = direction.Normalize(); up = up.Normalize();
+                if (Math.Abs(direction.DotProduct(up)) > 1e-8) throw new ArgumentException("Section up and viewing_direction must be orthogonal.");
+                double width = ModelEditInputs.Number(args, "width") * factor, height = ModelEditInputs.Number(args, "height") * factor, depth = ModelEditInputs.Number(args, "depth") * factor;
+                if (width <= 1e-6 || height <= 1e-6 || depth <= 1e-6) throw new ArgumentException("Section dimensions must exceed 0.000001 feet.");
+                var transform = Transform.Identity;
+                transform.Origin = origin; transform.BasisZ = direction; transform.BasisY = up; transform.BasisX = up.CrossProduct(direction).Normalize();
+                using var box = new BoundingBoxXYZ { Transform = transform, Min = new XYZ(-width / 2, -height / 2, 0), Max = new XYZ(width / 2, height / 2, depth), Enabled = true };
+                view = ViewSection.CreateSection(doc, Id("view_family_type_id"), box);
+            }
+            if (args.TryGetProperty("name", out var name))
+            {
+                if (name.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(name.GetString())) throw new ArgumentException("name must be nonempty.");
+                view.Name = name.GetString()!;
+            }
+            if (args.TryGetProperty("view_template_id", out _))
+            {
+                long template = JsonArgs.GetLong(args, "view_template_id") ?? 0;
+                if (template != -1 && (template <= 0 || !view.IsValidViewTemplate(new ElementId(template)))) throw new ArgumentException("view_template_id is not compatible with this view.");
+                view.ViewTemplateId = new ElementId(template);
+            }
+            if (args.TryGetProperty("scale", out var scale))
+            {
+                if (!scale.TryGetInt32(out int value) || value is < 1 or > 24000) throw new ArgumentException("scale must be an integer from 1 to 24000.");
+                var parameter = view.get_Parameter(BuiltInParameter.VIEW_SCALE);
+                if (parameter == null) throw new ArgumentException("This view's scale is unavailable.");
+                if (doc.GetElement(view.ViewTemplateId) is View template && template.GetTemplateParameterIds().Except(template.GetNonControlledTemplateParameterIds()).Contains(parameter.Id))
+                    throw new ArgumentException("This view's scale is controlled by its template.");
+                view.Scale = value;
+            }
+            doc.Regenerate();
+            return new() { ["before"] = before, ["view"] = Describe(view), ["created"] = action != "update", ["id_is_temporary"] = action != "update" && JsonArgs.GetBool(args, "preview", false) };
+        }) }).Payload;
+    }
+    private static object Describe(View view) => new { id = view.Id.Value, unique_id = view.UniqueId, name = view.Name, view_type = view.ViewType.ToString(), template_id = view.ViewTemplateId.Value, scale = view.Scale };
+}

package/src/Revit/Tools/MeasureGeometry.cs

@@ -0,0 +1,54 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class MeasureGeometry : ITool
+{
+    public string Name => "measure_geometry";
+    public string Label => "Measure Geometry";
+    public string Tier => "advanced";
+    public string Description => "Measure exact Euclidean distance between two explicit points, or approximate separation between two host elements' model axis-aligned bounding boxes. Required unit applies to point inputs, optional clearance threshold, and all output coordinates/distances. Points use document internal axes. Box gap is a lower bound on geometry separation: zero means enclosing boxes touch/overlap, not a confirmed clash. Bounds can include nonphysical geometry. An optional clearance threshold classifies only box proximity, never a physical clearance failure. Does not traverse linked contents.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            mode = new { type = "string", @enum = new[] { "point_distance", "bounding_box_gap" } }, unit = ModelEditInputs.LengthUnitSchema,
+            point_a = ModelEditInputs.VectorSchema("First point in document internal axes, in unit."), point_b = ModelEditInputs.VectorSchema("Second point in document internal axes, in unit."),
+            element_a_id = new { type = "integer", minimum = 1 }, element_b_id = new { type = "integer", minimum = 1 },
+            clearance = new { type = "number", minimum = 0, description = "Optional box-proximity threshold in unit, only for bounding_box_gap." },
+        }, required = new[] { "mode", "unit" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        double scale = ModelEditInputs.LengthScale(args);
+        string? mode = JsonArgs.GetString(args, "mode"), unit = JsonArgs.GetString(args, "unit");
+        if (mode == "point_distance")
+        {
+            if (args.TryGetProperty("clearance", out _) || args.TryGetProperty("element_a_id", out _) || args.TryGetProperty("element_b_id", out _))
+                throw new ArgumentException("point_distance accepts points, not element IDs or clearance.");
+            var a = ModelEditInputs.Vector(args, "point_a").Multiply(scale); var b = ModelEditInputs.Vector(args, "point_b").Multiply(scale);
+            return new { method = mode, approximate = false, coordinate_system = "document_internal", unit, distance = a.DistanceTo(b) / scale,
+                delta = SpatialBounds.Coordinates(b - a, scale), point_a = SpatialBounds.Coordinates(a, scale), point_b = SpatialBounds.Coordinates(b, scale) };
+        }
+        if (mode != "bounding_box_gap") throw new ArgumentException("Unknown measurement mode.");
+        if (args.TryGetProperty("point_a", out _) || args.TryGetProperty("point_b", out _)) throw new ArgumentException("bounding_box_gap accepts element IDs, not points.");
+        Element Resolve(string key)
+        {
+            long id = JsonArgs.GetLong(args, key) ?? 0;
+            return id > 0 ? doc.GetElement(new ElementId(id)) ?? throw new ArgumentException($"{key} {id} was not found.") : throw new ArgumentException($"{key} must be positive.");
+        }
+        var elementA = Resolve("element_a_id"); var elementB = Resolve("element_b_id");
+        var boundsA = SpatialBounds.Of(elementA) ?? throw new ArgumentException($"Element {elementA.Id.Value} has no model bounding box.");
+        var boundsB = SpatialBounds.Of(elementB) ?? throw new ArgumentException($"Element {elementB.Id.Value} has no model bounding box.");
+        var gap = boundsA.Gap(boundsB); double distance = gap.GetLength() / scale;
+        double? clearance = args.TryGetProperty("clearance", out _) ? ModelEditInputs.Number(args, "clearance") : null;
+        if (clearance < 0) throw new ArgumentException("clearance cannot be negative.");
+        return new { method = mode, approximate = true, coordinate_system = "document_internal", unit, distance, axis_gaps = SpatialBounds.Coordinates(gap, scale),
+            boxes_overlap_or_touch = boundsA.Intersects(boundsB), clearance, box_gap_below_clearance = clearance.HasValue ? (bool?)(distance < clearance.Value) : null,
+            interpretation = "Bounding-box gap is a lower bound on geometry separation. Overlap or a gap below clearance identifies candidates for geometry review, not a confirmed clash or clearance failure.",
+            element_a = new { id = elementA.Id.Value, unique_id = elementA.UniqueId, bounds = boundsA.Describe(scale) },
+            element_b = new { id = elementB.Id.Value, unique_id = elementB.UniqueId, bounds = boundsB.Describe(scale) } };
+    }
+}

package/src/Revit/Tools/ModelEditBatch.cs

@@ -0,0 +1,102 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+/// <summary>Runs model-only edits. Files, UI actions and arbitrary scripts must not use this preview contract.</summary>
+internal static class ModelEditBatch
+{
+    internal sealed record Step(Dictionary<string, object?> Target, Func<Dictionary<string, object?>> Apply);
+
+    internal sealed record Result(bool Committed, bool Preview, bool Atomic, bool CommitValidationPerformed,
+        IReadOnlyList<Dictionary<string, object?>> Succeeded, IReadOnlyList<Dictionary<string, object?>> Proposed,
+        IReadOnlyList<Dictionary<string, object?>> Failed, IReadOnlyList<string> Warnings)
+    {
+        public object Payload => new
+        {
+            updated = Committed ? Succeeded.Count : 0, committed = Committed, preview = Preview, atomic = Atomic,
+            succeeded = Succeeded, proposed = Proposed, failed = Failed, commitWarnings = Warnings,
+            commit_validation_performed = CommitValidationPerformed,
+            validation = Preview ? (CommitValidationPerformed ? "Revit commit validation completed; preview group rollback confirmed." : "Preview group rollback confirmed. Commit-time validation was not performed because the batch was rejected before commit.") : null,
+        };
+    }
+
+    public static Result Run(Document doc, string name, JsonElement args, IReadOnlyList<Step> steps)
+    {
+        foreach (string flag in new[] { "preview", "atomic" })
+            if (args.TryGetProperty(flag, out var value) && value.ValueKind is not (JsonValueKind.True or JsonValueKind.False))
+                throw new ArgumentException($"{flag} must be a boolean; no edits were attempted.");
+        bool preview = JsonArgs.GetBool(args, "preview", false);
+        bool atomic = JsonArgs.GetBool(args, "atomic", false);
+        var accepted = new List<Dictionary<string, object?>>();
+        var failed = new List<Dictionary<string, object?>>();
+        using var group = preview ? new TransactionGroup(doc, name + " preview") : null;
+        using var transaction = new Transaction(doc, name);
+        try
+        {
+            if (group != null && group.Start() != TransactionStatus.Started) throw new InvalidOperationException("Could not start preview transaction group.");
+            if (transaction.Start() != TransactionStatus.Started) throw new InvalidOperationException("Could not start model transaction.");
+            var failures = FailureGuard.Attach(transaction);
+            for (int index = 0; index < steps.Count; index++)
+            {
+                var step = steps[index];
+                using var part = new SubTransaction(doc);
+                if (part.Start() != TransactionStatus.Started) throw new InvalidOperationException("Could not start edit subtransaction.");
+                Dictionary<string, object?> change;
+                try
+                {
+                    change = step.Apply();
+                    if (part.Commit() != TransactionStatus.Committed || part.GetStatus() != TransactionStatus.Committed)
+                        throw new InvalidOperationException("Edit subtransaction did not commit.");
+                }
+                catch (Autodesk.Revit.Exceptions.RegenerationFailedException) { throw; }
+                catch (Exception error)
+                {
+                    if (part.GetStatus() == TransactionStatus.Started) part.RollBack();
+                    if (part.GetStatus() != TransactionStatus.RolledBack)
+                        throw new InvalidOperationException("Edit rollback could not be confirmed; stopping the batch.", error);
+                    var rejection = new Dictionary<string, object?>(step.Target) { ["index"] = index, ["reason"] = error.Message };
+                    failed.Add(rejection);
+                    continue;
+                }
+                var row = new Dictionary<string, object?>(step.Target) { ["index"] = index };
+                foreach (var field in change) row[field.Key] = field.Value;
+                accepted.Add(row);
+            }
+            bool commit = accepted.Count > 0 && !(atomic && failed.Count > 0);
+            if (commit)
+            {
+                var status = transaction.Commit();
+                if (status != TransactionStatus.Committed || transaction.GetStatus() != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"Commit returned {status}; final status {transaction.GetStatus()}." + failures.DescribeErrors());
+            }
+            else
+            {
+                var status = transaction.RollBack();
+                if (status != TransactionStatus.RolledBack || transaction.GetStatus() != TransactionStatus.RolledBack)
+                    throw new InvalidOperationException("Batch rollback could not be confirmed.");
+            }
+            if (group != null) RollBackGroup(group);
+            bool committed = commit && !preview;
+            return new Result(committed, preview, atomic, commit,
+                committed ? accepted : new List<Dictionary<string, object?>>(),
+                committed ? new List<Dictionary<string, object?>>() : accepted, failed, failures.Warnings);
+        }
+        catch (Exception error)
+        {
+            string cleanup = FailureGuard.RollBackAndDescribe(transaction);
+            if (group != null)
+            {
+                try { RollBackGroup(group); cleanup += " Preview group rollback confirmed."; }
+                catch (Exception rollback) { cleanup += " Preview group rollback not confirmed: " + rollback.Message; }
+            }
+            throw new InvalidOperationException(error.Message + " " + cleanup, error);
+        }
+    }
+
+    private static void RollBackGroup(TransactionGroup group)
+    {
+        if (group.GetStatus() == TransactionStatus.Started) group.RollBack();
+        if (group.GetStatus() != TransactionStatus.RolledBack) throw new InvalidOperationException($"Preview group status is {group.GetStatus()}.");
+    }
+}

package/src/Revit/Tools/ModelEditInputs.cs

@@ -0,0 +1,49 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal static class ModelEditInputs
+{
+    public static object IdsSchema => new { type = "array", minItems = 1, maxItems = 200, uniqueItems = true, items = new { type = "integer", minimum = 1 } };
+    public static object PreviewSchema => new { type = "boolean", description = "Commit-validate then roll back all model edits. Default false." };
+    public static object LengthUnitSchema => new { type = "string", @enum = new[] { "millimeters", "centimeters", "meters", "feet", "inches" } };
+    public static object VectorSchema(string description) => new { type = "array", minItems = 3, maxItems = 3, items = new { type = "number" }, description };
+    public static List<ElementId> Ids(JsonElement args)
+    {
+        var ids = JsonArgs.GetLongArray(args, "element_ids");
+        if (ids.Count is < 1 or > 200 || ids.Any(id => id <= 0) || ids.Distinct().Count() != ids.Count)
+            throw new ArgumentException("element_ids must contain 1–200 distinct positive IDs.");
+        return ids.Select(id => new ElementId(id)).ToList();
+    }
+    public static double LengthScale(JsonElement args) => JsonArgs.GetString(args, "unit") switch
+    {
+        "millimeters" => 1 / 304.8, "centimeters" => 1 / 30.48, "meters" => 1 / 0.3048,
+        "feet" => 1, "inches" => 1 / 12.0,
+        _ => throw new ArgumentException("unit must be millimeters, centimeters, meters, feet or inches."),
+    };
+    public static double Number(JsonElement args, string name)
+    {
+        if (!args.TryGetProperty(name, out var value) || value.ValueKind != JsonValueKind.Number || !value.TryGetDouble(out double number) || !double.IsFinite(number))
+            throw new ArgumentException($"{name} must be a finite number.");
+        return number;
+    }
+    public static XYZ Vector(JsonElement args, string name)
+    {
+        if (!args.TryGetProperty(name, out var values) || values.ValueKind != JsonValueKind.Array || values.GetArrayLength() != 3)
+            throw new ArgumentException($"{name} must contain exactly three finite numbers.");
+        var numbers = values.EnumerateArray().Select(v => v.ValueKind == JsonValueKind.Number && v.TryGetDouble(out double n) && double.IsFinite(n) ? n : throw new ArgumentException($"{name} must contain finite numbers.")).ToArray();
+        return new XYZ(numbers[0], numbers[1], numbers[2]);
+    }
+    public static object Snapshot(Element element)
+    {
+        static double[] Point(XYZ p) => new[] { p.X, p.Y, p.Z };
+        object? location = element.Location switch
+        {
+            LocationPoint p => new { kind = "point", point = Point(p.Point) },
+            LocationCurve c when c.Curve.IsBound => new { kind = "curve_endpoints", start = Point(c.Curve.GetEndPoint(0)), end = Point(c.Curve.GetEndPoint(1)) } as object,
+            _ => null,
+        };
+        return new { id = element.Id.Value, unique_id = element.UniqueId, name = element.Name, type_id = element.GetTypeId().Value, location };
+    }
+}

package/src/Revit/Tools/OpenView.cs

@@ -15,7 +15,8 @@ namespace RevitBridge.Tools
         public string Name => "open_view";
         public string Label => "Open View";
         public string Description => "Activate a view or sheet in the Revit UI, like double-clicking it in the Project Browser. Identify the target by view_id (an id from get_elements category Views/Sheets or from view/sheet creation) or by name (exact view name, sheet number like 'A-101', or sheet number - name; case-insensitive). Activation is queued and completes the instant this call returns control to Revit — a capture_view immediately after may still show the previous active view. View templates and internal views cannot be opened.";
-        public bool Write => false;
+        public bool Write => false;
+        public IReadOnlyList<string> Effects => new[] { "ui" };
 
         public object ParametersSchema => new
         {

package/src/Revit/Tools/QuerySpatialElements.cs

@@ -0,0 +1,63 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class QuerySpatialElements : ITool
+{
+    public string Name => "query_spatial_elements";
+    public string Label => "Query Spatial Elements";
+    public string Tier => "advanced";
+    public string Description => "Find host elements whose model axis-aligned bounding boxes intersect or lie inside an explicit region. Coordinates use document internal axes and the required length unit. query uses get_elements filters, covering the whole scope (maximum 10,000 candidates). Includes touching boundaries; elements without bounds are counted separately. Bounds may include nonphysical geometry, so these are approximate candidates, not solid intersections or clashes. Linked contents are not traversed. Results are ordered by element ID with paging.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            query = ElementQueryScope.Schema(),
+            min = ModelEditInputs.VectorSchema("Region minimum in document internal axes, in unit."),
+            max = ModelEditInputs.VectorSchema("Region maximum in document internal axes, in unit."),
+            unit = ModelEditInputs.LengthUnitSchema,
+            relation = new { type = "string", @enum = new[] { "intersects", "inside" } },
+            offset = new { type = "integer", minimum = 0 }, limit = new { type = "integer", minimum = 1, maximum = 200 },
+        }, required = new[] { "min", "max", "unit" },
+    };
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        double scale = ModelEditInputs.LengthScale(args);
+        var region = new SpatialBounds(ModelEditInputs.Vector(args, "min").Multiply(scale), ModelEditInputs.Vector(args, "max").Multiply(scale));
+        if (region.Min.X > region.Max.X || region.Min.Y > region.Max.Y || region.Min.Z > region.Max.Z)
+            throw new ArgumentException("Each min coordinate must be less than or equal to max.");
+        string relation = JsonArgs.GetString(args, "relation") ?? "intersects";
+        if (relation is not ("intersects" or "inside")) throw new ArgumentException("relation must be intersects or inside.");
+        var query = ElementQueryScope.Parse(args);
+        JsonElement RunQuery() => JsonSerializer.SerializeToElement(((ToolOutput)new GetElements().Execute(JsonSerializer.SerializeToElement(query), context)!).Payload);
+        query["count_only"] = true;
+        var counted = RunQuery();
+        int count = counted.GetProperty("total_count").GetInt32();
+        if (count > 10000) throw new ArgumentException($"Query has {count} candidates; narrow query to at most 10,000.");
+        object? warnings = counted.TryGetProperty("warnings", out var warning) ? warning.Clone() : null;
+        query["count_only"] = false; query["limit"] = 1000;
+        var matches = new List<(Element Element, SpatialBounds Bounds)>();
+        int withoutBounds = 0;
+        for (int start = 0; start < count; start += 1000)
+        {
+            query["offset"] = start;
+            foreach (var row in RunQuery().GetProperty("elements").EnumerateArray())
+            {
+                var element = doc.GetElement(new ElementId(row.GetProperty("id").GetInt64()));
+                var bounds = SpatialBounds.Of(element);
+                if (bounds == null) { withoutBounds++; continue; }
+                if (relation == "inside" ? region.Contains(bounds) : region.Intersects(bounds)) matches.Add((element, bounds));
+            }
+        }
+        int offset = Math.Max(0, JsonArgs.GetInt(args, "offset", 0)), limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 200);
+        var elements = matches.OrderBy(x => x.Element.Id.Value).Skip(offset).Take(limit).Select(x => new
+        {
+            id = x.Element.Id.Value, unique_id = x.Element.UniqueId, name = x.Element.Name, category = x.Element.Category?.Name, bounds = x.Bounds.Describe(scale),
+        }).ToArray();
+        return new { method = "axis_aligned_bounding_boxes", approximate = true, coordinate_system = "document_internal", unit = JsonArgs.GetString(args, "unit"),
+            relation, region = region.Describe(scale), candidate_count = count, without_bounds_count = withoutBounds, warnings,
+            total_count = matches.Count, offset, returned_count = elements.Length, next_offset = offset + elements.Length < matches.Count ? (int?)(offset + elements.Length) : null, elements };
+    }
+}

package/src/Revit/Tools/SetParameters.cs

@@ -19,14 +19,16 @@ namespace RevitBridge.Tools
 
         public string Name => "set_parameters";
         public string Label => "Set Parameters";
-        public string Description => "Write parameter values on elements — also the home for rename: parameter 'Name' covers levels, views, sheets, types, etc. (falls back to the element's Name property when the Name parameter is read-only). updates apply in ONE transaction: partial success commits and lists the failures; if every update fails the transaction is rolled back and nothing changes. parameter accepts a display name (Comments, Mark, Name), a BuiltInParameter enum name (e.g. ALL_MODEL_MARK), or guid:<GUID> for a shared parameter; type parameters live on the element type, so pass the type's id. Values are validated against the parameter's storage type; numeric values are interpreted in the document's display units for that parameter unless 'unit' (e.g. millimeters, feet, squareMeters) is given. Revit warnings raised at commit (e.g. duplicate Mark values) are auto-dismissed and listed in commitWarnings — mention them to the user; error-severity failures roll the whole transaction back.";
+        public string Description => "Write parameter values on elements — also the home for rename: parameter 'Name' covers levels, views, sheets, types, etc. (falls back to the element's Name property when the Name parameter is read-only). Each update has its own subtransaction inside one model transaction. Default partial success commits valid updates; atomic=true rolls everything back if any update fails. preview=true validates commit inside a transaction group, then rolls the group back. Results include observed per-step before/after values and distinguish succeeded from proposed updates. parameter accepts a display name (Comments, Mark, Name), a BuiltInParameter enum name (e.g. ALL_MODEL_MARK), or guid:<GUID> for a shared parameter; type parameters live on the element type, so pass the type's id. Values are validated against the parameter's storage type; numeric values are interpreted in the document's display units for that parameter unless 'unit' (e.g. millimeters, feet, squareMeters) is given. Revit warnings raised at commit (e.g. duplicate Mark values) are auto-dismissed and listed in commitWarnings — mention them to the user; error-severity failures roll the whole transaction back.";
         public bool Write => true;
 
         public object ParametersSchema => new
         {
             type = "object",
-            properties = new
-            {
+            properties = new
+            {
+                preview = new { type = "boolean", description = "Validate edits through Revit commit, then roll back the enclosing transaction group. Returns proposed before/after values; no model changes remain. Default false." },
+                atomic = new { type = "boolean", description = "Roll back all updates if any fails. Default false preserves successful updates. Each update is isolated in a subtransaction." },
                 updates = new
                 {
                     type = "array",
@@ -57,95 +59,40 @@ namespace RevitBridge.Tools
         public IReadOnlyList<string>? PromptGuidelines => new[]
         {
             "Use set_parameters for parameter writes and renames (parameter 'Name'); pass 'unit' with numeric values unless the document's display units are intended.",
-            "set_parameters commits partial successes — always check the failed list in its result instead of assuming every update applied.",
+            "set_parameters defaults to partial success; use atomic=true for all-or-nothing batches and preview=true for commit-validated model rollback. Always inspect committed, proposed and failed.",
         };
 
-        public object? Execute(JsonElement args, ToolContext context)
-        {
-            var doc = context.Document ?? throw new NoActiveDocumentException();
-            DocumentGuard.CheckExpectedDocument(args, doc);
-            var updates = ParseUpdates(args);
-
-            var succeeded = new List<Dictionary<string, object?>>();
-            var failed = new List<Dictionary<string, object?>>();
-
-            using var transaction = new Transaction(doc, "set_parameters");
-            if (transaction.Start() != TransactionStatus.Started)
-                throw new InvalidOperationException("Unable to start the set_parameters transaction.");
-            var failureGuard = FailureGuard.Attach(transaction);
-
-            try
-            {
-                foreach (var update in updates)
-                {
-                    try
-                    {
-                        string? newDisplayValue = Apply(doc, update);
-                        succeeded.Add(new Dictionary<string, object?>
-                        {
-                            ["id"] = update.ElementId,
-                            ["parameter"] = update.ParameterInput,
-                            ["newDisplayValue"] = newDisplayValue,
-                        });
-                    }
-                    catch (Exception ex)
-                    {
-                        failed.Add(new Dictionary<string, object?>
-                        {
-                            ["id"] = update.ElementId,
-                            ["parameter"] = update.ParameterInput,
-                            ["reason"] = ex.Message,
-                        });
-                    }
-                }
-
-                if (succeeded.Count > 0)
-                {
-                    var status = transaction.Commit();
-                    var finalStatus = transaction.GetStatus();
-                    if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
-                        throw new InvalidOperationException(
-                            $"The set_parameters commit returned {status}; current transaction status is {finalStatus}."
-                            + failureGuard.DescribeErrors());
-                }
-                else
-                {
-                    var status = transaction.RollBack();
-                    if (status != TransactionStatus.RolledBack || transaction.GetStatus() != TransactionStatus.RolledBack)
-                        throw new InvalidOperationException($"The set_parameters rollback returned {status}.");
-                }
-            }
-            catch (Exception ex)
-            {
-                throw new InvalidOperationException($"{ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
-            }
-
-            int elementCount = succeeded.Select(row => row["id"]).Distinct().Count();
-            string failureSample = failed.Count > 0
-                ? $" First failure: element {failed[0]["id"]} '{failed[0]["parameter"]}': {failed[0]["reason"]}"
-                : string.Empty;
-            string compact = failed.Count == 0
-                ? $"Updated {succeeded.Count} parameter value(s) on {elementCount} element(s)."
-                : succeeded.Count == 0
-                    ? $"No updates applied; all {failed.Count} failed — transaction rolled back.{failureSample}"
-                    : $"Updated {succeeded.Count} parameter value(s) on {elementCount} element(s); {failed.Count} failed.{failureSample}";
-            if (failureGuard.Warnings.Count > 0)
-                compact += $" {failureGuard.Warnings.Count} Revit warning(s) auto-dismissed at commit (see commitWarnings), e.g.: {failureGuard.Warnings[0]}";
-
-            return new ToolOutput(new
-            {
-                updated = succeeded.Count,
-                committed = succeeded.Count > 0,
-                succeeded,
-                failed,
-                commitWarnings = failureGuard.Warnings,
-            }, compact);
-        }
-
+        public object? Execute(JsonElement args, ToolContext context)
+        {
+            var doc = context.Document ?? throw new NoActiveDocumentException();
+            DocumentGuard.CheckExpectedDocument(args, doc);
+            var updates = ParseUpdates(args);
+            var steps = updates.Select(update => new ModelEditBatch.Step(
+                new Dictionary<string, object?> { ["id"] = update.ElementId, ["parameter"] = update.ParameterInput },
+                () =>
+                {
+                    var change = Apply(doc, update);
+                    return new Dictionary<string, object?>
+                    {
+                        ["before"] = change.Before, ["after"] = change.After,
+                        ["newDisplayValue"] = change.Display,
+                    };
+                })).ToArray();
+            var result = ModelEditBatch.Run(doc, Name, args, steps);
+            string summary = result.Preview
+                ? $"Preview rolled back: {result.Proposed.Count} proposed update(s), {result.Failed.Count} failure(s)."
+                : result.Committed
+                    ? $"Applied {result.Succeeded.Count} parameter update(s); {result.Failed.Count} failed."
+                    : $"No updates applied; {result.Failed.Count} failed. Batch rolled back.";
+            return new ToolOutput(result.Payload, summary);
+        }
+
         // ------------------------------------------------------------- application
 
-        /// <summary>Applies one update; returns the new display value or throws with the per-update reason.</summary>
-        private static string? Apply(Document doc, Update update)
+        private sealed record ValueChange(string? Display, object? Before, object? After);
+
+        /// <summary>Snapshots the concrete parameter or rename target actually written by this step.</summary>
+        private static ValueChange Apply(Document doc, Update update)
         {
             var element = doc.GetElement(new ElementId(update.ElementId))
                 ?? throw new InvalidOperationException($"Element {update.ElementId} not found.");
@@ -168,7 +115,8 @@ namespace RevitBridge.Tools
                 throw new InvalidOperationException($"Parameter '{parameter.Definition?.Name}' is read-only on element {update.ElementId}.");
             }
 
-            bool accepted = parameter.StorageType switch
+            var before = GetElementDetails.DescribeParameter(doc, parameter, parameter.Definition?.Name ?? "", false);
+            bool accepted = parameter.StorageType switch
             {
                 StorageType.String => parameter.Set(ValueAsString(update.Value)),
                 StorageType.Double => parameter.Set(ToInternalUnits(doc, parameter, RequireDouble(parameter, update.Value), update.Unit)),
@@ -183,17 +131,19 @@ namespace RevitBridge.Tools
                     return SetElementName(element, update);
                 throw new InvalidOperationException($"Revit rejected the value for '{parameter.Definition?.Name}' on element {update.ElementId} (Parameter.Set returned false).");
             }
-            return DescribeNewValue(parameter) ?? ValueAsString(update.Value);
+            return new ValueChange(DescribeNewValue(parameter) ?? ValueAsString(update.Value), before,
+                GetElementDetails.DescribeParameter(doc, parameter, parameter.Definition?.Name ?? "", false));
         }
 
         /// <summary>Rename fallback: the Element.Name property setter.</summary>
-        private static string SetElementName(Element element, Update update)
+        private static ValueChange SetElementName(Element element, Update update)
         {
             string name = ValueAsString(update.Value);
             if (string.IsNullOrWhiteSpace(name))
                 throw new InvalidOperationException("Renaming needs a non-empty string value.");
-            element.Name = name;
-            return name;
+            var before = new { value = element.Name, displayValue = element.Name, storageType = "String" };
+            element.Name = name;
+            return new ValueChange(name, before, new { value = element.Name, displayValue = element.Name, storageType = "String" });
         }
 
         private static Parameter? FindParameter(Element element, Update update)

package/src/Revit/Tools/SpatialBounds.cs

@@ -0,0 +1,30 @@
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed record SpatialBounds(XYZ Min, XYZ Max)
+{
+    public static SpatialBounds? Of(Element element)
+    {
+        var box = element.get_BoundingBox(null);
+        if (box == null) return null;
+        var corners = new List<XYZ>(8);
+        foreach (double x in new[] { box.Min.X, box.Max.X })
+        foreach (double y in new[] { box.Min.Y, box.Max.Y })
+        foreach (double z in new[] { box.Min.Z, box.Max.Z })
+            corners.Add(box.Transform.OfPoint(new XYZ(x, y, z)));
+        return new(new(corners.Min(p => p.X), corners.Min(p => p.Y), corners.Min(p => p.Z)),
+            new(corners.Max(p => p.X), corners.Max(p => p.Y), corners.Max(p => p.Z)));
+    }
+
+    public bool Intersects(SpatialBounds other) => Min.X <= other.Max.X && Max.X >= other.Min.X
+        && Min.Y <= other.Max.Y && Max.Y >= other.Min.Y && Min.Z <= other.Max.Z && Max.Z >= other.Min.Z;
+    public bool Contains(SpatialBounds other) => Min.X <= other.Min.X && Max.X >= other.Max.X
+        && Min.Y <= other.Min.Y && Max.Y >= other.Max.Y && Min.Z <= other.Min.Z && Max.Z >= other.Max.Z;
+    public XYZ Gap(SpatialBounds other) => new(
+        Math.Max(0, Math.Max(Min.X - other.Max.X, other.Min.X - Max.X)),
+        Math.Max(0, Math.Max(Min.Y - other.Max.Y, other.Min.Y - Max.Y)),
+        Math.Max(0, Math.Max(Min.Z - other.Max.Z, other.Min.Z - Max.Z)));
+    public static double[] Coordinates(XYZ p, double scale) => new[] { p.X / scale, p.Y / scale, p.Z / scale };
+    public object Describe(double scale) => new { min = Coordinates(Min, scale), max = Coordinates(Max, scale) };
+}