Krypton-Suite · PWagner1 · Jun 26, 2026 · Jun 26, 2026 · Jun 26, 2026 · Jun 26, 2026
@@ -0,0 +1,15 @@
+# Development Guides
+
+In-depth, maintainer-focused documentation for completed features lives in this folder.
+
+Each guide covers architecture, public APIs, usage, and validation. See **Feature Developer Documentation** in the repository root `AGENTS.md` for authoring rules.
+
+These guides are **not** indexed in `Documents/Changelog/Changelog.md` or `Scripts/ModernBuild/README.md`.
+
+## Guides
+
+_Add a row when a new guide is added._
+
+| Guide | Summary |
+|-------|---------|
+| _(none yet)_ | |
@@ -13,7 +13,7 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends the KryptonNavigator to work as a docking auto hidden group control.
+/// Tab strip for auto-hidden pages on one edge. Disposes itself when the last tab is removed.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]

@@ -13,7 +13,8 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends the KryptonPanel to work as a panel for hosting KryptonAutoHiddenGroup controls.
+/// Edge strip that stacks <see cref="KryptonAutoHiddenGroup"/> tab controls. Preferred size accounts
+/// for group stacking along the dock orientation.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]

@@ -13,7 +13,9 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Acts as a proxy for a KryptonPage inside an auto hidden group.
+/// Tab entry in an auto-hidden group that mirrors a single <see cref="KryptonPage"/> instance also
+/// hosted in the slide-out dockspace. The proxy supplies group-tab chrome; <see cref="Page"/> is the
+/// content shown when the tab is selected. Unwrapped by <c>PropogatePageState</c> for unique-name lookup.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]

@@ -17,7 +17,9 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends the KryptonPanel to work as a panel for hosting the display of a sliding in/out page.
+/// Animated slide-out host for auto-hidden content. State machine:
+/// Hidden → SlidingOut → Showing → SlidingIn → Hidden. <see cref="IMessageFilter"/> dismisses the panel
+/// when focus or the mouse leaves the slide/dockspace area; separator drag resizes against client minimums.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]
@@ -28,6 +30,7 @@ public class KryptonAutoHiddenSlidePanel : KryptonPanel,
     #region Static Fields
 
     private const int SLIDE_MINIMUM = 27;
+    // int.MaxValue advances the full distance each tick (instant slide); 16 would animate incrementally.
     private const int SLIDE_DISTANCE = int.MaxValue; // = 16;
     private const int SLIDE_INTERVAL = 15;
     private const int CLIENT_MINIMUM = 22;
@@ -160,7 +163,7 @@ public KryptonAutoHiddenSlidePanel(Control control, DockingEdge edge, KryptonAut
         // Do not show ourselves until we are needed
         Visible = false;
 
-        // Add a Button that is not showing and used to push focus away from the dockspace
+        // Off-screen focus sink so keyboard focus leaves the slide dockspace when sliding in.
         _dummyTarget = new Button
         {
             Location = new Point(-200, -200),
@@ -702,7 +705,7 @@ private void CalculateStartAndEnd()
         var slideSize = new Size(separatorPreferred.Width + dockspacePreferred.Width,
             separatorPreferred.Height + dockspacePreferred.Height);
 
-        // Find the maximum allowed size based on the owning control client area reduced by a sensible minimum
+        // Clamp slide size to remaining client area minus tab strips on other edges.
         Size innerSize = _control.ClientRectangle.Size;
         innerSize.Width -= CLIENT_MINIMUM;
         innerSize.Height -= CLIENT_MINIMUM;

@@ -13,7 +13,7 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends the KryptonNavigator to work within the docking framework.
+/// Designer-facing navigator wired into <see cref="KryptonDockingNavigator"/>; forwards docking events.
 /// </summary>
 [ToolboxBitmap(typeof(KryptonDockableWorkspace), "ToolboxBitmaps.KryptonDockableNavigator.bmp")]
 public class KryptonDockableNavigator : KryptonNavigator

@@ -13,7 +13,7 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends the KryptonWorkspace to work within the docking framework.
+/// Designer-facing workspace wired into <see cref="KryptonDockingWorkspace"/>; enables tab context menus.
 /// </summary>
 [ToolboxBitmap(typeof(KryptonDockableWorkspace), "ToolboxBitmaps.KryptonDockableWorkspace.bmp")]
 public class KryptonDockableWorkspace : KryptonSpace

@@ -13,7 +13,7 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends the KryptonWorkspace to work within the docking edge of a control.
+/// Visible docked workspace on a control edge. Store name "Docked" routes placeholder clears.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]

@@ -13,7 +13,8 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends the KryptonSeparator so work between dockspace entries on a control edge.
+/// Resize grip between stacked <see cref="KryptonDockspace"/> controls on one edge.
+/// Dock/orientation are derived from the parent edge and whether the grip faces inward.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]

@@ -13,7 +13,7 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends the KryptonWorkspace to work within the docking edge of a control.
+/// Dockspace hosted inside the auto-hidden slide panel. Page drag is disabled; content moves via pin/float requests.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]

@@ -12,7 +12,10 @@
 
 namespace Krypton.Docking;
 
-/// <summary>Extends the KryptonForm to act as a floating window within the docking framework.</summary>
+/// <summary>
+/// Top-level floating frame. Caption drag raises <see cref="WindowCaptionDragging"/> so
+/// <see cref="DockingDragManager"/> can reposition the window during a page drag operation.
+/// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]
 [DesignTimeVisible(false)]

@@ -13,7 +13,7 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends the KryptonWorkspace to work within the docking floating window.
+/// Workspace inside a floating window. Store name "Floating"; pin action is disabled.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]

@@ -13,7 +13,8 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends the KryptonWorkspace with common functionality shared by various docking implementations.
+/// Workspace base for dockspace, floatspace, and filler hosts. Caches per-cell button specs and focus
+/// state because docking chrome (close, pin, dropdown) is attached outside the workspace cell model.
 /// </summary>
 public abstract class KryptonSpace : KryptonWorkspace
 {
@@ -24,7 +25,7 @@ public abstract class KryptonSpace : KryptonWorkspace
     protected class CellToCachedState : Dictionary<KryptonWorkspaceCell, CachedCellState> { };
 
     /// <summary>
-    /// State cached per-cell within the workspace.
+    /// Per-cell docking chrome and focus tracking; keyed by cell because specs are not on KryptonWorkspaceCell.
     /// </summary>
     protected class CachedCellState
     {
@@ -321,7 +322,7 @@ public override void WritePageElement(XmlWriter xmlWriter, KryptonPage page)
 
         if (page != null)
         {
-            // If this is a store page then recreate as a store page type
+            // Attribute S marks a persisted placeholder; recreate as KryptonStorePage with this host's store name.
             if (CommonHelper.StringToBool(XmlHelper.XmlAttributeToText(xmlReader, @"S")))
             {
                 page = new KryptonStorePage(page.UniqueName, _storeName);

@@ -13,7 +13,9 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Acts as a placeholder for a KryptonPage so that it can be restored to this location at a later time.
+/// Invisible placeholder left at the original tab/cell index while the real page is shown elsewhere.
+/// <see cref="StoreName"/> scopes clears (<c>ClearDockedStoredPages</c>, etc.) so only the matching
+/// host removes its placeholder when the page returns or is discarded.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]

@@ -15,7 +15,8 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Manage a docking dragging operation.
+/// Docking-specific drag manager: tracks a <see cref="KryptonFloatingWindow"/> during page moves,
+/// filters Win32 messages for float-window caption drag, and clears temporary store pages on dispose.
 /// </summary>
 public class DockingDragManager : DragManager,
     IFloatingMessages,

@@ -13,7 +13,8 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Provides the set of drag targets relevant to the set of pages being moved.
+/// Collects drop targets from the docking tree via <see cref="KryptonDockingManager"/> propagation.
+/// Falls back to <see cref="DragTargetNull"/> when no edge or cell accepts the dragged pages.
 /// </summary>
 public class DockingDragTargetProvider : IDragTargetProvider
 {

@@ -100,6 +100,7 @@ protected override void Dispose(bool disposing)
     /// <param name="dragEndData">Data to be dropped at destination.</param>
     /// <returns>True if a match; otherwise false.</returns>
     public override bool IsMatch(Point screenPt, PageDragEndData? dragEndData) => true;
+    // Hot-rect hit testing lives in the base DragTarget; this override defers to that geometry.
 
     /// <summary>
     /// Perform the drop action associated with the target.
@@ -149,7 +150,7 @@ public override bool PerformDrop(Point screenPt, PageDragEndData? data)
             // Transfer valid pages into the new dockspace
             if (transferPages.Count > 0)
             {
-                // Convert the incoming pages into store pages for restoring later
+                // Store at source before append so the drag source can remove pages without losing index.
                 manager?.PropogateAction(DockingPropogateAction.StorePages, transferUniqueNames.ToArray());
 
                 // Create a new dockspace at the start of the list so it is closest to the control edge

@@ -35,6 +35,7 @@ public DragTargetNull()
     /// <param name="data">Data to pass to the target to process drop.</param>
     /// <returns>Drop was performed and the source can perform any removal of pages as required.</returns>
     public override bool PerformDrop(Point screenPt, PageDragEndData? data) => true;
+    // Returning true tells the drag source not to remove pages (no valid drop occurred).
 
     #endregion
 }
@@ -15,7 +15,10 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Implements base docking element functionality.
+/// Root of the docking element composite tree. Each node implements <see cref="IDockingElement"/> and
+/// forwards <c>Propogate*</c> requests to children; leaf nodes (spaces, groups, navigators) own the
+/// actual WinForms controls. Path resolution walks down by comma-separated element names; parent lookup
+/// walks up to reach <see cref="KryptonDockingManager"/>.
 /// </summary>
 public abstract class DockingElement : Component,
     IDockingElement
@@ -107,7 +110,7 @@ public string Path
             }
             else
             {
-                // Extract the remainder of the path
+                // Remainder keeps the leading comma so child names still parse as "Child,Grandchild"
                 var remainder = path.Substring(comma, path.Length - comma);
 
                 // Give each child a chance to resolve the remainder of the path

@@ -13,7 +13,8 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends base functionality by allowing a collection of child docking elements.
+/// Read-only child collection surface; mutations go through protected <c>Internal*</c> helpers so
+/// derived types control when children are added. Element names must be unique within a collection.
 /// </summary>
 public abstract class DockingElementClosedCollection : DockingElement
 {

@@ -13,7 +13,8 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Extends base functionality by allowing a collection of child docking elements.
+/// Exposes public Add/Insert/Remove/Clear on top of the closed collection; used by the manager root
+/// and <see cref="KryptonDockingControl"/> where callers assemble the docking tree at runtime.
 /// </summary>
 public abstract class DockingElementOpenCollection : DockingElementClosedCollection
 {

@@ -13,7 +13,8 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Provides display and docking functionality for a group of auto hidden pages.
+/// Element for one auto-hidden tab group. Pages appear as <see cref="KryptonAutoHiddenProxyPage"/>
+/// tabs; the slide panel shows the real page in a <see cref="KryptonDockspaceSlide"/>.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]
@@ -300,7 +301,7 @@ public override void PropogateAction(DockingPropogateAction action, KryptonPage[
     {
         if (state == DockingPropogatePageState.PageForUniqueName)
         {
-            // If we have the page (stored via a proxy) then return the actual page reference (but not for a placeholder)
+            // Tabs hold proxies; callers need the wrapped page for store/restore and drag operations.
             KryptonPage? page = AutoHiddenGroupControl.Pages[uniqueName];
             if (page is KryptonAutoHiddenProxyPage proxyPage)
             {

@@ -15,7 +15,8 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Provides docking functionality for a control instance.
+/// Binds docking to a single host <see cref="Control"/>. Suspends layout during multi-step updates,
+/// enforces <see cref="InnerMinimum"/> after dockspace resize, and registers outer/inner edge drag targets.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]
@@ -131,12 +132,13 @@ public override void PropogateAction(DockingPropogateAction action, string[]? un
         switch (action)
         {
             case DockingPropogateAction.StartUpdate:
-                // Only the first of several 'StartUpdate' actions needs actioning
+                // Nested StartUpdate/EndUpdate pairs only suspend layout on the outermost pair.
                 if (_updateCount++ == 0)
                 {
                     Control.SuspendLayout();
 
-                    /* Place the obscuring control at the top of the z-order
+                    /* ObscureControl overlay was retired: SuspendLayout alone avoids flicker without
+                    hiding the client area during batch updates.
                     Control.Controls.SetChildIndex(_obscure, 0);
 
                     // Set obscuring control to take up entire client area and be made visible, this prevents
@@ -203,7 +205,8 @@ public override void PropogateDragTargets(KryptonFloatingWindow? floatingWindow,
             // Only generate targets if we have some valid pages to transfer
             if (transferPages.Count > 0)
             {
-                // Generate targets for the four control edges
+                // Outer-edge targets (outsideEdge=true) insert new dockspaces at z-index 0; inner targets
+                // subdivide the remaining client rectangle when a navigator/workspace occupies the center.
                 Rectangle screenRect = Control.RectangleToScreen(Control.ClientRectangle);
                 var rectsDraw = SubdivideRectangle(screenRect, 3, int.MaxValue);
                 var rectsHot = SubdivideRectangle(screenRect, 10, 20);
@@ -392,7 +395,7 @@ private void OnControlSizeChanged(object? sender, EventArgs e)
 
     private void EnforceInnerMinimum()
     {
-        // Find the available inner rectangle of our containing control
+        // Shrink edge dockspaces greedily when docked panels consume more than InnerMinimum allows.
         Rectangle innerRect = DockingHelper.InnerRectangle(Control);
 
         // Do we need to adjust the left/right edge controls?
@@ -487,7 +490,7 @@ private static Rectangle[] SubdivideRectangle(Rectangle area,
     {
         var length = Math.Min(area.Width / divisor, Math.Min(area.Height / divisor, maxLength));
 
-        // Find the left, right, top, bottom, center rectangles
+        // Index 0-3: edge bands; index 4: center (unused for outer-edge targets).
         return new Rectangle[]{
             new Rectangle(area.X, area.Y, length, area.Height),
             new Rectangle(area.Right - length, area.Y, length, area.Height),

@@ -13,7 +13,8 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Provides docking functionality within a control edge using a KryptonDockspace.
+/// Docked host on a control edge. Raises <see cref="HasVisibleCells"/> / <see cref="HasNoVisibleCells"/>
+/// when the last visible page in all cells disappears so the dockspace control can hide itself.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]

@@ -13,7 +13,9 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Provides docking functionality for a specific edge of a control.
+/// One physical edge of a host control. Always owns paired <see cref="KryptonDockingEdgeAutoHidden"/>
+/// and <see cref="KryptonDockingEdgeDocked"/> children so pin/unpin can move pages between slide tabs
+/// and visible dockspaces on the same side.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]

@@ -13,7 +13,9 @@
 namespace Krypton.Docking;
 
 /// <summary>
-/// Provides auto hidden docking functionality against a specific control edge.
+/// Auto-hidden edge element: owns the tab strip (<see cref="KryptonAutoHiddenPanel"/>) and the
+/// slide-out panel that hosts the active group's dockspace. Hides the slide panel before store/remove
+/// propagate actions so layout changes do not flash over an open slide.
 /// </summary>
 [ToolboxItem(false)]
 [DesignerCategory("code")]
@@ -127,7 +129,7 @@ public override void PropogateAction(DockingPropogateAction action, string[]? un
             case DockingPropogateAction.RemovePages:
             case DockingPropogateAction.RemoveAndDisposePages:
             case DockingPropogateAction.StorePages:
-                // Ask the sliding panel to remove its display if an incoming name matches
+                // Dismiss an open slide before the page is stored or removed from the group.
                 if (uniqueNames != null)
                 {
                     foreach (var uniqueName in uniqueNames)