haltija 1.1.21 → 1.2.2

package/dist/index.js

@@ -1,12 +1,16 @@
 // @bun
 var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -670,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.1.21";
+var VERSION = "1.2.2";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -1118,11 +1122,16 @@ Response: { tagName, id, className, textContent, attributes: {...} }
 
 | Name | Type | Description |
 |------|------|-------------|
-| \`selector\` | string | CSS selector *(required)* |
+| \`ref\` | string,null | Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency |
+| \`selector\` | string,null | CSS selector |
 | \`all\` | boolean,null | Return all matches (default false = first only) |
 
 **Examples:**
 
+- **by-ref**: Query element by ref ID from /tree
+  \`\`\`json
+  {"ref":"42"}
+  \`\`\`
 - **by-id**: Find element by ID
   \`\`\`json
   {"selector":"#submit-btn"}
@@ -1172,13 +1181,18 @@ Use before clicking to verify element is visible and enabled.
 
 | Name | Type | Description |
 |------|------|-------------|
-| \`selector\` | string | CSS selector *(required)* |
+| \`ref\` | string,null | Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency |
+| \`selector\` | string,null | CSS selector |
 | \`fullStyles\` | boolean,null | Include all computed styles (default: false) |
 | \`matchedRules\` | boolean,null | Include matched CSS rules with specificity (default: false) |
 | \`window\` | string,null | Target window ID |
 
 **Examples:**
 
+- **by-ref**: Inspect element by ref ID from /tree
+  \`\`\`json
+  {"ref":"42"}
+  \`\`\`
 - **check-button**: Verify button is clickable
   \`\`\`json
   {"selector":"#submit"}
@@ -1256,7 +1270,8 @@ Response: array of inspection objects
 
 | Name | Type | Description |
 |------|------|-------------|
-| \`selector\` | string | CSS selector *(required)* |
+| \`ref\` | string,null | Ref ID from /tree output - returns single element as array |
+| \`selector\` | string,null | CSS selector |
 | \`limit\` | number,null | Max elements (default 10) |
 | \`fullStyles\` | boolean,null | Include all computed styles (default: false) |
 | \`matchedRules\` | boolean,null | Include matched CSS rules with specificity (default: false) |
@@ -1590,7 +1605,8 @@ Good for: sliders, resize handles, drag-and-drop reordering, range inputs.
 
 | Name | Type | Description |
 |------|------|-------------|
-| \`selector\` | string | CSS selector of drag handle *(required)* |
+| \`ref\` | string,null | Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency |
+| \`selector\` | string,null | CSS selector of drag handle |
 | \`deltaX\` | number,null | Horizontal distance in pixels |
 | \`deltaY\` | number,null | Vertical distance in pixels |
 | \`duration\` | number,null | Drag duration in ms (default 300) |
@@ -1598,6 +1614,10 @@ Good for: sliders, resize handles, drag-and-drop reordering, range inputs.
 
 **Examples:**
 
+- **by-ref**: Drag element by ref ID
+  \`\`\`json
+  {"ref":"15","deltaX":100}
+  \`\`\`
 - **slider-right**: Move slider right
   \`\`\`json
   {"selector":".slider-handle","deltaX":100}
@@ -1625,7 +1645,8 @@ Great for showing users what you found or pointing out issues. Use /unhighlight
 
 | Name | Type | Description |
 |------|------|-------------|
-| \`selector\` | string | CSS selector *(required)* |
+| \`ref\` | string,null | Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency |
+| \`selector\` | string,null | CSS selector |
 | \`label\` | string,null | Label text to show |
 | \`color\` | string,null | CSS color (default #6366f1) |
 | \`duration\` | number,null | Auto-hide after ms (omit for manual) |
@@ -1633,6 +1654,10 @@ Great for showing users what you found or pointing out issues. Use /unhighlight
 
 **Examples:**
 
+- **by-ref**: Highlight element by ref ID
+  \`\`\`json
+  {"ref":"42","label":"Found it!"}
+  \`\`\`
 - **point-out**: Show user where to click
   \`\`\`json
   {"selector":"#login-btn","label":"Click here"}
@@ -1662,16 +1687,17 @@ Remove any active highlight overlay created by /highlight.
 
 Smooth scroll with natural easing. Multiple modes:
 
-- selector: Scroll element into view (most common)
+- ref/selector: Scroll element into view (most common)
 - x/y: Scroll to absolute position
 - deltaX/deltaY: Scroll relative to current position
 
-At least one of selector, x, y, deltaX, or deltaY must be provided.
+At least one of ref, selector, x, y, deltaX, or deltaY must be provided.
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
+| \`ref\` | string,null | Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency |
 | \`selector\` | string,null | CSS selector to scroll into view |
 | \`x\` | number,null | Absolute X position in pixels |
 | \`y\` | number,null | Absolute Y position in pixels |
@@ -1684,6 +1710,10 @@ At least one of selector, x, y, deltaX, or deltaY must be provided.
 
 **Examples:**
 
+- **by-ref**: Scroll element into view by ref ID
+  \`\`\`json
+  {"ref":"42"}
+  \`\`\`
 - **to-element**: Scroll pricing section into view
   \`\`\`json
   {"selector":"#pricing"}
@@ -1775,13 +1805,18 @@ Response: { success: true, data: <return value> }
 
 | Name | Type | Description |
 |------|------|-------------|
-| \`selector\` | string | CSS selector of the element *(required)* |
+| \`ref\` | string,null | Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency |
+| \`selector\` | string,null | CSS selector of the element |
 | \`method\` | string | Method name to call or property name to get *(required)* |
 | \`args\` | array,null | Arguments to pass (omit to get property value) |
 | \`window\` | string,null | Target window ID |
 
 **Examples:**
 
+- **by-ref**: Get property by ref ID
+  \`\`\`json
+  {"ref":"42","method":"value"}
+  \`\`\`
 - **get-value**: Get input value
   \`\`\`json
   {"selector":"#email","method":"value"}
@@ -1867,18 +1902,18 @@ Use /location after to verify navigation succeeded.
 
 **Refresh the page**
 
-Hard reload the current page, bypassing cache. Use soft: true for cache-friendly reload.
+Hard reload the current page, bypassing all caches (CSS, JS, images). Use soft: true for cache-friendly reload.
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| \`soft\` | boolean,null | Use cached resources if available (default false = hard refresh) |
+| \`soft\` | boolean,null | Use cached resources if available (default false = hard refresh that busts all caches) |
 | \`window\` | string,null | Target window ID |
 
 **Examples:**
 
-- **hard**: Hard refresh (default, bypasses cache)
+- **hard**: Hard refresh (default, bypasses all caches)
   \`\`\`json
   {}
   \`\`\`
@@ -2515,16 +2550,20 @@ Use this when you see a blob URL in the DOM and need to access its content.
 
 **Capture a screenshot**
 
-Capture the page or a specific element as base64 PNG/WebP/JPEG.
+Capture the page or a specific element as PNG/WebP/JPEG.
 
 Works automatically in the Haltija Desktop app. In browser widget mode, captures viewport only.
 
-Response: { success, image: "data:image/png;base64,...", width, height, source }
+When file=true (default from CLI), saves to /tmp/haltija-screenshots/ and returns file path.
+When file=false, returns base64 data URL in response JSON.
+
+Response: { success, path?, image?, width, height, source }
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
+| \`ref\` | string,null | Ref ID from /tree output - capture specific element |
 | \`selector\` | string,null | Element to capture (omit for full page) |
 | \`scale\` | number,null | Scale factor (default 1) |
 | \`maxWidth\` | number,null | Max width in pixels |
@@ -2532,6 +2571,7 @@ Response: { success, image: "data:image/png;base64,...", width, height, source }
 | \`window\` | string,null | Target window ID |
 | \`chyron\` | boolean,null | Burn page title, URL, timestamp into image (default true, set false for clean screenshot) |
 | \`delay\` | number,null | Wait ms before capturing (e.g. 1000 to let page settle after navigation) |
+| \`file\` | boolean,null | Save to disk and return file path instead of data URL (default true \u2014 pass false for base64) |
 
 **Examples:**
 
@@ -2539,6 +2579,10 @@ Response: { success, image: "data:image/png;base64,...", width, height, source }
   \`\`\`json
   {}
   \`\`\`
+- **by-ref**: Capture element by ref ID
+  \`\`\`json
+  {"ref":"42"}
+  \`\`\`
 - **element**: Capture specific element
   \`\`\`json
   {"selector":"#chart"}
@@ -2584,6 +2628,76 @@ Great for debugging test failures - call this when something goes wrong.
   {"trigger":"test-failure","context":{"step":3,"error":"Element not found"}}
   \`\`\`
 
+---
+
+### \`POST /video/start\`
+
+**Start video recording**
+
+Start recording the browser tab as WebM video. Requires the Haltija Desktop app.
+
+The recording saves to /tmp/haltija-videos/ when stopped. Max duration is capped to prevent runaway recordings.
+
+Response: { success, recordingId }
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| \`maxDuration\` | number,null | Max recording duration in seconds (default 60, max 300) |
+| \`window\` | string,null | Target window ID |
+
+**Examples:**
+
+- **start**: Start recording active tab
+  \`\`\`json
+  {}
+  \`\`\`
+- **long**: Record up to 2 minutes
+  \`\`\`json
+  {"maxDuration":120}
+  \`\`\`
+
+---
+
+### \`POST /video/stop\`
+
+**Stop video recording**
+
+Stop recording and save the video file.
+
+Response: { success, path, duration, size }
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| \`window\` | string,null | Target window ID |
+
+**Examples:**
+
+- **stop**: Stop recording and get file path
+  \`\`\`json
+  {}
+  \`\`\`
+
+---
+
+### \`GET /video/status\`
+
+**Check video recording status**
+
+Check if video recording is active.
+
+Response: { recording, recordingId?, duration?, window? }
+
+**Examples:**
+
+- **check**: Check recording state
+  \`\`\`json
+  {}
+  \`\`\`
+
 ---
 `;
 var DOCS_MD = `# Haltija: Browser Control for AI Agents
@@ -2619,9 +2733,9 @@ hj --help              # All commands
 ### See the Page
 
 - \`hj tree [selector, depth, includeText, ...]\` - Get DOM tree structure
-- \`hj query [selector, all]\` - Query DOM elements by selector
-- \`hj inspect [selector, fullStyles, matchedRules, ...]\` - Deep inspection of an element
-- \`hj inspectAll [selector, limit, fullStyles, ...]\` - Inspect multiple elements
+- \`hj query [ref, selector, all]\` - Query DOM elements by selector
+- \`hj inspect [ref, selector, fullStyles, ...]\` - Deep inspection of an element
+- \`hj inspectAll [ref, selector, limit, ...]\` - Inspect multiple elements
 - \`hj find [text, tag, exact, ...]\` - Find elements by text content
 - \`hj form [selector, includeDisabled, includeHidden, ...]\` - Extract all form values as structured JSON
 
@@ -2630,12 +2744,12 @@ hj --help              # All commands
 - \`hj click [ref, selector, text, ...]\` - Click an element
 - \`hj type [ref, selector, text, ...]\` - Type text into an element
 - \`hj key [key, ref, selector, ...]\` - Send keyboard input
-- \`hj drag [selector, deltaX, deltaY, ...]\` - Drag from an element
-- \`hj highlight [selector, label, color, ...]\` - Visually highlight an element
+- \`hj drag [ref, selector, deltaX, ...]\` - Drag from an element
+- \`hj highlight [ref, selector, label, ...]\` - Visually highlight an element
 - \`hj unhighlight\` - Remove highlight
-- \`hj scroll [selector, x, y, ...]\` - Scroll to element or position
+- \`hj scroll [ref, selector, x, ...]\` - Scroll to element or position
 - \`hj wait [ms, forElement, hidden, ...]\` - Wait for time, element, or condition
-- \`hj call [selector, method, args, ...]\` - Call a method or get a property on an element
+- \`hj call [ref, selector, method, ...]\` - Call a method or get a property on an element
 
 ### Navigate
 
@@ -2691,8 +2805,11 @@ hj --help              # All commands
 - \`hj console\` - Get console output
 - \`hj eval [code, window]\` - Execute JavaScript
 - \`hj fetch [url, window]\` - Fetch a URL from within the tab context
-- \`hj screenshot [selector, scale, maxWidth, ...]\` - Capture a screenshot
+- \`hj screenshot [ref, selector, scale, ...]\` - Capture a screenshot
 - \`hj snapshot [trigger, context]\` - Capture page snapshot
+- \`hj video-start [maxDuration, window]\` - Start video recording
+- \`hj video-stop [window]\` - Stop video recording
+- \`hj video-status\` - Check video recording status
 
 ## Tips
 
@@ -2856,6 +2973,15 @@ function getPlaygroundHtml() {
       <button id="btn-danger" class="btn-test danger" onclick="showOutput('Danger button clicked!')">Danger Button</button>
     </div>
     
+    <h3>Background Colors</h3>
+    <p>Set the page background to a solid color. Useful for verifying screenshots and video capture.</p>
+    <div class="test-buttons">
+      <button id="bg-red" class="btn-test" style="background:#ef4444;color:white" onclick="document.body.style.backgroundColor='#ef4444';showOutput('Background: red')">Red</button>
+      <button id="bg-green" class="btn-test" style="background:#22c55e;color:white" onclick="document.body.style.backgroundColor='#22c55e';showOutput('Background: green')">Green</button>
+      <button id="bg-blue" class="btn-test" style="background:#3b82f6;color:white" onclick="document.body.style.backgroundColor='#3b82f6';showOutput('Background: blue')">Blue</button>
+      <button id="bg-reset" class="btn-test" style="background:#f8fafc;border:1px solid #cbd5e1" onclick="document.body.style.backgroundColor='#f8fafc';showOutput('Background: reset')">Reset</button>
+    </div>
+    
     <h3>Form Inputs</h3>
     <div class="test-form">
       <div class="form-row">
@@ -2918,6 +3044,12 @@ function getPlaygroundHtml() {
       <pre><code>hj query "#output"</code></pre>
     </div>
     
+    <p>Set background to red and take a screenshot:</p>
+    <div class="code-block">
+      <button class="copy-btn" data-copy-type="command" onclick="copyCode(this)">Copy</button>
+      <pre><code>hj click "#bg-red" && hj screenshot</code></pre>
+    </div>
+    
     <p>Get the page tree:</p>
     <div class="code-block">
       <button class="copy-btn" data-copy-type="command" onclick="copyCode(this)">Copy</button>
@@ -3572,10 +3704,16 @@ Use this to check if an element exists before clicking/typing. For detailed info
 Response: { tagName, id, className, textContent, attributes: {...} }`,
   category: "dom",
   input: L.object({
-    selector: L.string.describe("CSS selector"),
+    ref: L.string.describe("Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency").optional,
+    selector: L.string.describe("CSS selector").optional,
     all: L.boolean.describe("Return all matches (default false = first only)").optional
   }),
   examples: [
+    {
+      name: "by-ref",
+      input: { ref: "42" },
+      description: "Query element by ref ID from /tree"
+    },
     {
       name: "by-id",
       input: { selector: "#submit-btn" },
@@ -3602,14 +3740,14 @@ Response: { tagName, id, className, textContent, attributes: {...} }`,
     }
   ],
   invalidExamples: [
-    { name: "missing-selector", input: {}, error: "selector is required" },
+    { name: "missing-target", input: {}, error: "ref or selector is required" },
     {
       name: "wrong-type",
       input: { selector: 123 },
       error: "selector must be string"
     }
   ],
-  hints: '"selector", --all | see: tree, inspect'
+  hints: '@ref or "selector", --all | see: tree, inspect'
 });
 var inspect = endpoint({
   path: "/inspect",
@@ -3629,12 +3767,18 @@ Response includes:
 Use before clicking to verify element is visible and enabled.`,
   category: "dom",
   input: L.object({
-    selector: L.string.describe("CSS selector"),
+    ref: L.string.describe("Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency").optional,
+    selector: L.string.describe("CSS selector").optional,
     fullStyles: L.boolean.describe("Include all computed styles (default: false)").optional,
     matchedRules: L.boolean.describe("Include matched CSS rules with specificity (default: false)").optional,
     window: L.string.describe("Target window ID").optional
   }),
   examples: [
+    {
+      name: "by-ref",
+      input: { ref: "42" },
+      description: "Inspect element by ref ID from /tree"
+    },
     {
       name: "check-button",
       input: { selector: "#submit" },
@@ -3678,8 +3822,9 @@ Use before clicking to verify element is visible and enabled.`,
     }
   ],
   invalidExamples: [
-    { name: "missing-selector", input: {}, error: "selector is required" }
-  ]
+    { name: "missing-target", input: {}, error: "ref or selector is required" }
+  ],
+  hints: '@ref or "selector", --styles, --rules, --ancestors | see: tree, query'
 });
 var inspectAll = endpoint({
   path: "/inspectAll",
@@ -3695,7 +3840,8 @@ Same detailed info as /inspect, but for multiple elements. Great for:
 Response: array of inspection objects`,
   category: "dom",
   input: L.object({
-    selector: L.string.describe("CSS selector"),
+    ref: L.string.describe("Ref ID from /tree output - returns single element as array").optional,
+    selector: L.string.describe("CSS selector").optional,
     limit: L.number.describe("Max elements (default 10)").optional,
     fullStyles: L.boolean.describe("Include all computed styles (default: false)").optional,
     matchedRules: L.boolean.describe("Include matched CSS rules with specificity (default: false)").optional,
@@ -3971,13 +4117,19 @@ var drag = endpoint({
 Good for: sliders, resize handles, drag-and-drop reordering, range inputs.`,
   category: "interaction",
   input: L.object({
-    selector: L.string.describe("CSS selector of drag handle"),
+    ref: L.string.describe("Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency").optional,
+    selector: L.string.describe("CSS selector of drag handle").optional,
     deltaX: L.number.describe("Horizontal distance in pixels").optional,
     deltaY: L.number.describe("Vertical distance in pixels").optional,
     duration: L.number.describe("Drag duration in ms (default 300)").optional,
     window: L.string.describe("Target window ID").optional
   }),
   examples: [
+    {
+      name: "by-ref",
+      input: { ref: "15", deltaX: 100 },
+      description: "Drag element by ref ID"
+    },
     {
       name: "slider-right",
       input: { selector: ".slider-handle", deltaX: 100 },
@@ -3996,12 +4148,12 @@ Good for: sliders, resize handles, drag-and-drop reordering, range inputs.`,
   ],
   invalidExamples: [
     {
-      name: "missing-selector",
+      name: "missing-target",
       input: { deltaX: 100 },
-      error: "selector is required"
+      error: "ref or selector is required"
     }
   ],
-  hints: '"selector" <deltaX> <deltaY>, --duration 500 | see: click, scroll'
+  hints: '@ref or "selector" <deltaX> <deltaY>, --duration 500 | see: click, scroll'
 });
 var highlight = endpoint({
   path: "/highlight",
@@ -4012,13 +4164,19 @@ var highlight = endpoint({
 Great for showing users what you found or pointing out issues. Use /unhighlight to remove.`,
   category: "interaction",
   input: L.object({
-    selector: L.string.describe("CSS selector"),
+    ref: L.string.describe("Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency").optional,
+    selector: L.string.describe("CSS selector").optional,
     label: L.string.describe("Label text to show").optional,
     color: L.string.describe("CSS color (default #6366f1)").optional,
     duration: L.number.describe("Auto-hide after ms (omit for manual)").optional,
     window: L.string.describe("Target window ID").optional
   }),
   examples: [
+    {
+      name: "by-ref",
+      input: { ref: "42", label: "Found it!" },
+      description: "Highlight element by ref ID"
+    },
     {
       name: "point-out",
       input: { selector: "#login-btn", label: "Click here" },
@@ -4036,9 +4194,9 @@ Great for showing users what you found or pointing out issues. Use /unhighlight
     }
   ],
   invalidExamples: [
-    { name: "missing-selector", input: {}, error: "selector is required" }
+    { name: "missing-target", input: {}, error: "ref or selector is required" }
   ],
-  hints: '"selector", --label "text", --color #f00, --duration 3000 | see: unhighlight, screenshot'
+  hints: '@ref or "selector", --label "text", --color #f00, --duration 3000 | see: unhighlight, screenshot'
 });
 var unhighlight = endpoint({
   path: "/unhighlight",
@@ -4054,13 +4212,14 @@ var scroll = endpoint({
   summary: "Scroll to element or position",
   description: `Smooth scroll with natural easing. Multiple modes:
 
-- selector: Scroll element into view (most common)
+- ref/selector: Scroll element into view (most common)
 - x/y: Scroll to absolute position
 - deltaX/deltaY: Scroll relative to current position
 
-At least one of selector, x, y, deltaX, or deltaY must be provided.`,
+At least one of ref, selector, x, y, deltaX, or deltaY must be provided.`,
   category: "interaction",
   input: L.object({
+    ref: L.string.describe("Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency").optional,
     selector: L.string.describe("CSS selector to scroll into view").optional,
     x: L.number.describe("Absolute X position in pixels").optional,
     y: L.number.describe("Absolute Y position in pixels").optional,
@@ -4072,6 +4231,11 @@ At least one of selector, x, y, deltaX, or deltaY must be provided.`,
     window: L.string.describe("Target window ID").optional
   }),
   examples: [
+    {
+      name: "by-ref",
+      input: { ref: "42" },
+      description: "Scroll element into view by ref ID"
+    },
     {
       name: "to-element",
       input: { selector: "#pricing" },
@@ -4094,7 +4258,7 @@ At least one of selector, x, y, deltaX, or deltaY must be provided.`,
       description: "Slow animated scroll"
     }
   ],
-  hints: '"selector" or <deltaY>, --duration 500 | see: click, wait'
+  hints: '@ref or "selector" or <deltaY>, --duration 500 | see: click, wait'
 });
 var wait = endpoint({
   path: "/wait",
@@ -4265,17 +4429,17 @@ var refresh = endpoint({
   path: "/refresh",
   method: "POST",
   summary: "Refresh the page",
-  description: "Hard reload the current page, bypassing cache. Use soft: true for cache-friendly reload.",
+  description: "Hard reload the current page, bypassing all caches (CSS, JS, images). Use soft: true for cache-friendly reload.",
   category: "navigation",
   input: L.object({
-    soft: L.boolean.describe("Use cached resources if available (default false = hard refresh)").optional,
+    soft: L.boolean.describe("Use cached resources if available (default false = hard refresh that busts all caches)").optional,
     window: L.string.describe("Target window ID").optional
   }),
   examples: [
     {
       name: "hard",
       input: {},
-      description: "Hard refresh (default, bypasses cache)"
+      description: "Hard refresh (default, bypasses all caches)"
     },
     {
       name: "soft",
@@ -4530,12 +4694,18 @@ Return value is JSON-serialized. Promises are awaited.
 Response: { success: true, data: <return value> }`,
   category: "interaction",
   input: L.object({
-    selector: L.string.describe("CSS selector of the element"),
+    ref: L.string.describe("Ref ID from /tree output (e.g., 1, 42) - preferred for efficiency").optional,
+    selector: L.string.describe("CSS selector of the element").optional,
     method: L.string.describe("Method name to call or property name to get"),
     args: L.array(L.any).describe("Arguments to pass (omit to get property value)").optional,
     window: L.string.describe("Target window ID").optional
   }),
   examples: [
+    {
+      name: "by-ref",
+      input: { ref: "42", method: "value" },
+      description: "Get property by ref ID"
+    },
     {
       name: "get-value",
       input: { selector: "#email", method: "value" },
@@ -4607,38 +4777,49 @@ Response: { success: true, data: <return value> }`,
   ],
   invalidExamples: [
     {
-      name: "missing-selector",
+      name: "missing-target",
       input: { method: "click" },
-      error: "selector is required"
+      error: "ref or selector is required"
     },
     {
       name: "missing-method",
       input: { selector: "#btn" },
       error: "method is required"
     }
-  ]
+  ],
+  hints: '@ref or "selector" <method>, --args [...]  | see: eval, inspect'
 });
 var screenshot = endpoint({
   path: "/screenshot",
   method: "POST",
   summary: "Capture a screenshot",
-  description: `Capture the page or a specific element as base64 PNG/WebP/JPEG.
+  description: `Capture the page or a specific element as PNG/WebP/JPEG.
 
 Works automatically in the Haltija Desktop app. In browser widget mode, captures viewport only.
 
-Response: { success, image: "data:image/png;base64,...", width, height, source }`,
+When file=true (default from CLI), saves to /tmp/haltija-screenshots/ and returns file path.
+When file=false, returns base64 data URL in response JSON.
+
+Response: { success, path?, image?, width, height, source }`,
   category: "debug",
   input: L.object({
+    ref: L.string.describe("Ref ID from /tree output - capture specific element").optional,
     selector: L.string.describe("Element to capture (omit for full page)").optional,
     scale: L.number.describe("Scale factor (default 1)").optional,
     maxWidth: L.number.describe("Max width in pixels").optional,
     maxHeight: L.number.describe("Max height in pixels").optional,
     window: L.string.describe("Target window ID").optional,
     chyron: L.boolean.describe("Burn page title, URL, timestamp into image (default true, set false for clean screenshot)").optional,
-    delay: L.number.describe("Wait ms before capturing (e.g. 1000 to let page settle after navigation)").optional
+    delay: L.number.describe("Wait ms before capturing (e.g. 1000 to let page settle after navigation)").optional,
+    file: L.boolean.describe("Save to disk and return file path instead of data URL (default true \u2014 pass false for base64)").optional
   }),
   examples: [
     { name: "full-page", input: {}, description: "Capture entire page with chyron showing URL/title" },
+    {
+      name: "by-ref",
+      input: { ref: "42" },
+      description: "Capture element by ref ID"
+    },
     {
       name: "element",
       input: { selector: "#chart" },
@@ -5080,6 +5261,119 @@ Great for debugging test failures - call this when something goes wrong.`,
     }
   ]
 });
+var videoStart = endpoint({
+  path: "/video/start",
+  method: "POST",
+  summary: "Start video recording",
+  description: `Start recording the browser tab as WebM video. Requires the Haltija Desktop app.
+
+The recording saves to /tmp/haltija-videos/ when stopped. Max duration is capped to prevent runaway recordings.
+
+Response: { success, recordingId }`,
+  category: "debug",
+  input: L.object({
+    maxDuration: L.number.describe("Max recording duration in seconds (default 60, max 300)").optional,
+    window: L.string.describe("Target window ID").optional
+  }),
+  examples: [
+    { name: "start", input: {}, description: "Start recording active tab" },
+    { name: "long", input: { maxDuration: 120 }, description: "Record up to 2 minutes" }
+  ],
+  hints: "--maxDuration 120 | see: video-stop, video-status, screenshot"
+});
+var videoStop = endpoint({
+  path: "/video/stop",
+  method: "POST",
+  summary: "Stop video recording",
+  description: `Stop recording and save the video file.
+
+Response: { success, path, duration, size }`,
+  category: "debug",
+  input: L.object({
+    window: L.string.describe("Target window ID").optional
+  }),
+  examples: [
+    { name: "stop", input: {}, description: "Stop recording and get file path" }
+  ],
+  hints: "| see: video-start, video-status"
+});
+var videoStatus = endpoint({
+  path: "/video/status",
+  method: "GET",
+  summary: "Check video recording status",
+  description: `Check if video recording is active.
+
+Response: { recording, recordingId?, duration?, window? }`,
+  category: "debug",
+  input: L.object({}),
+  examples: [
+    { name: "check", input: {}, description: "Check recording state" }
+  ],
+  hints: "| see: video-start, video-stop"
+});
+var dialogConfigure = endpoint({
+  path: "/dialog/configure",
+  method: "POST",
+  summary: "Configure native dialog auto-response policy",
+  description: `Set how native browser dialogs (alert, confirm, prompt) are handled.
+
+By default, Haltija intercepts all native dialogs and auto-responds:
+- alert: dismissed immediately
+- confirm: accepted (returns true)
+- prompt: dismissed (returns null)
+
+Configure the policy **before** triggering actions that cause dialogs.
+Each dialog is logged and reported via the dialog/opened push event.
+
+Response: { policy: { alert, confirm, prompt, beforeunload } }`,
+  category: "dialog",
+  input: L.object({
+    alert: L.string.describe('"dismiss" (only option for alerts)').optional,
+    confirm: L.string.describe('"accept" or "dismiss"').optional,
+    prompt: L.any.describe('"dismiss" or { "response": "text" } to auto-fill').optional,
+    beforeunload: L.string.describe('"allow" or "block" \u2014 controls page unload').optional,
+    window: L.string.describe("Target window ID").optional
+  }),
+  examples: [
+    {
+      name: "accept-confirms",
+      input: { confirm: "accept" },
+      description: "Auto-accept all confirm dialogs"
+    },
+    {
+      name: "dismiss-confirms",
+      input: { confirm: "dismiss" },
+      description: "Auto-dismiss (cancel) all confirm dialogs"
+    },
+    {
+      name: "auto-fill-prompt",
+      input: { prompt: { response: "my answer" } },
+      description: "Auto-fill prompt dialogs with text"
+    }
+  ],
+  cli: {
+    name: "dialog-configure",
+    args: [],
+    flags: ["--confirm", "--prompt", "--beforeunload"]
+  }
+});
+var dialogHistory = endpoint({
+  path: "/dialog/history",
+  method: "GET",
+  summary: "Get recent dialog history",
+  description: `Returns a list of recently intercepted native dialogs.
+
+Each entry includes: type (alert/confirm/prompt), message, response given, timestamp.
+Buffer holds the last 50 dialogs.
+
+Response: { history: [{ type, message, defaultValue?, response, timestamp }] }`,
+  category: "dialog",
+  cli: {
+    name: "dialog-history",
+    args: [],
+    isGet: true
+  }
+});
 var status = endpoint({
   path: "/status",
   method: "GET",
@@ -5287,6 +5581,11 @@ var endpoints = {
   testSuite,
   testValidate,
   snapshot,
+  videoStart,
+  videoStop,
+  videoStatus,
+  dialogConfigure,
+  dialogHistory,
   status,
   stats,
   version,
@@ -5761,6 +6060,7 @@ registerHandler(click, async (body, ctx) => {
 registerHandler(query, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
   const response = await ctx.requestFromBrowser("dom", "query", {
+    ref: body.ref,
     selector: body.selector,
     all: body.all
   }, 5000, windowId);
@@ -5778,16 +6078,18 @@ registerHandler(fetchUrl, async (body, ctx) => {
 });
 registerHandler(call, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
-  const selector = JSON.stringify(body.selector);
-  const resolveExpr = `(window.__haltija_resolveSelector || document.querySelector.bind(document))(${selector})`;
+  const ref = body.ref;
+  const selector = body.selector;
   const method = body.method;
   const args = body.args;
+  const resolveExpr = ref ? `window.__haltija_refRegistry?.resolve(${JSON.stringify(ref)})` : `(window.__haltija_resolveSelector || document.querySelector.bind(document))(${JSON.stringify(selector)})`;
+  const targetDesc = ref ? `@${ref}` : selector || "(none)";
   let code;
   if (args !== undefined) {
     const argsJson = JSON.stringify(args);
     code = `(function() {
       const el = ${resolveExpr};
-      if (!el) return { success: false, error: 'Element not found: ${body.selector.replace(/'/g, "\\'")}' };
+      if (!el) return { success: false, error: 'Element not found: ${targetDesc.replace(/'/g, "\\'")}' };
       if (typeof el[${JSON.stringify(method)}] !== 'function') {
         return { success: false, error: 'Method not found: ${method}' };
       }
@@ -5801,7 +6103,7 @@ registerHandler(call, async (body, ctx) => {
   } else {
     code = `(function() {
       const el = ${resolveExpr};
-      if (!el) return { success: false, error: 'Element not found: ${body.selector.replace(/'/g, "\\'")}' };
+      if (!el) return { success: false, error: 'Element not found: ${targetDesc.replace(/'/g, "\\'")}' };
       try {
         const value = el[${JSON.stringify(method)}];
         return { success: true, data: value };
@@ -5817,31 +6119,41 @@ registerHandler(call, async (body, ctx) => {
   return Response.json(response, { headers: ctx.headers });
 });
 registerHandler(drag, async (body, ctx) => {
+  const ref = body.ref;
   const selector = body.selector;
   const deltaX = body.deltaX || 0;
   const deltaY = body.deltaY || 0;
   const duration = body.duration || 300;
   const steps = Math.max(5, Math.floor(duration / 16));
   const windowId = body.window || ctx.targetWindowId;
-  await ctx.requestFromBrowser("eval", "exec", {
-    code: `${qs(selector)}?.scrollIntoView({behavior: "smooth", block: "center"})`
-  }, 5000, windowId);
+  const targetDesc = ref ? `@${ref}` : selector;
+  if (ref) {
+    await ctx.requestFromBrowser("eval", "exec", {
+      code: `(window.__haltija_refRegistry?.resolve(${JSON.stringify(ref)}) || document.body)?.scrollIntoView({behavior: "smooth", block: "center"})`
+    }, 5000, windowId);
+  } else if (selector) {
+    await ctx.requestFromBrowser("eval", "exec", {
+      code: `${qs(selector)}?.scrollIntoView({behavior: "smooth", block: "center"})`
+    }, 5000, windowId);
+  }
   await sleep(100);
-  const inspectResponse = await ctx.requestFromBrowser("dom", "inspect", { selector }, 5000, windowId);
+  const inspectResponse = await ctx.requestFromBrowser("dom", "inspect", { ref, selector }, 5000, windowId);
   if (!inspectResponse.success || !inspectResponse.data) {
-    return Response.json({ success: false, error: "Element not found" }, { headers: ctx.headers });
+    return Response.json({ success: false, error: `Element not found: ${targetDesc}` }, { headers: ctx.headers });
   }
   const box = inspectResponse.data.box;
   const startX = box.x + box.width / 2;
   const startY = box.y + box.height / 2;
   for (const event of ["mouseenter", "mouseover", "mousemove"]) {
     await ctx.requestFromBrowser("events", "dispatch", {
+      ref,
       selector,
       event,
       options: { clientX: startX, clientY: startY }
     }, 5000, windowId);
   }
   await ctx.requestFromBrowser("events", "dispatch", {
+    ref,
     selector,
     event: "mousedown",
     options: { clientX: startX, clientY: startY }
@@ -5926,6 +6238,7 @@ registerHandler(key, async (body, ctx) => {
 registerHandler(inspect, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
   const response = await ctx.requestFromBrowser("dom", "inspect", {
+    ref: body.ref,
     selector: body.selector,
     fullStyles: body.fullStyles,
     matchedRules: body.matchedRules
@@ -5935,6 +6248,7 @@ registerHandler(inspect, async (body, ctx) => {
 registerHandler(inspectAll, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
   const response = await ctx.requestFromBrowser("dom", "inspectAll", {
+    ref: body.ref,
     selector: body.selector,
     limit: body.limit || 10,
     fullStyles: body.fullStyles,
@@ -5944,11 +6258,18 @@ registerHandler(inspectAll, async (body, ctx) => {
 });
 registerHandler(highlight, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
-  await ctx.requestFromBrowser("eval", "exec", {
-    code: `${qs(body.selector)}?.scrollIntoView({behavior: "smooth", block: "center"})`
-  }, 5000, windowId);
+  if (body.ref) {
+    await ctx.requestFromBrowser("eval", "exec", {
+      code: `(window.__haltija_refRegistry?.resolve(${JSON.stringify(body.ref)}) || document.body)?.scrollIntoView({behavior: "smooth", block: "center"})`
+    }, 5000, windowId);
+  } else if (body.selector) {
+    await ctx.requestFromBrowser("eval", "exec", {
+      code: `${qs(body.selector)}?.scrollIntoView({behavior: "smooth", block: "center"})`
+    }, 5000, windowId);
+  }
   await sleep(100);
   const response = await ctx.requestFromBrowser("dom", "highlight", {
+    ref: body.ref,
     selector: body.selector,
     label: body.label,
     color: body.color,
@@ -5966,9 +6287,9 @@ registerHandler(navigate, async (body, ctx) => {
   return Response.json(response, { headers: ctx.headers });
 });
 registerHandler(refresh, async (body, ctx) => {
-  const hard = body.hard ?? false;
+  const soft = body.soft ?? false;
   const windowId = body.window || ctx.targetWindowId;
-  const response = await ctx.requestFromBrowser("navigation", "refresh", { hard }, 5000, windowId);
+  const response = await ctx.requestFromBrowser("navigation", "refresh", { soft }, 5000, windowId);
   return Response.json(response, { headers: ctx.headers });
 });
 registerHandler(tree, async (body, ctx) => {
@@ -5991,6 +6312,7 @@ registerHandler(screenshot, async (body, ctx) => {
     ctx.updateSessionAffinity(windowId);
   }
   const response = await ctx.requestFromBrowser("dom", "screenshot", {
+    ref: body.ref,
     selector: body.selector,
     format: body.format,
     quality: body.quality,
@@ -6004,6 +6326,23 @@ registerHandler(screenshot, async (body, ctx) => {
     ...response,
     window: windowInfo || { id: windowId || "unknown", url: "unknown", title: "unknown" }
   };
+  if (body.file !== false && enrichedResponse.data?.image) {
+    const dataUrl = enrichedResponse.data.image;
+    const match = dataUrl.match(/^data:image\/(\w+);base64,(.+)$/);
+    if (match) {
+      const ext = match[1] === "jpeg" ? "jpg" : match[1];
+      const base64 = match[2];
+      const dir = "/tmp/haltija-screenshots";
+      const { mkdirSync, writeFileSync } = await import("fs");
+      mkdirSync(dir, { recursive: true });
+      const shortId = Math.random().toString(36).slice(2, 6);
+      const filename = `hj-${Date.now()}-${shortId}.${ext}`;
+      const filepath = `${dir}/${filename}`;
+      writeFileSync(filepath, Buffer.from(base64, "base64"));
+      enrichedResponse.data.path = filepath;
+      delete enrichedResponse.data.image;
+    }
+  }
   return Response.json(enrichedResponse, { headers: ctx.headers });
 });
 registerHandler(tabsOpen, async (body, ctx) => {
@@ -6434,11 +6773,13 @@ registerHandler(scroll, async (body, ctx) => {
     };
     const easing = easings[${JSON.stringify(easing)}] || easings['ease-out'];
   `;
-  if (body.selector) {
+  if (body.ref || body.selector) {
+    const resolveCode = body.ref ? `window.__haltija_refRegistry?.resolve(${JSON.stringify(body.ref)})` : `(window.__haltija_resolveSelector || document.querySelector.bind(document))(${JSON.stringify(body.selector)})`;
+    const targetDesc = body.ref ? `@${body.ref}` : body.selector;
     const code = `
       (async () => {
-        const el = (window.__haltija_resolveSelector || document.querySelector.bind(document))(${JSON.stringify(body.selector)});
-        if (!el) return { success: false, error: 'Element not found' };
+        const el = ${resolveCode};
+        if (!el) return { success: false, error: 'Element not found: ${targetDesc}' };
         const rect = el.getBoundingClientRect();
         const blockAlign = ${JSON.stringify(block)};
         let targetY;
@@ -6510,6 +6851,41 @@ registerHandler(scroll, async (body, ctx) => {
     return Response.json({ success: false, error: "Must provide selector, x/y coordinates, or deltaX/deltaY" }, { status: 400, headers: ctx.headers });
   }
 });
+registerHandler(videoStart, async (body, ctx) => {
+  const windowId = body.window || ctx.targetWindowId;
+  const maxDuration = Math.min(body.maxDuration || 60, 300);
+  const response = await ctx.requestFromBrowser("video", "start", { maxDuration }, 1e4, windowId);
+  return Response.json(response, { headers: ctx.headers });
+});
+registerHandler(videoStop, async (body, ctx) => {
+  const windowId = body.window || ctx.targetWindowId;
+  const response = await ctx.requestFromBrowser("video", "stop", {}, 30000, windowId);
+  if (response.success && response.data) {
+    return Response.json({
+      success: true,
+      path: response.data.path,
+      duration: response.data.duration,
+      size: response.data.size,
+      format: response.data.format || "webm"
+    }, { headers: ctx.headers });
+  }
+  return Response.json(response, { headers: ctx.headers });
+});
+registerHandler(videoStatus, async (_body, ctx) => {
+  const windowId = ctx.targetWindowId;
+  const response = await ctx.requestFromBrowser("video", "status", {}, 5000, windowId);
+  return Response.json(response, { headers: ctx.headers });
+});
+registerHandler(dialogConfigure, async (body, ctx) => {
+  const windowId = body.window || ctx.targetWindowId;
+  const response = await ctx.requestFromBrowser("dialog", "configure", body, 5000, windowId);
+  return Response.json(response, { headers: ctx.headers });
+});
+registerHandler(dialogHistory, async (_body, ctx) => {
+  const windowId = ctx.targetWindowId;
+  const response = await ctx.requestFromBrowser("dialog", "history", {}, 5000, windowId);
+  return Response.json(response, { headers: ctx.headers });
+});
 
 // src/api-router.ts
 function isDeprecated(endpoint2) {
@@ -10012,15 +10388,7 @@ var serverConfig = {
             }
             const widgetSessionId = data.payload.serverSessionId;
             if (widgetSessionId && widgetSessionId !== SERVER_SESSION_ID) {
-              console.log(`${LOG_PREFIX} Widget session mismatch (${widgetSessionId} vs ${SERVER_SESSION_ID}), sending reload`);
-              wsTyped.send(JSON.stringify({
-                id: uid(),
-                channel: "system",
-                action: "reload",
-                payload: { reason: "session_mismatch" },
-                timestamp: Date.now(),
-                source: "server"
-              }));
+              console.log(`${LOG_PREFIX} Widget from different session (${widgetSessionId.slice(0, 8)}... vs ${SERVER_SESSION_ID.slice(0, 8)}...), accepting anyway`);
             }
             if (windowId) {
               const recordingSession = activeRecordingSessions.get(windowId);