Windows internals (verified 2026-10-27, Win11 26200 + StartAllBack 3.9)

Findings behind scripts/win/, for contributors. Read this before changing the pin, icon or desktop logic. For a plain-language overview, see How it works.

Where a taskbar button's icon comes from#

• Running app with an explicit AppUserModelID (Electron apps like T3 Code, VS Code): the icon of the Start Menu shortcut carrying that ID. Changing that shortcut's icon + SHChangeNotify(UPDATEITEM) updates the button live. Changing the pinned .lnk alone does nothing while the app runs. WM_SETICON on the window does nothing either.
• Pinned, not running / apps without an explicit ID: the pinned .lnk's icon, read when Explorer starts. Needs an Explorer restart (refresh) to show.
• Windows caches icons by file path → write each new look to a new file name (apply adds a style hash).

Pinning#

• IPinnedList3::Modify / LegacyModify (CLSID_TaskbandPin 90AA3A4E-…, IID 0DD79AE2-…) return S_OK but are silently ignored outside explorer.exe. Read methods (IsPinned, GetChangeCount) work.
• The "Pin to taskbar" verb only appears inside Explorer. Invoking it through Explorer's own Shell.Application (desktop view or a folder window) fails: DoIt → E_INVALIDARG, InvokeVerb → no-op.
• What works: write HKCU\…\Explorer\Taskband while Explorer is stopped, then start it.
  • Favorites = {0x00, u32 cb, PIDL}* 0xFF; FavoritesResolve = {u32 cb, .lnk bytes}*, same order.
  • PIDL = UserPinned known-folder item + TaskBar item (copied from an existing entry) + the file item.
  • The file item must carry three extra blocks, or Explorer keeps the entry but never shows it: BEEF001E 02 00+"UserPinned\0" (UTF-16), BEEF002B FILETIME, BEEF001D 02 00+AppID\0. Each block: cb u16, ver u16=0, sig u32, payload, u16 offset-of-first-block.
  • AppID = explicit ID if the shortcut has one, else the Get-StartApps AppID (e.g. {1AC14E77-…}\charmap.exe).
• Windows auto-restarts the shell after Stop-Process explorer. Writing right after the kill wins the race.

Side effects#

• Restarting Explorer twice within ~30 s trips TranslucentTB's failsafe (taskbar falls back to the accent color, from Explorer\Accent\AccentPalette). The script samples the taskbar color before/after and only flags a change from a custom color to a stock one, and only if a styling tool was running (without one, the accent shade can drift between restarts). Styling tools that died are relaunched. pins --restart-cooldown <s> (MCP: restartCooldown) spaces out restarts; pin, unpin, reorder and refresh take --cooldown <s>. Context changes (TranslucentTB going clear on the desktop) are normal and not flagged.
• MCP clients start servers with a trimmed environment (no ProgramData/WINDIR): resolve folders via [Environment]::GetFolderPath, never env vars.
• All-users Start Menu shortcuts (C:\ProgramData\…) need admin; reported as skipped.
• Console apps (PowerShell, cmd) run inside Windows Terminal when it's the default terminal, so their running button is Terminal's. Use a GUI app to test.

Safety around pin-list writes#

• Writers parse Favorites and FavoritesResolve strictly (Taskband.Strict): every record must parse, Favorites must end in a single 0xFF, and both lists must have the same length. Anything else throws instead of rewriting a list that was only partly understood.
• Invoke-WithExplorerStopped snapshots both values first. If the action throws, the snapshot is written back before Explorer restarts.
• Backups in %LOCALAPPDATA%\iconwright\backups\: original\ (once, before the first change) and last\ (before every change; written to pending\ and promoted only if the change succeeds). Each holds taskband.reg (reg export) and TaskBar\ (the pinned shortcuts). Older versions wrote taskband-<stamp>.reg + TaskBar-folder-<stamp>; restore-pins --from original still reads those.
• reg.exe prints its status to stderr, which PowerShell 5.1 turns into an error under $ErrorActionPreference = 'Stop'; Invoke-Reg runs it with Continue and checks the exit code.
• Mutating commands hold the named mutex Local\iconwright-change.
• After the restart, Wait-Taskbar polls for Shell_TrayWnd. Explorer is started by hand only if Windows didn't restart it within 8 s (a second explorer.exe would open a File Explorer window).
• state.json holds each changed item's original icon for restore / restore-all.

Taskbar order#

Pin order = entry order in Favorites (with FavoritesResolve kept in the same order). reorder rewrites both while Explorer is stopped (one restart). Verified: Explorer keeps the new order.

Desktop icons (all live, no restart)#

• Reached like the taskbar shell object: ShellWindows.FindWindowSW(SWC_DESKTOP) → IShellBrowser → QueryActiveShellView → IFolderView2. Works cross-process (COM marshals the PIDLs).
• Items: ItemCount/Item + SHGetNameFromIDList (desktop child PIDLs are absolute). Positions: GetItemPosition / SelectAndPositionItems(SVSI_POSITIONITEM); auto-arrange is turned off first. Positions are quantized to the icon grid (GetSpacing, e.g. 150×210 px at 200% scale) even with "align to grid" off.
• Size: SetViewModeAndIconSize(FVM_ICON, px). Flags: SetCurrentFolderFlags (FWF_AUTOARRANGE, FWF_SNAPTOGRID, FWF_NOICONS).
• Persist: explorer saves the desktop layout only on a clean exit, so we call IShellView::SaveViewState after changes and before every forced Explorer restart.
• Icons: .lnk → IconLocation; .url → IconFile/IconIndex; folders → desktop.ini IconResource (+ReadOnly on the folder, Hidden+System on the ini); system icons (This PC, Recycle Bin…) → HKCU\…\Explorer\CLSID\{clsid}\DefaultIcon (Recycle Bin also empty/full) + SHCNE_ASSOCCHANGED. Plain files can't have per-file icons (type-based).
• System icon visibility: HKCU\…\HideDesktopIcons\NewStartPanel\{clsid} = 1 hidden / 0 shown, then refresh the desktop view.
• Label text color isn't configurable (always white with shadow).