novac 2.0.1 → 2.2.0

package/src/core/lexer.js

@@ -2,8 +2,329 @@
  * Nova Lexer v2
  * Removed: backtick template literals
  * Added: f"..." strings, full operator set, type/struct/interface/enum/trait keywords,
- *        numeric separators (1_000_000), &&= ||= ??= logical-assign, get/set keywords
+ *        numeric separators (1_000_000), &&= ||= ??= logical-assign, get/set keywords,
+ *        multi-char escape sequences, \ESCAPE{arg1,arg2} argument escapes,
+ *        40+ built-in escapes including \color{name}, \textType{type}, full ANSI terminal escapes
  */
+
+// ── ANSI Terminal Escape Engine ────────────────────────────────────────────
+// All escape sequences resolve to raw strings at lex time.
+// Custom escapes registered via #register escape NAME pattern
+// or the `register_escape` Classic statement.
+
+// Foreground colors (standard 8 + bright 8 = 16)
+const FG = {
+  black:         '\x1b[30m', red:           '\x1b[31m', green:         '\x1b[32m',
+  yellow:        '\x1b[33m', blue:          '\x1b[34m', magenta:       '\x1b[35m',
+  cyan:          '\x1b[36m', white:         '\x1b[37m',
+  // bright
+  brightblack:   '\x1b[90m', brightred:     '\x1b[91m', brightgreen:   '\x1b[92m',
+  brightyellow:  '\x1b[93m', brightblue:    '\x1b[94m', brightmagenta: '\x1b[95m',
+  brightcyan:    '\x1b[96m', brightwhite:   '\x1b[97m',
+  // aliases
+  grey:          '\x1b[90m', gray:          '\x1b[90m', orange:        '\x1b[33m',
+  pink:          '\x1b[95m', purple:        '\x1b[35m', violet:        '\x1b[35m',
+  lime:          '\x1b[92m', teal:          '\x1b[36m', navy:          '\x1b[34m',
+  maroon:        '\x1b[31m', olive:         '\x1b[33m', aqua:          '\x1b[36m',
+  silver:        '\x1b[37m', gold:          '\x1b[33m', indigo:        '\x1b[34m',
+  coral:         '\x1b[91m', salmon:        '\x1b[91m', khaki:         '\x1b[33m',
+  lavender:      '\x1b[95m', turquoise:     '\x1b[96m', crimson:       '\x1b[31m',
+  ivory:         '\x1b[97m', beige:         '\x1b[97m', tan:           '\x1b[33m',
+  sienna:        '\x1b[31m', amber:         '\x1b[33m', emerald:       '\x1b[32m',
+  ruby:          '\x1b[31m', sapphire:      '\x1b[34m', jade:          '\x1b[32m',
+  default:       '\x1b[39m',
+};
+
+// Background colors
+const BG = {
+  black:         '\x1b[40m', red:           '\x1b[41m', green:         '\x1b[42m',
+  yellow:        '\x1b[43m', blue:          '\x1b[44m', magenta:       '\x1b[45m',
+  cyan:          '\x1b[46m', white:         '\x1b[47m',
+  brightblack:   '\x1b[100m',brightred:     '\x1b[101m',brightgreen:   '\x1b[102m',
+  brightyellow:  '\x1b[103m',brightblue:    '\x1b[104m',brightmagenta: '\x1b[105m',
+  brightcyan:    '\x1b[106m',brightwhite:   '\x1b[107m',
+  grey:          '\x1b[100m',gray:          '\x1b[100m',orange:        '\x1b[43m',
+  pink:          '\x1b[105m',purple:        '\x1b[45m', default:       '\x1b[49m',
+};
+
+// SGR text style codes \textType{type}
+const TEXT_TYPES = {
+  reset:         '\x1b[0m',  bold:          '\x1b[1m',  dim:           '\x1b[2m',
+  italic:        '\x1b[3m',  underline:     '\x1b[4m',  blink:         '\x1b[5m',
+  rapidblink:    '\x1b[6m',  reverse:       '\x1b[7m',  hidden:        '\x1b[8m',
+  strikethrough: '\x1b[9m',
+  // reset variants
+  resetbold:     '\x1b[21m', resetdim:      '\x1b[22m', resetitalic:   '\x1b[23m',
+  resetunderline:'\x1b[24m', resetblink:    '\x1b[25m', resetreverse:  '\x1b[27m',
+  resethidden:   '\x1b[28m', resetstrike:   '\x1b[29m',
+  // extra
+  overline:      '\x1b[53m', resetoverline: '\x1b[55m',
+  doubleunderline:'\x1b[21m',
+  // aliases
+  b:             '\x1b[1m',  i:             '\x1b[3m',  u:             '\x1b[4m',
+  s:             '\x1b[9m',  r:             '\x1b[0m',  inv:           '\x1b[7m',
+};
+
+// All built-in named escape sequences (no args)
+// \name  → value
+const ESCAPE_SEQUENCES = {
+  // classic single-char
+  'n':   '\n',  't':   '\t',  'r':   '\r',  '\\':  '\\',
+  "'":   "'",   '"':   '"',   '0':   '\0',   'a':   '\x07',
+  'b':   '\x08','v':   '\x0B','f':   '\x0C','e':   '\x1b',
+  // ANSI reset / clear
+  'reset':      '\x1b[0m',
+  'clr':        '\x1b[0m',
+  // text styles (no-arg shortcuts)
+  'bold':       '\x1b[1m',
+  'dim':        '\x1b[2m',
+  'italic':     '\x1b[3m',
+  'underline':  '\x1b[4m',
+  'blink':      '\x1b[5m',
+  'rapidblink': '\x1b[6m',
+  'reverse':    '\x1b[7m',
+  'hidden':     '\x1b[8m',
+  'strike':     '\x1b[9m',
+  'overline':   '\x1b[53m',
+  'resetbold':  '\x1b[22m',
+  'resetdim':   '\x1b[22m',
+  'resetitalic':'\x1b[23m',
+  'resetul':    '\x1b[24m',
+  'resetblink': '\x1b[25m',
+  'resetrev':   '\x1b[27m',
+  // cursor movement (fixed)
+  'home':       '\x1b[H',
+  'cls':        '\x1b[2J',          // clear screen
+  'clearline':  '\x1b[2K',          // clear current line
+  'clearright': '\x1b[0K',          // clear line right of cursor
+  'clearleft':  '\x1b[1K',          // clear line left of cursor
+  'cleardown':  '\x1b[0J',          // clear screen below cursor
+  'clearup':    '\x1b[1J',          // clear screen above cursor
+  'savecursor': '\x1b[s',           // save cursor position
+  'restorecursor':'\x1b[u',         // restore cursor position
+  'hidecursor': '\x1b[?25l',        // hide cursor
+  'showcursor': '\x1b[?25h',        // show cursor
+  'cursorup':   '\x1b[1A',
+  'cursordown': '\x1b[1B',
+  'cursorright':'\x1b[1C',
+  'cursorleft': '\x1b[1D',
+  'cursorbol':  '\x1b[0G',          // cursor to beginning of line
+  // terminal modes
+  'altscreen':  '\x1b[?1049h',      // enter alternate screen buffer
+  'mainscreen': '\x1b[?1049l',      // exit alternate screen buffer
+  'wrap':       '\x1b[?7h',         // enable line wrap
+  'nowrap':     '\x1b[?7l',         // disable line wrap
+  // foreground color shortcuts
+  'black':      '\x1b[30m', 'red':       '\x1b[31m', 'green':    '\x1b[32m',
+  'yellow':     '\x1b[33m', 'blue':      '\x1b[34m', 'magenta':  '\x1b[35m',
+  'cyan':       '\x1b[36m', 'white':     '\x1b[37m',
+  // background shortcuts
+  'bgblack':    '\x1b[40m', 'bgred':     '\x1b[41m', 'bggreen':  '\x1b[42m',
+  'bgyellow':   '\x1b[43m', 'bgblue':    '\x1b[44m', 'bgmagenta':'\x1b[45m',
+  'bgcyan':     '\x1b[46m', 'bgwhite':   '\x1b[47m',
+  // misc chars
+  'bell':       '\x07',
+  'tab':        '\t',
+  'cr':         '\r',
+  'lf':         '\n',
+  'crlf':       '\r\n',
+  'null':       '\0',
+  'esc':        '\x1b',
+  'space':      ' ',
+  'nbsp':       '\u00A0',
+  'zwsp':       '\u200B',           // zero-width space
+  'zwnj':       '\u200C',
+  'zwj':        '\u200D',
+  // box-drawing
+  'hline':      '\u2500',           // ─
+  'vline':      '\u2502',           // │
+  'tlcorner':   '\u250C',           // ┌
+  'trcorner':   '\u2510',           // ┐
+  'blcorner':   '\u2514',           // └
+  'brcorner':   '\u2518',           // ┘
+  'ttee':       '\u252C',           // ┬
+  'btee':       '\u2534',           // ┴
+  'ltee':       '\u251C',           // ├
+  'rtee':       '\u2524',           // ┤
+  'cross':      '\u253C',           // ┼
+  // double box
+  'dhline':     '\u2550',           // ═
+  'dvline':     '\u2551',           // ║
+  'dtlcorner':  '\u2554',           // ╔
+  'dtrcorner':  '\u2557',           // ╗
+  'dblcorner':  '\u255A',           // ╚
+  'dbrcorner':  '\u255D',           // ╝
+  // arrows
+  'uarr':       '\u2191',           // ↑
+  'darr':       '\u2193',           // ↓
+  'larr':       '\u2190',           // ←
+  'rarr':       '\u2192',           // →
+  'udarr':      '\u2195',           // ↕
+  'lrarr':      '\u2194',           // ↔
+  // misc unicode
+  'check':      '\u2713',           // ✓
+  'cross2':     '\u2717',           // ✗
+  'bullet':     '\u2022',           // •
+  'ellipsis':   '\u2026',           // …
+  'degree':     '\u00B0',           // °
+  'copyright':  '\u00A9',           // ©
+  'registered': '\u00AE',           // ®
+  'trademark':  '\u2122',           // ™
+  'section':    '\u00A7',           // §
+  'dagger':     '\u2020',           // †
+  'middot':     '\u00B7',           // ·
+  'endash':     '\u2013',           // –
+  'emdash':     '\u2014',           // —
+};
+
+// Argument-taking built-in escape handlers: \NAME{arg1, arg2, ...} → string
+// Each is a function (args: string[]) → string
+const ESCAPE_HANDLERS = {
+  // \color{name}  — set foreground color by name
+  color: (args) => {
+    const raw  = (args[0] || '').trim();
+    // reassemble if split on inner comma: rgb:255, 100, 0 → rgb:255,100,0
+    const name = (args.length > 1 && (raw.startsWith('rgb:') || raw.startsWith('256:')))
+      ? args.join(',').toLowerCase().replace(/\s/g,'')
+      : raw.toLowerCase();
+    if (FG[name]) return FG[name];
+    // 256-color: \color{256:N}
+    if (name.startsWith('256:')) return `\x1b[38;5;${name.slice(4)}m`;
+    // RGB: \color{rgb:R,G,B}
+    if (name.startsWith('rgb:')) { const [r,g,b] = name.slice(4).split(','); return `\x1b[38;2;${r};${g};${b}m`; }
+    // hex: \color{#RRGGBB}
+    if (name.startsWith('#') && name.length === 7) {
+      const r = parseInt(name.slice(1,3),16), g = parseInt(name.slice(3,5),16), b = parseInt(name.slice(5,7),16);
+      return `\x1b[38;2;${r};${g};${b}m`;
+    }
+    return FG.default;
+  },
+  // \bg{name}  — set background color by name
+  bg: (args) => {
+    const raw  = (args[0] || '').trim();
+    const name = (args.length > 1 && (raw.startsWith('rgb:') || raw.startsWith('256:')))
+      ? args.join(',').toLowerCase().replace(/\s/g,'')
+      : raw.toLowerCase();
+    if (BG[name]) return BG[name];
+    if (name.startsWith('256:')) return `\x1b[48;5;${name.slice(4)}m`;
+    if (name.startsWith('rgb:')) { const [r,g,b] = name.slice(4).split(','); return `\x1b[48;2;${r};${g};${b}m`; }
+    if (name.startsWith('#') && name.length === 7) {
+      const r = parseInt(name.slice(1,3),16), g = parseInt(name.slice(3,5),16), b = parseInt(name.slice(5,7),16);
+      return `\x1b[48;2;${r};${g};${b}m`;
+    }
+    return BG.default;
+  },
+  // \textType{type}  — set text style / SGR attribute
+  textType: (args) => {
+    const t = (args[0] || '').toLowerCase().trim();
+    if (TEXT_TYPES[t]) return TEXT_TYPES[t];
+    // raw SGR code: \textType{33}
+    if (/^\d+$/.test(t)) return `\x1b[${t}m`;
+    return '';
+  },
+  // \sgr{n}  — raw SGR escape: \x1b[Nm
+  sgr: (args) => args.map(a => `\x1b[${a.trim()}m`).join(''),
+  // \cursor{up|down|left|right, N}  — move cursor N cells
+  cursor: (args) => {
+    const dir = (args[0] || '').toLowerCase().trim();
+    const n   = parseInt(args[1]) || 1;
+    const codes = { up:'A', down:'B', right:'C', left:'D', nextline:'E', prevline:'F', col:'G', row:'d' };
+    return codes[dir] ? `\x1b[${n}${codes[dir]}` : '';
+  },
+  // \pos{row,col}  — move cursor to absolute position
+  pos: (args) => {
+    const row = parseInt(args[0]) || 1, col = parseInt(args[1]) || 1;
+    return `\x1b[${row};${col}H`;
+  },
+  // \erase{mode}  — erase display or line
+  erase: (args) => {
+    const mode = (args[0] || 'screen').toLowerCase().trim();
+    const m = { screen:'2J', 'screen-down':'0J', 'screen-up':'1J', line:'2K', 'line-right':'0K', 'line-left':'1K' };
+    return m[mode] ? `\x1b[${m[mode]}` : '';
+  },
+  // \scroll{up|down, N}  — scroll terminal
+  scroll: (args) => {
+    const dir = (args[0] || 'up').toLowerCase().trim();
+    const n   = parseInt(args[1]) || 1;
+    return dir === 'down' ? `\x1b[${n}T` : `\x1b[${n}S`;
+  },
+  // \unicode{codepoint}  — literal unicode char: \unicode{U+1F600} or \unicode{128512}
+  unicode: (args) => {
+    const raw = (args[0] || '').trim().replace(/^U\+/i,'');
+    const cp  = parseInt(raw, 16);
+    return isNaN(cp) ? '' : String.fromCodePoint(cp);
+  },
+  // \hex{HH HH ...}  — raw hex bytes
+  hex: (args) => args.map(a => String.fromCharCode(parseInt(a.trim(),16))).join(''),
+  // \repeat{char, N}  — repeat a character N times
+  repeat: (args) => {
+    const ch = args[0] || ' ', n = parseInt(args[1]) || 1;
+    return ch.repeat(n);
+  },
+  // \pad{text, width, char}  — pad text to width
+  pad: (args) => {
+    const text  = args[0] || '', width = parseInt(args[1]) || 0, ch = args[2] || ' ';
+    return text.padEnd(width, ch);
+  },
+  // \padl{text, width, char}  — left-pad
+  padl: (args) => {
+    const text = args[0] || '', width = parseInt(args[1]) || 0, ch = args[2] || ' ';
+    return text.padStart(width, ch);
+  },
+  // \upper{text}  — uppercase at lex time
+  upper: (args) => (args[0] || '').toUpperCase(),
+  // \lower{text}  — lowercase at lex time
+  lower: (args) => (args[0] || '').toLowerCase(),
+  // \link{url, text}  — OSC 8 hyperlink (supported in iTerm2, Kitty, WezTerm)
+  link: (args) => `\x1b]8;;${args[0] || ''}\x1b\\${args[1] || args[0] || ''}\x1b]8;;\x1b\\`,
+  // \title{text}  — set terminal window title
+  title: (args) => `\x1b]0;${args[0] || ''}\x07`,
+  // \notify{title, body}  — terminal desktop notification (iTerm2/Kitty)
+  notify: (args) => `\x1b]9;${args[0] || ''}${args[1] ? ' ' + args[1] : ''}\x07`,
+  // \img{path, width, height}  — Kitty/iTerm2 inline image protocol stub
+  img: (args) => `\x1b]1337;File=inline=1;width=${args[1]||'auto'};height=${args[2]||'auto'}:${args[0]||''}\x07`,
+  // \256fg{N}  — 256-color foreground by number
+  '256fg': (args) => `\x1b[38;5;${parseInt(args[0])||0}m`,
+  // \256bg{N}  — 256-color background by number
+  '256bg': (args) => `\x1b[48;5;${parseInt(args[0])||0}m`,
+  // \rgbfg{R,G,B}  — true-color foreground
+  rgbfg: (args) => `\x1b[38;2;${parseInt(args[0])||0};${parseInt(args[1])||0};${parseInt(args[2])||0}m`,
+  // \rgbbg{R,G,B}  — true-color background
+  rgbbg: (args) => `\x1b[48;2;${parseInt(args[0])||0};${parseInt(args[1])||0};${parseInt(args[2])||0}m`,
+};
+
+// Global custom escape registry — populated by #register escape or register_escape statement
+const CUSTOM_ESCAPES = new Map();
+
+/**
+ * processEscape(name, args, source, line, col)
+ * Core escape resolver used by readString() and fstring().
+ * name  - escape name (multi-char allowed)
+ * args  - array of string arguments (empty if no {})
+ * Returns the resolved string value.
+ */
+function processEscape(name, args, line, col) {
+  // 1. custom registry first (allows overriding builtins)
+  if (CUSTOM_ESCAPES.has(name)) {
+    const handler = CUSTOM_ESCAPES.get(name);
+    if (typeof handler === 'function') return handler(args);
+    if (typeof handler === 'string')   return handler;
+  }
+  // 2. argument-taking built-ins
+  if (ESCAPE_HANDLERS[name]) return ESCAPE_HANDLERS[name](args);
+  // 3. no-arg built-ins
+  if (ESCAPE_SEQUENCES[name] !== undefined) return ESCAPE_SEQUENCES[name];
+  // 4. raw octal: \123
+  if (/^[0-7]+$/.test(name)) return String.fromCharCode(parseInt(name, 8));
+  // 5. raw hex: \xFF or \x1b
+  if (/^x[0-9a-fA-F]{1,4}$/.test(name)) return String.fromCharCode(parseInt(name.slice(1), 16));
+  // 6. unicode codepoint: \uXXXX \UXXXXXXXX
+  if (/^u[0-9a-fA-F]{4}$/.test(name)) return String.fromCodePoint(parseInt(name.slice(1), 16));
+  if (/^U[0-9a-fA-F]{8}$/.test(name)) return String.fromCodePoint(parseInt(name.slice(1), 16));
+  // 7. unknown — pass through literally (backslash + name)
+  return '\\' + name;
+}
+
 const HOLLAND = {
   million: 1e6,
   billion: 1e9,
@@ -45,51 +366,74 @@ const LITERALS = {
   nfunc: () => Symbol('NOVA_NULL'),
 };
 
+// ── Dynamic / Meta Variables ────────────────────────────────────────────────
+// These identifiers are intercepted at lex time and emitted as DVAR tokens.
+// The executor resolves them to their runtime values.
+// `default` is a special sentinel: when passed as a function argument, the
+// parameter's declared default value is used instead.
+const DYNAMIC_VARS = new Set([
+  'default',        // use parameter's default value when passed as arg
+  '__line__',       // current source line number
+  '__col__',        // current source column number
+  '__file__',       // absolute path of current file (or "<repl>")
+  '__dirname__',    // directory of current file
+  '__func__',       // name of the enclosing function (or "<top>")
+  '__date__',       // ISO date string (YYYY-MM-DD) at runtime
+  '__time__',       // ISO time string (HH:MM:SS) at runtime
+  '__timestamp__',  // Unix timestamp in ms at runtime
+  '__datetime__',   // Full ISO datetime string at runtime
+  '__version__',    // Nova runtime version
+  '__pid__',        // process.pid
+  '__platform__',   // process.platform
+  '__arch__',       // os.arch()
+  '__argv__',       // process.argv
+  '__env__',        // full process.env object
+  '__scope__',      // reference to current scope
+  '__caller__',     // name of calling function (one level up)
+  '__module__',     // current module name (file stem or "<repl>")
+  '__namespace__',  // active namespace name or null
+  '__random__',     // random float 0..1 (regenerated each read)
+  '__uuid__',       // a fresh UUID each read
+  '__iter__',       // current loop iteration index (-1 outside loops)
+  '__stack__',      // simplified call stack as array
+]);
+
+// Keywords that are ONLY valid inside an @classic { } block.
+// Outside @classic these identifiers are treated as plain IDENTIFIER tokens.
+const CLASSIC_KEYWORDS = new Set([
+  'foreach','temp','keep','echo','gear','engage','sandbox','infer','addto',
+  'macro','snippet','defunc','lambda','compose','partial',
+  'backup','retrieve','describe','classify','rate',
+  'using','unuse',
+  'lend','sstream','declare','session','enter','resu',
+  'warn','info','skip','end','clear','time','keyfunc',
+  'print','log','println','logln','expt','option','env','hello','eval',
+  'register_escape',
+]);
+
 const KEYWORDS = new Set([
   // core
   'var','let','const','class','if','else','for','repeat','unless','until',
   'throw','try','catch','finally','func','function','return','give', 'yield', 'goback',
-  'async','await','do','while', 'Strict',
+  'async','await','do','while', 'block',
   // control
   'switch','case','default','break','continue',
   'of','each','match','when','where','as',
   // meta
-  'assert','emit','on','new','extends',
+  'assert','emit','on','new','extends', 'link',
   // types
   'type','struct','interface','enum','trait','impl',
   // accessors
   'get','set',
-  // nova classic: iteration
-  'foreach',
-  // nova classic: scoping
-  'temp','keep',
-  // nova classic: output
-  'echo',
-  // nova classic: gears
-  'gear','engage',
-  // nova classic: isolation
-  'sandbox','infer',
-  // nova classic: collections
-  'addto',
-  // nova classic: code reuse
-  'macro','block','snippet','defunc','lambda','compose','partial',
-  // nova classic: state
-  'backup','retrieve','rate','classify','describe',
-  // nova classic: feature flags
-  'using','unuse',
-  // nova classic: flow variants
-  'guard','when','with','loop','wait','run',
-  'lend','sstream','declare','session','enter',
-  'namespace','resu','export',
-  'skip','end','clear','time',
-  // nova classic: output
-  'print','log','println','logln',
-  // nova classic: misc
-  'keyfunc','resu',
-  'expt','option',
-  'env',
+  // smart variable modifiers
+  'setter','getter','frozen','lazy','tracked','nonull','once',
+  // numeric constraint types
+  'fnum','fint',
+  // classic compatibility block
+  'classic',
   // misc
-  'hello', 'eval', 'import', 'import_builtin', 'from', 'export', 'default', 'namespace',
+  'import', 'import_builtin', 'from', 'export', 'default', 'namespace',
+  'guard','when','with','loop','wait','run', 'nat',
   // http / server
   'server', 'fetch',
   'post', 'put', 'delete', 'patch', 'head', 'options',
@@ -106,10 +450,25 @@ const KEYWORDS = new Set([
 
 const { CustomError, formatError } = require('./error');
 
-// All operators keyed by their symbol string.
+// Helper: split a comma-separated arg string respecting nested {}, (), []
+function splitArgs(str) {
+  const args = [];
+  let cur = '', depth = 0;
+  for (const ch of str) {
+    if (ch === '{' || ch === '(' || ch === '[') { depth++; cur += ch; }
+    else if (ch === '}' || ch === ')' || ch === ']') { depth--; cur += ch; }
+    else if (ch === ',' && depth === 0) { args.push(cur.trim()); cur = ''; }
+    else cur += ch;
+  }
+  if (cur.trim()) args.push(cur.trim());
+  return args;
+}
+
+
 // Higher precedence = binds tighter.
 const OPERATORS = new Map([
   // assignment (0)
+  ['$',    { precedence: 11, isUnary: true }],
   ['=',    { precedence: 0 }],
   ['=>',   { precedence: 0 }],
   ['|>',   { precedence: 0 }],
@@ -210,11 +569,11 @@ const OPERATORS = new Map([
   ['index',      { precedence: 14 }],
 ]);
 
-const PUNCTUATION = new Set(['(',')','{','}','[',']',',','.',':', ';','?','@','#']);
+const PUNCTUATION = new Set(['(',')','{','}','[',']',',','.',':', ';','?','@','#', '\\']);
 // Note: '...' is already in OPERATORS; '::' as two-char operator below
 
 class Lexer {
-  constructor(source) {
+  constructor(source, classicMode = false) {
     this.source   = source;
     this.position = 0;
     this.line     = 1;
@@ -222,6 +581,7 @@ class Lexer {
     this.tokens   = [];
     this.definitions = new Map();
     this.isSkipping  = false;
+    this.classicMode = classicMode; // true when tokenizing inside @classic { }
   }
 
   // ── preprocessor ──
@@ -267,6 +627,26 @@ class Lexer {
           const name = this.readIdentifier();
           OPERATORS.set(name, JSON.parse(this.readRestOfLine()));
           OPERATORS.get(name).custom = true;
+        } else if (dirArg === 'escape') {
+          // #register escape NAME replacement_string_or_function
+          const escapeName = this.readIdentifier();
+          const rest = this.readRestOfLine().trim();
+          // If rest is a quoted string, use as literal replacement
+          if ((rest.startsWith('"') && rest.endsWith('"')) ||
+              (rest.startsWith("'") && rest.endsWith("'"))) {
+            CUSTOM_ESCAPES.set(escapeName, rest.slice(1, -1)
+              .replace(/\\n/g, '\n').replace(/\\t/g, '\t')
+              .replace(/\\r/g, '\r').replace(/\\x1b/g, '\x1b'));
+          } else if (rest.startsWith('\\x') || rest.startsWith('\\u') || rest.startsWith('\\e')) {
+            // raw escape literal in the directive value
+            CUSTOM_ESCAPES.set(escapeName, rest.replace(/\\x([0-9a-fA-F]{2})/g, (_,h) => String.fromCharCode(parseInt(h,16)))
+              .replace(/\\u([0-9a-fA-F]{4})/g, (_,h) => String.fromCodePoint(parseInt(h,16)))
+              .replace(/\\e/g, '\x1b'));
+          } else {
+            // treat as a literal string value
+            CUSTOM_ESCAPES.set(escapeName, rest);
+          }
+          shouldSkip = false; // readRestOfLine already consumed the line
         }
         break;
       }
@@ -326,6 +706,10 @@ class Lexer {
         if (ident === 'f' && (this.peek() === '"' || this.peek() === "'")) {
           this.fstring(this.advance()); continue;
         }
+        // raw string prefix
+        if (ident === 'r' && (this.peek() === '"' || this.peek() === "'")) {
+          this.rstring(this.advance()); continue;
+        }
         // URL literal: http(s)://, ftp://, ws(s)://, content://, localhost(:port)?
         const col2 = this.column - ident.length - 1;
         const isScheme = ['http','https','ftp','ws','wss','content'].includes(ident);
@@ -368,8 +752,16 @@ class Lexer {
     const col = this.column - 1;
     if (Object.prototype.hasOwnProperty.call(LITERALS, value)) {
       this.addToken('LITERAL', LITERALS[value], col);
+    } else if (DYNAMIC_VARS.has(value)) {
+      // Dynamic/meta variable — bake source location into the token so the
+      // executor can report exact __line__/__col__ without re-scanning.
+      this.tokens.push({ type: 'DVAR', value, line: this.line, column: col, srcLine: this.line, srcCol: col });
     } else if (OPERATORS.has(value)) {
       this.addOperatorToken(value, col);
+    } else if (CLASSIC_KEYWORDS.has(value)) {
+      // Classic keywords only become KEYWORD tokens inside @classic { } blocks.
+      // Outside @classic they are plain identifiers so they don't pollute the core namespace.
+      this.addToken(this.classicMode ? 'KEYWORD' : 'IDENTIFIER', value, col);
     } else {
       this.addToken(KEYWORDS.has(value) ? 'KEYWORD' : 'IDENTIFIER', value, col);
     }
@@ -462,26 +854,75 @@ class Lexer {
     throw this.error('Unterminated block comment');
   }
 
+  // ── escape sequence reader ────────────────────────────────────────────
+  // Called after consuming the leading backslash inside any string context.
+  // Reads the escape name (one or more chars) and optional {arg1, arg2, ...} block.
+  // Returns the resolved string value.
+  readEscape() {
+    // Read escape name: one or more alphanumeric/underscore/dash chars OR a single symbol char
+    let name = '';
+    const first = this.peek();
+    if (!first || first === '\0') return '\\';
+
+    // Single-symbol escapes: \\  \'  \"  \{  \}  \`
+    if (/[\\'"{}` ]/.test(first)) {
+      this.advance();
+      // Let processEscape handle single-char symbol escapes
+      return processEscape(first, [], this.line, this.column);
+    }
+
+    // Read multi-char name
+    while (!this.isAtEnd() && /[A-Za-z0-9_\-]/.test(this.peek())) name += this.advance();
+
+    // No name at all — treat as literal backslash
+    if (!name) {
+      const ch = this.advance();
+      return processEscape(ch, [], this.line, this.column);
+    }
+
+    // Read optional argument block: {arg1, arg2, ...}
+    let args = [];
+    if (this.peek() === '{') {
+      this.advance(); // consume {
+      let argStr = '', depth = 1;
+      while (!this.isAtEnd() && depth > 0) {
+        const ch = this.peek();
+        if (ch === '{') { depth++; argStr += this.advance(); }
+        else if (ch === '}') { depth--; if (depth > 0) argStr += this.advance(); else this.advance(); }
+        else if (ch === '\n') { this.line++; this.column = 1; this.position++; argStr += '\n'; }
+        else argStr += this.advance();
+      }
+      // Split on top-level commas (not nested in brackets/parens)
+      args = splitArgs(argStr);
+    }
+
+    return processEscape(name, args, this.line, this.column);
+  }
+
   readString(quote) {
     const col = this.column;
     let value = '';
     while (!this.isAtEnd() && this.peek() !== quote) {
-      if (this.peek() === '\n') this.line++;
-      if (this.peek() === '\\') {
-        this.advance();
-        const esc = this.advance();
-        switch (esc) {
-          case 'n':  value += '\n'; break; case 't': value += '\t'; break;
-          case 'r':  value += '\r'; break; case '\\': value += '\\'; break;
-          case "'":  value += "'";  break; case '"': value += '"'; break;
-          default:   value += esc;  break;
-        }
-        continue;
-      }
-      value += this.advance();
+      const ch = this.advance();
+      if (ch === '\n') { this.line++; this.column = 1; value += ch; continue; }
+      if (ch === '\\') { value += this.readEscape(); continue; }
+      value += ch;
     }
     if (this.isAtEnd()) throw this.error('Unterminated string literal');
-    this.advance();
+    this.advance(); // consume closing quote
+    this.addToken('STRING', value, col);
+  }
+
+  rstring(quote) {
+    const col = this.column;
+    let value = '';
+    while (!this.isAtEnd() && this.peek() !== quote) {
+      const ch = this.advance();
+      if (ch === '\n') { this.line++; this.column = 1; value += ch; continue; }
+      value += ch;
+    }
+    if (this.isAtEnd()) throw this.error('Unterminated raw string literal');
+    this.advance(); // consume closing quote
     this.addToken('STRING', value, col);
   }
 
@@ -492,7 +933,13 @@ class Lexer {
       const ch = this.advance();
       if (ch === q && this.peek() === next) {
         this.advance();
-        this.addToken('IDENTIFIER', value.trim(), col);
+        const fullName = '__' + value.trim() + '__';
+        if (DYNAMIC_VARS.has(fullName)) {
+          // Emit as DVAR token with baked-in source location
+          this.tokens.push({ type: 'DVAR', value: fullName, line: this.line, column: col, srcLine: this.line, srcCol: col });
+        } else {
+          this.addToken('IDENTIFIER', fullName, col);
+        }
         return;
       }
       value += ch;
@@ -518,7 +965,7 @@ class Lexer {
           if (c === '{') depth++; else if (c === '}') depth--;
           if (depth > 0) expr += c;
         }
-        const innerLexer = new Lexer(expr);
+        const innerLexer = new Lexer(expr, this.classicMode);
         innerLexer.definitions = new Map(this.definitions); // inherit macros
         const innerTokens = innerLexer.tokenize();
         innerTokens.pop();
@@ -526,8 +973,9 @@ class Lexer {
         this.addToken('INTERPOLATION_END', '}', this.column - 1);
         continue;
       }
+      if (ch === '\\') { value += this.readEscape(); continue; }
       if (ch === quote) { flush(); this.addToken('FSTRING_END', 'f"', this.column - 1); return; }
-      if (ch === '\n') this.line++;
+      if (ch === '\n') { this.line++; this.column = 1; value += ch; continue; }
       value += ch;
     }
     throw this.error('Unterminated f-string');
@@ -575,4 +1023,4 @@ class Lexer {
   }
 }
 
-module.exports = { Lexer, KEYWORDS, OPERATORS, PUNCTUATION };
+module.exports = { Lexer, KEYWORDS, CLASSIC_KEYWORDS, OPERATORS, PUNCTUATION, CUSTOM_ESCAPES, processEscape, ESCAPE_SEQUENCES, ESCAPE_HANDLERS, DYNAMIC_VARS };