The Filter Changed After the User Tapped Off: Race-Proof Tencent RTC Beauty AR

T0  User selects a GAN effect
T1  The app starts preparing its resources
T2  User taps “Off”
T3  The UI changes to Off
T4  The old preparation finishes
T5  The GAN effect is applied anyway

type ViewState =
  | { kind: "ready"; active: "off" }
  | { kind: "preparing"; requested: EffectId; resolved: EffectId }
  | { kind: "active"; requested: EffectId; active: EffectId; degraded: boolean }
  | { kind: "failed"; requested: EffectId; message: string };

mkdir beauty-intent-coordinator
cd beauty-intent-coordinator
npm init -y
npm install --save-dev typescript tsx @types/node
mkdir src test

export type EffectId = "off" | "soft-beauty" | "virtual-bg" | "gan-look";

type EffectDefinition = {
  id: EffectId;
  needsSegmentation: boolean;
  needsGan: boolean;
  fallback: EffectId;
};

const EFFECTS: Record<EffectId, EffectDefinition> = {
  off: {
    id: "off",
    needsSegmentation: false,
    needsGan: false,
    fallback: "off",
  },
  "soft-beauty": {
    id: "soft-beauty",
    needsSegmentation: false,
    needsGan: false,
    fallback: "off",
  },
  "virtual-bg": {
    id: "virtual-bg",
    needsSegmentation: true,
    needsGan: false,
    fallback: "soft-beauty",
  },
  "gan-look": {
    id: "gan-look",
    needsSegmentation: false,
    needsGan: true,
    fallback: "soft-beauty",
  },
};

export type DevicePolicy = {
  segmentationAllowed: boolean;
  ganAllowed: boolean;
  budget: "normal" | "constrained";
};

export type ViewState =
  | { kind: "ready"; active: "off" }
  | { kind: "preparing"; requested: EffectId; resolved: EffectId }
  | {
      kind: "active";
      requested: EffectId;
      active: EffectId;
      degraded: boolean;
    }
  | { kind: "failed"; requested: EffectId; message: string };

export interface BeautyAdapter {
  /** Fetch or prepare resources. It should honor cancellation where possible. */
  prepare(effect: EffectId, signal: AbortSignal): Promise<void>;

  /** Commit one prepared effect to the processing pipeline. */
  apply(effect: EffectId): Promise<void>;

  /** Remove appearance processing and return to unmodified video. */
  clear(): Promise<void>;
}

export interface OutputGate {
  /** Synchronously prevent processed output from being shown or published. */
  hold(reason: "off-requested" | "consent-withdrawn"): void;

  /** Release the unmodified camera path after processing has been cleared. */
  releaseRaw(): void;
}

export class BeautyCoordinator {
  private consent = false;
  private desired: EffectId = "off";
  private version = 0;
  private preparation?: AbortController;
  private work: Promise<void> = Promise.resolve();

  private state: ViewState = { kind: "ready", active: "off" };

  constructor(
    private readonly adapter: BeautyAdapter,
    private readonly gate: OutputGate,
    private policy: DevicePolicy,
  ) {}

  getState(): ViewState {
    return this.state;
  }

  setConsent(granted: boolean): void {
    if (granted === this.consent) return;

    this.consent = granted;
    this.version += 1;
    this.preparation?.abort();

    if (!granted) {
      // Consent withdrawal invalidates the old preference. Re-enabling consent
      // will not silently restore a previous appearance effect.
      this.desired = "off";
      this.gate.hold("consent-withdrawn");
    }

    this.enqueue();
  }

  select(effect: EffectId): void {
    if (effect !== "off" && !this.consent) {
      this.state = {
        kind: "failed",
        requested: effect,
        message: "Consent is required before applying an appearance effect.",
      };
      return;
    }

    this.desired = effect;
    this.version += 1;
    this.preparation?.abort();

    if (effect === "off") {
      this.gate.hold("off-requested");
    }

    this.enqueue();
  }

  updatePolicy(policy: DevicePolicy): void {
    this.policy = policy;
    this.version += 1;
    this.preparation?.abort();
    this.enqueue();
  }

  async idle(): Promise<void> {
    await this.work;
  }

  private enqueue(): void {
    // One writer reaches the adapter at a time. Each queued reconciliation
    // reads the latest intent, so bursts naturally coalesce.
    this.work = this.work.then(() => this.reconcile());
  }

  private resolve(requested: EffectId): EffectId {
    const effect = EFFECTS[requested];

    if (requested === "off") return "off";

    if (this.policy.budget === "constrained") {
      if (effect.needsGan || effect.needsSegmentation) {
        return effect.fallback;
      }
    }

    if (effect.needsGan && !this.policy.ganAllowed) {
      return effect.fallback;
    }

    if (effect.needsSegmentation && !this.policy.segmentationAllowed) {
      return effect.fallback;
    }

    return requested;
  }

  private async reconcile(): Promise<void> {
    const operationVersion = this.version;
    const requested = this.desired;

    if (!this.consent || requested === "off") {
      try {
        await this.adapter.clear();
        this.state = { kind: "ready", active: "off" };
        this.gate.releaseRaw();
      } catch (error) {
        this.state = {
          kind: "failed",
          requested: "off",
          message: `Could not clear the effect: ${messageOf(error)}`,
        };
        // Do not release processed output when clear has not been confirmed.
      }
      return;
    }

    const resolved = this.resolve(requested);
    this.state = { kind: "preparing", requested, resolved };

    const abort = new AbortController();
    this.preparation = abort;

    try {
      await this.adapter.prepare(resolved, abort.signal);

      // Preparation completed, but another user action may now be authoritative.
      if (operationVersion !== this.version) return;

      await this.adapter.apply(resolved);

      // apply() might not be cancellable. If intent changed while it ran, leave
      // final reconciliation to the queued operation.
      if (operationVersion !== this.version) return;

      this.state = {
        kind: "active",
        requested,
        active: resolved,
        degraded: requested !== resolved,
      };
    } catch (error) {
      if (operationVersion !== this.version || isAbort(error)) return;

      try {
        await this.adapter.clear();
        this.gate.releaseRaw();
      } catch {
        // Keep the output gate's existing safety posture if cleanup also fails.
      }

      this.state = {
        kind: "failed",
        requested,
        message: `Effect unavailable: ${messageOf(error)}`,
      };
    } finally {
      if (this.preparation === abort) this.preparation = undefined;
    }
  }
}

function isAbort(error: unknown): boolean {
  return error instanceof Error && error.name === "AbortError";
}

function messageOf(error: unknown): string {
  return error instanceof Error ? error.message : "unknown error";
}

import assert from "node:assert/strict";
import test from "node:test";
import {
  BeautyAdapter,
  BeautyCoordinator,
  EffectId,
  OutputGate,
} from "../src/coordinator.js";

const sleep = (ms: number) =>
  new Promise<void>((resolve) => setTimeout(resolve, ms));

class FakeAdapter implements BeautyAdapter {
  prepared: EffectId[] = [];
  applied: EffectId[] = [];
  clears = 0;
  prepareDelay = 0;
  applyDelay = 0;
  failApply = false;

  async prepare(effect: EffectId, signal: AbortSignal): Promise<void> {
    this.prepared.push(effect);

    await new Promise<void>((resolve, reject) => {
      const timer = setTimeout(resolve, this.prepareDelay);
      signal.addEventListener(
        "abort",
        () => {
          clearTimeout(timer);
          const error = new Error("aborted");
          error.name = "AbortError";
          reject(error);
        },
        { once: true },
      );
    });
  }

  async apply(effect: EffectId): Promise<void> {
    await sleep(this.applyDelay);
    if (this.failApply) throw new Error("GPU setup failed");
    this.applied.push(effect);
  }

  async clear(): Promise<void> {
    this.clears += 1;
  }
}

class FakeGate implements OutputGate {
  held = false;
  reasons: string[] = [];

  hold(reason: "off-requested" | "consent-withdrawn"): void {
    this.held = true;
    this.reasons.push(reason);
  }

  releaseRaw(): void {
    this.held = false;
  }
}

const normalPolicy = {
  segmentationAllowed: true,
  ganAllowed: true,
  budget: "normal" as const,
};

test("latest selection wins while preparation is in flight", async () => {
  const adapter = new FakeAdapter();
  const gate = new FakeGate();
  adapter.prepareDelay = 20;

  const coordinator = new BeautyCoordinator(adapter, gate, normalPolicy);
  coordinator.setConsent(true);
  coordinator.select("virtual-bg");

  await sleep(5); // Let virtual-bg preparation begin.
  coordinator.select("gan-look");
  await coordinator.idle();

  assert.deepEqual(adapter.applied, ["gan-look"]);
  assert.deepEqual(coordinator.getState(), {
    kind: "active",
    requested: "gan-look",
    active: "gan-look",
    degraded: false,
  });
});

test("consent withdrawal holds output before a non-cancellable apply ends", async () => {
  const adapter = new FakeAdapter();
  const gate = new FakeGate();
  adapter.applyDelay = 25;

  const coordinator = new BeautyCoordinator(adapter, gate, normalPolicy);
  coordinator.setConsent(true);
  coordinator.select("gan-look");

  await sleep(5); // apply() is now in flight.
  coordinator.setConsent(false);

  assert.equal(gate.held, true);
  assert.equal(gate.reasons.at(-1), "consent-withdrawn");

  await coordinator.idle();

  assert.deepEqual(coordinator.getState(), { kind: "ready", active: "off" });
  assert.equal(gate.held, false);
  assert.ok(adapter.clears > 0);
});

test("a constrained budget resolves GAN to the declared fallback", async () => {
  const adapter = new FakeAdapter();
  const gate = new FakeGate();
  const coordinator = new BeautyCoordinator(adapter, gate, {
    segmentationAllowed: true,
    ganAllowed: true,
    budget: "constrained",
  });

  coordinator.setConsent(true);
  coordinator.select("gan-look");
  await coordinator.idle();

  assert.deepEqual(adapter.applied, ["soft-beauty"]);
  assert.deepEqual(coordinator.getState(), {
    kind: "active",
    requested: "gan-look",
    active: "soft-beauty",
    degraded: true,
  });
});

test("an apply failure returns to raw video and remains visible", async () => {
  const adapter = new FakeAdapter();
  const gate = new FakeGate();
  adapter.failApply = true;

  const coordinator = new BeautyCoordinator(adapter, gate, normalPolicy);
  coordinator.setConsent(true);
  coordinator.select("virtual-bg");
  await coordinator.idle();

  assert.equal(coordinator.getState().kind, "failed");
  assert.ok(adapter.clears > 0);
  assert.equal(gate.held, false);
});

npx tsx --test test/*.test.ts

class TencentBeautyAdapter implements BeautyAdapter {
  constructor(
    private readonly beautyRuntime: YourDocumentedBeautyIntegration,
  ) {}

  async prepare(effect: EffectId, signal: AbortSignal): Promise<void> {
    // Map your application's effect ID to the documented resource-loading path.
    // If that path cannot consume AbortSignal, check signal.aborted before and
    // after loading and let the coordinator reject stale completion.
  }

  async apply(effect: EffectId): Promise<void> {
    // Map exactly one resolved effect to your documented Beauty AR setup.
  }

  async clear(): Promise<void> {
    // Remove appearance processing using the documented integration path.
  }
}