module.php

<?php

/**
 * Potts Relationship Context for webtrees.
 *
 * Shows how the current individual relates to a selected reference person.
 *
 * @license GPL-3.0-or-later
 */

declare(strict_types=1);

use Fisharebest\Webtrees\Auth;
use Fisharebest\Webtrees\Contracts\UserInterface;
use Fisharebest\Webtrees\Fact;
use Fisharebest\Webtrees\FlashMessages;
use Fisharebest\Webtrees\I18N;
use Fisharebest\Webtrees\Individual;
use Fisharebest\Webtrees\GedcomRecord;
use Fisharebest\Webtrees\Module\AbstractModule;
use Fisharebest\Webtrees\Module\ModuleConfigInterface;
use Fisharebest\Webtrees\Module\ModuleConfigTrait;
use Fisharebest\Webtrees\Module\ModuleCustomInterface;
use Fisharebest\Webtrees\Module\ModuleCustomTrait;
use Fisharebest\Webtrees\Module\ModuleGlobalInterface;
use Fisharebest\Webtrees\Module\ModuleGlobalTrait;
use Fisharebest\Webtrees\Module\RelationshipsChartModule;
use Fisharebest\Webtrees\Registry;
use Fisharebest\Webtrees\Services\IndividualFactsService;
use Fisharebest\Webtrees\Services\RelationshipService;
use Fisharebest\Webtrees\Services\TreeService;
use Fisharebest\Webtrees\Tree;
use Fisharebest\Webtrees\Validator;
use Illuminate\Support\Collection;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

return new class extends AbstractModule implements ModuleCustomInterface, ModuleConfigInterface, ModuleGlobalInterface {
    use ModuleCustomTrait;
    use ModuleConfigTrait;
    use ModuleGlobalTrait;

    private const VERSION = '1.0.0-beta.1';

    private const PREF_SHOW_FACT_LABELS = 'show_fact_relationships';
    private const PREF_SHOW_FACTS_SUMMARY = 'show_facts_summary';
    private const PREF_SHOW_RELATIONSHIP_PATH = 'show_relationship_path';
    private const PREF_USE_ACCOUNT_INDIVIDUAL = 'use_account_individual';
    private const PREF_USE_FAVOURITE_INDIVIDUAL = 'use_favourite_individual';
    private const PREF_PUBLIC_REFERENCE_XREF = 'public_reference_xref';
    private const PREF_FALLBACK_TREE_ROOT = 'fallback_tree_root';
    private const PREF_MAX_GENERATIONS = 'max_generations';
    private const PREF_LABEL_STYLE = 'label_style';
    private const PREF_CARD_STYLE = 'card_style';
    private const PREF_SUMMARY_POSITION = 'summary_position';

    private const SUMMARY_POSITION_FACTS_PANEL = 'facts-panel';
    private const SUMMARY_POSITION_ABOVE_TABS = 'above-tabs';
    private const SUMMARY_POSITION_NEAR_TITLE = 'near-title';
    private const SUMMARY_POSITION_OFF = 'off';

    private const LABEL_STYLE_COMPACT = 'compact';
    private const LABEL_STYLE_SENTENCE = 'sentence';

    private const CARD_STYLE_THEME = 'theme';
    private const CARD_STYLE_POTTS = 'potts';

    /** @var array<string,string> */
    private const BOOLEAN_PREFERENCES = [
        self::PREF_SHOW_FACT_LABELS => '1',
        self::PREF_SHOW_FACTS_SUMMARY => '1',
        self::PREF_SHOW_RELATIONSHIP_PATH => '1',
        self::PREF_USE_ACCOUNT_INDIVIDUAL => '1',
        self::PREF_USE_FAVOURITE_INDIVIDUAL => '1',
        self::PREF_FALLBACK_TREE_ROOT => '1',
    ];

    public function title(): string
    {
        return I18N::translate('Potts Relationship Context');
    }

    public function description(): string
    {
        return I18N::translate('Shows relationship context between the current individual, the logged-in user and close-relative events.');
    }

    public function customModuleAuthorName(): string
    {
        return 'Jason Potts';
    }

    public function customModuleVersion(): string
    {
        return self::VERSION;
    }

    public function headContent(): string
    {
        $html = '<style>' . $this->styleCss() . '</style>';

        if (!$this->isIndividualPageRequest() || $this->isRelationshipsChartRequest()) {
            return $html;
        }

        $individual = $this->currentIndividualFromRequest();

        if (!$individual instanceof Individual) {
            $html .= $this->statusScript(array_merge([
                'enabled' => true,
                'version' => self::VERSION,
                'serverError' => 'individual-not-found',
            ], $this->requestDiagnostics()));

            return $html;
        }

        $reference = $this->referenceIndividual($individual->tree());

        if (!$reference['individual'] instanceof Individual) {
            $html .= $this->statusScript([
                'enabled' => true,
                'version' => self::VERSION,
                'serverError' => 'reference-not-found',
                'currentXref' => $individual->xref(),
                'currentName' => strip_tags($individual->fullName()),
            ]);

            return $html;
        }

        $reference_individual = $reference['individual'];
        $relationship = $this->relationshipName($reference_individual, $individual);
        $relationship_found = $relationship !== '';

        if (!$relationship_found) {
            $relationship = I18N::translate('relationship not found');
        }

        $config = [
            'enabled' => true,
            'version' => self::VERSION,
            'currentXref' => $individual->xref(),
            'currentName' => strip_tags($individual->fullName()),
            'referenceXref' => $reference_individual->xref(),
            'referenceName' => strip_tags($reference_individual->fullName()),
            'referenceMode' => $reference['mode'],
            'referenceIsLoggedInUser' => $reference['mode'] === 'account',
            'relationship' => $relationship,
            'relationshipFound' => $relationship_found,
            'relationshipPathUrl' => $relationship_found ? $this->relationshipPathUrl($reference_individual, $individual) : '',
            'showRelationshipPath' => $this->boolPreference(self::PREF_SHOW_RELATIONSHIP_PATH),
            'showFactLabels' => $this->boolPreference(self::PREF_SHOW_FACT_LABELS),
            'showFactsSummary' => $this->boolPreference(self::PREF_SHOW_FACTS_SUMMARY),
            'summaryPosition' => $this->summaryPosition(),
            'cardStyle' => $this->cardStyle(),
            'labelStyle' => $this->labelStyle(),
            'factRelationships' => $this->factRelationshipRows($individual),
        ];

        return $html . $this->injectionScript($config);
    }

    public function bodyContent(): string
    {
        return '';
    }

    /**
     * @param array<string,mixed> $config
     */
    private function statusScript(array $config): string
    {
        $json = json_encode($config, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_THROW_ON_ERROR);

        return '<script>window.pottsRelationshipContextStatus=' . $json . ';</script>';
    }

    /**
     * @param array<string,mixed> $config
     */
    private function injectionScript(array $config): string
    {
        $json = json_encode($config, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_THROW_ON_ERROR);
        $script = <<<'JS'
(function(){
    const config = CONFIG_PLACEHOLDER;
    const status = Object.assign({insertedFactLabels:0}, config);
    window.pottsRelationshipContextStatus = status;

    function normalise(text) {
        return String(text || '').replace(/\s+/g, ' ').trim().toLowerCase();
    }

    function possessive(name) {
        name = String(name || '').trim();
        if (!name) {
            return '';
        }
        return /s$/i.test(name) ? name + '’' : name + '’s';
    }

    function displayRelationship(relationship, capitalise) {
        let text = String(relationship || '').replace(/[-_]+/g, ' ').replace(/\s+/g, ' ').trim();
        if (!text) {
            return '';
        }
        text = text.toLowerCase();
        if (capitalise) {
            return text.charAt(0).toUpperCase() + text.slice(1);
        }
        return text;
    }

    function relationshipSummarySentence() {
        const currentName = String(config.currentName || 'This person').trim();
        const relationship = displayRelationship(config.relationship, false);

        if (!config.relationshipFound || !relationship || relationship === 'relationship not found') {
            if (config.referenceIsLoggedInUser) {
                return 'No relationship could be found between you and ' + currentName + '.';
            }

            if (config.referenceName) {
                return 'No relationship could be found between ' + currentName + ' and ' + config.referenceName + '.';
            }

            return 'No relationship could be found for ' + currentName + '.';
        }

        if (relationship === 'self' || config.currentXref === config.referenceXref) {
            return config.referenceIsLoggedInUser ? 'This is you.' : currentName + ' is the selected reference person.';
        }

        if (config.referenceIsLoggedInUser) {
            return currentName + ' is your ' + relationship + '.';
        }

        if (config.referenceName) {
            return currentName + ' is ' + possessive(config.referenceName) + ' ' + relationship + '.';
        }

        return currentName + ' is the reference person’s ' + relationship + '.';
    }

    function factsSummaryStorageKey() {
        return 'pottsRelationshipContext.showFactsSummary';
    }

    function factsSummaryVisible() {
        if (!config.showFactsSummary) {
            return false;
        }

        try {
            const stored = window.localStorage ? window.localStorage.getItem(factsSummaryStorageKey()) : null;
            if (stored === '0') {
                return false;
            }
            if (stored === '1') {
                return true;
            }
        } catch (e) {
            // Ignore local-storage failures.
        }

        return true;
    }

    function setFactsSummaryVisible(visible) {
        document.querySelectorAll('[data-potts-relationship-context="facts-summary"]').forEach(function(element){
            element.hidden = !visible;
        });
        document.querySelectorAll('[data-potts-relationship-context="facts-summary-toggle"]').forEach(function(input){
            input.checked = visible;
        });

        try {
            if (window.localStorage) {
                window.localStorage.setItem(factsSummaryStorageKey(), visible ? '1' : '0');
            }
        } catch (e) {
            // Ignore local-storage failures.
        }
    }

    function pottsModernThemeActive() {
        if (document.querySelector('.potts-individual-tab-panel,[class*="potts-individual"],[class*="potts-modern"]')) {
            return true;
        }

        const identity = [
            document.documentElement.className || '',
            document.body ? document.body.className || '' : '',
            document.body ? document.body.id || '' : ''
        ].concat(Array.from(document.querySelectorAll('link[rel="stylesheet"]')).map(function(link){
            return link.href || '';
        })).join(' ');

        return /potts[\s_-]*modern/i.test(identity);
    }

    function makeFactsSummary() {
        const summary = document.createElement('section');
        summary.className = 'potts-relationship-context-facts-summary';
        const usePottsStyle = config.cardStyle === 'potts'
            || (config.cardStyle === 'theme' && pottsModernThemeActive());
        summary.classList.add(usePottsStyle
            ? 'potts-relationship-context-style-potts'
            : 'potts-relationship-context-style-theme');
        summary.setAttribute('data-potts-relationship-context', 'facts-summary');
        summary.setAttribute('aria-label', config.relationshipFound ? 'Relationship context' : 'No relationship found');

        if (!config.relationshipFound) {
            summary.classList.add('potts-relationship-context-no-relationship');
        }

        const icon = document.createElement('div');
        icon.className = 'potts-relationship-context-summary-icon';
        icon.setAttribute('aria-hidden', 'true');
        icon.textContent = config.relationshipFound ? '↔' : '?';

        const body = document.createElement('div');
        body.className = 'potts-relationship-context-summary-body';

        const label = document.createElement('div');
        label.className = 'potts-relationship-context-summary-label';
        label.textContent = config.referenceIsLoggedInUser
            ? 'Relationship to you'
            : 'Relationship to ' + (config.referenceName || 'the reference person');

        const text = document.createElement('div');
        text.className = 'potts-relationship-context-summary-text';
        text.textContent = relationshipSummarySentence();

        body.appendChild(label);
        body.appendChild(text);

        if (config.relationshipFound && config.showRelationshipPath && config.relationshipPathUrl && config.referenceXref !== config.currentXref) {
            const pathLink = document.createElement('a');
            pathLink.className = 'potts-relationship-context-path-link';
            pathLink.href = config.relationshipPathUrl;
            pathLink.textContent = 'View relationship path';
            pathLink.setAttribute('aria-label', 'View the relationship path between ' + config.referenceName + ' and ' + config.currentName);
            body.appendChild(pathLink);
        }

        summary.appendChild(icon);
        summary.appendChild(body);
        summary.hidden = !factsSummaryVisible();
        return summary;
    }

    function elementRect(element) {
        try {
            return element.getBoundingClientRect();
        } catch (e) {
            return {width:0,height:0,top:0,left:0};
        }
    }

    function phraseCount(text, phrases) {
        return phrases.filter(function(phrase){ return text.indexOf(phrase) !== -1; }).length;
    }

    function factsControlScore(element, phrases) {
        if (!element || ignoredElement(element)) {
            return -1;
        }

        const text = normalise(element.textContent || '');
        if (!text || text.length > 1200) {
            return -1;
        }

        const matchedCount = phraseCount(text, phrases);
        if (matchedCount === 0) {
            return -1;
        }

        const rect = elementRect(element);
        let score = matchedCount * 1000;
        score += Math.min(rect.width || 0, 1200);

        // The actual webtrees control strip is usually a wide, shallow beige bar.
        // Prefer that over the individual checkbox label or a narrow left column.
        if ((rect.width || 0) > 450) {
            score += 900;
        }
        if ((rect.height || 0) > 0 && (rect.height || 0) < 120) {
            score += 250;
        }
        if (element.matches && element.matches('label,span,input')) {
            score -= 900;
        }
        if (element.querySelectorAll && element.querySelectorAll('input[type="checkbox"]').length >= 2) {
            score += 400;
        }

        return score;
    }

    function findFactsControlBar() {
        const phrases = ['events of close relatives', 'historic events', 'associated events'];
        const roots = candidateRoots();
        let best = null;
        let bestScore = -1;

        for (const root of roots) {
            const elements = [root].concat(Array.from(root.querySelectorAll('div,section,form,p,label,span')));

            for (const element of elements) {
                if (ignoredElement(element)) {
                    continue;
                }

                const text = normalise(element.textContent || '');
                if (!phrases.some(function(phrase){ return text.indexOf(phrase) !== -1; })) {
                    continue;
                }

                let current = element;
                let depth = 0;

                while (current && current !== document.body && depth < 8) {
                    if (ignoredElement(current)) {
                        break;
                    }

                    const score = factsControlScore(current, phrases) - (depth * 5);
                    if (score > bestScore) {
                        best = current;
                        bestScore = score;
                    }

                    const parent = current.parentElement;
                    if (!parent || ignoredElement(parent)) {
                        break;
                    }

                    const parentText = normalise(parent.textContent || '');
                    if (parentText.length > 1800) {
                        break;
                    }

                    current = parent;
                    depth++;
                }
            }
        }

        if (best) {
            const bestRect = elementRect(best);
            if ((bestRect.width || 0) < 450) {
                let current = best.parentElement;
                let depth = 0;
                while (current && current !== document.body && depth < 8) {
                    if (ignoredElement(current)) {
                        break;
                    }

                    const text = normalise(current.textContent || '');
                    const rect = elementRect(current);

                    if (phraseCount(text, phrases) > 0 && text.length < 2200 && (rect.width || 0) > (bestRect.width || 0)) {
                        best = current;
                    }

                    if ((rect.width || 0) >= 650 && phraseCount(text, phrases) > 0 && text.length < 2200) {
                        break;
                    }

                    current = current.parentElement;
                    depth++;
                }
            }
        }

        return best;
    }

    function addFactsSummaryToggle(bar, wideArea) {
        if (!bar || document.querySelector('[data-potts-relationship-context="facts-summary-toggle"]')) {
            return;
        }

        const label = document.createElement('label');
        label.className = 'potts-relationship-context-toggle-label';
        const checkbox = document.createElement('input');
        checkbox.type = 'checkbox';
        checkbox.checked = factsSummaryVisible();
        checkbox.setAttribute('data-potts-relationship-context', 'facts-summary-toggle');
        checkbox.addEventListener('change', function(){
            setFactsSummaryVisible(checkbox.checked);
        });
        label.appendChild(checkbox);
        label.appendChild(document.createTextNode(' Relationship'));
        bar.appendChild(label);
    }

    function ensureFactsSummaryToggle() {
        const controlBar = findFactsControlBar();
        if (!controlBar) {
            return;
        }

        const filterCell = controlBar.closest('td,th') || controlBar;
        const filterRow = filterCell.closest ? filterCell.closest('tr') : null;
        addFactsSummaryToggle(filterCell, filterRow || filterCell);
    }

    function insertFactsSummaryInFactsPanel(summary) {
        const controlBar = findFactsControlBar();
        if (!controlBar) {
            return false;
        }

        const filterCell = controlBar.closest('td,th');
        const filterRow = filterCell ? filterCell.closest('tr') : null;
        if (!filterCell || !filterRow || !filterRow.parentNode) {
            return false;
        }

        addFactsSummaryToggle(filterCell, filterRow);
        summary.classList.add('potts-relationship-context-summary-in-controls');

        // Facts are rendered as a two-column HTML table. A section cannot be a
        // direct child of TR, so give the summary its own valid full-width row.
        const summaryRow = document.createElement('tr');
        summaryRow.className = 'potts-relationship-context-summary-row';
        summaryRow.setAttribute('data-potts-relationship-context', 'facts-summary-row');

        const summaryCell = document.createElement('td');
        summaryCell.className = 'potts-relationship-context-summary-cell';
        const table = filterRow.closest('table');
        let columnCount = Math.max(2, filterRow.cells ? filterRow.cells.length : 0);

        if (table) {
            Array.from(table.rows || []).some(function(row){
                if (row !== filterRow && row.cells && row.cells.length > 1) {
                    columnCount = Math.max(columnCount, row.cells.length);
                    return true;
                }
                return false;
            });
        }

        summaryCell.colSpan = columnCount;
        summaryCell.appendChild(summary);
        summaryRow.appendChild(summaryCell);
        filterRow.insertAdjacentElement('afterend', summaryRow);

        status.summaryWideAreaWidth = Math.round(elementRect(summaryCell).width || 0);
        status.summaryControlWidth = Math.round(elementRect(filterCell).width || 0);
        status.summaryHostWidth = Math.round(elementRect(summary).width || 0);

        return true;
    }

    function insertFactsSummaryNearTitle(summary) {
        const heading = findHeading();
        if (!heading) {
            return false;
        }
        summary.classList.remove('col-12', 'w-100');
        summary.classList.add('potts-relationship-context-summary-near-title');
        const target = heading.closest('.wt-page-title,.individual-header,.wt-individual-header') || heading;
        target.insertAdjacentElement('afterend', summary);
        return true;
    }

    function insertFactsSummaryAboveTabs(summary) {
        const tabs = findTabsAnchor();
        if (!tabs || !tabs.parentNode) {
            return false;
        }
        tabs.insertAdjacentElement('beforebegin', summary);
        return true;
    }

    function insertFactsSummary() {
        if (!config.showFactsSummary || config.summaryPosition === 'off') {
            return;
        }

        // Keep the visitor control available regardless of where the summary
        // itself is placed. Repeated runs also catch tabs rendered slightly later.
        ensureFactsSummaryToggle();

        if (document.querySelector('[data-potts-relationship-context="facts-summary"]')) {
            return;
        }

        const summary = makeFactsSummary();
        summary.classList.add('col-12', 'w-100');

        let inserted = false;
        if (config.summaryPosition === 'near-title') {
            inserted = insertFactsSummaryNearTitle(summary);
        } else if (config.summaryPosition === 'above-tabs') {
            inserted = insertFactsSummaryAboveTabs(summary);
        } else {
            inserted = insertFactsSummaryInFactsPanel(summary);
        }

        status.insertedFactsSummary = inserted;
        if (!inserted && summary.parentNode) {
            summary.parentNode.removeChild(summary);
        }
    }

    function findHeading() {
        const selectors = [
            '.wt-page-title',
            '.individual-header h1',
            '.wt-individual-header h1',
            'main h1',
            '#content h1',
            'h1'
        ];

        for (const selector of selectors) {
            const element = document.querySelector(selector);
            if (element) {
                return element;
            }
        }

        return null;
    }

    function findTabsAnchor() {
        const selectors = [
            '.wt-tabs',
            '.wt-page-tabs',
            '.wt-individual-tabs',
            '.nav-tabs',
            '.nav-pills',
            '[role="tablist"]'
        ];

        for (const selector of selectors) {
            const element = document.querySelector(selector);
            if (element && !ignoredElement(element)) {
                return element;
            }
        }

        return null;
    }

    function likelyLeftTile(element) {
        if (!element) {
            return null;
        }

        function className(el) {
            return String(el && el.className || '');
        }

        function looksLikeTile(el) {
            if (!el) {
                return false;
            }

            const cls = className(el);
            const text = normalise(el.textContent || '');

            return /\bcol-(sm|md|lg|xl)-[234]\b/.test(cls)
                || cls.indexOf('fact-label') !== -1
                || cls.indexOf('fact-title') !== -1
                || cls.indexOf('wt-fact-label') !== -1
                || text.length < 180;
        }

        // Prefer the first column of the fact/event row. This avoids adding labels to the right-hand detail column.
        let current = element;
        let depth = 0;
        while (current && current !== document.body && depth < 8) {
            const children = Array.from(current.children || []);
            const cls = className(current);
            const rowLike = cls.indexOf('row') !== -1
                || cls.indexOf('wt-fact') !== -1
                || cls.indexOf('fact') !== -1
                || cls.indexOf('event') !== -1
                || children.some(function(child){ return /\bcol-(sm|md|lg|xl)-\d+\b/.test(className(child)); });

            if (current !== element && rowLike && children.length > 1 && children[0] && !children[0].contains(element) && looksLikeTile(children[0])) {
                return children[0];
            }
            current = current.parentElement;
            depth++;
        }

        const selectors = [
            '.wt-fact-label',
            '.fact_LABEL',
            '.fact-label',
            '.wt-fact-title',
            '[class*="fact-label"]',
            '[class*="fact-title"]',
            '.col-sm-3',
            '.col-md-3',
            '.col-lg-3',
            '.col-xl-3'
        ];

        for (const selector of selectors) {
            const match = element.closest(selector) || element.querySelector(selector);
            if (match) {
                return match;
            }
        }

        const row = element.closest('.row,.wt-fact,.fact,.event,[class*="fact"],[class*="event"]');
        if (row) {
            const columns = Array.from(row.children || []);
            if (columns.length > 1 && looksLikeTile(columns[0])) {
                return columns[0];
            }
            return row;
        }

        return element;
    }

    function candidateRoots() {
        const selectors = [
            '#personal_facts',
            '[id*="personal_facts"]',
            '#facts-content',
            '#facts',
            '.wt-facts',
            '.wt-fact-list',
            '.tab-content',
            '.tab-pane',
            'main',
            '#content'
        ];

        const roots = [];
        for (const selector of selectors) {
            document.querySelectorAll(selector).forEach(function(element){
                if (!roots.includes(element)) {
                    roots.push(element);
                }
            });
        }

        return roots.length ? roots : [document.body];
    }

    function ignoredElement(element) {
        if (!element || !element.closest) {
            return false;
        }

        return !!element.closest('.wt-family-navigator,.family-navigator,[class*="family-navigator"],[class*="relationship"],[class*="sidebar"],aside,nav,header,footer,.dropdown-menu,.wt-page-options,.wt-page-title');
    }

    function candidateElements() {
        const selectors = [
            '.wt-fact',
            '.fact',
            '.event',
            '.row',
            '[class*="fact"]',
            '[class*="event"]',
            '[class*="timeline"]'
        ];
        const elements = [];

        candidateRoots().forEach(function(root){
            selectors.forEach(function(selector){
                root.querySelectorAll(selector).forEach(function(element){
                    const text = normalise(element.textContent || '');

                    // Very large containers can contain several facts plus the family navigator.
                    // Matching those can place a relationship label on the first tile on the page.
                    if (text.length > 1200 || ignoredElement(element)) {
                        return;
                    }

                    if (!elements.includes(element)) {
                        elements.push(element);
                    }
                });
            });
        });

        // Prefer the smallest matching element so the label is attached to the actual fact row, not a parent wrapper.
        elements.sort(function(a, b){
            return normalise(a.textContent || '').length - normalise(b.textContent || '').length;
        });

        return elements;
    }

    function containsText(haystack, needle) {
        needle = normalise(needle);
        return !!needle && normalise(haystack).indexOf(needle) !== -1;
    }

    function isGenericAlias(alias) {
        alias = normalise(alias);
        return ['birth', 'christening', 'baptism', 'death', 'burial', 'marriage', 'occupation', 'residence', 'census'].indexOf(alias) !== -1;
    }

    function rowKey(row) {
        return String(row.rowKey || [row.category, row.subjectXref, row.label, row.date, row.relationship].join('|'));
    }

    function candidateIsRightSideDetail(element, tile) {
        if (!element || !tile) {
            return false;
        }

        if (element === tile || tile.contains(element)) {
            return false;
        }

        const tileText = normalise(tile.textContent || '');
        const elementText = normalise(element.textContent || '');

        return tileText && elementText && elementText.length > tileText.length * 2;
    }

    function matchesRow(elementText, row) {
        const text = normalise(elementText);
        if (!text || text.length > 1200 || text.indexOf('family navigator') !== -1) {
            return false;
        }

        const subjectName = normalise(row.subjectName || '');
        const date = normalise(row.date || '');
        const label = normalise(row.label || '');
        const relationship = normalise(row.relationship || '');

        // A close-relative or associate event must identify the other person.
        // This avoids placing a relationship label on ordinary personal facts such as the viewed person's own birth.
        if (subjectName && text.indexOf(subjectName) === -1) {
            return false;
        }

        if (date && text.indexOf(date) === -1) {
            return false;
        }

        if (label && text.indexOf(label) !== -1) {
            return true;
        }

        if (relationship && text.indexOf(relationship) !== -1) {
            return true;
        }

        const aliases = Array.isArray(row.aliases) ? row.aliases : [];
        return aliases.some(function(alias){
            alias = normalise(alias);
            return alias && !isGenericAlias(alias) && text.indexOf(alias) !== -1;
        });
    }

    function renderedRelationshipAlreadyShown(elements, row) {
        const subjectName = normalise(row.subjectName || '');
        const relationship = normalise(String(row.relationship || '').replace(/[-_]+/g, ' '));

        if (!subjectName || !relationship) {
            return false;
        }

        const kinshipTerms = [
            'father', 'mother', 'parent', 'grandfather', 'grandmother', 'grandparent',
            'brother', 'sister', 'sibling', 'son', 'daughter', 'child',
            'husband', 'wife', 'spouse', 'uncle', 'aunt', 'nephew', 'niece',
            'cousin', 'grandson', 'granddaughter', 'grandchild', 'in law'
        ].filter(function(term){ return relationship.indexOf(term) !== -1; });

        return elements.some(function(element){
            const text = normalise(element.textContent || '').replace(/[-_]+/g, ' ');
            if (!text || text.length > 1200 || text.indexOf(subjectName) === -1) {
                return false;
            }

            if (text.indexOf(relationship) !== -1) {
                return true;
            }

            return kinshipTerms.some(function(term){
                return text.indexOf(term) !== -1;
            });
        });
    }

    function relationshipLabelsIn(tile) {
        return Array.from(tile.querySelectorAll('[data-potts-relationship-context="fact"]'));
    }

    function ageElementIn(tile) {
        return tile.querySelector('.potts-fact-age-slot,.potts-fact-age-inline,[data-potts-fact-age-badge]');
    }

    function controlElementIn(tile) {
        return Array.from(tile.children || []).find(function(child){
            if (child.matches && child.matches('[data-potts-relationship-context="fact"],.potts-fact-age-slot,.potts-fact-age-inline,[data-potts-fact-age-badge]')) {
                return false;
            }

            const text = normalise(child.textContent || '');
            return text.length < 20 && !!child.querySelector('a,button,.btn,.dropdown,.icon');
        });
    }

    function placeLabelInTile(tile, label) {
        const age = ageElementIn(tile);
        if (age && age.parentNode === tile) {
            tile.insertBefore(label, age);
            return;
        }

        const controls = controlElementIn(tile);
        if (controls && controls.parentNode === tile) {
            tile.insertBefore(label, controls);
            return;
        }

        tile.appendChild(label);
    }

    function tidyExistingLabels() {
        document.querySelectorAll('[data-potts-relationship-context="fact"]').forEach(function(label){
            const tile = likelyLeftTile(label);
            if (!tile) {
                return;
            }

            placeLabelInTile(tile, label);
        });
    }

    function insertLabelIntoTile(tile, label) {
        placeLabelInTile(tile, label);
    }

    function insertFactLabels() {
        if (!config.showFactLabels || !Array.isArray(config.factRelationships)) {
            return;
        }

        const elements = candidateElements();
        let inserted = 0;

        config.factRelationships.forEach(function(row){
            if (!row || !row.relationship || !row.subjectName) {
                return;
            }

            const key = rowKey(row);
            if (document.querySelector('[data-potts-relationship-row-key="' + CSS.escape(key) + '"]')) {
                return;
            }

            if (renderedRelationshipAlreadyShown(elements, row)) {
                status.nativeRelationshipLabels = (status.nativeRelationshipLabels || 0) + 1;
                return;
            }

            for (const element of elements) {
                if (element.querySelector && element.querySelector('[data-potts-relationship-context="fact"]')) {
                    continue;
                }

                if (!matchesRow(element.textContent || '', row)) {
                    continue;
                }

                const tile = likelyLeftTile(element);
                if (!tile || tile.querySelector('[data-potts-relationship-context="fact"]')) {
                    continue;
                }

                if (candidateIsRightSideDetail(element, tile)) {
                    // Use the matched row to find the left tile, but never place the label in the detail column.
                }

                const label = document.createElement('div');
                label.className = 'potts-relationship-context-fact-label';
                label.setAttribute('data-potts-relationship-context', 'fact');
                label.setAttribute('data-potts-relationship-row-key', key);
                label.textContent = row.displayText || ('Relationship: ' + row.relationship);
                insertLabelIntoTile(tile, label);
                inserted++;
                break;
            }
        });

        status.insertedFactLabels = document.querySelectorAll('[data-potts-relationship-context="fact"]').length || inserted;
    }

    function run() {
        insertFactsSummary();
        insertFactLabels();
        tidyExistingLabels();
    }

    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', run);
    } else {
        run();
    }

    window.addEventListener('load', run);
    setTimeout(run, 250);
    setTimeout(run, 1000);
    setTimeout(run, 2500);
})();
JS;

        return '<script>' . str_replace('CONFIG_PLACEHOLDER', $json, $script) . '</script>';
    }

    private function styleCss(): string
    {
        return <<<'CSS'
.potts-relationship-context-facts-summary {
    align-items: center;
    background: linear-gradient(135deg, #f8fafc 0%, #fffaf0 100%);
    border: 1px solid #d7dee8;
    border-left: 6px solid #d2a45f;
    border-radius: 16px;
    box-shadow: 0 8px 20px rgba(15, 23, 42, .06);
    box-sizing: border-box;
    clear: both;
    color: #1f2933;
    display: flex;
    flex: 1 0 100% !important;
    gap: 12px;
    grid-column: 1 / -1 !important;
    line-height: 1.35;
    margin: 12px 0 18px 0;
    max-width: none !important;
    min-width: 0;
    padding: 14px 18px;
    width: 100% !important;
}
.potts-relationship-context-facts-summary[hidden] {
    display: none !important;
}
.potts-relationship-context-no-relationship {
    background: #f5f6f7 !important;
    border-color: #cbd1d8 !important;
    border-left-color: #7a8591 !important;
    box-shadow: none !important;
}
.potts-relationship-context-no-relationship .potts-relationship-context-summary-icon {
    background: #65717d;
}
.potts-relationship-context-no-relationship .potts-relationship-context-summary-label {
    color: #65717d;
}
.potts-relationship-context-summary-icon {
    align-items: center;
    background: #0f5b6e;
    border-radius: 999px;
    color: #fff;
    display: inline-flex;
    flex: 0 0 38px;
    font-size: 1.1rem;
    font-weight: 800;
    height: 38px;
    justify-content: center;
    width: 38px;
}
.potts-relationship-context-summary-body {
    min-width: 0;
    overflow-wrap: anywhere;
}
.potts-relationship-context-summary-label {
    color: #586574;
    font-size: .78rem;
    font-weight: 800;
    letter-spacing: .04em;
    text-transform: uppercase;
}
.potts-relationship-context-summary-text {
    color: #1f2933;
    font-size: 1.08rem;
    font-weight: 800;
    margin-top: 2px;
}
.potts-relationship-context-path-link {
    color: #0f5b6e;
    display: inline-flex;
    font-size: .86rem;
    font-weight: 750;
    margin-top: 5px;
    text-decoration: underline;
    text-decoration-thickness: 1px;
    text-underline-offset: 3px;
}
.potts-relationship-context-path-link:hover,
.potts-relationship-context-path-link:focus {
    color: #083f4d;
}
.potts-relationship-context-style-theme {
    background: var(--bs-body-bg, #fff) !important;
    border-color: var(--bs-border-color, #ced4da) !important;
    border-left-color: var(--bs-primary, #0d6efd) !important;
    box-shadow: 0 3px 10px rgba(0, 0, 0, .08) !important;
    color: var(--bs-body-color, #212529) !important;
}
.potts-relationship-context-style-theme .potts-relationship-context-summary-icon {
    background: var(--bs-primary, #0d6efd);
    color: var(--bs-white, #fff);
}
.potts-relationship-context-style-theme .potts-relationship-context-summary-label {
    color: var(--bs-secondary-color, #6c757d);
}
.potts-relationship-context-style-theme .potts-relationship-context-summary-text {
    color: var(--bs-body-color, #212529);
}
.potts-relationship-context-style-theme .potts-relationship-context-path-link {
    color: var(--bs-link-color, #0d6efd);
}
.potts-relationship-context-style-theme .potts-relationship-context-path-link:hover,
.potts-relationship-context-style-theme .potts-relationship-context-path-link:focus {
    color: var(--bs-link-hover-color, #0a58ca);
}
.potts-relationship-context-style-theme.potts-relationship-context-no-relationship {
    background: var(--bs-tertiary-bg, #f5f6f7) !important;
    border-color: var(--bs-border-color, #cbd1d8) !important;
    border-left-color: var(--bs-secondary-color, #7a8591) !important;
    box-shadow: none !important;
}
.potts-relationship-context-style-theme.potts-relationship-context-no-relationship .potts-relationship-context-summary-icon {
    background: var(--bs-secondary-color, #65717d);
}
.potts-relationship-context-summary-in-controls {
    display: flex !important;
    margin: 10px 0 14px 0 !important;
    max-width: none !important;
    width: 100% !important;
}
.potts-relationship-context-summary-near-title {
    align-self: center !important;
    flex: 0 1 auto !important;
    grid-column: auto !important;
    height: auto !important;
    justify-self: start !important;
    margin: 16px 24px !important;
    max-width: 680px !important;
    min-height: 0 !important;
    width: calc(100% - 48px) !important;
}
.potts-relationship-context-summary-row,
.potts-relationship-context-summary-cell {
    background: transparent !important;
    border: 0 !important;
}
.potts-relationship-context-summary-cell {
    padding: 0 !important;
    width: 100% !important;
}
@media (max-width: 767px) {
    .potts-relationship-context-facts-summary {
        align-items: flex-start;
        border-left-width: 4px;
        border-radius: 10px;
        gap: 10px;
        margin: 8px 0 12px 0;
        padding: 12px 13px;
    }
    .potts-relationship-context-summary-icon {
        flex-basis: 32px;
        font-size: .95rem;
        height: 32px;
        width: 32px;
    }
    .potts-relationship-context-summary-label {
        font-size: .7rem;
        line-height: 1.25;
    }
    .potts-relationship-context-summary-text {
        font-size: .98rem;
        line-height: 1.35;
    }
    .potts-relationship-context-path-link {
        font-size: .82rem;
    }
    .potts-relationship-context-summary-near-title {
        align-self: auto !important;
        grid-column: 1 / -1 !important;
        justify-self: stretch !important;
        margin: 10px 0 !important;
        max-width: none !important;
        width: 100% !important;
    }
    .potts-relationship-context-toggle-label {
        white-space: normal;
    }
    .potts-relationship-context-fact-label {
        font-size: .8rem;
    }
}
@media (max-width: 420px) {
    .potts-relationship-context-facts-summary {
        padding: 10px 11px;
    }
    .potts-relationship-context-summary-icon {
        flex-basis: 30px;
        height: 30px;
        width: 30px;
    }
    .potts-relationship-context-summary-text {
        font-size: .92rem;
    }
}
.potts-relationship-context-toggle-label {
    align-items: center;
    display: inline-flex;
    gap: 4px;
    margin-left: 0;
    white-space: nowrap;
}
.potts-relationship-context-toggle-label input {
    margin: 0;
}
.potts-relationship-context-fact-label {
    color: #586574;
    font-size: .86rem;
    font-weight: 700;
    line-height: 1.25;
    margin: 6px auto 5px auto;
    max-width: 100%;
    text-align: center;
    width: 100%;
}
.prc-admin-help {
    color: #586574;
    font-size: .92rem;
    line-height: 1.45;
    margin-top: 6px;
}
CSS;
    }

    /**
     * @return array{individual:?Individual,mode:string}
     */
    private function referenceIndividual(Tree $tree): array
    {
        if ($this->boolPreference(self::PREF_USE_ACCOUNT_INDIVIDUAL)) {
            try {
                $xref = $tree->getUserPreference(Auth::user(), UserInterface::PREF_TREE_ACCOUNT_XREF, '');

                if ($xref !== '') {
                    $individual = Registry::individualFactory()->make($xref, $tree);

                    if ($individual instanceof Individual) {
                        return ['individual' => $individual, 'mode' => 'account'];
                    }
                }
            } catch (Throwable) {
                // Continue to the next fallback.
            }
        }

        if ($this->boolPreference(self::PREF_USE_FAVOURITE_INDIVIDUAL)) {
            try {
                $xref = $tree->getUserPreference(Auth::user(), UserInterface::PREF_TREE_DEFAULT_XREF, '');

                if ($xref !== '') {
                    $individual = Registry::individualFactory()->make($xref, $tree);

                    if ($individual instanceof Individual) {
                        return ['individual' => $individual, 'mode' => 'favourite'];
                    }
                }
            } catch (Throwable) {
                // Continue to the next fallback.
            }
        }

        $xref = trim($this->getPreference(self::PREF_PUBLIC_REFERENCE_XREF, ''));

        if ($xref !== '') {
            $individual = Registry::individualFactory()->make($xref, $tree);

            if ($individual instanceof Individual && $individual->canShow(Auth::PRIV_PRIVATE)) {
                return ['individual' => $individual, 'mode' => 'public'];
            }
        }

        if ($this->boolPreference(self::PREF_FALLBACK_TREE_ROOT)) {
            $xref = $tree->getPreference('PEDIGREE_ROOT_ID', '');

            if ($xref !== '') {
                $individual = Registry::individualFactory()->make($xref, $tree);

                if ($individual instanceof Individual) {
                    return ['individual' => $individual, 'mode' => 'tree-root'];
                }
            }
        }

        return ['individual' => null, 'mode' => 'none'];
    }

    private function relationshipPathUrl(Individual $from, Individual $to): string
    {
        if ($from->xref() === $to->xref()) {
            return '';
        }

        try {
            $tree = $from->tree();

            return route(RelationshipsChartModule::class, [
                'tree' => $tree->name(),
                // The context module can report relationships by marriage.
                // Ancestor-only charts cannot display those paths.
                'ancestors' => 0,
                'recursion' => 0,
                'xref' => $from->xref(),
                'xref2' => $to->xref(),
            ]);
        } catch (Throwable) {
            return '';
        }
    }

    private function relationshipName(Individual $from, Individual $to): string
    {
        if ($from->xref() === $to->xref()) {
            return I18N::translate('self');
        }

        try {
            /** @var RelationshipService $relationship_service */
            $relationship_service = Registry::container()->get(RelationshipService::class);
            $relationship = trim(strip_tags($relationship_service->getCloseRelationshipName($from, $to)));

            if ($relationship !== '') {
                return $relationship;
            }
        } catch (Throwable) {
            // Fall back to the simple bloodline relationship calculation below.
        }

        return $this->bloodRelationshipName($from, $to, $this->maxGenerations());
    }

    private function bloodRelationshipName(Individual $from, Individual $to, int $max_generations): string
    {
        $from_ancestors = $this->ancestorMap($from, $max_generations);
        $to_ancestors = $this->ancestorMap($to, $max_generations);

        if (isset($from_ancestors[$to->xref()]) && $from_ancestors[$to->xref()]['generations'] > 0) {
            return $this->ancestorRelationship((int) $from_ancestors[$to->xref()]['generations'], $to->sex());
        }

        if (isset($to_ancestors[$from->xref()]) && $to_ancestors[$from->xref()]['generations'] > 0) {
            return $this->descendantRelationship((int) $to_ancestors[$from->xref()]['generations'], $to->sex());
        }

        $best = null;

        foreach ($from_ancestors as $xref => $from_data) {
            if (!isset($to_ancestors[$xref])) {
                continue;
            }

            $a = (int) $from_data['generations'];
            $b = (int) $to_ancestors[$xref]['generations'];

            if ($a === 0 || $b === 0) {
                continue;
            }

            $score = $a + $b;

            if ($best === null || $score < $best['score'] || ($score === $best['score'] && max($a, $b) < $best['max'])) {
                $best = [
                    'a' => $a,
                    'b' => $b,
                    'score' => $score,
                    'max' => max($a, $b),
                ];
            }
        }

        if ($best === null) {
            return '';
        }

        return $this->collateralRelationship((int) $best['a'], (int) $best['b'], $to->sex());
    }

    /**
     * @return array<string,array{individual:Individual,generations:int}>
     */
    private function ancestorMap(Individual $individual, int $max_generations): array
    {
        $access_level = Auth::accessLevel($individual->tree());
        $map = [
            $individual->xref() => [
                'individual' => $individual,
                'generations' => 0,
            ],
        ];

        $queue = [[$individual, 0]];

        while ($queue !== []) {
            [$current, $generation] = array_shift($queue);

            if ($generation >= $max_generations) {
                continue;
            }

            foreach ($current->childFamilies($access_level) as $family) {
                foreach ($family->spouses($access_level) as $parent) {
                    if (!$parent instanceof Individual || !$parent->canShow($access_level)) {
                        continue;
                    }

                    $next_generation = $generation + 1;
                    $xref = $parent->xref();

                    if (!isset($map[$xref]) || $next_generation < $map[$xref]['generations']) {
                        $map[$xref] = [
                            'individual' => $parent,
                            'generations' => $next_generation,
                        ];
                        $queue[] = [$parent, $next_generation];
                    }
                }
            }
        }

        return $map;
    }

    private function ancestorRelationship(int $generations, string $sex): string
    {
        if ($generations === 1) {
            return $this->gendered($sex, I18N::translate('father'), I18N::translate('mother'), I18N::translate('parent'));
        }

        if ($generations === 2) {
            return $this->gendered($sex, I18N::translate('grandfather'), I18N::translate('grandmother'), I18N::translate('grandparent'));
        }

        $base = $this->gendered($sex, I18N::translate('grandfather'), I18N::translate('grandmother'), I18N::translate('grandparent'));
        $greats = $generations - 2;

        if ($greats === 1) {
            return I18N::translate('great-%s', $base);
        }

        return $this->ordinal($greats) . ' ' . I18N::translate('great-%s', $base);
    }

    private function descendantRelationship(int $generations, string $sex): string
    {
        if ($generations === 1) {
            return $this->gendered($sex, I18N::translate('son'), I18N::translate('daughter'), I18N::translate('child'));
        }

        if ($generations === 2) {
            return $this->gendered($sex, I18N::translate('grandson'), I18N::translate('granddaughter'), I18N::translate('grandchild'));
        }

        $base = $this->gendered($sex, I18N::translate('grandson'), I18N::translate('granddaughter'), I18N::translate('grandchild'));
        $greats = $generations - 2;

        if ($greats === 1) {
            return I18N::translate('great-%s', $base);
        }

        return $this->ordinal($greats) . ' ' . I18N::translate('great-%s', $base);
    }

    private function collateralRelationship(int $from_to_common, int $to_to_common, string $sex): string
    {
        if ($from_to_common === 1 && $to_to_common === 1) {
            return $this->gendered($sex, I18N::translate('brother'), I18N::translate('sister'), I18N::translate('sibling'));
        }

        if ($to_to_common === 1 && $from_to_common >= 2) {
            $base = $this->gendered($sex, I18N::translate('uncle'), I18N::translate('aunt'), I18N::translate('aunt/uncle'));
            $greats = $from_to_common - 2;

            return $this->greatPrefix($greats, $base);
        }

        if ($from_to_common === 1 && $to_to_common >= 2) {
            $base = $this->gendered($sex, I18N::translate('nephew'), I18N::translate('niece'), I18N::translate('niece/nephew'));
            $greats = $to_to_common - 2;

            return $this->greatPrefix($greats, $base);
        }

        $degree = min($from_to_common, $to_to_common) - 1;
        $removed = abs($from_to_common - $to_to_common);
        $relationship = $this->ordinal($degree) . ' ' . I18N::translate('cousin');

        if ($removed === 1) {
            return $relationship . ' ' . I18N::translate('once removed');
        }

        if ($removed > 1) {
            return $relationship . ' ' . $this->ordinal($removed) . ' ' . I18N::translate('removed');
        }

        return $relationship;
    }

    private function greatPrefix(int $greats, string $base): string
    {
        if ($greats <= 0) {
            return $base;
        }

        if ($greats === 1) {
            return I18N::translate('great-%s', $base);
        }

        return $this->ordinal($greats) . ' ' . I18N::translate('great-%s', $base);
    }

    private function gendered(string $sex, string $male, string $female, string $unknown): string
    {
        return match ($sex) {
            'M' => $male,
            'F' => $female,
            default => $unknown,
        };
    }

    private function ordinal(int $number): string
    {
        $last_two = $number % 100;
        $last = $number % 10;

        if ($last_two >= 11 && $last_two <= 13) {
            return $number . 'th';
        }

        return match ($last) {
            1 => $number . 'st',
            2 => $number . 'nd',
            3 => $number . 'rd',
            default => $number . 'th',
        };
    }

    private function prettyRelationship(string $relationship): string
    {
        $relationship = trim(str_replace(['-', '_'], ' ', $relationship));
        $relationship = preg_replace('/\s+/', ' ', $relationship) ?? $relationship;

        if ($relationship === '') {
            return '';
        }

        return mb_strtoupper(mb_substr($relationship, 0, 1)) . mb_substr($relationship, 1);
    }

    private function factLabelAlreadyIncludesRelationship(string $label, string $relationship, string $category): bool
    {
        if ($category !== 'relative') {
            return false;
        }

        $label_text = strtolower(str_replace(['-', '_'], ' ', strip_tags($label)));
        $label_text = preg_replace('/\s+/', ' ', $label_text) ?? $label_text;
        $relationship_text = strtolower(str_replace(['-', '_'], ' ', strip_tags($relationship)));
        $relationship_text = preg_replace('/\s+/', ' ', $relationship_text) ?? $relationship_text;

        if ($relationship_text !== '' && str_contains($label_text, $relationship_text)) {
            return true;
        }

        foreach ([
            'father', 'mother', 'parent', 'grandfather', 'grandmother', 'grandparent',
            'brother', 'sister', 'sibling', 'son', 'daughter', 'child',
            'husband', 'wife', 'spouse', 'uncle', 'aunt', 'nephew', 'niece', 'cousin',
        ] as $word) {
            if (str_contains($label_text, $word)) {
                return true;
            }
        }

        return false;
    }

    /**
     * @return array<int,array<string,mixed>>
     */
    private function factRelationshipRows(Individual $individual): array
    {
        $rows = [];

        if (!$this->boolPreference(self::PREF_SHOW_FACT_LABELS)) {
            return $rows;
        }

        try {
            /** @var IndividualFactsService $service */
            $service = Registry::container()->get(IndividualFactsService::class);
            $this->appendFactRelationshipRows($rows, $individual, $service->relativeFacts($individual), 'relative');
            $this->appendFactRelationshipRows($rows, $individual, $service->associateFacts($individual), 'associate');
        } catch (Throwable) {
            return $rows;
        }

        return $rows;
    }

    /**
     * @param array<int,array<string,mixed>> $rows
     */
    private function appendFactRelationshipRows(array &$rows, Individual $individual, Collection $facts, string $category): void
    {
        $seen = [];

        foreach ($facts as $fact) {
            if (!$fact instanceof Fact) {
                continue;
            }

            $subject = $this->subjectIndividualForFact($fact, $individual);

            if (!$subject instanceof Individual || !$subject->canShow() || $subject->xref() === $individual->xref()) {
                continue;
            }

            $relationship = $this->relationshipName($individual, $subject);

            if ($relationship === '') {
                continue;
            }

            if ($this->factLabelAlreadyIncludesRelationship(strip_tags($fact->label()), $relationship, $category)) {
                continue;
            }

            $signature = sha1($category . ':' . $fact->gedcom() . ':' . $subject->xref());

            if (isset($seen[$signature])) {
                continue;
            }

            $seen[$signature] = true;
            $date = '';

            if ($fact->date()->isOK()) {
                $date = strip_tags($fact->date()->display());
            }

            $row_key = sha1($category . ':' . $subject->xref() . ':' . strip_tags($fact->label()) . ':' . $date . ':' . $relationship);

            foreach ($rows as $existing_row) {
                if (($existing_row['rowKey'] ?? '') === $row_key) {
                    continue 2;
                }
            }

            $display_text = $this->labelStyle() === self::LABEL_STYLE_SENTENCE
                ? I18N::translate('%1$s is this individual’s %2$s', strip_tags($subject->fullName()), $this->prettyRelationship($relationship))
                : $this->prettyRelationship($relationship);

            $rows[] = [
                'category' => $category,
                'subjectXref' => $subject->xref(),
                'subjectName' => strip_tags($subject->fullName()),
                'rowKey' => $row_key,
                'relationship' => $relationship,
                'displayText' => $display_text,
                'label' => strip_tags($fact->label()),
                'date' => $date,
                'aliases' => $this->factAliases($fact, $subject),
            ];
        }
    }

    private function subjectIndividualForFact(Fact $fact, Individual $viewed): ?Individual
    {
        $record = $fact->record();

        if ($record instanceof Individual && $record->xref() !== $viewed->xref()) {
            return $record;
        }

        $target = $fact->target();

        if ($target instanceof Individual && $target->xref() !== $viewed->xref()) {
            return $target;
        }

        if (preg_match_all('/@([^@]+)@/', $fact->gedcom(), $matches) === false) {
            return null;
        }

        foreach ($matches[1] as $xref) {
            $individual = Registry::individualFactory()->make($xref, $viewed->tree());

            if ($individual instanceof Individual && $individual->xref() !== $viewed->xref()) {
                return $individual;
            }
        }

        return null;
    }

    /**
     * @return array<int,string>
     */
    private function factAliases(Fact $fact, Individual $subject): array
    {
        $aliases = [];
        $aliases[] = strip_tags($fact->label());
        $aliases[] = strip_tags($subject->fullName());

        $value = trim(strip_tags($fact->value()));

        if ($value !== '' && $value !== 'Y') {
            $aliases[] = $value;
        }

        $type = trim(strip_tags($fact->attribute('TYPE')));

        if ($type !== '') {
            $aliases[] = $type;
        }

        return array_values(array_unique(array_filter($aliases)));
    }

    public function getAdminAction(ServerRequestInterface $request): ResponseInterface
    {
        $html = '<style>' . $this->styleCss() . $this->settingsCss() . '</style>';
        $html .= '<div class="prc-admin" style="max-width:1180px;margin:0 auto;padding:24px;font-family:system-ui,-apple-system,BlinkMacSystemFont,&quot;Segoe UI&quot;,sans-serif;color:#1f2933;">';
        $html .= '<div style="border:1px solid #d7dee8;border-radius:18px;background:#f8fafc;padding:22px 26px;margin-bottom:22px;box-shadow:0 10px 24px rgba(15,23,42,.06);">';
        $html .= '<div style="display:flex;flex-wrap:wrap;justify-content:space-between;gap:16px;align-items:flex-start;">';
        $html .= '<div>';
        $html .= '<h2 style="margin:0 0 8px 0;font-size:1.75rem;line-height:1.2;">' . $this->escape($this->title()) . '</h2>';
        $html .= '<p style="margin:0;color:#586574;font-size:1rem;">' . $this->escape($this->description()) . '</p>';
        $html .= '</div>';
        $html .= '<span style="display:inline-block;border:1px solid #cbd5e1;border-radius:999px;background:#fff;padding:5px 12px;color:#586574;font-size:.9rem;">' . $this->escape(self::VERSION) . '</span>';
        $html .= '</div>';
        $html .= '</div>';
        $html .= $this->adminNavigation($request, 'top');
        $html .= '<form method="post" action="' . $this->escape($this->getConfigLink()) . '">';
        $html .= csrf_field();
        $html .= '<input type="hidden" name="save" value="1">';

        $html .= $this->adminSection(
            I18N::translate('Reference person'),
            '<p style="margin-top:0;color:#586574;">' .
            I18N::translate('Choose who relationships are calculated from. Logged-in users can use their linked individual or favourite individual. Public visitors use the configured public reference person or the tree root.') .
            '</p>' .
            '<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:14px;">' .
            $this->checkboxField(self::PREF_USE_ACCOUNT_INDIVIDUAL, I18N::translate('Use logged-in user’s linked individual'), I18N::translate('Best option for signed-in family members.')) .
            $this->checkboxField(self::PREF_USE_FAVOURITE_INDIVIDUAL, I18N::translate('Use logged-in user’s favourite individual'), I18N::translate('Used if the account is not linked to an individual.')) .
            $this->checkboxField(self::PREF_FALLBACK_TREE_ROOT, I18N::translate('Fall back to the tree root individual'), I18N::translate('Used when there is no logged-in reference person and no public reference individual.')) .
            '</div>' .
            '<div style="margin-top:16px;">' . $this->publicReferenceField() . '</div>'
        );

        $html .= $this->adminSection(
            I18N::translate('Display options'),
            '<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:14px;">' .
            $this->checkboxField(self::PREF_SHOW_FACTS_SUMMARY, I18N::translate('Show relationship summary sentence'), I18N::translate('Shows a sentence such as “Beryl Patricia Potts is your aunt.” The position is controlled below.')) .
            $this->checkboxField(self::PREF_SHOW_RELATIONSHIP_PATH, I18N::translate('Show View relationship path link'), I18N::translate('Links the relationship summary to the built-in webtrees Relationships chart.')) .
            $this->checkboxField(self::PREF_SHOW_FACT_LABELS, I18N::translate('Show missing relationship labels on close-relative and associate events'), I18N::translate('Adds a relationship only when webtrees does not already display one for that person and event.')) .
            '</div>' .
            '<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:14px;margin-top:16px;">' .
            '<div>' . $this->summaryPositionField() . '</div>' .
            '<div>' . $this->cardStyleField() . '</div>' .
            '<div>' . $this->labelStyleField() . '</div>' .
            '<div>' . $this->maxGenerationsField() . '</div>' .
            '</div>'
        );

        $html .= '<div style="display:flex;gap:10px;margin-top:18px;">';
        $html .= '<button type="submit" style="border:0;border-radius:10px;background:#0d6efd;color:#fff;padding:12px 20px;font-weight:700;cursor:pointer;">' . I18N::translate('Save preferences') . '</button>';
        $html .= '</div>';
        $html .= '</form>';
        $html .= $this->adminNavigation($request, 'bottom');
        $html .= '</div>';

        return response($html);
    }

    public function postAdminAction(ServerRequestInterface $request): ResponseInterface
    {
        $save = Validator::parsedBody($request)->string('save', '');

        if ($save === '1') {
            $public_reference_error = false;

            foreach (self::BOOLEAN_PREFERENCES as $preference => $default) {
                $this->setPreference($preference, Validator::parsedBody($request)->boolean($preference, false) ? '1' : '0');
            }

            $xref = strtoupper(trim(Validator::parsedBody($request)->string(self::PREF_PUBLIC_REFERENCE_XREF, '')));
            $matches = $this->publicReferenceMatches($xref);

            if ($xref === '') {
                $this->setPreference(self::PREF_PUBLIC_REFERENCE_XREF, '');
            } elseif ($matches === []) {
                $public_reference_error = true;
                FlashMessages::addMessage(I18N::translate('The public reference XREF “%s” was not found. The previous public reference has been retained.', $xref), 'danger');
            } elseif (!array_filter($matches, static fn (array $match): bool => $match['public'])) {
                $public_reference_error = true;
                FlashMessages::addMessage(I18N::translate('The public reference “%s” is not visible to signed-out visitors. The previous public reference has been retained.', $xref), 'danger');
            } else {
                $this->setPreference(self::PREF_PUBLIC_REFERENCE_XREF, $xref);

                if (array_filter($matches, static fn (array $match): bool => !$match['public'])) {
                    FlashMessages::addMessage(I18N::translate('The reference “%s” is public in at least one tree but unavailable to visitors in another tree.', $xref), 'warning');
                }
            }

            $max_generations = Validator::parsedBody($request)->integer(self::PREF_MAX_GENERATIONS, 12);
            $max_generations = max(3, min(20, $max_generations));
            $this->setPreference(self::PREF_MAX_GENERATIONS, (string) $max_generations);

            $label_style = Validator::parsedBody($request)
                ->isInArray([self::LABEL_STYLE_COMPACT, self::LABEL_STYLE_SENTENCE])
                ->string(self::PREF_LABEL_STYLE, self::LABEL_STYLE_COMPACT);
            $this->setPreference(self::PREF_LABEL_STYLE, $label_style);

            $card_style = Validator::parsedBody($request)
                ->isInArray([self::CARD_STYLE_THEME, self::CARD_STYLE_POTTS])
                ->string(self::PREF_CARD_STYLE, self::CARD_STYLE_THEME);
            $this->setPreference(self::PREF_CARD_STYLE, $card_style);

            $summary_position = Validator::parsedBody($request)
                ->isInArray([self::SUMMARY_POSITION_FACTS_PANEL, self::SUMMARY_POSITION_ABOVE_TABS, self::SUMMARY_POSITION_NEAR_TITLE, self::SUMMARY_POSITION_OFF])
                ->string(self::PREF_SUMMARY_POSITION, self::SUMMARY_POSITION_FACTS_PANEL);
            $this->setPreference(self::PREF_SUMMARY_POSITION, $summary_position);


            if ($public_reference_error) {
                FlashMessages::addMessage(I18N::translate('The other module preferences were updated.'), 'info');
            } else {
                FlashMessages::addMessage(I18N::translate('The preferences for the module “%s” have been updated.', $this->title()), 'success');
            }
        }

        return redirect($this->getConfigLink());
    }

    private function settingsCss(): string
    {
        return <<<'CSS'
.prc-admin input[type="checkbox"] { transform: translateY(1px); }
.prc-admin a:hover { text-decoration: underline; }
CSS;
    }

    private function adminSection(string $title, string $body): string
    {
        return '<section style="border:1px solid #d7dee8;border-radius:16px;background:#fff;margin-bottom:18px;box-shadow:0 6px 18px rgba(15,23,42,.05);overflow:hidden;">' .
            '<div style="background:#edf2f7;padding:14px 18px;font-weight:700;border-bottom:1px solid #d7dee8;">' . $this->escape($title) . '</div>' .
            '<div style="padding:18px;">' . $body . '</div>' .
            '</section>';
    }

    private function checkboxField(string $name, string $label, string $help): string
    {
        $checked = $this->boolPreference($name) ? ' checked' : '';

        return '<label style="display:block;border:1px solid #d7dee8;border-radius:14px;background:#fff;padding:15px;min-height:100%;cursor:pointer;">' .
            '<div style="display:flex;gap:10px;align-items:flex-start;">' .
            '<input type="checkbox" name="' . $this->escape($name) . '" value="1"' . $checked . ' style="margin-top:3px;">' .
            '<div>' .
            '<div style="font-weight:700;">' . $this->escape($label) . '</div>' .
            '<div class="prc-admin-help">' . $this->escape($help) . '</div>' .
            '</div></div></label>';
    }

    private function publicReferenceField(): string
    {
        $xref = strtoupper(trim($this->getPreference(self::PREF_PUBLIC_REFERENCE_XREF, '')));
        $html = '<label for="' . self::PREF_PUBLIC_REFERENCE_XREF . '" style="display:block;font-weight:700;margin-bottom:6px;">' . I18N::translate('Public reference individual XREF') . '</label>';
        $html .= '<input id="' . self::PREF_PUBLIC_REFERENCE_XREF . '" name="' . self::PREF_PUBLIC_REFERENCE_XREF . '" value="' . $this->escape($xref) . '" placeholder="I123" style="width:100%;max-width:360px;border:1px solid #cbd5e1;border-radius:10px;padding:10px;background:#fff;font:inherit;">';
        $html .= '<div class="prc-admin-help">' . I18N::translate('Signed-out visitors use this person as their relationship reference. Leave blank to use the tree-root fallback.') . '</div>';

        if ($xref === '') {
            $html .= '<div style="margin-top:12px;border:1px solid #cbd5e1;border-radius:12px;background:#f8fafc;padding:12px 14px;color:#586574;">' . I18N::translate('No public reference is configured. The tree root will be used when that fallback is enabled.') . '</div>';

            return $html;
        }

        $matches = $this->publicReferenceMatches($xref);

        if ($matches === []) {
            $html .= '<div style="margin-top:12px;border:1px solid #efb3b3;border-radius:12px;background:#fff5f5;padding:12px 14px;color:#8b1e1e;"><strong>' . I18N::translate('Reference not found') . '</strong><div style="margin-top:3px;">' . I18N::translate('No individual with XREF “%s” was found in the configured family trees.', $this->escape($xref)) . '</div></div>';

            return $html;
        }

        $html .= '<div style="display:grid;gap:10px;margin-top:12px;">';

        foreach ($matches as $match) {
            $public = $match['public'];
            $border = $public ? '#a8d5b5' : '#efb3b3';
            $background = $public ? '#f3fbf5' : '#fff5f5';
            $colour = $public ? '#245b32' : '#8b1e1e';
            $status = $public ? I18N::translate('Visible to signed-out visitors') : I18N::translate('Not visible to signed-out visitors');
            $lifespan = $match['lifespan'] !== '' ? ' (' . $match['lifespan'] . ')' : '';

            $html .= '<div style="border:1px solid ' . $border . ';border-radius:12px;background:' . $background . ';padding:13px 15px;">';
            $html .= '<div style="display:flex;flex-wrap:wrap;justify-content:space-between;gap:8px;align-items:center;">';
            $html .= '<div><strong>' . $this->escape($match['name']) . '</strong>' . $this->escape($lifespan) . '</div>';
            $html .= '<span style="color:' . $colour . ';font-size:.84rem;font-weight:700;">' . $status . '</span>';
            $html .= '</div>';
            $html .= '<div class="prc-admin-help">' . I18N::translate('Tree: %1$s · XREF: %2$s', $this->escape($match['tree']), $this->escape($xref)) . '</div>';
            $html .= '<a href="' . $this->escape($match['url']) . '" target="_blank" rel="noopener" style="display:inline-block;margin-top:7px;color:#0f5b6e;font-weight:700;">' . I18N::translate('View individual') . '</a>';
            $html .= '</div>';
        }

        $html .= '</div>';

        return $html;
    }

    /**
     * @return array<int,array{tree:string,name:string,lifespan:string,url:string,public:bool}>
     */
    private function publicReferenceMatches(string $xref): array
    {
        $xref = strtoupper(trim($xref));

        if ($xref === '') {
            return [];
        }

        $matches = [];

        try {
            /** @var TreeService $tree_service */
            $tree_service = Registry::container()->get(TreeService::class);
            $trees = $tree_service->all();

            foreach ($trees as $tree) {
                if (!$tree instanceof Tree) {
                    continue;
                }

                $individual = Registry::individualFactory()->make($xref, $tree);

                if (!$individual instanceof Individual) {
                    continue;
                }

                $lifespan = preg_replace('/[\x{2068}\x{2069}]/u', '', strip_tags($individual->lifespan())) ?? '';
                $matches[] = [
                    'tree' => $tree->name(),
                    'name' => strip_tags($individual->fullName()),
                    'lifespan' => trim($lifespan),
                    'url' => $individual->url(),
                    'public' => $individual->canShow(Auth::PRIV_PRIVATE),
                ];
            }
        } catch (Throwable) {
            return [];
        }

        return $matches;
    }

    private function textField(string $name, string $label, string $help): string
    {
        return '<label for="' . $this->escape($name) . '" style="display:block;font-weight:700;margin-bottom:6px;">' . $this->escape($label) . '</label>' .
            '<input id="' . $this->escape($name) . '" name="' . $this->escape($name) . '" value="' . $this->escape($this->getPreference($name, '')) . '" style="width:100%;max-width:360px;border:1px solid #cbd5e1;border-radius:10px;padding:10px;background:#fff;font:inherit;">' .
            '<div class="prc-admin-help">' . $this->escape($help) . '</div>';
    }

    private function maxGenerationsField(): string
    {
        return '<label for="' . self::PREF_MAX_GENERATIONS . '" style="display:block;font-weight:700;margin-bottom:6px;">' . I18N::translate('Maximum generations to search') . '</label>' .
            '<input type="number" min="3" max="20" id="' . self::PREF_MAX_GENERATIONS . '" name="' . self::PREF_MAX_GENERATIONS . '" value="' . $this->escape((string) $this->maxGenerations()) . '" style="width:100%;border:1px solid #cbd5e1;border-radius:10px;padding:10px;background:#fff;font:inherit;">' .
            '<div class="prc-admin-help">' . I18N::translate('Higher values can find more distant cousins, but may be slower on very large trees.') . '</div>';
    }

    private function summaryPositionField(): string
    {
        $options = [
            self::SUMMARY_POSITION_FACTS_PANEL => I18N::translate('Inside the Facts and events control panel'),
            self::SUMMARY_POSITION_ABOVE_TABS => I18N::translate('Above the individual page tabs'),
            self::SUMMARY_POSITION_NEAR_TITLE => I18N::translate('Near the individual page title'),
            self::SUMMARY_POSITION_OFF => I18N::translate('Do not show the relationship summary'),
        ];

        $html = '<label for="' . self::PREF_SUMMARY_POSITION . '" style="display:block;font-weight:700;margin-bottom:6px;">' . I18N::translate('Relationship summary position') . '</label>';
        $html .= '<select id="' . self::PREF_SUMMARY_POSITION . '" name="' . self::PREF_SUMMARY_POSITION . '" style="width:100%;border:1px solid #cbd5e1;border-radius:10px;padding:10px;background:#fff;font:inherit;">';

        foreach ($options as $value => $label) {
            $selected = $this->summaryPosition() === $value ? ' selected' : '';
            $html .= '<option value="' . $this->escape($value) . '"' . $selected . '>' . $this->escape($label) . '</option>';
        }

        $html .= '</select>';
        $html .= '<div class="prc-admin-help">' . I18N::translate('Choose where the sentence such as “John Smith is your second cousin” appears.') . '</div>';

        return $html;
    }

    private function labelStyleField(): string
    {
        $options = [
            self::LABEL_STYLE_COMPACT => I18N::translate('Compact labels'),
            self::LABEL_STYLE_SENTENCE => I18N::translate('Sentence labels'),
        ];
        $html = '<label for="' . self::PREF_LABEL_STYLE . '" style="display:block;font-weight:700;margin-bottom:6px;">' . I18N::translate('Close-relative event label style') . '</label>';
        $html .= '<select id="' . self::PREF_LABEL_STYLE . '" name="' . self::PREF_LABEL_STYLE . '" style="width:100%;border:1px solid #cbd5e1;border-radius:10px;padding:10px;background:#fff;font:inherit;">';

        foreach ($options as $value => $label) {
            $selected = $this->labelStyle() === $value ? ' selected' : '';
            $html .= '<option value="' . $this->escape($value) . '"' . $selected . '>' . $this->escape($label) . '</option>';
        }

        $html .= '</select>';
        $html .= '<div class="prc-admin-help">' . I18N::translate('Compact labels work best on narrow fact/event tiles.') . '</div>';

        return $html;
    }

    private function cardStyleField(): string
    {
        $options = [
            self::CARD_STYLE_THEME => I18N::translate('Use active theme colours'),
            self::CARD_STYLE_POTTS => I18N::translate('Potts teal and gold'),
        ];
        $html = '<label for="' . self::PREF_CARD_STYLE . '" style="display:block;font-weight:700;margin-bottom:6px;">' . I18N::translate('Card appearance') . '</label>';
        $html .= '<select id="' . self::PREF_CARD_STYLE . '" name="' . self::PREF_CARD_STYLE . '" style="width:100%;border:1px solid #cbd5e1;border-radius:10px;padding:10px;background:#fff;font:inherit;">';

        foreach ($options as $value => $label) {
            $selected = $this->cardStyle() === $value ? ' selected' : '';
            $html .= '<option value="' . $this->escape($value) . '"' . $selected . '>' . $this->escape($label) . '</option>';
        }

        $html .= '</select>';
        $html .= '<div class="prc-admin-help">' . I18N::translate('Theme colours blend with webtrees themes and automatically recognise Potts Modern. Potts teal and gold forces the original module design in every theme.') . '</div>';

        return $html;
    }

    private function adminNavigation(ServerRequestInterface $request, string $position): string
    {
        $home_url = $this->homePageUrl($request);
        $modules_url = $this->siteUrl($request, 'index.php?route=%2Fadmin%2Fmodules');
        $control_panel_url = $this->siteUrl($request, 'index.php?route=%2Fadmin');
        $margin = $position === 'top' ? 'margin:-6px 0 18px 0;' : 'margin:18px 0 0 0;';

        return '<nav aria-label="' . $this->escape(I18N::translate('Settings navigation')) . '" style="display:flex;flex-wrap:wrap;gap:10px;align-items:center;' . $margin . '">' .
            '<a style="display:inline-flex;align-items:center;text-decoration:none;border:1px solid #cbd5e1;border-radius:999px;background:#fff;color:#1f2933;padding:8px 14px;font-weight:700;" href="' . $this->escape($modules_url) . '">' . I18N::translate('Back to modules') . '</a>' .
            '<a style="display:inline-flex;align-items:center;text-decoration:none;border:1px solid #cbd5e1;border-radius:999px;background:#fff;color:#1f2933;padding:8px 14px;font-weight:700;" href="' . $this->escape($control_panel_url) . '">' . I18N::translate('Control panel') . '</a>' .
            '<a style="display:inline-flex;align-items:center;text-decoration:none;border:1px solid #cbd5e1;border-radius:999px;background:#fff;color:#1f2933;padding:8px 14px;font-weight:700;" href="' . $this->escape($home_url) . '">' . I18N::translate('Home page') . '</a>' .
            '<button type="button" style="display:inline-flex;align-items:center;border:1px solid #cbd5e1;border-radius:999px;background:#fff;color:#1f2933;padding:8px 14px;font-weight:700;cursor:pointer;" onclick="history.back();">' . I18N::translate('Back') . '</button>' .
            '</nav>';
    }

    private function homePageUrl(ServerRequestInterface $request): string
    {
        $tree = $this->currentTreeFromRequest($request);

        if ($tree instanceof Tree) {
            return $this->siteUrl($request, 'index.php?ged=' . rawurlencode($tree->name()));
        }

        return $this->siteUrl($request, 'index.php');
    }

    private function siteUrl(ServerRequestInterface $request, string $relative_url): string
    {
        return rtrim($this->siteBasePath($request), '/') . '/' . ltrim($relative_url, '/');
    }

    private function siteBasePath(ServerRequestInterface $request): string
    {
        $path = $request->getUri()->getPath();
        $markers = [
            '/index.php',
            '/module.php',
            '/individual.php',
            '/family.php',
            '/admin',
            '/module/',
            '/tree/',
        ];

        foreach ($markers as $marker) {
            $position = strpos($path, $marker);

            if ($position !== false) {
                $base = substr($path, 0, $position + 1);

                return $base === '' ? '/' : $base;
            }
        }

        return '/';
    }

    private function isIndividualPageRequest(): bool
    {
        try {
            $request = $this->currentRequest();

            if (!$request instanceof ServerRequestInterface) {
                return false;
            }

            $uri = $request->getUri();
            $route = $request->getQueryParams()['route'] ?? '';
            $sources = [
                (string) $uri,
                $uri->getPath() . ($uri->getQuery() !== '' ? '?' . $uri->getQuery() : ''),
                $_SERVER['REQUEST_URI'] ?? '',
                is_string($route) ? $route : '',
            ];

            foreach ($sources as $source) {
                if (!is_string($source) || $source === '') {
                    continue;
                }

                foreach ([$source, urldecode($source)] as $candidate) {
                    if (preg_match('~/individual/[^/?#]+~i', $candidate) === 1) {
                        return true;
                    }

                    // Legacy/non-pretty individual-page URLs.
                    if (preg_match('/[?&](?:xref|pid|individual)=[^&]+/i', $candidate) === 1
                        && !str_contains(strtolower($candidate), '/relationships-')) {
                        return true;
                    }
                }
            }
        } catch (Throwable) {
            return false;
        }

        return false;
    }

    private function isRelationshipsChartRequest(): bool
    {
        try {
            $request = $this->currentRequest();

            if (!$request instanceof ServerRequestInterface) {
                return false;
            }

            foreach ($this->requestUriSources($request) as $source) {
                if (str_contains(strtolower($source), '/relationships-')) {
                    return true;
                }
            }
        } catch (Throwable) {
            return false;
        }

        return false;
    }

    private function currentIndividualFromRequest(): ?Individual
    {
        try {
            $request = $this->currentRequest();

            if (!$request instanceof ServerRequestInterface) {
                return null;
            }

            try {
                $individual = Validator::attributes($request)->individual();

                if ($individual instanceof Individual) {
                    return $individual;
                }
            } catch (Throwable) {
                // Some routes do not provide the individual as a request attribute.
            }

            $tree = $this->currentTreeFromRequest($request);

            if (!$tree instanceof Tree) {
                return null;
            }

            $xref = $this->currentIndividualXref($request);

            if ($xref === null) {
                return null;
            }

            $individual = Registry::individualFactory()->make($xref, $tree);

            return $individual instanceof Individual ? $individual : null;
        } catch (Throwable) {
            return null;
        }
    }

    private function currentRequest(): ?ServerRequestInterface
    {
        try {
            if (function_exists('request')) {
                $request = request();

                if ($request instanceof ServerRequestInterface) {
                    return $request;
                }
            }
        } catch (Throwable) {
            // Try the container fallback.
        }

        try {
            $request = Registry::container()->get(ServerRequestInterface::class);

            if ($request instanceof ServerRequestInterface) {
                return $request;
            }
        } catch (Throwable) {
            // Try a named container entry below.
        }

        try {
            $request = Registry::container()->get('request');

            if ($request instanceof ServerRequestInterface) {
                return $request;
            }
        } catch (Throwable) {
            // No request is available in this rendering context.
        }

        return null;
    }

    private function currentTreeFromRequest(ServerRequestInterface $request): ?Tree
    {
        try {
            try {
                $tree = Validator::attributes($request)->tree();

                if ($tree instanceof Tree) {
                    return $tree;
                }
            } catch (Throwable) {
                $tree = $request->getAttribute('tree');

                if ($tree instanceof Tree) {
                    return $tree;
                }
            }

            $tree_name = $this->currentTreeName($request);

            if ($tree_name === null || $tree_name === '') {
                return null;
            }

            return $this->treeFromName($tree_name);
        } catch (Throwable) {
            return null;
        }
    }

    private function currentTreeName(ServerRequestInterface $request): ?string
    {
        $query_params = $request->getQueryParams();

        foreach (['ged', 'tree'] as $key) {
            if (isset($query_params[$key]) && is_string($query_params[$key]) && $query_params[$key] !== '') {
                return urldecode($query_params[$key]);
            }
        }

        foreach ($this->requestUriSources($request) as $source) {
            if (preg_match('/[?&](?:ged|tree)=([^&]+)/', $source, $match) === 1) {
                return urldecode($match[1]);
            }

            if (preg_match('~/tree/([^/?#]+)/~', $source, $match) === 1) {
                return urldecode($match[1]);
            }

            if (preg_match('~/index\.php\?route=/tree/([^/&?#]+)~', $source, $match) === 1) {
                return urldecode($match[1]);
            }
        }

        return null;
    }

    private function treeFromName(string $tree_name): ?Tree
    {
        $tree_name = urldecode(trim($tree_name));

        if ($tree_name === '') {
            return null;
        }

        try {
            /** @var TreeService $tree_service */
            $tree_service = Registry::container()->get(TreeService::class);

            foreach (['findByName', 'find', 'get'] as $method) {
                if (method_exists($tree_service, $method)) {
                    try {
                        $tree = $tree_service->{$method}($tree_name);

                        if ($tree instanceof Tree) {
                            return $tree;
                        }
                    } catch (Throwable) {
                        // Try the next method.
                    }
                }
            }

            if (method_exists($tree_service, 'all')) {
                $trees = $tree_service->all();

                if ($trees instanceof Collection) {
                    $tree = $trees->get($tree_name);

                    if ($tree instanceof Tree) {
                        return $tree;
                    }

                    foreach ($trees as $candidate) {
                        if ($candidate instanceof Tree && $candidate->name() === $tree_name) {
                            return $candidate;
                        }
                    }
                }

                if (is_iterable($trees)) {
                    foreach ($trees as $key => $candidate) {
                        if ($candidate instanceof Tree && ((string) $key === $tree_name || $candidate->name() === $tree_name)) {
                            return $candidate;
                        }
                    }
                }
            }
        } catch (Throwable) {
            // Try other fallbacks.
        }

        try {
            if (method_exists(Tree::class, 'findByName')) {
                $tree = Tree::findByName($tree_name);

                if ($tree instanceof Tree) {
                    return $tree;
                }
            }
        } catch (Throwable) {
            // Continue.
        }

        try {
            if (method_exists(Registry::class, 'treeFactory')) {
                $tree = Registry::treeFactory()->make($tree_name);

                if ($tree instanceof Tree) {
                    return $tree;
                }
            }
        } catch (Throwable) {
            // Continue.
        }

        return null;
    }

    private function currentIndividualXref(ServerRequestInterface $request): ?string
    {
        foreach ($this->requestUriSources($request) as $source) {
            if (preg_match('/[?&](?:xref|pid|individual)=([^&]+)/', $source, $match) === 1) {
                return urldecode($match[1]);
            }

            if (preg_match('~/individual/([^/?#]+)~', $source, $match) === 1) {
                return urldecode($match[1]);
            }

            if (preg_match('~/tree/[^/?#]+/individual/([^/?#]+)~', $source, $match) === 1) {
                return urldecode($match[1]);
            }
        }

        return null;
    }

    /**
     * @return array<int,string>
     */
    private function requestUriSources(ServerRequestInterface $request): array
    {
        $uri = $request->getUri();
        $sources = [
            (string) $uri,
            $uri->getPath() . ($uri->getQuery() !== '' ? '?' . $uri->getQuery() : ''),
            $_SERVER['REQUEST_URI'] ?? '',
            $_SERVER['HTTP_REFERER'] ?? '',
            $_SERVER['REDIRECT_URL'] ?? '',
            $_SERVER['HTTP_X_ORIGINAL_URL'] ?? '',
        ];

        $route = $request->getQueryParams()['route'] ?? null;

        if (is_string($route) && $route !== '') {
            $sources[] = $route;
        }

        $decoded = [];

        foreach ($sources as $source) {
            if (!is_string($source) || $source === '') {
                continue;
            }

            $decoded[] = $source;
            $decoded[] = urldecode($source);
        }

        return array_values(array_unique(array_filter($decoded)));
    }

    /**
     * @return array<string,mixed>
     */
    private function requestDiagnostics(): array
    {
        try {
            $request = $this->currentRequest();

            if (!$request instanceof ServerRequestInterface) {
                $sources = array_values(array_unique(array_filter([
                    $_SERVER['REQUEST_URI'] ?? '',
                    $_SERVER['HTTP_REFERER'] ?? '',
                    $_SERVER['REDIRECT_URL'] ?? '',
                    $_SERVER['HTTP_X_ORIGINAL_URL'] ?? '',
                ])));

                return [
                    'requestAvailable' => false,
                    'serverRequestUri' => $_SERVER['REQUEST_URI'] ?? '',
                    'serverReferer' => $_SERVER['HTTP_REFERER'] ?? '',
                    'sampleSources' => $sources,
                ];
            }

            $tree_name = $this->currentTreeName($request);
            $xref = $this->currentIndividualXref($request);
            $tree = $tree_name !== null ? $this->treeFromName($tree_name) : null;
            $sources = array_slice($this->requestUriSources($request), 0, 8);

            return [
                'requestAvailable' => true,
                'requestPath' => $request->getUri()->getPath(),
                'requestQuery' => $request->getUri()->getQuery(),
                'parsedTreeName' => $tree_name,
                'parsedXref' => $xref,
                'treeFound' => $tree instanceof Tree,
                'sampleSources' => $sources,
            ];
        } catch (Throwable $ex) {
            return [
                'requestAvailable' => true,
                'diagnosticError' => $ex->getMessage(),
            ];
        }
    }

    private function maxGenerations(): int
    {
        $value = (int) $this->getPreference(self::PREF_MAX_GENERATIONS, '12');

        return max(3, min(20, $value));
    }

    private function summaryPosition(): string
    {
        $value = $this->getPreference(self::PREF_SUMMARY_POSITION, self::SUMMARY_POSITION_FACTS_PANEL);

        if (in_array($value, [self::SUMMARY_POSITION_FACTS_PANEL, self::SUMMARY_POSITION_ABOVE_TABS, self::SUMMARY_POSITION_NEAR_TITLE, self::SUMMARY_POSITION_OFF], true)) {
            return $value;
        }

        return self::SUMMARY_POSITION_FACTS_PANEL;
    }

    private function labelStyle(): string
    {
        $value = $this->getPreference(self::PREF_LABEL_STYLE, self::LABEL_STYLE_COMPACT);

        if (in_array($value, [self::LABEL_STYLE_COMPACT, self::LABEL_STYLE_SENTENCE], true)) {
            return $value;
        }

        return self::LABEL_STYLE_COMPACT;
    }

    private function cardStyle(): string
    {
        $value = $this->getPreference(self::PREF_CARD_STYLE, self::CARD_STYLE_THEME);

        if (in_array($value, [self::CARD_STYLE_THEME, self::CARD_STYLE_POTTS], true)) {
            return $value;
        }

        return self::CARD_STYLE_THEME;
    }

    private function boolPreference(string $name): bool
    {
        return $this->getPreference($name, self::BOOLEAN_PREFERENCES[$name] ?? '0') === '1';
    }

    private function escape(string $value): string
    {
        return htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
    }
};