pi-revit 0.3.1 → 0.4.0

package/src/Revit/Tools/ManageElementSets.cs

@@ -0,0 +1,106 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ManageElementSets : ITool
+{
+    private sealed record Member(long Id, string UniqueId);
+    private sealed record Snapshot(string Id, string DocumentId, string Label, DateTimeOffset Expires, IReadOnlyList<Member> Members);
+    private static readonly Dictionary<string, Snapshot> Sets = new(StringComparer.Ordinal);
+    private const int MaxElements = 10000;
+    private const int MaxSets = 32;
+
+    public string Name => "manage_element_sets";
+    public string Label => "Manage Element Sets";
+    public string Tier => "advanced";
+    public IReadOnlyList<string> Effects => new[] { "session" };
+    public string Description => "Create, list, read or forget reusable element sets without changing the model or selection. A set captures matching host-element identities (up to 10,000), expires after 30 minutes, and is valid only for the exact open document and bridge session. Read pages report live values, deleted members and identity mismatches; membership is a snapshot and filters are not re-evaluated. At most 32 sets are retained. Use read IDs with ordinary tools after checking missing members.";
+    public object ParametersSchema => new
+    {
+        type = "object",
+        properties = new
+        {
+            action = new { type = "string", @enum = new[] { "create", "list", "read", "forget" } },
+            query = ElementQueryScope.Schema(),
+            label = new { type = "string", maxLength = 160 },
+            set_id = new { type = "string" },
+            offset = new { type = "integer", minimum = 0 },
+            limit = new { type = "integer", minimum = 1, maximum = 1000 },
+            parameter_names = new { type = "array", maxItems = 20, items = new { type = "string" } },
+            include_type_parameters = new { type = "boolean" },
+        },
+        required = new[] { "action" },
+    };
+
+    public object Execute(JsonElement args, ToolContext context)
+    {
+        var doc = context.Document ?? throw new NoActiveDocumentException();
+        string documentId = DocumentGuard.GetIdentity(doc);
+        var now = DateTimeOffset.UtcNow;
+        foreach (var expired in Sets.Where(pair => pair.Value.Expires <= now).Select(pair => pair.Key).ToArray()) Sets.Remove(expired);
+        string action = JsonArgs.GetString(args, "action") ?? "";
+        if (action == "list") return new
+        {
+            sets = Sets.Values.Where(set => set.DocumentId == documentId).OrderBy(set => set.Expires)
+                .Select(set => new { set_id = set.Id, label = set.Label, total_count = set.Members.Count, expires_at = set.Expires }).ToArray(),
+        };
+        if (action == "create")
+        {
+            if (Sets.Count >= MaxSets) throw new ArgumentException("Element-set capacity reached. Forget an existing set or wait for expiry.");
+            string label = JsonArgs.GetString(args, "label") ?? "Element set";
+            if (label.Length > 160) throw new ArgumentException("label must be at most 160 characters.");
+            var query = ElementQueryScope.Parse(args);
+            query["fields"] = new JsonArray("id"); query["count_only"] = true;
+            JsonElement Query() => JsonSerializer.SerializeToElement(((ToolOutput)new GetElements().Execute(JsonSerializer.SerializeToElement(query), context)!).Payload);
+            var count = Query();
+            int total = count.GetProperty("total_count").GetInt32();
+            if (total > MaxElements) throw new ArgumentException($"Query matches {total} elements; narrow the scope to at most {MaxElements}.");
+            query["count_only"] = false; query["limit"] = 1000;
+            var members = new List<Member>(total);
+            for (int offset = 0; offset < total; offset += 1000)
+            {
+                query["offset"] = offset;
+                foreach (var row in Query().GetProperty("elements").EnumerateArray())
+                {
+                    var element = doc.GetElement(new ElementId(row.GetProperty("id").GetInt64()));
+                    members.Add(new Member(element.Id.Value, element.UniqueId));
+                }
+            }
+            var snapshot = new Snapshot(Guid.NewGuid().ToString("N"), documentId, label, now.AddMinutes(30), members);
+            Sets.Add(snapshot.Id, snapshot);
+            return new { set_id = snapshot.Id, document_id = documentId, label, total_count = total, expires_at = snapshot.Expires,
+                warnings = count.TryGetProperty("warnings", out var warnings) ? (object)warnings.Clone() : null };
+        }
+        if (action is not ("read" or "forget")) throw new ArgumentException("Unknown action; use create, list, read or forget.");
+        string setId = JsonArgs.GetString(args, "set_id") ?? "";
+        if (!Sets.TryGetValue(setId, out var saved)) throw new ArgumentException("Unknown or expired set_id. Create a fresh set; IDs do not survive a bridge restart.");
+        if (saved.DocumentId != documentId) throw new ArgumentException("This element set belongs to a different open document. Activate its original document or create a fresh set.");
+        if (action == "forget") { Sets.Remove(setId); return new { set_id = setId, forgotten = true }; }
+        int start = Math.Max(0, JsonArgs.GetInt(args, "offset", 0));
+        int limit = Math.Clamp(JsonArgs.GetInt(args, "limit", 100), 1, 1000);
+        var names = JsonArgs.GetStringArray(args, "parameter_names");
+        if (names?.Count > 20) throw new ArgumentException("parameter_names allows at most 20 identities.");
+        bool includeType = JsonArgs.GetBool(args, "include_type_parameters", false);
+        var page = saved.Members.Skip(start).Take(limit).ToArray();
+        var rows = new List<object>();
+        var missing = new List<object>();
+        foreach (var member in page)
+        {
+            var element = doc.GetElement(new ElementId(member.Id));
+            if (element == null || element.UniqueId != member.UniqueId)
+            {
+                missing.Add(new { id = member.Id, unique_id = member.UniqueId, reason = element == null ? "deleted" : "identity_changed" });
+                continue;
+            }
+            var row = ElementIdentity.Build(doc, element, ElementIdentity.Fields);
+            row["unique_id"] = member.UniqueId;
+            if (names is { Count: > 0 }) row["parameters"] = GetElementDetails.ProjectParameters(doc, element, names, includeType);
+            rows.Add(row);
+        }
+        return new { set_id = setId, document_id = documentId, snapshot_count = saved.Members.Count, expires_at = saved.Expires,
+            offset = start, visited_count = page.Length, returned_count = rows.Count,
+            next_offset = start + page.Length < saved.Members.Count ? (int?)(start + page.Length) : null, elements = rows, missing };
+    }
+}

package/src/Revit/Tools/ManageSchedules.cs

@@ -0,0 +1,164 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ManageSchedules : ITool
+{
+    public string Name => "manage_schedules";
+    public string Label => "Manage Schedules";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Create or configure a regular schedule in one atomic step. Create requires category and name; optional area_scheme_id supports area schedules. Configure requires schedule_id. Discover add_fields using get_schedule_fields and pass the returned parameter_id + field_type pair, including Count when listed. Count also supports field_type Count without a parameter_id. update_fields, sort_fields and filters use schedule-local field_id from get_schedules. Supplied sort_fields/filters replace their entire lists; empty arrays clear them. Numeric measured filter values require a compatible unit; returned numeric filter values use internal units. Column widths require explicit length units and apply to both grid and sheet. preview=true commit-validates then rolls back; created schedule/field IDs in previews are temporary. Revision schedules, templates, embedded schedules and calculated/combined-field authoring are outside this tool.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            action = new { type = "string", @enum = new[] { "create", "configure" } },
+            schedule_id = new { type = "integer", minimum = 1 }, category = new { type = "string" }, name = new { type = "string", minLength = 1 }, area_scheme_id = new { type = "integer", minimum = 1 },
+            is_itemized = new { type = "boolean" }, preview = ModelEditInputs.PreviewSchema,
+            add_fields = new { type = "array", maxItems = 50, items = new { type = "object", properties = new
+            {
+                parameter_id = new { type = "integer", description = "Use the ID returned by get_schedule_fields, including negative built-in IDs. Optional for Count; when supplied, the pair must be eligible for the schedule." }, field_type = new { type = "string" },
+                heading = new { type = "string" }, hidden = new { type = "boolean" }, width = new { type = "number", exclusiveMinimum = 0 }, unit = ModelEditInputs.LengthUnitSchema,
+            }, required = new[] { "field_type" } } },
+            update_fields = new { type = "array", maxItems = 50, items = new { type = "object", properties = new
+            {
+                field_id = new { type = "integer", minimum = 0 }, heading = new { type = "string" }, hidden = new { type = "boolean" }, width = new { type = "number", exclusiveMinimum = 0 }, unit = ModelEditInputs.LengthUnitSchema,
+            }, required = new[] { "field_id" } } },
+            sort_fields = new { type = "array", maxItems = 4, items = new { type = "object", properties = new { field_id = new { type = "integer", minimum = 0 }, descending = new { type = "boolean" }, show_header = new { type = "boolean" } }, required = new[] { "field_id" } } },
+            filters = new { type = "array", maxItems = 8, items = new { type = "object", properties = new
+            {
+                field_id = new { type = "integer", minimum = 0 }, comparison = new { type = "string", @enum = new[] { "equals", "not_equals", "contains", "greater_than", "less_than" } },
+                value_type = new { type = "string", @enum = new[] { "string", "number", "integer", "element_id" } }, value = new { description = "Filter value matching value_type." }, unit = new { type = "string", description = "Required for measured numbers; compatible forge unit name, e.g. meters, squareMeters, degrees." },
+            }, required = new[] { "field_id", "comparison", "value_type", "value" } } },
+        }, 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" or "configure")) throw new ArgumentException("action must be create or configure.");
+        var additions = Array(args, "add_fields", 50); var updates = Array(args, "update_fields", 50);
+        var sorts = Array(args, "sort_fields", 4); var filters = Array(args, "filters", 8);
+        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(new() { ["action"] = action }, () =>
+        {
+            ViewSchedule schedule;
+            if (action == "create")
+            {
+                string category = JsonArgs.GetString(args, "category") ?? throw new ArgumentException("category is required for creation.");
+                var categoryId = CategoryResolver.Resolve(doc, category);
+                schedule = JsonArgs.GetLong(args, "area_scheme_id") is long area ? ViewSchedule.CreateSchedule(doc, categoryId, new ElementId(area)) : ViewSchedule.CreateSchedule(doc, categoryId);
+                if (!args.TryGetProperty("name", out _)) throw new ArgumentException("name is required for creation.");
+            }
+            else
+            {
+                if (args.TryGetProperty("category", out _) || args.TryGetProperty("area_scheme_id", out _)) throw new ArgumentException("category and area_scheme_id are creation-only.");
+                schedule = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "schedule_id") ?? 0)) as ViewSchedule ?? throw new ArgumentException("schedule_id is not a schedule.");
+            }
+            if (schedule.IsTemplate || schedule.IsTitleblockRevisionSchedule || schedule.Definition.IsEmbedded) throw new ArgumentException("Use a regular, non-template schedule.");
+            if (args.TryGetProperty("name", out var name))
+            {
+                if (name.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(name.GetString())) throw new ArgumentException("name must be nonempty.");
+                schedule.Name = name.GetString()!;
+            }
+            var definition = schedule.Definition;
+            var added = new List<int>();
+            foreach (var input in additions)
+            {
+                string typeName = JsonArgs.GetString(input, "field_type") ?? "";
+                if (typeName.Length == 0 || !char.IsLetter(typeName[0]) || !Enum.TryParse<ScheduleFieldType>(typeName, false, out var type) || !Enum.IsDefined(type)) throw new ArgumentException("Use a field_type from get_schedule_fields, or Count.");
+                ScheduleField field;
+                if (type == ScheduleFieldType.Count && !input.TryGetProperty("parameter_id", out _))
+                {
+                    field = definition.AddField(type);
+                }
+                else
+                {
+                    long parameterId = JsonArgs.GetLong(input, "parameter_id") ?? throw new ArgumentException("parameter_id is required for this field.");
+                    var eligible = definition.GetSchedulableFields().FirstOrDefault(f => f.ParameterId.Value == parameterId && f.FieldType == type) ?? throw new ArgumentException("That parameter_id/field_type pair is not eligible for this schedule.");
+                    field = definition.AddField(eligible);
+                }
+                ConfigureField(field, input); added.Add(field.FieldId.IntegerValue);
+            }
+            var seen = new HashSet<int>();
+            foreach (var input in updates)
+            {
+                var id = FieldId(input);
+                if (!seen.Add(id.IntegerValue)) throw new ArgumentException("update_fields contains a duplicate field_id.");
+                ConfigureField(definition.GetField(id), input);
+            }
+            if (args.TryGetProperty("is_itemized", out _)) definition.IsItemized = Bool(args, "is_itemized");
+            if (args.TryGetProperty("sort_fields", out _))
+                definition.SetSortGroupFields(sorts.Select(input => new ScheduleSortGroupField(FieldId(input), Bool(input, "descending") ? ScheduleSortOrder.Descending : ScheduleSortOrder.Ascending) { ShowHeader = Bool(input, "show_header") }).ToList());
+            if (args.TryGetProperty("filters", out _)) definition.SetFilters(filters.Select(input => Filter(definition, input)).ToList());
+            doc.Regenerate();
+            return new() { ["schedule_id"] = schedule.Id.Value, ["unique_id"] = schedule.UniqueId, ["name"] = schedule.Name,
+                ["created"] = action == "create", ["id_is_temporary"] = action == "create" && JsonArgs.GetBool(args, "preview", false),
+                ["added_field_ids"] = added, ["added_field_ids_are_temporary"] = JsonArgs.GetBool(args, "preview", false),
+                ["is_itemized"] = definition.IsItemized, ["field_count"] = definition.GetFieldCount(), ["filter_count"] = definition.GetFilterCount(), ["sort_count"] = definition.GetSortGroupFieldCount() };
+        }) }).Payload;
+    }
+
+    private static List<JsonElement> Array(JsonElement args, string name, int max)
+    {
+        if (!args.TryGetProperty(name, out var value)) return new();
+        if (value.ValueKind != JsonValueKind.Array || value.GetArrayLength() > max) throw new ArgumentException($"{name} must be an array of at most {max} entries.");
+        var items = value.EnumerateArray().ToList();
+        if (items.Any(item => item.ValueKind != JsonValueKind.Object)) throw new ArgumentException($"{name} entries must be objects.");
+        return items;
+    }
+    private static bool Bool(JsonElement args, string name)
+    {
+        if (!args.TryGetProperty(name, out var value)) return false;
+        if (value.ValueKind is not (JsonValueKind.True or JsonValueKind.False)) throw new ArgumentException($"{name} must be boolean.");
+        return value.GetBoolean();
+    }
+    private static ScheduleFieldId FieldId(JsonElement input)
+    {
+        long id = JsonArgs.GetLong(input, "field_id") ?? -1;
+        return id is >= 0 and <= int.MaxValue ? new ScheduleFieldId((int)id) : throw new ArgumentException("field_id must be a nonnegative schedule-local ID.");
+    }
+    private static void ConfigureField(ScheduleField field, JsonElement input)
+    {
+        if (input.TryGetProperty("heading", out var heading)) field.ColumnHeading = heading.ValueKind == JsonValueKind.String ? heading.GetString()! : throw new ArgumentException("heading must be a string.");
+        if (input.TryGetProperty("hidden", out _)) field.IsHidden = Bool(input, "hidden");
+        if (input.TryGetProperty("width", out _))
+        {
+            double width = ModelEditInputs.Number(input, "width") * ModelEditInputs.LengthScale(input);
+            if (width <= 0) throw new ArgumentException("Column width must be positive.");
+            field.GridColumnWidth = width; field.SheetColumnWidth = width;
+        }
+    }
+    private static ScheduleFilter Filter(ScheduleDefinition definition, JsonElement input)
+    {
+        var id = FieldId(input); var field = definition.GetField(id);
+        var comparison = JsonArgs.GetString(input, "comparison") switch
+        {
+            "equals" => ScheduleFilterType.Equal, "not_equals" => ScheduleFilterType.NotEqual, "contains" => ScheduleFilterType.Contains,
+            "greater_than" => ScheduleFilterType.GreaterThan, "less_than" => ScheduleFilterType.LessThan, _ => throw new ArgumentException("Unknown comparison."),
+        };
+        if (comparison == ScheduleFilterType.Contains ? !definition.CanFilterBySubstring(id) : !definition.CanFilterByValue(id)) throw new ArgumentException("This field does not support that filter operation.");
+        if (!input.TryGetProperty("value", out var value)) throw new ArgumentException("Filter value is required.");
+        string? type = JsonArgs.GetString(input, "value_type");
+        if (type == "string" && value.ValueKind == JsonValueKind.String) return new ScheduleFilter(id, comparison, value.GetString()!);
+        if (type == "integer" && value.ValueKind == JsonValueKind.Number && value.TryGetInt32(out int integer)) return new ScheduleFilter(id, comparison, integer);
+        if (type == "element_id" && value.ValueKind == JsonValueKind.Number && value.TryGetInt64(out long elementId)) return new ScheduleFilter(id, comparison, new ElementId(elementId));
+        if (type == "number")
+        {
+            double number = ModelEditInputs.Number(input, "value");
+            var spec = field.GetSpecTypeId(); string? unit = JsonArgs.GetString(input, "unit");
+            if (UnitUtils.IsMeasurableSpec(spec))
+            {
+                if (string.IsNullOrWhiteSpace(unit)) throw new ArgumentException("Measured numeric filters require an explicit unit.");
+                var unitId = UnitResolver.Resolve(unit);
+                if (!UnitUtils.IsValidUnit(spec, unitId)) throw new ArgumentException("Filter unit does not match the field's specification.");
+                number = UnitUtils.ConvertToInternalUnits(number, unitId);
+            }
+            else if (unit != null) throw new ArgumentException("This numeric field has no measurable unit.");
+            return new ScheduleFilter(id, comparison, number);
+        }
+        throw new ArgumentException("Filter value does not match value_type.");
+    }
+}

package/src/Revit/Tools/ManageSelection.cs

@@ -11,7 +11,8 @@ namespace RevitBridge.Tools
     /// </summary>
     internal sealed class ManageSelection : ITool
     {
-        public string Name => "manage_selection";
+        public string Name => "manage_selection";
+        public IReadOnlyList<string> Effects => new[] { "ui", "model" };
         public string Label => "Manage Selection";
         public string Description => "Manage the Revit selection and view focus. action 'get' returns the currently selected elements (id, name, category, typeName, levelId); 'set'/'add'/'remove' change the selection with element_ids; 'clear' empties it; 'zoom' zooms open views to element_ids (default: the current selection). isolate_in_view=true additionally applies Revit's Temporary Hide/Isolate to the affected elements in the active view — temporary view state, not a model change (Revit needs a brief internal transaction to toggle it); with an empty target set (action 'clear', or 'get' with nothing selected) it resets the temporary isolate instead. Selection and zoom never modify model data.";
 
@@ -136,25 +137,25 @@ namespace RevitBridge.Tools
                 compactParts.Add($"ids not found: {string.Join(", ", notFound)}");
             }
 
-            if (isolateInView)
-            {
-                var view = uiDocument.ActiveGraphicalView;
-                IReadOnlyList<string> warnings;
-                try
-                {
-                    if (view is null)
-                        throw new ArgumentException("isolate_in_view requires an active graphical view in Revit.");
-                    warnings = ApplyTemporaryIsolate(doc, view, isolateTargets);
-                }
-                catch (Exception ex)
-                {
-                    throw new InvalidOperationException($"Selection action '{action}' completed before temporary isolate failed: {ex.Message}. Selection/zoom changes were not rolled back.", ex);
-                }
-                if (warnings.Count > 0)
-                {
-                    payload["commitWarnings"] = warnings;
-                    compactParts.Add($"{warnings.Count} Revit warning(s) auto-dismissed (see commitWarnings)");
-                }
+            if (isolateInView)
+            {
+                var view = uiDocument.ActiveGraphicalView;
+                IReadOnlyList<string> warnings;
+                try
+                {
+                    if (view is null)
+                        throw new ArgumentException("isolate_in_view requires an active graphical view in Revit.");
+                    warnings = ApplyTemporaryIsolate(doc, view, isolateTargets);
+                }
+                catch (Exception ex)
+                {
+                    throw new InvalidOperationException($"Selection action '{action}' completed before temporary isolate failed: {ex.Message}. Selection/zoom changes were not rolled back.", ex);
+                }
+                if (warnings.Count > 0)
+                {
+                    payload["commitWarnings"] = warnings;
+                    compactParts.Add($"{warnings.Count} Revit warning(s) auto-dismissed (see commitWarnings)");
+                }
                 payload["viewId"] = view.Id.Value;
                 payload["viewName"] = view.Name;
                 if (isolateTargets.Count == 0)
@@ -203,28 +204,28 @@ namespace RevitBridge.Tools
         /// only changes it inside an open transaction — so exactly this branch wraps
         /// a small one while the tool stays Write = false.
         /// </summary>
-        private static IReadOnlyList<string> ApplyTemporaryIsolate(Document doc, View view, ICollection<ElementId> elementIds)
-        {
-            using var transaction = new Transaction(doc, "manage_selection: temporary isolate");
-            if (transaction.Start() != TransactionStatus.Started)
-                throw new InvalidOperationException("Unable to start the temporary-isolate transaction.");
-            var failureGuard = FailureGuard.Attach(transaction);
+        private static IReadOnlyList<string> ApplyTemporaryIsolate(Document doc, View view, ICollection<ElementId> elementIds)
+        {
+            using var transaction = new Transaction(doc, "manage_selection: temporary isolate");
+            if (transaction.Start() != TransactionStatus.Started)
+                throw new InvalidOperationException("Unable to start the temporary-isolate transaction.");
+            var failureGuard = FailureGuard.Attach(transaction);
             try
             {
                 if (elementIds.Count == 0)
                     view.DisableTemporaryViewMode(TemporaryViewMode.TemporaryHideIsolate);
                 else
                     view.IsolateElementsTemporary(elementIds);
-                var status = transaction.Commit();
-                var finalStatus = transaction.GetStatus();
-                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
-                    throw new InvalidOperationException($"The temporary-isolate commit returned {status}; current transaction status is {finalStatus}." + failureGuard.DescribeErrors());
-                return failureGuard.Warnings;
-            }
-            catch (Exception ex)
-            {
-                throw new InvalidOperationException($"Temporary isolate in view '{view.Name}' failed: {ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
-            }
+                var status = transaction.Commit();
+                var finalStatus = transaction.GetStatus();
+                if (status != TransactionStatus.Committed || finalStatus != TransactionStatus.Committed)
+                    throw new InvalidOperationException($"The temporary-isolate commit returned {status}; current transaction status is {finalStatus}." + failureGuard.DescribeErrors());
+                return failureGuard.Warnings;
+            }
+            catch (Exception ex)
+            {
+                throw new InvalidOperationException($"Temporary isolate in view '{view.Name}' failed: {ex.Message} {FailureGuard.RollBackAndDescribe(transaction)}", ex);
+            }
         }
     }
 }

package/src/Revit/Tools/ManageSheetPlacements.cs

@@ -0,0 +1,97 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ManageSheetPlacements : ITool
+{
+    public string Name => "manage_sheet_placements";
+    public string Label => "Manage Sheet Placements";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "List, place or move viewports and schedule instances on a sheet. Positions are paper-space sheet coordinates with explicit length units, [x,y,0]; never multiply by view scale. For viewports position is the box center excluding its label; for schedules it is the insertion point. Place requires sheet_id/view_id, move requires placement_id. Viewports may rotate none/clockwise/counterclockwise; schedule rotation is not supported. preview=true commit-validates then rolls back; new placement IDs are temporary. List includes both viewports and schedules with paging. Exact document identity is required for every action.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            action = new { type = "string", @enum = new[] { "list", "place", "move" } },
+            sheet_id = new { type = "integer", minimum = 1 }, view_id = new { type = "integer", minimum = 1 }, placement_id = new { type = "integer", minimum = 1 },
+            position = ModelEditInputs.VectorSchema("Sheet paper-space [x,y,0] in unit."), unit = ModelEditInputs.LengthUnitSchema,
+            rotation = new { type = "string", @enum = new[] { "none", "clockwise", "counterclockwise" } },
+            offset = new { type = "integer", minimum = 0 }, limit = new { type = "integer", minimum = 1, maximum = 200 }, 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") ?? "";
+        ElementId Id(string name) => new(JsonArgs.GetLong(args, name) is long id && id > 0 ? id : throw new ArgumentException($"{name} must be a positive ID."));
+        if (action == "list")
+        {
+            var sheet = doc.GetElement(Id("sheet_id")) as ViewSheet ?? throw new ArgumentException("sheet_id is not a sheet.");
+            var items = new FilteredElementCollector(doc).OwnedByView(sheet.Id).WhereElementIsNotElementType()
+                .Where(e => e is Viewport or ScheduleSheetInstance).OrderBy(e => e.Id.Value).ToArray();
+            int offset = JsonArgs.GetInt(args, "offset", 0), limit = JsonArgs.GetInt(args, "limit", 100);
+            if (offset < 0 || limit is < 1 or > 200) throw new ArgumentException("Invalid paging range.");
+            var page = items.Skip(offset).Take(limit).Select(Describe).ToArray();
+            return new { sheet_id = sheet.Id.Value, total_count = items.Length, offset, returned_count = page.Length, next_offset = offset + page.Length < items.Length ? (int?)(offset + page.Length) : null, placements = page, coordinate_system = "sheet_paper", unit = "feet" };
+        }
+        if (action is not ("place" or "move")) throw new ArgumentException("action must be list, place or move.");
+        var point = ModelEditInputs.Vector(args, "position").Multiply(ModelEditInputs.LengthScale(args));
+        if (Math.Abs(point.Z) > 1e-9) throw new ArgumentException("Sheet position Z must be zero.");
+        var rotation = JsonArgs.GetString(args, "rotation") switch
+        {
+            null => (ViewportRotation?)null, "none" => ViewportRotation.None, "clockwise" => ViewportRotation.Clockwise,
+            "counterclockwise" => ViewportRotation.Counterclockwise, _ => throw new ArgumentException("Invalid rotation."),
+        };
+        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(new() { ["action"] = action }, () =>
+        {
+            Element placement;
+            object? before = null;
+            if (action == "place")
+            {
+                var sheet = doc.GetElement(Id("sheet_id")) as ViewSheet ?? throw new ArgumentException("sheet_id is not a sheet.");
+                if (sheet.IsPlaceholder) throw new ArgumentException("Cannot place content on a placeholder sheet.");
+                var view = doc.GetElement(Id("view_id")) as View ?? throw new ArgumentException("view_id is not a view or schedule.");
+                if (view is ViewSchedule schedule)
+                {
+                    if (rotation != null) throw new ArgumentException("Schedules do not support viewport rotation.");
+                    placement = ScheduleSheetInstance.Create(doc, sheet.Id, schedule.Id, point);
+                }
+                else
+                {
+                    if (!Viewport.CanAddViewToSheet(doc, sheet.Id, view.Id)) throw new ArgumentException("This view cannot be added to that sheet; it may already be placed.");
+                    placement = Viewport.Create(doc, sheet.Id, view.Id, point);
+                }
+            }
+            else
+            {
+                placement = doc.GetElement(Id("placement_id")) ?? throw new ArgumentException("placement_id was not found.");
+                if (args.TryGetProperty("sheet_id", out _) && placement.OwnerViewId != Id("sheet_id")) throw new ArgumentException("The placement does not belong to the expected sheet_id.");
+                if (placement.Pinned) throw new ArgumentException("Placement is pinned; it was not unpinned.");
+                before = Describe(placement);
+                if (placement is Viewport viewport) viewport.SetBoxCenter(point);
+                else if (placement is ScheduleSheetInstance schedule)
+                {
+                    if (rotation != null) throw new ArgumentException("Schedules do not support viewport rotation.");
+                    schedule.Point = point;
+                }
+                else throw new ArgumentException("placement_id must identify a viewport or schedule instance.");
+            }
+            if (rotation != null && placement is Viewport target) target.Rotation = rotation.Value;
+            doc.Regenerate();
+            if (placement is Viewport positioned) { positioned.SetBoxCenter(point); doc.Regenerate(); }
+            return new() { ["before"] = before, ["placement"] = Describe(placement), ["created"] = action == "place", ["id_is_temporary"] = action == "place" && JsonArgs.GetBool(args, "preview", false) };
+        }) }).Payload;
+    }
+    private static object Describe(Element element)
+    {
+        static double[] Point(XYZ p) => new[] { p.X, p.Y, p.Z };
+        return element switch
+        {
+            Viewport v => new { id = v.Id.Value, unique_id = v.UniqueId, kind = "viewport", sheet_id = v.SheetId.Value, view_id = v.ViewId.Value, position = Point(v.GetBoxCenter()), position_kind = "box_center_excluding_label", rotation = v.Rotation.ToString(), unit = "feet" } as object,
+            ScheduleSheetInstance s => new { id = s.Id.Value, unique_id = s.UniqueId, kind = "schedule", sheet_id = s.OwnerViewId.Value, view_id = s.ScheduleId.Value, position = Point(s.Point), position_kind = "insertion_point", unit = "feet" },
+            _ => throw new ArgumentException("Element is not a sheet placement."),
+        };
+    }
+}

package/src/Revit/Tools/ManageSheets.cs

@@ -0,0 +1,63 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools;
+
+internal sealed class ManageSheets : ITool
+{
+    public string Name => "manage_sheets";
+    public string Label => "Manage Sheets";
+    public string Tier => "advanced";
+    public bool Write => true;
+    public string Description => "Create or rename/renumber a drawing sheet. Creation requires name and number; optional titleblock_type_id chooses a loaded titleblock FamilySymbol, otherwise creates a sheet without a titleblock. Update requires sheet_id and accepts name/number. Revit validates unique sheet numbers and valid text; sheet names may repeat; the call rolls back on failure. preview=true commit-validates and rolls back, and new preview sheet IDs are temporary. Use manage_sheet_placements for views/schedules, get_elements for querying sheets, and delete_elements for removal.";
+    public object ParametersSchema => new
+    {
+        type = "object", properties = new
+        {
+            action = new { type = "string", @enum = new[] { "create", "update" } },
+            sheet_id = new { type = "integer", minimum = 1 }, name = new { type = "string", minLength = 1 }, number = new { type = "string", minLength = 1 },
+            titleblock_type_id = new { type = "integer", minimum = 1, description = "Creation only; omitted means no titleblock." }, 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" or "update")) throw new ArgumentException("action must be create or update.");
+        string? ReadText(string key)
+        {
+            if (!args.TryGetProperty(key, out var value)) return null;
+            if (value.ValueKind != JsonValueKind.String || string.IsNullOrWhiteSpace(value.GetString())) throw new ArgumentException($"{key} must be a nonempty string.");
+            return value.GetString();
+        }
+        string? name = ReadText("name"), number = ReadText("number");
+        if (action == "create" && (name == null || number == null)) throw new ArgumentException("Sheet creation requires name and number.");
+        if (action == "update" && args.TryGetProperty("titleblock_type_id", out _)) throw new ArgumentException("titleblock_type_id is only supported when creating a sheet; use change_element_types on an existing titleblock instance.");
+        return ModelEditBatch.Run(doc, Name, args, new[] { new ModelEditBatch.Step(new() { ["action"] = action }, () =>
+        {
+            ViewSheet sheet;
+            object? before = null;
+            if (action == "create")
+            {
+                var typeId = ElementId.InvalidElementId;
+                if (args.TryGetProperty("titleblock_type_id", out _))
+                {
+                    typeId = new ElementId(JsonArgs.GetLong(args, "titleblock_type_id") ?? 0);
+                    var type = doc.GetElement(typeId) as FamilySymbol;
+                    if (type?.Category?.Id.Value != (long)BuiltInCategory.OST_TitleBlocks) throw new ArgumentException("titleblock_type_id must identify a titleblock FamilySymbol.");
+                }
+                sheet = ViewSheet.Create(doc, typeId);
+            }
+            else
+            {
+                sheet = doc.GetElement(new ElementId(JsonArgs.GetLong(args, "sheet_id") ?? 0)) as ViewSheet ?? throw new ArgumentException("sheet_id is not a sheet.");
+                before = Describe(sheet);
+            }
+            if (number != null) sheet.SheetNumber = number;
+            if (name != null) sheet.Name = name;
+            doc.Regenerate();
+            return new() { ["before"] = before, ["sheet"] = Describe(sheet), ["created"] = action == "create", ["id_is_temporary"] = action == "create" && JsonArgs.GetBool(args, "preview", false) };
+        }) }).Payload;
+    }
+    private static object Describe(ViewSheet sheet) => new { id = sheet.Id.Value, unique_id = sheet.UniqueId, name = sheet.Name, number = sheet.SheetNumber, placeholder = sheet.IsPlaceholder };
+}