Add FileNode/FileStorage.GetPath and a JsonNode write bridge

GetPath(params object[] path) navigates a chain of mapping keys
(string) and/or sequence indices (int), disposing every intermediate
FileNode along the way - the chained-indexer pattern (node["a"]["b"])
otherwise leaves each intermediate node referenced by nothing, relying
on SafeHandle's finalizer for eventual (delayed) cleanup instead of
prompt disposal. FileStorage.GetPath starts from the top-level mapping
and delegates the rest to FileNode.GetPath.

FileStorage.Write(string, JsonNode?) is the write-side counterpart to
FileNode.ToJsonNode(): it recursively writes a JsonObject/JsonArray/
JsonValue tree via the existing Write/WriteStruct calls. Native
FileStorage remains the actual XML/YAML/JSON engine (no format-parsing
logic is reimplemented) - this only lets callers build the data with
System.Text.Json types instead of one call per value/struct scope.
A JSON null throws, since FileStorage has no native representation
for an explicit null scalar.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: shimat

src/OpenCvSharp/Modules/core/FileNode.cs

@@ -315,6 +315,50 @@ public FileNode? this[int i]
         }
     }
 
+    /// <summary>
+    /// Navigates a chain of mapping keys (<see cref="string"/>) and/or sequence indices
+    /// (<see cref="int"/>), disposing every intermediate <see cref="FileNode"/> along the way.
+    /// Equivalent to repeated indexer chaining (e.g. <c>node["a"][2]["b"]</c>), except that the
+    /// indexer chain leaves every intermediate node unreferenced - each one is still a real
+    /// native allocation that would otherwise sit around until the GC finalizes it.
+    /// </summary>
+    /// <param name="path">One or more mapping keys / sequence indices to follow, in order.</param>
+    /// <returns>The node at the end of the path, or null if any segment along the way is missing.</returns>
+    public FileNode? GetPath(params object[] path)
+    {
+        ArgumentNullException.ThrowIfNull(path);
+        if (path.Length == 0)
+            throw new ArgumentException("Path must contain at least one key or index.", nameof(path));
+
+        ThrowIfDisposed();
+
+        var current = this;
+        var ownsCurrent = false;
+
+        foreach (var segment in path)
+        {
+            var next = segment switch
+            {
+                string key => current[key],
+                int index => current[index],
+                _ => throw new ArgumentException(
+                    $"Path segments must be string (mapping key) or int (sequence index), got '{segment?.GetType()}'.",
+                    nameof(path)),
+            };
+
+            if (ownsCurrent)
+                current.Dispose();
+
+            if (next is null)
+                return null;
+
+            current = next;
+            ownsCurrent = true;
+        }
+
+        return current;
+    }
+
     /// <summary>
     /// Returns true if the node is empty
     /// </summary>

src/OpenCvSharp/Modules/core/FileStorage.cs

@@ -1,4 +1,5 @@
 using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Nodes;
 using OpenCvSharp.Internal;
 using OpenCvSharp.Internal.Vectors;
 
@@ -79,6 +80,41 @@ public FileNode? this[string nodeName]
         }
     }
 
+    /// <summary>
+    /// Navigates a chain of mapping keys (<see cref="string"/>) and/or sequence indices
+    /// (<see cref="int"/>) starting from the top-level mapping, disposing every intermediate
+    /// <see cref="FileNode"/> along the way. Equivalent to repeated indexer chaining (e.g.
+    /// <c>fs["a"][2]["b"]</c>), except that the indexer chain leaves every intermediate node
+    /// unreferenced - each one is still a real native allocation that would otherwise sit
+    /// around until the GC finalizes it.
+    /// </summary>
+    /// <param name="path">One or more mapping keys / sequence indices to follow, in order.
+    /// The first segment must be a string (a key of the top-level mapping).</param>
+    /// <returns>The node at the end of the path, or null if any segment along the way is missing.</returns>
+    public FileNode? GetPath(params object[] path)
+    {
+        ArgumentNullException.ThrowIfNull(path);
+        if (path.Length == 0)
+            throw new ArgumentException("Path must contain at least one key or index.", nameof(path));
+        if (path[0] is not string firstKey)
+            throw new ArgumentException("The first path segment must be a string (top-level mapping key).", nameof(path));
+
+        ThrowIfDisposed();
+
+        var first = this[firstKey];
+        if (first is null || path.Length == 1)
+            return first;
+
+        try
+        {
+            return first.GetPath(path[1..]);
+        }
+        finally
+        {
+            first.Dispose();
+        }
+    }
+
     /// <summary>
     /// the currently written element
     /// </summary>
@@ -521,7 +557,63 @@ public void Write(string name, IEnumerable<string> value)
     }
 
     /// <summary>
-    /// 
+    /// Writes a <see cref="JsonNode"/> tree (scalars, arrays, objects) under the given key,
+    /// recursively, via the ordinary <see cref="Write(string,int)"/>/<see cref="WriteStruct"/>
+    /// calls - the counterpart to <see cref="FileNode.ToJsonNode"/>. Native FileStorage remains
+    /// the actual XML/YAML/JSON engine; this only lets callers build the data to write using
+    /// <see cref="System.Text.Json"/> types instead of one-call-per-value/struct-scope calls.
+    /// </summary>
+    /// <param name="name">Key to write the value under (top level or inside an open mapping).
+    /// Pass an empty string for an anonymous element inside an open sequence.</param>
+    /// <param name="value">The value to write. A JSON null throws, since FileStorage has no
+    /// native representation for an explicit null scalar.</param>
+    public void Write(string name, JsonNode? value)
+    {
+        ThrowIfDisposed();
+        ArgumentNullException.ThrowIfNull(name);
+
+        switch (value)
+        {
+            case null:
+                throw new NotSupportedException(
+                    $"Cannot write a JSON null for key '{name}': FileStorage has no representation for an explicit null value.");
+
+            case JsonObject obj:
+                using (WriteStruct(name, FileNode.Types.Map))
+                {
+                    foreach (var (key, child) in obj)
+                        Write(key, child);
+                }
+                break;
+
+            case JsonArray array:
+                using (WriteStruct(name, FileNode.Types.Seq))
+                {
+                    foreach (var item in array)
+                        Write(string.Empty, item);
+                }
+                break;
+
+            case JsonValue scalar:
+                WriteJsonScalar(name, scalar);
+                break;
+
+            default:
+                throw new NotSupportedException($"Unsupported JsonNode type '{value.GetType()}' for key '{name}'.");
+        }
+    }
+
+    private void WriteJsonScalar(string name, JsonValue value)
+    {
+        if (value.TryGetValue(out bool b)) { Write(name, b); return; }
+        if (value.TryGetValue(out long l)) { Write(name, l); return; }
+        if (value.TryGetValue(out double d)) { Write(name, d); return; }
+        if (value.TryGetValue(out string? s)) { Write(name, s!); return; }
+        throw new NotSupportedException($"Unsupported JsonValue underlying type for key '{name}'.");
+    }
+
+    /// <summary>
+    ///
     /// </summary>
     /// <param name="value"></param>
     public void WriteScalar(int value)

test/OpenCvSharp.Tests/core/FileStorageTest.cs

@@ -593,4 +593,118 @@ public void ToJsonNodeConvertsScalarsSequencesAndMappings()
             Assert.Contains("widget", roundTripped, StringComparison.Ordinal);
         }
     }
+
+    [Fact]
+    public void WriteJsonNodeRoundTripsThroughToJsonNode()
+    {
+        const string fileName = "fs_write_json_node.yml";
+
+        var source = JsonNode.Parse("""
+            {
+                "name": "widget",
+                "count": 3,
+                "ratio": 1.5,
+                "enabled": true,
+                "tags": ["red", "green", "blue"],
+                "nested": { "x": 1, "y": 2 },
+                "matrix": [[1, 2], [3, 4]]
+            }
+            """)!;
+
+        using (var fs = new FileStorage(fileName, FileStorage.Modes.Write))
+        {
+            foreach (var (key, value) in source.AsObject())
+                fs.Write(key, value);
+        }
+
+        using (var fs = new FileStorage(fileName, FileStorage.Modes.Read))
+        {
+            using var root = fs.Root();
+            Assert.NotNull(root);
+            var json = root.ToJsonNode();
+            Assert.NotNull(json);
+
+            Assert.Equal("widget", json!["name"]!.GetValue<string>());
+            Assert.Equal(3L, json["count"]!.GetValue<long>());
+            Assert.Equal(1.5, json["ratio"]!.GetValue<double>());
+            Assert.Equal(1L, json["enabled"]!.GetValue<long>()); // bool round-trips as int (0/1) in FileStorage
+
+            var tags = Assert.IsType<JsonArray>(json["tags"]);
+            Assert.Equal(["red", "green", "blue"], tags.Select(n => n!.GetValue<string>()));
+
+            var nested = Assert.IsType<JsonObject>(json["nested"]);
+            Assert.Equal(1L, nested["x"]!.GetValue<long>());
+            Assert.Equal(2L, nested["y"]!.GetValue<long>());
+
+            var matrix = Assert.IsType<JsonArray>(json["matrix"]);
+            Assert.Equal(2, matrix.Count);
+            var row0 = Assert.IsType<JsonArray>(matrix[0]);
+            Assert.Equal([1L, 2L], row0.Select(n => n!.GetValue<long>()));
+            var row1 = Assert.IsType<JsonArray>(matrix[1]);
+            Assert.Equal([3L, 4L], row1.Select(n => n!.GetValue<long>()));
+        }
+    }
+
+    [Fact]
+    public void WriteJsonNodeNullThrows()
+    {
+        const string fileName = "fs_write_json_node_null.yml";
+        using var fs = new FileStorage(fileName, FileStorage.Modes.Write);
+
+        Assert.Throws<NotSupportedException>(() => fs.Write("x", (JsonNode?)null));
+    }
+
+    [Fact]
+    public void GetPathNavigatesNestedStructure()
+    {
+        const string fileName = "fs_get_path.yml";
+
+        using (var fs = new FileStorage(fileName, FileStorage.Modes.Write))
+        {
+            using (fs.WriteStruct("a", FileNode.Types.Map))
+            {
+                using (fs.WriteStruct("b", FileNode.Types.Seq))
+                {
+                    fs.Add(10).Add(20).Add(30);
+                }
+            }
+        }
+
+        using (var fs = new FileStorage(fileName, FileStorage.Modes.Read))
+        {
+            using var value = fs.GetPath("a", "b", 1);
+            Assert.NotNull(value);
+            Assert.Equal(20, value.ReadInt());
+
+            Assert.Null(fs.GetPath("a", "missing"));
+            Assert.Null(fs.GetPath("missing"));
+
+            using var root = fs.Root();
+            Assert.NotNull(root);
+            using var viaFileNode = root.GetPath("a", "b", 2);
+            Assert.NotNull(viaFileNode);
+            Assert.Equal(30, viaFileNode.ReadInt());
+        }
+    }
+
+    [Fact]
+    public void GetPathRejectsEmptyOrInvalidSegments()
+    {
+        const string fileName = "fs_get_path_invalid.yml";
+        using (var fs = new FileStorage(fileName, FileStorage.Modes.Write))
+        {
+            fs.Write("a", 1);
+        }
+
+        using (var fs = new FileStorage(fileName, FileStorage.Modes.Read))
+        {
+            Assert.Throws<ArgumentException>(() => fs.GetPath());
+            Assert.Throws<ArgumentException>(() => fs.GetPath(42)); // first segment must be a string
+
+            using var root = fs.Root();
+            Assert.NotNull(root);
+            Assert.Throws<ArgumentException>(() => root.GetPath());
+            Assert.Throws<ArgumentException>(() => root.GetPath(3.14)); // unsupported segment type
+        }
+    }
 }