# HPL Toolbox — Project Summary for AI

## What this project is

HPL Toolbox is an internal tool for a playable ad team. It ships as **two separate deliverables** from the same repo:

1. **VS Code Extension** (`src/`) — a `.vsix` that adds tool panels as webview tabs inside VS Code.
2. **Standalone Windows App** (`standalone/`) — a Go + WebView2 desktop app that exposes the same tools through a local HTTP server rendered in a native window. It is a **real, complete, production app** — not a prototype or subset.

Both deliverables implement the same set of tools. New features are typically added to both.

---

## Directory structure

```
HPLToolbox-Extension/
├── src/
│   ├── extension.ts          # Extension entry point, registers commands
│   ├── tools/                # One file per tool (VS Code webview panels)
│   │   ├── shared.ts         # Shared utilities: singletonPanel, webview styles, clipboard/open handlers
│   │   ├── plecUpload.ts     # PLEC Upload tool
│   │   ├── applovin.ts       # AppLovin Playable Preview
│   │   ├── base64Scanner.ts  # Base64 Scanner
│   │   ├── mraidChecker.ts   # MRAID Checker
│   │   ├── mintegral.ts      # Mintegral Checker
│   │   ├── sendToMobile.ts   # Send To Mobile
│   │   ├── playworks.ts      # Playworks Converter
│   │   ├── deviceSimulator.ts# Device Simulator
│   │   └── projectInit.ts    # Initialize Project
│   └── tools.json            # Tool launcher config (name, command, icon, description)
├── standalone/               # The Go standalone app — complete, production-grade
│   ├── main.go               # Entry point: HTTP server + WebView2 window + route registration
│   ├── platform.go           # AppConfig struct, defaultConfig(), LoadConfig/SaveConfig, OS helpers
│   ├── settings.go           # /api/settings POST endpoint; settings modal HTML
│   ├── layout.go             # Shared HTML layout, nav sidebar, CSS
│   ├── home.go               # Home page / tool launcher
│   ├── plec.go               # PLEC Upload: page HTML, pick endpoints, upload (legacy + WordPress)
│   ├── applovin.go           # AppLovin upload
│   ├── base64.go             # Base64 Scanner
│   ├── mraid.go              # MRAID Checker
│   ├── mintegral.go          # Mintegral Checker
│   ├── mobile.go             # Send To Mobile
│   ├── playworks.go          # Playworks Converter
│   ├── device_simulator.go   # Device Simulator
│   ├── project_init.go       # Initialize Project
│   ├── changelog.go          # Changelog page
│   ├── json.go               # newJSONStream helper (NDJSON streaming responses)
│   ├── update_checker.go     # Auto-update check against Gitea release API
│   ├── single_instance.go    # Single-instance lock via TCP port file
│   └── assets/               # Embedded static assets (qrcode.min.js, mintegral preview util)
├── scripts/
│   ├── build.ps1             # Builds both .vsix and standalone exe into dist/
│   └── run-standalone.ps1    # Runs the standalone app in dev mode (go run .)
├── data/
│   └── manifest.json         # Project Init manifest (team template files list)
├── aiAssets/                 # Sample HTML files used for testing/reference
├── package.json              # Extension manifest, VS Code settings contributions, npm scripts
├── tsconfig.json
└── README.md
```

---

## Tools

| Tool | Description |
|---|---|
| PLEC Upload | Upload HTML playable files to internal PLEC servers. Supports two servers: Default (167.99.227.249, legacy PHP) and Backup (20.255.60.183, WordPress). Backup server uses auto-login via credentials. |
| AppLovin Playable Preview | Upload HTML files to p.applov.in and generate QR preview links. |
| Base64 Scanner | Scan HTML files for external or non-base64 asset references. |
| Send To Mobile | Serve selected HTML files over LAN and display a QR code for mobile preview. |
| MRAID Checker | Check HTML files against MRAID requirements and best practices. |
| Mintegral Checker | Validate Mintegral playable ZIPs against PlayTurbo requirements with embedded runtime preview. |
| Playworks Converter | Convert Playworks HTML into per-network variants. |
| Device Simulator | Preview HTML playables inside accurate mobile device frames with notch/Dynamic Island overlays. |
| Initialize Project | Download team template files from a shared manifest (Google Drive or direct URL). |

---

## Architecture notes

### VS Code Extension
- Each tool is a singleton webview panel (`singletonPanel` in `shared.ts`).
- The panel HTML is returned as a template string from `getHtml()` inside each tool file.
- Communication between extension host and webview uses `panel.webview.postMessage` / `onDidReceiveMessage`.
- Settings are read from `vscode.workspace.getConfiguration('hplToolbox.*')` and contributed in `package.json`.
- Session-persistent UI state (e.g. last selected server) uses `context.globalState`.

### Standalone App
- Go HTTP server on a random localhost port, served into a WebView2 window.
- All pages return full HTML strings (no template files on disk).
- Long-running operations (uploads, scans) use `newJSONStream` to stream NDJSON progress events — the browser reads these with `ReadableStream` and updates the UI incrementally.
- Config is persisted to `%LOCALAPPDATA%\HPLToolbox\config.json` via `LoadConfig` / `SaveConfig`.
- `localStorage` is used for lightweight UI-only state (e.g. last selected server in PLEC Upload).
- Single-instance enforcement: on launch, tries to connect to a previous instance's port from a lock file and `POST /api/focus` to bring its window forward, then exits.

### PLEC Upload — dual server detail
- **Default (legacy)**: `POST http://167.99.227.249/src/upload_HTML_Experimental.php` with `fileUpload_N` / `iterationNameUpload_N` fields. Filenames are timestamped.
- **Backup (WordPress)**: `POST http://20.255.60.183/wp-admin/admin-ajax.php` with `action=plec_upload_files`, `nonce`, `rows` (JSON array), and `file_N` fields. Login flow: POST `/wp-login.php` → GET `/file-upload/` to extract nonce. Iteration name is used as the uploaded filename. Preview URL is constructed as `/preview?theme=calcite&n1=<original>&m1=<saved>`.

---

## Build

```powershell
npm run build            # builds both .vsix and standalone .exe into dist/
npm run build -- -Extension   # .vsix only
npm run build -- -Standalone  # .exe only
npm run run-standalone   # dev: go run . in standalone/
npm run compile          # tsc only
npm run watch            # tsc watch
```

Requires: Node.js, TypeScript (`npm install`), Go, optionally `vsce` and `rsrc`.

---

## Key config (VS Code settings)

All under `hplToolbox.*`:

| Key | Default | Purpose |
|---|---|---|
| `plec.uploadUrl` | `http://167.99.227.249/src/upload_HTML_Experimental.php` | Legacy server endpoint |
| `plec.originUrl` | `http://167.99.227.249` | Origin/Referer for legacy uploads |
| `plec.wpUsername` | `pm` | WordPress username for backup server |
| `plec.wpPassword` | _(set)_ | WordPress password for backup server |
| `applovin.cookie` | _(empty)_ | `__Host-APPLOVINID` cookie for p.applov.in |
| `deviceSimulator.devicesUrl` | Google Drive link | Remote devices.json URL |
| `deviceSimulator.languagesUrl` | Google Drive link | Remote languages.json URL |