Files
hyperframes/packages/cli/src/commands/motion-sample.browser.test.ts
T
Miguel Ángelandmiga-heygen e8659cb653 fix(cli): recognize textual motion in sweep checks (#3707)
* fix(cli): fingerprint textual sweep state

* fix(cli): share one motion classifier between sweep guard and liveness

The frozen-sweep guard (sweep_static) and keepsMoving liveness (motion_frozen)
each owned their own definition of "what counts as motion": the sweep
fingerprint in layout-audit.browser.js read nine channels while
motion-sample.browser.js compared box + opacity only. They meet in one decision
in checkPipeline.ts, so a fixed-width attr() countdown was accepted by the
sweep guard and still reported frozen by liveness.

Move the classifier into motion-signature.browser.js, injected before both
samplers, and make it the single owner:

- Per-element channels (box, opacity, font-variation axes, clip-path, direct
  text, form-control state, ::before/::after content, media pixels) as a
  reader list so further channels (e.g. SVG dash) plug in.
- Liveness consumes the same signature with 2px / 0.08 bucketing; the sweep
  guard consumes it exact. motion-sample throws at install if the shared
  script is missing.
- Counter state is a composition-level channel over box-generating elements
  and root ancestors. display:none subtrees generate no boxes and are
  excluded, and only declarations naming a counter that some painted
  generated content (::before/::after/::marker on a non-ignored, paintable
  host) consumes are folded in, so a decoy hidden counter cannot make a
  frozen composition read as live.
- clip-path is a channel, replacing the fingerprint's former reliance on the
  clipped-away visibility probe, so a wipe over a static box still counts.
- data-layout-ignore layers are excluded from the signature but not from the
  per-selector `visible` bit reported for explicit motion assertions.
- Root resolution for the "*" liveness scope now matches the sweep guard and
  the root element is part of its own signature.

Tests: motion-signature.browser.test.ts (happy-dom, per-element fake computed
style so ancestor handling comes from the classifier) and
motion-signature.browser.chromium.test.ts (real Chromium via puppeteer-core;
skips without a system browser) pin every branch: attr() substitution,
display:none decoys, named-counter gating, ::marker, zero-box hosts, ancestor
counters, textarea/indeterminate, root text, clip-path, ignore layers, and
sweep/liveness agreement on the countdown fixture.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* fix(cli): prune unrendered content from the motion signature and measure asserted scopes

The shared motion classifier pruned only display:none subtrees, so text,
pseudo content, media pixels, and counter decoys inside skipped
content-visibility contents changed the frozen-sweep and liveness
signatures although nothing painted. Pruning is now platform-owned where
checkVisibility exists (display:none, skipped hidden/auto contents; a
display:contents host keeps its painting pseudo-elements), with the
computed-style fallback for happy-dom. A content-visibility:hidden host
signs its own box, opacity, clip-path, font axes, and widget state, but
not its text, pseudo content, control value, or media pixels; hosts where
size containment does not apply (non-atomic inline, display:contents,
table and internal table boxes, ruby) skip nothing. isVisibleElement
regains the checkVisibility floor layout-audit uses on its opacity-floor
path, so an asserted selector inside skipped contents reports hidden.

The layout-audit opt-out no longer applies to the element passed as the
signature root: a keepsMoving scope that is itself data-layout-ignore is
measured (an assertion naming an element outranks the opt-out) instead of
producing an empty signature that motionAudit reports as a missing
selector. Opt-outs inside the scope still apply.

motion-sample defers the missing-classifier error to the first call so
the driver's evaluate surfaces it instead of an opaque "is not a
function" page error; round() is shared.

The real-Chromium suite is opt-in on Windows (HYPERFRAMES_BROWSER_TESTS=1):
in the shared Windows package lane the runner's Chrome did not launch
within the package hookTimeout, and the suite already runs on Linux CI
where the system Chrome is found. The launch hook has its own 120s ceiling.

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* fix(cli): prune display:contents in skipped contents; table-cell skips, caption paints

A display:contents child of a content-visibility:hidden host has no box
of its own, so the platform check could not tell it apart from an
ordinary display:contents owner and it stayed a counter consumer: a
change of the owner's counter-reset altered the sweep signature although
nothing paints. The parent's skipsContents verdict now prunes it; boxed
descendants keep being decided by the platform.

NOT_CONTAINABLE_DISPLAY had table-cell and table-caption inverted
versus Chromium 152, where a table-cell host skips its contents and a
table-caption host paints them.

Four Chromium pins: the display:contents-in-skipped-contents counter, a
table-cell host's own text and pseudo content (frozen), a table-caption
host's own text and pseudo content (motion), and a counter reachable
only through a skipped host's hidden ::marker / ::after (frozen; also
asserts the skipped child is not visible for motion-sample).

Co-Authored-By: Miguel Ángel <miguel.sierra@heygen.com>

* chore(cli): trim sweep motion comments to the comment ratchet

* chore(cli): shorten sweep motion comments to the merge-hook limit

---------

Co-authored-by: miga-heygen <miguel.sierra_miga@heygen.com>
2026-10-02 06:25:18 -07:00

205 lines
7.8 KiB
TypeScript

// @vitest-environment happy-dom
// fallow-ignore-file code-duplication
import { afterEach, describe, expect, it, vi } from "vitest";
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
const __dirname = dirname(fileURLToPath(import.meta.url));
const signatureScript = readFileSync(join(__dirname, "motion-signature.browser.js"), "utf-8");
const script = readFileSync(join(__dirname, "motion-sample.browser.js"), "utf-8");
interface Geo {
rect?: { left: number; top: number; width: number; height: number };
opacity?: string;
display?: string;
visibility?: string;
/** `::after` computed `content`; re-read on every call when a getter. */
afterContent?: string;
}
interface SampleResult {
data: Record<
string,
{ rect: { left: number; right: number }; opacity: number; visible: boolean } | null
>;
liveness: Record<string, string>;
}
function installGeometry(byId: Record<string, Geo>): void {
vi.spyOn(window, "getComputedStyle").mockImplementation((element, pseudoElement) => {
const geo = byId[(element as Element).id] ?? {};
if (pseudoElement) {
return {
content: pseudoElement === "::after" ? (geo.afterContent ?? "none") : "none",
} as unknown as CSSStyleDeclaration;
}
return {
display: geo.display ?? "block",
visibility: geo.visibility ?? "visible",
opacity: geo.opacity ?? "1",
} as unknown as CSSStyleDeclaration;
});
vi.spyOn(Element.prototype, "getBoundingClientRect").mockImplementation(function (this: Element) {
const geo = byId[this.id]?.rect ?? { left: 0, top: 0, width: 0, height: 0 };
return {
left: geo.left,
top: geo.top,
right: geo.left + geo.width,
bottom: geo.top + geo.height,
width: geo.width,
height: geo.height,
} as DOMRect;
});
}
function installScript(): void {
// The sampler reads the shared motion classifier at install time.
// eslint-disable-next-line no-new-func
new Function(signatureScript)();
// eslint-disable-next-line no-new-func
new Function(script)();
}
function sample(options: { selectors?: string[]; livenessScopes?: string[] }): SampleResult {
const fn = (window as unknown as { __hyperframesMotionSample: (o: unknown) => SampleResult })
.__hyperframesMotionSample;
return fn(options);
}
describe("motion-sample.browser", () => {
afterEach(() => {
vi.restoreAllMocks();
document.body.innerHTML = "";
delete (window as unknown as { __hyperframesMotionSample?: unknown }).__hyperframesMotionSample;
Reflect.deleteProperty(window, "__hyperframesMotionSignature");
Reflect.deleteProperty(window, "__hyperframesLayoutGeometry");
});
it("installs without the shared motion classifier and names it on the first call", () => {
// Installing must not throw: addScriptTag resolves on load regardless, so
// the driver only ever sees the error from its evaluate call.
// eslint-disable-next-line no-new-func
expect(() => new Function(script)()).not.toThrow();
expect(() => sample({ livenessScopes: ["*"] })).toThrow(/motion-signature\.browser\.js/);
});
it("samples a present, visible selector and returns null for an absent one", () => {
document.body.innerHTML = `
<div data-composition-id="main"><div id="headline">Hi</div></div>
`;
installGeometry({
headline: { rect: { left: 100, top: 50, width: 300, height: 80 }, opacity: "1" },
});
installScript();
const result = sample({ selectors: ["#headline", "#missing"] });
expect(result.data["#headline"]).toMatchObject({ visible: true, opacity: 1 });
expect(result.data["#headline"]?.rect).toMatchObject({ left: 100, right: 400 });
expect(result.data["#missing"]).toBeNull();
});
it("reports an explicitly asserted data-layout-ignore element as visible", () => {
document.body.innerHTML = `
<div data-composition-id="main"><div id="glow" data-layout-ignore>x</div></div>
`;
installGeometry({ glow: { rect: { left: 100, top: 50, width: 300, height: 80 } } });
installScript();
// The layout-audit opt-out excludes the layer from liveness, not from an
// assertion that names it.
expect(sample({ selectors: ["#glow"] }).data["#glow"]?.visible).toBe(true);
});
it("reflects inherited ancestor opacity", () => {
document.body.innerHTML = `
<div data-composition-id="main"><div id="wrap"><div id="headline">Hi</div></div></div>
`;
installGeometry({
wrap: { rect: { left: 0, top: 0, width: 400, height: 200 }, opacity: "0.5" },
headline: { rect: { left: 100, top: 50, width: 300, height: 80 }, opacity: "0.6" },
});
installScript();
const result = sample({ selectors: ["#headline"] });
expect(result.data["#headline"]?.opacity).toBeCloseTo(0.3, 5);
});
it("produces a different liveness signature when an element moves and an identical one when static", () => {
document.body.innerHTML = `<div data-composition-id="main"><div id="box">x</div></div>`;
installGeometry({ box: { rect: { left: 100, top: 100, width: 50, height: 50 } } });
installScript();
const before = sample({ livenessScopes: ["*"] }).liveness["*"];
vi.restoreAllMocks();
installGeometry({ box: { rect: { left: 100, top: 100, width: 50, height: 50 } } });
installScript();
const stillStatic = sample({ livenessScopes: ["*"] }).liveness["*"];
vi.restoreAllMocks();
installGeometry({ box: { rect: { left: 300, top: 100, width: 50, height: 50 } } });
installScript();
const moved = sample({ livenessScopes: ["*"] }).liveness["*"];
expect(stillStatic).toBe(before);
expect(moved).not.toBe(before);
});
// Liveness and the frozen-sweep guard share one classifier: a fixed-width
// attr()-backed countdown that the sweep guard accepts as motion must not be
// reported frozen by keepsMoving.
it("changes the liveness signature when attr-backed generated content changes, in step with the sweep fingerprint", () => {
document.body.innerHTML = `
<div data-composition-id="main"><span id="countdown" data-txt="10"></span></div>
`;
installGeometry({
countdown: {
rect: { left: 280, top: 140, width: 80, height: 48 },
get afterContent() {
return JSON.stringify(document.getElementById("countdown")!.getAttribute("data-txt"));
},
},
});
installScript();
const sweep = (window as unknown as { __hyperframesLayoutGeometry: () => string })
.__hyperframesLayoutGeometry;
const livenessBefore = sample({ livenessScopes: ["*"] }).liveness["*"];
const sweepBefore = sweep();
document.getElementById("countdown")!.setAttribute("data-txt", "09");
expect(sample({ livenessScopes: ["*"] }).liveness["*"]).not.toBe(livenessBefore);
expect(sweep()).not.toBe(sweepBefore);
});
it("signs a leaf withinSelector scope by the scope element itself", () => {
document.body.innerHTML = `
<div data-composition-id="main"><div id="logo">x</div></div>
`;
installGeometry({ logo: { rect: { left: 10, top: 10, width: 50, height: 50 } } });
installScript();
// The scope root is part of its own signature; a leaf scope is never "missing".
expect((sample({ livenessScopes: ["#logo"] }).liveness["#logo"] ?? "").length).toBeGreaterThan(
0,
);
});
it("scopes liveness to a withinSelector and returns empty for a missing scope", () => {
document.body.innerHTML = `
<div data-composition-id="main"><div id="scene"><div id="box">x</div></div></div>
`;
installGeometry({
scene: { rect: { left: 0, top: 0, width: 500, height: 500 } },
box: { rect: { left: 10, top: 10, width: 50, height: 50 } },
});
installScript();
const result = sample({ livenessScopes: ["#scene", "#nope"] });
expect((result.liveness["#scene"] ?? "").length).toBeGreaterThan(0);
expect(result.liveness["#nope"]).toBe("");
});
});