haltija 1.1.21 → 1.2.2

package/bin/cli-subcommand.mjs

@@ -23,12 +23,14 @@ import { fileURLToPath } from 'url'
 import { formatTree } from './format-tree.mjs'
 import { formatEvents } from './format-events.mjs'
 import { formatTestResult, formatSuiteResult } from './format-test.mjs'
+import { substituteGeneratedVars } from './test-data.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
 // Command hints - generated from api-schema.ts during build
-import hintsJson from './hints.json' with { type: 'json' }
-export const COMMAND_HINTS = hintsJson
+// Use readFileSync instead of JSON import to avoid Node.js ExperimentalWarning
+const hintsPath = join(__dirname, 'hints.json')
+export const COMMAND_HINTS = existsSync(hintsPath) ? JSON.parse(readFileSync(hintsPath, 'utf-8')) : {}
 
 // Endpoints that use GET (everything else is POST)
 export const GET_ENDPOINTS = new Set([
@@ -53,6 +55,9 @@ export const COMPOUND_PATHS = {
   'tabs-open': '/tabs/open',
   'tabs-close': '/tabs/close',
   'tabs-focus': '/tabs/focus',
+  'video-start': '/video/start',
+  'video-stop': '/video/stop',
+  'video-status': '/video/status',
   'recording-start': '/recording/start',
   'recording-stop': '/recording/stop',
   'recording-generate': '/recording/generate',
@@ -66,7 +71,7 @@ export const COMPOUND_PATHS = {
 
 // GET compound endpoints
 export const GET_COMPOUND = new Set([
-  'mutations-status', 'events-stats', 'select-status', 'select-result'
+  'mutations-status', 'events-stats', 'select-status', 'select-result', 'video-status'
 ])
 
 // How to map positional args to body fields for each endpoint
@@ -89,40 +94,54 @@ export const ARG_MAPS = {
   wait: (args) => parseWaitArgs(args),
   call: (args) => ({ ...parseTargetArgs(args.slice(0, 1)), method: args[1], args: args.slice(2).map(tryParseJSON) }),
   fetch: (args) => ({ url: args[0], prompt: args.slice(1).join(' ') || undefined }),
-  screenshot: (args) => parseTargetArgs(args),
+  screenshot: (args) => {
+    const dataUrl = args.includes('--data-url')
+    const filtered = args.filter(a => a !== '--data-url')
+    return { ...parseTargetArgs(filtered), file: !dataUrl }
+  },
   snapshot: (args) => ({ context: args.join(' ') || undefined }),
   select: (args) => ({ action: args[0] }),
   'select-start': () => ({}),
   'select-cancel': () => ({}),
   'select-clear': () => ({}),
-  refresh: (args) => (args.includes('--hard') ? { hard: true } : {}),
+  refresh: (args) => (args.includes('--soft') ? { soft: true } : {}),
   'tabs-open': (args) => ({ url: args[0] }),
   'tabs-close': (args) => ({ window: args[0] }),
   'tabs-focus': (args) => ({ window: args[0] }),
+  'video-start': (args) => {
+    const body = {}
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--maxDuration' || args[i] === '--max-duration') body.maxDuration = num(args[++i])
+    }
+    return body
+  },
+  'video-stop': () => ({}),
   'events-watch': (args) => ({ preset: args[0] || 'interactive' }),
   'mutations-watch': (args) => ({ preset: args[0] || 'smart' }),
   form: (args) => parseTargetArgs(args),
   // send <agent> <message> or send selection/recording
   // --no-submit flag prevents auto-submit (paste only)
   'test-run': (args) => {
-    if (!args.length) { console.error('Usage: hj test-run <file.json> [--vars JSON] [--timeoutMs N] [--allow-failures N]'); process.exit(1) }
+    if (!args.length) { console.error('Usage: hj test-run <file.json> [--vars JSON] [--seed N] [--timeoutMs N] [--allow-failures N]'); process.exit(1) }
     const { files, options, vars } = parseTestArgs(args)
     if (!files.length) { console.error('Usage: hj test-run <file.json>'); process.exit(1) }
-    return { ...readTestFile(files[0], vars), ...options }
+    const { seed, ...restOptions } = options
+    return { ...readTestFile(files[0], vars, seed), ...restOptions }
   },
   'test-validate': (args) => {
     if (!args.length) { console.error('Usage: hj test-validate <file.json> [--vars JSON]'); process.exit(1) }
-    const { files, vars } = parseTestArgs(args)
+    const { files, vars, options } = parseTestArgs(args)
     if (!files.length) { console.error('Usage: hj test-validate <file.json>'); process.exit(1) }
-    return readTestFile(files[0], vars)
+    return readTestFile(files[0], vars, options.seed)
   },
   'test-suite': (args) => {
-    if (!args.length) { console.error('Usage: hj test-suite <dir|file...> [--vars JSON] [--timeoutMs N] [--allow-failures N]'); process.exit(1) }
+    if (!args.length) { console.error('Usage: hj test-suite <dir|file...> [--vars JSON] [--seed N] [--timeoutMs N] [--allow-failures N]'); process.exit(1) }
     const { files: rawFiles, options, vars } = parseTestArgs(args)
     const files = expandTestFiles(rawFiles)
     if (!files.length) { console.error('Error: No test files found'); process.exit(1) }
-    const tests = files.map(f => readTestFile(f, vars).test)
-    return { tests, ...options }
+    const { seed, ...restOptions } = options
+    const tests = files.map(f => readTestFile(f, vars, seed).test)
+    return { tests, ...restOptions }
   },
   'send-message': (args) => {
     const noSubmit = args.includes('--no-submit')
@@ -271,26 +290,48 @@ export function parseModifiers(args) {
 /**
  * Substitute template variables in a string.
  * Replaces ${VAR_NAME} with values from vars object, falling back to env vars.
+ * Also handles ${GEN.TYPE} patterns for generated test data.
  * Unresolved variables are left as-is for debugging.
  */
-export function substituteVars(text, vars = {}) {
-  return text.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+export function substituteVars(text, vars = {}, seed) {
+  // First pass: replace ${GEN.*} patterns with generated test data
+  let genInfo = null
+  if (/\$\{GEN\./i.test(text)) {
+    genInfo = substituteGeneratedVars(text, seed)
+    text = genInfo.result
+  }
+
+  // Second pass: replace ${VAR_NAME} with explicit vars / env vars
+  const result = text.replace(/\$\{([^}]+)\}/g, (match, varName) => {
     const trimmed = varName.trim()
     if (trimmed in vars) return vars[trimmed]
     if (trimmed in process.env) return process.env[trimmed]
     return match  // Leave unresolved for debugging
   })
+
+  return { text: result, genInfo }
 }
 
 /** Read a test JSON file, returning { test: <parsed> }. Applies template variable substitution. */
-function readTestFile(filePath, vars = {}) {
+function readTestFile(filePath, vars = {}, seed) {
   if (!existsSync(filePath)) {
     console.error(`Error: File not found: ${filePath}`)
     process.exit(1)
   }
   try {
     const content = readFileSync(filePath, 'utf-8')
-    const processed = substituteVars(content, vars)
+    const { text: processed, genInfo } = substituteVars(content, vars, seed)
+
+    // Report generated values if any
+    if (genInfo && Object.keys(genInfo.generated).length > 0) {
+      const dim = (s) => `\x1b[2m${s}\x1b[0m`
+      console.error(dim(`[test-data] seed: ${genInfo.seed}`))
+      for (const [key, value] of Object.entries(genInfo.generated)) {
+        const display = value.length > 60 ? value.slice(0, 57) + '...' : value
+        console.error(dim(`  ${key} = ${JSON.stringify(display)}`))
+      }
+    }
+
     const parsed = JSON.parse(processed)
     return { test: parsed }
   } catch (err) {
@@ -319,6 +360,9 @@ export function parseTestArgs(args) {
     } else if (arg === '--step-delay' && args[i + 1]) {
       options.stepDelay = parseInt(args[i + 1], 10)
       i += 2
+    } else if (arg === '--seed' && args[i + 1]) {
+      options.seed = parseInt(args[i + 1], 10)
+      i += 2
     } else if (arg === '--vars' && args[i + 1]) {
       // Parse JSON object of variables: --vars '{"APP_URL": "http://localhost:5050"}'
       try {
@@ -462,8 +506,14 @@ async function startServerInBackground(port) {
 export async function runSubcommand(subcommand, subArgs, port = '8700') {
   const baseUrl = `http://localhost:${port}`
   const jsonOutput = subArgs.includes('--json')
-  // Remove --json from subArgs before processing
-  const filteredArgs = subArgs.filter(a => a !== '--json')
+  // Remove --json and extract --window before processing
+  let filteredArgs = subArgs.filter(a => a !== '--json')
+  let targetWindowId = undefined
+  const windowIdx = filteredArgs.indexOf('--window')
+  if (windowIdx !== -1) {
+    targetWindowId = filteredArgs[windowIdx + 1]
+    filteredArgs = [...filteredArgs.slice(0, windowIdx), ...filteredArgs.slice(windowIdx + 2)]
+  }
 
   // Check if server is running, auto-start if not
   if (!(await isServerRunning(port))) {
@@ -517,18 +567,15 @@ export async function runSubcommand(subcommand, subArgs, port = '8700') {
     }
   }
 
-  // Handle window targeting via --window flag
-  const windowIdx = filteredArgs.indexOf('--window')
-  if (windowIdx !== -1 && filteredArgs[windowIdx + 1]) {
-    const windowId = filteredArgs[windowIdx + 1]
+  // Handle window targeting via --window flag (extracted earlier)
+  if (targetWindowId) {
     if (isGet) {
-      // Append as query param for GET
       const url = new URL(path, baseUrl)
-      url.searchParams.set('window', windowId)
+      url.searchParams.set('window', targetWindowId)
       return doRequest(url.toString(), 'GET', undefined, { subcommand, jsonOutput })
     } else {
       if (!body) body = {}
-      body.window = windowId
+      body.window = targetWindowId
     }
   }
 
@@ -560,6 +607,18 @@ async function doRequest(url, method, body, context = {}) {
         console.log(formatTestResult(json))
       } else if (!jsonOutput && subcommand === 'test-suite' && json.results) {
         console.log(formatSuiteResult(json))
+      } else if (!jsonOutput && subcommand === 'screenshot' && json.data?.path) {
+        const bold = (s) => `\x1b[1m${s}\x1b[0m`
+        const dim = (s) => `\x1b[2m${s}\x1b[0m`
+        console.log(bold(json.data.path))
+        const meta = [json.data.width && json.data.height ? `${json.data.width}×${json.data.height}` : null, json.data.format, json.data.source].filter(Boolean).join(', ')
+        if (meta) console.log(dim(meta))
+      } else if (!jsonOutput && subcommand === 'video-stop' && json.data?.path) {
+        const bold = (s) => `\x1b[1m${s}\x1b[0m`
+        const dim = (s) => `\x1b[2m${s}\x1b[0m`
+        console.log(bold(json.data.path))
+        const meta = [json.data.duration ? `${json.data.duration.toFixed(1)}s` : null, json.data.size ? `${(json.data.size / 1024).toFixed(0)}KB` : null, json.data.format].filter(Boolean).join(', ')
+        if (meta) console.log(dim(meta))
       } else {
         console.log(JSON.stringify(json, null, 2))
       }
@@ -602,6 +661,7 @@ export const KNOWN_COMMANDS = new Set([
   'screenshot', 'snapshot', 'highlight', 'unhighlight',
   'select-start', 'select-result', 'select-cancel', 'select-clear',
   'windows', 'tabs-open', 'tabs-close', 'tabs-focus',
+  'video-start', 'video-stop', 'video-status',
   'recording', 'recording-start', 'recording-stop', 'recording-generate', 'recordings',
   'test-run', 'test-validate', 'test-suite',
   'send', 'send-message', 'send-selection', 'send-recording',
@@ -676,7 +736,7 @@ Subcommands (replace curl with simple commands):
 
   ${bold('Navigate')}
     navigate <url>                 Go to URL
-    refresh [--hard]               Reload page
+    refresh [--soft]               Reload page (hard by default)
     location                       Current URL and title
 
   ${bold('Observe')}
@@ -693,10 +753,13 @@ Subcommands (replace curl with simple commands):
     fetch <url> [prompt]           Fetch and process URL
 
   ${bold('Capture')}
-    screenshot [@ref|selector]     Take screenshot
+    screenshot [@ref|selector]     Take screenshot (saves to /tmp)
     snapshot [context]             Full page state capture
     highlight <@ref|selector>      Highlight element
     unhighlight                    Remove highlights
+    video-start [--maxDuration s]  Start video recording
+    video-stop                     Stop recording, get file path
+    video-status                   Check recording state
 
   ${bold('Selection')}
     select-start                   Begin region selection

package/bin/hints.json

@@ -1,20 +1,25 @@
 {
   "tree": "-d 5 (deeper), --compact, \"#selector\" | see: inspect, query, click",
-  "query": "\"selector\", --all | see: tree, inspect",
+  "query": "@ref or \"selector\", --all | see: tree, inspect",
+  "inspect": "@ref or \"selector\", --styles, --rules, --ancestors | see: tree, query",
   "click": "@ref or \"selector\", :text(Button), --diff | see: tree, wait, type",
   "type": "@ref, --clear, --humanlike false (fast) | see: click, key",
   "key": "<key> --ctrl --shift --alt --meta, --repeat 3 | see: type, click",
-  "drag": "\"selector\" <deltaX> <deltaY>, --duration 500 | see: click, scroll",
-  "highlight": "\"selector\", --label \"text\", --color #f00, --duration 3000 | see: unhighlight, screenshot",
-  "scroll": "\"selector\" or <deltaY>, --duration 500 | see: click, wait",
+  "drag": "@ref or \"selector\" <deltaX> <deltaY>, --duration 500 | see: click, scroll",
+  "highlight": "@ref or \"selector\", --label \"text\", --color #f00, --duration 3000 | see: unhighlight, screenshot",
+  "scroll": "@ref or \"selector\" or <deltaY>, --duration 500 | see: click, wait",
   "wait": "\"selector\", --text \"content\", --timeout 5000 | see: click, navigate",
   "events": "events-watch first | see: recording, console, mutations-watch",
   "eval": "\"code\" (returns result) | see: console, snapshot",
+  "call": "@ref or \"selector\" <method>, --args [...]  | see: eval, inspect",
   "screenshot": "[selector], --scale 0.5, --maxWidth 800 | see: highlight, snapshot",
   "windows": "--json | see: tabs-open, tabs-close, tabs-focus, status",
   "tabs-open": "[url] | see: tabs-focus, tabs-close, windows",
   "tabs-close": "<window-id> | see: windows, tabs-focus, tabs-open",
   "tabs-focus": "<window-id> | see: windows, tabs-close, tabs-open",
   "recording": "start, stop, list, replay <id|index> | see: test-run, events",
+  "video-start": "--maxDuration 120 | see: video-stop, video-status, screenshot",
+  "video-stop": "| see: video-start, video-status",
+  "video-status": "| see: video-start, video-stop",
   "status": "--json | see: windows, stats, console"
 }

package/bin/hj.mjs

@@ -10,7 +10,7 @@
  *   hj status            # Server status
  */
 
-import { runSubcommand, isSubcommand, getSuggestion, listSubcommands } from './cli-subcommand.mjs'
+import { runSubcommand, isSubcommand, getSuggestion, listSubcommands, COMMAND_HINTS } from './cli-subcommand.mjs'
 
 const args = process.argv.slice(2)
 
@@ -42,7 +42,13 @@ const subArgs = args.slice(1).filter(a => a !== '--window' || true) // keep all
 if (!isSubcommand(subcommand)) {
   const suggestion = getSuggestion(subcommand)
   if (suggestion === '--help') {
-    console.log(listSubcommands())
+    // hj help <topic> — filter help output by topic
+    const topic = args[1]
+    if (topic) {
+      filterHelp(topic)
+    } else {
+      console.log(listSubcommands())
+    }
     process.exit(0)
   }
   
@@ -57,3 +63,56 @@ if (!isSubcommand(subcommand)) {
 } else {
   runSubcommand(subcommand, subArgs, port)
 }
+
+function filterHelp(topic) {
+  const bold = (s) => `\x1b[1m${s}\x1b[0m`
+  const dim = (s) => `\x1b[2m${s}\x1b[0m`
+  const needle = topic.toLowerCase()
+  const helpText = listSubcommands()
+  const lines = helpText.split('\n')
+
+  const matches = []
+  let currentCategory = ''
+
+  for (const line of lines) {
+    // Detect category headers (bold ANSI text with no leading spaces beyond the initial 2)
+    if (line.match(/^\s{2}\x1b\[1m/)) {
+      currentCategory = line
+      continue
+    }
+
+    // Match content lines against topic
+    const stripped = line.replace(/\x1b\[[0-9;]*m/g, '').toLowerCase()
+    if (stripped.trim() && stripped.includes(needle)) {
+      matches.push({ category: currentCategory, line })
+    }
+  }
+
+  if (matches.length === 0) {
+    console.log(`No commands matching '${topic}'.`)
+    console.log(`Run ${dim('hj help')} to see all commands.`)
+    return
+  }
+
+  console.log(`\nCommands matching '${bold(topic)}':\n`)
+  let lastCategory = ''
+  for (const m of matches) {
+    if (m.category && m.category !== lastCategory) {
+      console.log(m.category)
+      lastCategory = m.category
+    }
+    console.log(m.line)
+  }
+
+  // Also show matching hints
+  const hintMatches = Object.entries(COMMAND_HINTS).filter(([cmd, hint]) =>
+    cmd.toLowerCase().includes(needle) || hint.toLowerCase().includes(needle)
+  )
+  if (hintMatches.length > 0) {
+    console.log(`\n  ${bold('Hints')}`)
+    for (const [cmd, hint] of hintMatches) {
+      console.log(`    ${bold(cmd.padEnd(28))} ${dim(hint)}`)
+    }
+  }
+  console.log('')
+}

package/bin/test-data.mjs

@@ -0,0 +1,291 @@
+/**
+ * Test Data Generators (Node.js / CLI version)
+ *
+ * Lightweight port of src/test-data.ts for use in bin/cli-subcommand.mjs.
+ * Produces deterministic, recognizable test data from a seed.
+ *
+ * Usage:
+ *   import { createTestDataGenerator, substituteGeneratedVars } from './test-data.mjs'
+ *   const gen = createTestDataGenerator(42)
+ *   gen.generate('EMAIL')  // "tessia.7f3a@haltija-test.example"
+ */
+
+// ============================================
+// Seeded PRNG (xorshift32)
+// ============================================
+
+function xorshift32(state) {
+  let s = state | 0
+  s ^= s << 13
+  s ^= s >>> 17
+  s ^= s << 5
+  return [s >>> 0, s >>> 0]
+}
+
+class SeededRandom {
+  constructor(seed) {
+    this.state = (seed === 0 ? 1 : seed) >>> 0
+  }
+  next() {
+    const [value, newState] = xorshift32(this.state)
+    this.state = newState
+    return value / 0x100000000
+  }
+  int(min, max) {
+    return min + Math.floor(this.next() * (max - min + 1))
+  }
+  pick(arr) {
+    return arr[this.int(0, arr.length - 1)]
+  }
+  hex(len) {
+    let s = ''
+    for (let i = 0; i < len; i++) s += this.int(0, 15).toString(16)
+    return s
+  }
+}
+
+// ============================================
+// Data pools
+// ============================================
+
+const FIRST_NAMES = [
+  'Tessia', 'Testopher', 'Testina', 'Qadir', 'Qaleen',
+  'Checkov', 'Validia', 'Assertia', 'Debugson', 'Mockwell',
+  'Fixturia', 'Stubson', 'Spectra', 'Suitewell', 'Runley',
+  'Passandra', 'Failsworth', 'Edgeworth', 'Boundara', 'Flaxton',
+]
+
+const WORDS = [
+  'quick', 'brown', 'fox', 'lazy', 'dog', 'test', 'data',
+  'jumps', 'over', 'fence', 'under', 'bridge', 'through',
+  'forest', 'around', 'mountain', 'beside', 'river', 'across',
+  'valley', 'between', 'clouds', 'above', 'ocean', 'below',
+]
+
+const COMPANIES = [
+  'Haltija Test Corp', 'QA Industries', 'Assertion Labs',
+  'Testify Inc', 'Validate Co', 'Fixture Holdings',
+  'Mock & Sons', 'Spec Systems', 'Check Group', 'Edge Corp',
+]
+
+const STREETS = [
+  'Test Avenue', 'QA Boulevard', 'Assertion Lane', 'Validate Street',
+  'Debug Drive', 'Fixture Road', 'Mock Court', 'Spec Way',
+  'Check Circle', 'Edge Parkway', 'Suite Plaza', 'Run Terrace',
+]
+
+const CITIES = [
+  'Testville', 'QA City', 'Assertonia', 'Validateburg',
+  'Debugton', 'Mockford', 'Specburgh', 'Fixtureopolis',
+]
+
+// ============================================
+// Evil / Adversarial strings
+// ============================================
+
+const EVIL_XSS = [
+  `<script>alert('xss')</script>`,
+  `"><img src=x onerror=alert('xss')>`,
+  `'><svg/onload=alert('xss')>`,
+  `javascript:alert('xss')`,
+  `<img src="x" onerror="alert(document.cookie)">`,
+  `<div onmouseover="alert('xss')">hover me</div>`,
+  `\x3cscript\x3ealert('xss')\x3c/script\x3e`,
+  `<iframe src="javascript:alert('xss')"></iframe>`,
+  `<body onload=alert('xss')>`,
+  `<input onfocus=alert('xss') autofocus>`,
+]
+
+const EVIL_SQL = [
+  `'; DROP TABLE users; --`,
+  `1 OR 1=1`,
+  `' UNION SELECT * FROM users --`,
+  `1; UPDATE users SET role='admin' WHERE 1=1; --`,
+  `' OR '1'='1`,
+  `'; EXEC xp_cmdshell('whoami'); --`,
+  `1' AND (SELECT COUNT(*) FROM users) > 0 --`,
+  `admin'--`,
+  `' OR 1=1 LIMIT 1 --`,
+  `'; INSERT INTO log VALUES('pwned'); --`,
+]
+
+const EVIL_UNICODE = [
+  '\u200B\u200C\u200D\uFEFF',
+  '\u202E\u0052\u0065\u0076\u0065\u0072\u0073\u0065',
+  '\u0410\u0412\u0421',
+  'A\u0300\u0301\u0302\u0303\u0304',
+  '\uFFFD\uFFFD\uFFFD',
+  '\u2028\u2029',
+  '\u0000\u0001\u0002',
+  '\uD800',
+  'a\u034F\u0061',
+  '\u200F\u200E',
+]
+
+const EVIL_EMOJI = [
+  '\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}\u{200D}\u{1F466}',
+  '\u{1F44B}\u{1F3FD}',
+  '\u{1F1FA}\u{1F1F8}',
+  '\u{1F468}\u{200D}\u{1F4BB}',
+  '\u{1F3F3}\uFE0F\u{200D}\u{1F308}',
+  '\u{1F9D1}\u{200D}\u{1F9D1}\u{200D}\u{1F9D2}',
+  '\u{1F600}\u{1F601}\u{1F602}\u{1F603}\u{1F604}',
+  '\u0023\uFE0F\u{20E3}',
+  '\u{1FAE0}',
+  '\u{1F600}\u{1F601}\u{1F602}\u{1F923}\u{1F603}\u{1F604}\u{1F605}\u{1F606}\u{1F607}\u{1F970}',
+]
+
+const EVIL_WHITESPACE = [
+  ' \t\n\r\x0B\x0C',
+  '\u00A0\u2000\u2001\u2002\u2003\u2004',
+  '\u2005\u2006\u2007\u2008\u2009\u200A',
+  '\u3000',
+  '\r\n\r\n\n\r',
+  '\t\t\t\t\t\t\t\t',
+  ' \u00A0 \u00A0 ',
+  '\u205F\u202F',
+  '   \u200B   ',
+  '\u180E\u2060',
+]
+
+const EVIL_NULL = [
+  'null', 'undefined', 'NaN', 'Infinity', '-Infinity',
+  'true', 'false', '0', '-0', '',
+  'None', 'nil', 'NULL', 'void', '[object Object]',
+]
+
+const EVIL_PATH = [
+  '../../etc/passwd',
+  'C:\\windows\\system32\\config\\sam',
+  '/dev/null',
+  '..\\..\\..\\windows\\system32',
+  'file:///etc/passwd',
+  '\\\\server\\share\\file',
+  '/proc/self/environ',
+  'CON', 'PRN', 'AUX', 'NUL',
+]
+
+const EVIL_FORMAT = [
+  '%s%s%s%s%s%s%s%s%s%s',
+  '${7*7}',
+  '{{constructor.constructor("return this")()}}',
+  '#{7*7}',
+  '<%= 7*7 %>',
+  '{{7*7}}',
+  '${toString}',
+  '$(whoami)',
+  '`whoami`',
+  '{${<%[%\'"}}%\\.',
+]
+
+// ============================================
+// Generator
+// ============================================
+
+const ALIASES = {
+  'NAME.FIRST': 'PERSON.FIRST',
+  'NAME.LAST': 'PERSON.LAST',
+  'NAME.FULL': 'PERSON.FULL',
+  'NAME': 'PERSON.FULL',
+  'TEXT.SENTENCE': 'TEXT',
+  'WORD': 'TEXT.SHORT',
+  'INT': 'NUMBER',
+  'ADDRESS.POSTAL': 'ADDRESS.ZIP',
+}
+
+export function createTestDataGenerator(seed) {
+  const actualSeed = seed ?? (Date.now() ^ (Math.random() * 0x100000000)) >>> 0
+  const rng = new SeededRandom(actualSeed)
+  const tag = rng.hex(4)
+  const cache = new Map()
+
+  function canonicalize(type) {
+    const upper = type.toUpperCase()
+    return ALIASES[upper] ?? upper
+  }
+
+  function generate(type) {
+    const key = canonicalize(type)
+    if (cache.has(key)) return cache.get(key)
+    const value = generateFresh(key)
+    cache.set(key, value)
+    return value
+  }
+
+  function generateFresh(upper) {
+    if (upper === 'PERSON.FIRST') return rng.pick(FIRST_NAMES)
+    if (upper === 'PERSON.LAST') return `Haltija-${tag}`
+    if (upper === 'PERSON.FULL') return `${generate('PERSON.FIRST')} ${generate('PERSON.LAST')}`
+    if (upper === 'EMAIL') return `${generate('PERSON.FIRST').toLowerCase()}.${tag}@haltija-test.example`
+    if (upper === 'PHONE') return `+1-555-0${rng.int(100, 199)}`
+    if (upper === 'USERNAME') return `test_${generate('PERSON.FIRST').toLowerCase()}_${tag}`
+    if (upper === 'PASSWORD') return `Test!Pass#${tag}${rng.hex(2)}`
+
+    if (upper === 'TEXT') {
+      const len = rng.int(5, 10)
+      const words = Array.from({ length: len }, () => rng.pick(WORDS))
+      words[0] = words[0][0].toUpperCase() + words[0].slice(1)
+      return words.join(' ') + '.'
+    }
+    if (upper === 'TEXT.SHORT') return rng.pick(WORDS)
+    if (upper === 'TEXT.PARAGRAPH') {
+      return Array.from({ length: rng.int(3, 6) }, () => generateFresh('TEXT')).join(' ')
+    }
+
+    if (upper === 'NUMBER') return String(rng.int(1, 9999))
+    const rangeMatch = upper.match(/^NUMBER\.RANGE\((\d+),\s*(\d+)\)$/)
+    if (rangeMatch) return String(rng.int(parseInt(rangeMatch[1]), parseInt(rangeMatch[2])))
+
+    if (upper === 'UUID') return `hj-${rng.hex(8)}-${rng.hex(4)}-${rng.hex(4)}-${rng.hex(4)}-${rng.hex(12)}`
+
+    if (upper === 'DATE') {
+      const y = rng.int(2024, 2026), m = rng.int(1, 12), d = rng.int(1, 28)
+      return `${y}-${String(m).padStart(2, '0')}-${String(d).padStart(2, '0')}`
+    }
+    if (upper === 'DATE.FUTURE') return new Date(Date.now() + rng.int(1, 365) * 86400000).toISOString().slice(0, 10)
+    if (upper === 'DATE.PAST') return new Date(Date.now() - rng.int(1, 365) * 86400000).toISOString().slice(0, 10)
+
+    if (upper === 'URL') return `https://haltija-test.example/${tag}`
+    if (upper === 'COMPANY') return `${rng.pick(COMPANIES)} ${tag}`
+    if (upper === 'ADDRESS.STREET') return `${rng.int(1, 9999)} ${rng.pick(STREETS)}`
+    if (upper === 'ADDRESS.CITY') return rng.pick(CITIES)
+    if (upper === 'ADDRESS.ZIP') return `555${String(rng.int(0, 99)).padStart(2, '0')}`
+    if (upper === 'ADDRESS.FULL') return `${generateFresh('ADDRESS.STREET')}, ${generateFresh('ADDRESS.CITY')} ${generateFresh('ADDRESS.ZIP')}`
+
+    if (upper === 'EVIL.XSS') return rng.pick(EVIL_XSS)
+    if (upper === 'EVIL.SQL') return rng.pick(EVIL_SQL)
+    if (upper === 'EVIL.UNICODE') return rng.pick(EVIL_UNICODE)
+    if (upper === 'EVIL.EMOJI') return rng.pick(EVIL_EMOJI)
+    if (upper === 'EVIL.WHITESPACE') return rng.pick(EVIL_WHITESPACE)
+    if (upper === 'EVIL.LONG') return 'A'.repeat(10000)
+    if (upper === 'EVIL.EMPTY') return ''
+    if (upper === 'EVIL.NULL') return rng.pick(EVIL_NULL)
+    if (upper === 'EVIL.PATH') return rng.pick(EVIL_PATH)
+    if (upper === 'EVIL.FORMAT') return rng.pick(EVIL_FORMAT)
+    if (upper === 'EVIL') {
+      const cats = ['XSS', 'SQL', 'UNICODE', 'EMOJI', 'WHITESPACE', 'NULL', 'PATH', 'FORMAT']
+      return generateFresh(`EVIL.${rng.pick(cats)}`)
+    }
+
+    return `[unknown:${upper}]`
+  }
+
+  return { generate, seed: actualSeed }
+}
+
+/**
+ * Process a string, replacing all ${GEN.TYPE} patterns with generated values.
+ * Same GEN key produces the same value (memoized). Use .2, .3 etc. for distinct instances.
+ */
+export function substituteGeneratedVars(text, seed) {
+  const gen = createTestDataGenerator(seed)
+  const generated = {}
+
+  const result = text.replace(/\$\{GEN\.([^}]+)\}/g, (_match, type) => {
+    const value = gen.generate(type.trim())
+    generated[`GEN.${type.trim()}`] = value
+    return value
+  })
+
+  return { result, seed: gen.seed, generated }
+}