htmx

Relied on the existing vendored partial-update library as an integration point. The new script cancels speech on its pre-swap event and on page hide so audio does not continue across content swaps. No new dependency was added.

What worked

Documented pre-swap event made cleanup straightforward without backend changes.

Followed the existing hypermedia pattern where a form post returns a status fragment that polls until the background draft is ready, keeping model latency out of the request path. Reused the established partial and polling conventions.

Relied on existing hypermedia partial pattern for answer and conversation fragments so follow-up questions update in place while reusing server-side scoping and grounding checks.

What worked

Partial rendering fit the existing list and row patterns without extra client machinery.

Relied on the existing server-rendered fragment pattern and its request lifecycle to cancel speech on navigation and keep controls consistent.

What worked

The small fragment convention and request events made it straightforward to wire cancellation without a build pipeline.

Built search preview and keep interactions as server-rendered fragments following the existing hypermedia pattern, so teachers see source and passage before attaching anything.

What worked

Fragment-based preview and idempotent keep action fit the existing editor flow without client-side state.

Relied on for the search-preview interaction model where a fragment renders results without persisting anything until the teacher explicitly attaches an item. No browser-level verification was recorded.

What worked

Partial-render pattern fit the preview-then-attach flow and kept the interaction synchronous at low expected traffic.

Quiz actions were added on the course page with the app's existing partial-update approach and exercised through the framework test client. A browser was unavailable, so live swaps and rendered error states were not observed. The test runs showed no library-specific failures.

What worked

Server-side handling of the quiz actions could be exercised through the test client together with the other flow tests.

Used htmx attributes to load and swap the materials panel fragments. For the upload-confirm step, a 400 response from an htmx request would have failed silently by default, so that step uses fetch plus htmx.process instead. Never exercised in a browser.

The grade cell was updated to show a saving state and poll until the graded row exists, using the project's existing htmx polling approach in the list and row templates. View tests covered the save path. The page was not opened in a browser, so the poll loop and partial updates were not observed in a real session.

What worked

Markup-level polling matched an async save without a separate frontend build. The list template and the row partial were both updated for the saving state.

Used a partial template for async quiz status polling after the teacher request, keeping slow gateway work out of the initial response. The pattern was minimal and fit the existing frontend approach; no browser check was shown.

What worked

Simple polling partial kept the UI responsive during background generation.

Used for teacher-facing generation flow with immediate pending partial, status polling, and an explicit publish step. Server tests covered the partial and fallback responses without browser verification.

What worked

Partial-versus-full-page branching kept the teacher flow non-blocking while preserving a plain fallback.

The quiz form and job status were added as server partials for the existing HTMX submit-and-poll pattern. The test client requested those fragments and the related tests passed. The HTMX script was never loaded in a browser, so swapping and poll timing were not observed.

What worked

The existing partial pattern made the form and status fragments straightforward to add and to request from the test client.

What got in the way

No browser session was available, so client-side swapping, polling, and script behavior were not exercised.

Used htmx attributes for search, preview, keep and remove actions. I used an out-of-band swap so re-keeping a passage replaces the row instead of duplicating it. I didn't test it in a browser.

What worked

Out-of-band swaps cleanly fixed the duplicate-row case without any custom JavaScript.

What got in the way

By default it doesn't swap in 4xx responses, so an expired preview or a disabled feature just does nothing when clicked. I left that as a known gap.

Search previews and saved citations were returned as fragments using the same partial-request style already in the app. The test client checked the HTML before any row was stored and after a save. The library itself was not run in a browser.

What worked

Server-rendered fragments were enough for the test client to confirm that a source and passage appear before a save and that a kept citation renders afterward.

What got in the way

No browser was available, so swapping content into the page, request headers, and other client runtime behavior were not exercised.

htmx attributes drive the quiz panel, form submit, and status polling on the existing course list. The server responses behind those attributes were checked with the framework test client. No browser was available, so the htmx runtime itself never ran.

What worked

Small attributes on the existing page were enough to load a partial, post the form, and poll until the quiz was ready, and the server contract tested cleanly.

What got in the way

Client-side swapping, polling, and error states were not executed, so the library's browser behavior is unverified.

I marked editor actions so search results, errors, and the saved-source list swap in place. Server tests checked the returned markup. No browser was available, so I never saw the client library perform a swap.

What worked

A few attributes on the existing form were enough to target partial templates for the preview, the error state, and the saved list.

What got in the way

Interactive behavior was not observed, because nothing clicked the search or save actions in a browser.

I marked the quiz panel to swap fragments and to poll only while a refresh trigger is present. Tests checked the rendered markup, including that a finished panel omits the trigger. The browser script was never executed.

What worked

The attribute conventions made polling, swapping, and stopping the poll expressible in the template, and the test client could assert that a finished panel no longer requested a refresh.

What got in the way

There was no browser session, so swaps and polling were not executed and the client runtime was not observed.

The course pages already load htmx as a deferred script. I placed the read-aloud script with it and checked that a row inserted after the initial render, in the same way those pages update, received working Play and Stop controls. I did not install or reconfigure the library.

What worked

The existing partial-update pattern fit controls that bind on rows already on the page and on a row added later. The deferred script still ran against a parsed document and could attach those controls.

The roster fragment is already swapped in with htmx, so the new file control and script use delegated events after the swap. Tests checked the rendered markup through the app test client. No browser was available, so the swap and upload were not clicked through.

What worked

Delegated events fit the existing fragment swap, and the test client could still assert that the upload control was present in the markup.

Roster fragments that replace part of the staff page use the same translated templates as the full screens. The fragment markup was updated, and the test client checked the returned HTML, including validation errors. No browser was available, so the client-side swap was not executed.

What worked

Fragments and full pages share one template catalog, so translated labels and form errors stay on the same strings.

The course list loads the narration player through an existing partial-request endpoint. Server-side tests checked the returned player markup. No browser was available, so the client-side swap was not exercised.

What worked

The partial endpoint fit the course list, and the test client could assert the player markup without a separate front-end harness.

What got in the way

The interactive request and audio element were not run in a browser, so swap behavior and playback were not observed.

Search results and attach actions were written as fragment responses in the same partial-update style already used in the app. The test client posted those forms and checked the returned HTML. No browser executed the library, so real swaps were not observed.

What worked

Fragment endpoints kept preview and attach off the full-page editor route, and the server-rendered markup matched the stored passage, source, and date.

What got in the way

Client-side swapping was not run, so I cannot say whether the attributes behave in a browser.

I built find and keep as partial updates using the library's request header and form include, so a teacher can review a source and passage before anything is stored. Server tests checked those responses, including the token on the request. I could not run the library in a graphical browser, so the client-side swap was not observed.

What worked

The header and include attributes matched the app's existing partial-page pattern. Tests that sent the partial-request header received the preview and the kept-row fragment, and a repeated keep updated the same row instead of inserting another.

What got in the way

Full-page cases still rendered the shared layout and were a poor check of the partial path. No graphical browser was available, so the library's own swap and error handling in the page were never executed.