pi-revit 0.2.11 → 0.2.13

package/src/Revit/Tools/CaptureView.cs

@@ -15,6 +15,10 @@ namespace RevitBridge.Tools
     {
         private const int MaxLongEdgePx = 1568;
 
+        /// <summary>How long a captured PNG stays on disk before a later capture sweeps it.
+        /// Long enough that a capture is never pulled out from under a session still reading it.</summary>
+        private static readonly TimeSpan CaptureRetention = TimeSpan.FromHours(24);
+
         public string Name => "capture_view";
         public string Label => "Capture View";
         public string Description => "Export a PNG snapshot of a Revit view to a temporary file and return its path — the response contains NO image data; open the returned filePath with the read tool to actually see the image. Defaults to the active view; pass view_id for any other graphical view or sheet (find ids with get_elements, category 'Views' or 'Sheets'). The long image edge is capped at 1568 px. Schedules and view templates cannot be captured.";
@@ -45,7 +49,8 @@ namespace RevitBridge.Tools
             var doc = context.Document ?? throw new NoActiveDocumentException();
             var view = ResolveView(doc, args);
 
-            string prefix = Path.Combine(Path.GetTempPath(), "revit_view_" + Guid.NewGuid().ToString("N"));
+            PruneOldCaptures();
+            string prefix = Path.Combine(CaptureDirectory(), "revit_view_" + Guid.NewGuid().ToString("N"));
             ExportPng(doc, view, prefix, GuessLandscape(view));
             string filePath = FindExportedFile(prefix);
             var (width, height) = ReadPngSize(filePath);
@@ -74,6 +79,60 @@ namespace RevitBridge.Tools
             }, compact);
         }
 
+        /// <summary>Captures live in one folder this add-in owns, NOT in Path.GetTempPath().
+        /// Revit can hand out a fresh per-session temp folder (observed: %LOCALAPPDATA%\Temp\
+        /// &lt;guid&gt;\), so a sweep of GetTempPath() only ever sees the current session's own
+        /// files while every earlier session's captures accumulate unreachably in sibling
+        /// folders. A fixed directory makes the sweep below correct and cheap. Falls back to
+        /// the temp path if the folder cannot be created — a capture must never fail over
+        /// where it is filed.</summary>
+        private static string CaptureDirectory()
+        {
+            try
+            {
+                string directory = Path.Combine(
+                    Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
+                    "pi-revit",
+                    "captures");
+                Directory.CreateDirectory(directory);
+                return directory;
+            }
+            catch
+            {
+                return Path.GetTempPath();
+            }
+        }
+
+        /// <summary>The PNG must outlive the call — the agent opens it with the read tool
+        /// after the result returns — so this run's file is never deleted here. Instead each
+        /// capture sweeps the ones left by earlier sessions, which otherwise accumulate
+        /// forever. Best-effort: a locked or vanished file is skipped, and a failing sweep
+        /// never costs the caller their capture. The wildcard also covers the older
+        /// 'revit_view_snapshot_*' naming so pre-existing captures are collected too.</summary>
+        private static void PruneOldCaptures()
+        {
+            try
+            {
+                DateTime cutoff = DateTime.UtcNow - CaptureRetention;
+                foreach (string path in Directory.EnumerateFiles(CaptureDirectory(), "revit_view_*.png"))
+                {
+                    try
+                    {
+                        if (File.GetLastWriteTimeUtc(path) < cutoff)
+                            File.Delete(path);
+                    }
+                    catch
+                    {
+                        // In use by a reader, or already gone: leave it for the next sweep.
+                    }
+                }
+            }
+            catch
+            {
+                // Capture folder unreadable: cleanup is never worth failing a capture over.
+            }
+        }
+
         private static View ResolveView(Document doc, JsonElement args)
         {
             View view;

package/src/Revit/Tools/ExecuteCsharp.cs

@@ -124,13 +124,26 @@ namespace RevitBridge.Tools
                 throw new InvalidOperationException("Unable to start the execute_csharp transaction.");
 
             object? returnValue;
+            string? projectionError = null;
             try
             {
                 // Runs synchronously on this (the Revit API) thread; await/async was
                 // rejected at compile time, so the task completes without suspending.
                 var state = script.RunAsync(globals).GetAwaiter().GetResult();
-                // Project inside the transaction so values reflect the script-end model state.
-                returnValue = Project(state.ReturnValue, 0);
+                // Project inside the transaction so values reflect the script-end model
+                // state — but never let projection failure masquerade as script failure:
+                // a lazy sequence that faults while being walked (a deleted element, a
+                // throwing property) would otherwise roll back a script that fully
+                // succeeded. The script's changes stand; only the return value is lost.
+                try
+                {
+                    returnValue = Project(state.ReturnValue, 0);
+                }
+                catch (Exception ex)
+                {
+                    projectionError = $"{ex.GetType().Name}: {ex.Message}";
+                    returnValue = $"<the script succeeded, but its return value could not be projected: {projectionError}. Return primitives, strings, or anonymous objects/lists, and use Dump(...) for intermediates.>";
+                }
             }
             catch (Exception ex)
             {
@@ -160,6 +173,8 @@ namespace RevitBridge.Tools
                 ["dumps"] = dumps,
                 ["durationMs"] = stopwatch.ElapsedMilliseconds,
             };
+            if (projectionError != null)
+                payload["returnValueError"] = projectionError;
             if (dialogGuard.Suppressed.Count > 0)
                 payload["suppressedDialogs"] = dialogGuard.Suppressed;
             if (failureGuard.Warnings.Count > 0)

package/src/Revit/Tools/ExportDocuments.cs

@@ -79,10 +79,12 @@ namespace RevitBridge.Tools
             string baseName = SanitizeFileName(string.IsNullOrWhiteSpace(prefixInput) ? doc.Title : prefixInput.Trim());
             bool combine = JsonArgs.GetBool(args, "combine", true);
 
-            // Produced files are found by diffing the directory; the timestamp check
-            // (with clock-skew slack) also catches overwrites of pre-existing names.
-            DateTime startedUtc = DateTime.UtcNow.AddSeconds(-2);
-            var before = new HashSet<string>(Directory.GetFiles(outputDir), StringComparer.OrdinalIgnoreCase);
+            // Produced files are found by diffing the directory, because Revit appends its
+            // own view/sheet suffixes to multi-file export names. Each file is compared
+            // against ITS OWN pre-export write time, so an overwrite of a pre-existing name
+            // still counts as produced while an untouched file that merely happens to be
+            // recent (a shared output_dir, another tool writing alongside) does not.
+            var before = SnapshotWriteTimes(outputDir);
 
             switch (format)
             {
@@ -93,7 +95,7 @@ namespace RevitBridge.Tools
             }
 
             var files = Directory.GetFiles(outputDir)
-                .Where(path => !before.Contains(path) || File.GetLastWriteTimeUtc(path) >= startedUtc)
+                .Where(path => !before.TryGetValue(path, out DateTime writtenBefore) || SafeWriteTime(path) != writtenBefore)
                 .OrderBy(path => path, StringComparer.OrdinalIgnoreCase)
                 .Select(path => new Dictionary<string, object?>
                 {
@@ -115,6 +117,35 @@ namespace RevitBridge.Tools
             }, compact);
         }
 
+        /// <summary>path -> last write time for the files already in the output directory.
+        /// A file whose time cannot be read is left out, so the export reports it if it
+        /// shows up afterwards rather than silently swallowing a produced file.</summary>
+        private static Dictionary<string, DateTime> SnapshotWriteTimes(string directory)
+        {
+            var snapshot = new Dictionary<string, DateTime>(StringComparer.OrdinalIgnoreCase);
+            foreach (string path in Directory.GetFiles(directory))
+            {
+                DateTime writtenAt = SafeWriteTime(path);
+                if (writtenAt != DateTime.MinValue)
+                    snapshot[path] = writtenAt;
+            }
+            return snapshot;
+        }
+
+        /// <summary>DateTime.MinValue when the timestamp is unreadable (file locked or gone),
+        /// which compares as "changed" — an unknown file is reported, never hidden.</summary>
+        private static DateTime SafeWriteTime(string path)
+        {
+            try
+            {
+                return File.GetLastWriteTimeUtc(path);
+            }
+            catch
+            {
+                return DateTime.MinValue;
+            }
+        }
+
         // ------------------------------------------------------------- format runs
 
         private static void ExportPdf(Document doc, List<View> views, string outputDir, string baseName, bool combine)

package/src/Revit/Tools/FailureGuard.cs

@@ -1,62 +1,62 @@
-using Autodesk.Revit.DB;
-
-namespace RevitBridge.Tools
-{
-    /// <summary>
-    /// Deterministic commit-time failure handling for tool-owned transactions. Without a
-    /// preprocessor, Revit resolves commit failures interactively: warnings pop the
-    /// transient toast (and spam the journal), and error-severity failures block the
-    /// Revit API thread behind the modal resolution dialog until a human clicks — past
-    /// the bridge's call budget. Attach() deletes warnings (recorded for the tool
-    /// result) and turns errors into a rollback, so a headless caller always gets an
-    /// answer instead of a hang.
-    /// </summary>
-    internal sealed class FailureGuard : IFailuresPreprocessor
-    {
-        public List<string> Warnings { get; } = new();
-        public List<string> Errors { get; } = new();
-
-        public static FailureGuard Attach(Transaction transaction)
-        {
-            var guard = new FailureGuard();
-            var options = transaction.GetFailureHandlingOptions();
-            options.SetFailuresPreprocessor(guard);
-            options.SetClearAfterRollback(true);
-            transaction.SetFailureHandlingOptions(options);
-            return guard;
-        }
-
-        public FailureProcessingResult PreprocessFailures(FailuresAccessor accessor)
-        {
-            bool hasError = false;
-            foreach (FailureMessageAccessor failure in accessor.GetFailureMessages())
-            {
-                string description;
-                try
-                {
-                    description = failure.GetDescriptionText();
-                }
-                catch
-                {
-                    description = "(failure without description)";
-                }
-
-                if (failure.GetSeverity() == FailureSeverity.Warning)
-                {
-                    Warnings.Add(description);
-                    accessor.DeleteWarning(failure);
-                }
-                else
-                {
-                    hasError = true;
-                    Errors.Add(description);
-                }
-            }
-            return hasError ? FailureProcessingResult.ProceedWithRollBack : FailureProcessingResult.Continue;
-        }
-
-        /// <summary>Formats the recorded errors for a commit-failure message.</summary>
-        public string DescribeErrors()
-            => Errors.Count > 0 ? $" Revit failure(s): {string.Join("; ", Errors)}." : string.Empty;
-    }
-}
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Deterministic commit-time failure handling for tool-owned transactions. Without a
+    /// preprocessor, Revit resolves commit failures interactively: warnings pop the
+    /// transient toast (and spam the journal), and error-severity failures block the
+    /// Revit API thread behind the modal resolution dialog until a human clicks — past
+    /// the bridge's call budget. Attach() deletes warnings (recorded for the tool
+    /// result) and turns errors into a rollback, so a headless caller always gets an
+    /// answer instead of a hang.
+    /// </summary>
+    internal sealed class FailureGuard : IFailuresPreprocessor
+    {
+        public List<string> Warnings { get; } = new();
+        public List<string> Errors { get; } = new();
+
+        public static FailureGuard Attach(Transaction transaction)
+        {
+            var guard = new FailureGuard();
+            var options = transaction.GetFailureHandlingOptions();
+            options.SetFailuresPreprocessor(guard);
+            options.SetClearAfterRollback(true);
+            transaction.SetFailureHandlingOptions(options);
+            return guard;
+        }
+
+        public FailureProcessingResult PreprocessFailures(FailuresAccessor accessor)
+        {
+            bool hasError = false;
+            foreach (FailureMessageAccessor failure in accessor.GetFailureMessages())
+            {
+                string description;
+                try
+                {
+                    description = failure.GetDescriptionText();
+                }
+                catch
+                {
+                    description = "(failure without description)";
+                }
+
+                if (failure.GetSeverity() == FailureSeverity.Warning)
+                {
+                    Warnings.Add(description);
+                    accessor.DeleteWarning(failure);
+                }
+                else
+                {
+                    hasError = true;
+                    Errors.Add(description);
+                }
+            }
+            return hasError ? FailureProcessingResult.ProceedWithRollBack : FailureProcessingResult.Continue;
+        }
+
+        /// <summary>Formats the recorded errors for a commit-failure message.</summary>
+        public string DescribeErrors()
+            => Errors.Count > 0 ? $" Revit failure(s): {string.Join("; ", Errors)}." : string.Empty;
+    }
+}

package/src/Revit/Tools/GetElements.cs

@@ -136,7 +136,7 @@ namespace RevitBridge.Tools
                 return collector;
             }
 
-            var (quickFilter, postPredicate) = BuildParameterFilter(doc, args, CreateBaseCollector);
+            var (quickFilter, postPredicate, filterWarnings) = BuildParameterFilter(doc, args, CreateBaseCollector);
 
             FilteredElementCollector CreateCollector()
             {
@@ -147,7 +147,7 @@ namespace RevitBridge.Tools
             string scope = DescribeScope(categoryInput, classInput, inActiveView);
 
             if (countOnly && postPredicate is null)
-                return CountResult(scope, CreateCollector().GetElementCount());
+                return CountResult(scope, CreateCollector().GetElementCount(), filterWarnings);
 
             var rows = countOnly ? null : new List<Dictionary<string, object?>>(Math.Min(limit, 256));
             int total = 0;
@@ -161,7 +161,7 @@ namespace RevitBridge.Tools
             }
 
             if (rows is null)
-                return CountResult(scope, total);
+                return CountResult(scope, total, filterWarnings);
 
             bool hasMore = offset + rows.Count < total;
             int? nextOffset = hasMore ? offset + rows.Count : null;
@@ -172,9 +172,10 @@ namespace RevitBridge.Tools
                 var sample = rows.Take(3).Select(row => $"'{row["name"]}' ({row["id"]})");
                 sampleText = $" Sample: {string.Join(", ", sample)}.";
             }
-            string compact = hasMore
+            string compact = (hasMore
                 ? $"{scope}: {total} total, returned {rows.Count} at offset {offset}, has_more (next_offset {nextOffset}).{sampleText}"
-                : $"{scope}: {total} total, returned {rows.Count} at offset {offset}.{sampleText}";
+                : $"{scope}: {total} total, returned {rows.Count} at offset {offset}.{sampleText}")
+                + WarningSuffix(filterWarnings);
 
             return new ToolOutput(new
             {
@@ -184,11 +185,16 @@ namespace RevitBridge.Tools
                 has_more = hasMore,
                 next_offset = nextOffset,
                 elements = rows,
+                warnings = filterWarnings.Count > 0 ? filterWarnings : null,
             }, compact);
         }
 
-        private static ToolOutput CountResult(string scope, int count)
-            => new(new { total_count = count, count_only = true }, $"{scope}: {count} elements match.");
+        private static ToolOutput CountResult(string scope, int count, IReadOnlyList<string> warnings)
+            => new(new { total_count = count, count_only = true, warnings = warnings.Count > 0 ? warnings : null },
+                $"{scope}: {count} elements match." + WarningSuffix(warnings));
+
+        private static string WarningSuffix(IReadOnlyList<string> warnings)
+            => warnings.Count > 0 ? " WARNING: " + string.Join(" ", warnings) : string.Empty;
 
         private static string DescribeScope(string? category, string? className, bool inActiveView)
         {
@@ -263,11 +269,11 @@ namespace RevitBridge.Tools
             public FilterRule? QuickRule { get; set; }
         }
 
-        private static (ElementFilter? Quick, Func<Element, bool>? Post) BuildParameterFilter(
+        private static (ElementFilter? Quick, Func<Element, bool>? Post, IReadOnlyList<string> Warnings) BuildParameterFilter(
             Document doc, JsonElement args, Func<FilteredElementCollector> createBaseCollector)
         {
             if (args.ValueKind != JsonValueKind.Object || !args.TryGetProperty("filter", out var filterElement) || filterElement.ValueKind != JsonValueKind.Object)
-                return (null, null);
+                return (null, null, Array.Empty<string>());
 
             bool matchAny = string.Equals(JsonArgs.GetString(filterElement, "match"), "any", StringComparison.OrdinalIgnoreCase);
             if (!filterElement.TryGetProperty("rules", out var rulesElement) || rulesElement.ValueKind != JsonValueKind.Array)
@@ -275,7 +281,7 @@ namespace RevitBridge.Tools
 
             var rules = rulesElement.EnumerateArray().Select(ParseRule).ToList();
             if (rules.Count == 0)
-                return (null, null);
+                return (null, null, Array.Empty<string>());
 
             // Probe a few in-scope elements so display-name parameters resolve to ids
             // and value typing / unit conversion can use the parameter's storage + spec.
@@ -287,6 +293,29 @@ namespace RevitBridge.Tools
                     break;
             }
 
+            // A display-name rule that no probed element carries is the localized-UI trap:
+            // the post-scan then matches nothing and the result reads "0 total" -- which the
+            // caller cannot tell apart from a genuine no-match. Typical case: an English
+            // display name queried against a non-English UI, where the same parameter
+            // carries a translated name.
+            // A warning (not an error: the parameter may exist past the probe window,
+            // and is_empty legitimately matches missing parameters) makes the zero honest.
+            var warnings = new List<string>();
+            if (probes.Count > 0)
+            {
+                foreach (var rule in rules)
+                {
+                    if (rule.BuiltIn != null || rule.SharedGuid != null)
+                        continue;
+                    if (probes.All(probe => FindParameter(probe, rule) is null))
+                        warnings.Add(
+                            $"Filter parameter '{rule.ParamInput}' was not found on any of the {probes.Count} probed element(s) in scope, "
+                            + "so a 0-match result may mean 'unknown parameter name', not 'no matching elements'. Display names are "
+                            + "localized in non-English Revit UIs -- prefer the language-independent BuiltInParameter enum name "
+                            + "(get_element_details reports it as builtInParameter per parameter).");
+                }
+            }
+
             // Display-name promotion is only trustworthy inside one category/class: the
             // probe sees just the first ProbeSize elements in collector order, so in an
             // unscoped query a unanimous sample can still hide other categories further
@@ -321,10 +350,10 @@ namespace RevitBridge.Tools
                 // OR with any post-scan rule means everything must be post-scanned: a
                 // collector-level OR filter would wrongly exclude post-rule-only matches.
                 if (postRules.Count > 0)
-                    return (null, element => rules.Any(rule => EvaluatePost(doc, element, rule)));
+                    return (null, element => rules.Any(rule => EvaluatePost(doc, element, rule)), warnings);
 
                 var filters = quickRules.Select(rule => (ElementFilter)new ElementParameterFilter(rule.QuickRule!)).ToList();
-                return (filters.Count == 1 ? filters[0] : new LogicalOrFilter(filters), null);
+                return (filters.Count == 1 ? filters[0] : new LogicalOrFilter(filters), null, warnings);
             }
 
             ElementFilter? quick = quickRules.Count > 0
@@ -333,7 +362,7 @@ namespace RevitBridge.Tools
             Func<Element, bool>? post = postRules.Count > 0
                 ? element => postRules.All(rule => EvaluatePost(doc, element, rule))
                 : null;
-            return (quick, post);
+            return (quick, post, warnings);
         }
 
         private static Rule ParseRule(JsonElement element)
@@ -501,6 +530,11 @@ namespace RevitBridge.Tools
             }
         }
 
+        /// <summary>Per-element evaluation for rules the collector cannot quick-filter.
+        /// A value that does not fit the parameter's storage type is a caller mistake, and
+        /// must fail the same way it does on the quick path (TryBuildQuickRule) — otherwise
+        /// the identical query reports a clear error when scoped and a silent zero matches
+        /// when unscoped.</summary>
         private static bool EvaluatePost(Document doc, Element element, Rule rule)
         {
             var parameter = FindParameter(element, rule);
@@ -544,7 +578,7 @@ namespace RevitBridge.Tools
                     if (rule.Op == RuleOp.Contains)
                         return ComparableText(doc, parameter).Contains(ValueAsString(rule.Value), StringComparison.Ordinal);
                     if (!TryValueAsDouble(rule.Value, out double raw))
-                        return false;
+                        throw new ArgumentException($"Filter rule on numeric parameter '{parameter.Definition?.Name}' needs a numeric value (got {rule.Value.GetRawText()}).");
                     double target = ToInternalUnits(doc, rule, parameter, raw);
                     double actual = parameter.AsDouble();
                     return rule.Op switch
@@ -559,7 +593,7 @@ namespace RevitBridge.Tools
                     if (rule.Op == RuleOp.Contains)
                         return ComparableText(doc, parameter).Contains(ValueAsString(rule.Value), StringComparison.Ordinal);
                     if (!TryValueAsInt(rule.Value, out int target))
-                        return false;
+                        throw new ArgumentException($"Filter rule on integer parameter '{parameter.Definition?.Name}' needs an integer or boolean value.");
                     return Compare(parameter.AsInteger().CompareTo(target), rule.Op);
                 }
                 case StorageType.ElementId:

package/src/Revit/Tools/OpenView.cs

@@ -0,0 +1,103 @@
+using System.Text.Json;
+using Autodesk.Revit.DB;
+
+namespace RevitBridge.Tools
+{
+    /// <summary>
+    /// Activates a view or sheet in the Revit UI — the API equivalent of double-clicking
+    /// it in the Project Browser. Uses UIDocument.RequestViewChange, which is explicitly
+    /// permitted from an ExternalEvent callback (where all bridge tools run) as long as no
+    /// transaction is open; the tool opens none. The activation is asynchronous by design:
+    /// Revit performs it the moment control returns from the bridge call.
+    /// </summary>
+    internal sealed class OpenView : ITool
+    {
+        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 object ParametersSchema => new
+        {
+            type = "object",
+            properties = new
+            {
+                view_id = new { type = "integer", description = "Id of the view or sheet to activate." },
+                name = new { type = "string", description = "Exact view name, sheet number, or sheet 'number - name' (case-insensitive). Used when view_id is absent." },
+            },
+        };
+
+        public string? PromptSnippet => "Activate a Revit view or sheet in the UI by id or name (like double-clicking it in the Project Browser).";
+        public IReadOnlyList<string>? PromptGuidelines => new[]
+        {
+            "Use open_view to put a view or sheet on the user's screen (e.g. after creating a sheet); activation completes right after the call, so capture_view in the SAME call batch may still show the old view.",
+        };
+
+        public object? Execute(JsonElement args, ToolContext context)
+        {
+            var doc = context.Document ?? throw new NoActiveDocumentException();
+            var uiapp = context.UIApplication ?? throw new NoActiveDocumentException();
+            var uidoc = uiapp.ActiveUIDocument ?? throw new NoActiveDocumentException();
+
+            long? viewId = JsonArgs.GetLong(args, "view_id");
+            string? name = JsonArgs.GetString(args, "name");
+            if (viewId is null && string.IsNullOrWhiteSpace(name))
+                throw new ArgumentException("Pass view_id or name to identify the view or sheet to open.");
+
+            View view = viewId is { } id ? ResolveById(doc, id) : ResolveByName(doc, name!.Trim());
+
+            try
+            {
+                uidoc.RequestViewChange(view);
+            }
+            catch (Autodesk.Revit.Exceptions.ArgumentException ex)
+            {
+                throw new ArgumentException($"View '{view.Name}' (id {view.Id.Value}) cannot be activated: {ex.Message}");
+            }
+            catch (Autodesk.Revit.Exceptions.InvalidOperationException ex)
+            {
+                throw new InvalidOperationException(
+                    $"Revit refused to queue the view change to '{view.Name}': {ex.Message} "
+                    + "The document may be mid-edit; retry after the current operation finishes.");
+            }
+
+            string kind = view is ViewSheet sheet ? $"sheet {sheet.SheetNumber}" : view.ViewType.ToString();
+            return new ToolOutput(new
+            {
+                requestedViewId = view.Id.Value,
+                viewName = view.Name,
+                viewType = view.ViewType.ToString(),
+            }, $"Queued activation of {kind} '{view.Name}' (id {view.Id.Value}); it opens as soon as Revit regains control.");
+        }
+
+        private static View ResolveById(Document doc, long id)
+        {
+            var view = doc.GetElement(new ElementId(id)) as View
+                ?? throw new ArgumentException($"Element {id} is not a view or sheet (or does not exist). Find view ids with get_elements, category 'Views' or 'Sheets'.");
+            if (view.IsTemplate)
+                throw new ArgumentException($"View '{view.Name}' (id {id}) is a view template; templates cannot be opened.");
+            return view;
+        }
+
+        private static View ResolveByName(Document doc, string name)
+        {
+            var candidates = new FilteredElementCollector(doc)
+                .OfClass(typeof(View))
+                .Cast<View>()
+                .Where(view => !view.IsTemplate)
+                .Where(view =>
+                    string.Equals(view.Name, name, StringComparison.OrdinalIgnoreCase)
+                    || (view is ViewSheet sheet
+                        && (string.Equals(sheet.SheetNumber, name, StringComparison.OrdinalIgnoreCase)
+                            || string.Equals($"{sheet.SheetNumber} - {sheet.Name}", name, StringComparison.OrdinalIgnoreCase))))
+                .ToList();
+
+            if (candidates.Count == 1)
+                return candidates[0];
+            if (candidates.Count == 0)
+                throw new ArgumentException($"No view or sheet named '{name}'. Find the exact name or sheet number with get_elements, category 'Views' or 'Sheets'.");
+            string list = string.Join("; ", candidates.Take(8).Select(view => $"'{view.Name}' (id {view.Id.Value}, {view.ViewType})"));
+            throw new ArgumentException($"'{name}' matches {candidates.Count} views: {list}. Pass view_id to disambiguate.");
+        }
+    }
+}