Add "Getting-Started"

Getting-Started.-.md

@@ -0,0 +1,225 @@
+# Getting Started
+
+This guide covers prerequisites, connection options, and basic browser interaction with go-webview.
+
+## Prerequisites
+
+You need a Chrome or Chromium browser running with remote debugging enabled. Start it from the command line:
+
+```bash
+# Linux
+google-chrome --remote-debugging-port=9222
+
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+
+# Headless mode (no GUI)
+google-chrome --headless --remote-debugging-port=9222
+```
+
+The `--remote-debugging-port` flag exposes Chrome's DevTools Protocol over HTTP and WebSocket on the specified port. The package connects to this endpoint to control the browser.
+
+## Connection Options
+
+Create a `Webview` instance using `New()` with one or more `Option` functions:
+
+### WithDebugURL
+
+Required. Specifies the Chrome DevTools HTTP endpoint:
+
+```go
+wv, err := webview.New(
+    webview.WithDebugURL("http://localhost:9222"),
+)
+```
+
+Under the hood, this calls `NewCDPClient()` which:
+1. Fetches available targets from `http://localhost:9222/json`
+2. Finds the first `"page"` type target with a WebSocket debugger URL
+3. If no page target exists, creates one via `/json/new`
+4. Opens a WebSocket connection to the target
+
+### WithTimeout
+
+Sets the default timeout for all operations. Defaults to 30 seconds:
+
+```go
+wv, err := webview.New(
+    webview.WithDebugURL("http://localhost:9222"),
+    webview.WithTimeout(60 * time.Second),
+)
+```
+
+Each method on `Webview` creates a `context.WithTimeout` using this duration for its CDP calls.
+
+### WithConsoleLimit
+
+Sets the maximum number of console messages retained in the built-in buffer. Defaults to 1000:
+
+```go
+wv, err := webview.New(
+    webview.WithDebugURL("http://localhost:9222"),
+    webview.WithConsoleLimit(5000),
+)
+```
+
+When the limit is reached, the oldest messages are pruned in batches of 100.
+
+## Navigation
+
+```go
+// Navigate to a URL (waits for page load)
+err := wv.Navigate("https://example.com")
+
+// Reload the current page
+err = wv.Reload()
+
+// Go back in history
+err = wv.GoBack()
+
+// Go forward in history
+err = wv.GoForward()
+```
+
+`Navigate` and `Reload` both poll `document.readyState` every 100ms until it equals `"complete"`, subject to the configured timeout.
+
+## Page Information
+
+```go
+// Get the current URL
+url, err := wv.GetURL()
+
+// Get the page title
+title, err := wv.GetTitle()
+
+// Get the full document HTML (pass empty string for whole page)
+html, err := wv.GetHTML("")
+
+// Get the outer HTML of a specific element
+elemHTML, err := wv.GetHTML("#main-content")
+```
+
+## Basic Interaction
+
+```go
+// Click an element by CSS selector
+err := wv.Click("#submit-button")
+
+// Type text into an input field
+err = wv.Type("#email-input", "user@example.com")
+
+// Wait for an element to appear in the DOM
+err = wv.WaitForSelector(".loaded-content")
+```
+
+`Click` resolves the element's bounding box via CDP and dispatches `mousePressed`/`mouseReleased` events at the element's centre. If the bounding box cannot be determined, it falls back to a JavaScript `element.click()`.
+
+`Type` focuses the element first, then dispatches `keyDown`/`keyUp` events for each character.
+
+## Viewport and User Agent
+
+```go
+// Set viewport dimensions
+err := wv.SetViewport(1920, 1080)
+
+// Override the user agent string
+err = wv.SetUserAgent("Custom Agent/1.0")
+```
+
+These use the CDP `Emulation` domain under the hood.
+
+## Screenshots
+
+```go
+// Capture a PNG screenshot
+pngData, err := wv.Screenshot()
+
+// Write to file
+os.WriteFile("page.png", pngData, 0644)
+```
+
+Returns raw PNG bytes using `Page.captureScreenshot`.
+
+## JavaScript Evaluation
+
+```go
+// Execute JavaScript and get the return value
+result, err := wv.Evaluate("document.querySelectorAll('a').length")
+// result is an any -- in this case, a float64
+
+// Execute a void script
+_, err = wv.Evaluate("document.body.style.background = 'red'")
+```
+
+Scripts are evaluated via `Runtime.evaluate` with `returnByValue: true`. If the script throws, the error is returned as a Go error prefixed with `"JavaScript error:"`.
+
+## Console Messages
+
+Console messages are automatically captured from the moment the `Webview` is created:
+
+```go
+// Get all captured console messages
+messages := wv.GetConsole()
+for _, msg := range messages {
+    fmt.Printf("[%s] %s
+", msg.Type, msg.Text)
+}
+
+// Clear the buffer
+wv.ClearConsole()
+```
+
+For advanced filtering and real-time watching, see [[Console-Monitoring]].
+
+## File Upload and Drag & Drop
+
+```go
+// Upload files to a file input element
+err := wv.UploadFile("#file-input", []string{"/path/to/file.pdf"})
+
+// Drag and drop between elements
+err = wv.DragAndDrop("#source-item", "#drop-target")
+```
+
+`UploadFile` uses `DOM.setFileInputFiles`. `DragAndDrop` dispatches a sequence of `mousePressed`, `mouseMoved`, and `mouseReleased` events between the source and target element centres.
+
+## Low-Level CDP Client
+
+For advanced use cases, you can work directly with `CDPClient`:
+
+```go
+// List all browser targets
+targets, err := webview.ListTargets("http://localhost:9222")
+
+// Get Chrome version info
+version, err := webview.GetVersion("http://localhost:9222")
+
+// Create a new tab
+client, err := existingClient.NewTab("https://example.com")
+defer client.Close()
+
+// Register an event handler
+client.OnEvent("Page.loadEventFired", func(params map[string]any) {
+    fmt.Println("Page loaded!")
+})
+
+// Make a raw CDP call
+result, err := client.Call(ctx, "DOM.getDocument", nil)
+```
+
+## Cleanup
+
+Always close the `Webview` when finished:
+
+```go
+defer wv.Close()
+```
+
+This cancels the internal context and closes the WebSocket connection to Chrome.
+
+## Next Steps
+
+- [[DOM-Queries]] -- Querying and inspecting DOM elements
+- [[Actions]] -- Chainable action sequences
+- [[Console-Monitoring]] -- Advanced console watching and filtering
+- [[Angular-Testing]] -- Angular-specific testing utilities