@swf2es/runtime 0.0.0-stage → 0.1.0

package/src/avm1/control.ts

@@ -0,0 +1,339 @@
+// What With and Try hold while control stays in their bytes, as adl runs
+// them (docs/avm1.md, "With and Try"): not activations of their own, as
+// Ruffle has them, but entries on the activation that come off as control
+// leaves the blocks they hold over, however it leaves them.
+//
+// The compiler writes a region's blocks in order of their offsets, so a
+// body's bytes are a range of its blocks, and every entry is a range: a
+// With's object or a catch's variable on the scope chain while control is
+// in the body; a Try's handlers while it is in the try or catch body; and a
+// finally reached by a throw or a Return, which throws again or returns as
+// control leaves it. Where control goes is a block of the region, -1 for
+// its exit, whose value is `cx.ret`.
+//
+// What adl shows of when they come off: a scope holds over its body's
+// bytes and the first action past them, where control runs off the body's
+// end or jumps, and comes off as control goes anywhere else (V.leave), or
+// after that action (V.scopes); only the scope on top is looked at, so one
+// a With pushes as that action keeps the one under it until both come off.
+// A Try's handlers and a finally's throw or Return come off at once
+// (V.leave, as control goes). A throw caught by a catch keeps every scope
+// over the catch body; a finally reached by a throw or a Return keeps them
+// only as control's going there keeps them.
+import type { Activation } from "./activation.js";
+import { Avm1Throw } from "./errors.js";
+import { Avm1Object } from "./objects.js";
+import { MAX_SCOPES, SCOPE_With, Scope } from "./scope.js";
+import type { Value } from "./values.js";
+
+/** A With's object, or a catch's variable, on the scope chain. */
+const HELD_Scope = 0;
+const HELD_Try = 1;
+/** A finally reached by a throw: `value` is thrown again as control leaves it. */
+const HELD_Thrown = 2;
+/** A finally reached by a Return, whose value is on the stack: it returns as control leaves it. */
+const HELD_Returned = 3;
+
+/** A Try's catch that a throw does not land in. */
+const NO_CATCH = -2;
+
+export class Held {
+  constructor(
+    readonly kind: number,
+    /** The blocks it holds over, from `from` to `to`, excluded. */
+    public from: number,
+    public to: number,
+    /** A finally's thrown value. */
+    readonly value: Value = undefined,
+  ) {}
+
+  holds(block: number): boolean {
+    return this.from <= block && block < this.to;
+  }
+
+  /** Whether a scope holds as control goes to `block`: one of its body's, or the first past it. */
+  admits(block: number): boolean {
+    return this.from <= block && block <= this.to;
+  }
+}
+
+const isScope = (h: Held): boolean => h.kind === HELD_Scope;
+
+/** A scope: the chain it made, and the chain under it, which it gives back as it comes off. */
+class ScopeHeld extends Held {
+  constructor(
+    from: number,
+    to: number,
+    readonly chain: Scope,
+    readonly below: Scope,
+  ) {
+    super(HELD_Scope, from, to);
+  }
+}
+
+/** A Try's handlers, held over its try and catch bodies. */
+class TryHeld extends Held {
+  constructor(
+    from: number,
+    /** Where the catch body starts: before it, a throw is the catch's. */
+    readonly catchFrom: number,
+    /** The finally body's blocks, none where it has none. */
+    readonly finallyFrom: number,
+    readonly finallyTo: number,
+    /** Where a throw lands for the catch, -1 for the region's exit, NO_CATCH for none. */
+    readonly catchAt: number,
+    /** The catch's variable, or its register. */
+    readonly into: string | number,
+    /** The operand stack's height as the Try ran, which a throw cuts it back to. */
+    readonly height: number,
+  ) {
+    super(HELD_Try, from, finallyFrom);
+  }
+}
+
+function heldOf(cx: Activation): Held[] {
+  let held = cx.held;
+  if (held === null) {
+    held = [];
+    cx.held = held;
+  }
+
+  return held;
+}
+
+/** `object` on top of the scope chain, held over the blocks from `from` to `to`. */
+function pushScope(cx: Activation, object: Avm1Object, from: number, to: number): void {
+  const below = cx.scope;
+  cx.scope = new Scope(below, SCOPE_With, object);
+  heldOf(cx).push(new ScopeHeld(from, to, cx.scope, below));
+}
+
+/**
+ * Keeps of `held`, from index `from` up, the entries `keep` says, and the
+ * scope chain as the scopes kept make it: the top one's, or with none
+ * kept, the chain under the first one taken off.
+ */
+function keepFrom(cx: Activation, held: Held[], from: number, keep: (h: Held) => boolean): void {
+  let n = from;
+  let top: Scope | null = null;
+  let base: Scope | null = null;
+  for (let i = from; i < held.length; i++) {
+    const h = held[i];
+    if (keep(h)) {
+      held[n++] = h;
+      if (h instanceof ScopeHeld) {
+        top = h.chain;
+      }
+    } else if (h instanceof ScopeHeld && base === null) {
+      base = h.below;
+    }
+  }
+
+  held.length = n;
+  if (top !== null) {
+    cx.scope = top;
+  } else if (base !== null) {
+    cx.scope = base;
+  }
+}
+
+/**
+ * Control going to the start of block `at`: the scopes on top that do not
+ * hold there come off at once, as adl looks only at the top one.
+ */
+function reach(cx: Activation, held: Held[], at: number): void {
+  let n = held.length;
+  while (n > 0 && held[n - 1].kind === HELD_Scope && !held[n - 1].admits(at)) {
+    n--;
+  }
+
+  if (n < held.length) {
+    keepFrom(cx, held, n, () => false);
+  }
+}
+
+function cut(st: Value[], height: number): void {
+  if (st.length > height) {
+    st.length = height;
+  }
+}
+
+/**
+ * With: `value`, a primitive boxed, on the scope chain over the body's
+ * blocks; false, the body skipped, for undefined and null, and where the
+ * chain holds MAX_SCOPES already (adl).
+ */
+export function enterWith(
+  cx: Activation,
+  value: Value,
+  from: number,
+  to: number,
+  version: number,
+): boolean {
+  if (value === undefined || value === null || cx.scope.depth >= MAX_SCOPES) {
+    return false;
+  }
+
+  pushScope(cx, cx.realm.box(value, version), from, to);
+  return true;
+}
+
+/** Try: its handlers, held over its try and catch bodies. */
+export function enterTry(
+  cx: Activation,
+  from: number,
+  catchFrom: number,
+  finallyFrom: number,
+  finallyTo: number,
+  catchAt: number,
+  into: string | number,
+): void {
+  heldOf(cx).push(
+    new TryHeld(from, catchFrom, finallyFrom, finallyTo, catchAt, into, cx.st.length),
+  );
+}
+
+/**
+ * Where control goes from the block `at`, where `error` was thrown: the
+ * catch of the first Try whose try body holds it, its variable set, or the
+ * finally of the first whose try or catch body does, which throws the
+ * value again as control leaves it. The stack is cut back to its height
+ * as that Try ran. Another error, a bug's or the host's, a recursion
+ * limit's, passes through, as does a value no Try catches.
+ */
+export function caught(cx: Activation, error: unknown, at: number): number {
+  const held = cx.held;
+  if (!(error instanceof Avm1Throw) || held === null) {
+    throw error;
+  }
+
+  cx.into = -1;
+  for (let i = held.length - 1; i >= 0; i--) {
+    const h = held[i];
+    if (!(h instanceof TryHeld) || !h.holds(at)) {
+      continue;
+    }
+
+    if (at < h.catchFrom && h.catchAt !== NO_CATCH) {
+      // The scopes where it was thrown hold over the catch body too, under
+      // its variable's (adl).
+      const from = h.catchFrom;
+      const to = h.finallyFrom;
+      keepFrom(cx, held, i + 1, isScope);
+      for (let j = i + 1; j < held.length; j++) {
+        held[j].from = from;
+        held[j].to = to;
+      }
+
+      cut(cx.st, h.height);
+      const into = h.into;
+      if (typeof into === "number") {
+        cx.into = into;
+        cx.thrown = error.value;
+      } else {
+        const scope = new Avm1Object();
+        scope.add(into, error.value, 0);
+        pushScope(cx, scope, from, to);
+      }
+
+      return h.catchAt;
+    }
+
+    if (h.finallyFrom < h.finallyTo) {
+      // The finally's mark goes under the scopes, which come off as control goes there.
+      held[i] = new Held(HELD_Thrown, h.finallyFrom, h.finallyTo, error.value);
+      keepFrom(cx, held, i + 1, isScope);
+      cut(cx.st, h.height);
+      reach(cx, held, h.finallyFrom);
+      return h.finallyFrom;
+    }
+  }
+
+  throw error;
+}
+
+/**
+ * Control going to block `to` (-1: the exit) across the bounds of a body:
+ * the Trys that do not hold over it come off, and a finally that a throw
+ * or a Return reached throws or returns as control leaves it, even by a
+ * jump. The scopes on top that do not hold there come off; those whose
+ * body it is the first block past, after its first action (V.scopes).
+ */
+export function leave(cx: Activation, to: number): number {
+  const held = cx.held;
+  if (held !== null) {
+    for (let i = held.length - 1; i >= 0; i--) {
+      const h = held[i];
+      if (h.holds(to)) {
+        break;
+      }
+
+      if (h.kind === HELD_Scope) {
+        continue;
+      }
+
+      held.splice(i, 1);
+      if (h.kind === HELD_Thrown) {
+        throw new Avm1Throw(h.value);
+      }
+
+      if (h.kind === HELD_Returned) {
+        return returned(cx);
+      }
+    }
+  }
+
+  if (to < 0) {
+    cx.ret = undefined;
+  } else if (held !== null) {
+    reach(cx, held, to);
+  }
+
+  return to;
+}
+
+/** The scopes that do not hold over block `at`, where control is, come off. */
+export function scopes(cx: Activation, at: number): void {
+  const held = cx.held;
+  if (held === null) {
+    return;
+  }
+
+  let n = held.length;
+  while (n > 0 && held[n - 1].kind === HELD_Scope && !held[n - 1].holds(at)) {
+    n--;
+  }
+
+  if (n < held.length) {
+    keepFrom(cx, held, n, () => false);
+  }
+}
+
+/**
+ * Return, its value on top of the stack: the finally of the first Try
+ * whose try or catch body holds control runs first, the stack cut back to
+ * its height as that Try ran with the value left on top, and the value is
+ * popped as control leaves it, the stack's top then (adl); a finally's own
+ * throw or Return gives way to this one.
+ */
+export function returned(cx: Activation): number {
+  const held = cx.held;
+  if (held !== null) {
+    for (let i = held.length - 1; i >= 0; i--) {
+      const h = held[i];
+      if (h instanceof TryHeld && h.finallyFrom < h.finallyTo) {
+        const st = cx.st;
+        const value = st.pop();
+        cut(st, h.height);
+        st.push(value);
+        held[i] = new Held(HELD_Returned, h.finallyFrom, h.finallyTo);
+        keepFrom(cx, held, i + 1, isScope);
+        reach(cx, held, h.finallyFrom);
+        return h.finallyFrom;
+      }
+    }
+  }
+
+  cx.ret = cx.st.pop();
+  return -1;
+}

package/src/avm1/errors.ts

@@ -0,0 +1,60 @@
+// What ends an AVM1 block other than its code: an action not done yet, the
+// SWF stopped at one Flash cannot read, or its actions disabled; and a value
+// the code throws.
+import type { Value } from "./values.js";
+
+/** An action the runtime does not do yet: it ends the block it is in. */
+export class NotYet extends Error {
+  override name = "Avm1NotYet";
+}
+
+/**
+ * Thrown once the host has stopped the SWF at an action Flash cannot read,
+ * to end whatever runs; the player takes it for no error.
+ */
+export class Halt extends Error {
+  override name = "Avm1Halt";
+}
+
+/**
+ * Thrown after a call, a `new` or a CallFrame that took the clip whose
+ * code runs off the display list: that code's activation returns there,
+ * a function's with undefined, and the code that called it goes on to its
+ * own check (adl; Ruffle's continue_if_base_clip_exists). One instance,
+ * thrown as a signal and never shown.
+ */
+export class BaseRemoved extends Error {
+  override name = "Avm1BaseRemoved";
+}
+
+export const BASE_REMOVED = new BaseRemoved("the clip whose code runs was removed");
+
+/**
+ * Thrown past Flash's recursion limit: Flash disables every action of the
+ * movie from there, and its timelines play on.
+ */
+export class Disabled extends Error {
+  override name = "Avm1Disabled";
+}
+
+/**
+ * Thrown as scripts run past the script timeout, Flash's 15 seconds or a
+ * ScriptLimits tag's: Flash asks whether to stop them, and stopped, the
+ * movie's actions are disabled as past the recursion limit (Ruffle halts
+ * its AVM1 so too).
+ */
+export class TimedOut extends Disabled {
+  override name = "Avm1TimedOut";
+}
+
+/**
+ * A value AVM1 code throws (Throw), which a Try's catch or finally takes
+ * and which, caught by none, ends the block as Flash ends it, silently.
+ */
+export class Avm1Throw extends Error {
+  override name = "Avm1Throw";
+
+  constructor(readonly value: Value) {
+    super("an AVM1 value thrown and not caught");
+  }
+}

package/src/avm1/functions.ts

@@ -0,0 +1,271 @@
+// AVM1's own functions, those DefineFunction and DefineFunction2 make, and
+// what calling them takes, as Ruffle's (https://github.com/ruffle-rs/ruffle)
+// core/src/avm1/function.rs and object/super_object.rs have them: MIT OR
+// Apache-2.0, Copyright (c) 2018-2022 Ruffle LLC and Ruffle contributors.
+// Where adl parts from Ruffle, adl decides (docs/avm1.md, "Functions and
+// registers").
+//
+// A function's code is a region of its block's compiled entry, which
+// takes the activation, `this` and the arguments; a DefineFunction2's
+// registers are the region's own `let`s, which it loads itself. What
+// the call needs of the runtime is here: an activation object for its
+// local variables, its parameters without a register among them, and
+// `arguments` and `super`, made only if the code asks for them.
+import { Activation, PENDING_Arguments, PENDING_Super, type Region } from "./activation.js";
+import { targetOrRoot } from "./clips.js";
+import { BASE_REMOVED, Disabled } from "./errors.js";
+import type { Target } from "./host.js";
+import { Avm1Function, Avm1Object, DONT_ENUM, fold, type Property } from "./objects.js";
+import type { Realm } from "./realm.js";
+import { SCOPE_Local, SCOPE_Target, Scope } from "./scope.js";
+import { isPrimitive, type Value } from "./values.js";
+
+// DefineFunction2's flags (the SWF's FunctionFlags).
+const FUNCTION_PreloadThis = 0x001;
+const FUNCTION_SuppressThis = 0x002;
+const FUNCTION_PreloadArguments = 0x004;
+const FUNCTION_SuppressArguments = 0x008;
+const FUNCTION_PreloadSuper = 0x010;
+const FUNCTION_SuppressSuper = 0x020;
+
+/** A DefineFunction or DefineFunction2's function. */
+export class ScriptFunction extends Avm1Function {
+  constructor(
+    proto: Value,
+    readonly world: Realm,
+    /** The region of its body. */
+    readonly region: Region,
+    /** Its block's regions, which DefineFunction in its body makes functions of. */
+    readonly code: Region[],
+    /** Its parameters' names, null for those in a register. */
+    readonly params: (string | null)[],
+    /** DefineFunction2's flags, 0 for a DefineFunction. */
+    readonly flags: number,
+    /** The version of the SWF that defined it. */
+    readonly version: number,
+    /** The scope chain it was defined in, which it closes over from SWF 6. */
+    readonly scope: Scope,
+    /** The constant pool of the activation that defined it, as it was then. */
+    readonly pool: Value[],
+    /** The clip whose code defined it, its activation's base clip, its target from SWF 6. */
+    readonly target: Target,
+    readonly clip: Avm1Object,
+    /**
+     * The `this` of the activation that defined it, which is its own where
+     * DefineFunction2 preloads or suppresses `this`; undefined from SWF 5,
+     * whose functions close over nothing (adl; Ruffle takes the caller's).
+     */
+    readonly definer: Value,
+  ) {
+    super(proto, world, notNative);
+  }
+
+  /**
+   * Run its body with `self` as `this`, `depth` how far up `this`'s
+   * prototypes it was found (which `super` starts from), in an activation
+   * of its own above the scope it closes over, or from SWF 5 above the
+   * clip of `this` or of the caller's target, as Flash 5 ran functions.
+   */
+  override call(self: Value, args: Value[], version: number, depth = 0): Value {
+    const realm = this.world;
+    const caller = realm.current;
+    if (caller === null) {
+      throw new Error("an AVM1 function called outside of AVM1 code");
+    }
+
+    if (realm.calls + 1 >= realm.maxCalls) {
+      throw new Disabled(`${realm.maxCalls} levels of recursion were exceeded`);
+    }
+
+    // Calls count down to the script timeout's check, as jumps back do.
+    if (--realm.budget < 0) {
+      realm.timeout();
+    }
+
+    if (self !== undefined && self !== null && isPrimitive(self)) {
+      self = realm.box(self, version);
+    }
+
+    let scope = this.scope;
+    let target = this.target;
+    let clip = this.clip;
+    if (this.version < 6) {
+      const own = self instanceof Avm1Object ? caller.host.clipOf?.(self) : undefined;
+      if (own !== undefined) {
+        target = own;
+        clip = self as Avm1Object;
+      } else {
+        target = targetOrRoot(caller);
+        clip = caller.clip;
+      }
+
+      scope = new Scope(realm.globalScope, SCOPE_Target, clip);
+    }
+
+    const flags = this.flags;
+    const local = new Avm1Object();
+    const inherited = (flags & (FUNCTION_PreloadThis | FUNCTION_SuppressThis)) !== 0;
+    const cx = new Activation(
+      caller.st,
+      this.pool,
+      target,
+      caller.host,
+      realm,
+      // adl counts a SWF 5 function's chain as a timeline's, for the With's limit.
+      new Scope(scope, SCOPE_Local, local, this.version < 6 ? scope.depth : scope.depth + 1),
+      inherited ? this.definer : self,
+      clip,
+    );
+    cx.code = this.code;
+    cx.callee = this;
+    cx.caller = caller.callee;
+    cx.args = args;
+    cx.depth = depth;
+    cx.receiver = self;
+
+    const params = this.params;
+    for (let i = 0; i < params.length; i++) {
+      const name = params[i];
+      if (name !== null) {
+        defineParam(local, name, i < args.length ? args[i] : undefined, this.version);
+      }
+    }
+
+    let pending = 0;
+    if ((flags & (FUNCTION_PreloadArguments | FUNCTION_SuppressArguments)) === 0) {
+      pending |= PENDING_Arguments;
+    }
+
+    if (
+      (flags & (FUNCTION_PreloadSuper | FUNCTION_SuppressSuper)) === 0 &&
+      depth > 0 &&
+      this.version >= 6 &&
+      self instanceof Avm1Object
+    ) {
+      pending |= PENDING_Super;
+    }
+
+    if (pending !== 0) {
+      cx.pending = pending;
+      local.lazy = cx;
+    }
+
+    realm.calls++;
+    realm.current = cx;
+    try {
+      return this.region(cx, self, args);
+    } catch (error) {
+      // Its clip was removed under it: it returns undefined there.
+      if (error === BASE_REMOVED) {
+        return undefined;
+      }
+
+      throw error;
+    } finally {
+      realm.calls--;
+      realm.current = caller;
+    }
+  }
+
+  /** As a constructor: its result is the object `new` made, whatever the body returns. */
+  override initialize(self: Avm1Object, args: Value[], version: number): void {
+    this.call(self, args, version, 1);
+  }
+
+  override callConstructor(self: Avm1Object, args: Value[], version: number, depth: number): Value {
+    return this.call(self, args, version, depth);
+  }
+}
+
+function notNative(): Value {
+  return undefined;
+}
+
+/** A parameter as a local variable; of two of the same name, the later. */
+function defineParam(local: Avm1Object, name: string, value: Value, version: number): void {
+  const p = local.own(name, version);
+  if (p === undefined) {
+    local.add(name, value, 0);
+  } else {
+    p.value = value;
+  }
+}
+
+/**
+ * `super` in a method: an object whose prototype is the one above where
+ * the method was found, whose methods run with the method's `this`.
+ */
+export class Avm1Super extends Avm1Object {
+  constructor(
+    /** The `this` of the method that made it. */
+    readonly self: Avm1Object,
+    /** How far up `self`'s prototypes the method was found. */
+    readonly depth: number,
+    version: number,
+  ) {
+    super(superProto(self, depth, version));
+  }
+}
+
+/** The prototype `depth` steps up from `self`, then its own: where `super` looks. */
+function superProto(self: Avm1Object, depth: number, version: number): Value {
+  let base: Value = self;
+  for (let i = 0; i < depth; i++) {
+    if (!(base instanceof Avm1Object)) {
+      return undefined;
+    }
+
+    base = base.protoFor(version);
+  }
+
+  return base instanceof Avm1Object ? base.protoFor(version) : undefined;
+}
+
+/**
+ * `super` for an activation, undefined where it has none: a plain call has
+ * none, nor does a SWF 5 (adl).
+ */
+export function superOf(cx: Activation, self: Value, version: number): Value {
+  return cx.depth > 0 && version >= 6 && self instanceof Avm1Object
+    ? new Avm1Super(self, cx.depth, version)
+    : undefined;
+}
+
+/** A function's `arguments`: an array of them, with `callee` and `caller`. */
+export function argumentsOf(cx: Activation, args: Value[], version: number): Avm1Object {
+  const array = cx.realm.newArray(args, version);
+  array.define("callee", cx.callee, DONT_ENUM);
+  array.define("caller", cx.caller, DONT_ENUM);
+  return array;
+}
+
+/** Whether `name` is `local` for a SWF of `version`. */
+const named = (name: string, local: string, version: number) =>
+  name === local || (version < 7 && fold(name) === local);
+
+/**
+ * `arguments` or `super` on a function's activation object `o`, as a
+ * lookup first misses it; any other name stays missing.
+ */
+export function pendingLocal(
+  cx: Activation,
+  o: Avm1Object,
+  name: string,
+  version: number,
+): Property | undefined {
+  let p: Property | undefined;
+  if (cx.pending & PENDING_Arguments && named(name, "arguments", version)) {
+    cx.pending &= ~PENDING_Arguments;
+    p = o.add("arguments", argumentsOf(cx, cx.args, version), 0);
+  } else if (cx.pending & PENDING_Super && named(name, "super", version)) {
+    cx.pending &= ~PENDING_Super;
+    // Not listed by for..in, as `arguments` is (adl).
+    p = o.add("super", superOf(cx, cx.receiver, version), DONT_ENUM);
+  }
+
+  if (cx.pending === 0) {
+    o.lazy = null;
+  }
+
+  return p;
+}