On the AI context item edit form, the description under the **Global context** checkbox displays the tag as text: > Always include this context for every agent.\<br\>Saving the form with this > enabled will clear previous scope settings. `AiContextScopeGlobal::getFormDescription()` exists specifically so this checkbox can carry a line break. Its own docblock says so: ```php /** * Gets the checkbox description for the context item form. * * Uses a line break that is not safe for settings pages escaped with * Html::escape(), so keep plain text in getDescription() instead. */ protected function getFormDescription(): string { return (string) $this->t('Always include this context for every agent.<br>Saving the form with this enabled will clear previous scope settings.'); } ``` `src/Plugin/AiContextScope/AiContextScopeGlobal.php:77-79` But the `(string)` cast throws away the `TranslatableMarkup`, and `TranslatableMarkup` is the only reason the markup would survive — it implements `MarkupInterface`, which is what tells Form API not to escape a `#description`. Casting to a plain string means Form API escapes it, so the one tag the method was split out to allow is the one thing it cannot deliver. The split itself is right and worth keeping: `getDescription()` really is run through `Html::escape()` by `AiContextScopeSettingsFormBase.php:125` and `AiContextScopeOverviewForm.php:98`, so that one must stay plain text. Only the cast in `getFormDescription()` is wrong. The consumer is two lines below, at `AiContextScopeGlobal.php:100`: ```php '#description' => $this->getFormDescription(), ``` ## Steps to reproduce 1. Install `ai_context`. 2. Go to `/admin/config/ai/context/items/add` (or edit any existing item). 3. Open the **Context Scope** section. 4. The description under the **Global context** checkbox shows a literal `<br>` in the running text. Rendered markup, confirmed via `renderInIsolation()` on the element that `buildValueForm()` returns: ```html <small id="…--description" class="description form-text text-muted"> Always include this context for every agent.&lt;br&gt;Saving the form with this enabled will clear previous scope settings. </small> ``` ## Proposed resolution Return the `TranslatableMarkup` instead of casting it away, and declare that as the return type. `TranslatableMarkup` is already imported in this file for the `#[AiContextScope]` attribute, so no new `use` statement is needed. ```diff --- a/src/Plugin/AiContextScope/AiContextScopeGlobal.php +++ b/src/Plugin/AiContextScope/AiContextScopeGlobal.php @@ -71,9 +71,13 @@ * * Uses a line break that is not safe for settings pages escaped with * Html::escape(), so keep plain text in getDescription() instead. + * + * Returned as TranslatableMarkup rather than a plain string: #description + * escapes anything that is not a MarkupInterface, which would render the + * line break as literal "<br>" text. */ - protected function getFormDescription(): string { - return (string) $this->t('Always include this context for every agent.<br>Saving the form with this enabled will clear previous scope settings.'); + protected function getFormDescription(): TranslatableMarkup { + return $this->t('Always include this context for every agent.<br>Saving the form with this enabled will clear previous scope settings.'); } /** ``` After the patch the same render produces a real tag: ```html <small id="…--description" class="description form-text text-muted"> Always include this context for every agent.<br>Saving the form with this enabled will clear previous scope settings. </small> ``` `getFormDescription()` is `protected` and has no callers outside this class (`grep -rn "getFormDescription" src/ tests/` returns only the declaration and the one use at line 100), so widening the return type is not an API break for anything in the module. A subclass overriding it with a `string` return type would break, but no such subclass exists in the project. `getDescription()` is untouched and stays plain text, so the escaped settings and overview pages are unaffected. ### Alternative If a `MarkupInterface` return type is unwelcome here, dropping the `<br>` and splitting the sentence in two also fixes the visible symptom — but then `getFormDescription()` no longer has a reason to exist separately from `getDescription()` and could be removed entirely. ## Remaining tasks - Review. - Optional: a test asserting the built element's `#description` is a `MarkupInterface`. `AiContextScopeGlobalTest` already covers this plugin, and `AiContextScopeContextItemFormTest` already exercises the form. ## User interface changes The **Global context** checkbox description breaks across two lines as intended, instead of showing `<br>` as text. No wording change. ## API changes `AiContextScopeGlobal::getFormDescription()` return type widens from `string` to `TranslatableMarkup`. Protected, single internal caller, no subclasses in the project. ## Data model changes None.