Opened 2 months ago
Closed 6 weeks ago
#66131 closed defect (bug) (fixed)
Emoji scripts carry code which never runs, with no tests or type checking
| Reported by: | westonruter | Owned by: | westonruter |
|---|---|---|---|
| Priority: | normal | Milestone: | 7.2 |
| Component: | Emoji | Version: | 4.4 |
| Severity: | normal | Keywords: | has-patch has-unit-tests |
| Cc: | Focuses: | javascript, docs, coding-standards |
Description
Several things in the two scripts behind emoji replacement, src/js/_enqueues/lib/emoji-loader.js and src/js/_enqueues/wp/emoji.js, do not work, and some of them never have. Others cannot run at all in any browser able to load the files. Neither script is type checked and neither has a test of any kind, which is a good part of why none of this has been noticed. This ticket proposes fixing the defects, and then doing the work which would have caught them: adding both to the TypeScript checked files as the next step of #65997, modernizing the JavaScript, correcting the inline documentation in the spirit of #65951 and #66033, and giving them their first tests.
For the loader this is a direct continuation of r60899, which converted it from a blocking inline script to a script module and modernized it on the way, giving it const, let and arrow functions, and of r60902, which moved it to the footer and removed the last of its ready handling. Both were work on #63842, the second also closing #64076. Neither touched wp-emoji.js, which is why one of the two already reads as current JavaScript and the other does not.
Defects
The fallback for an emoji image which fails to load has never worked. The handler given to Twemoji refers to the library object in three places where it means the image element. The library object has no parentNode, so the handler returns having done nothing, and a reader is left with a broken image icon rather than the character the image stood for. Twemoji's own handler, in src/js/_enqueues/vendor/twemoji.js, which this one was adapted from, uses this throughout, which is what it is called with.
The MutationObserver looks for the data-error attribute that handler is supposed to set, in order to recognize a replacement it must leave alone, so that branch cannot be reached either. The two depend on each other: without the attribute, the observer parses the replacement text straight back into the image which has just failed.
That guard abandons every remaining mutation record rather than the one it has recognized, which makes the callback sensitive to the order the records are visited in. It cannot be left for another day: the moment the handler sets the attribute, the guard is reached for the first time, and anything added in the same batch as a failed image is then never parsed. Correcting the handler on its own would trade one defect for another. Measured with only the handler corrected, an element added alongside a failed image is dropped; with the guard also corrected to skip only its own record, it is kept.
An <svg> element has its text replaced with <img> elements. Twemoji avoids SVG when collecting text to replace, but that test is applied to the descendants of whatever it is given rather than to the node itself, so an <svg> arriving as an added node is parsed. The same goes for MathML. Neither should be parsed.
The exclusion class is matched as a substring. doNotParse() searches the class attribute for wp-exclude-emoji rather than testing for the class, so wp-exclude-emoji-wrapper, my-wp-exclude-emoji and wp-exclude-emojis all exclude an element and everything beneath it. It should test for the class.
TypeScript
Both files should be added to the files list in tsconfig.json. Doing so reports thirty errors for the loader and twenty-seven for wp-emoji.
Two new entries under typings/ are needed to resolve them:
- One declaring
WorkerGlobalScope, which thedomlib does not provide and which thewebworkerlib cannot be used for, as the two conflict. - One declaring the settings which PHP exports through
_print_emoji_detection_script(), along with the vendored Twemoji library. These belong outside either script, because both read them.
The exported settings are also incompletely documented. baseUrl, ext, svgUrl and svgExt are all exported and read, and none of them are described anywhere.
One caution for whoever writes the annotations. TypeScript passing is not on its own enough to say an annotation is a good one, because the editors do not read all of the same forms. Describing what wpEmoji() returns as typeof parse and typeof test type checks perfectly well, and leaves PhpStorm unable to say what wp.emoji is at all, which in turn has it report every call made through that as a call to something which might not be a function. Writing the two signatures out suits both. Forms which both understand should be preferred wherever there is a choice.
Code which cannot run
The following should be removed:
- The Internet Explorer 11 workaround. Support was dropped in 5.8, and the browser cannot parse the file at all once it uses
const, failing before it reaches the guarded block. browserSupportsSvgAsImage(). It asksdocument.implementation.hasFeature(), which the DOM standard requires to returntruefor any argument, so the PNG fallback is unreachable and the SVG images are always used.- The vendor prefixed spellings of
MutationObserver, and the check that it exists. It has been baseline widely available since July 2015.
Modernization
The loader had most of this in r60899. What follows is largely wp-emoji.js catching up with it.
varshould be replaced throughout, one declaration apiece.- The nested counting loops in the observer callback should become
for...of. - The
nodeTypeandnodeNamecomparisons should becomeinstanceoftests. Those narrow, where the comparisons do not, so the casts currently needed to reachdata,altandgetAttributecan go. Editors which do not follow inline cast comments report those three as unresolved. - The
data-errormarker should be written and read throughdataset. - The anonymous callbacks should become arrow functions, except the failed image handler, which is called with the image as
this. Declaring that callback to take anHTMLImageElementasthismeans converting it by mistake stops the build rather than going unnoticed. - The image attributes should be decided once, rather than the property being replaced after the fact.
wpEmoji()should be called as the function it is. It builds no instance and never refers tothis, returning an object instead, so calling it withnewdoes nothing but discard an empty instance, and the@classtag above it describes something the code has never been.- Spacing should be corrected per the JavaScript coding standard, which asks for a space after
functionwhen the function is anonymous.
Documentation
Several descriptions restate the name of the thing they describe, and the typedef for what is kept in session storage has no description for itself or for either of its properties, so nothing records that the timestamp is in milliseconds. These are reported by jsdoc/require-property-description and jsdoc/informative-docs, neither of which is enabled yet, and can be fixed without changing the configuration, per the workflow in #66033.
Two findings worth recording for #66033 while they are fresh:
jsdoc/no-undefined-typesappears unusable on these files, reportingWindow,HTMLElementandCanvasRenderingContext2Das undefined. It is not. The ESLint configuration declares no browser globals, and once it does, only the project's own types remain, which the rule'sdefinedTypesoption accounts for. Note thatglobals.browsercontains a key with trailing whitespace which ESLint 10 rejects outright.jsdoc/tag-linesshould not be enabled with its default options. It requires no blank lines between tags, which is the opposite of the documented template, and would strip the tag grouping from every docblock which currently conforms.
Tests
Neither script has a test of any kind. The PHPUnit tests for emoji touch wp-includes/js/wp-emoji-loader.js into existence so the PHP which prints the script tag can find it, but nothing has ever run a line of either file.
QUnit tests should be added for wp-emoji, covering wp.emoji.test(), everything wp.emoji.parse() decides, the callbacks it composes but does not otherwise expose, and the observer it installs. Each of the defects above should be covered by a test which fails without the fix.
The recovery from a failed image needs both halves covered, and separately. The handler marking the image it replaces, and the observer recognizing that mark and leaving the replacement be, only do anything together, so a test of either alone says little. The observer half wants a control beside it: the same replacement made twice, once marked and once not, where only the unmarked one is parsed. That the two differ is what shows the mark to be doing the work.
Anyone writing the observer tests should know that every test in this suite is wrapped by sinon-test, which swaps the timers for a fake clock. A callback left on that clock is never called, so waiting for the observer with a timer hangs the whole suite rather than failing. Mutation records are delivered in a microtask, and waiting on one of those works.
The loader is harder. It exports nothing and performs its work when imported, so there is no seam to test through. Giving it one is a larger change and is probably a separate ticket.
Size
Measured on a branch implementing the above, the effect on the minified scripts is:
| File | Before | After |
|---|---|---|
wp-emoji.min.js | 2,820 bytes | 2,280 bytes |
wp-emoji-loader.min.js | 2,942 bytes | 2,995 bytes |
The loader grows slightly: checking that URL.createObjectURL is callable, and testing explicitly that session storage returned anything, both cost a few bytes.
Not included
The expiry on the cached support tests, which is #58663, is out of scope here.
#66120 is not fixed by any of this, and is worth reading alongside it. An excluded element is still parsed when it is itself the node handed to parse(), because doNotParse() is only consulted for the descendants of that node. Running the cases in that ticket against the work proposed here gives the same counts as against trunk, including the case its reporter had not tested: text added inside an excluded element is replaced too.
The two do meet in one place, though. The proposed fix there is a check in the observer before parse() is called, and the observer loop is one of the things being rewritten here, so whichever lands second will have to be rebased over the other. The rewritten loop resolves the element to parse into a constant and tests it before parsing, which is where such a check would go.
🤖 Prepared with the assistance of Claude Opus 5 using Claude Code.
Change History (4)
This ticket was mentioned in PR #13592 on WordPress/wordpress-develop by @westonruter.
2 months ago
#2
- Keywords has-patch has-unit-tests added
@westonruter commented on PR #13592:
6 weeks ago
#3
🤖 _Comment by Claude Opus 5.5_
A final code review was run on the branch before committing. Nine findings came back. None was judged to need a change here: each is either a pre-existing issue, an intended change already covered in the commit message, or a narrow edge case. They are recorded below for reference.
Possible follow-up tickets
The Worker in the loader has no onerror handler. Only onmessage is set, so if the Worker fails asynchronously the support-test promise never resolves, and Twemoji is never loaded on browsers that need it. One trigger is a CSP whose worker-src / script-src does not allow blob:. This predates the branch.
emoji_svg_url is commonly filtered to false. The filter is documented as taking a string, but add_filter( 'emoji_svg_url', '__return_false' ) appears 139 times across 134 plugins in the directory, including WP Fastest Cache, Autoptimize and The Events Calendar. It dates from when wp_resource_hints() reused this filter for the s.w.org dns-prefetch, which was removed in r53904. On such sites settings.svgUrl is false, so Twemoji falls back to its own default base, and the callback in wp-emoji.js builds https://cdn.jsdelivr.net/gh/jdecked/twemoji@17.0.1/assets/<icon>.svg. That path does not exist, since the SVGs live under assets/svg/, so every replaced emoji on those sites has always been a broken image. With this PR the restored onerror fallback turns them back into the emoji character, which is an improvement. Casting the filtered value to a string would make things worse: '' is a valid base, so each image would request a relative <icon>.svg from the site itself and get a WordPress 404. Falling back to the default URL when the value is not a non-empty string would fix it, though it would start sending requests to s.w.org on sites that may have returned false to avoid exactly that.
Known or intended
- A failed image can be re-parsed. When a text node is later added to the same parent, the observer can turn the restored character back into an image that fails again. This was noted in the approval above and is acceptable, since the browser caches the failed request.
wp-exclude-emojiis now matched exactly. Classes such aswp-exclude-emoji-wrapperno longer exclude an element. This is intended and covered by tests.- The loader now throws when no 2D canvas context is available. It fails at the same point as before, just with a clearer error, so nothing gets worse.
- The trailing
return falsewas removed frombrowserSupportsEmoji(). The set of test kinds is fixed within the file, and a missingcaseis now reported bytsc.
Minor
- The
instanceofchecks in the observer can miss nodes from another realm. A node created in a same-origin iframe and moved into the document failsinstanceof HTMLElement, where the oldnodeTypechecks accepted it. This is an obscure case, but it is the one real cost of switching toinstanceof. - The observer can re-parse the same parent. Each added text node triggers
parse()on its parent, so several siblings added in one batch re-walk the same subtree. This predates the branch. - The QUnit settings fixture hard-codes the 17.0.2 emoji URLs. It will drift from
_print_emoji_detection_script()on the next version bump, but it is only test data.
Adds both emoji scripts to the TypeScript checked files, fixes the defects that surfaced along the way, modernizes the JavaScript, and gives them their first tests.
For the loader this continues r60899 and r60902, which converted it to a script module and modernized it in passing. Neither touched
wp-emoji.js, which is why one of the two already read as current JavaScript and the other did not.Each commit is one change with its own reasoning, and was verified in isolation.
Defects fixed
The fallback for an emoji image which fails to load has never worked. The handler given to Twemoji referred to the library object in three places where it meant the image element. The library object has no
parentNode, so the handler returned having done nothing: a reader was left with a broken image icon rather than the character the image stood for. Introduced in r35637 for Core-34640, so it has been shipping since 4.4.The
MutationObserverlooks for thedata-errorattribute that handler was supposed to set, in order to recognize a replacement it must leave alone, so that branch was unreachable too. The two need each other — without the attribute, the observer parses the replacement text straight back into the image which has just failed.That guard abandoned every remaining mutation record rather than the one it recognized, which made the callback sensitive to the order records were visited in. It could not be left for later: the moment the handler sets the attribute the guard becomes reachable, so correcting the handler alone would have traded one defect for another. Measured with only the handler corrected, an element added alongside a failed image is dropped; with the guard corrected too, it is kept.
An
<svg>element had its text replaced with<img>elements. Twemoji avoids SVG when collecting text to replace, but applies that test to the descendants of whatever it is given rather than to the node itself, so an<svg>arriving as an added node was parsed. The same went for MathML.The exclusion class was matched as a substring, so
wp-exclude-emoji-wrapper,my-wp-exclude-emojiandwp-exclude-emojisall excluded an element and everything beneath it.Code which could not run
const, failing before it reaches the guarded block. Confirmed by parsing the built file with acorn atecmaVersion: 5.browserSupportsSvgAsImage(). It askeddocument.implementation.hasFeature(), which the DOM standard requires to returntruefor any argument, so the PNG fallback was unreachable in both directions.MutationObserver, and the check that it exists.TypeScript
Thirty errors were reported for the loader and twenty-seven for
wp-emoji.js. Two entries are added undertypings/: one forWorkerGlobalScope, which thedomlib does not provide and which thewebworkerlib cannot be used for as the two conflict; and one for the settings PHP exports through_print_emoji_detection_script()together with the vendored Twemoji library, which live outside either script because both read them. The settings were also incompletely documented —baseUrl,ext,svgUrlandsvgExtare all exported and read, and none were described.One thing worth knowing for the wider effort in Core-65997: TypeScript passing is not on its own enough to say an annotation is a good one. Describing what
wpEmoji()returns astypeof parsetype checks perfectly well, and leaves PhpStorm unable to say whatwp.emojiis at all, which has it report every call through that as possibly not a function. Writing the signatures out suits both.Tests
Twenty-nine QUnit tests, run against both the unminified and the minified script. They cover
wp.emoji.test(), everythingwp.emoji.parse()decides, the callbacks it composes but does not otherwise expose, and the observer it installs.Every defect above is covered by a test which fails without its fix. Each was checked by reintroducing the defect and confirming the suite goes red by name, then restoring.
The observer tests need a little care, noted in the file for whoever comes next: every test in this suite is wrapped by sinon-test, which swaps the timers for a fake clock, so waiting for the observer with a timer hangs the suite rather than failing it. Mutation records arrive in a microtask, and waiting on one of those works.
The loader has no tests. It exports nothing and does its work when imported, so there is no seam to test through; giving it one is a larger change and belongs elsewhere.
Size
wp-emoji.min.jswp-emoji-loader.min.jsThe loader grows slightly: checking that
URL.createObjectURLis callable, and testing explicitly that session storage returned anything, both cost a few bytes.Not included
Core-58663, the expiry on the cached support tests, is untouched.
Core-66120 is not fixed here. An excluded element is still parsed when it is itself the node handed to
parse(). Running that ticket's cases against this branch gives the same counts as against trunk, including the case its reporter had not tested: text added inside an excluded element is replaced too. The two do meet in one place, though — the fix proposed there is a check in the observer beforeparse()is called, and this rewrites that loop, so whichever lands second will need rebasing.Use of AI Tools
AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Substantially the whole of it. The code changes, the QUnit tests, the commit messages and this description were authored by the model working from my direction, and were reviewed and corrected by me throughout; two of the twenty-two commits are entirely mine. Every behavioral claim above was verified by running it — reintroducing each defect and watching the relevant test fail by name, parsing the built file to confirm the IE 11 branch is unreachable, and reproducing Core-66120 against both trunk and this branch — rather than taken on the model's word.
🤖 Generated with Claude Code