Add HTML5 article rendering with embedded content viewers by rtibbles · Pull Request #14548 · learningequality/kolibri

rtibbles · 2026-04-07T16:37:15Z

Summary

Refactors the content viewer architecture to support rendering HTML content directly in the DOM (rather than exclusively in sandboxed iframes), and migrates the MediaPlayer from Vuex to composables.

Key changes:

Content viewer composable API refactored so viewer components receive data via composables instead of props
New DOM element-based rendering path alongside existing iframe rendering
MediaPlayer Vuex module replaced with useMediaPlayer composable
VideoPlayer extracted from MediaPlayerIndex; new AudioPlayer with custom controls and inline transcript
Shared ViewerToolbar component replaces per-viewer toolbar implementations (HTML5, PDF, EPUB)
SafeHtml5Renderer updated to render HTML content with embedded media support and progress tracking
Design refresh across the media players (audio + video) and embedded viewers (PDF, EPUB)

References

Reviewer guidance

To test: load any HTML5 content, PDF, EPUB, video, or audio content and verify it renders and plays correctly. For HTML5 content with embedded media, use the Kolibri QA Channel under HTML5 > HTML5 Article.

HTML5 Articles with embedded content use a blended progress model: 50% from scroll progress, 50% from embedded content completion. The 50/50 split is arbitrary and may need tuning — worth scrutinizing whether this feels right in practice.

Implementation involved judgment calls that may deviate from the design specs — worth comparing against the original designs during review.

Risky areas:

packages/kolibri/internal/pluginMediator.js — viewer registration now supports DOM element viewers alongside preset-based viewers; this is the core extension point
packages/kolibri/components/internal/ContentViewer/index.js — major rewrite from a simple wrapper to a render-function component with provide/inject context, viewer ID tracking, and DOM element file extraction
kolibri/core/content/hooks.py — new css_selectors and allow_object_tag on ContentRendererHook; the all_css_selectors classmethod uses module-level caching

Standalone players (desktop)

State	Screenshot
Video player
Audio player

Embedded in HTML5 article (desktop, 1280px)

State	Screenshot
Article text rendering
Embedded audio players
Embedded video player
Embedded PDF viewer
Embedded EPUB viewer

Embedded video player

Screencast.From.2026-04-07.19-26-04.mp4

Sticky audio player

Screencast.From.2026-04-07.19-24-22.mp4

Embedded in HTML5 article (mobile, 412px)

State	Screenshot
Article text
Embedded audio
Embedded video
Embedded PDF
Embedded EPUB

AI usage

Implementation was done collaboratively with Claude Code (Opus). I directed the architecture and made design decisions; Claude helped with implementation, test writing, and iterating on the embedded content rendering approach. All code was reviewed and verified against a running dev server.

github-actions · 2026-04-07T17:24:31Z

Build Artifacts

Asset type	Download link
PEX file	kolibri-0.19.5.dev0_git.20260603025252.pex
Windows Installer (EXE)	kolibri-0.19.5.dev0+git.20260603025252-windows-setup-unsigned.exe
Debian Package	kolibri_0.19.5.dev0+git.20260603025252-0ubuntu1_all.deb
Mac Installer (DMG)	kolibri-0.19.5.dev0+git.20260603025252.dmg
Android Package (APK)	kolibri-0.19.5.dev0+git.20260603025252-0.1.10-debug.apk
Raspberry Pi Image	kolibri-pi-image-0.19.5.dev0+git.20260603025252.zip
TAR file	kolibri-0.19.5.dev0+git.20260603025252.tar.gz
WHL file	kolibri-0.19.5.dev0+git.20260603025252-py2.py3-none-any.whl

Smoke test screenshot

Download screenshot

github-actions · 2026-04-14T00:02:39Z

npm Package Versions

Warning

The following packages have changed files but no version bump:

Package	Version	Changed files
kolibri	0.18.0	15

If these changes affect published code, consider bumping the version.

rtibbles

Some things I need to update before undrafting.

rtibbles · 2026-04-08T14:13:36Z

-  import useContentViewer, { contentViewerProps } from 'kolibri/composables/useContentViewer';
+  import useContentViewer from 'kolibri/composables/useContentViewer';

 In order to log data about users viewing content, the component should emit ``startTracking``, ``updateProgress``, and ``stopTracking`` events, using the Vue ``$emit`` method. ``startTracking`` and ``stopTracking`` are emitted without any arguments, whereas ``updateProgress`` should be emitted with a single value between 0 and 1 representing the current proportion of progress on the content.


Question for reviewers - should I move the entire public API surface into the composable? Just make methods for startTracking, stopTracking and updateProgress and skip the emit altogether?

rtibbles · 2026-04-08T14:15:03Z

+    allow_object_tag = False
+
+    @classmethod
+    def all_css_selectors(cls):


Using css_selectors allows for specific content viewers to only render certain DOM nodes if they have particular attributes present, for example.

rtibbles · 2026-04-08T14:15:49Z

 from le_utils.constants.file_formats import BLOOMPUB
 from le_utils.constants.file_formats import H5P
 from le_utils.constants.file_formats import HTML5
+from le_utils.constants.file_formats import HTML5_ARTICLE


Need to add this to allow larger media files to be loaded via the zip content backend from kpub files.

rtibbles · 2026-04-08T14:16:18Z

    :style="{ width: iframeWidth }"
    @changeFullscreen="isInFullscreen = $event"
  >
-    <div


We had copied this across HTML5, EPUB, PDF, and Bloompub - rule of three more than applied!

rtibbles · 2026-04-08T14:18:57Z

 class DocumentEPUBRenderAsset(content_hooks.ContentRendererHook):
    bundle_id = "main"
    presets = (format_presets.EPUB,)
+    allow_object_tag = True


We use this as a shorthand to let the <object> tag be used for these kinds of files (but we use the preset logic to work out which files in the object tag they should render and generate CSS selectors accordingly).

rtibbles

Some open questions, some things I can revisit now before review.

rtibbles · 2026-06-02T17:36:34Z

      this.visitedPages = this.savedVisitedPages || {};
    },
    beforeMount() {
-      global.ePub = Epub;


This wasn't needed - I'm not sure why it was ever here.

rtibbles · 2026-06-02T17:36:45Z

      window.removeEventListener('mousedown', this.handleMouseDown, { passive: true });
      clearInterval(this.updateContentStateInterval);
    },
-    destroyed() {


Cleanup was unnecessary too.

rtibbles · 2026-06-02T17:37:59Z

      };
    },
    props: {
-      ...contentViewerProps,


contentViewerProps is no longer a thing, so we just explicitly define this here.

rtibbles · 2026-06-02T17:38:38Z

      };
    },
    props: {
-      ...contentViewerProps,


This component was duplicated for the courses work - so do the same updates here too.

rtibbles · 2026-06-02T17:40:55Z

@@ -0,0 +1,185 @@
+import { ref, computed } from 'vue';


Taking the opportunity of the composable refactor to add test coverage here.

rtibbles · 2026-06-02T17:59:51Z

    setup(props, context) {
      const { windowBreakpoint } = useKResponsiveWindow();
-      const { defaultFile, contentDirection } = useContentViewer(props, context);
+      const {


Note that this will probably need rebasing if the Perseus upgrade PR lands first.

rtibbles · 2026-06-02T18:00:55Z

@@ -0,0 +1,213 @@
+import { render, screen, waitFor } from '@testing-library/vue';


There's a decision encoded in this spec and the code to have 50% of progress be from scrolling through the article, 50% from any nested viewers. I don't know what the right call is here.

rtibbles · 2026-06-02T18:02:29Z

    }
    return acc;
  }, {});
+  const ALLOWED_URI_REGEXP = buildAllowedUriRegexp(allowedOrigins);


This is required to allow the "large file" fallback used in kolibri-zip that directly defers to the zipcontent endpoint.

rtibbles · 2026-06-02T18:07:04Z

        );
      }
-
-      const safeAttrs = {};


Previously arbitrary props could be passed through to viewer plugin components, creating implicit APIs that bypassed the content viewer. This tightens this up.

…nents to use the viewer props, and instead direct all data via the composable api.

…ction Replace the Vuex store module with composables for instance-specific state management. Extract VideoPlayer and implement AudioPlayer with custom transport controls, sticky player, and inline transcript. Add useMediaProgress composable for shared progress tracking logic.

ContentViewer now generates unique viewer IDs and appends them to all interaction events, allowing parent components to track which embedded viewer emitted each event. SafeHtml5RendererIndex uses this to aggregate progress from multiple embedded viewers (e.g., videos in HTML5 content), combining scroll-based progress with embedded viewer progress using dynamic weighting.

Replace v-bind="$attrs" with explicit class="safe-html" and remove inheritAttrs: false, reducing the component API surface area. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

rtibbles force-pushed the html_viewer_injection branch 8 times, most recently from 4735d6d to f00e02e Compare April 14, 2026 00:01

rtibbles force-pushed the html_viewer_injection branch 3 times, most recently from d597e47 to 5da5ce9 Compare April 21, 2026 15:09

rtibbles assigned bjester and akolson Apr 21, 2026

rtibbles commented Apr 21, 2026

View reviewed changes

rtibbles force-pushed the html_viewer_injection branch from 5da5ce9 to fdb1287 Compare April 22, 2026 03:00

rtibbles force-pushed the html_viewer_injection branch from fdb1287 to e307c3c Compare May 1, 2026 02:24

rtibbles force-pushed the html_viewer_injection branch from e307c3c to 4eb097a Compare May 14, 2026 03:41

rtibbles force-pushed the html_viewer_injection branch from 4eb097a to e714f78 Compare June 1, 2026 23:10

rtibbles commented Jun 2, 2026

View reviewed changes

rtibbles added 3 commits June 2, 2026 18:14

Refactor content viewer to no longer require implemented viewer compo…

8c8df77

…nents to use the viewer props, and instead direct all data via the composable api.

rtibbles and others added 2 commits June 2, 2026 19:39

Add shared ViewerToolbar and integrate across all viewers

1924145

Simplify SafeHtmlImage and SafeHtmlTable attribute passing

7b138aa

Replace v-bind="$attrs" with explicit class="safe-html" and remove inheritAttrs: false, reducing the component API surface area. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

rtibbles force-pushed the html_viewer_injection branch from e714f78 to 7b138aa Compare June 3, 2026 02:52

		@@ -0,0 +1,213 @@
		import { render, screen, waitFor } from '@testing-library/vue';

Uh oh!

Conversation

rtibbles commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

References

Reviewer guidance

Standalone players (desktop)

Embedded in HTML5 article (desktop, 1280px)

Embedded in HTML5 article (mobile, 412px)

AI usage

Uh oh!

github-actions Bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

npm Package Versions

Uh oh!

rtibbles left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rtibbles left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rtibbles commented Apr 7, 2026 •

edited

Loading

github-actions Bot commented Apr 7, 2026 •

edited

Loading

github-actions Bot commented Apr 14, 2026 •

edited

Loading