Skip to content

Cut the icon webfonts to the glyphs the templates draw (#63, stacked on #126) - #307

Open
r0ny123 wants to merge 19 commits into
masterfrom
perf/subset-icon-fonts
Open

r0ny123 wants to merge 19 commits into
masterfrom
perf/subset-icon-fonts

Conversation

@r0ny123

@r0ny123 r0ny123 commented Oct 21, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #126. Merge it first; until then this diff also shows its commits. This PR's own is the last one, 5111842.

Part of #63. base.html preloads Font Awesome's solid face on every signed-in page (issue #62). It is 150 KB for the 35 of its 1,389 glyphs the templates draw. This cuts the solid and regular faces to those glyphs, and to the text the faces cover. It also drops the 499 brand-icon rules #126's subset kept by mistake, about half of that stylesheet.

Change.

  • scripts/subset_fontawesome.py cuts the fonts as well as the CSS.
    • subset_fonts() (scripts/subset_fontawesome.py:109) writes the solid and regular faces as woff2 and TrueType to static/webfonts/subset/. point_at_subset_fonts() (:95) points the subset's @font-face rules at them.
    • Each cut face keeps the Basic Latin and angle-quote characters it maps (TEXT_CODEPOINTS, :50). Cut to the icons' private-use codepoints alone, Chromium drew the pager's « ‹ › » arrows about 0.15 px lower, though the glyph outlines and metrics were the same.
    • The whole fonts stay as the source, as all.css does for the CSS. The brands face is still the whole file, and no page draws from it.
  • The glyph-rule pattern (scripts/subset_fontawesome.py:38) knew only .fa-house::before. all.css writes its 499 brand icons' rules as .fa-github:before, so Trim the page weight: page-specific libraries, minified CSS, deferred Bootstrap, lazy Dropzone, gzip (#63) #126's subset kept every one of them as if it were not a glyph rule. The pattern now knows both spellings. fontawesome-subset.css drops from 45,797 to 22,334 bytes. Apart from the @font-face URLs, the rules it keeps are the same.
  • base.html:31 preloads the cut solid face.
  • Cutting needs fontTools with brotli. It is a tool for whoever adds an icon, not a dependency of the application, and main() checks for it before writing anything. ADR-0017 records the cut.

Verification. On the testbed, #126's head (4c80af2) and this branch ran as side instances against the live backend, logged in as analyst1. The measurements were taken at 8733e93; 5111842 changes only tests/testIconFonts.py. Apart from the logins, the POSTs were the function page's own to /explore/findLoops/, which computes an answer and writes nothing, and, on the #126 instance only, an earlier browser review of #306. That review saved analyst1's default filter in the instance's own database (it ended as it started) and issued analyst1 a new API token there. The backend's corpus is unchanged. The #126 screenshots predate those writes, and the Lighthouse runs follow them.

file, bytes on the wire #126 this branch
fa-solid-900.woff2 (preloaded on every signed-in page) 150,472 6,012
fa-regular-400.woff2 25,096 4,160
fontawesome-subset.css, gzipped 7,661 3,010

On /explore/samples, the icon stylesheet and the solid face come to 9,022 bytes, from 158,133.

Lighthouse 12.8.2, mobile. The two sides ran in turn, page by page, two runs each. Performance is given for each run; FCP and LCP are the mean of the two.

page Performance FCP LCP
/ 95/92 -> 98/93 1.89 -> 2.00 s 2.75 -> 2.22 s
/explore/samples 91/87 -> 91/95 2.35 -> 2.30 s 3.18 -> 2.58 s
/explore/samples/1 92/89 -> 97/93 2.13 -> 1.97 s 3.03 -> 2.33 s
/explore/functions/83 71/67 -> 76/72 2.99 -> 2.87 s 4.77 -> 4.31 s
1vN result 6ab3b4455ccfc2538ffea9b6 75/83 -> 91/88 2.98 -> 2.64 s 3.94 -> 3.01 s
/help 81/81 -> 88/88 1.85 -> 1.89 s 4.96 -> 3.73 s

The largest paint comes 0.46 to 1.23 s earlier on every page. First paint changes by between -0.34 and +0.11 s. On #126, jQuery and the project's scripts still block rendering on both sides; #245 and #304 defer them. The other three categories are the same on both sides. Best Practices is 93 on both, because base.html has no viewport meta tag, so the viewport and font-size audits fail. #253 adds the tag.

A browser review on the same font files, before the brand rules went, compared both sides element by element. It covered 37 pages and 18 more variants, at both widths, signed in and out, and found no icon missing or changed. It also opened about 236 menus, modals, tabs and accordions per side, and the CFG viewers, with identical results.

The same review also found:

  • the branch requests only the cut fonts, each once per page;
  • Chromium reports no unused preload;
  • with every woff2 refused, the cut TrueType fallback draws the same pages.

Tests.

  • New tests/testIconFonts.py reads the cut fonts with the standard library, since CI has no fontTools:

    • each face's character map from the TrueType file;
    • the woff2's table directory, which woff2 does not compress.

    It checks these things:

    • the subset CSS draws both faces from the cut files only;
    • each cut face maps exactly the codepoints the CSS draws, plus its text, so a face that was not cut again after the CSS changed fails;
    • every drawn codepoint is in the solid face;
    • the woff2 and TrueType files hold the same tables;
    • each cut is under a quarter of the whole face;
    • the copyright and name records are kept;
    • the preload names the cut face.
  • tests/testAssetDiet.py:

    • Every glyph rule the subset keeps draws an icon that a template or one of mcritweb's own scripts uses. It spells both patterns out itself, so the script's pattern cannot hide a rule from it.
    • The glyph-rule pattern knows both spellings.
    • The size check is tightened from half to a quarter of all.css.
  • tests/testIconPreload.py follows the preload to the cut face.

  • On Trim the page weight: page-specific libraries, minified CSS, deferred Bootstrap, lazy Dropzone, gzip (#63) #126's code (4c80af2), 18 of the 32 tests in the three changed test modules fail. The new one that passes there too is a guard: test_the_table_lists_are_the_specifications, the self-check of the woff2 tag table.

  • Full suite with Chromium on 5111842: 2158 passed, none skipped; with master 8fd5a8c merged in, 2562 passed. ruff check . is clean.

Relation to open PRs. A trial merge (git merge-tree) with each open PR head adds no conflict to those #126 already has, and the merge with #306, also stacked on #126, is clean. #133 adds icons, rotate-right and sliders. As with #126's subset, if it merges after this it re-runs scripts/subset_fontawesome.py, which now cuts the fonts too. #254's key and #301's triangle-exclamation are on master, and the merge of master cuts them in. tests/testAssetDiet.py fails until it does, and tests/testIconFonts.py fails if the CSS is regenerated without the fonts.

Master 8fd5a8c is merged in directly (68df33c), with #126's part resolved as on #126, and one adaptation commit, 59bc403, which regenerates the subset CSS and the cut faces for master's fa-key and fa-triangle-exclamation (the solid woff2 is now 6,144 bytes).

r0ny123 added 16 commits August 30, 2026 04:44
Issue #63, first bullet: "remove data-tables js/css once it is not needed
anymore". base.html loaded 623 KB of render-blocking JavaScript and 41 KB of
CSS on every page in the app, for two calls.

DataTables is removed outright, not moved. Its one initialiser selected
`#job-table`, and the jobs page renders its table with `table_id=active` -
the job method - so the selector matched nothing on every request. Confirmed
against the running app: `id="job-table"` appears in zero of /data/jobs,
?active=..., ?state=... and /. It was also configured with paging, searching
and info all off, so even where it had matched it would only have restyled
the table.

jQuery UI moves to result_cross.html, the only page that calls `.sortable()`.
{% block style %} runs after base.html's scripts, so jQuery is in place first.

Measured with Chromium, total decoded bytes per page:

    /                     1667 KB -> 1017 KB
    /explore/samples      1667 KB -> 1017 KB
    /data/jobs            1667 KB -> 1017 KB
    /data/result/<cross>  1691 KB -> 1595 KB   (keeps jQuery UI)

Behaviour is unchanged: `.sortable()` still applies on the cross compare, the
clipboard tooltips still get Bootstrap instances rather than jQuery UI's -
both libraries define `.tooltip()`, and removing jQuery UI makes which one
wins deterministic rather than a load-order race - and no page logs a console
error.

Deliberately not done: `defer` on the remaining scripts, and removing jQuery.
Both need an audit of 23 inline blocks and 36 onclick handlers, several of
which call functions declared at the top level of those blocks; that is a
separate change. The remaining majority of the render-blocking weight is CSS,
not JS - bootstrap.css alone is 196 KB and is the unminified build.
Every unit job on every Python version fails with:

    /opt/hostedtoolcache/Python/3.11.16/x64/bin/python: No module named pytest

The Makefile said "pytest and pytest-cov arrive with mcrit, so requirements.txt
covers both". mcrit declares them under its `dev` extra:

    $ python -c "import importlib.metadata as m; print(m.requires('mcrit'))"
    ... 'pytest; extra == "dev"', 'pytest-cov; extra == "dev"' ...

so a plain `pip install -r requirements.txt` does not bring them in, and the
suite has not actually run in CI since mcrit moved them there. Ruff is green
throughout, which is why this looked like a working pipeline.

Installed in the workflow rather than added to requirements.txt: neither is a
runtime dependency and a deployment should not get them. Pinned, for the same
reason the lint job pins ruff. The two stale comments that said otherwise are
corrected.
`init` still ran `pip install -r requirements.txt` alone, so a fresh checkout
that follows the README lands without pytest and `make test` fails with
"No module named pytest" - the same failure the CI change on this branch fixes
for the runner, left unfixed for a contributor.

pytest and pytest-cov are not runtime dependencies and are not in
requirements.txt; mcrit declares them under its `dev` extra, which nothing
here requests, so they do not arrive transitively either. Install them from
`init`, pinned to the versions CI uses, and say so once above the target
rather than in a comment further down that describes a step that never ran.

Reported by Codex review.
…rst one was safe

The previous commit did #63's first bullet. The other four are "consider", "enable
text compression" and "what to inline"; a recorded, measured decision is the
resolution for those, so ADR-0015 makes them. Numbers first, all from Chromium
driving the app over real HTTP against the captured corpus.

  * text compression is the largest win left, and it is not ours. Nothing is
    compressed anywhere: Flask's static handler does not, and neither does the
    reference deployment - nginx.conf, mcritweb_plain.conf and mcritweb_ssl.conf in
    danielplohmann/docker-mcrit at 7e9501a carry no gzip directive, and location /
    proxies /static/ straight through. Simulating `gzip on;` in front of this branch,
    cold Fast-3G load of /, median of 7: first paint 3872 ms -> 1024 ms, wire
    1,069,548 B -> 354,002 B. That is more than the whole of the first bullet, and it
    belongs in docker-mcrit.

  * lazy dropzone: right target, wrong shape today. dropzone.js is 353,924 B, 38% of
    every page, but it loads at the end of <body>, so blocking it outright - an upper
    bound - moves first paint by 8 ms. It buys DOMContentLoaded (1585 -> 1009 ms) and
    23% of the transfer. The cost is Flask-Dropzone: dropzone.config() emits
    Dropzone.options.myDropzone *after* the library and only works because discovery
    waits for DOMContentLoaded. Injected late, contentLoaded() sees readyState
    "complete" and binds the element with default options - no CSRF header, no
    autoProcessQueue: false. Doing it right means replacing create()/config() by hand
    in the one place static/dropzone.js's local patch has to keep working.
    "autocomplete on mouseover" is 4,621 B, 1,507 gzipped: no.

  * removing jQuery: no. 15 of 26 inline blocks call $, 36 inline event attributes
    hang off them, trace_CFG/main.js and main_duo.js expect it from base.html, jQuery
    UI cannot load without it, and .tooltip()/.modal() go through Bootstrap's jQuery
    bridge. 89,503 B, 30,882 gzipped - under 9% of a compressed page.

  * inline vs reference is already right: 7,141 B of inline JS against 902,940 B of
    referenced library. The remaining CSS weight (bootstrap.css is the unminified
    build) compresses 8x, so gzip answers that too.

ADR-0004 asked #63 to assert rather than assume which library owns $.fn.tooltip, and
called the current arrangement a load-order race. Measured, it is not one. Bootstrap
5.0.2 defines its jQuery plugins on DOMContentLoaded, after every plain <script> in
the document, so it wins the name in both arrangements - jQuery UI before it, as
base.html used to, and after it, as result_cross.html now does. Checked on every page
that renders a [data-toggle="tooltip"] target: $.fn.tooltip.Constructor.NAME is
"tooltip", bootstrap.Tooltip.getInstance(el) is set, $(el).data("ui-tooltip") is not.
What does flip it is loading jQuery UI *after* DOMContentLoaded, which is exactly what
a lazy loader would do - so the hazard is lazy loading, not ordering.
test_bootstrap_is_loaded_synchronously pins that.

The one factual correction: the previous commit said DataTables' initialiser "selected
an element the app never renders". The app does render id="job-table" - job_table
still defaults to it and job_overview and single_sample take the default, confirmed on
/explore/samples/1. What made DataTables dead is narrower: the initialiser lived on
the jobs page, which passes table_id=active. The removal stands; the reason in the
comments and the test docstring did not, and now says what was measured.

New tests, each mutation-checked by breaking the code it guards:

  TestTheJobsPage             - none of the three jobs views renders id="job-table"
  TestTheCrossComparePage     - the rendered page ships jquery-ui, jquery.js reaches
                                it first, and no other page ships it at all
  test_only_base_html_loads_a_jquery      - both CFG templates' second jQuery stays
                                            commented out
  test_bootstrap_is_loaded_synchronously  - no defer/async on the bundle

code_of() now strips HTML comments as well as Jinja ones, which is what makes the
second-jQuery check see the commented-out includes as absent rather than present.
…zone, gzip

Font Awesome is reduced to the icons the templates use, Bootstrap ships
minified and deferred, the Dropzone script and stylesheet load on the first
drag or on opening the modal, and responses over 1 KiB of compressible types
leave gzipped (MCRITWEB_COMPRESS_RESPONSES turns it off behind a proxy that
compresses itself).
ADR-0015 had left compression to the proxy and the other bullets to a later
audit. Both happened; 0015 is marked superseded and 0016 holds the
measurements and the rules that follow from them.
The type-ahead conflicts are the ones that matter. This branch's side of
js/ac_family_names.html and the submit dropzone still carried the old
family-name code - names shipped with |tojson and pushed unescaped into a
widget that renders suggestions through innerHTML, which is the injection
master closed in #168 (and #146 moved to a JSON endpoint). Master's
escaped code is kept in both places; what this branch contributes there
is only its reason to change them, that Bootstrap is now deferred, so the
widgets are built once the deferred scripts have run. In
ac_family_names.html the DOMContentLoaded listener is also the scope,
replacing master's IIFE, so this branch's timing test can see it. The
Playwright tests that drive the real widget pass with Bootstrap deferred.

The rest:
- base.html: the minified Bootstrap and the Font Awesome subset, with
  master's signed-in font preload (#62) - the subset loads the same
  ../webfonts/fa-solid-900.woff2 the preload names; Bootstrap and
  post_action.js deferred, page_loading.js kept a plain script as master
  has it; clearDropzone keeps the lazy-load guard with master's const.
- the dropzone keeps mcritInitDropzone(), with master's const myDropzone
  (#61) - nothing outside that function uses it.
- import.html takes master's import status script, with dropzone.min.js.
- README keeps the compression paragraph and master's reverse-proxy
  section.
- the Font Awesome subset is regenerated for three icons master's
  templates added (arrows-rotate, code, diagram-project), nothing else
  changes in it; the subset script lists the webfont file stems as
  non-glyphs, since master's preload and its comment name
  fa-solid-900.woff2 and the icon scan read that as an icon.

1026 passed, ruff clean.
…libraries

Master replaced the family names shipped with each page by a type-ahead that
fetches them as they are typed (#192), and the submit dropzone now includes
js/ac_family_names.html instead of building its own list. Kept master's
widget and this branch's reason to touch it: Bootstrap is deferred, so the
widgets are built in a DOMContentLoaded listener rather than master's IIFE.
The dropzone macro takes master's signature without `families` and keeps
`lazy`, which base.html's overlay still passes.
The lazy loader, the query and submit pages and the import page loaded
static/dropzone.min.js, which is stock Dropzone 5.9.2. Only dropzone.js
carries the patch that sends the head of a dropped file, so a drop posted
no file_header and the submit form was no longer pre-filled. All three
load dropzone.js again; dropzone.min.js is the retired file now.

A failed fetch of the script left mcritDropzoneLoading set, so the overlay
never opened again on that page. It is cleared on error, and the next drag
tries again without adding a second stylesheet. A dragover while the
script is on its way no longer queues the same callback again. The two
URLs go into the script through |tojson.
send_file answers If-None-Match against the plain ETag before the
after_request hook renames it, so a client revalidating its gzipped copy
never matched and downloaded every asset again. The conditional check is
made again against the renamed ETag.

HTML is no longer compressed. A page carries the session's CSRF token, the
same in every response, next to input it reflects, which is what a BREACH
attack needs. Downloads, the /api passthrough, bodies of unknown length
and bodies over 1 MiB are left alone too: the exports and the cached
result download are streamed so that they never sit in memory whole, and
reading them in to gzip them undid that.

gzip;q=0 is a refusal; request.accept_encodings reads it as one. The
README said docker-mcrit's NGINX compresses; its configuration has no
gzip directive (ADR 0015).
…irect in its test

Master's templates now use fa-pen, which the Font Awesome subset did not carry, so
scripts/subset_fontawesome.py is rerun. /data/jobs now redirects to the URL that
names its first tab, so the DataTables id check follows the redirect to the page
that is actually rendered.
Batch C brought master docs/adr/0016-slow-function-search-is-mcrits.md,
so this branch's 0016 shared the number. The record moves to 0017 and
ADR-0015's status line points at it; nothing else names the file.
base.html preloads the solid face on every signed-in page, 150 KB for
the 35 of its 1,389 glyphs the templates use. subset_fontawesome.py now
also writes the solid and regular faces cut to those glyphs, as woff2
and TrueType, to static/webfonts/subset/, and points the subset's
@font-face rules and the preload at them. Each cut face keeps the Basic
Latin and angle-quote characters it maps; without them Chromium placed
the pager's arrows a fraction of a pixel lower.

The script's glyph-rule pattern knew only `.fa-x::before`, while all.css
writes its 499 brand icons' rules as `.fa-x:before`, so the subset kept
every one of them. It now knows both, and the subset CSS drops from
45,797 to 22,334 bytes.

Cutting needs fontTools with brotli, a tool for whoever adds an icon.
tests/testIconFonts.py reads the cut files with the standard library and
fails when a face lacks a glyph the CSS draws or holds one it does not.
# Conflicts:
#	mcritweb/__init__.py
#	mcritweb/templates/base.html
#	mcritweb/templates/table/submit_or_query_dropzone.html
Master's legacy-token notice and statistics page use fa-key and
fa-triangle-exclamation, which the cut stylesheet and the cut solid face
did not have. Regenerated with scripts/subset_fontawesome.py.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant