split-off! Update all model classes to Electron API 39.2

Author: softworkz

src/ElectronNET.API/API/Entities/EntitiesAuditInstructions.md

@@ -0,0 +1,238 @@
+# Electron.NET Entities Audit – MCP-Driven Instructions (Internal)
+
+> Internal instructions for Cline to restore the current reasoning state from zero.
+> Audience: the assistant only. Human readability is not required but acceptable.
+
+---
+
+## 1. Absolute Rules
+
+1. Electron API information **must come only** from the MCP server `docs-mcp-server`.
+2. The only relevant library in that server for this task is currently:
+   - `electronjs`
+3. Do **not** use:
+   - Your own remembered Electron knowledge.
+   - External web requests or documentation.
+   - Any assumption that is not traceable to the MCP results.
+4. For **every Entity class and every member** (property/field):
+   - Ensure **all members that exist in the Electron docs are present** in C#.
+   - Ensure C# **types** match the Electron semantics (including, but not limited to, numeric ones).
+   - Ensure XML documentation is **accurate and complete** relative to the MCP text (fix inaccuracies, add missing detail when MCP provides it).
+5. If the MCP docs (via `search_docs`) do not provide enough information to decide something:
+   - **Do not modify** the affected Entity or property.
+   - Explicitly treat it as “undecidable from MCP data alone”.
+6. Numeric properties are **high risk** for deserialization, especially when Electron sends fractional values into C# integral fields.
+   - There is a dedicated tracking file: `ElectronNET.API/API/Entities/NumericPropertiesToCheck.txt`.
+   - Only numeric properties in Bucket B or Bucket C (see section 4) — i.e. values that may practically be fractional or are ambiguous from MCP docs — must be listed there as `ClassName.PropertyName`. Clearly integral Bucket A fields (ids, counts, bit depths, etc.) are **not** recorded there.
+
+---
+
+## 2. Allowed MCP Tools and How to Use Them
+
+Server: `docs-mcp-server`
+
+### 2.1 Tools
+
+- `list_libraries`
+  - Purpose: confirm available libraries.
+  - For this task: used once to discover `electronjs`. No need to repeat unless configuration changes.
+
+- `search_docs`
+  - **Primary tool.**
+  - Parameters:
+    - `library`: `"electronjs"`
+    - `query`: free-text query targeting a specific Electron API or structure.
+    - `limit`: small integer (`1`–`5`) to keep responses compact.
+    - `version`: optional (may be added if version-specific behavior is needed later).
+  - Behavior:
+    - Returns a small number of documentation excerpts (markdown blocks) with URLs and surrounding context.
+    - This is the authoritative source for field names, types, and semantics.
+  - Usage patterns:
+    - Structures: `"api/structures/<name>"` (e.g. `"api/structures/display"`).
+    - Modules: `"api/<module>"` (e.g. `"api/screen"`, `"api/notification"`).
+
+- **Do not use** for this workflow unless explicitly instructed:
+  - `scrape_docs`, `refresh_version`, `list_jobs`, `get_job_info`, `cancel_job`, `remove_docs`.
+  - `fetch_url` (direct URL fetch is not the intended access pattern for Electron docs here).
+
+### 2.2 MCP Argument Discipline
+
+- When calling any `docs-mcp-server` tool (`search_docs`, `list_libraries`, etc.), **only** send parameters that are explicitly defined by that tool.
+- Do **not** send extra fields such as `task_progress` or any other metadata; these can break the server.
+- For `search_docs`, the allowed parameters are: `library`, `query`, `limit`, and optional `version`.
+
+### 2.3 MCP Connection Failures
+
+- If any MCP call (`search_docs`, `list_libraries`, etc.) fails due to connection/tool errors (e.g. "No connection found for server", transport errors, malformed-argument errors):
+  - **Do not** conclude that there is "no MCP coverage" or that docs do not exist.
+  - **Do not** proceed with code or documentation changes for the affected Entity.
+  - **Stop all MCP-dependent work** and explicitly request user assistance via the Cline follow-up mechanism (ask the user to "Retry MCP Connection" or otherwise fix the MCP integration).
+- Only treat a structure as "not found in MCP" when:
+  - `search_docs` executes successfully, and
+  - The server explicitly returns a "No results found" response for a reasonable, structure-targeted query.
+- Never apply the `Up-to-date with Electron API 39.2` remark, change types, or adjust members based on assumptions made while the MCP server is unavailable or misconfigured.
+
+---
+
+## 3. Core Workflow per Entity Class
+
+Entity classes live under:
+
+- `ElectronNET.API/API/Entities/*.cs`
+
+For each C# Entity class:
+
+1. **Identify matching Electron API document via MCP**
+   - Use `search_docs(library="electronjs", query=...)` with a query that should land on the right Electron doc.
+   - Example patterns:
+     - `"api/structures/display"` → Display structure.
+     - `"api/screen"` → Screen module.
+     - `"api/structures/<entity-name>"` where `<entity-name>` matches or closely resembles the C# Entity name.
+   - If multiple results come back, select the excerpt that:
+     - Mentions the structure name, or
+     - Clearly lists fields/properties that resemble the C# properties.
+   - If no relevant result is found:
+     - Mark the Entity as **"cannot be validated from MCP docs"**.
+     - Do **not** change it.
+
+2. **Extract Electron field definitions from MCP result**
+   - From the chosen excerpt, enumerate:
+     - Field names.
+     - Field types (e.g. `string`, `number`, `boolean`, `Rectangle`, `Size`, `Point`, etc.).
+     - Short description text for each field, as this is needed for numeric semantics.
+
+3. **Read the C# Entity source**
+   - Open `ElectronNET.API/API/Entities/<Entity>.cs`.
+   - For each C# property, record:
+     - `PropertyName`.
+     - Type (e.g. `int`, `double`, `string`, `Rectangle`, `Size`, etc.).
+     - XML summary comments, if any; these should be checked against MCP descriptions.
+
+4. **Compare MCP definition to C# Entity**
+   - For every field in MCP:
+     - **Matched**: there is a C# property of the same concept.
+     - **Missing**: no corresponding C# property.
+   - For every C# property:
+     - **Backed by MCP**: exists in MCP docs.
+     - **Not backed**: not present in MCP docs; keep but mark as not documented by MCP.
+   - For matched fields:
+     - Check type compatibility (especially numerics).
+     - Check XML doc comments for completeness and alignment with MCP description.
+
+5. **Plan changes (still per Entity)**
+   - For each matched field:
+     - If type and docs align with MCP → no change.
+     - If type is incompatible (or clearly suboptimal) given MCP semantics → mark for type change.
+     - If XML docs are missing or inaccurate vs MCP text → mark for doc update.
+   - For missing fields:
+     - If MCP docs clearly define a field not present in C# → consider adding a property once in Act mode.
+   - For extra C# properties not in MCP:
+     - Leave them but note that they are not MCP-backed.
+
+6. **Implementation (when performing edits)**
+   - Apply type changes and doc updates that are justified **directly** by MCP snippets.
+   - Add MCP-backed missing properties where the mapping is unambiguous.
+   - After each file (or every 3–5 files, per user preference), update `NumericPropertiesToCheck.txt`.
+
+---
+
+## 4. Numeric Properties – Detailed Rules
+
+For Electron fields typed as `number` in MCP docs, the assistant must classify them into 3 buckets **using only the MCP text**.
+
+### 4.1 Bucket A – Clearly Integral
+
+Criteria (derived strictly from MCP descriptions):
+
+- Description uses *count/identifier* language, e.g.:
+  - "ID", "identifier", "unique identifier", "index", "sequential number".
+  - "The number of bits per pixel".
+  - "The number of bits per color component".
+- Concept is inherently discrete (bits, channels, counts of items).
+
+Actions:
+
+- C# type should be an integral type (`int` or `long`), aligned with existing code conventions.
+- Record the property in `NumericPropertiesToCheck.txt` as `ClassName.PropertyName`.
+
+### 4.2 Bucket B – Clearly Potentially Fractional (Double/Decimal)
+
+Criteria based on MCP docs (no external memory):
+
+- Description involves quantities that are naturally fractional:
+  - Scale factors, ratios, percentages.
+  - Frequencies or rates where fractional values conceptually make sense.
+- MCP examples (if present) show decimal literals (`1.5`, `0.8`, etc.).
+
+Actions:
+
+- C# type should be a floating-point type (`double` by default, `decimal` only if user later requests that convention).
+- Record in `NumericPropertiesToCheck.txt` as `ClassName.PropertyName`.
+- When explaining changes, explicitly state that the decision is inferred from the MCP description (e.g. "scale factor"), not from prior Electron knowledge.
+
+### 4.3 Bucket C – Ambiguous Numeric (Do Not Change Type Blindly)
+
+Criteria:
+
+- MCP just says `number` with a neutral description.
+- Semantics are not clearly count/identifier and not clearly ratio/scale.
+
+Actions:
+
+- Do **not** change the existing C# type.
+- Still record `ClassName.PropertyName` in `NumericPropertiesToCheck.txt` for later manual/runtime inspection.
+
+### 4.4 Process for Recording Numeric Properties
+
+For each Entity, after aligning fields with MCP docs:
+
+1. Identify all fields in the MCP snippet typed as `number` (or clearly numeric) and their corresponding C# properties.
+2. For each such property in **Bucket B or Bucket C only** (potentially fractional or ambiguous numerics):
+   - Append a line to `NumericPropertiesToCheck.txt`:
+     - `ClassName.PropertyName`
+3. Do **not** record Bucket A (clearly integral) fields in `NumericPropertiesToCheck.txt`.
+4. Keep this file updated after each file edit or after a small batch of files (3–5), as per the user’s guidance.
+
+---
+
+## 5. Documentation Updates
+
+- When MCP docs provide clear textual descriptions or additional semantics:
+  - Update the XML `<summary>` comments on C# properties to:
+    - Correct inaccuracies.
+    - Fill in missing details that MCP provides.
+- Always ensure that **every change to docs** can be traced back to an MCP snippet:
+  - Include key phrases from MCP in your summary.
+  - Do not introduce new semantics not present in MCP.
+- After a class has been fully audited against MCP docs (or explicitly determined to have no MCP counterpart but retained as project-specific), add a class-level remarks tag to mark its status:
+  - Insert `/// <remarks>Up-to-date with Electron API 39.2</remarks>` immediately below the class `<summary>` XML doc.
+  - Only add this remark when the mapping against MCP docs is complete and current.
+- For any member or type whose MCP docs include platform tags (e.g. `_macOS_`, `_Windows_`, `_Linux_`):
+  - Add `[SupportedOSPlatform("...")]` attributes from `System.Runtime.Versioning` for each supported platform.
+  - Do **not** add these attributes when MCP shows no platform restriction (i.e., supported on all major desktop platforms).
+  - Prefer class-level attributes when the entire type is restricted to a single platform (e.g. options objects used only on Windows), and property-level attributes when only selected members are platform-specific.
+
+---
+
+## 6. High-Level Execution Strategy (File-by-File)
+
+1. Enumerate all `*.cs` under `ElectronNET.API/API/Entities`.
+2. For each file, in order (A-to-Z across all Entities), in a single pass:
+   - Use `search_docs` on `electronjs` to find the relevant Electron structure/module.
+   - Compare the Entity against the MCP definition.
+   - Immediately apply safe, MCP-backed changes (types + docs + missing fields) based on that comparison.
+   - Update `NumericPropertiesToCheck.txt` with all numeric properties from that file.
+3. There is no separate "audit report" phase; validation and implementation are done together in this single pass. You may keep brief internal notes if helpful, but no per-Entity external reports are required.
+4. If at any point MCP does not contain the necessary information:
+   - Stop for that Entity and mark it as unresolved rather than guessing.
+
+---
+
+## 7. Non-Negotiables
+
+- Never assume or invent Electron field behavior.
+- Never infer numeric ranges, enums, or value sets beyond what MCP explicitly states.
+- For any doubt, prefer:
+  - No change to code, plus
+  - Recording the property in `NumericPropertiesToCheck.txt`, plus
+  - A note that it is ambiguous from MCP docs.

src/ElectronNET.API/API/Entities/NumericPropertiesToCheck.txt

@@ -0,0 +1,33 @@
+Display.DisplayFrequency
+Display.ScaleFactor
+AddRepresentationOptions.ScaleFactor
+BitmapOptions.ScaleFactor
+CreateFromBitmapOptions.ScaleFactor
+CreateFromBufferOptions.ScaleFactor
+CreateInterruptedDownloadOptions.StartTime
+CPUUsage.PercentCPUUsage
+CPUUsage.IdleWakeupsPerSecond
+Margins.Top
+Margins.Bottom
+Margins.Left
+Margins.Right
+InputEvent.Location
+PrintOptions.ScaleFactor
+PrintDpi.Horizontal
+PrintDpi.Vertical
+BrowserWindowOptions.Opacity
+WebPreferences.ZoomFactor
+Cookie.ExpirationDate
+PrintToPDFOptions.Scale
+UploadFile.ModificationTime
+ProcessMetric.CreationTime
+Certificate.ValidStart
+Certificate.ValidExpiry
+CookieDetails.ExpirationDate
+PageSize.Height
+PageSize.Width
+EnableNetworkEmulationOptions.Latency
+EnableNetworkEmulationOptions.DownloadThroughput
+EnableNetworkEmulationOptions.UploadThroughput
+ProgressInfo.Percent
+UpdateInfo.StagingPercentage