agentleFS
garfiecgarfiec/Librechat-Mobile/.claude/skills/update-web-assets/SKILL.md

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

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
  1. Very specific:

    Read scripts/web-assets.json before doing anything: Every entry carries a pin_reason, and several of them are load-bearing rather than …

    line 24
  2. Distinctive:

    Do not report a bump as done on green gates alone.

    line 41
  3. Very specific:

    If --check fails before you have changed anything, stop and report it — someone hand-edited a vendored file, or a repin was left …

    line 54
  4. Very specific:

    Read its pin_reason in the registry.

    line 62
  5. Distinctive:

    If the reason forbids or constrains the bump, say so and do not bump it.

    line 63
  6. Distinctive:

    mermaid: must stay on the v10 line (v11+ is ESM-only and fails in Android WebView).

    line 65
  7. Very specific:

    Check the upstream changelog for breaking changes in the range, especially anything touching the entry point path the registry's files …

    line 67
  8. Very specific:

    Dependency policy applies: Before adding or bumping one, check its last release date and its advisories (npm audit in …

    line 88
  9. Distinctive:

    If the bump changes the entry point path or an API the renderer calls, update the HTML builder in the same pass.

    line 120
  10. Distinctive:

    Do not open a PR. Per the repo's convention, stop at local commits and let the user device-test first.

    line 174

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 highlight option in v5. Passing one to setOptions is 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 defines hljs.

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):

  1. Read its pin_reason in the registry.
  2. 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.
  3. Check the upstream changelog for breaking changes in the range, especially anything touching the entry point path the registry's files block names. A package that reorganises its dist/ is the most likely way a bump fails, and --sync will refuse with a clear error if a declared path no longer exists.
  4. 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:

  • --sync needs node and npm (npm ci --ignore-scripts runs inside it). --check does not.
  • --bump refuses bundles. Repin in package.json, run npm install --prefix scripts/artifact-modules --ignore-scripts to refresh the lockfile, set the registry entry's version to match, then --sync. --check fails until the lock's recipe hash matches, so a lockfile edited without a re-sync can't ship.
  • --outdated reports single-package bundles; for shadcn-ui run npm outdated in that directory.
  • What to bundle follows web: standardDependencies in upstream client/src/utils/artifacts.ts (watched as artifact-sandpack-dependencies), with divergences recorded in each pin_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 audit in scripts/artifact-modules). A package that is unmaintained, deprecated or vulnerable but still worth shipping gets an advisory (kind, library) and a sandbox_risk explaining 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_url in the shadcn-ui and vaul entries). After a sync, move both entries' URLs and shadcn-ui's version to the new UPSTREAM_VERSION commit. build.mjs refuses 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:

AssetBuilt in
katexandroidMain/components/LatexBlock.kt, iosMain/components/PlatformMediaComponents.ios.kt
mermaidandroidMain/components/MermaidDiagram.kt, commonMain/…/artifact/MermaidWebContent.kt, iosMain/components/PlatformMediaComponents.ios.kt
marked, marked-highlight, highlightcommonMain/…/artifact/MarkdownWebContent.kt
tailwind, babel, react, react-domcommonMain/…/artifact/ArtifactWebContent.kt
every bundle assetloaded 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-previewnot 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:assembleDebug

VendoredAssetReferenceTest 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:

AssetWhat to look at on a device
katexa message containing $$x^2$$ — check glyphs AND that fonts loaded (no fallback serif)
mermaida ```mermaid block in a message, and a mermaid artifact opened fullscreen
marked / marked-highlight / highlighta markdown artifact with a fenced code block — highlighting present, theme matches light/dark
tailwindan HTML artifact using utility classes
babel / react / react-doma React artifact that uses hooks; then one importing an unbundled package, which must show the naming error rather than a blank box
jszip / docx-previewa code-interpreter DOCX preview — page-style render, NOT the "High-fidelity renderer unavailable" fallback notice
any bundle asseta 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.