Skip to content

Write HTML. Render video. Built for agents.

27.0 KB
Raw Blame
/**
 * Static evaluation for computed GSAP timelines (browser-safe, acorn/ESTree).
 *
 * The read parser resolves only literals and top-level consts, so timelines
 * built by a helper called N times or by a bounded loop collapse to position 0.
 * This module expands those constructs into a synthetic analysis AST: each
 * helper invocation and each loop iteration becomes its own concrete set of
 * `tl.*` calls, with parameters/loop-vars substituted by the call's argument
 * (or element/index) AST nodes — after which the existing parse pipeline
 * resolves positions and `motionPath` arcs unchanged.
 *
 * Substituted nodes keep their original source offsets, so downstream
 * source-slicing (raw extras, keyframes) stays correct. The substitution
 * primitives never mutate their input; `inlineComputedTimelines` rewrites the
 * Program body of the freshly-parsed AST it is handed (owned by the caller).
 */
import type { GsapProvenance } from "./gsapSerialize.js";

// acorn ESTree nodes are structurally untyped; mirror gsapParserAcorn.ts.
type Node = any;

/** Node keys that are metadata, not child AST to traverse/substitute. */
const SKIP_KEYS = new Set([
  "type",
  "start",
  "end",
  "loc",
  "range",
  "__hfProvenance",
  "__hfOrder",
  "__hfSiteStart",
]);

const FUNCTION_TYPES = new Set([
  "ArrowFunctionExpression",
  "FunctionExpression",
  "FunctionDeclaration",
]);
const GSAP_METHODS = new Set(["set", "to", "from", "fromTo"]);

// Bounds on synthetic expansion (recursion + iteration runaway guards).
const MAX_DEPTH = 8;
const MAX_ITERS = 512;

export function isFunctionNode(node: Node): boolean {
  return !!node && FUNCTION_TYPES.has(node.type);
}

function isNode(x: Node): boolean {
  return !!x && typeof x === "object" && typeof x.type === "string";
}

/**
 * Apply `fn` to each child AST node, writing back its return value. Skips
 * metadata keys and key/member slots that must not be treated as values.
 * The one place array-vs-single child traversal lives, so walkers stay flat.
 */
function transformChildren(node: Node, fn: (child: Node) => Node): void {
  for (const key of Object.keys(node)) {
    if (SKIP_KEYS.has(key) || isNonValueIdentifierSlot(node, key)) continue;
    const child = node[key];
    if (Array.isArray(child)) {
      for (let i = 0; i < child.length; i++) child[i] = fn(child[i]);
    } else {
      node[key] = fn(child);
    }
  }
}

/** Deep structural clone preserving `start`/`end`/`loc` (needed for source slicing). */
export function cloneNode<T extends Node>(node: T): T {
  return structuredClone(node);
}

// ponytail: Identifier + default + rest only. Destructured bindings (`{x}`, `[x]`)
// aren't inlined (U2 inlines Identifier-param helpers / loop vars only), so a
// destructuring shadow is a double-rare miss that just falls back. Add the
// pattern cases here if that ever bites.
function collectPatternNames(pattern: Node, out: Set<string>): void {
  if (pattern?.type === "Identifier") out.add(pattern.name);
  else if (pattern?.type === "AssignmentPattern") collectPatternNames(pattern.left, out);
  else if (pattern?.type === "RestElement") collectPatternNames(pattern.argument, out);
}

function boundPatterns(node: Node): Node[] {
  if (isFunctionNode(node)) return node.params ?? [];
  if (node.type === "VariableDeclarator") return [node.id];
  if (node.type === "CatchClause") return [node.param];
  if (node.type === "AssignmentExpression" && node.left?.type === "Identifier") return [node.left];
  return [];
}

/** Every identifier name bound anywhere inside the subtree (fn params, declared vars, catch params). */
function collectBoundNames(root: Node): Set<string> {
  const names = new Set<string>();
  const visit = (node: Node): Node => {
    if (!isNode(node)) return node;
    for (const pattern of boundPatterns(node)) collectPatternNames(pattern, names);
    transformChildren(node, visit);
    return node;
  };
  visit(root);
  return names;
}

/** A child in key/property position that must not be treated as a value identifier. */
function isNonValueIdentifierSlot(node: Node, key: string): boolean {
  if (node.computed) return false;
  return (
    (node.type === "MemberExpression" && key === "property") ||
    (node.type === "Property" && key === "key")
  );
}

/**
 * Substitute bound identifiers in an already-cloned subtree, returning the
 * (possibly replaced) root. Names shadowed anywhere inside (nested function
 * params, declared vars) are dropped up front rather than tracked per scope —
 * worst case we under-substitute and the caller falls back to current behavior.
 * Never substitutes identifiers in key/member positions. Mutates the passed
 * clone in place — callers pass `cloneNode(...)`.
 */
export function substituteParams(node: Node, bindings: ReadonlyMap<string, Node>): Node {
  const shadowed = collectBoundNames(node);
  let effective = bindings;
  if (shadowed.size > 0) {
    effective = new Map(bindings);
    for (const name of shadowed) (effective as Map<string, Node>).delete(name);
  }
  if (effective.size === 0) return node;
  return replace(node, effective);
}

function replace(node: Node, bindings: ReadonlyMap<string, Node>): Node {
  if (!isNode(node)) return node;
  if (node.type === "Identifier" && bindings.has(node.name)) {
    return cloneNode(bindings.get(node.name));
  }
  transformChildren(node, (child) => replace(child, bindings));
  return node;
}

/** Tag a node (typically a `tl.*` CallExpression) with its construction provenance. */
export function tagProvenance(node: Node, provenance: GsapProvenance): Node {
  if (node && typeof node === "object") node.__hfProvenance = provenance;
  return node;
}

/** Read a provenance tag previously set by `tagProvenance`, if any. */
export function readProvenance(node: Node): GsapProvenance | undefined {
  return node?.__hfProvenance;
}

/** Synthesize a numeric `Literal` node (for loop indices, which have no source node). */
export function numericLiteral(value: number): Node {
  return { type: "Literal", value, raw: String(value) };
}

// ── Expansion engine (U2) ─────────────────────────────────────────────────────

/** Resolve an expression to a literal value (top-level consts in scope, arithmetic). */
type LiteralResolver = (node: Node) => number | string | boolean | undefined;

interface ExpandCtx {
  helpers: Map<string, Node>;
  timelineVar: string;
  resolve: LiteralResolver;
  depth: number;
  /** Mutable source-order counter for provenance call-site ordinals. */
  site: { n: number };
  /** Mutable counter stamping expansion order onto tweens (clones share source loc). */
  order: { n: number };
  /** Source offset of the top-level statement being expanded; tweens inherit it as their sort site. */
  rootStart: number;
}

function walkNodes(node: Node, fn: (n: Node) => void): void {
  if (!isNode(node)) return;
  fn(node);
  for (const key of Object.keys(node)) {
    if (SKIP_KEYS.has(key)) continue;
    const child = node[key];
    if (Array.isArray(child)) for (const c of child) walkNodes(c, fn);
    else walkNodes(child, fn);
  }
}

/** The identifier a (possibly chained) call's member expression is rooted at. */
function timelineRootName(call: Node): string | null {
  let obj = call.callee?.object;
  while (obj?.type === "CallExpression") obj = obj.callee?.object;
  return obj?.type === "Identifier" ? obj.name : null;
}

export function isTimelineRooted(call: Node, timelineVar: string): boolean {
  if (timelineRootName(call) !== timelineVar) return false;
  return (
    call.callee?.property?.type === "Identifier" && GSAP_METHODS.has(call.callee.property.name)
  );
}

/** True for `tl.addLabel(...)`: not a tween, but its position must sort in the same coordinate
 *  space as tween calls, or a label defined inside an inlined helper resolves at its declaration
 *  offset instead of its call site. */
function isAddLabelCall(call: Node, timelineVar: string): boolean {
  return timelineRootName(call) === timelineVar && call.callee?.property?.name === "addLabel";
}

function containsTimelineCall(node: Node, timelineVar: string): boolean {
  let found = false;
  walkNodes(node, (n) => {
    if (n.type === "CallExpression" && isTimelineRooted(n, timelineVar)) found = true;
  });
  return found;
}

function rangeOf(node: Node): [number, number] | undefined {
  return typeof node.start === "number" && typeof node.end === "number"
    ? [node.start, node.end]
    : undefined;
}

interface SupportedParam {
  name: string;
  defaultExpression?: Node;
}

const SAFE_DEFAULT_NODES = new Set([
  "ArrayExpression",
  "BinaryExpression",
  "ChainExpression",
  "ConditionalExpression",
  "Identifier",
  "Literal",
  "LogicalExpression",
  "MemberExpression",
  "ObjectExpression",
  "Property",
  "SpreadElement",
  "TemplateElement",
  "TemplateLiteral",
  "UnaryExpression",
]);

// ponytail: This allowlist is intentionally load-bearing. Defaults are evaluated
// while deciding whether a helper declaration can be erased, so admitting calls,
// assignments, updates, or constructors here could execute author code at a
// different time (or more than once). Add syntax only with negative-path tests.

/**
 * A default expression is safe only when evaluating it cannot execute author
 * code and every value identifier refers to an earlier parameter. This mirrors
 * JavaScript's left-to-right default binding while keeping the static parser
 * deliberately narrower than a JavaScript interpreter.
 */
function isSafeDefaultExpression(node: Node, earlierParams: ReadonlySet<string>): boolean {
  let safe = true;
  // fallow-ignore-next-line complexity
  const visit = (current: Node, parent?: Node, key?: string): void => {
    if (!isNode(current) || !safe) return;
    if (!SAFE_DEFAULT_NODES.has(current.type)) {
      safe = false;
      return;
    }
    if (current.type === "UnaryExpression" && current.operator === "delete") {
      safe = false;
      return;
    }
    if (current.type === "Identifier") {
      const nonValue = parent && key ? isNonValueIdentifierSlot(parent, key) : false;
      if (!nonValue && current.name !== "undefined" && !earlierParams.has(current.name)) {
        safe = false;
      }
      return;
    }
    for (const childKey of Object.keys(current)) {
      if (SKIP_KEYS.has(childKey)) continue;
      const child = current[childKey];
      if (Array.isArray(child)) {
        for (const item of child) visit(item, current, childKey);
      } else {
        visit(child, current, childKey);
      }
    }
  };
  visit(node);
  return safe;
}

const SUPPORTED_PARAMS_CACHE = new WeakMap<object, SupportedParam[] | null>();

function supportedParam(param: Node, earlier: ReadonlySet<string>): SupportedParam | null {
  if (param.type === "Identifier") return { name: param.name };
  if (param.type !== "AssignmentPattern" || param.left?.type !== "Identifier") return null;
  if (!isSafeDefaultExpression(param.right, earlier)) return null;
  return { name: param.left.name, defaultExpression: param.right };
}

function supportedParams(fn: Node): SupportedParam[] | null {
  if (SUPPORTED_PARAMS_CACHE.has(fn)) return SUPPORTED_PARAMS_CACHE.get(fn) ?? null;
  const params: SupportedParam[] = [];
  const earlier = new Set<string>();
  for (const param of fn.params ?? []) {
    const parsed = supportedParam(param, earlier);
    if (!parsed) {
      SUPPORTED_PARAMS_CACHE.set(fn, null);
      return null;
    }
    params.push(parsed);
    earlier.add(parsed.name);
  }
  SUPPORTED_PARAMS_CACHE.set(fn, params);
  return params;
}

/** Identifier/default params + block body (shape we can inline). Timeline content checked separately. */
function isShapeEligible(fn: Node): boolean {
  return isFunctionNode(fn) && fn.body?.type === "BlockStatement" && supportedParams(fn) !== null;
}

/** True if the subtree calls any function named in `names`. */
function callsAny(node: Node, names: Set<string>): boolean {
  let hit = false;
  walkNodes(node, (n) => {
    if (
      n.type === "CallExpression" &&
      n.callee?.type === "Identifier" &&
      names.has(n.callee.name)
    ) {
      hit = true;
    }
  });
  return hit;
}

/** `[name, fnNode]` if a single-declarator `const f = fn` is an inlinable-shaped helper. */
function varDeclHelper(stmt: Node): [string, Node] | null {
  if (stmt.declarations?.length !== 1) return null;
  const d = stmt.declarations[0];
  return d.id?.type === "Identifier" && isShapeEligible(d.init) ? [d.id.name, d.init] : null;
}

/** `[name, fnNode]` if `stmt` declares an inlinable-shaped helper, else null. */
function helperFromStatement(stmt: Node): [string, Node] | null {
  if (stmt.type === "FunctionDeclaration") {
    return stmt.id && isShapeEligible(stmt) ? [stmt.id.name, stmt] : null;
  }
  if (stmt.type === "VariableDeclaration") return varDeclHelper(stmt);
  return null;
}

/** Top-level functions whose shape we can inline (Identifier params + block body). */
function gatherHelperCandidates(program: Node): Map<string, Node> {
  const candidates = new Map<string, Node>();
  for (const stmt of program.body ?? []) {
    const helper = helperFromStatement(stmt);
    if (helper) candidates.set(helper[0], helper[1]);
  }
  return candidates;
}

/** Names that build the timeline directly or by calling another builder (transitive closure). */
function timelineBuildingNames(candidates: Map<string, Node>, timelineVar: string): Set<string> {
  const building = new Set<string>();
  for (const [name, fn] of candidates) {
    if (containsTimelineCall(fn.body, timelineVar)) building.add(name);
  }
  for (let changed = true; changed; ) {
    changed = false;
    for (const [name, fn] of candidates) {
      if (!building.has(name) && callsAny(fn.body, building)) {
        building.add(name);
        changed = true;
      }
    }
  }
  return building;
}

function bump(counts: Map<string, number>, key: string): void {
  counts.set(key, (counts.get(key) ?? 0) + 1);
}

function undefinedIdentifier(): Node {
  return { type: "Identifier", name: "undefined" };
}

function isExplicitUndefined(node: Node | undefined): boolean {
  return (
    (node?.type === "Identifier" && node.name === "undefined") ||
    (node?.type === "UnaryExpression" &&
      node.operator === "void" &&
      node.argument?.type === "Literal" &&
      node.argument.value === 0)
  );
}

/** Resolve one call exactly as JavaScript binds identifier/default parameters. */
function resolveHelperBindings(call: Node, params: SupportedParam[]): Map<string, Node> | null {
  if (call.arguments?.some((arg: Node) => arg?.type === "SpreadElement")) return null;

  const bindings = new Map<string, Node>();
  for (let i = 0; i < params.length; i++) {
    const param = params[i]!;
    const arg = call.arguments?.[i];
    if (arg && !isExplicitUndefined(arg)) {
      bindings.set(param.name, arg);
    } else if (param.defaultExpression) {
      bindings.set(param.name, substituteParams(cloneNode(param.defaultExpression), bindings));
    } else {
      // Omitted required parameters are still bound by JavaScript. Keeping an
      // explicit undefined node prevents a dropped helper declaration from
      // leaving its parameter identifier dangling in the synthetic AST.
      bindings.set(param.name, undefinedIdentifier());
    }
  }
  return bindings;
}

function statementHelperCall(node: Node, names: ReadonlySet<string>): Node | undefined {
  if (node.type !== "ExpressionStatement") return undefined;
  const expression = node.expression;
  if (expression?.type !== "CallExpression" || expression.callee?.type !== "Identifier") {
    return undefined;
  }
  return names.has(expression.callee.name) ? expression : undefined;
}

/**
 * Keep only candidates safe to drop: every reference to the name is its
 * declaration or a statement-level call. (1 decl id + 1 callee id per
 * statement-level call ⇒ total occurrences with no stray uses.)
 */
function safelyDroppable(program: Node, candidates: Map<string, Node>): Map<string, Node> {
  const names = new Set(candidates.keys());
  const totalIds = new Map<string, number>();
  const stmtCalls = new Map<string, number>();
  const unbindable = new Set<string>();
  walkNodes(program, (n) => {
    if (n.type === "Identifier" && names.has(n.name)) bump(totalIds, n.name);
    const call = statementHelperCall(n, names);
    if (!call) return;
    bump(stmtCalls, call.callee.name);
    const fn = candidates.get(call.callee.name);
    const params = fn && supportedParams(fn);
    if (!params || !resolveHelperBindings(call, params)) unbindable.add(call.callee.name);
  });
  const safe = new Map<string, Node>();
  for (const [name, fn] of candidates) {
    if (!unbindable.has(name) && (totalIds.get(name) ?? 0) === 1 + (stmtCalls.get(name) ?? 0)) {
      safe.set(name, fn);
    }
  }
  return safe;
}

/** Top-level timeline-building helpers that are safe to inline-and-drop. */
function collectInlinableHelpers(program: Node, timelineVar: string): Map<string, Node> {
  const candidates = gatherHelperCandidates(program);
  if (candidates.size === 0) return candidates;
  const building = timelineBuildingNames(candidates, timelineVar);
  for (const name of [...candidates.keys()]) if (!building.has(name)) candidates.delete(name);
  if (candidates.size === 0) return candidates;
  return safelyDroppable(program, candidates);
}

function isHelperDecl(stmt: Node, helpers: Map<string, Node>): boolean {
  if (stmt.type === "FunctionDeclaration") return !!stmt.id && helpers.get(stmt.id.name) === stmt;
  if (stmt.type === "VariableDeclaration" && stmt.declarations?.length === 1) {
    const d = stmt.declarations[0];
    return d.id?.type === "Identifier" && helpers.get(d.id.name) === d.init;
  }
  return false;
}

function bodyStatements(node: Node): Node[] {
  if (node?.type === "BlockStatement") return node.body ?? [];
  return node ? [{ type: "ExpressionStatement", expression: node }] : [];
}

/** Tag this body's direct timeline tweens with provenance + a monotonic expansion-order stamp. */
function tagTimelineCalls(stmts: Node[], prov: GsapProvenance, ctx: ExpandCtx): void {
  for (const stmt of stmts) {
    const calls: Node[] = [];
    walkNodes(stmt, (n) => {
      if (
        n.type === "CallExpression" &&
        (isTimelineRooted(n, ctx.timelineVar) || isAddLabelCall(n, ctx.timelineVar))
      )
        calls.push(n);
    });
    // A chain's outer call is visited first but runs last; stamp in source order.
    calls.sort((a, b) => a.callee.property.start - b.callee.property.start);
    for (const n of calls) {
      tagProvenance(n, { ...prov });
      n.__hfOrder = ctx.order.n++;
      n.__hfSiteStart = ctx.rootStart;
    }
  }
}

/** Clone a body as one scope, substitute the bindings, tag provenance, recurse. */
function expandBody(
  bodyStmts: Node[],
  bindings: Map<string, Node>,
  prov: GsapProvenance,
  ctx: ExpandCtx,
): Node[] {
  const block = substituteParams(cloneNode({ type: "BlockStatement", body: bodyStmts }), bindings);
  tagProvenance(block, prov);
  tagTimelineCalls(block.body, prov, ctx);
  block.body = expandStatements(block.body, { ...ctx, depth: ctx.depth + 1 });
  // Keep each synthetic expansion in its own lexical scope. Flattening repeated
  // loop/helper bodies into Program scope makes same-named local DOM bindings
  // overwrite one another during selector analysis.
  return [block];
}

function inlineHelper(call: Node, ctx: ExpandCtx): Node[] | null {
  const fn = ctx.helpers.get(call.callee.name);
  if (!fn) return null;
  const params = supportedParams(fn);
  if (!params) return null;
  const bindings = resolveHelperBindings(call, params);
  if (!bindings) return null;
  const prov: GsapProvenance = {
    kind: "helper",
    fn: call.callee.name,
    callSite: ++ctx.site.n,
    sourceRange: rangeOf(call),
  };
  return expandBody(fn.body.body, bindings, prov, ctx);
}

function assignStep(update: Node, resolve: LiteralResolver): number | undefined {
  if (update.operator === "+=") return asNum(resolve(update.right));
  if (update.operator === "-=") {
    const s = asNum(resolve(update.right));
    return s === undefined ? undefined : -s;
  }
  // `i = i + S` — the step is the right operand of the addition.
  if (update.operator === "=" && update.right?.type === "BinaryExpression") {
    return asNum(resolve(update.right.right));
  }
  return undefined;
}

/** The loop variable a `for` update clause mutates (`i++` or `i += S`), or null. */
function updatedVarName(update: Node): string | null {
  if (update?.type === "UpdateExpression") return update.argument?.name ?? null;
  if (update?.type === "AssignmentExpression") return update.left?.name ?? null;
  return null;
}

function loopStep(update: Node, varName: string, resolve: LiteralResolver): number | undefined {
  if (updatedVarName(update) !== varName) return undefined;
  if (update.type === "UpdateExpression") return update.operator === "++" ? 1 : -1;
  return assignStep(update, resolve);
}

function asNum(v: unknown): number | undefined {
  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
}

function loopSatisfied(op: string, x: number, end: number): boolean {
  if (op === "<") return x < end;
  if (op === "<=") return x <= end;
  if (op === ">") return x > end;
  if (op === ">=") return x >= end;
  return false;
}

interface ForHeader {
  v: string;
  start: number;
  end: number;
  op: string;
  step: number;
}

/** The single `let v = <init>` of a for-loop init clause, or null. */
function forInitVar(init: Node): { name: string; initExpr: Node } | null {
  if (init?.type !== "VariableDeclaration" || init.declarations?.length !== 1) return null;
  const d = init.declarations[0];
  return d.id?.type === "Identifier" ? { name: d.id.name, initExpr: d.init } : null;
}

/** Parse `for (let v = A; v <op> B; v += S)` into resolved bounds, or null if not statically bounded. */
function parseForHeader(stmt: Node, resolve: LiteralResolver): ForHeader | null {
  const iv = forInitVar(stmt.init);
  const test = stmt.test;
  if (!iv || test?.type !== "BinaryExpression" || test.left?.name !== iv.name) return null;
  const start = asNum(resolve(iv.initExpr));
  const end = asNum(resolve(test.right));
  const step = loopStep(stmt.update, iv.name, resolve);
  if (start === undefined || end === undefined || !step) return null;
  return { v: iv.name, start, end, op: test.operator, step };
}

function unrollFor(stmt: Node, ctx: ExpandCtx): Node[] | null {
  const h = parseForHeader(stmt, ctx.resolve);
  if (!h) return null;
  const body = bodyStatements(stmt.body);
  const out: Node[] = [];
  const site = ++ctx.site.n;
  let iteration = 0;
  for (let x = h.start; loopSatisfied(h.op, x, h.end); x += h.step) {
    if (iteration >= MAX_ITERS) return null;
    const prov: GsapProvenance = {
      kind: "loop",
      callSite: site,
      iteration,
      sourceRange: rangeOf(stmt),
    };
    out.push(...expandBody(body, new Map([[h.v, numericLiteral(x)]]), prov, ctx));
    iteration++;
  }
  return out;
}

function forOfVarName(left: Node): string | null {
  if (left?.type === "VariableDeclaration") {
    const id = left.declarations?.[0]?.id;
    return id?.type === "Identifier" ? id.name : null;
  }
  return left?.type === "Identifier" ? left.name : null;
}

/** Expand `for (const el of [literal array]) {...}` and `[literal array].forEach((el, i) => {...})`. */
function unrollOverArray(
  elements: Node[],
  body: Node[],
  elName: string | null,
  idxName: string | null,
  range: [number, number] | undefined,
  ctx: ExpandCtx,
): Node[] {
  const out: Node[] = [];
  const site = ++ctx.site.n;
  elements.forEach((el, i) => {
    if (!el) return;
    const bindings = new Map<string, Node>();
    if (elName) bindings.set(elName, el);
    if (idxName) bindings.set(idxName, numericLiteral(i));
    const prov: GsapProvenance = { kind: "loop", callSite: site, iteration: i, sourceRange: range };
    out.push(...expandBody(body, bindings, prov, ctx));
  });
  return out;
}

function unrollForOf(stmt: Node, ctx: ExpandCtx): Node[] | null {
  if (stmt.right?.type !== "ArrayExpression") return null;
  const elName = forOfVarName(stmt.left);
  if (!elName) return null;
  return unrollOverArray(
    stmt.right.elements ?? [],
    bodyStatements(stmt.body),
    elName,
    null,
    rangeOf(stmt),
    ctx,
  );
}

/** The (element, index) param names of a callback, or null if either is non-Identifier. */
function callbackParamNames(cb: Node): { el: string | null; idx: string | null } | null {
  const names: Array<string | null> = [];
  for (const p of [cb.params?.[0], cb.params?.[1]]) {
    if (!p) names.push(null);
    else if (p.type !== "Identifier") return null;
    else names.push(p.name);
  }
  return { el: names[0]!, idx: names[1]! };
}

/** True for `[arrayLiteral].forEach` member callees. */
function isForEachCall(callee: Node): boolean {
  return (
    callee?.type === "MemberExpression" &&
    callee.property?.name === "forEach" &&
    callee.object?.type === "ArrayExpression"
  );
}

/** The element array + callback of `[...].forEach(cb)`, or null. */
function forEachTarget(call: Node): { elements: Node[]; cb: Node } | null {
  if (!isForEachCall(call.callee)) return null;
  const cb = call.arguments?.[0];
  return isFunctionNode(cb) ? { elements: call.callee.object.elements ?? [], cb } : null;
}

function unrollForEach(call: Node, ctx: ExpandCtx): Node[] | null {
  const target = forEachTarget(call);
  if (!target) return null;
  const params = callbackParamNames(target.cb);
  if (!params) return null;
  return unrollOverArray(
    target.elements,
    bodyStatements(target.cb.body),
    params.el,
    params.idx,
    rangeOf(call),
    ctx,
  );
}

function expandCall(call: Node, ctx: ExpandCtx): Node[] | null {
  if (call.callee?.type === "Identifier" && ctx.helpers.has(call.callee.name)) {
    return inlineHelper(call, ctx);
  }
  return unrollForEach(call, ctx);
}

function expandStatement(stmt: Node, ctx: ExpandCtx): Node[] | null {
  if (ctx.depth >= MAX_DEPTH) return null;
  if (stmt.type === "ForStatement") return unrollFor(stmt, ctx);
  if (stmt.type === "ForOfStatement") return unrollForOf(stmt, ctx);
  if (stmt.type === "ExpressionStatement" && stmt.expression?.type === "CallExpression") {
    return expandCall(stmt.expression, ctx);
  }
  return null;
}

function expandStatements(stmts: Node[], ctx: ExpandCtx): Node[] {
  const out: Node[] = [];
  for (const stmt of stmts) {
    const expanded = expandStatement(stmt, ctx);
    if (expanded) out.push(...expanded);
    else out.push(stmt);
  }
  return out;
}

/**
 * Rewrite the Program body so helper invocations and bounded loops that build
 * the timeline are expanded into concrete per-call / per-iteration `tl.*`
 * statements, each tagged with provenance. Mutates `ast` in place (caller owns
 * the freshly-parsed tree). Constructs it can't statically resolve are left
 * untouched, so the parser falls back to current behavior for them.
 */
export function inlineComputedTimelines(
  ast: Node,
  timelineVar: string,
  resolve: LiteralResolver,
): void {
  const helpers = collectInlinableHelpers(ast, timelineVar);
  const ctx: ExpandCtx = {
    helpers,
    timelineVar,
    resolve,
    depth: 0,
    site: { n: 0 },
    order: { n: 0 },
    rootStart: 0,
  };
  const body = (ast.body ?? []).filter((stmt: Node) => !isHelperDecl(stmt, helpers));
  ast.body = body.flatMap((stmt: Node) => {
    ctx.rootStart = stmt.start;
    return expandStatements([stmt], ctx);
  });
}