README

Sucrose Wiki — Publishing Guide (Maintainer Only)

This file is NOT a wiki page. It is an internal guide for the maintainer who publishes the contents of this wiki/ folder to the Sucrose GitHub Wiki. Do NOT copy README.md into the wiki clone — copy every other .md file.

This folder holds the source Markdown for the Sucrose GitHub Wiki. GitHub serves a repository's wiki from a separate Git repository (<repo>.wiki.git), so publishing is a copy-and-push operation, not a normal repo commit.

---

How to publish

1. Enable the wiki on GitHub. In the Sucrose repository: Settings → Features → Wikis (check the box). Then open the Wiki tab once and create the first page (any content) so GitHub initializes the backing wiki repository. This only has to be done once.

2. Clone the wiki repository (note the .wiki.git suffix — it is a different repo from the code):

   git clone https://github.com/Taiizor/Sucrose.wiki.git

3. Copy every .md from this wiki/ folder into the clone, EXCEPT this README.md.

   PowerShell:

   $src = "E:\MyProject\Sucrose\Pro\Sucrose\wiki"
   $dst = "<path-to>\Sucrose.wiki"
   Get-ChildItem -Path $src -Filter *.md |
       Where-Object { $_.Name -ne 'README.md' } |
       Copy-Item -Destination $dst -Force

   bash:

   cd <path-to>/Sucrose.wiki
   find <path-to-repo>/wiki -maxdepth 1 -name '*.md' ! -name 'README.md' -exec cp {} . \;

4. Commit and push:

   cd <path-to>/Sucrose.wiki
   git add -A
   git commit -m "Publish Sucrose wiki"
   git push origin master   # the wiki default branch is usually 'master'

   The pages go live immediately on the repository's Wiki tab.

GitHub-wiki special files

Three files are treated specially by GitHub Wikis — keep their exact names:

File	Role
Home.md	The wiki landing page (the tab's default page).
_Sidebar.md	Renders as the navigation sidebar on every page.
_Footer.md	Renders as the footer on every page.

All other *.md files become pages named after the file (e.g. Type-Web.md → the Type-Web page). Internal links use the page name without the extension, e.g. [Type-Web](Type-Web).

Counts. This folder contains 91 .md files. Excluding this README.md, 90 files publish: the 3 GitHub-wiki special files (Home.md, _Sidebar.md, _Footer.md) plus 87 content pages.

---

Asset placeholder checklist

The content pages contain 72 image placeholders (📷 screenshot / 🖼️ diagram) marked with > 📷 **Screenshot needed:** or > 🖼️ **Diagram needed:** blockquotes. Before (or after) publishing, capture/produce each asset, add it to the wiki, and replace the placeholder blockquote with the image. Grouped by page:

Architecture-Overview.md

• Architecture-Overview.md: Diagram — a "who-spawns-whom" map: Launcher (entry point) at the root, branching through Commandog to Portal, the live engine, Backgroundog, Reportdog, Update, Property, Watchdog, and Undo.

Automation-Examples.md

• Automation-Examples.md: Screenshot — the Sucrose.Commandog.exe console output after running ✔Test✖true✖42✖hello, showing the Test Values: line and the three parsed values.

Backgroundog-Service.md

• Backgroundog-Service.md: Diagram — Backgroundog lifecycle (on-demand launch via Commandog → single-instance gate → Initialize loop with Specification + Performance/Condition/Attempt → self-exit when no live wallpaper).
• Backgroundog-Service.md: Diagram — Backgroundog data pump (Specification.Start() builds the 10-JObject payload → branches on PipeRequired/SignalRequired/TransmissionRequired → WebView/CefSharp Web.cs server → JS bridge ExecuteScriptAsync).

Backup-Restore-Reset.md

• Backup-Restore-Reset.md: Screenshot — Portal → Settings → System page showing the Export / Import / Reset buttons and the clear-cache/store/log actions with their live size hints.

Bundle-Installer-Internals.md

• Bundle-Installer-Internals.md: Diagram — the single Sucrose.Bundle.exe with its embedded resources (Packages\Sucrose.7z, SevenZip\7z.exe, Checksum\Hashes.json, Checksum\Template.html, Showcase\**) extracting to %TEMP%, %LocalAppData%\Sucrose, and %AppData%\Sucrose\Showcase.

Cache-Management.md

• Cache-Management.md: Screenshot — Portal → Settings → System showing the Clear Cache / Clear Store actions with their live size hints.

Choosing-Engines.md

• Choosing-Engines.md: Diagram — a type → engine mapping diagram (six type boxes on the left, seven engine boxes on the right, arrows showing which engines each type can use, defaults highlighted).
• Choosing-Engines.md: Screenshot — Portal → Settings → Wallpaper page showing the per-type engine selector ComboBoxes (Gif/Video/Url/Web/YouTube/Application Player).

Command-Reference.md

• Command-Reference.md: Diagram — command flow (emitter builds a ✔Command✖value string → spawns Sucrose.Commandog.exe → parse → switch dispatch to Processor.Run/Processor.Kill or a shared helper → target .exe launches).

Crash-Reporting.md

• Crash-Reporting.md: Diagram — crash flow (process throws → Watch.* logs locally → Watchdog.Start builds Base64(app✖exception✖show✖log) → Commandog spawns Watchdog.exe → Report/.json written + faulting process killed + optional dialog → Reportdog uploads later).
• Crash-Reporting.md: Screenshot — Watchdog crash dialog (dark theme) showing the exception message and the log/source/help fields.

Create-Customization-Controls.md

• Create-Customization-Controls.md: Screenshot — the Portal "Customize" panel for a Web wallpaper showing a slider, a dropdown, a color picker, and a checkbox grouped under section labels.

Create-Example-Wallpapers.md

• Create-Example-Wallpapers.md: Screenshot — the Portal Library showing the shipped Showcase wallpapers (Neo Matrix, Fluid Simulation, Simple System, Music Tunnel, Living Room, Ray Music Visualizer).

Create-Overview.md

• Create-Overview.md: Diagram — a wallpaper folder shown as a box containing SucroseInfo.json (required, highlighted) plus the optional siblings and source media files.
• Create-Overview.md: Screenshot — a wallpaper folder open in File Explorer showing SucroseInfo.json, SucroseProperties.json, an HTML source file, and thumbnail/preview images.

Create-Package-Format.md

• Create-Package-Format.md: Diagram — annotated folder tree mapping each file to the manifest field that references it (Thumbnail → Thumbnail, Preview → Preview, source file → Source, License.txt → License).

Create-Step-By-Step.md

• Create-Step-By-Step.md: Screenshot — the Portal "Create Theme" dialog showing the Title/Description/Author/Contact fields, tag chips, thumbnail/preview pickers, and the type-specific Source input.

Create-Web-Architecture.md

• Create-Web-Architecture.md: Diagram — sequence diagram (Backgroundog timer → build bundle → transport Pipe/Signal/Transmission → engine handler → ExecuteScriptAsync → page callbacks; with side branches for property push at init + change and raw-input forwarding).

Customizing-Wallpaper.md

• Customizing-Wallpaper.md: Screenshot — the Customize / Property editor window for a video wallpaper (MpvPlayer panel).
• Customizing-Wallpaper.md: Screenshot — the Customize / Property editor window for a web/browser wallpaper showing the filter sliders.

Data-Locations.md

• Data-Locations.md: Screenshot — Windows File Explorer at %AppData%\Sucrose with the Setting, Log, Cache, Library, and Showcase folders expanded one level.

Discord-Rich-Presence.md

• Discord-Rich-Presence.md: Screenshot — a Discord profile card showing the Sucrose Rich Presence with its state text, images, and the Browse / Download buttons.
• Discord-Rich-Presence.md: Screenshot — Portal → Settings → Other page showing the Discord Hook, Discord refresh, and Discord delay controls.

Engine-Aurora.md

• Engine-Aurora.md: Screenshot — an Application wallpaper running via Aurora across two monitors (e.g. a game or screensaver embedded behind the desktop icons).

Engine-Comparison.md

• Engine-Comparison.md: Diagram — a matrix/grid graphic mapping the six wallpaper types (rows) to the seven engines (columns), with cells marked "default" or "available".

Engines-Overview.md

• Engines-Overview.md: Diagram — Type → engine → process flow (a wallpaper's SucroseInfo.json Type feeds Run.cs, which resolves an engine setting and asks Commandog to launch Sucrose.Live.<Name>.exe, which then attaches to the desktop).
• Engines-Overview.md: Screenshot — Portal → Settings → Wallpaper page showing the per-type engine selectors (GifPlayer / VideoPlayer / UrlPlayer / WebPlayer / YouTubePlayer / ApplicationPlayer).

Extending-Sucrose.md

• Extending-Sucrose.md: Diagram — setting data-flow (Portal control → ViewModel → Manager.Manage.<Area> accessor → SettingManager → JSON file in %AppData%\Sucrose\Setting).

Getting-Help.md

• Getting-Help.md: Screenshot — Portal → About dialog showing the version, framework, and architecture fields to include in a bug report.

Installation.md

• Installation.md: Screenshot — the Sucrose listing on the Microsoft Store (apps.microsoft.com) showing the Get/Install button.
• Installation.md: Screenshot — the GitHub Releases asset table for the latest Sucrose tag, showing the three per-architecture .exe files.

IPC.md

• IPC.md: Diagram — Producer (Backgroundog) → one of {Pipe, Signal, Transmission} → Consumer (WebView/CefSharp engine) → ExecuteScriptAsync → JavaScript in the wallpaper page; plus the tray-control side channel (Portal/Backgroundog → Signal → Launcher → TrayIconManager).

Lifecycle.md

• Lifecycle.md: Diagram — a timeline/sequence diagram of the cold start (Launcher OnStartup → Instance.Basic → Configure() → TrayIconManager.Start() with engine auto-restore, Reportdog, update check → signal channel → Discord).

Logs-Diagnostics.md

• Logs-Diagnostics.md: Screenshot — Portal → Settings → System showing the log create/delete action used to produce the compressed log bundle.

Managing-Library.md

• Managing-Library.md: Screenshot — Portal → Library page showing a grid of installed wallpaper cards.
• Managing-Library.md: Screenshot — LibraryCard right-click context menu open over a wallpaper.

Multi-Monitor.md

• Multi-Monitor.md: Screenshot — the Display Preferences dialog showing the Screen/Expand/Duplicate radio group and the clickable monitor tiles.

Performance-Rules.md

• Performance-Rules.md: Diagram — state machine showing Resume → (condition trips) → Pause or Close → (condition clears) → Resume, with Backgroundog evaluating conditions each tick.

Portal-Interface-Tour.md

• Portal-Interface-Tour.md: Screenshot — the Portal main window with the top navigation, a populated Library, and the footer toolbar visible.

Property-Service.md

• Property-Service.md: Screenshot — the Property (Customize) window showing a mix of slider, dropdown, checkbox, and color-picker controls for a wallpaper.

Publish-Pipeline.md

• Publish-Pipeline.md: Diagram — flow from .build/Sucrose.ps1 → publish 17 projects → install + trim Sucrose.Runtime → compress to Sucrose-<arch>.7z → consumed by Sucrose.Bundle → renamed installer .exe.

Quick-Start.md

• Quick-Start.md: Screenshot — the Portal main window on the Library page right after first launch, showing the auto-imported Showcase wallpapers.

Repository-Layout.md

• Repository-Layout.md: Diagram — a tree of the src/ folder annotated with the logical layer each folder maps to.

Settings-General.md

• Settings-General.md: Screenshot — Portal → Settings → General page showing the Appearance & Behavior, Sound, and Library cards.

Settings-Other.md

• Settings-Other.md: Screenshot — Portal → Settings → Other page showing the Data, Discord, Update, and Developer cards.

Settings-Overview.md

• Settings-Overview.md: Screenshot — %AppData%\Sucrose\Setting\ folder open in File Explorer showing the individual *.json files.

Settings-Performance.md

• Settings-Performance.md: Screenshot — Portal → Settings → Performance page showing the per-condition Close/Pause/Resume combo boxes and the threshold number boxes.

Settings-Persistence.md

• Settings-Persistence.md: Diagram — settings read/write flow (Manage.* accessor → SettingManager with freshness check / in-memory copy → mutex-guarded Reader/Writer → %AppData%\Sucrose\Setting\<Category>.json).

Settings-Personal.md

• Settings-Personal.md: Screenshot — Portal → Settings → Personal page showing the Store, Library, and Appearance cards.

Settings-System.md

• Settings-System.md: Screenshot — Portal → Settings → System page showing the action cards with their live folder-size hints.

Settings-Wallpaper.md

• Settings-Wallpaper.md: Screenshot — Portal → Settings → Wallpaper page showing the per-type engine selectors and global toggles.

Shared-Item-Projects.md

• Shared-Item-Projects.md: Diagram — a shared project's .shproj/.projitems pair on the left, arrows to several consuming .csproj files, each compiling the shared .cs files into its own executable with a different preprocessor symbol.

Theme-Tray-Startup.md

• Theme-Tray-Startup.md: Screenshot — Portal footer toolbar with the light/dark theme toggle button highlighted.
• Theme-Tray-Startup.md: Screenshot — the Sucrose system-tray icon with its context menu expanded.
• Theme-Tray-Startup.md: Screenshot — Portal → Settings → General page showing the Application Startup, Notify Icon visibility, and Notify → Exit on close controls.

Troubleshooting-Common.md

• Troubleshooting-Common.md: Screenshot — Portal → Settings → Wallpaper page showing the per-type engine selectors (used to switch engines while troubleshooting).

Troubleshooting-Settings-Startup-GPU.md

• Troubleshooting-Settings-Startup-GPU.md: Diagram — where Sucrose state lives (JSON settings files in %AppData%\Sucrose\Setting, the Task Scheduler "Autorun for Sucrose" task, and the Windows UserGpuPreferences registry key) and which control surface writes each.

Type-Application.md

• Type-Application.md: Diagram — Aurora launching one app instance per monitor and reparenting each window behind the desktop icons.

Type-Gif.md

• Type-Gif.md: Screenshot — the Customize panel for a GIF wallpaper showing the MpvPlayer property sliders.

Type-Url.md

• Type-Url.md: Screenshot — a URL wallpaper showing a live external page on the desktop.

Type-Video.md

• Type-Video.md: Screenshot — the Customize panel for a Video wallpaper rendered by MpvPlayer.

Type-Web.md

• Type-Web.md: Diagram — sequence diagram (apply Web wallpaper → engine starts local HTTP server → Backgroundog pumps audio/system data over pipe → engine ExecuteScriptAsync into the page's Sucrose* callbacks).

Type-YouTube.md

• Type-YouTube.md: Screenshot — the Customize panel for a YouTube wallpaper showing the caption and playbackRate controls.

Undo-Internals.md

• Undo-Internals.md: Screenshot — the Sucrose Undo Yes/No/Cancel uninstall confirmation dialog.
• Undo-Internals.md: Diagram — Undo removal sequence (confirm dialog → kill all Sucrose processes in 3 passes → restore desktop → delete install keeping Undo/Runtime → optional data delete → remove shortcuts + registry key → spawn del_.bat → self-delete).

Uninstalling-Sucrose.md

• Uninstalling-Sucrose.md: Screenshot — Windows "Installed apps" list with the Sucrose Wallpaper Engine entry and its Uninstall option.

Update-Internals.md

• Update-Internals.md: Diagram — the update step pipeline flowchart (Cache → Network → Releases → Release → Comparing → Searching → (Silent) → Downloading → Extracting/Running, with the abort-on-false branches).

Using-Store.md

• Using-Store.md: Screenshot — Portal → Store page (FullStorePage) with the category navigation on the left and a grid of wallpaper cards.
• Using-Store.md: Screenshot — a StoreCard mid-download showing the progress ring.

Wallpaper-Cycling.md

• Wallpaper-Cycling.md: Screenshot — the Wallpaper Cycling dialog showing the active toggle, transition-time number box, transition-type dropdown, and the reset-exclusion button.

Wallpaper-Types.md

• Wallpaper-Types.md: Diagram — a 6-box row of the wallpaper types (Gif, Url, Web, Video, YouTube, Application), each with a representative icon, fanning out to the engines that can render them.

Inline screenshot/preview references such as ../.screenshots/Preview.png and the per-type *.gif previews in Home.md and the Type-* pages point at existing repo assets and are not counted as placeholders above. On the GitHub Wiki those relative paths will not resolve — re-upload the images to the wiki (or use absolute raw URLs) when publishing.

---

Research source note

These pages were generated from the research documents in docs/wiki-research/. Those research files are an internal working source and can be deleted after the wiki is finalized.