update-web-assets
Skill160 starsChanged 5 days agoApache-2.0View on GitHub
Update the third-party JavaScript vendored into the app for the artifact, diagram, and math WebViews (KaTeX, mermaid, marked, highlight.js, Tailwind, Babel, React) and the npm modules React artifacts may import (lucide-react, recharts, three, date-fns, react-router, shadcn/ui and its Radix base, dat.gui, vaul). Checks what is outdated, reads each pin's rationale before proposing a bump, re-downloads from the official source, verifies the lock, and runs the gates. Ends by naming what must be checked on a device, because a broken WebView asset fails silently. Use when bumping a vendored web library, adding a new one, or investigating whether a rendering bug comes from a stale pin.
- Installs packages
In this repository13 other files it gives its agents.
- app/CLAUDE.mdCLAUDE.md
- build-logic/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- fastlane/CLAUDE.mdCLAUDE.md
- .github/CLAUDE.mdCLAUDE.md
- shared/CLAUDE.mdCLAUDE.md
- audit-depsSkill
- audit-i18nSkill
- audit-paritySkill
- marketing-refreshSkill
- release-highlightsSkill
- small-screensSkill
- sync-upstreamSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 5 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
Read
scripts/web-assets.jsonbefore doing anything: Every entry carries a pin_reason, and several of them are load-bearing rather than … - Distinctive: line 41
Do not report a bump as done on green gates alone.
- Very specific: line 54
If --check fails before you have changed anything, stop and report it — someone hand-edited a vendored file, or a repin was left …
- Very specific: line 62
Read its pin_reason in the registry.
- Distinctive: line 63
If the reason forbids or constrains the bump, say so and do not bump it.
- Distinctive: line 65
mermaid: must stay on the v10 line (v11+ is ESM-only and fails in Android WebView).
- Very specific: line 67
Check the upstream changelog for breaking changes in the range, especially anything touching the entry point path the registry's files …
- Very specific: line 88
Dependency policy applies: Before adding or bumping one, check its last release date and its advisories (npm audit in …
- Distinctive: line 120
If the bump changes the entry point path or an API the renderer calls, update the HTML builder in the same pass.
- Distinctive: line 174
Do not open a PR. Per the repo's convention, stop at local commits and let the user device-test first.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Update vendored web assets
The artifact, diagram and math renderers are WebViews, and every script they execute ships
inside the app. scripts/web-assets.json is the registry; scripts/vendor-web-assets.py
moves the bytes; scripts/web-assets.lock.json records a sha256 per file and CI verifies it.
Read scripts/web-assets.json before doing anything. Every entry carries a
pin_reason, and several of them are load-bearing rather than informational — two pins
must NOT be moved to the newest version, and the reason is in the file, not in this skill.
What makes this different from a Gradle dependency bump
A wrong version here does not fail the build, fail a test, or throw anything Kotlin can catch. The failure happens inside the WebView, and the usual shape of it is a blank box or a feature that quietly stops working. Both libraries this system replaced were already broken that way before anyone noticed:
- marked deleted its
highlightoption in v5. Passing one tosetOptionsis accepted and silently ignored, so syntax highlighting had been dead with no error anywhere. - highlight.js was being loaded from a URL that served CommonJS. In a browser
<script>that throws immediately and never defineshljs.
So: the gates below prove the wiring is consistent, and only a device proves it renders. Do not report a bump as done on green gates alone.
Phase 0 — Establish what is stale
scripts/vendor-web-assets.py --check # tree matches the lock (should be clean first)
scripts/vendor-web-assets.py --outdated # what npm has that we don't
scripts/vendor-web-assets.py --list # what each asset is for, and who uses it--outdated prints each pin's pin_reason next to any version it reports. Read it. It is
advisory output about a registry that has opinions.
If --check fails before you have changed anything, stop and report it — someone
hand-edited a vendored file, or a repin was left half-applied. That is a finding to raise,
not a precondition to quietly re-sync away.
Phase 1 — Decide, per asset
For each asset the user named (or each one --outdated flags, if they named none):
- Read its
pin_reasonin the registry. - If the reason forbids or constrains the bump, say so and do not bump it. Two known
standing constraints, both explained in full in the registry:
- mermaid must stay on the v10 line (v11+ is ESM-only and fails in Android WebView).
- react / react-dom must move together and are bounded by UMD availability.
- Check the upstream changelog for breaking changes in the range, especially anything
touching the entry point path the registry's
filesblock names. A package that reorganises itsdist/is the most likely way a bump fails, and--syncwill refuse with a clear error if a declared path no longer exists. - For a major version, use AskUserQuestion rather than deciding alone.
Artifact modules (source.type: "bundle")
The packages a React artifact may import are not lifted from a tarball: esbuild bundles each
into one classic script from scripts/artifact-modules/ (exact pins in package.json, the tree in
package-lock.json, the bundling in build.mjs). So:
--syncneeds node and npm (npm ci --ignore-scriptsruns inside it).--checkdoes not.--bumprefuses bundles. Repin inpackage.json, runnpm install --prefix scripts/artifact-modules --ignore-scriptsto refresh the lockfile, set the registry entry'sversionto match, then--sync.--checkfails until the lock's recipe hash matches, so a lockfile edited without a re-sync can't ship.--outdatedreports single-package bundles; forshadcn-uirunnpm outdatedin that directory.- What to bundle follows web:
standardDependenciesin upstreamclient/src/utils/artifacts.ts(watched asartifact-sandpack-dependencies), with divergences recorded in eachpin_reason. lucide-react stays on the exact version the server's artifact prompt names. - Dependency policy applies. Before adding or bumping one, check its last release date and its
advisories (
npm auditinscripts/artifact-modules). A package that is unmaintained, deprecated or vulnerable but still worth shipping gets anadvisory(kind,library) and asandbox_riskexplaining why the sandbox makes it acceptable. Users are then asked before an artifact loads it (ArtifactLibraryGate), so a flagged library must live in a bundle of its own (as vaul does): declining it has to keep its code from running at all. - The shadcn components come from upstream source at a pinned commit (
components_url,shared_files_urlin the shadcn-ui and vaul entries). After a sync, move both entries' URLs and shadcn-ui'sversionto the newUPSTREAM_VERSIONcommit.build.mjsrefuses to build when upstream mounts a component no entry lists, or the registry lists one upstream dropped.
tailwind is pinned to a URL, not npm, because Tailwind v3 never published a browser
build. --bump refuses it deliberately; repinning it means editing both the version and
every file URL in the registry by hand, and moving to @tailwindcss/browser means moving
to v4, which is a behaviour change for artifacts (the registry explains which utilities
changed).
Phase 2 — Apply
scripts/vendor-web-assets.py --bump <id> <version>This repins the registry, wipes that asset's directory, re-downloads from the official
tarball, rewrites the lock, and regenerates VendoredWebAssets.kt and the Settings catalog of
flagged libraries (core/data/…/FlaggedArtifactLibraries.kt). The wipe is deliberate:
a repin that drops a file must not leave the old one behind to be served.
Adding a new asset instead: add a registry entry (with a real why, pin_reason and
used_by), run --sync, then reference it from the renderer by a path relative to the
document base — never an absolute URL.
If the bump changes the entry point path or an API the renderer calls, update the HTML builder in the same pass. The builders are:
| Asset | Built in |
| katex | androidMain/components/LatexBlock.kt, iosMain/components/PlatformMediaComponents.ios.kt |
| mermaid | androidMain/components/MermaidDiagram.kt, commonMain/…/artifact/MermaidWebContent.kt, iosMain/components/PlatformMediaComponents.ios.kt |
| marked, marked-highlight, highlight | commonMain/…/artifact/MarkdownWebContent.kt |
| tailwind, babel, react, react-dom | commonMain/…/artifact/ArtifactWebContent.kt |
every bundle asset | loaded by commonMain/…/artifact/ArtifactWebContent.kt through the generated VendoredWebAssets.MODULES; which modules load is ReactArtifactImports.kt; the consent prompt for advisory entries is ArtifactLibraryGate.kt |
| jszip, docx-preview | not built here: the server builds the document; commonMain/…/artifact/OfficePreviewLocalizer.kt rewrites its exact CDN URLs (VENDORED_OFFICE_RENDERERS). Repin only to the server's DOCX_PREVIEW_CDN versions, and update the map in the same pass |
Note KaTeX and mermaid each have two independent HTML builders (Android and iOS) that do not share code. Changing one and not the other is the easiest mistake to make here.
Phase 3 — Gates
scripts/vendor-web-assets.py --check
./gradlew :feature:chat:testDebugUnitTest --tests '*VendoredAssetReferenceTest*' \
--tests '*ReactArtifactRenderTest*'
./gradlew :feature:chat:detekt
./gradlew :app:assembleDebugVendoredAssetReferenceTest is the one that matters most: it asserts that no document
references a remote origin, that no CSP lets one execute, and that every path a document
references exists in the generated manifest — which is what catches a bump that renamed a
dist file, since the symptom otherwise is a blank WebView.
Per the repo's workflow preference, skip iOS builds unless asked; if asked, stop at the
Gradle framework link (./gradlew :feature:chat:compileKotlinIosSimulatorArm64).
Phase 4 — Report, and name the device check
Report: which assets moved, from and to; the APK size delta if it is material; anything in
a pin_reason you deliberately did not act on.
Then state plainly that the gates cannot confirm rendering, and name what to look at for the assets that actually moved:
| Asset | What to look at on a device |
| katex | a message containing $$x^2$$ — check glyphs AND that fonts loaded (no fallback serif) |
| mermaid | a ```mermaid block in a message, and a mermaid artifact opened fullscreen |
| marked / marked-highlight / highlight | a markdown artifact with a fenced code block — highlighting present, theme matches light/dark |
| tailwind | an HTML artifact using utility classes |
| babel / react / react-dom | a React artifact that uses hooks; then one importing an unbundled package, which must show the naming error rather than a blank box |
| jszip / docx-preview | a code-interpreter DOCX preview — page-style render, NOT the "High-fidelity renderer unavailable" fallback notice |
any bundle asset | a React artifact importing it renders (VendoredWebAssetInstrumentedTest has one case per bundle: run it on an emulator); for one with an advisory, the prompt appears inline and fullscreen, and Don't load shows the stub |
VendoredWebAssetInstrumentedTest covers the bundles on a real WebView:
ANDROID_SERIAL=<emulator> ./gradlew :feature:chat:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.garfiec.librechat.feature.chat.components.web.VendoredWebAssetInstrumentedTest.
Do not open a PR. Per the repo's convention, stop at local commits and let the user device-test first.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

