feat: #3631526 Use AI Prompts for the SVG, document, image and Ask AI prompts

Rajab Natshahrequested to merge
issue/ai_media-3631526:3631526-ai-prompts into 1.0.x

Issue: #3631526 "Initialize the AI Media module"

Chunk 5 of the UX and integration plan (20 October 2026): AI Prompts (plan section 2.5).

Depends on !11 (closed) (3631526-single-preview), which depends on !10 (closed), !9 (closed), !8 (closed) and !6 (merged). Until those merge, this diff includes them; the change of this MR is its last commit.

What changed

  • The prompts AI Media sends are AI Prompts of the AI module (ai.ai_prompt_type, ai.ai_prompt), owned and edited by the site at Configuration > AI > Prompts:

    Prompt type Used by Variables Default prompt
    ai_media_svg SVG system prompt {width}, {height} (required) ai_media_svg__default
    ai_media_document Document system prompt {words} (required), {language} ai_media_document__default
    ai_media_text_to_image Image and video frame {description} (required), {context} ai_media_text_to_image__default: {description} then {context}, nothing added
    ai_media_metadata Ask AI: name, alt, title {request} (required), {result_excerpt}, {max_length} ai_media_metadata__name, __alt, __title

  • The default prompts hold the exact text sent before, so output is unchanged.

  • Settings store prompt IDs: prompts.svg, prompts.document, prompts.text_to_image, metadata.<target>.prompt, typed ai_media.prompt with ConfigExists: prefix: 'ai.ai_prompt.'.

  • The settings page uses the AI module's ai_prompt element: an "AI Prompts" section on the Generators tab, and one picker per value on the Name, title and alternative text tab. The picker's radios have no label of their own, so AI Media adds a visually hidden "Use " to each (axe flagged them otherwise). "Manage all AI Prompts" links to the prompt list for users with "Manage AI prompts".

  • The SVG and document sanitizers run whatever a prompt says; the settings page and the prompt type labels say so.

  • A chosen prompt that has been deleted falls back to the shipped one.

  • A recipe installs a module's config entities only when it imports them. Without config: import: ai_media: '*' the prompt types and prompts are missing; AI Media then uses the shipped prompt text from config/install and the settings page says the prompts are not imported, instead of failing on the picker. The fixtures recipe imports them; the README and docs say a recipe should. (Found by the first pipeline of this MR, fixed in the second commit.)

  • No update hook and no post update, by the maintainer's decision while the module is initialized: only config/install and the schema change. A site that installed an earlier commit keeps its old prompt strings in metadata.<target>.prompt; they are not prompt IDs, so the shipped prompts are used until the form is saved.

  • Note for review: the AI module's picker lets anyone who can open the AI Media settings ("Administer AI Media", restricted) add a prompt inline, as on the AI Translate settings. AI Media adds no check of its own.

How it was tested

  • Kernel PromptsTest: the four types and six prompts install and are referenced from the settings; the defaults render exactly the old SVG, document, image and Ask AI texts; a site prompt chosen in the settings is what reaches the provider, with {description} and {max_length} filled; a missing prompt falls back. All 20 Kernel tests pass.
  • Plain Drupal 11.4 (aimplan1): the settings page shows the pickers with the defaults selected, saving keeps the IDs, "Ask AI" with the shipped prompt works with Echo.
  • axe-core 4.10.2: 0 violations on the Generators tab with "AI Prompts" open and on the naming tab with a picker shown, in Claro, Gin and Default Admin at 1440 and 1920 (a first Default Admin run flagged hover colours left by the test pointer; with the pointer moved away it is clean).
  • A fresh standard site with the fixtures recipe (as CI builds it): the prompts install and the settings page renders. With the prompt config removed: the shipped texts are sent and the page shows the note. Kernel PromptsTest covers the fallback.
  • Varbase E2E, Firefox: 06-01-01-settings (9 scenarios, including the new prompts one) passes; the defaults step resets the prompts too.
  • phpcs (Drupal, DrupalPractice), phpstan level 1, cspell, eslint, stylelint: clean.

Not tested

  • Real providers with an edited prompt (Echo only; no paid calls in this MR).
  • Creating a prompt inline from the picker on the AI Media page (the AI module's own feature).
  • Mobile widths (out of scope).

AI-Generated: Yes. Written with Claude Code (Claude Opus 5.5) under the Drupal AI policy; tested by the author before submission.

Checkpoints:

  • File an issue
  • Addition/Change/Update/Fix
  • Testing to ensure no regression
  • Automated unit testing coverage
  • Automated functional testing coverage
  • UX/UI designer responsibilities
  • Readability
  • Accessibility
  • Performance
  • Security
  • Developer Documentation
  • User Guide Documentation
  • Reviewed by human
  • Code review by maintainers
  • Full testing and approval
  • Credit contributors
  • Review with the product owner
  • Release notes snippet
  • Release
Edited by Rajab Natshah

Merge request reports