azeroth-shell 0.0.0-stage → 0.1.1

package/src/domain/macro/describe.ts

@@ -0,0 +1,169 @@
+// Macros in plain English. Pure, no DOM: Build-mode rows, the editor preview and the smoke goldens
+// all read from here. Same voice as the rotation editor's rule rows.
+
+import type { MacroCond, MacroClause, MacroLine, MacroVerb } from './parse.ts';
+import { MACRO_CREATURE_TYPE_LABEL } from './creatureTypes.ts';
+import { describeMacroUnit } from './units.ts';
+import { describeMacroInvSlot } from './slots.ts';
+
+/** What the verb does, as a verb phrase. */
+export const MACRO_VERB_LABEL: Readonly<Record<MacroVerb, string>> = {
+  cast: 'cast',
+  use: 'use',
+  equip: 'equip',
+  equipoh: 'equip in the off hand',
+  target: 'target',
+  petattack: 'send your pet at',
+  petfollow: 'call your pet back',
+  petstay: 'make your pet stay',
+  startattack: 'start attacking',
+  stopattack: 'stop attacking',
+  stopcasting: 'stop casting',
+  unshift: 'leave your form',
+  focus: 'set focus to',
+  clearfocus: 'clear your focus',
+  outfitter: 'change outfit',
+};
+
+/** Verbs that read as a complete sentence on their own (no argument to name). */
+const NO_ARG_VERBS: ReadonlySet<MacroVerb> = new Set<MacroVerb>([
+  'petfollow', 'petstay', 'startattack', 'stopattack', 'stopcasting', 'unshift', 'clearfocus',
+]);
+
+const listOf = (values: readonly string[], join = 'or'): string => {
+  if (values.length <= 1) return values[0] ?? '';
+  return `${values.slice(0, -1).join(', ')} ${join} ${values[values.length - 1]}`;
+};
+
+const pct = (c: MacroCond): string => `${c.cmp === '<' ? 'below' : 'above'} ${c.amount}%`;
+const flat = (c: MacroCond): string => `${c.cmp === '<' ? 'below' : 'above'} ${c.amount}`;
+
+/** The English for one condition. Unknown keys say so rather than reading as satisfied. */
+export function describeMacroCond(cond: MacroCond): string {
+  const v = cond.values;
+  const first = v[0] ?? '';
+  switch (cond.key) {
+    case 'help': return 'the unit is friendly';
+    case 'harm': return 'the unit can be attacked';
+    case 'exists': return 'the unit is there';
+    case 'noexists': return 'the unit is not there';
+    case 'target': return `aimed at ${first}`;
+    case 'dead': return 'the unit is dead';
+    case 'nodead': return 'the unit is alive';
+    case 'combat': return 'you are in combat';
+    case 'nocombat': return 'you are out of combat';
+    case 'stealth': return 'you are stealthed';
+    case 'nostealth': return 'you are not stealthed';
+    case 'stance':
+      return v.length === 1 && v[0] === '0' ? 'you are not in a form' : `you are in form ${listOf(v)}`;
+    case 'nostance':
+      return v.length === 1 && v[0] === '0' ? 'you are in a form' : `you are not in form ${listOf(v)}`;
+    case 'mod': return v.length ? `${listOf(v.map((m) => m.toUpperCase()))} is held` : 'a modifier is held';
+    case 'nomod':
+    case 'nomodifier': return 'no modifier is held';
+    case 'modifier': return v.length ? `${listOf(v.map((m) => m.toUpperCase()))} is held` : 'a modifier is held';
+    case 'equipped':
+    case 'worn': return `you have ${listOf(v)} equipped`;
+    case 'noequipped':
+    case 'noworn': return `you have no ${listOf(v)} equipped`;
+    case 'party': return 'the unit is in your party';
+    case 'raid': return 'the unit is in your raid';
+    case 'group': return first === 'raid' ? 'you are in a raid' : first === 'party' ? 'you are in a party' : 'you are grouped';
+    case 'buff': return `the unit has ${first}`;
+    case 'nobuff': return `the unit does not have ${first}`;
+    case 'debuff': return `the unit is affected by ${first}`;
+    case 'nodebuff': return `the unit is not affected by ${first}`;
+    case 'mybuff': return `you have ${first}`;
+    case 'nomybuff': return `you do not have ${first}`;
+    case 'mydebuff': return `you are affected by ${first}`;
+    case 'nomydebuff': return `you are not affected by ${first}`;
+    case 'hp': return `the unit's health is ${pct(cond)}`;
+    case 'myhp': return `your health is ${pct(cond)}`;
+    case 'power': return `the unit's power is ${pct(cond)}`;
+    case 'mypower': return `your power is ${pct(cond)}`;
+    case 'rawpower': return `the unit's power is ${flat(cond)}`;
+    case 'myrawpower': return `your power is ${flat(cond)}`;
+    case 'type': {
+      const known = Object.values(MACRO_CREATURE_TYPE_LABEL)
+        .find((l) => l.toLowerCase() === first.toLowerCase().replace(/_/g, ' '));
+      return `the unit is ${known ?? listOf(v)}`;
+    }
+    case 'isplayer': return 'the unit is a player';
+    case 'isnpc': return 'the unit is an NPC';
+    case 'cooldown': return `${first} is on cooldown`;
+    case 'nocooldown': return `${first} is ready`;
+    case 'channeled': return 'you are channelling';
+    case 'nochanneled': return 'you are not channelling';
+    case 'attacks': return `your target is attacking ${first}`;
+    case 'noattacks': return `your target is not attacking ${first}`;
+    case 'never': return 'never (this condition could not be read)';
+    default: return `"${cond.key}" is not a condition I know`;
+  }
+}
+
+/** One `;` branch, described. */
+export interface MacroBranchDescription {
+  /** What it acts on: a spell/item name, a unit phrase, a `{macro}` call, or ''. */
+  action: string;
+  /** The unit the action is aimed at, when one is named. */
+  unit?: string;
+  /** Every condition, in bracket order. Groups are OR-ed, so they read as "or". */
+  conds: string[];
+  /** True when the branch has more than one OR-group (`[a][b]`). */
+  anyGroup: boolean;
+}
+
+export interface MacroLineDescription {
+  n: number;
+  verb: MacroVerb;
+  verbLabel: string;
+  branches: MacroBranchDescription[];
+}
+
+/** The action phrase for a branch: `{Macro}` call, unit, argument, or nothing. */
+function branchAction(clause: MacroClause, verb: MacroVerb): string {
+  if (clause.call) return `the macro ${clause.call}`;
+  if (clause.arg) {
+    const slot = (verb === 'use' || verb === 'equip' || verb === 'equipoh')
+      ? describeMacroInvSlot(clause.arg) : null;
+    const name = slot ? `your ${slot}` : clause.arg;
+    return clause.noRecast ? `${name} (only if it is not already running)` : name;
+  }
+  if (clause.argUnit) return describeMacroUnit(clause.argUnit);
+  if (NO_ARG_VERBS.has(verb)) return '';
+  if (clause.unit) return describeMacroUnit(clause.unit);
+  return '';
+}
+
+export function describeMacroLine(line: MacroLine): MacroLineDescription {
+  return {
+    n: line.n,
+    verb: line.verb,
+    verbLabel: MACRO_VERB_LABEL[line.verb],
+    branches: line.clauses.map((clause) => {
+      // `@unit` shows as the aim, not as a condition — it is the same information twice.
+      const conds = clause.groups.flat().filter((c) => c.key !== 'target').map(describeMacroCond);
+      const aimed = clause.argUnit && clause.arg ? undefined : clause.unit;
+      return {
+        action: branchAction(clause, line.verb),
+        unit: aimed && (clause.arg || clause.call) ? describeMacroUnit(aimed) : undefined,
+        conds,
+        anyGroup: clause.groups.length > 1,
+      };
+    }),
+  };
+}
+
+/** One-line English for a whole macro line (preview text, goldens, aria labels). */
+export function describeMacroLineText(line: MacroLine): string {
+  const d = describeMacroLine(line);
+  const parts = d.branches.map((b) => {
+    const at = b.unit ? ` at ${b.unit}` : '';
+    const head = `${d.verbLabel}${b.action ? ` ${b.action}` : ''}${at}`;
+    if (!b.conds.length) return head;
+    const joiner = b.anyGroup ? ' or ' : ' and ';
+    return `${head} when ${b.conds.join(joiner)}`;
+  });
+  if (!parts.length) return d.verbLabel;
+  return parts.join('; otherwise ');
+}

package/src/domain/macro/icon.ts

@@ -0,0 +1,60 @@
+// Macro button icon: follow the first /cast or /use unless the player picked one. The question
+// mark is the auto sentinel, as on a new client macro; any other basename is a deliberate pick.
+
+import { parseMacroBody } from './parse.ts';
+import { splitSpellRank } from './snapshot.ts';
+import { MACRO_ICON_FALLBACK } from './types.ts';
+import { sanitizeMacroIcon } from './normalize.ts';
+
+export type MacroIconSpellHit = { icon?: string } | null;
+export type MacroIconItemHit = { icon?: string } | null;
+
+export function macroIconIsCustom(icon: string): boolean {
+  return sanitizeMacroIcon(icon) !== MACRO_ICON_FALLBACK;
+}
+
+/** First icon the body names: pinned #showtooltip, else the first /cast /use /equip argument. */
+export function suggestedMacroIcon(
+  body: string,
+  resolveSpell: (name: string, rank?: number, subtext?: string) => MacroIconSpellHit,
+  resolveItem: (name: string) => MacroIconItemHit,
+): string | null {
+  const fromArg = (raw: string): string | null => {
+    const { name, rank, subtext } = splitSpellRank(raw);
+    if (!name) return null;
+    const spell = resolveSpell(name, rank, subtext);
+    if (spell?.icon) return sanitizeMacroIcon(spell.icon);
+    const item = resolveItem(raw);
+    if (item?.icon) return sanitizeMacroIcon(item.icon);
+    return null;
+  };
+  const prog = parseMacroBody(body);
+  if (prog.tooltip.kind === 'named') {
+    const pinned = fromArg(prog.tooltip.name);
+    if (pinned) return pinned;
+  }
+  for (const line of prog.lines) {
+    if (line.verb !== 'cast' && line.verb !== 'use' && line.verb !== 'equip' && line.verb !== 'equipoh') {
+      continue;
+    }
+    for (const clause of line.clauses) {
+      if (!clause.arg) continue;
+      const hit = fromArg(clause.arg);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+// What to draw. A custom stored icon wins. Otherwise the body suggestion, then the question mark.
+// `liveTipIcon` is the #showtooltip resolution for right now (combat/world bars).
+export function macroDisplayIcon(
+  def: { icon: string; body: string },
+  resolveSpell: (name: string, rank?: number, subtext?: string) => MacroIconSpellHit,
+  resolveItem: (name: string) => MacroIconItemHit,
+  liveTipIcon?: string,
+): string {
+  if (macroIconIsCustom(def.icon)) return sanitizeMacroIcon(def.icon);
+  if (liveTipIcon) return sanitizeMacroIcon(liveTipIcon);
+  return suggestedMacroIcon(def.body, resolveSpell, resolveItem) ?? MACRO_ICON_FALLBACK;
+}

package/src/domain/macro/index.ts

@@ -0,0 +1,20 @@
+// Barrel for the pure macro layer: model + caps, normalize, parse, conditions, plan.
+// Hosts (UI) and the engine import from here; nothing in this folder touches DOM or RNG.
+
+export * from './types.ts';
+export * from './units.ts';
+export * from './normalize.ts';
+export * from './parse.ts';
+export * from './snapshot.ts';
+export * from './weaponTypes.ts';
+export * from './slots.ts';
+export * from './creatureTypes.ts';
+export * from './conditions.ts';
+export * from './plan.ts';
+export * from './describe.ts';
+export * from './compose.ts';
+export * from './templates.ts';
+export * from './icon.ts';
+// The macro -> rotation compiler is pure and light. Its ENV builder (rotationEnv.ts) is kept out of
+// the barrel on purpose: it pulls domain/rotation/build.ts, which server importers must not load.
+export * from './rotation.ts';

package/src/domain/macro/normalize.ts

@@ -0,0 +1,112 @@
+// The one choke point every macro boundary runs: save load, validateSave, save/delete and each
+// press. Total functions that never throw — a tampered store becomes a legal, possibly empty list.
+
+import {
+  MACROS_PER_SCOPE, MACRO_BODY_MAX, MACRO_ICON_FALLBACK, MACRO_LINES_MAX, MACRO_NAME_MAX,
+  isMacroId, macroScopeOf, macroScopePrefix, type MacroDef, type MacroScope,
+} from './types.ts';
+
+/** Printable-only, single line, clamped to the client's 16-char name box. */
+export function sanitizeMacroName(raw: unknown): string {
+  if (typeof raw !== 'string') return '';
+  let out = '';
+  for (const ch of raw) {
+    const code = ch.codePointAt(0)!;
+    // Drop C0/C1 controls (incl. newlines) so a name can never break a row or a label.
+    if (code < 0x20 || (code >= 0x7f && code <= 0x9f)) continue;
+    out += ch;
+    if (out.length >= MACRO_NAME_MAX) break;
+  }
+  return out.trim().slice(0, MACRO_NAME_MAX);
+}
+
+/** Keeps newlines (a body is multi-line), drops other controls, clamps chars AND lines. */
+export function sanitizeMacroBody(raw: unknown): string {
+  if (typeof raw !== 'string') return '';
+  const unified = raw.replace(/\r\n?/g, '\n');
+  let out = '';
+  for (const ch of unified) {
+    const code = ch.codePointAt(0)!;
+    if (code !== 0x0a && (code < 0x20 || (code >= 0x7f && code <= 0x9f))) continue;
+    out += ch;
+    if (out.length >= MACRO_BODY_MAX) break;
+  }
+  const lines = out.split('\n');
+  return (lines.length > MACRO_LINES_MAX ? lines.slice(0, MACRO_LINES_MAX) : lines)
+    .join('\n')
+    .slice(0, MACRO_BODY_MAX);
+}
+
+// An icon is a basename under /icons — never a path, never a URL. Anything else becomes the question mark,
+// so a tampered icon cannot point an <img src> anywhere off-origin.
+export function sanitizeMacroIcon(raw: unknown): string {
+  if (typeof raw !== 'string') return MACRO_ICON_FALLBACK;
+  const low = raw.trim().toLowerCase();
+  if (!low || low.length > 64) return MACRO_ICON_FALLBACK;
+  return /^[a-z0-9_]+$/.test(low) ? low : MACRO_ICON_FALLBACK;
+}
+
+// Adopt one untrusted macro. `id` is kept only when well-formed AND in `scope`; callers needing a
+// fresh id pass keepId: false. A macro with no name is not a macro, so it returns null.
+export function normalizeMacro(
+  raw: unknown,
+  scope: MacroScope,
+  opts: { keepId?: boolean } = {},
+): MacroDef | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const r = raw as Record<string, unknown>;
+  const name = sanitizeMacroName(r.name);
+  if (!name) return null;
+  const keepId = opts.keepId !== false;
+  const id = keepId && isMacroId(r.id) && macroScopeOf(r.id as string) === scope
+    ? (r.id as string)
+    : '';
+  return { id, name, icon: sanitizeMacroIcon(r.icon), body: sanitizeMacroBody(r.body) };
+}
+
+// Adopt an untrusted macro LIST for one scope: drops junk rows, re-issues missing/duplicate/ cross-scope
+// ids in list order, and caps the list at 18. Idempotent.
+export function normalizeMacros(raw: unknown, scope: MacroScope): MacroDef[] {
+  if (!Array.isArray(raw)) return [];
+  const out: MacroDef[] = [];
+  const used = new Set<string>();
+  const pending: MacroDef[] = [];
+  for (const row of raw) {
+    if (out.length + pending.length >= MACROS_PER_SCOPE) break;
+    const def = normalizeMacro(row, scope);
+    if (!def) continue;
+    if (def.id && !used.has(def.id)) {
+      used.add(def.id);
+      out.push(def);
+    } else {
+      pending.push({ ...def, id: '' });
+    }
+  }
+  // Second pass keeps original list ORDER while handing the id-less rows the free slots.
+  const p = macroScopePrefix(scope);
+  let next = 1;
+  for (const def of pending) {
+    while (next <= MACROS_PER_SCOPE && used.has(`${p}${next}`)) next++;
+    if (next > MACROS_PER_SCOPE) break;
+    const id = `${p}${next}`;
+    used.add(id);
+    out.push({ ...def, id });
+  }
+  // Restore the caller's order: rows that already had ids kept their place above, so sort by
+  // the index they appeared at. Cheap and stable for <= 18 rows.
+  const orderOf = new Map<MacroDef, number>();
+  let i = 0;
+  for (const row of raw) {
+    const def = out.find((d) => !orderOf.has(d) && sameSource(d, row));
+    if (def) orderOf.set(def, i);
+    i++;
+  }
+  return out.sort((a, b) => (orderOf.get(a) ?? 0) - (orderOf.get(b) ?? 0));
+}
+
+/** Row identity for order restoration: name + body is enough for <= 18 hand-made macros. */
+function sameSource(def: MacroDef, raw: unknown): boolean {
+  if (!raw || typeof raw !== 'object') return false;
+  const r = raw as Record<string, unknown>;
+  return sanitizeMacroName(r.name) === def.name && sanitizeMacroBody(r.body) === def.body;
+}

package/src/domain/macro/parse.ts

@@ -0,0 +1,316 @@
+// Macro body -> a bounded program. Pure and TOTAL: any string parses and problems come back as
+// issues. Fixed regexes only. The grammar follows the 1.12 client plus Roid-Macros.
+
+import {
+  MACRO_CLAUSES_MAX, MACRO_CONDS_MAX, MACRO_GROUPS_MAX, MACRO_LINES_MAX, MACRO_NAME_MAX,
+} from './types.ts';
+import { macroUnitToken, parseMacroUnit, type MacroUnitRef } from './units.ts';
+
+export type MacroVerb =
+  | 'cast' | 'use' | 'equip' | 'equipoh' | 'outfitter' | 'target'
+  | 'petattack' | 'petfollow' | 'petstay'
+  | 'startattack' | 'stopattack' | 'stopcasting' | 'unshift'
+  | 'focus' | 'clearfocus';
+
+/** One condition inside a `[…]` group. `values` are `/`-separated, `_` already read as space. */
+export interface MacroCond {
+  key: string;
+  values: string[];
+  /** Present for `key>N` / `key<N` (Roid's bigger=1 / 0). */
+  cmp?: '>' | '<';
+  amount?: number;
+}
+
+/** One `;` branch: OR-ed condition groups plus what to do when they pass. */
+export interface MacroClause {
+  /** `[a b][c]` → [[a,b],[c]]. Groups OR, conditions inside a group AND. */
+  groups: MacroCond[][];
+  // Last `@unit` in the clause (serialize / describe). Press and auto-combat read each group's own unit via
+  // macroGroupUnit — a later `[harm]` does not inherit a sibling `@mouseover`.
+  unit?: MacroUnitRef;
+  /** Spell / item / macro-name argument, `!` and `{}` already stripped. */
+  arg: string;
+  // The argument when it is itself a unit (/target @targettarget) — the FINAL target. Separate from
+  // `unit`, so `/target [harm @mouseover] Ragnaros` checks mouseover and selects Ragnaros.
+  argUnit?: MacroUnitRef;
+  /** `!Mind Flay` — skip while that channel / autorepeat is already running. */
+  noRecast: boolean;
+  /** `{Other}` — run that macro instead of casting `arg`. */
+  call?: string;
+}
+
+export interface MacroLine {
+  /** 1-based body line, so the editor can point at it. */
+  n: number;
+  verb: MacroVerb;
+  clauses: MacroClause[];
+}
+
+export interface MacroParseIssue { line: number; message: string }
+
+export type MacroTooltipDirective =
+  | { kind: 'none' }
+  | { kind: 'dynamic' }
+  | { kind: 'named'; name: string };
+
+export interface MacroProgram {
+  tooltip: MacroTooltipDirective;
+  lines: MacroLine[];
+  issues: MacroParseIssue[];
+}
+
+/** Slash command -> verb. Aliases match what the client accepts. */
+const VERBS: Record<string, MacroVerb> = {
+  cast: 'cast',
+  use: 'use',
+  equip: 'equip',
+  equipoh: 'equipoh',
+  outfitter: 'outfitter',
+  equipoffhand: 'equipoh',
+  target: 'target',
+  petattack: 'petattack',
+  petfollow: 'petfollow',
+  petstay: 'petstay',
+  startattack: 'startattack',
+  stopattack: 'stopattack',
+  stopcasting: 'stopcasting',
+  unshift: 'unshift',
+  cancelform: 'unshift',
+  focus: 'focus',
+  clearfocus: 'clearfocus',
+};
+
+/** Commands that only exist from TBC on — named so the editor can say why, not just "unknown". */
+const POST_VANILLA: Record<string, string> = {
+  castsequence: '/castsequence is a TBC command; vanilla macros have no sequences',
+  castrandom: '/castrandom is a TBC command',
+  cancelaura: '/cancelaura is a TBC command; use /unshift for forms',
+  click: '/click is not supported',
+  run: '/run and /script are not supported: a macro is data here, not code',
+  script: '/run and /script are not supported: a macro is data here, not code',
+};
+
+/** Verbs whose clause must name something (a spell, an item, a macro, or a unit). */
+const NEEDS_ARG: ReadonlySet<MacroVerb> = new Set<MacroVerb>(['cast', 'use', 'equip', 'equipoh', 'outfitter', 'target']);
+/** Verbs that read a unit from `@unit` or a bare unit token. */
+const UNIT_VERBS: ReadonlySet<MacroVerb> = new Set<MacroVerb>(['target', 'focus', 'petattack']);
+
+const SHOWTOOLTIP = '#showtooltip';
+
+/** Split one condition group into at most MACRO_CONDS_MAX tokens (spaces or commas). */
+function condTokens(text: string): string[] {
+  const out: string[] = [];
+  for (const raw of text.split(/[\s,]+/)) {
+    const t = raw.trim();
+    if (!t) continue;
+    out.push(t);
+    if (out.length >= MACRO_CONDS_MAX) break;
+  }
+  return out;
+}
+
+/** `key:v1/v2` values: `_` reads as a space (Conditionals.lua:69 gsub "_" -> " "). */
+function condValues(text: string): string[] {
+  const out: string[] = [];
+  for (const raw of text.split('/')) {
+    const v = raw.replace(/_/g, ' ').trim();
+    if (v) out.push(v);
+  }
+  return out;
+}
+
+// Roid's FindDelimeter order: ':' wins, then '>', then '<' (Core.lua:58-79). `=` is accepted as a ':' alias
+// so retail muscle memory (`[target=focus]`) parses too.
+function splitCond(token: string): { key: string; rest: string; cmp?: '>' | '<' } {
+  const colon = token.indexOf(':');
+  if (colon >= 0) return { key: token.slice(0, colon), rest: token.slice(colon + 1) };
+  const eq = token.indexOf('=');
+  if (eq >= 0) return { key: token.slice(0, eq), rest: token.slice(eq + 1) };
+  const gt = token.indexOf('>');
+  if (gt >= 0) return { key: token.slice(0, gt), rest: token.slice(gt + 1), cmp: '>' };
+  const lt = token.indexOf('<');
+  if (lt >= 0) return { key: token.slice(0, lt), rest: token.slice(lt + 1), cmp: '<' };
+  return { key: token, rest: '' };
+}
+
+interface GroupParse { groups: MacroCond[][]; unit?: MacroUnitRef; rest: string; issues: string[] }
+
+/** Read the leading `[…]` groups off a clause. Unclosed bracket -> issue, rest is dropped. */
+function parseGroups(text: string, lineNo: number): GroupParse {
+  const groups: MacroCond[][] = [];
+  const issues: string[] = [];
+  let unit: MacroUnitRef | undefined;
+  let s = text.trimStart();
+  while (s.startsWith('[') && groups.length < MACRO_GROUPS_MAX) {
+    const end = s.indexOf(']');
+    if (end < 0) {
+      issues.push('unclosed [ in the conditions');
+      return { groups, unit, rest: '', issues };
+    }
+    const body = s.slice(1, end);
+    s = s.slice(end + 1).trimStart();
+    const conds: MacroCond[] = [];
+    for (const token of condTokens(body)) {
+      if (token.startsWith('@')) {
+        const u = parseMacroUnit(token.slice(1));
+        if (!u) {
+          issues.push(`unknown unit "${token}"`);
+          // A named-but-unknown unit must never silently become "the current target".
+          conds.push({ key: 'never', values: [] });
+          continue;
+        }
+        unit = u;
+        conds.push({ key: 'target', values: [macroUnitToken(u)] });
+        continue;
+      }
+      const { key, rest, cmp } = splitCond(token);
+      const low = key.trim().toLowerCase();
+      if (!low) continue;
+      if (cmp) {
+        const amount = Number(rest);
+        if (!Number.isFinite(amount)) {
+          issues.push(`"${token}" needs a number after ${cmp}`);
+          conds.push({ key: 'never', values: [] });
+          continue;
+        }
+        conds.push({ key: low, values: [], cmp, amount });
+        continue;
+      }
+      const values = condValues(rest);
+      if (low === 'target') {
+        const u = values[0] ? parseMacroUnit(values[0]) : null;
+        if (u) unit = u;
+        else if (values.length) {
+          issues.push(`unknown unit "${values[0]}"`);
+          conds.push({ key: 'never', values: [] });
+          continue;
+        }
+      }
+      conds.push({ key: low, values });
+      if (conds.length >= MACRO_CONDS_MAX) break;
+    }
+    groups.push(conds);
+  }
+  // A 5th group is silently ignored by the caps; say so rather than change the meaning quietly.
+  if (s.startsWith('[')) issues.push(`only ${MACRO_GROUPS_MAX} condition groups per line are read`);
+  void lineNo;
+  return { groups, unit, rest: s, issues };
+}
+
+/** One `;` branch -> clause. `!arg` and `{Macro}` are read off the argument here. */
+function parseClause(text: string, verb: MacroVerb, lineNo: number): { clause: MacroClause; issues: string[] } {
+  const g = parseGroups(text, lineNo);
+  const issues = [...g.issues];
+  let arg = g.rest.trim();
+  let noRecast = false;
+  let call: string | undefined;
+  if (arg.startsWith('!')) {
+    noRecast = true;
+    arg = arg.slice(1).trim();
+  }
+  if (arg.startsWith('{')) {
+    const end = arg.indexOf('}');
+    if (end < 0) issues.push('unclosed { in the macro name');
+    else {
+      call = arg.slice(1, end).trim().slice(0, MACRO_NAME_MAX);
+      arg = '';
+      if (!call) issues.push('{} needs a macro name');
+    }
+  }
+  const unit = g.unit;
+  // The argument may name the FINAL target. An `@` always parses as a unit; a bare word only for
+  // the unit verbs, so a mob called "Target Dummy" stays a name. Cite: Core.lua:305-311.
+  let argUnit: MacroUnitRef | undefined;
+  if (arg) {
+    const asUnit = arg.startsWith('@') || UNIT_VERBS.has(verb) ? parseMacroUnit(arg) : null;
+    if (asUnit) {
+      argUnit = asUnit;
+      arg = '';
+    } else if (arg.startsWith('@')) {
+      issues.push(`unknown unit "${arg}"`);
+      arg = '';
+    }
+  }
+  // Only complain about a missing argument when the conditions parsed cleanly — an unclosed
+  // bracket already ate the rest of the line, and two messages for one typo is noise.
+  if (NEEDS_ARG.has(verb) && !arg && !call && !argUnit && !unit && !issues.length) {
+    issues.push(`/${verb} needs something to act on`);
+  }
+  return { clause: { groups: g.groups, unit, argUnit, arg, noRecast, call }, issues };
+}
+
+/** `@unit` for this one `[…]` group. Later groups do not inherit a sibling's unit. */
+export function macroGroupUnit(group: readonly MacroCond[]): MacroUnitRef | undefined {
+  let ref: MacroUnitRef | undefined;
+  for (const cond of group) {
+    if (cond.key !== 'target' || !cond.values[0]) continue;
+    const u = parseMacroUnit(cond.values[0]);
+    if (u) ref = u;
+  }
+  return ref;
+}
+
+// Parse a macro body. Never throws; caps every dimension (16 lines, 8 branches, 4 groups, 8 conditions) so
+// a hand-edited 255-char body cannot produce unbounded work at press time.
+export function parseMacroBody(body: string): MacroProgram {
+  const issues: MacroParseIssue[] = [];
+  const lines: MacroLine[] = [];
+  let tooltip: MacroTooltipDirective = { kind: 'none' };
+  const raw = typeof body === 'string' ? body.replace(/\r\n?/g, '\n') : '';
+  const src = raw.split('\n');
+  const count = Math.min(src.length, MACRO_LINES_MAX);
+  if (src.length > MACRO_LINES_MAX) {
+    issues.push({ line: MACRO_LINES_MAX + 1, message: `only the first ${MACRO_LINES_MAX} lines run` });
+  }
+  for (let i = 0; i < count; i++) {
+    const lineNo = i + 1;
+    const line = src[i]!.trim();
+    if (!line) continue;
+    if (line.startsWith('#')) {
+      const low = line.toLowerCase();
+      if (tooltip.kind === 'none' && low.startsWith(SHOWTOOLTIP)) {
+        const rest = line.slice(SHOWTOOLTIP.length).trim();
+        tooltip = rest ? { kind: 'named', name: rest } : { kind: 'dynamic' };
+      }
+      continue;
+    }
+    if (!line.startsWith('/')) {
+      issues.push({ line: lineNo, message: 'a macro line starts with a / command' });
+      continue;
+    }
+    const sp = line.search(/\s/);
+    const verbRaw = (sp < 0 ? line.slice(1) : line.slice(1, sp)).toLowerCase();
+    const rest = sp < 0 ? '' : line.slice(sp + 1);
+    const verb = VERBS[verbRaw];
+    if (!verb) {
+      issues.push({
+        line: lineNo,
+        message: POST_VANILLA[verbRaw] ?? `unknown command /${verbRaw}`,
+      });
+      continue;
+    }
+    const clauses: MacroClause[] = [];
+    const branches = rest.split(';');
+    const take = Math.min(branches.length, MACRO_CLAUSES_MAX);
+    if (branches.length > MACRO_CLAUSES_MAX) {
+      issues.push({ line: lineNo, message: `only ${MACRO_CLAUSES_MAX} ";" branches per line run` });
+    }
+    for (let b = 0; b < take; b++) {
+      const text = branches[b]!;
+      // `/stopcasting` and friends take no argument: one empty clause still has to run.
+      if (!text.trim() && (b > 0 || NEEDS_ARG.has(verb))) continue;
+      const { clause, issues: cIssues } = parseClause(text, verb, lineNo);
+      for (const m of cIssues) issues.push({ line: lineNo, message: m });
+      clauses.push(clause);
+    }
+    if (!clauses.length) {
+      if (NEEDS_ARG.has(verb)) {
+        issues.push({ line: lineNo, message: `/${verb} needs something to act on` });
+        continue;
+      }
+      clauses.push({ groups: [], arg: '', noRecast: false });
+    }
+    lines.push({ n: lineNo, verb, clauses });
+  }
+  return { tooltip, lines, issues };
+}