1/**
2 * Shared event validation for the live helper server.
3 * Extracted for unit testing (insert mode rules).
4 */
5 
6import { canCreateInsert } from './insert-ui.mjs';
7 
8// The accepted visual action values come from the canonical vocabulary so the
9// validator, the picker UI, and the marketing demo never drift. Imported (not
10// just re-exported) so it is also in scope for the validators below.
11import { VISUAL_ACTIONS } from './vocabulary.mjs';
12export { VISUAL_ACTIONS };
13 
14const ID_PATTERN = /^[0-9a-f]{8}$/;
15const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;
16const INSERT_POSITIONS = new Set(['before', 'after']);
17const FORBIDDEN_MANUAL_EDIT_TEXT_CHARS = ['<', '{', '}', '`'];
18 
19function isValidId(v) { return typeof v === 'string' && ID_PATTERN.test(v); }
20function isValidVariantId(v) { return typeof v === 'string' && VARIANT_ID_PATTERN.test(v); }
21 
22function validateManualEditText(newText) {
23  if (typeof newText !== 'string') return null;
24  const hits = FORBIDDEN_MANUAL_EDIT_TEXT_CHARS.filter((char) => newText.includes(char));
25  return hits.length > 0 ? hits : null;
26}
27 
28function validateAnnotationFields(msg) {
29  if (msg.screenshotPath !== undefined && typeof msg.screenshotPath !== 'string') {
30    return 'generate: screenshotPath must be string';
31  }
32  if (msg.comments !== undefined && !Array.isArray(msg.comments)) {
33    return 'generate: comments must be array';
34  }
35  if (msg.strokes !== undefined && !Array.isArray(msg.strokes)) {
36    return 'generate: strokes must be array';
37  }
38  return null;
39}
40 
41function validateInsertGenerate(msg) {
42  if (!msg.insert || typeof msg.insert !== 'object') return 'generate: insert mode requires insert object';
43  if (!INSERT_POSITIONS.has(msg.insert.position)) return 'generate: insert.position must be before or after';
44  const anchor = msg.insert.anchor;
45  if (!anchor || typeof anchor !== 'object') return 'generate: insert.anchor required';
46  if (!anchor.tagName && !anchor.outerHTML && !(Array.isArray(anchor.classes) && anchor.classes.length)) {
47    return 'generate: insert.anchor needs tagName, classes, or outerHTML';
48  }
49  if (!msg.placeholder || typeof msg.placeholder !== 'object') return 'generate: insert mode requires placeholder dimensions';
50  if (!Number.isFinite(msg.placeholder.width) || !Number.isFinite(msg.placeholder.height)) {
51    return 'generate: placeholder width and height must be numbers';
52  }
53  if (!canCreateInsert({
54    prompt: msg.freeformPrompt,
55    comments: msg.comments,
56    strokes: msg.strokes,
57  })) {
58    return 'generate: insert requires freeformPrompt or annotations';
59  }
60  return validateAnnotationFields(msg);
61}
62 
63function validateReplaceGenerate(msg) {
64  if (!msg.action || !VISUAL_ACTIONS.includes(msg.action)) return 'generate: invalid action';
65  if (!msg.element || !msg.element.outerHTML) return 'generate: missing element context';
66  return validateAnnotationFields(msg);
67}
68 
69function validateManualEditEvent(msg, label) {
70  if (!isValidId(msg.id)) return label + ': missing or malformed id';
71  if (!msg.pageUrl || typeof msg.pageUrl !== 'string') return label + ': missing pageUrl';
72  if (!msg.element || typeof msg.element !== 'object') return label + ': missing element';
73  if (!Array.isArray(msg.ops) || msg.ops.length === 0) return label + ': ops must be non-empty array';
74  if (msg.ops.length > 100) return label + ': too many ops (max 100)';
75  for (const op of msg.ops) {
76    if (typeof op.ref !== 'string') return label + ': op.ref required';
77    if (typeof op.tag !== 'string') return label + ': op.tag required';
78    if (typeof op.originalText !== 'string') return label + ': op.originalText required';
79    if (op.deleted !== true && typeof op.newText !== 'string') {
80      return label + ': text op requires newText';
81    }
82    if (typeof op.newText === 'string') {
83      if (op.deleted !== true && op.newText.trim().length === 0) {
84        return label + ': newText cannot be empty';
85      }
86      const forbidden = validateManualEditText(op.newText);
87      if (forbidden) {
88        return label + ': newText cannot contain ' + forbidden.join(' ') + ' (plain text only; ask the AI to insert markup)';
89      }
90    }
91  }
92  return null;
93}
94 
95export function validateEvent(msg) {
96  if (!msg || typeof msg !== 'object' || !msg.type) return 'Missing or invalid message';
97  switch (msg.type) {
98    case 'generate':
99      if (!isValidId(msg.id)) return 'generate: missing or malformed id';
100      if (!Number.isInteger(msg.count) || msg.count < 1 || msg.count > 8) return 'generate: count must be 1-8';
101      if (msg.mode === 'insert') return validateInsertGenerate(msg);
102      return validateReplaceGenerate(msg);
103    case 'accept':
104      if (!isValidId(msg.id)) return 'accept: missing or malformed id';
105      if (!isValidVariantId(msg.variantId)) return 'accept: missing or malformed variantId';
106      if (msg.paramValues !== undefined) {
107        if (typeof msg.paramValues !== 'object' || msg.paramValues === null || Array.isArray(msg.paramValues)) {
108          return 'accept: paramValues must be an object';
109        }
110      }
111      return null;
112    case 'discard':
113      return isValidId(msg.id) ? null : 'discard: missing or malformed id';
114    case 'checkpoint':
115      if (!isValidId(msg.id)) return 'checkpoint: missing or malformed id';
116      if (!Number.isInteger(msg.revision) || msg.revision < 0) return 'checkpoint: revision must be a non-negative integer';
117      if (msg.paramValues !== undefined && (typeof msg.paramValues !== 'object' || msg.paramValues === null || Array.isArray(msg.paramValues))) {
118        return 'checkpoint: paramValues must be an object';
119      }
120      return null;
121    case 'exit':
122      return null;
123    case 'prefetch':
124      if (!msg.pageUrl || typeof msg.pageUrl !== 'string') return 'prefetch: missing pageUrl';
125      return null;
126    case 'manual_edits':
127      return validateManualEditEvent(msg, 'manual_edits');
128    case 'steer':
129      if (!isValidId(msg.id)) return 'steer: missing or malformed id';
130      if (typeof msg.message !== 'string' || !msg.message.trim()) return 'steer: message required';
131      if (msg.message.length > 4000) return 'steer: message too long';
132      if (msg.pageUrl !== undefined && typeof msg.pageUrl !== 'string') return 'steer: pageUrl must be string';
133      return null;
134    default:
135      return 'Unknown event type: ' + msg.type;
136  }
137}
138