Per-runtime detail (model keys → descriptor)

← Back to GenUI Reference

Each renderer lives in src/experience/genui/renderers/<name>.js, takes (model, ctx), and returns {kind, data}. ctx.urlPolicy ({allow:[schemes]}) is threaded from the ExperienceRenderer. Every renderer accepts multiple input key aliases (the model is untrusted LLM output) and clamps text via safeText(str, max) and URLs via safeUrl(url, policy).

1. flashcards (renderFlashcards)

Cards come from model.cards, model.items, or model.flashcards. Each card:

Descriptor: {kind:'flashcards', data:{title, cards:[{front, back, label}]}}.

2. followups (renderFollowups)

Descriptor: {kind:'followups', data:{questions:[string]}}. Server-side add_to_history:false — chips are suggestions, not replayed into history.

3. sources (renderSources)

Items come from model.sources, model.items, or model.citations. Each item:

Descriptor: {kind:'sources', data:{sources:[{title, url, snippet, score?}]}}. score's presence is not a claimed backend guarantee.

4. summary (renderSummary)

Descriptor: {kind:'summary', data:{title, summary, bullets:[string]}}. The summary stays untrusted (LLM output); by default mountWidget renders it as flat escaped text. Pass mountWidget(descriptor, el, {markdown:true}) to opt into a first-party, allow-listed markdown-to-DOM renderer instead — see GenUI · Authoring and Consuming Widgets § Markdown rendering (opt-in). The SDK never emits raw HTML either way.

5. video-gallery (renderVideoGallery) — Kaltura clips

Items come from model.videos, model.entries, or model.items. Each item:

Descriptor: {kind:'video-gallery', data:{title, videos:[{entryId, title, thumbnailUrl, url, embedUrl, duration, description, alt}]}}. This is the in-platform video widget: the host renders the Kaltura player against entryId.

6. show-link (renderShowLink) — links

Descriptor: {kind:'show-link', data:{url, label, description, safe}} where safe:!!url — an unsafe scheme yields url:'' and safe:false, so the host drops it.

7. external-video (renderExternalVideo) — non-Kaltura video embeds

Descriptor: {kind:'external-video', data:{url, embedUrl, title, provider, poster, description, safe}}, safe:!!url. The client check is defense-in-depth; the server-side media-URL validator is the primary guard.

8. user-properties-form (renderUserPropertiesForm) — structured data collection

Fields come from model.fields, model.properties, or model.items. A field without a key is dropped. Each field:

required/description let a host wire aria-required/aria-describedby/inputmode.

Descriptor: {kind:'user-properties-form', data:{title, fields:[{key, type, label, knownValue, required, description}]}}.

• Report back: the default path (when user_properties_forms is configured) has the host call session.submitStructuredDataForm(info) (session.js). This sanitizeJsons the object and emits the socket event setFormLeadInfo — a fire-and-forget emit with no durable server-side read-back. An app can take a different, durable path instead. Skip configuring user_properties_forms entirely, and reach this same user-properties-form widget as one enum value of its own show_widget client tool (with kaltura_genie_experiences OFF). Render it into your own dedicated host UI. On submit, bridge the collected values into request_vars, so the brain itself can call a server-side api tool that persists them wherever you point it — see Structured Data Forms.
• For the full picture, see Structured Data Forms and External API Integrations. They cover configuration, why the agent treats a configured stage as mandatory, where setFormLeadInfo actually persists server-side, and how to deliver the collected data somewhere durable.

9. content-gallery (renderContentGallery) — image/content cards

Items come from model.items, model.slides, or model.cards. Each item:

Descriptor: {kind:'content-gallery', data:{title, items:[{id, title, description, imageUrl, url, alt}]}}. This is the image-bearing widget (a deck/gallery of cards with thumbnails). Note the backend key is gallery_slides, and the video_gallery capability summary says it permits both video-gallery-tool and content-gallery-tool.

• Multi-item only. The renderer always wraps items in a CSS grid sized for several thumbnails (.kgenui__gallery, repeat(auto-fill, minmax(120px,1fr))). It does not branch on item count. So a single, image-less item stretches to the grid's full row width inside the widget's full-slot frame and reads as an oversized, awkward card. A :has(> .kgenui__gallery > li:only-child) CSS rule can give that case a flex/centered treatment instead. A show_widget tool description can also steer the brain toward summary for a single text-only point. Prefer content-gallery for 2+ image-bearing items, and summary for one.

10. graded-question (renderGradedQuestion) — a host-registered "10th runtime"

Unlike sections 1–9, this is not one of the nine backend unisphere-tool runtimes — there is no brain tool that emits graded-question-tool. It's a comprehension-check widget you register yourself, via the exact "10th runtime" extensibility seam described in GenUI · Authoring and Consuming Widgets § Registration, fallback, and provenance (.register() / cfg.renderers): a prompt with either multiple-choice options or a free-text answer, an optional answer key, and an optional explanation, graded client-side.

import { ExperienceRenderer, renderGradedQuestion } from '@kaltura/intelligent-agents/experience/genui';

const renderer = new ExperienceRenderer({
  mount: document.getElementById('widgets'),
  renderers: { 'graded-question': renderGradedQuestion },
  onAction: (action, payload) => {
    if (action === 'answer') console.log(payload.questionId, payload.correct, payload.value);
  },
});

// however your app decides to show a check-in question — e.g. after a video chapter —
// render + mount it, same as any custom widget:
renderer.render('graded-question', {
  questionId: 'q1',
  prompt: 'Which HTTP method is idempotent?',
  options: [{ id: 'a', text: 'POST' }, { id: 'b', text: 'PUT' }],
  correctOptionId: 'b',
  explanation: 'PUT replaces a resource; calling it twice has the same effect as once.',
});

Because it isn't backend-emitted, the LLM itself never authors this widget's model over the wire — your app supplies data directly (e.g. from your own quiz content). renderGradedQuestion still accepts a handful of common source-key aliases for convenience and forward compatibility. Every field is run through safeText twice: once in the renderer, and once again in mountWidget's DOM builder. So a hand-built descriptor that skips the renderer entirely is exactly as safe.

Descriptor: {kind:'graded-question', data:{questionId, variant, prompt, options:[{id,text}], correctOptionId, acceptedAnswers, explanation}}.

Grading is client-side, not tamper-proof. The answer key (correctOptionId/acceptedAnswers) travels inside the descriptor itself — the same trust model every other GenUI widget's model data already uses. Treat this as a comprehension-check for a cooperative learner (e.g. a knowledge-check after a video chapter), not a proctored or high-stakes assessment primitive.

correct is nullable by design. null means "no answer key was authored" (an open-ended, ungraded question) — distinct from false (a definitively wrong answer). A choice question with no correctOptionId, or a free-text question with no acceptedAnswers, always grades null.

Interaction event. Once the learner submits (one answer per mount — a second submit is a no-op), mountWidget's builder calls:

onAction('answer', {
  questionId,          // string — the descriptor's questionId
  variant,              // 'choice' | 'text'
  correct,               // boolean | null — null = no answer key authored
  value,                  // the chosen option's text (choice) or the sanitized free-text answer (text)
  explanation,             // string — '' if none was authored
  optionId,                 // string — present only for the 'choice' variant (the chosen option's id)
});

A listening integration branches conversation flow off correct/questionId — e.g. session.speak(...) a hint on correct:false, or advance a lesson plan on correct:true. See examples/genui-graded-question.mjs for a full runnable walkthrough of both variants, including the exact onAction payloads for a right answer, a wrong answer, and an ungraded (open-ended) one.

Related docs