Create modular javascript for bundling

[oscarlevin]

With the help of copilot I have a possible way forward on making the javascript modular and easier to maintain. I'm marking this as draft, since it definitely needs more eyes and testing, but from what I've seen, there are no functional changes to the sample article or sample book.

The idea is that we will maintain a js/src directory with modular files that get bundled by a esbuild function (see script/jsbuilder) This creates js/dist/pretext-core.js and js/dist/pretext-search.js (since we don't always provide the search javascript).

There was an initial attempt to remove jquery (and I think we removed the reliance on jquery from pretext_add_on's replacements), but I think maybe some runestone js requires us to have a copy of jquery? I don't really understand that.

So @rbeezer and @ascholerChemeketa, do you think this is the sort of thing we want? Any suggestions? When we are mostly happy with the new file structure I will remove the old files we no longer need and clean up all the commits.

[ascholerChemeketa]

Thoughts - not trying to start discussion here necessarily, mostly so I remember.

Any appetite for moving raw source to typescript? IMO it goes a long way to reduce some sources of bugs related to type coercion between things like null, undefined, "", false, etc... If there was, seems like a logical time to introduce.

Integration with themes? There isn't tons of theme specific JS. So don't think we need to do anything at this stage. But if a theme needs specific JS for handling UI elements, it would be nice to only include that when necessary (especially if different themes have conflicting requirements). What might that look like? Sidecar files? Monolithic self contained single js file for each theme?

Definitely not a part of this PR, but IMO PTX should not have to inject JQuery for RS. RS should be bundling that itself.

[rbeezer]

Yes, I would be in favor of modernization and bundling. pretext_add_on is not a very professional looking file anyway! Not much I can do as far as a review or an opinion (I did read the first commit with the plan, etc.)

I see your CoPilot and raise you by a Claude Code. Next.

[rbeezer]

This is a significant infrastructure change — modularizing the JavaScript, removing jQuery from core, and introducing an esbuild-based build system. Some observations:

Architecture. The approach mirrors the existing CSS build system (script/cssbuilder/ -> css/dist/), which is good for consistency. The entry point pattern (pretext-core-entry.js imports focused modules, esbuild bundles to an IIFE) is clean and the jsbuilder tool with watch mode will be useful for development.

jQuery removal. jQuery is removed from core and only loaded conditionally for Runestone builds (pretext-runestone.xsl line 227-229). The jQuery file itself was updated from 3.3.1 to 3.7.1 — presumably for security, but worth noting since it's not mentioned in the PR description. The core bundle uses vanilla DOM throughout.

Old files not removed. The original files (pretext.js, pretext_add_on.js, knowl.js, lti_iframe_resizer.js, pretext_search.js) are still in the repository. The PR description mentions "When we are mostly happy with the new file structure I will remove the old files" — but these should definitely be removed before merge. They're no longer loaded (the XSL now points to dist/pretext-core.js and dist/pretext-search.js) and leaving them creates confusion about which files are authoritative.

Built artifacts in the repo. The js/dist/ directory contains bundled output (pretext-core.js at 1615 lines, pretext-search.js at 263 lines) plus source maps (140KB total). Committing built artifacts is a trade-off — it means users without Node.js can still build PreTeXt, but it creates a risk of the dist files drifting out of sync with the source modules. The CSS build system already sets this precedent, so this is consistent. The source maps might not need to be committed to the repo though, since they're only useful for debugging in a browser dev console.

Copilot instructions file. The PR adds .github/copilot-instructions.md (88 lines). This is GitHub Copilot configuration for the repo, not part of the JS modernization itself. It should be a separate PR if it's wanted — and it's worth a broader discussion about whether the project wants AI tool configuration in the repository.

PLAN.md. script/jsbuilder/PLAN.md (203 lines) documents the modernization phases and dead code analysis. This is useful context during development but probably shouldn't be merged — it's process documentation, not reference documentation. The README.md in the same directory is more appropriate for long-term inclusion.

lti-iframe-resizer template is now empty. The lti-iframe-resizer named template (line 10876) had its <script> tag removed since the code is now bundled, but the empty template shell remains. It's still called at line 11214. This is fine — the template serves as a no-op placeholder — but a comment explaining why it's empty (beyond the existing one-liner) would help future maintainers who might wonder if something was accidentally deleted.

The knowl.js comment reference. Line 13814 still says knowl.js code controls Sage Cells within knowls. This comment should be updated to reference the new location.

The knowl module was substantially rewritten. Comparing the old knowl.js (338 lines, vanilla DOM with manual animation) to the new js/src/knowl.js (337 lines), the new version introduces a SlideRevealer class with a proper state machine. This is a functional change, not just a modularization — it changes how knowl animations work. The PR description says "there are no functional changes" but this should be verified carefully, especially the animation behavior and the edge cases around nested knowls and MathJax re-typesetting.

Dead code is preserved with deprecation flags. The deprecated/ subdirectory contains auto-id.js, scrollbar-width.js, and video-magnify.js. These are still imported and executed in the entry point (lines 80-83 of pretext-core-entry.js). If they're truly dead, they should not be bundled at all — importing dead code adds bundle size and potential for runtime errors. If there's uncertainty about whether they're dead, that's fine to note, but they shouldn't run on every page load.

Responding to @ascholerChemeketa's comment about TypeScript: that would be a separate decision and probably best deferred until the modular structure settles. The current JS modules are a good foundation that TypeScript could be layered onto later.

Claude Opus 4.6, acting as a review assistant for Rob Beezer

[bnmnetp]

Removing jQuery will break the interactive components in static html builds.
This would be project on the runestone side as the Sphinx build system always include jQuery in a runestone build.

I'm sure it can be done, but I think I would rather put my efforts into the continued removal of jQuery from the components themselves and once that is complete then you would not need to include it anywhere.

Brad Miller, acting like he knows what he's talking about.

[oscarlevin]

Thanks everyone. I am 100% on board with moving toward typescript (that's what I'm using for pretext tools and such).

The various comments about old files and the plan.md and copilot-instructions.md, I totally agree that they will go away before this is merged.

I'll take a close look at the knowl.js rewrite and make sure that is for the best.

So I guess that if that gets resolved, then this is likely good to go. I'll try to get this cleaned up this weekend.

[rbeezer]

@oscarlevin - I am battling LaTeX, MathJax 3, and MathJax 4 today. Slow going and subject to big changes at the least surprise. :-( But to your point, I have branch which incorporates #2180 - adding a new *.js and removing mathjaxknowl3.js. But I think it needs to sit and wait for mid-May. Not sure how disruptive that is for you right now?

[oscarlevin]

I don't think that change would be difficult to incorporate (this switch leaves mathjaxknowl3.js alone, I think).

While modularizing should not have any effect on users, it will make development a lot easier. So I would recommend we take care of this sooner rather than later. That said, I can redo this work again later if you think it should wait.

[rbeezer]

Just a heads-up, I would not, was not, suggesting a pause until mid-May. Unless my change was going to be a headache, otr something. Carry on.