Improve capture workflow and generated layout file guidance

stenci · stenci · commit 711bf6c8035c · 2026-03-20T12:18:08.000-05:00
diff --git a/README.md b/README.md
@@ -44,13 +44,13 @@ When `WindowLayout\window_layouts.txt` is reformatted, the script also regenerat
 - `Portable`: runs directly from a folder such as the desktop
 - `Monitor setups`: separate physical monitor arrangements from window layouts
 - `Relative monitor matching`: matches the current monitors to a saved setup by relative position, not Windows numbering
-- `Capture workflow`: saves the current layout to `current_layout.txt`, which you can trim and copy into `window_layouts.txt`
+- `Capture workflow`: saves the current layout to `current_layout.txt` with a timestamped comment header, and you can trim and copy parts into `window_layouts.txt`
 - `Readable config`: uses a pipe-delimited text format instead of JSON
 - `Regex titles`: supports `regex` title matching, including `|` inside regex patterns
 - `Cascade support`: capture emits both a cascade row and individual rows for multi-instance apps
 - `Virtual desktops`: captures and restores a manually editable desktop number for each window
 - `Editable percentages`: capture writes integer `x`, `y`, `w`, and `h` values, but you can manually change them to decimals for finer positioning
-- `Ignore list`: processes without a valid desktop number are written to `processes_to_ignore.txt` and excluded from future captures and restores
+- `Ignore list`: processes whose captured windows never resolve to a valid desktop number are written to `processes_to_ignore.txt` and excluded from future captures and restores
 
 ## Folder Layout
 
@@ -63,11 +63,11 @@ WindowLayout/
   readme.txt
 ```
 
-`window_layouts.txt` is created on first run.
+`window_layouts.txt` is created on first run with a comment header and a blank line before the content.
 
 Per-layout `.cmd` shortcut scripts inside `WindowLayout\` are generated from `window_layouts.txt` when it is reformatted.
 
-`current_layout.txt` is generated only when you capture a layout.
+`current_layout.txt` is generated only when you capture a layout. It includes a timestamped comment header and a blank line before the captured content.
 
 `processes_to_ignore.txt` is updated automatically when capture finds processes without a valid desktop number.
 
@@ -79,7 +79,9 @@ Per-layout `.cmd` shortcut scripts inside `WindowLayout\` are generated from `wi
 4. Choose a saved layout, or capture the current layout.
 5. After capture, copy the parts you want from `current_layout.txt` into `window_layouts.txt`.
 
-Capture usually sees more windows than you want to keep, including helper windows and some windows that are not obvious at first glance. Processes without a valid desktop number are not written to `current_layout.txt`; instead, their process names are added to `WindowLayout\processes_to_ignore.txt`.
+When you create a new monitor setup, capture first lists the detected monitors, then asks you to name each monitor, then asks for the monitor configuration name.
+
+Capture usually sees more windows than you want to keep, including helper windows and some windows that are not obvious at first glance. Individual windows without a valid desktop number are not written to `current_layout.txt`; if all captured windows for a process lack a valid desktop number, that process name is added to `WindowLayout\processes_to_ignore.txt`.
 
 ## Configuration Model
 
@@ -144,7 +146,8 @@ That shows a useful pattern:
 ## Capture Notes
 
 - Capture learns ignored processes automatically and stores them in `WindowLayout\processes_to_ignore.txt`
-- Processes without a valid desktop number are blacklisted and omitted from `current_layout.txt`
+- Individual windows without a valid desktop number are omitted from `current_layout.txt`
+- If all captured windows for a process have no valid desktop number, that process is blacklisted
 - `WindowLayout.cmd -CaptureCurrent -IgnoreBlacklist` captures the full visible window list for troubleshooting, including blacklisted processes and windows without a usable desktop number
 - Capture still writes integer percentages, but manual decimal edits in `window_layouts.txt` are preserved when the file is reformatted
 
diff --git a/WindowLayout/WindowLayout.ps1 b/WindowLayout/WindowLayout.ps1
@@ -320,6 +320,38 @@ function New-DefaultConfig {
     }
 }
 
+function Get-ConfigFileHeader {
+    return @(
+        '# These layouts are used by the script.',
+        '# Edit this file to control which window layouts can be applied.',
+        '',
+        ''
+    ) -join [Environment]::NewLine
+}
+
+function Get-CapturedLayoutHeader {
+    $capturedAt = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
+    return @(
+        ('# This window layout was captured at {0}.' -f $capturedAt),
+        '# Copy all or part of this file into window_layouts.txt if you want to save it.',
+        '# These captured layouts are not used by the script.',
+        '',
+        ''
+    ) -join [Environment]::NewLine
+}
+
+function ConvertTo-ConfigFileText {
+    param([Parameter(Mandatory = $true)]$Config)
+
+    return (Get-ConfigFileHeader) + (ConvertTo-ConfigText -Config $Config)
+}
+
+function ConvertTo-CapturedLayoutFileText {
+    param([Parameter(Mandatory = $true)]$Config)
+
+    return (Get-CapturedLayoutHeader) + (ConvertTo-ConfigText -Config $Config)
+}
+
 function Add-PendingMessage {
     param([Parameter(Mandatory = $true)][string]$Message)
 
@@ -470,7 +502,7 @@ function Show-MenuHeader {
 
 function Ensure-ConfigFile {
     if (-not (Test-Path -LiteralPath $script:ConfigPath)) {
-        [System.IO.File]::WriteAllText($script:ConfigPath, '', (New-Object System.Text.UTF8Encoding($true)))
+        [System.IO.File]::WriteAllText($script:ConfigPath, (Get-ConfigFileHeader), (New-Object System.Text.UTF8Encoding($true)))
     }
 }
 
@@ -1065,7 +1097,7 @@ function Get-Config {
     $raw = Get-Content -LiteralPath $script:ConfigPath -Raw -Encoding UTF8
     $config = ConvertTo-ConfigFromText -Text $raw
     Validate-Config -Config $config
-    $wasReformatted = Write-FormattedConfigIfNeeded -Path $script:ConfigPath -FormattedText (ConvertTo-ConfigText -Config $config)
+    $wasReformatted = Write-FormattedConfigIfNeeded -Path $script:ConfigPath -FormattedText (ConvertTo-ConfigFileText -Config $config)
     if ($wasReformatted) {
         [void](Sync-LayoutShortcutScripts -Config $config)
         Add-PendingMessage -Message "Reformatted and saved '$script:ConfigPath'."
@@ -1722,35 +1754,78 @@ function Get-SizePercent {
     return [int]$percent
 }
 
-function New-RoleFromCoordinates {
-    param(
-        [int]$X,
-        [int]$Y
-    )
+function Get-MonitorLetterLabel {
+    param([Parameter(Mandatory = $true)][int]$Index)
 
-    return "x$X`_y$Y"
+    if ($Index -lt 1) {
+        throw 'Monitor index must be at least 1.'
+    }
+
+    $value = $Index
+    $label = ''
+    while ($value -gt 0) {
+        $remainder = ($value - 1) % 26
+        $label = ([char]([int][char]'A' + $remainder)) + $label
+        $value = [int](($value - 1) / 26)
+    }
+
+    return $label
 }
 
-function New-MonitorSetupFromCurrentMonitors {
-    param(
-        [Parameter(Mandatory = $true)][string]$Name,
-        [Parameter(Mandatory = $true)]$ActualMonitors
-    )
+function Read-RequiredText {
+    param([Parameter(Mandatory = $true)][string]$Prompt)
 
-    $monitors = foreach ($monitor in $ActualMonitors) {
-        [pscustomobject]@{
-            role = New-RoleFromCoordinates -X $monitor.X -Y $monitor.Y
+    while ($true) {
+        Write-Host ''
+        $value = Read-Host $Prompt
+        Write-Host ''
+        if (-not [string]::IsNullOrWhiteSpace($value)) {
+            return $value.Trim()
+        }
+
+        Write-Host 'Please enter a value.'
+    }
+}
+
+function New-MonitorSetupInteractively {
+    param([Parameter(Mandatory = $true)]$ActualMonitors)
+
+    Write-Host ('Found {0} monitors:' -f $ActualMonitors.Count)
+    for ($i = 0; $i -lt $ActualMonitors.Count; $i++) {
+        $monitor = $ActualMonitors[$i]
+        $label = Get-MonitorLetterLabel -Index ($i + 1)
+
+        Write-Host ('Monitor {0}: {1} x {2} at {3},{4}' -f $label, $monitor.Width, $monitor.Height, $monitor.X, $monitor.Y)
+    }
+
+    $monitors = @()
+    for ($i = 0; $i -lt $ActualMonitors.Count; $i++) {
+        $monitor = $ActualMonitors[$i]
+        $label = Get-MonitorLetterLabel -Index ($i + 1)
+        $role = Read-RequiredText -Prompt ('Please enter name for monitor {0} (example "Main", "Left", "Wide screen", etc.)' -f $label)
+        $monitors += [pscustomobject]@{
+            role = $role
             x    = $monitor.X
             y    = $monitor.Y
         }
     }
 
+    $name = Read-RequiredText -Prompt 'Please enter name for monitor configuration (example "Main", "Office", etc.)'
+
     return [pscustomobject]@{
-        name     = $Name
+        name     = $name
         monitors = @($monitors)
     }
 }
 
+function New-MonitorSetupFromCurrentMonitors {
+    param(
+        [Parameter(Mandatory = $true)]$ActualMonitors
+    )
+
+    return New-MonitorSetupInteractively -ActualMonitors $ActualMonitors
+}
+
 function Read-ChoiceNumber {
     param(
         [Parameter(Mandatory = $true)][string]$Prompt,
@@ -1761,7 +1836,9 @@ function Read-ChoiceNumber {
     )
 
     while ($true) {
+        Write-Host ''
         $choice = Read-Host $Prompt
+        Write-Host ''
         if ($AllowBlank -and [string]::IsNullOrWhiteSpace($choice)) {
             return $BlankValue
         }
@@ -1780,13 +1857,8 @@ function Select-MonitorSetupForCapture {
 
     $actualMonitors = @(Get-ActualMonitors)
     if ($Config.monitorSetups.Count -eq 0) {
-        $name = Read-Host "No monitor setups exist yet. Enter a name for the new monitor setup"
-        if ([string]::IsNullOrWhiteSpace($name)) {
-            $name = 'Current setup'
-        }
-
         return [pscustomobject]@{
-            setup = New-MonitorSetupFromCurrentMonitors -Name $name -ActualMonitors $actualMonitors
+            setup = New-MonitorSetupFromCurrentMonitors -ActualMonitors $actualMonitors
             isNew = $true
         }
     }
@@ -1797,21 +1869,16 @@ function Select-MonitorSetupForCapture {
         Write-Host ("{0}. {1}" -f $index, $setup.name)
         $index++
     }
-    Write-Host ("{0}. create new monitor setup" -f $index)
+    Write-Host ("{0}. Create new monitor setup" -f $index)
 
     $selection = Read-ChoiceNumber -Prompt 'Choose an option' -Minimum 1 -Maximum $index -AllowBlank -BlankValue 0
     if ($selection -eq 0) {
         return $null
     }
 
     if ($selection -eq $index) {
-        $name = Read-Host 'Enter the new monitor setup name'
-        if ([string]::IsNullOrWhiteSpace($name)) {
-            $name = 'Current setup'
-        }
-
         return [pscustomobject]@{
-            setup = New-MonitorSetupFromCurrentMonitors -Name $name -ActualMonitors $actualMonitors
+            setup = New-MonitorSetupFromCurrentMonitors -ActualMonitors $actualMonitors
             isNew = $true
         }
     }
@@ -1889,23 +1956,40 @@ function Capture-CurrentLayout {
         }
     }
 
+    $rowsWithBlankDesktop = @(
+        $capturedRows | Where-Object {
+            $processKey = $_.processName.ToLowerInvariant()
+            (-not $protectedProcesses.ContainsKey($processKey)) -and $null -eq $_.desktop
+        }
+    )
+
     $processesWithBlankDesktop = @(
-        $capturedRows |
+        $rowsWithBlankDesktop |
             Group-Object -Property processName |
             Where-Object {
                 $processName = [string]$_.Name
                 $processKey = $processName.ToLowerInvariant()
-                $hasDesktop = @($_.Group | Where-Object { $null -ne $_.desktop }).Count -gt 0
+                $hasDesktop = @($capturedRows | Where-Object {
+                    $_.processName -eq $processName -and $null -ne $_.desktop
+                }).Count -gt 0
                 (-not $protectedProcesses.ContainsKey($processKey)) -and (-not $hasDesktop)
             } |
             ForEach-Object { $_.Name } |
             Sort-Object -Unique
     )
 
-    if (-not $IgnoreBlacklist -and $processesWithBlankDesktop.Count -gt 0) {
-        [void](Add-IgnoredProcesses -ProcessNames $processesWithBlankDesktop)
-        $capturedRows = @($capturedRows | Where-Object { $processesWithBlankDesktop -notcontains $_.processName })
-        Add-PendingMessage ("Ignored processes with no usable desktop: {0}" -f ($processesWithBlankDesktop -join ', '))
+    if (-not $IgnoreBlacklist -and $rowsWithBlankDesktop.Count -gt 0) {
+        if ($processesWithBlankDesktop.Count -gt 0) {
+            [void](Add-IgnoredProcesses -ProcessNames $processesWithBlankDesktop)
+            Add-PendingMessage ("Ignored processes with no usable desktop: {0}" -f ($processesWithBlankDesktop -join ', '))
+        }
+
+        $capturedRows = @($capturedRows | Where-Object {
+            $processKey = $_.processName.ToLowerInvariant()
+            $protectedProcesses.ContainsKey($processKey) -or $null -ne $_.desktop
+        })
+
+        Add-PendingMessage ("Skipped {0} captured window(s) with no usable desktop number." -f $rowsWithBlankDesktop.Count)
     }
     elseif ($IgnoreBlacklist) {
         Add-PendingMessage 'Capture ignored processes blacklist and kept windows even when their desktop number was unavailable.'
@@ -1953,7 +2037,7 @@ function Save-CapturedLayout {
         [Parameter(Mandatory = $true)]$Config
     )
 
-    $text = ConvertTo-ConfigText -Config $Config
+    $text = ConvertTo-CapturedLayoutFileText -Config $Config
     Set-Content -LiteralPath $script:CurrentLayoutPath -Value $text -Encoding UTF8
 }
 
@@ -1971,15 +2055,14 @@ function Show-Menu {
         foreach ($layout in $Config.layouts) {
             $label = "$($layout.monitorSetup) - $($layout.name)"
             $options += [pscustomobject]@{ Number = $index; Action = 'apply'; Layout = $layout; Label = $label }
-            Write-Host ("{0}. set window layout '{1}'" -f $index, $label)
+            Write-Host ("{0}. Set window layout '{1}'" -f $index, $label)
             $index++
         }
 
         $captureNumber = $index
         $options += [pscustomobject]@{ Number = $captureNumber; Action = 'capture' }
-        Write-Host ("{0}. get current window layout" -f $captureNumber)
-        Write-Host '0. exit'
-        Write-Host ''
+        Write-Host ("{0}. Get current window layout" -f $captureNumber)
+        Write-Host '0. Exit'
 
         $choice = Read-ChoiceNumber -Prompt 'Choose an option' -Minimum 0 -Maximum $captureNumber -AllowBlank -BlankValue 0
         if ($choice -eq 0) {
diff --git a/WindowLayout/readme.txt b/WindowLayout/readme.txt
@@ -11,9 +11,9 @@ Why this is useful
 Files
 - WindowLayout.cmd must stay next to the WindowLayout folder.
 - WindowLayout\WindowLayout.ps1 is the main script.
-- WindowLayout\window_layouts.txt is the editable layouts file. It is created automatically on first run.
+- WindowLayout\window_layouts.txt is the editable layouts file. It is created automatically on first run with a comment header and a blank line before the content.
 - WindowLayout\WindowLayout - <monitor setup> - <layout>.cmd files are generated from window_layouts.txt when that file is reformatted.
-- WindowLayout\current_layout.txt is generated only when you capture the current layout.
+- WindowLayout\current_layout.txt is generated only when you capture the current layout. It includes a comment header with the capture date and time, followed by a blank line.
 - WindowLayout\processes_to_ignore.txt is maintained automatically for processes without a valid desktop number.
 
 Setup examples:
@@ -27,11 +27,14 @@ How to use it
 1. Double-click WindowLayout.cmd.
 2. Choose a layout from the menu in the form "monitor setup - layout".
 3. Or choose to capture the current layout.
-4. During capture, choose which monitor setup to map the current monitors to.
-5. After capture, open current_layout.txt, copy the monitor setup or layout you want into window_layouts.txt, and remove the rows you do not need.
-6. Capture usually includes more windows than you want, including helper windows and some windows that are not obvious at first glance.
-7. Processes without a valid desktop number are added to processes_to_ignore.txt instead of being written to current_layout.txt.
-8. For troubleshooting, run WindowLayout.cmd -CaptureCurrent -IgnoreBlacklist to capture the full visible window list, including blacklisted processes and windows with no usable desktop number.
+4. During capture, choose which monitor setup to map the current monitors to, or create a new one.
+5. When creating a new monitor setup, capture first lists all detected monitors, then asks you to name each monitor, then asks for the monitor configuration name.
+6. After capture, open current_layout.txt, copy the monitor setup or layout you want into window_layouts.txt, and remove the rows you do not need.
+7. current_layout.txt is only a captured snapshot and is not used by the script unless you copy parts of it into window_layouts.txt.
+8. Capture usually includes more windows than you want, including helper windows and some windows that are not obvious at first glance.
+9. Individual windows without a valid desktop number are skipped in current_layout.txt.
+10. If all captured windows for a process have no valid desktop number, that process is added to processes_to_ignore.txt.
+11. For troubleshooting, run WindowLayout.cmd -CaptureCurrent -IgnoreBlacklist to capture the full visible window list, including blacklisted processes and windows with no usable desktop number.
 
 Direct shortcut script
 - You can also run a layout directly from the command line:
@@ -100,11 +103,12 @@ Monitor setups
 - The script matches the currently connected monitors to the selected monitor setup by relative monitor positions, not by Windows monitor numbering.
 
 Capture behavior
-- If the config has no monitor setups yet, capture asks for a name and creates the first monitor setup from the current monitors.
-- If monitor setups already exist, capture asks which setup to use, or lets you create a new one.
+- If the config has no monitor setups yet, capture lists the detected monitors, asks you to name each monitor, then asks for the monitor configuration name.
+- If monitor setups already exist, capture asks which setup to use, or lets you create a new one with the same interactive naming flow.
 - The monitor match is tolerant: it does not require a perfect coordinate or size match.
 - Capture records the virtual desktop number for each included window.
-- Processes without a valid desktop number are added to processes_to_ignore.txt and left out of current_layout.txt.
+- Individual windows without a valid desktop number are left out of current_layout.txt.
+- If all captured windows for a process have no valid desktop number, that process is added to processes_to_ignore.txt.
 - Running WindowLayout.cmd -CaptureCurrent -IgnoreBlacklist bypasses that filter and keeps those rows in current_layout.txt with a blank desktop column.
 - For multi-instance applications, capture emits both:
   - one cascade row with an empty title
@@ -126,7 +130,7 @@ Menu behavior
 
 Restart from scratch
 - Delete WindowLayout\window_layouts.txt and WindowLayout\current_layout.txt.
-- On the next run, the script recreates a fresh empty window_layouts.txt.
+- On the next run, the script recreates window_layouts.txt with its comment header and blank line.
 
 Command line examples
 - WindowLayout.cmd
