# Common Shared Library

This project contains shared utility classes that can be referenced from any project in the solution.

## Files

- **StdUtil.cs**: File system and encoding utility methods
- **StdWeb.cs**: Web-specific utility methods for ASP.NET applications

## Namespace

The shared utilities use the `Utils` namespace.

## Usage in Projects

### Recommended baseline

1. Add a project reference to `Common\Common.csproj`
2. Use the shared namespace:
   ```csharp
   using Utils;
   // or
   using static Utils.StdUtil;
   using static Utils.StdWeb;
   ```
3. Exclude or remove any legacy per-project `StdUtil.cs` / `StdWeb.cs` files so only the shared versions are compiled

### Project reference

```xml
<ItemGroup>
  <ProjectReference Include="..\Common\Common.csproj">
    <Project>{8B5F3D2A-9C7E-4F1B-A2D6-3E8F7C9A1B4D}</Project>
    <Name>Common</Name>
  </ProjectReference>
</ItemGroup>
```

## Migration from Legacy Local Copies

If a project still has local `StdUtil.cs` and `StdWeb.cs` files:

1. Add a reference to `Common\Common.csproj`
2. Update using statements from legacy namespaces to `Utils`
3. Exclude or remove the legacy local `StdUtil.cs` and `StdWeb.cs` files from that project

## Download API rendered capture mode

The Muq Web project now supports a rendered capture mode in `POST ~/api/download/init`.

### Static pull

```json
{
  "url": "http://localhost:1085/Muq/?view=prn"
}
```

This saves the raw HTTP response body, equivalent to a static source pull.

### Rendered pull

```json
{
  "url": "http://localhost:1085/Muq/?view=prn&deck=prn",
  "rendered": true,
  "includeStatic": true,
  "waitMs": 5000,
  "readySelector": "#panel-prn.active",
  "outRel": "audit",
  "outName": "prn-audit",
  "outExt": "html"
}
```

This mode opens the page in a hidden browser host, waits for activation, then saves the post-JavaScript DOM HTML. When `includeStatic` is true, a second sidecar file is also saved containing the static source snapshot.

### Rendered pull with target image capture

```json
{
  "url": "http://localhost:1085/Muq/?view=prn&deck=prn&target=panel-prn",
  "rendered": true,
  "includeStatic": true,
  "waitMs": 5000,
  "readySelector": "#panel-prn.active",
  "target": "#panel-prn",
  "outRel": "audit",
  "outName": "prn-audit",
  "outExt": "html"
}
```

When `target` is supplied, rendered mode also saves a PNG sidecar named like `prn-audit.target.png`. The target can be supplied either:

- directly in the JSON body as `target`
- or as a `target` query parameter embedded in the requested URL

If the target value is a simple id-like token such as `panel-prn`, Muq treats it as `#panel-prn`. Full CSS selectors are also supported.

### Request fields

- `rendered`: when true, capture activated DOM instead of raw response bytes
- `includeStatic`: when true with rendered mode, also save a static sidecar snapshot
- `waitMs`: minimum time to wait before returning rendered HTML
- `readySelector`: optional CSS selector that must exist before capture completes
- `target`: optional selector/id-like token for a target element image capture

### Status fields

`GET ~/api/download/status?downloadId=...` now also returns:

- `rendered`
- `staticOutPath`
- `targetOutPath`

### Notes

- Rendered capture uses a hidden Windows browser host and requires a Windows desktop-capable environment.
- Static and rendered pulls can now be stored separately for audit and test snapshots.
- Target capture writes a cropped PNG of the activated target region when the target exists after activation.

## Building

The Common project targets .NET Framework 4.8 and can be built independently:

```
dotnet build Common\Common.csproj
```

Or build the entire solution:

```
dotnet build Muqload.sln